OPER-11A
Ensure agent branch exists at claim-time (fix ghost-branch pipeline deadlock)
Body
Discovered via OPER-7A alerts: 205 Portico tasks are PLANNING_VALIDATED with `gitBranchName` set, but the branch does not exist in Operant-Health/portico. `backend.claim()` now correctly rejects them (PR #48 reality-gate), so no dispatch ever fires. Pipeline is permanently deadlocked for these tasks.
Root cause: NO code in the dispatcher, planner, or auto-shipper creates the git branch. Agent-dispatch.yml checks out `${{ inputs.branch }}` and expects it to already exist. Older `agent/POR-XXX` runs succeeded because those branches were created manually or by an earlier removed code path. Current `justin/por-XXX` naming has never had a branch-creator.
Secondary bug: when a PR merges (squash-merge auto-delete-head-branch), the Ledger Task record is not updated, so on next re-dispatch we hit the same ghost.
Fix scope:
1. Add branch-creation to backend.claim() as part of the atomic claim transaction:
- If gitBranchName is set AND branch does not exist in the target repo, create it from main HEAD via GitHub REST `POST /repos/{owner}/{repo}/git/refs`
- If gitBranchName is null, generate one from `justin/<lowercased-identifier>-<slug(title)>` and create + persist to Task.gitBranchName
- Use the existing GH_DISPATCH_PAT (has Contents:write on all Operant-Health repos)
- Circuit-breaker: if branch-creation fails due to GitHub 5xx, defer claim (do not mark FAILED); if 422 (branch already exists as ref), treat as success
2. On workflow completion (agent-dispatch.yml callback into Ledger), if PR was merged and branch deleted upstream, mark Task.gitBranchName = null (clean state for potential future re-dispatch)
3. Post-fix backfill: identify all PLANNING_VALIDATED tasks in Portico where gitBranchName is set but branch does not exist. For each, either (a) create the branch from main if the task is still relevant, or (b) null-out gitBranchName to let the fixed claim() re-mint. Run this backfill via a one-shot script committed to `scripts/oper-11a-branch-backfill.ts`.
4. Emit DispatchAudit rows for branch-creation attempts (extends OPER-7A audit trail).
5. Add unit test: claim() with missing branch creates branch + succeeds. claim() with GitHub 500 defers gracefully.
Blocked by: Nothing. This IS what unblocks the 205 stuck Portico tasks.
DOC review: not required (bug fix, not architectural change). Post-merge: monitor OPER-7A alerts — queue_liveness violation should self-clear within 15 min.Attachments
Loading attachments…
Comments
Loading comments…