@haposoft/cafekit 0.16.0-rc.3 → 0.16.0-rc.5

package/src/codex/hooks/lib/spec-receipt.cjs

@@ -3,162 +3,100 @@
 const fs = require('fs');
 const path = require('path');
 
-const EVIDENCE_NAMES = [
-  'Evidence',
-  'Task Test Plan & Verification Evidence',
-  'Verification & Evidence'
-];
-const PASS_MARKER = /^\s*Verification:\s*PASS\s*$/m;
-const LEGACY_SUCCESS = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
-
-// Single authority: delegate to shared workflow-policy validator. If an
-// installed policy exists but is broken, do not fall back to another copy.
-function loadSharedPolicy() {
-  const installed = path.join(__dirname, '../../scripts/workflow-policy.cjs');
-  const repo = path.join(__dirname, '../../../claude/scripts/workflow-policy.cjs');
-  const candidates = fs.existsSync(installed) ? [installed] : [repo];
-  let lastError = new Error('shared workflow policy is missing');
+function loadModule(installedName, sourceName, validate, missingMessage) {
+  const installed = path.join(__dirname, '../../scripts', installedName);
+  const source = path.join(__dirname, '../../../claude/scripts', sourceName);
+  const candidates = fs.existsSync(installed) ? [installed] : [source];
+  let lastError = new Error(missingMessage);
   for (const candidate of candidates) {
     try {
-      const policy = require(candidate);
-      if (typeof policy?.validateCanonicalReceipt !== 'function') {
-        throw new Error('shared workflow policy has no validateCanonicalReceipt function');
-      }
-      return { policy, error: null, path: candidate };
-    } catch (error) {
-      lastError = error;
-    }
+      const value = require(candidate);
+      validate(value);
+      return { value, error: null, path: candidate };
+    } catch (error) { lastError = error; }
   }
-  return { policy: null, error: lastError, path: candidates[0] };
+  return { value: null, error: lastError, path: candidates[0] };
 }
 
-function getSharedPolicy() {
-  return loadSharedPolicy().policy;
+function loadSharedPolicy() {
+  const loaded = loadModule(
+    'workflow-policy.cjs',
+    'workflow-policy.cjs',
+    (policy) => {
+      if (typeof policy?.validateCanonicalReceipt !== 'function') {
+        throw new Error('shared workflow policy has no validateCanonicalReceipt function');
+      }
+    },
+    'shared workflow policy is missing'
+  );
+  return { policy: loaded.value, error: loaded.error, path: loaded.path };
 }
 
-function getSharedValidate() {
-  return loadSharedPolicy().policy?.validateCanonicalReceipt || null;
+function loadSharedReceipt() {
+  const loaded = loadModule(
+    'spec-receipt.cjs',
+    'spec-receipt.cjs',
+    (receipt) => {
+      if (typeof receipt?.checkTaskReceipt !== 'function') {
+        throw new Error('shared spec receipt helper has no checkTaskReceipt function');
+      }
+    },
+    'shared spec receipt helper is missing'
+  );
+  return { receipt: loaded.value, error: loaded.error, path: loaded.path };
 }
 
-function isTapMetadataHeading(line) {
-  const policy = getSharedPolicy();
-  return typeof policy?.isTapMetadataHeading === 'function' && policy.isTapMetadataHeading(line);
-}
+function getSharedPolicy() { return loadSharedPolicy().policy; }
+function getSharedValidate() { return getSharedPolicy()?.validateCanonicalReceipt || null; }
 
-function evidenceBody(text) {
-  const lines = text.split('\n');
-  let start = -1;
-  let level = 0;
-  for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].match(/^(#{2,3})\s+(.+?)\s*$/);
-    if (match && EVIDENCE_NAMES.includes(match[2])) {
-      start = index + 1;
-      level = match[1].length;
-      break;
-    }
-  }
-  if (start < 0) return null;
-  let end = lines.length;
-  for (let index = start; index < lines.length; index += 1) {
-    const heading = lines[index].match(/^(#{1,6})\s+/);
-    if (heading && heading[1].length <= level && !isTapMetadataHeading(lines[index])) {
-      end = index;
-      break;
-    }
-  }
-  return lines.slice(start, end).join('\n');
+function receiptHelper() {
+  const loaded = loadSharedReceipt();
+  if (!loaded.receipt) throw loaded.error;
+  return loaded.receipt;
 }
 
+function evidenceBody(text) { return receiptHelper().evidenceBody(text, getSharedPolicy() || {}); }
 function safeTaskFile(featureDir, taskPath) {
-  const resolvedFeature = path.resolve(featureDir);
-  const target = path.resolve(featureDir, taskPath);
-  const relative = path.relative(resolvedFeature, target);
-  if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return null;
-  if (!fs.existsSync(target)) return null;
-  try {
-    const canonicalFeature = fs.realpathSync(resolvedFeature);
-    const canonicalTarget = fs.realpathSync(target);
-    const rel = path.relative(canonicalFeature, canonicalTarget);
-    if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
-  } catch {
-    return null;
-  }
-  return target;
+  const result = receiptHelper().safeRead(featureDir, taskPath);
+  return result.status === 'ok' ? result.path : null;
 }
-
 function validateCanonicalReceipt(body, options = {}) {
-  const fn = getSharedValidate();
-  if (!fn) return ['shared_validator'];
-  return fn(body, options);
+  const validate = getSharedValidate();
+  return validate ? validate(body, options) : ['shared_validator'];
+}
+function checkReceiptDetails(featureDir, taskPath, task, runtimeContext) {
+  const policy = getSharedPolicy();
+  if (!policy) return { failures: ['shared_validator'], status: 'missing' };
+  return receiptHelper().checkTaskReceipt(featureDir, taskPath, task, runtimeContext, policy);
 }
-
 function checkReceipt(featureDir, taskPath, task, runtimeContext) {
-  const failures = [];
-  const file = safeTaskFile(featureDir, taskPath);
-  if (!file || !fs.existsSync(file)) return ['a'];
-  let text = '';
-  try { text = fs.readFileSync(file, 'utf8'); } catch { return ['a']; }
-
-  const status = text.split('\n')
-    .find((line) => /^\s*(?:\*\*)?Status(?:\*\*)?\s*:/i.test(line));
-  if (!status || !/\bdone\b/i.test(status)) failures.push('a');
-
-  const body = evidenceBody(text);
-  if (body === null) {
-    failures.push('b');
-  } else if (
-    /\{\{[^}]+\}\}/.test(body)
-    || !(PASS_MARKER.test(body) || LEGACY_SUCCESS.test(body))
-  ) {
-    failures.push('c');
-  } else {
-    const policy = loadSharedPolicy().policy;
-    const options = typeof policy?.receiptValidatorOptions === 'function'
-      ? policy.receiptValidatorOptions(task, { runtimeContext, requireProvenanceBinding: true })
-      : { requireProvenanceBinding: true };
-    const canonical = validateCanonicalReceipt(body, options);
-    const map = {
-      verification_state: 'c',
-      command: 'e',
-      exit_result: 'f',
-      provenance: 'g',
-      artifact_hash: 'h',
-      artifact_declaration: 'h',
-      placeholder: 'c',
-      shared_validator: 'c',
-      validator_unavailable: 'c',
-    };
-    for (const fail of canonical) {
-      if (fail === 'verification_state' || fail === 'shared_validator' || fail === 'validator_unavailable') {
-        if (!failures.includes('c')) failures.push('c');
-        continue;
-      }
-      if (fail === 'placeholder') {
-        if (!failures.includes('c')) failures.push('c');
-        continue;
-      }
-      const letter = map[fail];
-      if (letter && !failures.includes(letter)) failures.push(letter);
-    }
-    if (!PASS_MARKER.test(body)) {
-      if (!failures.includes('c')) failures.push('c');
-    }
-  }
-
-  const completedAt = task?.completed_at;
-  if (
-    typeof completedAt !== 'string'
-    || !/^\d{4}-\d{2}-\d{2}T/.test(completedAt)
-    || Number.isNaN(Date.parse(completedAt))
-  ) failures.push('d');
-  return failures;
+  const map = {
+    unsafe_path: 'a', missing_receipt: 'b', task_status: 'a', completed_at: 'd',
+    verification_state: 'c', placeholder: 'c', validator_unavailable: 'c',
+    command: 'e', command_identity: 'e', exit_result: 'f', provenance: 'g',
+    artifact_hash: 'h', artifact_declaration: 'h',
+  };
+  return [...new Set(checkReceiptDetails(featureDir, taskPath, task, runtimeContext).failures.map((failure) => map[failure] || failure))];
+}
+function checkFeatureReceipt(featureDir, runtimeContext) {
+  const policy = getSharedPolicy();
+  if (!policy) return { failures: ['shared_validator'], status: 'missing' };
+  return receiptHelper().checkFeatureReceipt(featureDir, runtimeContext, policy);
+}
+function readTaskProof(featureDir, taskPath) {
+  return receiptHelper().readTaskProof(featureDir, taskPath, getSharedPolicy() || {});
 }
 
 module.exports = {
+  checkFeatureReceipt,
   checkReceipt,
+  checkReceiptDetails,
   evidenceBody,
+  getSharedPolicy,
+  getSharedValidate,
+  loadSharedPolicy,
+  loadSharedReceipt,
+  readTaskProof,
   safeTaskFile,
   validateCanonicalReceipt,
-  loadSharedPolicy,
-  getSharedPolicy,
 };

package/src/codex/hooks/lib/spec-utils.cjs

@@ -2,26 +2,77 @@
 
 const fs = require('fs');
 const path = require('path');
+const PATH_SAFETY = require('./runtime-path-safety.cjs');
+
+// Save original fs methods at load time to avoid being affected by test monkey patches
+// that simulate runtime canonicalization failures for spec paths. Resolver discovery
+// must use these originals, while spec resolution uses the (possibly patched) fs.
+const originalLstatSync = fs.lstatSync;
 
 // Installed Codex hooks use .codex/scripts; source tests use the Claude-side
 // source path. If an installed resolver exists but is malformed, do not fall
 // back to another copy: the shared authority is unavailable.
 const RESOLVER_CANDIDATES = [
-  path.join(__dirname, '../../scripts/spec-resolver.cjs'),
-  path.join(__dirname, '../../../claude/scripts/spec-resolver.cjs'),
+  {
+    file: path.join(__dirname, '../../scripts/spec-resolver.cjs'),
+    root: path.resolve(__dirname, '../..'),
+  },
+  {
+    file: path.join(__dirname, '../../../claude/scripts/spec-resolver.cjs'),
+    root: path.resolve(__dirname, '../../..'),
+  },
 ];
 
+function canonicalRealpath(candidate) {
+  try {
+    return PATH_SAFETY.canonicalRegularFile(candidate.root, candidate.file, 'shared spec resolver');
+  } catch (error) {
+    throw new Error(`${error.message} (${candidate.file})`);
+  }
+}
+
+function findCandidate() {
+  // Fail closed if preferred installed resolver exists but is invalid; never silently fall back to source.
+  const primary = RESOLVER_CANDIDATES[0];
+  let primaryExists = false;
+  try {
+    originalLstatSync(primary.file);
+    primaryExists = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw new Error(`resolver check failed: ${e.message} (${primary.file})`);
+  }
+  if (primaryExists) {
+    canonicalRealpath(primary);
+    return primary;
+  }
+  const secondary = RESOLVER_CANDIDATES[1];
+  let secondaryExists = false;
+  try {
+    originalLstatSync(secondary.file);
+    secondaryExists = true;
+  } catch (e) {
+    if (e.code !== 'ENOENT') throw new Error(`resolver check failed: ${e.message} (${secondary.file})`);
+  }
+  if (secondaryExists) {
+    canonicalRealpath(secondary);
+    return secondary;
+  }
+  return null;
+}
+
 function sharedResolver() {
-  const candidate = RESOLVER_CANDIDATES.find((file) => fs.existsSync(file)) || RESOLVER_CANDIDATES[0];
+  const candidate = findCandidate() || RESOLVER_CANDIDATES[0];
   try {
-    const resolver = require(candidate);
+    // Use canonical realpath for require to avoid symlink hijack
+    const realCandidate = canonicalRealpath(candidate);
+    const resolver = require(realCandidate);
     if (typeof resolver?.resolveActiveSpec !== 'function') {
       throw new Error('shared spec resolver has no resolveActiveSpec function');
     }
     return resolver;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`${message} (${candidate})`);
+    throw new Error(`${message} (${candidate.file})`);
   }
 }
 

package/src/codex/hooks/privacy-approval.cjs

@@ -24,6 +24,10 @@ try {
   const data = readPayload();
   if (!data) process.exit(0);
   const { projectRoot } = getHookContext(data);
+  // A pasted prompt arrives with whatever whitespace the terminal added around
+  // it. Rejecting on a trailing newline made the approval look broken while the
+  // id it named was still perfectly valid; the exactness that matters is the
+  // request id, checked below.
   const prompt = String(data.prompt || '').trim();
   cleanup(projectRoot);
 
@@ -49,8 +53,8 @@ try {
   }
 
   context(
-    `User approved one retry for the pending sensitive access (${result.displayName}). ` +
-    `The token is session-bound, path-bound, tool-bound, time-limited, and consumed atomically.`
+    `User approved the pending sensitive access (${result.displayName}). ` +
+    `The grant is session-bound, bound to exactly those paths, and expires in one hour.`
   );
   process.exit(0);
 } catch {

package/src/codex/hooks/privacy-block.cjs

@@ -6,12 +6,13 @@ const path = require('path');
 const {
   APPROVAL_PREFIX,
   createPending,
-  consumeToken
+  hasGrant
 } = require('./lib/privacy-state.cjs');
 const {
   getHookContext,
   readPayload
 } = require('./lib/hook-context.cjs');
+const { commandAccess } = require('./lib/privacy-command-analysis.cjs');
 
 const RESTRICTED = [
   /^\.env(?:[.\[*?{]|$)/i,
@@ -60,15 +61,90 @@ function resolveTarget(filePath, cwd) {
   }
 }
 
-function extractCommandPaths(command) {
-  const paths = new Set();
-  for (const token of String(command).split(/[\s|;&<>"']+/).filter(Boolean)) {
-    const cleaned = token.replace(/^["'()`]+|["'(),:]+$/g, '');
-    for (const candidate of cleaned.split('=')) {
-      const value = candidate.replace(/^["'()`]+|["'(),:]+$/g, '');
-      if (value && (isSensitive(value) || isSafe(value))) paths.add(value);
+/**
+ * When realpath fails, check whether the requested path is a symlink (or chain)
+ * whose lexical target is sensitive. Dangling link to protected target -> true (fail-closed deny);
+ * dangling benign link or link to allowed example/template -> false (allow).
+ * Limit hops to avoid loops; malformed/looping -> fail closed.
+ * TOCTOU note: check and use are not atomic; target could be swapped between this check and the actual read.
+ * This is a best-effort guardrail, not an arbitrary-shell security boundary. For strong isolation use OS sandbox.
+ */
+function isSymlinkToSensitive(filePath, cwd) {
+  try {
+    const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+    let current = requested;
+    let hops = 0;
+    const MAX_HOPS = 8;
+    while (hops < MAX_HOPS) {
+      let stat;
+      try {
+        stat = fs.lstatSync(current);
+      } catch {
+        return false;
+      }
+      if (!stat.isSymbolicLink()) return false;
+      let linkTarget;
+      try {
+        linkTarget = fs.readlinkSync(current);
+      } catch {
+        return true;
+      }
+      if (isSensitive(linkTarget) && !isSafe(linkTarget)) return true;
+      if (isSafe(linkTarget)) return false;
+      const next = path.isAbsolute(linkTarget) ? linkTarget : path.resolve(path.dirname(current), linkTarget);
+      if (next === current) return true;
+      try {
+        const real = fs.realpathSync(next);
+        if (isSensitive(real) && !isSafe(real)) return true;
+        if (isSafe(real)) return false;
+        return false;
+      } catch {
+        current = next;
+        hops += 1;
+        continue;
+      }
     }
+    return true;
+  } catch {
+    return true;
+  }
+}
+
+function extractCommandPaths(command) {
+  // The analyzer parses the command and returns the operands of every reading
+  // command it recognises, nested shells and `find -exec` included. Treating
+  // every unresolved expansion as sensitive, as this did before, denied
+  // `cat $FILE`, `wc -l *.cjs` and `cat ~/.zshrc` alike -- and every denial here
+  // costs a round trip through a one-shot approval prompt.
+  // A heredoc whose delimiter is quoted (<<'BODY') is inert: the shell expands
+  // nothing inside it, so no word in the body is ever read. The analyzer has no
+  // notion of heredocs and parses the body as shell, so prose that quotes a
+  // command -- a PR body carrying `cat .env` in backticks -- came back as a real
+  // command substitution. Blank those bodies out first. An unquoted delimiter
+  // (<<BODY) does expand, so it is left to the analyzer.
+  const scrubbed = String(command).replace(
+    /(<<-?[ \t]*)(['"])([A-Za-z_]\w*)\2[^\n]*\n[\s\S]*?\n[ \t]*\3\b/g,
+    '$1$2$3$2'
+  );
+
+  const paths = new Set(commandAccess(scrubbed).paths);
+
+  // Two shapes the analyzer cannot return. It drops any word carrying an
+  // expansion, so `~/.ssh/id_rsa` and `certs/*.pem` still have to be matched by
+  // name. And it only walks commands it recognises, so an unknown tool handed a
+  // secret through a file-shaped option, such as
+  // `docker compose --env-file .env`, is invisible to it.
+  const FILE_OPTION = /^--?[\w-]*(?:file|config|key|cert|identity)$/i;
+  const tokens = scrubbed.split(/[\s|;&<>"'()`]+/);
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    const shaped = /^~|[*?[{]/.test(token);
+    const optionFed = index > 0 && FILE_OPTION.test(tokens[index - 1]);
+    if (!shaped && !optionFed) continue;
+    const value = token.replace(/^~/, '').replace(/^["'()`]+|["'(),]+$/g, '');
+    if (value && isSensitive(value) && !isSafe(value)) paths.add(value);
   }
+
   return [...paths];
 }
 
@@ -126,6 +202,8 @@ function sensitiveRequest(filePath, cwd) {
   if (target) {
     if (isSensitive(target) && !isSafe(target)) return true;
     if (isSafe(target)) return false;
+  } else {
+    if (isSymlinkToSensitive(filePath, cwd)) return true;
   }
   return !isSafe(filePath) && isSensitive(filePath);
 }
@@ -152,7 +230,8 @@ try {
   if (runtime.privacyBlock === false) process.exit(0);
 
   const filePaths = sensitivePaths(data.tool_name || '', data.tool_input || {}, sessionCwd);
-  if (filePaths.length === 0) process.exit(0);
+  const effectivePaths = filePaths;
+  if (effectivePaths.length === 0) process.exit(0);
   if (!data.session_id) {
     deny(
       'Sensitive file access denied because this hook invocation had no Codex session ID. ' +
@@ -160,19 +239,19 @@ try {
     );
     process.exit(0);
   }
-  const tokenInput = {
+  const grantInput = {
     projectRoot,
     sessionCwd,
     sessionId: data.session_id,
-    filePaths,
-    toolName: data.tool_name
+    filePaths: effectivePaths
   };
-  if (consumeToken(tokenInput)) process.exit(0);
+  if (hasGrant(grantInput)) process.exit(0);
 
-  const pending = createPending(tokenInput);
+  const pending = createPending(grantInput);
   deny(
     `Sensitive file access denied: ${pending.displayName}. ` +
-    `If you approve exactly one retry in this Codex session, send this exact user prompt: ` +
+    `To approve access to exactly these paths for the next hour of this Codex ` +
+    `session, send this exact user prompt: ` +
     `${APPROVAL_PREFIX}${pending.requestId}`
   );
   process.exit(0);

package/src/codex/hooks/semantic-review-authority.cjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const STATE = require('./completion-authority-state.cjs');
+const PATH_SAFETY = require('./lib/runtime-path-safety.cjs');
+
+const SCHEMA_VERSION = 1;
+const MARKER = 'CAFEKIT_SEMANTIC_REVIEW_ATTESTATION ';
+const SHA256_RE = /^sha256:[a-f0-9]{64}$/;
+const REVIEWER_ROLE_ALLOWLIST = new Set(['code-auditor', 'code_auditor']);
+const RECORD_FIELDS = ['schema_version', 'kind', 'identity', 'semantic_digest', 'event', 'verdict', 'host_session_id', 'reviewer_agent_id', 'reviewer_agent_type', 'issued_at', 'mac'];
+
+function plain(value) { return Boolean(value && typeof value === 'object' && !Array.isArray(value)); }
+function exactKeys(value, fields) { return plain(value) && JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...fields].sort()); }
+function inside(root, target) { const relative = path.relative(root, target); return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative); }
+
+function projectRoot(payload = {}) {
+  const installedRoot = path.resolve(__dirname, '..', '..');
+  if (fs.existsSync(path.join(installedRoot, '.codex', 'hooks', path.basename(__filename)))) {
+    try { return STATE.canonicalProjectRoot(installedRoot); } catch {}
+  }
+  for (const candidate of [process.env.CLAUDE_PROJECT_DIR, process.env.PROJECT_ROOT]) {
+    if (typeof candidate === 'string' && candidate.trim()) { try { return STATE.canonicalProjectRoot(candidate); } catch { /* continue */ } }
+  }
+  const cwd = typeof payload.cwd === 'string' && payload.cwd.trim() ? payload.cwd : process.cwd();
+  return STATE.canonicalProjectRoot(cwd);
+}
+
+function identityFor(root, specFile, featureName) {
+  if (typeof featureName !== 'string' || !featureName.trim() || featureName.includes('/') || featureName.includes('\\') || featureName === '.' || featureName === '..' || featureName.includes('..')) throw new Error('feature identity is malformed');
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(featureName)) throw new Error('feature identity is malformed');
+  const canonicalRoot = STATE.canonicalProjectRoot(root);
+  const canonicalSpec = fs.realpathSync(path.resolve(specFile));
+  if (!inside(canonicalRoot, canonicalSpec) || path.basename(canonicalSpec) !== 'spec.json') throw new Error('spec identity escapes the project');
+  const relative = path.relative(canonicalRoot, canonicalSpec);
+  const expected = path.join('specs', featureName, 'spec.json');
+  if (relative !== expected) throw new Error(`spec identity must be ${expected}, not ${relative}`);
+  const spec = JSON.parse(fs.readFileSync(canonicalSpec, 'utf8'));
+  if (spec.feature_name !== featureName) throw new Error('feature identity does not match spec.json');
+  return { project_root: canonicalRoot, spec_file: canonicalSpec, feature_name: featureName };
+}
+
+function recordPath(root, identity) {
+  const name = STATE.digest({ namespace: 'cafekit-semantic-review-observation-v1', identity });
+  return path.join(STATE.stateDir(root), 'semantic-reviews', `observation-${name}.json`);
+}
+
+function parseClaim(message) {
+  const lines = String(message || '').split(/\r?\n/).filter((line) => line.startsWith(MARKER));
+  if (lines.length === 0) return null;
+  if (lines.length !== 1) throw new Error('exactly one semantic review attestation marker is required');
+  const claim = JSON.parse(lines[0].slice(MARKER.length));
+  if (!exactKeys(claim, ['feature_name', 'spec_file', 'semantic_digest', 'verdict'])) throw new Error('semantic review claim fields are malformed');
+  if (claim.verdict !== 'PASS' || !SHA256_RE.test(claim.semantic_digest || '')) throw new Error('semantic review claim must contain literal PASS and a sha256 digest');
+  return claim;
+}
+
+function validatorFor(root) {
+  const installedRoot = path.join(root, '.codex');
+  const installedHook = path.join(installedRoot, 'hooks', path.basename(__filename));
+  if (fs.existsSync(installedHook)) {
+    const canonicalHook = PATH_SAFETY.canonicalRegularFile(root, installedHook, 'installed semantic hook');
+    if (canonicalHook !== fs.realpathSync(__filename)) throw new Error('installed semantic hook identity is invalid');
+    const validator = path.join(installedRoot, 'scripts', 'validate-spec-output.cjs');
+    PATH_SAFETY.verifyCommonJsClosure(installedRoot, validator);
+    return PATH_SAFETY.canonicalRegularFile(installedRoot, validator, 'semantic validator');
+  }
+
+  const sourceRuntime = path.resolve(__dirname, '..', '..', 'claude');
+  const sourceRoot = path.resolve(sourceRuntime, '..');
+  if (path.basename(sourceRuntime) !== 'claude' || path.basename(sourceRoot) !== 'src') {
+    throw new Error('semantic validator runtime root is not recognized');
+  }
+  const validator = path.join(sourceRuntime, 'scripts', 'validate-spec-output.cjs');
+  PATH_SAFETY.verifyCommonJsClosure(sourceRoot, validator);
+  return PATH_SAFETY.canonicalRegularFile(sourceRoot, validator, 'semantic validator');
+}
+
+function currentDigest(root, specFile) {
+  const validator = validatorFor(root);
+  const result = spawnSync(process.execPath, [validator, path.dirname(specFile), '--semantic-digest'], { cwd: root, encoding: 'utf8' });
+  const digest = result.stdout.trim();
+  if (result.status !== 0 || !SHA256_RE.test(digest)) throw new Error(`semantic digest could not be recomputed (${result.stderr.trim() || `exit ${result.status}`})`);
+  return digest;
+}
+
+function recordFromSubagentStop(payload) {
+  // Honest-agent guardrail: the host hook observes this SubagentStop payload.
+  // The worker-authored claim is not authenticated input or a security boundary.
+  if (!plain(payload) || payload.hook_event_name !== 'SubagentStop') return { recorded: false, reason: 'event' };
+  for (const field of ['session_id', 'agent_id', 'agent_type', 'last_assistant_message']) if (typeof payload[field] !== 'string' || !payload[field].trim()) return { recorded: false, reason: `missing-${field}` };
+  if (!REVIEWER_ROLE_ALLOWLIST.has(payload.agent_type)) return { recorded: false, reason: 'reviewer-role' };
+  const root = projectRoot(payload);
+  const claim = parseClaim(payload.last_assistant_message);
+  if (claim === null) return { recorded: false, reason: 'no-claim' };
+  const identity = identityFor(root, path.resolve(root, claim.spec_file), claim.feature_name);
+  const digest = currentDigest(root, identity.spec_file);
+  if (digest !== claim.semantic_digest) throw new Error('claimed semantic digest does not match current artifacts');
+  const key = STATE.ensureKey();
+  const record = { schema_version: SCHEMA_VERSION, kind: 'semantic-review-observation', identity, semantic_digest: digest, event: 'SubagentStop', verdict: 'PASS', host_session_id: payload.session_id, reviewer_agent_id: payload.agent_id, reviewer_agent_type: payload.agent_type, issued_at: new Date().toISOString() };
+  record.mac = STATE.recordMac(record, key);
+  STATE.atomicWrite(recordPath(root, identity), record);
+  return { recorded: true, record };
+}
+
+function verifyAttestation(root, specFile, featureName, semanticDigest) {
+  let identity;
+  try { identity = identityFor(root, specFile, featureName); } catch (error) { return { ok: false, reason: error.message }; }
+  let record;
+  try { record = JSON.parse(fs.readFileSync(recordPath(root, identity), 'utf8')); } catch (error) { return { ok: false, reason: error.code === 'ENOENT' ? 'matching host-hook observation is missing' : 'host-hook observation is unreadable' }; }
+  const key = STATE.readKey();
+  if (key.missing) return { ok: false, reason: 'completion authority key is missing' };
+  if (!exactKeys(record, RECORD_FIELDS) || !STATE.macMatches(record, key.key)) return { ok: false, reason: 'host-hook observation is malformed or its MAC is invalid' };
+  if (record.schema_version !== SCHEMA_VERSION || record.kind !== 'semantic-review-observation' || record.event !== 'SubagentStop' || record.verdict !== 'PASS') return { ok: false, reason: 'host-hook observation event or verdict is invalid' };
+  if (STATE.stableStringify(record.identity) !== STATE.stableStringify(identity)) return { ok: false, reason: 'host-hook observation project, feature, or spec identity is invalid' };
+  if (record.semantic_digest !== semanticDigest) return { ok: false, reason: 'host-hook observation semantic digest is stale' };
+  return { ok: true, record };
+}
+
+if (require.main === module) {
+  try { const raw = fs.readFileSync(0, 'utf8').trim(); if (raw) recordFromSubagentStop(JSON.parse(raw)); }
+  catch (error) { process.stderr.write(`CafeKit semantic review SubagentStop claim rejected: ${error.message}\n`); }
+  // Codex SubagentStop requires valid JSON on stdout for every exit-0 hook.
+  process.stdout.write('{}\n');
+}
+
+module.exports = { MARKER, REVIEWER_ROLE_ALLOWLIST, recordFromSubagentStop, verifyAttestation, identityFor, recordPath };