@dzhechkov/harness-core 0.4.4 → 0.5.0

package/src/agents-policy.ts

@@ -0,0 +1,338 @@
+/**
+ * Pure extraction, rendering, budget measurement, and drift detection for the
+ * always-on policy projection written to the root AGENTS.md.
+ *
+ * Callers own filesystem I/O. Keeping this module string-in/string-out makes
+ * the layer-1 drift guard deterministic and usable from both tests and CLI.
+ */
+
+import { createHash } from 'node:crypto';
+
+import { POLICY_BLOCK_BEGIN, POLICY_BLOCK_END } from '@dzhechkov/core';
+
+export interface PolicySource {
+  readonly id: string;
+  readonly file: string;
+  readonly heading: string;
+  readonly why: string;
+  /** Clause whose loss would turn the policy into a slogan rather than a rule. */
+  readonly operativeClause: string;
+}
+
+/** Ordered by cold-start value; this order is also the deterministic emit order. */
+export const POLICY_SOURCES: readonly PolicySource[] = [
+  {
+    id: 'integrity-rule',
+    file: 'CLAUDE.md',
+    heading: 'Integrity Rule (ABSOLUTE)',
+    why: 'Prevents fabricated evidence and unmeasured claims from a fresh runtime.',
+    operativeClause: 'measure before asserting',
+  },
+  {
+    id: 'verify-before-claiming',
+    file: 'CLAUDE.md',
+    heading: 'Verify before claiming',
+    why: 'Requires execution evidence instead of a prediction that work passes.',
+    operativeClause: 'verify before claiming success',
+  },
+  {
+    id: 'test-execution-no-watch',
+    file: 'CLAUDE.md',
+    heading: 'Test execution: never watch',
+    why: 'A watch-mode test run hangs an unattended coding session.',
+    operativeClause: 'npm test -- --run',
+  },
+  {
+    id: 'data-protection',
+    file: 'CLAUDE.md',
+    heading: 'Data protection',
+    why: 'Protects persistent QE and database state from destructive cleanup.',
+    operativeClause: 'without confirmation',
+  },
+  {
+    id: 'fixes-through-pipeline',
+    file: '.claude/rules/feature-adr-conventions.md',
+    heading: 'Fixes go through the pipeline',
+    why: 'Preserves the framing checkpoint for fixes and selects independent QE up front.',
+    operativeClause: 'ultracode or plain?',
+  },
+  {
+    id: 'publish-gate',
+    file: '.claude/rules/feature-adr-conventions.md',
+    heading: 'Publish gate',
+    why: 'Prevents publishing an unsettled disk version before independent verification lands.',
+    operativeClause: 'independent round with no blockers',
+  },
+  {
+    id: 'readme-first',
+    file: 'CLAUDE.md',
+    heading: 'README-first',
+    why: 'Keeps each changed package and the repository documentation current before a bump.',
+    operativeClause: 'in the SAME change',
+  },
+  {
+    id: 'cross-family-qe',
+    file: '.claude/rules/feature-adr-ultracode.md',
+    heading: 'Cross-family QE',
+    why: 'Prevents the model family that wrote code from certifying its own work.',
+    operativeClause: 'FAMILY, not host',
+  },
+  {
+    id: 'cost-of-detection-ladder',
+    file: '.claude/rules/feature-adr-conventions.md',
+    heading: 'Cost-of-detection ladder',
+    why: 'Places deterministic checks at the earliest reliable layer instead of reviewer memory.',
+    operativeClause: 'strongest layer that can express it',
+  },
+] as const;
+
+export interface PolicyBlock {
+  readonly id: string;
+  readonly file: string;
+  readonly heading: string;
+  /** Verbatim anchor body after the documented minimal whitespace normalization. */
+  readonly text: string;
+  readonly sha: string;
+}
+
+export interface ExtractPolicyBlocksResult {
+  readonly blocks: readonly PolicyBlock[];
+  /** Registry ids whose source is absent/null or whose begin/end anchor is malformed. */
+  readonly missing: readonly string[];
+}
+
+export type PolicyDriftStatus = 'ok' | 'stale' | 'missing-stamp' | 'missing-anchor' | 'orphan-stamp';
+
+export interface PolicyDriftFinding {
+  readonly id: string;
+  readonly file: string;
+  readonly status: PolicyDriftStatus;
+  readonly expectedSha: string | null;
+  readonly actualSha: string | null;
+}
+
+export interface PolicyDriftResult {
+  readonly applicable: boolean;
+  readonly findings: readonly PolicyDriftFinding[];
+}
+
+/** MEASURED 2026-08-18, codex-cli 0.147.0, project_doc_max_bytes unset: codex debug prompt-input included exactly 32768 bytes of a 414013-byte AGENTS.md and truncated mid-line with no notice. */
+export const CODEX_PROJECT_DOC_MAX_BYTES = 32_768;
+export const AGENTS_MD_BUDGET_WARN_FRACTION = 0.9;
+
+export interface AgentsMdBudget {
+  readonly bytes: number;
+  readonly cap: number;
+  /** Percentage in the human convention, e.g. 50 means half the cap. */
+  readonly pct: number;
+  readonly overflow: boolean;
+  /** UTF-8 byte offset immediately after the policy END marker, or -1 when absent. */
+  readonly policyBlockEndsAtByte: number;
+}
+
+const POLICY_STAMP = /^<!-- dz:policy id=([a-z0-9-]+) src=([^\s]+) sha=([a-f0-9]{12}) -->$/gm;
+
+export function normalizePolicyText(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map((line) => line.replace(/[ \t]+$/g, ''))
+    .join('\n')
+    .trim();
+}
+
+export function policyTextSha(text: string): string {
+  return createHash('sha256').update(normalizePolicyText(text), 'utf8').digest('hex').slice(0, 12);
+}
+
+function anchorPair(id: string): { begin: string; end: string } {
+  return { begin: `<!-- dz:policy id=${id} -->`, end: '<!-- dz:policy end -->' };
+}
+
+export function extractPolicyBlocks(
+  files: ReadonlyMap<string, string | null>,
+  sources: readonly PolicySource[] = POLICY_SOURCES,
+): ExtractPolicyBlocksResult {
+  const blocks: PolicyBlock[] = [];
+  const missing: string[] = [];
+  for (const source of sources) {
+    const raw = files.get(source.file);
+    if (typeof raw !== 'string') {
+      missing.push(source.id);
+      continue;
+    }
+    const { begin, end } = anchorPair(source.id);
+    const beginIndex = raw.indexOf(begin);
+    const secondBegin = beginIndex === -1 ? -1 : raw.indexOf(begin, beginIndex + begin.length);
+    const endIndex = beginIndex === -1 ? -1 : raw.indexOf(end, beginIndex + begin.length);
+    const nestedBegin = beginIndex === -1 ? -1 : raw.indexOf('<!-- dz:policy id=', beginIndex + begin.length);
+    if (beginIndex === -1 || secondBegin !== -1 || endIndex === -1 || (nestedBegin !== -1 && nestedBegin < endIndex)) {
+      missing.push(source.id);
+      continue;
+    }
+    const text = normalizePolicyText(raw.slice(beginIndex + begin.length, endIndex));
+    if (text.length === 0) {
+      missing.push(source.id);
+      continue;
+    }
+    blocks.push({ id: source.id, file: source.file, heading: source.heading, text, sha: policyTextSha(text) });
+  }
+  return { blocks, missing };
+}
+
+export function renderPolicySections(
+  blocks: readonly PolicyBlock[],
+  sources: readonly PolicySource[] = POLICY_SOURCES,
+): readonly string[] {
+  const headingById = new Map(sources.map((source) => [source.id, source.heading]));
+  return blocks.map((block) => {
+    const heading = headingById.get(block.id) ?? block.heading;
+    return `<!-- dz:policy id=${block.id} src=${block.file} sha=${block.sha} -->\n## ${heading}\n\n${block.text}\n\nCanonical: ${block.file}`;
+  });
+}
+
+/**
+ * Has this repository OPTED IN to policy sync? The `dz:policies` fence in `AGENTS.md` is the only
+ * durable on-disk signal that `dz agents-sync` was ever run here. Keeping the marker knowledge in
+ * this module means no caller has to re-spell the literal (a second spelling is a second surface).
+ */
+export function hasPolicyFence(fileText: string | null | undefined): boolean {
+  return typeof fileText === 'string' && fileText.includes(POLICY_BLOCK_BEGIN);
+}
+
+export function measureAgentsMdBudget(fileText: string): AgentsMdBudget {
+  const bytes = Buffer.byteLength(fileText, 'utf8');
+  const endChar = fileText.indexOf(POLICY_BLOCK_END);
+  const policyBlockEndsAtByte = endChar === -1
+    ? -1
+    : Buffer.byteLength(fileText.slice(0, endChar + POLICY_BLOCK_END.length), 'utf8');
+  return {
+    bytes,
+    cap: CODEX_PROJECT_DOC_MAX_BYTES,
+    pct: Number(((bytes / CODEX_PROJECT_DOC_MAX_BYTES) * 100).toFixed(2)),
+    overflow: bytes > CODEX_PROJECT_DOC_MAX_BYTES,
+    policyBlockEndsAtByte,
+  };
+}
+
+interface ParsedStamp {
+  readonly id: string;
+  readonly file: string;
+  readonly sha: string;
+  readonly section: string;
+}
+
+function parsePolicyStamps(agentsMdText: string | null): ParsedStamp[] {
+  if (typeof agentsMdText !== 'string') return [];
+  const begin = agentsMdText.indexOf(POLICY_BLOCK_BEGIN);
+  const end = begin === -1 ? -1 : agentsMdText.indexOf(POLICY_BLOCK_END, begin + POLICY_BLOCK_BEGIN.length);
+  if (begin === -1 || end === -1) return [];
+  const inner = agentsMdText.slice(begin + POLICY_BLOCK_BEGIN.length, end);
+  const matches = [...inner.matchAll(POLICY_STAMP)];
+  return matches.map((match, index) => ({
+    id: match[1]!,
+    file: match[2]!,
+    sha: match[3]!,
+    section: inner.slice((match.index ?? 0) + match[0].length, matches[index + 1]?.index ?? inner.length),
+  }));
+}
+
+function markerCount(text: string, marker: string): number {
+  let count = 0;
+  let offset = 0;
+  while (true) {
+    const found = text.indexOf(marker, offset);
+    if (found === -1) return count;
+    count += 1;
+    offset = found + marker.length;
+  }
+}
+
+function hasUnclaimedPolicyPrefix(text: string): boolean {
+  const begin = text.indexOf(POLICY_BLOCK_BEGIN);
+  const end = begin === -1 ? -1 : text.indexOf(POLICY_BLOCK_END, begin + POLICY_BLOCK_BEGIN.length);
+  if (begin === -1 || end === -1) return false;
+  const inner = text.slice(begin + POLICY_BLOCK_BEGIN.length, end);
+  const firstStamp = [...inner.matchAll(POLICY_STAMP)][0];
+  return inner.slice(0, firstStamp?.index ?? inner.length).trim().length > 0;
+}
+
+function hasPolicyStampOutsideFence(text: string): boolean {
+  const begin = text.indexOf(POLICY_BLOCK_BEGIN);
+  const end = begin === -1 ? -1 : text.indexOf(POLICY_BLOCK_END, begin + POLICY_BLOCK_BEGIN.length);
+  if (begin === -1 || end === -1) return [...text.matchAll(POLICY_STAMP)].length > 0;
+  const innerStart = begin + POLICY_BLOCK_BEGIN.length;
+  return [...text.matchAll(POLICY_STAMP)].some((match) => (match.index ?? -1) < innerStart || (match.index ?? -1) >= end);
+}
+
+function emittedBody(stamp: ParsedStamp, source: PolicySource): string | null {
+  const normalized = stamp.section.replace(/^\n+/, '').replace(/\n+$/, '');
+  const heading = `## ${source.heading}`;
+  if (!normalized.startsWith(`${heading}\n`)) return null;
+  const afterHeading = normalized.slice(heading.length).replace(/^\n+/, '');
+  const canonical = `\n\nCanonical: ${source.file}`;
+  if (!afterHeading.endsWith(canonical)) return null;
+  return normalizePolicyText(afterHeading.slice(0, -canonical.length));
+}
+
+export function detectPolicyDrift(
+  sourceFiles: ReadonlyMap<string, string | null>,
+  agentsMdText: string | null,
+  sources: readonly PolicySource[] = POLICY_SOURCES,
+): PolicyDriftResult {
+  const sourceFilesPresent = new Set(sources.map((source) => source.file))
+    .size > 0 && sources.some((source) => typeof sourceFiles.get(source.file) === 'string');
+  const extracted = extractPolicyBlocks(sourceFiles, sources);
+  const blockById = new Map(extracted.blocks.map((block) => [block.id, block]));
+  const stamps = parsePolicyStamps(agentsMdText);
+  const stampsById = new Map<string, ParsedStamp>();
+  const duplicateStamps: ParsedStamp[] = [];
+  for (const stamp of stamps) {
+    if (stampsById.has(stamp.id)) duplicateStamps.push(stamp);
+    else stampsById.set(stamp.id, stamp);
+  }
+
+  const findings: PolicyDriftFinding[] = [];
+  for (const source of sources) {
+    const block = blockById.get(source.id);
+    const stamp = stampsById.get(source.id);
+    if (!block) {
+      findings.push({ id: source.id, file: source.file, status: 'missing-anchor', expectedSha: null, actualSha: stamp?.sha ?? null });
+      continue;
+    }
+    if (!stamp) {
+      findings.push({ id: source.id, file: source.file, status: 'missing-stamp', expectedSha: block.sha, actualSha: null });
+      continue;
+    }
+    const body = emittedBody(stamp, source);
+    const stale = stamp.file !== source.file || stamp.sha !== block.sha || body === null || policyTextSha(body) !== block.sha;
+    findings.push({
+      id: source.id,
+      file: source.file,
+      status: stale ? 'stale' : 'ok',
+      expectedSha: block.sha,
+      actualSha: stamp.sha,
+    });
+  }
+
+  const sourceIds = new Set(sources.map((source) => source.id));
+  for (const stamp of [...stamps.filter((entry) => !sourceIds.has(entry.id)), ...duplicateStamps]) {
+    findings.push({ id: stamp.id, file: stamp.file, status: 'orphan-stamp', expectedSha: null, actualSha: stamp.sha });
+  }
+
+  if (typeof agentsMdText === 'string') {
+    const beginCount = markerCount(agentsMdText, POLICY_BLOCK_BEGIN);
+    const endCount = markerCount(agentsMdText, POLICY_BLOCK_END);
+    if (
+      beginCount > 1 ||
+      endCount > 1 ||
+      beginCount !== endCount ||
+      hasUnclaimedPolicyPrefix(agentsMdText) ||
+      hasPolicyStampOutsideFence(agentsMdText)
+    ) {
+      findings.push({ id: 'dz:policies', file: 'AGENTS.md', status: 'orphan-stamp', expectedSha: null, actualSha: null });
+    }
+  }
+
+  return { applicable: sourceFilesPresent, findings };
+}

package/src/codex-hooks-assets.ts

@@ -0,0 +1,291 @@
+/**
+ * The emitted Codex helper bodies (`crossrt-2-codex-hooks`, ADR-003 / ADR-004).
+ *
+ * Generated-code-as-a-string, following the `generateAgentdbWriter` precedent (`setup.ts`): the
+ * helpers are THIN and the logic lives in the package, because a changed helper body changes
+ * codex's `currentHash` and disarms the entry until it is re-trusted (MEASURED — M0 spike §4).
+ * Every byte in here is therefore a liability; keep them boring.
+ *
+ * ## The contracts, side by side
+ *
+ * |                | `dz-codex-veto.cjs` (PreToolUse)                    | `dz-codex-recall.cjs` (UserPromptSubmit) |
+ * |----------------|-----------------------------------------------------|------------------------------------------|
+ * | Polarity       | mode-driven on POLICY (default `warn` ⇒ exit 0)      | **never-block, always**                  |
+ * | Keys on        | presence of `tool_input.command` (AM-8)              | `payload.prompt`                          |
+ * | Activation     | nearest `.dz` walking up from `payload.cwd` (AM-25)  | same                                      |
+ * | Our own failure| exit 0, silent, note to `helper-errors.jsonl`        | exit 0, empty stdout, no write (AM-9)     |
+ *
+ * `.git` is **not** an activation marker (AM-25): a user-global hook that treats "any git checkout"
+ * as opted-in reaches every repository on the machine, including trees nobody pointed at dz.
+ *
+ * The self-failure note goes to `$CODEX_HOME/dz-hooks/helper-errors.jsonl` (AM-33), never into a
+ * project — writing it into `<project>/.dz/` would CREATE a `.dz/` in a foreign repo, which is the
+ * exact thing the activation rule exists to prevent.
+ *
+ * A `UserPromptSubmit` hook that exits 2 **blocks the user's turn**, so the recall helper has no
+ * path to a non-zero exit at all.
+ *
+ * @packageDocumentation
+ */
+
+import { DZ_HOOK_HELPER_VERSION } from './codex-hooks.js';
+
+/** Shared prologue: payload read, project-root walk, never-throw error note. */
+function preamble(): string {
+  return `#!/usr/bin/env node
+// GENERATED by @dzhechkov/harness-core — dz-hook-helper-version: ${DZ_HOOK_HELPER_VERSION}
+// Do not edit: dz rewrites this file, and any edit disarms the hook until it is re-trusted.
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+
+const HELPER_VERSION = ${DZ_HOOK_HELPER_VERSION};
+const CODEX_HOME = process.env.CODEX_HOME || path.join(require('node:os').homedir(), '.codex');
+const ERROR_LOG = path.join(CODEX_HOME, 'dz-hooks', 'helper-errors.jsonl');
+
+/**
+ * Append one line to the helper NOTES log. Never throws. Never writes into a project.
+ *
+ * Carries BOTH self-failures and policy WARNINGS. MEASURED (M9 live probe, 2026-08-19): codex
+ * surfaces a hook's stderr in the transcript ONLY when the hook exits 2 — an exit-0 hook's stderr is
+ * swallowed. So a warn that lived only on stderr would be unobservable, and "the guard is live but
+ * not blocking" (G-J) would be unprovable. This file is where it is observable.
+ */
+function note(stage, err, extra) {
+  try {
+    fs.appendFileSync(
+      ERROR_LOG,
+      JSON.stringify(Object.assign(
+        { ts: new Date().toISOString(), helper: HELPER, helperVersion: HELPER_VERSION, stage, message: String((err && err.message) || err || '') },
+        extra || {},
+      )) + '\\n',
+    );
+  } catch (_) { /* the note is best-effort; it must never become the failure */ }
+}
+
+function readPayload() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch (err) {
+    note('read-payload', err);
+    return null;
+  }
+}
+
+/**
+ * Walk UP from cwd to the nearest directory containing a \`.dz\` DIRECTORY.
+ * \`.git\` is deliberately not a marker (AM-25). No root => the helper is inert.
+ */
+function findProjectRoot(startDir) {
+  try {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < 64; i += 1) {
+      try {
+        if (fs.statSync(path.join(dir, '.dz')).isDirectory()) return dir;
+      } catch (_) { /* not here; keep walking */ }
+      const parent = path.dirname(dir);
+      if (parent === dir) return null;
+      dir = parent;
+    }
+    return null;
+  } catch (err) {
+    note('find-root', err);
+    return null;
+  }
+}
+
+function readProjectConfig(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, '.dz', 'config.json'), 'utf8'));
+  } catch (_) {
+    return null; // absent or unreadable config is the DEFAULT case, not an error
+  }
+}
+
+/** Load a built module from the project's own harness-core, or null. Never throws. */
+function loadCore(root, fileName, predicate) {
+  const candidates = [
+    path.join(root, 'node_modules', '@dzhechkov', 'harness-core', 'dist', fileName),
+    path.join(root, 'packages', '@dzhechkov', 'harness-core', 'dist', fileName),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (!fs.existsSync(candidate)) continue;
+      const mod = require(candidate);
+      if (predicate(mod)) return mod;
+    } catch (err) {
+      note('load-core:' + fileName, err);
+    }
+  }
+  return null;
+}
+`;
+}
+
+/**
+ * The PreToolUse veto helper.
+ *
+ * Fail-OPEN on OUR failure, mode-driven on a POLICY hit. Exit 2 only when the project explicitly
+ * opted in — the shipped default warns and returns 0 (AM-24 / G-J).
+ */
+export function generateCodexVetoHelper(): string {
+  return `${preamble().replace('const HELPER_VERSION', "const HELPER = 'dz-codex-veto';\nconst HELPER_VERSION")}
+function main() {
+  const payload = readPayload();
+  if (payload === null) return 0;
+
+  // AM-8: key on the PRESENCE of a command, never on tool_name equality. MEASURED payload
+  // (M0 spike): { tool_name: 'Bash', tool_input: { command: "…" }, cwd: "…" }.
+  const input = payload.tool_input;
+  const command = input && typeof input === 'object' ? input.command : undefined;
+  if (typeof command !== 'string' || command === '') return 0;
+
+  const cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : process.env.PWD || process.cwd();
+  const root = findProjectRoot(cwd);
+  if (root === null) return 0; // inert outside an opted-in dz project: no decision, no output, no write
+
+  const policy = loadCore(root, 'shell-veto-policy.js', (m) => typeof m.vetoShellCommand === 'function');
+  if (policy === null) return 0; // no logic available => allow (never block on OUR failure)
+
+  let hit = null;
+  let mode = 'warn';
+  try {
+    hit = policy.vetoShellCommand(command);
+    mode = policy.resolveVetoMode(readProjectConfig(root));
+  } catch (err) {
+    note('policy', err);
+    return 0;
+  }
+  if (hit === null || mode === 'off') return 0;
+
+  if (mode === 'block') {
+    process.stderr.write('DZ-VETO: ' + hit.rule + ' — ' + hit.reason + ' — command: ' + command + '\\n');
+    note('veto-block', null, { marker: 'DZ-VETO', rule: hit.rule, command: command, mode: mode });
+    return 2;
+  }
+  const warnLine = 'DZ-VETO-WARN: ' + hit.rule + ' — ' + hit.reason + ' — command: ' + command;
+  process.stderr.write(warnLine + '\\n');
+  // Codex swallows an exit-0 hook's stderr (MEASURED), so the warn is ALSO recorded where it can be
+  // read back — otherwise the shipped default would be live-but-unobservable.
+  note('veto-warn', null, { marker: 'DZ-VETO-WARN', rule: hit.rule, command: command, mode: mode });
+  return 0;
+}
+
+let code = 0;
+try {
+  code = main();
+} catch (err) {
+  note('main', err);
+  code = 0;
+}
+process.exit(code === 2 ? 2 : 0);
+`;
+}
+
+/**
+ * The UserPromptSubmit recall helper.
+ *
+ * NEVER blocks and NEVER exits non-zero (AM-9). Silence is its correct output when nothing is
+ * relevant, which is exactly why the acceptance canary is a FORCED HIT plus a removed-hook twin
+ * (AM-4) — a dead hook and a correctly-silent one are indistinguishable from the outside.
+ */
+export function generateCodexRecallHelper(): string {
+  return `${preamble().replace('const HELPER_VERSION', "const HELPER = 'dz-codex-recall';\nconst HELPER_VERSION")}
+const net = require('node:net');
+const DAEMON_TIMEOUT_MS = 2000;
+
+/** Ask the project's embed daemon for candidates. Resolves undefined on ANY problem. */
+function askDaemon(root, prompt) {
+  return new Promise((resolve) => {
+    const socket = process.env.DZ_EMBED_SOCKET || path.join(root, '.dz', 'embed.sock');
+    let exists = false;
+    try { exists = fs.existsSync(socket); } catch (_) { exists = false; }
+    if (!exists) return resolve(undefined);
+    let settled = false;
+    const done = (v) => {
+      if (settled) return;
+      settled = true;
+      try { sock.destroy(); } catch (_) { /* ignore */ }
+      resolve(v);
+    };
+    const sock = net.connect(socket);
+    const timer = setTimeout(() => done(undefined), DAEMON_TIMEOUT_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+    let buf = '';
+    sock.on('connect', () => sock.write(JSON.stringify({ op: 'recall', prompt: prompt, limit: 8 }) + '\\n'));
+    sock.on('data', (chunk) => {
+      buf += chunk.toString('utf8');
+      const nl = buf.indexOf('\\n');
+      if (nl === -1) return;
+      clearTimeout(timer);
+      let msg = null;
+      try { msg = JSON.parse(buf.slice(0, nl)); } catch (_) { msg = null; }
+      done(msg && Array.isArray(msg.hits) ? msg.hits : undefined);
+    });
+    sock.on('error', () => { clearTimeout(timer); done(undefined); });
+  });
+}
+
+async function main() {
+  const payload = readPayload();
+  if (payload === null) return;
+  const prompt = typeof payload.prompt === 'string' ? payload.prompt : '';
+  if (prompt.trim() === '') return;
+
+  const cwd = typeof payload.cwd === 'string' && payload.cwd !== '' ? payload.cwd : process.env.PWD || process.cwd();
+  const root = findProjectRoot(cwd);
+  if (root === null) return; // inert outside an opted-in dz project
+
+  const policy = loadCore(root, 'recall-hook-policy.js', (m) => typeof m.selectHookHits === 'function');
+  if (policy === null) return;
+
+  const candidates = await askDaemon(root, prompt);
+  if (!candidates || candidates.length === 0) return; // daemon dead or nothing relevant: silence
+
+  let selection = null;
+  try {
+    selection = policy.selectHookHits(prompt, candidates);
+  } catch (err) {
+    note('select-hits', err);
+    return;
+  }
+  if (!selection || !Array.isArray(selection.hits) || selection.hits.length === 0) return;
+
+  let context = '';
+  try { context = policy.renderHookContext(selection); } catch (err) { note('render', err); return; }
+  if (context === '') return; // empty context => print NOTHING (an empty block is noise)
+
+  process.stdout.write(
+    JSON.stringify({ hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: context } }) + '\\n',
+  );
+
+  // The usage row carries runtime: 'codex' (ADR-003 §3) through the SHARED chained appender in
+  // harness-core — ONE writer implementation, two callers (AM-6/AM-7). Written AFTER stdout so a
+  // logging failure can never cost the user their injection.
+  const usage = loadCore(root, 'recall-usage.js', (m) => typeof m.appendRecallUsage === 'function');
+  if (usage === null) return;
+  try {
+    usage.appendRecallUsage({
+      projectRoot: root,
+      runtime: 'codex',
+      query: prompt,
+      runId: typeof payload.session_id === 'string' ? payload.session_id : undefined,
+      hits: selection.hits.map((h) => ({ dzId: h.dzId, score: h.score })),
+    });
+  } catch (err) {
+    note('append-usage', err);
+  }
+}
+
+main()
+  .catch((err) => note('main', err))
+  .finally(() => process.exit(0)); // a UserPromptSubmit exit 2 BLOCKS the user's turn
+`;
+}
+
+/** Both helper bodies, keyed by the file they are written to. */
+export function generateCodexHelpers(): Readonly<Record<'veto' | 'recall', string>> {
+  return { veto: generateCodexVetoHelper(), recall: generateCodexRecallHelper() };
+}