create-agent-rig 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -14,6 +14,99 @@ 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,
@@ -991,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;
@@ -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.8.0",
+  "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 };

package/packages/cli/dist/index.js

@@ -2,13 +2,16 @@
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
+import { execFileRunner, setupSubsystems } from './commands/setup.js';
 import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
 import { readManifest } from './lib/manifest.js';
+import { SubsystemsError, refreshSubsystems, subsystemsManifestPath } from './lib/subsystems.js';
 import { promptConfirm, promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
 import { DEFAULT_TARGET, TARGET_NAMES } from './lib/targets.js';
-import { packageVersion } from './lib/version.js';
+import { packageVersion, rigHandshake } from './lib/version.js';
+import { runMemory } from './commands/memory.js';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
 Scaffolds a new project into <dir>: a Claude Code + Codex agent operating system
@@ -20,7 +23,8 @@ Options
                     required when not a terminal — default: ${DEFAULT_TARGET})
   --no-git          skip git init + the pristine-template baseline commit
   --no-color        plain output (NO_COLOR is respected too)
-  --version         print the version
+  --version         print the version (--version --json: the contract handshake,
+                    one JSON object with the name, version and contract version)
   -h, --help        this text
 
 Also: create-agent-rig init [--dry-run]
@@ -32,7 +36,68 @@ Also: create-agent-rig init [--dry-run]
 
 Also: create-agent-rig upgrade [--dry-run] [--yes]
   Bring the rig in the CURRENT repo up to this version. Replaces the files it
-  installed and you did not touch; everything else is reported, never merged.`;
+  installed and you did not touch; everything else is reported, never merged.
+  Re-runs the subsystem manifest derivation when one exists (see setup).
+
+Also: create-agent-rig setup --memory-root <checkout> [--memory-ref <sha>] [--dry-run]
+  Record the Memory executable in this machine's subsystem manifest
+  (~/.config/create-agent-rig/subsystems.json; %APPDATA% on Windows) from the
+  one declared root. Performs the --version --json handshake first and refuses
+  a foreign contract major with exit 4 before writing anything.
+
+Also: create-agent-rig memory <doctor|load> [args…]
+  Run a Memory verb through the registered executable: the --version --json
+  handshake first (a foreign contract major exits 4 and the verb never runs),
+  then the verb and its arguments verbatim, Memory's answer passed through
+  unchanged. No manifest answers unsupported/absent (exit 0); an invalid
+  invocation exits 2.`;
+async function runSetup(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: {
+                'memory-root': { type: 'string' },
+                'memory-ref': { type: 'string' },
+                'dry-run': { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const memoryRoot = values['memory-root'];
+    if (memoryRoot === undefined) {
+        process.stderr.write(`setup needs --memory-root <checkout>\n\n${USAGE}\n`);
+        return 1;
+    }
+    try {
+        const result = await setupSubsystems({
+            memoryRoot,
+            memoryRef: values['memory-ref'] ?? null,
+            dryRun: values['dry-run'] === true,
+        });
+        if (result.outcome === 'refused') {
+            process.stderr.write(`Memory handshake: ${JSON.stringify(result.handshake)}\n`);
+            return result.exitCode;
+        }
+        process.stdout.write(`Memory handshake: ${JSON.stringify(result.handshake)}\n` +
+            (result.outcome === 'dry-run'
+                ? `Dry run — nothing written (would write ${result.file}).\n`
+                : `Wrote ${result.file}\n`));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError) {
+            process.stderr.write(`setup: ${error.message} (${error.code})\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
 async function runInit(rawArgs) {
     let values;
     try {
@@ -219,15 +284,47 @@ async function runUpgrade(rawArgs) {
     }
     const result = await applyUpgrade(cwd, plan);
     process.stdout.write(`\nWrote ${result.written.length} files.\n`);
+    // The subsystem manifest is machine-scoped and written by `setup`; an
+    // upgrade re-runs the same derivation so `installedVersion` follows the
+    // executable the root now holds. It is never part of the rig manifest or of
+    // `result.written` — that file list is the repository's, this one is the
+    // user's. Absent stays absent: creating it is `setup`'s act.
+    try {
+        const refreshed = await refreshSubsystems({
+            file: subsystemsManifestPath(process.env, process.platform),
+            run: execFileRunner,
+            nodeExecutable: process.execPath,
+            platform: process.platform,
+        });
+        if (refreshed !== 'absent')
+            process.stdout.write(`Subsystem manifest: ${typeof refreshed === 'string' ? refreshed : JSON.stringify(refreshed)}\n`);
+    }
+    catch (error) {
+        if (!(error instanceof SubsystemsError))
+            throw error;
+        process.stdout.write(`Subsystem manifest: not refreshed — ${error.message} (${error.code})\n`);
+    }
     return 0;
 }
 async function main() {
     if (process.argv[2] === 'init') {
         return runInit(process.argv.slice(3));
     }
+    if (process.argv[2] === 'setup') {
+        return runSetup(process.argv.slice(3));
+    }
     if (process.argv[2] === 'upgrade') {
         return runUpgrade(process.argv.slice(3));
     }
+    if (process.argv[2] === 'memory') {
+        // The consumer path of the RP-19 handshake: manifest → `--version --json`
+        // → exit 4 on a foreign major → doctor/load passed through verbatim.
+        const [verb = '', ...args] = process.argv.slice(3);
+        const result = await runMemory({ verb, args });
+        process.stdout.write(result.stdout);
+        process.stderr.write(result.stderr);
+        return result.exitCode;
+    }
     let positionals;
     let values;
     try {
@@ -237,6 +334,9 @@ async function main() {
                 help: { type: 'boolean', short: 'h' },
                 target: { type: 'string' },
                 version: { type: 'boolean' },
+                // `--json` is read on `--version` alone: the handshake object of
+                // docs/command-contract.md, one JSON line and nothing else on stdout.
+                json: { type: 'boolean' },
                 'no-git': { type: 'boolean' },
                 'no-color': { type: 'boolean' },
             },
@@ -248,6 +348,10 @@ async function main() {
         return 1;
     }
     if (values.version) {
+        if (values.json) {
+            process.stdout.write(`${JSON.stringify(await rigHandshake())}\n`);
+            return 0;
+        }
         process.stdout.write(`${await packageVersion()}\n`);
         return 0;
     }