glm-coding-router 1.1.1 → 2.0.0

package/dist/handoff/bundle.js

@@ -0,0 +1,203 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../core/logging.js";
+import { gitTopLevel, runGit } from "../core/git.js";
+import { atomicWriteFile } from "../project/atomic-write.js";
+import { CHECKPOINT_FILE_NAME, writeCheckpoint } from "../runs/checkpoint.js";
+/** Where the bundle lands: `<runDir>/handoff/` (doc §17). */
+export const HANDOFF_DIR_NAME = "handoff";
+/** The one provider v2 knows (H2/D5), hardcoded into the H5 handoff block. */
+const ZAI_PROVIDER = "zai.zcode";
+/** H5: v3 §18's cross-provider handoff targets the orchestrator, by name. */
+const ORCHESTRATOR_PROVIDER = "anthropic.claude-code";
+/**
+ * Writes the handoff bundle (doc §17): `checkpoint.json`, `diff.patch`,
+ * `handoff.md`, `handoff.json` under `<runDir>/handoff/`.
+ *
+ * **Never fails the run.** Returns null only when the bundle directory itself
+ * cannot be created; every git call and every file write is individually
+ * guarded, so one degraded section (no diff, no branch, a lost file) becomes a
+ * debug log while the rest of the bundle still reaches disk. The caller prints
+ * the bundle path and carries on regardless — the work on disk is the thing
+ * being rescued here, and it is already safe.
+ *
+ * `diff.patch` is plain `git diff` — tracked changes only, never `git add`
+ * (this repo's no-automatic-git rule is exactly why untracked files get their
+ * own heading in `handoff.md` instead of being staged into the diff). Plain
+ * `git diff` rather than `git diff HEAD` deliberately: the router never stages
+ * anything, and on an unborn HEAD `git diff` still exits 0 where `HEAD` would
+ * fail and needlessly drop the diff section.
+ *
+ * C3: every task-derived string here (title, completed lines, validation
+ * commands, file paths) comes from the checkpoint, whose fields were already
+ * redacted and capped upstream. No prompt body, tool result or LLM response is
+ * ever read, and nothing from the environment is written.
+ */
+export async function writeHandoffBundle(input) {
+    const dir = path.join(input.runDir, HANDOFF_DIR_NAME);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: creating ${dir} failed: ${errorMessage(error)}`);
+        return null;
+    }
+    const handoffMd = path.join(dir, "handoff.md");
+    const handoffJson = path.join(dir, "handoff.json");
+    const checkpointJson = path.join(dir, CHECKPOINT_FILE_NAME);
+    const diffFile = path.join(dir, "diff.patch");
+    const git = input.runGit ?? runGit;
+    const workspace = await workspaceInfo(input.cwd, git);
+    const diff = workspace.isRepo ? await trackedDiff(input.cwd, git) : null;
+    const diffPatch = diff !== null && guardedWrite(diffFile, diff) ? diffFile : null;
+    // Reuses the never-throwing writer so the bundle's copy is byte-identical to
+    // the one the run directory itself may already hold.
+    writeCheckpoint(dir, input.checkpoint);
+    guardedWrite(handoffMd, renderMarkdown(input, workspace, diffPatch !== null));
+    guardedWrite(handoffJson, JSON.stringify({
+        // Doc §18's shape, verbatim in key order...
+        status: "handoff_required",
+        run_id: input.runId,
+        reason: input.reason,
+        completed: input.checkpoint.completed,
+        pending: input.checkpoint.pending,
+        handoff_path: handoffMd,
+        // ...then hedge H5: v3 §17's from/to and v4 §20's workspace block, so
+        // a v2 bundle stays readable by v3/v4 without a migration pass.
+        from: { provider: ZAI_PROVIDER, role: input.role },
+        to: { provider: ORCHESTRATOR_PROVIDER, role: "orchestrator" },
+        workspace: { repo: workspace.repo, worktree: workspace.worktree, branch: workspace.branch },
+        bundle: { checkpoint: checkpointJson, diff: diffPatch, markdown: handoffMd },
+    }, null, 2) + "\n");
+    return { dir, handoffMd, handoffJson, checkpointJson, diffPatch };
+}
+/**
+ * Everything C3 allows a human to read: the title (the checkpoint's first
+ * pending entry), the run id and reason, done/remaining/files/validation from
+ * the checkpoint, and the git facts. Untracked files get their OWN heading
+ * because they are invisible to `diff.patch` — a reader who assumes the patch
+ * is the whole story silently loses them.
+ */
+function renderMarkdown(input, workspace, diffWritten) {
+    const checkpoint = input.checkpoint;
+    const title = checkpoint.pending.length > 0 ? checkpoint.pending[0] : "continue the task";
+    const workspaceLine = workspace.isRepo
+        ? `${workspace.repo ?? "?"} on ${workspace.branch ?? "(detached HEAD)"} — ${workspace.worktree ?? input.cwd}`
+        : "not a git repository";
+    const lines = [
+        `# Handoff: ${title}`,
+        "",
+        `- Run: ${input.runId}`,
+        `- Reason: ${input.reason}`,
+        `- Role: ${input.role} (model ${input.model})`,
+        `- Workspace: ${workspaceLine}`,
+        "",
+        "## Done",
+        ...bullets(checkpoint.completed, "(no completed turns recorded)"),
+        "",
+        "## Remaining",
+        ...bullets(checkpoint.pending, "(nothing recorded — see the run's events)"),
+        "",
+        "## Files changed",
+        ...bullets(checkpoint.filesChanged, "(none)"),
+    ];
+    if (workspace.isRepo) {
+        // The heading is the warning: these files are NOT inside diff.patch.
+        lines.push("", "## Untracked files (not in diff.patch)", ...bullets(workspace.untracked, "(none)"));
+    }
+    lines.push("", "## Validation still owed", ...bullets(checkpoint.validationPending, "(none)"), "", "## Diff");
+    if (!workspace.isRepo) {
+        lines.push("Not a git repository — no `diff.patch` was written.");
+    }
+    else if (!diffWritten) {
+        lines.push("Tracked changes could not be captured — `diff.patch` was not written. Run `git diff` yourself.");
+    }
+    else {
+        lines.push("Tracked changes are in `diff.patch`. Untracked files are the ones listed above, not in the patch.");
+    }
+    lines.push("", "## Next step", "", `Continue the task in the same worktree (\`${input.cwd}\`) — pick up from "Remaining" above instead of re-running the worker from scratch.`, "");
+    return lines.join("\n");
+}
+function bullets(items, empty) {
+    return items.length > 0 ? items.map((item) => `- ${item}`) : [`- ${empty}`];
+}
+/** One guard per git question, so a broken answer degrades alone. */
+async function workspaceInfo(cwd, git) {
+    let topLevel;
+    try {
+        // gitTopLevel rejects (rather than resolving) when git itself is missing,
+        // so even repo detection is inside the guard.
+        topLevel = await gitTopLevel(cwd, git);
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: repo detection in ${cwd} failed: ${errorMessage(error)}`);
+        topLevel = undefined;
+    }
+    if (topLevel === undefined) {
+        return { isRepo: false, repo: null, worktree: null, branch: null, untracked: [] };
+    }
+    const branch = await currentBranch(cwd, git);
+    const untracked = await untrackedFiles(cwd, git);
+    return { isRepo: true, repo: path.basename(topLevel), worktree: topLevel, branch, untracked };
+}
+async function currentBranch(cwd, git) {
+    try {
+        const result = await git(["branch", "--show-current"], cwd);
+        if (result.code !== 0) {
+            logger.debug(`handoff bundle: branch lookup in ${cwd} exited ${result.code}`);
+            return null;
+        }
+        // Empty output is a detached HEAD — truthful as null, not as "".
+        const branch = result.stdout.trim();
+        return branch.length > 0 ? branch : null;
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: branch lookup in ${cwd} failed: ${errorMessage(error)}`);
+        return null;
+    }
+}
+async function untrackedFiles(cwd, git) {
+    try {
+        const result = await git(["status", "--porcelain", "-z"], cwd);
+        if (result.code !== 0) {
+            logger.debug(`handoff bundle: status in ${cwd} exited ${result.code}`);
+            return [];
+        }
+        // -z: NUL-terminated, unquoted — spaces in filenames survive intact.
+        return result.stdout
+            .split("\0")
+            .filter((entry) => entry.startsWith("?? "))
+            .map((entry) => entry.slice(3));
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: status in ${cwd} failed: ${errorMessage(error)}`);
+        return [];
+    }
+}
+async function trackedDiff(cwd, git) {
+    try {
+        const result = await git(["diff"], cwd);
+        if (result.code !== 0) {
+            logger.debug(`handoff bundle: git diff in ${cwd} exited ${result.code}`);
+            return null;
+        }
+        return result.stdout;
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: git diff in ${cwd} failed: ${errorMessage(error)}`);
+        return null;
+    }
+}
+function guardedWrite(file, content) {
+    try {
+        atomicWriteFile(file, content);
+        return true;
+    }
+    catch (error) {
+        logger.debug(`handoff bundle: writing ${file} failed: ${errorMessage(error)}`);
+        return false;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/handoff/parent-handoff.js

@@ -0,0 +1,48 @@
+import { ExitCode } from "../core/errors.js";
+import { logger } from "../core/logging.js";
+/**
+ * Emit a handoff to the parent session and return its exit code (D2).
+ *
+ * **stdout carries the JSON and nothing else.** Contract C1 reserves stdout
+ * for the run's final answer, and a handed-off run has none — it did not
+ * finish. Printing a partial answer next to the JSON would give an
+ * orchestrator two things to parse and no way to tell which is authoritative,
+ * so the JSON *is* the output of a run that ends this way.
+ *
+ * 41 and 42 differ only in what already happened: 41 is a preflight refusal
+ * that spawned nothing, 42 a live run stopped at a safe boundary with its work
+ * preserved in a bundle. Neither is a crash, which is exactly what the
+ * orchestrator templates now say.
+ */
+export function writeHandoffResult(streams, result, humanSummary, exitCode = ExitCode.HandoffRequired) {
+    streams.stdout.write(JSON.stringify(result) + "\n");
+    try {
+        streams.stderr.write(humanSummary.join("\n") + "\n");
+    }
+    catch (error) {
+        // The machine-readable half already landed; losing the prose must not
+        // change the exit code the parent reads.
+        logger.debug(`parent handoff: writing the human summary failed: ${errorMessage(error)}`);
+    }
+    return exitCode;
+}
+/** The `[Router]` block a human reads on stderr when a live run hands off (doc §14, §18). */
+export function handoffSummaryLines(input) {
+    const lines = [
+        `[Router] handing the task back to the parent session (${input.reason}).`,
+        `[Router] run ${input.runId} stopped at a safe boundary; its work is on disk.`,
+    ];
+    if (input.completed.length > 0) {
+        lines.push("[Router] done so far:", ...input.completed.map((entry) => `[Router]   ${entry}`));
+    }
+    if (input.pending.length > 0) {
+        lines.push("[Router] still to do:", ...input.pending.map((entry) => `[Router]   ${entry}`));
+    }
+    lines.push(input.bundlePath === null
+        ? "[Router] no bundle was written (nothing had changed on disk yet)."
+        : `[Router] bundle: ${input.bundlePath}`, "[Router] continue in the SAME worktree; do not re-run the worker until quota resets.");
+    return lines;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/mcp/server.js

@@ -1,4 +1,5 @@
 import os from "node:os";
+import { Writable } from "node:stream";
 import { buildWorkerArgs } from "../bin/glm-worker.js";
 import { buildReviewArgs } from "../bin/glm-review.js";
 import { loadConfig } from "../core/config.js";
@@ -11,7 +12,9 @@ import { applyProfile } from "../core/profile.js";
 import { version } from "../core/version.js";
 import { createDelegateWorktree, delegateBranch, removeDelegateWorktree, rollbackDelegateBranch, validateDelegateName, } from "../core/worktree.js";
 import { resolveZaiApiKey } from "../core/zai-key.js";
-import { aggregateLocalUsage, describeWindow, fetchZaiQuota } from "../commands/usage.js";
+import { runInstrumented, shouldObserve } from "../runs/worker-run.js";
+import { aggregateLocalUsage } from "../commands/usage.js";
+import { describeWindow, fetchZaiQuota } from "../core/zai-quota.js";
 const PROMPT_PROPERTY = { type: "string", description: "The task prompt for the GLM agent." };
 export const MCP_TOOLS = [
     {
@@ -80,6 +83,47 @@ async function runAgent(prompt, profile, kind, deps) {
     }
     const claudePath = locateClaude(config, env);
     const args = kind === "worker" ? buildWorkerArgs(prompt, config) : buildReviewArgs(prompt, config);
+    // An injected `spawn` pins the v1 capture path: that caller owns child
+    // execution and expects the captured stdout/stderr (C4). Production passes
+    // none and observes by default.
+    if (deps.spawn === undefined && shouldObserve(args, env)) {
+        // C2 (v2 spec Phase D): MCP's stdout is the JSON-RPC channel, so the run is
+        // instrumented with the renderer off and both streams captured — the final
+        // text comes back as the tool result string, and the run still lands in the
+        // registry/history. is-error stays derived from the exit code, exactly like
+        // the capture path below.
+        let stdoutText = "";
+        let stderrText = "";
+        const stderr = new Writable({
+            write: (chunk, _encoding, callback) => {
+                stderrText += String(chunk);
+                callback();
+            },
+        });
+        const result = await runInstrumented({
+            kind,
+            prompt,
+            args,
+            claudePath,
+            config,
+            secrets: [resolved.key],
+            cwd: deps.cwd ?? process.cwd(),
+            env: createGlmEnv(config, resolved.key, env),
+            home,
+            progress: "off",
+            stdout: {
+                write: (text) => {
+                    stdoutText += text;
+                },
+            },
+            stderr,
+        });
+        const text = stdoutText.trim() || "(no output)";
+        if (result.code !== 0) {
+            return { text: `${text}\n[worker exited ${result.code}]${stderrText ? `\n${tail(stderrText.trim())}` : ""}`, isError: true };
+        }
+        return { text, isError: false };
+    }
     const spawn = deps.spawn ?? spawnAgentCapture;
     const captured = await spawn(claudePath, {
         args,

package/dist/routing/glm-routing.js

@@ -0,0 +1,131 @@
+import { zoneFor } from "../budget/manager.js";
+/**
+ * DEVIATION FROM THE SPEC, deliberate: the spec's signature says `estimate`
+ * (singular), but its own refusal rule needs both models' p90 — wouldRefuse
+ * is true only when the cost does not fit for main AND fast (doc §14: always
+ * try Flash before giving up). One estimate cannot express that, and deriving
+ * the fast estimate by scaling the main one would bake the estimator's
+ * baseline ratio (FAST_MODEL_RATIO, 0.4) into the router, so this takes both
+ * and the caller computes each with estimateCost.
+ *
+ * Pure: every input arrives as an argument — no files, no network, no clock,
+ * no logging, and the process is never exited from here. The rules, in order:
+ *
+ * 1. `quotaAware: false` or `confidence: "unknown"` fails OPEN — a monitoring
+ *    outage must never block work: action "run", the requested model (or
+ *    main), wouldRefuse false, zone as computed.
+ * 2. zone = zoneFor(snapshot, config.routing).
+ * 3. The BINDING window is whichever of fiveHour/weekly has the lower
+ *    remainingRatio — the same window zoneFor's min() picks, so the budget
+ *    arithmetic and the zone can never disagree. reserve = reserveRatio ×
+ *    binding.limit; usableBudget = max(0, binding.remaining − reserve).
+ * 4. Zone preference (doc §12): HEALTHY → main; CONSERVE, HANDOFF_READY and
+ *    CRITICAL → fast. CRITICAL is in the fast arm because with the shipped
+ *    default it still runs, and a nearly-empty quota should run cheap.
+ * 5. `requestedModel` PINS the model, overriding the zone preference. It does
+ *    NOT bypass an enforced refusal — only `force` does.
+ * 6. wouldRefuse when the zone is CRITICAL, or when NEITHER model's
+ *    p90 × safetyFactor fits usableBudget.
+ * 7. wouldRefuse becomes `return_to_parent` only when `refuseOnCritical` is
+ *    true and `force` is absent.
+ * 8. "downgrade" when the fast model was chosen without a pin (the route
+ *    changed underneath the caller); otherwise "run".
+ *
+ * `refuseOnCritical` ships FALSE in 2.0.0 (decision D3), and this function is
+ * built to run with it off: the estimator's baseline table has never been
+ * measured on this stack, so a wrongly-high row would refuse runs the quota
+ * could have afforded, and the user would only find --force after being
+ * blocked. With the switch off, wouldRefuse is simply reported and the caller
+ * logs a BudgetWarning and runs anyway. Do not flip the default here; flip it
+ * in config once the routingAdvice evidence exists.
+ *
+ * The affordability fallback is one-way (main → fast), mirroring doc §14's
+ * "always try Flash before giving up": when the unpinned choice is main and
+ * only fast fits, the route downgrades to fast. There is no fast → main
+ * upgrade — when a zone below HEALTHY asks for the fast model, the zone (not
+ * the estimate) is what protects the remaining quota.
+ */
+export function decideRoute(input) {
+    const { snapshot, estimates, config, requestedModel, force } = input;
+    const routing = config.routing;
+    const zone = zoneFor(snapshot, routing);
+    const usableBudget = usableBudgetOf(snapshot, routing.reserveRatio);
+    const costOf = (estimate) => estimate.p90 * routing.safetyFactor;
+    const fits = (estimate) => costOf(estimate) <= usableBudget;
+    // Rule 1 — fail-open. usableBudget/estimatedCost are still reported (an
+    // unknown snapshot honestly yields 0: we know no budget), but they gate
+    // nothing here.
+    if (!routing.quotaAware || snapshot.confidence === "unknown") {
+        const slot = requestedModel ?? "main";
+        return {
+            action: "run",
+            model: config.models[slot],
+            zone,
+            reason: routing.quotaAware ? "quota confidence unknown, failing open" : "quota-aware routing is disabled",
+            usableBudget,
+            estimatedCost: costOf(estimates[slot]),
+            wouldRefuse: false,
+        };
+    }
+    const preferred = zone === "HEALTHY" ? "main" : "fast";
+    let slot = requestedModel ?? preferred;
+    let fellBackToFit = false;
+    if (requestedModel === undefined && slot === "main" && !fits(estimates.main) && fits(estimates.fast)) {
+        slot = "fast";
+        fellBackToFit = true;
+    }
+    const wouldRefuse = zone === "CRITICAL" || (!fits(estimates.main) && !fits(estimates.fast));
+    // Rule 7 — D3: with the shipped refuseOnCritical: false this stays false and
+    // wouldRefuse is only reported. force bypasses the enforced form only.
+    const enforced = wouldRefuse && routing.refuseOnCritical && force !== true;
+    return {
+        action: enforced
+            ? "return_to_parent"
+            : slot === "fast" && requestedModel === undefined
+                ? "downgrade"
+                : "run",
+        model: config.models[slot],
+        zone,
+        reason: enforced
+            ? zone === "CRITICAL"
+                ? "zone CRITICAL, refusal enforced"
+                : "neither model's estimated cost fits the usable budget"
+            : requestedModel !== undefined
+                ? `--model ${requestedModel} pinned`
+                : fellBackToFit
+                    ? "estimated main cost exceeds usable budget, trying the fast model"
+                    : `zone ${zone} prefers the ${preferred} model`,
+        usableBudget,
+        estimatedCost: costOf(estimates[slot]),
+        wouldRefuse,
+    };
+}
+/**
+ * The window the budget arithmetic must respect: the one with the lower
+ * remainingRatio, i.e. the same window zoneFor's min() already picked — so
+ * the credits and the zone are computed against one window, never two that
+ * could disagree. On an exact ratio tie min() is indifferent, so the smaller
+ * limit binds: it leaves less absolute headroom, which is the conservative
+ * reading. (confidence "unknown" never reaches here with real numbers —
+ * decideRoute fails open first — and its zero windows tie harmlessly.)
+ */
+/**
+ * Credits this run may actually spend: the binding window's remaining, less
+ * the untouchable reserve, floored at 0.
+ *
+ * Exported because the Phase F drain controller re-asks the same question
+ * every poll, and two implementations of one piece of arithmetic would drift
+ * — preflight and mid-run draining have to agree on what "affordable" means
+ * or the router contradicts itself halfway through a run.
+ */
+export function usableBudgetOf(snapshot, reserveRatio) {
+    const binding = bindingWindow(snapshot);
+    return Math.max(0, binding.remaining - reserveRatio * binding.limit);
+}
+function bindingWindow(snapshot) {
+    const { fiveHour, weekly } = snapshot;
+    if (fiveHour.remainingRatio !== weekly.remainingRatio) {
+        return fiveHour.remainingRatio < weekly.remainingRatio ? fiveHour : weekly;
+    }
+    return fiveHour.limit <= weekly.limit ? fiveHour : weekly;
+}

package/dist/runs/checkpoint.js

@@ -0,0 +1,204 @@
+import path from "node:path";
+import { logger } from "../core/logging.js";
+import { atomicWriteFile } from "../project/atomic-write.js";
+/** Doc §16's shape, rebuilt from events only (doc §17). */
+export const CHECKPOINT_FILE_NAME = "checkpoint.json";
+/** Tools whose appearance in a turn marks that turn as implementation work. */
+const EDIT_TOOLS = new Set(["Edit", "Write", "MultiEdit"]);
+/** C3: the widest any human-readable checkpoint line may ever be. */
+const LINE_MAX_CHARS = 120;
+/**
+ * Rebuilds a checkpoint from an event stream — the pure half of Phase F. Never
+ * throws and never reads a prompt: every string it returns is either a
+ * redacted tool summary (the adapter already enforced C3) or the redacted,
+ * 120-char `taskTitle` the `RunStarted` event already persisted.
+ *
+ * `pending` is the C3-safe reading of a spec that contradicted itself: Phase F
+ * first says it is "derived from the prompt's checklist lines if present", then
+ * that the checkpoint is "rebuilt from events only". Both cannot hold, and the
+ * first would put prompt text into `checkpoint.json` under `<configDir>/runs/`,
+ * which the C3 sweep walks. Events win:
+ *
+ * - with a `RunStarted`: the run's `taskTitle`, plus one entry per validation
+ *   still owed (`validationPending`);
+ * - without one: the single entry `"continue the task"`.
+ *
+ * Do not "restore" prompt parsing here — if a richer pending list is ever
+ * wanted, the event model is where it must arrive (e.g. a task-spec event), not
+ * the prompt body.
+ */
+export function buildCheckpoint(events) {
+    let taskTitle;
+    let lastTurnStarted = 0;
+    let lastToolTurn = 0;
+    let terminalSeen = false;
+    const turns = new Map();
+    const filesChanged = [];
+    const seenFiles = new Set();
+    for (const event of events) {
+        switch (event.type) {
+            case "RunStarted":
+                // First wins: a multi-segment run (error_max_turns + continue) replays
+                // its opener, and the original title is the one the registry recorded.
+                if (taskTitle === undefined) {
+                    taskTitle = event.taskTitle;
+                }
+                break;
+            case "TurnStarted":
+                lastTurnStarted = Math.max(lastTurnStarted, event.turn);
+                break;
+            case "ToolStarted": {
+                const state = turnState(turns, event.turn);
+                state.toolLines.push(`${event.tool} ${event.summary}`);
+                if (EDIT_TOOLS.has(event.tool)) {
+                    state.hasEditTool = true;
+                }
+                lastToolTurn = Math.max(lastToolTurn, event.turn);
+                break;
+            }
+            case "ToolCompleted": {
+                const state = turnState(turns, event.turn);
+                // The completion alone is enough evidence of an edit: a stream whose
+                // `ToolStarted` line was lost to a crash still classifies truthfully.
+                if (EDIT_TOOLS.has(event.tool)) {
+                    state.hasEditTool = true;
+                }
+                lastToolTurn = Math.max(lastToolTurn, event.turn);
+                break;
+            }
+            case "FileChanged":
+                turnState(turns, event.turn).hasEditTool = true;
+                lastToolTurn = Math.max(lastToolTurn, event.turn);
+                if (!seenFiles.has(event.path)) {
+                    seenFiles.add(event.path);
+                    filesChanged.push(event.path);
+                }
+                break;
+            case "ValidationStarted":
+                turnState(turns, event.turn).validationStarts.push(event.command);
+                lastToolTurn = Math.max(lastToolTurn, event.turn);
+                break;
+            case "ValidationCompleted": {
+                const state = turnState(turns, event.turn);
+                (event.ok ? state.validationOk : state.validationFailed).push(event.command);
+                lastToolTurn = Math.max(lastToolTurn, event.turn);
+                break;
+            }
+            case "ToolDenied":
+                // A denied tool ran nothing, so it proves neither edits nor validation;
+                // its ToolStarted summary is already in toolLines (A0: reportable).
+                lastToolTurn = Math.max(lastToolTurn, event.turn);
+                break;
+            case "RunCompleted":
+            case "RunFailed":
+            case "RunCancelled":
+                terminalSeen = true;
+                break;
+            default:
+                break;
+        }
+    }
+    const ordered = [...turns.entries()].sort((a, b) => a[0] - b[0]);
+    // Phase comes from the LAST turn with tool activity — a TurnStarted alone is
+    // a counter, not activity, so a stream truncated right after one keeps the
+    // phase of the turn that was actually doing something.
+    const lastActive = lastToolTurn > 0 ? turns.get(lastToolTurn) : undefined;
+    const phase = lastActive !== undefined && lastActive.validationStarts.length > 0
+        ? "validation"
+        : lastActive !== undefined && lastActive.hasEditTool
+            ? "implementation"
+            : "exploration";
+    const completed = [];
+    for (const [turn, state] of ordered) {
+        // Finished = a later turn started, or the run reached a terminal event.
+        // The final turn of a stream with no terminal event is the one in progress
+        // when the handoff happened, so it stays out of `completed`.
+        if (state.toolLines.length > 0 && (turn < lastTurnStarted || terminalSeen)) {
+            completed.push(`turn ${turn}: ${state.toolLines.join(", ")}`.slice(0, LINE_MAX_CHARS));
+        }
+    }
+    const validationPending = owedValidations(ordered);
+    const pending = taskTitle === undefined
+        ? // No RunStarted at all: the stream lost its opener (or is empty), so
+            // there is no title to carry — one honest entry, nothing fabricated.
+            ["continue the task"]
+        : [taskTitle.trim().length > 0 ? taskTitle : "continue the task", ...validationPending];
+    return {
+        // Mirrors summarize(): the first event's runId is the run the stream
+        // belongs to, and "" is the only answer an empty stream has.
+        runId: events.length > 0 ? events[0].runId : "",
+        phase,
+        completed,
+        pending,
+        filesChanged,
+        validationPending,
+    };
+}
+/**
+ * Writes `checkpoint.json` into a run directory and returns its path, or null
+ * on any failure — logged at debug, never thrown. A checkpoint is an aid: the
+ * run it describes has already happened, and losing the aid must not cost the
+ * run its exit path.
+ */
+export function writeCheckpoint(runDirPath, checkpoint) {
+    const file = path.join(runDirPath, CHECKPOINT_FILE_NAME);
+    try {
+        atomicWriteFile(file, JSON.stringify(checkpoint, null, 2) + "\n");
+        return file;
+    }
+    catch (error) {
+        logger.debug(`writeCheckpoint: writing ${file} failed: ${errorMessage(error)}`);
+        return null;
+    }
+}
+/**
+ * Validations still owed: every started command with no ok completion in the
+ * SAME turn (the adapter ties a completion to the turn that started it), plus
+ * every completion that reported `ok: false`. A denied validation falls under
+ * the first clause — the denial never produces a completion, and A0 settled
+ * that a denied validation is a real, reportable outcome rather than an error,
+ * so it must resurface here instead of vanishing. Deduplicated by command,
+ * first-owed order: the reader wants which commands to run, not how many times
+ * the run failed to run them.
+ */
+function owedValidations(orderedTurns) {
+    const owed = [];
+    const seen = new Set();
+    const add = (command) => {
+        if (!seen.has(command)) {
+            seen.add(command);
+            owed.push(command);
+        }
+    };
+    for (const [, state] of orderedTurns) {
+        for (const command of new Set(state.validationStarts)) {
+            if (occurrences(state.validationOk, command) < occurrences(state.validationStarts, command)) {
+                add(command);
+            }
+        }
+        for (const command of state.validationFailed) {
+            add(command);
+        }
+    }
+    return owed;
+}
+function turnState(turns, turn) {
+    let state = turns.get(turn);
+    if (state === undefined) {
+        state = { toolLines: [], validationStarts: [], validationOk: [], validationFailed: [], hasEditTool: false };
+        turns.set(turn, state);
+    }
+    return state;
+}
+function occurrences(commands, command) {
+    let count = 0;
+    for (const entry of commands) {
+        if (entry === command) {
+            count += 1;
+        }
+    }
+    return count;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}