glm-coding-router 1.1.2 → 2.1.0

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);
+}

package/dist/runs/drain.js

@@ -0,0 +1,165 @@
+import { execFile } from "node:child_process";
+import { logger } from "../core/logging.js";
+import { zoneFor } from "../budget/manager.js";
+import { usableBudgetOf } from "../routing/glm-routing.js";
+/**
+ * Grace between SIGINT and SIGTERM. Five seconds is enough for `claude` to
+ * finish flushing the tool result it is holding and exit on its own — the
+ * point of the ladder is to let it close cleanly, not to win a race.
+ */
+export const TERMINATE_GRACE_MS = 5_000;
+/** Second grace, before Windows' last resort. Short: by now it has ignored two signals. */
+export const TASKKILL_GRACE_MS = 2_000;
+/** Worst-to-best, so "at or below HANDOFF_READY" is one comparison. */
+const ZONE_SEVERITY = {
+    CRITICAL: 3,
+    HANDOFF_READY: 2,
+    CONSERVE: 1,
+    HEALTHY: 0,
+};
+/**
+ * Should this run be worried yet? (specs/v2-architecture.md Phase F.)
+ *
+ * Pure: the caller does the polling and owns every side effect. Note what this
+ * projects — the cost of what is LEFT, not of the whole task. A run three
+ * quarters done needs a quarter of the estimate, and treating it as if it were
+ * starting over would raise the alarm on every long run that is nearly
+ * finished, which is precisely when interrupting costs the most.
+ *
+ * `confidence: "unknown"` can never reach `atRisk`, because `zoneFor` fails
+ * open to HEALTHY — a monitoring outage must not drain a live child.
+ */
+export function assessDrain(input) {
+    const routing = input.config.routing;
+    const zone = zoneFor(input.snapshot, routing);
+    const usableBudget = usableBudgetOf(input.snapshot, routing.reserveRatio);
+    // A run that has already used every turn it was given has nothing left to
+    // project; an unknown/zero ceiling means "assume it all still lies ahead".
+    const remainingTurnRatio = input.maxTurns > 0
+        ? Math.min(1, Math.max(0, (input.maxTurns - input.turnsDone) / input.maxTurns))
+        : 1;
+    const projectedCost = input.estimate.p90 * routing.safetyFactor * remainingTurnRatio;
+    return {
+        zone,
+        usableBudget,
+        projectedCost,
+        atRisk: ZONE_SEVERITY[zone] >= ZONE_SEVERITY.HANDOFF_READY && projectedCost > usableBudget,
+    };
+}
+/**
+ * Polls the budget while the child runs and calls back the first time the run
+ * becomes at-risk, then never again: the warning and the checkpoint are worth
+ * writing once, and a per-poll repeat would turn a tight quota into a wall of
+ * identical stderr lines.
+ *
+ * Every timer is injectable because a test must not wait a real minute, and
+ * the interval is unref'd so a poll in flight can never hold the process open
+ * past the run it was watching.
+ */
+export function startDrainWatch(input) {
+    const setIntervalFn = input.setIntervalImpl ?? ((tick, ms) => setInterval(tick, ms));
+    const clearIntervalFn = input.clearIntervalImpl ?? ((handle) => clearInterval(handle));
+    let fired = false;
+    let stopped = false;
+    const tick = () => {
+        if (fired || stopped) {
+            return;
+        }
+        // Fire-and-forget: a poll that rejects must not become an unhandled
+        // rejection, and a slow endpoint must not delay the next tick.
+        void (async () => {
+            try {
+                const assessment = assessDrain({
+                    snapshot: await input.readBudget(),
+                    estimate: input.estimate(),
+                    config: input.config,
+                    turnsDone: input.turnsDone(),
+                    maxTurns: input.maxTurns,
+                });
+                if (assessment.atRisk && !fired && !stopped) {
+                    fired = true;
+                    input.onAtRisk(assessment);
+                }
+            }
+            catch (error) {
+                logger.debug(`drain watch: poll failed, continuing: ${errorMessage(error)}`);
+            }
+        })();
+    };
+    const handle = setIntervalFn(tick, Math.max(1, input.config.routing.pollIntervalSec) * 1000);
+    handle.unref?.();
+    return {
+        stop() {
+            stopped = true;
+            clearIntervalFn(handle);
+        },
+    };
+}
+/**
+ * Stop the child at a safe boundary: SIGINT, grace, SIGTERM, and on Windows
+ * `taskkill /pid <pid> /t` as the last resort — the same ladder and the same
+ * no-shell rule the spawn helpers already follow.
+ *
+ * Windows has no real POSIX signals: Node emulates `kill` by terminating the
+ * process, and a `claude` that spawned its own children leaves them behind,
+ * which is what `/t` (kill the tree) is for. `/f` is deliberately NOT used
+ * before the tree walk — a forced kill is the thing this whole ladder exists
+ * to avoid, because it is what loses the work on disk.
+ *
+ * Resolves when the child is gone or the ladder is exhausted; never throws.
+ */
+export async function terminateChild(child, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const wait = options.waitImpl ?? defaultWait;
+    const exited = () => child.exitCode !== null || child.signalCode !== null;
+    send(child, "SIGINT");
+    if (exited()) {
+        return;
+    }
+    await wait(options.graceMs ?? TERMINATE_GRACE_MS);
+    if (exited()) {
+        return;
+    }
+    send(child, "SIGTERM");
+    if (platform !== "win32") {
+        return;
+    }
+    await wait(options.taskkillGraceMs ?? TASKKILL_GRACE_MS);
+    if (exited() || typeof child.pid !== "number") {
+        return;
+    }
+    const taskkill = options.runTaskkill ?? defaultTaskkill;
+    try {
+        taskkill(child.pid);
+    }
+    catch (error) {
+        logger.debug(`terminateChild: taskkill failed: ${errorMessage(error)}`);
+    }
+}
+/** A kill on an already-dead child throws ESRCH; that is success, not an error. */
+function send(child, signal) {
+    try {
+        child.kill(signal);
+    }
+    catch (error) {
+        logger.debug(`terminateChild: ${signal} failed: ${errorMessage(error)}`);
+    }
+}
+/** argv array, no shell — the same rule every spawn in this package follows. */
+function defaultTaskkill(pid) {
+    execFile("taskkill", ["/pid", String(pid), "/t"], { windowsHide: true }, (error) => {
+        if (error) {
+            logger.debug(`taskkill /pid ${pid} /t failed: ${error.message}`);
+        }
+    });
+}
+function defaultWait(ms) {
+    return new Promise((resolve) => {
+        // unref: a pending grace period must never keep the process alive.
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/runs/heartbeat.js

@@ -0,0 +1,45 @@
+import { logger } from "../core/logging.js";
+import { updateRun } from "./registry.js";
+/**
+ * Doc §6 fixes the tick at 5 s and keeps it out of config on purpose: the
+ * 30 s orphan threshold is six missed ticks of THIS interval. A config knob
+ * here would let anyone silently break liveness detection.
+ */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+/**
+ * Emits a `Heartbeat` event and refreshes `heartbeatAt` in the active file on
+ * every tick — the pair that `watch` and orphan detection read. A file
+ * failure is caught and logged at debug: the heartbeat is liveness plumbing,
+ * and plumbing must never kill the run it is monitoring. The bus's own
+ * subscriber guard covers the emit side.
+ */
+export function startHeartbeat(deps) {
+    const intervalMs = deps.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    const tick = () => {
+        deps.bus.emit({ type: "Heartbeat", state: deps.getState(), turn: deps.getTurn() });
+        try {
+            updateRun(deps.home, deps.runId, { heartbeatAt: new Date().toISOString() });
+        }
+        catch (error) {
+            logger.debug(`heartbeat: could not refresh ${deps.runId}: ${errorMessage(error)}`);
+        }
+    };
+    const setIntervalImpl = deps.setIntervalImpl ?? ((fn, ms) => setInterval(fn, ms));
+    const clearIntervalImpl = deps.clearIntervalImpl ?? ((timer) => clearInterval(timer));
+    let timer = setIntervalImpl(tick, intervalMs);
+    // Unref when the runtime supports it: a leaked heartbeat timer must never
+    // be the reason the process stays open after the run finished.
+    timer.unref?.();
+    return {
+        stop() {
+            if (timer === null) {
+                return;
+            }
+            clearIntervalImpl(timer);
+            timer = null;
+        },
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}