agent-dealer 1.2.3 → 1.2.4

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

@@ -16,9 +16,9 @@
 //      `~/.claude.json` (this module — free, ingested on every capacity
 //      read; only that subtree is ever parsed, the rest of the config —
 //      accountUuid, email, credentials, projects — is never retained).
-//   3. One minimal bounded paid probe, only when every valid 5H/1W
-//      observation is older than 60 minutes AND the explicit opt-in
-//      `AGENT_DEALER_CLAUDE_CAPACITY_REFRESH=paid-after-1h` is set.
+//   3. One minimal bounded paid probe when every valid 5H/1W observation is
+//      older than 60 minutes. This is the default; operators can explicitly
+//      disable it with `AGENT_DEALER_CLAUDE_CAPACITY_REFRESH=off`.
 //
 // Both file sources write the same `claude_unified_five_hour` /
 // `claude_unified_seven_day` window keys through the shared
@@ -68,7 +68,7 @@
 //
 // If a live proof ever shows the minimal probe does not reliably emit 5H/1W
 // (neither in its stream nor via the cache side effect), the probe is a
-// recurring paid no-op: disable the opt-in and revise this ticket instead of
+// recurring paid no-op: disable the fallback and revise this ticket instead of
 // shipping it. The `no_windows` diagnostic below exists to make that visible.
 import { spawn } from "node:child_process";
 import fs from "node:fs";
@@ -82,9 +82,10 @@ import { configuredCapacityRuntimes } from "./service.js";
 import { CLAUDE_RUNTIME, extractClaudeCapacityFromEvents, normalizeClaudeResetsAt, recordClaudeCapacityFromEvents, recordClaudeWindowReadings, } from "./claude-events.js";
 /** Override for the Claude cache file (tests, smoke). */
 export const CLAUDE_CACHE_FILE_ENV = "AGENT_DEALER_CLAUDE_CACHE_FILE";
-/** Paid-fallback opt-in. Any value other than PAID_AFTER_1H disables probing. */
+/** Paid-fallback setting. Unset defaults to PAID_AFTER_1H; `off` disables it. */
 export const CLAUDE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_CLAUDE_CAPACITY_REFRESH";
 export const CLAUDE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+export const CLAUDE_CAPACITY_REFRESH_OFF_VALUE = "off";
 /** Upper bound for one probe spawn (ms). */
 export const CLAUDE_CAPACITY_PROBE_TIMEOUT_ENV = "AGENT_DEALER_CLAUDE_PROBE_TIMEOUT_MS";
 export const CLAUDE_PROBE_TIMEOUT_MS_DEFAULT = 90_000;
@@ -408,11 +409,16 @@ export function ingestClaudeLocalCache(nowMs = Date.now()) {
     return recordClaudeWindowReadings(result.windows, CLAUDE_RUNTIME, nowMs);
 }
 // ---------------------------------------------------------------------------
-// Paid fallback probe (explicit opt-in only)
+// Paid fallback probe (enabled by default, explicit off switch)
 // ---------------------------------------------------------------------------
-/** True only under the exact opt-in; any other value disables paid probing. */
+/**
+ * Paid probing defaults on when the setting is absent/empty. The documented
+ * `paid-after-1h` value is accepted explicitly; `off` and unrecognized values
+ * disable spending so a typo never silently changes the configured policy.
+ */
 export function isClaudePaidFallbackEnabled() {
-    return process.env[CLAUDE_CAPACITY_REFRESH_ENV] === CLAUDE_CAPACITY_REFRESH_PAID_VALUE;
+    const setting = process.env[CLAUDE_CAPACITY_REFRESH_ENV];
+    return setting === undefined || setting === "" || setting === CLAUDE_CAPACITY_REFRESH_PAID_VALUE;
 }
 /** Bounded direct spawn of `claude` — never the coordinator, never a run. */
 export function defaultProbeRunner(bin, argv, opts) {
@@ -712,8 +718,8 @@ function probeCooldownMs() {
  * On-demand paid fallback: when `claude_code` is configured and no valid
  * 5H/1W observation is newer than 60 minutes, run one minimal bounded probe
  * (single-flight across concurrent readers; at most one attempt per account
- * per 60 minutes, backing off exponentially on failure). Disabled is a
- * strict no-op — no spawn, no spend. Never throws, never touches Dealer
+ * per 60 minutes, backing off exponentially on failure). Explicitly disabled
+ * is a strict no-op — no spawn, no spend. Never throws, never touches Dealer
  * workflow/session state or `runtime_availability`.
  */
 export async function maybeProbeClaudeCapacity(nowMs = Date.now(), opts = {}) {

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

@@ -263,12 +263,16 @@ 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("paid fallback 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" });
@@ -276,8 +280,8 @@ test("disabled fallback never spawns: every non-opt-in value is a strict no-op",
     process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
     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("default-on fallback suppresses a fresh sample; stale data triggers exactly one", async () => {
+    delete process.env[CLAUDE_CAPACITY_REFRESH_ENV];
     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);

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
@@ -128,6 +130,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`;
@@ -458,6 +462,7 @@ export class MuseCapacityHost {
         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();
@@ -470,7 +475,8 @@ export class MuseCapacityHost {
             });
         }
         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 +511,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 +530,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 +547,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;
@@ -579,15 +604,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 +631,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 +663,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 };
     }

package/bundle/server/dist/capacity/muse-lifecycle.test.js

@@ -14,8 +14,7 @@
 // - the first observation arrives as a `usage/changed` notification;
 // - a fresh/unobserved host reads `missing` (restart is fresh — the client
 //   holds no cross-process usage state);
-// - resume/turn methods are refused before write, so refresh can never
-//   manufacture a billable call.
+// - resume/turn methods are refused before write on the free adapter path.
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { assertMuseReadOnlyMethod, museUsageToReadings, readMuseCapacity, requestMuseUsage, } from "./muse.js";
@@ -90,7 +89,7 @@ test("lifecycle: a fresh host with no observation reads missing — twice", asyn
         assert.equal(result.unavailable[0].reason, "missing");
     }
 });
-test("lifecycle: refresh can never manufacture a session, turn, or prompt", () => {
+test("lifecycle: the free read adapter cannot manufacture a session, turn, or prompt", () => {
     for (const m of ["session/start", "session/resume", "session/prompt", "turn/start", "exec"]) {
         assert.throws(() => assertMuseReadOnlyMethod(m), /refusing non-read method/);
     }

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

@@ -0,0 +1,250 @@
+// packages/server/src/capacity/muse-probe.ts
+//
+// Reliable Muse 5H/1W fallback. Muse's stable protocol only exposes
+// subscription capacity after the same `muse serve` process has observed
+// real provider traffic. A read-only poll, session resume, or exec log cannot
+// populate it (NOT-269). When the free sources have no complete current pair
+// for one hour, this module runs one tiny bounded turn on a dedicated owned
+// host, then performs `usage/read` on that exact host.
+//
+// The fallback is default-on and can be disabled with
+// `AGENT_DEALER_MUSE_CAPACITY_REFRESH=off`. It is single-flight, attempted at
+// most once per hour, and backs off 1h -> 2h -> 4h -> 8h after failures. The
+// host disables shell and workspace writes and keeps restricted network;
+// Muse 1.4's serve protocol has no per-turn max-step or disable-web-tools
+// switch, so the fixed one-word prompt plus wall-clock cancellation is the
+// tightest supported bound. No transcript, prompt, credential, or account
+// payload is logged.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { MUSE_CODE_CONTRIBUTOR_MODEL } from "@agent-dealer/shared";
+import { getDataDir } from "../db/index.js";
+import { listCapacitySnapshots } from "../repository/runtime-capacity.js";
+import { runMuseServeTurn } from "../runners/muse-serve-session.js";
+import { configuredCapacityRuntimes } from "./service.js";
+import { maybeRefreshMuseCapacityFromHost, MuseCapacityHost, } from "./muse-host.js";
+import { MUSE_RUNTIME } from "./muse.js";
+export const MUSE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_MUSE_CAPACITY_REFRESH";
+export const MUSE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+export const MUSE_CAPACITY_REFRESH_OFF_VALUE = "off";
+export const MUSE_CAPACITY_PROBE_TIMEOUT_ENV = "AGENT_DEALER_MUSE_CAPACITY_PROBE_TIMEOUT_MS";
+export const MUSE_CAPACITY_PROBE_TIMEOUT_MS_DEFAULT = 60_000;
+export const MUSE_CAPACITY_PROBE_STALE_AFTER_MS = 60 * 60 * 1000;
+export const MUSE_CAPACITY_PROBE_ATTEMPT_COOLDOWN_MS = 60 * 60 * 1000;
+export const MUSE_CAPACITY_PROBE_BACKOFF_CAP_MS = 8 * 60 * 60 * 1000;
+export const MUSE_CAPACITY_PROBE_PROMPT = "Reply with exactly: OK";
+export const MUSE_CAPACITY_PROBE_SERVE_ARGV = [
+    "serve",
+    "--sandbox-network",
+    "restricted",
+    "--disable-write",
+    "--disable-shell",
+];
+export function isMusePaidFallbackEnabled() {
+    const setting = process.env[MUSE_CAPACITY_REFRESH_ENV];
+    if (setting === MUSE_CAPACITY_REFRESH_PAID_VALUE)
+        return true;
+    if (setting !== undefined && setting !== "")
+        return false;
+    // Backward compatibility: this older switch used to disable every Muse
+    // capacity refresh. Do not turn an existing no-refresh deployment into a
+    // spender on upgrade. An explicit paid-after-1h above may override it.
+    if (process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS === "off")
+        return false;
+    return true;
+}
+export function museCapacityProbeTimeoutMs() {
+    const raw = process.env[MUSE_CAPACITY_PROBE_TIMEOUT_ENV];
+    if (raw !== undefined && raw !== "") {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return MUSE_CAPACITY_PROBE_TIMEOUT_MS_DEFAULT;
+}
+function validRoleObservedAtMs(role, nowMs) {
+    const row = listCapacitySnapshots(MUSE_RUNTIME).find((w) => w.criticalRole === role);
+    if (!row || row.remainingPercent === null || row.unavailableReason !== null || row.source === "unavailable") {
+        return null;
+    }
+    const observedMs = Date.parse(row.observedAt);
+    if (!Number.isFinite(observedMs) || observedMs > nowMs)
+        return null;
+    if (row.resetAt !== null) {
+        const resetMs = Date.parse(row.resetAt);
+        if (!Number.isFinite(resetMs) || resetMs <= nowMs)
+            return null;
+    }
+    return observedMs;
+}
+/** Both halves must be valid and under one hour old. A fresh 5H window may
+ * never hide a missing/stale 1W sibling (or vice versa). */
+export function hasFreshMuseCapacityPair(nowMs = Date.now()) {
+    const fiveHour = validRoleObservedAtMs("five_hour", nowMs);
+    const weekly = validRoleObservedAtMs("weekly", nowMs);
+    return (fiveHour !== null &&
+        weekly !== null &&
+        nowMs - fiveHour < MUSE_CAPACITY_PROBE_STALE_AFTER_MS &&
+        nowMs - weekly < MUSE_CAPACITY_PROBE_STALE_AFTER_MS);
+}
+function museProbeDiagnosticLogPath() {
+    return path.join(getDataDir(), "capacity", "muse-probe.log");
+}
+function appendMuseProbeDiagnostic(nowMs, result) {
+    try {
+        const file = museProbeDiagnosticLogPath();
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({
+            ts: new Date(nowMs).toISOString(),
+            event: "muse_capacity_probe",
+            trigger: "stale_60m",
+            model: MUSE_CODE_CONTRIBUTOR_MODEL,
+            ...result,
+        })}\n`);
+    }
+    catch {
+        // Diagnostics are advisory; capacity refresh must never fail on logging.
+    }
+}
+/** One bounded real turn followed by a read on the same restricted host. */
+export async function runMuseCapacityProbe(nowMs = Date.now(), opts = {}) {
+    const startedRealMs = Date.now();
+    const timeoutMs = opts.timeoutMs ?? museCapacityProbeTimeoutMs();
+    const ownsHost = opts.host === undefined;
+    const host = opts.host ??
+        new MuseCapacityHost({
+            ...opts.hostOptions,
+            args: opts.hostOptions?.args ?? [...MUSE_CAPACITY_PROBE_SERVE_ARGV],
+            timeoutMs: Math.min(opts.hostOptions?.timeoutMs ?? timeoutMs, timeoutMs),
+        });
+    let result;
+    try {
+        const turn = await runMuseServeTurn({
+            host,
+            prompt: MUSE_CAPACITY_PROBE_PROMPT,
+            model: MUSE_CODE_CONTRIBUTOR_MODEL,
+            cwd: os.tmpdir(),
+            timeoutMs,
+            rpcTimeoutMs: Math.min(15_000, timeoutMs),
+        });
+        if (!turn.admitted) {
+            result = {
+                ok: false,
+                admitted: false,
+                terminal: null,
+                failureKind: "unadmitted",
+                windowsUpdated: [],
+                durationMs: Date.now() - startedRealMs,
+            };
+        }
+        else {
+            await host.readUsage();
+            const checkNowMs = Math.max(nowMs, Date.now());
+            const ok = hasFreshMuseCapacityPair(checkNowMs);
+            result = {
+                ok,
+                admitted: true,
+                terminal: turn.terminal,
+                failureKind: ok
+                    ? null
+                    : turn.timedOut
+                        ? "timeout"
+                        : turn.failure !== null
+                            ? "turn_failed"
+                            : "no_windows",
+                windowsUpdated: ok ? ["rolling_all_models", "weekly_all_models"] : [],
+                durationMs: Date.now() - startedRealMs,
+            };
+        }
+    }
+    catch {
+        result = {
+            ok: false,
+            admitted: false,
+            terminal: null,
+            failureKind: "exception",
+            windowsUpdated: [],
+            durationMs: Date.now() - startedRealMs,
+        };
+    }
+    finally {
+        if (ownsHost)
+            await host.shutdown().catch(() => undefined);
+    }
+    appendMuseProbeDiagnostic(nowMs, result);
+    const outcome = result.ok ? "ok" : `failed: ${result.failureKind ?? "unknown"}`;
+    console.error(`[muse-capacity] fallback ${outcome}`);
+    return result;
+}
+let museProbeInFlight = null;
+let lastMuseProbeAttemptMs = 0;
+let consecutiveMuseProbeFailures = 0;
+function museProbeCooldownMs() {
+    const shift = Math.min(consecutiveMuseProbeFailures, 3);
+    return Math.min(MUSE_CAPACITY_PROBE_ATTEMPT_COOLDOWN_MS * 2 ** shift, MUSE_CAPACITY_PROBE_BACKOFF_CAP_MS);
+}
+export function resetMuseCapacityProbeStateForTests() {
+    museProbeInFlight = null;
+    lastMuseProbeAttemptMs = 0;
+    consecutiveMuseProbeFailures = 0;
+}
+export async function maybeProbeMuseCapacity(nowMs = Date.now(), opts = {}) {
+    try {
+        if (!isMusePaidFallbackEnabled())
+            return { probed: false, reason: "disabled" };
+        if (!configuredCapacityRuntimes().includes(MUSE_RUNTIME)) {
+            return { probed: false, reason: "unconfigured" };
+        }
+        if (hasFreshMuseCapacityPair(nowMs))
+            return { probed: false, reason: "fresh" };
+        if (museProbeInFlight) {
+            const shared = await museProbeInFlight;
+            return {
+                probed: true,
+                reason: "shared",
+                ok: shared.ok,
+                failureKind: shared.failureKind,
+                windowsUpdated: shared.windowsUpdated,
+            };
+        }
+        if (nowMs - lastMuseProbeAttemptMs < museProbeCooldownMs()) {
+            return { probed: false, reason: "backoff" };
+        }
+        lastMuseProbeAttemptMs = nowMs;
+        const run = runMuseCapacityProbe(nowMs, opts);
+        museProbeInFlight = run;
+        try {
+            const result = await run;
+            consecutiveMuseProbeFailures = result.ok ? 0 : consecutiveMuseProbeFailures + 1;
+            return {
+                probed: true,
+                reason: "completed",
+                ok: result.ok,
+                failureKind: result.failureKind,
+                windowsUpdated: result.windowsUpdated,
+            };
+        }
+        finally {
+            if (museProbeInFlight === run)
+                museProbeInFlight = null;
+        }
+    }
+    catch {
+        return { probed: false, reason: "error" };
+    }
+}
+/** Free read first; only a still-missing/stale complete pair reaches the
+ * bounded paid fallback. Route callers run this in the background. */
+export async function refreshMuseCapacityIfStale(nowMs = Date.now(), opts = {}) {
+    if (!configuredCapacityRuntimes().includes(MUSE_RUNTIME)) {
+        return { probed: false, reason: "unconfigured" };
+    }
+    try {
+        await maybeRefreshMuseCapacityFromHost({}, nowMs);
+    }
+    catch {
+        // The paid gate below still decides from durable last-good rows.
+    }
+    return maybeProbeMuseCapacity(nowMs, opts);
+}

package/bundle/server/dist/capacity/muse-probe.test.js

@@ -0,0 +1,183 @@
+// Default-on one-hour Muse capacity fallback. Fake MSP host only: no live
+// provider request and no paid model call in this suite.
+import { beforeEach, test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-probe-"));
+import { MuseCapacityHost } from "./muse-host.js";
+import { hasFreshMuseCapacityPair, isMusePaidFallbackEnabled, maybeProbeMuseCapacity, MUSE_CAPACITY_PROBE_SERVE_ARGV, MUSE_CAPACITY_REFRESH_ENV, resetMuseCapacityProbeStateForTests, runMuseCapacityProbe, } from "./muse-probe.js";
+import { ingestMuseUsagePayload } from "./muse.js";
+const { migrate } = await import("../db/index.js");
+const { createAgent } = await import("../repository/agents.js");
+const { clearAllCapacitySnapshots, listCapacitySnapshots } = await import("../repository/runtime-capacity.js");
+const FAKE = new URL("./fixtures/fake-muse-serve.mjs", import.meta.url).pathname;
+function hostOpts(mode, extraEnv = {}) {
+    const now = Date.now();
+    return {
+        command: process.execPath,
+        args: [FAKE],
+        env: {
+            META_API_KEY: "test-fake-key",
+            FAKE_MSP_MODE: mode,
+            FAKE_MSP_NOW_MS: String(now),
+            ...extraEnv,
+        },
+        timeoutMs: 10_000,
+    };
+}
+function payload(nowMs, roles = "both") {
+    return {
+        usage: {
+            observedAtMs: nowMs,
+            tier: "synthetic",
+            window: {
+                usedPercent: 25,
+                resetsAtMs: nowMs + 2 * 3600_000,
+                windowDurationMins: 300,
+            },
+            ...(roles === "both"
+                ? { weekly: { usedPercent: 40, resetsAtMs: nowMs + 3 * 24 * 3600_000 } }
+                : {}),
+        },
+    };
+}
+function recordedMethods(file) {
+    if (!fs.existsSync(file))
+        return [];
+    return fs
+        .readFileSync(file, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => String(JSON.parse(line).method ?? ""));
+}
+beforeEach(() => {
+    migrate();
+    clearAllCapacitySnapshots();
+    resetMuseCapacityProbeStateForTests();
+    delete process.env[MUSE_CAPACITY_REFRESH_ENV];
+    delete process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS;
+    const existing = createAgent({
+        name: `muse-probe-${Date.now()}-${Math.random()}`,
+        runtime: "muse_code",
+        deckId: "33333333-3333-4333-8333-333333333333",
+    });
+    assert.equal(existing.runtime, "muse_code");
+});
+test("fallback defaults on; explicit off and unrecognized values disable spending", async () => {
+    for (const value of [undefined, "", "paid-after-1h"]) {
+        if (value === undefined)
+            delete process.env[MUSE_CAPACITY_REFRESH_ENV];
+        else
+            process.env[MUSE_CAPACITY_REFRESH_ENV] = value;
+        assert.equal(isMusePaidFallbackEnabled(), true);
+    }
+    for (const value of ["off", "auto", "paid-after-1h "]) {
+        process.env[MUSE_CAPACITY_REFRESH_ENV] = value;
+        assert.equal(isMusePaidFallbackEnabled(), false);
+        assert.deepEqual(await maybeProbeMuseCapacity(Date.now()), {
+            probed: false,
+            reason: "disabled",
+        });
+    }
+});
+test("legacy refresh off remains no-spend unless paid fallback is explicitly enabled", () => {
+    process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS = "off";
+    delete process.env[MUSE_CAPACITY_REFRESH_ENV];
+    assert.equal(isMusePaidFallbackEnabled(), false);
+    process.env[MUSE_CAPACITY_REFRESH_ENV] = "paid-after-1h";
+    assert.equal(isMusePaidFallbackEnabled(), true);
+});
+test("a complete pair under one hour suppresses the fallback", async () => {
+    const now = Date.now();
+    await ingestMuseUsagePayload(payload(now - 59 * 60_000));
+    assert.equal(hasFreshMuseCapacityPair(now), true);
+    assert.deepEqual(await maybeProbeMuseCapacity(now), { probed: false, reason: "fresh" });
+});
+test("one missing half triggers one minimal turn and stores exactly 5H plus 1W", async () => {
+    const now = Date.now();
+    await ingestMuseUsagePayload(payload(now - 5 * 60_000, "five_hour"));
+    assert.equal(hasFreshMuseCapacityPair(now), false, "a fresh half is not a complete pair");
+    const host = new MuseCapacityHost(hostOpts("serve-turn-full"));
+    try {
+        const outcome = await maybeProbeMuseCapacity(now, { host, timeoutMs: 10_000 });
+        assert.equal(outcome.probed, true);
+        assert.equal(outcome.reason, "completed");
+        assert.equal(outcome.ok, true);
+        assert.deepEqual(outcome.windowsUpdated?.sort(), ["rolling_all_models", "weekly_all_models"]);
+        const roles = listCapacitySnapshots("muse_code")
+            .filter((w) => w.criticalRole !== null)
+            .map((w) => w.criticalRole)
+            .sort();
+        assert.deepEqual(roles, ["five_hour", "weekly"]);
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("concurrent stale readers single-flight one turn", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-probe-record-"));
+    const record = path.join(dir, "methods.jsonl");
+    const host = new MuseCapacityHost(hostOpts("serve-turn-full", { FAKE_MSP_RECORD: record }));
+    try {
+        const now = Date.now();
+        const outcomes = await Promise.all(Array.from({ length: 5 }, () => maybeProbeMuseCapacity(now, { host, timeoutMs: 10_000 })));
+        assert.equal(outcomes.filter((o) => o.reason === "completed").length, 1);
+        assert.equal(outcomes.filter((o) => o.reason === "shared").length, 4);
+        assert.ok(outcomes.every((o) => o.probed && o.ok));
+        assert.equal(recordedMethods(record).filter((m) => m === "turn/start").length, 1);
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("failed admission preserves rows and enters hourly backoff", async () => {
+    const now = Date.now();
+    await ingestMuseUsagePayload(payload(now - 61 * 60_000));
+    const before = listCapacitySnapshots("muse_code").map((w) => ({
+        key: w.windowKey,
+        remaining: w.remainingPercent,
+        observedAt: w.observedAt,
+    }));
+    const host = new MuseCapacityHost(hostOpts("serve-turn-rejected"));
+    try {
+        const first = await maybeProbeMuseCapacity(now, { host, timeoutMs: 10_000 });
+        assert.equal(first.probed, true);
+        assert.equal(first.ok, false);
+        assert.equal(first.failureKind, "unadmitted");
+        assert.deepEqual(await maybeProbeMuseCapacity(now + 60_000, { host, timeoutMs: 10_000 }), {
+            probed: false,
+            reason: "backoff",
+        });
+        assert.deepEqual(listCapacitySnapshots("muse_code").map((w) => ({
+            key: w.windowKey,
+            remaining: w.remainingPercent,
+            observedAt: w.observedAt,
+        })), before);
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("production probe host disables shell/write and keeps restricted network", () => {
+    assert.deepEqual([...MUSE_CAPACITY_PROBE_SERVE_ARGV], [
+        "serve",
+        "--sandbox-network",
+        "restricted",
+        "--disable-write",
+        "--disable-shell",
+    ]);
+});
+test("direct probe success requires the complete pair", async () => {
+    const host = new MuseCapacityHost(hostOpts("serve-turn-full"));
+    try {
+        const result = await runMuseCapacityProbe(Date.now(), { host, timeoutMs: 10_000 });
+        assert.equal(result.ok, true);
+        assert.equal(result.admitted, true);
+        assert.equal(result.failureKind, null);
+    }
+    finally {
+        await host.shutdown();
+    }
+});

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

@@ -9,14 +9,15 @@
 // retired: only a host that observed the account's provider traffic can
 // answer `usage/read` / emit `usage/changed`.
 //
-// Reads observed capacity through the stable Muse Session Protocol without
-// sending a prompt and without consuming model tokens: `initialize` →
+// The free read phase reads observed capacity through the stable Muse Session
+// Protocol without sending a prompt or consuming model tokens: `initialize` →
 // `initialized` → `usage/read` on the owned host, with `usage/changed`
 // notifications ingested as received. The client enforces a read-only
 // allowlist (`initialize`, `initialized`, `usage/read`) — any other method
 // throws before it is written, so a capacity read can never start a
-// session, send a prompt, or run model work. It never touches the Keychain
-// or undocumented endpoints.
+// session, send a prompt, or run model work. The separate default-on fallback
+// in `muse-probe.ts` runs only after this phase still lacks a complete current
+// pair for an hour. Neither path touches the Keychain or undocumented endpoints.
 //
 // Stable `usage/read` shape:
 //   result: {
@@ -48,6 +49,11 @@ import fs from "node:fs";
 import { MUSE_CLI_ENV, resolveMuseAuthFile, resolveMuseBin } from "../cli-env.js";
 import { normalizeAdapterWindow, normalizeUnavailableWindow, } from "./adapter.js";
 export const MUSE_RUNTIME = "muse_code";
+/** Muse observations remain the last-known current value until the one-hour
+ * fallback boundary. This avoids the shared adapter's generic 15-minute N/A
+ * gap before a bounded refresh is eligible to run. */
+export const MUSE_CAPACITY_STALE_AFTER_MS = 60 * 60 * 1000;
+export const MUSE_CAPACITY_EXPIRES_AFTER_MS = 60 * 60 * 1000;
 /** Methods this client may ever send. Anything else throws before write. */
 export const MSP_READ_ONLY_METHODS = ["initialize", "initialized", "usage/read"];
 /**
@@ -189,6 +195,8 @@ function windowReadingFromEntry(kind, entry, observedAt) {
         usedPercent,
         resetAt,
         observedAt,
+        staleAfterMs: MUSE_CAPACITY_STALE_AFTER_MS,
+        expiresAfterMs: MUSE_CAPACITY_EXPIRES_AFTER_MS,
         source: "supported_protocol",
         // Muse reports exactly this one rolling/weekly pair — it is always the
         // account-wide critical window, never a model-specific extra.
@@ -868,8 +876,10 @@ export function createMuseCapacityAdapter(opts = {}) {
 export const MUSE_REFRESH_THROTTLE_MS_DEFAULT = 5 * 60 * 1000;
 /**
  * Throttle bound for production refreshes. Override with
- * `AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS` (milliseconds); `off` disables
- * refresh entirely. Non-positive or unparsable values fall back to the default.
+ * `AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS` (milliseconds); `off` disables the
+ * free host read and, for backward-compatible no-spend behavior, also disables
+ * the paid fallback unless `AGENT_DEALER_MUSE_CAPACITY_REFRESH=paid-after-1h`
+ * is explicit. Non-positive or unparsable values fall back to the default.
  * Shared with the owned host (`./muse-host.js`).
  */
 export function museRefreshThrottleMs() {

package/bundle/server/dist/routes/index.js

@@ -8,7 +8,7 @@ import { getLinearUsageSnapshot } from "../adapters/linear-graphql.js";
 import { listRuntimeModels } from "../runners/models.js";
 import { configuredCapacityRuntimes, getRuntimeCapacitySnapshot } from "../capacity/service.js";
 import { refreshClaudeCapacityIfStale } from "../capacity/claude-local-cache.js";
-import { maybeRefreshMuseCapacityFromHost } from "../capacity/muse-host.js";
+import { refreshMuseCapacityIfStale } from "../capacity/muse-probe.js";
 import { refreshCodexCapacityIfStale } from "../capacity/codex-app-server.js";
 import { getCursorTeamBillingSnapshot, refreshCursorTeamBillingIfStale, } from "../capacity/cursor-team.js";
 import { getCursorIndividualBillingSnapshot, refreshCursorIndividualBillingIfStale, refreshCursorIndividualCapacityIfStale, } from "../capacity/cursor-individual.js";
@@ -63,13 +63,12 @@ export async function registerRoutes(app) {
     // NOT-245: provider-neutral capacity read model — one entry per configured
     // runtime account with its windows, freshness, and explicit unavailable
     // reasons. Normalized snapshots only; evidence stays server-side.
-    // NOT-270: the only production trigger for Muse capacity — a throttled
-    // (default 5 min), bounded, best-effort refresh through the server-owned
-    // long-lived `muse serve` host when `muse_code` is configured. The
-    // refresh runs in the background without blocking the read: GET serves
-    // the last-known snapshot immediately so a slow or hanging host (bounded
-    // by the capacity timeout) can never stall the Agents page. Failures
-    // preserve last-good rows as N/A and never fail the read.
+    // Muse capacity: first take the free throttled read from the server-owned
+    // execution host. If there is still no complete observation under an hour
+    // old, the default-on bounded fallback runs one minimal turn on a dedicated
+    // restricted host and reads 5H/1W from that same host. This stays in the
+    // background: GET serves last-good immediately and never waits on model
+    // work. `AGENT_DEALER_MUSE_CAPACITY_REFRESH=off` disables paid fallback.
     // NOT-246: on-demand Codex refresh — when the stored Codex snapshot is
     // stale the read triggers one bounded, non-billable App Server poll
     // (single-flight, never health rows, never throws); fresh snapshots and
@@ -79,9 +78,9 @@ export async function registerRoutes(app) {
     // Claude Code's own free cache (plain file read, never a spawn) and then
     // considers the paid probe without blocking the read: a bounded Haiku
     // probe fires at most once per hour and only under the explicit
-    // `AGENT_DEALER_CLAUDE_CAPACITY_REFRESH=paid-after-1h` opt-in when every
-    // valid 5H/1W observation is older than 60 minutes. Disabled is a strict
-    // no-op (no spawn, no spend). Failures never break the read below.
+    // valid 5H/1W observation is older than 60 minutes. This is the default;
+    // `AGENT_DEALER_CLAUDE_CAPACITY_REFRESH=off` is a strict no-op (no spawn,
+    // no spend). Failures never break the read below.
     app.get("/api/runtime-capacity", async () => {
         try {
             void refreshClaudeCapacityIfStale().catch(() => {
@@ -93,7 +92,7 @@ export async function registerRoutes(app) {
         }
         try {
             if (configuredCapacityRuntimes().includes("muse_code")) {
-                void maybeRefreshMuseCapacityFromHost().catch(() => {
+                void refreshMuseCapacityIfStale().catch(() => {
                     // Best-effort: failures preserve last-good rows via the ingest path.
                 });
             }

package/bundle/server/dist/routes/runtime-capacity.test.js

@@ -15,6 +15,12 @@ process.env.AGENT_DEALER_SKIP_AGENT_HEALTH = "1";
 // Never spawn a real provider from route tests: the on-demand Codex refresh is
 // covered against the fake App Server in codex-app-server.test.ts.
 process.env.AGENT_DEALER_CODEX_CAPACITY_REFRESH = "off";
+// Claude's paid-after-1h fallback is default-on in production. Route tests
+// exercise stored/read behavior only and must never launch a real paid probe.
+process.env.AGENT_DEALER_CLAUDE_CAPACITY_REFRESH = "off";
+// Muse's one-hour fallback is also default-on; route tests cover the free
+// host trigger only and must never run a real model turn.
+process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH = "off";
 // NOT-268: the route also ingests the real ~/.claude.json cache on every read. Point it at a
 // path that never exists so a developer's own Claude usage never leaks extra windows into the
 // fixture-controlled assertions below (this passed in CI, which has no such file, but failed
@@ -62,9 +68,10 @@ test("GET /api/runtime-capacity returns normalized entries without evidence", as
     assert.ok(!raw.includes("evidence"), "no evidence pointers leak to the browser");
     await app.close();
 });
-test("GET triggers the Muse refresh when muse_code is configured", async () => {
-    // NOT-270: the route is the only production trigger for Muse capacity
-    // (owned host). No credential here (env key removed, empty login dir),
+test("GET triggers the free Muse refresh when muse_code is configured", async () => {
+    // The route is the production trigger for Muse capacity. This suite sets
+    // the paid fallback off, so it exercises only the free owned-host read.
+    // No credential here (env key removed, empty login dir),
     // so the refresh short-circuits to a `missing` sentinel without spawning
     // anything live.
     clearAllCapacitySnapshots();

package/bundle/server/dist/runners/muse-serve-session.js

@@ -1,12 +1,13 @@
 // packages/server/src/runners/muse-serve-session.ts
 //
-// NOT-270: run a real Dealer Muse developer turn through the server-owned
-// `muse serve` host (the NOT-269 proven lifecycle). Only a host that
+// NOT-270: run a Muse turn through a caller-owned `muse serve` host (the
+// NOT-269 proven lifecycle). Only a host that
 // observes the account's provider traffic can answer `usage/read`, so the
-// observation opportunity IS the real session: `session/start` +
-// `turn/start` on the owned host, then the session-boundary `usage/read`
-// (the existing refresh hook) populates 5H/1W. No synthetic prompt is ever
-// sent — the turn below carries the genuine Dealer developer prompt.
+// observation opportunity is a `session/start` + `turn/start` on that host.
+// Production callers use this for genuine Dealer developer work and, when
+// capacity has been unavailable for an hour, the dedicated bounded capacity
+// probe. The capacity probe owns a separate restricted host and shuts it down
+// after its final `usage/read`.
 //
 // Wire contract (stable MSP, Muse 1.4.x):
 //   session/start {commandId UUIDv7, workspaceRoot, modelId, approvalMode}

package/bundle/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/server",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -22,7 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@agent-dealer/shared": "1.2.3",
+    "@agent-dealer/shared": "1.2.4",
     "@fastify/cors": "^11.0.1",
     "@fastify/static": "^8.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/bundle/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-dealer/shared",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/doctor.d.ts

@@ -23,9 +23,10 @@ export declare function describeCursorIndividualLogin(status: {
 export declare function checkCursorIndividualLogin(): Promise<CursorIndividualLoginReport>;
 /** Env override for the Claude cache file (tests/smoke). */
 export declare const CLAUDE_CAPACITY_CACHE_FILE_ENV = "AGENT_DEALER_CLAUDE_CACHE_FILE";
-/** Paid-fallback opt-in env and its only enabling value. */
+/** Paid-fallback setting: enabled by default; `off` disables it. */
 export declare const CLAUDE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_CLAUDE_CAPACITY_REFRESH";
 export declare const CLAUDE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+export declare const CLAUDE_CAPACITY_REFRESH_OFF_VALUE = "off";
 /** Which local 5H/1W cache state the capacity ladder would read. */
 export type ClaudeCapacitySourceKind = "fresh" | "stale" | "missing";
 export interface ClaudeCapacitySourceReport {
@@ -42,11 +43,25 @@ export declare function describeClaudeCapacitySource(status: {
     ageMs: number | null;
 } | null | undefined): ClaudeCapacitySourceReport;
 /**
- * Map the paid-fallback setting to an opt-in warning line, or null when the
- * probe is disabled (the quiet default — no spend possible, nothing to say).
+ * Map the paid-fallback setting to its warning line, or null when explicitly
+ * disabled (or unrecognized). Unset/empty is the paid-after-1h default.
  * Pure (no I/O): unit tests pin both states here.
  */
 export declare function describeClaudeProbeOptIn(setting: string | undefined): string | null;
+/** Paid-fallback setting: enabled by default; `off` disables it. */
+export declare const MUSE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_MUSE_CAPACITY_REFRESH";
+export declare const MUSE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+export declare const MUSE_CAPACITY_REFRESH_OFF_VALUE = "off";
+/** Legacy free-read throttle; `off` also preserves no-spend behavior when the
+ * new setting is absent. */
+export declare const MUSE_CAPACITY_REFRESH_MS_ENV = "AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS";
+/**
+ * Match the server's Muse paid-fallback precedence exactly. The explicit new
+ * paid value overrides a legacy free-refresh `off`; otherwise that legacy
+ * switch remains no-spend for backward compatibility. Unknown new values
+ * fail closed. Pure (no I/O) so doctor never risks a provider request.
+ */
+export declare function describeMuseProbeOptIn(setting: string | undefined, legacyRefreshMs: string | undefined): string | null;
 /**
  * Read the `cachedUsageUtilization.fetchedAtMs` timestamp out of Claude
  * Code's config file (override first, then `~/.claude.json`) — the same key

package/dist/doctor.js

@@ -117,6 +117,9 @@ export async function runDoctor() {
             const probe = describeClaudeProbeOptIn(process.env.AGENT_DEALER_CLAUDE_CAPACITY_REFRESH);
             if (probe)
                 console.warn(probe);
+            const museProbe = describeMuseProbeOptIn(process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH, process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS);
+            if (museProbe)
+                console.warn(museProbe);
         }
         catch {
             // Informational only: a broken probe must never fail doctor.
@@ -261,9 +264,10 @@ export async function checkCursorIndividualLogin() {
 // ---------------------------------------------------------------------------
 /** Env override for the Claude cache file (tests/smoke). */
 export const CLAUDE_CAPACITY_CACHE_FILE_ENV = "AGENT_DEALER_CLAUDE_CACHE_FILE";
-/** Paid-fallback opt-in env and its only enabling value. */
+/** Paid-fallback setting: enabled by default; `off` disables it. */
 export const CLAUDE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_CLAUDE_CAPACITY_REFRESH";
 export const CLAUDE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+export const CLAUDE_CAPACITY_REFRESH_OFF_VALUE = "off";
 /**
  * Map a cache-file presence/age probe to the doctor line. Pure (no I/O):
  * unit tests pin all three states here.
@@ -298,17 +302,42 @@ function formatCacheAge(ageMs) {
     return `${Math.floor(hours / 24)}d`;
 }
 /**
- * Map the paid-fallback setting to an opt-in warning line, or null when the
- * probe is disabled (the quiet default — no spend possible, nothing to say).
+ * Map the paid-fallback setting to its warning line, or null when explicitly
+ * disabled (or unrecognized). Unset/empty is the paid-after-1h default.
  * Pure (no I/O): unit tests pin both states here.
  */
 export function describeClaudeProbeOptIn(setting) {
-    if (setting === CLAUDE_CAPACITY_REFRESH_PAID_VALUE) {
-        return ("⚠ Claude capacity paid fallback: armed (one ≤$0.01 Haiku probe after 1h stale — " +
-            `unset ${CLAUDE_CAPACITY_REFRESH_ENV} to disable)`);
+    if (setting === undefined || setting === "" || setting === CLAUDE_CAPACITY_REFRESH_PAID_VALUE) {
+        return ("⚠ Claude capacity paid fallback: enabled (one ≤$0.01 Haiku probe after 1h stale — " +
+            `set ${CLAUDE_CAPACITY_REFRESH_ENV}=${CLAUDE_CAPACITY_REFRESH_OFF_VALUE} to disable)`);
     }
     return null;
 }
+// ---------------------------------------------------------------------------
+// Muse capacity paid-fallback reporting for doctor.
+// ---------------------------------------------------------------------------
+/** Paid-fallback setting: enabled by default; `off` disables it. */
+export const MUSE_CAPACITY_REFRESH_ENV = "AGENT_DEALER_MUSE_CAPACITY_REFRESH";
+export const MUSE_CAPACITY_REFRESH_PAID_VALUE = "paid-after-1h";
+export const MUSE_CAPACITY_REFRESH_OFF_VALUE = "off";
+/** Legacy free-read throttle; `off` also preserves no-spend behavior when the
+ * new setting is absent. */
+export const MUSE_CAPACITY_REFRESH_MS_ENV = "AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS";
+/**
+ * Match the server's Muse paid-fallback precedence exactly. The explicit new
+ * paid value overrides a legacy free-refresh `off`; otherwise that legacy
+ * switch remains no-spend for backward compatibility. Unknown new values
+ * fail closed. Pure (no I/O) so doctor never risks a provider request.
+ */
+export function describeMuseProbeOptIn(setting, legacyRefreshMs) {
+    const enabled = setting === MUSE_CAPACITY_REFRESH_PAID_VALUE ||
+        ((setting === undefined || setting === "") && legacyRefreshMs !== "off");
+    if (!enabled)
+        return null;
+    return ("⚠ Muse capacity paid fallback: enabled when Muse is configured " +
+        "(one restricted contributor-model turn after 1h stale — " +
+        `set ${MUSE_CAPACITY_REFRESH_ENV}=${MUSE_CAPACITY_REFRESH_OFF_VALUE} to disable)`);
+}
 /**
  * Read the `cachedUsageUtilization.fetchedAtMs` timestamp out of Claude
  * Code's config file (override first, then `~/.claude.json`) — the same key

package/dist/doctor.test.js

@@ -9,6 +9,7 @@ import assert from "node:assert/strict";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import Database from "better-sqlite3";
 // Local mirror of the server module's env/key contract
 // (packages/server/src/capacity/cursor-individual-credentials.ts). A static
@@ -45,7 +46,7 @@ test("fixture env/key names match the server module's live contract", async () =
     assert.equal(mod.CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV, CURSOR_INDIVIDUAL_DESKTOP_STATE_FILE_ENV);
     assert.equal(mod.CURSOR_INDIVIDUAL_HOME_ENV, CURSOR_INDIVIDUAL_HOME_ENV);
 });
-import { CLAUDE_CAPACITY_CACHE_FILE_ENV, CLAUDE_CAPACITY_REFRESH_ENV, CLAUDE_CAPACITY_REFRESH_PAID_VALUE, CURSOR_INDIVIDUAL_LOGIN_LINES, checkClaudeCapacitySource, checkCursorIndividualLogin, describeClaudeCapacitySource, describeClaudeProbeOptIn, describeCursorIndividualLogin, } from "./doctor.js";
+import { CLAUDE_CAPACITY_CACHE_FILE_ENV, CLAUDE_CAPACITY_REFRESH_ENV, CLAUDE_CAPACITY_REFRESH_PAID_VALUE, CURSOR_INDIVIDUAL_LOGIN_LINES, MUSE_CAPACITY_REFRESH_ENV, MUSE_CAPACITY_REFRESH_MS_ENV, MUSE_CAPACITY_REFRESH_PAID_VALUE, checkClaudeCapacitySource, checkCursorIndividualLogin, describeClaudeCapacitySource, describeClaudeProbeOptIn, describeCursorIndividualLogin, describeMuseProbeOptIn, } from "./doctor.js";
 const SECRET = "doctor-fixture-secret-must-never-print";
 const USER_ID = "user_doctor_fixture";
 function fixtureJwt(sub) {
@@ -188,15 +189,44 @@ test("describe maps each cache state to its static line", () => {
         assert.match(report.line, /no local 5H\/1W cache/);
     }
 });
-test("probe opt-in line appears only under the exact paid value", () => {
-    assert.equal(describeClaudeProbeOptIn(undefined), null);
-    assert.equal(describeClaudeProbeOptIn(""), null);
+test("probe warning appears for the default and explicit paid value", () => {
+    for (const setting of [undefined, "", CLAUDE_CAPACITY_REFRESH_PAID_VALUE]) {
+        const armed = describeClaudeProbeOptIn(setting);
+        assert.ok(armed);
+        assert.match(armed, /enabled/);
+        assert.match(armed, /≤\$0\.01/);
+        assert.match(armed, /=off/);
+    }
     assert.equal(describeClaudeProbeOptIn("off"), null);
     assert.equal(describeClaudeProbeOptIn("auto"), null);
-    const armed = describeClaudeProbeOptIn(CLAUDE_CAPACITY_REFRESH_PAID_VALUE);
-    assert.ok(armed);
-    assert.match(armed, /armed/);
-    assert.match(armed, /≤\$0\.01/);
+});
+test("Muse paid-fallback warning matches server defaults and legacy no-spend precedence", () => {
+    for (const setting of [undefined, "", MUSE_CAPACITY_REFRESH_PAID_VALUE]) {
+        const armed = describeMuseProbeOptIn(setting, undefined);
+        assert.ok(armed);
+        assert.match(armed, /Muse capacity paid fallback: enabled/);
+        assert.match(armed, /restricted contributor-model turn/);
+        assert.match(armed, new RegExp(`${MUSE_CAPACITY_REFRESH_ENV}=off`));
+    }
+    assert.equal(describeMuseProbeOptIn("off", undefined), null);
+    assert.equal(describeMuseProbeOptIn("auto", undefined), null);
+    assert.equal(describeMuseProbeOptIn(undefined, "off"), null);
+    assert.equal(describeMuseProbeOptIn("", "off"), null);
+    assert.ok(describeMuseProbeOptIn(MUSE_CAPACITY_REFRESH_PAID_VALUE, "off"), "the explicit new paid value overrides the legacy free-refresh switch");
+});
+test("Muse doctor env names and paid value match the server contract", () => {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(here, "..", "..", "server", "src", "capacity", "muse-probe.ts"),
+        path.resolve(here, "..", "..", "server", "dist", "capacity", "muse-probe.js"),
+    ];
+    const src = candidates.find((file) => fs.existsSync(file));
+    assert.ok(src, "the server Muse probe module must exist for the contract pin");
+    const text = fs.readFileSync(src, "utf8");
+    assert.ok(text.includes(`"${MUSE_CAPACITY_REFRESH_ENV}"`));
+    assert.ok(text.includes(`"${MUSE_CAPACITY_REFRESH_PAID_VALUE}"`));
+    assert.ok(text.includes("AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS"));
+    assert.equal(MUSE_CAPACITY_REFRESH_MS_ENV, "AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS");
 });
 test("check reads fetchedAtMs from the config key, never mtime or the real home", async () => {
     const now = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dealer",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "description": "Human control plane for agent execution — queue, plan approval, audit",
   "license": "MIT",
   "type": "module",