@cspeach/cli 1.0.0 → 1.1.0

package/dist/commands/plan-chain.js

@@ -0,0 +1,671 @@
+// cspeach-cli/src/commands/plan-chain.ts
+//
+// Task 6 (agentic-flow, 2026-07-03) — the shared post-phase sequence, called
+// by BOTH repl.tsx plan-resume call sites (Ink + classic) so neither
+// duplicates the block. Exact order (the crash-safety design):
+//
+//   finishPlanResume persisted the phase WITH audit:'pending'   (caller)
+//     → runPhaseAudit          (fresh-context, tool-less judge turn)
+//     → applyAuditResult       (verdict persisted as revision N+1)
+//     → verdict handling       (failed ⇒ re-run/waive/block; infra ⇒ stop,
+//                               2nd consecutive infra ⇒ retry/waive/block)
+//     → decideNextPhaseGate    (step/guarded transition decision)
+//     → offerNextPhaseAutoRun  (prompt, or auto-queue in guarded mode)
+//
+// A crash anywhere before applyAuditResult leaves 'pending' on disk;
+// preparePlanResume's re-audit-on-resume then runs this chain FIRST on the
+// next --resume (executedPhaseId = the pending phase, forceAudit) instead of
+// executing a new phase — the audit is never skipped.
+//
+// Everything I/O-heavy or interactive is injectable via PlanChainDeps so the
+// chain is unit-testable without a provider, Ink, or inquirer.
+import { basename } from 'node:path';
+import chalk from 'chalk';
+import { readProjectFile } from '../projects/status.js';
+import { parsePlanContent } from '../projects/plan-schema.js';
+import { statusesFromItems, computeNextPhase, isPhaseSatisfied, isAuditResolved, planCompletionLines, renderPlanTracker, } from '../projects/plan-run.js';
+import { decideNextPhaseGate, getAndResetPlanPhaseSubagentDispatches, getAndResetPlanDeviation, } from './plan-gate.js';
+import { runPhaseAudit } from './plan-audit.js';
+import { applyAuditResult, applyPhaseResolution, buildResumeCommand, offerNextPhaseAutoRun, } from './plan-resume.js';
+import { appendCostLine, buildEntry } from '../cost/cost-log.js';
+import { startThinkingHeartbeat, AUDIT_HEARTBEAT_THRESHOLDS } from '../renderer/thinking-heartbeat.js';
+import { computeCost, formatCost } from '../cost/pricing.js';
+/** Two consecutive failed verdicts on the same phase force status 'blocked'. */
+export const MAX_CONSECUTIVE_AUDIT_FAILURES = 2;
+/** Infra error strings are model/HTTP noise — clamp when rendering (Task 5 review). */
+const INFRA_RENDER_CHARS = 200;
+/**
+ * Run the post-phase chain. Returns the LATEST saved envelope path (the
+ * caller's savedPath when nothing was written), or null when the chain could
+ * not even load the envelope.
+ */
+export async function runPostPhaseChain(args) {
+    let path = args.savedPath;
+    let loaded = loadPlan(path, args.log);
+    if (!loaded)
+        return null;
+    let phase = loaded.content.phases.find((p) => p.id === args.executedPhaseId);
+    if (!phase) {
+        args.log(chalk.red(`[plan] phase '${args.executedPhaseId}' not found in ${basename(path)} — chain skipped.`));
+        return path;
+    }
+    // Per-run flags survive the chain: an explicitly flagged run keeps its mode
+    // AND its audit setting across every harness-built resume command (I2 — the
+    // audit flag mirrors modeFlag; --audit maps to itself, 'off' to --no-audit).
+    const flagSuffix = (args.modeFlag ? ` --${args.modeFlag}` : '')
+        + (args.auditFlag === 'off' ? ' --no-audit' : args.auditFlag === 'on' ? ' --audit' : '');
+    const resumeCmd = (p) => buildResumeCommand(p) + flagSuffix;
+    let chainWrote = false;
+    // Task 7 — phase-end subagent report. agent_run counted every dispatch
+    // made while the plan-phase flag was on (all forced read-only). The REPL
+    // reads+resets the counter in its runTurn finally and threads the value
+    // here (fix-wave, item 1) — this chain can be skipped on error paths, so
+    // consuming the counter here alone would let counts leak into the next
+    // phase's report line. The read+reset below is only the fallback for
+    // callers that ran no phase turn (re-audit passes, direct test calls) —
+    // zero there in practice, so nothing is printed.
+    const subagentDispatches = args.subagentDispatches ?? getAndResetPlanPhaseSubagentDispatches();
+    if (subagentDispatches > 0) {
+        args.log(chalk.dim(`[phase] ${args.executedPhaseId}: ${subagentDispatches} subagent dispatch(es) — read-only enforced`));
+    }
+    /* ── 0. deviation backstop (Task 10) ──────────────────────────────────────
+     * approval.ts raised the flag mid-turn: this phase declared writes:false
+     * but requested a write approval anyway — the write was DENIED without
+     * prompting; here the chain records why and stops. Design choice (per the
+     * task's simpler-path option): SKIP the audit — the phase didn't complete
+     * honestly and was deliberately stopped, so auditing it wastes a turn. The
+     * finishPlanResume-injected 'pending' audit is dropped in the same write
+     * (clearAudit) or the next resume would re-audit the blocked phase. Same
+     * read+reset pattern as the subagent counter — the flag never leaks into
+     * the next chain leg. Guarded-only by construction: approval.ts only ever
+     * raises it while isGuardedRunActive(). */
+    const deviationDetail = getAndResetPlanDeviation();
+    if (deviationDetail) {
+        path = await applyPhaseResolution(path, phase.id, {
+            status: 'blocked',
+            lastStop: { phaseId: phase.id, reason: 'deviation', detail: deviationDetail, at: new Date().toISOString() },
+            summary: `guarded chain stopped: plan deviation in ${phase.id} — ${deviationDetail}`,
+            clearAudit: true,
+            log: args.log,
+        });
+        args.log(chalk.red(`✖ plan deviation in phase ${phase.id} — ${deviationDetail}`), stoppedBanner(`plan deviation — phase ${phase.id} blocked (undeclared write denied)`, resumeCmd(path)));
+        ringBell();
+        return path;
+    }
+    /* ── 1. audit (only when unresolved-pending/infra, or forced) ─────────── */
+    // Off-switch: audits off skips the NORMAL post-phase audit (no injected
+    // pending exists to catch anyway). A forced re-audit still runs — a persisted
+    // pending/infra record from an earlier ON run must resolve regardless.
+    const auditState = phase.audit?.state;
+    const auditsOff = args.auditMode === 'off';
+    // audit-infra-continue (2026-07-09): 'infra_failed' is now RESOLVED and no
+    // longer auto-re-audited — an audit that could not run already let the chain
+    // continue, so it must not spontaneously re-run on a later pass. Only a
+    // persisted 'pending' (crash between phase-save and verdict-save) or an
+    // explicit forceAudit (hand-edit re-verification) triggers an audit here.
+    const needsAudit = args.forceAudit
+        || (!auditsOff && auditState === 'pending');
+    if (needsAudit) {
+        args.log('', chalk.dim(`[audit] independent audit of phase ${phase.id} — fresh context, judged against the tool-call evidence…`));
+        // Evidence lives with the session that EXECUTED the phase; on a re-audit
+        // in a fresh CLI session that id was recorded on the pending audit.
+        const evidenceSessionId = phase.audit?.sessionId ?? args.sessionId;
+        const auditFn = args.deps?.runPhaseAuditFn ?? runPhaseAudit;
+        let cost;
+        // D-B — window the evidence to THIS attempt only. Live post-phase audit:
+        // the repl threads the turn-start it captured (attemptStartedAt).
+        // RE-audit (review item 1): the OLD session's JSONL can hold MULTIPLE
+        // attempts (fail → rerun in the same process → die before verdict →
+        // resume re-audits), so an unwindowed re-audit re-creates the exact
+        // cross-attempt false-ordering on the standard recovery path — use the
+        // window finishPlanResume persisted on the audit record
+        // (audit.attemptStartedAt, carried through verdict writes). A legacy
+        // record without the field runs unwindowed (fail-open, no window claim
+        // is made to the auditor either — see buildAuditPrompt).
+        const sinceIso = args.attemptStartedAt ?? phase.audit?.attemptStartedAt;
+        // D-F item 4 — liveness. The audit is a single fresh-context model turn
+        // (10-40s) with no streaming into this chain, so the [audit] header sat
+        // silent. Reuse the house-style heartbeat (same primitive loop.ts uses),
+        // routed through args.log so it works under both Ink and classic.
+        // audit-timeout (2026-07-06): use the audit-specific schedule — the audit
+        // is a PROXY call (api.cspeach.dev), so the generic "check the VPN" 5m copy
+        // is the wrong diagnosis. runPhaseAudit now hard-caps each attempt at 120s,
+        // so this can never sit stuck forever. Attempt transitions are surfaced via
+        // onRetry below. Always stopped in finally.
+        // audit-lean FIX #2 — a LIVE token count threaded from the auditor's stream
+        // into the heartbeat suffix, so a stall (`· 0 tokens`) reads differently
+        // from slow-but-working progress. The suffix closure reads the latest value
+        // at each heartbeat tick; onProgress updates it as chunks arrive.
+        let auditTokens = 0;
+        const heartbeat = startThinkingHeartbeat({
+            thresholds: AUDIT_HEARTBEAT_THRESHOLDS,
+            emit: (line) => args.log(line),
+            suffix: () => ` · ${auditTokens.toLocaleString()} token${auditTokens === 1 ? '' : 's'}`,
+        });
+        let verdict;
+        try {
+            verdict = await auditFn({
+                envelope: loaded.envelope,
+                phaseId: phase.id,
+                sessionId: evidenceSessionId,
+                cwd: args.cwd,
+                ...(sinceIso ? { sinceIso } : {}),
+                onCost: (c) => { cost = c; },
+                // Best-effort: the heartbeat reads auditTokens at each tick.
+                onProgress: (n) => { auditTokens = n; },
+                // audit-timeout — an honest attempt-transition line when a prior
+                // attempt hit its deadline (or otherwise failed) and we retry in a
+                // fresh session. Keeps the timeline truthful against the 120s×3 ceiling.
+                onRetry: (r) => {
+                    const why = r.reason === 'timeout' ? 'previous attempt timed out'
+                        : r.reason === 'unparseable' ? 'previous attempt returned no verdict'
+                            : 'previous attempt errored';
+                    args.log(chalk.dim(`  [audit] attempt ${r.attempt} of ${r.totalAttempts} (${why})`));
+                },
+            });
+        }
+        finally {
+            heartbeat.stop();
+        }
+        if (cost)
+            renderAuditCost(args, cost);
+        // Fix-wave (item 10a) — a persisted 'failed' reaching a re-audit means
+        // the session died AT the failure menu (verdict written, resolution
+        // never was). A failed verdict then RE-CONFIRMS the same failure: hold
+        // the counter instead of incrementing, and re-render the menu — the
+        // developer must still get the re-run/waive/block choice they lost.
+        // Delta-review edge: an interleaved infra outage launders the same case
+        // — failed(1) → menu death → re-audit hits infra (the counter is carried
+        // onto infra_failed) → the NEXT re-audit's failed verdict would count as
+        // consecutive and silently force-block. A persisted infra_failed that
+        // CARRIES a failure counter is therefore also a reconfirmation: the
+        // menu was owed and never shown.
+        const reconfirmingFailed = auditState === 'failed'
+            || (auditState === 'infra_failed' && (phase.audit?.consecutiveFailures ?? 0) >= 1);
+        // Consecutive-failure decision happens BEFORE the write so the forced
+        // block lands in the SAME revision as the verdict.
+        const priorFailures = phase.audit?.consecutiveFailures ?? 0;
+        const countedFailures = reconfirmingFailed
+            ? Math.max(priorFailures, 1)
+            : priorFailures + 1;
+        const forceBlock = verdict.state === 'failed'
+            && countedFailures >= MAX_CONSECUTIVE_AUDIT_FAILURES;
+        const nowIso = new Date().toISOString();
+        // Only a real 'failed' verdict records a stop. 'infra_failed' no longer
+        // stops (audit-infra-continue) — like warn/pass it leaves no lastStop, so
+        // applyAuditResult clears any stale one (see its resolved-verdict branch).
+        const lastStop = verdict.state === 'failed'
+            ? { phaseId: phase.id, reason: 'audit-failed', detail: clampInfra(verdict.findings[0] ?? ''), at: nowIso }
+            : undefined;
+        // Confidence-tiered redesign (2026-07-08) — the GATE. A `warn` verdict is
+        // NON-BLOCKING: it persists LITERALLY (state:'warn', findings carried),
+        // clears the failure counter (a warn is not a failure), and the chain
+        // continues exactly like a pass — no menu, no lastStop, forceBlock can
+        // never fire on it (forceBlock keys off verdict.state === 'failed' above).
+        // fail / infra_failed / pass persistence is byte-unchanged.
+        path = await applyAuditResult(path, phase.id, {
+            state: verdict.state,
+            findings: verdict.findings,
+        }, {
+            lastStop,
+            ...(forceBlock ? { statusOverride: 'blocked' } : {}),
+            ...(reconfirmingFailed ? { reconfirmedFailure: true } : {}),
+            log: args.log,
+        });
+        chainWrote = true;
+        loaded = loadPlan(path, args.log);
+        if (!loaded)
+            return path;
+        phase = loaded.content.phases.find((p) => p.id === args.executedPhaseId);
+        // D-E — the progress board renders HERE, AFTER the verdict lands, so the
+        // tally is audit-aware and never contradicts a later verdict. (finishPlanResume
+        // now prints only a neutral "audit pending…" line; the board it used to
+        // print counted the just-run phase as done because it erased the pending
+        // audit for display — a validated phase with a pending audit is NOT
+        // satisfied, so the pre-audit board read "2/3" for what was really "1/3".)
+        // Suppressed on mid-pass re-audit legs (runReauditPass renders once at the
+        // end via its final, unsuppressed leg).
+        if (!args.suppressOffer) {
+            const boardStatuses = statusesFromItems(loaded.envelope.interaction.items, loaded.content.phases);
+            args.log('', renderPlanTracker({
+                title: loaded.envelope.title,
+                version: loaded.envelope.version,
+                content: loaded.content,
+                statuses: boardStatuses,
+                currentId: null,
+                auditsOff,
+            }), '');
+        }
+        if (verdict.state === 'infra_failed') {
+            // audit-infra-continue (2026-07-09): the audit COULD NOT RUN — after the
+            // in-turn 3 attempts (runPhaseAudit's 120s×3 ceiling) the model call
+            // returned no output. That is an audit-INFRASTRUCTURE failure, not a
+            // finding against the phase, whose own exit gate (activation + ATC)
+            // already passed. So we do NOT hard-stop verified work: exactly like a
+            // warn/pass, render a LOUD, DISTINCT "could not run / NOT verified" note,
+            // keep the infra_failed state recorded (tracker keeps ⚠ audit not run;
+            // the final summary lists it as unverified) and CONTINUE to the gate +
+            // offer below. isAuditResolved treats infra_failed as resolved, so
+            // dependants unlock and the failure menu is never shown.
+            renderAuditNotRun(args.log, phase.id, clampInfra(verdict.findings[0] ?? 'auditor infrastructure failure'), resumeCmd(path));
+        }
+        else if (verdict.state === 'failed') {
+            renderFindings(args.log, phase.id, verdict.findings);
+            if (forceBlock) {
+                args.log(chalk.red(`✖ phase ${phase.id} failed its audit ${countedFailures} times in a row — marked blocked.`), stoppedBanner('two consecutive failed audits — phase blocked', resumeCmd(path)));
+                ringBell();
+                return path;
+            }
+            const select = args.deps?.selectFailureAction ?? defaultSelectFailureAction;
+            const action = await select({ phaseId: phase.id, findings: verdict.findings });
+            if (action === 'none') {
+                // D-C — fail CLOSED. 'none' is headless OR an interactive decline/cancel
+                // (Esc, no listener, or an unrecognised menu answer). The phase must NOT
+                // auto-re-run — a re-run is an explicit menu choice, never a default.
+                // Stop with the banner; resuming re-audits and re-offers the menu (the
+                // persisted 'failed' on a still-satisfied phase is re-caught by
+                // preparePlanResume's died-at-menu scan).
+                args.log(stoppedBanner(`audit failed for phase ${phase.id} — resolve interactively (re-run / waive / block)`, resumeCmd(path)));
+                ringBell();
+                return path;
+            }
+            if (action === 'blocked') {
+                path = await applyPhaseResolution(path, phase.id, {
+                    status: 'blocked',
+                    lastStop: { phaseId: phase.id, reason: 'audit-failed', detail: 'user marked the phase blocked after a failed audit', at: new Date().toISOString() },
+                    summary: `audit ${phase.id}: failed — user marked phase blocked`,
+                    log: args.log,
+                });
+                args.log(stoppedBanner(`phase ${phase.id} marked blocked after failed audit`, resumeCmd(path)));
+                ringBell();
+                return path;
+            }
+            if (action === 'rerun') {
+                // Status back to 'todo' — computeNextPhase re-picks it, and the flow
+                // ALWAYS audits an executed phase, so a re-run is re-audited by
+                // construction. The failed audit + counter stay on the phase until
+                // the re-run's finishPlanResume replaces them with 'pending'.
+                path = await applyPhaseResolution(path, phase.id, {
+                    status: 'todo',
+                    summary: `audit ${phase.id}: failed — user chose re-run (status → todo)`,
+                    log: args.log,
+                });
+                args.log(`↩ re-running phase ${phase.id} — it will be re-audited after execution.`);
+                args.queueDispatch(resumeCmd(path));
+                return path;
+            }
+            // action === 'waive'
+            const reasonRaw = (await args.prompt(`Waive reason for ${phase.id} (one line): `)).trim();
+            const reason = reasonRaw.length > 0 ? reasonRaw : 'waived by user (no reason given)';
+            // §10 Q2 — a light 2-choice category alongside the reason: was the audit
+            // WRONG (false-positive) or is the finding real-but-accepted
+            // (accepted-risk)? Persisted so the audit's FP rate is measurable.
+            // Headless / cancel → accepted-risk (never a false-positive unasserted).
+            const category = await (args.deps?.selectWaiveCategory ?? defaultSelectWaiveCategory)({ phaseId: phase.id });
+            path = await applyAuditResult(path, phase.id, { state: 'waived', waivedReason: reason, waiveCategory: category }, { log: args.log });
+            loaded = loadPlan(path, args.log);
+            if (!loaded)
+                return path;
+            phase = loaded.content.phases.find((p) => p.id === args.executedPhaseId);
+            args.log(chalk.yellow(`✎ audit waived (${category}) for ${phase.id} — reason recorded in the envelope.`));
+        }
+        else if (verdict.state === 'warn') {
+            // Non-blocking tier: ALWAYS shown, concise (Open-Q decision — warns are
+            // never swallowed). The chain continues to the gate + offer below just
+            // like a pass; the notes are already recorded on phase.audit.findings.
+            renderWarnings(args.log, phase.id, verdict.findings);
+        }
+        else {
+            args.log(chalk.green(`✔ audit passed — ${phase.id} verified against the evidence.`));
+        }
+    }
+    /* ── 2. gate + offer ──────────────────────────────────────────────────── */
+    // Review I-2 — mid-pass re-audits stop after the verdict: the pass owner
+    // (runReauditPass) issues one offer at the end.
+    if (args.suppressOffer)
+        return path;
+    const statuses = statusesFromItems(loaded.envelope.interaction.items, loaded.content.phases);
+    const next = computeNextPhase(loaded.content.phases, statuses);
+    if (!next) {
+        // Terminal messages only when this chain changed something — otherwise
+        // finishPlanResume already printed the same conclusion (no duplicates).
+        if (chainWrote) {
+            if (loaded.content.phases.every((p) => isPhaseSatisfied(statuses[p.id], p.audit))) {
+                args.log(...planCompletionLines(loaded.content.phases));
+            }
+            else {
+                const blocked = loaded.content.phases.filter((p) => statuses[p.id] === 'blocked').map((p) => p.id);
+                const unresolved = loaded.content.phases
+                    .filter((p) => isPhaseSatisfied(statuses[p.id]) && !isAuditResolved(p.audit))
+                    .map((p) => `${p.id} (audit ${p.audit?.state ?? 'unknown'})`);
+                const unresolvedNote = unresolved.length > 0 ? ` Unresolved audits: ${unresolved.join(', ')}.` : '';
+                args.log(`No eligible next phase. Blocked: ${blocked.join(', ') || '(none)'}.${unresolvedNote}`);
+            }
+        }
+        return path;
+    }
+    const decision = decideNextPhaseGate({
+        mode: args.mode,
+        nextPhase: { id: next.id, writes: next.writes },
+        prevPhaseAudit: phase?.audit,
+    });
+    if (decision.action === 'stop') {
+        path = await applyPhaseResolution(path, args.executedPhaseId, {
+            lastStop: {
+                phaseId: args.executedPhaseId,
+                reason: decision.stopReason === 'audit-infra' ? 'audit-infra' : 'audit-failed',
+                at: new Date().toISOString(),
+            },
+            summary: `guarded chain stopped: ${decision.stopReason}`,
+            log: args.log,
+        });
+        args.log(substitutePlanToken(decision.banner ?? stoppedBanner('guarded chain stopped', resumeCmd(path)), path));
+        ringBell();
+        return path;
+    }
+    if (decision.action === 'prompt' && decision.stopReason === 'write-phase') {
+        // The prompt IS the stop (guarded semantics) — record it crash-safe
+        // BEFORE blocking on the user, then render the banner + bell.
+        path = await applyPhaseResolution(path, args.executedPhaseId, {
+            lastStop: { phaseId: next.id, reason: 'write-phase', at: new Date().toISOString() },
+            summary: `guarded chain stopped: write-phase consent for ${next.id}`,
+            log: args.log,
+        });
+        args.log(substitutePlanToken(decision.banner ?? '', path));
+        ringBell();
+    }
+    await offerNextPhaseAutoRun({
+        outcome: {
+            savedPath: path,
+            resumeCommand: resumeCmd(path),
+            nextPhaseId: next.id,
+            nextDelegateTo: next.delegateTo,
+        },
+        prompt: args.prompt,
+        queueDispatch: args.queueDispatch,
+        log: args.log,
+        gate: decision,
+    });
+    return path;
+}
+/**
+ * Review I-2 — a re-audit PASS over multiple phases in ONE dispatch. Used by
+ * the repl's re-audit-on-resume branch: usually a single pending/infra phase,
+ * but a guarded hand-edit re-verification lists EVERY hand-edited satisfied
+ * phase (design: "an audit pass over hand-edited statuses"). Each phase runs
+ * the full chain with the offer suppressed except on the last; the saved path
+ * feeds forward so every verdict lands on the latest revision.
+ *
+ * Abort semantics: when a chain iteration queues a dispatch (the user picked
+ * re-run, or the final offer auto/consented), the pass stops — continuing to
+ * audit while a dispatch is pending would race the re-entry. Any phases left
+ * un-audited are named in a warning: hand-edit detection is history-author
+ * based and the pass's own writes wash it away, so they will NOT be
+ * re-detected automatically on the next resume. Stops (blocked/infra) do NOT
+ * abort the pass — infra persists as `infra_failed` (re-caught by the
+ * pending/infra scan next resume) and auditing the remaining phases is still
+ * useful information.
+ */
+export async function runReauditPass(args) {
+    // Task 10 review follow-up — a re-audit dispatch runs NO model turn, so a
+    // raised deviation flag here is never legitimate: it can only be stale
+    // residue from a chain leg that crashed before consuming it (possibly for
+    // a DIFFERENT plan in the same process). Discard it — mirroring the repl's
+    // phase-turn-start discard — or the deviation step inside runPostPhaseChain
+    // would wrongly block the re-audited phase and clearAudit would destroy
+    // the very 'pending' audit crash-safety depends on.
+    getAndResetPlanDeviation();
+    const { phaseIds, ...chainArgs } = args;
+    if (phaseIds.length === 0)
+        return args.savedPath;
+    if (phaseIds.length > 1) {
+        args.log(chalk.dim(`[audit] re-audit pass over ${phaseIds.length} phases: ${phaseIds.join(', ')}`));
+    }
+    let path = args.savedPath;
+    let queued = false;
+    const queueDispatch = (cmd) => { queued = true; args.queueDispatch(cmd); };
+    for (let i = 0; i < phaseIds.length; i++) {
+        const result = await runPostPhaseChain({
+            ...chainArgs,
+            savedPath: path,
+            executedPhaseId: phaseIds[i],
+            forceAudit: true,
+            suppressOffer: i < phaseIds.length - 1,
+            queueDispatch,
+        });
+        if (result)
+            path = result;
+        if (queued) {
+            const remaining = phaseIds.slice(i + 1);
+            if (remaining.length > 0) {
+                args.log(chalk.yellow(`⚠ ${remaining.length} hand-edited phase(s) not re-audited yet: ${remaining.join(', ')} — `
+                    + 'they are not auto-detected after this write; verify them (or re-run their phases) once the queued dispatch completes.'));
+            }
+            break;
+        }
+    }
+    return path;
+}
+/* ── helpers ───────────────────────────────────────────────────────────── */
+function loadPlan(path, log) {
+    try {
+        const envelope = readProjectFile(path);
+        if (envelope.artefactType !== 'plan') {
+            log(chalk.red(`[plan] ${basename(path)} is not a plan envelope — chain skipped.`));
+            return null;
+        }
+        const pc = parsePlanContent(envelope.content);
+        if (!pc.ok) {
+            log(chalk.red(`[plan] ${basename(path)} failed content validation — chain skipped: ${pc.errors[0] ?? ''}`));
+            return null;
+        }
+        return { envelope, content: pc.content };
+    }
+    catch (e) {
+        log(chalk.red(`[plan] could not load ${basename(path)} — ${e instanceof Error ? e.message : String(e)}`));
+        return null;
+    }
+}
+/**
+ * Terminal bell with the STOPPED banner — TTY only (a piped/CI stream must
+ * never receive a raw BEL byte).
+ */
+function ringBell() {
+    if (process.stdout.isTTY)
+        process.stdout.write('\u0007');
+}
+/** STOPPED banner in the plan-gate style, with the REAL resume command. */
+function stoppedBanner(reason, resumeCommand) {
+    return `\n■ STOPPED — ${reason}\n  Resume with: ${resumeCommand}\n`;
+}
+/**
+ * Task 3 left the gate banner's `@<plan>` placeholder literal (the pure
+ * module doesn't know the saved path) — substitute the real basename here.
+ */
+export function substitutePlanToken(banner, savedPath) {
+    return banner.replace(/@<plan>/g, `@${basename(savedPath)}`);
+}
+function clampInfra(msg) {
+    const flat = msg.replace(/\s+/g, ' ').trim();
+    return flat.length > INFRA_RENDER_CHARS ? flat.slice(0, INFRA_RENDER_CHARS - 1).trimEnd() + '…' : flat;
+}
+function renderFindings(log, phaseId, findings) {
+    log('', chalk.red(`✖ audit FAILED for phase ${phaseId}:`));
+    const shown = findings.length > 0 ? findings : ['(auditor returned no findings text)'];
+    shown.forEach((f, i) => log(`  ${i + 1}. ${f}`));
+}
+/**
+ * Confidence-tiered redesign (2026-07-08) — the concise, always-shown render
+ * for a NON-BLOCKING warn verdict. Mirrors renderFindings' shape but frames the
+ * phase as passed-with-notes (the chain continues). Each finding is already
+ * formatted "[W1] detail" by the auditor (plan-audit.renderFinding).
+ */
+function renderWarnings(log, phaseId, findings) {
+    const n = findings.length;
+    log('', chalk.yellow(`⚠ audit passed with ${n} note${n === 1 ? '' : 's'} for phase ${phaseId}:`));
+    const shown = n > 0 ? findings : ['(auditor returned a warn verdict with no note detail)'];
+    shown.forEach((f, i) => log(`  ${i + 1}. ${f}`));
+}
+/**
+ * audit-infra-continue (2026-07-09) — the LOUD, always-shown note for an
+ * audit that COULD NOT RUN. Distinct from warn's "passed with N notes": this
+ * frames the phase as unverified-but-proceeding, is explicit that the audit
+ * INFRASTRUCTURE failed (not the work), reassures that the phase's own exit
+ * gate passed, and points at the off-switch for a persistent outage — a
+ * pointer, not a forced prompt. Never swallowed (the chain continues, so
+ * nothing else surfaces this).
+ */
+function renderAuditNotRun(log, phaseId, reason, resumeCommand) {
+    log('', chalk.yellow(`⚠ audit could not run for phase ${phaseId} (audit infrastructure failed after 3 attempts — the model call returned no output).`), chalk.yellow('  This phase is NOT audit-verified; its own exit gate (activation + ATC) passed. Proceeding.'), chalk.dim(`  reason: ${reason}`), chalk.dim(`  If the auditor keeps failing, run with --no-audit (or set audit off in config) to stop retrying; resume as usual: ${resumeCommand}`));
+}
+/**
+ * Shared menu surface for the audit-resolution selects. Mirrors
+ * safety-confirm.ts: headless → no decision (fail-closed, nothing written);
+ * Ink → askQuestionEmitter choice modal; classic → inquirer select.
+ */
+async function selectAuditAction(args) {
+    const { isHeadless, shouldUseInk } = await import('../renderer/tty.js');
+    if (isHeadless())
+        return 'none';
+    if (shouldUseInk()) {
+        // D-C — this modal opens in the POST-PHASE chain, after the phase turn
+        // ended. Its sibling gate presentSafetyConfirmation (repl/safety-confirm.ts)
+        // documents the exact failure this caused live: opening the askQuestion
+        // modal while another render source (the in-place tool spinner, a ticking
+        // turn-status row) still repaints the Ink frame lets the first keystroke
+        // LEAK past the modal and auto-select its FIRST choice. Here the first
+        // choice is "Re-run phase", so the menu never visibly rendered and the
+        // phase silently re-ran — the reported symptom. Claim exclusive input
+        // focus the same way safety-confirm does: stop the spinner, freeze the
+        // status row, restore both in the finally.
+        const { clearActiveSpinner } = await import('../renderer/tool-widget.js');
+        const { turnStatusEmitter } = await import('../ui/turn-status-emitter.js');
+        const { askQuestionEmitter } = await import('../ui/ask-question-emitter.js');
+        clearActiveSpinner();
+        const statusWasActive = turnStatusEmitter.snapshot().active;
+        if (statusWasActive)
+            turnStatusEmitter.pause();
+        try {
+            const res = await askQuestionEmitter.request({
+                id: args.id,
+                question: args.question,
+                context: args.context,
+                kind: 'choice',
+                choices: args.choices,
+            });
+            if (res.cancelled || res.answer == null)
+                return 'none';
+            return coerceAction(res.answer, args.choices);
+        }
+        finally {
+            if (statusWasActive)
+                turnStatusEmitter.resume();
+        }
+    }
+    const { select } = await import('@inquirer/prompts');
+    const { withInquirer } = await import('../repl/inquirer-guard.js');
+    const { inquirerTheme } = await import('../repl/inquirer-theme.js');
+    const picked = await withInquirer(() => select({
+        message: args.question,
+        theme: inquirerTheme,
+        choices: args.choices.map((c) => ({ value: c.value, name: c.label })),
+    }));
+    return coerceAction(picked, args.choices);
+}
+/**
+ * D-C — fail CLOSED on any answer that is not one of this menu's own choice
+ * values. `'' ?? 'none'` did NOT catch an empty-string answer (nullish
+ * coalescing only guards null/undefined), so a stray/blank answer used to fall
+ * through the runPostPhaseChain switch to a silent default. Anything the menu
+ * did not explicitly offer maps to 'none' (stop, no auto-action).
+ */
+function coerceAction(answer, choices) {
+    return choices.some((c) => c.value === answer) ? answer : 'none';
+}
+/** Production failed-verdict menu (see selectAuditAction for the surface). */
+async function defaultSelectFailureAction(a) {
+    return selectAuditAction({
+        id: 'plan-audit-failed',
+        question: `Audit failed for phase ${a.phaseId} — what now?`,
+        context: a.findings.map((f, i) => `${i + 1}. ${f}`).join('\n'),
+        choices: [
+            { value: 'rerun', label: 'Re-run phase (re-audited after execution)' },
+            { value: 'waive', label: 'Waive audit (record a one-line reason)' },
+            { value: 'blocked', label: 'Mark phase blocked' },
+        ],
+    });
+}
+/**
+ * §10 Q2 (audit-confidence redesign) — production waive-category menu. A LIGHT
+ * 2-choice shown right after the waive-reason prompt so the audit's real
+ * false-positive rate is measurable. Same surface as selectAuditAction, but
+ * headless / cancel / stray answer → 'accepted-risk' (the CONSERVATIVE default:
+ * a waive no human explicitly labelled a false-positive is recorded as
+ * accepted-risk, so the measured FP rate never over-counts). Never hangs.
+ */
+async function defaultSelectWaiveCategory(a) {
+    const { isHeadless, shouldUseInk } = await import('../renderer/tty.js');
+    if (isHeadless())
+        return 'accepted-risk';
+    const question = `Waiving ${a.phaseId} — why? (measures the audit's false-positive rate)`;
+    const choices = [
+        { value: 'accepted-risk', label: 'Accepted risk — the finding is real, I accept it and proceed' },
+        { value: 'false-positive', label: 'False positive — the audit was wrong, the work is actually fine' },
+    ];
+    const coerce = (answer) => choices.some((c) => c.value === answer) ? answer : 'accepted-risk';
+    if (shouldUseInk()) {
+        // Same input-focus discipline as selectAuditAction — this modal opens in
+        // the post-phase chain, so a leaked keystroke must not auto-select choice 1.
+        const { clearActiveSpinner } = await import('../renderer/tool-widget.js');
+        const { turnStatusEmitter } = await import('../ui/turn-status-emitter.js');
+        const { askQuestionEmitter } = await import('../ui/ask-question-emitter.js');
+        clearActiveSpinner();
+        const statusWasActive = turnStatusEmitter.snapshot().active;
+        if (statusWasActive)
+            turnStatusEmitter.pause();
+        try {
+            const res = await askQuestionEmitter.request({
+                id: 'plan-waive-category',
+                question,
+                kind: 'choice',
+                choices,
+            });
+            if (res.cancelled || res.answer == null)
+                return 'accepted-risk';
+            return coerce(res.answer);
+        }
+        finally {
+            if (statusWasActive)
+                turnStatusEmitter.resume();
+        }
+    }
+    const { select } = await import('@inquirer/prompts');
+    const { withInquirer } = await import('../repl/inquirer-guard.js');
+    const { inquirerTheme } = await import('../repl/inquirer-theme.js');
+    const picked = await withInquirer(() => select({
+        message: question,
+        theme: inquirerTheme,
+        choices: choices.map((c) => ({ value: c.value, name: c.label })),
+    }));
+    return coerce(picked);
+}
+/**
+ * Audit spend surfaces twice: a dim line next to the turn footer (the
+ * `audit` entry) and a labelled turn-0 line in the session cost JSONL —
+ * the audit runs in its own isolated session, so without this its tokens
+ * would be invisible to the user's cost trail. Best-effort, never throws.
+ */
+function renderAuditCost(args, cost) {
+    try {
+        const tok = cost.tokens.input + cost.tokens.output;
+        const usd = computeCost(cost.model, cost.tokens);
+        args.log(chalk.dim(`[audit] ${tok.toLocaleString()} tok · ${formatCost(usd)} (${cost.model})`));
+        void appendCostLine(args.sessionId, {
+            ...buildEntry({ turn: 0, model: cost.model, tokens: cost.tokens, duration_ms: cost.durationMs }),
+            label: 'audit',
+        });
+    }
+    catch {
+        // observability only
+    }
+}