glm-coding-router 1.1.2 → 2.1.0

package/dist/commands/usage.js

@@ -5,47 +5,10 @@ import { Errors } from "../core/errors.js";
 import { configDir } from "../core/paths.js";
 import { version } from "../core/version.js";
 import { resolveZaiApiKey } from "../core/zai-key.js";
+import { describeWindow, fetchZaiQuota } from "../core/zai-quota.js";
 import { emitJson } from "./context.js";
-/** Z.ai monitor API used by their own dashboard (specs/usage.md). */
-const ZAI_QUOTA_URL = "https://api.z.ai/api/monitor/usage/quota/limit";
-/** Window labels for the observed enum values (specs/usage.md); unknown values stay generic. */
-export function describeWindow(limit) {
-    if (limit.unit === 3 && typeof limit.number === "number") {
-        return `${limit.number}-hour window`;
-    }
-    if (limit.unit === 6 && limit.number === 1) {
-        return "weekly";
-    }
-    return `window unit=${String(limit.unit)} x ${String(limit.number)}`;
-}
-/** Fetch and validate the Z.ai quota snapshot. Never logs the Authorization header. */
-export async function fetchZaiQuota(key, fetchImpl) {
-    let response;
-    try {
-        response = await fetchImpl(ZAI_QUOTA_URL, {
-            method: "GET",
-            headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
-            signal: AbortSignal.timeout(10_000),
-        });
-    }
-    catch (error) {
-        throw new Error(`Z.ai monitor endpoint unreachable (${error instanceof Error ? error.message : "network error"})`);
-    }
-    if (!response.ok) {
-        throw new Error(`Z.ai monitor endpoint returned HTTP ${response.status}`);
-    }
-    let body;
-    try {
-        body = (await response.json());
-    }
-    catch {
-        throw new Error("Z.ai monitor endpoint returned a non-JSON body");
-    }
-    if (body.code !== 200 || typeof body.data !== "object" || body.data === null) {
-        throw new Error(`Z.ai monitor endpoint rejected the request (${body.msg ?? `code ${String(body.code)}`})`);
-    }
-    return body.data;
-}
+import { createCommandUi } from "../tui/command-ui.js";
+import { createWriter } from "../tui/render.js";
 /** Aggregate saved benchmark reports (specs/benchmark.md) into one local summary. */
 export function aggregateLocalUsage(home) {
     const dir = path.join(configDir(home), "benchmarks");
@@ -124,39 +87,52 @@ export async function usageCommand(options, deps = {}) {
         emitJson(json);
         return quotaError ? 1 : 0;
     }
-    const lines = [`GLM Coding Router v${version} — usage snapshot`, ""];
+    const stream = deps.stdout ?? process.stdout;
+    const writer = createWriter(stream);
+    const ui = createCommandUi(writer, { quiet: options.quiet });
+    const blocks = [];
+    const header = ui.header(`GLM CODING ROUTER  v${version}  /  USAGE`, "Coding Plan quota snapshot");
+    if (header)
+        blocks.push(header);
+    const quotaRows = [
+        ui.section(`Z.AI CODING PLAN${quota?.level ? `  /  ${quota.level}` : ""}`),
+    ];
     if (quotaError) {
-        lines.push(`Z.ai Coding Plan`);
-        lines.push(`  ✗ ${quotaError}`);
+        quotaRows.push(ui.row("Z.ai Coding Plan", quotaError, "fail"));
+    }
+    else if (limits.length === 0) {
+        quotaRows.push(ui.detail("(no quota windows reported)"));
     }
     else {
-        lines.push(`Z.ai Coding Plan${quota?.level ? ` (level: ${quota.level})` : ""}`);
-        if (limits.length === 0) {
-            lines.push("  (no quota windows reported)");
-        }
         for (const limit of limits) {
             const consumed = limit.currentValue ?? "?";
             const total = limit.usage ?? "?";
-            const percentage = typeof limit.percentage === "number"
+            // Never treat a missing consumed/total as zero quota — only a finite
+            // ratio with total > 0 may be turned into a percentage (spec §B.5).
+            const percentNumeric = typeof limit.percentage === "number"
                 ? limit.percentage
                 : typeof limit.currentValue === "number" && typeof limit.usage === "number" && limit.usage > 0
                     ? Math.round((limit.currentValue / limit.usage) * 100)
-                    : "?";
+                    : undefined;
+            const percentage = percentNumeric ?? "?";
             const resets = typeof limit.nextResetTime === "number" ? ` — resets ${new Date(limit.nextResetTime).toISOString()}` : "";
-            lines.push(`  ${describeWindow(limit).padEnd(15)} ${consumed} / ${total} credits (${percentage}%)${resets}`);
+            quotaRows.push(ui.row(describeWindow(limit), `${consumed} / ${total} credits (${percentage}%)${resets}`));
+            const remaining = typeof limit.remaining === "number" ? `${limit.remaining} remaining` : "remaining unknown";
+            quotaRows.push(ui.detail(`${ui.bar(percentNumeric)} · ${remaining}`));
         }
     }
-    lines.push("");
-    lines.push("Local (benchmark reports)");
+    blocks.push(quotaRows.join("\n"));
+    const benchmarkRows = [ui.section("LOCAL BENCHMARKS")];
     if (local.runs === 0) {
-        lines.push("  (none yet — run glm-router benchmark)");
+        benchmarkRows.push(ui.detail("(none yet — run glm-router benchmark)"));
     }
     else {
-        lines.push(`  runs ${local.runs} · tokens ${local.tokensIn} in / ${local.tokensOut} out · last ${local.lastFinishedAt}`);
+        benchmarkRows.push(ui.row("Runs", String(local.runs)));
+        benchmarkRows.push(ui.row("Tokens", `${local.tokensIn} in / ${local.tokensOut} out`));
+        benchmarkRows.push(ui.row("Last run", String(local.lastFinishedAt)));
     }
-    lines.push("");
-    lines.push(`Claude quota   ${json.claude}`);
-    lines.push(`Codex usage    ${json.codex}`);
-    process.stdout.write(lines.join("\n") + "\n");
+    blocks.push(benchmarkRows.join("\n"));
+    blocks.push([ui.section("OTHER PROVIDERS"), ui.row("Claude", json.claude), ui.row("Codex", json.codex)].join("\n"));
+    writer.line(blocks.join("\n\n"));
     return quotaError ? 1 : 0;
 }

package/dist/commands/watch.js

@@ -0,0 +1,289 @@
+import fs from "node:fs";
+import os from "node:os";
+import { loadConfig } from "../core/config.js";
+import { Errors } from "../core/errors.js";
+import { logger } from "../core/logging.js";
+import { activeRunFile, runDir } from "../core/paths.js";
+import { createEventBus } from "../events/bus.js";
+import { listActive, listHistory } from "../runs/registry.js";
+import { eventsFilePath } from "../runs/store.js";
+import { attachProgress, resolveProgressMode } from "../tui/progress.js";
+/**
+ * fs.watch is the primary follow mechanism but is unreliable on some platforms
+ * (and fires spuriously on others), so a slow interval re-reads from the last
+ * offset as a backstop — never as a tight poll loop.
+ */
+const DEFAULT_FALLBACK_INTERVAL_MS = 1000;
+/** The events that end a run; seeing one means there is nothing left to follow. */
+const TERMINAL_EVENT_TYPES = new Set(["RunCompleted", "RunFailed", "RunCancelled"]);
+/**
+ * glm-router watch [run-id] — attach to a running run and follow it live. The
+ * stored events are re-emitted onto a fresh bus that `attachProgress` renders
+ * through, so a followed run prints exactly what a live one prints. Attaching
+ * reads from the CURRENT end of `events.jsonl` (`--from-start` rewinds to 0):
+ * the user wants what happens from now on, not a replay of what they missed.
+ * Exit 0 on every stop — a run ending, crashing or being interrupted is what
+ * watching is for, not a failure of the command.
+ */
+export function watchCommand(options, deps = {}) {
+    const home = deps.home ?? os.homedir();
+    const target = resolveTarget(home, options.runId);
+    if (target.kind === "none") {
+        // Nothing running is normal, not an error — one clear line, exit 0.
+        process.stdout.write("no active run\n");
+        return Promise.resolve(0);
+    }
+    if (target.kind === "finished") {
+        process.stdout.write(`run ${target.id} already finished (${target.state}) — nothing to follow\n`);
+        return Promise.resolve(0);
+    }
+    const run = target.run;
+    const stream = deps.stderr ?? process.stderr;
+    const intervalMs = deps.intervalMs ?? DEFAULT_FALLBACK_INTERVAL_MS;
+    const file = eventsFilePath(runDir(home, run.date, run.id));
+    const activeFile = activeRunFile(home, run.id);
+    // The registry is the fast path, but the events are the truth: a run whose
+    // last recorded event is terminal is over even while a stale active file
+    // still lists it (a crash between summary and cleanup leaves exactly that).
+    // Following such a file would hang forever, so say so and leave.
+    if (options.fromStart !== true) {
+        const ended = lastTerminalEventType(file);
+        if (ended !== null) {
+            process.stdout.write(`run ${run.id} already ended (${ended}) — nothing to follow\n`);
+            return Promise.resolve(0);
+        }
+    }
+    // Same mode resolution as a live run, so the two views cannot diverge.
+    const mode = resolveProgressMode({
+        quiet: options.quiet,
+        configMode: loadConfig(home).ui.mode,
+        env: process.env,
+        isTTY: streamIsTTY(stream),
+    });
+    const bus = createEventBus(run.id);
+    const progress = attachProgress(bus, { mode, stream });
+    return new Promise((resolve) => {
+        // Bytes below `offset` have been consumed; `pending` holds a torn final
+        // line until its remainder arrives (the store appends whole lines, so a
+        // torn line is the normal mid-append state, not corruption).
+        let offset = options.fromStart === true ? 0 : fileSize(file);
+        let pending = Buffer.alloc(0);
+        let watcher = null;
+        let timer = null;
+        let stopped = false;
+        const stop = (code) => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            if (timer !== null) {
+                clearInterval(timer);
+            }
+            watcher?.close();
+            process.removeListener("SIGINT", onSigint);
+            progress.detach(); // restores the cursor in rich mode
+            bus.close();
+            resolve(code);
+        };
+        const onSigint = () => {
+            stop(0);
+        };
+        /** A transient fs error inside a timer/watch callback must not kill node. */
+        const pump = () => {
+            if (stopped) {
+                return;
+            }
+            try {
+                pumpOnce();
+            }
+            catch (error) {
+                logger.debug(`watch: pumping ${file} failed: ${errorMessage(error)}`);
+            }
+        };
+        const pumpOnce = () => {
+            // A stat failure (file not created yet by a very fresh run, or a prune
+            // racing the watch) reads as "nothing new" — the active-file check below
+            // is the only authority on whether the run itself ended.
+            const size = fileSize(file);
+            if (size > offset) {
+                const chunk = readRange(file, offset, size - offset);
+                offset = size;
+                pending = Buffer.concat([pending, chunk]);
+            }
+            // Only newline-terminated lines are parsed; anything else waits for the
+            // next pump, which is what makes a mid-append read harmless.
+            for (;;) {
+                const newline = pending.indexOf(10);
+                if (newline === -1) {
+                    break;
+                }
+                const line = pending.subarray(0, newline).toString("utf8").trim();
+                pending = pending.subarray(newline + 1);
+                const event = parseStoredEvent(line);
+                if (event === null) {
+                    continue;
+                }
+                // The bus re-stamps seq/ts on replay; nothing downstream of a watch
+                // renders those fields, and a single emit authority stays simpler
+                // than a bypass that would let two writers disagree.
+                bus.emit(event);
+                if (TERMINAL_EVENT_TYPES.has(event.type)) {
+                    stop(0);
+                    return;
+                }
+            }
+            // Every terminal event is appended before the active file is deleted,
+            // so at this point a missing active file means the run died without
+            // one (crash) — the pump above already delivered its last events.
+            if (!fs.existsSync(activeFile)) {
+                process.stdout.write(`run ${run.id} is no longer active — no terminal event was recorded\n`);
+                stop(0);
+            }
+        };
+        const tryStartFsWatch = () => {
+            if (watcher !== null || stopped) {
+                return;
+            }
+            try {
+                watcher = fs.watch(file, () => {
+                    pump();
+                });
+            }
+            catch (error) {
+                // A run so fresh that events.jsonl does not exist yet — the backstop
+                // tick retries until the store creates it.
+                logger.debug(`watch: fs.watch on ${file} failed: ${errorMessage(error)}`);
+            }
+        };
+        process.on("SIGINT", onSigint);
+        if (options.fromStart === true) {
+            pump();
+        }
+        if (!stopped) {
+            if (deps.watchImpl !== undefined) {
+                watcher = deps.watchImpl(file, pump);
+            }
+            else {
+                tryStartFsWatch();
+            }
+            timer = setInterval(() => {
+                if (deps.watchImpl === undefined) {
+                    tryStartFsWatch();
+                }
+                pump();
+            }, intervalMs);
+            // fs.watch keeps the loop alive on its own; the interval is only a
+            // backstop and must not become a second reason to stay alive. When it
+            // IS the mechanism (watchImpl injected, or fs.watch never started), it
+            // stays referenced — otherwise node would exit mid-follow.
+            if (deps.watchImpl === undefined && watcher !== null) {
+                timer.unref();
+            }
+        }
+    });
+}
+/**
+ * Full id or unique suffix, exact match first, ambiguity named — the same
+ * rule as `runs show`. A suffix can also hit history: a finished run is
+ * reported as such rather than "not found" (which would be false) — and
+ * watching one would hang forever, so the caller prints and exits instead.
+ */
+function resolveTarget(home, input) {
+    const activeRuns = listActive(home); // newest first
+    if (input === undefined) {
+        return activeRuns.length > 0 ? { kind: "active", run: activeRuns[0] } : { kind: "none" };
+    }
+    const exact = activeRuns.find((run) => run.id === input);
+    if (exact !== undefined) {
+        return { kind: "active", run: exact };
+    }
+    const suffix = activeRuns.filter((run) => run.id.endsWith(input));
+    if (suffix.length === 1) {
+        return { kind: "active", run: suffix[0] };
+    }
+    if (suffix.length > 1) {
+        throw Errors.invalidArgs(`run id "${input}" is ambiguous — ${suffix.length} active runs end with it:`, suffix.map((run) => run.id));
+    }
+    const refs = listHistory(home);
+    const refExact = refs.find((ref) => ref.id === input);
+    const refSuffix = refs.filter((ref) => ref.id.endsWith(input));
+    const match = refExact ?? (refSuffix.length === 1 ? refSuffix[0] : undefined);
+    if (refExact === undefined && refSuffix.length > 1) {
+        throw Errors.invalidArgs(`run id "${input}" is ambiguous — ${refSuffix.length} recorded runs end with it:`, refSuffix.map((candidate) => candidate.id));
+    }
+    if (match !== undefined) {
+        return { kind: "finished", id: match.id, state: match.state };
+    }
+    throw Errors.invalidArgs(`no run found with id "${input}"`, [`Run "glm-router runs" to list recorded runs.`]);
+}
+/**
+ * The runtime check mirrors `readEvents`: "parses and has a `type` string".
+ * History written by a future version must degrade to an ignored line, not
+ * crash the watcher.
+ */
+function parseStoredEvent(line) {
+    if (line === "") {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed === "object" && parsed !== null && typeof parsed.type === "string") {
+            return parsed;
+        }
+    }
+    catch {
+        // A malformed newline-terminated line is skipped, like readEvents skips it.
+    }
+    return null;
+}
+/** Reads exactly [offset, offset+length) — a follow must never re-read bytes. */
+function readRange(file, offset, length) {
+    const fd = fs.openSync(file, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        const read = fs.readSync(fd, buffer, 0, length, offset);
+        return read === length ? buffer : buffer.subarray(0, read);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function fileSize(file) {
+    try {
+        return fs.statSync(file).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * The `type` of the last COMPLETE line, when that type is terminal — null
+ * otherwise (including "file missing" and "last line torn", which both mean
+ * "keep following"). Only the file's tail is read; one event line is far
+ * smaller than the 8 KiB window.
+ */
+function lastTerminalEventType(file) {
+    const size = fileSize(file);
+    if (size === 0) {
+        return null;
+    }
+    const length = Math.min(size, 8192);
+    const body = readRange(file, size - length, length).toString("utf8");
+    const terminated = body.endsWith("\n") ? body.slice(0, -1) : body;
+    const lastNewline = terminated.lastIndexOf("\n");
+    if (lastNewline !== -1 || length === size) {
+        const line = (lastNewline === -1 ? terminated : terminated.slice(lastNewline + 1)).trim();
+        const event = parseStoredEvent(line);
+        if (event !== null && TERMINAL_EVENT_TYPES.has(event.type)) {
+            return event.type;
+        }
+    }
+    return null;
+}
+/** NodeJS.WritableStream has no terminal members; narrow structurally. */
+function streamIsTTY(stream) {
+    return stream.isTTY === true;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/config.js

@@ -68,6 +68,53 @@ export const ConfigSchema = z.object({
     codexPath: z.string().min(1).optional(),
     // Named overlays selected via --profile (specs/glm-fast-profiles.md).
     profiles: z.record(z.string(), ProfileSchema).default({}),
+    // Run-history retention (specs/v2-architecture.md, Phase B / Config v2).
+    // The whole section is defaulted so every v1 config still validates.
+    history: z.object({
+        retentionDays: z.number().int().positive(),
+        maxRuns: z.number().int().positive(),
+    }).default({ retentionDays: 30, maxRuns: 1000 }),
+    // Progress renderer defaults (specs/v2-architecture.md, Phase C / Config v2).
+    // Defaulted exactly like `history` so every v1 config still validates and
+    // schemaVersion stays 1; `mode: "auto"` means rich on a TTY, nested otherwise.
+    ui: z.object({
+        mode: z.enum(["auto", "rich", "nested", "off"]),
+        color: z.boolean(),
+    }).default({ mode: "auto", color: true }),
+    // Quota-aware routing (specs/v2-architecture.md, Phase E / Config v2).
+    // Defaulted exactly like `history` so every v1 config still validates and
+    // schemaVersion stays 1.
+    routing: z.object({
+        quotaAware: z.boolean(),
+        refuseOnCritical: z.boolean(),
+        handoffOnLowQuota: z.boolean(),
+        reserveRatio: z.number().gt(0).lt(1),
+        safetyFactor: z.number().gte(1),
+        preferFlashBelow: z.number().gt(0).lt(1),
+        handoffReadyBelow: z.number().gt(0).lt(1),
+        criticalBelow: z.number().gt(0).lt(1),
+        pollIntervalSec: z.number().int().positive(),
+        quotaCacheTtlSec: z.number().int().positive(),
+    })
+        .refine((routing) => routing.criticalBelow < routing.handoffReadyBelow &&
+        routing.handoffReadyBelow < routing.preferFlashBelow, { message: "routing zones must be ordered criticalBelow < handoffReadyBelow < preferFlashBelow" })
+        .default({
+        quotaAware: true,
+        // D3 (specs/v2-architecture.md, Decisions): refuseOnCritical and
+        // handoffOnLowQuota ship OFF in 2.0.0. Both act on an unmeasured cost
+        // baseline, and a wrong refusal/kill blocks real work behind a --force
+        // escape hatch; a wrong downgrade costs almost nothing. Observe and
+        // downgrade only until the routingAdvice evidence justifies flipping.
+        refuseOnCritical: false,
+        handoffOnLowQuota: false,
+        reserveRatio: 0.10,
+        safetyFactor: 1.3,
+        preferFlashBelow: 0.30,
+        handoffReadyBelow: 0.15,
+        criticalBelow: 0.08,
+        pollIntervalSec: 60,
+        quotaCacheTtlSec: 60,
+    }),
 });
 export function defaultConfig() {
     return {
@@ -88,6 +135,20 @@ export function defaultConfig() {
             codexSkill: true,
         },
         profiles: {},
+        history: { retentionDays: 30, maxRuns: 1000 },
+        ui: { mode: "auto", color: true },
+        routing: {
+            quotaAware: true,
+            refuseOnCritical: false, // D3: observe in 2.0.0, refuse only on 2.1 evidence
+            handoffOnLowQuota: false, // D3: never kill a live child by default
+            reserveRatio: 0.10,
+            safetyFactor: 1.3,
+            preferFlashBelow: 0.30,
+            handoffReadyBelow: 0.15,
+            criticalBelow: 0.08,
+            pollIntervalSec: 60,
+            quotaCacheTtlSec: 60,
+        },
     };
 }
 /**

package/dist/core/errors.js

@@ -22,6 +22,8 @@ export const ExitCode = {
     ProjectRootNotFound: 30,
     ManagedFileWriteFailed: 31,
     ChildAgentFailed: 40,
+    QuotaInsufficient: 41,
+    HandoffRequired: 42,
     UnsupportedPlatform: 50,
 };
 /** Base error for all expected failures. Printed as `ERROR [NAME]` (spec §36). */
@@ -102,6 +104,28 @@ export const Errors = {
         message: `The child agent process failed: ${cause}`,
         exitCode: ExitCode.ChildAgentFailed,
     }),
+    // 41 and 42 (specs/v2-architecture.md Phase E/F, decision D2) both mean
+    // "unfinished, work preserved" — orchestrators read them as a handoff, not
+    // a crash, which is why their hints point at resuming rather than retrying.
+    quotaInsufficient: (estimatedCost, usableBudget) => new GlmRouterError({
+        name: "QUOTA_INSUFFICIENT",
+        // Both numbers are plan credits (H7), never currency.
+        message: `Estimated cost ${estimatedCost} credits does not fit the usable budget of ${usableBudget} credits.`,
+        // 41 is the preflight refusal: nothing was spawned yet, so the only
+        // moves are wait for a reset or explicitly accept the risk.
+        hint: ["Wait for the quota window to reset, or re-run with --force to run anyway."],
+        exitCode: ExitCode.QuotaInsufficient,
+    }),
+    handoffRequired: (reason, bundlePath) => new GlmRouterError({
+        name: "HANDOFF_REQUIRED",
+        message: `The run stopped unfinished: ${reason}.`,
+        // 42 is the mid-run handoff: the work is never lost, only moved.
+        hint: [
+            "The work is unfinished but preserved.",
+            ...(bundlePath !== undefined ? [`Pick it up from: ${bundlePath}`] : []),
+        ],
+        exitCode: ExitCode.HandoffRequired,
+    }),
     unsupportedPlatform: (platform) => new GlmRouterError({
         name: "UNSUPPORTED_PLATFORM",
         message: `This platform is not supported (detected: ${platform}).`,

package/dist/core/key-inspector.js

@@ -0,0 +1,45 @@
+/**
+ * Two-source credential comparison for `doctor` (specs/terminal-ui-doctor.md
+ * §C). This module never changes runtime key precedence — `resolveZaiApiKey`
+ * in zai-key.ts remains the single source of truth for which key an agent
+ * actually uses. It only *observes* both sources once, privately, so doctor
+ * can warn when the process value that wins is stale.
+ *
+ * `effectiveKey` on the returned snapshot is the real secret value. Never put
+ * it in a `DoctorReport`, JSON payload, log line or thrown error — only the
+ * `comparison` / `keyMismatch` / `effectiveSource` fields are safe to expose.
+ */
+import { detectUserEnvStore, readUserEnvDiagnostic } from "./user-env.js";
+import { ZAI_API_KEY_ENV } from "./zai-key.js";
+/**
+ * Read both sources once and compare them without changing which one wins.
+ * Precedence mirrors `resolveZaiApiKey`: process environment, then the
+ * per-user store.
+ */
+export function inspectZaiKey(options = {}) {
+    const env = options.env ?? process.env;
+    const store = options.store ?? detectUserEnvStore();
+    const diagnose = options.readUserEnvDiagnostic ?? ((name) => readUserEnvDiagnostic(name));
+    const rawProcess = env[ZAI_API_KEY_ENV];
+    const processValue = rawProcess && rawProcess.trim() ? rawProcess.trim() : undefined;
+    const storeResult = diagnose(ZAI_API_KEY_ENV);
+    const storeValue = storeResult.value;
+    const effectiveKey = processValue ?? storeValue;
+    const effectiveSource = processValue
+        ? "process-env"
+        : storeValue
+            ? "user-store"
+            : undefined;
+    let comparison;
+    if (!storeResult.readable) {
+        comparison = "unavailable";
+    }
+    else if (processValue && storeValue) {
+        comparison = processValue === storeValue ? "match" : "different";
+    }
+    else {
+        comparison = "not-comparable";
+    }
+    const keyMismatch = comparison === "different" ? true : comparison === "match" ? false : null;
+    return { effectiveKey, effectiveSource, comparison, keyMismatch, store };
+}

package/dist/core/paths.js

@@ -11,3 +11,35 @@ export function configPath(home = os.homedir()) {
 export function ownershipPath(home = os.homedir()) {
     return path.join(configDir(home), "ownership.json");
 }
+/** Run history root: <configDir>/runs (specs/v2-architecture.md, Phase B). */
+export function runsDir(home = os.homedir()) {
+    return path.join(configDir(home), "runs");
+}
+/** Registry of still-running workers; a run graduates to history on finish. */
+export function activeRunsDir(home = os.homedir()) {
+    return path.join(runsDir(home), "active");
+}
+/**
+ * History partitioned per day so retention can prune whole date directories
+ * (doc §6). `date` (YYYY-MM-DD) comes from the caller — no clock inside the
+ * path helpers, so the store decides when the day flips.
+ */
+export function runHistoryDir(home = os.homedir(), date) {
+    return path.join(runsDir(home), "history", date);
+}
+/** One directory per run: events.jsonl, summary.json, checkpoint, handoff bundle. */
+export function runDir(home = os.homedir(), date, id) {
+    return path.join(runHistoryDir(home, date), id);
+}
+/** The registry entry for an active run, deleted when the run moves to history. */
+export function activeRunFile(home = os.homedir(), id) {
+    return path.join(activeRunsDir(home), `${id}.json`);
+}
+/** Cached quota snapshot (specs/v2-architecture.md, Phase E) — a cache, never truth. */
+export function quotaCachePath(home = os.homedir()) {
+    return path.join(configDir(home), "cache", "quota.json");
+}
+/** Cost-history samples, one JSON line per cleanly measured run (doc §13, Phase E). */
+export function costSamplesPath(home = os.homedir()) {
+    return path.join(configDir(home), "cost-samples.jsonl");
+}