kc-beta 0.7.3 → 0.8.1

package/src/agent/tools/worker-llm-call.js

@@ -49,7 +49,10 @@ export class WorkerLLMCallTool extends BaseTool {
     return (
       "Call a worker LLM at a specified tier (tier1-tier4) for extraction, " +
       "judgment, or other verification tasks. Tier1 is most capable/expensive, " +
-      "tier4 is cheapest. Returns response with model used and token counts."
+      "tier4 is cheapest. Pass `prompt` for a single call OR `prompts: [...]` " +
+      "for batch (parallel up to concurrency=5). Returns response(s) with " +
+      "model used and token counts. v0.8 P2-B: batch mode keeps the engine " +
+      "visible to LLM usage instead of agents bypassing via direct HTTP."
     );
   }
 
@@ -58,29 +61,105 @@ export class WorkerLLMCallTool extends BaseTool {
       type: "object",
       properties: {
         tier: { type: "string", enum: ["tier1", "tier2", "tier3", "tier4"], description: "Worker LLM tier to use" },
-        prompt: { type: "string", description: "The user/task prompt to send" },
-        system_prompt: { type: "string", description: "Optional system prompt for context" },
-        max_tokens: { type: "integer", description: "Maximum tokens in response (default 4096)" },
+        prompt: { type: "string", description: "The user/task prompt to send (single-call mode)" },
+        prompts: {
+          type: "array",
+          items: { type: "string" },
+          description: "Batch mode: array of prompts processed in parallel (up to concurrency=5). All share the same tier + system_prompt. Mutually exclusive with `prompt`.",
+        },
+        system_prompt: { type: "string", description: "Optional system prompt for context (shared across all prompts in batch mode)" },
+        max_tokens: { type: "integer", description: "Maximum tokens per response (default 4096)" },
+        concurrency: { type: "integer", description: "Batch mode only: max parallel requests (default 5, max 10)" },
       },
-      required: ["tier", "prompt"],
+      required: ["tier"],
     };
   }
 
   async execute(input) {
     const tier = input.tier || "tier2";
-    const prompt = input.prompt || "";
     const systemPrompt = input.system_prompt;
     const maxTokens = input.max_tokens || 4096;
 
-    if (!prompt) return new ToolResult("No prompt provided", true);
     if (!this._apiKey) return new ToolResult("Worker LLM API key not configured", true);
 
+    // v0.8 P2-B: batch mode dispatch
+    if (Array.isArray(input.prompts)) {
+      return this._executeBatch(input.prompts, { tier, systemPrompt, maxTokens, concurrency: input.concurrency });
+    }
+
+    const prompt = input.prompt || "";
+    if (!prompt) return new ToolResult("No prompt provided (pass `prompt` for single-call or `prompts: [...]` for batch)", true);
+
+    const result = await this._executeOne({ prompt, tier, systemPrompt, maxTokens });
+    if (result.error) return new ToolResult(result.error, true);
+    return new ToolResult(JSON.stringify(result.payload, null, 2));
+  }
+
+  /**
+   * v0.8 P2-B: process N prompts in parallel with concurrency control.
+   * Returns aggregated results as a JSON array under "results" with
+   * summary stats (total_in, total_out, n_failed). Partial failures don't
+   * fail the whole call — individual results carry their own error flag.
+   */
+  async _executeBatch(prompts, { tier, systemPrompt, maxTokens, concurrency }) {
+    if (prompts.length === 0) return new ToolResult("Empty prompts array", true);
     this._loadTiers();
     const models = this._tierModels[tier] || [];
     if (models.length === 0) {
       return new ToolResult(`No models configured for ${tier}. Check .env TIER1-TIER4 settings.`, true);
     }
 
+    const limit = Math.max(1, Math.min(10, Number.isFinite(concurrency) ? concurrency : 5));
+    const results = new Array(prompts.length);
+    let cursor = 0;
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let nFailed = 0;
+
+    const worker = async () => {
+      while (true) {
+        const idx = cursor++;
+        if (idx >= prompts.length) break;
+        const r = await this._executeOne({ prompt: prompts[idx], tier, systemPrompt, maxTokens });
+        if (r.error) {
+          results[idx] = { index: idx, error: r.error };
+          nFailed++;
+        } else {
+          results[idx] = { index: idx, ...r.payload };
+          tokensIn += r.payload.tokens_in || 0;
+          tokensOut += r.payload.tokens_out || 0;
+        }
+      }
+    };
+
+    await Promise.all(Array.from({ length: limit }, () => worker()));
+
+    const summary = {
+      n_total: prompts.length,
+      n_succeeded: prompts.length - nFailed,
+      n_failed: nFailed,
+      total_tokens_in: tokensIn,
+      total_tokens_out: tokensOut,
+      tier,
+      concurrency: limit,
+      results,
+    };
+    return new ToolResult(JSON.stringify(summary, null, 2), nFailed > 0 && nFailed === prompts.length);
+  }
+
+  /**
+   * Single-prompt path. Returns {error?: string, payload?: {...}}.
+   * Used by both single-call and batch modes; batch dedups the tier
+   * lookup and shares concurrency with multiple in-flight invocations.
+   */
+  async _executeOne({ prompt, tier, systemPrompt, maxTokens }) {
+    if (!prompt) return { error: "Empty prompt" };
+    this._loadTiers();
+    const models = this._tierModels[tier] || [];
+    if (models.length === 0) {
+      return { error: `No models configured for ${tier}. Check .env TIER1-TIER4 settings.` };
+    }
+
     const messages = [];
     if (systemPrompt) messages.push({ role: "system", content: systemPrompt });
     messages.push({ role: "user", content: prompt });
@@ -98,14 +177,15 @@ export class WorkerLLMCallTool extends BaseTool {
         if (resp.ok) {
           const data = await resp.json();
           const usage = data.usage || {};
-          const result = {
-            response: data.choices[0].message.content,
-            model_used: model,
-            tier,
-            tokens_in: usage.prompt_tokens || 0,
-            tokens_out: usage.completion_tokens || 0,
+          return {
+            payload: {
+              response: data.choices[0].message.content,
+              model_used: model,
+              tier,
+              tokens_in: usage.prompt_tokens || 0,
+              tokens_out: usage.completion_tokens || 0,
+            },
           };
-          return new ToolResult(JSON.stringify(result, null, 2));
         }
         lastError = `${model}: HTTP ${resp.status}`;
       } catch (e) {
@@ -113,6 +193,6 @@ export class WorkerLLMCallTool extends BaseTool {
       }
     }
 
-    return new ToolResult(`All models for ${tier} failed. Last error: ${lastError}`, true);
+    return { error: `All models for ${tier} failed. Last error: ${lastError}` };
   }
 }

package/src/agent/tools/workspace-file.js

@@ -30,9 +30,7 @@ export class WorkspaceFileTool extends BaseTool {
       "Read, write, or list files. " +
       "scope='workspace' (default): KC's working directory for rules, skills, workflows, results. " +
       "scope='project': the user's project folder where KC was launched — source regulations and samples live here. " +
-      "Operations: read (returns file content), write (creates/overwrites a file), list (shows directory contents). " +
-      "read returns up to 50,000 chars per call; longer files are truncated. " +
-      "For full reads of regulation/rule documents (typically smaller than this cap), prefer this tool over sandbox_exec."
+      "Operations: read (returns file content), write (creates/overwrites a file), list (shows directory contents)."
     );
   }
 
@@ -163,10 +161,12 @@ export class WorkspaceFileTool extends BaseTool {
       return new ToolResult(msg);
     };
 
-    // v0.7.3: route writes to shared coordination paths (rules/catalog.json,
-    // tasks.json, refs/manifest.json, etc.) through the workspace lock so
-    // concurrent writers serialize. No-op for non-shared paths and for
-    // project-scope writes (project dir is the user's, not shared engine state).
+    // v0.7.4 (re-applied from v0.7.3 G1a): route writes to shared
+    // coordination paths (rules/catalog.json, tasks.json,
+    // refs/manifest.json, etc.) through the workspace lock so
+    // concurrent writers serialize. No-op for non-shared paths and
+    // for project-scope writes (project dir is the user's, not
+    // shared engine state).
     if (scope === "workspace") {
       return await this._workspace.withSharedLockIfApplicable(filePath, doWrite);
     }

package/src/agent/workspace.js

@@ -170,11 +170,12 @@ export class Workspace {
    * @param {{timeoutMs?: number, retryMs?: number, staleMs?: number}} [opts]
    * @returns {Promise<T>}
    */
-  async withFileLock(relPath, fn, { timeoutMs = 10_000, retryMs = 50, staleMs = 60_000 } = {}) {
+  async withFileLock(relPath, fn, { timeoutMs = 10_000, retryMs = 50, staleMs = 60_000, eventLog = null, blockedWarnMs = 5_000 } = {}) {
     const target = this.resolvePath(relPath);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     const lockPath = target + ".lock";
     const start = Date.now();
+    let blockedWarned = false;
 
     while (true) {
       let fd;
@@ -193,7 +194,24 @@ export class Workspace {
           // Lockfile vanished between EEXIST and stat — retry to acquire.
           continue;
         }
-        if (Date.now() - start > timeoutMs) {
+        // v0.8 P4-C: emit lock_blocked event once when wait crosses
+        // blockedWarnMs (default 5s). Lets parent see subagent contention
+        // before the call fails. 贷款 v0.7.5 audit: subagent burned 5 min
+        // on silent lock contention; parent only saw it as a long-running
+        // subagent. Now there's a visible signal.
+        const waited = Date.now() - start;
+        if (!blockedWarned && waited > blockedWarnMs && eventLog?.append) {
+          try {
+            eventLog.append("lock_blocked", {
+              path: relPath,
+              waited_ms: waited,
+              session_id: this.sessionId,
+              pid: process.pid,
+            });
+          } catch { /* best-effort */ }
+          blockedWarned = true;
+        }
+        if (waited > timeoutMs) {
           throw new Error(`Timeout acquiring lock on ${relPath} after ${timeoutMs}ms (held by another engine)`);
         }
         await new Promise((r) => setTimeout(r, retryMs));
@@ -221,8 +239,11 @@ export class Workspace {
    * Lets callsites uniformly wrap their writes without knowing which
    * paths are shared.
    */
-  async withSharedLockIfApplicable(relPath, fn) {
-    if (isSharedCoordinationPath(relPath)) return this.withFileLock(relPath, fn);
+  async withSharedLockIfApplicable(relPath, fn, opts = {}) {
+    // v0.8 P4-C: forward optional {eventLog, ...} through to withFileLock
+    // so lock_blocked events can fire from any call site (workspace_file,
+    // rule_catalog, etc.) once they pass their engine's eventLog.
+    if (isSharedCoordinationPath(relPath)) return this.withFileLock(relPath, fn, opts);
     return fn();
   }
 

package/src/cli/components.js

@@ -89,7 +89,7 @@ function truncateVisual(s, maxCells) {
   return head + "…" + tail;
 }
 
-export function StatusBar({ sessionId, phase, contextTokens, contextLimit }) {
+export function StatusBar({ sessionId, phase, contextTokens, contextLimit, marathonActive }) {
   const samplesRef = useRef([]);
   const peakRef = useRef(0);
 
@@ -136,6 +136,9 @@ export function StatusBar({ sessionId, phase, contextTokens, contextLimit }) {
     h(Text, { dimColor: true, wrap: "truncate-end" }, "  ⏵⏵  KC "),
     h(Text, { dimColor: true, wrap: "truncate-end" }, displaySessionId ? `[${displaySessionId}]` : ""),
     phase ? h(Text, { color: "cyan", wrap: "truncate-end" }, ` ${phase.toUpperCase()}`) : null,
+    // v0.8.1 P8-A: marathon-mode indicator. Only renders when active —
+    // normal interactive mode shows no indicator (avoid clutter).
+    marathonActive ? h(Text, { color: "magenta", bold: true, wrap: "truncate-end" }, "  🏃 MARATHON") : null,
     h(Text, { color: "green", wrap: "truncate-end" }, "  ●  "),
     h(Text, { color: ctxColor, wrap: "truncate-end" }, `CTX: ${ctxLabel}/${limitLabel} (${pct}%)`),
     showPeak ? h(Text, { dimColor: true, wrap: "truncate-end" }, ` · peak ${fmt(peak)}`) : null,

package/src/cli/index.js

@@ -59,6 +59,8 @@ function App({ engine, config }) {
   const [spinnerStatus, setSpinnerStatus] = useState(null);
   const [contextTokens, setContextTokens] = useState(0);
   const [contextLimit, setContextLimit] = useState(config.kcContextLimit || 200000);
+  // v0.8.1 P8-A: marathon-mode indicator for StatusBar.
+  const [marathonActive, setMarathonActive] = useState(false);
   const [taskList, setTaskList] = useState([]);
   const [taskProgress, setTaskProgress] = useState(null);
 
@@ -124,6 +126,11 @@ function App({ engine, config }) {
             setCurrentTool(null);
             setSpinnerStatus(null);
             updateContextStats();
+            // v0.8.1 P8-A: refresh marathon indicator. If the driver
+            // self-terminated (max_wallclock / finalization_settled),
+            // engine clears marathonDriver on next decideNext loop;
+            // we sync the TUI state here.
+            setMarathonActive(engineRef.current.isMarathonActive());
             break;
 
           case "tool_start":
@@ -221,6 +228,9 @@ function App({ engine, config }) {
             "  /sessions            List all sessions\n" +
             "  /resume <name>       Resume a previous session\n" +
             "  /rename <name>       Rename current session\n" +
+            "  /marathon <goal>     Activate marathon mode (chains turns automatically)\n" +
+            "  /marathon off        Deactivate marathon (return to interactive)\n" +
+            "  /marathon status     Show marathon driver state\n" +
             "  /exit                Quit",
         });
         return true;
@@ -593,6 +603,84 @@ function App({ engine, config }) {
         }
         return true;
 
+      case "/marathon": {
+        // v0.8.1 P8-A: inline marathon mode. `/marathon <goal>` activates;
+        // `/marathon off` deactivates; `/marathon status` shows snapshot.
+        const sub = arg.split(/\s+/)[0]?.toLowerCase();
+        if (sub === "off" || sub === "stop") {
+          const final = engineRef.current.exitMarathonMode("user_off");
+          setMarathonActive(false);
+          if (final) {
+            addMessage({
+              role: "system",
+              content: `Marathon mode OFF.\n  decisions: ${final.decisionCount}\n  runtime: ${Math.round(final.runtimeMs / 1000)}s\n  last phase: ${final.currentPhase}`,
+            });
+          } else {
+            addMessage({ role: "system", content: "Marathon was not active." });
+          }
+          return true;
+        }
+        if (sub === "status") {
+          if (!engineRef.current.isMarathonActive()) {
+            addMessage({ role: "system", content: "Marathon mode is OFF." });
+            return true;
+          }
+          const s = engineRef.current.marathonDriver.getStatus();
+          const lines = [
+            `Marathon mode ON`,
+            `  goal: ${s.goal.slice(0, 100)}${s.goal.length > 100 ? "..." : ""}`,
+            `  language: ${s.language}`,
+            `  started: ${s.startedAt}  (${Math.round(s.runtimeMs / 60000)} min ago)`,
+            `  current_phase: ${s.currentPhase}`,
+            `  turns this phase: ${s.turnsThisPhase}`,
+            `  total decisions: ${s.decisionCount}`,
+          ];
+          if (s.recentDecisions?.length) {
+            lines.push(`  recent decisions:`);
+            for (const d of s.recentDecisions.slice(-3)) {
+              lines.push(`    ${d.ts.slice(11, 19)} [${d.template}] ${d.reason}`);
+            }
+          }
+          addMessage({ role: "system", content: lines.join("\n") });
+          return true;
+        }
+        // `/marathon <goal>` — activate
+        if (!arg) {
+          addMessage({
+            role: "system",
+            content:
+              "Usage:\n" +
+              "  /marathon <goal description>   Activate marathon mode with the given goal\n" +
+              "  /marathon off                  Deactivate (return to interactive)\n" +
+              "  /marathon status               Show current driver state\n\n" +
+              "Marathon mode chains turns automatically using templated continuation prompts.\n" +
+              "F5 strict one-phase-per-prompt is bypassed while active. /resume after a crash\n" +
+              "does NOT auto-restore marathon — re-type /marathon to re-engage.",
+          });
+          return true;
+        }
+        try {
+          const status = engineRef.current.enterMarathonMode(arg);
+          setMarathonActive(true);
+          addMessage({
+            role: "system",
+            content:
+              `🏃 Marathon mode ON.\n` +
+              `  goal: ${arg.slice(0, 200)}${arg.length > 200 ? "..." : ""}\n` +
+              `  language: ${status.language}\n` +
+              `  stop conditions: ${Math.round(status.maxWallclockMs / 3600000)}h wall-clock OR 5 turns settled in finalization\n\n` +
+              `Next turn will use the marathon initial prompt. Type /marathon off to disengage.`,
+          });
+          // Immediately trigger a turn with the initial prompt
+          const initialPrompt = engineRef.current.marathonDriver.getInitialPrompt();
+          // Hand the initial prompt to the same runTurn path as a user message
+          runTurn(initialPrompt);
+        } catch (e) {
+          addMessage({ role: "system", content: `Marathon activation failed: ${e.message}` });
+        }
+        return true;
+      }
+
       case "/exit":
       case "/quit":
         // Save state + stop diagnostics before exit
@@ -752,7 +840,7 @@ function App({ engine, config }) {
       placeholderRight: queueSize > 0 ? `(${queueSize} queued)` : null,
     }),
     h(HRule),
-    h(StatusBar, { sessionId, phase, contextTokens, contextLimit }),
+    h(StatusBar, { sessionId, phase, contextTokens, contextLimit, marathonActive }),
   );
 }
 
@@ -821,6 +909,14 @@ export async function main({ languageOverride } = {}) {
   };
   process.on("SIGINT", saveOnExit);
   process.on("SIGTERM", saveOnExit);
+  // v0.8.1 P8-B: SIGHUP coverage. E2E #11 found macOS sends signals to
+  // descendant processes when a Terminal.app window closes or quits;
+  // nohup masks SIGHUP but not SIGTERM, and we already cover SIGTERM.
+  // Adding SIGHUP makes the kc-beta process robust against terminal
+  // teardown even if it's not nohup'd. Without this, a closed terminal
+  // can leave KC half-shut-down (events.jsonl flushed, but no
+  // marathon_detach event, no clean session-state save).
+  process.on("SIGHUP", saveOnExit);
 
   const instance = render(h(App, { engine, config }));
   await instance.waitUntilExit();

package/src/config.js

@@ -21,7 +21,11 @@ function loadGlobalConfig() {
  * Parse a .env file into a key-value object.
  * Handles KEY=VALUE lines, ignores comments and blank lines.
  */
-function loadEnvFile(envPath) {
+// v0.8 P1-B: exported so engine.js can re-overlay workspace .env after
+// the workspace directory is known (cli/index.js calls loadSettings()
+// without a workspace path because the path isn't known until the engine
+// constructs the Workspace object).
+export function loadEnvFile(envPath) {
   if (!fs.existsSync(envPath)) return {};
   // v0.7.0 H9: defend bootstrap against a .env that exists but isn't
   // readable (permission denied, unexpected directory, encoding error,
@@ -90,7 +94,7 @@ export function loadSettings(workspacePath) {
     tier3: env.TIER3 || gc.tiers?.tier3 || "",
     tier4: env.TIER4 || gc.tiers?.tier4 || "",
 
-    // VLM tiers (vision/OCR models). v0.7.3: accept OCR_MODEL_TIER* as
+    // VLM tiers (vision/OCR models). v0.7.4: accept OCR_MODEL_TIER* as
     // alias since template/.env.template + initializer.js seed that name.
     // VLM_TIER* takes precedence when both are set.
     vlmTier1: env.VLM_TIER1 || env.OCR_MODEL_TIER1 || gc.vlm_tiers?.tier1 || "",
@@ -110,7 +114,20 @@ export function loadSettings(workspacePath) {
 
     // Workspace (process.env wins — for parallel benchmark runs)
     kcWorkspaceRoot: penv.KC_WORKSPACE_ROOT || gc.workspace_root || path.join(os.homedir(), ".kc_agent", "workspaces"),
-    kcExecTimeout: parseInt(env.KC_EXEC_TIMEOUT || "30", 10),
+    // v0.8 P1-F sandbox_exec timeout model. Default 120s (Claude Code parity),
+    // max 600s (10 min) ceiling. Agent can pass per-call timeout_ms up to max.
+    // Legacy KC_EXEC_TIMEOUT (seconds) accepted as deprecation alias for default.
+    kcExecDefaultTimeoutMs: parseInt(
+      env.KC_EXEC_DEFAULT_TIMEOUT_MS ||
+      (env.KC_EXEC_TIMEOUT ? String(parseInt(env.KC_EXEC_TIMEOUT, 10) * 1000) : "") ||
+      "120000",
+      10,
+    ),
+    kcExecMaxTimeoutMs: parseInt(env.KC_EXEC_MAX_TIMEOUT_MS || "600000", 10),
+    // Legacy alias kept for any consumer reading it directly. Computed
+    // from the new ms-based field for consistency. New code should read
+    // kcExecDefaultTimeoutMs / kcExecMaxTimeoutMs.
+    kcExecTimeout: parseInt(env.KC_EXEC_TIMEOUT || "120", 10),
 
     // Accuracy thresholds
     skillAccuracy: parseFloat(env.SKILL_ACCURACY || gc.accuracy_threshold?.toString() || "0.9"),

package/src/marathon/driver.js

@@ -0,0 +1,217 @@
+// v0.8.1 P8-A — marathon driver as inline state machine.
+//
+// v0.8.0 shipped this as a separate-process driver (bin/kc-marathon.js)
+// that tailed events.jsonl + wrote prompts to .kc_marathon/inbox.jsonl.
+// E2E #11 audits found both drivers died silently within 10 min when
+// the terminal closed or laptop slept (SIGHUP/SIGTERM unhandled). The
+// engine survived both deaths because it lives in a different process.
+//
+// v0.8.1 redesign per user proposal (2026-05-15):
+//   - Single process: driver runs inline as part of the engine
+//   - Activated via `/marathon <goal>` slash command in kc-beta TUI
+//   - Engine calls decideNext(state) after each turn_complete to get
+//     the next continuation prompt (or null if marathon should end)
+//   - No filesystem IPC (no inbox, no active marker, no state.json)
+//   - State persists via engine's existing session-state.json
+//
+// The state machine logic from v0.8.0 is preserved verbatim — only
+// the I/O wrapper changes. Templates (renderPrompt) unchanged.
+
+import { renderPrompt } from "./prompts.js";
+
+const DEFAULT_STUCK_AFTER_MS = 30 * 60 * 1000;        // 30 min
+const DEFAULT_MAX_WALLCLOCK_MS = 12 * 60 * 60 * 1000; // 12 h
+
+export class MarathonDriver {
+  /**
+   * @param {object} opts
+   * @param {string} opts.goal — the marathon goal-description prompt
+   * @param {string} [opts.language] — "en" or "zh"
+   * @param {number} [opts.maxWallclockMs] — stop after this much wall time
+   * @param {number} [opts.stuckAfterMs] — emit unstick prompt after idle
+   */
+  constructor(opts = {}) {
+    if (!opts.goal || typeof opts.goal !== "string") {
+      throw new Error("MarathonDriver requires a non-empty `goal` string");
+    }
+    this.goal = opts.goal;
+    this.language = opts.language === "zh" ? "zh" : "en";
+    this.maxWallclockMs = opts.maxWallclockMs ?? DEFAULT_MAX_WALLCLOCK_MS;
+    this.stuckAfterMs = opts.stuckAfterMs ?? DEFAULT_STUCK_AFTER_MS;
+
+    this.startedAt = Date.now();
+    this.lastDecisionAt = 0;
+    this.decisionCount = 0;
+    this.currentPhase = "bootstrap";
+    this.lastMilestones = {};
+    this.turnsThisPhase = 0;
+    this.lastEventTs = Date.now();
+    this.initialDelivered = false;
+    this.stopped = false;
+    this.stopReason = null;
+
+    // Decision history (kept in-memory; surfaced in /marathon status).
+    // Bounded to last 100 to cap memory.
+    this.decisions = [];
+  }
+
+  /**
+   * Engine calls this once BEFORE the initial turn after /marathon was
+   * typed. Returns the goal-description prompt to feed into runTurn.
+   */
+  getInitialPrompt() {
+    const out = renderPrompt(
+      "initial",
+      this._stateSnapshot(),
+      this.language,
+    );
+    this._recordDecision("initial", "marathon kickoff", out);
+    this.initialDelivered = true;
+    return out;
+  }
+
+  /**
+   * Engine calls decideNext(state) after each turn_complete event.
+   * Returns { prompt, template, reason } if marathon should continue,
+   * or null if a stop condition is met (engine will exit marathon mode).
+   *
+   * @param {object} state — engine snapshot:
+   *   {currentPhase, milestones, phaseChanged, errorSeen, turnsThisPhase}
+   */
+  decideNext(state = {}) {
+    if (this.stopped) return null;
+
+    // Update tracked state from engine
+    if (state.currentPhase && state.currentPhase !== this.currentPhase) {
+      this.currentPhase = state.currentPhase;
+      this.turnsThisPhase = 0;
+    }
+    if (state.milestones) this.lastMilestones = state.milestones;
+    if (typeof state.turnsThisPhase === "number") {
+      this.turnsThisPhase = state.turnsThisPhase;
+    } else {
+      this.turnsThisPhase += 1;
+    }
+    this.lastEventTs = Date.now();
+
+    // Stop conditions
+    if (this._shouldStop()) {
+      this.stopped = true;
+      // Emit one final "stop" prompt so the agent has a chance to wrap up.
+      const out = renderPrompt("stop", this._stateSnapshot(), this.language);
+      this._recordDecision("stop", this.stopReason, out);
+      return { prompt: out, template: "stop", reason: this.stopReason };
+    }
+
+    let template = "continue_phase";
+    let reason = "turn_complete in same phase";
+
+    if (state.errorSeen) {
+      template = "unstick";
+      reason = "engine emitted error event";
+    } else if (state.phaseChanged) {
+      if (this.currentPhase === "finalization") {
+        template = "finalize";
+        reason = "reached finalization";
+      } else {
+        template = "continue_phase";
+        reason = `entered ${this.currentPhase}`;
+      }
+    } else {
+      const idleMs = Date.now() - this.lastEventTs;
+      if (idleMs > this.stuckAfterMs) {
+        template = "unstick";
+        reason = `idle for ${Math.round(idleMs / 60000)} min`;
+      }
+    }
+
+    const out = renderPrompt(template, this._stateSnapshot(), this.language);
+    this._recordDecision(template, reason, out);
+    return { prompt: out, template, reason };
+  }
+
+  /** User-invoked manual stop (e.g., `/marathon off`). */
+  stop(reason = "user_off") {
+    this.stopped = true;
+    this.stopReason = reason;
+    this._recordDecision("manual_stop", reason, "");
+  }
+
+  /** Snapshot for /marathon status command + audit. */
+  getStatus() {
+    return {
+      active: !this.stopped,
+      goal: this.goal,
+      language: this.language,
+      startedAt: new Date(this.startedAt).toISOString(),
+      runtimeMs: Date.now() - this.startedAt,
+      currentPhase: this.currentPhase,
+      turnsThisPhase: this.turnsThisPhase,
+      decisionCount: this.decisionCount,
+      lastDecisionAt: this.lastDecisionAt ? new Date(this.lastDecisionAt).toISOString() : null,
+      stopReason: this.stopReason,
+      maxWallclockMs: this.maxWallclockMs,
+      stuckAfterMs: this.stuckAfterMs,
+      recentDecisions: this.decisions.slice(-5),
+    };
+  }
+
+  /** Serialize for session-state.json persistence (NOT used for auto-resume per user-locked decision; included for audit visibility only). */
+  toJSON() {
+    return {
+      goal: this.goal,
+      language: this.language,
+      maxWallclockMs: this.maxWallclockMs,
+      stuckAfterMs: this.stuckAfterMs,
+      startedAt: this.startedAt,
+      currentPhase: this.currentPhase,
+      turnsThisPhase: this.turnsThisPhase,
+      decisionCount: this.decisionCount,
+      initialDelivered: this.initialDelivered,
+      stopped: this.stopped,
+      stopReason: this.stopReason,
+      // Note: decisions array not persisted (memory-only)
+    };
+  }
+
+  // ─── internals ──────────────────────────────────────────────────
+
+  _stateSnapshot() {
+    return {
+      goal: this.goal,
+      currentPhase: this.currentPhase,
+      milestones: this.lastMilestones,
+      idleSec: Math.round((Date.now() - this.lastEventTs) / 1000),
+      lastEventType: this._lastEventType || null,
+    };
+  }
+
+  _shouldStop() {
+    if (this.stopped) return true;
+    if (Date.now() - this.startedAt > this.maxWallclockMs) {
+      this.stopReason = "max_wallclock";
+      return true;
+    }
+    if (
+      this.currentPhase === "finalization" &&
+      this.turnsThisPhase >= 5
+    ) {
+      this.stopReason = "finalization_settled";
+      return true;
+    }
+    return false;
+  }
+
+  _recordDecision(template, reason, prompt) {
+    this.decisionCount += 1;
+    this.lastDecisionAt = Date.now();
+    this.decisions.push({
+      ts: new Date().toISOString(),
+      template,
+      reason,
+      currentPhase: this.currentPhase,
+      promptPreview: (prompt || "").slice(0, 200),
+    });
+    if (this.decisions.length > 100) this.decisions.shift();
+  }
+}