agent-dealer 1.2.3 → 1.2.5

package/bundle/server/dist/capacity/claude-local-cache.test.js

@@ -1,8 +1,8 @@
 // packages/server/src/capacity/claude-local-cache.test.ts
 //
 // NOT-268: Claude capacity local-first ladder — local cache 5H/1W plus a
-// one-hour paid fallback. No test here performs a live provider request:
-// every probe spawn goes through an injected fake runner.
+// free `/usage` refresh after one hour stale. No test here performs a live
+// provider request: every probe spawn goes through an injected fake runner.
 import { test, before, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import fs from "node:fs";
@@ -42,17 +42,39 @@ function fullCacheFixture(fetchedAtMs) {
         },
     });
 }
-function probeStreamFixture(observedIso, costUsd = 0.0003) {
+// Mirrors a real `claude -p "/usage"` stream at 2.1.283: a local-command
+// result event carrying `usage_report.rate_limits.limits[]` (verified live
+// 2026-09-27 — see claude-local-cache.ts module header), followed by the
+// terminal `result` event. Real runs cost $0 (no model call); `costUsd`
+// defaults to 0 but stays overridable for the cost-plumbing assertions.
+function probeStreamFixture(observedIso, costUsd = 0) {
     return [
         JSON.stringify({
-            type: "rate_limit_event",
+            type: "assistant",
             timestamp: observedIso,
-            rate_limit_info: {
-                status: "allowed",
-                unifiedWindows: [
-                    { window: "five_hour", utilization: 0.2, resetsAt: FIVE_HOUR_RESET_SEC },
-                    { window: "seven_day", utilization: 0.4, resetsAt: SEVEN_DAY_RESET_SEC },
-                ],
+            local_command_run: { command: "usage", args: "" },
+            usage_report: {
+                session: { total_cost_usd: 0 },
+                rate_limits: {
+                    limits: [
+                        {
+                            kind: "session",
+                            group: "session",
+                            percent: 20,
+                            resets_at: new Date(FIVE_HOUR_RESET_SEC * 1000).toISOString(),
+                            severity: "normal",
+                            is_active: false,
+                        },
+                        {
+                            kind: "weekly_all",
+                            group: "weekly",
+                            percent: 40,
+                            resets_at: new Date(SEVEN_DAY_RESET_SEC * 1000).toISOString(),
+                            severity: "normal",
+                            is_active: true,
+                        },
+                    ],
+                },
             },
         }),
         JSON.stringify({
@@ -263,21 +285,40 @@ test("a 2-hour-old cache ingests with its true age and reads expired, never live
         assert.equal(w.unavailableReason, "expired");
     }
 });
-test("disabled fallback never spawns: every non-opt-in value is a strict no-op", async () => {
-    for (const value of [undefined, "", "off", "auto", "paid-after-1h "]) {
+test("refresh defaults on; explicit off and unrecognized values never spawn", async () => {
+    for (const value of [undefined, "", "paid-after-1h"]) {
         if (value === undefined)
             delete process.env[CLAUDE_CAPACITY_REFRESH_ENV];
         else
             process.env[CLAUDE_CAPACITY_REFRESH_ENV] = value;
+        assert.equal(isClaudePaidFallbackEnabled(), true);
+    }
+    for (const value of ["off", "auto", "paid-after-1h "]) {
+        process.env[CLAUDE_CAPACITY_REFRESH_ENV] = value;
         assert.equal(isClaudePaidFallbackEnabled(), false);
         const outcome = await maybeProbeClaudeCapacity(NOW_MS, { runner: throwingRunner });
         assert.deepEqual(outcome, { probed: false, reason: "disabled" });
     }
-    process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
+    delete process.env[CLAUDE_CAPACITY_REFRESH_ENV];
     assert.equal(isClaudePaidFallbackEnabled(), true);
 });
-test("fresh sample suppresses the probe; stale data triggers exactly one", async () => {
-    process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
+test("extractClaudeUsageReportLimits reads the /usage local-command result", async () => {
+    const { extractClaudeUsageReportLimits } = await import("./claude-local-cache.js");
+    const observedIso = new Date(NOW_MS).toISOString();
+    const events = probeStreamFixture(observedIso).split("\n").map((l) => JSON.parse(l));
+    const readings = extractClaudeUsageReportLimits(events, NOW_MS);
+    assert.ok(readings);
+    assert.equal(readings.length, 2);
+    const fiveHour = readings.find((w) => w.criticalRole === "five_hour");
+    const weekly = readings.find((w) => w.criticalRole === "weekly");
+    assert.equal(fiveHour.usedPercent, 20);
+    assert.equal(weekly.usedPercent, 40);
+    assert.equal(fiveHour.observedAt, observedIso);
+    assert.equal(fiveHour.evidenceRef, "claude-probe:usage-command");
+    // No usage_report anywhere in the stream — nothing fabricated.
+    assert.equal(extractClaudeUsageReportLimits([{ type: "result" }], NOW_MS), null);
+});
+test("default-on refresh suppresses a fresh sample; stale data triggers exactly one", async () => {
     fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 10 * 60_000));
     assert.equal(ingestClaudeLocalCache(NOW_MS), 2);
     assert.ok((newestValidClaudeObservationMs(NOW_MS) ?? 0) > NOW_MS - 60 * 60_000);
@@ -300,8 +341,7 @@ test("fresh sample suppresses the probe; stale data triggers exactly one", async
     assert.equal(outcomes.filter((o) => o.reason === "shared").length, 4);
     assert.ok(outcomes.every((o) => o.probed && o.ok));
 });
-test("probe argv pins the fixed prompt, cheapest model, no tools/MCP, one turn, ≤$0.01", async () => {
-    process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
+test("probe argv pins the fixed /usage command plus structural model-turn safeguards", async () => {
     fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 61 * 60_000));
     assert.equal(ingestClaudeLocalCache(NOW_MS), 2);
     let seenBin = "";
@@ -318,7 +358,7 @@ test("probe argv pins the fixed prompt, cheapest model, no tools/MCP, one turn,
     assert.equal(seenBin, "/fake/claude");
     assert.deepEqual(seenArgv, [
         "-p",
-        "Reply with exactly: ok",
+        "/usage",
         "--model",
         "haiku",
         "--max-turns",
@@ -333,13 +373,14 @@ test("probe argv pins the fixed prompt, cheapest model, no tools/MCP, one turn,
         "--max-budget-usd",
         "0.01",
     ]);
-    // Semantic pins behind the exact match: cheapest model, hard one-turn
-    // bound, tools fully off, MCP restricted to none passed, stream JSON,
-    // hard budget cap.
+    // Semantic pins behind the exact match: no MCP config passed, cheapest
+    // model + hard one-turn bound + no tools kept as structural safeguards
+    // (2026-09-27 review hardening) even though `/usage` never reaches the
+    // model on 2.1.283, plus the defensive budget cap.
+    assert.ok(!seenArgv.includes("--mcp-config"));
     assert.equal(seenArgv[seenArgv.indexOf("--model") + 1], "haiku");
     assert.equal(seenArgv[seenArgv.indexOf("--max-turns") + 1], "1");
     assert.equal(seenArgv[seenArgv.indexOf("--tools") + 1], "");
-    assert.ok(!seenArgv.includes("--mcp-config"));
     const budget = Number(seenArgv[seenArgv.indexOf("--max-budget-usd") + 1]);
     assert.ok(Number.isFinite(budget) && budget <= 0.01);
     assert.equal(seenArgv.filter((a) => a === "-p").length, 1);
@@ -353,7 +394,7 @@ test("probe success updates both 5H and 1W and records cost without prompt/outpu
     assert.equal(ingestClaudeLocalCache(NOW_MS), 2);
     const marker = "probe-stream-marker-must-never-reach-log";
     const runner = async () => ({
-        stdout: `${probeStreamFixture(new Date(NOW_MS).toISOString(), 0.0007)}\n${JSON.stringify({ type: "assistant", text: marker })}`,
+        stdout: `${probeStreamFixture(new Date(NOW_MS).toISOString())}\n${JSON.stringify({ type: "assistant", text: marker })}`,
         exitCode: 0,
         timedOut: false,
         spawnError: null,
@@ -361,28 +402,134 @@ test("probe success updates both 5H and 1W and records cost without prompt/outpu
     const result = await runClaudeCapacityProbe(NOW_MS, { runner });
     assert.equal(result.ok, true);
     assert.equal(result.failureKind, null);
-    assert.equal(result.costUsd, 0.0007);
+    assert.equal(result.costUsd, 0);
     assert.deepEqual(result.windowsUpdated, ["claude_unified_five_hour", "claude_unified_seven_day"]);
     const rows = listCapacitySnapshots("claude_code");
     assert.equal(rows.find((r) => r.providerBucket === "five_hour").remainingPercent, 80);
     assert.equal(rows.find((r) => r.providerBucket === "seven_day").remainingPercent, 60);
     assert.equal(rows.find((r) => r.providerBucket === "five_hour").observedAt, new Date(NOW_MS).toISOString());
     const logText = fs.readFileSync(probeDiagnosticLogPath(), "utf8");
-    assert.ok(logText.includes('"costUsd":0.0007'));
+    assert.ok(logText.includes('"costUsd":0'));
     assert.ok(!logText.includes("Reply with exactly"));
     assert.ok(!logText.includes(marker));
 });
-test("probe success via the cache side effect when the stream carries no windows", async () => {
+test("probe rejects and ingests nothing when the result reports nonzero cost", async () => {
+    // Reviewer-requested hardening (PR #165): any charge means /usage did not
+    // resolve locally as expected — reject the whole run rather than trusting
+    // windows a real (unexpected) model turn happened to produce.
+    process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
+    fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 61 * 60_000));
+    assert.equal(ingestClaudeLocalCache(NOW_MS), 2);
+    const runner = async () => ({
+        stdout: probeStreamFixture(new Date(NOW_MS).toISOString(), 0.0007),
+        exitCode: 0,
+        timedOut: false,
+        spawnError: null,
+    });
+    const result = await runClaudeCapacityProbe(NOW_MS, { runner });
+    assert.equal(result.ok, false);
+    assert.equal(result.failureKind, "unexpected_cost");
+    assert.equal(result.costUsd, 0.0007);
+    assert.deepEqual(result.windowsUpdated, []);
+    // Last-good rows from before the rejected run are untouched.
+    const rows = listCapacitySnapshots("claude_code");
+    assert.equal(rows.find((r) => r.providerBucket === "five_hour").remainingPercent, 83);
+});
+test("probe rejects and ingests nothing when cost cannot be verified as zero", async () => {
+    // Reviewer-requested hardening, round 2 (PR #165): a stream with the
+    // local-command marker and well-formed windows, but a `result` event that
+    // omits `total_cost_usd` (costUsd === null), must fail closed exactly like
+    // a confirmed positive charge — null is not evidence of zero cost.
+    process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
+    fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 61 * 60_000));
+    assert.equal(ingestClaudeLocalCache(NOW_MS), 2);
+    const runner = async () => ({
+        stdout: [
+            JSON.stringify({
+                type: "assistant",
+                timestamp: new Date(NOW_MS).toISOString(),
+                local_command_run: { command: "usage", args: "" },
+                usage_report: {
+                    rate_limits: {
+                        limits: [
+                            { kind: "session", percent: 20, resets_at: new Date(FIVE_HOUR_RESET_SEC * 1000).toISOString() },
+                            { kind: "weekly_all", percent: 40, resets_at: new Date(SEVEN_DAY_RESET_SEC * 1000).toISOString() },
+                        ],
+                    },
+                },
+            }),
+            // No `result` event at all — total_cost_usd is unknowable.
+        ].join("\n"),
+        exitCode: 0,
+        timedOut: false,
+        spawnError: null,
+    });
+    const result = await runClaudeCapacityProbe(NOW_MS, { runner });
+    assert.equal(result.ok, false);
+    assert.equal(result.failureKind, "unexpected_cost");
+    assert.equal(result.costUsd, null);
+    assert.deepEqual(result.windowsUpdated, []);
+    const rows = listCapacitySnapshots("claude_code");
+    assert.equal(rows.find((r) => r.providerBucket === "five_hour").remainingPercent, 83);
+});
+test("probe rejects and ingests nothing when the local-command marker is absent", async () => {
+    // Reviewer-requested hardening (PR #165): a stream that never shows
+    // `/usage` resolving locally must not be trusted, even if it happens to
+    // carry a well-formed usage_report (e.g. a different CLI build echoing it
+    // from a real turn) or a fresh cache-file side effect.
+    process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
+    fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 61 * 60_000));
+    assert.equal(ingestClaudeLocalCache(NOW_MS), 2);
+    const runner = async () => {
+        fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS + 5_000));
+        return {
+            stdout: [
+                JSON.stringify({
+                    type: "assistant",
+                    timestamp: new Date(NOW_MS).toISOString(),
+                    usage_report: {
+                        rate_limits: { limits: [{ kind: "session", percent: 20, resets_at: null }] },
+                    },
+                }),
+                JSON.stringify({ type: "result", is_error: false, total_cost_usd: 0 }),
+            ].join("\n"),
+            exitCode: 0,
+            timedOut: false,
+            spawnError: null,
+        };
+    };
+    const result = await runClaudeCapacityProbe(NOW_MS, { runner });
+    assert.equal(result.ok, false);
+    assert.equal(result.failureKind, "not_local_command");
+    assert.deepEqual(result.windowsUpdated, []);
+    const rows = listCapacitySnapshots("claude_code");
+    assert.equal(rows.find((r) => r.providerBucket === "five_hour").remainingPercent, 83);
+});
+test("probe success via the cache side effect when usage_report carries no windows", async () => {
     process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
     fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 61 * 60_000));
-    // The stream is empty but the probe run itself refreshes Claude's own
-    // cache file — the re-read must count as success.
+    // The local-command marker is present (so the run is trusted) and cost is
+    // $0, but usage_report carries no usable limits[] — the cache re-read
+    // (the probe run itself refreshes Claude's own cache file) still counts
+    // as corroborating success.
     const runner = async () => {
         // A real probe refreshes Claude's own cache file while it runs, so the
         // new `fetchedAtMs` is later than the pre-spawn `NOW_MS` stamp — the
         // post-spawn re-read must accept it, not reject it as future.
         fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS + 5_000));
-        return { stdout: "", exitCode: 0, timedOut: false, spawnError: null };
+        return {
+            stdout: [
+                JSON.stringify({
+                    type: "assistant",
+                    timestamp: new Date(NOW_MS).toISOString(),
+                    local_command_run: { command: "usage", args: "" },
+                }),
+                JSON.stringify({ type: "result", is_error: false, total_cost_usd: 0 }),
+            ].join("\n"),
+            exitCode: 0,
+            timedOut: false,
+            spawnError: null,
+        };
     };
     const result = await runClaudeCapacityProbe(NOW_MS, { runner });
     assert.equal(result.ok, true);
@@ -404,7 +551,9 @@ test("probe failure preserves last-good rows and enters bounded backoff", async
     const first = await maybeProbeClaudeCapacity(NOW_MS, { runner: failing });
     assert.equal(first.probed, true);
     assert.equal(first.ok, false);
-    assert.equal(first.failureKind, "nonzero_exit");
+    // Unparsable stdout ("not-json") means no local-command marker is found —
+    // that check runs before the nonzero-exit fallback.
+    assert.equal(first.failureKind, "not_local_command");
     // Last-good rows are untouched by the failed probe (0.17 used → 83 left).
     const rows = listCapacitySnapshots("claude_code");
     assert.equal(rows.find((r) => r.providerBucket === "five_hour").remainingPercent, 83);

package/bundle/server/dist/capacity/muse-host.js

@@ -44,9 +44,11 @@
 //   clears the sentinel.
 // - Capacity stays independent from `runtime_availability` hard-cap
 //   admission: this module never reads or writes health rows.
-// - The client enforces the read-only allowlist (`initialize`,
-//   `initialized`, `usage/read`) — a capacity read by itself never sends
-//   `session/start`, a prompt, a turn, a tool, or any other billable method.
+// - The free read path enforces the read-only allowlist (`initialize`,
+//   `initialized`, `usage/read`) and never starts billable work. The separate
+//   default-on fallback in `muse-probe.ts` may create a dedicated restricted
+//   host for one fixed, bounded turn after the complete pair has been absent
+//   for an hour.
 //
 // Execution precondition (NOT-269): only a host that observes the account's
 // provider traffic can answer `usage/read`. Real Dealer Muse turns run
@@ -54,12 +56,12 @@
 // below, driven by runners/muse-serve-session.ts) — that traffic is the
 // observation, so the session-boundary refresh hook
 // (`refreshMuseCapacityAfterSession` in coordinator/muse-spawn.ts) is the
-// final `usage/read` that populates 5H/1W. No synthetic model prompt is
-// ever issued to refresh capacity. When the serve execution lane cannot
-// admit a turn (host unavailable, unimplemented method, auth), the session
-// falls back to the legacy `muse exec` subprocess before any model work
-// starts — the host stays unobserved and the read stays honest N/A with
-// last-good rows preserved.
+// final `usage/read` that populates 5H/1W. If no genuine turn has populated
+// a complete current pair for an hour, `muse-probe.ts` may use its own host
+// for the bounded paid fallback. When the normal serve execution lane cannot
+// admit a developer turn, that session still falls back to the legacy
+// `muse exec` subprocess before any model work starts; last-good capacity
+// rows remain preserved.
 //
 // PRODUCT DECISION (2026-09-26, resolved via human_action on this ticket):
 // the runner migration is in scope for NOT-270, in this same PR, not a
@@ -85,13 +87,32 @@
 //   shell restriction) is unaffected.
 // This question was escalated twice on this ticket (product_scope_decision,
 // resolved both times); the decision above is final for NOT-270's scope.
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { MUSE_CLI_ENV, resolveMuseAuthFile, resolveMuseBin } from "../cli-env.js";
+import { getDataDir } from "../db/index.js";
+import { parseMuseVersion } from "../adapters/muse-capability.js";
 import { buildMuseDeveloperSettings } from "../runners/muse-code-settings.js";
 import { MSP_USAGE_CHANGED, MUSE_CLIENT_INFO, MUSE_SERVE_ARGV, assertMuseExecMethod, assertMuseReadOnlyMethod, hasMuseCredential, ingestMuseUsagePayload, museCapacityTimeoutMs, museClassifyRpcError, museEvidenceRef, museRefreshThrottleMs, museUuidv7, noteMuseCapacityFailure, parseMuseRpcLine, } from "./muse.js";
+function readResolvedMuseVersion() {
+    return new Promise((resolve) => {
+        execFile(resolveMuseBin(), ["--version"], { encoding: "utf8", timeout: 30_000, env: { ...process.env, ...MUSE_CLI_ENV } }, (err, stdout) => resolve(err ? null : parseMuseVersion(stdout)));
+    });
+}
+/**
+ * NOT-273: dedicated cwd for the coordinator-owned `muse serve` child.
+ * The spawn must never inherit the server process's ambient working
+ * directory (in a maintainer's `npm run dev` checkout that is the repo
+ * itself, where a stray `git add . && git commit` in the child would land
+ * real commits on the checkout). Created if missing.
+ */
+export function resolveMuseHostCwd() {
+    const dir = path.join(getDataDir(), "capacity", "muse-host-home");
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 /**
  * NOT-270 serve lane: the owned host must run workers under the same
  * posture as the exec lane's per-attempt settings — no MCP servers, no
@@ -128,6 +149,8 @@ export function prepareMuseServeHome(ambientAuthFile = resolveMuseAuthFile()) {
     }
     return { configHome, dataHome, authLinked };
 }
+const KEYCHAIN_UNREADABLE_RE = /keychain item .* unreadable|OSStatus\s+-?\d+/i;
+const AUTH_FAILURE_RE = /credential|auth|login|sign[ -]?in|\b401\b|\b403\b/i;
 function readOnlyRequest(id, method, params) {
     assertMuseReadOnlyMethod(method);
     return `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
@@ -167,6 +190,14 @@ export class MuseCapacityHost {
     observedOnConnection = false;
     /** Increments on every spawn — tests use it to prove host reuse/restart. */
     connectionEpoch = 0;
+    /**
+     * NOT-277: the Muse version the live child runs — the on-disk binary's reported version, read
+     * immediately before the spawn and again after the handshake; null when unknown or when the
+     * binary changed across the spawn. A long-lived host keeps running the build it started on
+     * after an auto-update, so developer work only uses it when this is the capability-checked
+     * version (see `ensureStartedOnVersion`).
+     */
+    runningVersion = null;
     /**
      * Server-owned XDG home for the host (worker settings + auth link).
      * Built lazily on first spawn, reused across restarts, removed on
@@ -237,6 +268,7 @@ export class MuseCapacityHost {
         const child = this.child;
         this.child = null;
         this.dead = true;
+        this.runningVersion = null;
         for (const [, p] of this.pending) {
             try {
                 p.resolve({});
@@ -453,24 +485,51 @@ export class MuseCapacityHost {
             this.starting = null;
         }
     }
+    /**
+     * NOT-277: start (or reuse) the host, and report whether it runs `version`. A live host on any
+     * other (or an unknown) version is restarted onto the current on-disk binary when it is idle;
+     * while real turns are using it, it is left alone and this returns false (the caller runs its
+     * work on the exec lane instead). Never true for a host not known to run `version`.
+     */
+    async ensureStartedOnVersion(version) {
+        if (!(await this.ensureStarted()))
+            return false;
+        if (this.runningVersion === version)
+            return true;
+        if (this.hasInflightExecution() || this.inflightRead)
+            return false;
+        this.killChild();
+        if (!(await this.ensureStarted()))
+            return false;
+        return this.runningVersion === version;
+    }
     async start() {
         this.killChild();
+        const readVersion = this.opts.readVersion ?? (this.opts.command ? async () => null : readResolvedMuseVersion);
+        const versionBefore = await readVersion();
         const timeoutMs = this.opts.timeoutMs ?? museCapacityTimeoutMs();
         const mergedEnv = this.mergedEnv();
         if (!hasMuseCredential(mergedEnv, this.opts.authFilePath ?? resolveMuseAuthFile())) {
+            this.startFailure = "credential_missing";
             return false;
         }
         const command = this.opts.command ?? resolveMuseBin();
         const args = this.opts.args ?? [...MUSE_SERVE_ARGV];
         let child;
         try {
-            child = spawn(command, args, {
+            // NOT-273: explicit cwd — never inherit the server process's ambient
+            // working directory (which in dev is the repo checkout itself).
+            const cwd = this.opts.cwd ?? resolveMuseHostCwd();
+            const spawnFn = this.opts.spawnImpl ?? spawn;
+            child = spawnFn(command, args, {
+                cwd,
                 stdio: ["pipe", "pipe", "pipe"],
                 env: { ...mergedEnv, ...MUSE_CLI_ENV },
             });
         }
         catch (err) {
-            this.startFailure = err?.code === "ENOENT" ? "unsupported" : null;
+            this.startFailure =
+                err?.code === "ENOENT" ? "binary_missing" : "spawn_failed";
             return false;
         }
         this.child = child;
@@ -505,14 +564,17 @@ export class MuseCapacityHost {
                     return;
             }
         });
-        child.on("error", () => {
+        child.on("error", (err) => {
             if (!this.isCurrentChild(child))
                 return;
+            this.startFailure =
+                err?.code === "ENOENT" ? "binary_missing" : "spawn_failed";
             this.killChild();
         });
         child.stdin?.on("error", () => {
             if (!this.isCurrentChild(child))
                 return;
+            this.startFailure = "transport_error";
             this.killChild();
         });
         child.on("close", () => {
@@ -521,6 +583,15 @@ export class MuseCapacityHost {
             // its replacement must not kill the new host.
             if (!this.isCurrentChild(child))
                 return;
+            if (KEYCHAIN_UNREADABLE_RE.test(this.stderrTail)) {
+                this.startFailure = "keychain_unreadable";
+            }
+            else if (AUTH_FAILURE_RE.test(this.stderrTail)) {
+                this.startFailure = "auth_rejected";
+            }
+            else if (this.startFailure === null) {
+                this.startFailure = "host_exited";
+            }
             this.killChild();
         });
         const initId = `muse-capacity-init-${this.connectionEpoch}`;
@@ -529,7 +600,14 @@ export class MuseCapacityHost {
             if (init?.error) {
                 const kind = museClassifyRpcError(init.error);
                 this.startFailure =
-                    kind === "auth" ? "auth" : kind === "unsupported" ? "unsupported" : null;
+                    kind === "auth"
+                        ? "auth_rejected"
+                        : kind === "unsupported"
+                            ? "unsupported"
+                            : "handshake_rejected";
+            }
+            else if (this.startFailure === null) {
+                this.startFailure = this.dead ? "host_exited" : "handshake_timeout";
             }
             this.killChild();
             return false;
@@ -541,6 +619,11 @@ export class MuseCapacityHost {
             this.killChild();
             return false;
         }
+        // The spawned build is the on-disk one only if the binary did not change across the spawn.
+        const versionAfter = await readVersion();
+        if (this.isCurrentChild(child)) {
+            this.runningVersion = versionBefore !== null && versionBefore === versionAfter ? versionBefore : null;
+        }
         return true;
     }
     startFailure = null;
@@ -579,15 +662,20 @@ export class MuseCapacityHost {
         this.startFailure = null;
         const started = await this.ensureStarted();
         if (!started) {
-            if (this.startFailure === "unsupported") {
+            // `ensureStarted` records the failure asynchronously. TypeScript does
+            // not model that mutation across the awaited call, so widen the field
+            // back to its declared type before selecting the fallback category.
+            const diagnostic = this.startFailure ?? "spawn_failed";
+            if (diagnostic === "unsupported" || diagnostic === "binary_missing") {
+                console.error(`[muse-capacity] host start failed: ${diagnostic}`);
                 await noteMuseCapacityFailure("unsupported");
-                return { status: "failure", reason: "unsupported" };
+                return { status: "failure", reason: "unsupported", diagnostic };
             }
             // No credential, spawn failure, timeout, or bad exit before the
             // handshake: honest `missing`, last-good rows preserved.
-            console.error("[muse-capacity] host start failed: missing");
+            console.error(`[muse-capacity] host start failed: ${diagnostic}`);
             await noteMuseCapacityFailure("missing");
-            return { status: "missing" };
+            return { status: "missing", diagnostic };
         }
         this.readSeq += 1;
         const id = `muse-capacity-${this.connectionEpoch}-${this.readSeq}`;
@@ -601,23 +689,23 @@ export class MuseCapacityHost {
             if (!this.hasInflightExecution())
                 this.killChild();
             await noteMuseCapacityFailure("missing");
-            return { status: "missing" };
+            return { status: "missing", diagnostic: "read_timeout" };
         }
         if (res.error) {
             const kind = museClassifyRpcError(res.error);
             if (kind === "auth") {
                 console.error("[muse-capacity] host read failed: unauthenticated");
                 await noteMuseCapacityFailure("missing");
-                return { status: "missing" };
+                return { status: "missing", diagnostic: "auth_rejected" };
             }
             if (kind === "unsupported") {
                 console.error("[muse-capacity] host read failed: unsupported");
                 await noteMuseCapacityFailure("unsupported");
-                return { status: "failure", reason: "unsupported" };
+                return { status: "failure", reason: "unsupported", diagnostic: "unsupported" };
             }
             console.error("[muse-capacity] host read failed: malformed");
             await noteMuseCapacityFailure("unparsable");
-            return { status: "failure", reason: "unparsable" };
+            return { status: "failure", reason: "unparsable", diagnostic: "read_rejected" };
         }
         let payload = res.result;
         if (payload &&
@@ -633,7 +721,7 @@ export class MuseCapacityHost {
             // Fresh/unobserved host: `usage` omitted — honest `missing`, never a
             // write, so a newer known pair is never overwritten or deleted.
             await noteMuseCapacityFailure("missing");
-            return { status: "missing" };
+            return { status: "missing", diagnostic: "unobserved" };
         }
         return { status: "observed", written: outcome.written, skippedStale: outcome.skippedStale };
     }