@dzhechkov/harness-core 0.4.4 → 0.5.0

package/src/parity.ts

@@ -23,7 +23,13 @@ import type { TargetName } from './targets.js';
 export type RuntimeCapability =
   | 'shell' // can run the dz CLI, i.e. a shell WITH Node.js (what `npm i -g` implies on a dev machine)
   | 'skills' // consumes compiled skills (all adapters emit them; agents-md as one merged file)
-  | 'hooks' // pre/post tool-call hooks (auto claim-check, auto recall apply-leg)
+  // The blanket `hooks` capability is deliberately GONE (AM-21). The matrix is COMPUTED, so one
+  // word here moves several cells: granting a target `hooks` promoted BOTH `claim-check` (a
+  // GATE_FEATURE_IDS member) and `learning-apply` to `full` in one edit, and a caveat comment
+  // cannot move a computed cell back.
+  | 'hooks-write' // PreToolUse on FILE writes — what claim-check's automatic form needs
+  | 'hooks-shell' // PreToolUse on SHELL commands — what the codex veto leg ships
+  | 'hooks-prompt' // UserPromptSubmit — what the auto-recall apply leg ships
   | 'mcp' // Model Context Protocol client exists on the platform (servers still need configuring)
   | 'mcp-configured' // our MCP servers (AgentDB / agentic-qe) are wired up out of the box (.mcp.json)
   | 'workflows' // deterministic multi-agent Workflow runtime (ultracode feature-adr, delivery gate)
@@ -33,7 +39,9 @@ export type RuntimeCapability =
 export const RUNTIME_CAPABILITIES: readonly RuntimeCapability[] = [
   'shell',
   'skills',
-  'hooks',
+  'hooks-write',
+  'hooks-shell',
+  'hooks-prompt',
   'mcp',
   'mcp-configured',
   'workflows',
@@ -47,9 +55,18 @@ export const RUNTIME_CAPABILITIES: readonly RuntimeCapability[] = [
 export const TARGET_CAPABILITIES: Record<TargetName, readonly RuntimeCapability[]> = {
   // Daily-driven harness: hooks (claim-check PreToolUse, recall UserPromptSubmit), MCP servers,
   // Workflow runtime and the statusline are all exercised in this repo every session.
-  'claude-code': ['shell', 'skills', 'hooks', 'mcp', 'mcp-configured', 'workflows', 'statusline'],
+  'claude-code': ['shell', 'skills', 'hooks-write', 'hooks-shell', 'hooks-prompt', 'mcp', 'mcp-configured', 'workflows', 'statusline'],
   // MCP subsystem probed live: `codex mcp --help` + `codex mcp list` answer (2026-07-19).
-  codex: ['shell', 'skills', 'mcp'],
+  // hooks-shell + hooks-prompt: user-global `$CODEX_HOME/hooks.json`, installed and ARMED
+  // unattended, proved by a live two-sided block probe (2026-08-19, codex-cli 0.147.0 — the
+  // transcripts named in CAPABILITY_EVIDENCE). `hooks-write` is NOT granted: this leg ships no
+  // PreToolUse guard on Write/Edit, so `claim-check` stays `manual` on codex.
+  //
+  // Fact CORRECTED 2026-08-19: a project-level `<repo>/.codex/hooks.json` DOES load on 0.147.0
+  // (`source: "project"`, MEASURED). The earlier note that project-level files are ignored was
+  // measured on 0.144.6 and is stale. dz still writes only the user-global registry, but that is
+  // now a DECISION (one carrier, one removable unit) rather than a description of the runtime.
+  codex: ['shell', 'skills', 'mcp', 'hooks-shell', 'hooks-prompt'],
   // Conservative v1: skills emission verified by the adapters; richer runtimes unproven.
   opencode: ['shell', 'skills'],
   hermes: ['shell', 'skills'],
@@ -62,6 +79,103 @@ export const TARGET_CAPABILITIES: Record<TargetName, readonly RuntimeCapability[
   windsurf: ['shell', 'skills'],
 };
 
+/**
+ * WHY each capability grant is believed, as machine-readable DATA (AM-22).
+ *
+ * `parity.ts` has declared an honesty contract in prose since day one — *"a capability flag states
+ * only what has been VERIFIED, each with its source in a comment"*. A comment is documentation, not
+ * a gate. The pinned map in `parity.test.ts` catches an ACCIDENTAL capability, but updating a pin is
+ * a mechanical edit that demands no evidence, so the contract had no layer-1 half.
+ *
+ * This is that half. `parity_no_capability_grant_without_evidence` fails when a target declares a
+ * capability with no record here, when a `transcript` record points at a file that does not exist,
+ * or when **any cell computes `full` on a target whose deciding capability has no transcript**.
+ *
+ * `kind: 'transcript'` means a recorded live run is on disk at `evidence`; `kind: 'reproducer'`
+ * means `evidence` is a command anyone can re-run.
+ */
+export interface CapabilityEvidence {
+  readonly evidence: string;
+  readonly kind: 'transcript' | 'reproducer';
+  /** ISO date the evidence was produced. Stale evidence is still evidence — silence is not. */
+  readonly at: string;
+}
+
+export const CAPABILITY_EVIDENCE: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = {
+  'claude-code': {
+    shell: { evidence: 'dz --version', kind: 'reproducer', at: '2026-07-19' },
+    skills: { evidence: 'dz compose --target claude-code', kind: 'reproducer', at: '2026-07-19' },
+    'hooks-write': { evidence: 'grep -n claim-check-hook .claude/settings.json', kind: 'reproducer', at: '2026-07-19' },
+    'hooks-shell': { evidence: 'grep -n PreToolUse .claude/settings.json', kind: 'reproducer', at: '2026-07-19' },
+    'hooks-prompt': { evidence: 'grep -n recall-hook.cjs .claude/settings.json', kind: 'reproducer', at: '2026-07-19' },
+    mcp: { evidence: 'cat .mcp.json', kind: 'reproducer', at: '2026-07-19' },
+    'mcp-configured': { evidence: 'cat .mcp.json', kind: 'reproducer', at: '2026-07-19' },
+    workflows: { evidence: 'ls .claude/workflows/feature-adr.js', kind: 'reproducer', at: '2026-07-19' },
+    statusline: { evidence: 'dz statusline', kind: 'reproducer', at: '2026-07-19' },
+  },
+  codex: {
+    shell: { evidence: 'codex exec -m <id> "Reply with exactly: OK"', kind: 'reproducer', at: '2026-07-19' },
+    skills: { evidence: 'dz compose --target codex', kind: 'reproducer', at: '2026-07-19' },
+    mcp: { evidence: 'codex mcp list', kind: 'reproducer', at: '2026-07-19' },
+    // The two-sided live block: our marker in the transcript AND the sentinel side effect absent,
+    // in a NON-bypassed run, with the entry reported `trusted` by codex's own `hooks/list`.
+    'hooks-shell': {
+      evidence: 'features/crossrt-2-codex-hooks/07_code_changes/probe-results/veto-armed.txt',
+      kind: 'transcript',
+      at: '2026-08-19',
+    },
+    'hooks-prompt': {
+      evidence: 'features/crossrt-2-codex-hooks/07_code_changes/probe-results/recall-canary.md',
+      kind: 'transcript',
+      at: '2026-08-19',
+    },
+  },
+  opencode: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target opencode', kind: 'reproducer', at: '2026-07-19' } },
+  hermes: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target hermes', kind: 'reproducer', at: '2026-07-19' } },
+  openclaude: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target openclaude', kind: 'reproducer', at: '2026-07-19' } },
+  copilot: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target copilot', kind: 'reproducer', at: '2026-07-19' } },
+  'agents-md': { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target agents-md', kind: 'reproducer', at: '2026-07-19' } },
+  cursor: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target cursor', kind: 'reproducer', at: '2026-07-19' } },
+  gemini: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target gemini', kind: 'reproducer', at: '2026-07-19' } },
+  windsurf: { shell: { evidence: 'adapter emit', kind: 'reproducer', at: '2026-07-19' }, skills: { evidence: 'dz compose --target windsurf', kind: 'reproducer', at: '2026-07-19' } },
+};
+
+export interface UnbackedCapability {
+  readonly target: TargetName;
+  readonly capability: RuntimeCapability;
+  readonly reason: 'no-evidence-record' | 'dangling-transcript';
+  readonly evidence?: string;
+}
+
+/**
+ * Every capability grant that is NOT backed by usable evidence.
+ *
+ * PURE, with the filesystem injected as `transcriptExists`. That is deliberate: the property this
+ * enforces — *a grant with a dangling transcript is not a grant* — has to be provable without a
+ * repository on disk, or the mutation gate (which copies the PACKAGE, not the repo) could never
+ * turn its mutant red, and an unkillable mutant is a false green wearing a gate's clothes.
+ */
+export function findUnbackedCapabilities(
+  transcriptExists: (path: string) => boolean,
+  capabilities: Record<TargetName, readonly RuntimeCapability[]> = TARGET_CAPABILITIES,
+  evidence: Record<TargetName, Partial<Record<RuntimeCapability, CapabilityEvidence>>> = CAPABILITY_EVIDENCE,
+): UnbackedCapability[] {
+  const out: UnbackedCapability[] = [];
+  for (const target of Object.keys(capabilities) as TargetName[]) {
+    for (const capability of capabilities[target]) {
+      const record = evidence[target]?.[capability];
+      if (record === undefined) {
+        out.push({ target, capability, reason: 'no-evidence-record' });
+        continue;
+      }
+      if (record.kind === 'transcript' && !transcriptExists(record.evidence)) {
+        out.push({ target, capability, reason: 'dangling-transcript', evidence: record.evidence });
+      }
+    }
+  }
+  return out;
+}
+
 /** How a feature manifests on a platform: a concrete FORM with its runtime requirements. */
 export interface FeatureForm {
   /** Human-readable name of the form, shown as the `via` of a parity cell (AM-2). */
@@ -124,7 +238,7 @@ export const PARITY_FEATURES: readonly ParityFeature[] = [
     id: 'claim-check',
     title: 'Integrity claim-check',
     forms: [
-      { form: 'PreToolUse hook (automatic on Write/Edit)', requires: ['hooks'], level: 'full' },
+      { form: 'PreToolUse hook (automatic on Write/Edit)', requires: ['hooks-write'], level: 'full' },
       { form: 'dz claim-check (CLI) + publish gate', requires: ['shell'], level: 'manual' },
     ],
   },
@@ -137,7 +251,7 @@ export const PARITY_FEATURES: readonly ParityFeature[] = [
     id: 'learning-apply',
     title: 'Self-learning: automatic apply-leg',
     forms: [
-      { form: 'UserPromptSubmit hook (auto recall)', requires: ['hooks'], level: 'full' },
+      { form: 'UserPromptSubmit hook (auto recall)', requires: ['hooks-prompt'], level: 'full' },
       { form: 'manual dz recall before a task', requires: ['shell'], level: 'manual' },
     ],
   },

package/src/recall-usage.ts

@@ -13,13 +13,26 @@
  * @packageDocumentation
  */
 
+// STATIC node: imports, deliberately (2026-08-19). A deferred `require('node:fs')` here compiled
+// into an ESM dist, where `require` is NOT in scope: every call from the emitted `.cjs` hook threw
+// ReferenceError into `appendRecallUsage`'s own catch and returned **0 rows appended, silently**.
+// The Codex recall leg looked wired and correctly-silent for exactly the reason AM-4's forced-hit
+// canary exists to expose. Importing node: modules at the top costs nothing — they are built in.
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
 import {
+  EMPTY_LOG_TAIL,
   EVENT_CHAIN_FIELD_OVERHEAD_BYTES,
   EVENT_CHAIN_LEDGER_KIND,
+  EVENT_CHAIN_TAIL_BYTES,
+  appendChainedLines,
   chainRewrite,
   defaultEventWeight,
+  readTailInfo,
   verifyEventChainText,
   type EventChainDefect,
+  type LogTail,
 } from './event-chain.js';
 
 export const RECALL_USAGE_LOG_RELATIVE = '.dz/recall-usage.jsonl';
@@ -45,6 +58,35 @@ export interface RecallUsageReadRecord {
   readonly eventId?: string;
   /** True when the stored query is a PREFIX of the real prompt — not replayable. */
   readonly queryTruncated?: boolean;
+  /**
+   * WHICH HOST injected the lesson (ADR-003 §1, H-B additive). Absent ⇒ `claude-code`, so every row
+   * written before the Codex leg keeps its meaning without a migration.
+   */
+  readonly runtime?: Runtime;
+}
+
+/** The hosts that run the apply leg. Additive by design: an old reader ignores the field. */
+export type Runtime = 'claude-code' | 'codex';
+
+export const RUNTIMES: readonly Runtime[] = ['claude-code', 'codex'];
+
+/** A row without `runtime` predates the Codex leg and is Claude Code's by construction. */
+export function runtimeOf(record: RecallUsageReadRecord): Runtime {
+  return record.runtime ?? 'claude-code';
+}
+
+function normalizeRuntime(value: unknown): Runtime | undefined {
+  return value === 'claude-code' || value === 'codex' ? value : undefined;
+}
+
+function normalizeRuntimes(value: unknown): readonly Runtime[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const set = new Set<Runtime>();
+  for (const v of value) {
+    const r = normalizeRuntime(v);
+    if (r !== undefined) set.add(r);
+  }
+  return set.size === 0 ? undefined : [...set].sort();
 }
 
 /** Query text is capped so a pasted wall of text cannot bloat the log. */
@@ -59,6 +101,21 @@ export interface RecallUsageAggregateRecord {
   readonly maxScore: number;
   readonly totalScore: number;
   readonly compactedAt: string;
+  /**
+   * The SET UNION of the runtimes whose reads were folded into this record (sorted, deduped).
+   *
+   * AM-27, and the whole reason it exists: `compactVerifiedRecallUsageLog` keeps verbatim only the
+   * newest {@link RECALL_USAGE_REPLAY_KEEP} read rows that carry a `query`. Everything else — a
+   * *fresh* row without `query` included — is folded into this record, whose merge key is `dzId`
+   * alone. The allowlist on the READ record therefore never touches the path where provenance is
+   * actually lost. The union does.
+   *
+   * Residual accepted loss, registered in `architecture/degradations.md`: this says WHICH runtimes
+   * used a lesson, not HOW OFTEN each did. Widening the merge key to `(dzId, runtime)` would split
+   * the stats rows `buildRecallUsageReport` looks up by `dzId` alone — a cross-feature blast radius
+   * this leg has no mandate for.
+   */
+  readonly runtimes?: readonly Runtime[];
 }
 
 export type RecallUsageRecord = RecallUsageReadRecord | RecallUsageAggregateRecord;
@@ -76,6 +133,8 @@ export interface RecallUsageStat {
   readonly lastReadAt: string;
   readonly maxScore: number;
   readonly avgScore: number;
+  /** Set union of contributing runtimes (AM-27). Empty ⇒ nothing carried provenance. */
+  readonly runtimes: readonly Runtime[];
 }
 
 export interface RecallPatternUsageRef {
@@ -115,6 +174,7 @@ interface Acc {
   lastMs: number;
   maxScore: number;
   totalScore: number;
+  runtimes: Set<Runtime>;
 }
 
 export interface RecallUsageRecordInput {
@@ -125,6 +185,7 @@ export interface RecallUsageRecordInput {
   readonly runId?: unknown;
   readonly eventId?: unknown;
   readonly queryTruncated?: unknown;
+  readonly runtime?: unknown;
 }
 
 /**
@@ -182,6 +243,7 @@ export function aggregateRecallUsage(records: readonly RecallUsageRecord[]): rea
       lastReadAt: a.lastReadAt,
       maxScore: a.maxScore,
       avgScore: a.totalScore / a.reads,
+      runtimes: [...a.runtimes].sort(),
     }))
     .sort(compareStats);
 }
@@ -397,6 +459,10 @@ function normalizeReadRecord(value: unknown): RecallUsageReadRecord | undefined
     ...(typeof runId === 'string' && runId.trim() !== '' ? { runId: runId.trim() } : {}),
     ...(typeof value['eventId'] === 'string' && (value['eventId'] as string).trim() !== '' ? { eventId: (value['eventId'] as string).trim() } : {}),
     ...(value['queryTruncated'] === true ? { queryTruncated: true } : {}),
+    // ALLOWLIST (AM-20): the normaliser is an allowlist and `compactVerifiedRecallUsageLog`
+    // re-serialises every retained row through it — a non-allowlisted field dies at the first
+    // compaction. Necessary, but NOT sufficient: see `runtimes` on the aggregate (AM-27).
+    ...(normalizeRuntime(value['runtime']) !== undefined ? { runtime: normalizeRuntime(value['runtime'])! } : {}),
   };
 }
 
@@ -413,7 +479,18 @@ function normalizeAggregateRecord(value: Record<string, unknown>): RecallUsageAg
   if (!validTs(firstReadAt) || !validTs(lastReadAt) || !validTs(compactedAt)) return undefined;
   if (typeof maxScore !== 'number' || !Number.isFinite(maxScore)) return undefined;
   if (typeof totalScore !== 'number' || !Number.isFinite(totalScore)) return undefined;
-  return { kind: 'aggregate', dzId: dzId.trim(), reads, firstReadAt, lastReadAt, maxScore, totalScore, compactedAt };
+  const runtimes = normalizeRuntimes(value['runtimes']);
+  return {
+    kind: 'aggregate',
+    dzId: dzId.trim(),
+    reads,
+    firstReadAt,
+    lastReadAt,
+    maxScore,
+    totalScore,
+    compactedAt,
+    ...(runtimes !== undefined ? { runtimes } : {}),
+  };
 }
 
 function mergeRead(byId: Map<string, Acc>, rec: RecallUsageReadRecord): void {
@@ -429,9 +506,11 @@ function mergeRead(byId: Map<string, Acc>, rec: RecallUsageReadRecord): void {
       lastMs: ms,
       maxScore: rec.score,
       totalScore: rec.score,
+      runtimes: new Set<Runtime>([runtimeOf(rec)]),
     });
     return;
   }
+  prev.runtimes.add(runtimeOf(rec));
   prev.reads += 1;
   prev.totalScore += rec.score;
   prev.maxScore = Math.max(prev.maxScore, rec.score);
@@ -459,9 +538,11 @@ function mergeAggregate(byId: Map<string, Acc>, rec: RecallUsageAggregateRecord)
       lastMs,
       maxScore: rec.maxScore,
       totalScore: rec.totalScore,
+      runtimes: new Set<Runtime>(rec.runtimes ?? []),
     });
     return;
   }
+  for (const r of rec.runtimes ?? []) prev.runtimes.add(r);
   prev.reads += rec.reads;
   prev.totalScore += rec.totalScore;
   prev.maxScore = Math.max(prev.maxScore, rec.maxScore);
@@ -485,6 +566,9 @@ function aggregateRecord(stat: RecallUsageStat, compactedAt: string): RecallUsag
     maxScore: stat.maxScore,
     totalScore: stat.avgScore * stat.reads,
     compactedAt,
+    // AM-27's mutant: dropping this union silently destroys per-runtime provenance at the first
+    // compaction, and the READ-record allowlist cannot save it because this path never sees one.
+    ...(stat.runtimes.length > 0 ? { runtimes: [...stat.runtimes].sort() } : {}),
   };
 }
 
@@ -535,3 +619,102 @@ function joinLines(lines: readonly string[]): string {
 function byteLength(text: string): number {
   return text.length;
 }
+
+/* ========================================================================== */
+/* The SHARED writer (`crossrt-2-codex-hooks`, ADR-003 · AM-6/AM-7)           */
+/* ========================================================================== */
+/*
+ * Everything above this line is pure. What follows is the ONE writer both hosts call, and it is
+ * here rather than in a helper because the alternative — a second inline appender per runtime — is
+ * exactly the drift AM-7 forbids: the Claude helper had the only implementation for 19 days and the
+ * Codex leg could not exist without either importing it or copying it.
+ *
+ * It NEVER throws. A hook that dies on a logging failure costs the user their turn, and the log is
+ * telemetry: losing a row is a smaller harm than losing a prompt.
+ */
+
+export interface AppendRecallUsageHit {
+  readonly dzId: unknown;
+  readonly score: unknown;
+}
+
+export interface AppendRecallUsageInput {
+  /** Project ROOT (the helper walks up to it; a cwd-relative writer splits the log — AM-5). */
+  readonly projectRoot: string;
+  readonly hits: readonly AppendRecallUsageHit[];
+  /** The host that injected. Omitted ⇒ `claude-code`, matching every pre-Codex row. */
+  readonly runtime?: Runtime;
+  readonly query?: string | undefined;
+  readonly runId?: string | undefined;
+  /** One id per PROMPT. Generated when absent so a multi-hit prompt still counts as one event. */
+  readonly eventId?: string | undefined;
+  readonly now?: string;
+  /** Test seam. Production leaves it unset and the path is derived from `projectRoot`. */
+  readonly logPath?: string;
+}
+
+/**
+ * Append one prompt's injected hits as CHAINED rows.
+ *
+ * @returns the number of rows appended; **0** on any failure (unwritable directory, unreadable
+ *          tail, empty input). Never throws.
+ */
+export function appendRecallUsage(input: AppendRecallUsageInput): number {
+  try {
+    const hits = Array.isArray(input?.hits) ? input.hits : [];
+    if (hits.length === 0) return 0;
+    const ts = validTs(input.now) ? input.now : new Date().toISOString();
+    const eventId =
+      typeof input.eventId === 'string' && input.eventId.trim() !== ''
+        ? input.eventId.trim()
+        : `${ts}:${Math.random().toString(36).slice(2, 10)}`;
+    const full = typeof input.query === 'string' ? input.query.trim() : '';
+    const query = full !== '' ? full.slice(0, RECALL_USAGE_QUERY_MAX_CHARS) : undefined;
+    const queryTruncated = full.length > RECALL_USAGE_QUERY_MAX_CHARS ? true : undefined;
+
+    const records: RecallUsageReadRecord[] = [];
+    for (const hit of hits) {
+      const rec = normalizeReadRecord({
+        dzId: hit?.dzId,
+        score: hit?.score,
+        ts,
+        query,
+        runId: input.runId,
+        eventId,
+        queryTruncated,
+        runtime: input.runtime ?? 'claude-code',
+      });
+      if (rec !== undefined) records.push(rec);
+    }
+    if (records.length === 0) return 0;
+
+    const logPath = input.logPath ?? join(input.projectRoot, ...RECALL_USAGE_LOG_RELATIVE.split('/'));
+    const payload = appendChainedLines(records, readLogTailSync(logPath));
+    if (payload === '') return 0;
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, payload, 'utf-8');
+    return records.length;
+  } catch {
+    return 0; // never-block outranks telemetry completeness
+  }
+}
+
+/** Read the chain tail. An UNREADABLE tail is a torn tail, never an empty one (event-chain AM-6). */
+function readLogTailSync(file: string): LogTail {
+  try {
+    if (!existsSync(file)) return EMPTY_LOG_TAIL;
+    const fd = openSync(file, 'r');
+    try {
+      const size = fstatSync(fd).size;
+      if (!Number.isFinite(size) || size <= 0) return EMPTY_LOG_TAIL;
+      const want = Math.min(size, EVENT_CHAIN_TAIL_BYTES);
+      const buf = Buffer.alloc(want);
+      readSync(fd, buf, 0, want, size - want);
+      return readTailInfo(buf.toString('utf-8'), { partial: want < size });
+    } finally {
+      try { closeSync(fd); } catch { /* nothing to do */ }
+    }
+  } catch {
+    return EMPTY_LOG_TAIL;
+  }
+}

package/src/setup.ts

@@ -19,6 +19,8 @@ import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node
 import { join } from 'node:path';
 import { execSync } from 'node:child_process';
 
+import { mergeManagedHookEntries } from './managed-hooks.js';
+
 /** Memory backend type. */
 export type MemoryBackend = 'jsonl' | 'agentdb';
 
@@ -567,35 +569,32 @@ export function runSetup(opts: SetupOptions): SetupResult {
     } else {
       try {
         const existing = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
-        const hooks = (existing['hooks'] ?? {}) as Record<string, unknown[]>;
-        let changed = false;
-        let replacedLegacy = false;
-        for (const event of Object.keys(generated.hooks)) {
-          const current = Array.isArray(hooks[event]) ? hooks[event] : [];
-          // Drop dz-generated entries (any vintage, either shape) — keep the user's own hooks
-          // untouched. Flat dz entries (≤0.3.43) are dropped too, migrating them to the valid
-          // matcher-group shape appended below.
-          const kept = current.filter((entry) => {
-            const cmds = commandsOf(entry);
-            const isDz = cmds.some((cmd) => cmd.includes('agentdb add') || cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl'));
-            const isFlat = !Array.isArray((entry as { hooks?: unknown[] })?.hooks);
-            if (isDz && (isFlat || cmds.some((cmd) => cmd.includes('agentdb add')))) replacedLegacy = true;
-            return !isDz;
-          });
-          const next = [...kept, ...generated.hooks[event]!];
-          if (JSON.stringify(next) !== JSON.stringify(current)) changed = true;
-          hooks[event] = next;
-        }
-        if (changed) {
-          existing['hooks'] = hooks;
+        // ONE merge implementation, shared with the Codex target (AM-3 / G-E). The Claude path's
+        // historical SUBSTRING attribution is passed IN verbatim rather than reimplemented, so the
+        // emitted bytes, the report tail string and the no-write path all stay identical (AM-37).
+        const plan = mergeManagedHookEntries(
+          (existing['hooks'] ?? {}) as Record<string, unknown[]>,
+          generated.hooks as unknown as Record<string, unknown[]>,
+          {
+            // Drop dz-generated entries (any vintage, either shape) — keep the user's own hooks
+            // untouched. Flat dz entries (≤0.3.43) are dropped too, migrating them to the valid
+            // matcher-group shape appended below.
+            isManaged: (entry) =>
+              commandsOf(entry).some(
+                (cmd) => cmd.includes('agentdb add') || cmd.includes('agentdb-writer.mjs') || cmd.includes('sessions.jsonl'),
+              ),
+            isLegacy: (entry) =>
+              !Array.isArray((entry as { hooks?: unknown[] })?.hooks) ||
+              commandsOf(entry).some((cmd) => cmd.includes('agentdb add')),
+            reportLabel: backend,
+          },
+        );
+        if (plan.changed) {
+          existing['hooks'] = plan.hooks;
           writeFileSync(settingsPath, JSON.stringify(existing, null, 2));
-          steps.push({
-            name: 'Configure hooks',
-            status: 'done',
-            detail: replacedLegacy ? `replaced legacy dz hooks with ${backend} hooks` : `merged ${backend} hooks (user hooks preserved)`,
-          });
+          steps.push({ name: 'Configure hooks', status: 'done', detail: plan.report });
         } else {
-          steps.push({ name: 'Configure hooks', status: 'skipped', detail: 'hooks already current' });
+          steps.push({ name: 'Configure hooks', status: 'skipped', detail: plan.report });
         }
       } catch {
         steps.push({ name: 'Configure hooks', status: 'error', detail: 'could not parse existing settings.json — fix it and re-run' });

package/src/shell-veto-policy.ts

@@ -0,0 +1,119 @@
+/**
+ * Shell veto policy (`crossrt-2-codex-hooks`, ADR-004 + ADR-005).
+ *
+ * ONE rule, judged on the raw command string, with no I/O of any kind. The mode — what the CALLER
+ * does with a hit — is decided by the caller from project config, never here.
+ *
+ * Polarity, in one sentence (ADR-004): **a policy hit ⇒ WARN by default, BLOCK only when the
+ * project opted in; our own failure ⇒ always ALLOW.**
+ *
+ * ## Why exactly one rule, and why this one
+ *
+ * `shell-veto-policy.ts` is NOT a general shell-guardrail engine (plan §0.1's C4 fence). Its
+ * charter is a single rule whose violation is **unambiguous**: the command line explicitly asks for
+ * WEAKER authentication than the ssh default. Every token below is one a safe invocation never
+ * contains, so a hit always means the user deliberately disabled a protection.
+ *
+ * The withdrawn v1 (`ssh-no-identity`, AM-23) judged the ABSENCE of `-i`/`IdentityFile=`, which
+ * blocked `ssh myhost` whenever the identity came from `~/.ssh/config` or `ssh-agent` — the normal
+ * secure case — from a user-global registry that reaches every directory on the machine. Absence of
+ * a token is not evidence of intent; presence of these four is.
+ *
+ * `StrictHostKeyChecking=no` and `UserKnownHostsFile=/dev/null` are deliberately NOT rules: they are
+ * a real weakening, but CI images use them legitimately, so no unambiguous verdict is available.
+ * They are the first candidates for a future rule with its own ADR — **no second rule ships in this
+ * leg**.
+ *
+ * @packageDocumentation
+ */
+
+/** What the caller does with a hit. `warn` is the shipped default (ADR-004). */
+export type VetoMode = 'off' | 'warn' | 'block';
+
+/** A policy hit. `null` from {@link vetoShellCommand} means allow. */
+export interface VetoHit {
+  readonly rule: string;
+  readonly reason: string;
+}
+
+/** The one rule id this leg ships. Exported so tests and the probe cannot drift from it. */
+export const SHELL_VETO_RULE_ID = 'ssh-explicit-auth-weakening';
+
+/**
+ * Shell word boundaries. Both ends of every token are anchored, so `echo "sshpassword"` and
+ * `--my-passwordauthentication=yes` cannot hit: a user-global guard that matches on a bare
+ * substring is one common word away from a machine-wide outage.
+ */
+const BOUNDARY = String.raw`[\s;&|()'"\`]`;
+const OPT = String.raw`(?:^|${BOUNDARY})-o\s*`;
+const END = String.raw`(?=$|${BOUNDARY})`;
+
+/** `-o PasswordAuthentication=yes` — the user turns ON password auth against the ssh default. */
+const PASSWORD_AUTHENTICATION = new RegExp(`${OPT}passwordauthentication\\s*=\\s*yes${END}`, 'i');
+
+/** `-o PubkeyAuthentication=no` — the user turns OFF key auth. */
+const PUBKEY_AUTHENTICATION = new RegExp(`${OPT}pubkeyauthentication\\s*=\\s*no${END}`, 'i');
+
+/** `-o PreferredAuthentications=…password…` — the user ORDERS password auth ahead of pubkey. */
+const PREFERRED_AUTHENTICATIONS = new RegExp(
+  `${OPT}preferredauthentications\\s*=\\s*` +
+    `(?:[a-z][a-z0-9-]*\\s*,\\s*)*` +
+    `(?:password|keyboard-interactive)` +
+    `(?:\\s*,\\s*[a-z][a-z0-9-]*)*${END}`,
+  'i',
+);
+
+/** `sshpass` as a COMMAND TOKEN — a password is fed to ssh from the command line by construction. */
+const SSHPASS_TOKEN = new RegExp(`(?:^|${BOUNDARY})sshpass${END}`, 'i');
+
+/**
+ * Judge one raw shell command.
+ *
+ * @returns a {@link VetoHit} when the command EXPLICITLY weakens ssh authentication, else `null`.
+ *          Pure: no filesystem, no environment, no config, no clock.
+ */
+export function vetoShellCommand(command: string): VetoHit | null {
+  if (typeof command !== 'string' || command === '') return null;
+
+  if (SSHPASS_TOKEN.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'sshpass feeds an ssh password from the command line, disabling key-based auth by construction',
+    };
+  }
+  if (PASSWORD_AUTHENTICATION.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'PasswordAuthentication=yes turns ON password auth against the ssh default',
+    };
+  }
+  if (PUBKEY_AUTHENTICATION.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'PubkeyAuthentication=no turns OFF key auth',
+    };
+  }
+  if (PREFERRED_AUTHENTICATIONS.test(command)) {
+    return {
+      rule: SHELL_VETO_RULE_ID,
+      reason: 'PreferredAuthentications orders password/keyboard-interactive auth ahead of pubkey',
+    };
+  }
+  return null;
+}
+
+/**
+ * Resolve the enforcement mode from a parsed `.dz/config.json`.
+ *
+ * ABSENT, unknown, non-string, or malformed ⇒ `'warn'`. Never `'block'` by default: fail-closed is
+ * a decision the owner makes, not one a user-global hook install imposes on every directory
+ * (ADR-004 / AM-24). A mutant that flips this default is registered in the mutation registry.
+ */
+export function resolveVetoMode(projectConfig: unknown): VetoMode {
+  if (typeof projectConfig !== 'object' || projectConfig === null) return 'warn';
+  const hooks = (projectConfig as Record<string, unknown>)['hooks'];
+  if (typeof hooks !== 'object' || hooks === null) return 'warn';
+  const mode = (hooks as Record<string, unknown>)['shellVeto'];
+  if (mode === 'off' || mode === 'warn' || mode === 'block') return mode;
+  return 'warn';
+}