@dzhechkov/harness-core 0.5.0 → 0.5.2

package/src/operations.ts

@@ -7,9 +7,11 @@
  */
 
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+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,
@@ -26,6 +28,14 @@ import {
   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';
@@ -1121,6 +1131,26 @@ export interface CodexHooksSyncOptions {
   /** 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 {
@@ -1137,6 +1167,15 @@ export interface CodexHooksSyncReport {
   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[];
@@ -1145,7 +1184,10 @@ export interface CodexHooksSyncReport {
   readonly writes: readonly string[];
 }
 
-function resolveCodexHome(explicit: string | undefined): 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;
@@ -1203,6 +1245,76 @@ function pruneBackups(dir: string, prefix: string, keep: number): void {
  * 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);
@@ -1225,6 +1337,9 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
     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
@@ -1242,19 +1357,34 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
     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) {
-    const removal = removeCodexHooks(currentText, manifest);
+    // 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] };
-    if (removal.result.changed) {
-      backupRegistry(paths, currentText, now, writes);
-      atomicWrite(paths.registry, removal.result.text);
-      writes.push(paths.registry);
-    }
-    for (const p of [paths.vetoHelper, paths.recallHelper, paths.manifest]) rmSync(p, { force: true });
     return {
       ...base,
       codexVersion,
@@ -1281,13 +1411,40 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
     // 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);
+    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,
@@ -1297,21 +1454,41 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
       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 is exit 0.
-      exitCode: drift.installed ? (executable && checkTrust === 'trusted' ? 0 : 1) : manifest === undefined ? 0 : 1,
-      warnings:
-        drift.installed && !executable
-          ? [`the registry entry exists but exits ${String(live.status)} through \`$SHELL -lc\` — a hook that cannot execute is NOT armed`]
-          : warnings,
+      // 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).
-  const planned = planCodexHooks({ currentText, entries, manifest });
+  //
+  // 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,
@@ -1325,16 +1502,6 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
     };
   }
 
-  mkdirSync(paths.helperDir, { recursive: true, mode: 0o700 });
-  const helpers = generateCodexHelpers();
-  writeHelperIfChanged(paths.vetoHelper, helpers.veto, writes);
-  writeHelperIfChanged(paths.recallHelper, helpers.recall, writes);
-
-  if (planned.plan.changed) {
-    backupRegistry(paths, currentText, now, writes);
-    atomicWrite(paths.registry, planned.plan.text);
-    writes.push(paths.registry);
-  }
 
   // (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);
@@ -1361,12 +1528,58 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
     null,
     2,
   )}\n`;
-  atomicWrite(paths.manifest, manifestText);
-  writes.push(paths.manifest);
+  // 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 = diffCodexHooks(readFileSync(paths.registry, 'utf8'), entries, undefined);
+  const drift = manifestOutcome.drift;
   const installed = drift.installed;
-  const exitCode: 0 | 1 | 3 = installed && executable && trustResult.trust === 'trusted' ? 0 : 1;
+  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,
@@ -1379,6 +1592,9 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
     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,
@@ -1386,6 +1602,179 @@ export function runSyncCodexHooks(options: CodexHooksSyncOptions = {}): CodexHoo
   };
 }
 
+
+/* -------------------------------------------------------------------------- */
+/* 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',
@@ -1427,7 +1816,13 @@ 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[] } {
+): {
+  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 {
@@ -1438,30 +1833,36 @@ function armCodexHookTrust(
       ],
     };
   }
-  const own = selectOwnHookMetadata(listed, entries);
+  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 — trust recorded only for the ones it sees`],
+      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 next = upsertTrustBlock(
+  const upserted = upsertTrustBlock(
     configText,
     own.map((o) => ({ key: o.meta.key, trustedHash: o.meta.currentHash })),
   );
-  if (next !== configText) {
-    atomicWrite(paths.configToml, next);
+  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);
+  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'],