create-agent-rig 0.7.1 → 0.9.0

package/CHANGELOG.md

@@ -9,7 +9,178 @@ Versions are published to npm as [`create-agent-rig`](https://www.npmjs.com/pack
 
 Numbering is ordinary semver — **additive is a minor, a fix is a patch** — so
 that "I only take minors" remains a usable policy; 0.3.2 shipped additive
-content as a patch by the owner's call and stays recorded as one.
+content as a patch by the owner's call and stays recorded as one. 0.8.0 is the
+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.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,
+described the mechanisms behind them wrongly — and each fix is a deletion.** A
+count and a path list, both in `.claude/rules/autonomy.md`, and a paraphrase of
+that same path list in `loop/SKILL.md`, which ships in both harnesses' copies.
+Every one of them was a second writing of a fact the code owns, and every one
+had drifted from its source while the suite stayed green.
+
+**The `templates/agent-os/` payload gains no file and loses none**, measured
+tarball to tarball — `npm pack create-agent-rig@0.7.1` unpacked, against this
+release's own `npm pack`. That payload is the same 95 files either way, and
+exactly three of them differ in content. ⚠ The tarball as a whole is **not**
+unchanged: it grows by eleven files, and the section below names which and why.
+
+**Numbered a minor by the owner's call, not by this file's rule.** The rule at
+the top — additive is a minor, a fix is a patch — makes this delta a patch,
+because nothing is added to what a project installs. It ships as `0.8.0`
+because the owner's milestone of that name closes here and the number was fixed
+before the delta was measured. Recorded rather than reconciled, the way `0.3.2`
+is recorded above: a consumer on "I only take minors" receives three corrected
+documents and no new capability.
+
+### Fixed
+
+- **`.claude/rules/autonomy.md` stated a blind-spot count `guard-secret-file`
+  had outgrown.** The Never bullet said the guard's header "states the four
+  blind spots"; the header had been raised past four in `51402e99`, and the
+  stale copy shipped in 0.6.1, 0.6.2, 0.7.0 and 0.7.1 — a security rule
+  describing its own mechanism wrongly for four releases. The fix is not a
+  corrected number, which would only restart the same clock: the prose states
+  no count and points at the header, and `README.md` moved with it for the same
+  reason. Pinned in the generator's `test/template/guard-secret-file.test.ts`
+  (absent in a generated rig) › "no live rulebook document restates the guard’s
+  limit count" and › "the rule and the README still send the reader to the
+  guard’s own header".
+
+- **The same file re-listed the paths `guard-rulebook` protects, and its list
+  was incomplete.** The enumeration of trees an unattended run may not edit
+  omitted `.claude/doctor-exemptions.json`, which the guard does refuse. It is
+  replaced by a pointer to `RULEBOOK_PREFIXES` in
+  `.claude/scripts/unattended-flag.mjs` — the set the guard judges an edit
+  against — so there is one spelling of it rather than two. One fact that
+  pointer cannot carry is stated beside it, because it does not follow from the
+  set: the checkout board selector is refused **even when an item's allow-list
+  names it**.
+
+- **`loop/SKILL.md` paraphrased that set too, in both harnesses' copies.** The
+  step where a session composes an allow-list summarised the protected rulebook
+  in prose, so the one moment the set is read in anger was the moment it was
+  read from a summary that had already drifted. It now names
+  `RULEBOOK_PREFIXES` and says to open it. Both copies carry the change — the
+  Claude skill at `.claude/skills/loop/SKILL.md` and its Codex projection at
+  `.agents/skills/loop/SKILL.md`.
+
+### Inside the generator, and not inside a rig
+
+`packages/cli/src/policy/` is new — a typed policy declaration, a registry, a
+decision-record schema and one adapter per harness. Its compiled output adds
+eleven files to the published tarball, 245 → 256. **No command imports it**, so nothing a
+project scaffolded from this release does comes from it. What such a project
+does get from this release is the three corrected documents above — and an
+installed 0.7.1 rig still needs `create-agent-rig upgrade` to receive them —
+which is a necessary condition and not a sufficient one, because a rig whose
+owner has edited one of those three files is handed a conflict to merge rather
+than an overwrite.
+This module is named here only because a reader diffing the two tarballs sees
+eleven new files and is owed the reason they are not part of that answer.
+
+`templates/release-ledger.json` carries `0.7.1` at `52e879b6`, the commit it was
+published from, read from `npm view create-agent-rig@0.7.1 gitHead` and verified
+an ancestor of `master`. `templates/hash-history.json` is regenerated from it and
+now covers eleven releases, `0.2.0` through `0.7.1`, so `upgrade` can tell an
+untouched file from an edited one in a rig installed from 0.7.1.
 
 ## 0.7.1
 
@@ -913,7 +1084,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

@@ -85,6 +85,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           # same, for load; every argument after the verb goes to Memory verbatim
+```
+
+`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 +132,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;
@@ -116,7 +183,7 @@ wired by both `.claude/settings.json` and `.codex/hooks.json`:
   carries a credential VALUE. Both arms read one vocabulary,
   `.claude/scripts/lib/secrets.mjs`, and a refusal names the pattern and the line
   and **never the matched value** — printing it would leak the secret in the act
-  of refusing it. Its four blind spots are in its own header, each naming the
+  of refusing it. Its blind spots are in its own header, each naming the
   test that pins it or saying plainly that none does — and those tests live in
   this generator, not in the rig;
 - **`block-no-verify`** — refuses bypassing pre-commit checks (and knows the
@@ -135,7 +202,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 +243,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 +338,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.7.1",
+  "version": "0.9.0",
   "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/memory.js

@@ -0,0 +1,123 @@
+// `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 verbatim and returns Memory's answer unchanged.
+//
+// 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'];
+/** doctor/load do real work; the caller-supplied `--timeout-ms` is Memory's own bound. */
+const VERB_TIMEOUT_MS = 60_000;
+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 answer = await run(command, [script, options.verb, ...options.args], {
+        timeoutMs: VERB_TIMEOUT_MS,
+    });
+    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 };