glm-coding-router 2.0.0 → 2.1.0

package/dist/cli.js

@@ -4,6 +4,7 @@ import { version } from "./core/version.js";
 import { ExitCode } from "./core/errors.js";
 import { isMainModule } from "./core/main-guard.js";
 import { applyGlobalOptions, reportError } from "./commands/context.js";
+import { landingCommand } from "./commands/landing.js";
 import { initCommand } from "./commands/init.js";
 import { doctorCommand } from "./commands/doctor-command.js";
 import { statusCommand } from "./commands/status.js";
@@ -31,7 +32,10 @@ program
     .option("--verbose", "debug-level output")
     .option("--dry-run", "preview file modifications without writing")
     .option("--force", "apply actions even when already done")
-    .option("--yes", "assume defaults for all prompts");
+    .option("--yes", "assume defaults for all prompts")
+    // No subcommand: an offline landing page (specs/terminal-ui-doctor.md §B.1),
+    // not a call into any command that reads config/credentials or the network.
+    .action(() => execute(() => Promise.resolve(landingCommand(globalOptions()))));
 /** Shared action wrapper: apply global flags, catch errors, set the exit code. */
 async function execute(action) {
     applyGlobalOptions(globalOptions());
@@ -51,8 +55,9 @@ program
     .action(() => execute(() => initCommand(globalOptions())));
 program
     .command("doctor")
-    .description("diagnose the full runtime")
-    .option("--network", "also probe Z.ai endpoint reachability")
+    .description("diagnose the full runtime, authenticating the effective Z.ai key by default")
+    .option("--network", "also probe Anthropic endpoint reachability")
+    .option("--offline", "local checks only; skip online key authentication")
     .action((commandOptions) => execute(() => doctorCommand({ ...globalOptions(), ...commandOptions })));
 program
     .command("status")

package/dist/commands/doctor-auth.js

@@ -0,0 +1,107 @@
+/**
+ * Pure credential-authentication state and doctor verdict logic
+ * (specs/terminal-ui-doctor.md §D, §E). Kept separate from doctor-command.ts
+ * so the precedence rules are unit-testable without mocking fetch/stdout.
+ */
+import { ZaiQuotaError, fetchZaiQuota } from "../core/zai-quota.js";
+/**
+ * Authenticate exactly the effective key once. Never retries with a
+ * different key on rejection (spec §C.6) — that would hide the key the next
+ * worker will actually use.
+ */
+export async function authenticateZaiKey(key, fetchImpl, offline) {
+    if (offline) {
+        return {
+            state: "skipped",
+            checked: false,
+            method: "zai-quota-monitor",
+            reason: "offline",
+            detail: "Online authentication was not performed (--offline).",
+        };
+    }
+    if (!key) {
+        return {
+            state: "missing",
+            checked: false,
+            method: "zai-quota-monitor",
+            reason: "missing-key",
+            detail: "No ZAI_API_KEY was found in the process environment or the per-user store.",
+        };
+    }
+    try {
+        await fetchZaiQuota(key, fetchImpl);
+        return {
+            state: "verified",
+            checked: true,
+            method: "zai-quota-monitor",
+            reason: "accepted",
+            detail: "The Z.ai monitor endpoint accepted the selected key.",
+        };
+    }
+    catch (error) {
+        if (!(error instanceof ZaiQuotaError)) {
+            return {
+                state: "unverified",
+                checked: true,
+                method: "zai-quota-monitor",
+                reason: "network-error",
+                detail: "Authentication could not be completed.",
+            };
+        }
+        switch (error.kind) {
+            case "unauthorized":
+                return { state: "rejected", checked: true, method: "zai-quota-monitor", reason: "http-401", detail: error.message };
+            case "forbidden":
+                return { state: "rejected", checked: true, method: "zai-quota-monitor", reason: "http-403", detail: error.message };
+            case "rate-limited":
+                return { state: "unverified", checked: true, method: "zai-quota-monitor", reason: "rate-limited", detail: error.message };
+            case "http":
+                return { state: "unverified", checked: true, method: "zai-quota-monitor", reason: "http-error", detail: error.message };
+            case "network":
+                return {
+                    state: "unverified",
+                    checked: true,
+                    method: "zai-quota-monitor",
+                    reason: error.timeout ? "timeout" : "network-error",
+                    detail: error.message,
+                };
+            case "invalid-response":
+                return { state: "unverified", checked: true, method: "zai-quota-monitor", reason: "invalid-response", detail: error.message };
+            case "provider":
+                return { state: "unverified", checked: true, method: "zai-quota-monitor", reason: "provider-error", detail: error.message };
+        }
+    }
+}
+/** The Credentials-section row status for the authentication check (spec §D table's "Check" column). */
+export function authenticationCheckStatus(state) {
+    switch (state) {
+        case "verified":
+            return "ok";
+        case "rejected":
+        case "missing":
+            return "fail";
+        case "unverified":
+        case "skipped":
+            return "warn";
+    }
+}
+/**
+ * Overall summary precedence (spec §E, first matching row wins). `networkProbeFailed`
+ * only applies when `--network` was explicitly requested; it is `false`/`undefined`
+ * whenever that probe was not run or came back reachable.
+ */
+export function deriveDoctorVerdict(input) {
+    const { localFailure, authentication, keyComparison, offline, networkProbeFailed } = input;
+    if (localFailure || authentication.state === "missing" || authentication.state === "rejected") {
+        return { status: "ISSUES", exitCode: 1 };
+    }
+    if (authentication.state === "unverified" || authentication.state === "skipped" || networkProbeFailed) {
+        const exitCode = offline && authentication.state === "skipped" ? 0 : 1;
+        return { status: "UNVERIFIED", exitCode };
+    }
+    // authentication.state === "verified" from here on.
+    if (keyComparison === "different" || keyComparison === "unavailable") {
+        return { status: "ATTENTION", exitCode: 0 };
+    }
+    return { status: "HEALTHY", exitCode: 0 };
+}

package/dist/commands/doctor-command.js

@@ -1,36 +1,13 @@
 import { runDoctorChecks, doctorHasFailures } from "./doctor.js";
 import { emitJson } from "./context.js";
 import { logger } from "../core/logging.js";
-const SYMBOL = {
-    ok: "✓",
-    warn: "⚠",
-    fail: "✗",
-};
-function renderText(results, networkResult) {
-    const lines = ["GLM Coding Router Doctor", ""];
-    let currentSection = "";
-    for (const result of results) {
-        if (result.section !== currentSection) {
-            currentSection = result.section;
-            lines.push(currentSection);
-        }
-        lines.push(`  ${SYMBOL[result.status]} ${result.name}`);
-        if (result.detail) {
-            lines.push(`      ${result.detail}`);
-        }
-        if (result.note) {
-            lines.push(`      ${result.note}`);
-        }
-    }
-    if (networkResult) {
-        lines.push("Network");
-        lines.push(`  ${networkResult === "reachable" ? "✓" : "⚠"} Z.ai endpoint ${networkResult}`);
-    }
-    const failures = doctorHasFailures(results);
-    lines.push("");
-    lines.push(`Status: ${failures ? "ISSUES DETECTED" : "HEALTHY"}`);
-    return lines.join("\n");
-}
+import { Errors } from "../core/errors.js";
+import { inspectZaiKey } from "../core/key-inspector.js";
+import { authenticateZaiKey, authenticationCheckStatus, deriveDoctorVerdict, } from "./doctor-auth.js";
+import { describeKeyStore, detectUserEnvStore } from "../core/user-env.js";
+import { createWriter } from "../tui/render.js";
+import { createCommandUi } from "../tui/command-ui.js";
+import { version } from "../core/version.js";
 /** Lightweight endpoint reachability probe (spec §42). Never consumes coding quota. */
 export async function probeEndpoint(baseUrl, fetchImpl = fetch) {
     try {
@@ -45,24 +22,177 @@ export async function probeEndpoint(baseUrl, fetchImpl = fetch) {
         return "not reachable";
     }
 }
+function shellUnsetLines(platform) {
+    if (platform === "win32") {
+        return ["PowerShell:  Remove-Item Env:ZAI_API_KEY", "CMD:         set ZAI_API_KEY="];
+    }
+    return ["POSIX shell: unset ZAI_API_KEY"];
+}
+function describeComparisonRow(inspection) {
+    switch (inspection.comparison) {
+        case "match":
+            return { status: "ok", value: "Matches the saved key" };
+        case "different":
+            return { status: "warn", value: "Different from the saved key" };
+        case "unavailable":
+            return { status: "warn", value: `Could not read ${describeKeyStore(inspection.store)} to compare` };
+        case "not-comparable":
+            if (inspection.store === "none") {
+                return { status: "info", value: "No persistent store on this platform" };
+            }
+            if (inspection.effectiveSource === "process-env") {
+                return { status: "info", value: "No saved key to compare against" };
+            }
+            if (inspection.effectiveSource === "user-store") {
+                return { status: "info", value: "No process override" };
+            }
+            return { status: "info", value: "Not applicable" };
+    }
+}
+/** Ordered, actionable "next step" lines. Empty when the verdict is HEALTHY. */
+function buildNextSteps(input) {
+    const { authentication, comparison, store, platform, networkProbeFailed, verdictStatus } = input;
+    if (verdictStatus === "HEALTHY") {
+        return [];
+    }
+    const lines = [];
+    if (comparison === "different") {
+        lines.push("This terminal's key takes priority over the saved key (process environment wins).", "Restart the terminal's hosting app to refresh its environment,", "or if this is an intentional process override, update that override instead.", ...shellUnsetLines(platform));
+    }
+    else if (comparison === "unavailable") {
+        lines.push(`Could not read ${describeKeyStore(store)} to compare against the process key.`);
+    }
+    switch (authentication.reason) {
+        case "missing-key":
+            lines.push("No ZAI_API_KEY was found.", platform === "win32" ? "Run: glm-router key set" : 'Run: glm-router key set, or export ZAI_API_KEY="<your-key>"');
+            break;
+        case "http-401":
+            lines.push("The selected key was rejected. To replace it: glm-router key set");
+            break;
+        case "http-403":
+            lines.push("Access was denied for the selected key. Check the key's account permissions — not necessarily expiry.");
+            break;
+        case "rate-limited":
+            lines.push("The Z.ai monitor endpoint is rate-limiting this key. Retry in a moment.");
+            break;
+        case "http-error":
+        case "network-error":
+        case "timeout":
+            lines.push("Could not reach the Z.ai monitor endpoint. Check network/proxy connectivity and retry.");
+            break;
+        case "invalid-response":
+        case "provider-error":
+            lines.push("The Z.ai monitor endpoint returned an unexpected response — this is not proof the key is invalid.");
+            break;
+        case "offline":
+            lines.push("Authentication was not checked (--offline). Run without --offline to verify the key online.");
+            break;
+        case "accepted":
+            break;
+    }
+    if (networkProbeFailed) {
+        lines.push("The configured Anthropic endpoint reachability probe did not succeed (separate from key authentication).");
+    }
+    if (lines.length > 0 && authentication.reason !== "offline") {
+        lines.push("Then run: glm-router doctor");
+    }
+    return lines;
+}
 export async function doctorCommand(options, deps = {}) {
-    const report = runDoctorChecks({ home: deps.home, env: deps.env, readUserEnv: deps.readUserEnv });
+    if (options.offline && options.network) {
+        throw Errors.invalidArgs("--offline and --network cannot be used together.", [
+            "Use --offline for local-only checks, or --network for the extra reachability probe.",
+        ]);
+    }
+    const env = deps.env ?? process.env;
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const offline = options.offline ?? false;
+    const platform = deps.platform ?? process.platform;
+    const store = deps.store ?? detectUserEnvStore({ platform, env });
+    const report = runDoctorChecks({ home: deps.home, env, readUserEnv: deps.readUserEnv, store });
+    const inspection = inspectZaiKey({ env, readUserEnvDiagnostic: deps.readUserEnvDiagnostic, store });
+    const [authentication, networkResult] = await Promise.all([
+        authenticateZaiKey(inspection.effectiveKey, fetchImpl, offline),
+        options.network ? probeEndpoint(report.config.provider.anthropicBaseUrl, fetchImpl) : Promise.resolve(undefined),
+    ]);
+    const localFailure = doctorHasFailures(report.results);
+    const networkProbeFailed = networkResult !== undefined && networkResult !== "reachable";
+    const verdict = deriveDoctorVerdict({
+        localFailure,
+        authentication,
+        keyComparison: inspection.comparison,
+        offline,
+        networkProbeFailed,
+    });
     if (options.json) {
-        const networkResult = options.network
-            ? await probeEndpoint(report.config.provider.anthropicBaseUrl, deps.fetchImpl)
-            : undefined;
         emitJson({
-            status: doctorHasFailures(report.results) ? "ISSUES" : "HEALTHY",
+            status: verdict.status,
             checks: report.results,
             keySource: report.keySource,
             network: networkResult,
+            authentication,
+            keyComparison: inspection.comparison,
+            keyMismatch: inspection.keyMismatch,
         });
-        return doctorHasFailures(report.results) ? 1 : 0;
+        return verdict.exitCode;
     }
-    const networkResult = options.network
-        ? await probeEndpoint(report.config.provider.anthropicBaseUrl, deps.fetchImpl)
-        : undefined;
-    process.stdout.write(renderText(report.results, networkResult) + "\n");
+    const stream = deps.stdout ?? process.stdout;
+    const writer = createWriter(stream);
+    const ui = createCommandUi(writer, { quiet: options.quiet });
+    writer.line(renderText(ui, report.results, inspection, authentication, networkResult, verdict, platform));
     logger.debug(`anthropic base url: ${report.config.provider.anthropicBaseUrl}`);
-    return doctorHasFailures(report.results) ? 1 : 0;
+    return verdict.exitCode;
+}
+function renderText(ui, results, inspection, authentication, networkResult, verdict, platform) {
+    const blocks = [];
+    const header = ui.header(`GLM CODING ROUTER  v${version}  /  DOCTOR`, "Runtime and credential diagnostics");
+    if (header)
+        blocks.push(header);
+    let currentSection = "";
+    const localRows = [];
+    for (const result of results) {
+        if (result.section !== currentSection) {
+            currentSection = result.section;
+            localRows.push(ui.section(currentSection.toUpperCase()));
+        }
+        const status = result.status === "ok" ? "ok" : result.status === "warn" ? "warn" : "fail";
+        localRows.push(ui.row(result.name, result.detail ?? "", status));
+        if (result.note)
+            localRows.push(ui.detail(result.note));
+    }
+    blocks.push(localRows.join("\n"));
+    const credentialRows = [ui.section("CREDENTIALS")];
+    credentialRows.push(ui.row("Selected source", inspection.effectiveSource === "process-env" ? "Process environment" : inspection.effectiveSource === "user-store" ? describeKeyStore(inspection.store) : "none", "info"));
+    const comparisonRow = describeComparisonRow(inspection);
+    credentialRows.push(ui.row("Saved key comparison", comparisonRow.value, comparisonRow.status));
+    credentialRows.push(ui.row("Monitor authentication", authentication.detail, authenticationCheckStatus(authentication.state)));
+    blocks.push(credentialRows.join("\n"));
+    if (networkResult !== undefined) {
+        const networkRows = [
+            ui.section("NETWORK"),
+            ui.row("Z.ai endpoint reachability", networkResult, networkResult === "reachable" ? "ok" : "warn"),
+        ];
+        blocks.push(networkRows.join("\n"));
+    }
+    const nextSteps = buildNextSteps({
+        authentication,
+        comparison: inspection.comparison,
+        store: inspection.store,
+        platform,
+        networkProbeFailed: networkResult !== undefined && networkResult !== "reachable",
+        verdictStatus: verdict.status,
+    });
+    if (nextSteps.length > 0) {
+        const footer = ui.footer(nextSteps.join("\n"));
+        if (footer)
+            blocks.push([ui.section("NEXT STEP"), footer].join("\n"));
+    }
+    const resultLabel = {
+        HEALTHY: "HEALTHY",
+        ATTENTION: "ATTENTION",
+        UNVERIFIED: "UNVERIFIED",
+        ISSUES: "ISSUES DETECTED",
+    };
+    blocks.push(`RESULT  ${resultLabel[verdict.status]}`);
+    return blocks.join("\n\n");
 }

package/dist/commands/landing.js

@@ -0,0 +1,47 @@
+/**
+ * `glm-router` with no subcommand (specs/terminal-ui-doctor.md §B.1). Purely
+ * static: no provider request, no key/config read, no side effects. Exists
+ * so a first-time user sees "what do I run" instead of nothing.
+ */
+import { Errors } from "../core/errors.js";
+import { version } from "../core/version.js";
+import { createCommandUi } from "../tui/command-ui.js";
+import { createWriter } from "../tui/render.js";
+export function landingCommand(options, deps = {}) {
+    if (options.json) {
+        // Root --json has no data to emit — a data-producing command must be named.
+        throw Errors.invalidArgs("--json requires a command that produces data.", [
+            "Try:", "", "  glm-router status --json", "  glm-router doctor --json", "  glm-router usage --json",
+        ]);
+    }
+    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}`, "Coding Plan workers for Claude Code and Codex");
+    if (header)
+        blocks.push(header);
+    blocks.push([
+        ui.section("CHECK & MONITOR"),
+        ui.row("glm-router doctor", "Check setup and verify API key"),
+        ui.row("glm-router status", "Quick offline overview"),
+        ui.row("glm-router usage", "Coding Plan quota and reset times"),
+        ui.row("glm-router dashboard", "Live quota and worker activity"),
+    ].join("\n"));
+    blocks.push([
+        ui.section("WORK"),
+        ui.row('glm-worker "<task>"', "Run an implementation task"),
+        ui.row('glm-review "<task>"', "Run a read-only review"),
+        ui.row("glm-router runs", "Inspect recorded runs"),
+    ].join("\n"));
+    blocks.push([
+        ui.section("SETUP"),
+        ui.row("glm-router init", "Guided setup"),
+        ui.row("glm-router key set", "Save a replacement API key"),
+    ].join("\n"));
+    const footer = ui.footer("Start with: glm-router doctor\nAll commands: glm-router --help");
+    if (footer)
+        blocks.push(footer);
+    writer.line(blocks.join("\n\n"));
+    return 0;
+}

package/dist/commands/status.js

@@ -6,7 +6,9 @@ import { resolveZaiApiKey } from "../core/zai-key.js";
 import { skillTargets } from "../integrations/skill.js";
 import { GLM_DELEGATION_SKILL_NAME } from "../templates/glm-delegation-skill.js";
 import { emitJson } from "./context.js";
-/** Fast, fully offline summary (spec §41) — no API requests, no key values. */
+import { createCommandUi } from "../tui/command-ui.js";
+import { createWriter } from "../tui/render.js";
+/** Fast, fully offline summary (spec §41, specs/terminal-ui-doctor.md §B.4) — no API requests, no key values. */
 export function statusCommand(options, deps = {}) {
     const home = deps.home ?? os.homedir();
     const env = deps.env ?? process.env;
@@ -51,23 +53,34 @@ export function statusCommand(options, deps = {}) {
         });
         return 0;
     }
-    /** Every status row pads its label to this column (spec §41). */
-    const LABEL_WIDTH = 16;
-    const lines = [
-        `GLM Coding Router v${version}`,
-        "",
-        `Z.ai key        ${resolved ? "configured" : "not configured"}`,
-        `Claude          ${claudeInstalled ? "installed" : "missing"}`,
-        `Codex           ${codexInstalled ? "installed" : "missing"}`,
-        "",
-        `Claude policy   ${config.integrations.claude ? "enabled" : "disabled"}`,
-        `Codex policy    ${config.integrations.codex ? "enabled" : "disabled"}`,
+    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}  /  STATUS`, "Offline overview — credentials not verified this run");
+    if (header)
+        blocks.push(header);
+    blocks.push([
+        ui.section("SYSTEM"),
+        // Presence only, never validity — that claim belongs to `doctor` (spec §B.4).
+        ui.row("Z.ai key", resolved ? "configured (not verified — run: glm-router doctor)" : "not configured", resolved ? "ok" : "fail"),
+        ui.row("Claude", claudeInstalled ? "installed" : "missing", claudeInstalled ? "ok" : "fail"),
+        ui.row("Codex", codexInstalled ? "installed" : "missing", codexInstalled ? "ok" : "warn"),
+    ].join("\n"));
+    const integrationRows = [
+        ui.section("INTEGRATIONS"),
+        ui.row("Claude policy", config.integrations.claude ? "enabled" : "disabled", config.integrations.claude ? "ok" : "info"),
+        ui.row("Codex policy", config.integrations.codex ? "enabled" : "disabled", config.integrations.codex ? "ok" : "info"),
     ];
     for (const row of skillState) {
         const enabled = row.homeDetected && row.installed;
-        lines.push(`${`${row.agent} skill`.padEnd(LABEL_WIDTH)}${enabled ? "enabled" : "disabled"}`);
+        integrationRows.push(ui.row(`${row.agent} skill`, enabled ? "enabled" : "disabled", enabled ? "ok" : "info"));
     }
-    lines.push("", `Main model      ${config.models.main}`, `Fast model      ${config.models.fast}`);
-    process.stdout.write(lines.join("\n") + "\n");
+    blocks.push(integrationRows.join("\n"));
+    blocks.push([ui.section("MODELS"), ui.row("Main model", config.models.main), ui.row("Fast model", config.models.fast)].join("\n"));
+    const footer = ui.footer("Run: glm-router doctor to verify credentials and connectivity.");
+    if (footer)
+        blocks.push(footer);
+    writer.line(blocks.join("\n\n"));
     return 0;
 }

package/dist/commands/usage.js

@@ -7,6 +7,8 @@ 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";
+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");
@@ -85,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/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/user-env.js

@@ -63,12 +63,17 @@ export function describeKeyStore(store) {
     }
 }
 /**
- * Read a variable from the per-user store. Returns undefined on any failure —
- * callers fall back or raise their own error.
+ * Read a variable from the per-user store, distinguishing "no store" / "not
+ * set" (readable: true, value: undefined) from "the read itself failed"
+ * (readable: false). `readUserEnv` below is a thin wrapper that collapses
+ * both to `undefined` for existing callers.
  */
-export function readUserEnv(name, deps = {}) {
+export function readUserEnvDiagnostic(name, deps = {}) {
     assertEnvVarName(name);
     const store = detectUserEnvStore(deps);
+    if (store === "none") {
+        return { readable: true, value: undefined };
+    }
     const run = deps.run ?? defaultRun;
     try {
         let value;
@@ -87,16 +92,21 @@ export function readUserEnv(name, deps = {}) {
             case "libsecret":
                 value = run("secret-tool", ["lookup", "service", KEY_STORE_SERVICE, "account", name], { capture: true });
                 break;
-            case "none":
-                return undefined;
         }
         const trimmed = value.trim();
-        return trimmed || undefined;
+        return { readable: true, value: trimmed || undefined };
     }
     catch {
-        return undefined;
+        return { readable: false, value: undefined };
     }
 }
+/**
+ * Read a variable from the per-user store. Returns undefined on any failure —
+ * callers fall back or raise their own error.
+ */
+export function readUserEnv(name, deps = {}) {
+    return readUserEnvDiagnostic(name, deps).value;
+}
 /**
  * Write a variable to the per-user store. Throws when there is no store —
  * callers print platform-appropriate guidance instead.