create-agent-rig 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -14,6 +14,146 @@ second recorded departure; its own entry states the direction and the reason,
 and this paragraph deliberately does not restate them — a numbering rule with
 two copies of its exceptions is the shape 0.8.0 exists to remove.
 
+## 0.9.1
+
+**A patch, numbered by the owner.** Every entry corrects existing behaviour;
+two of them (RP-182, RP-59) do it by recording or reporting something new.
+Nothing is added to what `create`, `init` or `upgrade` install beyond the
+corrected files, the contract version stays `1.0`, and the application
+skeletons remain deprecated and scheduled for removal in 0.10.0 exactly as
+0.9.0 announced.
+
+### Fixed
+
+- **`init` records the files it kept.** When `init` finds a payload path
+  already present and leaves it alone, the manifest now records that file's
+  hash under `kept`, so a later `upgrade` can say whether the file is
+  unchanged or edited since `init` found it instead of reporting it with no
+  history (RP-182). A manifest with nothing kept is written exactly as
+  before.
+- **`memory load` passes Memory a deadline of its own.** A `load` that names
+  no `--timeout-ms` gets `--timeout-ms 45000` appended, below the rig's 60 s
+  kill. A well-formed `--timeout-ms <value>` pair raises that kill to the
+  value plus 15 s when that is above 60 s, capped at Node's timer limit of
+  2 147 483 647 ms; any other spelling passes through unchanged. `doctor`'s
+  arguments are untouched. The README example adds `--cwd .`, which the Memory
+  owner names as part of Memory's own contract (RP-183).
+- **`reconcile-external-prs.mjs` works on a `gh` that does not serve
+  `authorAssociation`** from `gh pr list`: the association is fetched
+  separately and kept only when it answers for the same pull request, and a
+  failed lookup leaves those pull requests untrusted rather than failing the
+  sweep. A failure now names the one cause the evidence shows, with terminal
+  control sequences and credential shapes removed from the detail (RP-99).
+- **The queue reports a Blocks link the ticket body says was removed but the
+  tracker still carries** — a body line of the form
+  `The Blocks link A -> B is removed` — as a `link-contradicted-by-body`
+  hygiene finding (RP-59).
+- **A Jira triage proposal with a long `change` is filed, not refused by the
+  tracker.** Jira rejects a summary over 255 characters; the summary is now
+  cut to fit and the full text stays in the description (RP-121).
+
+### Generator CI (not a rig-facing change)
+
+Test-fixture cleanup goes through one bounded-retry helper, and an audit holds
+every other recursive removal and every in-repository fixture to a written
+reason. The four child-process time bounds are measured inside the child, and
+the package-manager CLI-start cases carry their own measured budget. The e2e
+installs run in a vitest group of their own, so they no longer compete with
+the template tests on the Windows full-suite runner (RP-158).
+
+## 0.9.0
+
+**The harness ↔ Memory boundary is executable, and the rig is a consumer of
+Memory rather than a host for it.** The CLI gains a `setup --memory-root
+<checkout>` command that records the Memory executable in a machine-scoped
+subsystem manifest after a `--version --json` handshake, and a `memory
+<doctor|load>` command that runs the registered executable through that
+handshake and refuses a foreign contract major with exit 4 before any verb
+runs; the CLI itself answers `--version --json` with its name, version and
+contract version. These are commands of the tool, not files in a project: the
+manifest is machine-scoped and nothing Memory-related is added to what
+`create`, `init` or `upgrade` write into a project. None of this puts
+Memory code inside the rig: the executable is spawned across a process
+boundary and only its handshake is parsed (`docs/command-contract.md`, "The
+version handshake"; `docs/decisions/memory-rig-boundary.md`).
+
+**Deprecated: the application skeletons.** `create <dir> [--target <name>]`
+still scaffolds `aws-serverless` and `node-service` in this release, unchanged, and they are
+**scheduled for removal in 0.10.0**. The product boundary the owner fixed on
+2026-09-13 is a package manager for repository-scoped Claude Code and Codex
+configuration — `init` into an existing repository, `upgrade`, `doctor`, the
+Memory handshake — and application scaffolding is outside it. Take `init` for
+a new project's rig; a skeleton generated today is yours and stays yours, but
+`upgrade` will not carry skeleton files forward once they are gone.
+
+**Numbered a minor by the rule at the top of this file**: two new commands and
+a new payload are additive.
+
+### Added
+
+- **`setup --memory-root <checkout> [--memory-ref <sha>] [--dry-run]`** and the
+  machine subsystem manifest it writes (`~/.config/create-agent-rig/subsystems.json`,
+  `%APPDATA%` on Windows) — RP-147. `upgrade` re-runs the same derivation when a
+  manifest exists, so `installedVersion` follows the executable the root holds.
+- **`memory <doctor|load> [args…]`** through the registered executable, with the
+  handshake first and Memory's answer passed through unchanged; `--version
+--json` on the rig bin — RP-19. Exit codes on that surface: 0 unsupported /
+  absent, 1 integration-failed, 2 invalid invocation, 3 prerequisite unmet, 4
+  foreign contract major.
+- **Role-specific subagent routing** in the payload: one routing table
+  (`templates/agent-os/subagent-routing.json`) pins each reviewer's model and
+  effort for both harnesses; the Claude agent specs carry the pins, the Codex
+  profiles are derived from the same table, and two Claude Code hooks —
+  `guard-subagent-model` (refuses a call-site `model` override on a pinned
+  reviewer) and `warn-subagent-routing` (says so at session start when an
+  effort override is in force) — are wired in `.claude/settings.json`
+  (RP-166, RP-173; `docs/decisions/subagent-routing.md`).
+- **`preflight` fails on an unreadable configured queue** instead of selecting
+  from nothing (RP-56).
+- **Concurrent sessions on one machine** — the ruling on what shared state
+  they may touch, and a bounded rename retry so a Windows gate-round counter
+  is not lost to a transient lock (RP-120; `docs/decisions/concurrent-sessions.md`).
+- **A mechanical release preflight**, `node scripts/release-preflight.mjs`,
+  for the step the owner types by hand (`docs/releasing.md`).
+- **The Rig-side conformance runner** for the Memory boundary,
+  `scripts/memory-conformance.mjs --from <checkout> --json`, and the contract
+  schemas under `contracts/conformance/v1/` (RP-13) — generator repository
+  only, never delivered to a rig; the authoritative cross-repository run lives
+  in the private Memory repository and checks this one out at an exact SHA.
+- **The policy benchmark** (`docs/policy-benchmark.md`, RP-111): adapter-process
+  evidence for both harnesses on an immutable snapshot of the tree. It remains
+  in 0.9.0; whether it stays is a 0.10.0 decision.
+
+### Fixed
+
+- **`edit-input`** — an unreadable `tool_input` is a refusal on every edit
+  surface, never a clean edit (RP-85); a widening `--allow` entry no longer
+  leaves an unattended run with no flag on disk, and the `loop` skill verifies
+  the flag armed instead of trusting that it did (RP-103).
+- **Capability coverage** — the policy capability contract names exactly what
+  the code covers, and the two silent passes it had are closed (RP-36); policy
+  validators read own-and-enumerable record fields (RP-153).
+- **Windows** — the node-service skeleton's static-dir tests use a native file
+  URL (RP-168); the e2e harness spawns package managers and file checks on
+  Windows (RP-169); the one PowerShell case carries its own measured budget
+  (RP-162); the benchmark's guard-spawning cases are classified UNVERIFIABLE
+  on the hosted Windows image rather than reported green on nothing (RP-111),
+  and the Windows governance fixtures are set up under a bound that names the
+  stage that timed out (RP-172).
+- **Repository scans skip sibling worktrees** under `.claude/worktrees/`, so a
+  second checkout is no longer reported as this one's drift (RP-155).
+
+### Generator CI (not a rig-facing change)
+
+The pull-request path runs on GitHub-hosted runners only: in `ci.yml`, `ci`
+and the two template checks on Linux and `windows-smoke` (the CLI's unit
+project) on Windows; in `e2e.yml`, the Linux `e2e` job — the full suite with
+the e2e installs and the benchmark — when the pull request touches the CLI,
+the templates, the e2e harness or that workflow. The full suite on Windows
+runs in `e2e.yml` on master, nightly and by dispatch only, and a
+`runner_mode` switch there selects a self-hosted fallback that no pull
+request can reach (`docs/runners.md`).
+
 ## 0.8.0
 
 **Three stale second copies, spread over three payload files a rig obeys,
@@ -991,7 +1131,18 @@ sometimes earlier (step 6). Everything before that is mechanical:
    `test/template/hash-history.test.ts` › "builds the table from the ledger
    alone — tags are a warning source, never an input".
 
-8. **Owner:** `npm publish`.
+8. **Owner:** `npm publish` — and immediately before it, from the checkout you
+   are about to publish from:
+
+   ```sh
+   node scripts/release-preflight.mjs   # exit 0, or it names what to fix
+   ```
+
+   It checks the manifests, the ledger, the checkout, and the tarball `npm pack`
+   would actually produce. What it looks at is the code, not this list; what it
+   cannot see is stated in its own header. It is a preflight, not a gate —
+   nothing runs it for you, and exit 0 is not a verdict on the release.
+
 9. **Owner:** smoke the published artifact — `npx create-agent-rig@<version>` in
    an empty directory, then `pnpm install && pnpm check` inside it; and
    `upgrade --dry-run` in a rig installed from the previous version.

package/README.md

@@ -65,7 +65,13 @@ it does not. Each conflict names the file, why it was kept, and the path to the
 new version so you can diff it yourself.
 
 How it knows: `create` and `init` write `.claude/.rig-manifest.json` — the rig
-version plus a hash per installed file. **Commit it**; without it in the
+version plus a hash per installed file. A file `init` found already in place and
+left alone is recorded separately, under `kept`, with the hash of the bytes it
+found, and never as the rig's (`packages/cli/test/init.test.ts` › "records what
+it kept, with the sha256 of the bytes actually on disk — never in `files`"). An
+`upgrade` conflict on such a file says it was kept by init and whether it was
+edited since (`packages/cli/test/upgrade.test.ts` › "says "edited since"
+instead, once the disk sha no longer matches what init recorded"). **Commit it**; without it in the
 repository the command is blind on CI and on a colleague's machine. Rigs
 installed before 0.4.0 have no manifest, so the package also carries the hashes
 of every release whose published commit is on record (0.2.0 onward — 0.1.0's
@@ -85,6 +91,44 @@ enough for this one, and a replacement that would stop calling a hook the
 current wiring names — while that hook's file is still in `.claude/hooks/` — is
 handed over instead.
 
+### Registering Memory on this machine
+
+Memory is a separate subsystem with its own version; the rig never imports it
+and never searches for it. `setup` records where it is, once per machine:
+
+```sh
+npx create-agent-rig@latest setup --memory-root ~/claude-config             # the checkout that holds shared-memory/memory.mjs
+npx create-agent-rig@latest setup --memory-root ~/claude-config --dry-run   # handshake only, write nothing
+```
+
+It derives the invocation from that one root, runs Memory's `--version --json`
+first, and refuses a foreign contract major with exit 4 before writing anything.
+What it writes is one machine-scoped manifest —
+`~/.config/create-agent-rig/subsystems.json` (`%APPDATA%\create-agent-rig\` on
+Windows) — carrying the invocation, the required contract major, the pinned
+Memory ref (`--memory-ref`) and the version the handshake observed. `upgrade`
+re-runs the same derivation when the manifest exists; it never creates one. The
+behaviour is pinned in `packages/cli/test/setup.test.ts` and
+`packages/cli/test/subsystems.test.ts`; the seam itself is ADR-RP-002 R6
+(`docs/decisions/memory-rig-boundary.md`).
+
+Both bins answer the same handshake, and the rig consumes Memory only through it
+(RP-19):
+
+```sh
+npx create-agent-rig@latest --version --json          # {"schemaVersion":1,"name":"create-agent-rig","version":"…","contractVersion":"1.0"}
+npx create-agent-rig@latest memory doctor --json      # handshake first, then Memory's doctor, answer passed through unchanged
+npx create-agent-rig@latest memory load --json --cwd .   # same, for load (`--cwd`: Memory's own contract, per its owner — RP-183); arguments pass to Memory verbatim, plus `--timeout-ms 45000` when you name none
+```
+
+`memory` reads the manifest above, runs Memory's `--version --json`, and only
+then the verb: a foreign contract major exits 4 and the verb never runs; no
+manifest (or an executable that has moved) is `unsupported`/`absent`, exit 0;
+an executable that answers but not as the manifest promised — a broken
+`VERSION`, a malformed handshake — is `integration-failed`, exit 1, never
+"absent". Pinned in `packages/cli/test/memory.test.ts` and
+`packages/cli/test/cli-version.test.ts`.
+
 **A file you deleted stays deleted.** The rules invite you to delete the ones
 whose invariant your project does not have, so an upgrade that quietly restored
 them would be undoing your work. With a manifest that is direct — it names the
@@ -94,13 +138,42 @@ it covers was there to be removed. The single case nothing can tell apart is a
 file a **later** release added, which your rig never had — that one is installed,
 and `--dry-run` lists it before anything is written.
 
+### Conformance runner
+
+`contracts/conformance/v1/` holds the JSON schemas of the command contract's
+`--version --json`, `doctor --json` and `load --json` answers, and
+`scripts/memory-conformance.mjs` checks a Memory checkout against them:
+
+```sh
+pnpm build
+node scripts/memory-conformance.mjs --from <claude-config checkout> --json [--out report.json]
+```
+
+It is offline by construction — `--from` is mandatory, nothing is fetched, no
+credential is read — and it never imports Memory code or copies a Memory
+fixture into this repository (`test/template/memory-conformance.test.ts` ›
+"carries no fetch, clone or credential: the checkout is always the caller's"
+and › "the repository carries no Memory fixture"). The contract directory is
+this repository's own, not a rig payload: `create`, `init` and `upgrade` do
+not deliver it (`test/template/conformance-contract.test.ts` › "is not
+delivered to rigs: no template carries a conformance contract"). The report's
+rows, its `rigSha` / `memorySha` / `verifierDigest` fields and the `--out`
+file are pinned by the same test file's › "passes every row against a
+well-formed local fixture root and names both SHAs and the verifier digest"
+and › "derives verifierDigest from the runner, its validator and the contract
+files, in that order, and writes the same report to --out". The authoritative
+cross-repository run lives in the private `claude-config` repository, which
+checks this repository out at an explicit full SHA and runs the command above
+against its own tree; the CI here runs only the offline tests.
+
 ## What you get
 
 **A system of boundaries, each held by tooling.** An agent (or a human using
 one) cannot talk its way past them — each guard is a pre-write scan that stops
 the normal path cold (review and tests back it; the claim is stated exactly,
 never inflated). The hook implementations live once in `.claude/hooks/` and are
-wired by both `.claude/settings.json` and `.codex/hooks.json`:
+wired by both `.claude/settings.json` and `.codex/hooks.json` — except the two
+marked Claude Code, which only `.claude/settings.json` wires:
 
 - **`guard-core-purity`** — refuses any edit that puts I/O, clock, randomness,
   environment access, or a non-allowlisted import into the pure domain core;
@@ -135,7 +208,16 @@ wired by both `.claude/settings.json` and `.codex/hooks.json`:
 - **`inject-rules`** — re-injects the autonomy rules at session start, so they
   survive compaction and resumes: the whole file, minus the regions the file
   itself marks as reference. What is left out is a decision written in
-  `autonomy.md` on the line above it, not one this hook infers.
+  `autonomy.md` on the line above it, not one this hook infers;
+- **`guard-subagent-model`** (Claude Code) — refuses an `Agent` dispatch that
+  passes a call-site `model` for a subagent whose definition pins one: the
+  definition, not the call, decides which model a gate reads with;
+- **`warn-subagent-routing`** (Claude Code) — at session start, warns when
+  `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` is set (it replaces every model pin below),
+  when `CLAUDE_CODE_EFFORT_LEVEL` is set (it replaces every effort pin), when
+  Claude Code is older than 2.1.251 (the unnamed default then replaces the model
+  pins), or when its version cannot be read (so the pins cannot be confirmed to
+  hold). It warns and never blocks.
 
 **A brake that is a real file.** `touch ~/.claude/<project>-loop-STOP` and no
 merge lands until it is removed — enforced at the tool layer, so it holds even if
@@ -167,6 +249,19 @@ generator for the invariant→hook→test pattern; `post-deploy-verify` and
 `ro-debug` on the AWS target), and matching one-page `CLAUDE.md` / `AGENTS.md`
 maps a fresh session orients by.
 
+**Each gate reads with a pinned model and effort**, so a SHIP does not change
+meaning with whatever model the session was started on. `code-reviewer`,
+`security-scanner` and `cdk-diff-reviewer` pin `claude-opus-5`; `test-writer` and
+`prose-reviewer` pin `claude-sonnet-5`; all pin `high` effort — and their Codex
+profiles pin `gpt-5.6-sol` / `gpt-5.6-terra` from the same role table. A subagent
+with no definition defaults to `claude-sonnet-5` through
+`CLAUDE_CODE_SUBAGENT_MODEL` in `.claude/settings.json`; its effort cannot be
+pinned and follows the session. The driver session's own model and effort stay
+yours. To change a role in a generated project, edit `model:` / `effort:` in its
+`.claude/agents/<role>.md` — and the matching `.codex/agents/<role>.toml` — in a
+reviewed change; `upgrade` then reports the edited file as yours instead of
+replacing it. Why these values, and what voids them: `docs/decisions/subagent-routing.md`.
+
 **The hooks are examples, not laws.** `.claude/rules/invariants.md` states the
 pattern behind each one — a stated invariant, a mechanical check, a test for the
 check — so you can delete the ones whose invariant your project does not have and
@@ -249,6 +344,6 @@ that fails open must do provably bounded work, because fail-open turns every lin
 of its own work into a potential bypass.
 
 Development (from a clone — `PLAN.md` and `demo.sh` live in the repository, not
-in the published tarball): `pnpm test` (full), `pnpm test:unit` (fast loop),
+in the published tarball): `pnpm test` (full), `pnpm test:unit` (fast loop), `pnpm test:smoke` (the unit project only — the Windows pull-request lane),
 `pnpm template:check` (templates in place). The plan of record is `PLAN.md`;
 release notes and the release checklist ship in `CHANGELOG.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",
@@ -43,7 +43,8 @@
     "format": "prettier --write .",
     "typecheck": "tsc -p packages/cli/tsconfig.json && tsc -p tsconfig.json",
     "test": "pnpm build && vitest run",
-    "test:unit": "vitest run --project unit --project template",
+    "test:unit": "vitest run --project unit --project template --project benchmark",
+    "test:smoke": "vitest run --project unit",
     "test:e2e": "pnpm build && vitest run --project e2e",
     "template:install": "pnpm --dir templates/skeleton/aws-serverless install",
     "template:check": "pnpm --dir templates/skeleton/aws-serverless run check"
@@ -59,6 +60,6 @@
     "prettier": "^3.9.6",
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.65.0",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   }
 }

package/packages/cli/dist/commands/init.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, lstat, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { settingsForInstalledHooks } from '../lib/init-settings.js';
 import { mapConcurrent } from '../lib/copy-tree.js';
@@ -158,17 +158,40 @@ export async function initProject(repoDir, options) {
     const written = actions.filter(({ verdict }) => verdict === 'written').map(({ rel }) => rel);
     const skipped = actions.filter(({ verdict }) => verdict === 'skipped').map(({ rel }) => rel);
     if (!options.dryRun)
-        await recordInstall(repoDir, written, contents);
+        await recordInstall(repoDir, written, skipped, contents);
     return { written, skipped, plannedCount };
 }
+/**
+ * The text of a regular file, or `null` for anything else at that path — a
+ * directory, a symlink, a file this process cannot read. `kept` records only
+ * bytes that are the file itself: hashing through a link would put the hash of
+ * something outside the repository into a committed manifest, and a read that
+ * throws here would abort the install after every other file was written.
+ */
+async function readRegularFile(abs) {
+    try {
+        if (!(await lstat(abs)).isFile())
+            return null;
+        return await readFile(abs, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Record what was installed, so a later `upgrade` can tell a file it wrote
  * from a file the user owns.
  *
- * Only files actually **written** are recorded. A file `init` kept is
- * somebody else's — claiming it here would let the next upgrade replace a
- * user's own document with the rig's. Earlier entries are preserved: a re-run
- * writes nothing and must not therefore un-remember everything.
+ * Only files actually **written** are recorded in `files`. A file `init` kept
+ * is somebody else's — claiming it there would let the next upgrade replace a
+ * user's own document with the rig's. It is recorded in `kept` instead, with
+ * the sha256 of the bytes found on disk (RP-182): not a claim of ownership, a
+ * record that the rig saw the file and left it — so the next upgrade can say
+ * "kept by init, unchanged since" or "edited since" rather than only "not a
+ * version this rig ever released". A path already in `files` is never moved to
+ * `kept` by a later run that skips it: the rig wrote those bytes. Earlier
+ * entries are preserved: a re-run writes nothing and must not therefore
+ * un-remember everything.
  *
  * 🔴 **`kind`, `project` and `stacks` are preserved, not rewritten.** Reached
  * inside a rig `create` produced, this used to stamp `kind: 'init'`,
@@ -196,12 +219,24 @@ export async function initProject(repoDir, options) {
  * leaves is a `create` rig whose `CLAUDE.md` was deleted, and this function is
  * what makes that case safe.
  */
-async function recordInstall(repoDir, written, contents) {
+async function recordInstall(repoDir, written, skipped, contents) {
     const previous = await readManifest(repoDir);
     const name = projectNameFor(repoDir);
     const files = { ...(previous?.files ?? {}) };
     for (const rel of written)
         files[rel] = sha256(contents.get(rel) ?? '');
+    const kept = { ...(previous?.kept ?? {}) };
+    for (const rel of written)
+        delete kept[rel];
+    for (const rel of skipped) {
+        if (files[rel] !== undefined)
+            continue; // the rig wrote it once; still its bytes to vouch for
+        const found = await readRegularFile(path.join(repoDir, rel));
+        if (found === null)
+            delete kept[rel];
+        else
+            kept[rel] = sha256(found);
+    }
     const manifest = {
         version: await packageVersion(),
         kind: previous?.kind ?? 'init',
@@ -211,6 +246,7 @@ async function recordInstall(repoDir, written, contents) {
         project: previous?.project ?? { name, scope: name, region: '' },
         stacks: previous?.stacks ?? [],
         files,
+        ...(Object.keys(kept).length > 0 ? { kept } : {}),
     };
     await writeManifest(repoDir, manifest);
 }

package/packages/cli/dist/commands/memory.js

@@ -0,0 +1,182 @@
+// `create-agent-rig memory <doctor|load> [args…]`: the Rig side of the
+// RP-19 version handshake. The Rig is a CONSUMER of the Memory subsystem: it
+// resolves the executable from the machine subsystem manifest `setup` wrote
+// (RP-147), performs `--version --json` first, refuses a foreign contract
+// major with exit 4 before doctor/load ever run, and otherwise hands the verb
+// and its arguments to Memory and returns Memory's answer unchanged. The one
+// thing it adds to the arguments: a `load` that names no `--timeout-ms` gets
+// Memory's default internal deadline appended (`deadlinesFor`, RP-183);
+// everything the caller wrote passes through verbatim, and `doctor` is never
+// touched.
+//
+// What it never does, by construction: import Memory code, read Memory's
+// storage tree, or reinterpret a doctor/load payload — the only Memory bytes
+// it parses are the handshake's (`docs/command-contract.md`, "The version
+// handshake"; "Storage-tree ownership"). Pinned in packages/cli/test/memory.test.ts.
+//
+// Exit codes on this surface follow the contract: 0 for UNSUPPORTED/absent
+// (Memory is not registered here, or its executable is gone — the relocation
+// case), 1 for INTEGRATION-FAILED (the executable answered, but not with a
+// handshake the manifest promised — a broken VERSION is `manifest-stale`,
+// never `absent`), 3 for an unmet prerequisite (no configuration root: APPDATA
+// or HOME unset), 4 for a foreign contract major. For 0, 1, 3 and 4 the stdout
+// is exactly one JSON object with no file path in it; an invalid invocation
+// (exit 2 — no verb, or one outside doctor/load) writes nothing to stdout and
+// names the verbs on stderr; human hints always go to stderr.
+import { execFileRunner } from './setup.js';
+import { MEMORY_CONTRACT_MAJOR, SubsystemsError, handshake, readSubsystemsManifest, subsystemsManifestPath, } from '../lib/subsystems.js';
+const MEMORY_VERBS = ['doctor', 'load'];
+/**
+ * The outer deadline: the rig kills the Memory child after this many ms. It is
+ * the consumer's bound, and it should not be the one that fires first — a kill
+ * leaves no JSON answer behind. So `load` always carries an INTERNAL deadline
+ * as well (RP-183): Memory's own `--timeout-ms`, which per the Memory owner
+ * (RP-183, Jira) it answers with a typed result instead of being killed.
+ * `doctor` accepts no such flag per the same source — its args are never
+ * touched. Pinned in packages/cli/test/memory.test.ts, "RP-183".
+ */
+const VERB_TIMEOUT_MS = 60_000;
+/** Memory's default internal deadline when the caller names none. */
+const DEFAULT_MEMORY_TIMEOUT_MS = 45_000;
+/**
+ * Headroom the outer deadline keeps above an explicit internal one. Sized per
+ * the Memory owner (RP-183, Jira): Memory's Windows cleanup may return up to
+ * 10 s after its own deadline fired; the rest is spawn overhead. The rig does
+ * not measure that lag itself.
+ */
+const OUTER_MARGIN_MS = 15_000;
+/**
+ * The largest delay `execFile`'s timer can hold: Node clamps a larger
+ * `setTimeout` to ONE millisecond, which would make the outer kill fire first
+ * — the inversion this whole helper exists to prevent. A caller who asks for
+ * more than ~24.8 days gets this ceiling as the outer deadline.
+ */
+const MAX_TIMER_MS = 2_147_483_647;
+const TIMEOUT_FLAG = '--timeout-ms';
+/** Memory's own grammar for the value: a positive integer, milliseconds. */
+const TIMEOUT_VALUE = /^[1-9][0-9]*$/;
+/**
+ * The verb's argument list and outer deadline. `load` with no `--timeout-ms`
+ * gets the default appended; a caller-owned flag — any spelling — passes
+ * through verbatim, and only a well-formed `--timeout-ms <value>` pair can
+ * raise the outer deadline above it. Memory owns the refusal of a malformed
+ * value, so the rig neither corrects nor drops one.
+ */
+const deadlinesFor = (verb, args) => {
+    if (verb !== 'load')
+        return { args: [...args], timeoutMs: VERB_TIMEOUT_MS };
+    const at = args.findIndex((arg) => arg === TIMEOUT_FLAG || arg.startsWith(`${TIMEOUT_FLAG}=`));
+    if (at === -1) {
+        return {
+            args: [...args, TIMEOUT_FLAG, String(DEFAULT_MEMORY_TIMEOUT_MS)],
+            timeoutMs: VERB_TIMEOUT_MS,
+        };
+    }
+    const value = args[at] === TIMEOUT_FLAG ? args[at + 1] : undefined;
+    const internal = value !== undefined && TIMEOUT_VALUE.test(value) ? Number(value) : null;
+    // A digit string too long for a safe integer — or for a double at all —
+    // still lands on the ceiling: `Number` yields a huge float or Infinity, and
+    // `Math.min` with the ceiling holds either.
+    const timeoutMs = internal !== null
+        ? Math.min(Math.max(VERB_TIMEOUT_MS, internal + OUTER_MARGIN_MS), MAX_TIMER_MS)
+        : VERB_TIMEOUT_MS;
+    return { args: [...args], timeoutMs };
+};
+const jsonLine = (payload) => `${JSON.stringify(payload)}\n`;
+const isVerb = (verb) => MEMORY_VERBS.includes(verb);
+export async function runMemory(options) {
+    if (!isVerb(options.verb)) {
+        return {
+            exitCode: 2,
+            stdout: '',
+            stderr: `memory needs a verb: create-agent-rig memory <${MEMORY_VERBS.join('|')}> [args…]\n`,
+        };
+    }
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const run = options.run ?? execFileRunner;
+    let file;
+    try {
+        file = subsystemsManifestPath(env, platform);
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError && error.code === 'config-root-unavailable') {
+            // Nothing was attempted: without a configuration root there is no place
+            // the manifest could be. The contract's first exit-3 occasion — a
+            // variable that is not set — with the variable named, never a path.
+            const variable = platform === 'win32' ? 'APPDATA' : 'HOME';
+            return {
+                exitCode: 3,
+                stdout: jsonLine({
+                    schemaVersion: 1,
+                    result: 'prerequisites-unmet',
+                    missing: [{ kind: 'environment', name: variable, detail: 'not set' }],
+                }),
+                stderr: `memory: ${variable} is not set, so there is no configuration root to read the subsystem manifest from\n`,
+            };
+        }
+        throw error;
+    }
+    let manifest;
+    try {
+        manifest = await readSubsystemsManifest(file);
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError)
+            return {
+                exitCode: 1,
+                stdout: jsonLine({ schemaVersion: 1, result: 'integration-failed', reason: 'unreadable' }),
+                stderr: `memory: the subsystem manifest is not readable (${error.code}); run setup --memory-root again\n`,
+            };
+        throw error;
+    }
+    if (manifest === null)
+        return {
+            exitCode: 0,
+            stdout: jsonLine({ schemaVersion: 1, result: 'unsupported', reason: 'absent' }),
+            stderr: 'memory: Memory is not registered on this machine; run setup --memory-root <checkout>\n',
+        };
+    const entry = manifest.entries.memory;
+    const result = await handshake(entry, run);
+    if (result.status === 'foreign-major')
+        return {
+            exitCode: 4,
+            stdout: jsonLine({
+                schemaVersion: 1,
+                result: 'foreign-major',
+                contractVersion: result.contractVersion,
+                requiredMajor: MEMORY_CONTRACT_MAJOR,
+            }),
+            stderr: `memory: the registered Memory implements contract ${result.contractVersion}, ` +
+                `this rig requires major ${MEMORY_CONTRACT_MAJOR}; ${options.verb} was not run\n`,
+        };
+    if (result.status === 'unsupported')
+        return {
+            exitCode: 0,
+            stdout: jsonLine({ schemaVersion: 1, result: 'unsupported', reason: 'absent' }),
+            stderr: 'memory: the registered Memory executable is no longer there; ' +
+                'run setup --memory-root <checkout> again\n',
+        };
+    if (result.status === 'integration-failed')
+        return {
+            exitCode: 1,
+            stdout: jsonLine({ schemaVersion: 1, result: 'integration-failed', reason: result.reason }),
+            stderr: `memory: the handshake did not answer as the manifest promised (${result.reason}); ${options.verb} was not run\n`,
+        };
+    const [command, script] = entry.invocation;
+    const deadlines = deadlinesFor(options.verb, options.args);
+    const answer = await run(command, [script, options.verb, ...deadlines.args], {
+        timeoutMs: deadlines.timeoutMs,
+    });
+    if (answer.spawnError)
+        return {
+            exitCode: 1,
+            stdout: jsonLine({
+                schemaVersion: 1,
+                result: 'integration-failed',
+                reason: 'backend-failed',
+            }),
+            stderr: `memory: ${options.verb} could not be started (${answer.spawnError.code ?? 'spawn error'})\n`,
+        };
+    return { exitCode: answer.code, stdout: answer.stdout, stderr: answer.stderr };
+}

package/packages/cli/dist/commands/setup.js

@@ -0,0 +1,45 @@
+// `create-agent-rig setup --memory-root <checkout>`: the sole writer of the
+// machine subsystem manifest for 0.9.0 (ADR-RP-002 R6, RP-147). Order is the
+// contract: derive the entry from the one declared root, perform the
+// `--version --json` handshake, refuse a foreign contract major with exit 4
+// before anything is written, then write the manifest atomically.
+import { execFile } from 'node:child_process';
+import { SUBSYSTEMS_SCHEMA_VERSION, SubsystemsError, deriveMemoryEntry, handshake, subsystemsManifestPath, writeSubsystemsManifest, } from '../lib/subsystems.js';
+/** The default runner: one child, one JSON line, a bounded wait. */
+export const execFileRunner = (file, args, { timeoutMs }) => new Promise((resolve) => {
+    execFile(file, args, { timeout: timeoutMs, maxBuffer: 64 * 1024, windowsHide: true }, (error, stdout, stderr) => {
+        if (error && error.code === 'ENOENT')
+            resolve({ code: 1, stdout, stderr, spawnError: error });
+        else if (error && typeof error.code === 'number')
+            resolve({ code: error.code, stdout, stderr });
+        else if (error)
+            resolve({ code: 1, stdout, stderr, spawnError: error });
+        else
+            resolve({ code: 0, stdout, stderr });
+    });
+});
+export async function setupSubsystems(options) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const run = options.run ?? execFileRunner;
+    const file = subsystemsManifestPath(env, platform);
+    const entry = deriveMemoryEntry({
+        memoryRoot: options.memoryRoot,
+        nodeExecutable: options.nodeExecutable ?? process.execPath,
+        memoryRef: options.memoryRef ?? null,
+        installedVersion: '',
+    }, platform);
+    const result = await handshake(entry, run);
+    if (result.status === 'foreign-major')
+        return { outcome: 'refused', exitCode: 4, handshake: result };
+    if (result.status !== 'ok')
+        return { outcome: 'refused', exitCode: 1, handshake: result };
+    if (options.dryRun === true)
+        return { outcome: 'dry-run', file, handshake: result };
+    await writeSubsystemsManifest(file, {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: { memory: { ...entry, installedVersion: result.version } },
+    });
+    return { outcome: 'written', file, handshake: result };
+}
+export { SubsystemsError };