fix: auto-create branch before workspace clone

[simple-agent-manager]

Summary

• When tasks are dispatched with an explicit branch that doesn't exist on the remote, git clone --branch <branch> fails on the VM agent. This adds a best-effort branch existence check and auto-creation step before workspace provisioning.
• New ensureBranchExists() in github-app.ts checks the GitHub API and creates the branch from the project's default branch if missing. Called from ensureBranchExistsOnRemote() in workspace-steps.ts before createWorkspaceOnVmAgent().
• Best-effort: failures log warnings but never block workspace creation.
• Handles race conditions (422 = branch created between check and create).
• Threads defaultBranch through TaskRunConfig to avoid extra D1 round-trip.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test — 4845 tests pass (14 new)
• Additional validation run (if applicable)

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — Deploy Staging workflow passed for ensure-branch-exists-before-clone
• Live app verified via Playwright — logged into app.sammy.party using test credentials
• Existing workflows confirmed working — dashboard, projects, settings all load; 0 console errors
• New feature/fix verified on staging — backend-only change exercised during task dispatch; verified deploy succeeds and no regressions
• Infrastructure verification completed — N/A: no infra changes
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes

Staging Verification Evidence

• API health endpoint responds healthy at api.sammy.party/health
• Dashboard loads with project cards, projects page lists projects, settings page renders
• 0 console errors across all pages
• The branch-check code path runs only during TaskRunner DO workspace creation — not directly triggerable via UI without compute resources. All 14 tests (7 unit for ensureBranchExists + 7 integration for ensureBranchExistsOnRemote) cover the full behavior.

UI Compliance Checklist (Required for UI changes)

N/A: no UI changes

End-to-End Verification (Required for multi-component changes)

• Data flow traced from user input to final outcome with code path citations
• Capability test exercises the complete happy path across system boundaries
• All spec/doc assumptions about existing behavior verified against code
• If any gap exists between automated test coverage and full E2E, manual verification steps documented below

Data Flow Trace

1. MCP dispatch_task or task submit → dispatch-tool.ts:419 sets checkoutBranch = explicitBranch || project.defaultBranch
2. startTaskRunnerDO() → task-runner-do.ts:106 threads branch + defaultBranch into TaskRunConfig
3. TaskRunner DO createAndProvisionWorkspace() → workspace-steps.ts:167 calls ensureBranchExistsOnRemote()
4. ensureBranchExistsOnRemote() → workspace-steps.ts:228 short-circuits if branch === defaultBranch, otherwise calls ensureBranchExists()
5. ensureBranchExists() → github-app.ts:561 checks GitHub API, creates branch if 404, handles 422 race
6. createWorkspaceOnVmAgent() → workspace-steps.ts:283 proceeds regardless of branch-check result

Untested Gaps

The actual GitHub API call during a live task dispatch is not tested on staging (would require provisioning a VM). This is by design — the function is best-effort and all failure paths are tested locally. The VM agent clone will fail with a clear error if the branch truly doesn't exist.

Post-Mortem (Required for bug fix PRs)

What broke

Tasks dispatched via MCP dispatch_task with an explicit branch that doesn't exist on the remote fail with git clone failed: exit status 128: fatal: Remote branch not found.

Root cause

No validation between task creation and workspace provisioning verifies the branch exists. dispatch-tool.ts:419 allows any branch name to pass through to the VM agent.

Class of bug

Missing pre-condition validation at a system boundary — the API accepts input it cannot fulfill without first establishing the precondition.

Why it wasn't caught

The happy path (branch already exists) always works. The failure only manifests when MCP callers specify branches that don't exist yet, which is a common pattern for task-scoped work.

Process fix included in this PR

N/A — this is a feature gap, not a regression from a code change. No process rule would have prevented the original omission.

Post-mortem file

tasks/archive/2026-06-02-ensure-branch-exists-before-clone.md

Specialist Review Evidence (Required for agent-authored PRs)

• All dispatched reviewers completed and findings addressed before merge
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — N/A, all completed

Reviewer	Status	Outcome
cloudflare-specialist	ADDRESSED	1 HIGH (D1 query eliminated by threading defaultBranch through TaskRunConfig) + 3 MEDIUM (separate 422/201 logs, consume response body, improve log clarity) fixed in commit 0bdeee4
task-completion-validator	ADDRESSED	2 HIGH (missing integration tests for ensureBranchExistsOnRemote, missing default branch short-circuit test) fixed in commit 41889dc

Exceptions (If any)

• Scope: N/A
• Rationale: N/A
• Expiration: N/A

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

GitHub REST API official documentation consulted for branch management endpoints:

• Branches API: https://docs.github.com/en/rest/branches/branches?apiVersion=2022-11-28
• Git Refs API (get ref): https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28#get-a-reference
• Git Refs API (create ref): https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28#create-a-reference

Codebase Impact Analysis

• apps/api/src/services/github-app.ts — new ensureBranchExists() function
• apps/api/src/durable-objects/task-runner/workspace-steps.ts — new ensureBranchExistsOnRemote() step
• apps/api/src/durable-objects/task-runner/types.ts — defaultBranch added to TaskRunConfig
• apps/api/src/services/task-runner-do.ts — threads defaultBranch input
• 8 call sites updated to pass defaultBranch to startTaskRunnerDO()

Documentation & Specs

N/A: internal API behavior change, no user-facing documentation affected

Constitution & Risk Check

Principle XI (No Hardcoded Values): The fallback 'main' for defaultBranch is a safe default matching GitHub's convention, used only when the field is empty. All other values are derived from project configuration in D1.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.4% Duplication on New Code

See analysis details on SonarQube Cloud