ASK KNOX
beta
Learn/Parallel Agent Dispatch & Worktrees/Lesson 417
LESSON 417

The Shared-File Collision Problem

Registry files like index.ts and tracks.ts are the blast radius of parallel dispatch — identify them before you dispatch, not after a collision.

8 min read·Parallel Agent Dispatch & Worktrees

The Registry Problem

Registries are the invisible collision points in any large codebase. They are single files that aggregate references to everything else: the index.ts that exports all MDX components, the tracks.ts that registers all academy tracks, the tiers.ts that assigns tracks to tiers, the content-integrity.test.ts that asserts exact file counts.

Every parallel dispatch session in the academy touches multiple of these files. Multiple workers all need to add their outputs to the registries. If those workers all edit the registries simultaneously, every one of them becomes a collision point.

The Collision Map

The pattern is consistent across all parallel dispatch work in this academy:

  • components/mdx/index.ts: Every new diagram requires a new export line. This is the hottest file in any track-building session. Multiple workers adding exports = guaranteed conflict. Orchestrator-only.
  • lib/tracks.ts: The track definition object. Only the orchestrator adds new track entries. Workers that add themselves to lessonOrder will conflict.
  • lib/tiers.ts: The tier assignment array. One append per session, by the orchestrator, after all lesson files are confirmed.
  • tests/content-integrity.test.ts: The lesson count and track count assertions. These are integer values. Two workers bumping from 387 to different numbers = conflict. Orchestrator calculates the final count and edits once.

The safe files — individual lesson MDX files and diagram TSX components with unique names — can be parallelized freely. No two workers will ever create the same file name if the orchestrator assigns distinct lesson number ranges and enforces the naming prefix rule (Pad for this track).

The Four Collision Types

Understanding the four collision types lets you design around each one:

File overwrite collision: The easiest to prevent. Assign distinct files to each worker. Worker A: one block of lesson files. Worker B: the next block. Zero overlap.

HEAD reset collision: The Agent Gateway incident. Agent Gateway's cron fires mid-session and runs git operations on the main working tree. Prevention: always use isolated worktrees for multi-step agent work. Agent Gateway can only reset the main working tree — it cannot touch a worktree at a different path.

Registry append collision: The subtlest collision because each edit seems correct in isolation. Two workers each add a different line to index.ts. Both edits are valid. But the cherry-pick produces a conflict because both branches modified the same file. Prevention: off-limits list in every dispatch prompt.

Test count desync: The most confusing collision because it looks like a test failure, not a git conflict. Two workers both bump EXPECTED_LESSON_COUNT from 387 to their own number. One cherry-pick wins. The other worker's count is lost. The test fails with a count that doesn't match any expected value. Prevention: test count constants are always off-limits. Orchestrator calculates final count from all workers' output and edits once.

The Agent Gateway Incident in Detail

Knox's production environment runs Agent Gateway on the production server, and Agent Gateway has cron jobs that perform git operations. The cron jobs run in the main working tree — the same directory Knox uses for development.

On one incident (documented in Knox's production incident log): a coding agent was mid-session in the main working tree. It had committed its work-in-progress to the branch it was on. Agent Gateway's automation cron fired git reset --hard followed by a forced checkout of main to put the tree into a known state for a different task. The hard reset moved the branch pointer past the agent's commit and force-rewrote the working tree — the agent's commit was no longer reachable from any branch.

The coding agent attempted to continue, found the working tree was in an unexpected state, and the session state became corrupted.

Recovery: the commit still existed in git's object store. git reflog | head -20 surfaced its SHA — reflog records every HEAD movement, including the cron's reset. git cherry-pick <sha> re-applied the lost commit onto a fresh worktree.

Note the precondition: reflog recovery worked because the work had been committed. Staged-but-uncommitted changes never enter the commit graph — a hard reset destroys them with nothing in reflog to recover from. Commit early and often inside your worktree.

Prevention for all future sessions: every multi-step git operation from a coding agent uses git worktree add first. The worktree is at .claude/worktrees/<name>, which Agent Gateway's crons do not touch.

Before-Dispatch Checklist

Before every parallel dispatch session:

# 1. Identify all registry files in this repo
grep -r "EXPECTED_" __tests__/         # count constants
cat components/mdx/index.ts | tail -5  # registry format
grep -r "TRACKS\|TIERS" lib/           # track/tier registries

# 2. Add all identified files to off-limits list
# DO NOT TOUCH: components/mdx/index.ts, lib/tracks.ts, lib/tiers.ts
# DO NOT TOUCH: __tests__/content-integrity.test.ts, __tests__/projects-api.test.ts

# 3. Plan the orchestrator's final registry pass
# After convergence: add N exports to index.ts, 1 track entry to tracks.ts,
# 1 slug to tiers.ts, bump EXPECTED_LESSON_COUNT by 9, EXPECTED_TRACK_COUNT by 1

The 5 minutes spent on this checklist prevents 45 minutes of conflict resolution at convergence.

What's Next

The next lesson covers fan-out patterns: pure parallel versus pipeline. The collision map tells you which files require serialization. The fan-out pattern tells you whether to dispatch all workers simultaneously or in sequential waves. Together they determine the full dispatch topology for any given task.