stack/agents/herb/work/queue-197/BUILD.md

Row 197 execution ledger

Plan: MANIFEST.md r2, approved by Webby ca6b32d66. Build grant: sage-1390. Suites, image builds and paired proof are not granted. Rebased five documentation commits onto origin/refactor aa1bd209e before code. Existing worktree herb/row197 and plain node_modules symlink retained.

• T1 preflight/steps: in progress.
• T2 locks/status/recovery: pending.
• T3 image/Docker: pending.
• T4 fixtures/timing: pending.
• T5 evidence/acceptance: historical timing done; implementation pending.

Preflight interfaces: T1 RunPaths supplies T2 ownership and T3 image checks. T2 run receipt supplies T4 lane/port state and T5 attribution. T3 image identity is checked before Docker-bearing steps. T4 timings supply T5 pair summaries. No interface conflict found. No product API or assertion changes are authorized.

Ruling: use this approved BUILD.md as the execution ledger, rather than adding skill workspace paths outside the manifest. This preserves the reviewed path boundary. Missing ledger detail would cost recovery time, not product behavior.

Implementation checkpoint 2026-10-20T20:11:58Z

T1-T5 source is present within the approved manifest. Full acceptance is pending. Fresh single-file checks: preflight/supervisor 6/6; state/recovery 11/11; image and Docker guard 4/4; port leases/attribution/proof summary 3/3. No skips or failures. Existing files checked singly: board serve; WebUI serve, preview, proof-cli, tester-cli and service; harness pi and Claude. Stack-release R1 selected single passed 1/1. WebUI service also passed 31/31 with lane-a leases and a 30-byte root. All existing assert lines are unchanged. Shell syntax and diff checks pass.

Observed defects fixed during the single-file cycles: cancellation incorrectly returned zero when a TERM handler exited zero; recovery did not supersede an unclean terminal; status omitted the lock-before-receipt window. Evidence logs retain the failing and passing observations. Source still has no commit because applicable suites have not run. No image build, proof, push or live operation.

Ruling: use an instrumented single-lane author gate on a frozen dirty-source clone before committing source. The new wrapper requires a clean candidate and proven image receipt, while repository rules require green suites before source commits. The author gate retains every suite and assertion, caps concurrency at two, uses own port/state/temp/project roots, and guards Docker against builds. Cost if wrong: the author gate fails; clean-candidate wrapper baselines and the paired proof remain mandatory after source is verified and committed.

Ruling: publish the initial run directory atomically after the start receipt is complete. This avoids a second lane observing a partially written start. A crash before publication has started no test or mutable Docker operation. Cost if wrong: a lane refuses or quarantines; no protected state is bypassed.

Implementation review corrections, 2026-10-20T20:33Z

Webby-0029 reviewed the first implementation packet at f942bd7d4. B1 identified missing manifest tests. B2 identified a test that leased both real bands through a private lock namespace. The old author-gate clear was withdrawn in herb-0019. SOURCE.json, BUILD.patch and gate.sh still describe the old frozen clone. They are not a clear for the edited working tree. No author gate ran.

B2 correction: the helper test uses only the active lane and MOSAIC_GATE_STATE. It compares the other band arithmetically and has no unasserted listener. The occupied-port probe first obtains its own real lease, binds that port, and asserts that its sentinel listener survives refusal. No test reserves another lane's band. Exhaustion narrows only the test process's band to one owned port.

B1 coverage added within the existing approved paths. No case is dropped:

Manifest case	Added check
T1 canonical and builder checkout, existing output	gate-lane.test: direct validateRun refusals
T1 92-byte socket and over-107-byte socket	exact design example with a distinct gt- test root; 108-byte refusal
T1 both candidates carry tooling	validateTooling compares each launcher file, including missing and changed cases
T1 duplicates and NODE_TEST_CONTEXT	repeated package/script fixture is retained; sanitized environment is exercised by both supervised children
T2 one-winner race and inherited FDs	two actual shell wrappers race; a controlled supervisor verifies held FDs, and its child checks that no FD points to either lock file
T2 same checkout and legacy claim refusal	activeConflicts uses synthetic process observations with a live lane and a sibling landing gate
T2 surviving child and interrupted recovery	locked recovery kills a child proven by the private root, preserves a foreign child, is killed during fake Docker cleanup, leaves quarantine, and resumes under a new fixture grant
T3 missing receipt and missing image	verifyImage refuses absent provenance and failing inspection
T3 tag changed mid-gate and at gate end	runGate now uses the same executePinnedSteps boundary exercised by the tests; the next step never runs after a changed ID
T3 mutable-tag rebuild	fake preparation returns a new image ID with identical input digest; the old receipt refuses it
T3 cold and warm counters	preparation records one build and its time; warm execution records zero builds; repeated verification never builds
T4 parallel test-file leases	two generated Node test files hold ports in the same lane/state; locks are checked during child execution and shutdown
T4 exhausted band, occupied port and foreign listener	a one-port process-local band refuses both a held lease and an existing sentinel listener; the listener survives
T4 owner death	a killed allocator releases only its own holder; a foreign lease remains held
T4 lease through child shutdown	parent probes the lock while the fixture test runs and after its child has stopped
T4 fixtureCacheEnv	replacement child environment writes only under separate tmp, jiti and cache directories
T5 unrelated session append	a separate process waits for a running-step barrier, appends under a fixture HOME, and remains unrelated in the resulting metadata attribution

N1 removes the unused closed binding. All leases reserve an unbound endpoint; existing closed options need no call-site change. N2 makes child TMPDIR a tmp subdirectory. N3 normalizes ss interface scopes before checking port 9. N4 uses gt- for unit run roots. N5 documents the canonical node_modules dependency. N6 is recorded: row 200 also edits stack-release.test.mjs; the second landing must rebase and rerun that file singly. Sage was told in herb-0019.

Before Sage's hold, expanded preflight tests passed 11/11, state tests 14/14, image tests 7/7, and the pi/Claude singles passed 8/8 each with separate tmp subdirectories. Later source/test edits still need verification. In particular, the new parallel test-file probe had a cleanup-order defect and is unverified. Its root cleanup ran before child shutdown. Cleanup now stops children before removing their root. Output is retained for a useful failure report. The initial FD probe also assumed Node did not reopen FD numbers; it now checks the actual lock targets. The early passing fixture file covered child allocators, before they were changed to actual generated test files. It is not acceptance of the latest file.

Sage-1448 stopped all node --test runs at 20:30Z for Rocko's browser slot. The remaining owned process tree was stopped at 20:30:32Z. Inspection found no remaining owned test processes afterward. Edits and static inspection continue. 20 module syntax checks, shell syntax and git diff checks pass. Existing-file assertion lines remain identical to HEAD. No test is run during the hold.

Next: after Sage passes Rocko's clear, verify the corrected files singly, including a lane-env helper-file check. Then refresh the frozen clone and all three packet artifacts, send their hashes, and request a new author-gate clear. Suites, image builds and paired proofs still need their own grants. No source commit, push, suite, real Docker build or paired proof has run in this phase.

Refrozen review packet, 2026-10-20T20:41Z

Sage-1454 lifted the single-file hold. Fresh runs passed without failures or skips: review-t1-resume.log 11/11, review-t2-resume.log 14/14, review-t3-resume.log 8/8, review-t4-resume.log 8/8. The helper file also passed 8/8 with lane-a environment in review-t4-lane-a.log. Its retained state had only an a port-lock namespace, no b directory, and every lock was released. Generated fixture Node test entries explicitly use --test-concurrency=2. The child-test probe now finishes and cleans up before removing its root. All 41 new tests pass.

B1 and B2 fixes are ready for Webby's review. No manifest case was dropped. All 25 source paths were copied to a new frozen clone and compared by mode and SHA-256. This supersedes the earlier withdrawn source packet:

• SOURCE.json: 91ba149f2fc039a8bed0e6d1ad5da44b80fb8cbec84d0fa4e38616040138596b
• gate.sh: 48e06e23e45d3484755f8cd79ad5b6dfde5ef4f960081e7c455a2540e707fed1
• BUILD.patch: 0b3871bd9848ca223c7cda50266debc04643e5d986eb7f0fece096aaf25ff43e
• Frozen checkout: /mnt/storage/scratch/mg197-a-d22dacd92735/wt
• Output: /mnt/storage/scratch/mg197-a-d22dacd92735/out
• Temporary root: /mnt/storage/scratch/ga-VPXhG7 (30 bytes)
• Compose project: mg197-a-d22dacd92735

After an explicit author-gate grant, run this command with Sage's actual ID:

env MOSAIC_GATE_GRANT=ACTUAL_SAGE_GRANT_ID bash /home/jwoltje/.t3/worktrees/mosaic-stack/herb-row197/agents/herb/work/queue-197/gate.sh > /mnt/storage/scratch/mg197-a-d22dacd92735/out/gate.log 2>&1

No gate or suite has started. Queue order from sage-1454 is 192, 201, 204, 200, Gander, then 197. No branch deletion is authorized or attempted. Any later rebase uses a new branch name, and pr-merge.sh -d stays off under #426(a). Whichever of rows 197 and 200 lands second must rerun stack-release singly. Clean-candidate wrapper baselines, image preparation and paired proofs remain separately gated acceptance work. There is still no source commit or push.

Implementation approval and final notes, 2026-10-20T20:47Z

Webby-0031 approved r2 in REVIEW-impl-r2.md at 1f404c973. Their static review verified every source hash/mode and patch result, and all B1/B2 cases. No queue review request comment exists yet; Sage owns creating it if needed.

Folded all three optional notes into the same approved paths. The helper file's standalone fallback now shares /mnt/storage/scratch/mosaic-gate-lanes with real lane-a leases and leaves its stable lock files in place. Band assertions use the imported BANDS. Both T5 polling children fail after five seconds if their barrier is missed. README records the shared standalone namespace and deadlines.

Fresh single-file logs review-r3-fixtures.log and review-r3-lane-a.log both pass 8/8 with zero skips. The lane-a run has no b lock directory, and every lock was released. Syntax and diff checks pass. No existing test assertions or timeouts changed. Remaining source matches the 11/14/8-file checks from r2.

Refreshed all 25 source rows in the existing frozen checkout. New digests replace the preceding r2 packet. gate.sh and its command are unchanged:

• SOURCE.json: 3584763642506e81a532c839bdd07b111d25daa87e35dbe441d8e8c01a2c2aab
• gate.sh: 48e06e23e45d3484755f8cd79ad5b6dfde5ef4f960081e7c455a2540e707fed1
• BUILD.patch: 55fe390da17ab926a0593d39e79561abe52756a1b1a2c756ec57f45d90f10fde

Author gate remains unstarted and queued for Sage's explicit grant. No source commit, suite, image build, paired proof, push or branch deletion ran.

R3 approval receipt

Webby-0033 approved r3 in REVIEW-impl-r3.md at a5643f9bd. Static review verified the three packet hashes, all 25 source rows, and the patch result. Their review accepts N1-N3; no additional hang-guard test is requested. No queue review request comment exists yet, so Webby has not recorded a queue review.

Read-only verification after receipt confirms that the approved packet hashes and all 25 worktree/frozen source hashes and modes still match. Source and gate script stay frozen. The author gate has not started and still needs Sage's grant.

Queue review round 1

Sage-1476 authorized moving row 197 to in-review before the author gate. Created CANDIDATE.sha256 from the same 25 reviewed SOURCE.json rows. Its digest is 6318f0d0bba9ee90ccaa3503cac8c2e04c6397f2ef6c3564f687fbc2092989e3. Ran the queue move from the canonical checkout with op herb-197-review-r3. The move succeeded at revision 2395, opening round 1 on #1695. The request post failed before send because MOSAIC_GITEA_CREDENTIAL_FILE is not set; revision 2396 records the failed outcome. Exit code 1 describes the failed post, not a failed row transition. Read-back confirms state in-review and the correct candidate. Sage will post as jarvis and give Webby the request comment number. No credential lookup, alternate post or retry was attempted here.

SOURCE.json, BUILD.patch, gate.sh and all 25 frozen source rows remain unchanged. Latest slot order is row 190 r2, 201, 204, 200, Gander, then Herb. No gate starts before Sage sends an explicit grant ID.

Follow-on assignment

Sage-1503 assigns row 215, Case 2 C2-04, to Herb after row 197 (queue rev 2455, Gosalyn design r11). Read docs/plans/2026-10-20_case2-rows.md, C2-04 section, at 5b8def2f1 when starting that row. Its required base is origin/refactor 305857c8f. This assignment does not replace row 197 or authorize its gate. Keep row 197's approved source frozen while awaiting Sage's grant. Start row 215 only after row 197, using a new branch name under the existing fleet rule.

Round 2 merge preparation on row 233

Sage-1757 replaces history replay with one candidate commit on 57f59e0c3. The attempted history replay on herb/row197-r2-233 had already finished when that instruction arrived. Its only conflict was the append-only BUILD-LOG tail. That branch remains for history; none of its replayed commits is in this round. The current branch is herb/row197-r3-233, directly from 57f59e0c39.

Stash correction: shared refs/stash was used incorrectly. The exact entry 2767b88549dfd8c7e810908b5416876fa50cb571 is now kept on herb/row197-r3-wip. After verifying stash@{0} still named it, only that entry was dropped. The two other entries remain. No further stash creation, force push, branch deletion or refs/stash mutation is planned. A separate working-copy backup is /mnt/storage/scratch/herb197-merge-W4oiLg.

Sage-1760 requires preserving every landed hunk on every changed manifest path. Checked each of the 25 r1 paths with git diff aa1bd209e 57f59e0c3 -- PATH. Exactly three changed upstream. Their r2 diff against 57f59e0c3 is captured in r2-merge-only.patch:

Merged path	Only row 197 changes against landed base	Landed content retained
packages/cli/tests/stack-release.test.mjs	leasePort and laneAfter imports; freePort now calls the lease helper	All landed tests, including row 233's tests after R15 and BACKUP_STORE checks
packages/webui/tests/service.test.mjs	leasePort and laneAfter imports; closedPort now calls the lease helper	SEND_REFUSAL permits --sso; default unit rendering removes the @CONFIG_ENV@ line
scripts/test-discord.sh	fixture PI_CODING_AGENT_DIR setup; optional two-worker nested Node cap	Row 190's absent scratch MOSAIC_CONFIG selection and caller-config restoration

The other 22 paths equal the r1 reviewed source bytes and modes. r2-MERGE.json lists every path, its r1/r2 digest, mode, upstream-change flag and equality result. Source copies came from the hash-verified r1 frozen checkout. Original r1 digest: 6318f0d0bba9ee90ccaa3503cac8c2e04c6397f2ef6c3564f687fbc2092989e3. No existing assertion or timeout line differs from the landed base. Static checks only: 20 module syntax checks, four shell syntax checks and git diff check pass. BUILD-LOG.md equals 57f59e0c3 byte for byte and is outside this commit.

Sage explicitly requested the local candidate SHA before granting tests. This commit is an untested preparation checkpoint, not gate evidence. No tests or push are authorized yet. r2-TEST-FILES.txt lists the requested grant scope: 16 Node test files singly and scripts/test-discord.sh, test-foundation.sh and test-queue.sh. The four stack-release consumers are stack-release.test.mjs, stack-release-external.test.mjs, stack-upgrade.test.mjs and stack-instances.test.mjs. The shared stack-release-fixture.mjs is exercised by its importing test files, not run as a standalone test. This covers all 13 touched Node test files plus three additional stack-release consumers and all three touched shell suites.

Current slot order from sage-1760: Gizmoduck, Launchpad, Darkwing, then Herb, around 06:30Z. Wait for an explicit grant. After granted checks and authorized push, build the new candidate manifest from that pushed tip and open the merge-scoped round 2. Old SOURCE.json, CANDIDATE.sha256 and gate.sh remain r1 historical artifacts and are not a clear to run the merged candidate.

Round 2 rebuilt on row 234

Sage-1776 names landing c771a36f4b. Built a new branch, herb/row197-r4-234, directly from that landing. No history replay, stash, force push, branch deletion, test run or push is involved. The prior candidate a3b7cbde8 remains untested and is not the queued candidate.

Checked git diff --name-only 57f59e0c3 c771a36f4 against all 25 source paths. Only packages/cli/tests/stack-release.test.mjs overlaps; the other 24 do not. The full comparison is in r2-on234-OVERLAP.txt. The stack-release file starts from the landing and keeps both T46 untimed entries, host_grants and hosts. Its only changes against the landing are the leasePort and laneAfter imports and freePort's call to the lease helper. r2-on234-merge-only.patch records those hunks. Existing assertions and timeouts match the landing exactly.

Every other source path equals a3b7cbde8 byte for byte and retains its mode. This includes the previously merged service and test-discord files, preserving all landed --sso, CONFIG_ENV and scratch-config handling. The earlier evidence r2-MERGE.json still records those three pre-234 merge cases. The new r2-on234-MERGE.json records each current digest, prior digest, mode and equality result. BUILD-LOG.md equals the new landing byte for byte and is excluded.

Static check of the changed Node file and the candidate diff pass. No tests were run. The scope stays r2-TEST-FILES.txt: 16 Node files singly plus the three shell suites. No manifest or queue round is rebuilt until granted checks and authorized push. Old SOURCE.json, CANDIDATE.sha256 and gate.sh remain historical r1 evidence. The test slot follows Darkwing 240 and needs Sage's explicit grant.

Round 6 preparation (sage-1883, mos-1162)

New branch herb/row197-r6 starts at fefd54e13, after the standalone row 212 landing ee7b2f137. No r5 manifest path changed between e7078e6a8 and this base; all 32 r5 blobs and modes were copied intact before the two umask changes. No history replay, stash, force push or branch deletion.

executeSteps now launches each argv through /bin/bash with umask 022 and exec, preserving the process group and argv boundaries. The supervisor and gate-lane.sh retain 077, including state, locks, private logs and roots. New gate-lane tests assert the actual child umask and created file mode, the unchanged parent mask, private log mode, and actual wrapper-created state/lock modes. No shell, image preparation, credentials test or other existing assertions changed. process.test.mjs equals the landed base; lane-image.mjs equals r5. N7 remains DEFERRED at fefd54e13; rows 243 and 244 own the explicit chmod and PI_AUTH_FILE fixtures respectively.

Read Sage's permitted failed pkg-bus log: process.test startup token refusal saw ready.ok true, consistent with inherited 077 narrowing its fixture mode. No further diagnostic read of the retained ga-8I3iZc root is needed. No r6 tests or probes have run. Source commit, push and new manifest await the explicit granted checks. r6-OVERLAP.json records the empty overlap.

Sage-1892 focused grant: gate-lane.test whole 13/0, process.test whole through executeSteps 8/0, zero skips/cancellations. Syntax checks passed. All new umask/mode assertions passed. No Docker, image, lane or proof run. Empty /proc cwd/argv scan and removal recorded in r6-granted/cleanup.json; clear herb-0068 at 09:21Z. The source matches r5 on 29 of its 32 paths, including modes. Only BUILD.md, gate-lane.test.mjs and gate-lane.mjs differ. The new r6-OVERLAP.json records the base comparison. No process test edit. Sage-1895 authorizes one source commit and seat-only push after range check.

Round 7 preparation (sage-1951, sage-1955)

The r6 proof passed all package suites with the original process.test, then failed script-release. The guard injected --no-build into compose run; Compose 5.5.1 rejects it before container creation. The old unit test only asserted the same invalid argv, so it could not detect this compatibility error. This supersedes no-build-flag claims in the historical packet.

herb/row197-r7 starts at b1fece6f0. No r6 manifest path changed between fefd54e13 and this base; all 33 r6 blobs/modes were copied intact before r7 tests were authored. No history replay, stash, force push or deletion. Sage-1955 accepts the private tempRoot/compose-no-build.yaml override, mode0600, with build: !reset null and image pinned to the receipt's imageId. The guard owns the -f arguments and forces run --pull never --no-deps. Caller-supplied Compose config/build/pull options remain refused. The existing proof removes successful temp roots and retains failed roots; the override stays within that same cleanup ownership.

Tests first: installed-binary run --help before SERVICE checks parser acceptance without starting a container. A separate compose config --format json check uses the actual candidate compose.yaml, made-up env/auth paths, and an empty Docker config directory, asserting no build key and the exact pinned image. The no-build-restoration mutant must fail that parser test. No test, probe or Docker command has run on r7; waiting for Sage's grant.

Primary references: Docker's merge reference documents !reset null: https://docs.docker.com/reference/compose-file/merge/#reset-value Docker's run reference documents --pull and --no-deps, with no --no-build: https://docs.docker.com/reference/cli/docker/compose/run/ Installed 5.5.1 acceptance and merged configuration are still unverified.

Sage-1956 focused grant, 2026-10-21 11:19-11:21Z: busy check CLEAR. Whole gate-lane-image.test on the r6 guard: 9 pass, 2 fail. The installed Compose parser emitted unknown flag: --no-build; the other expected failure was the missing override helper. No cancellation or skip. After the fix, whole file 11/0. The committed r7-no-build.mutant.patch restores the invalid flag. Applied only for the installed parser regression: 0/1 with the same unknown-flag error, killed. Restored source and whole file passed 11/0 again. Both approved node --check commands passed. Empty /proc cwd/argv scan; clear herb-0073 at 11:21:04Z. No container start, image build, lane, proof or full suite ran. Logs/counts/scan are in r7-granted/ (local run evidence).

The guard supplies both absolute -f paths, suppressing automatic override selection, pins receipt imageId, removes build via !reset null and adds --pull never --no-deps. Its main entry publishes the override before Docker runs. A unique private staging file plus hard-link publication prevents partial writes or replacement under concurrent guard calls; existing bytes, mode0600, file type and ownership must match, with O_NOFOLLOW on reads. The file stays under the run's short private tempRoot for existing proof cleanup. Caller Compose options remain allowlisted and config/build/pull options refuse. The actual installed Compose config test reports no build key and the exact image ID; parser help is before SERVICE, so no container operation can run. Fixtures supply made-up env/auth paths and empty Docker configuration. Existing image provenance, cleanup and umask behavior remain.

Range check: one source commit on b1fece6f0, same 33 r6 paths plus the mutant patch and r7 overlap receipt (35 paths). Thirty r6 paths retain the same blob/mode. Only lane-docker.mjs, gate-lane-image.test.mjs and BUILD.md differ from r6. process.test and BUILD-LOG equal the landing. No force push, branch deletion, history replay or other source edits. Sage-1956 authorizes the source commit and seat-only push; fresh proof remains Sage's action.

Round 8 preparation (sage-1979)

The r7 D5 proof passed business and bus, then failed the two installed Compose probes in pkg-cli. Their subprocess fixture retained the lane's shim-leading PATH but omitted MOSAIC_GATE_DOCKER_RECORD, so the shim read an undefined path. This is a test context error; the production guard stays byte-identical to r7.

New herb/row197-r8 starts at 5c6f73ed7. None of r7's 35 manifest paths changed from b1fece6f0 to this base. Tests choose the record's real absolute Docker path when a lane record is set; outside lanes they keep using docker. Only the two read-only help/config probes use this helper. The subprocess env still holds fixture-only configuration; the record need not propagate to it. No run or policy allowlist is widened.

Sage-1979 grants 215's 16 singles first, then r8's normal and lane-shaped shim-leading PATH whole-file checks and the record-lookup-removal mutant. The shim fixture invokes the actual unchanged guard, with a private made-up record naming the real Docker binary. No image build, container start, lane or proof is part of r8 checks. No r8 checks have started yet.

Sage-1979 r8 checks followed 215's early singles, then clear herb-0078 at 2026-10-21 12:09:28Z. Whole gate-lane-image.test normal PATH11/0; whole actual guard-shim-leading PATH plus private record11/0. The committed r8-record-lookup.mutant.patch removes the lookup: installed-Compose argv regression0/1, killed with the original Received undefined path error. Restored code, repeated whole shim-PATH file11/0. All zero skips/cancellations. Logs/counts/fixture metadata/empty /proc cwd+argv scan are in r8-granted/. Both 215 and r8 private roots were removed after an empty process scan. No image build, container start, suite, lane or proof ran for r8.

Range: one commit on5c6f73ed7. Of r7's35 paths,33 keep the same blob/mode; only gate-lane-image.test and this BUILD.md change. The r8 mutant and overlap receipt are added. The production guard and all other tooling match r7. BUILD-LOG and process.test equal the landing. No history replay, force push, branch deletion, live state change or policy widening. Fresh proof remains Sage's action after Webby's merge review.