@event4u/agent-config 16.0.0 → 16.1.0

package/src/install/recordedOwnership.ts

@@ -0,0 +1,149 @@
+/**
+ * Recorded-ownership classification — road-to-a-conformance-check-that-can-fail
+ * Phase 5.
+ *
+ * The install conflict matrix decided ownership by **path-set membership**:
+ * `policy.knownPaths.has(targetPath)`. That answers "did we ever write here",
+ * which collapses two materially different trees into one row — a managed file
+ * still carrying the bytes we wrote, and a managed file the user has since
+ * edited. The second is a data-loss surface and the first is not, and the
+ * matrix could not tell them apart because a path set carries no content.
+ *
+ * This module is the plumbing half: read the per-file SHA-256 the install
+ * manifest already records, and compare it against a digest the caller
+ * computed. It changes no install behaviour on its own — the matrix wiring
+ * lands separately (Phase 5.2), so the behaviour change is reviewable as a
+ * diff that contains no hash computation.
+ *
+ * Why a local YAML read rather than `installed_tools.read_manifest()`: that
+ * reader is a hand-rolled parser with no YAML dependency, and it drops nested
+ * `files[]` entries by design (a degraded read that ADR-200 documents as
+ * intentional). It therefore cannot supply a recorded hash at all. Reading
+ * the same file with the `yaml` package — already a runtime dependency — is
+ * additive and leaves that reader's byte-exact golden tests untouched.
+ *
+ * `src/scripts/_lib/install_drift.ts` reads the same field of the same file
+ * for the same reason, and this module is a second reader rather than a
+ * caller of it because `collect_drift` computes the digests itself and
+ * returns only the entries that drifted. The conflict matrix needs the
+ * opposite: every recorded digest, and no hashing, because the digest it
+ * compares against is one the caller already has. What this module does NOT
+ * duplicate is that module's stated invariant — `manifest_path()` stays the
+ * one place that decides where the manifest is, so the
+ * `AGENT_CONFIG_INSTALLED_TOOLS` override and `~` expansion behave
+ * identically in both.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import * as YAML from 'yaml';
+
+import { manifest_path, type EnvMap } from '../scripts/_lib/installed_tools.js';
+
+/**
+ * How the install matrix owns a target on disk.
+ *
+ * - `recorded-unchanged` — the manifest records this path and the bytes on
+ *   disk still match the digest it recorded. Ours, untouched.
+ * - `recorded-modified`  — the manifest records this path and the bytes have
+ *   changed since. Ours, edited by someone. Overwriting loses their work.
+ * - `unknown`            — the manifest does not record this path, or records
+ *   it without a digest (bridges carry `sha256: null`), or the bytes could not
+ *   be read. Not an assertion that the file is foreign — an assertion that
+ *   this tree cannot say.
+ */
+export type RecordedOwnership = 'recorded-unchanged' | 'recorded-modified' | 'unknown';
+
+/** Absolute target path → the SHA-256 the manifest recorded (`null` for bridges). */
+export type RecordedHashes = ReadonlyMap<string, string | null>;
+
+/** The empty answer — "nothing is recorded", used whenever no manifest resolves. */
+export const NO_RECORDED_HASHES: RecordedHashes = new Map<string, string | null>();
+
+/**
+ * Classify one target from the recorded digest and the on-disk digest.
+ *
+ * Pure — the caller supplies both digests. `undefined` for `recordedSha256`
+ * means the path is not recorded at all; `null` means recorded without a
+ * digest. Both answer `unknown`, because neither supports a comparison.
+ */
+export function classifyOwnership(
+    recordedSha256: string | null | undefined,
+    onDiskSha256: string | null,
+): RecordedOwnership {
+    if (recordedSha256 === undefined || recordedSha256 === null) return 'unknown';
+    if (onDiskSha256 === null) return 'unknown';
+    return recordedSha256 === onDiskSha256 ? 'recorded-unchanged' : 'recorded-modified';
+}
+
+/**
+ * Read `tools[].files[]` out of an installed-tools manifest into a
+ * path → digest map.
+ *
+ * Relative paths resolve against `projectRoot` and a leading `~` expands
+ * first — the manifest stores user-scope entries absolute or `~`-rooted and
+ * project-scope entries relative, and both existing readers
+ * (`install_drift.resolve_entry_path`, `cmd_doctor._resolve_path`) resolve
+ * them that way. A missing, unreadable or malformed manifest yields the
+ * empty map rather than throwing — an install plan must never fail because a
+ * lockfile is corrupt.
+ */
+export function readRecordedHashes(manifestPath: string, projectRoot: string): RecordedHashes {
+    if (!existsSync(manifestPath)) return NO_RECORDED_HASHES;
+    let doc: unknown;
+    try {
+        doc = YAML.parse(readFileSync(manifestPath, 'utf8'));
+    } catch {
+        return NO_RECORDED_HASHES;
+    }
+    if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return NO_RECORDED_HASHES;
+    const tools = (doc as Record<string, unknown>)['tools'];
+    if (!Array.isArray(tools)) return NO_RECORDED_HASHES;
+
+    const out = new Map<string, string | null>();
+    for (const tool of tools) {
+        if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) continue;
+        const files = (tool as Record<string, unknown>)['files'];
+        if (!Array.isArray(files)) continue;
+        for (const entry of files) {
+            if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue;
+            const rec = entry as Record<string, unknown>;
+            const raw = rec['path'];
+            if (typeof raw !== 'string' || raw.length === 0) continue;
+            const sha = rec['sha256'];
+            const expanded = expanduser(raw);
+            const target = isAbsolute(expanded)
+                ? resolve(expanded)
+                : resolve(projectRoot, expanded);
+            out.set(target, typeof sha === 'string' && sha.length > 0 ? sha : null);
+        }
+    }
+    return out;
+}
+
+/** Expand a leading `~`, matching `installed_tools.expanduser`. */
+function expanduser(p: string): string {
+    if (p === '~') return homedir();
+    if (p.startsWith('~/') || (process.platform === 'win32' && p.startsWith('~\\'))) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
+
+/**
+ * {@link readRecordedHashes} for a PROJECT root, via `installed_tools`.
+ *
+ * `manifest_path` carries the `AGENT_CONFIG_INSTALLED_TOOLS` override, so an
+ * install running against a relocated manifest classifies ownership instead
+ * of degrading every file to `unknown`.
+ *
+ * The argument must be a project root. An {@link InstallPlan.root} for a
+ * `global` target is the install anchor (`~/.event4u/agent-config/`), which
+ * holds no manifest — such a plan gets the empty map and therefore the
+ * pre-hash answer, which is correct but is a floor rather than a feature.
+ */
+export function recordedHashesForRoot(root: string, env?: EnvMap | null): RecordedHashes {
+    return readRecordedHashes(manifest_path(root, env), root);
+}

package/src/install/txlog.ts

@@ -2,8 +2,17 @@
  * Transaction log — Phase A4 (council Finding #18).
  *
  * Append-only JSONL at `getLogPath()` (`~/.event4u/agent-config/install-log.jsonl`).
- * Each successful atomic write appends one entry; recovery on crash is
- * `tail -n` + reverse-apply. No PID lockfile (per Phase-A4 decision 8).
+ * Recovery on crash is `tail -n` plus the wizard's resume / dismiss decision —
+ * nothing is un-written automatically. No PID lockfile (per Phase-A4
+ * decision 8).
+ *
+ * WHAT ACTUALLY WRITES THIS FILE, as of 2026-09-15: two call sites.
+ * `src/server/routes/install.ts`'s recovery-dismiss handler appends a
+ * `rollback` marker with an empty path and a null hash; `src/scripts/install.ts`
+ * — the surviving headless writer, per-file, through `_log_tx_entry` — appends
+ * a `write` or `skip` entry per copied/skipped path during
+ * `_copy_dir_dereferencing_symlinks`. Both call `appendTxLog` directly, so the
+ * entry shape is identical by construction rather than by convention.
  *
  * Rotation: 10 MB OR 30 days, whichever first. Rotated copies move to
  * `install-log.<ISO>.jsonl.gz` siblings; recovery never scans them.

package/src/install/types.ts

@@ -16,6 +16,9 @@
  *   - v2 manifest `files_by_tool` → {@link InstallPlan.filesByTool}
  */
 
+// Type-only — erased at compile time, so this module stays runtime-free.
+import type { RecordedOwnership } from './recordedOwnership.js';
+
 /**
  * Where the install lands.
  *
@@ -130,9 +133,11 @@ export interface InstallPlan {
  * Phase B3 — surfaced by the `/api/v1/install/plan` route so the wizard's
  * conflict screen can render single-pick / batch-resolution UI **before**
  * the apply phase opens the transaction log. A `ConflictEntry` means the
- * target exists, its bytes do not match the planned SHA, it is not in
- * `policy.knownPaths`, and `policy.force` is false — i.e. the policy
- * would surface this file to the UI during apply.
+ * target exists, its bytes do not match the planned SHA, `policy.force` is
+ * false, and the planner does not hold it as ours-and-unchanged — i.e. the
+ * policy would surface this file to the UI. Since `ownership` landed it is
+ * NO LONGER equivalent to "not in `policy.knownPaths`": a `recorded-modified`
+ * entry is emitted precisely when the path IS in that set.
  *
  * `mergeable` is `true` only for `.json` deployed files; the wizard
  * shows the per-row `merge` button only on those. `existingSha256` is
@@ -145,6 +150,15 @@ export interface ConflictEntry {
     readonly plannedSha256: string | null;
     readonly existingSha256: string | null;
     readonly mergeable: boolean;
+    /**
+     * Three-state ownership from the manifest's recorded digest — the column
+     * path-set membership could not produce (Phase 5.1 of
+     * road-to-a-conformance-check-that-can-fail). `recorded-modified` is the
+     * row that matters: a file we wrote that someone has since edited.
+     * `unknown` reproduces the pre-hash answer and is what every tree without
+     * a readable manifest reports.
+     */
+    readonly ownership: RecordedOwnership;
 }
 
 /**
@@ -164,7 +178,8 @@ export type ConflictResolution = 'skip' | 'overwrite' | 'merge';
  * Result of applying an {@link InstallPlan}.
  *
  * Surfaced to the wizard's progress bar (Phase B1) and recorded in the
- * transaction log (Phase A4) so recovery can reverse-apply on crash.
+ * transaction log (Phase A4) so a crashed run's tail can be surfaced to
+ * the wizard's recovery screen.
  */
 export interface ApplyResult {
     readonly target: InstallTarget;

package/src/scripts/_cli/cmd_conformance.ts

@@ -6,7 +6,9 @@
  * consumer-facing checks that answer ONE question deterministically:
  * "is agent-config installed AND firing in this repo?"
  *
- *   (a) txlog-clean          — install log tail carries no abandoned run
+ *   (a) txlog-clean          — install log tail carries no abandoned run;
+ *                              an absent log on an installed tree is `unknown`,
+ *                              not green (see `_check_txlog_clean`)
  *   (b) router-pointers      — dist/router.json ids + routes_to resolve on disk
  *   (c) hook-dispatcher      — dispatcher answers synthetic session_start/stop
  *   (d) lean-projection      — lean_projection.mode matches projected artifacts
@@ -75,6 +77,21 @@ export const CONFORMANCE_CHECK_IDS = [
 /** Marker emitted by `project_thin_rules.thin_entry()` — the thin-stub signature. */
 export const THIN_STUB_MARKER = 'Routed rule — load the body on trigger-match';
 
+/**
+ * Rendering symbols for this verb's rows — doctor's table plus `unknown`.
+ *
+ * `unknown` is a conformance concept: the check ran and could not answer.
+ * Distinct from `skipped` ("not applicable here") and from `ok` ("answered,
+ * green"), and never folded into the exit code, which keys off `fail` alone.
+ * It lives here rather than in `cmd_doctor`'s table because doctor emits no
+ * such row — and because `cmd_doctor.ts` is already over the source-size
+ * ceiling, so a line added there is a ratchet violation.
+ */
+const CONFORMANCE_STATUS_SYMBOLS: Record<string, string> = {
+    ...STATUS_SYMBOLS,
+    unknown: '❔',
+};
+
 function print(s = ''): void {
     process.stdout.write(`${s}\n`);
 }
@@ -105,21 +122,75 @@ export function installLogPath(): string {
 // Check (a) — txlog tail clean.
 // ---------------------------------------------------------------------------
 
-export function _check_txlog_clean(logPath: string = installLogPath()): Dict {
-    if (!fs.existsSync(logPath)) {
-        return {
-            id: 'txlog-clean',
-            status: 'ok',
-            message: 'no install transaction log — nothing to recover',
-            remedy: '',
-        };
-    }
-    const entries = readRecentEntries(logPath);
+/**
+ * True when this tree carries an install manifest — i.e. something was
+ * installed here, so an install transaction log was expected.
+ *
+ * The discriminator for the two absent-log cases below. A tree with no
+ * manifest was never installed and has genuinely nothing to recover; a
+ * tree WITH a manifest recorded an install and no log for it, which is
+ * not the same answer and must not be reported as the same colour.
+ */
+export function _installLogExpected(projectRoot: string): boolean {
+    return fs.existsSync(installed_tools.manifest_path(projectRoot));
+}
+
+/**
+ * Check (a) — the install transaction log tail carries no abandoned run.
+ *
+ * A log with nothing usable in it is two answers, not one
+ * (road-to-a-conformance-check-that-can-fail Phase 1). Until this split the
+ * branch returned `ok` unconditionally, so every install satisfied the check
+ * by having produced nothing.
+ *
+ * - nothing usable, no manifest  → `ok`      (nothing was installed here)
+ * - nothing usable, manifest     → `unknown` (an install recorded nothing)
+ * - usable entries               → `ok` / `fail` on the tail, as before
+ *
+ * `unknown` is deliberately NOT `fail`: an install that predates the log, or
+ * one written by a path that does not log, is an unanswered question rather
+ * than a broken install, and reddening every such consumer at upgrade is the
+ * risk this phase's shape exists to avoid. The exit contract keys off `fail`
+ * only, so `unknown` leaves exit codes untouched — including the verdict
+ * banner, where the per-row symbol is the only signal.
+ *
+ * Reach, updated 2026-09-15 — Phase 3 landed: the headless installer
+ * (`src/scripts/install.ts`, `_copy_dir_dereferencing_symlinks`) now appends
+ * a `write` or `skip` entry per copied/skipped path, through the same
+ * `appendTxLog` module the recovery-dismiss route calls. So a headless
+ * install now leaves the `unknown` branch above and reads `ok` on its own
+ * evidence rather than on the absence of any. `unknown` is still the answer
+ * for an install that predates this change, or for the wizard's browser
+ * path, which does not call the headless copy function; `fail` is still
+ * unreachable because nothing writes an `abort` yet.
+ */
+export function _check_txlog_clean(
+    logPath: string = installLogPath(),
+    projectRoot: string | null = null,
+): Dict {
+    const entries = fs.existsSync(logPath) ? readRecentEntries(logPath) : [];
     if (entries.length === 0) {
+        // One branch for all three no-usable-entries shapes — absent, empty,
+        // and unreadable. Splitting them let a zero-byte or fully-corrupt log
+        // reach `ok` on a tree the absent-log branch would have called
+        // `unknown`: `readRecentEntries` drops malformed lines silently, so
+        // "the file exists" is not evidence that anything recorded anything.
+        if (projectRoot !== null && _installLogExpected(projectRoot)) {
+            return {
+                id: 'txlog-clean',
+                status: 'unknown',
+                message:
+                    'install manifest present, no usable install transaction log — ' +
+                    'nothing recorded this install, so the last run cannot be confirmed complete',
+                remedy:
+                    'no install path writes this log today; ' +
+                    'run `agent-config doctor` for the drift answer this check cannot give',
+            };
+        }
         return {
             id: 'txlog-clean',
             status: 'ok',
-            message: 'install transaction log is empty',
+            message: 'no usable install transaction log and no install manifest — nothing was installed here',
             remedy: '',
         };
     }
@@ -131,7 +202,9 @@ export function _check_txlog_clean(logPath: string = installLogPath()): Dict {
             message:
                 `install log tail is an abandoned run (abort at ${last.ts}` +
                 `${last.note ? `: ${last.note}` : ''})`,
-            remedy: 're-run `agent-config init` (recovery reverse-applies the aborted tail)',
+            remedy:
+                're-run `agent-config init` — it re-applies the plan over the partial tail; ' +
+                "the aborted run's writes stay on disk and are replaced only where the plan covers them",
         };
     }
     return {
@@ -492,7 +565,7 @@ export function runConformanceChecks(opts: ConformanceRunOptions = {}): Dict[] {
     const projectRoot = opts.projectRoot ?? process.cwd();
     const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
     const checks: Dict[] = [];
-    checks.push(_check_txlog_clean());
+    checks.push(_check_txlog_clean(installLogPath(), projectRoot));
     checks.push(_check_router_pointers(packageRoot));
     if (opts.skipDispatcher === true) {
         checks.push({
@@ -653,7 +726,7 @@ function main(argv: string[] | null = null): number {
         print(`  📍  project_root: ${project_root}`);
         print('conformance:');
         for (const c of allChecks) {
-            const sym = STATUS_SYMBOLS[c['status'] as string] ?? '?';
+            const sym = CONFORMANCE_STATUS_SYMBOLS[c['status'] as string] ?? '?';
             print(`  ${sym} ${c['id']}: ${c['message']}`);
             if (c['status'] !== 'ok' && c['remedy']) {
                 print(`      fix: ${c['remedy']}`);

package/src/scripts/_cli/cmd_doctor.ts

@@ -114,6 +114,7 @@ import {
     resolve_project_root,
     type TraceRecord,
 } from '../_lib/agent_settings.js';
+import { executionJson, forgeProtectionJson, UNREAD_FORGE } from './doctor_execution.js';
 import * as ai_council_clients from '../ai_council/clients.js';
 import * as ai_council_config from '../ai_council/config.js';
 import {
@@ -3074,9 +3075,9 @@ function _emit_json(
         foreign,
         tag_drift,
     };
-    if (origin !== null) {
-        payload['project_root_origin'] = origin;
-    }
+    if (origin !== null) payload['project_root_origin'] = origin;
+    payload['execution'] = executionJson(() => iter_setting_overrides({ cwd: project_root }));
+    payload['forge_protection'] = forgeProtectionJson(UNREAD_FORGE); // 3.2
     if (checks !== null) {
         payload['checks'] = checks;
         const drift = missing.length + modified.length + foreign.length + tag_drift.length;

package/src/scripts/_cli/cmd_route_explain.ts

@@ -78,7 +78,14 @@ function _trigger_label(trigger: Trigger): string {
     return `trigger: ${JSON.stringify(trigger)}`;
 }
 
-/** Projection mode from settings; the shipped default is eager-all. */
+/**
+ * Projection mode from settings.
+ *
+ * The shipped template carries `delivery` for `claude-code` (ADR-267), so on a
+ * readable settings file that is what comes back. The `eager-all` below is the
+ * parser fallback for an absent or unreadable value, matching
+ * `DEFAULT_LEAN_PROJECTION_MODE` — it is not what the template ships.
+ */
 export function _projection_mode(): string {
     try {
         const settings = load_agent_settings({ cwd: REPO_ROOT }) as Record<string, unknown>;
@@ -90,7 +97,7 @@ export function _projection_mode(): string {
             }
         }
     } catch {
-        // settings unreadable → shipped default
+        // settings unreadable → parser fallback, not the template value
     }
     return 'eager-all';
 }

package/src/scripts/_cli/cmd_settings_get.ts

@@ -33,6 +33,10 @@
  * `2` usage error.
  */
 
+import {
+    resolveLocalAutoRun,
+    type AutoRunResolution,
+} from '../../shared/missionExecution.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
@@ -142,6 +146,31 @@ export function carveOutFor(key: string): CarveOutKey | undefined {
     return SETTINGS_CARVE_OUT.find((c) => c.key === key);
 }
 
+/**
+ * The mission-time resolution of `key`, or `null` when a mission changes nothing.
+ *
+ * Exactly one key resolves differently inside a mission today, and the function
+ * is keyed on that rather than generalised: a second mission-sensitive key would
+ * need its own argument about WHY the mission condition applies to it, and a
+ * generic table would let one land without that argument.
+ *
+ * `merged` is the already-loaded settings tree — no second cascade walk, for the
+ * same reason `layersFor` delegates rather than re-walking.
+ */
+export function missionResolutionFor(
+    key: string,
+    merged: unknown,
+): AutoRunResolution | null {
+    if (key !== 'quality.local_auto_run') return null;
+    const configured = getSettingsLeaf(merged, 'quality.local_auto_run');
+    const missionValue = getSettingsLeaf(merged, 'quality.local_auto_run_in_mission');
+    return resolveLocalAutoRun({
+        configured: configured === true,
+        missionValue: typeof missionValue === 'boolean' ? missionValue : undefined,
+        inMission: true,
+    });
+}
+
 /**
  * `true` when the key is present in the user-global file but is NOT whitelisted,
  * i.e. the loader read it and threw it away.
@@ -206,6 +235,7 @@ export function runSettingsGet(opts: SettingsGetOptions): SettingsGetResult {
     const fallback = templateDefault(opts.packageRoot, opts.key);
     const carveOut = carveOutFor(opts.key);
     const drop = userGlobalDrop(opts.key);
+    const mission = missionResolutionFor(opts.key, merged);
 
     if (opts.json) {
         out.push(
@@ -223,6 +253,9 @@ export function runSettingsGet(opts: SettingsGetOptions): SettingsGetResult {
                         ? { resolves_to: carveOut.absentResolvesTo, reader: carveOut.reader }
                         : null,
                     user_global_dropped: drop.dropped ? drop.file : null,
+                    in_mission: mission === null
+                        ? null
+                        : { value: mission.value, decided_by: mission.origin },
                 },
                 null,
                 2,
@@ -263,6 +296,17 @@ export function runSettingsGet(opts: SettingsGetOptions): SettingsGetResult {
         );
     }
 
+    if (mission !== null) {
+        out.push(
+            '',
+            `ℹ️  Inside a mission this key resolves to: ${JSON.stringify(mission.value)}`,
+            `    Decided by: ${mission.origin === 'mission' ? 'quality.local_auto_run_in_mission' : 'the settings layers above'}`,
+            '    A mission is an autonomous roadmap run with a claimed contract. The',
+            '    resolution is a runtime condition, never a layer, so no file above',
+            '    carries the mission value — see src/shared/missionExecution.ts.',
+        );
+    }
+
     if (drop.dropped) {
         out.push(
             '',

package/src/scripts/_cli/doctor_execution.ts

@@ -0,0 +1,90 @@
+/**
+ * The `execution` block of `agent-config doctor --json`.
+ *
+ * `road-to-adversarial-verification-and-long-runs` Phase 0.3. Its own module
+ * rather than a function inside `cmd_doctor.ts` for the reason
+ * `_lib/continuation_ladder.ts` states for itself: `check_source_size_budget` is
+ * a shrink-only ratchet and `cmd_doctor.ts` sits far past the 1,500-line cap, so
+ * every line added there is an added violation. A phase pays for its additions by
+ * putting new code in a file under the cap rather than by raising a baseline.
+ *
+ * `owner_owned_check` appears here as the ladder's last RUNG rather than as a
+ * separate field, because it is not a separate switch: it is the rung that
+ * decides whether the residue is owner-owned at all, and lifting it out would
+ * suggest it can be toggled independently of the order it sits in.
+ */
+
+import {
+    executionPostureFromOverrides,
+    resolveExecutionPosture,
+} from '../../shared/missionExecution.js';
+import {
+    forgeProtectionRows,
+    protectionActions,
+    type ForgeReading,
+} from '../_lib/forge_protection.js';
+
+type Dict = Record<string, unknown>;
+
+/** A settings-override stream, in the shape `iter_setting_overrides` yields. */
+export type OverrideStream = Iterable<readonly [string, unknown, string]>;
+
+/**
+ * Build the payload block from a settings-override stream.
+ *
+ * A stream that throws yields the defaults rather than propagating — a
+ * diagnostic that cannot report because its own input is malformed is the one
+ * shape `doctor` must never take.
+ */
+export function executionJson(overrides: () => OverrideStream): Dict {
+    let posture;
+    try {
+        posture = executionPostureFromOverrides(overrides());
+    } catch {
+        posture = resolveExecutionPosture({});
+    }
+    return {
+        fix_loop_max: posture.fix_loop_max,
+        escalation: [...posture.escalation],
+    };
+}
+
+/**
+ * The `forge_protection` block of `doctor --json` — Phase 3.2.
+ *
+ * **`doctor` does NOT reach the network on its own.** A diagnostic that makes a
+ * `gh` call on every invocation is one nobody runs offline, and the sibling
+ * anchor gate already declined that cost for the same reason. So the reading is
+ * INJECTED: a caller that has queried the forge passes it, and a caller that has
+ * not passes the all-null reading, which produces five `unread` rows that still
+ * name the call each value would come from.
+ *
+ * That is the honest shape for *read, never guessed*: the block is always
+ * present, a value appears only when a named call produced it, and `unread` is a
+ * third state rather than a quiet `false`. A row that was never looked at and a
+ * row that was looked at and failed are different repairs.
+ *
+ * `actions` carries the human ACTION lines — the step's own words are that a
+ * missing row is a blocker entry and NOT a halt, so this reports and returns.
+ */
+export function forgeProtectionJson(reading: ForgeReading): Dict {
+    const rows = forgeProtectionRows(reading);
+    return {
+        rows: rows.map((r) => ({
+            id: r.id,
+            state: r.state,
+            source: r.source,
+            detail: r.detail,
+        })),
+        actions: protectionActions(rows),
+        read_from_forge: rows.some((r) => r.state !== 'unread'),
+    };
+}
+
+/** The all-null reading: nothing was queried. */
+export const UNREAD_FORGE: ForgeReading = {
+    rulesets: null,
+    defaultBranch: null,
+    allowAutoMerge: null,
+    deployRestricted: null,
+};