enhance(#3897): ADR-3473 §8.3 rungs 2-4 — runtime marker, derived Codex sandbox, short-form depends_on (#3941)

* test(#3897): failing-first coverage for §8.3 rungs 2-4

ADR-3473 §8.3 has four rungs; #3883/PR #3896 shipped the first. This pins the
other three RED before any fix.

Rung 2 — the install marker has four readers and resolveRuntime is not one.

  resolveRuntime resolves GSD_RUNTIME > config.runtime > 'claude' and reads no
  marker at all, while bin/install.js writes one (#2297) and FOUR hand-rolled
  readInstallRuntimeMarker copies exist: src/model-resolver.cts:65 (cached, with
  test seams), hooks/gsd-agent-isolation-guard.js:112, and TWICE in
  hooks/gsd-cursor-subagent-start.js at :346 and :355. Four copies of one rule.

  Fixtures and seam names mined from PR #3382 rather than re-derived; it
  implemented this rung and was closed "not on the merits".

Rung 3 — the sandbox map, and the fallback that was the real defect.

  Measured across all 35 files in agents/, deriving workspace-write iff tools:
  declares Write or Edit:

    - all 11 CODEX_AGENT_SANDBOX entries derive to their mapped value exactly,
      zero disagreements — the map carries nothing the contract does not
    - 24 roles fall through `|| 'read-only'`, of which 16 declare Write or Edit

  So the map is redundant and the silent fallback is the defect. The maintainer
  chose to derive but hold those 16 at read-only pending the question of whether
  Codex enforces sandbox_mode or merely advises; HALT.md records it.

  T20 asserts the emitted sandbox_mode PER ROLE against a captured baseline, not
  in aggregate — an aggregate passes while one role silently widens, which is
  the proxy-instead-of-identity shape this repo names. T24 and T25 fail on a
  stale hold, so the hold list cannot rot into the subset map being deleted.

Rung 4 — shortFormToId, recovered rather than invented.

  I nearly reported this as another wrong §8.3 claim: `git log -S shortFormToId`
  returns only documentation commits. That was the wrong instrument. Direct
  inspection of sdk/src/query/phase.ts at 11918dcc3^ shows five occurrences, and
  the tests match that code rather than a guess at its semantics — including
  first-write-wins on a duplicate short form.

  T43 asserts at the consumer's output: the emitted `waves` map from the real
  CLI, which pre-fix collapses to {"1":[...]} because every short-form edge is
  dropped. A unit assertion on resolveDependencyId would have passed throughout
  this defect's life.

Observed RED, this tree:
  rung 2   11/11 fail — no marker rung, no seams
  rung 3   T23,T24,T25,T26,T30 fail; T28 fails (validate agents passes a TOML
           whose sandbox_mode disagrees — it checks presence only)
  rung 4   T42,T44 fail; T43,T49 fail with waves collapsed to a single wave 1

Green and staying green: T20/T21/T22/T27 as captured baselines, #3885's
unresolvable-token warning and wave-verdict suppression, and #3785's
display-mapping passthrough. If the third tier over-reaches, those go red — that
is their job.

Disclosed weakness: T45 (a canonical id with no dash is not short-form indexed)
cannot be isolated behaviorally, because planMap always masks it. It is a
non-crash boundary pin, weaker than the other rows, and is recorded as such
rather than presented as equivalent.

Design:      .gsd/phase/feat-3897-adr3473-83-rungs/40-design.md
Test matrix: .gsd/phase/feat-3897-adr3473-83-rungs/50-test-matrix.md
Decision:    .gsd/phase/feat-3897-adr3473-83-rungs/HALT.md

Refs #3897

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

* enhance(#3897): §8.3 rungs 2-4 — one marker reader, a derived sandbox, the third depends_on tier

ADR-3473 §8.3 has four rungs. #3883/PR #3896 shipped the first. These are the
other three.

Rung 2 — the install marker had four readers, and resolveRuntime was not one.

  resolveRuntime resolved GSD_RUNTIME > config.runtime > 'claude' and read no
  marker, while bin/install.js writes one (#2297) and four hand-rolled
  readInstallRuntimeMarker copies existed: src/model-resolver.cts (cached, with
  seams), hooks/gsd-agent-isolation-guard.js, and twice in
  hooks/gsd-cursor-subagent-start.js.

  model-resolver's was already the house idiom, so it was promoted rather than
  replaced: src/runtime-slash.cts now owns it, and model-resolver plus both
  hooks delegate. The hooks reach it through ensureRuntimeBuild(), the seam
  lint-hooks-runtime-build-seam enforces. No import cycle existed - checked
  both directions before moving anything.

  The marker is the THIRD rung: env > project config > marker > 'claude'.

  N1 was checked rather than assumed, and my first reading of it was wrong. A
  marker holding an unknown name comes back essentially verbatim, which looked
  like a validation gap. Measured against the env rung with the same inputs -
  including "../../etc/passwd" and "claude;rm -rf /" - the two are identical,
  because they share resolveRuntimeNameFromCandidates. N1 asks for exactly that,
  and it is met. The residual (the shared normalizer normalizes shape, it does
  not validate against the known-runtime set) is pre-existing on the env rung
  and plausibly deliberate, since a new runtime should not need a code change.
  The marker also does not widen the trust boundary in any real sense: it lives
  inside the install tree beside the code, so anyone who can write it can write
  runtime-slash.cjs itself.

Rung 3 — the map was redundant; the silent fallback was the defect.

  Measured across all 35 files in agents/, deriving workspace-write iff tools:
  declares Write or Edit: all 11 CODEX_AGENT_SANDBOX entries derive to their
  mapped value exactly, zero disagreements. The map carried nothing the contract
  did not already have, so it is DELETED rather than reconciled. What was
  actually broken is `|| 'read-only'`, which silently under-granted 24 of 35
  roles.

  16 of those 24 declare Write or Edit and would widen under derivation. Per the
  maintainer's decision (HALT.md), they are held at read-only pending the
  question of whether Codex enforces sandbox_mode or merely advises. Emitted
  TOML is therefore byte-identical for all 35 roles - asserted per role, not in
  aggregate, because an aggregate passes while one role silently widens.

  The hold list self-invalidates. A hold whose role no longer derives broader
  fails, and so does a hold naming a role with no agents/<name>.md. Without
  that it would rot into exactly the hand-maintained subset map being deleted,
  and this commit's own ledger claim would become false over time. Both cases
  were proved by injecting them and watching them throw.

  Two committed tests asserted the deleted map's existence and contents. They
  were pinning the thing being removed, so the tests moved rather than the
  production code: the 11 role-value pairs survive as a test-local
  PRE_3897_CODEX_AGENT_SANDBOX baseline, and the assertions now drive the real
  derivation against real agents/*.md. The coverage is preserved; only its
  source moved out of production code.

  validate agents gains checkCodexSandboxPosture, mirroring the existing
  checkCodexModelPosture: each installed TOML's sandbox_mode must equal the
  role's expected value, failing with role, expected and found. It previously
  checked file presence and manifest completeness only, so a TOML whose
  sandbox_mode disagreed passed.

Rung 4 — shortFormToId, recovered rather than invented.

  I nearly reported this as another wrong §8.3 claim: git log -S returns only
  documentation commits. Wrong instrument. sdk/src/query/phase.ts at 11918dcc3^
  carries five occurrences, and the implementation here matches that code rather
  than a guess at its semantics - including first-write-wins on a duplicate
  short form, deterministic from the sorted plan order.

  It resolves the bare plan number: depends_on: ["01"] now reaches
  26-01-auth-hardening. That is a control-flow change, not a diagnostic one -
  plans that silently collapsed into a single wave 1 now execute in their
  declared waves, and execute-phase.md consumes those wave values.

  In-phase only, by construction: the map is built from this phase's rawPlans,
  so a same-named short form in another phase does not resolve.

  #3785's display-mapping passthrough and #3885's unresolvable-token warning and
  wave-verdict suppression are untouched and stay green. If the third tier had
  over-reached, those are what would have caught it.

Refs #3897

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

* fix(#3897): close a fail-open I introduced, and wire the posture check to its command

Two blockers from review. Both are mine, and one is a security regression my own
change created.

1. A held role could escape its hold by editing its own frontmatter.

  The Codex install loop set the sandbox identity from the agent's frontmatter
  `name:` field rather than from its filename, so the hold lookup keyed off a
  value the file itself declares:

    deriveCodexSandboxMode('gsd-doc-writer',   <real file>)          -> read-only
    deriveCodexSandboxMode('gsd-doc-writer-x', <same file, name: edited>) -> workspace-write
    deriveCodexSandboxMode('GSD-Doc-Writer',   <same file, name: recased>) -> workspace-write

  What makes this a blocker rather than a nit is the DIRECTION. The deleted
  CODEX_AGENT_SANDBOX map had the identical lookup-key quirk, but it was an
  allowlist: an unmatched key fell back to read-only, which is safe. The new
  scheme derives workspace-write from the tool contract and uses the hold as a
  subtraction, so the same mismatch fails OPEN. I converted a fail-closed quirk
  into a fail-open one and did not notice; the isolated reviewer proved it by
  execution.

  Neither safety net caught it. validateCodexSandboxHolds only checks that
  <key>.md exists, never that a file's derived identity matches its key.
  checkCodexSandboxPosture looks the canonical source up by the installed TOML's
  filename, finds nothing for a renamed agent, and treats it as a custom
  non-roster agent — silently no violation.

  The identity is now the FILENAME STEM, which is what validateCodexSandboxHolds
  already validates and what an attacker editing frontmatter cannot change
  without renaming the file — at which point the existing validator catches it.
  The lookup is case-insensitive so a recase does not slip past either. The
  frontmatter name still drives the TOML body and filename, unchanged; only the
  sandbox identity moved.

  All 35 roster files were checked: name matches filename stem everywhere, so a
  stricter "they must agree or throw" invariant would have been safe against real
  content. It is deliberately NOT added — it would abort an install on a tampered
  file where emitting a correctly-derived read-only TOML is the safer outcome.
  Recorded as a fork rather than decided silently.

2. checkCodexSandboxPosture was exported and never called.

  cmdValidateAgents (src/verify.cts) called checkAgentsInstalled and
  checkCodexModelPosture only; grep for the sandbox check in that file returned
  nothing. So criterion 3 — "validate agents fails on semantic drift, not only on
  missing files" — was unmet, and `validate agents` behaved exactly as before.
  That is ADR-3473 Decision 2's named shape: a declared policy with no executor.

  It also meant the T28 test asserted at the helper's return value while the
  COMMAND stayed broken — the ADR-3180 Decision 4(b) failure this epic exists to
  close, committed by me while enforcing it elsewhere in the same epic.

  Now wired as an additive `sandbox_posture` field beside `codex_posture`,
  following the sibling precedent exactly. Drift is report-only, not a non-zero
  exit, because that is what checkCodexModelPosture does — two sibling posture
  checks disagreeing about whether a violation is fatal would be its own defect.
  The choice is recorded in a comment rather than left implicit. A consumer-output
  test now drives the real CLI and asserts on the emitted JSON, and was shown
  failing before the wiring and passing after.

Also corrected a stale artifact: the design's Known limit L1 still claimed rung 3
was not in this deliverable, written while it was halted and false once the
maintainer unblocked it.

Verified after both fixes: the three bypass probes all return read-only, the
per-role table is 35/35 byte-identical, and both hold self-invalidation cases
still throw.

Refs #3897

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

* docs(#3897): the marker rung, the derived sandbox, and the bare plan-number depends_on

Reference: the runtime precedence ladder in docs/CLI-TOOLS.md gains the install
marker rung; docs/COMMANDS.md documents validate agents' new sandbox_posture
field; docs/reference/plan-md.md documents that depends_on accepts the bare plan
number.

Explanation: a docs/features fragment keyed id 3897, so it cannot collide with a
concurrent PR hand-allocating a section number, regenerated into FEATURES.md.

ADR-3473 §8.3 gains an ANSWER blockquote in the document's own correction style,
recording what was measured and built against the section's 2026-08-26 correction
- including the qualification that checkAgentsInstalled itself still checks
presence only, and the semantic assertion lives in a sibling wired into validate
agents rather than folded into it.

No how-to. Both user-visible changes are zero-step: a non-Claude install resolving
its own runtime, and plans executing in their declared waves, both happen without
the user doing anything. docs/how-to/control-the-reported-host-runtime.md covers a
DIFFERENT ladder (resolveReportedRuntime / agent_runtime) that this change does
not touch, and was deliberately left alone rather than edited by association.

No tutorial - nothing multi-step to walk through. docs/AGENTS.md unchanged: it
documents Claude-side tools frontmatter, never Codex sandbox_mode, and the
emitted tools contract did not change.

The prompt layer documents depends_on only by example, not by schema, so nothing
there needed editing - and few-shot-examples/plan-checker.md already showed
depends_on: ['01'], which now actually resolves.

Translated copies of plan-md.md are untouched; the project treats translations as
community-maintained.

Refs #3897

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

* fix(#3897): move the sandbox derivation out of the installer, off the install path, and off a third parser

The full suite came back with 26 failures across four files. Three distinct
causes, mapped individually rather than assuming the first explained the rest.

A. Requiring bin/install.js printed the GSD banner to stdout and corrupted
   `validate agents` JSON.

     Unexpected token '', "[36m   ██"... is not valid JSON

   checkCodexSandboxPosture reached deriveCodexSandboxMode by lazily requiring
   bin/install.js, whose module load prints the ASCII banner. So the command
   emitted banner bytes before its JSON and every JSON consumer broke, including
   ten tests that predate this branch. src/ reaching into bin/ was backwards
   layering that happened to also be loud.

   The derivation now lives in src/codex-agent-toml.cts - the existing Codex TOML
   domain module, no new module and no six-gate ripple - and both bin/install.js
   and src/agent-install-check.cts import it. One owner, which is §8.3's rule
   applied to the fix for §8.3.

B. The stale-hold throw fired on a legitimate partial source dir, and masked a
   security assertion.

   validateCodexSandboxHolds treated "this hold's .md is absent from the install
   SOURCE dir" as a stale hold and threw. A test fixture, or any partial install
   source, legitimately contains a couple of agents. Worse, it threw BEFORE the
   path-escape check, so a test asserting that a `../../evil` frontmatter name is
   rejected got my unrelated error instead of the traversal rejection it was
   written for. A fail-closed check of mine was hiding a real security check.

   The "no stale holds, shrink-only" invariant is a property of the repo's
   canonical agents/ roster, not of whatever directory an install happens to read.
   It is off the runtime path and enforced where it belongs, in the tests that
   already existed for it. A partial source dir now installs cleanly, and the
   evil-name case throws with its own escapes-configHome message again.

C. T8 depended on ambient process.env state.

   The marker/env parity assertion round-tripped through live process.env. It now
   compares against resolveExplicitRuntime's already-exported dependency-injection
   parameter - deterministic and hermetic, same claim. Proven still falsifiable
   rather than assumed: with the marker rung's normalization temporarily bypassed
   the two rungs diverge ("codex\n../../etc/passwd" vs "codex-../../etc/passwd")
   and the assertion fails, then passes again once reverted.

One correction folded in along the way. The first version of the move added
private _extractFrontmatterAndBody/_extractFrontmatterField helpers to
codex-agent-toml.cts - a THIRD copy of frontmatter extraction, where the graph
already shows two (bin/install.js:2348, runtime-artifact-conversion.cts:893).
Adding a third inside the epic whose thesis is one implementation per rule is not
defensible. deriveCodexSandboxMode no longer parses anything: it takes
(identity, toolsValue) and each caller supplies the tools value using the
extractor it already has. Both helpers are deleted. The identity argument is
still the filename stem, so the fail-open fix is untouched.

Verified after all three: `validate agents --raw` emits parseable JSON with no
banner and both posture fields; the four hold-bypass probes still return
read-only; the per-role table is 35/35 byte-identical at 26 read-only / 9
workspace-write; the hold list is still 16.

Refs #3897

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

* fix(#3897): drop a dev-only transitive dep, make the derivation total, retire a stale fallback test

Suite down to 7 failures from 26. Three more causes, mapped individually.

A. My extractor import dragged in a script that does not exist in an installed
   tree.

     Cannot find module '../../../scripts/fix-slash-commands.cjs'

   Chain: src/agent-install-check.cts imported runtime-artifact-conversion.cjs,
   which requires command-roster.cjs, whose line 36 requires
   ../../../scripts/fix-slash-commands.cjs. That path exists in the repo and not
   in an install, so every test exercising a synthetic install dir died at module
   load. I picked that extractor for convenience without checking what it pulls
   in - the same mistake that produced the banner bug, one layer further out.

   agent-install-check now uses a single-purpose extractToolsLine on
   codex-agent-toml.cts. That is deliberately NOT a general frontmatter parser:
   we deleted those helpers a commit ago for good reason, and this reads one
   line. Verified from outside the repo root that requiring either module prints
   nothing and does not throw.

B. A test pinned the deleted name-based fallback.

   'defaults unknown agents to read-only' called generateCodexAgentToml with a
   fixture declaring tools: Read, Write, Edit. Under derivation an unknown agent
   with a writing contract correctly derives workspace-write - design row S6, a
   new writing role gets the contract, not the pin. The behavior it asserted was
   the silent fallback this rung deleted; identity no longer decides the sandbox.

   Replaced with two rows rather than a flipped string: no tools declared ->
   read-only (absence is not a grant), and Write/Edit declared -> workspace-write.
   Strictly more coverage than the row it replaces.

C. The stale-hold check still threw per derivation call.

   Last commit took the roster-existence check off the install path, but
   deriveCodexSandboxMode itself still threw when a hold's role did not derive
   broader FOR THE CONTENT IT WAS HANDED - so it fired on any synthetic fixture
   for a held role.

   The throw is gone, and it cost nothing: if a held role's content does not
   derive broader, the hold pins read-only and derivation returns read-only
   anyway, so the hold is a no-op and there is nothing to fail about. The
   staleness invariant is a property of the real agents/ roster, and
   validateCodexSandboxHolds still enforces it there - confirmed against the real
   roster after the change, not assumed.

   deriveCodexSandboxMode is now total: every (identity, toolsValue) including
   undefined and null returns read-only or workspace-write, never throws.

Verified: validate agents emits parseable JSON; the four hold-bypass probes
return read-only; the per-role table is 35/35 at 26 read-only / 9
workspace-write.

Refs #3897

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

* docs(#3897): put the rung-3 decision in the shipped docs instead of pointing at an ignored path

The ADR entry and the feature fragment both ended their rung-3 explanation with
"see .gsd/phase/feat-3897-adr3473-83-rungs/45-decision-rung3-sandbox.md". That
directory is gitignored (.gitignore:55), so the rationale for holding 16 roles at
read-only was reachable only from the machine that produced it. A reader of the
ADR got a pointer to nothing.

Both now carry the reasoning inline: the criterion asks both that the sandbox
derive from the declared tool contract and that no role gain a broader sandbox,
and those cannot both hold, because a faithful derivation widens 16 roles the
deleted map never listed and that fell through its silent read-only default. The
resolution is derive-and-hold - the derivation owns the rule now, each hold is
released as its enforcement question is answered, and a hold is reversible where
a widened sandbox that turns out to be enforced is not.

Checked before assuming this was a defect class: CONTEXT.md cites
.gsd/phase/<slug>/40-design.md as its standard Design: provenance line in eight
module entries, and four other shipped docs do the same. Citing a phase artifact
is an established convention here, so those are left alone. What was wrong was
specific to these two: they put load-bearing rationale behind the pointer instead
of provenance.

docs/FEATURES.md regenerated from the fragment via scripts/gen-features.cjs
rather than hand-edited.

Refs #3897

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

* fix(#3897): close a fail-open, stop a silent mis-resolution, and read a declaration as a declaration

Two orthogonal reviews on the shipped sha. Three of the findings are the same
failure class this epic exists to close, committed inside it.

1. BLOCKER - the sandbox was decided for one identity and applied to another.

   bin/install.js derived sandbox_mode for the filename stem and then wrote the
   result to `${name}.toml`, where name comes from the file's own frontmatter.
   Make the two disagree and a HELD role's artifact goes wide:

     rename gsd-doc-writer.md -> gsd-doc-writer-v2.md, keep name: gsd-doc-writer
       -> stem is unheld, derives workspace-write, lands on gsd-doc-writer.toml
     add any gsd-*.md whose frontmatter name: is a held role
       -> clobbers that role's toml with workspace-write

   Both emit read-only on origin/next, because the deleted map was an allowlist
   and a miss fell back safe. This is a regression my change introduced. The
   previous review round moved the HOLD KEY off frontmatter to the filename stem
   and left the OUTPUT PATH on frontmatter; my own comment at install.js:6985
   calls that value attacker-editable, four lines above the line that uses it as
   the filename.

   The decision is now made over BOTH candidate identities, most-restrictive
   wins: if either the stem or the emitted name is held, the mode is read-only.

2. MAJOR - hold matching was toLowerCase() only, so confusables escaped.

   Turkish dotted/dotless i, fullwidth, NFD, trailing space/NBSP/dot/newline,
   ./ and ../agents/ all slipped the hold and emitted workspace-write.
   Identities are now basenamed, trimmed of NBSP/zero-width/control characters,
   NFKC-normalized and lowercased - and anything still carrying a character
   outside [a-z0-9._-] is treated as suspicious and derives read-only. We do not
   enumerate confusables; every shipped roster file is ASCII, so refusing to
   widen on an identity we cannot recognize is fail-closed with no false
   positives on real content.

3. MAJOR - the short-form depends_on tier mis-resolved SILENTLY.

   shortFormToId keyed on the last dash-segment of any canonical id with no
   constraint that it is a plan number, so a phase holding 09-FIX-auth-PLAN.md
   made depends_on: ["auth"] bind at wave 2 with zero warnings. This is the
   worst shape in the epic: the unresolvable-token warning fires on a DROPPED
   token, so a MIS-RESOLVED one is invisible and the tool reports a confident
   wave assignment built from a wrong edge. A wrong edge is worse than a missing
   one.

   The segment must now match /^\d+$/, which is exactly the contract
   docs/reference/plan-md.md already documents. This tier was recovered verbatim
   from the retired SDK lineage, which carried the same defect; we are
   deliberately NOT preserving it bug-for-bug, and the comment says so, so the
   next reader does not "restore" it.

4. MAJOR - the derivation was reading a declaration as an absence.

   extractToolsLine read one line, so a YAML list-form tools: block returned only
   its first item. Two roster files use list form, and gsd-nyquist-auditor
   declares Write and Edit there - parsed as "- Read", found no write tool, and
   emitted read-only. Rung 3's headline claim is that sandbox_mode derives from
   the declared tool contract; that claim was false for 2 of 35 roles and
   materially wrong for 1. Reading a declaration as an absence is the silent-drop
   class this epic exists to close.

   Renamed extractToolsValue and taught it both shapes. gsd-nyquist-auditor now
   derives workspace-write and joins CODEX_SANDBOX_HOLDS as its 17th entry, per
   the standing derive-and-hold decision - so emitted TOML stays byte-identical
   at 26 read-only / 9 workspace-write while the hold list finally records every
   role that would widen. A previous pass declined this fix because it moved the
   count; that inverts the priority. Byte-identity is preserved THROUGH the hold,
   not by leaving a parser broken.

   Divergence check, because this is where that bug hides: both paths feeding
   sandbox derivation - install.js's emitter and checkCodexSandboxPosture - now
   route through the one extractor. The tools readers in
   runtime-artifact-conversion and install.js's other frontmatter call sites
   serve Claude-side emission and do not feed sandbox derivation.

Also fixed, each real: the posture check's `found` used a naive whole-file regex
where its own sibling uses the block-aware scanner, so prose inside
developer_instructions produced a false violation; `found` skipped
truncatePostureValue and leaked a 300-char value into validate agents output;
deriveCodexSandboxMode's absolute never-throws claim was false for an object with
a throwing toString; T49 could not falsify cross-phase leakage (its target phase
had its own 01, so a globally-scoped map passed too); T20/N6 iterated a hardcoded
table and pinned the FIXTURE size, so a 36th agent would be silently unchecked;
three tests reimplemented the code they were testing instead of importing it; and
T2-T4 deleted GSD_RUNTIME without restoring it.

Verified: hold list 17, gsd-nyquist-auditor derives workspace-write unheld and
emits read-only held, roster 35/35 at 26/9, depends_on ["auth"] no longer
resolves while ["01"] still does, both identity-bypass cases and every confusable
vector emit read-only.

Refs #3897

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

* docs(#3897): the hold list is 17, and the reason the 17th was missing

The count read 16 because the derivation could not read the declaration it
claimed to derive from: the tools reader was single-line, so a YAML list-form
tools: block returned only its first item and gsd-nyquist-auditor's declared
Write and Edit were read as an absence.

Both the ADR entry and the feature fragment now carry the corrected count and the
reason for it, rather than a silently updated number. Deriving from a declaration
you cannot parse is not deriving, and a flattering count is worse than a wrong
one because it looks settled.

docs/FEATURES.md regenerated from the fragment.

Refs #3897

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

* chore(#3897): backfill changeset pr number

Refs #3897

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

---------

Co-authored-by: sim <sim@local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-08-27 15:19:01 -04:00
committed by GitHub
parent a76ce94d18
commit 9410f7e6e6
22 changed files with 2837 additions and 121 deletions

View File

@@ -67,13 +67,37 @@ const {
mergeCodexConfig,
install,
GSD_CODEX_MARKER,
CODEX_AGENT_SANDBOX,
deriveCodexSandboxMode,
// #3897 rung 3 (ADR-3473 §8.3, option 2 — HALT.md): anticipated new export
// holding the 17 explicit read-only pins for roles whose tool contract would
// otherwise derive workspace-write (16 measured by HALT.md + gsd-nyquist-auditor,
// surfaced by the list-form parse fix). Does not exist on the current tree —
// destructuring a non-existent key is `undefined`, not a throw, so requiring
// this module still succeeds; every test below that touches it fails on its
// own `typeof` guard instead.
CODEX_SANDBOX_HOLDS,
parseTomlToObject,
validateCodexConfigSchema,
} = require('../bin/install.js');
const { resolveNodeRunner } = require('../gsd-core/bin/lib/runtime-hooks-surface.cjs');
const { resolveInstallPlan } = require('../gsd-core/bin/lib/runtime-config-adapter-registry.cjs');
// #3897 fixup: deriveCodexSandboxMode's 2nd param is now the already-resolved
// `tools:` frontmatter VALUE, not raw agent content (codex-agent-toml.cjs no
// longer parses frontmatter at all — no third copy of that extraction).
const {
extractFrontmatterAndBody,
extractFrontmatterField,
} = require('../gsd-core/bin/lib/runtime-artifact-conversion.cjs');
// #3897 list-form parse fix: the ONE shared `tools:`-value reader both
// sandbox-feeding production paths (`bin/install.js`'s `generateCodexAgentToml`
// and `agent-install-check.cts`'s `checkCodexSandboxPosture`) now route
// through — handles inline (`tools: Read, Write`) AND YAML block-list
// (`tools:` + indented `- Item` lines) form. Used below by `realAgentToolsRaw`
// so the test's own measurement of "what does this role's tool contract
// declare" cannot silently disagree with production (the exact generative-
// fix-divergence shape this fix closes).
const { extractToolsValue } = require('../gsd-core/bin/lib/codex-agent-toml.cjs');
function runCodexInstall(codexHome, cwd = path.join(__dirname, '..')) {
const previousCodeHome = process.env.CODEX_HOME;
@@ -483,9 +507,27 @@ tools: Read, Grep, Glob
assert.ok(result.includes('description = "GSD agent gsd-unknown"'), 'falls back to synthetic description');
});
test('defaults unknown agents to read-only', () => {
// #3897 CAUSE B fix: this used to assert the deleted name-based fallback
// (an unknown agent NAME defaulted to read-only regardless of its tool
// contract). Under derivation, identity no longer determines the sandbox —
// the tool contract does (S6: "a new writing role gets the contract, not
// the pin"). Split into the two rows the old single assertion conflated:
// absence of a `tools:` grant (N8) vs. an unknown role that legitimately
// declares a writing tool (S6).
test('unknown agent with no tools: frontmatter derives read-only (N8: absence is not a grant)', () => {
const noToolsAgent = `---
name: gsd-unknown
description: An unknown agent with no declared tools
---
<role>You are an unknown agent.</role>`;
const result = generateCodexAgentToml('gsd-unknown', noToolsAgent);
assert.ok(result.includes('sandbox_mode = "read-only"'), 'no tools: frontmatter -> read-only');
});
test('unknown agent declaring Write/Edit derives workspace-write (S6: the tool contract, not the pin, decides)', () => {
const result = generateCodexAgentToml('gsd-unknown', sampleAgent);
assert.ok(result.includes('sandbox_mode = "read-only"'), 'defaults to read-only');
assert.ok(result.includes('sandbox_mode = "workspace-write"'), 'declares Write/Edit -> workspace-write');
});
// ─── #2256: model_overrides support ───────────────────────────────────────
@@ -919,6 +961,735 @@ description: Maps the codebase
});
});
// ─── #3897 rung 3 (ADR-3473 §8.3, HALT.md option 2): sandbox_mode derives from
// the tool contract, with 17 widening roles held at read-only ────────────────
//
// Spec: .gsd/phase/feat-3897-adr3473-83-rungs/{40-design,50-test-matrix}.md,
// rows S1-S9 / T20-T30. Measured against `next` @ ad6abc896 (HALT.md):
// deriving `workspace-write` iff an agent's frontmatter `tools:` declares
// `Write` or `Edit` reproduces all 11 CODEX_AGENT_SANDBOX map entries exactly,
// and would additionally widen 16 fallback roles that the map never covered.
// HALT.md's 16 was measured against a `tools:`-VALUE reader that only handled
// inline form; the #3897 list-form parse fix corrected `gsd-nyquist-auditor`'s
// YAML block-list `tools:` (previously misread as `"- Read"`, no Write/Edit
// found), which genuinely derives `workspace-write` and adds a 17th widening
// role. `CODEX_SANDBOX_HOLDS` (destructured above; `undefined` on the current
// tree) is this rung's pin list for those 17 — every row below that depends
// on it fails on its own `typeof` guard until it lands.
//
// Deriving-from-real-content is deliberate for T20/T21/T26/T27/T30: a
// synthetic `tools:` fixture cannot prove the CURRENT tree's byte output is
// preserved, only that the derivation LOGIC agrees with a made-up example.
// #3897 rung 3 — bin/install.js's `CODEX_AGENT_SANDBOX` map is DELETED
// (ADR-3473 §8.3): HALT.md measured that deriving `workspace-write` iff an
// agent's `tools:` frontmatter declares Write/Edit reproduces every one of
// these 11 entries exactly, with zero disagreements, making the hand-
// maintained map fully redundant. This literal is the pre-#3897
// `CODEX_AGENT_SANDBOX` contents, preserved here as a regression baseline —
// the only surviving copy of these 11 role -> mode pairs. T21 below and the
// `CODEX_AGENT_SANDBOX (deleted map, derivation regression baseline)` describe
// block both reference this ONE literal rather than duplicating it.
const PRE_3897_CODEX_AGENT_SANDBOX = {
'gsd-executor': 'workspace-write',
'gsd-planner': 'workspace-write',
'gsd-phase-researcher': 'workspace-write',
'gsd-project-researcher': 'workspace-write',
'gsd-research-synthesizer': 'workspace-write',
'gsd-verifier': 'workspace-write',
'gsd-codebase-mapper': 'workspace-write',
'gsd-roadmapper': 'workspace-write',
'gsd-debugger': 'workspace-write',
'gsd-plan-checker': 'read-only',
'gsd-integration-checker': 'read-only',
};
describe('#3897 rung 3: sandbox_mode derivation and the hold list', () => {
const AGENTS_DIR = path.join(__dirname, '..', 'agents');
// #3897 rung 4 (isolated correctness review, MINOR finding 6): T20/N6 used
// to iterate `Object.keys(EXPECTED_SANDBOX_BY_ROLE)` and then pin
// `assert.equal(checked, 35)` — that pins the FIXTURE, not the roster, so a
// 36th agent added to `agents/` would be silently unchecked by the entire
// rung-3 block instead of failing loudly. Driven from the real roster
// instead; a dedicated parity test below fails loudly, naming any file
// present in one set and not the other, the moment the two diverge.
const AGENT_ROSTER_ROLES = fs
.readdirSync(AGENTS_DIR)
.filter((f) => f.endsWith('.md'))
.map((f) => f.slice(0, -'.md'.length))
.sort();
function realAgentToolsRaw(agentName) {
const content = fs.readFileSync(path.join(AGENTS_DIR, `${agentName}.md`), 'utf8');
// #3897 list-form parse fix: route through the SAME shared extractor
// production uses, rather than a naive single-line regex here — a
// second, test-local reimplementation of "read the tools: value" is
// exactly the generative-fix-divergence shape that let this test's own
// `measuredWideningRoles` silently miss `gsd-nyquist-auditor` (YAML
// list-form `tools:`) before this fix.
return extractToolsValue(content) ?? '';
}
// #3897 rung 4 (isolated correctness review, NIT finding 7): this used to
// be a SEPARATE, simpler reimplementation of the real, private
// `_codexToolsDeclareWriteOrEdit` (codex-agent-toml.cts) — a naive
// comma-split-and-includes check that does not handle the real predicate's
// "except" negation form (F5). That is exactly the generative-fix-
// divergence shape CLAUDE.md warns about: a future change to the real
// predicate this copy does not mirror would silently disagree with it
// forever. `_codexToolsDeclareWriteOrEdit` is intentionally not exported
// (module-internal), so rather than reimplementing it a second time, this
// delegates to the REAL implementation through the public
// `deriveCodexSandboxMode`, pinned to an identity guaranteed to never be
// held or "suspicious" (F3) — with no hold in play,
// `deriveCodexSandboxMode(identity, toolsRaw) === 'workspace-write'` IS
// `_codexToolsDeclareWriteOrEdit(toolsRaw)`, byte for byte, because there is
// no second copy left to drift.
const PARITY_PROBE_IDENTITY = 'zzz-parity-probe-never-a-real-or-held-role';
function declaresWriteOrEdit(toolsRaw) {
return deriveCodexSandboxMode(PARITY_PROBE_IDENTITY, toolsRaw) === 'workspace-write';
}
test('sanity: the parity-probe identity used by declaresWriteOrEdit is never itself held or suspicious', () => {
assert.equal(
Object.prototype.hasOwnProperty.call(CODEX_SANDBOX_HOLDS, PARITY_PROBE_IDENTITY),
false,
'the probe identity must not collide with a real hold, or every T20/T21/T24 verdict derived from it would be silently wrong',
);
assert.equal(
deriveCodexSandboxMode(PARITY_PROBE_IDENTITY, 'Read, Write, Edit'),
'workspace-write',
'sanity: an unheld identity that declares Write/Edit must derive workspace-write',
);
});
// T20 (LOAD-BEARING, N6): frozen fixture of TODAY's real, per-role emitted
// sandbox_mode for all 35 roles in agents/ — captured from the CURRENT build
// by running the REAL generateCodexAgentToml against the REAL agent .md
// content (never a synthetic fixture) and committed here. This is the
// safety net for the refactor: it is true today (nothing has changed yet)
// and MUST remain true, per role, after sandbox_mode moves from the map to a
// derivation — an aggregate "35 roles emitted" count would pass even if one
// role silently widened; asserting per role (one test per role, mirroring
// codex-agent-toml.test.cjs's A14 round-trip pattern) does not let that hide.
const EXPECTED_SANDBOX_BY_ROLE = {
'gsd-advisor-researcher': 'read-only',
'gsd-ai-researcher': 'read-only',
'gsd-assumptions-analyzer': 'read-only',
'gsd-code-fixer': 'read-only',
'gsd-code-reviewer': 'read-only',
'gsd-codebase-mapper': 'workspace-write',
'gsd-debug-session-manager': 'read-only',
'gsd-debugger': 'workspace-write',
'gsd-doc-classifier': 'read-only',
'gsd-doc-synthesizer': 'read-only',
'gsd-doc-verifier': 'read-only',
'gsd-doc-writer': 'read-only',
'gsd-dom-verifier': 'read-only',
'gsd-domain-researcher': 'read-only',
'gsd-eval-auditor': 'read-only',
'gsd-eval-planner': 'read-only',
'gsd-executor': 'workspace-write',
'gsd-framework-selector': 'read-only',
'gsd-integration-checker': 'read-only',
'gsd-intel-updater': 'read-only',
'gsd-mempalace-curator': 'read-only',
'gsd-nyquist-auditor': 'read-only',
'gsd-pattern-mapper': 'read-only',
'gsd-phase-researcher': 'workspace-write',
'gsd-plan-checker': 'read-only',
'gsd-planner': 'workspace-write',
'gsd-project-researcher': 'workspace-write',
'gsd-research-synthesizer': 'workspace-write',
'gsd-roadmapper': 'workspace-write',
'gsd-security-auditor': 'read-only',
'gsd-ui-auditor': 'read-only',
'gsd-ui-checker': 'read-only',
'gsd-ui-researcher': 'read-only',
'gsd-user-profiler': 'read-only',
'gsd-verifier': 'workspace-write',
};
// The 17 roles that widen: declare Write/Edit, not in the pre-#3897
// CODEX_AGENT_SANDBOX map (now deleted; PRE_3897_CODEX_AGENT_SANDBOX above
// is the surviving baseline of its contents), so today's `|| 'read-only'`
// fallback under-grants them (16 measured by HALT.md + gsd-nyquist-auditor,
// whose YAML block-list `tools:` the pre-fix single-line reader misread as
// `"- Read"`, hiding its Write/Edit declaration). Computed here from the REAL
// agents/*.md tools frontmatter and that baseline — never hand-copied from
// HALT.md's prose — so this list cannot silently drift from what agents/
// actually declares (T30: "derived, not a second hardcoded copy").
const measuredWideningRoles = Object.keys(EXPECTED_SANDBOX_BY_ROLE).filter((role) => {
const declaresWrite = declaresWriteOrEdit(realAgentToolsRaw(role));
const inOldMap = Object.prototype.hasOwnProperty.call(PRE_3897_CODEX_AGENT_SANDBOX, role);
return declaresWrite && !inOldMap;
});
// #3897 rung 4 (isolated correctness review, MINOR finding 6): the roster
// and the expectation table must cover EXACTLY the same set of roles — a
// role present in one and not the other fails loudly here, by name,
// instead of being silently unchecked by the whole rung-3 block.
test('T20 roster parity: EXPECTED_SANDBOX_BY_ROLE covers exactly the real agents/ roster, no more, no fewer', () => {
const expectedRoles = Object.keys(EXPECTED_SANDBOX_BY_ROLE).sort();
const inRosterNotExpected = AGENT_ROSTER_ROLES.filter((r) => !expectedRoles.includes(r));
const inExpectedNotRoster = expectedRoles.filter((r) => !AGENT_ROSTER_ROLES.includes(r));
assert.deepEqual(
inRosterNotExpected,
[],
`agents/ contains role(s) with no EXPECTED_SANDBOX_BY_ROLE entry: ${JSON.stringify(inRosterNotExpected)} — add them or this rung's coverage silently skips them`,
);
assert.deepEqual(
inExpectedNotRoster,
[],
`EXPECTED_SANDBOX_BY_ROLE names role(s) no longer present in agents/: ${JSON.stringify(inExpectedNotRoster)} — remove the stale entry`,
);
});
for (const role of AGENT_ROSTER_ROLES) {
test(`T20 everyRoleEmitsTheSameSandboxAsBefore: ${role} emits sandbox_mode="${EXPECTED_SANDBOX_BY_ROLE[role]}" byte-identically`, () => {
assert.ok(
Object.prototype.hasOwnProperty.call(EXPECTED_SANDBOX_BY_ROLE, role),
`${role} exists in agents/ but has no EXPECTED_SANDBOX_BY_ROLE entry — see the roster-parity test above`,
);
const content = fs.readFileSync(path.join(AGENTS_DIR, `${role}.md`), 'utf8');
const toml = generateCodexAgentToml(role, content);
const match = toml.match(/^sandbox_mode = "([^"]+)"$/m);
assert.ok(match, `${role}'s emitted TOML must contain a sandbox_mode line`);
assert.equal(
match[1],
EXPECTED_SANDBOX_BY_ROLE[role],
`${role} must emit the SAME sandbox_mode after the derivation refactor lands — a per-role regression, not an aggregate count`,
);
});
}
test('T30 holdListMatchesTheMeasuredWideningSet: CODEX_SANDBOX_HOLDS is exactly the 17 measured widening roles, derived not hardcoded twice', () => {
assert.equal(
typeof CODEX_SANDBOX_HOLDS,
'object',
'install.js must export CODEX_SANDBOX_HOLDS — the hold list does not exist yet',
);
assert.notEqual(CODEX_SANDBOX_HOLDS, null);
assert.deepEqual(
Object.keys(CODEX_SANDBOX_HOLDS).sort(),
measuredWideningRoles.sort(),
'CODEX_SANDBOX_HOLDS must equal exactly the set of roles that declare Write/Edit but were never in the old map — no more, no fewer',
);
// 16 measured by HALT.md against a single-line tools: reader + 1
// (gsd-nyquist-auditor, YAML block-list tools: — the list-form parse fix)
// = 17. `measuredWideningRoles` is computed from realAgentToolsRaw, which
// now routes through the fixed extractToolsValue, so this count moves
// WITH the parser fix rather than needing a second hand-edit.
assert.equal(measuredWideningRoles.length, 17, 'sanity: 17 widening roles against the current agents/ tree, once list-form tools: parses correctly');
});
test('T21 mappedRolesDeriveToTheirFormerValue: every former CODEX_AGENT_SANDBOX entry (11) derives to the identical value from its real tool contract', () => {
for (const [role, formerValue] of Object.entries(PRE_3897_CODEX_AGENT_SANDBOX)) {
const derivesWorkspaceWrite = declaresWriteOrEdit(realAgentToolsRaw(role));
const derived = derivesWorkspaceWrite ? 'workspace-write' : 'read-only';
assert.equal(
derived,
formerValue,
`${role}: the tool-contract derivation must reproduce the former map value exactly (HALT.md: zero disagreements across all 11)`,
);
}
assert.equal(Object.keys(PRE_3897_CODEX_AGENT_SANDBOX).length, 11);
});
test('T22 nonWritingFallbackRoleDerivesReadOnly: a fallback role declaring neither Write nor Edit derives read-only (S2)', () => {
const role = 'gsd-user-profiler'; // tools: Read (no Write/Edit), never in the map
assert.equal(Object.prototype.hasOwnProperty.call(PRE_3897_CODEX_AGENT_SANDBOX, role), false);
assert.equal(declaresWriteOrEdit(realAgentToolsRaw(role)), false);
const content = fs.readFileSync(path.join(AGENTS_DIR, `${role}.md`), 'utf8');
const toml = generateCodexAgentToml(role, content);
assert.ok(toml.includes('sandbox_mode = "read-only"'));
});
test('T23 heldRoleStaysReadOnlyWithARecordedReason: one of the 17 held roles stays read-only via an explicit, reasoned hold (S3)', () => {
assert.equal(typeof CODEX_SANDBOX_HOLDS, 'object', 'CODEX_SANDBOX_HOLDS does not exist yet');
const role = 'gsd-doc-writer'; // declares Write+Edit; one of HALT.md's 16
assert.ok(declaresWriteOrEdit(realAgentToolsRaw(role)), 'sanity: this role must actually declare a writing tool');
assert.ok(Object.prototype.hasOwnProperty.call(CODEX_SANDBOX_HOLDS, role), `${role} must be an explicit hold entry`);
const entry = CODEX_SANDBOX_HOLDS[role];
const reason = typeof entry === 'string' ? entry : entry && entry.reason;
assert.equal(typeof reason, 'string', `the hold for ${role} must carry a recorded reason string, not a bare boolean pin`);
assert.ok(reason.length > 0);
const content = fs.readFileSync(path.join(AGENTS_DIR, `${role}.md`), 'utf8');
const toml = generateCodexAgentToml(role, content);
assert.ok(toml.includes('sandbox_mode = "read-only"'), 'byte-identical output despite the hold, per N6');
});
test('T24 staleHoldFailsRatherThanBeingHonored: a hold whose role no longer derives broader must FAIL, naming the role (S4)', () => {
assert.equal(
typeof CODEX_SANDBOX_HOLDS,
'object',
'CODEX_SANDBOX_HOLDS does not exist yet, so there is nothing to validate for staleness',
);
// Every REAL hold entry, right now, must still derive workspace-write from
// the tool contract. A hold for a role whose tools no longer declare
// Write/Edit is exactly the staleness this row exists to catch; without
// this assertion the hold list is honored unconditionally forever, which
// is the hand-maintained-subset-map defect this rung deletes, rebuilt one
// list later (the ledger claim HALT.md makes).
for (const role of Object.keys(CODEX_SANDBOX_HOLDS)) {
assert.ok(
declaresWriteOrEdit(realAgentToolsRaw(role)),
`stale hold: ${role} is pinned to read-only but its CURRENT tool contract no longer declares Write/Edit — this hold must fail validation, not be silently honored`,
);
}
});
test('T25 holdForUnknownRoleFails: a hold naming a role that no longer exists in agents/ must FAIL (S5)', () => {
assert.equal(
typeof CODEX_SANDBOX_HOLDS,
'object',
'CODEX_SANDBOX_HOLDS does not exist yet, so there is nothing to validate for an unknown role',
);
for (const role of Object.keys(CODEX_SANDBOX_HOLDS)) {
assert.ok(
fs.existsSync(path.join(AGENTS_DIR, `${role}.md`)),
`stale hold: ${role} is pinned but no longer exists in agents/ — this hold must fail validation`,
);
}
});
test('T26 newWritingRoleGetsTheContractNotThePin: a brand-new agent declaring Write, with no hold, derives workspace-write (S6) — RED today, falls back to read-only', () => {
const newAgentContent = `---
name: gsd-totally-new-agent
description: A brand-new writing agent that has never been in the map or a hold
tools: Read, Write, Bash
---
<role>You are a brand-new agent.</role>`;
// Today: CODEX_AGENT_SANDBOX['gsd-totally-new-agent'] is undefined, so the
// `|| 'read-only'` fallback silently under-grants it — the exact defect
// §8.3 exists to fix (24 of 35 roles fell through this fallback).
const toml = generateCodexAgentToml('gsd-totally-new-agent', newAgentContent);
assert.ok(
toml.includes('sandbox_mode = "workspace-write"'),
'a new agent declaring Write, absent from both the map and any hold, must derive workspace-write from its own tool contract — not silently fall back to read-only',
);
});
test('T27 absentToolContractIsNotAGrant: an agent with no tools: frontmatter at all derives read-only (N8/S7)', () => {
const noToolsContent = `---
name: gsd-no-contract-agent
description: Declares no tools frontmatter key at all
---
<role>You have no declared tools.</role>`;
const toml = generateCodexAgentToml('gsd-no-contract-agent', noToolsContent);
assert.ok(
toml.includes('sandbox_mode = "read-only"'),
'absence of a tools: contract must never be read as a grant of workspace-write',
);
});
// #3897 security review follow-up (post-merge blocker): `bin/install.js`'s
// Codex install loop used to key the CODEX_SANDBOX_HOLDS lookup off the
// agent's OWN frontmatter `name:` field (`extractFrontmatterField(frontmatter,
// 'name') || file.replace('.md', '')`) rather than its filename — so editing,
// or merely recasing, a held role's `name:` field (same file, same tool
// contract) silently derived `workspace-write` instead of the pinned
// `read-only`. Unlike the deleted CODEX_AGENT_SANDBOX map (an ALLOWLIST whose
// unmatched-key fallback was `read-only`, i.e. safe), CODEX_SANDBOX_HOLDS is a
// SUBTRACTION from a derivation that defaults to `workspace-write`, so the
// identical lookup-key mismatch now fails OPEN — a severity flip. The fix
// keys the hold off the canonical source FILENAME stem (what
// `validateCodexSandboxHolds` already verifies exists), threaded through
// `installCodexConfig`'s per-file loop independently of the frontmatter
// `name:` used for the TOML body, with a case-insensitive lookup as a second
// line of defense.
test('heldRoleCannotEscapeItsHoldByRenamingFrontmatter_3897: editing or recasing a held role\'s frontmatter name: must not change its sandbox_mode from read-only', () => {
const { installCodexConfig } = require('../bin/install.js');
const heldRole = 'gsd-doc-writer'; // one of the 17 CODEX_SANDBOX_HOLDS entries
assert.ok(
Object.prototype.hasOwnProperty.call(CODEX_SANDBOX_HOLDS, heldRole),
`sanity: ${heldRole} must be a real CODEX_SANDBOX_HOLDS entry`,
);
const variants = [
{ label: 'frontmatter name: edited to a different value', newName: 'gsd-doc-writer-x' },
{ label: 'frontmatter name: merely recased', newName: 'GSD-Doc-Writer' },
];
for (const { label, newName } of variants) {
const tmpAgentsSrc = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-codex-tamper-src-'));
const tmpDest = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-codex-tamper-dest-'));
try {
fs.cpSync(AGENTS_DIR, tmpAgentsSrc, { recursive: true });
const rolePath = path.join(tmpAgentsSrc, `${heldRole}.md`);
const original = fs.readFileSync(rolePath, 'utf8');
const tampered = original.replace(/^name:\s*.*$/m, `name: ${newName}`);
assert.notEqual(tampered, original, `sanity: the frontmatter name: line must actually change (${label})`);
fs.writeFileSync(rolePath, tampered);
// The FILE on disk is untouched (still `gsd-doc-writer.md`) — only its
// frontmatter content changed. validateCodexSandboxHolds only checks
// the file exists, so it does not (and should not) catch this by itself.
installCodexConfig(tmpDest, tmpAgentsSrc);
const emittedTomlPath = path.join(tmpDest, 'agents', `${newName}.toml`);
assert.ok(
fs.existsSync(emittedTomlPath),
`${label}: expected an emitted .toml at ${emittedTomlPath} (named after the tampered frontmatter name, per existing TOML-naming behavior — unrelated to this fix)`,
);
const toml = fs.readFileSync(emittedTomlPath, 'utf8');
const sandboxLine = toml.match(/^sandbox_mode = "([^"]{0,50})"$/m);
assert.ok(sandboxLine, `${label}: emitted .toml must contain a sandbox_mode line`);
assert.equal(
sandboxLine[1],
'read-only',
`${label}: a held role's sandbox_mode must stay read-only even when its frontmatter name: diverges ` +
`from its own filename — the hold is keyed off the file, not a self-declared field. Got: ${sandboxLine[1]}`,
);
} finally {
cleanup(tmpAgentsSrc);
cleanup(tmpDest);
}
}
});
test('N6 (post-fix regression check): every real agents/ role remains byte-identical in emitted sandbox_mode after the filename-identity fix', () => {
// #3897 rung 4 (isolated correctness review, MINOR finding 6): driven
// from the real roster (AGENT_ROSTER_ROLES), not the hardcoded
// EXPECTED_SANDBOX_BY_ROLE key set — the roster-parity test above already
// fails loudly if the two sets ever diverge, so `checked` here is a
// genuine roster count, not a fixture-pinned literal that would silently
// stop growing when a 36th agent lands.
let checked = 0;
for (const role of AGENT_ROSTER_ROLES) {
assert.ok(
Object.prototype.hasOwnProperty.call(EXPECTED_SANDBOX_BY_ROLE, role),
`${role} exists in agents/ but has no EXPECTED_SANDBOX_BY_ROLE entry — see the roster-parity test above`,
);
const content = fs.readFileSync(path.join(AGENTS_DIR, `${role}.md`), 'utf8');
const toml = generateCodexAgentToml(role, content);
const match = toml.match(/^sandbox_mode = "([^"]+)"$/m);
assert.ok(match, `${role} must emit a sandbox_mode line`);
assert.equal(
match[1],
EXPECTED_SANDBOX_BY_ROLE[role],
`${role}: sandbox_mode must not drift as a side effect of the #3897 filename-identity fix`,
);
checked++;
}
assert.equal(
checked,
AGENT_ROSTER_ROLES.length,
'N6: every real role in agents/ must be checked and byte-identical',
);
});
});
// ─── #3897 security review F1/F3/F4/F5 regressions ─────────────────────────
//
// Isolated security review of this rung found a fail-open: `bin/install.js`'s
// Codex emit loop DECIDED sandbox_mode for the source filename stem but
// APPLIED it to the emitted `.toml`'s path, which is keyed on the
// frontmatter `name:` value instead — so a renamed file, or a sibling file
// whose `name:` collides with a held role, could land a held role's own
// artifact at `workspace-write`. F1(a)/F1(b) below assert on the EMITTED
// ARTIFACT (the written `.toml`'s `sandbox_mode`), never on
// `deriveCodexSandboxMode`'s return value directly — the whole defect is
// that the derivation and the emitted artifact could disagree.
describe('#3897 security review: F1 filename/name identity confusion, F3 confusables, F4/F5 totality', () => {
const AGENTS_DIR = path.join(__dirname, '..', 'agents');
const {
installCodexConfig,
deriveCodexSandboxMode: deriveCodexSandboxModeLocal,
} = require('../bin/install.js');
const {
normalizeSandboxIdentity,
isSandboxHeld,
extractToolsValue: extractToolsValueLocal,
} = require('../gsd-core/bin/lib/codex-agent-toml.cjs');
function sandboxModeOfToml(toml) {
const match = toml.match(/^sandbox_mode = "([^"]+)"$/m);
return match ? match[1] : null;
}
test('F1(a) rename case: a source file whose FILENAME differs from a held role, but whose frontmatter name: IS the held role, emits read-only', () => {
const src = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-f1a-src-'));
const dest = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-f1a-dest-'));
try {
const original = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-doc-writer.md'), 'utf8');
assert.ok(/^name:\s*gsd-doc-writer\s*$/m.test(original), 'sanity: fixture source declares name: gsd-doc-writer');
// Renamed FILE, unchanged frontmatter name: — the fileStem no longer
// matches the held role, but the emitted TOML is still named after
// `gsd-doc-writer` (the frontmatter name:).
fs.writeFileSync(path.join(src, 'gsd-doc-writer-v2.md'), original);
installCodexConfig(dest, src);
const emittedPath = path.join(dest, 'agents', 'gsd-doc-writer.toml');
assert.ok(fs.existsSync(emittedPath), `expected an emitted .toml at ${emittedPath}`);
const toml = fs.readFileSync(emittedPath, 'utf8');
assert.equal(
sandboxModeOfToml(toml),
'read-only',
'F1(a): a held role\'s own emitted .toml must stay read-only even when reached via a renamed source file whose filename stem is unheld',
);
} finally {
cleanup(src);
cleanup(dest);
}
});
test('F1(b) sibling-clobber case: a second, unheld source file whose frontmatter name: IS a held role must not widen the held role\'s emitted .toml', () => {
const src = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-f1b-src-'));
const dest = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-f1b-dest-'));
try {
const heldOriginal = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-doc-writer.md'), 'utf8');
fs.writeFileSync(path.join(src, 'gsd-doc-writer.md'), heldOriginal);
// A sibling file — different filename stem, no hold entry for IT — but
// its frontmatter `name:` collides with the held role. Named to sort
// AFTER `gsd-doc-writer.md` (readdirSync/emit-loop order is
// alphabetical) so this sibling's write is the LAST one to the shared
// `gsd-doc-writer.toml` output path — the exact ordering the pre-fix
// defect needed to actually clobber the held role's own artifact
// (a sibling sorting BEFORE it gets silently overwritten again by the
// legitimate file's own correct read-only write, masking the bug).
const sibling = [
'---',
'name: gsd-doc-writer',
'description: sibling file colliding on frontmatter name',
'tools: Read, Write, Edit',
'---',
'',
'<role>sibling</role>',
].join('\n');
fs.writeFileSync(path.join(src, 'gsd-zzz-attacker-clone.md'), sibling);
installCodexConfig(dest, src);
const emittedPath = path.join(dest, 'agents', 'gsd-doc-writer.toml');
assert.ok(fs.existsSync(emittedPath), `expected an emitted .toml at ${emittedPath}`);
const toml = fs.readFileSync(emittedPath, 'utf8');
assert.equal(
sandboxModeOfToml(toml),
'read-only',
'F1(b): a sibling file whose frontmatter name: collides with a held role must not clobber that role\'s emitted .toml with workspace-write',
);
} finally {
cleanup(src);
cleanup(dest);
}
});
const F3_CONFUSABLE_VECTORS = [
['Turkish dotted I (İ)', 'gsd-doc-wrİter'],
['Turkish dotless i (ı)', 'gsd-doc-wrıter'],
['fullwidth leading g (g)', 'gsd-doc-writer'],
['NFD combining acute on r (writeŕ)', 'gsd-doc-writeŕ'],
['trailing ASCII space', 'gsd-doc-writer '],
['trailing NBSP', 'gsd-doc-writer '],
['trailing dot', 'gsd-doc-writer.'],
['trailing newline', 'gsd-doc-writer\n'],
['trailing carriage return', 'gsd-doc-writer\r'],
['relative-path prefix ./', './gsd-doc-writer'],
['path traversal ../agents/', '../agents/gsd-doc-writer'],
];
for (const [label, vector] of F3_CONFUSABLE_VECTORS) {
test(`F3 confusable/whitespace/path vector — ${label} — derives read-only`, () => {
const mode = deriveCodexSandboxModeLocal(vector, 'Read, Write, Edit');
assert.equal(
mode,
'read-only',
`F3: identity ${JSON.stringify(vector)} (${label}) must derive read-only — either it normalizes onto the real held key, or it is unrecognizable and must fail closed`,
);
});
}
test('F3: isSandboxHeld flags each confusable vector as held or suspicious (never silently neither)', () => {
for (const [label, vector] of F3_CONFUSABLE_VECTORS) {
const { held, suspicious } = isSandboxHeld(vector);
assert.ok(held || suspicious, `${label} (${JSON.stringify(vector)}) must be held or suspicious`);
}
});
test('F5: "All tools except Write, Edit" derives read-only (negation excludes Write/Edit)', () => {
const mode = deriveCodexSandboxModeLocal('gsd-negation-agent', 'All tools except Write, Edit');
assert.equal(mode, 'read-only', 'excluding Write and Edit after "except" must derive read-only');
});
test('F5: "All tools except Agent" derives workspace-write (Write/Edit are not excluded)', () => {
const mode = deriveCodexSandboxModeLocal('gsd-negation-agent', 'All tools except Agent');
assert.equal(mode, 'workspace-write', 'excluding only Agent leaves Write/Edit granted, so this must still derive workspace-write');
});
test('totality: deriveCodexSandboxMode never throws for undefined/null/[]/[undefined] identities', () => {
for (const identity of [undefined, null, [], [undefined]]) {
assert.doesNotThrow(
() => deriveCodexSandboxModeLocal(identity, 'Read, Write, Edit'),
`deriveCodexSandboxMode must not throw for identity ${JSON.stringify(identity)}`,
);
const result = deriveCodexSandboxModeLocal(identity, 'Read, Write, Edit');
assert.equal(typeof result, 'string', `deriveCodexSandboxMode must return a string for identity ${JSON.stringify(identity)}`);
}
});
// #3897 rung 4 (isolated correctness review, MINOR finding 4): two exotic
// identity shapes more adversarial than the undefined/null/[]/[undefined]
// set above — an object whose OWN toString throws, and a null-prototype
// object (no inherited Object.prototype methods at all, so even a
// defensive `.toString`/`.hasOwnProperty` call site would blow up). Both
// must derive a string, never throw — "TOTAL for any input" per this
// function's own docstring is not just for well-behaved falsy/array shapes.
test('totality: deriveCodexSandboxMode never throws for an identity with a throwing toString', () => {
const hostile = { toString() { throw new Error('id-boom'); } };
assert.doesNotThrow(
() => deriveCodexSandboxModeLocal(hostile, 'Read'),
'deriveCodexSandboxMode must not throw for an identity whose toString throws',
);
assert.equal(typeof deriveCodexSandboxModeLocal(hostile, 'Read'), 'string');
});
test('totality: deriveCodexSandboxMode never throws for a null-prototype identity object', () => {
const nullProto = Object.create(null);
assert.doesNotThrow(
() => deriveCodexSandboxModeLocal(nullProto, 'Read'),
'deriveCodexSandboxMode must not throw for a null-prototype identity object',
);
assert.equal(typeof deriveCodexSandboxModeLocal(nullProto, 'Read'), 'string');
});
test('totality: normalizeSandboxIdentity never throws for undefined/null/non-string input', () => {
for (const raw of [undefined, null, 42, {}, []]) {
assert.doesNotThrow(() => normalizeSandboxIdentity(raw), `must not throw for ${JSON.stringify(raw)}`);
assert.equal(normalizeSandboxIdentity(raw), null, `non-string input ${JSON.stringify(raw)} must normalize to null`);
}
});
test('F4: extractToolsValue returns undefined (never throws) for undefined/null/Buffer input', () => {
for (const value of [undefined, null, Buffer.from('tools: Write')]) {
assert.doesNotThrow(() => extractToolsValueLocal(value), `extractToolsValue must not throw for ${String(value)}`);
assert.equal(extractToolsValueLocal(value), undefined, `extractToolsValue must return undefined for non-string input ${String(value)}`);
}
});
test('F4: extractToolsValue still returns the parsed value for real string content — inline form (no regression)', () => {
const content = ['---', 'tools: Read, Write', '---', ''].join('\n');
assert.equal(extractToolsValueLocal(content), 'Read, Write');
});
// ─── #3897 list-form parse fix: YAML block-list `tools:` ─────────────────
//
// `agents/gsd-nyquist-auditor.md` and `agents/gsd-security-auditor.md` are
// the only two roster files using this shape. The pre-fix single-line
// regex `/^tools:\s*(.+)$/m` let `\s*` swallow the newline after a bare
// `tools:` key and matched into the FIRST list item's own line, returning
// just `"- Read"` — a real Write/Edit DECLARATION read as an absence.
test('list-form: a tools: block list declaring Write derives workspace-write (FAILS before the parse fix — pre-fix reader returned "- Read")', () => {
const content = [
'---',
'name: gsd-list-form-writer',
'tools:',
' - Read',
' - Write',
' - Edit',
' - Bash',
'---',
'',
'<role>list-form writer</role>',
].join('\n');
const toolsRaw = extractToolsValueLocal(content);
assert.equal(toolsRaw, 'Read, Write, Edit, Bash', 'list items must be joined the same way the comma-tokenizer downstream expects');
assert.equal(
deriveCodexSandboxModeLocal('zzz-list-form-probe-never-held', toolsRaw),
'workspace-write',
'a tools: block list declaring Write must derive workspace-write, not read-only from a truncated first-item read',
);
});
test('list-form: a tools: block list with NO write tool derives read-only (no over-correction)', () => {
const content = [
'---',
'name: gsd-list-form-reader',
'tools:',
' - Read',
' - Bash',
' - Glob',
'---',
'',
'<role>list-form reader</role>',
].join('\n');
const toolsRaw = extractToolsValueLocal(content);
assert.equal(toolsRaw, 'Read, Bash, Glob');
assert.equal(
deriveCodexSandboxModeLocal('zzz-list-form-probe-never-held', toolsRaw),
'read-only',
'a list-form tools: with no Write/Edit item must still derive read-only',
);
});
test('list-form: the list terminates at the next frontmatter key and does not swallow its value', () => {
const content = [
'---',
'name: gsd-list-form-terminates',
'tools:',
' - Read',
' - Write',
'color: blue',
'---',
'',
'<role>list-form terminates before a sibling key</role>',
].join('\n');
assert.equal(extractToolsValueLocal(content), 'Read, Write');
// The sibling key's own value must remain independently readable — it
// must never have been consumed as a phantom third list item.
const { frontmatter } = extractFrontmatterAndBody(content);
assert.equal(extractFrontmatterField(frontmatter, 'color'), 'blue');
});
test('list-form: the list terminates at the closing --- and does not run past the frontmatter', () => {
const content = [
'---',
'name: gsd-list-form-eof',
'tools:',
' - Read',
' - Write',
'---',
'- this looks like a list item but is BODY text, not frontmatter',
].join('\n');
assert.equal(extractToolsValueLocal(content), 'Read, Write');
});
test('roster truth: gsd-nyquist-auditor DERIVES workspace-write from its real tool contract AND is HELD, so its emitted .toml stays read-only', () => {
const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-nyquist-auditor.md'), 'utf8');
const toolsRaw = extractToolsValueLocal(content);
assert.ok(
/\bWrite\b/.test(toolsRaw) && /\bEdit\b/.test(toolsRaw),
`sanity: gsd-nyquist-auditor's real tools: must declare both Write and Edit, got ${JSON.stringify(toolsRaw)}`,
);
// Derivation WITHOUT the hold (an identity guaranteed never held/suspicious,
// same probe idiom as the rung-3 describe block's PARITY_PROBE_IDENTITY)
// must show the role genuinely derives workspace-write from its contract —
// this is what proves derive-and-hold is doing real work, not that the
// parser happens to agree with the pin by accident.
assert.equal(
deriveCodexSandboxModeLocal('zzz-nyquist-unheld-probe-never-a-real-role', toolsRaw),
'workspace-write',
'gsd-nyquist-auditor must genuinely derive workspace-write from its tool contract once list-form tools: parses correctly',
);
// The REAL identity IS held, so the actual emitted artifact stays read-only.
assert.ok(
Object.prototype.hasOwnProperty.call(CODEX_SANDBOX_HOLDS, 'gsd-nyquist-auditor'),
'gsd-nyquist-auditor must be an explicit CODEX_SANDBOX_HOLDS entry',
);
const { generateCodexAgentToml: generateCodexAgentTomlLocal } = require('../bin/install.js');
const toml = generateCodexAgentTomlLocal('gsd-nyquist-auditor', content);
assert.ok(
toml.includes('sandbox_mode = "read-only"'),
'gsd-nyquist-auditor\'s emitted .toml must stay read-only (held), even though it now derives workspace-write',
);
});
});
// ─── #3241: shared isAnthropicFlavoredModel / CLAUDE_AGENT_ALIASES surface ─────
// Phase 2/3 need one predicate. 40-design.md's "seam decision" moves
// CLAUDE_AGENT_ALIASES into model-catalog.cjs and defines isAnthropicFlavoredModel
@@ -1091,29 +1862,46 @@ describe('installCodexConfig sandboxTier threading seam', () => {
// codex.sandboxTier === 'codex-agent-sandbox') confirms the real registry has
// valid values for all 15 runtimes.
// ─── CODEX_AGENT_SANDBOX mapping ────────────────────────────────────────────────
// ─── CODEX_AGENT_SANDBOX (deleted map): derivation regression baseline ──────────
describe('CODEX_AGENT_SANDBOX', () => {
test('has all 11 agents mapped', () => {
const agentNames = Object.keys(CODEX_AGENT_SANDBOX);
describe('CODEX_AGENT_SANDBOX (deleted map, derivation regression baseline)', () => {
// bin/install.js's CODEX_AGENT_SANDBOX map is gone (ADR-3473 §8.3, #3897
// rung 3) — deriveCodexSandboxMode is the sole owner of sandbox_mode now.
// These tests assert the SAME underlying property the deleted map's own
// suite used to assert (which 11 roles get which sandbox_mode), but against
// the real derivation and the real agents/*.md content, sourced from the
// PRE_3897_CODEX_AGENT_SANDBOX baseline literal above rather than the map.
const AGENTS_DIR = path.join(__dirname, '..', 'agents');
function realDerivedSandboxMode(role) {
const content = fs.readFileSync(path.join(AGENTS_DIR, `${role}.md`), 'utf8');
const { frontmatter } = extractFrontmatterAndBody(content);
const toolsRaw = extractFrontmatterField(frontmatter || '', 'tools') || '';
return deriveCodexSandboxMode(role, toolsRaw);
}
test('has all 11 baseline agents', () => {
const agentNames = Object.keys(PRE_3897_CODEX_AGENT_SANDBOX);
assert.strictEqual(agentNames.length, 11, 'has 11 agents');
});
test('workspace-write agents have write tools', () => {
test('workspace-write agents still derive workspace-write', () => {
const writeAgents = [
'gsd-executor', 'gsd-planner', 'gsd-phase-researcher',
'gsd-project-researcher', 'gsd-research-synthesizer', 'gsd-verifier',
'gsd-codebase-mapper', 'gsd-roadmapper', 'gsd-debugger',
];
for (const name of writeAgents) {
assert.strictEqual(CODEX_AGENT_SANDBOX[name], 'workspace-write', `${name} is workspace-write`);
assert.strictEqual(PRE_3897_CODEX_AGENT_SANDBOX[name], 'workspace-write', `${name} baseline is workspace-write`);
assert.strictEqual(realDerivedSandboxMode(name), 'workspace-write', `${name} still derives workspace-write`);
}
});
test('read-only agents have no write tools', () => {
test('read-only agents still derive read-only', () => {
const readOnlyAgents = ['gsd-plan-checker', 'gsd-integration-checker'];
for (const name of readOnlyAgents) {
assert.strictEqual(CODEX_AGENT_SANDBOX[name], 'read-only', `${name} is read-only`);
assert.strictEqual(PRE_3897_CODEX_AGENT_SANDBOX[name], 'read-only', `${name} baseline is read-only`);
assert.strictEqual(realDerivedSandboxMode(name), 'read-only', `${name} still derives read-only`);
}
});
});