muonroi-cli 1.8.4 → 1.8.5

package/dist/src/council/clarifier.js

@@ -1,5 +1,5 @@
 import { pickCouncilTaskModel } from "./leader.js";
-import { tracedGenerate } from "./llm.js";
+import { tracedGenerate, tracedGenerateWithFallback } from "./llm.js";
 import { phaseDone, phaseError, phaseStart } from "./phase-events.js";
 import { buildClarificationPrompt, buildReadinessJudgePrompt, buildSpecSynthesisPrompt } from "./prompts.js";
 /** P5: Hard cap on clarification rounds regardless of judge verdict. */
@@ -138,6 +138,45 @@ export function buildClarifyOptions(suggestions, recommended) {
     }
     return { options, defaultIndex };
 }
+/**
+ * Build council options from the model's richer `{label, description,
+ * recommended}` objects, preserving each choice's explanation as `description`
+ * and pointing `defaultIndex` at the option the model flagged `recommended`
+ * (falling back to the first when none is flagged). The same "Type something" /
+ * "Chat about this" escape-hatches are appended as in `buildClarifyOptions`.
+ * Pure + exported for unit testing.
+ */
+export function buildClarifyOptionsRich(specs) {
+    const cleaned = (specs ?? []).filter((s) => !!s && typeof s.label === "string" && s.label.trim().length > 0);
+    const choices = cleaned.map((s) => ({
+        label: s.label.trim(),
+        value: s.label.trim(),
+        kind: "choice",
+        ...(typeof s.description === "string" && s.description.trim().length > 0
+            ? { description: s.description.trim() }
+            : {}),
+    }));
+    const options = [
+        ...choices,
+        {
+            label: "Type something",
+            description: "Nhập câu trả lời tự do",
+            value: "",
+            kind: "freetext",
+        },
+        {
+            label: "Chat about this",
+            description: "Thảo luận thêm trước khi trả lời",
+            value: "",
+            kind: "chat",
+        },
+    ];
+    let defaultIndex;
+    const recIdx = cleaned.findIndex((s) => s.recommended === true);
+    if (recIdx !== -1)
+        defaultIndex = recIdx;
+    return { options, defaultIndex };
+}
 export async function* runClarification(topic, leaderModelId, conversationContext, respondToQuestion, llm, signal, seedQuestions, maxRounds, 
 /**
  * Optional pre-filled answers keyed by seed-question id. When the loop's
@@ -152,7 +191,13 @@ prefillAnswers,
  * a cheaper tier model on the same provider as the leader. Falls back to
  * the leader model if no cheaper model is cataloged. Default false.
  */
-costAware = false) {
+costAware = false, 
+/**
+ * Healthy panel models to fall back to when the leader's cost-tier spec-synth
+ * model is on a failing proxy — keeps the spec's ≥3 observable criteria (and
+ * thus a meaningful leader eval) instead of degrading to one generic criterion.
+ */
+fallbackModels = []) {
     // P5: use MAX_CLARIFY_ROUNDS (12) as the hard cap; respect explicit override
     // from callers that pass maxRounds (e.g. tests that want old 3-round behavior).
     const max = typeof maxRounds === "number" && maxRounds > 0 ? maxRounds : MAX_CLARIFY_ROUNDS;
@@ -284,7 +329,16 @@ costAware = false) {
                 continue;
             }
             const questionId = crypto.randomUUID();
-            const { options, defaultIndex } = buildClarifyOptions(q.suggestions, q.recommended);
+            // Prefer the model's richer {label, description, recommended} options so
+            // every choice shows its own explanation + the recommended default is
+            // pre-selected. Fall back to the legacy string `suggestions` shape (PIL
+            // gray-area seeds and any model still emitting the old format).
+            const { options, defaultIndex } = q.options && q.options.length > 0
+                ? buildClarifyOptionsRich(q.options)
+                : buildClarifyOptions(q.suggestions, q.recommended);
+            // Keep the deprecated `suggestions` mirror populated for consumers that
+            // still read it (audit/replay), deriving labels from rich options.
+            const suggestionLabels = q.suggestions ?? (q.options ? q.options.map((o) => o.label).filter((l) => typeof l === "string") : undefined);
             yield {
                 type: "council_question",
                 content: `**${q.question}**\n${q.why ? `> ${q.why}` : ""}`,
@@ -293,7 +347,7 @@ costAware = false) {
                     phase: "clarify",
                     question: q.question,
                     context: q.why,
-                    suggestions: q.suggestions,
+                    suggestions: suggestionLabels,
                     options,
                     isRequired: q.isRequired,
                     defaultIndex,
@@ -329,7 +383,7 @@ costAware = false) {
         startedAt: phaseStartedAt,
         detail: allQA.length > 0 ? `${allQA.length} Q&A` : "no clarification needed",
     });
-    const spec = yield* synthesizeSpec(topic, conversationContext, allQA, leaderModelId, llm, costAware);
+    const spec = yield* synthesizeSpec(topic, conversationContext, allQA, leaderModelId, llm, costAware, fallbackModels);
     // P5: attach ready-gate metadata to the returned spec
     spec.confidenceScore = gateConfidence;
     spec.remainingGaps = gateGaps;
@@ -355,13 +409,18 @@ costAware = false) {
     };
     return spec;
 }
-export function buildSpecFromTopic(topic, _conversationContext) {
+export function buildSpecFromTopic(topic, conversationContext) {
     return {
         problemStatement: topic,
         constraints: [],
         successCriteria: [`Address the topic: ${topic.slice(0, 100)}`],
         scope: "Determined by conversation context",
         rawQA: [],
+        // Carry the session/task context onto the spec so every debate stage (not
+        // just the opening) can stay anchored to the parent task. Previously this
+        // argument was dropped (prefixed `_`), which is why auto-council debates saw
+        // only the isolated sub-task and drifted off-topic.
+        parentContext: conversationContext?.trim() || undefined,
     };
 }
 /**
@@ -374,7 +433,7 @@ export function buildSpecFromTopic(topic, _conversationContext) {
  * We LLM-extract criteria/constraints/scope from the topic when QA is empty.
  * Falls back to the original buildSpecFromTopic if the LLM call fails.
  */
-async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware) {
+async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware, fallbackModels = []) {
     const system = `You are extracting an implicit specification from a short topic statement. ` +
         `The user did not answer clarification questions, but the topic itself often ` +
         `implies scope, criteria, and constraints. Tease them out.\n\n` +
@@ -396,16 +455,21 @@ async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId
         `- Write all fields in the user's language (detected from the topic).`;
     const prompt = `## Topic\n${topic}\n\n${conversationContext ? `## Context\n${conversationContext}\n` : ""}`;
     try {
+        // Model-fallback: the cost-tier synth model can sit on a flaky proxy
+        // (Console Go glm/kimi → "Upstream request failed"). Falling back to
+        // buildSpecFromTopic yields a single generic criterion, which makes the
+        // leader eval read a vague "1/1 criteria met". Retry on healthy panel models
+        // first so the spec keeps its ≥3 observable criteria.
         const synthModel = pickCouncilTaskModel("spec_synthesis", leaderModelId, costAware);
-        const raw = yield* tracedGenerate(llm, {
+        const raw = yield* tracedGenerateWithFallback(llm, {
             phase: "synthesis",
             label: "Inferring spec from topic (no clarification answers)",
-            modelId: synthModel,
+            models: [synthModel, ...fallbackModels],
             system,
             prompt,
             maxTokens: 1024,
         });
-        const match = raw.match(/\{[\s\S]*\}/);
+        const match = raw?.match(/\{[\s\S]*\}/);
         if (match) {
             const parsed = JSON.parse(match[0]);
             const criteria = Array.isArray(parsed.successCriteria) && parsed.successCriteria.length >= 1
@@ -429,12 +493,12 @@ async function* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId
     }
     return buildSpecFromTopic(topic, conversationContext);
 }
-async function* synthesizeSpec(topic, conversationContext, qa, leaderModelId, llm, costAware = false) {
+async function* synthesizeSpec(topic, conversationContext, qa, leaderModelId, llm, costAware = false, fallbackModels = []) {
     if (qa.length === 0) {
         // Clarifier asked 0 questions OR user skipped all of them. Use the LLM to
         // pull implicit criteria/constraints/scope from the topic alone instead of
         // returning the single-criterion fallback that makes leader-eval trivial.
-        return yield* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware);
+        return yield* inferSpecFromTopicOnly(topic, conversationContext, leaderModelId, llm, costAware, fallbackModels);
     }
     const { system, prompt } = buildSpecSynthesisPrompt(topic, conversationContext, qa);
     const resolved = {};
@@ -444,16 +508,18 @@ async function* synthesizeSpec(topic, conversationContext, qa, leaderModelId, ll
         }
     }
     try {
+        // Model-fallback (see inferSpecFromTopicOnly): keep the ≥3-criteria spec even
+        // when the leader's cost-tier synth model is on a failing proxy.
         const synthModel = pickCouncilTaskModel("spec_synthesis", leaderModelId, costAware);
-        const raw = yield* tracedGenerate(llm, {
+        const raw = yield* tracedGenerateWithFallback(llm, {
             phase: "synthesis",
             label: "Synthesizing clarified spec",
-            modelId: synthModel,
+            models: [synthModel, ...fallbackModels],
             system,
             prompt,
             maxTokens: 2048,
         });
-        const match = raw.match(/\{[\s\S]*\}/);
+        const match = raw?.match(/\{[\s\S]*\}/);
         if (match) {
             const parsed = JSON.parse(match[0]);
             return {

package/dist/src/council/context.js

@@ -98,7 +98,7 @@ function getCompactionText(msg) {
         return null;
     return msg.content;
 }
-function extractUserText(content) {
+function extractText(content) {
     if (typeof content === "string")
         return content;
     if (Array.isArray(content)) {
@@ -109,40 +109,74 @@ function extractUserText(content) {
     }
     return "";
 }
+/** Filter assistant messages to exclude tool-call-only turns (tool_use + tool_result
+ *  pairs that carry no analytical text). An assistant turn with ≥80 chars of text
+ *  content is considered "analytical" (contains decisions, analysis, code, or plans). */
+function isAnalyticalAssistant(content) {
+    const text = extractText(content);
+    return text.trim().length >= 80;
+}
+/** Maximum total characters for the built context string. Raised from 12K to 32K
+ *  (~8K tokens) so council participants get meaningful session history rather than
+ *  only 5 user-message snippets. */
+const MAX_CONTEXT_CHARS = 32_000;
 export function buildCouncilContext(messages) {
     const parts = [];
+    // 1. Compaction summary (first message if it's a system compaction)
     if (messages.length > 0 && isCompactionSummary(messages[0])) {
         const summary = getCompactionText(messages[0]);
         if (summary) {
             parts.push(`## Session Context (from compaction summary)\n${summary}`);
         }
     }
-    const userMessages = [];
-    for (let i = messages.length - 1; i >= 0 && userMessages.length < 5; i--) {
+    // 2. Recent conversation turns — scan BOTH user + analytical assistant messages
+    //    from the tail, capturing at most 8 meaningful entries.
+    //    Previously only captured 5 user messages — lost ALL assistant analysis,
+    //    code changes, and decisions made during the session.
+    const conversationTurns = [];
+    for (let i = messages.length - 1; i >= 0 && conversationTurns.length < 8; i--) {
         const msg = messages[i];
         if (msg.role === "user") {
-            const text = extractUserText(msg.content);
+            const text = extractText(msg.content);
+            if (text.trim()) {
+                conversationTurns.unshift(`[User] ${text.slice(0, 3000).trim()}`);
+            }
+        }
+        else if (msg.role === "assistant" && isAnalyticalAssistant(msg.content)) {
+            const text = extractText(msg.content);
             if (text.trim()) {
-                userMessages.unshift(`- ${text.slice(0, 2000).trim()}`);
+                // Cap assistant text to 1500 chars — enough to convey analysis/decisions
+                // without blowing the context budget on long code outputs.
+                conversationTurns.unshift(`[Assistant] ${text.slice(0, 1500).trim()}`);
             }
         }
     }
-    if (userMessages.length > 0) {
-        parts.push(`## Recent User Messages\n${userMessages.join("\n")}`);
+    if (conversationTurns.length > 0) {
+        parts.push(`## Recent Conversation\n${conversationTurns.join("\n\n")}`);
     }
-    const councilMemories = [];
+    // 3. Key decisions from system messages (task outcomes, decisions, plans)
+    const decisionMsgs = [];
     for (const msg of messages) {
-        if (msg.role === "system" && typeof msg.content === "string" && msg.content.includes("[Council Memory]")) {
-            councilMemories.push(msg.content);
+        if (msg.role !== "system" || typeof msg.content !== "string")
+            continue;
+        const c = msg.content;
+        if (c.includes("[Council Memory]") ||
+            c.includes("[Council Decision]") ||
+            c.includes("[Council Action Items]") ||
+            c.includes("[Council Plan Update]") ||
+            c.includes("[Decision]") ||
+            c.includes("[Task Completed]") ||
+            c.includes("[NEEDS HUMAN REVIEW]")) {
+            decisionMsgs.push(c);
         }
     }
-    if (councilMemories.length > 0) {
-        const digests = councilMemories.slice(-2).map(formatCouncilMemoryDigest);
-        parts.push(`## Previous Council Outcomes (cite by role/round)\n${digests.join("\n\n")}`);
+    if (decisionMsgs.length > 0) {
+        const digests = decisionMsgs.slice(-4).map(formatCouncilMemoryDigest);
+        parts.push(`## Key Decisions\n${digests.join("\n\n")}`);
     }
     const combined = parts.join("\n\n---\n\n");
-    if (combined.length > 12000) {
-        return `${combined.slice(0, 12000)}\n\n[... context truncated to fit token budget]`;
+    if (combined.length > MAX_CONTEXT_CHARS) {
+        return `${combined.slice(0, MAX_CONTEXT_CHARS)}\n\n[... context truncated to fit token budget]`;
     }
     return combined;
 }

package/dist/src/council/debate-checkpoint.d.ts

@@ -0,0 +1,129 @@
+/**
+ * src/council/debate-checkpoint.ts
+ *
+ * C (mid-debate checkpoint) — persist the CB-1 council debate's per-round state
+ * so a break mid-debate (provider 5xx on round 5, host crash, cap breach) can
+ * resume from the last completed round instead of re-running the whole debate.
+ *
+ * The debate accumulates all state in RAM (`exchangeLogs`, `active`,
+ * `runningSummary`, `archive`, convergence trackers). Without a checkpoint a
+ * break loses every round — a 5-round multi-provider debate must restart from
+ * round 1. This module owns the on-disk snapshot: `runDebate` writes it after
+ * each completed round and deletes it on normal completion; the resume path
+ * reads it and seeds `runDebate` so it skips research + openings + completed
+ * rounds.
+ *
+ * File: `<checkpointDir>/debate-checkpoint.json` (checkpointDir = the run dir,
+ * `.muonroi-flow/runs/<runId>`). Written atomically (tmp + rename) so a crash
+ * mid-write can never leave a half-JSON file.
+ */
+import type { ClarifiedSpec, CouncilParticipant, DebateArchiveEntry } from "./types.js";
+/** Bump when the checkpoint shape changes incompatibly so stale files are ignored. */
+export declare const DEBATE_CHECKPOINT_VERSION: 1;
+export declare const DEBATE_CHECKPOINT_FILE = "debate-checkpoint.json";
+/**
+ * Serializable snapshot of an in-flight debate, written after each completed
+ * discussion round. `exchangeLogs` (a `Map`) is stored as entry tuples since
+ * JSON has no Map; everything else in the payload is already JSON-native.
+ */
+export interface DebateCheckpoint {
+    version: typeof DEBATE_CHECKPOINT_VERSION;
+    /**
+     * Identity guard — the checkpoint is only restored when it matches the debate
+     * about to run. `problemStatement` pins the spec; `participantModels` pins the
+     * panel. A mismatch (spec changed, panel re-resolved differently) => ignore
+     * the stale checkpoint and run the debate fresh rather than splice wrong state.
+     */
+    problemStatement: string;
+    participantModels: string[];
+    /** Rounds fully completed (transcript + summary persisted). Resume starts at roundCount+1. */
+    roundCount: number;
+    /** Current round budget after any leader/user extensions. */
+    maxRounds: number;
+    /** Accumulated per-pair transcript (Map<pairKey, turns[]> serialized as entries). */
+    exchangeLogs: Array<[string, string[]]>;
+    /** Latest inter-round summary. */
+    runningSummary: string;
+    /** Research findings (so the research phase is not re-run on resume). */
+    researchFindings?: string;
+    /** Surviving participants with their latest position + stance (so openings are not re-run). */
+    active: CouncilParticipant[];
+    /** Citation archive accumulated so far. */
+    archive: DebateArchiveEntry[];
+    /** Convergence continuity: last round's per-criterion met flags. */
+    lastCriteriaMet: boolean[];
+    /** B4 auto-remedy high-water mark of pinned criteria met. */
+    bestCriteriaMetCount: number;
+    /** B4 consecutive evaluated rounds with no new met criterion. */
+    roundsSinceProgress: number;
+    /** Topic carried into the next round from the prior leader nextRoundFocus. */
+    nextTopic?: string;
+    /** Wall-clock the checkpoint was written (ISO). Diagnostics only. */
+    savedAt: string;
+}
+/** Input to {@link buildDebateCheckpoint} — the live round-loop locals. */
+export interface DebateCheckpointInput {
+    problemStatement: string;
+    roundCount: number;
+    maxRounds: number;
+    exchangeLogs: Map<string, string[]>;
+    runningSummary: string;
+    researchFindings?: string;
+    active: CouncilParticipant[];
+    archive: DebateArchiveEntry[];
+    lastCriteriaMet: boolean[];
+    bestCriteriaMetCount: number;
+    roundsSinceProgress: number;
+    nextTopic?: string;
+    /** ISO timestamp; the caller supplies it (Date.now is unavailable in some sandboxes). */
+    savedAt: string;
+}
+/** Build the serializable checkpoint payload from live debate state. */
+export declare function buildDebateCheckpoint(input: DebateCheckpointInput): DebateCheckpoint;
+/** Rehydrate `exchangeLogs` from the serialized entry tuples. */
+export declare function restoreExchangeLogs(cp: DebateCheckpoint): Map<string, string[]>;
+/**
+ * Whether `cp` describes the debate that is about to run. Guards against
+ * splicing a stale checkpoint (different question, re-resolved panel) into a
+ * fresh debate. Participant order is not significant; the model SET must match.
+ */
+export declare function checkpointMatches(cp: DebateCheckpoint, problemStatement: string, participantModels: string[]): boolean;
+/**
+ * Atomically write the checkpoint to `<dir>/debate-checkpoint.json`.
+ * Non-fatal: a checkpoint write failure must never break the live debate — it
+ * only forfeits resumability for that round. Logs with context (No-Silent-Catch).
+ */
+export declare function writeDebateCheckpoint(dir: string, cp: DebateCheckpoint): Promise<void>;
+/**
+ * Read + parse the checkpoint. Returns null when absent or unparseable (a
+ * corrupt checkpoint must not crash resume — the debate just runs fresh).
+ */
+export declare function readDebateCheckpoint(dir: string): Promise<DebateCheckpoint | null>;
+/**
+ * Delete the checkpoint (debate completed normally, or the run was aborted).
+ * Non-fatal — a leftover checkpoint is only re-validated (and discarded on
+ * mismatch) on the next resume, never silently mis-applied.
+ */
+export declare function deleteDebateCheckpoint(dir: string): Promise<void>;
+export declare const DEBATE_INPUTS_FILE = "debate-inputs.json";
+/**
+ * C-v2 — the minimal gather-stage outputs needed to re-enter the council debate
+ * on a fresh session (cross-process resume) WITHOUT re-running the interactive
+ * discovery + interview. Persisted once at debate start; the loop-driver resume
+ * entry restores `clarifiedSpec` + `conversationContext` and jumps straight to
+ * the research/debate stage (participants + leader are re-resolved from the
+ * session model deterministically, then matched against the checkpoint panel).
+ */
+export interface DebateInputs {
+    version: typeof DEBATE_CHECKPOINT_VERSION;
+    problemStatement: string;
+    clarifiedSpec: ClarifiedSpec;
+    conversationContext: string;
+    savedAt: string;
+}
+/** Atomically persist the debate inputs. Non-fatal on failure (forfeits cross-session resume only). */
+export declare function writeDebateInputs(dir: string, inputs: DebateInputs): Promise<void>;
+/** Read the debate inputs. Returns null when absent/unparseable/version-mismatched. */
+export declare function readDebateInputs(dir: string): Promise<DebateInputs | null>;
+/** Delete the debate inputs (debate + scoping finished, or run aborted). Non-fatal. */
+export declare function deleteDebateInputs(dir: string): Promise<void>;

package/dist/src/council/debate-checkpoint.js

@@ -0,0 +1,176 @@
+/**
+ * src/council/debate-checkpoint.ts
+ *
+ * C (mid-debate checkpoint) — persist the CB-1 council debate's per-round state
+ * so a break mid-debate (provider 5xx on round 5, host crash, cap breach) can
+ * resume from the last completed round instead of re-running the whole debate.
+ *
+ * The debate accumulates all state in RAM (`exchangeLogs`, `active`,
+ * `runningSummary`, `archive`, convergence trackers). Without a checkpoint a
+ * break loses every round — a 5-round multi-provider debate must restart from
+ * round 1. This module owns the on-disk snapshot: `runDebate` writes it after
+ * each completed round and deletes it on normal completion; the resume path
+ * reads it and seeds `runDebate` so it skips research + openings + completed
+ * rounds.
+ *
+ * File: `<checkpointDir>/debate-checkpoint.json` (checkpointDir = the run dir,
+ * `.muonroi-flow/runs/<runId>`). Written atomically (tmp + rename) so a crash
+ * mid-write can never leave a half-JSON file.
+ */
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+/** Bump when the checkpoint shape changes incompatibly so stale files are ignored. */
+export const DEBATE_CHECKPOINT_VERSION = 1;
+export const DEBATE_CHECKPOINT_FILE = "debate-checkpoint.json";
+/** Build the serializable checkpoint payload from live debate state. */
+export function buildDebateCheckpoint(input) {
+    return {
+        version: DEBATE_CHECKPOINT_VERSION,
+        problemStatement: input.problemStatement,
+        participantModels: input.active.map((p) => p.model),
+        roundCount: input.roundCount,
+        maxRounds: input.maxRounds,
+        exchangeLogs: [...input.exchangeLogs.entries()].map(([k, v]) => [k, [...v]]),
+        runningSummary: input.runningSummary,
+        researchFindings: input.researchFindings,
+        active: input.active,
+        archive: input.archive,
+        lastCriteriaMet: [...input.lastCriteriaMet],
+        bestCriteriaMetCount: input.bestCriteriaMetCount,
+        roundsSinceProgress: input.roundsSinceProgress,
+        nextTopic: input.nextTopic,
+        savedAt: input.savedAt,
+    };
+}
+/** Rehydrate `exchangeLogs` from the serialized entry tuples. */
+export function restoreExchangeLogs(cp) {
+    return new Map(cp.exchangeLogs.map(([k, v]) => [k, [...v]]));
+}
+/**
+ * Whether `cp` describes the debate that is about to run. Guards against
+ * splicing a stale checkpoint (different question, re-resolved panel) into a
+ * fresh debate. Participant order is not significant; the model SET must match.
+ */
+export function checkpointMatches(cp, problemStatement, participantModels) {
+    if (cp.version !== DEBATE_CHECKPOINT_VERSION)
+        return false;
+    if (cp.roundCount < 1)
+        return false; // nothing useful to resume from
+    if (cp.problemStatement !== problemStatement)
+        return false;
+    const a = [...cp.participantModels].sort();
+    const b = [...participantModels].sort();
+    if (a.length !== b.length)
+        return false;
+    return a.every((m, i) => m === b[i]);
+}
+/**
+ * Atomically write the checkpoint to `<dir>/debate-checkpoint.json`.
+ * Non-fatal: a checkpoint write failure must never break the live debate — it
+ * only forfeits resumability for that round. Logs with context (No-Silent-Catch).
+ */
+export async function writeDebateCheckpoint(dir, cp) {
+    const finalPath = path.join(dir, DEBATE_CHECKPOINT_FILE);
+    const tmpPath = `${finalPath}.${process.pid}.tmp`;
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(tmpPath, JSON.stringify(cp), "utf8");
+        await fs.rename(tmpPath, finalPath);
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] write failed (dir=${dir}, round=${cp.roundCount}): ${err?.message}`);
+        // Best-effort cleanup of the temp file; ignore if it never got created.
+        await fs.rm(tmpPath, { force: true }).catch(() => { });
+    }
+}
+/**
+ * Read + parse the checkpoint. Returns null when absent or unparseable (a
+ * corrupt checkpoint must not crash resume — the debate just runs fresh).
+ */
+export async function readDebateCheckpoint(dir) {
+    const finalPath = path.join(dir, DEBATE_CHECKPOINT_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(finalPath, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            console.error(`[debate-checkpoint] read failed (dir=${dir}): ${err?.message}`);
+        }
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== DEBATE_CHECKPOINT_VERSION)
+            return null;
+        return parsed;
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] parse failed (dir=${dir}): ${err?.message}`);
+        return null;
+    }
+}
+/**
+ * Delete the checkpoint (debate completed normally, or the run was aborted).
+ * Non-fatal — a leftover checkpoint is only re-validated (and discarded on
+ * mismatch) on the next resume, never silently mis-applied.
+ */
+export async function deleteDebateCheckpoint(dir) {
+    const finalPath = path.join(dir, DEBATE_CHECKPOINT_FILE);
+    try {
+        await fs.rm(finalPath, { force: true });
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] delete failed (dir=${dir}): ${err?.message}`);
+    }
+}
+// ── Debate inputs (C-v2 cross-session resume) ────────────────────────────────
+export const DEBATE_INPUTS_FILE = "debate-inputs.json";
+/** Atomically persist the debate inputs. Non-fatal on failure (forfeits cross-session resume only). */
+export async function writeDebateInputs(dir, inputs) {
+    const finalPath = path.join(dir, DEBATE_INPUTS_FILE);
+    const tmpPath = `${finalPath}.${process.pid}.tmp`;
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(tmpPath, JSON.stringify(inputs), "utf8");
+        await fs.rename(tmpPath, finalPath);
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] inputs write failed (dir=${dir}): ${err?.message}`);
+        await fs.rm(tmpPath, { force: true }).catch(() => { });
+    }
+}
+/** Read the debate inputs. Returns null when absent/unparseable/version-mismatched. */
+export async function readDebateInputs(dir) {
+    const finalPath = path.join(dir, DEBATE_INPUTS_FILE);
+    let raw;
+    try {
+        raw = await fs.readFile(finalPath, "utf8");
+    }
+    catch (err) {
+        if (err?.code !== "ENOENT") {
+            console.error(`[debate-checkpoint] inputs read failed (dir=${dir}): ${err?.message}`);
+        }
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.version !== DEBATE_CHECKPOINT_VERSION)
+            return null;
+        return parsed;
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] inputs parse failed (dir=${dir}): ${err?.message}`);
+        return null;
+    }
+}
+/** Delete the debate inputs (debate + scoping finished, or run aborted). Non-fatal. */
+export async function deleteDebateInputs(dir) {
+    try {
+        await fs.rm(path.join(dir, DEBATE_INPUTS_FILE), { force: true });
+    }
+    catch (err) {
+        console.error(`[debate-checkpoint] inputs delete failed (dir=${dir}): ${err?.message}`);
+    }
+}
+//# sourceMappingURL=debate-checkpoint.js.map