# 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. ## Candidate and base Base `c974cafa`. `build.patch` is `git diff --binary c974cafa` of eight paths, the two new files included. Apply it with `git apply --index` to a detached worktree of `c974cafa`; `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) I built on `6e1f9335`. Row 69's landing, `90d7ed66`, then changed `packages/cli/README.md` in the launch section. My patch applied to `7f0f54ab` without conflict, and `c974cafa` touches none of the eight paths. After the move I reflowed three lines of that README paragraph that my insert had left ragged ("directory, spawns the runner" stood alone). The other seven files are byte-identical to the ones the gate below ran on. The gate ran on `6e1f9335`, so it predates row 69's cli changes (`app.mjs`, `screens.mjs`, `app.test.mjs`). Neither touches the launcher or this row's tests. Filbert's review run on `c974cafa` is the first run on the new base. ## Row 90 overlap (decision 127) Row 90 round 2 (Dewey, manifest digest `95611274`, `build.patch` sha256 `77de6251`) also edits `packages/harness/src/bundle.mjs` and `packages/harness/tests/bundle.test.mjs`, on other lines. Both orders, each on a fresh worktree of `c974cafa`: | order | result | |---|---| | row 90 applied, then `git apply --check` of row 91 | OK | | row 91 applied, then `git apply --check` of row 90 | OK | After applying both in each order, the two bundle files are byte-identical between orders. In `prompt()` the clones line comes after the Workspace line and row 90's stop line goes after the token line. I did not run the harness suite on the combined tree. Whichever row lands second reruns the rebase check and the full gate. ## What changed - `packages/seat/src/checkout.mjs`, new. `ensureCheckouts({ workspace, projects, env })` makes sure each project of the business file has a clone at `//`. No clone: `git clone -q --no-hardlinks --template= --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", ": ")`. 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 `/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 `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`. 23:37:00Z to 23:39:19Z, after the mutant rerun, so with both new tests. Base `6e1f9335` plus the candidate as it was before the move to `c974cafa` (see "Candidate and base"). Sequential in a clean worktree with `node_modules` linked, all 13 rc=0, 0 skipped: | suite | result | |---|---| | seat `node --test tests/*.test.mjs` | 83 pass, 0 fail | | cli | 122 pass, 0 fail | | bus | 108 pass, 0 fail | | harness | 66 pass, 0 fail | | `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` | 14/0 | | `test-task.sh` (`DOCKER_HOST=unix:///nonexistent`) | 26/0 | After the gate I removed the `wt_default` Docker network it left (created 23:39:07Z, 0 containers). ## 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:s3cr3t-token@git.example` origin and `http.extraHeader` in the "no credential or forge remote" test, which checks that they never reach a clone.