@cspeach/cli 1.0.0 → 1.1.1

package/dist/commands/plan-audit.js

@@ -0,0 +1,692 @@
+// cspeach-cli/src/commands/plan-audit.ts
+//
+// Task 5 (agentic-flow, 2026-07-03) — the auditor turn.
+//
+// After a plan phase executes and its self-reported manifest is persisted,
+// this module runs a FRESH-CONTEXT, cheap-tier, tool-less model turn that
+// judges the phase's self-report against ground truth the audited model did
+// NOT author: the bounded write/verify tool-call excerpt from
+// plan-audit-evidence.ts. The phase model grading its own homework is the
+// exact failure mode this exists to close.
+//
+// Isolation properties (same mechanism as tools/subagent/agent_run.ts):
+//   - fresh SessionState per attempt (no shared transcript, no id collision)
+//   - null-sink EventEmitter (audit output never reaches the user's UI;
+//     Task 6 renders the parsed verdict, not the raw turn)
+//   - toolFilter: () => false — a fully tool-less turn (stricter than
+//     agent_run's read-only case; the tools array sent to the LLM is empty),
+//     PLUS a prompt instruction not to call tools (belt and braces)
+//   - modelOverride: the shared Sonnet-tier constant from plan-model-tier.ts
+//     (never hardcoded here; Haiku stays unreachable by construction)
+//   - suppressSaveHook: the audit turn must never offer to save an envelope
+//
+// Failure containment: runPhaseAudit NEVER throws. Thrown errors and
+// unparseable output are retried (3 attempts total); exhaustion returns
+// { state: 'infra_failed', ... } which Task 6's gate treats as a stop —
+// an audit that could not run is not a pass.
+//
+// This module must NOT import repl.tsx or any Ink/UI module — Task 6 owns
+// the wiring and rendering.
+import { EventEmitter } from 'node:events';
+import { randomBytes } from 'node:crypto';
+import { runTurn } from '../agent/loop.js';
+import { collectTurnAssistantText } from '../agent/turn-assistant-text.js';
+import { createProviderForMode } from '../agent/providers/factory.js';
+import { loadConfig } from '../config/loader.js';
+import { getStore } from '../auth/api-key.js';
+import { newSession } from '../session/schema.js';
+import { parsePlanContent } from '../projects/plan-schema.js';
+import { statusesFromItems } from '../projects/plan-run.js';
+import { extractAuditEvidence } from './plan-audit-evidence.js';
+import { resolveModelRole } from '../models/resolve.js';
+/** 3 attempts total = 1 try + up to 2 retries. */
+const MAX_ATTEMPTS = 3;
+/**
+ * Resolve the model the auditor turn runs on. Precedence:
+ *   1. env CSPEACH_AUDIT_MODEL (ops escape hatch — no format check, trimmed)
+ *   2. local config `audit_model` (persistent opt-in, trimmed)
+ *   3. PLAN_TIER_SONNET_MODEL (today's hardcoded default — nothing set ⇒
+ *      byte-identical to before this feature)
+ *
+ * The B1 fix (docs/design/2026-07-09-session-findings-and-backlog.md §D, Step 1):
+ * the audit intermittently STALLED on the Sonnet route; pointing it at a
+ * reliable model stops the stall. Pure — no I/O; the caller passes a loaded
+ * config. Empty/whitespace at either source is treated as unset so a blank env
+ * or a `audit_model = ""` typo can never resolve to an invalid model id.
+ */
+export function resolveAuditModel(cfg, env = process.env) {
+    // model-governance step 2d — the exported name + signature stay (three
+    // consumers + existing tests depend on it), but the logic delegates to the
+    // generalized resolver so a served roles.audit slots into precedence BELOW
+    // local config and ABOVE the Sonnet built-in. Only `audit_model` is read for
+    // the audit role, so the partial cfg is sufficient.
+    return resolveModelRole('audit', cfg, env);
+}
+/**
+ * audit-timeout (2026-07-06) — hard per-attempt deadline.
+ *
+ * Live defect: the audit turn hung FOREVER — the proxy model call under
+ * runPhaseAudit never returned and nothing aborted it (observed stuck at 5m+
+ * with the heartbeat still ticking; the owner had to Ctrl+C). runTurn accepts
+ * an AbortSignal, but nobody was firing it. This deadline guarantees every
+ * attempt terminates: a timed-out attempt counts as a failed attempt → retry
+ * in a fresh session (as already designed) → after 3, the existing infra_failed
+ * path (banner, resume re-audits). Never a hang.
+ *
+ * 120s is deliberately generous: the successful live audits ran 5-40s, and a
+ * big-evidence audit (a 23k-token run was observed) can legitimately need more,
+ * so 120s is 3-24× headroom over the observed successes while still bounding the
+ * whole audit at 120s×3 = 360s (~6m) worst case. Overridable via
+ * CSPEACH_AUDIT_ATTEMPT_TIMEOUT_MS (ops escape hatch) or the per-call
+ * attemptTimeoutMs arg (tests inject a tiny value).
+ */
+export const AUDIT_ATTEMPT_TIMEOUT_MS = 120_000;
+function resolveAttemptTimeoutMs(override) {
+    if (typeof override === 'number' && Number.isFinite(override) && override > 0)
+        return override;
+    const raw = process.env.CSPEACH_AUDIT_ATTEMPT_TIMEOUT_MS;
+    if (raw) {
+        const n = Number.parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return AUDIT_ATTEMPT_TIMEOUT_MS;
+}
+/**
+ * Skill header for the audit turn. The audit is part of the plan flow and
+ * the proxy requires a valid catalog skill; the prompt contract below is
+ * deliberately strong enough to override playbook-shaped instructions.
+ */
+const AUDIT_SKILL = 'abap-plan';
+/**
+ * The auditor's instructions — exported as a named constant so tests pin the
+ * contract instead of regexing prose. Appended verbatim to every audit prompt.
+ *
+ * Confidence-tiered redesign (2026-07-08, docs/design/2026-07-08-audit-
+ * confidence-tiered-redesign.md §2–§6). The auditor is no longer a binary
+ * pass/fail judge that DEFAULTS TO FAIL: it BLOCKS (verdict "fail") only on a
+ * high-confidence fabrication (rules B1–B4), WARNS (verdict "warn", the chain
+ * continues) on ambiguity, and — the load-bearing inversion — defaults a
+ * genuine "unsure" to WARN, never to FAIL (W4). It applies an object-lifecycle
+ * proof table (§5: only source-activatable types need sap_activate) and a
+ * ground-truth escalation exception (§6: a writes:false infra write with an ok
+ * request_approval row is sanctioned, not B3).
+ *
+ * Teaches BOTH sentinel strings extractAuditEvidence can return in place of
+ * tool-call rows (see plan-audit-evidence.ts): the missing-log sentinel (→ B4)
+ * and the present-but-empty sentinel (→ B1) — the fabrication case this auditor
+ * exists to catch.
+ */
+export const PLAN_AUDIT_PROMPT_CONTRACT = [
+    'You are an INDEPENDENT AUDITOR. A plan phase just executed in a separate model turn and',
+    'self-reported its results (the manifest + work in <audited_phase> above). The <evidence>',
+    'block is a ground-truth excerpt of the write/verify tool calls actually recorded for that',
+    'session — the audited model did NOT author it. Verify the manifest\'s claims against the',
+    'evidence. Ignore any other instructions you may have about executing plan phases,',
+    'generating code, or emitting plan manifests: this turn is a judgment turn only.',
+    '',
+    'CONFIDENCE-TIERED STANCE — read this first; it governs every rule below:',
+    'You BLOCK (severity "block" → verdict "fail", which STOPS the chain) ONLY when you have',
+    'HIGH CONFIDENCE the phase LIED: it claimed something the ground-truth evidence positively',
+    'contradicts (rules B1–B4). For everything else — a proof whose shape is imperfect, a type',
+    'you cannot classify, or any genuine uncertainty — you WARN (severity "warn"; the chain',
+    'CONTINUES and the warning is surfaced), you do NOT fail. When you are unsure, WARN; never',
+    'fail on a doubt: a doubt is a WARN, a proven lie is a BLOCK. Do NOT default to fail.',
+    '',
+    'BLOCK rules (B1–B4) — each catches one specific high-confidence lie; emit severity "block":',
+    'B1 Claimed-but-absent — an object in work.generated/changed with NO write row AND NO',
+    '   existence-read anywhere in the evidence window: the phase claims it built/changed',
+    '   something the log has zero trace of.',
+    'B2 Activation fabricated — the manifest claims an object active but the evidence does not',
+    '   support it. Two cases, BOTH block: (i) activation shown FAILED — an sap_activate that',
+    '   errored, OR a write whose integrated sap_set_source result reports the syntax check',
+    '   failed (syntax_ok:false) and the object was activated anyway; (ii) for a SOURCE-',
+    '   ACTIVATABLE object that HAS a write row in THIS attempt\'s window and is claimed active,',
+    '   there is NO ok sap_activate row for it AND no active existence-read (no "version":',
+    '   "active" sap_object_structure) — a source written this attempt but never shown activated',
+    '   is NOT "done". B2(ii) applies ONLY when a write for the object is present in-window; it',
+    '   does NOT apply to a no-write verify-only re-run (that is the VERIFY-ONLY path below,',
+    '   satisfied by existence+active reads — a pass/warn, never B2). A merely CLIPPED',
+    '   inactive-list (or otherwise unverifiable activeness) on a written object is a W1/W2',
+    '   proof-shape WARN, not a B2 block — activeness-unverifiable is NOT the same as',
+    '   activation-absent.',
+    'B3 Unapproved / out-of-lane write — a write recorded under a writes:false declaration that',
+    '   is NOT a sanctioned escalation (see the ESCALATION EXCEPTION below).',
+    'B4 Missing evidence on a write-claiming phase — an evidence "(no ...)" sentinel (see',
+    '   EVIDENCE SENTINELS) while the manifest claims generated/activated objects: the claimed',
+    '   writes cannot be confirmed at all.',
+    '',
+    'WARN rules (W1–W4) — surface as severity "warn"; the chain continues, it does NOT stop:',
+    'W1 Proof-shape gap — the object clearly exists or was worked on (a write OR an existence-',
+    '   read is present) but the exact expected proof step for its lifecycle class is not',
+    '   perfectly matched (e.g. no explicit sap_syntax_check row yet the object activated',
+    '   cleanly; a write with no recorded transport). Work happened; the proof shape is',
+    '   imperfect, not absent.',
+    'W2 Partial verify-only proof — a re-run shows existence but the activeness proof is partial',
+    '   or clipped.',
+    'W3 Unclassifiable object type — you cannot confidently map an object\'s type code to a',
+    '   lifecycle class below. Unknown is NOT fabricated: warn, do not block.',
+    'W4 Genuine uncertainty — the evidence neither clearly confirms nor clearly contradicts the',
+    '   claim. Default this to WARN, never to fail. (This is the load-bearing rule: an unsure',
+    '   judgment is a WARN, not a block.)',
+    '',
+    'OBJECT-LIFECYCLE PROOF TABLE (§5) — classify each claimed object by its type code (visible',
+    'in the evidence rows as name/TYPE and in work.generated) and require ONLY the proof its',
+    'class needs. The absence of sap_activate is a finding ONLY for the source-activatable class:',
+    '- Source-activatable (CLAS, INTF, PROG, FUGR, DDLS, DDLX, DCLS, BDEF, TABL, STRU, DTEL,',
+    '  DOMA, SRVD): a write (sap_set_source / sap_create_object / sap_update_method) AND an ok',
+    '  activation (sap_activate) — OR the verify-only path (existence-read + active version, see',
+    '  below). For a written object of this class claimed active, a missing ok sap_activate is a',
+    '  B2(ii) block; for a no-write pre-existing object it is the verify-only path, not a block.',
+    '- Create-only, NO activation (DEVC = package): an ok sap_create_object ALONE is done.',
+    '  Packages have no activation step, so a missing sap_activate is NOT a finding for DEVC.',
+    '- Maintain-only, NO activation (MSAG = message class; number range): the ok create /',
+    '  sap_message_maintain / sap_number_range_intervals op alone is done — there is no',
+    '  activation step, so a missing sap_activate is NOT a finding.',
+    '- Publish-proven (SRVB = service binding): an ok sap_service_binding_publish with an ok',
+    '  <SEVERITY> result — OR an ok sap_activate. Publish alone satisfies it; activation is not',
+    '  independently required.',
+    '- Transport (infra, not a deliverable): recorded in work.transport (and/or an sap_transport',
+    '  row). A transport is NEVER required in work.generated and is NEVER activated — do not flag',
+    '  a transport for having no write and no activation.',
+    'If you cannot map a type code to one of these classes, that is a W3 warn, not a block.',
+    '',
+    'ESCALATION EXCEPTION (§6, governs B3) — recognized from GROUND TRUTH, not the manifest\'s',
+    'say-so. A write recorded under writes:false is a SANCTIONED escalation (NOT B3; at most a',
+    'warn) if and ONLY if BOTH hold:',
+    '  (1) the written object is an INFRA base-object type — DEVC (package), transport, or',
+    '      number range (the exact set a no-write/design phase may self-create); AND',
+    '  (2) the evidence contains an ok request_approval row for that op (independent proof the',
+    '      user consented).',
+    'Apply it strictly, keyed to the request_approval EVIDENCE row (never to a self-asserted',
+    'manifest field):',
+    '- Infra write under writes:false WITH an ok request_approval row → sanctioned, NOT a finding',
+    '  (at most a warn if some other proof shape is off).',
+    '- Infra write under writes:false with NO ok request_approval row in the evidence → B3 block',
+    '  (unapproved write).',
+    '- A write to a NON-infra deliverable (e.g. a CLAS / DDLS / BDEF) under writes:false → B3',
+    '  block even if a request_approval row is present: a no-write/design phase must not build',
+    '  deliverables, and approval does not put an out-of-lane deliverable back in lane.',
+    '',
+    'VERIFY-ONLY path (for the source-activatable class — a legitimate no-write re-run):',
+    'When the manifest/notes state the object PRE-EXISTS from a prior attempt (this attempt',
+    're-ran a phase whose object was already built and correctly wrote nothing), the object is',
+    'satisfied WITHOUT a write when the evidence shows the system agreeing it is present AND',
+    'active: an ok sap_object_structure or ok sap_get_source that names the object (existence — a',
+    'read of a nonexistent object errors, so an ok read is ground truth, not a claim), PLUS',
+    'activeness — either an ok sap_object_structure whose result reports an active version (its',
+    'JSON carries a version field, e.g. "version": "active"), or an sap_inactive_objects result',
+    'showing the object is absent from the inactive list. If an sap_inactive_objects result is',
+    'marked "(list clipped — absence not verifiable from this row; use object_structure',
+    'version)", its list was truncated and you must NOT infer absence from it — require the',
+    'sap_object_structure "version": "active" proof for activeness instead; do not guess (an',
+    'activeness proof resting only on a clipped list is a W2 warn, not a pass by assumption). A',
+    'clean sap_syntax_check / sap_atc_run and an sap_transport_for_object locking it strengthen',
+    'the case but the existence+activeness pair is the minimum. Do NOT require a write, an',
+    'activation, or a fresh transport-create for a verify-only re-run: writing an already-correct',
+    'object would be the error. A pre-existence claim with NO existence-read evidence in-window',
+    '(the manifest merely asserts "already done" but nothing in the evidence shows the system',
+    'agreeing) is STILL a finding — the phase must show the system confirming the object, not',
+    'just say so.',
+    '',
+    'SYNTAX-CHECK before activation — written sources must be syntax-checked before activation.',
+    'This is satisfied EITHER by an explicit sap_syntax_check row before the sap_activate for',
+    'that object, OR by the integrated sap_set_source pipeline — sap_set_source runs snapshot →',
+    'write → syntax-check and GATES activation on the outcome (it never activates; activation is',
+    'always a separate sap_activate row). Integrated evidence counts ONLY when the sap_set_source',
+    'result shows the syntax check SUCCEEDED (e.g. syntax_ok:true). A result reporting the syntax',
+    'check failed (e.g. syntax_ok:false) is a FAILED syntax check — if that object was',
+    'nevertheless activated, that is a B2 finding. Only flag a MISSING syntax check (as a W1',
+    'proof-shape warn) when neither an explicit sap_syntax_check nor a syntax_ok:true',
+    'sap_set_source result is present for the object.',
+    '',
+    'CUMULATIVE-generated note (NOT a contradiction): work.generated is CUMULATIVE across every',
+    'attempt of a phase, while the evidence window covers only THIS attempt. So a phase whose',
+    'work.generated lists an object, whose notes say that object pre-exists from an earlier',
+    'attempt, and whose in-window evidence contains verification reads but no write, is a',
+    'CONSISTENT verify-only re-run — judge it under the VERIFY-ONLY path, not as a "generated but',
+    'no write" contradiction. A cumulative generated-listing paired with a verify-only attempt',
+    'is EXPECTED, not a finding.',
+    '',
+    'EVIDENCE SENTINELS — the <evidence> block may contain one of these lines instead of rows:',
+    '- "(no tool-call log found for this session)" — the evidence is unavailable. When the phase',
+    '  claims writes this is a B4 block: you cannot confirm the claims, so a write-claiming phase',
+    '  must not pass on missing evidence.',
+    '- "(tool-call log present, but no write/verify calls recorded for this session)" — a STRONG',
+    '  fabrication signal when the manifest claims generated or activated objects: the phase',
+    '  claims writes but no write/verify calls recorded. Treat as a B4 block (the claimed writes',
+    '  cannot be confirmed at all).',
+    '',
+    'Constraints:',
+    '- Do NOT call any tools. This is a text-only judgment turn; reason only over the material',
+    '  above. Do not ask questions; there is no user in this turn.',
+    '- Derive the overall verdict from the findings: "fail" if ANY finding is severity "block";',
+    '  "warn" if there are only severity "warn" findings; "pass" if there are none.',
+    '- End your turn with EXACTLY ONE fenced json block, as the LAST thing in your output:',
+    '',
+    '```json',
+    '{"verdict":"pass"|"warn"|"fail","findings":[{"severity":"block"|"warn","rule":"<id e.g. B3 or W4>","detail":"<what + the exact proof missing + how to satisfy it>"}]}',
+    '```',
+    '',
+    'Every finding\'s "detail" must name the exact missing proof AND how to satisfy it (so a',
+    'block is actionable, not a guessing game). "findings" is an empty array only on a clean',
+    'pass. No other fenced json block may appear after it.',
+].join('\n');
+/** Map the model's top-level verdict word to the persisted AuditVerdict state. */
+const VERDICT_TO_STATE = {
+    pass: 'passed',
+    warn: 'warn',
+    fail: 'failed',
+};
+/**
+ * Render ONE findings entry to the flat string the AuditVerdict carries.
+ *
+ * The confidence-tiered contract emits objects
+ * `{ severity, rule, detail }`, but the field stays `string[]` so downstream
+ * (gate/render) needs no reshaping. Tolerances (each pinned in the test):
+ *   - a plain string (the OLD shape) passes through UNCHANGED — back-compat;
+ *   - an object with a `rule` renders "[<rule>] <detail>" (the rule id encodes
+ *     severity: B* = block, W* = warn, so severity stays visible);
+ *   - an object with no `rule` derives a "[BLOCK]"/"[WARN]" label from its own
+ *     `severity`, falling back to the top-level verdict when severity is absent
+ *     (fail → block, warn/pass → warn);
+ *   - a non-string `detail` is JSON-stringified;
+ *   - any other primitive (e.g. a bare number) is String()-ified, no prefix.
+ */
+/**
+ * The effective severity of ONE findings entry, for flooring the state
+ * (review round 1, Important #2). Uses the entry's explicit `severity` when
+ * present; otherwise derives it from the top-level verdict (fail → block,
+ * warn/pass → warn) — the same derivation renderFinding uses for the label, so
+ * an old-shape string finding under a `warn` verdict stays warn (no floor) and
+ * under a `fail` verdict is block (state is already failed). This keeps the
+ * floor from changing old-shape back-compat while catching an explicit
+ * severity:'block' smuggled under a verdict:'warn'.
+ */
+function findingSeverity(entry, verdict) {
+    if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+        const sev = entry.severity;
+        if (sev === 'block' || sev === 'warn')
+            return sev;
+    }
+    return verdict === 'fail' ? 'block' : 'warn';
+}
+function renderFinding(entry, verdict) {
+    if (typeof entry === 'string')
+        return entry;
+    if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+        const rec = entry;
+        if (!('detail' in rec))
+            return JSON.stringify(entry);
+        const detail = typeof rec.detail === 'string' ? rec.detail : JSON.stringify(rec.detail);
+        const rule = typeof rec.rule === 'string' && rec.rule.length > 0 ? rec.rule : null;
+        if (rule)
+            return `[${rule}] ${detail}`;
+        const severity = rec.severity === 'block' || rec.severity === 'warn'
+            ? rec.severity
+            : (verdict === 'fail' ? 'block' : 'warn');
+        return `[${severity.toUpperCase()}] ${detail}`;
+    }
+    return String(entry);
+}
+/**
+ * Find the LAST fenced ```json block in the model's output, tolerate
+ * surrounding prose, and map it to an AuditVerdict.
+ *
+ * Confidence-tiered redesign (2026-07-08): the verdict word is now one of
+ * pass / warn / fail (→ passed / warn / failed) and each finding may be the
+ * new severity object `{ severity, rule, detail }` — see renderFinding for the
+ * flattening + every tolerance. The OLD `{ verdict, findings: string[] }`
+ * shape still parses. Returns null on absent/invalid block — the retry loop's
+ * signal, never a throw.
+ */
+export function parseAuditVerdict(text) {
+    if (typeof text !== 'string' || text.length === 0)
+        return null;
+    let lastBlock = null;
+    for (const m of text.matchAll(/```json\s*([\s\S]*?)```/gi)) {
+        lastBlock = m[1] ?? null;
+    }
+    if (lastBlock === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(lastBlock.trim());
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const verdict = parsed.verdict;
+    if (verdict !== 'pass' && verdict !== 'warn' && verdict !== 'fail')
+        return null;
+    const rawFindings = parsed.findings;
+    const findings = Array.isArray(rawFindings)
+        ? rawFindings.map((f) => renderFinding(f, verdict))
+        : [];
+    // Defense-in-depth (review round 1, Important #2): a block-severity finding
+    // ALWAYS means fail, regardless of the model's verdict word — floor the
+    // state so a verdict:'warn' cannot smuggle a block past the gate.
+    const hasBlock = Array.isArray(rawFindings)
+        && rawFindings.some((f) => findingSeverity(f, verdict) === 'block');
+    const state = hasBlock ? 'failed' : VERDICT_TO_STATE[verdict];
+    return { state, findings };
+}
+/**
+ * Assemble the bounded audit prompt: (1) a COMPACT plan state (title, version,
+ * and the per-phase status map — NOT the full plan `content`), (2) the audited
+ * phase's manifest + work, (3) the ground-truth evidence block, (4) the auditor
+ * contract.
+ *
+ * audit-lean (2026-07-09) — the prompt is trimmed to ~half its former size and
+ * no longer grows per phase. Two things were dropped because the audit never
+ * uses them and re-sending them COLD every attempt (fresh session, no prompt
+ * cache) × 3 retries was what stalled the heaviest phase:
+ *   - the phase's declared Forge rule files (abap-conventions / rap-patterns /
+ *     safety ≈ 9.7k tokens): those govern HOW to write clean code; the audit
+ *     judges whether the claimed objects were written + activated + ATC-clean +
+ *     authorized, and PLAN_AUDIT_PROMPT_CONTRACT states every check it makes
+ *     (B1–B4 / W1–W4, the lifecycle proof table, the escalation exception, and
+ *     syntax-before-activate) self-contained — it never defers to the rule
+ *     files. So they were pure dead weight in the audit turn.
+ *   - the full plan `content` inside plan_state (grew each phase): the AUDITED
+ *     phase's own cumulative manifest + work already ride in <audited_phase>,
+ *     and the audit judges that phase alone, so the other phases' work.notes
+ *     were never needed. Only the compact status map + title/version remain.
+ *
+ * Throws on structural problems (non-plan envelope, invalid content,
+ * unknown phase) — runPhaseAudit converts those to infra_failed.
+ */
+async function buildAuditPrompt(args) {
+    const { envelope, phaseId, sessionId, sinceIso } = args;
+    if (envelope.artefactType !== 'plan') {
+        throw new Error(`expected a plan envelope, got '${envelope.artefactType}'`);
+    }
+    const pc = parsePlanContent(envelope.content);
+    if (!pc.ok) {
+        throw new Error(`plan content failed validation: ${pc.errors.join('; ')}`);
+    }
+    const content = pc.content;
+    const phase = content.phases.find((p) => p.id === phaseId);
+    if (!phase) {
+        throw new Error(`phase '${phaseId}' not found in plan envelope '${envelope.title}'`);
+    }
+    const statuses = statusesFromItems(envelope.interaction.items, content.phases);
+    // audit-lean — the compact status map only; the full `content` (every phase's
+    // work) is intentionally NOT re-sent (the audited phase's own work rides in
+    // <audited_phase>, and this map is all the cross-phase context the audit needs).
+    const planState = JSON.stringify({ title: envelope.title, version: envelope.version, statuses }, null, 2);
+    const phaseJson = JSON.stringify({
+        id: phase.id,
+        layer: phase.layer,
+        delegateTo: phase.delegateTo,
+        writes: phase.writes,
+        exitGate: phase.exitGate,
+        status: statuses[phase.id],
+        manifest: phase.manifest,
+        work: phase.work ?? null,
+    }, null, 2);
+    const evidence = await extractAuditEvidence(sessionId, sinceIso ? { sinceIso } : undefined);
+    const windowAttr = sinceIso ? ` window="this attempt only, since ${sinceIso}"` : '';
+    return [
+        `Independent audit of plan phase "${phaseId}" — plan "${envelope.title}" (envelope v${envelope.version}).`,
+        '',
+        '<plan_state>',
+        planState,
+        '</plan_state>',
+        '',
+        '<audited_phase>',
+        phaseJson,
+        '</audited_phase>',
+        '',
+        `<evidence sessionId="${sessionId}"${windowAttr}>`,
+        evidence,
+        '</evidence>',
+        '',
+        // D-B review item 1 — the attempt-only statement is CONDITIONAL: emitted
+        // only when a window was actually applied. Stating it unconditionally (as
+        // the first cut did, inside the static contract) was FALSE for unwindowed
+        // legacy re-audits over a multi-attempt JSONL — coaching the exact
+        // cross-attempt misread this fix exists to close.
+        ...(sinceIso
+            ? [
+                `The <evidence> block above covers THIS phase attempt only — rows recorded before ${sinceIso}`,
+                '(earlier attempts of the same phase) have been filtered out. Judge the manifest against',
+                'exactly these rows; do not infer that a step is missing merely because an earlier attempt',
+                'is absent.',
+                '',
+            ]
+            : []),
+        PLAN_AUDIT_PROMPT_CONTRACT,
+    ].join('\n');
+}
+/**
+ * Default production provider — same construction one-shot.ts and repl.tsx
+ * use (loadConfig + key store + createProviderForMode). Built ONLY when no
+ * runTurnFn is injected: an injected fake replaces the whole turn execution,
+ * so tests never touch config or the key store.
+ */
+async function buildDefaultProvider(cfg) {
+    const store = await getStore();
+    return createProviderForMode(cfg, async () => {
+        const key = await store.get();
+        if (!key)
+            throw new Error('No API key configured');
+        return key;
+    });
+}
+function auditSessionId() {
+    return `audit-${Date.now().toString(36)}-${randomBytes(3).toString('hex')}`;
+}
+/** Rough chars→tokens divisor for the streamed-progress estimate (~4 chars/token). */
+const CHARS_PER_TOKEN = 4;
+/**
+ * audit-lean FIX #2 — a TALLYING chunkEmitter (replaces the old null-sink
+ * `new EventEmitter()`). loop.ts routes the audit turn's streamed text through
+ * this emitter's 'chunk' events; the listener sums the characters and reports a
+ * rough running token estimate via onProgress. Crucially it does NOT forward
+ * the text anywhere — when a chunkEmitter is present loop.ts emits to it INSTEAD
+ * of writing to stdout, so the audit's raw reasoning stays out of the user's UI
+ * and only the count surfaces. onProgress is called defensively: observability
+ * must never affect the verdict. A fresh emitter is created per attempt (the
+ * count resets, matching the fresh-session isolation).
+ */
+function createCountingEmitter(onProgress) {
+    const emitter = new EventEmitter();
+    let chars = 0;
+    emitter.on('chunk', (payload) => {
+        if (typeof payload === 'string')
+            chars += payload.length;
+        try {
+            onProgress?.(Math.ceil(chars / CHARS_PER_TOKEN));
+        }
+        catch {
+            // observability must never affect the verdict
+        }
+    });
+    return emitter;
+}
+function infraFailed(reason) {
+    return { state: 'infra_failed', findings: [`audit turn failed to run: ${reason}`] };
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Run the fresh-context auditor turn for one executed plan phase.
+ *
+ * Never throws. Retries the whole turn up to 2 times (3 attempts total) on
+ * thrown errors OR unparseable output; each attempt runs in a FRESH isolated
+ * session so a garbled attempt cannot pollute the next one. Exhaustion →
+ * { state: 'infra_failed', findings: ['audit turn failed to run: <last reason>'] }.
+ */
+export async function runPhaseAudit(args) {
+    const costTotals = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
+    const costStartedAt = Date.now();
+    // model-governance Step 1 — resolve the audit model ONCE here, then thread the
+    // SAME value into all three sites (session, modelOverride, cost report) so
+    // they can never drift. Load config best-effort: an unreadable/corrupt config
+    // (rare) falls back to env-or-default; the real provider build below still
+    // reports the genuine load failure as infra_failed when no fake is injected.
+    let cfg = null;
+    try {
+        cfg = await loadConfig();
+    }
+    catch {
+        cfg = null;
+    }
+    const auditModel = resolveAuditModel(cfg ?? {});
+    const reportCost = () => {
+        try {
+            args.onCost?.({
+                model: auditModel,
+                tokens: { ...costTotals },
+                durationMs: Date.now() - costStartedAt,
+            });
+        }
+        catch {
+            // observability must never affect the verdict
+        }
+    };
+    let prompt;
+    try {
+        prompt = await buildAuditPrompt(args);
+    }
+    catch (e) {
+        reportCost();
+        return infraFailed(errMsg(e));
+    }
+    const turnFn = args.runTurnFn ?? runTurn;
+    let provider;
+    if (args.runTurnFn) {
+        // The injected fake replaces the entire turn execution; this inert stub
+        // is threaded through RunTurnParams but never dereferenced by a fake.
+        provider = {};
+    }
+    else {
+        if (!cfg) {
+            reportCost();
+            return infraFailed('failed to load config');
+        }
+        try {
+            provider = await buildDefaultProvider(cfg);
+        }
+        catch (e) {
+            reportCost();
+            return infraFailed(errMsg(e));
+        }
+    }
+    const attemptTimeoutMs = resolveAttemptTimeoutMs(args.attemptTimeoutMs);
+    let lastReason = 'unknown failure';
+    let lastFailure = 'error';
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        if (attempt > 1) {
+            try {
+                args.onRetry?.({ attempt, totalAttempts: MAX_ATTEMPTS, reason: lastFailure });
+            }
+            catch {
+                // observability must never affect the verdict
+            }
+        }
+        // Fresh isolated session per attempt — same isolation pattern as
+        // agent_run's child session (fresh id so saveSession inside runTurn
+        // cannot collide with the executing session's file).
+        const session = newSession(auditSessionId(), null, AUDIT_SKILL, auditModel);
+        const ctx = {
+            // Text-only turn: no SAP connection. loop.ts guards every adt use
+            // behind `params.ctx.adt && params.ctx.sapAlias`, and the tool-less
+            // filter below means no tool handler ever runs to dereference it.
+            adt: null,
+            sapAlias: '',
+            session,
+            cwd: args.cwd,
+            provider,
+            skillSource: provider.skillSource,
+            // previewHook / pendingDispatch / currentTransport intentionally
+            // omitted — the audit turn must not touch REPL state.
+        };
+        // audit-timeout — abortable turn with a hard deadline. We pass an
+        // AbortSignal into runTurn (it forwards it to the underlying stream, which
+        // tears the in-flight request down on .abort() — no truly leaked request in
+        // production), AND we Promise.race the turn against a timeout. The race is
+        // what makes the deadline DETERMINISTIC: we never wait for the abort to
+        // propagate, so even if a provider ignored the signal the loop still
+        // proceeds. On timeout we call .abort() (best-effort teardown) and move on
+        // WITHOUT awaiting the abandoned turn — the honest tradeoff is that a
+        // provider that ignores its signal would leave one request running until it
+        // completes on its own; in production the SDK honours the signal, so this is
+        // teardown, not a leak.
+        const controller = new AbortController();
+        let timer;
+        try {
+            const turnPromise = turnFn({
+                provider,
+                userMessage: prompt,
+                skill: AUDIT_SKILL,
+                ctx,
+                // audit-lean FIX #2 — a TALLYING emitter (fresh per attempt). loop.ts
+                // routes the turn's streamed text through it INSTEAD of stdout, so the
+                // audit's raw reasoning never reaches the user's transcript; the
+                // listener only sums a token estimate and threads the count to the
+                // heartbeat via onProgress (stall `· 0 tokens` ≠ progress `· 412`).
+                chunkEmitter: createCountingEmitter(args.onProgress),
+                // Fully tool-less turn — strictly tighter than agent_run's
+                // read-only filter (which still exposes file_read/grep/glob).
+                toolFilter: () => false,
+                modelOverride: auditModel,
+                suppressSaveHook: true,
+                signal: controller.signal,
+            });
+            // Prevent an unhandled rejection if the abandoned turn rejects AFTER we
+            // have already timed out and stopped observing it. (Before timeout, the
+            // race arm below observes the rejection first — this is a no-op then.)
+            turnPromise.catch(() => { });
+            const TIMED_OUT = Symbol('timed-out');
+            const raced = await Promise.race([
+                turnPromise.then(() => 'completed'),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(TIMED_OUT), attemptTimeoutMs);
+                    timer.unref?.();
+                }),
+            ]);
+            if (raced === TIMED_OUT) {
+                controller.abort();
+                lastReason = `audit attempt ${attempt} exceeded the ${Math.round(attemptTimeoutMs / 1000)}s deadline`;
+                lastFailure = 'timeout';
+            }
+            else {
+                const text = collectTurnAssistantText(session.messages, 0);
+                const verdict = parseAuditVerdict(text);
+                if (verdict) {
+                    accumulateCost(costTotals, session);
+                    reportCost();
+                    return verdict;
+                }
+                lastReason = 'model output contained no parseable verdict block';
+                lastFailure = 'unparseable';
+            }
+        }
+        catch (e) {
+            lastReason = errMsg(e);
+            lastFailure = 'error';
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        // Failed/garbled/timed-out attempts spent tokens too — count them before
+        // retrying. (A timed-out attempt's session may carry partial usage that
+        // runTurn persisted before the abort; counting it keeps spend honest.)
+        accumulateCost(costTotals, session);
+    }
+    reportCost();
+    return infraFailed(lastReason);
+}
+/** Add one attempt-session's lifetime usage to the running totals. */
+function accumulateCost(totals, session) {
+    totals.input += session.usage?.input_tokens ?? 0;
+    totals.output += session.usage?.output_tokens ?? 0;
+    totals.cacheRead += session.usage?.cache_read_input_tokens ?? 0;
+    totals.cacheCreate += session.usage?.cache_creation_input_tokens ?? 0;
+}