@smartmemory/compose 0.4.1 → 0.5.1

package/server/stratum-client.js

@@ -7,7 +7,7 @@
  *
  * Contract:
  *   - Query calls:   5s timeout, 1 retry on timeout, no retry on error
- *   - Mutation calls: 10s timeout, no retry (mutations are not idempotent to retry)
+ *   - Mutation calls: 30s timeout, no retry (mutations are not idempotent to retry)
  *   - Exit 0  → parse stdout as JSON, return result
  *   - Exit 2  → conflict (idempotency), return { conflict: true, ... }
  *   - Non-zero → log stderr internally, return { error: { code, message, detail } }
@@ -22,7 +22,13 @@ import { resolveStratumBin, resolveStratumEngine as resolveEngine } from '../lib
 let _execFile = _execFileDefault;
 export function _testOnly_setExecFile(fn) { _execFile = fn; }
 const QUERY_TIMEOUT_MS = 5_000;
-const MUTATION_TIMEOUT_MS = 10_000;
+// Measured 2026-09-07 on this seam: a `guard transition` subprocess costs
+// 1.5-3.9 s idle (node startup + the stratum CLI module graph + guard store IO).
+// A 10 s budget left under 3x headroom, and under full-suite load 6 of 200
+// lifecycle-guard-e2e runs blew it; at 30 s the same probe under the same load
+// was 0 of 200. A mutation timeout is a fail-closed refusal to the caller, so
+// the budget must clear a loaded machine, not just an idle one.
+const MUTATION_TIMEOUT_MS = 30_000;
 
 // ---------------------------------------------------------------------------
 // Engine selection (COMP-STRATUM-TS)
@@ -81,8 +87,28 @@ function _spawnResult(bin, err, out, err2) {
   const stdout = out || '';
   let stderr = err2 || '';
   let code;
-  if (err?.code === 'ETIMEDOUT') code = -1;
-  else if (typeof err?.code === 'number') code = err.code;
+  // A timeout kill NEVER reaches the execFile CALLBACK as `code: 'ETIMEDOUT'` —
+  // node kills the child and reports `{ code: null, killed: true, signal:
+  // 'SIGTERM' }`. Matching only on ETIMEDOUT left every real timeout falling
+  // through to the generic `code = 1` branch below, so the TIMEOUT arms of
+  // runQuery/runMutation/runGuard (and runQuery's retry) were unreachable and a
+  // timed-out guard transition surfaced as `UNKNOWN` — rendered by the lifecycle
+  // routes as "transition refused by guard", i.e. an infrastructure timeout
+  // claiming the evidence was evaluated and rejected. Measured 2026-09-07:
+  // 6/200 lifecycle-guard-e2e runs under full-suite load, every one this shape.
+  // (`ETIMEDOUT` is still matched: execFileSync/spawnSync do set it, and
+  // probeStratumBin in lib/stratum-engine.js already checks all three.)
+  // `killed` is set only when NODE killed the child (timeout). A child that
+  // died to an outside signal reports `signal` with `killed: false`; that is
+  // not a timeout and is named as what it was rather than relabelled.
+  if (err?.code === 'ETIMEDOUT' || err?.killed === true) {
+    code = -1;
+    stderr = stderr || err.message || String(err);
+  } else if (typeof err?.code === 'number') code = err.code;
+  else if (err?.signal != null) {
+    code = 1;
+    stderr = stderr || `stratum child killed by ${err.signal}`;
+  }
   else if (typeof err?.code === 'string' && _SPAWN_CODES.has(err.code)) {
     code = -2;
     stderr = _spawnRemedy(bin, err.code);
@@ -102,6 +128,18 @@ function _spawnRemedy(bin, code) {
   return `${bin} (TS stratum engine) failed to spawn (${code}). Install @smartmemory/stratum or set COMPOSE_STRATUM_TS_CLI_BIN`;
 }
 
+/**
+ * A bounded, diagnosable tail of what the subprocess actually produced. The
+ * TIMEOUT/PARSE_ERROR envelopes used to carry `detail: ''`, which made every
+ * such failure indistinguishable from every other one in a log. stderr is not
+ * forwarded to REST callers (see the module contract) — this detail is the
+ * process-level shape (exit code + a stdout excerpt), not the child's stderr.
+ */
+function _detail(result) {
+  const out = String(result?.stdout ?? '').trim();
+  return `exit=${result?.code}${out ? ` stdout=${JSON.stringify(out.slice(0, 400))}` : ' stdout=<empty>'}`;
+}
+
 /**
  * Run a query command (read-only). Retries once on timeout.
  *
@@ -115,7 +153,7 @@ async function runQuery(args) {
     // Retry once on timeout
     result = await spawnStratum(args, QUERY_TIMEOUT_MS, bin);
     if (result.code === -1) {
-      return { error: { code: 'TIMEOUT', message: 'Stratum query timed out', detail: '' } };
+      return { error: { code: 'TIMEOUT', message: 'Stratum query timed out', detail: _detail(result) } };
     }
   }
 
@@ -136,7 +174,7 @@ async function runQuery(args) {
   try {
     return JSON.parse(result.stdout);
   } catch {
-    return { error: { code: 'PARSE_ERROR', message: 'Stratum returned invalid JSON', detail: '' } };
+    return { error: { code: 'PARSE_ERROR', message: 'Stratum returned invalid JSON', detail: _detail(result) } };
   }
 }
 
@@ -149,7 +187,7 @@ async function runMutation(args) {
   const result = await spawnStratum(args, MUTATION_TIMEOUT_MS, flowGateBin());
 
   if (result.code === -1) {
-    return { error: { code: 'TIMEOUT', message: 'Stratum gate timed out', detail: '' } };
+    return { error: { code: 'TIMEOUT', message: 'Stratum gate timed out', detail: _detail(result) } };
   }
 
   if (result.code === -2) {
@@ -177,7 +215,7 @@ async function runMutation(args) {
   try {
     return JSON.parse(result.stdout);
   } catch {
-    return { error: { code: 'PARSE_ERROR', message: 'Stratum returned invalid JSON', detail: '' } };
+    return { error: { code: 'PARSE_ERROR', message: 'Stratum returned invalid JSON', detail: _detail(result) } };
   }
 }
 
@@ -226,7 +264,7 @@ async function runGuard(action, kwargs, timeoutMs = MUTATION_TIMEOUT_MS, extraEn
   const result = await spawnStratumStdin(['guard', action], JSON.stringify(kwargs), timeoutMs, flowGateBin(), extraEnv);
 
   if (result.code === -1) {
-    return { error: { code: 'TIMEOUT', message: 'Stratum guard timed out', detail: '' } };
+    return { error: { code: 'TIMEOUT', message: 'Stratum guard timed out', detail: _detail(result) } };
   }
   if (result.code === -2) {
     console.error('[stratum-client] guard spawn failure:', result.stderr);
@@ -247,7 +285,7 @@ async function runGuard(action, kwargs, timeoutMs = MUTATION_TIMEOUT_MS, extraEn
   try {
     return JSON.parse(result.stdout);
   } catch {
-    return { error: { code: 'PARSE_ERROR', message: 'Stratum returned invalid JSON', detail: '' } };
+    return { error: { code: 'PARSE_ERROR', message: 'Stratum returned invalid JSON', detail: _detail(result) } };
   }
 }
 
@@ -367,17 +405,25 @@ export async function guardTransition({ resourceId, fromState, toState, artifact
 }
 
 /**
- * The single sanctioned bypass of predicate verification. Requires an
- * out-of-band override token (server env STRATUM_GUARD_OVERRIDE_TOKEN), a human
- * resolver, and a rationale. Records a 'deviation' ledger entry.
+ * The single sanctioned bypass of predicate verification. Requires a signed
+ * one-shot AUTHORIZATION, a human resolver, and a rationale. Records a
+ * 'deviation' ledger entry.
+ *
+ * Corrected 2026-09-07: this wrapper sent `override_token`, the shared secret
+ * stratum retired in STRAT-GUARD-AUTHZ @3647b4c. Stratum now reads
+ * `authorization` (`ts/src/mcp/server.ts:270`) — an sshsig over a payload it
+ * reconstructs, bound to the resource's ledger head — so every call this wrapper
+ * could have made was destined to fail on a missing authorization. It has no
+ * production caller; the field name is fixed so the first one does not inherit
+ * the break.
  * @returns {Promise<{status:string,ledger_ref:string,current_state:string}|ErrorResult>}
  */
-export async function guardOverride({ resourceId, fromState, toState, overrideToken, rationale, resolvedBy = 'human' }) {
+export async function guardOverride({ resourceId, fromState, toState, authorization, rationale, resolvedBy = 'human' }) {
   return runGuard('override', _compact({
     resource_id: resourceId,
     from_state: fromState,
     to_state: toState,
-    override_token: overrideToken,
+    authorization,
     rationale,
     resolved_by: resolvedBy,
   }));

package/server/supervisor.js

@@ -22,6 +22,8 @@ import { COMPOSE_HOME, getTargetRoot, ensureDataDir } from './project-root.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 console.log('[supervisor] Target project:', getTargetRoot());
 const PID_FILE = path.join(COMPOSE_HOME, '.compose-supervisor.pid');
+const VITE_BIN = path.join(COMPOSE_HOME, 'node_modules', '.bin', 'vite');
+const IS_SOURCE_CHECKOUT = fs.existsSync(path.join(COMPOSE_HOME, '.git'));
 
 const PROCESSES = [
   {
@@ -36,13 +38,25 @@ const PROCESSES = [
     port: process.env.AGENT_PORT || 4002,
     type: 'fork',
   },
-  {
+];
+
+if (IS_SOURCE_CHECKOUT) {
+  delete process.env.COMPOSE_PACKAGED_UI;
+  if (!fs.existsSync(VITE_BIN)) {
+    console.error(`[supervisor] Vite is required in a Compose source checkout but was not found at ${VITE_BIN}`);
+    console.error(`[supervisor] Run \`npm install\` in ${COMPOSE_HOME}, then retry \`compose start\`.`);
+    process.exit(1);
+  }
+  PROCESSES.push({
     name: 'vite',
-    command: path.join(COMPOSE_HOME, 'node_modules', '.bin', 'vite'),
+    command: VITE_BIN,
     port: process.env.VITE_PORT || 5195,
     type: 'spawn',
-  },
-];
+  });
+} else {
+  process.env.COMPOSE_PACKAGED_UI = '1';
+  console.log('[supervisor] Packaged install: serving cockpit from dist/ through the API server');
+}
 
 const MIN_BACKOFF = 500;
 const MAX_BACKOFF = 10_000;

package/server/vision-routes.js

@@ -53,7 +53,7 @@ import { addOpenLoop, resolveOpenLoop, listOpenLoops } from './open-loops-store.
 import {
   TERMINAL,
   guardedTransition, ensureGuard, projectFeatureStatus,
-  verifyCompletionEvidence, guardTestCommand,
+  verifyCompletionEvidence, guardTestCommand, isGuardInfraError,
 } from './lifecycle-guard.js';
 import {
   transitionsOf, skippableOf, completablePhaseOf, getMode, resolveMode,
@@ -85,6 +85,12 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   // COMP-MCP-ENFORCE: when enabled, lifecycle transitions are verdict-gated by
   // stratum's STRAT-GUARD (fail-closed). Default OFF — legacy behavior intact.
   const guardEnabled = () => capabilities?.guard === true;
+  // A guard that never answered is 503 "guard unavailable"; a guard that
+  // answered no is 422 "transition refused by guard". Collapsing them told the
+  // user their evidence was rejected when the subprocess had merely timed out.
+  const guardFailure = (res, g, from, to) => isGuardInfraError(g)
+    ? res.status(503).json({ error: 'guard unavailable', from, to, guardError: g.error })
+    : res.status(422).json({ error: 'transition refused by guard', from, to, verdict: g.verdict, guardError: g.error });
 
   // COMP-MCP-ENFORCE Slice 4: opt-in loopback REST auth on vision MUTATION
   // endpoints (lifecycle transitions, iterations, gate resolve, item CRUD,
@@ -404,7 +410,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // COMP-MCP-ENFORCE: verdict-gate the transition (fail-closed) before mutating.
       if (guardEnabled()) {
         const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
-        if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
+        if (!g.applied) return guardFailure(res, g, from, targetPhase);
       }
 
       item.lifecycle.currentPhase = targetPhase;
@@ -446,7 +452,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // COMP-MCP-ENFORCE: verdict-gate the skip (fail-closed) before mutating.
       if (guardEnabled()) {
         const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
-        if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
+        if (!g.applied) return guardFailure(res, g, from, targetPhase);
       }
 
       item.lifecycle.currentPhase = targetPhase;

package/dist/assets/channel-SnZzzh7k.js

@@ -1 +0,0 @@
-import{aq as o,ar as n}from"./App-Z4MU-H_F.js";const t=(r,a)=>o.lang.round(n.parse(r)[a]);export{t as c};

package/dist/assets/classDiagram-6PBFFD2Q-CBu92dSH.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-JytR14a9.js";import{_ as i}from"./App-Z4MU-H_F.js";import"./chunk-FMBD7UC4-C9s7KR9m.js";import"./chunk-YZCP3GAM-iE_tzriw.js";import"./chunk-55IACEB6-B4Q97BCP.js";import"./chunk-EDXVE4YY-R_qarkSf.js";import"./mobile-B7m9EO9D.js";import"./index-BEfrNBp8.js";import"./graph-CI_1htl0.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/assets/classDiagram-v2-HSJHXN6E-CBu92dSH.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-JytR14a9.js";import{_ as i}from"./App-Z4MU-H_F.js";import"./chunk-FMBD7UC4-C9s7KR9m.js";import"./chunk-YZCP3GAM-iE_tzriw.js";import"./chunk-55IACEB6-B4Q97BCP.js";import"./chunk-EDXVE4YY-R_qarkSf.js";import"./mobile-B7m9EO9D.js";import"./index-BEfrNBp8.js";import"./graph-CI_1htl0.js";var b={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{b as diagram};

package/dist/assets/clone-DgklGjHm.js

@@ -1 +0,0 @@
-import{b as r}from"./graph-BNzKGvoy.js";var e=4;function a(o){return r(o,e)}export{a as c};

package/dist/assets/stateDiagram-v2-QKLJ7IA2-DkVLzHbY.js

@@ -1 +0,0 @@
-import{s as r,b as e,a,S as s}from"./chunk-OYMX7WX6-BySQzVxc.js";import{_ as i}from"./App-Z4MU-H_F.js";import"./chunk-55IACEB6-B4Q97BCP.js";import"./chunk-EDXVE4YY-R_qarkSf.js";import"./mobile-B7m9EO9D.js";import"./index-BEfrNBp8.js";import"./graph-CI_1htl0.js";var n={parser:a,get db(){return new s(2)},renderer:e,styles:r,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{n as diagram};

package/lib/append-integrity.js

@@ -1,81 +0,0 @@
-/**
- * append-integrity.js — integrity for append-only canon files.
- *
- * COMP-CANON-OVERRIDE S1. Shared with COMP-CANON-ATTEST, which needs the same
- * primitive for `docs/judgment/records/ledger.jsonl`.
- *
- * A whole-file hash over an append-only file churns on every append and so
- * carries no signal about history. The useful question is narrower: **is the
- * prefix we previously attested still byte-identical?** That is what
- * `{length, prefix_hash}` answers — `prefix_hash` is sha256 over
- * `bytes[0, length)`, so a legitimate append (which only extends) verifies
- * clean while any rewrite of earlier content does not.
- *
- * A `{length, tail_hash}` variant was tried first and rejected: hashing the
- * trailing bytes says nothing about the prefix, so an in-place edit of an
- * early row that preserves total byte length — the shape a careless
- * `sed -i 's/park/ship/'` takes — produced a byte-identical attestation.
- *
- * SCOPE: this is drift detection, not enforcement. It catches careless and
- * accidental corruption. A deliberate actor who rewrites the file AND
- * recomputes the baseline passes, because both live in the workspace the
- * actor can write. See design.md, "The in-workspace ceiling".
- *
- * Pure — no I/O. Callers own reading the file and storing the baseline.
- */
-import { createHash } from 'node:crypto';
-
-/** @typedef {{ length: number, prefix_hash: string }} AppendBaseline */
-/** @typedef {{ ok: boolean, kind: 'clean'|'shrunk'|'prefix_changed'|'malformed_baseline' }} AppendVerdict */
-
-const HEX64 = /^[0-9a-f]{64}$/;
-
-function toBuffer(bytes) {
-  return Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes ?? '');
-}
-
-function sha256(buf) {
-  return createHash('sha256').update(buf).digest('hex');
-}
-
-/**
- * Capture the attestable state of an append-only file.
- *
- * @param {Buffer|string} bytes current file contents
- * @returns {AppendBaseline}
- */
-export function baselineFor(bytes) {
-  const buf = toBuffer(bytes);
-  return { length: buf.length, prefix_hash: sha256(buf) };
-}
-
-/**
- * Verify that `bytes` is `baseline` plus zero or more appended bytes.
- *
- * Fails closed on a malformed baseline: a missing or nonsensical baseline is
- * never treated as "nothing to check". That mirrors the malformed-record rule
- * the judgment attestation already follows (S5 R4).
- *
- * @param {Buffer|string} bytes current file contents
- * @param {AppendBaseline} baseline previously attested state
- * @returns {AppendVerdict}
- */
-export function verifyAppend(bytes, baseline) {
-  if (
-    !baseline
-    || typeof baseline !== 'object'
-    || !Number.isInteger(baseline.length)
-    || baseline.length < 0
-    || typeof baseline.prefix_hash !== 'string'
-    || !HEX64.test(baseline.prefix_hash)
-  ) {
-    return { ok: false, kind: 'malformed_baseline' };
-  }
-
-  const buf = toBuffer(bytes);
-  if (buf.length < baseline.length) return { ok: false, kind: 'shrunk' };
-  if (sha256(buf.subarray(0, baseline.length)) !== baseline.prefix_hash) {
-    return { ok: false, kind: 'prefix_changed' };
-  }
-  return { ok: true, kind: 'clean' };
-}

package/lib/canon-override.js

@@ -1,196 +0,0 @@
-/**
- * canon-override.js — the canon override: grant-then-write, ledger-first.
- *
- * COMP-CANON-OVERRIDE S2, implementing COMP-CANON-GUARD Decision 4.
- *
- * WHAT THIS IS: audit and careless-drift tooling. It makes the cooperative
- * path logged and the accidental path hard. It is NOT enforcement and must
- * never be described as such — `Bash` and Codex writes never reach the hook,
- * and every piece of state here lives in the workspace the agent can write.
- * A determined actor who forges a token AND its ledger row AND the baseline
- * passes. See design.md, "The in-workspace ceiling".
- *
- * ORDERING IS THE ATOMICITY ANSWER. The bypass row and the attest baseline are
- * written BEFORE the token is minted, so the failure mode is over-recording,
- * never under-recording: a token cannot exist without its row. If the write
- * that follows never happens, a bypass entry exists for a write that did not
- * occur — deliberately the safe direction.
- *
- * SINGLE-USE IS A RENAME, NOT A LOCK. Each grant is its own file, claimed by
- * renaming it into `consumed/`. Exactly one caller can rename a given path;
- * every loser gets ENOENT. An earlier draft used one shared JSON file with
- * temp-write-plus-rename, which gives atomic *publication* but not mutual
- * exclusion — two readers could each drop the token from their own snapshot
- * and both succeed.
- */
-import {
-  mkdirSync, writeFileSync, readFileSync, renameSync, readdirSync, existsSync, appendFileSync,
-} from 'node:fs';
-import { join, dirname } from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { isOverrideEligible } from './canon-registry.js';
-import { baselineFor } from './append-integrity.js';
-
-export const LEDGER_REL = '.compose/canon-overrides.jsonl';
-export const ATTEST_REL = '.compose/canon-overrides-attest.json';
-export const GRANTS_REL = '.compose/data/canon-grants';
-const CONSUMED_SUBDIR = 'consumed';
-
-/** 5 minutes: long enough for a grant-then-write round trip through an agent
- *  turn, short enough that a forgotten grant is not a standing hole. */
-export const GRANT_TTL_MS = 5 * 60 * 1000;
-
-function typedError(code, message) {
-  const err = new Error(message);
-  err.code = code;
-  return err;
-}
-
-function ensureDir(path) {
-  mkdirSync(path, { recursive: true });
-}
-
-/** Read the bypass ledger as parsed rows. Malformed lines are skipped rather
- *  than thrown on — a corrupt row must not make every claim fail open. */
-export function readOverrideLedger(cwd) {
-  const path = join(cwd, LEDGER_REL);
-  let raw;
-  try {
-    raw = readFileSync(path, 'utf8');
-  } catch (err) {
-    if (err?.code === 'ENOENT') return [];
-    throw err;
-  }
-  const rows = [];
-  for (const line of raw.split('\n')) {
-    if (!line.trim()) continue;
-    try { rows.push(JSON.parse(line)); } catch { /* skip a corrupt row */ }
-  }
-  return rows;
-}
-
-/**
- * Mint a single-use, path-scoped grant.
- *
- * @param {string} cwd workspace root
- * @param {{path:string, reason:string, operation?:string, featuresDir?:string}} args
- *   `actor` is deliberately NOT accepted — it is stamped here per Decision 3.
- * @returns {{token_id:string, path:string, expires_at:string}}
- */
-export function mintGrant(cwd, { path, reason, operation, featuresDir = 'docs/features' } = {}) {
-  if (typeof reason !== 'string' || reason.trim() === '') {
-    throw typedError(
-      'CANON_OVERRIDE_REASON',
-      'canon_override_grant: a non-empty reason is required — the bypass row is the whole point',
-    );
-  }
-  if (typeof path !== 'string' || path.trim() === '') {
-    throw typedError('CANON_OVERRIDE_PATH', 'canon_override_grant: path is required');
-  }
-  if (!isOverrideEligible(path, { featuresDir, point: 'hook' })) {
-    throw typedError(
-      'CANON_OVERRIDE_INELIGIBLE',
-      `canon_override_grant: ${path} is not override-eligible. Either it is not guarded at the `
-      + 'write-time hook (nothing is blocking it), or it is the override\'s own governance state, '
-      + 'which is deliberately ungrantable so a bypass cannot authorise rewriting its own record.',
-    );
-  }
-
-  const now = new Date();
-  const tokenId = randomUUID();
-  const row = {
-    ts: now.toISOString(),
-    actor: 'agent',                       // stamped here; never caller-supplied
-    path,
-    reason: reason.trim(),
-    operation: typeof operation === 'string' ? operation : null,
-    token_id: tokenId,
-  };
-
-  // ── Ledger and baseline FIRST ──────────────────────────────────────────────
-  const ledgerPath = join(cwd, LEDGER_REL);
-  ensureDir(dirname(ledgerPath));
-  appendFileSync(ledgerPath, `${JSON.stringify(row)}\n`);
-  writeAttestBaseline(cwd);
-
-  // ── Then the token ─────────────────────────────────────────────────────────
-  const grantsDir = join(cwd, GRANTS_REL);
-  ensureDir(grantsDir);
-  const expiresAt = new Date(now.getTime() + GRANT_TTL_MS).toISOString();
-  writeFileSync(
-    join(grantsDir, `${tokenId}.json`),
-    `${JSON.stringify({
-      token_id: tokenId,
-      path,
-      actor: 'agent',
-      operation: row.operation,
-      issued_at: now.toISOString(),
-      expires_at: expiresAt,
-    }, null, 2)}\n`,
-    { flag: 'wx' },                       // exclusive create: mint is serialized too
-  );
-
-  return { token_id: tokenId, path, expires_at: expiresAt };
-}
-
-/** Re-attest the bypass ledger. Called only from the append path — never as a
- *  standalone "fix", which would be the laundering step (S5 R1). */
-function writeAttestBaseline(cwd) {
-  const ledgerPath = join(cwd, LEDGER_REL);
-  const bytes = existsSync(ledgerPath) ? readFileSync(ledgerPath) : Buffer.alloc(0);
-  const attestPath = join(cwd, ATTEST_REL);
-  ensureDir(dirname(attestPath));
-  writeFileSync(attestPath, `${JSON.stringify(baselineFor(bytes), null, 2)}\n`);
-}
-
-/**
- * Claim a live grant for exactly `path`. Returns true if the write may proceed.
- *
- * Never throws: the hook's policy is fail-open, and a claim that explodes must
- * not wedge the session. A false return means "no grant" and the caller denies
- * on its own terms.
- */
-export function claimGrant(cwd, path) {
-  try {
-    const grantsDir = join(cwd, GRANTS_REL);
-    if (!existsSync(grantsDir)) return false;
-
-    // A token is only honoured if its row is in the ledger. This is what stops
-    // a raw-written token file from being consumable — the Bash-forgery case.
-    // It binds the two artifacts without pretending to be crypto: an actor who
-    // writes BOTH still passes, which is the documented ceiling.
-    const ledgerTokenIds = new Set(
-      readOverrideLedger(cwd).filter((r) => r?.path === path).map((r) => r?.token_id),
-    );
-    if (ledgerTokenIds.size === 0) return false;
-
-    const now = Date.now();
-    for (const entry of readdirSync(grantsDir, { withFileTypes: true })) {
-      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
-      const tokenPath = join(grantsDir, entry.name);
-
-      let token;
-      try { token = JSON.parse(readFileSync(tokenPath, 'utf8')); } catch { continue; }
-      if (token?.path !== path) continue;
-      if (!ledgerTokenIds.has(token?.token_id)) continue;
-
-      // Expiry from the immutable stamp, NOT mtime: a checkout gives a file a
-      // fresh mtime, which would revive a mistakenly committed token.
-      const expiresAt = Date.parse(token?.expires_at ?? '');
-      if (!Number.isFinite(expiresAt) || expiresAt <= now) continue;
-
-      // The claim. Exactly one caller can rename a given path; losers get ENOENT.
-      const consumedDir = join(grantsDir, CONSUMED_SUBDIR);
-      ensureDir(consumedDir);
-      try {
-        renameSync(tokenPath, join(consumedDir, entry.name));
-        return true;
-      } catch {
-        continue;                        // another process won; try the next token
-      }
-    }
-    return false;
-  } catch {
-    return false;
-  }
-}