@nurix/etna 0.20.22 → 0.20.23

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "e02eaf6819db",
+    "fingerprint": "722680de8132",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/harness.json

@@ -1,7 +1,7 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.18.1",
+  "version": "3.19.1",
   "files": [
     ".prettierignore",
     ".prettierrc.json",
@@ -25,5 +25,5 @@
     }
   ],
   "docsRoot": "docs",
-  "digest": "6c141ff0afec"
+  "digest": "bc085dd8505c"
 }

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

@@ -49,6 +49,22 @@ import {
   pruneState,
 } from "./lib/claims.mjs";
 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";
+
+// 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
+// into the project (docs/harness/code/exit-check.md).
+function queueHasReader(projectDir) {
+  let allowlist = null;
+  try {
+    allowlist = wallsAllowlist(projectDir) ?? exitWallsAllowlist(projectDir);
+  } catch (e) {
+    allowlist = null;
+  }
+  return wallEnabled(allowlist, "queue") || wallEnabled(allowlist, "bookkeeping");
+}
 
 // ---------------------------------------------------------------------------
 // SessionStart
@@ -566,7 +582,7 @@ function postToolUse(projectDir, payload) {
       detectOutcomes(projectDir, meta, rows);
     }
   }
-  appendRows(projectDir, rows);
+  if (rows.length > 0 && queueHasReader(projectDir)) appendRows(projectDir, rows);
 }
 
 // ---------------------------------------------------------------------------

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

@@ -25,6 +25,7 @@ import { appendEvent, unresolvedDenials, sessionLogPath, malformedEventLines } f
 import { approvedPackages, rejectedPackages } from "./lib/approved.mjs";
 import { claimActivity, releaseActivity, recentForeignTouches } from "./lib/claims.mjs";
 import { atStop, graphDenial, wallsAllowlist } from "./lib/graph-store.mjs";
+import { exitAtStop, exitWallsAllowlist, recordUnreadable } from "./lib/exit-store.mjs";
 import { WALLS, wallEnabled } from "./lib/walls.mjs";
 
 // --- the build graph's switch ------------------------------------------------------------
@@ -32,12 +33,13 @@ import { WALLS, wallEnabled } from "./lib/walls.mjs";
 // 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.
+// 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.
 let allowlistCache;
 function wallOn(projectDir, name) {
   if (allowlistCache === undefined) {
     try {
-      allowlistCache = wallsAllowlist(projectDir);
+      allowlistCache = wallsAllowlist(projectDir) ?? exitWallsAllowlist(projectDir);
     } catch (e) {
       allowlistCache = null; // a broken graph never switches a wall off
     }
@@ -524,6 +526,29 @@ function graphStop(projectDir, stopHookActive) {
   };
 }
 
+// The exit check (docs/harness/code/exit-check.md): authority, so a crash blocks rather than passes. It
+// blocks once — the box walls `.claude/state`, so the model cannot repair the file — and the second stop
+// records `blocked`, so the node still ends failed instead of met.
+function exitStop(projectDir, stopHookActive) {
+  let step;
+  try {
+    step = exitAtStop(projectDir);
+  } catch (e) {
+    const reason = `EXIT CHECK FAILED — ${e?.message || e}`;
+    if (!stopHookActive) {
+      return { decision: "block", reason: `${reason}. This node's exit set cannot be read, so it is not finished. (Said once — the next Stop ends the node blocked.)` };
+    }
+    try {
+      recordUnreadable(projectDir, reason);
+    } catch (e2) {
+      /* nowhere to record it; the box seals without a verdict and the run owner's own check decides */
+    }
+    return null;
+  }
+  if (!step || step.allow) return null;
+  return { decision: "block", reason: step.block };
+}
+
 function stopGate(projectDir, payload) {
   // The build graph is asked BEFORE the runtime's loop guard, and deliberately ignores it. The
   // guard exists because an unbounded Stop hook is a hang; the walker is bounded instead — every
@@ -538,6 +563,9 @@ function stopGate(projectDir, payload) {
   // hand-written graph should know it.
   const graph = graphStop(projectDir, payload.stop_hook_active);
   if (graph) return graph;
+  // The exit check is asked before the loop guard for the walker's reason: it is bounded by its own attempts.
+  const exit = exitStop(projectDir, payload.stop_hook_active);
+  if (exit) return exit;
 
   if (payload.stop_hook_active) return null; // the runtime's infinite-loop guard — never re-block
 

package/data/harnesses/code/hooks/lib/exit-store.mjs

@@ -0,0 +1,152 @@
+// harness/code/hooks/lib/exit-store.mjs — the exit check: what a NuStack generation box hands the harness
+// instead of a build graph. The box writes `.claude/state/exit.json` naming the documents a node owes; at
+// every Stop this module checks that each one EXISTS — never its shape — and hands the turn back naming what
+// is missing until the attempts run out, then records `blocked` (docs/harness/code/exit-check.md).
+//
+// This is authority, not hygiene: the caller turns a thrown error into a block, never a pass.
+
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite, stateDir } from "./state.mjs";
+
+export const EXIT_VERSION = 1;
+export const EXIT_FILE = "exit.json";
+export const EXIT_VERDICT_FILE = "exit-verdict.json";
+
+const SKIPPED_DIRS = new Set(["node_modules", ".git"]);
+
+// Read through a plain join: absence is dormancy, and asking must never create the folder.
+export function exitFile(projectDir) {
+  return path.join(projectDir, ".claude", "state", EXIT_FILE);
+}
+
+export function exitVerdictFile(projectDir) {
+  return path.join(stateDir(projectDir), EXIT_VERDICT_FILE);
+}
+
+// Absent → null. Present but not a v1 exit set → throws: a set nobody can read is not a set that is met.
+export function loadExit(projectDir) {
+  let text;
+  try {
+    text = fs.readFileSync(exitFile(projectDir), "utf8");
+  } catch (e) {
+    return null;
+  }
+  const set = JSON.parse(text);
+  const attempts = set?.attempts;
+  if (!set || set.v !== EXIT_VERSION || !Array.isArray(set.owed) || !Number.isInteger(attempts?.used) || !Number.isInteger(attempts?.max)) {
+    throw new Error(`.claude/state/${EXIT_FILE} is not a v${EXIT_VERSION} exit set`);
+  }
+  return set;
+}
+
+// `*` matches within one path segment; everything else is literal.
+export function globMatches(glob, rel) {
+  const pattern = glob
+    .split("*")
+    .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+    .join("[^/]+");
+  return new RegExp(`^${pattern}$`).test(rel);
+}
+
+function isFile(projectDir, rel) {
+  try {
+    return fs.statSync(path.join(projectDir, rel)).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+// How many files match a glob, walking only below its literal prefix.
+function globCount(projectDir, glob) {
+  const segments = glob.split("/");
+  const wild = segments.findIndex((segment) => segment.includes("*"));
+  const base = wild === -1 ? path.posix.dirname(glob) : segments.slice(0, wild).join("/");
+  let count = 0;
+  const walk = (rel) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(path.join(projectDir, rel), { withFileTypes: true });
+    } catch (e) {
+      return;
+    }
+    for (const entry of entries) {
+      if (SKIPPED_DIRS.has(entry.name)) continue;
+      const child = rel ? `${rel}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(child);
+      else if (entry.isFile() && globMatches(glob, child)) count += 1;
+    }
+  };
+  walk(base === "." ? "" : base);
+  return count;
+}
+
+// The owed entries not on disk: a path that is not a file, or a glob matching fewer files than its floor.
+export function missingOf(projectDir, set) {
+  const missing = [];
+  for (const entry of set.owed) {
+    if (typeof entry?.path === "string") {
+      if (!isFile(projectDir, entry.path)) missing.push({ type: entry.type, path: entry.path });
+    } else if (typeof entry?.glob === "string") {
+      const min = Number.isInteger(entry.min) && entry.min > 0 ? entry.min : 1;
+      const found = globCount(projectDir, entry.glob);
+      if (found < min) missing.push({ type: entry.type, glob: entry.glob, min, found });
+    } else {
+      throw new Error(`an owed entry names neither a path nor a glob: ${JSON.stringify(entry)}`);
+    }
+  }
+  return missing;
+}
+
+function describeMissing(entry) {
+  return entry.path
+    ? `\`${entry.path}\` (${entry.type})`
+    : `at least ${entry.min} file(s) matching \`${entry.glob}\` (${entry.type}, ${entry.found} found)`;
+}
+
+export function writeVerdict(projectDir, verdict) {
+  atomicWrite(exitVerdictFile(projectDir), `${JSON.stringify({ v: EXIT_VERSION, ...verdict }, null, 2)}\n`);
+}
+
+// Stop: null when dormant; `{ allow, verdict }` when the set is met or its attempts are spent; `{ block }` otherwise, charging one attempt.
+export function exitAtStop(projectDir) {
+  const set = loadExit(projectDir);
+  if (!set) return null;
+  const missing = missingOf(projectDir, set);
+  const nodeSlug = set.nodeSlug ?? null;
+  if (missing.length === 0) {
+    writeVerdict(projectDir, { nodeSlug, verdict: "done", missing, attempts: set.attempts });
+    return { allow: true, verdict: "done", missing };
+  }
+  if (set.attempts.used >= set.attempts.max) {
+    writeVerdict(projectDir, { nodeSlug, verdict: "blocked", missing, attempts: set.attempts });
+    return { allow: true, verdict: "blocked", missing };
+  }
+  const attempts = { ...set.attempts, used: set.attempts.used + 1 };
+  atomicWrite(exitFile(projectDir), `${JSON.stringify({ ...set, attempts }, null, 2)}\n`);
+  const left = attempts.max - attempts.used;
+  return {
+    block:
+      `EXIT CHECK — this node owes documents that do not exist yet: ${missing.map(describeMissing).join("; ")}. Write them, then stop. ` +
+      (left > 0
+        ? `This stop was handed back; ${left} more will be, and after that the node ends blocked.`
+        : "The next stop ends the node blocked if any of them is still missing."),
+    missing,
+    attempts,
+  };
+}
+
+// A set that cannot be read still ends the node — as blocked, naming why — rather than as met.
+export function recordUnreadable(projectDir, reason) {
+  writeVerdict(projectDir, { nodeSlug: null, verdict: "blocked", missing: [{ type: "exit-check", reason }], attempts: { used: 0, max: 0 } });
+}
+
+// The set's `mode.walls` allowlist, or null. A broken file switches no wall off: hygiene fails open.
+export function exitWallsAllowlist(projectDir) {
+  try {
+    const set = loadExit(projectDir);
+    return Array.isArray(set?.mode?.walls) ? set.mode.walls : null;
+  } catch (e) {
+    return null;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/etna",
-  "version": "0.20.22",
+  "version": "0.20.23",
   "description": "Bootstrap a project with a Nurix harness — copies the harness's CLAUDE.md, skills, agents, rules, and hooks directly into the project from a bundled payload (no marketplace fetch, no network).",
   "type": "module",
   "bin": {
@@ -42,5 +42,5 @@
     "agent",
     "plugin"
   ],
-  "etnaFingerprint": "e02eaf6819db"
+  "etnaFingerprint": "722680de8132"
 }