@dzhechkov/harness-core 0.4.5 → 0.5.0

package/dist/operations.js

@@ -5,8 +5,12 @@
  *
  * @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, } 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';
@@ -17,11 +21,12 @@ 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 { computeRiskScore } from './risk-scoring.js';
 import { applyEmitResult } from './apply.js';
-import { discoverSkillIds, loadSkillFromDir } from './skills.js';
+import { describeSkillLoadFailure, discoverSkillIds, loadSkillFromDir } from './skills.js';
 import { TARGETS } from './targets.js';
+import { AGENTS_MD_BUDGET_WARN_FRACTION, CODEX_PROJECT_DOC_MAX_BYTES, POLICY_SOURCES, detectPolicyDrift, extractPolicyBlocks, measureAgentsMdBudget, renderPolicySections, } from './agents-policy.js';
 // ---------------------------------------------------------------------------
 // Platform enrichment — optional extras beyond SKILL.md
 // ---------------------------------------------------------------------------
@@ -121,6 +126,26 @@ function enrichEmitForTarget(emit, target, skillId, skill) {
         warnings: [...emit.warnings, `enriched: ${extra.length} platform-specific file(s) for ${target}`],
     };
 }
+/**
+ * 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, sections, config, options = {}) {
+    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
@@ -170,19 +195,24 @@ function runInitSingleFileMd(options, config) {
         }
     }
     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 = [];
+    const loaded = [];
+    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 = picked.map(({ id }, index) => {
+    const skills = loaded.map(({ id }, index) => {
         const owns = index === 0;
         return {
             id,
@@ -191,7 +221,9 @@ function runInitSingleFileMd(options, config) {
             warnings: owns ? [config.lossyWarning] : [],
         };
     });
-    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: [] };
 }
 /**
  * Aggregate every selected skill into ONE root `AGENTS.md`, merging into any
@@ -220,6 +252,88 @@ export function runInitGeminiMd(options) {
         lossyWarning: GEMINI_MD_LOSSY_WARNING,
     });
 }
+/**
+ * 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) {
+    const sources = options.sources ?? POLICY_SOURCES;
+    const sourceFiles = new Map();
+    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 = 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 = [];
+    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) {
     // agents-md is a flattening single-file target — aggregate all selected skills
@@ -248,19 +362,43 @@ export async function runInit(options) {
     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 = [];
+    const applyFailures = [];
     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 };
 }
 /** Compile every skill for `target` and report whether each verifies. */
 export async function runVerify(options) {
@@ -295,9 +433,18 @@ export async function runVerify(options) {
 export async function runSync(options) {
     const dirs = options.canonicalDirs ?? (options.canonicalDir ? [options.canonicalDir] : []);
     const skills = [];
+    // Skip-and-collect (D1): a broken canonical skill must not hide every other pack.
+    const failures = [];
     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;
             let missing = false;
@@ -323,6 +470,7 @@ export async function runSync(options) {
     return {
         dryRun: options.dryRun === true,
         skills,
+        failures,
         summary: {
             total: skills.length,
             inSync: skills.filter((skill) => skill.status === 'in-sync').length,
@@ -526,6 +674,38 @@ export async function runDoctor(options) {
         }
     }
     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');
@@ -621,4 +801,360 @@ export async function runDoctor(options) {
     catch { /* advisory only — the vector tier must never fail doctor */ }
     return { node: process.version, checks, ok: checks.every((check) => check.ok) };
 }
+function resolveCodexHome(explicit) {
+    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() {
+    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, payload) {
+    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?.message ?? err) };
+    }
+}
+/** Keep the newest N backups; older ones are litter in the user's home (AM-35b). */
+function pruneBackups(dir, prefix, keep) {
+    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 = {}) {
+    const codexHome = resolveCodexHome(options.codexHome);
+    const paths = codexHooksPaths(codexHome);
+    const warnings = [];
+    const errors = [];
+    const writes = [];
+    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: [],
+        trust: 'unknown',
+        codexVersion: null,
+        writes: [],
+    };
+    // (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.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 = 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', rows: [], warnings: [] }
+        : armCodexHookTrust(paths, entries, writes);
+    for (const w of trustResult.warnings)
+        warnings.push(w);
+    const trustKeys = {};
+    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 = 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, text) {
+    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, body, writes) {
+    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, currentText, now, writes) {
+    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, entries, writes) {
+    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, cwd = process.cwd()) {
+    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);
+        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) {
+    try {
+        if (!existsSync(logPath))
+            return { hasCodexRow: false };
+        const lines = readFileSync(logPath, 'utf-8').split('\n');
+        let newest;
+        let hasCodexRow = false;
+        for (const line of lines) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const rec = JSON.parse(line);
+                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 };
+    }
+}
 //# sourceMappingURL=operations.js.map