Ask Knox

Convergence Is Not a Merge — It Is a Protocol

Most developers think of "bringing branches together" as git merge. Convergence in parallel dispatch is more deliberate: the orchestrator validates each worker's output, determines the integration order based on dependencies, performs the actual cherry-picks, edits the shared registries, runs the full verification suite, and cleans up the worktrees.

Skipping any step breaks the post-convergence system state. Running the test suite before editing registries produces failures that would have passed with correct registries. Cleaning up worktrees before cherry-picking loses the work. Merging instead of cherry-picking produces a diff history that is harder to review.

The Convergence Flow

Step 1 — Collect reports: Every worker must report PASS before convergence begins on that worker's output. A PASS is not "I think it works" — it is the literal output of npm run test and npx tsc --noEmit. Workers that report FAIL get a new dispatch cycle; they do not block convergence of passing workers.

Step 2 — Cherry-pick in dependency order: The orchestrator is in the main working tree. It cherry-picks each passing worker's branch in the order that respects dependencies. If Worker A's output feeds into Worker B's registration step, A comes before B. For independent workers (typical), order is by file area to minimize conflict surface.

Always use the range form main..feat/agent-x. It re-applies every commit the worker made on its branch, in order. A bare git cherry-pick feat/agent-x applies only the branch's tip commit — if a worker committed incrementally (typical for agents), every earlier commit is silently dropped with no git error, and the missing work only surfaces at post-convergence verification, if at all.

cd ~/dev/academy  # main working tree, not a worktree
git cherry-pick main..feat/agent-a   # range form: ALL of the worker's commits
git cherry-pick main..feat/agent-b
git cherry-pick main..feat/agent-c

Step 3 — Edit registries once: After all cherry-picks succeed, the orchestrator edits all shared files in one atomic commit. For a track-building session: add all exports to components/mdx/index.ts, add the track definition to lib/tracks.ts, append the slug to lib/tiers.ts, update the count constants in the test files.

# Edit all registries, then single commit
git add components/mdx/index.ts lib/tracks.ts lib/tiers.ts __tests__/content-integrity.test.ts
git commit -m "feat: register parallel-agent-dispatch track and 18 diagram components"

Step 4 — Full verification: Run the complete test suite from the main working tree. npm run test AND npx tsc --noEmit. Both must pass before declaring convergence complete.

Step 5 — Cleanup: git worktree remove every temporary worktree. git branch -D every ephemeral worker branch — it must be -D (force), because cherry-pick created new SHAs on main, so the worker branch tips are never ancestors of main and -d refuses with "not fully merged". git worktree list must show only the main working tree.

Stray Commit Recovery

The Agent Gateway incident is not hypothetical — it has happened in Knox's production environment. The pattern: coding agent working in the main working tree, Agent Gateway cron fires a git operation, working tree state is disrupted, agent's commits appear lost.

The recovery protocol is always the same:

git reflog | head -30
# Find the last known-good SHA — it will be there
# (Every git operation creates a reflog entry)

git show <sha> --stat
# Confirm this is the lost commit by reviewing its files

git cherry-pick <sha>
# Apply the lost commit onto the current branch

git log --oneline -5
# Verify the recovery commit is in the chain

The reflog retains entries for reachable commits for 90 days by default — but a stray, orphaned commit (exactly the lost-commit case here) is unreachable, and git's default gc.reflogExpireUnreachable prunes those after just 30 days. The safety window for a lost commit is 30 days, not 90, so recover it promptly. The recovery procedure itself takes 5 minutes.

Prevention: use isolated worktrees for all multi-step git work. git worktree add .claude/worktrees/my-work -b feat/my-work. Agent Gateway's cron can only reset the main working tree — it does not touch worktrees at other paths.

Now run the protocol yourself: cherry-pick three passing worker branches in order, edit the shared registries in one atomic commit, and recover a stray commit from reflog when a concurrent cron disrupts the tree.

Handling Cherry-Pick Conflicts

Cherry-pick conflicts happen when two workers modified the same file — usually because the off-limits list was not complete or not followed.

git cherry-pick main..feat/agent-b
# CONFLICT: components/mdx/index.ts

git diff HEAD components/mdx/index.ts
# Review: both agents added an export line to the end of the file
# Resolution: keep both exports (they are for different components)

git add components/mdx/index.ts
git cherry-pick --continue

When a conflict is resolved: the resolution is almost always "keep both" because each worker added different content to the same file. The conflict is cosmetic — git saw the same line number changed and flagged it, but the intent is to include both changes. Understand the intent, resolve accordingly, do not discard either worker's changes.

Post-Convergence Verification

After all cherry-picks and registry edits, before opening any PR:

npm run test
# Must show all passing. Fix any failures before proceeding.

npx tsc --noEmit  
# Must show 0 errors. Fix any type errors before proceeding.

git log --oneline -10
# Review the commit chain. Does it look correct?
# No unexpected commits, no duplicate entries, right order.

git worktree list
# Should show ONLY the main working tree.
# Any stale worktrees = run git worktree remove immediately.

If any of these checks fail, do not proceed to PR. Fix the issue in the main working tree and re-run the checks. The PR represents the final verified state — it should not require CI to catch what the local verification could have caught.

What's Next