simt-dev 0.7.0 → 0.7.1

package/docs/decisions/ADR-122-the-shims-move-into-the-state-directory-and-the-legacy-directory-removes-itself.md

@@ -0,0 +1,94 @@
+---
+simt-affects: ["src/hooks/shim.mjs", "src/commands/hooks.mjs", "src/journal.mjs", "src/agenthooks/shim.mjs", "test/hooks.test.mjs", "test/agenthooks.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-122 — the shims move into the state directory, and the legacy directory removes itself
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+The git shims live in a top-level `.simt-hooks/` directory, and `core.hooksPath` points
+git at it. Every other piece of per-repo state — the journal, the ledger, the evidence,
+the index — lives under the state directory `.simt/`, which the repository ignores as a
+single line. The top-level split has no technical reason: `core.hooksPath` accepts any
+path, and nothing about the shims requires a location of its own. It does have a cost —
+two roots for what is one body of state, and an ignore line that exists only for the
+shims.
+
+The move has one genuine collision. The journal's stated boundary is that nothing under
+the state directory is journaled: the journal recording itself is recursion, and the
+ledger, index and candidates are evidence and caches whose byte-shape must not be
+rolled back. Review 0003 Q22 ruled the opposite for the shims: `undo` restores
+`core.hooksPath` and the shims together, because a routing restored without its shims is
+a hook that no longer runs. Shims that land under the state directory unjournaled would
+recreate Q22 exactly — the undo restores the routing and the shims stay. The move is
+therefore not a rename; it is a rename plus a named exception to a recorded boundary.
+
+Repositories installed before the move carry the legacy directory. The move must be
+self-healing in those repositories, and the cleanup must obey the rule that already
+governs the hooks directory: a file this tool cannot recognise as its own is never
+deleted on its way.
+
+## Ruling
+
+### 1. The shims live in the state directory, and everything derives from one constant
+
+`HOOKS_DIR` is `.simt/hooks`. The shim file names (`fileFor`), the agent-hook shim
+(`.simt/hooks/agent-hook`), the `core.hooksPath` value a write installs, the hooks
+status, and the agent-hooks `rm` policy all derive from that one constant, so the
+location has exactly one home. The preceding location is `HOOKS_DIR_LEGACY`
+(`.simt-hooks`), named because it is read during cleanup and cited in the plan.
+
+### 2. The legacy directory removes itself on install, judged in the plan
+
+On `hooks install` (and `doctor --fix`, which shares the plan), a present legacy
+directory is scanned and judged removable in the plan: every entry in it must be a
+regular file carrying a simt-dev marker — the shim marker or the chain marker. Removable
+means the plan announces the removal and the apply removes each file journaled and then
+takes the directory down, so `undo` re-creates the files and their directory. A single
+entry the tool cannot recognise as its own — a foreign file, or anything that is not a
+regular file — leaves the directory in place, unannounced and untouched. The judgment
+lives in the plan and the deletion in the apply, so preview and apply agree by
+construction, the way every other write in this command does.
+
+### 3. The shim directory is the one named exception to the unjournaled state directory
+
+`journaledWriteFile` and `journaledRemoveFile` record writes under the state directory
+only when the path is the shim directory. The exception is named, not broadened: the
+recursion and evidence arguments for the rest of the directory are untouched, and the
+module header states the exception alongside the rule. Without it, `undo` after an
+install restores `core.hooksPath` to unset and leaves the shims behind — the Q22
+defect, relocated.
+
+## Consequences
+
+- `src/hooks/shim.mjs` exports both constants; `src/commands/hooks.mjs` gains
+  `legacyHooksScan` (the plan-side judgment) and the apply-side removal; `doctor --fix`
+  inherits both through the shared plan.
+- `src/journal.mjs` imports the shim location from `src/hooks/shim.mjs` — the
+  dependency direction is the journal learning one named path, not the location module
+  learning about the journal.
+- The repository's ignore file drops the `.simt-hooks/` line: the state directory line
+  already covers the shims.
+- A repository installed before the move self-heals on its next `hooks install --yes`:
+  the routing re-points, the new shims land, and the legacy directory is gone — journaled,
+  so an `undo` brings it back.
+- `src/toolwords.mjs` keeps `simt-hooks` as a tool word: the legacy name is still a
+  reference to the tool in remedies and history, and the estate pattern that exempts it
+  is unchanged.
+- The agent-hook shim is re-rendered at its new location by the agent-hooks installer,
+  which reads the same constant.
+
+## Rejected
+
+- **Leaving the shims at the top level.** The split buys nothing and costs an ignore
+  line, a second state root, and a location that the state-directory story does not
+  explain.
+- **Removing the legacy directory without the marker check.** A file a person put there
+  is not the tool's to delete, and the hooks directory already carries exactly this rule
+  for its own files; the cleanup is the same principle applied to the directory.
+- **Journaled everything under the state directory.** The recursion and evidence
+  arguments are load-bearing for the ledger and the index; the exception must be the one
+  directory git's routing points at, and no wider.

package/docs/decisions/ADR-123-a-surplus-positional-is-not-refused-because-arity-is-not-in-the-source.md

@@ -0,0 +1,57 @@
+---
+simt-affects: ["src/commands/index.mjs", "src/commands/spec.mjs", "test/argv-repeat.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-123 — a surplus positional is not refused, because a command's arity is not in its source
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+Review 0003 Q62 asked dispatch to validate a command's positionals the way it validates
+its flags, and the cheapest place to read the maximum looked like the module that
+receives `args`: a command that reads `args[0]` takes one, a command that reads nothing
+takes none, and a command that joins or spreads `args` has no maximum at all.
+
+Measured against the tree, that rule is wrong for five of the 76 rows. `init`, `tokens`,
+`explain`, `graph lint` and `bench report` all accept a positional that their own module
+does not index — it is forwarded to a helper in another module, or deliberately ignored.
+Enforcing the derived maximum failed 27 tests, 11 of them on `init` alone (`init` a path
+is the command's most ordinary call). The source tells you where an argument is *read*;
+it does not tell you what the command *accepts*, and for the five commands whose reading
+happens elsewhere the two answers differ.
+
+## Ruling
+
+### 1. Dispatch does not enforce a maximum number of positionals
+
+Dispatch enforces what a spec row can state truthfully: the flags a command reads, the values a closed set accepts, and that a single-valued flag is given once. It does not enforce a positional maximum, and a surplus positional is accepted exactly as it was before the rule was attempted.
+
+### 2. A command that refuses a surplus positional says so itself, in its own words
+
+
+
+### 3. The withdrawn arity is recorded here rather than carried as a spec field
+
+
+
+## Consequences
+
+- Q62's surplus-positional clause is withdrawn. The arity it would have needed (29 rows
+  with a maximum, 47 unbounded) is not shipped, and no row carries an `args` field.
+- `test/argv-repeat.test.mjs` keeps the refusal of a repeated flag and the closed set;
+  the surplus-positional test is gone with the rule that would have made it pass.
+- The source-reading heuristic is recorded here rather than kept in a comment, because
+  the next agent to read Q62 will propose it again, and it will fail the same 27 tests.
+
+## Rejected
+
+- **Reading arity from the module, as written.** A command's accepted positionals are a
+  contract, and the source is an implementation of it; `init` proves they diverge. A
+  check that refuses `init <path>` is worse than the silence it replaces.
+- **Declaring arity by hand for all 76 rows.** A number nobody derives and no caller
+  checks drifts silently, and a wrong maximum refuses a real call — the same failure,
+  arriving a release later and without a test to find it.
+- **Making every surplus positional an error.** The forwarding commands would need a
+  per-command exception list, which is the manual declaration above with extra steps.

package/docs/decisions/ADR-124-the-manifest-has-a-schema-in-the-tool-and-its-unknown-keys-stay-the-repositorys.md

@@ -0,0 +1,64 @@
+---
+simt-affects: ["src/manifest/schema.mjs", "src/resolve/fingerprint.mjs", "test/manifest-schema.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-124 — the manifest has a schema in the tool, and its unknown keys stay the repository's
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+`simt.json` is read in 29 places and 41 keys are read ad hoc across the tree. There was
+no list of the keys, so `"mode": "kernal"` was accepted by every reader and reached the
+projection as a mode nothing had heard of, and one reader (`fingerprint`) returned
+`{error}` as the manifest, so a file that did not parse looked like a declaration of a
+key called `error`.
+
+Writing that list is where this repository's characteristic mistake is easiest to make:
+the first draft was written from memory and called `limits.fileLines` a positive integer
+and `surfaces` an object. In the only manifest the tool has to hand, the first is an
+object of two tiers and the second is a list.
+
+## Ruling
+
+### 1. One table declares the manifest keys, their owner and their check
+
+One table in `src/manifest/schema.mjs` declares every key with its owner (`tool` or
+`repo`), the version it arrived in, and a check that returns a sentence naming what is
+wrong. One loader, `loadManifest(root)`, returns the manifest, whether a file exists,
+the version, and the problems. The table is held to this repository's own `simt.json` by
+a test, because a schema written from memory fails that test in the same run that proves
+the loader works.
+
+### 2. An unparseable file is no manifest, and an absent version field is version 1
+
+A caller that receives a half-read object cannot tell it from a declaration, so a file
+that does not parse yields no manifest and one problem naming the parse error. `version`
+arrived after every manifest now on disk, so absent means 1 rather than a problem.
+
+### 3. An unknown key is not a problem, because the file invites the repository's own
+
+The manifest comment tells a repository that a value it adds survives a re-init. A
+validator that refused an unknown key would make the tool the owner of a file it calls
+the repository's, so only a known key with an impossible value is reported.
+
+## Consequences
+
+- `fingerprint` reads through the loader, so a broken manifest no longer arrives as an
+  object with an `error` key; a dependent read sees no declaration.
+- The 29 direct `JSON.parse` call sites remain. Migrating them is the rest of Q69 and
+  changes no behaviour this table already answers for a single call.
+- `GENERATED_KEYS` is not yet derived from the table; the table distinguishes `tool`
+  from `repo` keys, so the derivation is possible and is not taken here.
+
+## Rejected
+
+- **A JSON Schema file and a validator dependency.** `package.json` declares an empty
+  dependency set (ADR-012), and a schema in a second language would be a second place
+  the keys are stated.
+- **Refusing unknown keys.** The file comment invites a repository to keep its own
+  keys, and refusing them breaks every repository that already does.
+- **Throwing on a bad value.** A manifest is read on the path of every command; a throw
+  turns a typo into a crash with no remedy, where a named problem can be printed beside
+  the answer.

package/docs/decisions/ADR-125-a-shared-context-belongs-to-a-read-and-a-writer-reads-directly.md

@@ -0,0 +1,65 @@
+---
+simt-affects: ["src/context.mjs", "src/commands/hooks.mjs", "test/hooks-context.test.mjs"]
+simt-supersedes: []
+---
+
+# ADR-125 — a shared context belongs to a read, and a writer reads directly
+
+Status: **accepted** · 2026-10-31
+
+## Context
+
+`repoContext` holds one pending promise per question for the length of a command. It
+was threaded through the reads — `check`, the four skills reads, `diagnose`, the rules
+catalogue — and Q67's last clause was to finish the job, which raised the question the
+row did not answer: should a command that *writes* hold a context too?
+
+The two cases are not the same. A reader asks several questions about an unchanging
+tree and pays once. A writer changes the tree between its questions: `init` writes a
+manifest and then renders against it, `upgrade` replaces files and then reports drift,
+`sync` rewrites the region and then computes the lock. A context that survived those
+writes would answer the second question with the first answer, and the command would
+report a repository it had already changed.
+
+## Ruling
+
+### 1. A read command may hold one context for its whole run
+
+A command that only reads creates one `repoContext` at its entry and passes it to
+every reader beneath it. Two questions with the same answer cost one computation, and
+the cache reports its own hits so a context that is wired but never used cannot pass
+for a fast machine.
+
+### 2. A writer reads its repository directly
+
+A writer calls the readers as it always has. It is not an optimisation left undone: a
+shared context would make a stale answer the reward for a correct write, and the
+failure would surface as a drifted manifest in a repository that had just been fixed.
+
+### 3. The hook path keeps its dynamic import
+
+`planHooksInstall` resolves the node runner from a fingerprint, and it imports the
+fingerprint module dynamically so that loading the hooks command does not load it.
+Static-importing a context into `src/commands/hooks.mjs` costs about 3 ms of module
+graph on the shim path, which Q64 measured and removed once. A caller that holds a
+context passes it and shares the walk; a caller that does not keeps the light path.
+
+## Consequences
+
+- Q67 closes with the reads threaded and the writers explained rather than converted.
+- The 3 ms module cost is paid only when a command actually uses a context; `hooks
+  run` keeps the dynamic path.
+- A future writer that wants a context has this record to argue against, instead of
+  discovering the staleness as a bug report.
+
+## Rejected
+
+- **Giving every writer a context and invalidating entries after each write.** The
+  invalidation is the whole bug surface: forget one entry and the failure is a stale
+  answer that looks like a correct one, in the command whose job is to make the tree
+  correct.
+- **A process-lifetime context.** `bench` writes manifests mid-run; a process-wide
+  memo would answer a benchmark for a repository it had just changed.
+- **Making the context required on every reader signature.** It would put the cache in
+  the contract of functions that do not need one, and a caller with no context would
+  have to invent an empty one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simt-dev",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "An intelligence amplifier for AI coding agents: rules and dual gates adopted by one command, plus local retrieval, task briefs, benches and repo memory — deterministic by default, with local-model adapters that propose and never select.",
   "license": "Apache-2.0",
   "author": "Said Elimam",
@@ -44,6 +44,14 @@
   ],
   "scripts": {
     "test": "node --test --test-concurrency=$(node -p 'os.cpus().length') test/*.test.mjs",
-    "lint": "node bin/simt.mjs doctor"
+    "lint": "node bin/simt.mjs graph lint",
+    "verify:shipped": "node --test test/shipped.test.mjs",
+    "build:sea": "node scripts/build-sea.mjs",
+    "verify:wheel": "node scripts/verify-wheel.mjs"
+  },
+  "exports": {
+    ".": "./src/api.mjs",
+    "./package.json": "./package.json",
+    "./src/*": "./src/*"
   }
 }

package/rules/core.md

@@ -24,9 +24,16 @@ commands belongs in this repository, not here.
 
 ## Git
 
+The commit and push procedure - order, message format, worktrees - is the `slice-commit`
+rule; follow it for every commit and push.
+
 - Commit locally, report the SHA. **Push only on explicit approval.** (ADR-001)
 - Before asking for push approval, state whether the push triggers a deployment, a migration
   or any remote mutation.
+- Once approved, you may push directly without the pre-push gate re-running the full suite
+  when you already ran that suite green on the current state and changed nothing since: cite
+  the already-passing run as the pass, and the gate recognizes the evidence and skips the
+  re-run rather than paying for it again. (ADR-120)
 - Never use `--no-verify`, amend, rebase, reset or rewrite history unless explicitly asked.
 - Never commit failing, partial, secret-bearing or unrelated work.
 

package/rules/mdc/slice-commit.mdc

@@ -15,6 +15,35 @@ one is a mechanical procedure with a fixed order, because every step after it de
 on the one before: you cannot review a diff you have not staged, and you cannot claim
 evidence for a test you have not run.
 
+## Commit message
+
+A message is read by the next agent before they are told what to do. It says what the
+commit is, what it answers, and what it changed, so a reader never reconstructs that
+from the diff.
+
+The title is Conventional Commits: imperative, no trailing period, a short scope slug
+that names the subsystem — not a ticket id.
+
+    feat(dispatcher): skip the test gate on a push that already passed
+
+The body is plain sections in this order. Drop any section that has nothing to say; a
+one-line commit needs none of them.
+
+    What: <one sentence — what this commit is>
+    Why: <what it answers — the task, defect, or decision that asked for it>
+    Before: <the state this replaces, briefly>
+    After: <the state it leaves, briefly>
+
+"Before" and "After" are a short state summary, not a diff: enough to see what moved,
+not enough to need the patch. Cite a decision record where one settles the change, and
+never claim a test in the body that was not run on this tree.
+
+The message ends with a trailer on its own line, after the body - attribution to the
+tool, in the form git renders as a co-author. It is part of the message, not a
+section, so it stays even when every section is dropped:
+
+    Co-Authored-By: Simt Dev <noreply@simt.space>
+
 ## Order
 
 1. **Run the focused test the change needs**, through the repository's own runner,
@@ -24,10 +53,8 @@ evidence for a test you have not run.
    alone. Report what you left alone; silence about it reads as "I reverted it".
 3. **Read the staged diff.** Not the working tree — the diff. It is what will be
    committed, and it is the last chance to notice a file that does not belong.
-4. **Write the message.** Conventional Commits, imperative subject, no trailing period:
-   `fix(gates): declare only gates a repo can run, and report the ones it cannot`.
-   The subject says what changed; the body says why, and what was deliberately not
-   changed.
+4. **Write the message in the format above.** The title names what changed; the body
+   says why, and what was deliberately not changed.
 5. **Commit.** `git commit`, non-interactive. Report the SHA.
 6. **Stop.**
 
@@ -44,6 +71,32 @@ Never use `--no-verify`. A hook that fails is telling you something about the ch
 skipping it turns a gate into a suggestion and the next person has no way to know it
 was skipped.
 
+Once the push is approved, you may push directly without the pre-push gate re-running
+the full suite when you already ran that suite green on the current state and changed
+nothing since: the gate records every run against the tree it ran on, recognises that
+evidence, and skips the re-run, reporting the skip and the record that earned it.
+Cite the already-passing run as the pass — do not claim a re-run that did not happen.
+(ADR-120)
+
+## Worktrees
+
+A worktree is the unit of isolation for concurrent work. The rules that keep it honest:
+
+- **One agent, one worktree, one slice.** Never direct two agents at the same files
+  concurrently; give each its own worktree and a slice whose files do not overlap.
+- **Start from the record, not from memory.** `simt slice start <id>` creates the
+  worktree for the tracker row and returns its path; work in that path, not the main
+  checkout.
+- **Finish where you started.** `simt slice finish <id>` runs the declared gates and
+  commits from the worktree; `simt plan done <id> <sha>` records the SHA in the main
+  checkout's tracker. A slice is not done when its worktree is green — it is done
+  when the tracker row is complete and the SHA is recorded.
+- **Leave the worktree when the slice is done.** A finished worktree that still holds
+  a dirty tree is a claim about work that is not committed; remove it, and report what
+  you left behind if there was any.
+- **Never rewrite history across worktrees.** A rebase, reset or amend in one worktree
+  changes the base every other worktree branched from; coordinate it, or do not do it.
+
 ## What never belongs in a commit
 
 - Failing, partial, or unrun work. A commit is a claim; a partial one is a false one.

package/src/agenthooks/prompt.mjs

@@ -60,7 +60,7 @@ export async function promptOptIn(root) {
  * a minute while a repository is walked — is how the hook gets uninstalled, and the
  * packet is not worth a prompt that cannot be typed.
  */
-export async function deliverPrompt(row, payload) {
+export async function deliverPrompt(row, payload, { root: flagRoot } = {}) {
   const task = promptText(row, payload);
   if (task === null) return { skipped: 'the payload carries no prompt this harness documents' };
 
@@ -68,7 +68,10 @@ export async function deliverPrompt(row, payload) {
   // and resolved to the repository's top level the same way: the manifest, like the
   // lease file, is a repository-relative fact, and a prompt submitted from a
   // subdirectory must find it (review 0003 Q16).
-  const root = repoRoot(factsFrom(row, payload).root);
+  // `--root` outranks the payload here as it does on the decision path: a packaged hook
+  // runs from the plugin directory, so the payload's cwd would name the wrong repository
+  // and find no manifest, which delivered nothing and looked like an opt-out.
+  const root = repoRoot(factsFrom(row, payload, { root: flagRoot }).root);
   const optIn = await promptOptIn(root);
   if (!optIn.optedIn) return { skipped: optIn.why };
 

package/src/agenthooks/shim.mjs

@@ -4,7 +4,7 @@
 // harness's PATH. A harness config naming the bare `simt` binary therefore
 // runs nothing on Claude (a non-2 exit is silent: no enforcement) and blocks
 // every tool call on Cursor (its hook fails closed). The fix is a shim beside
-// the git shims, resolved the same way: `.simt-hooks/agent-hook` locates the
+// the git shims, resolved the same way: `.simt/hooks/agent-hook` locates the
 // dispatcher with the shared `renderLocator` block and hands over, so every
 // harness config names the shim and never the bare binary (review 0003 Q21).
 //

package/src/api.mjs

@@ -0,0 +1,29 @@
+// The library surface: the read commands as data (review 0003 Q63).
+//
+// Every function here is the one the CLI and the MCP tools already call. Nothing in
+// this file renders: a caller that wants text, JSON or an MCP result renders these
+// results itself, which is the whole point - a UI, a harness and a terminal asking the
+// same question must not get three answers, and they cannot disagree if they are
+// reading one function's return value.
+//
+// This is the read half only. The commands that write (`init`, `sync`, `hooks
+// install`, `skills install`, `upgrade`) still print their plans from the command
+// module, because their output is a diff a person reviews before it is applied
+// (ADR-001). They migrate in the next slice, when `run(ctx, input)` exists to carry
+// a plan back to a caller that can show it.
+//
+// The exports map in package.json points `import 'simt-dev'` here, and keeps
+// `./src/*` because the plugin runtime and the harness shims import deep paths.
+// Removing that subpath would break them to make the surface look tidier.
+
+export { checkRepo, checkTargets, checkTarget, frozenFindings } from './commands/sync.mjs';
+export { diagnose, serialisedFindings } from './commands/doctor.mjs';
+export { rulesCatalogue, rulesWhyFacts } from './commands/rules.mjs';
+export { skillsBriefFacts, skillsFindFacts, skillsShowFacts, skillsWhyFacts } from './commands/skills.mjs';
+export { assembleBrief } from './brief/assemble.mjs';
+export { loadRegistry } from './graph/load.mjs';
+export { discover } from './compare/discover.mjs';
+export { buildRows, resolveConcurrency, summarise } from './compare/row.mjs';
+export { planNext } from './plan/index.mjs';
+export { buildPrBody } from './prbody.mjs';
+export { federationAccess, readFederation } from './federation/config.mjs';

package/src/argv.mjs

@@ -26,6 +26,11 @@ import { EXIT } from './output/index.mjs';
 // mean something, which it could not while three accepted flags had no description.
 
 export const BOOL_FLAGS = new Set([
+  // bench ablate: compare across harness, model and experiment groups. The command
+  // read `flags.crossGroup` while the parser accepted no such flag, so the override
+  // existed only in the error message that told the reader to pass it (review 0003
+  // Q62, found by the spec-vs-parser drift test).
+  'cross-group',
   'json',
   'all',
   'dry-run',
@@ -89,6 +94,10 @@ export const BOOL_FLAGS = new Set([
   // bench.json marked unmeasured, and a lint that failed it on arrival would make
   // every new pack red before its author wrote the rule (plan 0003 R45).
   'require-measured',
+  // bench mine: restore the old "reflect exactly this history" semantics by
+  // deleting task files the current history does not reproduce. Off by default
+  // because mining is append-only (review 0003 Q48).
+  'replace',
   // distill: propose the summary from the configured local chat model instead of
   // the deterministic outline. Off by default: no model in the default path (P1),
   // and a model that is not asked for should not be opened against (ADR-090).
@@ -166,6 +175,9 @@ export const VALUE_FLAGS = new Set([
   // lease: how long the claim lasts, in seconds. A value, because "a lease is short"
   // is not a number any reader can act on, and an expiry nobody chose is an expiry
   // nobody can plan around (plan 0003 R54, ADR-101).
+  // lessons capture: how long a captured candidate stays eligible. A value, because a
+  // default would be a deadline nobody chose (review 0003 Q62, found by the drift test).
+  'expires',
   'ttl',
   // map: outline (paths), names (exported symbols) or signatures (the line).
   // A boolean would not say which of the three the caller wanted.
@@ -281,9 +293,23 @@ export function parse(argv) {
         flags.reps = n;
       } else {
         const key = camel(raw);
-        flags[key] = REPEATABLE_FLAGS.has(raw)
-          ? [...(Array.isArray(flags[key]) ? flags[key] : []), value]
-          : value;
+        if (REPEATABLE_FLAGS.has(raw)) {
+          flags[key] = [...(Array.isArray(flags[key]) ? flags[key] : []), value];
+        } else if (flags[key] !== undefined) {
+          // `--root a --root b` kept `b`, so half of what the caller asked for vanished
+          // with no error and no way to tell which half. Only a flag declared repeatable
+          // accumulates (review 0003 Q62); a second value for any other is a usage error.
+          return {
+            ok: false,
+            error: usage(
+              `--${raw} was given twice; it takes one value (repeatable: ${[...REPEATABLE_FLAGS]
+                .map((name) => `--${name}`)
+                .join(', ')})`,
+            ),
+          };
+        } else {
+          flags[key] = value;
+        }
       }
       continue;
     }

package/src/bench/adapters.json

@@ -10,6 +10,8 @@
       "args": ["-p", "{prompt}", "--output-format", "json", "--max-turns", "{turns}"],
       "modelArgs": ["--model", "{model}"],
       "format": "json",
+      "isolation": "env",
+      "env": ["ANTHROPIC_API_KEY"],
       "usageSource": "usage.*, total_cost_usd, num_turns",
       "fields": {
         "input": ["usage.input_tokens", "usage.input"],
@@ -30,6 +32,8 @@
       "args": ["exec", "--json", "{prompt}"],
       "modelArgs": ["--model", "{model}"],
       "format": "jsonl",
+      "isolation": "env",
+      "env": ["OPENAI_API_KEY"],
       "usageSource": "token events in JSONL",
       "fields": {
         "input": ["usage.input_tokens", "input_tokens", "usage.input"],
@@ -50,6 +54,8 @@
       "args": ["-p", "{prompt}", "--output-format", "json"],
       "modelArgs": ["--model", "{model}"],
       "format": "json",
+      "isolation": "env",
+      "env": ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
       "usageSource": "stats block",
       "fields": {
         "input": ["stats.inputTokens", "stats.tokens.prompt", "stats.prompt_tokens", "usage.input_tokens"],
@@ -70,6 +76,8 @@
       "args": ["run", "--format", "json", "{prompt}"],
       "modelArgs": ["--model", "{model}"],
       "format": "jsonl",
+      "isolation": "env",
+      "env": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
       "usageSource": "session export",
       "fields": {
         "input": ["tokens.input", "usage.input_tokens", "part.tokens.input"],
@@ -90,6 +98,8 @@
       "args": ["-p", "{prompt}", "--output-format", "json"],
       "modelArgs": ["--model", "{model}"],
       "format": "json",
+      "isolation": "env",
+      "env": ["CURSOR_API_KEY"],
       "usageSource": "result JSON",
       "fields": {
         "input": ["usage.input_tokens", "usage.input", "stats.inputTokens"],
@@ -110,6 +120,8 @@
       "args": ["--message", "{prompt}", "--yes-always", "--analytics-log", "{analyticsLog}"],
       "modelArgs": ["--model", "{model}"],
       "format": "analytics-log",
+      "isolation": "env",
+      "env": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
       "usageSource": "--analytics-log file",
       "fields": {
         "input": ["prompt_tokens", "properties.prompt_tokens", "usage.input_tokens"],
@@ -130,6 +142,8 @@
       "args": [],
       "modelArgs": [],
       "format": "builtin",
+      "isolation": "none",
+      "env": [],
       "usageSource": "vault gold.patch",
       "fields": {}
     },
@@ -142,6 +156,8 @@
       "args": [],
       "modelArgs": [],
       "format": "builtin",
+      "isolation": "none",
+      "env": [],
       "usageSource": "none",
       "fields": {}
     }