@dzhechkov/harness-core 0.4.4 → 0.5.0

package/dist/codex-hooks-assets.js

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

package/dist/codex-hooks-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-hooks-assets.js","sourceRoot":"","sources":["../src/codex-hooks-assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,gFAAgF;AAChF,SAAS,QAAQ;IACf,OAAO;oEAC2D,sBAAsB;;;;;;yBAMjE,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkF9C,CAAC;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,GAAG,QAAQ,EAAE,CAAC,OAAO,CAAC,sBAAsB,EAAE,uDAAuD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkD9G,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO,GAAG,QAAQ,EAAE,CAAC,OAAO,CAAC,sBAAsB,EAAE,yDAAyD,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0FhH,CAAC;AACF,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,oBAAoB;IAClC,OAAO,EAAE,IAAI,EAAE,uBAAuB,EAAE,EAAE,MAAM,EAAE,yBAAyB,EAAE,EAAE,CAAC;AAClF,CAAC"}

package/dist/codex-hooks-verify.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The fail-closed veto-probe classifier (`crossrt-2-codex-hooks`, ADR-002).
+ *
+ * Turns the evidence of ONE live probe run into a two-axis verdict. Pure: it never reads a file,
+ * never runs a command, and never consults its own emitter's intent — the whole point is that
+ * "we wrote the hook" is not evidence that the hook fired.
+ *
+ * ## The two axes (AM-16)
+ *
+ * `verdict` answers *did OUR hook block the forbidden command?* and comes from the TRANSCRIPT plus
+ * the sentinel side effect. `trust` answers *is the entry armed in the runtime's own view?* and
+ * comes from `hooks/list`'s `trustStatus` (MEASURED available headlessly — M0 spike, probe 1).
+ *
+ * ## No path defaults to a pass
+ *
+ * Every branch states its own verdict; there is no `??` fallback and no `else` that guesses. The
+ * four ways a probe can LOOK like a pass without being one, each closed here:
+ *
+ * 1. **A bypassed run.** `--dangerously-bypass-hook-trust` makes an UNTRUSTED hook fire, so a block
+ *    observed under it says nothing about the installed state (AM-1). Decided FIRST.
+ * 2. **Somebody else's block.** MEASURED (M0 §5): the runtime prefixes our stderr with its own
+ *    `Command blocked by PreToolUse hook: `. That phrase WITHOUT `DZ-VETO:` means *a* hook blocked,
+ *    not that ours did.
+ * 3. **A command that never ran.** "the model declined" and "the command was blocked" both show an
+ *    absent sentinel; only the transcript separates them (AM-36).
+ * 4. **A stale transcript.** Without this run's nonce the text is evidence about some other run.
+ *
+ * @packageDocumentation
+ */
+export type VetoVerdict = 'armed' | 'not-armed' | 'inconclusive';
+export type VetoTrust = 'trusted' | 'trust-pending' | 'unknown';
+/** The runtime's own `HookTrustStatus` vocabulary (v2 `HooksListResponse.json`, codex 0.147.0). */
+export type CodexHookTrustStatus = 'managed' | 'untrusted' | 'trusted' | 'modified';
+/** Our block marker. Must appear verbatim for a block to be attributed to dz. */
+export declare const DZ_VETO_MARKER = "DZ-VETO:";
+/** The default-mode (warn) marker — a hit that did NOT block (G-J). */
+export declare const DZ_VETO_WARN_MARKER = "DZ-VETO-WARN:";
+/** The runtime's generic block phrase. Present WITHOUT our marker ⇒ not our block. */
+export declare const RUNTIME_BLOCK_PHRASE = "Command blocked by PreToolUse hook";
+export interface VetoProbeEvidence {
+    /** stdout+stderr of the probe run, verbatim. */
+    readonly transcript: string;
+    /** Per-run nonce embedded in the probe command; guards against grading a stale transcript. */
+    readonly nonce: string;
+    /** Did the sentinel side effect land? `true` ⇒ the command RAN. */
+    readonly sentinelPresent: boolean;
+    /** Did the transcript show the model actually attempting the shell command? */
+    readonly shellAttempted: boolean;
+    /** Was `--dangerously-bypass-hook-trust` in play? `true` can never yield a pass. */
+    readonly bypassedTrust: boolean;
+    /** From `hooks/list`. Absent ⇒ trust could not be established, which is not the same as bad. */
+    readonly trustStatus?: CodexHookTrustStatus | undefined;
+    /** The codex version the manifest was written against. */
+    readonly recordedCodexVersion?: string | undefined;
+    /** The codex version observed now. A mismatch re-asserts stale facts, so it is inconclusive. */
+    readonly probedCodexVersion?: string | undefined;
+}
+export interface VetoProbeResult {
+    readonly verdict: VetoVerdict;
+    readonly trust: VetoTrust;
+    readonly reason: string;
+}
+/** Trust axis. Derived only from the runtime's own report, never from our emitter. */
+export declare function classifyTrust(status: VetoProbeEvidence['trustStatus']): VetoTrust;
+/** Classify one probe run. Exhaustive; no branch falls through to a pass. */
+export declare function classifyVetoProbe(e: VetoProbeEvidence): VetoProbeResult;
+/**
+ * Exit map (ADR-002 §5). `0` demands BOTH axes: an `armed` run whose entry is only `trust-pending`
+ * exits non-zero, because the next session may not fire it.
+ */
+export declare function verifyExitCode(r: VetoProbeResult): 0 | 1 | 3;
+/** True only for the one outcome that may print a success word (AM-17 / G-G). */
+export declare function isReadyVerdict(r: VetoProbeResult): boolean;
+//# sourceMappingURL=codex-hooks-verify.d.ts.map

package/dist/codex-hooks-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-hooks-verify.d.ts","sourceRoot":"","sources":["../src/codex-hooks-verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,GAAG,cAAc,CAAC;AACjE,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,eAAe,GAAG,SAAS,CAAC;AAEhE,mGAAmG;AACnG,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpF,iFAAiF;AACjF,eAAO,MAAM,cAAc,aAAa,CAAC;AACzC,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AACnD,sFAAsF;AACtF,eAAO,MAAM,oBAAoB,uCAAuC,CAAC;AAEzE,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,gGAAgG;IAChG,QAAQ,CAAC,WAAW,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACxD,0DAA0D;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnD,gGAAgG;IAChG,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,MAAM,EAAE,iBAAiB,CAAC,aAAa,CAAC,GAAG,SAAS,CAWjF;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,eAAe,CAqFvE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAI5D;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,CAAC,EAAE,eAAe,GAAG,OAAO,CAE1D"}

package/dist/codex-hooks-verify.js

@@ -0,0 +1,140 @@
+/**
+ * The fail-closed veto-probe classifier (`crossrt-2-codex-hooks`, ADR-002).
+ *
+ * Turns the evidence of ONE live probe run into a two-axis verdict. Pure: it never reads a file,
+ * never runs a command, and never consults its own emitter's intent — the whole point is that
+ * "we wrote the hook" is not evidence that the hook fired.
+ *
+ * ## The two axes (AM-16)
+ *
+ * `verdict` answers *did OUR hook block the forbidden command?* and comes from the TRANSCRIPT plus
+ * the sentinel side effect. `trust` answers *is the entry armed in the runtime's own view?* and
+ * comes from `hooks/list`'s `trustStatus` (MEASURED available headlessly — M0 spike, probe 1).
+ *
+ * ## No path defaults to a pass
+ *
+ * Every branch states its own verdict; there is no `??` fallback and no `else` that guesses. The
+ * four ways a probe can LOOK like a pass without being one, each closed here:
+ *
+ * 1. **A bypassed run.** `--dangerously-bypass-hook-trust` makes an UNTRUSTED hook fire, so a block
+ *    observed under it says nothing about the installed state (AM-1). Decided FIRST.
+ * 2. **Somebody else's block.** MEASURED (M0 §5): the runtime prefixes our stderr with its own
+ *    `Command blocked by PreToolUse hook: `. That phrase WITHOUT `DZ-VETO:` means *a* hook blocked,
+ *    not that ours did.
+ * 3. **A command that never ran.** "the model declined" and "the command was blocked" both show an
+ *    absent sentinel; only the transcript separates them (AM-36).
+ * 4. **A stale transcript.** Without this run's nonce the text is evidence about some other run.
+ *
+ * @packageDocumentation
+ */
+/** Our block marker. Must appear verbatim for a block to be attributed to dz. */
+export const DZ_VETO_MARKER = 'DZ-VETO:';
+/** The default-mode (warn) marker — a hit that did NOT block (G-J). */
+export const DZ_VETO_WARN_MARKER = 'DZ-VETO-WARN:';
+/** The runtime's generic block phrase. Present WITHOUT our marker ⇒ not our block. */
+export const RUNTIME_BLOCK_PHRASE = 'Command blocked by PreToolUse hook';
+/** Trust axis. Derived only from the runtime's own report, never from our emitter. */
+export function classifyTrust(status) {
+    switch (status) {
+        case 'trusted':
+        case 'managed':
+            return 'trusted';
+        case 'untrusted':
+        case 'modified':
+            return 'trust-pending';
+        default:
+            return 'unknown';
+    }
+}
+/** Classify one probe run. Exhaustive; no branch falls through to a pass. */
+export function classifyVetoProbe(e) {
+    const transcript = typeof e.transcript === 'string' ? e.transcript : '';
+    // 1. A bypassed run is a DIAGNOSTIC, never a verdict (AM-1). Decided before any other evidence.
+    if (e.bypassedTrust === true) {
+        return {
+            verdict: 'inconclusive',
+            trust: 'unknown',
+            reason: 'run used --dangerously-bypass-hook-trust: it proves the helper body works, not that the installed entry is armed',
+        };
+    }
+    const trust = classifyTrust(e.trustStatus);
+    // 2. Stale facts are not facts (AM-10).
+    const recorded = e.recordedCodexVersion;
+    const probed = e.probedCodexVersion;
+    if (typeof recorded === 'string' && typeof probed === 'string' && recorded !== probed) {
+        return {
+            verdict: 'inconclusive',
+            trust,
+            reason: `codex version mismatch: manifest recorded ${recorded}, runtime reports ${probed} — re-probe before trusting the verdict`,
+        };
+    }
+    // 3. A stale or foreign transcript cannot grade THIS run.
+    if (typeof e.nonce !== 'string' || e.nonce === '' || !transcript.includes(e.nonce)) {
+        return {
+            verdict: 'inconclusive',
+            trust,
+            reason: "transcript does not carry this run's nonce — it is not evidence about this run",
+        };
+    }
+    // 4. "the command never ran" and "the command was blocked" both show an absent sentinel (AM-36).
+    if (e.shellAttempted !== true) {
+        return {
+            verdict: 'inconclusive',
+            trust,
+            reason: 'transcript shows no shell attempt: the model declined or rewrote the command — re-drive the probe',
+        };
+    }
+    const ourMarker = transcript.includes(DZ_VETO_MARKER);
+    // 5. Somebody ELSE's block is not ours (MEASURED: the runtime prefixes our stderr, M0 §5).
+    if (!ourMarker && transcript.includes(RUNTIME_BLOCK_PHRASE)) {
+        return {
+            verdict: 'inconclusive',
+            trust,
+            reason: `a PreToolUse hook blocked the command but the transcript carries no ${DZ_VETO_MARKER} marker — the block is not attributable to dz`,
+        };
+    }
+    if (ourMarker) {
+        if (e.sentinelPresent === true) {
+            return {
+                verdict: 'inconclusive',
+                trust,
+                reason: 'contradictory evidence: our block marker is present AND the sentinel side effect landed',
+            };
+        }
+        return {
+            verdict: 'armed',
+            trust,
+            reason: 'our marker present and the sentinel absent: the forbidden command was blocked by the dz hook',
+        };
+    }
+    // 6. No marker, and the command demonstrably ran.
+    if (e.sentinelPresent === true) {
+        return {
+            verdict: 'not-armed',
+            trust,
+            reason: 'the forbidden command ran to completion (sentinel present) with no dz block marker',
+        };
+    }
+    // 7. Attempted, no marker, no sentinel: something swallowed it. Missing evidence is not clean evidence.
+    return {
+        verdict: 'inconclusive',
+        trust,
+        reason: 'shell was attempted but neither a dz block marker nor the sentinel is present — evidence is missing, not clean',
+    };
+}
+/**
+ * Exit map (ADR-002 §5). `0` demands BOTH axes: an `armed` run whose entry is only `trust-pending`
+ * exits non-zero, because the next session may not fire it.
+ */
+export function verifyExitCode(r) {
+    if (r.verdict === 'armed' && r.trust === 'trusted')
+        return 0;
+    if (r.verdict === 'inconclusive')
+        return 3;
+    return 1;
+}
+/** True only for the one outcome that may print a success word (AM-17 / G-G). */
+export function isReadyVerdict(r) {
+    return r.verdict === 'armed' && r.trust === 'trusted';
+}
+//# sourceMappingURL=codex-hooks-verify.js.map

package/dist/codex-hooks-verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-hooks-verify.js","sourceRoot":"","sources":["../src/codex-hooks-verify.ts"],"names":[],"mappings":"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"}