fix(container): link /scratch to the read-only surface scratch root #1146

Merged

coilyco-ops merged 2 commits from issue-1142 into main

2026-07-13 03:26:25 +00:00

coilyco-ops commented

2026-07-13 03:20:39 +00:00

Member

The composed container doctrine promises /scratch as the writable escape hatch on read-only surface sessions, but those sessions keep their scratch root on the gitcache volume (<gitcache>/surface-scratch) for verification headroom, so /scratch never existed. The read-only half of the contract held and the escape-hatch half did not, so every read-only agent paid an ENOENT tax rediscovering a writable path.

Bootstrap now links the doctrine-promised /scratch path to the actual scratch root right after prepareScratchSpace, taking the issue's preferred direction: the doctrine text stays the authoritative contract and the mount becomes true, while the storage stays where the disk headroom is. The alias step is idempotent, repoints a stale link, and leaves a pre-existing real directory alone. On writable engineer runs the scratch root already is /scratch, so the alias is a no-op.

The branch also carries a debt-burndown commit: recent reaper-committed work landed without the pre-commit gate, leaving main red on the code-comments hook (40 violations) and the issue-refs hook. That red gate blocked any hook-clean commit, so this branch reflows the offending comment blocks and rewrites the terse doc refs first.

Verification: TestEnsureScratchAlias covers the fresh link, the write-through probe from the issue, idempotent re-run, stale-link repoint, and the pre-existing-directory case. On a fresh read-only director surface, ls -ld /scratch now shows the alias and touch /scratch/probe succeeds.

closes #1142

ward.workflow: pull-request-and-merge

🤖 Generated with Claude Code

The composed container doctrine promises `/scratch` as the writable escape hatch on read-only surface sessions, but those sessions keep their scratch root on the gitcache volume (`<gitcache>/surface-scratch`) for verification headroom, so `/scratch` never existed. The read-only half of the contract held and the escape-hatch half did not, so every read-only agent paid an ENOENT tax rediscovering a writable path. Bootstrap now links the doctrine-promised `/scratch` path to the actual scratch root right after `prepareScratchSpace`, taking the issue's preferred direction: the doctrine text stays the authoritative contract and the mount becomes true, while the storage stays where the disk headroom is. The alias step is idempotent, repoints a stale link, and leaves a pre-existing real directory alone. On writable engineer runs the scratch root already is `/scratch`, so the alias is a no-op. The branch also carries a debt-burndown commit: recent reaper-committed work landed without the pre-commit gate, leaving `main` red on the code-comments hook (40 violations) and the issue-refs hook. That red gate blocked any hook-clean commit, so this branch reflows the offending comment blocks and rewrites the terse doc refs first. Verification: `TestEnsureScratchAlias` covers the fresh link, the write-through probe from the issue, idempotent re-run, stale-link repoint, and the pre-existing-directory case. On a fresh read-only director surface, `ls -ld /scratch` now shows the alias and `touch /scratch/probe` succeeds. closes #1142 ward.workflow: pull-request-and-merge 🤖 Generated with [Claude Code](https://claude.com/claude-code)

coilyco-ops added 2 commits

2026-07-13 03:20:39 +00:00

chore: burn down pre-commit debt left by hook-bypassing commits a5c0bdee2a

Recent reaper-committed work (fbbc6320, c0fb2de1 and siblings) landed
without the pre-commit gate, leaving main red on two catalog hooks:

- code-comments: 40 violations (comment blocks over the 2-line cap)
  across ten cmd/ward files. Reflowed each block to two lines within the
  90-char cap, keeping the constraint content. The dropped merge-order
  narrative for resolvePlaceholderSentinels lives in fbbc6320's commit
  message.
- issue-refs: terse refs in docs/FEATURES.md and docs/release.md rewritten
  to full-URL links by scripts/lint_issue_refs.py --fix.

No behavior change. Unblocks committing on a clean gate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fix(container): link /scratch to the read-only surface scratch root

test / test (pull_request) Successful in 36s

Details

50f3d92ba6

The composed container doctrine promises /scratch as the writable escape
hatch on read-only surface sessions, but those sessions keep their scratch
root on the gitcache volume (<gitcache>/surface-scratch) for verification
headroom, so /scratch never existed and every read-only agent paid an
ENOENT tax rediscovering a writable path.

Bootstrap now links the doctrine-promised /scratch path to the actual
scratch root after prepareScratchSpace, making the doctrine true on every
surface while keeping the storage where the headroom is. The alias step is
idempotent, repoints a stale link, and leaves a pre-existing real
directory alone.

closes #1142

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

coilyco-ops referenced this pull request

2026-07-13 03:21:59 +00:00

Reaper commits bypass the pre-commit gate and can land a red tree on main #1147

coilyco-ops referenced this pull request

2026-07-13 03:22:26 +00:00

Read-only surface: container doctrine promises /scratch but the mount does not exist #1142

coilyco-ops merged commit fc918b88b0 into main

2026-07-13 03:26:25 +00:00

coilyco-ops referenced this pull request from a commit

2026-07-13 03:26:27 +00:00

Merge pull request 'fix(container): link /scratch to the read-only surface scratch root' (#1146) from issue-1142 into main