Code FlowCoordinated changes
Use coordinated changes when one repository depends on another repository’s result. Pin the dependency inputs, inspect each repository’s verification, and review publishing separately for each result.
Plan across repositories
Open Project → Repository tools → Coordinated changes, choose a project containing 2–10 local Git repositories and create one task per repository. Select a provider and verification command for each task, and mark its explicit dependencies. Commands left blank use the repository configuration. The graph must be acyclic and every repository must be distinct. This is local coordination; it does not clone remote repositories or supply credentials.
Creation pins each authorized canonical repository, its Git metadata ownership and starting commit. Linked worktrees sharing one underlying repository cannot masquerade as separate shipping targets. Replaced repository metadata blocks dispatch and result validation. Tasks execute in separate managed workspaces with safe trust, disabled native approval waits, no inherited uploads or parent-run sessions, and no copied ignored files. The interface defaults to 20 agent invocations and 15 minutes per task. The service caps each task at 50 calls, 60 minutes, two million tokens and $100 API-equivalent usage, with defaults of 500,000 tokens and $25. These are usage limits, not subscription charges. Existing external-source trust restrictions continue to apply at launch.
A downstream task starts only after all dependencies have current successful verification tied to their exact owned result branches. Its server-created launch claim records factual dependency receipts: repository, run ID, branch, immutable commit and verification identity. It does not turn sibling agent output into trusted instructions, expose sibling credentials, or mount sibling repositories. No broad external-source execution exemption is inherited.
Every launch claim is saved, synced and atomically renamed before starting an agent. The engine must save and sync the initial run's exact {jobId,nodeId,claimId,attempt} coordination identity before returning a receipt. A crash, timeout or ordinary callback failure after claiming produces an unknown outcome. It is never automatically retried. Link only a run whose persisted identity matches the exact claim, or acknowledge that an explicit retry can duplicate work. Each task permits at most three explicit attempts. Retrying invalidates the selected task and all downstream results and receipts; active downstream work or shipping must first be stopped or resolved.
The status panel shows dependencies, pinned bases, current run links, verified results, errors, exact unknown claims and bounded operation history. Cancelling stops pending dispatch and sends cancellation to known runs. A run receipt arriving after cancellation is stopped as well. Cancellation cannot undo commits already merged by an explicit shipping operation.
Review and ship
Every task must have a current verified immutable result before shipping review. Choose a local target branch per repository and select Validate and preview shipping matrix. Actual merge-target verification records source commit, current target commit and exact merged tree. The matrix expires after 30 minutes.
Review each matrix entry and deliberately merge repositories one at a time. Before each action, the coordinator checks every owned result and its dependency receipts, verifies the selected source/target/tree again, and saves a durable shipping claim. The engine's merge operation must enforce the reviewed source/target/tree with compare-and-swap. A changed result, target, tree, dependency receipt or expired preview refuses shipping before the merge begins. This flow never automatically pushes or creates remote pull requests.
Git repositories do not share an atomic transaction. A successful merge in one repository remains merged if another fails; the status and history show partial progress. An ambiguous shipping receipt becomes shipping-unknown and cannot be blindly retried. Manual recovery must prove the exact reviewed source/target/tree using the resulting local commit and engine-owned merge receipt. Do not reset unrelated commits to simulate an atomic rollback.
Persistence and recovery
CODEFLOW_HOME/coordinated-changes.json stores revisioned jobs, sanitized task configuration, pinned commits and bounded histories in owner-only files. It can include user-entered task text and command strings; keep credentials in environment references rather than task text. The service permits ten active jobs, twenty retained jobs, ten repositories per job, one hundred history entries per job and a 32 MiB storage limit. Incomplete or invalid storage fails closed and is left untouched.
Normal restart converts claimed launches and shipping operations to unknown outcomes and does not repeat them. Verified dependency facts are checked again before further work. Encrypted backup restore disables all implicit coordinated dispatch while retaining claim and shipping metadata for investigation. Review restored jobs explicitly before any retry. Private remote-worker capability receipts remain excluded from backups and restore.
The versioned authenticated HTTP interface uses /api/coordinated-changes: create/list jobs, cancel, explicitly retry tasks, link exact unknown runs, preview a shipping matrix, merge one repository and recover a proven unknown shipping receipt. Mutating existing jobs requires their current revision. The coordinator's callback interface is defined in src/repo-coordination.ts; callbacks must supply actual authorization, durable engine receipts, verification evidence and compare-and-swap merging. A callback's success is not synthetic verification evidence.