@nurix/etna 0.20.26 → 0.20.28

package/README.md

@@ -1,6 +1,6 @@
 # @nurix/etna
 
-CLI to bootstrap a project with a Nurix harness. Copies the harness's `CLAUDE.md`, skills, agents, rules, and hooks (plus scripts, if the harness ships any) into the project so they live with the code — version-controllable, editable per project, and visible without leaving the repo.
+CLI to bootstrap a project with a Nurix harness. It writes the harness in two layers. The **contract** is committed with your code: `CLAUDE.md`, `AGENTS.md`, `.claude/harness.json` (which harness, which version, where it comes from), `.claude/settings.json` and the one session-start hook. The **mounted harness** (skills, agents, rules, hooks) is gitignored, and every session start keeps it current from the harness CDN.
 
 A second install path also exists and is fully supported: `/plugin install <plugin>@nurixlabs` from inside Claude Code, which installs the harness as a plugin from the `nurixlabs/skills` marketplace. The two paths are first-class equals — pick the one that matches how you want to manage the harness. See [`docs/playbooks/harness/Readme.md`](../../docs/playbooks/harness/Readme.md#the-install-model) for the comparison.
 
@@ -24,23 +24,24 @@ After this completes (the `code` harness shown — the component folders differ
 
 ```
 your-project/
-├── CLAUDE.md              ← harness policy (non-git repo: existing file → CLAUDE.md.bak.<ISO>)
-├── AGENTS.md              ← Codex: CLAUDE.md byte-for-byte + a generated Codex runtime adapter
-├── .prettierrc.json       ← markdown formatting (proseWrap: never)
-├── .prettierignore
-├── .vscode/settings.json  ← editor settings (markdown formatter on save)
+├── CLAUDE.md              ← committed: harness policy (a pre-existing file moves aside as CLAUDE.bkp.md on first install)
+├── AGENTS.md              ← committed: Codex — CLAUDE.md byte-for-byte + a generated Codex runtime adapter
+├── .gitignore             ← gains the managed `# etna:mount:start` … `# etna:mount:end` block
+├── .prettierrc.json, .prettierignore, .vscode/settings.json   ← committed project config
+├── .codex/hooks.json      ← committed: Codex's SessionStart hook (runs mount.mjs)
+├── .codex/agents/         ← mounted: Codex subagents
+├── .agents/skills/        ← mounted: mirror of .claude/skills/ for Codex
 └── .claude/
-    ├── skills/            ← boundary, brainstorm, design, documentation, test-plan, workflow-mapper
-    ├── agents/            ← brainstorm, change-review, lld-mode, maintenance, performance-review, retro
-    ├── rules/             ← database.md, express.md, frontend.md, general.md, nomenclature.md, pnpm.md, testing.md
-    ├── hooks/             ← generate-ownership-index (SessionStart) + hooks.json
-    ├── settings.json      ← the hook is deep-merged in here (your existing keys preserved)
-    └── harness.json       ← {harness, name, version, files, digest, owned} — the installed-harness sentinel
+    ├── harness.json       ← committed: {harness, version, digest, docsRoot, mount: {origin, track}, owned, …}
+    ├── settings.json      ← committed: the hooks deep-merged in (your existing keys preserved)
+    ├── hooks/mount.mjs    ← committed: the SessionStart hook that mounts everything else
+    ├── skills/ agents/ rules/ hooks/…   ← mounted, gitignored by name (your own components stay tracked)
+    └── state/             ← machine-local: mount.json and the hooks' state, self-ignored
 ```
 
-Alongside the Claude tree, the installer projects the **Codex** artifacts so the repo also works under OpenAI Codex: `AGENTS.md` (above), `.agents/skills/` (a mirror of `.claude/skills/`, Codex's skill-scan path), and `.codex/agents/*.toml` + `.codex/hooks.json` (its subagents and SessionStart hook) — each surface written only when the harness ships that component kind. Nothing is written outside the project. No marketplace registration, no `enabledPlugins` entry, no global cache dependency — Claude Code picks up the project-scoped agents/skills/rules on its next session start (and Codex reads `AGENTS.md` + `.agents/` + `.codex/`), and the hooks wire in through `.claude/settings.json`.
+**At every session start** `.claude/hooks/mount.mjs` mounts the version `harness.json` pins, from the machine cache (`~/.etna/cache`) or the origin (`https://cdn.nustack.io` by default). It then checks `latest.json` for a newer version. When it finds one, it downloads the version beside the running one and prints *Harness code {new} is ready (mounted {old}); restart the session to run on it*. With `--track=latest` (the default) it also moves `version` in `harness.json`; commit that change like a lockfile bump. With `--track=pinned` it only prints the notice. `--origin=<url>` points a private network at its own origin. Offline with a warm cache, the session mounts from the cache. Offline with a cold cache, it prints one line and runs on what is on disk.
 
-Re-run `npx --yes @nurix/etna --name=code` anytime to refresh the harness content with what the latest published package ships. Existing same-named files are overwritten, and a component the harness used to own but no longer ships is pruned; files you've added that aren't part of the harness are left alone. In a git repo the previous `CLAUDE.md` and `.claude/` are overwritten and refreshed in place (recover them with `git checkout`); outside a git repo `CLAUDE.md` is backed up to `CLAUDE.md.bak.<ISO-timestamp>` and the whole `.claude/` tree is snapshotted to `.claude.bak.<ISO-timestamp>` first. Because the new `harness.json` carries the installed `{version, digest}`, a re-run whose **major** version is ahead of your repo's stamped `harness-version` is what the reconcile (below) detects as a structural upgrade.
+`npx --yes @nurix/etna --name=code` refreshes the contract and remounts from the bundle. A component absent from the manifest is pruned; files you've added that aren't part of the harness are left alone. **On a repository whose tracked set includes mounted paths**, the CLI prints the exact `git rm -r --cached -- <paths>` that adopts the mount; the files stay on disk, and you run and commit it yourself. Because `harness.json` carries the installed `{version, digest}`, a re-run whose **major** version is ahead of your repo's stamped `harness-version` is what the reconcile (below) detects as a structural upgrade.
 
 ## After install: bootstrap the harness
 

package/bin/etna.js

@@ -1,18 +1,10 @@
 #!/usr/bin/env node
 // packages/cli/bin/etna.js
-// `npx @nurix/etna [harness-name]` — copy a Nurix harness into the current
-// directory. Given a name it installs straight away; with no name (in a TTY) it
-// prompts you to pick one. Drops the harness's CLAUDE.md + project-root config
-// files (.prettierrc.json, .vscode/settings.json, …) at the project root, and
-// copies its skills, agents, rules, scripts, and hooks into <project>/.claude/.
-// Agents — the brainstorm facilitator plus the generic governance agents
-// (spec-mode, maintenance, change-review, performance-review) —
-// are vendored per-project into <project>/.claude/agents/, the same lifecycle as
-// skills and rules. The CLI writes only inside the target folder; nothing global.
-// No marketplace, no plugin enablement — files live in the project,
-// version-controlled and editable per project. Re-run `etna` to refresh.
-// Harnesses are addressed by their harness/<folder> name; several harnesses may
-// share one plugin.
+// `npx @nurix/etna --name=<harness>` — install a Nurix harness into the current directory: the
+// committed contract (CLAUDE.md, AGENTS.md, .claude/harness.json, settings.json, the mount hook,
+// .codex/hooks.json, root config and seeds) plus the mounted harness, gitignored by a managed
+// .gitignore block and written from the bundled payload. Outside the project it writes only the
+// machine cache (~/.etna/cache). Fuller account: docs/packages/cli.md.
 
 import { existsSync, mkdirSync, copyFileSync, cpSync, rmSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
@@ -20,6 +12,8 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import * as p from '@clack/prompts';
 import { materializeHarness, readJson as readJsonOrThrow } from '../lib/install/materialize.mjs';
+import { planHarnessFiles } from '../lib/install/plan.mjs';
+import { buildManifest, warmCacheFromPlan, probeOrigin, mountSettings } from '../lib/install/mount.mjs';
 import { projectSkills } from '../lib/codex/skills.mjs';
 
 // WHERE A HARNESS'S FILES LAND is not decided here — `lib/install/materialize.mjs` owns that
@@ -112,7 +106,7 @@ async function resolveHarnessName(name, harnesses) {
 
 // Copy one harness's bundled payload into the current directory. All file ops run
 // inside a spinner; the per-item detail + any warnings are emitted after it stops.
-async function installHarness(harnessName, harnesses) {
+async function installHarness(harnessName, harnesses, mount = {}) {
   const bundledHarnessDir = join(dataDir, 'harnesses', harnessName);
   const targetDir = process.cwd();
 
@@ -128,6 +122,7 @@ async function installHarness(harnessName, harnesses) {
     result = materializeHarness({
       bundledHarnessDir,
       targetDir,
+      mount,
     });
   } catch (error) {
     spin.stop(`Could not install ${harnessName}`);
@@ -136,9 +131,37 @@ async function installHarness(harnessName, harnesses) {
 
   spin.stop(`Installed ${harnessName}${versionTag}`);
 
+  // Warm the machine cache from the bundle so another clone on this machine mounts offline, then
+  // ask the origin whether a fresh clone elsewhere can mount this version.
+  const warnings = [...result.warnings];
+  const marker = readJson(join(targetDir, '.claude', 'harness.json'));
+  const { origin } = mountSettings(marker);
+  if (harnessMeta.version) {
+    try {
+      const { files, owned } = planHarnessFiles(bundledHarnessDir);
+      const placementVersion = `@nurix/etna@${readJson(join(pkgRoot, 'package.json')).version}`;
+      const manifest = buildManifest(files, {
+        slug: harnessName,
+        version: harnessMeta.version,
+        digest: harnessMeta.digest,
+        placementVersion,
+        owned,
+      });
+      warmCacheFromPlan({ files, manifest });
+    } catch (error) {
+      warnings.push(`Machine cache not warmed: ${error.message}`);
+    }
+    const published = await probeOrigin({ origin, slug: harnessName, version: harnessMeta.version });
+    if (published === 'unreachable') {
+      warnings.push(`${origin} is unreachable — mounted from the bundled payload; a fresh clone elsewhere mounts once it answers.`);
+    } else if (published === 'unpublished') {
+      warnings.push(`${harnessName} ${harnessMeta.version} is not published at ${origin} — a fresh clone elsewhere cannot mount it yet.`);
+    }
+  }
+
   p.note(result.installed.join('\n'), 'Written');
   for (const notice of result.notices) p.log.info(notice);
-  for (const warning of result.warnings) p.log.warn(warning);
+  for (const warning of warnings) p.log.warn(warning);
 
   p.outro(
     `${harnessName}${versionTag} ready in ${targetDir}. ` +
@@ -152,6 +175,7 @@ async function installHarness(harnessName, harnesses) {
 function parseArgs(args) {
   let name = null;
   let help = false;
+  const mount = {};
   let positional = null;
   const components = [];
   const takeValue = (a, flag, i) =>
@@ -161,6 +185,15 @@ function parseArgs(args) {
     if (a === '-h' || a === '--help') help = true;
     else if (a.startsWith('--name=')) name = a.slice('--name='.length);
     else if (a === '--name') name = args[++i] ?? '';
+    else if (a === '--track' || a.startsWith('--track=')) {
+      const [value, next] = takeValue(a, '--track', i);
+      i = next;
+      mount.track = value;
+    } else if (a === '--origin' || a.startsWith('--origin=')) {
+      const [value, next] = takeValue(a, '--origin', i);
+      i = next;
+      mount.origin = value.replace(/\/+$/, '');
+    }
     else if (a === '--rule' || a.startsWith('--rule=')) {
       const [value, next] = takeValue(a, '--rule', i);
       i = next;
@@ -171,7 +204,7 @@ function parseArgs(args) {
       if (value) components.push({ kind: 'skills', name: value });
     } else if (!a.startsWith('-') && positional === null) positional = a;
   }
-  return { name, help, positional, components };
+  return { name, help, positional, components, mount };
 }
 
 // Install one catalog component into the current directory — a rule as
@@ -257,7 +290,7 @@ function selfUpdateOrReexec() {
 async function main(args) {
   const idx = loadHarnessIndex();
   const harnesses = idx.harnesses || {};
-  const { name, help, positional, components } = parseArgs(args);
+  const { name, help, positional, components, mount } = parseArgs(args);
 
   if (help) {
     p.intro('@nurix/etna — Nurix harness installer');
@@ -266,7 +299,9 @@ async function main(args) {
         '  npx @nurix/etna                   pick a harness from the menu\n' +
         '  npx @nurix/etna --name=<harness>  install that harness directly\n' +
         '  npx @nurix/etna --rule=<name>     install one catalog rule\n' +
-        '  npx @nurix/etna --skill=<name>    install one subscribed catalog skill',
+        '  npx @nurix/etna --skill=<name>    install one subscribed catalog skill\n' +
+        '  --track=latest|pinned             whether sessions move the pin to a newer version (default latest)\n' +
+        '  --origin=<url>                    where sessions fetch the harness from (default https://cdn.nustack.io)',
     );
     printHarnessList(harnesses);
     const index = readJson(join(dataDir, 'catalog', 'index.json'));
@@ -282,6 +317,13 @@ async function main(args) {
 
   p.intro('@nurix/etna — Nurix harness installer');
 
+  if (mount.track !== undefined && !['latest', 'pinned'].includes(mount.track)) {
+    die(`--track takes latest or pinned, not '${mount.track}'.`);
+  }
+  if (mount.origin !== undefined && !/^https?:\/\/\S+$/.test(mount.origin)) {
+    die(`--origin takes an http(s) URL, not '${mount.origin}'.`);
+  }
+
   // A component install is standalone and skips the harness path entirely: it writes one
   // file or folder and records no ownership, so it needs no bundle, no manifest, and no
   // prune pass. Combining it with --name would make the ordering load-bearing (the harness
@@ -325,7 +367,7 @@ async function main(args) {
   const harnessName = await resolveHarnessName(requested, harnesses);
   if (!harnessName) return; // user cancelled the interactive pick
 
-  await installHarness(harnessName, harnesses);
+  await installHarness(harnessName, harnesses, mount);
 }
 
 // Before anything else: if a newer @nurix/etna is published, re-exec it (so a stale

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "9db89d92a35b",
+    "fingerprint": "47047f5258d8",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/codex/agents/bookkeeper.toml

@@ -18,7 +18,7 @@ Ground every edit in this ladder, in order. Never invent content; a fact you can
     | `dead-glob` | read the owning doc, find where the files went (`git log --follow`, glob search), update its `owns:` frontmatter |
     | `header-missing` | add the file-path header comment in the file's native comment syntax |
     | `doc-lint` | fix the finding, or add `<!-- doc-lint-disable: id -->` with a reason beside it when the flagged text is deliberate |
-    | `index-row-missing` | add the doc's row to `docs/README.md` |
+    | `index-row-missing` | a retired kind — delete the row. An index names folders, never files; a doc is found by `ls` and by the ownership index, not by a README row |
     | `doc-implicated` | read the diff of the named source file (`git diff` / `git log -p`), and update the owning doc **only where the diff contradicts documented behavior**; if nothing documented changed, the row's resolution is deleting it |
 
 2. **`note:` rows — expand strictly from the stated context.** The one-line context after the area is everything the session chose to hand you; land it in the destination the row names (`lands-in:` an owning doc, the backlog, or memory), written in that document's genre.

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.19.4",
+  "version": "3.19.6",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -25,5 +25,9 @@
     }
   ],
   "docsRoot": "docs",
-  "digest": "f3f36722fca1"
+  "mount": {
+    "origin": "https://cdn.nustack.io",
+    "track": "latest"
+  },
+  "digest": "761c9744d17b"
 }

package/data/harnesses/code/hooks/awareness.mjs

@@ -2,11 +2,12 @@
 // SessionStart: inject the session context block, the ownership index, and a budget-capped drift
 // banner (full report → .claude/state/drift-report.md). PostToolUse (Edit|Write|MultiEdit|Bash):
 // the silent detector — record file→doc touches, append machine-recomputable findings as auto:
-// rows to docs/operations/bookkeeping.md. Never narrates into the session, never blocks, exits 0
+// rows to docs/operations/bookkeeping.md. Both events emit backlog rows through the records door. Never narrates into the session, never blocks, exits 0
 // on every path: everything here is a convenience, absent on any failure.
 
 import fs from "node:fs";
 import path from "node:path";
+import os from "node:os";
 import { spawnSync } from "node:child_process";
 import {
   readStdin,
@@ -52,6 +53,7 @@ import { appendEvent } from "./lib/session-log.mjs";
 import { wallsAllowlist } from "./lib/graph-store.mjs";
 import { exitWallsAllowlist } from "./lib/exit-store.mjs";
 import { wallEnabled } from "./lib/walls.mjs";
+import { detectBacklog } from "./lib/backlog-detector.mjs";
 
 // Whether anything will ever read a row: a run whose allowlist switches off both walls the queue feeds —
 // the Stop wall and the commit wall — has nobody to drain it, so its rows would only ride the run's output
@@ -140,6 +142,42 @@ function toolsLines(projectDir) {
   return out;
 }
 
+// Versions staged in the machine cache for this harness (the mount hook writes them there).
+function stagedVersions(slug) {
+  const root = process.env.ETNA_CACHE_DIR || path.join(os.homedir(), ".etna", "cache");
+  try {
+    return fs.readdirSync(path.join(root, slug)).filter((v) => fs.existsSync(path.join(root, slug, v, "manifest.json")));
+  } catch (e) {
+    return [];
+  }
+}
+
+function newerThan(a, b) {
+  const left = String(a).split(".").map((n) => parseInt(n, 10) || 0);
+  const right = String(b).split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(left.length, right.length); i++) {
+    if ((left[i] || 0) !== (right[i] || 0)) return (left[i] || 0) > (right[i] || 0);
+  }
+  return false;
+}
+
+// The mounted version and digest from state/mount.json, and a newer version staged beside it.
+function mountSegment(projectDir, marker) {
+  let mounted = null;
+  try {
+    mounted = JSON.parse(readSafe(path.join(projectDir, ".claude", "state", "mount.json")));
+  } catch (e) {
+    mounted = null;
+  }
+  if (!mounted || !mounted.version) return " · not mounted";
+  const digest = mounted.digest ? ` (${mounted.digest})` : "";
+  const staged = stagedVersions(marker.harness || "")
+    .filter((v) => newerThan(v, mounted.version))
+    .sort((a, b) => (newerThan(a, b) ? -1 : 1))[0];
+  const waiting = staged ? ` · ${staged} staged — restart the session to run on it` : "";
+  return ` · mounted ${mounted.version}${digest}${waiting}`;
+}
+
 function harnessLine(projectDir) {
   let marker = null;
   try {
@@ -157,7 +195,7 @@ function harnessLine(projectDir) {
       : stamped
         ? `stamped ${stamped} — behind: run maintenance`
         : "unstamped — run maintenance";
-  return `Harness: installed ${marker.version} · ${root}/structure.md ${state}`;
+  return `Harness: installed ${marker.version}${mountSegment(projectDir, marker)} · ${root}/structure.md ${state}`;
 }
 
 function memoryLine(projectDir) {
@@ -575,6 +613,15 @@ function postToolUse(projectDir, payload) {
   if (rows.length > 0 && queueHasReader(projectDir)) appendRows(projectDir, rows);
 }
 
+// Backlog rows leave through the records door as they are written; silent, and never fatal.
+function observeBacklog(projectDir) {
+  try {
+    detectBacklog(projectDir);
+  } catch (e) {
+    /* the door is a convenience; the committed file stays the record */
+  }
+}
+
 // ---------------------------------------------------------------------------
 
 function main() {
@@ -589,6 +636,7 @@ function main() {
   const event = payload.hook_event_name || "SessionStart";
   if (event === "PostToolUse") postToolUse(projectDir, payload);
   else sessionStart(projectDir, payload);
+  observeBacklog(projectDir);
 }
 
 try {

package/data/harnesses/code/hooks/hooks.json

@@ -8,7 +8,7 @@
   },
   "hooks": {
     "SessionStart": [
-      { "matcher": "", "hooks": [ { "type": "command", "command": "f=\"$CLAUDE_PROJECT_DIR/.claude/hooks/awareness.mjs\"; [ -f \"$f\" ] || exit 0; node \"$f\"", "timeout": 10 } ] }
+      { "matcher": "", "hooks": [ { "type": "command", "command": "f=\"$CLAUDE_PROJECT_DIR/.claude/hooks/mount.mjs\"; [ -f \"$f\" ] || exit 0; node \"$f\"", "timeout": 15 } ] }
     ],
     "PostToolUse": [
       { "matcher": "Edit|Write|MultiEdit|Bash", "hooks": [ { "type": "command", "command": "f=\"$CLAUDE_PROJECT_DIR/.claude/hooks/awareness.mjs\"; [ -f \"$f\" ] || exit 0; node \"$f\"", "timeout": 10 }, { "type": "command", "command": "f=\"$CLAUDE_PROJECT_DIR/.claude/hooks/build-graph.mjs\"; [ -f \"$f\" ] || exit 0; node \"$f\"", "timeout": 10 } ] }

package/data/harnesses/code/hooks/lib/backlog-detector.mjs

@@ -0,0 +1,82 @@
+// harness/code/hooks/lib/backlog-detector.mjs — rows added to or removed from the backlog since the
+// last observation, emitted through the records door as `backlog` and `backlog.remove`. The last
+// observation lives in .claude/state/backlog-seen.json; an unchanged mtime and size, or an unchanged
+// hash, skips the parse. The row grammar mirrors NuStack's backlogRow.ts, anchor included.
+// Fuller account: docs/harness/code/hooks.md § lib/backlog-detector.mjs.
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { docsRoot } from "./repo.mjs";
+import { stateDir } from "./state.mjs";
+import { emitRecord } from "./records-door.mjs";
+
+// FNV-1a 64 over UTF-16 code units, first 8 hex — the same anchor NuStack's parser gives a row.
+export function anchorOf(text) {
+  let hash = 0xcbf29ce484222325n;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= BigInt(text.charCodeAt(i));
+    hash = (hash * 0x100000001b3n) & 0xffffffffffffffffn;
+  }
+  return hash.toString(16).padStart(16, "0").slice(0, 8);
+}
+
+// Rows of `- **[P1]** text — discovered by X` under their `## Section` headings; template sections skipped.
+export function parseBacklog(body) {
+  const rows = [];
+  let section = "Open";
+  for (const line of String(body || "").split("\n")) {
+    const heading = /^## (.+)$/.exec(line);
+    if (heading) {
+      section = heading[1].trim();
+      continue;
+    }
+    const match = /^- \*\*\[(P[0-3])\]\*\*\s*(.*)$/.exec(line);
+    if (!match || /^(format|grammar|template)$/i.test(section)) continue;
+    const text = match[2].trim();
+    const discovered = /—\s*discovered (?:by|while|during)\s+(.+?)\s*$/.exec(text);
+    rows.push({ anchor: anchorOf(text), priority: match[1], text, discoveredBy: discovered ? discovered[1] : null, section });
+  }
+  return rows;
+}
+
+export function backlogFile(projectDir) {
+  return path.join(projectDir, docsRoot(projectDir), "history", "backlog.md");
+}
+
+// Diffs the backlog against the last observation and emits the difference. Returns { added, removed }
+// (null when the file was unchanged and not parsed).
+export function detectBacklog(projectDir, { emit = emitRecord, parse = parseBacklog } = {}) {
+  const file = backlogFile(projectDir);
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch (e) {
+    return null;
+  }
+  const seenFile = path.join(stateDir(projectDir), "backlog-seen.json");
+  let seen = null;
+  try {
+    seen = JSON.parse(fs.readFileSync(seenFile, "utf8"));
+  } catch (e) {
+    seen = null;
+  }
+  if (seen && seen.mtimeMs === stat.mtimeMs && seen.size === stat.size) return null;
+  const text = fs.readFileSync(file, "utf8");
+  const hash = createHash("sha256").update(text).digest("hex");
+  const write = (rows) =>
+    fs.writeFileSync(seenFile, JSON.stringify({ mtimeMs: stat.mtimeMs, size: stat.size, hash, rows }) + "\n");
+  if (seen && seen.hash === hash) {
+    write(seen.rows || {});
+    return null;
+  }
+  const now = {};
+  for (const row of parse(text)) now[row.anchor] = row;
+  const prior = (seen && seen.rows) || {};
+  const added = Object.keys(now).filter((anchor) => !prior[anchor]).map((anchor) => now[anchor]);
+  const removed = Object.keys(prior).filter((anchor) => !now[anchor]).map((anchor) => prior[anchor]);
+  if (added.length) emit("backlog", added, { projectDir });
+  if (removed.length) emit("backlog.remove", removed, { projectDir });
+  write(now);
+  return { added, removed };
+}

package/data/harnesses/code/hooks/lib/records-door.mjs

@@ -0,0 +1,54 @@
+// harness/code/hooks/lib/records-door.mjs — the hooks' side of the records door. A hook never holds a
+// credential: it hands rows to `nustack records emit`, which climbs the door's rungs, and when the tool
+// is absent or its call fails it appends them to .claude/state/records/<kind>.jsonl, where the next
+// session finds them. Never throws. Fuller account: docs/harness/code/hooks.md § lib/records-door.mjs.
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { stateDir } from "./state.mjs";
+
+// The first executable named `name` on the PATH, or null.
+export function onPath(name, pathEnv = process.env.PATH || "") {
+  for (const dir of pathEnv.split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(dir, name);
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      if (fs.statSync(candidate).isFile()) return candidate;
+    } catch (e) {
+      /* not here */
+    }
+  }
+  return null;
+}
+
+function appendLocal(projectDir, kind, rows) {
+  const dir = path.join(stateDir(projectDir), "records");
+  fs.mkdirSync(dir, { recursive: true });
+  const at = new Date().toISOString();
+  fs.appendFileSync(path.join(dir, `${kind}.jsonl`), rows.map((row) => JSON.stringify({ kind, row, at }) + "\n").join(""));
+}
+
+// Emits rows of one kind: through `nustack records emit --kind <kind> --json` when the tool is on the
+// PATH and answers 0, else to the rung-4 file. Returns "door" or "file" (or "none" when nothing landed).
+export function emitRecord(kind, rows, { projectDir, env = process.env, timeoutMs = 5000 } = {}) {
+  const list = (Array.isArray(rows) ? rows : [rows]).filter(Boolean);
+  if (list.length === 0) return "none";
+  const binary = onPath("nustack", env.PATH || "");
+  if (binary) {
+    const res = spawnSync(binary, ["records", "emit", "--kind", kind, "--json"], {
+      cwd: projectDir,
+      input: JSON.stringify({ kind, rows: list }),
+      encoding: "utf8",
+      env,
+      timeout: timeoutMs,
+    });
+    if (!res.error && res.status === 0) return "door";
+  }
+  try {
+    appendLocal(projectDir, kind, list);
+    return "file";
+  } catch (e) {
+    return "none";
+  }
+}