glm-coding-router 1.1.1 → 2.0.0

package/dist/bin/glm-review.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { STRICT_MCP_ARGS } from "../core/agent-args.js";
 import { loadConfig } from "../core/config.js";
 import { locateClaude } from "../core/claude.js";
 import { createGlmEnv } from "../core/env.js";
@@ -6,20 +7,41 @@ import { Errors, formatGlmError, GlmRouterError } from "../core/errors.js";
 import { isMainModule } from "../core/main-guard.js";
 import { logger, redact } from "../core/logging.js";
 import { applyProfile, extractProfileFlag } from "../core/profile.js";
+import { extractRoutingFlags } from "../core/routing-flags.js";
 import { readStdin, resolvePrompt } from "../core/prompt.js";
 import { spawnAgent } from "../core/process.js";
 import { resolveZaiApiKey } from "../core/zai-key.js";
+import { runInstrumented, shouldObserve } from "../runs/worker-run.js";
 /** Read-only review surface (spec §17) — no Edit, Write, or Bash. */
 export const REVIEW_TOOLS = "Read,Glob,Grep";
+/**
+ * Build the child arguments (spec §17, specs/review-mcp-isolation.md).
+ *
+ * `--tools` alone does not make this read-only: it restricts the built-in set,
+ * while MCP tools from the user's config are additive — with our own server
+ * registered, a review could call `glm_worker` and write files. STRICT_MCP_ARGS
+ * is what actually holds the guarantee.
+ */
 export function buildReviewArgs(prompt, config) {
-    return ["-p", prompt, "--max-turns", String(config.review.maxTurns), "--tools", REVIEW_TOOLS];
+    return [
+        "-p",
+        prompt,
+        "--max-turns",
+        String(config.review.maxTurns),
+        "--tools",
+        REVIEW_TOOLS,
+        ...STRICT_MCP_ARGS,
+    ];
 }
 /**
  * glm-review (spec §17): read-only worker for exploration, call-graph
  * discovery, duplicate detection, dependency inspection, and review.
  */
 export async function runReview(argv) {
-    const { rest, profile } = extractProfileFlag(argv);
+    const { rest: withoutProfile, profile } = extractProfileFlag(argv);
+    // Phase E flags come off before resolvePrompt: whatever is still in
+    // `rest` at that point becomes the prompt.
+    const { rest, model, force, refreshQuota } = extractRoutingFlags(withoutProfile);
     const prompt = await resolvePrompt(rest, readStdin, "glm-review");
     const config = applyProfile(loadConfig(), profile);
     const resolved = resolveZaiApiKey();
@@ -30,12 +52,32 @@ export async function runReview(argv) {
     const args = buildReviewArgs(prompt, config);
     const env = createGlmEnv(config, resolved.key);
     logger.debug(redact(`spawning ${claudePath} ${args.join(" ")}`, [resolved.key]));
-    return spawnAgent(claudePath, {
+    // v2 spec Phase D (C4): observe unless the caller opted out or already asked
+    // for a specific --output-format. The legacy path stays byte-identical.
+    if (!shouldObserve(args, process.env)) {
+        return spawnAgent(claudePath, {
+            args,
+            cwd: process.cwd(),
+            env,
+            interactive: false,
+        });
+    }
+    const observed = await runInstrumented({
+        kind: "review",
+        prompt,
         args,
+        claudePath,
+        config,
+        secrets: [resolved.key],
         cwd: process.cwd(),
         env,
-        interactive: false,
+        // Phase E; instrumented runs only, same as glm-worker.
+        zaiKey: resolved.key,
+        requestedModel: model,
+        force,
+        refreshQuota,
     });
+    return observed.code;
 }
 if (isMainModule(import.meta.url)) {
     runReview(process.argv.slice(2)).then((code) => process.exit(code), (error) => {

package/dist/bin/glm-worker.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { STRICT_MCP_ARGS } from "../core/agent-args.js";
 import { loadConfig } from "../core/config.js";
 import { locateClaude } from "../core/claude.js";
 import { createGlmEnv } from "../core/env.js";
@@ -6,9 +7,11 @@ import { Errors, formatGlmError, GlmRouterError } from "../core/errors.js";
 import { isMainModule } from "../core/main-guard.js";
 import { logger, redact } from "../core/logging.js";
 import { applyProfile, extractProfileFlag } from "../core/profile.js";
+import { extractRoutingFlags } from "../core/routing-flags.js";
 import { resolvePrompt } from "../core/prompt.js";
 import { spawnAgent } from "../core/process.js";
 import { resolveZaiApiKey } from "../core/zai-key.js";
+import { runInstrumented, shouldObserve } from "../runs/worker-run.js";
 /** Worker tool surface (spec §16). */
 export const WORKER_TOOLS = "Read,Glob,Grep,Edit,Write,Bash";
 /** Same surface minus Bash, used when no Bash command is allowed. */
@@ -21,6 +24,10 @@ export const WORKER_TOOLS_NO_BASH = "Read,Glob,Grep,Edit,Write";
  * `--allowedTools` every Bash call comes back "This command requires
  * approval". When the allowlist is empty we drop Bash from `--tools` entirely
  * rather than advertising a tool the worker can never use.
+ *
+ * STRICT_MCP_ARGS keeps the user's MCP servers out of the child
+ * (specs/review-mcp-isolation.md): write is expected here, undeclared
+ * recursion into `glm_delegate` and its own turn budget is not.
  */
 export function buildWorkerArgs(prompt, config) {
     const allowedBash = config.worker.allowedBash;
@@ -33,6 +40,8 @@ export function buildWorkerArgs(prompt, config) {
         "acceptEdits",
         "--tools",
         allowedBash.length > 0 ? WORKER_TOOLS : WORKER_TOOLS_NO_BASH,
+        // Before --allowedTools: its values are variadic and must stay last.
+        ...STRICT_MCP_ARGS,
     ];
     if (allowedBash.length > 0) {
         args.push("--allowedTools", ...allowedBash.map((pattern) => `Bash(${pattern})`));
@@ -54,12 +63,15 @@ export function extractNoBashFlag(argv) {
 }
 /**
  * glm-worker (spec §15, §16): headless implementation worker.
- * Prompt priority: stdin → arguments → error. Never uses
+ * Prompt priority: arguments → stdin → error. Never uses
  * --dangerously-skip-permissions.
  */
 export async function runWorker(argv) {
     const { rest: withoutProfile, profile } = extractProfileFlag(argv);
-    const { rest, noBash } = extractNoBashFlag(withoutProfile);
+    const { rest: withoutBashFlag, noBash } = extractNoBashFlag(withoutProfile);
+    // Phase E flags come off last, and before resolvePrompt: everything still in
+    // `rest` at that point becomes the prompt.
+    const { rest, model, force, refreshQuota } = extractRoutingFlags(withoutBashFlag);
     const prompt = await resolvePrompt(rest);
     const loaded = applyProfile(loadConfig(), profile);
     const config = noBash
@@ -73,12 +85,33 @@ export async function runWorker(argv) {
     const args = buildWorkerArgs(prompt, config);
     const env = createGlmEnv(config, resolved.key);
     logger.debug(redact(`spawning ${claudePath} ${args.join(" ")}`, [resolved.key]));
-    return spawnAgent(claudePath, {
+    // v2 spec Phase D (C4): observe unless the caller opted out or already asked
+    // for a specific --output-format. The legacy path stays byte-identical.
+    if (!shouldObserve(args, process.env)) {
+        return spawnAgent(claudePath, {
+            args,
+            cwd: process.cwd(),
+            env,
+            interactive: false,
+        });
+    }
+    const observed = await runInstrumented({
+        kind: "worker",
+        prompt,
         args,
+        claudePath,
+        config,
+        secrets: [resolved.key],
         cwd: process.cwd(),
         env,
-        interactive: false,
+        // Phase E. The legacy path above never reaches here, so these flags apply
+        // to instrumented runs only — routing needs the event stream it observes.
+        zaiKey: resolved.key,
+        requestedModel: model,
+        force,
+        refreshQuota,
     });
+    return observed.code;
 }
 if (isMainModule(import.meta.url)) {
     runWorker(process.argv.slice(2)).then((code) => process.exit(code), (error) => {

package/dist/budget/estimator.js

@@ -0,0 +1,218 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../core/logging.js";
+import { costSamplesPath } from "../core/paths.js";
+/**
+ * Priority-ordered keyword table: the first row with a case-insensitive WHOLE
+ * WORD match wins, which is what makes "fix the failing test" a bugfix rather
+ * than a tests task — repair beats coverage when both match.
+ *
+ * Whole words, not substrings: a substring table reads "docker" as docs and
+ * "fixture" as bugfix, and this classifier is not cosmetic — it picks the cost
+ * row that decides `wouldRefuse`, which is the evidence D3 says 2.1's
+ * refuse-by-default decision will be argued from. Noise here becomes a wrong
+ * answer to "how often would the refusal have been wrong?". Word forms are
+ * therefore listed explicitly; an unlisted form falls through to a later row
+ * or to "other", and guessing low is the conservative failure.
+ */
+const KEYWORDS = [
+    [
+        "bugfix",
+        ["fix", "fixes", "fixed", "fixing", "bug", "bugs", "broken", "regression", "regressions",
+            "crash", "crashes", "crashing", "error", "errors", "defect", "defects", "repair"],
+    ],
+    ["tests", ["test", "tests", "testing", "spec", "specs", "coverage", "vitest", "jest", "pytest"]],
+    [
+        "docs",
+        ["doc", "docs", "document", "documents", "documentation", "docstring", "docstrings",
+            "readme", "comment", "comments", "changelog"],
+    ],
+    [
+        "refactor",
+        ["refactor", "refactors", "refactoring", "rename", "renames", "renaming", "extract",
+            "cleanup", "clean up", "restructure", "simplify", "migrate", "migration"],
+    ],
+    [
+        "explore",
+        ["explore", "investigate", "find", "search", "understand", "audit", "review", "analyze",
+            "analyse", "analysis"],
+    ],
+    [
+        "crud",
+        ["add", "create", "implement", "implements", "implementing", "endpoint", "endpoints",
+            "model", "models", "schema", "schemas", "crud", "build", "write"],
+    ],
+];
+/** Whole-word matcher for one row; `clean up` shows why a plain split() is not enough. */
+const MATCHERS = KEYWORDS.map(([kind, words]) => [
+    kind,
+    new RegExp(`\\b(?:${words.map(escapeRegExp).join("|")})\\b`, "i"),
+]);
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Deterministic keyword classifier — no model call, so preflight stays free,
+ * instant and reproducible. The prompt itself is never persisted here (C3);
+ * only the resulting kind reaches `cost-samples.jsonl`.
+ */
+export function classifyTask(prompt) {
+    for (const [kind, matcher] of MATCHERS) {
+        if (matcher.test(prompt)) {
+            return kind;
+        }
+    }
+    return "other";
+}
+/**
+ * Appends one JSON line to cost-samples.jsonl. Never throws: cost history is
+ * an optimization the next run can live without, and the run that earned the
+ * sample has already done its work by the time this is called.
+ */
+export function recordSample(home, sample) {
+    const file = costSamplesPath(home);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, JSON.stringify(sample) + "\n", "utf8");
+    }
+    catch (error) {
+        logger.debug(`estimator: could not record cost sample (${errorMessage(error)})`);
+    }
+}
+/**
+ * Reads the cost history. A missing file is "no history yet" and a malformed
+ * line is skipped, not fatal — the same tolerate-the-wreckage contract as the
+ * run store, because a truncated final line is normal crash wreckage.
+ */
+export function readSamples(home) {
+    let text;
+    try {
+        text = fs.readFileSync(costSamplesPath(home), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const samples = [];
+    for (const [index, line] of text.split(/\r?\n/).entries()) {
+        if (line.trim() === "") {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(line);
+            if (isSampleLike(parsed)) {
+                samples.push(parsed);
+            }
+            else {
+                logger.debug(`estimator: line ${index + 1} in ${costSamplesPath(home)} is not a sample`);
+            }
+        }
+        catch {
+            logger.debug(`estimator: skipping malformed line ${index + 1} in ${costSamplesPath(home)}`);
+        }
+    }
+    return samples;
+}
+/**
+ * True only when the quota delta between two snapshots can be attributed to
+ * exactly one run. All four rules must hold:
+ *
+ * - both snapshots have confidence "exact" or "cached" — an "unknown" side
+ *   makes the delta fiction;
+ * - fiveHour.resetAt is unchanged — a window reset mid-run makes the delta
+ *   meaningless (used drops to 0 and the difference goes negative);
+ * - the credit delta (end.used - start.used) is >= 0 — a negative delta
+ *   means a reset or a server correction, not a cost;
+ * - activeRunCount is exactly 1 — concurrent runs make credit attribution
+ *   meaningless, so those runs record nothing rather than a wrong number.
+ */
+export function isCleanMeasurement(input) {
+    const trusted = (confidence) => confidence === "exact" || confidence === "cached";
+    return (trusted(input.startSnapshot.confidence) &&
+        trusted(input.endSnapshot.confidence) &&
+        input.startSnapshot.fiveHour.resetAt === input.endSnapshot.fiveHour.resetAt &&
+        input.endSnapshot.fiveHour.used - input.startSnapshot.fiveHour.used >= 0 &&
+        input.activeRunCount === 1);
+}
+/**
+ * Main-model baseline, p50/p90 in plan credits. Transcribed from doc §13 and
+ * NEVER MEASURED on this stack — decision D3 keeps preflight refusal off in
+ * 2.0.0 precisely because this table is unmeasured; a wrongly-high row would
+ * refuse runs the quota could have afforded.
+ */
+const BASELINE_MAIN = {
+    explore: { p50: 15, p90: 28 },
+    crud: { p50: 42, p90: 66 },
+    tests: { p50: 30, p90: 50 },
+    docs: { p50: 12, p90: 22 },
+    refactor: { p50: 45, p90: 75 },
+    bugfix: { p50: 35, p90: 60 },
+    other: { p50: 35, p90: 60 },
+};
+/** Fast models are assumed to cost 40% of the main row, rounded. */
+const FAST_MODEL_RATIO = 0.4;
+/** History starts winning at this many samples; below it the noise would outrank the baseline. */
+const MIN_HISTORY_SAMPLES = 5;
+/**
+ * Estimated credits for one run of a task kind on a model. History wins when
+ * at least MIN_HISTORY_SAMPLES samples match BOTH the task kind and the model;
+ * otherwise the baseline table answers, with `samples: 0` and
+ * `source: "baseline"`.
+ *
+ * Main vs fast is decided by comparing `model` with the `fastModel`
+ * ARGUMENT — this module is deliberately config-free so it stays pure and
+ * testable, and callers (preflight, part 2) pass config.models.fast in.
+ */
+export function estimateCost(home, taskKind, model, fastModel) {
+    const credits = readSamples(home)
+        .filter((entry) => entry.taskKind === taskKind && entry.model === model)
+        .map((entry) => entry.credits);
+    if (credits.length >= MIN_HISTORY_SAMPLES) {
+        const sorted = [...credits].sort((a, b) => a - b);
+        return {
+            p50: nearestRank(sorted, 0.5),
+            p90: nearestRank(sorted, 0.9),
+            samples: sorted.length,
+            source: "history",
+        };
+    }
+    const main = BASELINE_MAIN[taskKind];
+    if (model === fastModel) {
+        return {
+            p50: Math.round(main.p50 * FAST_MODEL_RATIO),
+            p90: Math.round(main.p90 * FAST_MODEL_RATIO),
+            samples: 0,
+            source: "baseline",
+        };
+    }
+    return { p50: main.p50, p90: main.p90, samples: 0, source: "baseline" };
+}
+/**
+ * Nearest-rank percentile, deliberately NOT interpolation: sort ascending,
+ * take index ceil(p * n) - 1, clamped into [0, n-1]. For p90 with n = 5 that
+ * is literally the maximum sample. Interpolating would invent costs between
+ * samples that never happened; the rank is the honest, conservative reading.
+ * Do not "fix" this into interpolation later.
+ */
+function nearestRank(sortedAsc, p) {
+    const index = Math.min(sortedAsc.length - 1, Math.max(0, Math.ceil(p * sortedAsc.length) - 1));
+    return sortedAsc[index];
+}
+/**
+ * Same philosophy as the run store's isEventLike: "parses and has the fields
+ * estimateCost reads" (taskKind, model, credits). A line that parses but
+ * carries none of those cannot feed the estimator and is dropped; anything
+ * richer is history written by a future version and is kept.
+ */
+function isSampleLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.taskKind === "string" &&
+        typeof candidate.model === "string" &&
+        typeof candidate.credits === "number" &&
+        Number.isFinite(candidate.credits));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/budget/manager.js

@@ -0,0 +1,223 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fetchZaiQuota } from "../core/zai-quota.js";
+import { logger } from "../core/logging.js";
+import { quotaCachePath } from "../core/paths.js";
+/** Same TTL as the shipped config default; callers pass routing.quotaCacheTtlSec. */
+const DEFAULT_TTL_SEC = 60;
+const ZERO_WINDOW = {
+    used: 0,
+    limit: 0,
+    remaining: 0,
+    remainingRatio: 0,
+    resetAt: null,
+};
+/**
+ * Maps one CREDIT_LIMIT entry onto a BudgetWindow. The server's `remaining`
+ * is authoritative even though the real payload does not add up
+ * (912 + 1087 = 1999 of 2000) — recomputing it would silently change the
+ * number routing decides on. `limit - used` is only a fallback for when the
+ * server omits `remaining` entirely.
+ */
+function windowFrom(limit) {
+    if (limit === undefined) {
+        return ZERO_WINDOW;
+    }
+    const limitValue = finiteNumber(limit.usage) ?? 0;
+    const used = finiteNumber(limit.currentValue) ?? 0;
+    const remaining = finiteNumber(limit.remaining) ?? limitValue - used;
+    return {
+        used,
+        limit: limitValue,
+        remaining,
+        // 0 — never NaN, never Infinity — when the limit is 0 or missing, so the
+        // ratio math downstream (zoneFor, the Phase E router) stays finite no
+        // matter what the endpoint reports.
+        remainingRatio: limitValue > 0 ? remaining / limitValue : 0,
+        resetAt: typeof limit.nextResetTime === "number" && Number.isFinite(limit.nextResetTime)
+            ? new Date(limit.nextResetTime).toISOString()
+            : null,
+    };
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Window mapping verified live (specs/usage.md): `unit 3` is the 5-hour
+ * window, `unit 6 & number 1` the weekly one. Other entries are windows this
+ * build does not route on and are ignored.
+ */
+function snapshotFrom(data, fetchedAt) {
+    const limits = Array.isArray(data.limits) ? data.limits : [];
+    const fiveHour = limits.find((limit) => limit.unit === 3);
+    const weekly = limits.find((limit) => limit.unit === 6 && limit.number === 1);
+    // Fail-open has a side door, and this closes it. A 200 response that carries
+    // neither window is a real state of this endpoint, not a hypothetical —
+    // `usage.ts` already renders "(no quota windows reported)" for it. Mapped
+    // naively it becomes an "exact" all-zero snapshot, which zoneFor reads as
+    // CRITICAL: every run downgraded and warned today, every run refused once
+    // refuseOnCritical flips in 2.1 — on a payload that told us nothing at all.
+    // A window we cannot see is unknown, never empty. Both are required because
+    // the router reasons about GLM's 5-hour/weekly PAIR; with one of them
+    // missing the min() that picks the binding window is meaningless.
+    if (fiveHour === undefined || weekly === undefined) {
+        logger.debug("budget: quota payload carried no recognizable 5-hour/weekly pair, treating as unknown");
+        return unknownSnapshot(fetchedAt);
+    }
+    return {
+        provider: "zai.zcode",
+        unit: "credit",
+        costClass: "subscription",
+        fiveHour: windowFrom(fiveHour),
+        weekly: windowFrom(weekly),
+        confidence: "exact",
+        fetchedAt,
+    };
+}
+function unknownSnapshot(fetchedAt) {
+    return {
+        provider: "zai.zcode",
+        unit: "credit",
+        costClass: "subscription",
+        fiveHour: ZERO_WINDOW,
+        weekly: ZERO_WINDOW,
+        confidence: "unknown",
+        fetchedAt,
+    };
+}
+/**
+ * The Z.ai quota as a BudgetSnapshot, read through a short-lived file cache
+ * so a burst of runs makes ONE request.
+ *
+ * FAIL-OPEN is the contract of this function: no key, endpoint down, HTTP
+ * error, malformed body, unparseable cache — every one of those returns an
+ * all-zero snapshot with confidence "unknown". This function never throws
+ * and never rejects; a monitoring outage must not block work, it degrades
+ * routing to "run normally".
+ */
+export async function fetchBudget(deps) {
+    const home = deps.home ?? os.homedir();
+    const now = deps.now ?? (() => new Date());
+    const ttlSec = deps.ttlSec ?? DEFAULT_TTL_SEC;
+    try {
+        // `refresh` (what --refresh-quota will drive) bypasses the cache without
+        // deleting it — the next normal read may still use the fresh entry this
+        // fetch writes.
+        if (!deps.refresh) {
+            const cached = readCachedSnapshot(home);
+            // NaN from an unparseable fetchedAt compares false, i.e. stale: a cache
+            // entry with no valid timestamp must never suppress a live fetch.
+            if (cached !== null && now().getTime() - Date.parse(cached.fetchedAt) < ttlSec * 1000) {
+                return { ...cached, confidence: "cached" };
+            }
+        }
+        if (deps.key === undefined || deps.key.length === 0) {
+            return unknownSnapshot(now().toISOString());
+        }
+        const data = await fetchZaiQuota(deps.key, deps.fetchImpl ?? fetch);
+        const snapshot = snapshotFrom(data, now().toISOString());
+        writeCachedSnapshot(home, snapshot);
+        return snapshot;
+    }
+    catch (error) {
+        logger.debug(`budget: quota unavailable, failing open (${errorMessage(error)})`);
+        return unknownSnapshot(now().toISOString());
+    }
+}
+/**
+ * Zone classification for routing and warnings (doc §11). The worst window
+ * wins — a healthy 5-hour window cannot paper over an exhausted weekly one.
+ *
+ * confidence "unknown" returns HEALTHY on purpose, not CRITICAL: unknown
+ * windows are all-zero, and a naive min() over them would read "no credits
+ * left" and throttle every run for the whole duration of a monitoring
+ * outage — the exact opposite of fail-open. An outage degrades to "run
+ * normally, warn once".
+ */
+export function zoneFor(snapshot, thresholds) {
+    if (snapshot.confidence === "unknown") {
+        return "HEALTHY";
+    }
+    const ratio = Math.min(snapshot.fiveHour.remainingRatio, snapshot.weekly.remainingRatio);
+    if (ratio < thresholds.criticalBelow) {
+        return "CRITICAL";
+    }
+    if (ratio < thresholds.handoffReadyBelow) {
+        return "HANDOFF_READY";
+    }
+    if (ratio < thresholds.preferFlashBelow) {
+        return "CONSERVE";
+    }
+    return "HEALTHY";
+}
+/**
+ * The cache is a deduplication layer, never a source of truth: any problem
+ * reading it (missing, unreadable, unparseable, wrong shape) reads as "no
+ * cache" so the caller falls through to a live fetch.
+ */
+function readCachedSnapshot(home) {
+    const file = quotaCachePath(home);
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        logger.debug(`budget: unparseable quota cache at ${file} ignored`);
+        return null;
+    }
+    if (!isSnapshotLike(parsed)) {
+        logger.debug(`budget: quota cache at ${file} is not a snapshot, ignored`);
+        return null;
+    }
+    return parsed;
+}
+/** Write failures are debug-logged, never thrown — a read-only home must not fail a run. */
+function writeCachedSnapshot(home, snapshot) {
+    const file = quotaCachePath(home);
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(snapshot) + "\n", "utf8");
+    }
+    catch (error) {
+        logger.debug(`budget: could not write quota cache (${errorMessage(error)})`);
+    }
+}
+/**
+ * "Parses and has the fields the consumers read": enough shape to trust the
+ * cached numbers without duplicating the snapshot definition. Anything that
+ * fails this was not written by this build.
+ */
+function isSnapshotLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return ((candidate.confidence === "exact" ||
+        candidate.confidence === "cached" ||
+        candidate.confidence === "unknown") &&
+        typeof candidate.fetchedAt === "string" &&
+        isWindowLike(candidate.fiveHour) &&
+        isWindowLike(candidate.weekly));
+}
+function isWindowLike(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const window = value;
+    return (typeof window.used === "number" &&
+        typeof window.limit === "number" &&
+        typeof window.remaining === "number" &&
+        typeof window.remainingRatio === "number" &&
+        (window.resetAt === null || typeof window.resetAt === "string"));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/cli.js

@@ -16,6 +16,9 @@ import { uninstallCommand } from "./commands/uninstall.js";
 import { delegateCommand } from "./commands/delegate.js";
 import { benchmarkCommand } from "./commands/benchmark.js";
 import { usageCommand } from "./commands/usage.js";
+import { runsCleanCommand, runsCommand, runsLogsCommand, runsShowCommand } from "./commands/runs.js";
+import { watchCommand } from "./commands/watch.js";
+import { dashboardCommand } from "./commands/dashboard.js";
 import { mcpCommand } from "./commands/mcp.js";
 const program = new Command();
 program
@@ -109,6 +112,41 @@ program
     .command("usage")
     .description("provider usage snapshots: Z.ai Coding Plan quota + local benchmark totals")
     .action(() => execute(() => usageCommand(globalOptions())));
+const runs = program
+    .command("runs")
+    .description("inspect recorded worker runs — the default action lists them")
+    .option("--active", "list only runs in the active registry")
+    .option("--limit <n>", "show at most N runs (default 20)", (value) => Number(value))
+    .option("--json", "machine-readable JSON output")
+    .action((commandOptions) => execute(() => Promise.resolve(runsCommand({ ...globalOptions(), ...commandOptions }))));
+runs
+    .command("show <id>")
+    .description("show one run: metadata, summary numbers, per-turn tool tree")
+    .option("--json", "machine-readable JSON output")
+    .action((id, commandOptions) => execute(() => Promise.resolve(runsShowCommand(id, { ...globalOptions(), ...commandOptions }))));
+runs
+    .command("logs <id>")
+    .description("render the run's events.jsonl, one line per event")
+    .option("--json", "print the raw events.jsonl lines unchanged")
+    .action((id, commandOptions) => execute(() => Promise.resolve(runsLogsCommand(id, { ...globalOptions(), ...commandOptions }))));
+runs
+    .command("clean")
+    .description("prune history by age/count and reap orphaned active runs")
+    .option("--older-than <nd>", 'prune runs older than N days, e.g. "30d" (default: history.retentionDays)')
+    .option("--orphans", "reap active runs whose heartbeat is stale and whose pid is dead")
+    .option("--dry-run", "print what would happen without changing anything")
+    .option("--json", "machine-readable JSON output")
+    .action((commandOptions) => execute(() => Promise.resolve(runsCleanCommand({ ...globalOptions(), ...commandOptions }))));
+program
+    .command("watch [run-id]")
+    .description("attach to a running run and follow its progress live (newest active run by default)")
+    .option("--from-start", "render the events written before attaching, then follow")
+    .action((runId, commandOptions) => execute(() => watchCommand({ ...globalOptions(), runId, ...commandOptions })));
+program
+    .command("dashboard")
+    .description("quota + active runs + recent runs: one snapshot when piped, a live view on a TTY")
+    .option("--interval <seconds>", "repaint interval in seconds on a TTY (default 2)", (value) => Number(value))
+    .action((commandOptions) => execute(() => dashboardCommand({ ...globalOptions(), ...commandOptions })));
 const mcp = program
     .command("mcp")
     .description("optional glm-mcp MCP server: snippet, install, remove")