Skip to content

docs: design walkthrough for a supervisor-owned orchestrator worktree - #449

Open
kumaakh wants to merge 1 commit into
mainfrom
docs/orchestrator-worktree-model
Open

kumaakh wants to merge 1 commit into
mainfrom
docs/orchestrator-worktree-model

Conversation

@kumaakh

@kumaakh kumaakh commented Aug 22, 2026

Copy link
Copy Markdown
Contributor

Summary

Design walkthrough (not implemented) for a proposed fix to the orchestrator-role selection problem uncovered while root-causing PR #448: today, orchestrator silently falls back to whichever registered member sorts first when roleMap.orchestrator is unset, which can hand every pre-sprint bd/git/Dolt operation to a remote member with a stale clone.

The proposed model: on sprint launch, the supervisor itself creates a fresh git worktree, registers it as a throwaway local member, reserves it to the sprint, and injects it as roleMap.orchestrator -- so the user never configures this, and it's torn down (worktree removed, reservation released, member unregistered) on every terminal path.

This document walks the model phase-by-phase (Sprint Setup, Plan, Develop, Test, Harvest, supervisor launch/teardown) against the actual current codebase, with file:line references throughout, and calls out what's genuinely reusable vs. new plumbing.

Key findings

  • Central constraint: git enforces one-branch-one-worktree. The orchestrator worktree must be pinned to the sprint branch (it pushes and raises the PR), but Ensure Sprint Branch dispatches a checkout to every member including the orchestrator and hard-throws on non-dirty-tree failures -- so the orchestrator's parent clone must come from a repo no registered member shares. Not a preference, a hard requirement.
  • The "no builds on the orchestrator" constraint already holds today: every orchestratorMember-routed call is bd/git/two node -e one-liners; deploy/integ/regression already route to their own roles.
  • Three open risks ranked by severity: (1) whether a freshly-registered throwaway local member can actually mint a push+PR credential, (2) registry.ts has no locking, so concurrent launches can clobber each other's register_member write, (3) the beads directory-walk-up trick needs to be verified under the supervisor's actual environment, not assumed.

Status

Design/proposal only -- no code changes. Intended as a scoping document for a future bead/epic under apra-fleet-eft, not something to merge-and-ship as-is.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant