@dzhechkov/harness-core 0.4.4 → 0.5.0

package/src/operations.ts

@@ -6,9 +6,27 @@
  * @packageDocumentation
  */
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+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 {
+  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 { AGENTS_MD_PATH } from '@dzhechkov/adapter-agents-md';
 import { claudeAdapter } from '@dzhechkov/adapter-claude';
 import { CODEX_SKILLS_ROOT } from '@dzhechkov/adapter-codex';
@@ -19,14 +37,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 +98,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 +264,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 +351,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 +379,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 +413,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 +552,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 +676,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 +722,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 +971,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 +1097,429 @@ 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;
+}
+
+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;
+  /** 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[];
+}
+
+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).
+ */
+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[],
+  };
+
+  // (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 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);
+    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,
+      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);
+    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';
+    return {
+      ...base,
+      codexVersion,
+      installed: drift.installed,
+      executable,
+      trust: checkTrust,
+      foreignPreserved: drift.foreignPreserved,
+      unattributable: drift.unattributable,
+      drift: drift.drifted,
+      // 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,
+      errors,
+      writes,
+    };
+  }
+
+  // (5) Install. Parse-refuse BEFORE any mkdir (I1: an unparseable file must not be overwritten).
+  const planned = planCodexHooks({ currentText, entries, manifest });
+  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`,
+      ],
+    };
+  }
+
+  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);
+  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`;
+  atomicWrite(paths.manifest, manifestText);
+  writes.push(paths.manifest);
+
+  const drift = diffCodexHooks(readFileSync(paths.registry, 'utf8'), entries, undefined);
+  const installed = drift.installed;
+  const exitCode: 0 | 1 | 3 = installed && executable && trustResult.trust === 'trusted' ? 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,
+    exitCode,
+    warnings,
+    errors,
+    writes,
+  };
+}
+
+/** 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[] } {
+  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);
+  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`],
+    };
+  }
+  const configText = existsSync(paths.configToml) ? readFileSync(paths.configToml, 'utf8') : '';
+  const next = upsertTrustBlock(
+    configText,
+    own.map((o) => ({ key: o.meta.key, trustedHash: o.meta.currentHash })),
+  );
+  if (next !== configText) {
+    atomicWrite(paths.configToml, next);
+    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 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 })),
+    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 };
+  }
+}