stack/agents/darkwing/work/queue-91/r2/build.md

Row 91, a project clone in each role workspace, build (Darkwing)

Issue #1585. Brief: docs/plans/2026-10-12_pm-task-flow.md, "A project checkout in each role workspace", with Sage's decision 126 (brief blob 844832c3). Reviewer: Filbert.

Round 2

Round 2 is round 1 rebased onto 6b0215aa, after row 90 landed (e918a915), with no change of its own. Sage ruled it (decision 127): row 91 lands second, so it gets a new manifest and a full gate on the new base. Filbert's static review of round 1 carries over; the test run and the verdict go on this manifest.

Round 1 was manifest 39d6eb7d on base c974cafa (request comment 28067). From c974cafa to 6b0215aa, one commit touches this row's paths: e918a915 adds two lines to packages/harness/src/bundle.mjs and two to packages/harness/tests/bundle.test.mjs. Round 1's build.patch applies to 6b0215aa with git apply --index and no fuzz. Six of the eight manifest lines are the same as round 1; the two bundle files differ by row 90's lines only. git diff 6b0215aa of the two bundle files is the same hunks as round 1's.

e918a915 also adds packages/tasks/src/requirements.mjs to RUNNER_FILES in packages/seat/src/sandbox.mjs. I checked that this row needs no line there. RUNNER_FILES lists what the runner loads inside the sandbox. checkout.mjs runs on the host: launcher.mjs imports it (and launcher.test.mjs imports gitEnv from it). bundle.mjs, which is a runner file, gains no import; it only reads session.checkouts. The seat suite's "RUNNER_FILES is exactly what the runner and the harness sources it starts import" test walks those imports and passes in the gate below.

Candidate and base

Base 6b0215aa. build.patch is git diff --binary 6b0215aa of eight paths, the two new files included. Apply it with git apply --index to a detached worktree of 6b0215aa; sha256sum -c candidate-manifest.sha256 then gives 8/8 OK (checked on a fresh worktree).

• packages/cli/README.md
• packages/cli/src/launcher.mjs
• packages/cli/tests/launcher.test.mjs
• packages/harness/src/bundle.mjs
• packages/harness/tests/bundle.test.mjs
• packages/seat/README.md
• packages/seat/src/checkout.mjs (new)
• packages/seat/tests/checkout.test.mjs (new)

In prompt() the clones line comes after the Workspace line; row 90's stop line is after the token line. Round 1's notes on its own drift (built on 6e1f9335, moved to c974cafa with a README reflow) are in round 1's build.md (agents/darkwing/work/queue-91/, f759432e).

What changed

• packages/seat/src/checkout.mjs, new. ensureCheckouts({ workspace, projects, env }) makes sure each project of the business file has a clone at <workspace>/<project id>/. No clone: git clone -q --no-hardlinks --template= --branch <root's branch> into a temp directory beside it, renamed into place, removed if anything fails. A clean clone on the root's branch: fetch from origin, merge --ff-only. Anything else is kept as it is, with a reason. A clone that can't be made throws CheckoutError with the project id.
• packages/cli/src/launcher.mjs, start() and the header comment. The clones come after credentialStatus and before newRun, so a refusal leaves no run. CheckoutError becomes Refusal("checkout-failed", "<project>: <message>"). Each kept clone is a checkout-kept line in the launch log with instance, project and reason. The session gets checkouts.
• packages/harness/src/bundle.mjs, prompt() and the session doc comment. One line after the Workspace line names each clone, its path, and its branch or why it wasn't updated. No checkouts, no line.
• packages/seat/README.md, a new section "The project clones (#1585)" with the outcomes, the reasons, the guards and the instance-running rule.
• packages/cli/README.md, the launch checks table gains checkout-failed; the paragraph under it and the on-disk sentence name the clones.
• Tests: packages/seat/tests/checkout.test.mjs (new), packages/cli/tests/launcher.test.mjs, packages/harness/tests/bundle.test.mjs.

Decision 126's three additions

Sage named the allowlist the main risk. Each guard below has a rigged clone in the "a clone the session rigged" test, and each case checks that the clone is kept with its reason, that the marker file the bait would write is absent, and that the root's fingerprint (every path, mode, link count, contents) is unchanged.

1. The lstat walk of all of .git: every entry is a directory or a regular file with one link. A symlink (.git/logs, .git/refs/heads, .git/objects, .git/config), a fifo HEAD and a reflog hard-linked to a file outside each give not-a-clone. The clone directory and .git must be real directories: a symlinked clone, a gitdir: file and a symlinked .git give not-a-clone. commondir and objects/info/alternates give not-a-clone.
2. .git/config must be a regular file of at most 64 KiB. Over the cap gives config-changed. Then every key must be one git clone writes, with the value a clone writes (allowed()): remote.origin.url equal to the root, the default fetch line, branch.*.remote = origin, branch.*.merge under refs/heads/. A duplicate key or a missing origin url is config-changed. Cases: core.fsmonitor, core.hooksPath, include.path, includeIf, a filter driver, origin moved, a second origin url, the origin url twice with the root both times, an ext:: origin, a branch tracking another remote, a branch merging a tag, a fetch line onto local branches, no origin. A non-empty .git/hooks is hooks-present.
3. The check and the git calls run only while no session holds the workspace. I didn't add a lock, because the launcher already has the rule. check() (packages/cli/src/launcher.mjs, the line if (registry.running(b.id, instance)) throw new Refusal("instance-running")) runs inside serialize() for both fromSession and launchPm, before start(). A workspace is one instance's (workspaceDir(dataRoot, business, instance), packages/seat/src/session.mjs). So while a session of the instance runs, no launch of it reaches ensureCheckouts. The launcher test pins it: with the PM running, a commit to the root, then a second --pm launch refuses instance-running and the clone's HEAD has not moved.

Second-line guards: every git call also gets -c core.hooksPath=/dev/null -c core.fsmonitor=false -c protocol.allow=never -c protocol.file.allow=always, an environment with only PATH from the host, no system or global config and HOME at /nonexistent. The root's reads set GIT_CEILING_DIRECTORIES to the root's parent, so a root that isn't a repository is not mistaken for the one above it.

Choices

• Git runs async (spawn with a 100 s timeout and SIGKILL), so a slow clone doesn't block the bus host's other work. Launches are serialized anyway.
• The prompt line says the host fetches at each launch and the origin is outside the sandbox, so the session doesn't try to fetch or push.
• A kept clone does not refuse the launch. The brief says "left exactly as it is", and the session may be mid-change in it.
• --template= on clone, so no sample hooks land in .git/hooks and the empty-hooks rule holds for a fresh clone.

The tests

packages/seat/tests/checkout.test.mjs, new, 50 tests counting each rigged and kept case:

• a first launch clones the root at its branch, with the root's path as origin
• the clone is not at its place until git clone has finished (a git on PATH runs the real one and notes whether <workspace>/stack exists when clone returns)
• a later launch fast-forwards a clean clone after a commit to the root, then finds it current
• a clone ahead of the root keeps its commits and counts as current
• a dirty clone (modified, untracked, staged), one on another branch, one diverged and a detached HEAD are kept as they are
• a clone the session rigged is kept, and git runs nothing and writes nothing outside it (the cases under decision 126 above, plus the clone a file and the clone a plain directory)
• a root that can't be cloned refuses with the project id and leaves nothing behind (a plain directory inside another repository, on no branch, missing an object)
• a clone whose root is on no branch, or gone, is kept and named
• no credential or forge remote of the root reaches a clone
• every project in the business file gets its own clone at its own branch

packages/cli/tests/launcher.test.mjs, two tests:

• each launch makes sure the workspace has a clone of the project: cloned, fast-forwarded, or kept and logged; it also pins the instance-running rule. Each host releases its own cto claim (role.release) before it closes, as the existing launcher tests do, so the next host's setup can claim it.
• a project clone that can't be made refuses checkout-failed, from --pm and from a session, with no run and no clone left

packages/harness/tests/bundle.test.mjs, one test: the prompt names the project clones in the workspace, and none when there are none.

Mutants

The mutants ran on round 1, on 6e1f9335. Round 2 changes none of the lines they edit; I did not rerun them.

mutants.sh (31 mutants, with mut.mjs, which edits exactly one match or exits 3). First run 23:32:16Z to 23:35:26Z, mutants.txt: 26 killed, 5 survived. I added two tests for two of the survivors and reran those three lines, 23:36:40Z to 23:36:46Z, mutants-rerun.txt. In all, 28 of 31 are killed.

mutant	first run	rerun
duplicate-key-ok	survived	killed, "the origin url twice, both the root"
clone-in-place	survived	killed, "the clone is not at its place until git clone has finished"
merge-not-ff-only	survived	survived
safe-no-hookspath	survived	not rerun
safe-no-fsmonitor	survived	not rerun

merge-not-ff-only is equivalent on this host. Without --ff-only, a diverged clone needs a merge commit. Under gitEnv() git has no identity: no config and HOME at /nonexistent, and this host's name has no domain, so git refuses with "unable to auto-detect email address (got 'jwoltje@dragon-lin.(none)')". The merge fails and the clone is kept as not-fast-forward, the same as with --ff-only. On a host whose name resolves to a domain, git could form an identity and the "a diverged branch" case would kill it.

safe-no-hookspath and safe-no-fsmonitor are second-line guards and were expected to survive (the comment in mutants.sh says so): the hooks check and the allowlist stop each of those cases before git runs. The !st.isFile() half of the config check was not mutated; a symlinked config is stopped by the walk first.

Sage's row 69 gate overlapped the first run from 23:34:36Z. Sage ruled that no mutant rerun is needed, since each result is explained.

Gate

gate.sh, gate-summary.txt. 00:07:08Z to 00:10:09Z on 2026-10-13, in the slot Rocko cleared, after the busy check. Base 6b0215aa with this build.patch staged; the script checks the manifest 8/8 OK before it starts. Sequential in a clean worktree with node_modules linked and DOCKER_HOST=unix:///nonexistent for the whole run, as Sage asked. All 14 rc=0:

suite	result
seat node --test tests/*.test.mjs	83 pass, 0 fail, 0 skipped
cli	125 pass, 0 fail, 0 skipped
bus	111 pass, 0 fail, 0 skipped
harness	67 pass, 0 fail, 0 skipped
tasks	89 pass, 0 fail, 0 skipped
test-auth.sh	15/0
test-conductor.sh	17/0
test-config.sh	24/0
test-discord.sh	66/0
test-extension-package.sh	18/0
test-foundation.sh	44/0
test-queue.sh	27/0
test-release.sh	4/0
test-task.sh	26/0

With Docker off, the scripts skip what needs a daemon: test-release.sh its state-machine cases (4 run here, 14 in round 1's gate), test-task.sh its adapter seam, workspace, live task and live recall cases. test-queue.sh skips queue verify and render --check, since the worktree isn't the queue's canonical root. This row touches none of what those cases cover. No Docker network was made, and no process was left with a cwd in my worktree.

The round 1 gate (6e1f9335, 23:37:00Z to 23:39:19Z, 13 suites green) is in round 1's packet.

Found, not fixed

• recover() in the launcher: a leftover session whose SIGKILL has not taken effect within 5 s still has its run ended and its role released. A launch of that instance could then reach ensureCheckouts while the old process still writes the workspace. Outside this row's lines.

Secrets scan

I scanned the packet for token, secret, password, api key and private key markers. The matches are test stand-ins: CLAUDE_CODE_OAUTH_TOKEN = "stand-in" and a comment in the launcher test context, and the fake bot:[email protected] origin and http.extraHeader in the "no credential or forge remote" test, which checks that they never reach a clone.