@nurix/etna 0.20.47 → 0.20.48

package/data/harnesses/code/hooks/lib/protection-gate.mjs

@@ -0,0 +1,208 @@
+// harness/code/hooks/lib/protection-gate.mjs — the Protection walls: frozen records and protected files,
+// on the file tools and on the shell write screen. The one module the fail-closed `protection.mjs`
+// loads, so its import graph stays narrow (frozen, repo, session-log, walls, graph, node built-ins): a
+// partial mount missing a compliance-only module cannot crash the hook that blocks on a crash.
+// `protectionVerdict` is the predicate and writes nothing; `protectionGate` adds the logged deny.
+// Compliance runs the same predicate first and defers when `protectionHandled` (docs/harness/code/hooks.md).
+
+import fs from "node:fs";
+import path from "node:path";
+import { frozenStatusAtHead } from "./frozen.mjs";
+import { readSafe, relIfInside, commandRoot, backtickTokens, docsRoot, resolveProjectDir } from "./repo.mjs";
+import { appendEvent } from "./session-log.mjs";
+import { wallEnabled } from "./walls.mjs";
+import { readGraph } from "./graph.mjs";
+
+// The per-call ceiling of one git call, and the default when a caller carries no deadline.
+const GIT_TIMEOUT_MS = 5000;
+
+// Milliseconds a git call may take: the time left before `deadlineAt`, capped at GIT_TIMEOUT_MS.
+function budgetMs(deadlineAt) {
+  if (!Number.isFinite(deadlineAt)) return GIT_TIMEOUT_MS;
+  return Math.max(0, Math.min(GIT_TIMEOUT_MS, Math.floor(deadlineAt - Date.now())));
+}
+
+export function decision(permissionDecision, reason) {
+  return {
+    hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: reason },
+  };
+}
+
+// A deny is also an event in the session gate log — the record that makes going silent after a
+// block impossible. The log is a dated per-session record (never drained; bookkeeping stays a
+// queue); the Stop and commit walls block on `denied` lines with no later `resolved` pair.
+export function deny(projectDir, sessionId, gate, target, reason) {
+  appendEvent(projectDir, sessionId, "denied", gate, target);
+  return decision("deny", reason);
+}
+
+// --- the build graph's switch ------------------------------------------------------------
+// A run handed a build graph (docs/harness/code/build-graph.md) may declare `mode.walls`, an
+// allowlist over lib/walls.mjs. Every wall it does not name is off for that session — because
+// the compliance set assumes a session that can dispatch a bookkeeper and a user who can answer
+// an ask, and a generation box has neither: its walls would be unresolvable blocks, not guard
+// rails. No graph, or a graph with no `mode` block, leaves every wall exactly as it was. With no graph
+// declaring one, an exit set (docs/harness/code/exit-check.md) may carry the same block.
+// Read here rather than through lib/graph-store.mjs and lib/exit-store.mjs, which import the state
+// module; the reading is theirs (`wallsAllowlist`, `exitWallsAllowlist`), field for field.
+function graphWalls(projectDir) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(projectDir, ".claude", "state", "graph.json"), "utf8");
+  } catch (e) {
+    return null; // absent — dormancy
+  }
+  const parsed = readGraph(text, projectDir);
+  if (!parsed.ok || !parsed.graph.mode) return null; // a refused graph never switches a wall off
+  return parsed.graph.mode.walls;
+}
+
+function exitWalls(projectDir) {
+  try {
+    const set = JSON.parse(fs.readFileSync(path.join(projectDir, ".claude", "state", "exit.json"), "utf8"));
+    const attempts = set?.attempts;
+    const isExitSet = set && set.v === 1 && Array.isArray(set.owed) && Number.isInteger(attempts?.used) && Number.isInteger(attempts?.max);
+    return isExitSet && Array.isArray(set?.mode?.walls) ? set.mode.walls : null;
+  } catch (e) {
+    return null; // absent or unreadable — no allowlist
+  }
+}
+
+// Keyed by projectDir, so one importer serving two repositories never reads the other's switch.
+const allowlistCache = new Map();
+export function wallOn(projectDir, name) {
+  if (!allowlistCache.has(projectDir)) {
+    let allowlist;
+    try {
+      allowlist = graphWalls(projectDir) ?? exitWalls(projectDir);
+    } catch (e) {
+      allowlist = null; // a broken graph never switches a wall off
+    }
+    allowlistCache.set(projectDir, allowlist);
+  }
+  return wallEnabled(allowlistCache.get(projectDir), name);
+}
+
+// The protected-list reader: AGENTS.md, the list itself, and every backticked path in
+// <docs>/operations/protected-files.md. Read once per projectDir per process.
+const protectedCache = new Map();
+export function protectedPaths(projectDir) {
+  if (protectedCache.has(projectDir)) return protectedCache.get(projectDir);
+  const root = docsRoot(projectDir);
+  const text = readSafe(path.join(projectDir, root, "operations", "protected-files.md"));
+  const list = ["AGENTS.md", `${root}/operations/protected-files.md`, ...backtickTokens(text)];
+  protectedCache.set(projectDir, list);
+  return list;
+}
+
+// A file write arriving by shell hits the same wall the Edit tool does. Only tokens in a
+// WRITING position count — redirect targets, `tee`/`mv`/`cp` destinations, and any path on an
+// in-place editor line (`sed -i`, `perl -i`) — so reading a frozen record into a pipe stays
+// legal. A token that isn't an existing repo path falls through frozenStatus/protected as a
+// no-op, which keeps sed expressions and flags harmless without shell-parsing them.
+export function bashWriteTargets(command) {
+  const targets = [];
+  let m;
+  const redirect = />{1,2}\s*([^\s;|&<>]+)/g;
+  while ((m = redirect.exec(command))) targets.push(m[1]);
+  const tee = /\btee\s+(?:-\S+\s+)*([^\s;|&<>]+)/g;
+  while ((m = tee.exec(command))) targets.push(m[1]);
+  const moveCopy = /\b(?:mv|cp)\s+(?:-\S+\s+)*\S+\s+([^\s;|&<>]+)/g;
+  while ((m = moveCopy.exec(command))) targets.push(m[1]);
+  if (/\b(?:sed|perl)\s+(?:-\S*\s+)*-\S*i/.test(command) || /\bsed\s+--in-place\b/.test(command)) {
+    for (const t of command.split(/[\s"']+/)) {
+      if (t && !t.startsWith("-") && /[/.]/.test(t)) targets.push(t);
+    }
+  }
+  return targets;
+}
+
+// The two walls on one repo-relative path. frozenStatusAtHead, not frozenStatus: a record frozen
+// only in the WORKTREE is a freeze born in the current edit — a plan legitimately flipping to
+// Complete — and denying that walls the completion ceremony itself. A spent budget reads as not
+// frozen: a timeout is never a gate. Returns { wall, rel, message, projectDir } or null.
+export function pathVerdict(projectDir, rel, { deadlineAt, shell = false } = {}) {
+  if (wallOn(projectDir, "frozen-record")) {
+    const timeoutMs = budgetMs(deadlineAt);
+    const frozen = timeoutMs > 0 ? frozenStatusAtHead(projectDir, rel, { timeoutMs }) : { frozen: false };
+    if (frozen.frozen) {
+      return {
+        wall: "frozen-record",
+        rel,
+        projectDir,
+        message: shell
+          ? `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}) — a shell write is still a write. A correction is a new dated entry that links back.`
+          : `BLOCKED — frozen record. \`${rel}\` is committed history and is never edited (${frozen.reason}). A correction is a new dated entry that links back.`,
+      };
+    }
+  }
+  if (wallOn(projectDir, "protected-file") && protectedPaths(projectDir).includes(rel)) {
+    return {
+      wall: "protected-file",
+      rel,
+      projectDir,
+      message: shell
+        ? `BLOCKED — protected file. \`${rel}\` is on the protected list — a shell write is still a write.`
+        : `BLOCKED — protected file. \`${rel}\` is on the protected list.`,
+    };
+  }
+  return null;
+}
+
+// The two walls on every write target of a shell command run in `root`; the first denial wins.
+export function shellVerdict(root, command, { deadlineAt } = {}) {
+  for (const target of bashWriteTargets(command || "")) {
+    const rel = relIfInside(root, target);
+    if (!rel) continue;
+    const verdict = pathVerdict(root, rel, { deadlineAt, shell: true });
+    if (verdict) return verdict;
+  }
+  return null;
+}
+
+// The predicate over a PreToolUse payload: { wall, rel, message, projectDir } or null. Writes nothing.
+// A Bash command is judged in the repo it acts on (lib/repo.mjs#commandRoot).
+export function protectionVerdict(projectDir, payload, { deadlineAt } = {}) {
+  const input = (payload && payload.tool_input) || {};
+  if (payload && payload.tool_name === "Bash") {
+    if (!input.command) return null;
+    const timeoutMs = budgetMs(deadlineAt);
+    const root = timeoutMs > 0 ? commandRoot(projectDir, payload, input.command, { timeoutMs }) : projectDir;
+    return shellVerdict(root, input.command, { deadlineAt });
+  }
+  const rel = relIfInside(projectDir, input.file_path);
+  return rel ? pathVerdict(projectDir, rel, { deadlineAt }) : null;
+}
+
+// The predicate with the logged deny: the hook output object, or null.
+export function protectionGate(projectDir, payload, { deadlineAt } = {}) {
+  const verdict = protectionVerdict(projectDir, payload, { deadlineAt });
+  if (!verdict) return null;
+  return deny(verdict.projectDir, payload.session_id, verdict.wall, verdict.rel, verdict.message);
+}
+
+// The dispatcher protection.mjs calls.
+export function protectionPreToolUse(payload, { deadlineAt } = {}) {
+  if (!payload || payload.hook_event_name !== "PreToolUse") return null;
+  return protectionGate(resolveProjectDir(payload), payload, { deadlineAt });
+}
+
+// True when the project's committed .claude/settings.json registers a PreToolUse handler whose
+// command names .claude/hooks/protection.mjs, and that file exists. A mount rewrites .claude/hooks/**
+// without touching the settings, so either half can be missing; compliance holds both walls then.
+export function protectionHandled(projectDir) {
+  if (!fs.existsSync(path.join(projectDir, ".claude", "hooks", "protection.mjs"))) return false;
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(path.join(projectDir, ".claude", "settings.json"), "utf8"));
+  } catch (e) {
+    return false;
+  }
+  const groups = settings?.hooks?.PreToolUse;
+  if (!Array.isArray(groups)) return false;
+  return groups.some(
+    (group) =>
+      Array.isArray(group?.hooks) &&
+      group.hooks.some((handler) => typeof handler?.command === "string" && handler.command.includes(".claude/hooks/protection.mjs"))
+  );
+}

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

@@ -1,12 +1,12 @@
 // 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.
+// credential: it hands rows to `nustack records emit` as a bare JSON array on stdin, and the CLI climbs
+// the door's rungs. There is no fallback file: with the tool absent or its call failing, the caller
+// keeps the rows and offers them again (lib/backlog-detector.mjs). 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 || "") {
@@ -22,33 +22,24 @@ export function onPath(name, pathEnv = process.env.PATH || "") {
   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).
+// Emits rows of one kind through `nustack records emit --kind <kind> --json`, the rows as a bare array
+// on stdin — the shape every published CLI's parseRows accepts. Returns "door" (exit 0), "absent" (no
+// `nustack` on the PATH), "failed" (a non-zero exit, a spawn error or a timeout) or "none" (no rows).
 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) {
+  if (!binary) return "absent";
+  try {
     const res = spawnSync(binary, ["records", "emit", "--kind", kind, "--json"], {
       cwd: projectDir,
-      input: JSON.stringify({ kind, rows: list }),
+      input: JSON.stringify(list),
       encoding: "utf8",
       env,
       timeout: timeoutMs,
     });
-    if (!res.error && res.status === 0) return "door";
-  }
-  try {
-    appendLocal(projectDir, kind, list);
-    return "file";
+    return !res.error && res.status === 0 ? "door" : "failed";
   } catch (e) {
-    return "none";
+    return "failed";
   }
 }

package/data/harnesses/code/hooks/lib/repo.mjs

@@ -1,11 +1,36 @@
-// harness/code/hooks/lib/repo.mjs — the shared floor every hook module stands on: safe reads,
-// path normalization, git, session ids, and the one definition of "source file". Each of these
-// existed as 2–5 diverging private copies before being hoisted here.
+// harness/code/hooks/lib/repo.mjs — the shared floor every hook module stands on: stdin, the project
+// root, the state folder, safe reads, path normalization, git, session ids, and the one definition of
+// "source file". Each of these existed as 2–5 diverging private copies before being hoisted here. It
+// imports nothing but node built-ins, which keeps the Protection hook's import graph narrow.
 
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
+// Read all of stdin synchronously; returns "" if nothing is piped.
+export function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch (e) {
+    return "";
+  }
+}
+
+// Resolve the project root: CLAUDE_PROJECT_DIR env, else payload cwd, else process cwd.
+export function resolveProjectDir(payload) {
+  return process.env.CLAUDE_PROJECT_DIR || (payload && payload.cwd) || process.cwd();
+}
+
+// Ensure .claude/state/ exists and is self-ignoring (a `*` .gitignore inside it),
+// so consumers never see machine-local state as untracked noise. Returns the dir.
+export function stateDir(projectDir) {
+  const dir = path.join(projectDir, ".claude", "state");
+  fs.mkdirSync(dir, { recursive: true });
+  const ignore = path.join(dir, ".gitignore");
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
+  return dir;
+}
+
 export function readSafe(file) {
   try {
     return fs.readFileSync(file, "utf8");
@@ -44,8 +69,8 @@ export function relIfInside(projectDir, filePath) {
   return rel.split(path.sep).join("/");
 }
 
-export function git(cwd, args) {
-  const res = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 5000 });
+export function git(cwd, args, { timeoutMs = 5000 } = {}) {
+  const res = spawnSync("git", args, { cwd, encoding: "utf8", timeout: timeoutMs });
   return res.status === 0 ? (res.stdout || "").trim() : null;
 }
 
@@ -75,7 +100,8 @@ export function backtickTokens(text) {
 // A candidate is normalized to its git toplevel so a subdirectory cwd still resolves to the
 // repo root. Claim and release both route here — two private copies of this rule once
 // disagreed, and the divergence leaked stale claims.
-export function commandRoot(projectDir, payload, command) {
+// `timeoutMs` bounds the toplevel lookup, for a caller spending a wall-clock budget.
+export function commandRoot(projectDir, payload, command, { timeoutMs = 5000 } = {}) {
   const cdMatch = /(?:^|\n|&&|;)\s*cd\s+"?([^"\s;&]+)"?/.exec(command || "");
   for (const candidate of [cdMatch && cdMatch[1], payload && payload.cwd]) {
     if (!candidate || !path.isAbsolute(candidate)) continue;
@@ -84,7 +110,7 @@ export function commandRoot(projectDir, payload, command) {
     } catch (e) {
       continue;
     }
-    return git(candidate, ["rev-parse", "--show-toplevel"]) || candidate;
+    return git(candidate, ["rev-parse", "--show-toplevel"], { timeoutMs }) || candidate;
   }
   return projectDir;
 }

package/data/harnesses/code/hooks/lib/session-log.mjs

@@ -9,8 +9,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { stateDir } from "./state.mjs";
-import { sid8 } from "./repo.mjs";
+import { stateDir, sid8 } from "./repo.mjs";
 
 export function sessionLogPath(projectDir, sessionId) {
   const dir = path.join(stateDir(projectDir), "sessions");

package/data/harnesses/code/hooks/lib/state.mjs

@@ -17,7 +17,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { globToRegExp } from "./ownership.mjs";
-import { docsRoot } from "./repo.mjs";
+import { docsRoot, stateDir } from "./repo.mjs";
 
 // Relative to the docs root (lib/repo.mjs#docsRoot) — never a bare "docs/..." literal.
 export const QUEUE_PATH = ["operations", "bookkeeping.md"];
@@ -326,15 +326,9 @@ export function waiverCovers(rows, kind, subject, today) {
   return unexpiredWaivers(rows, kind, today).some((w) => w.body.includes(`\`${subject}\``));
 }
 
-// Ensure .claude/state/ exists and is self-ignoring (a `*` .gitignore inside it),
-// so consumers never see machine-local state as untracked noise. Returns the dir.
-export function stateDir(projectDir) {
-  const dir = path.join(projectDir, ".claude", "state");
-  fs.mkdirSync(dir, { recursive: true });
-  const ignore = path.join(dir, ".gitignore");
-  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
-  return dir;
-}
+// stateDir lives in lib/repo.mjs, so the Protection hook's narrow import graph reaches it without
+// this module; it is re-exported here for every existing importer.
+export { stateDir };
 
 // The build graph's two machine-local files. Named here so every reader — the walker's adapters,
 // the compliance gates, a composer writing a graph before any session has run — spells them once.

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

@@ -0,0 +1,53 @@
+// harness/code/hooks/protection.mjs — the Protection hook: the fail-closed PreToolUse entry over
+// lib/protection-gate.mjs. It denies an edit or a shell write to a frozen record or a protected file,
+// and it is the one hook registered with `onFailure: "block"`: an exception in the gate, or a module
+// that cannot load, exits 1 after a line in .claude/state/hook-failures.log, and Claude Code then
+// blocks the call. A timeout is never a gate: every git call spends one wall-clock budget, a spent
+// budget allows, and a backstop timer exits 0 at the deadline if an asynchronous wait outlives it.
+// A repository with no git, no protected list or no docs root is no failure: nothing is frozen or
+// protected there. Fuller account: docs/harness/code/hooks.md.
+
+import fs from "node:fs";
+import path from "node:path";
+
+// The wall-clock budget, under the handler's 10 s timeout so process start fits in the gap.
+const PROTECTION_DEADLINE_MS = 7000;
+
+const deadlineAt = Date.now() + PROTECTION_DEADLINE_MS;
+setTimeout(() => process.exit(0), PROTECTION_DEADLINE_MS).unref();
+
+async function main() {
+  const { protectionPreToolUse } = await import("./lib/protection-gate.mjs");
+  let raw = "";
+  try {
+    raw = fs.readFileSync(0, "utf8");
+  } catch (e) {
+    raw = "";
+  }
+  let payload = {};
+  try {
+    payload = raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    payload = {}; // no payload names nothing to protect
+  }
+  const out = protectionPreToolUse(payload, { deadlineAt });
+  if (out) process.stdout.write(JSON.stringify(out));
+}
+
+let code = 0;
+try {
+  await main();
+} catch (e) {
+  // Fail closed: a Protection wall that cannot run must not let the write through.
+  code = 1;
+  try {
+    const dir = path.join(process.env.CLAUDE_PROJECT_DIR || process.cwd(), ".claude", "state");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(path.join(dir, "hook-failures.log"), `${new Date().toISOString()} protection.mjs ${e?.message || e}\n`);
+  } catch (e2) {
+    /* nowhere to write — the exit status still blocks */
+  }
+  process.stderr.write(`protection.mjs failed closed: ${e?.message || e}\n`);
+} finally {
+  process.exit(code);
+}

package/lib/install/plan.mjs

@@ -128,6 +128,8 @@ function freshSettings(bundleDir) {
 // `.codex/hooks.json` — the Claude hooks.json filtered to type:"command", the only kind Codex
 // executes, with each command prefixed so `$CLAUDE_PROJECT_DIR` resolves under a runtime that does
 // not export it. The translation itself is `toCodexCommand`, imported rather than restated.
+// `onFailure` is dropped from every handler: Codex's hook schema has no such field, and the
+// fail-closed claim it carries holds on Claude Code only.
 function codexHooks(bundleDir) {
   const hooksJson = join(bundleDir, 'hooks', 'hooks.json');
   if (!existsSync(hooksJson)) return null;
@@ -143,7 +145,7 @@ function codexHooks(bundleDir) {
     for (const group of groups) {
       const hooks = (group.hooks || [])
         .filter((h) => h.type === 'command')
-        .map((h) => ({ ...h, command: toCodexCommand(h.command) }));
+        .map(({ onFailure, ...h }) => ({ ...h, command: toCodexCommand(h.command) }));
       if (hooks.length) kept.push({ ...group, hooks });
     }
     if (kept.length) out[event] = kept;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.47",
+  "version": "0.20.48",
   "description": "Bootstrap a project with a Nurix harness — writes the committed contract (CLAUDE.md, AGENTS.md, .claude/harness.json, settings.json, the mount hook) and mounts the harness itself, gitignored, from a bundled payload; sessions keep it current from the CDN.",
   "type": "module",
   "bin": {
@@ -46,5 +46,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "7097a106c017"
+  "etnaFingerprint": "7050b3489eda"
 }