@dzhechkov/harness-core 0.4.5 → 0.5.1

package/src/operations.ts

@@ -6,8 +6,36 @@
  * @packageDocumentation
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildManagedEntries,
+  buildCodexHookManifest,
+  codexHooksPaths,
+  diffCodexHooks,
+  parseCodexHookManifest,
+  planCodexHooks,
+  removeCodexHooks,
+  selectOwnHookMetadata,
+  upsertTrustBlock,
+  type CodexHooksPaths,
+  type HooksListHookMetadata,
+  type ManagedEntry,
+} from './codex-hooks.js';
+import { generateCodexHelpers } from './codex-hooks-assets.js';
+import {
+  classifyVetoProbe,
+  isReadyVerdict,
+  verifyExitCode,
+  type CodexHookTrustStatus,
+  type VetoProbeEvidence,
+  type VetoProbeResult,
+} from './codex-hooks-verify.js';
 
 import { AGENTS_MD_PATH } from '@dzhechkov/adapter-agents-md';
 import { claudeAdapter } from '@dzhechkov/adapter-claude';
@@ -19,14 +47,27 @@ import { OPENCLAUDE_SKILLS_ROOT } from '@dzhechkov/adapter-openclaude';
 import { COPILOT_INSTRUCTIONS_ROOT } from '@dzhechkov/adapter-copilot';
 import { CURSOR_RULES_ROOT } from '@dzhechkov/adapter-cursor';
 import { WINDSURF_RULES_ROOT } from '@dzhechkov/adapter-windsurf';
-import { mergeAgentsMd, mergeGeminiMd, renderAgentsMdSection } from '@dzhechkov/core';
+import { AGENTS_MD_BLOCK_BEGIN, mergeAgentsMd, mergeGeminiMd, mergePolicyBlock, renderAgentsMdSection } from '@dzhechkov/core';
 import type { CanonicalSkill, EmitResult, SkillAsset } from '@dzhechkov/core';
 import { computeRiskScore } from './risk-scoring.js';
 
 import { applyEmitResult } from './apply.js';
-import { discoverSkillIds, loadSkillFromDir } from './skills.js';
+import { describeSkillLoadFailure, discoverSkillIds, loadSkillFromDir } from './skills.js';
+import type { SkillApplyFailure, SkillLoadFailure } from './skills.js';
 import { TARGETS } from './targets.js';
 import type { TargetName } from './targets.js';
+import {
+  AGENTS_MD_BUDGET_WARN_FRACTION,
+  CODEX_PROJECT_DOC_MAX_BYTES,
+  POLICY_SOURCES,
+  detectPolicyDrift,
+  extractPolicyBlocks,
+  measureAgentsMdBudget,
+  renderPolicySections,
+  type AgentsMdBudget,
+  type PolicyDriftFinding,
+  type PolicySource,
+} from './agents-policy.js';
 
 // ---------------------------------------------------------------------------
 // init — compile a skills directory for a target and write it (additively)
@@ -67,6 +108,27 @@ export interface InitReport {
    * installing fewer skills than the selection asked for.
    */
   readonly missing: string[];
+  /**
+   * Skill directories that could not be LOADED (unparseable `SKILL.md`, unreadable
+   * file, schema rejection). Additive and always present — empty when nothing failed.
+   *
+   * Before feature dz-cli-defects a single unloadable skill threw out of the whole
+   * loop, so `dz init`/`dz install` reported nothing at all. Skipping without a record
+   * would only trade a loud failure for a silent one; this field is the record.
+   */
+  readonly failures: readonly SkillLoadFailure[];
+  /**
+   * Skills that LOADED cleanly but could not be compiled or written (fix round 1,
+   * QE F4). Kept separate from {@link InitReport.failures} because the two name
+   * different subjects: a load failure accuses the source `SKILL.md`, an apply
+   * failure accuses the target tree. Merging them made `EEXIST: mkdir …` print under
+   * the header "unparseable SKILL.md" against a perfectly valid file.
+   *
+   * Additive and always present — empty when nothing failed. Only `runInit` can
+   * populate it; the single-file targets render in memory and write once, outside
+   * any per-skill loop.
+   */
+  readonly applyFailures: readonly SkillApplyFailure[];
 }
 
 // ---------------------------------------------------------------------------
@@ -212,6 +274,40 @@ interface SingleFileMdConfig {
   readonly lossyWarning: string;
 }
 
+export interface ManagedMarkdownWriteReport {
+  readonly filePath: string;
+  readonly changed: boolean;
+  readonly bytes: number;
+  /** The complete candidate bytes, returned so callers can run pure post-merge checks. */
+  readonly content: string;
+}
+
+/**
+ * The one read/merge/write path for every root managed-Markdown projection.
+ * `write:false` is check-only and never creates a directory or target file.
+ * A max-byte refusal happens before mkdir/write, leaving the target byte-identical.
+ */
+export function writeManagedMarkdown(
+  projectRoot: string,
+  sections: readonly string[],
+  config: Pick<SingleFileMdConfig, 'filePath' | 'merge'>,
+  options: { readonly write?: boolean; readonly maxBytes?: number } = {},
+): ManagedMarkdownWriteReport {
+  const fileAbs = join(projectRoot, config.filePath);
+  const existing = existsSync(fileAbs) ? readFileSync(fileAbs, 'utf-8') : null;
+  const merged = config.merge(existing, sections);
+  const bytes = Buffer.byteLength(merged, 'utf8');
+  if (options.maxBytes !== undefined && bytes > options.maxBytes) {
+    throw new Error(`${config.filePath} policy emit exceeds the ${options.maxBytes.toLocaleString('en-US')} byte Codex project-document budget (${bytes.toLocaleString('en-US')} bytes); target left unchanged`);
+  }
+  const changed = merged !== existing;
+  if (options.write !== false && changed) {
+    mkdirSync(dirname(fileAbs), { recursive: true });
+    writeFileSync(fileAbs, merged, 'utf-8');
+  }
+  return { filePath: config.filePath, changed, bytes, content: merged };
+}
+
 /**
  * The lossy warning surfaced ONCE per agents-md install (not once per skill):
  * agents-md flattens every selected skill into plain-Markdown sections of a
@@ -265,24 +361,25 @@ function runInitSingleFileMd(options: AgentsMdInitOptions, config: SingleFileMdC
   }
   const missing = selection === undefined ? [] : selection.filter((id) => !discovered.has(id));
 
-  const sections = picked.map(({ id, skillsDir }) =>
-    renderAgentsMdSection(loadSkillFromDir(skillsDir, id)),
-  );
-
-  const fileAbs = join(options.projectRoot, config.filePath);
-  const existing = existsSync(fileAbs) ? readFileSync(fileAbs, 'utf-8') : null;
-  const merged = config.merge(existing, sections);
-  const changed = merged !== existing;
-
-  if (picked.length > 0 && changed) {
-    mkdirSync(dirname(fileAbs), { recursive: true });
-    writeFileSync(fileAbs, merged, 'utf-8');
+  // Skip-and-collect: one unloadable skill must not discard the whole aggregation.
+  const failures: SkillLoadFailure[] = [];
+  const loaded: { id: string; section: string }[] = [];
+  for (const { id, skillsDir } of picked) {
+    try {
+      loaded.push({ id, section: renderAgentsMdSection(loadSkillFromDir(skillsDir, id)) });
+    } catch (error) {
+      failures.push(describeSkillLoadFailure(skillsDir, id, error));
+    }
   }
+  const sections = loaded.map((entry) => entry.section);
+
+  const managed = writeManagedMarkdown(options.projectRoot, sections, config, { write: loaded.length > 0 });
+  const changed = managed.changed;
 
   // Report the shared root file as written/skipped on the FIRST contributing
   // skill only, so callers that SUM per-skill file counts don't count the one
   // shared file N times. The lossy warning is surfaced ONCE, on that same skill.
-  const skills: InitSkillResult[] = picked.map(({ id }, index) => {
+  const skills: InitSkillResult[] = loaded.map(({ id }, index) => {
     const owns = index === 0;
     return {
       id,
@@ -292,7 +389,9 @@ function runInitSingleFileMd(options: AgentsMdInitOptions, config: SingleFileMdC
     };
   });
 
-  return { target: config.target, skillsDir: joinedDir, projectRoot: options.projectRoot, skills, missing };
+  // No apply failures are possible here: the single write is outside every per-skill
+  // loop, so a write error propagates as itself rather than being attributed to a skill.
+  return { target: config.target, skillsDir: joinedDir, projectRoot: options.projectRoot, skills, missing, failures, applyFailures: [] };
 }
 
 /**
@@ -324,6 +423,114 @@ export function runInitGeminiMd(options: AgentsMdInitOptions): InitReport {
   });
 }
 
+export interface AgentsPolicySyncOptions {
+  readonly projectRoot: string;
+  /** Verify only. No directory or file is created, even when AGENTS.md is absent. */
+  readonly check?: boolean;
+  /** Test/extension seam; production uses the fixed ordered registry. */
+  readonly sources?: readonly PolicySource[];
+}
+
+export interface AgentsPolicySyncReport {
+  readonly filePath: 'AGENTS.md';
+  /** In check mode: the target would change. In write mode: the target did change. */
+  readonly changed: boolean;
+  readonly written: boolean;
+  readonly inSync: boolean;
+  readonly blocks: readonly { readonly id: string; readonly sha: string }[];
+  readonly missing: readonly string[];
+  readonly drift: readonly PolicyDriftFinding[];
+  readonly budget: AgentsMdBudget;
+  readonly warnings: readonly string[];
+}
+
+/**
+ * Refresh or verify the policy fence in root AGENTS.md. Source reads are an
+ * explicit I/O shell around the pure agents-policy module; missing/unreadable
+ * input returns inconclusive evidence and never writes a partial projection.
+ */
+export function runSyncAgentsPolicy(options: AgentsPolicySyncOptions): AgentsPolicySyncReport {
+  const sources = options.sources ?? POLICY_SOURCES;
+  const sourceFiles = new Map<string, string | null>();
+  for (const file of new Set(sources.map((source) => source.file))) {
+    try {
+      sourceFiles.set(file, readFileSync(join(options.projectRoot, file), 'utf8'));
+    } catch {
+      sourceFiles.set(file, null);
+    }
+  }
+  const agentsPath = join(options.projectRoot, AGENTS_MD_PATH);
+  let currentAgents: string | null = null;
+  try { currentAgents = readFileSync(agentsPath, 'utf8'); } catch { /* absent target is a normal first sync */ }
+
+  const extracted = extractPolicyBlocks(sourceFiles, sources);
+  if (extracted.missing.length > 0) {
+    const drift = detectPolicyDrift(sourceFiles, currentAgents, sources);
+    return {
+      filePath: AGENTS_MD_PATH,
+      changed: true,
+      written: false,
+      inSync: false,
+      blocks: extracted.blocks.map(({ id, sha }) => ({ id, sha })),
+      missing: extracted.missing,
+      drift: drift.findings,
+      budget: measureAgentsMdBudget(currentAgents ?? ''),
+      warnings: [`policy source evidence is incomplete: ${extracted.missing.join(', ')}`],
+    };
+  }
+
+  const currentDrift = detectPolicyDrift(sourceFiles, currentAgents, sources);
+  const malformedOuterFence = currentDrift.findings.some((finding) => finding.id === 'dz:policies');
+  if (options.check !== true && malformedOuterFence) {
+    return {
+      filePath: AGENTS_MD_PATH,
+      changed: true,
+      written: false,
+      inSync: false,
+      blocks: extracted.blocks.map(({ id, sha }) => ({ id, sha })),
+      missing: [],
+      drift: currentDrift.findings,
+      budget: measureAgentsMdBudget(currentAgents ?? ''),
+      warnings: ['refusing to rewrite malformed or duplicate dz:policies fence markers; repair their cardinality first'],
+    };
+  }
+
+  const sections = renderPolicySections(extracted.blocks, sources);
+  const rendered = sections.join('\n\n');
+  const claudeOnlyTokens = ['Workflow({', 'subagent_type', 'mcp__', '.claude/agents/v3/'];
+  const leaked = claudeOnlyTokens.find((token) => rendered.includes(token));
+  if (leaked !== undefined) throw new Error(`AGENTS.md policy block contains Claude-only token ${JSON.stringify(leaked)}; target left unchanged`);
+
+  const managed = writeManagedMarkdown(
+    options.projectRoot,
+    sections,
+    { filePath: AGENTS_MD_PATH, merge: mergePolicyBlock },
+    { write: options.check !== true, maxBytes: CODEX_PROJECT_DOC_MAX_BYTES },
+  );
+  const budget = measureAgentsMdBudget(managed.content);
+  const drift = detectPolicyDrift(sourceFiles, options.check === true ? currentAgents : managed.content, sources);
+  const warnings: string[] = [];
+  if (budget.bytes >= budget.cap * AGENTS_MD_BUDGET_WARN_FRACTION) {
+    warnings.push(`AGENTS.md uses ${budget.pct}% of the measured ${budget.cap.toLocaleString('en-US')} byte Codex project-document budget`);
+  }
+  const skillsBegin = managed.content.indexOf(AGENTS_MD_BLOCK_BEGIN);
+  if (skillsBegin !== -1 && budget.policyBlockEndsAtByte > Buffer.byteLength(managed.content.slice(0, skillsBegin), 'utf8')) {
+    warnings.push('policy fence must end before the skills fence because Codex truncates the tail');
+  }
+  const nonOk = drift.findings.filter((finding) => finding.status !== 'ok');
+  return {
+    filePath: AGENTS_MD_PATH,
+    changed: managed.changed,
+    written: options.check !== true && managed.changed,
+    inSync: options.check === true ? !managed.changed && nonOk.length === 0 : nonOk.length === 0,
+    blocks: extracted.blocks.map(({ id, sha }) => ({ id, sha })),
+    missing: [],
+    drift: drift.findings,
+    budget,
+    warnings,
+  };
+}
+
 /** Compile every skill in `skillsDir` for `target` and apply it under `projectRoot`. */
 export async function runInit(options: InitOptions): Promise<InitReport> {
   // agents-md is a flattening single-file target — aggregate all selected skills
@@ -355,19 +562,41 @@ export async function runInit(options: InitOptions): Promise<InitReport> {
   const missing = selection === undefined
     ? []
     : selection.filter((id) => !discovered.includes(id));
+  // Skip-and-collect (D1): one unparseable SKILL.md must not discard the whole install.
+  // Same shape as `runVerify`'s long-standing per-id try/catch below.
+  //
+  // The `try` is scoped to `loadSkillFromDir` ALONE (ADR-001 §Decision part 2, restored
+  // in fix round 1 / QE F4). It used to wrap compile + apply too, so an EEXIST from
+  // `mkdir` was described by `describeSkillLoadFailure` and printed under the
+  // "unparseable SKILL.md" header, naming the source file — which was valid. Compile
+  // and write failures are a SECOND kind with their own subject and their own header;
+  // they are collected, not thrown, so one unwritable target directory still cannot
+  // discard the rest of the install.
+  const failures: SkillLoadFailure[] = [];
+  const applyFailures: SkillApplyFailure[] = [];
   for (const id of ids) {
-    const skill = loadSkillFromDir(options.skillsDir, id);
-    let emit = await adapter.compile(skill, { targetRoot: options.projectRoot });
-    if (options.enrich === true) {
-      emit = enrichEmitForTarget(emit, options.target, id, skill);
+    let skill;
+    try {
+      skill = loadSkillFromDir(options.skillsDir, id);
+    } catch (error) {
+      failures.push(describeSkillLoadFailure(options.skillsDir, id, error));
+      continue;
+    }
+    try {
+      let emit = await adapter.compile(skill, { targetRoot: options.projectRoot });
+      if (options.enrich === true) {
+        emit = enrichEmitForTarget(emit, options.target, id, skill);
+      }
+      const applied = applyEmitResult(emit, {
+        targetRoot: options.projectRoot,
+        force: options.force === true,
+      });
+      skills.push({ id, written: applied.written, skipped: applied.skipped, warnings: [...emit.warnings] });
+    } catch (error) {
+      applyFailures.push({ id, reason: error instanceof Error ? error.message : String(error) });
     }
-    const applied = applyEmitResult(emit, {
-      targetRoot: options.projectRoot,
-      force: options.force === true,
-    });
-    skills.push({ id, written: applied.written, skipped: applied.skipped, warnings: [...emit.warnings] });
   }
-  return { target: options.target, skillsDir: options.skillsDir, projectRoot: options.projectRoot, skills, missing };
+  return { target: options.target, skillsDir: options.skillsDir, projectRoot: options.projectRoot, skills, missing, failures, applyFailures };
 }
 
 // ---------------------------------------------------------------------------
@@ -457,15 +686,28 @@ export interface SyncReport {
   readonly dryRun: boolean;
   readonly skills: SyncSkillResult[];
   readonly summary: { total: number; inSync: number; missing: number; drift: number };
+  /**
+   * Canonical skill directories that could not be LOADED. Additive, always present.
+   * See {@link InitReport.failures} — same contract, same reason.
+   */
+  readonly failures: readonly SkillLoadFailure[];
 }
 
 /** Compare each canonical skill (compiled for Claude Code) to the legacy tree. */
 export async function runSync(options: SyncOptions): Promise<SyncReport> {
   const dirs = options.canonicalDirs ?? (options.canonicalDir ? [options.canonicalDir] : []);
   const skills: SyncSkillResult[] = [];
+  // Skip-and-collect (D1): a broken canonical skill must not hide every other pack.
+  const failures: SkillLoadFailure[] = [];
   for (const canonicalDir of dirs) {
     for (const id of discoverSkillIds(canonicalDir)) {
-    const skill = loadSkillFromDir(canonicalDir, id);
+    let skill;
+    try {
+      skill = loadSkillFromDir(canonicalDir, id);
+    } catch (error) {
+      failures.push(describeSkillLoadFailure(canonicalDir, id, error));
+      continue;
+    }
     const emit = await claudeAdapter.compile(skill, { targetRoot: options.projectRoot });
 
     let differ = false;
@@ -490,6 +732,7 @@ export async function runSync(options: SyncOptions): Promise<SyncReport> {
   return {
     dryRun: options.dryRun === true,
     skills,
+    failures,
     summary: {
       total: skills.length,
       inSync: skills.filter((skill) => skill.status === 'in-sync').length,
@@ -738,6 +981,38 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
       });
     }
   } catch { /* settings absent/unreadable — covered by other checks */ }
+  // CODEX APPLY-LEG (AM-19, fact CORRECTED by AM-30). This block is deliberately OUTSIDE the
+  // `existsSync(writerPath)` guard below. MEASURED: the Claude apply-leg check has THREE
+  // preconditions, not two — the `.claude/settings.json` text check is NESTED inside
+  // `if (existsSync(join(root,'.dz','agentdb-writer.mjs')))`. A Codex-only machine has no writer
+  // file and no `.claude/settings.json`, so a Codex branch added *in place* would report nothing at
+  // all — reproducing the exact 19-day dark-leg shape this check exists to kill.
+  //
+  // A WIRED-BUT-SILENT leg is an explicit non-OK row, never an absent one.
+  try {
+    const { codexHooksPaths: codexPaths, parseCodexHookManifest: parseCodexManifest } = await import('./codex-hooks.js');
+    const codexHome = process.env['CODEX_HOME'] ?? join(homedir(), '.codex');
+    const manifestPath = codexPaths(codexHome).manifest;
+    if (existsSync(manifestPath)) {
+      const manifest = parseCodexManifest(readFileSync(manifestPath, 'utf-8'));
+      const claimsRecall = manifest?.entries.some((e) => e.id === 'codex-recall') === true;
+      if (claimsRecall) {
+        const usageLog = join(root, '.dz', 'recall-usage.jsonl');
+        const { newest, hasCodexRow } = newestRecallUsageRuntime(usageLog);
+        const fresh = newest !== undefined && Date.now() - Date.parse(newest) < 14 * 24 * 60 * 60 * 1000;
+        checks.push({
+          name: 'codex apply-leg (recall hook)',
+          ok: hasCodexRow && fresh,
+          detail: hasCodexRow
+            ? fresh
+              ? `codex recall rows present, newest ${newest}`
+              : `codex recall hook is WIRED but SILENT: newest recall-usage row is ${String(newest)} — the entry may have lost hook trust (re-run dz hooks-sync --target codex --verify)`
+            : 'codex recall hook is WIRED but has NEVER written a row — a dead leg looks exactly like a correctly-silent one, so this is reported non-OK until one lands',
+        });
+      }
+    }
+  } catch { /* doctor never throws on a diagnostic */ }
+
   const writerPath = join(root, '.dz', 'agentdb-writer.mjs');
   if (existsSync(writerPath)) {
     const { writerVersionOf, AGENTDB_WRITER_VERSION } = await import('./setup.js');
@@ -832,3 +1107,820 @@ export async function runDoctor(options: { projectRoot: string }): Promise<Docto
 
   return { node: process.version, checks, ok: checks.every((check) => check.ok) };
 }
+
+/* ========================================================================== */
+/* Codex hook install (`crossrt-2-codex-hooks`, M7 · ADR-001/ADR-002)         */
+/* ========================================================================== */
+
+export interface CodexHooksSyncOptions {
+  /** Defaults to `$CODEX_HOME`, then `~/.codex`. Every automated probe passes a temp dir (AM-11). */
+  readonly codexHome?: string;
+  /** Verify only. NOTHING is created — not even the helper directory. */
+  readonly check?: boolean;
+  /** Remove manifest-attributed entries and stop. */
+  readonly remove?: boolean;
+  /** Absolute interpreter for the emitted command. Defaults to `process.execPath` (AM-32). */
+  readonly nodePath?: string;
+/**
+   * Test seam: `false` skips EVERY live runtime call — the `$SHELL -lc` liveness self-probe AND the
+   * `hooks/list` trust query. Both spawn processes (the RPC drives a real `codex app-server`), which
+   * is seconds per install; a test that installs six times to check backup pruning is measuring
+   * pruning, not the runtime. With it off, `trust` is reported `'unknown'` rather than assumed.
+   */
+  readonly liveness?: boolean;
+  /** Test seam. Production probes the real binary. */
+  readonly codexVersion?: string | null;
+  readonly now?: string;
+  /**
+   * Run the LIVE veto probe (ADR-002). Default `true` whenever live calls are enabled — a report
+   * that says `ready` without one is the CRITICAL finding this option exists to close.
+   * `false` (the CLI's `--no-verify`) never yields a success word and never exits 0.
+   */
+  readonly verify?: boolean;
+  /**
+   * MUTUAL EXCLUSION SEAM (feature qe-bridge-claude, round-2 CRITICAL C2). The caller wraps ONLY the
+   * registry read-plan-write transaction — the part where two dz processes can lose each other's
+   * entries. It must NOT span the live probes: those spawn a real `codex app-server` turn and can
+   * block for minutes, far past any advisory lock's stale threshold, at which point a waiter is
+   * entitled to break the lock and the holder becomes a liar. Default: run unwrapped.
+   */
+  readonly criticalSection?: <T>(fn: () => T) => T;
+  /** The project whose consent the probe runs under (`--project`). See {@link runCodexVetoProbe}. */
+  readonly project?: string;
+  /** Pinned probe model id; defaults to `DZ_CODEX_PROBE_MODEL`, then codex's own configured model. */
+  readonly probeModel?: string;
+  /** Test seam: replace the live probe. Production runs {@link runCodexVetoProbe}. */
+  readonly probe?: (options: CodexVetoProbeOptions) => CodexVetoProbeRun;
+}
+
+export interface CodexHooksSyncReport {
+  readonly codexHome: string;
+  readonly registryPath: string;
+  /** Both managed entries are present in the file (recomputed from the FILE, not the manifest). */
+  readonly installed: boolean;
+  /** The emitted command actually RUNS through `$SHELL -lc`. A hook that cannot execute is not armed. */
+  readonly executable: boolean;
+  readonly written: boolean;
+  readonly removed: number;
+  readonly foreignPreserved: number;
+  readonly unattributable: number;
+  readonly drift: readonly string[];
+  readonly trust: 'trusted' | 'trust-pending' | 'unknown';
+  readonly codexVersion: string | null;
+  /** The live veto probe's verdict. `null` ⇒ no probe ran (`--no-verify`, or the test seam). */
+  readonly verify: VetoProbeResult | null;
+  /** A live, non-bypassed probe ran AND witnessed our block. The only route to a success word. */
+  readonly verified: boolean;
+  /**
+   * armed ∧ trusted, PROVEN — installed + executable + trusted + a witnessed live block. This is
+   * the single predicate the CLI's `ready` line is allowed to read (AM-17 / G-G).
+   */
+  readonly ready: boolean;
+  /** 0 = armed+trusted · 1 = not armed / drift / refusal · 3 = inconclusive. */
+  readonly exitCode: 0 | 1 | 3;
+  readonly warnings: readonly string[];
+  readonly errors: readonly string[];
+  /** Written paths, for the declared-write-set test. */
+  readonly writes: readonly string[];
+}
+
+/** The one place that decides WHERE `hooks.json` lives. Exported (feature qe-bridge-claude) so the
+ * CLI can take the `codex-hooks` advisory lock BESIDE that registry — a lock in this repo's `.dz/`
+ * would not serialize a writer operating from another checkout. */
+export function resolveCodexHome(explicit: string | undefined): string {
+  if (typeof explicit === 'string' && explicit !== '') return explicit;
+  const env = process.env['CODEX_HOME'];
+  if (typeof env === 'string' && env !== '') return env;
+  return join(homedir(), '.codex');
+}
+
+/** `codex --version` → `codex-cli 0.147.0`. `null` when the binary is absent or silent. */
+function probeCodexVersion(): string | null {
+  try {
+    const out = execFileSync('codex', ['--version'], { encoding: 'utf8', timeout: 15_000, stdio: ['ignore', 'pipe', 'ignore'] });
+    const trimmed = out.trim();
+    return trimmed === '' ? null : trimmed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Run the emitted command THE WAY THE RUNTIME WILL — through `$SHELL -lc` (AM-32 / G-L).
+ *
+ * MEASURED: the codex hook runner spawns via `$SHELL -lc`, and under nvm/asdf/volta a
+ * non-interactive login shell frequently lacks `node`. The helper then exits **127**, which the
+ * runtime reads as **ALLOW** — a blocking guard that is silently dead in the fail-open direction,
+ * with the helper's own self-failure note unable to fire because the process never started.
+ * Grading on file presence would call that "installed".
+ */
+export function probeHookLiveness(command: string, payload: string): { readonly status: number | null; readonly stderr: string } {
+  const shell = process.env['SHELL'] ?? '/bin/sh';
+  try {
+    const res = spawnSync(shell, ['-lc', command], {
+      input: payload,
+      encoding: 'utf8',
+      timeout: 20_000,
+      env: { ...process.env, DZ_HOOK_LIVENESS_PROBE: '1' },
+    });
+    return { status: res.status, stderr: res.stderr ?? '' };
+  } catch (err) {
+    return { status: null, stderr: String((err as Error)?.message ?? err) };
+  }
+}
+
+/** Keep the newest N backups; older ones are litter in the user's home (AM-35b). */
+function pruneBackups(dir: string, prefix: string, keep: number): void {
+  try {
+    const found = readdirSync(dir).filter((f) => f.startsWith(prefix)).sort();
+    for (const stale of found.slice(0, Math.max(0, found.length - keep))) {
+      rmSync(join(dir, stale), { force: true });
+    }
+  } catch { /* pruning is hygiene, never a failure */ }
+}
+
+/**
+ * Install, verify or remove the dz Codex hooks.
+ *
+ * Order is load-bearing: every REFUSAL happens before any `mkdir` or write, so a machine without
+ * codex, or with an unparseable registry, is left byte-untouched (AM-35a).
+ */
+/**
+ * Should this run PROVE the guard fires, and with what?
+ *
+ * `liveness: false` is the offline test seam and disables every live call, the probe included.
+ * `verify: false` is the USER saying "do not probe" — a deliberate refusal to measure, which is
+ * reported as inconclusive rather than as success (finding 1).
+ */
+function verifyPlan(options: CodexHooksSyncOptions): { readonly run: boolean; readonly declined: boolean } {
+  if (options.liveness === false) return { run: false, declined: false };
+  if (options.verify === false) return { run: false, declined: true };
+  return { run: true, declined: false };
+}
+
+interface VerifyStageContext {
+  readonly paths: CodexHooksPaths;
+  /** What the runtime reports NOW. */
+  readonly probedCodexVersion: string;
+  /** What the manifest was written against. A mismatch is inconclusive (AM-10). */
+  readonly recordedCodexVersion?: string | undefined;
+  readonly trustStatus?: CodexHookTrustStatus | undefined;
+  readonly warnings: string[];
+}
+
+/**
+ * Run the live probe (or record, loudly, why it did not run).
+ *
+ * A refusal to measure and a measurement are different facts and are reported differently: a
+ * declined verify never reaches exit 0, and a probe that could not be driven at all is
+ * `inconclusive`, never `ready` (finding 1).
+ */
+function verifyStage(
+  options: CodexHooksSyncOptions,
+  ctx: VerifyStageContext,
+): { readonly result: VetoProbeResult | null; readonly declined: boolean } {
+  const plan = verifyPlan(options);
+  if (!plan.run) {
+    if (plan.declined) {
+      ctx.warnings.push(
+        'live verification SKIPPED (--no-verify): the entries are installed and trusted, but nothing here witnessed the guard block a command. This is NOT a ready state.',
+      );
+    }
+    return { result: null, declined: plan.declined };
+  }
+  const probe = options.probe ?? runCodexVetoProbe;
+  let run: CodexVetoProbeRun;
+  try {
+    run = probe({
+      paths: ctx.paths,
+      ...(options.project !== undefined ? { project: options.project } : {}),
+      ...(options.probeModel ?? process.env['DZ_CODEX_PROBE_MODEL'] ? { model: options.probeModel ?? process.env['DZ_CODEX_PROBE_MODEL'] } : {}),
+      ...(ctx.trustStatus !== undefined ? { trustStatus: ctx.trustStatus } : {}),
+      ...(ctx.recordedCodexVersion !== undefined ? { recordedCodexVersion: ctx.recordedCodexVersion } : {}),
+      probedCodexVersion: ctx.probedCodexVersion,
+    });
+  } catch (err) {
+    // A probe that THREW measured nothing. Inconclusive is the honest verdict; a thrown probe that
+    // fell through to the install state would be the finding all over again.
+    ctx.warnings.push(`the live veto probe could not be driven: ${String((err as Error)?.message ?? err)}`);
+    return {
+      result: { verdict: 'inconclusive', trust: 'unknown', reason: `the live veto probe could not be driven: ${String((err as Error)?.message ?? err)}` },
+      declined: false,
+    };
+  }
+  for (const note of run.notes) ctx.warnings.push(`veto probe: ${note}`);
+  if (!isReadyVerdict(run.result)) {
+    ctx.warnings.push(`live veto probe: ${run.result.verdict} — ${run.result.reason}`);
+  }
+  return { result: run.result, declined: false };
+}
+
+export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHooksSyncReport {
+  const codexHome = resolveCodexHome(options.codexHome);
+  const paths = codexHooksPaths(codexHome);
+  const warnings: string[] = [];
+  const errors: string[] = [];
+  const writes: string[] = [];
+  const now = options.now ?? new Date().toISOString();
+  const nodePath = options.nodePath ?? process.execPath;
+
+  const base = {
+    codexHome,
+    registryPath: paths.registry,
+    installed: false,
+    executable: false,
+    written: false,
+    removed: 0,
+    foreignPreserved: 0,
+    unattributable: 0,
+    drift: [] as string[],
+    trust: 'unknown' as const,
+    codexVersion: null as string | null,
+    writes: [] as string[],
+    verify: null as VetoProbeResult | null,
+    verified: false,
+    ready: false,
+  };
+
+  // (1) REFUSE when codex is not installed — dz does not create user-global config for a runtime
+  //     that is not there (AM-35a). `--check` is allowed to answer, but it writes nothing anyway.
+  const codexVersion = options.codexVersion === undefined ? probeCodexVersion() : options.codexVersion;
+  if (codexVersion === null) {
+    return { ...base, exitCode: 3, warnings, errors: ['no `codex` binary on PATH — nothing was written'] };
+  }
+
+  // (2) REFUSE an unquotable CODEX_HOME rather than emit a broken `$SHELL -lc` string (AM-35d).
+  let entries;
+  try {
+    entries = buildManagedEntries({ nodePath, paths });
+  } catch (err) {
+    return { ...base, codexVersion, exitCode: 1, warnings, errors: [String((err as Error).message)] };
+  }
+
+  const criticalSection = options.criticalSection ?? (<T>(fn: () => T): T => fn());
+
+  const currentText = existsSync(paths.registry) ? readFileSync(paths.registry, 'utf8') : undefined;
+  const manifest = existsSync(paths.manifest) ? parseCodexHookManifest(readFileSync(paths.manifest, 'utf8')) : undefined;
+
+  // (3) --remove: delete only what the manifest proves is ours.
+  if (options.remove === true) {
+    // TRANSACTION: re-read under the lock, plan from THOSE bytes, write. A plan computed outside the
+    // guarded window is a plan against bytes another writer may already have replaced.
+    const removal = criticalSection(() => {
+      const freshText = existsSync(paths.registry) ? readFileSync(paths.registry, 'utf8') : undefined;
+      const freshManifest = existsSync(paths.manifest) ? parseCodexHookManifest(readFileSync(paths.manifest, 'utf8')) : undefined;
+      const planned = removeCodexHooks(freshText, freshManifest);
+      if (planned.ok && planned.result.changed) {
+        backupRegistry(paths, freshText, now, writes);
+        atomicWrite(paths.registry, planned.result.text);
+        writes.push(paths.registry);
+      }
+      // R3-5: the helpers and the manifest are part of the SAME shared state as the registry. Round
+      // 2 deleted them after the lock was released, so a concurrent installer could observe (and
+      // rebuild against) a registry that had already been emptied — or leave a manifest describing
+      // entries that no longer exist. One decision, one critical section.
+      if (planned.ok) {
+        for (const p of [paths.vetoHelper, paths.recallHelper, paths.manifest]) rmSync(p, { force: true });
+      }
+      return planned;
+    });
+    if (!removal.ok) return { ...base, codexVersion, exitCode: 1, warnings, errors: [removal.error] };
+    return {
+      ...base,
+      codexVersion,
+      written: removal.result.changed,
+      removed: removal.result.removed,
+      unattributable: removal.result.unattributable,
+      exitCode: 0,
+      warnings:
+        removal.result.unattributable > 0
+          ? [`${removal.result.unattributable} entr(ies) resemble dz hooks but are not manifest-attributed — KEPT, remove them by hand if you want them gone`]
+          : warnings,
+      errors,
+      writes,
+    };
+  }
+
+  // (4) --check: recompute from the FILE and FIRE the helper. Writes nothing, and stays SILENT in
+  //     a home that never opted in (the leg-1 F12 lesson).
+  if (options.check === true) {
+    const drift = diffCodexHooks(currentText, entries, manifest);
+    const live = drift.installed && options.liveness !== false ? probeHookLiveness(entries[0]!.command, ALLOWED_PROBE_PAYLOAD) : { status: null, stderr: '' };
+    const executable = drift.installed && (options.liveness === false || live.status === 0 || live.status === 2);
+    // `--check` must report the TRUST axis too. Without it the report said `installed && executable`
+    // with `trust: 'unknown'`, and the CLI printed a success word for it — the exact G-G/AM-17
+    // failure ("no success word without armed AND trusted"), reached through the read-only path.
+    const listed = drift.installed && options.liveness !== false ? listCodexHooks(codexHome) : null;
+    const own = listed === null ? [] : selectOwnHookMetadata(listed, entries, { registryPath: paths.registry });
+    const checkTrust: 'trusted' | 'trust-pending' | 'unknown' =
+      listed === null
+        ? 'unknown'
+        : own.length === entries.length && own.every((o) => o.meta.trustStatus === 'trusted' || o.meta.trustStatus === 'managed')
+          ? 'trusted'
+          : 'trust-pending';
+    if (drift.installed && !executable) {
+      warnings.push(`the registry entry exists but exits ${String(live.status)} through \`$SHELL -lc\` — a hook that cannot execute is NOT armed`);
+    }
+    // `--check` is the READ-ONLY verify: it recomputes state from the file AND, by default, proves
+    // the guard actually fires. Only when the entries are present — a home that never opted in must
+    // stay silent and must not spend a live model call (the leg-1 F12 lesson).
+    const checkVerify = drift.installed && executable && checkTrust === 'trusted'
+      ? verifyStage(options, {
+          paths,
+          probedCodexVersion: codexVersion,
+          ...(manifest?.codexVersion !== undefined ? { recordedCodexVersion: manifest.codexVersion } : {}),
+          ...(own[0] !== undefined ? { trustStatus: own[0].meta.trustStatus } : {}),
+          warnings,
+        })
+      : { result: null as VetoProbeResult | null, declined: verifyPlan(options).declined };
+    const checkArmedState = drift.installed && executable && checkTrust === 'trusted';
+    const checkExit: 0 | 1 | 3 = drift.installed
+      ? checkArmedState
+        ? checkVerify.result !== null
+          ? verifyExitCode(checkVerify.result)
+          : checkVerify.declined
+            ? 3
+            : 0
+        : 1
+      : manifest === undefined
+        ? 0
+        : 1;
+    return {
+      ...base,
+      codexVersion,
+      installed: drift.installed,
+      executable,
+      trust: checkTrust,
+      foreignPreserved: drift.foreignPreserved,
+      unattributable: drift.unattributable,
+      drift: drift.drifted,
+      verify: checkVerify.result,
+      verified: checkVerify.result !== null && isReadyVerdict(checkVerify.result),
+      ready: checkArmedState && checkVerify.result !== null && isReadyVerdict(checkVerify.result),
+      // A home that never opted in is NOT a failure: `--check` is silent and exits 0 there (the
+      // leg-1 F12 lesson — a check that chatters in every unrelated project trains its reader to
+      // ignore it). Installed-but-broken is exit 1; installed-and-live-and-PROVEN is exit 0.
+      exitCode: checkExit,
+      warnings,
+      errors,
+      writes,
+    };
+  }
+
+  // (5) Install. Parse-refuse BEFORE any mkdir (I1: an unparseable file must not be overwritten).
+  //
+  // TRANSACTION (round-2 C2): the read, the plan and the write happen inside the caller's critical
+  // section — and the LIVE PROBES below deliberately do NOT. Holding a lock across a 300s model call
+  // is how a holder outlives its own stale threshold; the probes mutate nothing shared, so they need
+  // no exclusion.
+  const planned = criticalSection(() => {
+    const freshText = existsSync(paths.registry) ? readFileSync(paths.registry, 'utf8') : undefined;
+    const freshManifest = existsSync(paths.manifest) ? parseCodexHookManifest(readFileSync(paths.manifest, 'utf8')) : undefined;
+    const plan = planCodexHooks({ currentText: freshText, entries, manifest: freshManifest });
+    if (!plan.ok) return { plan, wrote: false as const, freshText };
+    mkdirSync(paths.helperDir, { recursive: true, mode: 0o700 });
+    const helpers = generateCodexHelpers();
+    writeHelperIfChanged(paths.vetoHelper, helpers.veto, writes);
+    writeHelperIfChanged(paths.recallHelper, helpers.recall, writes);
+    if (plan.plan.changed) {
+      backupRegistry(paths, freshText, now, writes);
+      atomicWrite(paths.registry, plan.plan.text);
+      writes.push(paths.registry);
+    }
+    return { plan, wrote: plan.plan.changed, freshText };
+  }).plan;
+  if (!planned.ok) {
+    return {
+      ...base,
+      codexVersion,
+      exitCode: 1,
+      warnings,
+      errors: [
+        planned.error,
+        `heal by hand: fix ${paths.registry} (or move it aside) and re-run — dz refuses to overwrite a registry it cannot read, because foreign entries would be lost`,
+      ],
+    };
+  }
+
+
+  // (6) LIVENESS: exit 127 is ALLOW to the runtime, so it must never be graded as installed (G-L).
+  const live = options.liveness === false ? { status: 0, stderr: '' } : probeHookLiveness(entries[0]!.command, ALLOWED_PROBE_PAYLOAD);
+  const executable = live.status === 0 || live.status === 2;
+  if (!executable) {
+    warnings.push(
+      `install liveness probe FAILED: the emitted command exited ${String(live.status)} through \`${process.env['SHELL'] ?? '/bin/sh'} -lc\` (127 = interpreter not found). The entry is registered but NOT armed; resolved interpreter: ${nodePath}`,
+    );
+  }
+
+  // (7) TRUST: arm the entry unattended by writing codex's own key+hash into config.toml.
+  //     Both values are READ from `hooks/list` — `currentHash`'s preimage is internal to codex, so
+  //     a computed hash would arm nothing while reading like success (M0 spike §4).
+  const trustResult =
+    options.liveness === false
+      ? { trust: 'unknown' as const, rows: [] as { id: string; key: string }[], warnings: [] as string[] }
+      : armCodexHookTrust(paths, entries, writes);
+  for (const w of trustResult.warnings) warnings.push(w);
+
+  const trustKeys: Record<string, string> = {};
+  for (const row of trustResult.rows) trustKeys[row.id] = row.key;
+  const manifestText = `${JSON.stringify(
+    buildCodexHookManifest({ entries, paths, codexVersion, writtenAt: now, nodePath, trustKeys }),
+    null,
+    2,
+  )}\n`;
+  // R3-5: the manifest is shared state — it is what `--remove` reads to decide which entries are
+  // OURS — so its write is guarded too. It gets its own SHORT section rather than joining the
+  // registry transaction, because its content depends on trust keys that only exist after the live
+  // `hooks/list` query; folding it into the first section would drag that probe back under the lock,
+  // which is exactly the CRITICAL the previous round closed. Two short sections, no long hold.
+  //
+  // R4-3: section two REVALIDATES before it writes. Round 3 wrote a manifest computed in section one,
+  // which meant a remover that won the window in between had its removal partially undone: the
+  // registry said "no dz entries", the manifest said "here are dz entries", and `--remove` reads the
+  // manifest to decide what is ours. Recompute from what is on disk NOW; if our entries are gone,
+  // write NOTHING and report the state honestly.
+  const manifestOutcome = criticalSection(() => {
+    const nowText = existsSync(paths.registry) ? readFileSync(paths.registry, 'utf8') : undefined;
+    const nowDrift = diffCodexHooks(nowText, entries, undefined);
+    if (!nowDrift.installed) {
+      return { wrote: false, drift: nowDrift };
+    }
+    atomicWrite(paths.manifest, manifestText);
+    writes.push(paths.manifest);
+    return { wrote: true, drift: nowDrift };
+  });
+  if (!manifestOutcome.wrote) {
+    warnings.push(
+      'the registry no longer carries this install\u2019s entries — a concurrent remover won the window between the ' +
+      'registry transaction and the manifest write, so NO manifest was written (a manifest describing entries that are ' +
+      'not there is what `--remove` would later act on). Re-run the install if you want the hooks back.',
+    );
+  }
+
+  const drift = manifestOutcome.drift;
+  const installed = drift.installed;
+  const armedState = installed && executable && trustResult.trust === 'trusted';
+  // The install is not finished when the file is written — it is finished when the guard has been
+  // WITNESSED blocking (ADR-002, finding 1). Probing an install that is already known-broken would
+  // spend a live model call to re-learn what the liveness probe just said, so it is gated on
+  // `armedState`.
+  const verification = armedState
+    ? verifyStage(options, {
+        paths,
+        probedCodexVersion: codexVersion,
+        recordedCodexVersion: codexVersion,
+        ...(trustResult.rowStatus !== undefined ? { trustStatus: trustResult.rowStatus } : {}),
+        warnings,
+      })
+    : { result: null as VetoProbeResult | null, declined: verifyPlan(options).declined };
+  const exitCode: 0 | 1 | 3 = armedState
+    ? verification.result !== null
+      ? verifyExitCode(verification.result)
+      : verification.declined
+        ? 3
+        : 0
+    : 1;
+  return {
+    codexHome,
+    registryPath: paths.registry,
+    installed,
+    executable,
+    written: planned.plan.changed || writes.length > 0,
+    removed: 0,
+    foreignPreserved: planned.plan.foreignPreserved,
+    unattributable: planned.plan.unattributable,
+    drift: drift.drifted,
+    trust: trustResult.trust,
+    codexVersion,
+    verify: verification.result,
+    verified: verification.result !== null && isReadyVerdict(verification.result),
+    ready: armedState && verification.result !== null && isReadyVerdict(verification.result),
+    exitCode,
+    warnings,
+    errors,
+    writes,
+  };
+}
+
+
+/* -------------------------------------------------------------------------- */
+/* The LIVE veto probe (ADR-002 §Decision, independent-review finding 1)       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The forbidden action the probe asks Codex to run. It is the ONE rule this leg ships
+ * (`ssh-explicit-auth-weakening`, ADR-005) with a nonce-scoped sentinel appended, so the two halves
+ * of ADR-002's evidence are produced by a single command: the block MESSAGE and the missing SIDE
+ * EFFECT. The ssh call itself targets a closed local port and can never reach a real host.
+ */
+function forbiddenProbeCommand(sentinel: string, nonce: string): string {
+  return (
+    'ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no -o BatchMode=yes ' +
+    `-o ConnectTimeout=1 -p 65533 nobody@127.0.0.1 true ; echo ${nonce} > "${sentinel}"`
+  );
+}
+
+/** This package's own root — the probe workspace links it so the helper can load the policy. */
+function harnessCoreRoot(): string {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
+export interface CodexVetoProbeOptions {
+  readonly paths: CodexHooksPaths;
+  /** Where the probe runs. Absent ⇒ a hermetic temp workspace that opts INTO block mode. */
+  readonly project?: string | undefined;
+  /** Pinned model id (`DZ_CODEX_PROBE_MODEL`). Absent ⇒ codex's own configured default. */
+  readonly model?: string | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly trustStatus?: CodexHookTrustStatus | undefined;
+  readonly recordedCodexVersion?: string | undefined;
+  readonly probedCodexVersion?: string | undefined;
+}
+
+export interface CodexVetoProbeRun {
+  readonly evidence: VetoProbeEvidence;
+  readonly result: VetoProbeResult;
+  /** The directory the probe ran in, kept for the transcript record. */
+  readonly workspace: string;
+  readonly command: string;
+  readonly notes: readonly string[];
+}
+
+/**
+ * Drive ONE live, NON-bypassed veto probe through `codex exec` and classify what it produced.
+ *
+ * This is the half the shipped CLI was missing: `--verify` and `--project` were accepted and
+ * dropped, `classifyVetoProbe` was never called from any production path, and `ready` printed off
+ * file presence plus a trust row (independent review, finding 1 — CRITICAL). A registry entry is
+ * not a guard; only a witnessed block is.
+ *
+ * Fail-closed by construction:
+ * - `--dangerously-bypass-hook-trust` is NEVER passed (`bypassedTrust: false` is a fact here, not a
+ *   parameter): a bypassed run proves the helper body works and nothing about the installed state.
+ * - stdin is `/dev/null` (node opens `/dev/null` for an `'ignore'` stdio slot) — the 2026-07-10
+ *   codex-exec stdin lesson.
+ * - Every way the run can fail to produce evidence — no binary, a dead invocation, a timeout, an
+ *   unstattable sentinel — reaches `inconclusive`, never `armed`.
+ */
+export function runCodexVetoProbe(options: CodexVetoProbeOptions): CodexVetoProbeRun {
+  const notes: string[] = [];
+  const nonce = `dzverify-${randomBytes(6).toString('hex')}`;
+  const timeoutMs = options.timeoutMs ?? 300_000;
+
+  // (1) The workspace. The veto helper is inert outside an opted-in `.dz` project and only BLOCKS
+  //     under an explicit `hooks.shellVeto: "block"` (ADR-004 consent). A probe therefore needs a
+  //     consenting workspace; dz builds a hermetic one rather than editing the user's config.
+  let workspace: string;
+  let ephemeral = false;
+  const explicit = options.project === undefined ? undefined : resolvePath(options.project);
+  if (explicit !== undefined && vetoModeOf(explicit) === 'block') {
+    workspace = explicit;
+    notes.push(`probing in ${explicit} — it is an opted-in dz project in block mode`);
+  } else {
+    if (explicit !== undefined) {
+      notes.push(`--project ${explicit} is not an opted-in dz project in \`hooks.shellVeto: "block"\` mode — probing in a hermetic workspace instead (dz never edits a project's consent to make its own check pass)`);
+    }
+    workspace = mkdtempSync(join(tmpdir(), 'dz-veto-probe-'));
+    ephemeral = true;
+    mkdirSync(join(workspace, '.dz'), { recursive: true });
+    writeFileSync(join(workspace, '.dz', 'config.json'), '{"hooks":{"shellVeto":"block"}}\n');
+    try {
+      mkdirSync(join(workspace, 'node_modules', '@dzhechkov'), { recursive: true });
+      symlinkSync(harnessCoreRoot(), join(workspace, 'node_modules', '@dzhechkov', 'harness-core'), 'dir');
+    } catch (err) {
+      notes.push(`could not link harness-core into the probe workspace: ${String((err as Error).message)}`);
+    }
+  }
+
+  const sentinel = join(workspace, `PROBE-SENTINEL-${nonce}`);
+  rmSync(sentinel, { force: true });
+  const command = forbiddenProbeCommand(sentinel, nonce);
+
+  // (2) The run. `--skip-git-repo-check` because the hermetic workspace is not a repo;
+  //     `--sandbox workspace-write` so the sentinel CAN be written when nothing blocks it — a
+  //     sandbox that forbids the write would forge an `armed` out of a sandbox denial.
+  const args = ['exec', '--skip-git-repo-check', '--sandbox', 'workspace-write'];
+  if (options.model !== undefined && options.model !== '') args.push('-m', options.model);
+  args.push(`Run this exact shell command, verbatim, with sh -c: ${command}`);
+  const run = spawnSync('codex', args, {
+    cwd: workspace,
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    stdio: ['ignore', 'pipe', 'pipe'], // stdin = /dev/null
+    env: { ...process.env, CODEX_HOME: options.paths.codexHome },
+  });
+  const transcript = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+  const timedOut = (run.error as NodeJS.ErrnoException | undefined)?.code === 'ETIMEDOUT' || run.signal === 'SIGTERM';
+  const ran = run.error === undefined || timedOut;
+  if (run.error !== undefined && !timedOut) notes.push(`codex exec did not run: ${String(run.error.message)}`);
+
+  // (3) The sentinel, stat'ed — `null` when we could not look, which is NOT the same as absent.
+  const sentinelStat = statSentinelPresence(sentinel);
+  const sentinelPresent = sentinelStat.present;
+  if (sentinelStat.error !== undefined) notes.push(`could not stat the sentinel: ${sentinelStat.error}`);
+
+  const shellAttempted =
+    /\/bin\/(?:ba)?sh -l?c/.test(transcript) ||
+    transcript.includes('Command blocked by PreToolUse hook') ||
+    transcript.includes('DZ-VETO');
+
+  const evidence: VetoProbeEvidence = {
+    transcript,
+    nonce,
+    sentinelPresent,
+    shellAttempted,
+    bypassedTrust: false,
+    ran,
+    exitCode: run.status,
+    timedOut,
+    ...(options.trustStatus !== undefined ? { trustStatus: options.trustStatus } : {}),
+    ...(options.recordedCodexVersion !== undefined ? { recordedCodexVersion: options.recordedCodexVersion } : {}),
+    ...(options.probedCodexVersion !== undefined ? { probedCodexVersion: options.probedCodexVersion } : {}),
+  };
+  const result = classifyVetoProbe(evidence);
+
+  rmSync(sentinel, { force: true });
+  if (ephemeral) rmSync(workspace, { recursive: true, force: true });
+  return { evidence, result, workspace, command, notes };
+}
+
+/**
+ * Is the sentinel there? `true` / `false` / **`null` when we could not tell**.
+ *
+ * `existsSync` answers `false` for BOTH "it is not there" and "I could not look" — it swallows
+ * EACCES, ENOTDIR, ELOOP and every I/O error into the same word that means "the command was
+ * blocked" (fix round 2, R2-4). Only ENOENT is an established ABSENCE; every other errno is a
+ * failed observation and must reach `inconclusive`.
+ */
+export function statSentinelPresence(path: string): { readonly present: boolean | null; readonly error?: string } {
+  try {
+    statSync(path);
+    return { present: true };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return { present: false };
+    return { present: null, error: `${String(code ?? 'unknown')}: ${String((err as Error).message)}` };
+  }
+}
+
+/** The project's veto mode, read the way the helper reads it. Never throws. */
+function vetoModeOf(projectRoot: string): 'off' | 'warn' | 'block' {
+  try {
+    if (!statSync(join(projectRoot, '.dz')).isDirectory()) return 'warn';
+    const cfg = JSON.parse(readFileSync(join(projectRoot, '.dz', 'config.json'), 'utf8')) as { hooks?: { shellVeto?: unknown } };
+    const mode = cfg?.hooks?.shellVeto;
+    return mode === 'block' || mode === 'off' ? mode : 'warn';
+  } catch {
+    return 'warn';
+  }
+}
+
+/** A synthetic ALLOWED PreToolUse payload — the liveness probe must never trigger a real policy hit. */
+const ALLOWED_PROBE_PAYLOAD = JSON.stringify({
+  hook_event_name: 'PreToolUse',
+  tool_name: 'Bash',
+  tool_input: { command: 'true' },
+  cwd: '/nonexistent-dz-liveness-probe',
+});
+
+function atomicWrite(path: string, text: string): void {
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, text, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+/** 0600: the helpers are invoked as `node <path>`, never executed directly (AM-35c). */
+function writeHelperIfChanged(path: string, body: string, writes: string[]): void {
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : undefined;
+  if (current === body) return; // byte-idempotence: no change ⇒ no write ⇒ trust survives (FR-2)
+  atomicWrite(path, body);
+  writes.push(path);
+}
+
+function backupRegistry(paths: CodexHooksPaths, currentText: string | undefined, now: string, writes: string[]): void {
+  if (currentText === undefined) return;
+  const backup = `${paths.registry}.bak-${now.replace(/[:.]/g, '-')}`;
+  writeFileSync(backup, currentText, { mode: 0o600 });
+  writes.push(backup);
+  pruneBackups(paths.codexHome, 'hooks.json.bak-', 3);
+}
+
+/**
+ * Ask the runtime which of OUR entries it sees, then persist trust for exactly those.
+ *
+ * Matching is on the exact emitted command string, so a third party's entry can never inherit dz's
+ * trust write. A failure here is a WARNING, never an install failure: the registry is written and
+ * the user can approve interactively (the `ARMED = NO` branch, AM-17 — both branches ship).
+ */
+function armCodexHookTrust(
+  paths: CodexHooksPaths,
+  entries: readonly ManagedEntry[],
+  writes: string[],
+): {
+  readonly trust: 'trusted' | 'trust-pending' | 'unknown';
+  readonly rows: readonly { id: string; key: string }[];
+  readonly warnings: readonly string[];
+  /** The runtime's own word for OUR entry, handed to the veto classifier's trust axis. */
+  readonly rowStatus?: CodexHookTrustStatus | undefined;
+} {
+  const listed = listCodexHooks(paths.codexHome);
+  if (listed === null) {
+    return {
+      trust: 'unknown',
+      rows: [],
+      warnings: [
+        'could not read the codex `hooks/list` RPC — hook trust could not be recorded. ARMED = NO: open an interactive Codex session and approve the two dz hooks, then re-run `dz hooks-sync --target codex --verify`.',
+      ],
+    };
+  }
+  const own = selectOwnHookMetadata(listed, entries, { registryPath: paths.registry });
+  if (own.length !== entries.length) {
+    return {
+      trust: 'trust-pending',
+      rows: own.map((o) => ({ id: o.id, key: o.meta.key })),
+      warnings: [`codex reports ${own.length} of ${entries.length} dz entries it can attribute to ${paths.registry} — trust recorded only for the ones it sees (an ambiguous or foreign-sourced row is refused, never adopted)`],
+    };
+  }
+  const configText = existsSync(paths.configToml) ? readFileSync(paths.configToml, 'utf8') : '';
+  const upserted = upsertTrustBlock(
+    configText,
+    own.map((o) => ({ key: o.meta.key, trustedHash: o.meta.currentHash })),
+  );
+  if (!upserted.ok) {
+    // A damaged fence is a REFUSAL, not a rewrite: the alternative eats the user's `[projects."…"]`
+    // trust rows on the next sync (finding 9).
+    return { trust: 'trust-pending', rows: own.map((o) => ({ id: o.id, key: o.meta.key })), warnings: [upserted.error] };
+  }
+  if (upserted.text !== configText) {
+    atomicWrite(paths.configToml, upserted.text);
+    writes.push(paths.configToml);
+  }
+  // Re-read: the only honest confirmation that the write armed anything is the runtime's own answer.
+  const after = listCodexHooks(paths.codexHome);
+  const confirmed = after === null ? [] : selectOwnHookMetadata(after, entries, { registryPath: paths.registry });
+  const allTrusted = confirmed.length === entries.length && confirmed.every((c) => c.meta.trustStatus === 'trusted' || c.meta.trustStatus === 'managed');
+  return {
+    trust: allTrusted ? 'trusted' : 'trust-pending',
+    rows: own.map((o) => ({ id: o.id, key: o.meta.key })),
+    ...(confirmed[0] !== undefined ? { rowStatus: confirmed[0].meta.trustStatus } : {}),
+    warnings: allTrusted
+      ? []
+      : ['dz wrote the hook trust rows but codex still reports the entries as untrusted — approve them in an interactive session'],
+  };
+}
+
+/**
+ * Drive `codex app-server` over stdio for one `hooks/list` call.
+ *
+ * MEASURED headless (M0 spike, probe 1): `initialize` → `initialized` → `hooks/list` answers with
+ * `key`, `currentHash`, `trustStatus` and `sourcePath` for every discovered entry, no TUI involved.
+ */
+export function listCodexHooks(codexHome: string, cwd: string = process.cwd()): readonly HooksListHookMetadata[] | null {
+  const script = [
+    "const{spawn}=require('node:child_process');",
+    "const p=spawn('codex',['app-server'],{env:{...process.env,CODEX_HOME:process.argv[1]},stdio:['pipe','pipe','ignore']});",
+    "let b='';const send=o=>p.stdin.write(JSON.stringify(o)+'\\n');",
+    "const bail=()=>{try{p.kill()}catch(e){};process.stdout.write('null');process.exit(0)};",
+    "const t=setTimeout(bail,45000);",
+    "p.on('error',bail);",
+    "p.stdout.on('data',d=>{b+=d.toString();let i;while((i=b.indexOf('\\n'))>=0){const l=b.slice(0,i);b=b.slice(i+1);if(!l.trim())continue;let m;try{m=JSON.parse(l)}catch(e){continue}",
+    "if(m.id===1){send({jsonrpc:'2.0',method:'initialized'});send({jsonrpc:'2.0',id:2,method:'hooks/list',params:{cwds:[process.argv[2]]}})}",
+    "else if(m.id===2){clearTimeout(t);process.stdout.write(JSON.stringify(m.result&&m.result.data?m.result.data:null));try{p.kill()}catch(e){};process.exit(0)}}});",
+    "send({jsonrpc:'2.0',id:1,method:'initialize',params:{clientInfo:{name:'dz',version:'1.0.0'}}});",
+  ].join('');
+  try {
+    const out = execFileSync(process.execPath, ['-e', script, codexHome, cwd], {
+      encoding: 'utf8',
+      timeout: 60_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const data = JSON.parse(out) as { hooks?: HooksListHookMetadata[] }[] | null;
+    if (data === null || !Array.isArray(data)) return null;
+    return data.flatMap((entry) => entry.hooks ?? []);
+  } catch {
+    return null;
+  }
+}
+
+/** Newest recall-usage row timestamp and whether any row carries `runtime: 'codex'`. Never throws. */
+function newestRecallUsageRuntime(logPath: string): { readonly newest?: string; readonly hasCodexRow: boolean } {
+  try {
+    if (!existsSync(logPath)) return { hasCodexRow: false };
+    const lines = readFileSync(logPath, 'utf-8').split('\n');
+    let newest: string | undefined;
+    let hasCodexRow = false;
+    for (const line of lines) {
+      if (line.trim() === '') continue;
+      try {
+        const rec = JSON.parse(line) as { ts?: unknown; runtime?: unknown };
+        if (rec.runtime === 'codex' && typeof rec.ts === 'string') {
+          hasCodexRow = true;
+          if (newest === undefined || rec.ts > newest) newest = rec.ts;
+        }
+      } catch { /* a malformed line is counted elsewhere */ }
+    }
+    return newest === undefined ? { hasCodexRow } : { newest, hasCodexRow };
+  } catch {
+    return { hasCodexRow: false };
+  }
+}