agent-dealer 1.3.2 → 1.3.3

package/bundle/server/dist/adapters/agent-health.test.js

@@ -17,6 +17,8 @@ const { migrate, getDb } = await import("../db/index.js");
 const { createAgent, getAgent } = await import("../repository/agents.js");
 const { healthForAgent, runtimeIssuesUncached, githubIssuesUncached, githubIssuesSync, classifyGithubAuthStatus, clearAgentHealthCaches, setCursorProbeTimingForTests, setRunCommandForTests, } = await import("./agent-health.js");
 const { setMuseCapabilityProbeForTests, settleMuseCapabilityCheckForTests } = await import("./muse-capability.js");
+const { recordMuseUsageCap } = await import("../runners/usage-cap.js");
+const { runtimeAvailability, clearAllRuntimeAvailability, } = await import("../repository/runtime-availability.js");
 migrate();
 // NOT-277: health never runs the real (billed) Muse capability probe in tests.
 setMuseCapabilityProbeForTests(async () => ({ status: "capable" }));
@@ -441,6 +443,56 @@ The keychain item is stuck. Delete it and sign in again:
         assert.match(issues[0].message, /panic: something else broke/);
         assert.doesNotMatch(issues[0].message, /muse login/);
     });
+    // ---------------------------------------------------------------------------
+    // NOT-439: agent health renders the exact provider boundary from persisted
+    // availability — the reproduced Muse message resolves to 11:59 AM in
+    // America/Los_Angeles, not the 11:46 AM of the old 30-minute fallback.
+    // ---------------------------------------------------------------------------
+    test("NOT-439: persisted muse provider reset renders the exact boundary, not the fallback", async () => {
+        clearAllRuntimeAvailability();
+        clearAgentHealthCaches();
+        try {
+            // Pinned incident replay: the provider said resets-at 18:59:01Z while the
+            // old fallback stored 18:46:20.154Z. Timezone-safe assertions on the
+            // stored instant itself.
+            const incidentNow = Date.parse("2026-10-12T18:16:20.154Z");
+            const cap = recordMuseUsageCap({
+                kind: "usage_cap",
+                message: "Subscription quota exhausted. Your usage window resets at 2026-10-12T18:59:01Z",
+            }, incidentNow);
+            assert.equal(cap?.unavailableUntil, "2026-10-12T18:59:01.000Z");
+            const stored = runtimeAvailability("muse_code", incidentNow);
+            assert.equal(stored.available, false);
+            if (!stored.available)
+                assert.equal(stored.until, "2026-10-12T18:59:01.000Z");
+            const la = { hour: "2-digit", minute: "2-digit", timeZone: "America/Los_Angeles" };
+            assert.equal(new Date("2026-10-12T18:59:01.000Z").toLocaleTimeString("en-US", la), "11:59 AM");
+            // The superseded fallback instant renders differently, proving the
+            // assertion distinguishes the two.
+            assert.equal(new Date("2026-10-12T18:46:20.154Z").toLocaleTimeString("en-US", la), "11:46 AM");
+            // Live surface: a guaranteed-future provider reset flows verbatim from
+            // persisted availability into the usage_capped health message.
+            const future = new Date(Date.now() + 2 * 3600_000);
+            future.setMilliseconds(0);
+            const resetIso = future.toISOString();
+            const live = recordMuseUsageCap({ kind: "usage_cap", message: `Subscription quota exhausted. Resets at ${resetIso}` });
+            assert.equal(live?.unavailableUntil, resetIso);
+            const stub = stubMuse(`cat ${JSON.stringify(path.join(FIXTURES, "muse-version.txt"))}`);
+            const agent = createAgent({ name: "muse-capped", runtime: "muse_code", deckId: randomUUID() });
+            const result = await withMuseEnv({ MUSE_CLI: stub.bin, META_API_KEY: "k", configHome: emptyConfigHome() }, () => healthForAgent(agent, true, undefined, true, null, NO_GITHUB));
+            const issue = result.issues.find((i) => i.code === "usage_capped");
+            assert.ok(issue, "expected a usage_capped issue from persisted availability");
+            const expectedRendering = new Date(resetIso).toLocaleTimeString([], {
+                hour: "2-digit",
+                minute: "2-digit",
+            });
+            assert.ok(issue.message.includes(expectedRendering), `expected health message ${JSON.stringify(issue.message)} to render ${expectedRendering}`);
+        }
+        finally {
+            clearAllRuntimeAvailability();
+            clearAgentHealthCaches();
+        }
+    });
     test("a muse probe that hangs past the timeout is runtime_unknown", async () => {
         const stub = stubMuse("sleep 30");
         setCursorProbeTimingForTests({ timeoutMs: 150 });

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

@@ -5,12 +5,16 @@
 // profiles sharing one account produce one entry — each carrying whatever
 // windows the provider actually reported.
 //
-// Connection health, hard-cap availability, and remaining capacity stay
-// separate states: this service never reads `runtime_availability` and its
-// output never implies health. Only normalized snapshots leave this module —
-// evidence refs and raw provider payloads stay server-side.
+// Connection health and remaining capacity stay separate states: output never
+// implies health. Only normalized snapshots leave this module — evidence refs
+// and raw provider payloads stay server-side.
+//
+// NOT-440: an active hard cap (the same `runtime_availability` row that blocks
+// admission) rides alongside the windows as `activeCap`; stored snapshots are
+// never rewritten, and the overlay disappears with the row's lazy cleanup.
 import { isWindowKnown, Runtime as RuntimeSchema } from "@agent-dealer/shared";
 import { getDb } from "../db/index.js";
+import { activeRuntimeCap } from "../repository/runtime-availability.js";
 import { listAllCapacitySnapshots, recordCapacitySnapshots, } from "../repository/runtime-capacity.js";
 import { normalizeAdapterWindow, normalizeUnavailableWindow, } from "./adapter.js";
 /** Distinct runtimes across Agent profiles — the configured runtime accounts. */
@@ -83,6 +87,61 @@ function classifyWindow(w, nowMs) {
         known: false,
     };
 }
+const PAIR_RUNTIMES = new Set(["claude_code", "codex_local", "muse_code"]);
+const CURSOR_BILLING_WINDOW_KEY = "billing_cycle";
+/** Structured provider limit types that name a compact critical window. */
+const LIMIT_TYPE_ROLE = {
+    five_hour: "five_hour",
+    seven_day: "weekly",
+};
+/** A cap reset and a snapshot reset within this distance name the same boundary. */
+const RESET_MATCH_TOLERANCE_MS = 60_000;
+/** The compact role a stored window presents under, or null when it never renders compactly. */
+function compactRole(runtime, w) {
+    if (runtime === "cursor_local")
+        return w.windowKey === CURSOR_BILLING_WINDOW_KEY ? "billing_cycle" : null;
+    if (PAIR_RUNTIMES.has(runtime))
+        return w.criticalRole;
+    return null;
+}
+/**
+ * Which compact window an active cap exhausts: structured limit metadata
+ * first (a reported non-compact limit stays unmapped), then a tightly bounded
+ * match between the provider reset and exactly one tagged snapshot reset.
+ * A fallback-cooldown cap (no provider reset) is never matched.
+ */
+export function resolveCapWindowRole(runtime, cap, windows) {
+    if (cap.limitType !== null) {
+        const role = LIMIT_TYPE_ROLE[cap.limitType] ?? null;
+        return role !== null && PAIR_RUNTIMES.has(runtime) ? role : null;
+    }
+    if (cap.providerResetAt === null)
+        return null;
+    const capResetMs = Date.parse(cap.providerResetAt);
+    if (!Number.isFinite(capResetMs))
+        return null;
+    const matched = new Set();
+    for (const w of windows) {
+        const role = compactRole(runtime, w);
+        if (role === null || w.resetAt === null)
+            continue;
+        const resetMs = Date.parse(w.resetAt);
+        if (Number.isFinite(resetMs) && Math.abs(resetMs - capResetMs) <= RESET_MATCH_TOLERANCE_MS) {
+            matched.add(role);
+        }
+    }
+    return matched.size === 1 ? [...matched][0] : null;
+}
+function activeCapFor(runtime, windows, nowMs) {
+    const cap = activeRuntimeCap(runtime, nowMs);
+    if (cap === null)
+        return null;
+    return {
+        unavailableUntil: cap.unavailableUntil,
+        reason: cap.reason,
+        windowRole: resolveCapWindowRole(runtime, cap, windows),
+    };
+}
 /**
  * Read model for `GET /api/runtime-capacity`: every configured runtime, its
  * windows with freshness applied, and an explicit unavailable reason whenever
@@ -103,14 +162,15 @@ export function getRuntimeCapacitySnapshot(nowMs = Date.now()) {
     const entries = [...runtimes]
         .sort()
         .map((runtime) => {
-        const windows = (byRuntime.get(runtime) ?? []).map((w) => classifyWindow(w, nowMs).snapshot);
+        const raw = byRuntime.get(runtime) ?? [];
+        const windows = raw.map((w) => classifyWindow(w, nowMs).snapshot);
         const knownCount = windows.filter((w) => w.unavailableReason === null).length;
         let unavailableReason = null;
         if (knownCount === 0) {
             const first = windows.find((w) => w.unavailableReason)?.unavailableReason;
             unavailableReason = first ?? "missing";
         }
-        return { runtime, windows, unavailableReason };
+        return { runtime, windows, unavailableReason, activeCap: activeCapFor(runtime, raw, nowMs) };
     });
     return { runtimes: entries, generatedAt: new Date(nowMs).toISOString() };
 }

package/bundle/server/dist/capacity/service.test.js

@@ -219,3 +219,223 @@ test("a past reset time is never presented as current capacity", async () => {
     assert.equal(muse.windows[0].unavailableReason, "expired");
     assert.equal(muse.unavailableReason, "expired");
 });
+// NOT-440: active hard caps overlay the compact read model without rewriting
+// stored provider observations.
+const NOT440_NOW = Date.parse("2026-10-12T18:20:00.000Z");
+const NOT440_RESET = "2026-10-12T18:59:01.000Z";
+const NOT440_WEEKLY_RESET = "2026-10-16T02:00:00.000Z";
+async function seedPair(runtime, windows) {
+    const { recordCapacitySnapshots } = await import("../repository/runtime-capacity.js");
+    recordCapacitySnapshots(runtime, windows.map((w) => ({
+        windowKey: w.windowKey,
+        providerBucket: "all_models",
+        durationMinutes: w.durationMinutes ?? (w.criticalRole === "weekly" ? 10080 : 300),
+        displayLabel: w.criticalRole === "weekly" ? "1W" : "5H",
+        usedValue: 100 - w.remainingPercent,
+        usedUnit: "percent",
+        remainingPercent: w.remainingPercent,
+        resetAt: w.resetAt,
+        observedAt: "2026-10-12T18:03:00.000Z",
+        freshUntil: "2026-10-12T19:03:00.000Z",
+        expiresAt: "2026-10-12T19:03:00.000Z",
+        source: "observed_event",
+        unavailableReason: null,
+        criticalRole: w.criticalRole,
+    })));
+}
+async function seedReproducedMuse() {
+    await seedPair("muse_code", [
+        { windowKey: "five_hour", criticalRole: "five_hour", remainingPercent: 50, resetAt: NOT440_RESET },
+        { windowKey: "weekly", criticalRole: "weekly", remainingPercent: 52, resetAt: NOT440_WEEKLY_RESET },
+    ]);
+}
+function storedMuseRemaining() {
+    const rows = getDb()
+        .prepare("SELECT window_key, remaining_percent FROM runtime_capacity_snapshots WHERE runtime = 'muse_code'")
+        .all();
+    return Object.fromEntries(rows.map((r) => [r.window_key, r.remaining_percent]));
+}
+const { getDb } = await import("../db/index.js");
+const { clearAllRuntimeAvailability, recordRuntimeAvailability, runtimeAvailability } = await import("../repository/runtime-availability.js");
+const { recordMuseUsageCap } = await import("../runners/usage-cap.js");
+const { resolveCapWindowRole } = await import("./service.js");
+test("NOT-440: reproduced Muse cap maps to 5H without modifying stored snapshots", async () => {
+    clearAllCapacitySnapshots();
+    clearAllRuntimeAvailability();
+    await seedReproducedMuse();
+    assert.deepEqual(storedMuseRemaining(), { five_hour: 50, weekly: 52 });
+    recordMuseUsageCap({ kind: "usage_cap", message: `Subscription quota exhausted. Usage resets at 2026-10-12T18:59:01Z.` }, Date.parse("2026-10-12T18:16:00.000Z"));
+    const snap = getRuntimeCapacitySnapshot(NOT440_NOW);
+    const muse = snap.runtimes.find((r) => r.runtime === "muse_code");
+    assert.deepEqual(muse.activeCap, {
+        unavailableUntil: NOT440_RESET,
+        reason: muse.activeCap.reason,
+        windowRole: "five_hour",
+    });
+    assert.match(muse.activeCap.reason, /muse_code usage capped/);
+    // Windows remain the raw provider observation; the overlay is activeCap.
+    assert.equal(muse.windows.find((w) => w.criticalRole === "five_hour").remainingPercent, 50);
+    assert.equal(muse.windows.find((w) => w.criticalRole === "weekly").remainingPercent, 52);
+    assert.deepEqual(storedMuseRemaining(), { five_hour: 50, weekly: 52 });
+    // Admission/health read the same row.
+    assert.deepEqual(runtimeAvailability("muse_code", NOT440_NOW), {
+        available: false,
+        until: NOT440_RESET,
+        reason: muse.activeCap.reason,
+    });
+});
+test("NOT-440: overlay is absent at and after unavailableUntil; history is kept", async () => {
+    for (const offset of [0, 1]) {
+        clearAllCapacitySnapshots();
+        clearAllRuntimeAvailability();
+        await seedReproducedMuse();
+        recordMuseUsageCap({ kind: "usage_cap", message: `Subscription quota exhausted. Usage resets at 2026-10-12T18:59:01Z.` }, Date.parse("2026-10-12T18:16:00.000Z"));
+        const atMs = Date.parse(NOT440_RESET) + offset;
+        const snap = getRuntimeCapacitySnapshot(atMs);
+        const muse = snap.runtimes.find((r) => r.runtime === "muse_code");
+        assert.equal(muse.activeCap, null, `offset ${offset}ms`);
+        // Normal classification resumes: the 5H reset has passed, 1W is still current.
+        const fiveHour = muse.windows.find((w) => w.criticalRole === "five_hour");
+        assert.equal(fiveHour.remainingPercent, null);
+        assert.equal(fiveHour.unavailableReason, "expired");
+        assert.equal(muse.windows.find((w) => w.criticalRole === "weekly").remainingPercent, 52);
+        assert.deepEqual(storedMuseRemaining(), { five_hour: 50, weekly: 52 });
+        const capRows = getDb()
+            .prepare("SELECT COUNT(*) AS n FROM runtime_availability WHERE runtime = 'muse_code'")
+            .get();
+        assert.equal(capRows.n, 0, "lazy cleanup cleared the expired cap row");
+        assert.deepEqual(runtimeAvailability("muse_code", atMs), { available: true });
+    }
+});
+test("NOT-440: a cap with no provider reset or role stays unmapped (explicit capped)", async () => {
+    clearAllCapacitySnapshots();
+    clearAllRuntimeAvailability();
+    await seedReproducedMuse();
+    // Fallback cooldown that happens to land on the 5H reset is still not a provider boundary.
+    recordRuntimeAvailability({
+        runtime: "muse_code",
+        unavailableUntil: NOT440_RESET,
+        reason: "muse_code usage capped — usage cap",
+    });
+    const muse = getRuntimeCapacitySnapshot(NOT440_NOW).runtimes.find((r) => r.runtime === "muse_code");
+    assert.equal(muse.activeCap.windowRole, null);
+    assert.equal(muse.activeCap.unavailableUntil, NOT440_RESET);
+    assert.deepEqual(storedMuseRemaining(), { five_hour: 50, weekly: 52 });
+});
+const tagged = (windowKey, criticalRole, resetAt) => ({
+    windowKey,
+    providerBucket: "all_models",
+    durationMinutes: 300,
+    displayLabel: "5H",
+    usedValue: 50,
+    usedUnit: "percent",
+    remainingPercent: 50,
+    resetAt,
+    observedAt: "2026-10-12T18:03:00.000Z",
+    freshUntil: "2026-10-12T19:03:00.000Z",
+    expiresAt: "2026-10-12T19:03:00.000Z",
+    source: "observed_event",
+    unavailableReason: null,
+    criticalRole,
+});
+test("NOT-440: cap window role resolution per runtime (metadata first, then reset match)", () => {
+    const pair = [tagged("five_hour", "five_hour", NOT440_RESET), tagged("weekly", "weekly", NOT440_WEEKLY_RESET)];
+    const cases = [
+        {
+            name: "Claude five_hour metadata wins even without a reset match",
+            runtime: "claude_code",
+            cap: { providerResetAt: "2026-10-12T20:00:00.000Z", limitType: "five_hour" },
+            windows: pair,
+            expected: "five_hour",
+        },
+        {
+            name: "Claude seven_day metadata maps to weekly",
+            runtime: "claude_code",
+            cap: { providerResetAt: null, limitType: "seven_day" },
+            windows: pair,
+            expected: "weekly",
+        },
+        {
+            name: "Claude model-specific limit stays unmapped despite a matching weekly reset",
+            runtime: "claude_code",
+            cap: { providerResetAt: NOT440_WEEKLY_RESET, limitType: "seven_day_sonnet" },
+            windows: pair,
+            expected: null,
+        },
+        {
+            name: "Codex reset match on the weekly window",
+            runtime: "codex_local",
+            cap: { providerResetAt: NOT440_WEEKLY_RESET, limitType: null },
+            windows: pair,
+            expected: "weekly",
+        },
+        {
+            name: "Muse reset match on the 5H window (within tolerance)",
+            runtime: "muse_code",
+            cap: { providerResetAt: "2026-10-12T18:59:30.000Z", limitType: null },
+            windows: pair,
+            expected: "five_hour",
+        },
+        {
+            name: "Muse reset outside tolerance stays unmapped",
+            runtime: "muse_code",
+            cap: { providerResetAt: "2026-10-12T19:05:00.000Z", limitType: null },
+            windows: pair,
+            expected: null,
+        },
+        {
+            name: "Cursor reset match on the billing cycle",
+            runtime: "cursor_local",
+            cap: { providerResetAt: "2026-11-01T00:00:00.000Z", limitType: null },
+            windows: [tagged("billing_cycle", null, "2026-11-01T00:00:00.000Z")],
+            expected: "billing_cycle",
+        },
+        {
+            name: "Untagged diagnostic window with a matching reset never maps",
+            runtime: "muse_code",
+            cap: { providerResetAt: "2026-10-13T00:00:00.000Z", limitType: null },
+            windows: [...pair, tagged("muse_account_usage", null, "2026-10-13T00:00:00.000Z")],
+            expected: null,
+        },
+        {
+            name: "Fallback cooldown (no provider reset) never maps",
+            runtime: "codex_local",
+            cap: { providerResetAt: null, limitType: null },
+            windows: pair,
+            expected: null,
+        },
+        {
+            name: "Ambiguous reset matching both pair windows stays unmapped",
+            runtime: "codex_local",
+            cap: { providerResetAt: NOT440_RESET, limitType: null },
+            windows: [tagged("five_hour", "five_hour", NOT440_RESET), tagged("weekly", "weekly", NOT440_RESET)],
+            expected: null,
+        },
+    ];
+    for (const c of cases) {
+        assert.equal(resolveCapWindowRole(c.runtime, c.cap, c.windows), c.expected, c.name);
+    }
+});
+test("NOT-440: Claude structured rate_limit_event persists limit type and maps through the read model", async () => {
+    clearAllCapacitySnapshots();
+    clearAllRuntimeAvailability();
+    await seedPair("claude_code", [
+        { windowKey: "five_hour", criticalRole: "five_hour", remainingPercent: 40, resetAt: NOT440_RESET },
+        { windowKey: "weekly", criticalRole: "weekly", remainingPercent: 70, resetAt: NOT440_WEEKLY_RESET },
+    ]);
+    const { recordUsageCapFromEvents } = await import("../runners/usage-cap.js");
+    recordUsageCapFromEvents([
+        {
+            type: "rate_limit_event",
+            rate_limit_info: {
+                status: "rejected",
+                rateLimitType: "seven_day",
+                resetsAt: Math.floor(Date.parse(NOT440_WEEKLY_RESET) / 1000),
+            },
+        },
+    ], "claude_code", NOT440_NOW);
+    const claude = getRuntimeCapacitySnapshot(NOT440_NOW).runtimes.find((r) => r.runtime === "claude_code");
+    assert.equal(claude.activeCap.windowRole, "weekly");
+    assert.equal(claude.activeCap.unavailableUntil, NOT440_WEEKLY_RESET);
+    clearAllRuntimeAvailability();
+});

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

@@ -378,6 +378,14 @@ export function migrate() {
       );
     `);
     }
+    // NOT-440: normalized cap metadata for capacity reconciliation.
+    const runtimeAvailCols = db.prepare("PRAGMA table_info(runtime_availability)").all();
+    if (!runtimeAvailCols.some((c) => c.name === "provider_reset_at")) {
+        db.exec("ALTER TABLE runtime_availability ADD COLUMN provider_reset_at TEXT");
+    }
+    if (!runtimeAvailCols.some((c) => c.name === "limit_type")) {
+        db.exec("ALTER TABLE runtime_availability ADD COLUMN limit_type TEXT");
+    }
     // NOT-245: normalized capacity snapshots for databases created before
     // schema.sql declared the table (same upgrade-path pattern as queue_entries).
     const capacitySnapshots = db

package/bundle/server/dist/db/schema.sql

@@ -473,7 +473,11 @@ CREATE TABLE IF NOT EXISTS runtime_availability (
   unavailable_until TEXT NOT NULL,
   reason TEXT NOT NULL,
   evidence_json TEXT,
-  observed_at TEXT NOT NULL
+  observed_at TEXT NOT NULL,
+  -- NOT-440: provider-reported reset (null when unavailable_until is the
+  -- fallback cooldown) and structured provider limit type, if any.
+  provider_reset_at TEXT,
+  limit_type TEXT
 );
 
 -- NOT-171: append-only normalized failure-cause evidence. A derived view over

package/bundle/server/dist/repository/runtime-availability.js

@@ -2,19 +2,23 @@
 //
 // NOT-111: durable per-runtime (account-level) usage-cap state. Runners write when they
 // observe a hard cap; coordinator and queue admission read via runtimeAvailability().
+// NOT-440: the capacity read model reads the same row via activeRuntimeCap().
 import { getDb } from "../db/index.js";
 /** Upsert the latest cap observation for a runtime (one row per runtime). */
 export function recordRuntimeAvailability(input) {
     const now = new Date().toISOString();
     getDb()
         .prepare(`
-      INSERT INTO runtime_availability (runtime, unavailable_until, reason, evidence_json, observed_at)
-      VALUES (@runtime, @unavailable_until, @reason, @evidence_json, @observed_at)
+      INSERT INTO runtime_availability
+        (runtime, unavailable_until, reason, evidence_json, observed_at, provider_reset_at, limit_type)
+      VALUES (@runtime, @unavailable_until, @reason, @evidence_json, @observed_at, @provider_reset_at, @limit_type)
       ON CONFLICT(runtime) DO UPDATE SET
         unavailable_until = excluded.unavailable_until,
         reason = excluded.reason,
         evidence_json = excluded.evidence_json,
-        observed_at = excluded.observed_at
+        observed_at = excluded.observed_at,
+        provider_reset_at = excluded.provider_reset_at,
+        limit_type = excluded.limit_type
     `)
         .run({
         runtime: input.runtime,
@@ -22,6 +26,8 @@ export function recordRuntimeAvailability(input) {
         reason: input.reason,
         evidence_json: input.evidence !== undefined ? JSON.stringify(input.evidence) : null,
         observed_at: now,
+        provider_reset_at: input.providerResetAt ?? null,
+        limit_type: input.limitType ?? null,
     });
 }
 /** Clear a runtime row once its unavailable_until has passed (lazy cleanup on read). */
@@ -30,23 +36,35 @@ function clearExpired(runtime, nowMs = Date.now()) {
         .prepare("DELETE FROM runtime_availability WHERE runtime = ? AND unavailable_until <= ?")
         .run(runtime, new Date(nowMs).toISOString());
 }
-/**
- * Single read function for coordinator deferral and NOT-103 queue admission.
- * Returns `{ available: true }` when no active cap is recorded.
- */
-export function runtimeAvailability(runtime, nowMs = Date.now()) {
+/** The active cap row for a runtime, or null once it has expired (lazily cleared). */
+export function activeRuntimeCap(runtime, nowMs = Date.now()) {
     clearExpired(runtime, nowMs);
     const row = getDb()
         .prepare("SELECT * FROM runtime_availability WHERE runtime = ?")
         .get(runtime);
     if (!row)
-        return { available: true };
+        return null;
     const untilMs = Date.parse(row.unavailable_until);
     if (!Number.isFinite(untilMs) || untilMs <= nowMs) {
         getDb().prepare("DELETE FROM runtime_availability WHERE runtime = ?").run(runtime);
-        return { available: true };
+        return null;
     }
-    return { available: false, until: row.unavailable_until, reason: row.reason };
+    return {
+        unavailableUntil: row.unavailable_until,
+        reason: row.reason,
+        providerResetAt: row.provider_reset_at,
+        limitType: row.limit_type,
+    };
+}
+/**
+ * Single read function for coordinator deferral and NOT-103 queue admission.
+ * Returns `{ available: true }` when no active cap is recorded.
+ */
+export function runtimeAvailability(runtime, nowMs = Date.now()) {
+    const cap = activeRuntimeCap(runtime, nowMs);
+    if (!cap)
+        return { available: true };
+    return { available: false, until: cap.unavailableUntil, reason: cap.reason };
 }
 /** Test helper — wipe all cap rows. */
 export function clearAllRuntimeAvailability() {

package/bundle/server/dist/runners/usage-cap.js

@@ -23,9 +23,46 @@ function parseResetsAt(raw) {
     const d = new Date(ms);
     return Number.isFinite(d.getTime()) ? d : null;
 }
+/**
+ * Provider reset timestamps embedded in already-classified cap-error text
+ * (NOT-439). ISO-8601 only (`2026-10-12T18:59:01Z`, optional fractional
+ * seconds or numeric offset), and only when introduced by reset phrasing
+ * ("resets at", "reset_at:", "until", "retry after") so unrelated stamps in
+ * the same stderr/log text are ignored. Never consulted to decide whether a
+ * cap exists, only to place the boundary of one the cap classifier accepted.
+ */
+const RESET_TIMESTAMP_RE = /\b(?:resets?(?:_at)?|until|retry\s+after)\b[^\d\n]{0,20}(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2}))/gi;
+/**
+ * Shared reset extractor for every hard-cap path (NOT-439): structured
+ * numeric seconds/milliseconds first, then provider reset timestamps in
+ * already-classified cap-error text. Returns the normalized ISO-8601 instant
+ * of the first finite future reset, or null when no trustworthy future reset
+ * is present (absent, past, or malformed). Never creates a cap by itself —
+ * callers invoke it only after their existing cap classifier has matched.
+ */
+export function extractUsageCapReset(input, nowMs = Date.now()) {
+    for (const raw of input.resets ?? []) {
+        const d = parseResetsAt(raw);
+        if (d && d.getTime() > nowMs)
+            return d.toISOString();
+    }
+    if (typeof input.text === "string" && input.text) {
+        for (const [, candidate] of input.text.matchAll(RESET_TIMESTAMP_RE)) {
+            const ms = Date.parse(candidate);
+            if (Number.isFinite(ms) && ms > nowMs)
+                return new Date(ms).toISOString();
+        }
+    }
+    return null;
+}
 function fallbackUntil(nowMs = Date.now()) {
     return new Date(nowMs + usageCapFallbackCooldownMs()).toISOString();
 }
+/** Provider reset when trustworthy, otherwise the configured fallback cooldown. */
+function resolveUnavailableUntil(input, nowMs) {
+    const providerResetAt = extractUsageCapReset(input, nowMs);
+    return { unavailableUntil: providerResetAt ?? fallbackUntil(nowMs), providerResetAt };
+}
 function capReason(runtime, detail) {
     return `${runtime} usage capped — ${detail}`;
 }
@@ -38,16 +75,16 @@ function isHardCapRateLimitInfo(info) {
 function signalFromRateLimitInfo(runtime, info, evidence, nowMs) {
     if (!isHardCapRateLimitInfo(info))
         return null;
-    const reset = parseResetsAt(info.resetsAt) ??
-        parseResetsAt(info.overageResetsAt) ??
-        parseResetsAt(info.overage_resets_at) ??
-        parseResetsAt(info.resets_at);
-    const unavailableUntil = reset && reset.getTime() > nowMs ? reset.toISOString() : fallbackUntil(nowMs);
-    const limitType = String(info.rateLimitType ?? info.rate_limit_type ?? "plan");
+    const until = resolveUnavailableUntil({
+        resets: [info.resetsAt, info.overageResetsAt, info.overage_resets_at, info.resets_at],
+    }, nowMs);
+    const rawLimitType = info.rateLimitType ?? info.rate_limit_type;
+    const limitType = typeof rawLimitType === "string" && rawLimitType ? rawLimitType : null;
     return {
-        unavailableUntil,
-        reason: capReason(runtime, `${limitType} limit rejected`),
+        ...until,
+        reason: capReason(runtime, `${limitType ?? "plan"} limit rejected`),
         evidence: { ...evidence, rate_limit_info: info },
+        limitType,
     };
 }
 function signalFromApiRetry(e, runtime, nowMs) {
@@ -64,6 +101,8 @@ function signalFromApiRetry(e, runtime, nowMs) {
         unavailableUntil: fallbackUntil(nowMs),
         reason: capReason(runtime, err.replace("_", " ")),
         evidence: { event: e },
+        providerResetAt: null,
+        limitType: null,
     };
 }
 function signalFromResultError(e, runtime, nowMs) {
@@ -73,7 +112,8 @@ function signalFromResultError(e, runtime, nowMs) {
     if (!CAP_ERROR_RE.test(text))
         return null;
     return {
-        unavailableUntil: fallbackUntil(nowMs),
+        ...resolveUnavailableUntil({ text }, nowMs),
+        limitType: null,
         reason: capReason(runtime, "session ended with cap error"),
         evidence: { result: text.slice(0, 500) },
     };
@@ -113,7 +153,8 @@ function codexCapFromEvents(events, runtime, nowMs) {
             }
             if (CAP_ERROR_RE.test(msg)) {
                 return {
-                    unavailableUntil: fallbackUntil(nowMs),
+                    ...resolveUnavailableUntil({ text: msg }, nowMs),
+                    limitType: null,
                     reason: capReason(runtime, msg.slice(0, 120) || "turn failed"),
                     evidence: { turn_failed: err },
                 };
@@ -121,7 +162,8 @@ function codexCapFromEvents(events, runtime, nowMs) {
         }
         if (e.type === "error" && typeof e.message === "string" && CAP_ERROR_RE.test(e.message)) {
             return {
-                unavailableUntil: fallbackUntil(nowMs),
+                ...resolveUnavailableUntil({ text: e.message }, nowMs),
+                limitType: null,
                 reason: capReason(runtime, e.message.slice(0, 120)),
                 evidence: { error: e.message },
             };
@@ -198,7 +240,8 @@ export function detectUsageCapFromRawLog(raw, runtime, nowMs = Date.now()) {
         const haystack = textFallbackHaystack(raw, events);
         if (CAP_FALLBACK_RE.test(haystack)) {
             return {
-                unavailableUntil: fallbackUntil(nowMs),
+                ...resolveUnavailableUntil({ text: haystack }, nowMs),
+                limitType: null,
                 reason: capReason(runtime, "stderr/log matched usage-cap pattern"),
                 evidence: { matched: haystack.slice(0, 300) },
             };
@@ -221,6 +264,8 @@ export function recordUsageCapFromLog(logPath, runtime, nowMs = Date.now()) {
         unavailableUntil: cap.unavailableUntil,
         reason: cap.reason,
         evidence: cap.evidence,
+        providerResetAt: cap.providerResetAt,
+        limitType: cap.limitType,
     });
     return cap;
 }
@@ -236,19 +281,23 @@ export function recordUsageCapFromEvents(events, runtime, nowMs = Date.now()) {
         unavailableUntil: cap.unavailableUntil,
         reason: cap.reason,
         evidence: cap.evidence,
+        providerResetAt: cap.providerResetAt,
+        limitType: cap.limitType,
     });
     return cap;
 }
 /**
  * NOT-181: Muse's usage-cap signal is the parsed failure kind (runners/muse-code-jsonl.ts), not a
- * Claude-shaped log event. Muse reports no reset time (NOT-177: real cap payload never observed),
- * so the deferral uses the fallback cooldown.
+ * Claude-shaped log event. NOT-439: the 2026-10-12 incident proved Muse does report a reset
+ * timestamp in the failure message (`... resets at 2026-10-12T18:59:01Z`), so the deferral
+ * preserves it and uses the fallback cooldown only when no trustworthy future reset is present.
  */
 export function recordMuseUsageCap(failure, nowMs = Date.now()) {
     if (failure?.kind !== "usage_cap")
         return null;
     const cap = {
-        unavailableUntil: fallbackUntil(nowMs),
+        ...resolveUnavailableUntil({ text: failure.message }, nowMs),
+        limitType: null,
         reason: capReason("muse_code", failure.message.slice(0, 120) || "usage cap"),
         evidence: { muse_failure: failure },
     };
@@ -257,6 +306,8 @@ export function recordMuseUsageCap(failure, nowMs = Date.now()) {
         unavailableUntil: cap.unavailableUntil,
         reason: cap.reason,
         evidence: cap.evidence,
+        providerResetAt: cap.providerResetAt,
+        limitType: cap.limitType,
     });
     return cap;
 }