agent-dealer 1.2.5 → 1.2.7

package/bundle/server/dist/adapters/muse-capability.test.js

@@ -3,13 +3,27 @@
 // NOT-277: Muse Code developer shell/write capability is re-validated once per newly reported
 // version — cached per version, auto-confirmed on success, blocked by name on loss, fail-closed
 // when the check cannot complete. The real probe runs against fixtures/fake-muse.mjs (never Meta).
-import { describe, test, beforeEach } from "node:test";
+import { describe, test, beforeEach, before, after } from "node:test";
 import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
+import http from "node:http";
+import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-capability-"));
+// NOT-278: the worker MCP config root (the per-attempt base dir) refuses temp dirs, so the
+// dealer home for this file is a home scratch root, never OS temp. Removed in `after`
+// below so local runs do not clutter $HOME.
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.homedir(), ".dealer-muse-capability-"));
+after(() => {
+    try {
+        fs.rmSync(process.env.AGENT_DEALER_HOME, { recursive: true, force: true });
+    }
+    catch {
+        // best-effort — a failed rm must not fail the suite
+    }
+});
 const { museCapabilityIssues, museCapabilityCheckInFlight, parseMuseVersion, settleMuseCapabilityCheckForTests, setMuseCapabilityProbeForTests, resetMuseCapabilityStateForTests, ageMuseCapabilityCheckForTests, defaultMuseCapabilityProbe, } = await import("./muse-capability.js");
 const OLD = "1.3.0-R3401.1";
 const NEW = "1.4.0-R4161.1";
@@ -225,20 +239,68 @@ describe("muse-capability", { concurrency: false }, () => {
 // The real probe: one developer-posture session against the fake Muse, always a fresh `muse exec`.
 describe("defaultMuseCapabilityProbe (fake muse)", { concurrency: false }, () => {
     const FAKE_MUSE = path.join(path.dirname(fileURLToPath(import.meta.url)), "../coordinator/fixtures/fake-muse.mjs");
+    // A stub Agent Deck API: only `/health` matters to the probe's cheap pre-spawn gate
+    // (the fake muse never dials the deck). Started once for this block on an ephemeral port.
+    let deckApiUrl = "";
+    let deckServer = null;
+    before(() => new Promise((resolve) => {
+        deckServer = http
+            .createServer((req, res) => {
+            if (req.url === "/health") {
+                res.writeHead(200, { "content-type": "text/plain" });
+                res.end("ok");
+            }
+            else {
+                res.writeHead(404);
+                res.end();
+            }
+        })
+            .listen(0, "127.0.0.1", () => {
+            deckApiUrl = `http://127.0.0.1:${deckServer.address().port}`;
+            resolve();
+        });
+    }));
+    // `closeAllConnections` first: fetch keep-alive sockets would otherwise hold the
+    // stub open and the runner would never exit.
+    after(() => new Promise((resolve) => {
+        if (!deckServer)
+            return resolve();
+        deckServer.closeAllConnections();
+        deckServer.close(() => resolve());
+    }));
+    /** A surely-closed loopback port: nothing answers, so the deck reads as unreachable. */
+    async function deadDeckApiUrl() {
+        const srv = net.createServer();
+        await new Promise((r) => srv.listen(0, "127.0.0.1", r));
+        const port = srv.address().port;
+        await new Promise((r) => srv.close(() => r()));
+        return `http://127.0.0.1:${port}`;
+    }
+    // The probe binds a real listed deck and preflights it before spawning; there is no
+    // live deck/MCP here, so tests substitute both steps (production defaults hit the live
+    // `fetchDecks` + `verifyWorkerDeckConnection`). Overrides exercise the fail-closed paths.
+    const PROBE_DECK_ID = "11111111-1111-4111-8111-111111111111";
     async function probeWith(scenario, extraEnv = {}, opts = {}) {
         const env = {
             MUSE_CLI: FAKE_MUSE,
             FAKE_MUSE_SCENARIO: scenario,
             FAKE_MUSE_VERSION: NEW,
+            // NOT-278: the probe runs the deck-required exec lane without a database — the endpoint
+            // comes from the env override and the credential from a fake API key on stdin. The
+            // stub above answers `/health`, so the cheap pre-spawn gate passes and the fake runs.
+            AGENT_DECK_API_URL: deckApiUrl,
+            META_API_KEY: "mk-test-fake-key-0123456789abcdef",
             ...extraEnv,
         };
-        const keys = [...Object.keys(env), "AGENT_DEALER_MUSE_RUNNER"];
+        const keys = [...Object.keys(env)];
         const prev = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
         Object.assign(process.env, env);
-        // The serve lane is the production default; the probe must bypass it on its own.
-        delete process.env.AGENT_DEALER_MUSE_RUNNER;
         try {
-            return await defaultMuseCapabilityProbe(NEW, opts);
+            return await defaultMuseCapabilityProbe(NEW, {
+                timeoutMs: opts.timeoutMs,
+                listDecks: opts.listDecks ?? (async () => ({ ok: true, decks: [{ id: PROBE_DECK_ID, name: "probe" }] })),
+                verifyDeck: opts.verifyDeck ?? (async () => ({ ok: true })),
+            });
         }
         finally {
             for (const k of keys) {
@@ -260,6 +322,43 @@ describe("defaultMuseCapabilityProbe (fake muse)", { concurrency: false }, () =>
         const result = await probeWith("auth");
         assert.equal(result.status, "error");
     });
+    test("an unreachable deck fails closed before any model session is spent", async () => {
+        // The fixture would succeed and record under this scenario — an absent record proves no
+        // child ever spawned, so the deck outage cost a cheap health check, never a paid turn.
+        const record = path.join(process.env.AGENT_DEALER_HOME, `no-spawn-${randomUUID()}.json`);
+        const result = await probeWith("capability-shell", {
+            AGENT_DECK_API_URL: await deadDeckApiUrl(),
+            FAKE_MUSE_RECORD: record,
+        });
+        assert.equal(result.status, "error");
+        assert.match(result.detail, /Agent Deck is unreachable/);
+        assert.match(result.detail, /no model session spent/);
+        assert.equal(fs.existsSync(record), false, "no child spawned, so the fixture never recorded");
+    });
+    test("the probe binds the listed real deck id, never a synthetic one", async () => {
+        const record = path.join(process.env.AGENT_DEALER_HOME, `deck-id-${randomUUID()}.json`);
+        const result = await probeWith("capability-shell", { FAKE_MUSE_RECORD: record });
+        assert.deepEqual(result, { status: "capable" });
+        const seen = JSON.parse(fs.readFileSync(record, "utf8"));
+        assert.match(seen.settings, new RegExp(PROBE_DECK_ID));
+        assert.doesNotMatch(seen.settings, /00000000-0000-4000-a000-000000000000/);
+    });
+    test("a deck that responds but rejects the probe deck fails closed without a model session", async () => {
+        const record = path.join(process.env.AGENT_DEALER_HOME, `rejected-${randomUUID()}.json`);
+        const result = await probeWith("capability-shell", { FAKE_MUSE_RECORD: record }, { verifyDeck: async () => ({ ok: false, kind: "infra_failure", reason: "get_bound_deck returned deck other, expected probe" }) });
+        assert.equal(result.status, "error");
+        assert.match(result.detail, /rejected probe deck/);
+        assert.match(result.detail, /no model session spent/);
+        assert.equal(fs.existsSync(record), false, "no child spawned, so the fixture never recorded");
+    });
+    test("an empty deck list fails closed without a model session", async () => {
+        const record = path.join(process.env.AGENT_DEALER_HOME, `no-decks-${randomUUID()}.json`);
+        const result = await probeWith("capability-shell", { FAKE_MUSE_RECORD: record }, { listDecks: async () => ({ ok: true, decks: [] }) });
+        assert.equal(result.status, "error");
+        assert.match(result.detail, /no decks/);
+        assert.match(result.detail, /no model session spent/);
+        assert.equal(fs.existsSync(record), false, "no child spawned, so the fixture never recorded");
+    });
     test("a session that ran the shell but then timed out is could-not-verify, never capable", async () => {
         const result = await probeWith("capability-shell-then-hang", {}, { timeoutMs: 1500 });
         assert.equal(result.status, "error");
@@ -270,7 +369,7 @@ describe("defaultMuseCapabilityProbe (fake muse)", { concurrency: false }, () =>
         assert.equal(result.status, "error");
         assert.match(result.detail, /probe session (failed|exited)/);
     });
-    test("the probe never runs on the shared serve host (it may still be the pre-update build)", async () => {
+    test("the probe never runs on the shared serve host (deck-enabled turns are always isolated exec)", async () => {
         const { getMuseCapacityHost, resetMuseCapacityHostForTests } = await import("../capacity/muse-host.js");
         await resetMuseCapacityHostForTests();
         let serveSpawns = 0;
@@ -299,49 +398,51 @@ describe("defaultMuseCapabilityProbe (fake muse)", { concurrency: false }, () =>
         assert.match(result.detail, /1\.5\.0-R5000\.1 after probing 1\.4\.0-R4161\.1/);
     });
 });
-// Admission checks the on-disk binary; developer work must not then run on a serve host that is
-// still an older (possibly broken) build. A capable → B broken → C capable, host restarted onto B.
-describe("developer sessions run only on the capability-checked build", { concurrency: false }, () => {
+// NOT-278: deck-enabled developer turns always run the isolated `muse exec` lane — the shared
+// serve host cannot carry per-session deck/workspace identity, so no version check can route a
+// session onto it. The capability gate still admits (or blocks) the on-disk binary; the lane is
+// always exec.
+describe("deck-enabled developer sessions always use the isolated exec lane", { concurrency: false }, () => {
     const FAKE_MUSE = path.join(path.dirname(fileURLToPath(import.meta.url)), "../coordinator/fixtures/fake-muse.mjs");
-    const B = NEW;
-    const C = "1.4.0-R4302.1";
-    /** One developer session with the shared host reporting `hostVersion`; returns the RPCs sent to it. */
-    async function sessionWithHostOn(hostVersion) {
+    /** One deck-enabled developer session while a serve host exists; returns host spawn attempts. */
+    async function sessionBesideServeHost() {
         const { getMuseCapacityHost, resetMuseCapacityHostForTests } = await import("../capacity/muse-host.js");
         const { runMuseDeveloperSession } = await import("../coordinator/muse-spawn.js");
         await resetMuseCapacityHostForTests();
-        const host = getMuseCapacityHost({
-            command: process.execPath,
-            args: [path.join(path.dirname(fileURLToPath(import.meta.url)), "../capacity/fixtures/fake-muse-serve.mjs")],
-            env: { META_API_KEY: "test-fake-key", FAKE_MSP_MODE: "persistent-full" },
-            readVersion: async () => hostVersion,
+        let serveSpawns = 0;
+        getMuseCapacityHost({
+            spawnImpl: (() => {
+                serveSpawns += 1;
+                throw new Error("serve host must not be used by a deck-enabled developer session");
+            }),
         });
-        const sent = [];
-        const execRequest = host.execRequest.bind(host);
-        host.execRequest = (id, method, params, timeoutMs) => {
-            sent.push(method);
-            return execRequest(id, method, params, timeoutMs);
-        };
-        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-bound-"));
-        const keys = ["MUSE_CLI", "FAKE_MUSE_SCENARIO", "FAKE_MUSE_VERSION", "AGENT_DEALER_MUSE_RUNNER"];
+        // NOT-278: home scratch, never OS temp (the attempt rejects temp dirs).
+        const dir = fs.mkdtempSync(path.join(os.homedir(), ".dealer-muse-exec-"));
+        const configHome = fs.mkdtempSync(path.join(os.homedir(), ".dealer-muse-exec-cfg-"));
+        const keys = ["MUSE_CLI", "FAKE_MUSE_SCENARIO", "META_API_KEY", "XDG_CONFIG_HOME"];
         const prev = Object.fromEntries(keys.map((k) => [k, process.env[k]]));
-        Object.assign(process.env, { MUSE_CLI: FAKE_MUSE, FAKE_MUSE_SCENARIO: "success", FAKE_MUSE_VERSION: C });
-        delete process.env.AGENT_DEALER_MUSE_RUNNER;
+        Object.assign(process.env, {
+            MUSE_CLI: FAKE_MUSE,
+            FAKE_MUSE_SCENARIO: "success",
+            META_API_KEY: "mk-test-fake-key-0123456789abcdef",
+            XDG_CONFIG_HOME: configHome,
+        });
         try {
             const { execFileSync } = await import("node:child_process");
             execFileSync("git", ["init", "-q"], { cwd: dir });
             const run = await runMuseDeveloperSession({
-                sessionId: "bound-session",
+                sessionId: randomUUID(),
                 runtime: "muse_code",
                 policy: {},
                 model: null,
+                deckId: "00000000-0000-4000-a000-000000000099",
+                agentDeckUrl: "http://127.0.0.1:1110/mcp",
                 prompt: "implement",
                 cwd: dir,
                 timeoutMs: 30_000,
                 logPath: path.join(dir, "session.ndjson"),
             });
-            assert.equal(run.exitCode, 0);
-            return sent;
+            return { exitCode: run.exitCode, serveSpawns };
         }
         finally {
             for (const k of keys) {
@@ -352,27 +453,12 @@ describe("developer sessions run only on the capability-checked build", { concur
             }
             await resetMuseCapacityHostForTests();
             fs.rmSync(dir, { recursive: true, force: true });
+            fs.rmSync(configHome, { recursive: true, force: true });
         }
     }
-    beforeEach(() => {
-        resetMuseCapabilityStateForTests();
-        stubProbe({ [OLD]: { status: "capable" }, [B]: { status: "missing", detail: "no shell" }, [C]: { status: "capable" } });
-    });
-    test("C confirmed but the host still runs broken B: the session never reaches the host", async () => {
-        await check(OLD);
-        await check(B);
-        const { settled } = await check(C);
-        assert.deepEqual(settled, []);
-        assert.deepEqual(await sessionWithHostOn(B), [], "work ran on the checked exec lane, not the B host");
-    });
-    test("a host running the confirmed version serves the session", async () => {
-        await check(C);
-        const sent = await sessionWithHostOn(C);
-        assert.ok(sent.includes("session/start"), "serve lane used when the host runs the checked build");
-    });
-    test("while the reported version is not confirmed, no session reaches the host", async () => {
-        await check(OLD);
-        await check(B);
-        assert.deepEqual(await sessionWithHostOn(OLD), []);
+    test("the session runs on the exec lane and never touches the serve host", async () => {
+        const { exitCode, serveSpawns } = await sessionBesideServeHost();
+        assert.equal(exitCode, 0);
+        assert.equal(serveSpawns, 0, "no serve-host spawn for a deck-enabled developer turn");
     });
 });

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

@@ -13,8 +13,10 @@
 //      `~/.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 FREE refresh when every valid 5H/1W observation is older
-//      than 60 minutes: `claude -p "/usage"`. This is the default behavior.
+//   3. One minimal FREE refresh when either valid 5H/1W observation is
+//      missing or at least 14 minutes old: `claude -p "/usage"` (NOT-281 —
+//      the 15-minute display freshness would otherwise lapse into N/A while
+//      the old 60-minute trigger waited). This is the default behavior.
 //      Set `AGENT_DEALER_CLAUDE_CAPACITY_REFRESH=off` to disable it entirely
 //      — reading capacity then never spawns Claude. Unrecognized values also
 //      fail closed (stay disabled).
@@ -133,10 +135,20 @@ export const CLAUDE_PROBE_PROMPT = "/usage";
 export const CLAUDE_PROBE_MODEL = "haiku";
 /** Defensive spend cap (USD) — normal cost is $0; see module header. */
 export const CLAUDE_PROBE_MAX_BUDGET_USD = 0.01;
-/** A 5H/1W observation newer than this suppresses the refresh. */
-export const CLAUDE_PROBE_STALE_AFTER_MS = 60 * 60 * 1000;
-/** Minimum gap between probe attempts (per account); failures back off. */
-export const CLAUDE_PROBE_ATTEMPT_COOLDOWN_MS = 60 * 60 * 1000;
+/**
+ * Either critical window (5H or 1W) at least this old triggers the refresh.
+ * 14 minutes — one minute inside the 15-minute display `freshUntil` (NOT-281)
+ * so the asynchronous single-flight `/usage` run normally completes before
+ * the UI would mark the reading stale. Checked per window, never as a
+ * newest-of-pair: one fresh sibling must not suppress its stale twin.
+ */
+export const CLAUDE_PROBE_STALE_AFTER_MS = 14 * 60 * 1000;
+/**
+ * Minimum gap between probe attempts (per account). Aligned with the trigger
+ * above: a healthy observation causes at most one refresh per 14 minutes;
+ * failures back off exponentially (14m → 28m → 56m → ~2h, capped at 8h).
+ */
+export const CLAUDE_PROBE_ATTEMPT_COOLDOWN_MS = 14 * 60 * 1000;
 export const CLAUDE_PROBE_BACKOFF_CAP_MS = 8 * 60 * 60 * 1000;
 /** Account-wide window identities for the local cache (exact, lowercase). */
 const FIVE_HOUR_LIMIT_NAMES = new Set(["five_hour", "session"]);
@@ -704,7 +716,7 @@ export async function runClaudeCapacityProbe(nowMs = Date.now(), opts = {}) {
         appendProbeDiagnostic({
             ts: new Date(nowMs).toISOString(),
             event: "claude_capacity_probe",
-            trigger: "stale_60m",
+            trigger: "stale_14m",
             probeCommand: CLAUDE_PROBE_PROMPT,
             budgetUsd: CLAUDE_PROBE_MAX_BUDGET_USD,
             ...out,
@@ -811,24 +823,27 @@ export async function runClaudeCapacityProbe(nowMs = Date.now(), opts = {}) {
     appendProbeDiagnostic({
         ts: new Date(nowMs).toISOString(),
         event: "claude_capacity_probe",
-        trigger: "stale_60m",
+        trigger: "stale_14m",
         probeCommand: CLAUDE_PROBE_PROMPT,
         budgetUsd: CLAUDE_PROBE_MAX_BUDGET_USD,
         ...out,
     });
     return out;
 }
-// ---------------------------------------------------------------------------
-// Freshness gate, single-flight, backoff
-// ---------------------------------------------------------------------------
 /**
- * Newest valid account-wide 5H/1W observation (event or cache — both share
- * window keys and critical roles). A row counts when it carries a remaining
- * %, its reset is absent or future, and its observed time is not in the
- * future. Returns null when no such sample exists.
+ * Newest valid account-wide observation per critical window (event or cache
+ * — both share window keys and critical roles). A row counts when it
+ * carries a remaining %, its reset is absent or future, and its observed
+ * time is not in the future. A role maps to null when it has no such
+ * sample (missing, expired, or unparsable). Split per window on purpose
+ * (NOT-281): the refresh gate must see a stale twin hiding behind a fresh
+ * sibling, which a newest-of-pair maximum cannot show.
  */
-export function newestValidClaudeObservationMs(nowMs = Date.now()) {
-    let max = null;
+export function newestValidClaudeObservationMsByRole(nowMs = Date.now()) {
+    const out = {
+        five_hour: null,
+        weekly: null,
+    };
     for (const row of listCapacitySnapshots(CLAUDE_RUNTIME)) {
         if (row.criticalRole !== "five_hour" && row.criticalRole !== "weekly")
             continue;
@@ -842,9 +857,22 @@ export function newestValidClaudeObservationMs(nowMs = Date.now()) {
         const observedMs = Date.parse(row.observedAt);
         if (!Number.isFinite(observedMs) || observedMs > nowMs)
             continue;
-        max = max === null ? observedMs : Math.max(max, observedMs);
+        const prev = out[row.criticalRole];
+        out[row.criticalRole] = prev === null ? observedMs : Math.max(prev, observedMs);
     }
-    return max;
+    return out;
+}
+/**
+ * Newest valid account-wide 5H/1W observation across both critical windows.
+ * Kept for diagnostics; the refresh gate uses the per-role variant above.
+ */
+export function newestValidClaudeObservationMs(nowMs = Date.now()) {
+    const byRole = newestValidClaudeObservationMsByRole(nowMs);
+    if (byRole.five_hour === null)
+        return byRole.weekly;
+    if (byRole.weekly === null)
+        return byRole.five_hour;
+    return Math.max(byRole.five_hour, byRole.weekly);
 }
 let claudeProbeInFlight = null;
 let lastClaudeProbeAttemptMs = 0;
@@ -868,12 +896,14 @@ function probeCooldownMs() {
     return Math.min(CLAUDE_PROBE_ATTEMPT_COOLDOWN_MS * 2 ** shift, CLAUDE_PROBE_BACKOFF_CAP_MS);
 }
 /**
- * On-demand free `/usage` refresh: 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). Explicitly
- * disabled is a strict no-op — no spawn at all. Never throws, never touches
- * Dealer workflow/session state or `runtime_availability`.
+ * On-demand free `/usage` refresh: when `claude_code` is configured and
+ * either critical window (5H or 1W) is missing or at least 14 minutes old,
+ * run one minimal bounded probe (single-flight across concurrent readers;
+ * at most one attempt per account per 14 minutes while healthy, backing
+ * off exponentially on failure). Per-window on purpose (NOT-281): a fresh
+ * sibling must never suppress its stale twin. Explicitly disabled is a
+ * strict no-op — no spawn at all. Never throws, never touches Dealer
+ * workflow/session state or `runtime_availability`.
  */
 export async function maybeProbeClaudeCapacity(nowMs = Date.now(), opts = {}) {
     try {
@@ -882,8 +912,10 @@ export async function maybeProbeClaudeCapacity(nowMs = Date.now(), opts = {}) {
         if (!configuredCapacityRuntimes().includes(CLAUDE_RUNTIME)) {
             return { probed: false, reason: "unconfigured" };
         }
-        const newest = newestValidClaudeObservationMs(nowMs);
-        if (newest !== null && nowMs - newest < CLAUDE_PROBE_STALE_AFTER_MS) {
+        const byRole = newestValidClaudeObservationMsByRole(nowMs);
+        const fiveFresh = byRole.five_hour !== null && nowMs - byRole.five_hour < CLAUDE_PROBE_STALE_AFTER_MS;
+        const weeklyFresh = byRole.weekly !== null && nowMs - byRole.weekly < CLAUDE_PROBE_STALE_AFTER_MS;
+        if (fiveFresh && weeklyFresh) {
             return { probed: false, reason: "fresh" };
         }
         // Single-flight first: readers arriving while a probe runs share it

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

@@ -1,8 +1,10 @@
 // packages/server/src/capacity/claude-local-cache.test.ts
 //
 // NOT-268: Claude capacity local-first ladder — local cache 5H/1W plus a
-// free `/usage` refresh after one hour stale. No test here performs a live
-// provider request: every probe spawn goes through an injected fake runner.
+// free `/usage` refresh; NOT-281 retargeted the trigger to either window at
+// least 14 minutes old (per-window, inside the 15-minute display freshness).
+// 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";
@@ -14,8 +16,8 @@ const { createAgent } = await import("../repository/agents.js");
 const { listCapacitySnapshots, clearAllCapacitySnapshots, } = await import("../repository/runtime-capacity.js");
 const { parseNdjson } = await import("../runners/stream-json.js");
 const { getRuntimeCapacitySnapshot } = await import("./service.js");
-const { recordClaudeCapacityFromEvents } = await import("./claude-events.js");
-const { CLAUDE_CACHE_FILE_ENV, CLAUDE_CAPACITY_REFRESH_ENV, buildClaudeProbeArgv, claudeCacheFilePath, extractClaudeCacheSubtree, ingestClaudeLocalCache, isClaudePaidFallbackEnabled, maybeProbeClaudeCapacity, newestValidClaudeObservationMs, parseClaudeCachedUtilization, probeDiagnosticLogPath, readClaudeLocalCache, refreshClaudeCapacityIfStale, resetClaudeCapacityRefreshState, runClaudeCapacityProbe, } = await import("./claude-local-cache.js");
+const { recordClaudeCapacityFromEvents, recordClaudeWindowReadings } = await import("./claude-events.js");
+const { CLAUDE_CACHE_FILE_ENV, CLAUDE_CAPACITY_REFRESH_ENV, CLAUDE_PROBE_STALE_AFTER_MS, buildClaudeProbeArgv, claudeCacheFilePath, extractClaudeCacheSubtree, ingestClaudeLocalCache, isClaudePaidFallbackEnabled, maybeProbeClaudeCapacity, newestValidClaudeObservationMs, newestValidClaudeObservationMsByRole, parseClaudeCachedUtilization, probeDiagnosticLogPath, readClaudeLocalCache, refreshClaudeCapacityIfStale, resetClaudeCapacityRefreshState, runClaudeCapacityProbe, } = await import("./claude-local-cache.js");
 const NOW_MS = Date.parse("2026-09-20T12:00:00.000Z");
 const FIVE_HOUR_RESET_SEC = Math.floor(NOW_MS / 1000) + 2 * 3600;
 const SEVEN_DAY_RESET_SEC = Math.floor(NOW_MS / 1000) + 3 * 24 * 3600;
@@ -88,6 +90,42 @@ function probeStreamFixture(observedIso, costUsd = 0) {
 const throwingRunner = () => {
     throw new Error("probe runner must not be called while disabled/fresh");
 };
+/**
+ * Seed the snapshot store with per-window ages (NOT-281): the shared cache
+ * fixture always stamps both windows together, so split-freshness cases
+ * need direct per-role rows. Resets stay in the future so rows count as
+ * valid observations at NOW_MS.
+ */
+function seedWindowAges(fiveHourAgeMs, weeklyAgeMs, nowMs = NOW_MS) {
+    const readings = [];
+    const role = (five, ageMs) => ({
+        windowKey: five ? "claude_unified_five_hour" : "claude_unified_seven_day",
+        providerBucket: five ? "five_hour" : "seven_day",
+        durationMinutes: five ? 300 : 10080,
+        providerLabel: five ? "five_hour" : "seven_day",
+        usedValue: five ? 0.17 : 0.42,
+        usedUnit: "fraction",
+        usedFraction: five ? 0.17 : 0.42,
+        resetAt: new Date((five ? FIVE_HOUR_RESET_SEC : SEVEN_DAY_RESET_SEC) * 1000).toISOString(),
+        observedAt: new Date(nowMs - ageMs).toISOString(),
+        source: "observed_event",
+        evidenceRef: "test:split-window-seed",
+        criticalRole: five ? "five_hour" : "weekly",
+    });
+    if (fiveHourAgeMs !== null)
+        readings.push(role(true, fiveHourAgeMs));
+    if (weeklyAgeMs !== null)
+        readings.push(role(false, weeklyAgeMs));
+    assert.equal(recordClaudeWindowReadings(readings, "claude_code", nowMs), readings.length);
+}
+function successRunner(atMs = NOW_MS) {
+    return async () => ({
+        stdout: probeStreamFixture(new Date(atMs).toISOString()),
+        exitCode: 0,
+        timedOut: false,
+        spawnError: null,
+    });
+}
 before(() => {
     migrate();
     createAgent({
@@ -319,12 +357,13 @@ test("extractClaudeUsageReportLimits reads the /usage local-command result", asy
     assert.equal(extractClaudeUsageReportLimits([{ type: "result" }], NOW_MS), null);
 });
 test("default-on refresh suppresses a fresh sample; stale data triggers exactly one", async () => {
+    assert.equal(CLAUDE_PROBE_STALE_AFTER_MS, 14 * 60_000);
     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);
+    assert.ok((newestValidClaudeObservationMs(NOW_MS) ?? 0) > NOW_MS - CLAUDE_PROBE_STALE_AFTER_MS);
     const fresh = await maybeProbeClaudeCapacity(NOW_MS, { runner: throwingRunner });
     assert.deepEqual(fresh, { probed: false, reason: "fresh" });
-    // All samples ≥60 minutes old: five concurrent readers share one probe.
+    // All samples past the 14-minute trigger: five concurrent readers share one probe.
     clearAllCapacitySnapshots();
     resetClaudeCapacityRefreshState();
     fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 61 * 60_000));
@@ -341,6 +380,121 @@ test("default-on refresh suppresses a fresh sample; stale data triggers exactly
     assert.equal(outcomes.filter((o) => o.reason === "shared").length, 4);
     assert.ok(outcomes.every((o) => o.probed && o.ok));
 });
+test("a stale twin triggers one refresh even when its sibling is newer", async () => {
+    // NOT-281: the old newest-of-pair gate let one fresh window suppress the
+    // refresh while its sibling went stale. Freshness is per window now.
+    seedWindowAges(5 * 60_000, 20 * 60_000);
+    const byRole = newestValidClaudeObservationMsByRole(NOW_MS);
+    assert.equal(byRole.five_hour, NOW_MS - 5 * 60_000);
+    assert.equal(byRole.weekly, NOW_MS - 20 * 60_000);
+    let calls = 0;
+    const runner = async () => {
+        calls++;
+        return {
+            stdout: probeStreamFixture(new Date(NOW_MS).toISOString()),
+            exitCode: 0,
+            timedOut: false,
+            spawnError: null,
+        };
+    };
+    const outcome = await maybeProbeClaudeCapacity(NOW_MS, { runner });
+    assert.equal(calls, 1);
+    assert.equal(outcome.probed, true);
+    assert.equal(outcome.reason, "completed");
+    assert.equal(outcome.ok, true);
+    // On success both windows are fresh again …
+    const after = newestValidClaudeObservationMsByRole(NOW_MS);
+    assert.equal(after.five_hour, NOW_MS);
+    assert.equal(after.weekly, NOW_MS);
+    // … and the next API/UI poll (a minute later, well inside the ordinary
+    // 15-minute stale boundary) reports known values with no new spawn.
+    const poll = await maybeProbeClaudeCapacity(NOW_MS + 60_000, { runner: throwingRunner });
+    assert.deepEqual(poll, { probed: false, reason: "fresh" });
+    const snap = getRuntimeCapacitySnapshot(NOW_MS + 60_000);
+    const claude = snap.runtimes.find((r) => r.runtime === "claude_code");
+    assert.equal(claude.windows.find((w) => w.displayLabel === "5H").remainingPercent, 80);
+    assert.equal(claude.windows.find((w) => w.displayLabel === "1W").remainingPercent, 60);
+});
+test("a missing window triggers a refresh even when the sibling is newer", async () => {
+    seedWindowAges(5 * 60_000, null);
+    assert.deepEqual(newestValidClaudeObservationMsByRole(NOW_MS), {
+        five_hour: NOW_MS - 5 * 60_000,
+        weekly: null,
+    });
+    let calls = 0;
+    const runner = async () => {
+        calls++;
+        return {
+            stdout: probeStreamFixture(new Date(NOW_MS).toISOString()),
+            exitCode: 0,
+            timedOut: false,
+            spawnError: null,
+        };
+    };
+    const outcome = await maybeProbeClaudeCapacity(NOW_MS, { runner });
+    assert.equal(calls, 1);
+    assert.equal(outcome.ok, true);
+    assert.deepEqual(newestValidClaudeObservationMsByRole(NOW_MS), {
+        five_hour: NOW_MS,
+        weekly: NOW_MS,
+    });
+});
+test("the freshness boundary is 14 minutes: just under stays quiet, exactly at triggers", async () => {
+    seedWindowAges(13 * 60_000, 13 * 60_000);
+    const fresh = await maybeProbeClaudeCapacity(NOW_MS, { runner: throwingRunner });
+    assert.deepEqual(fresh, { probed: false, reason: "fresh" });
+    clearAllCapacitySnapshots();
+    resetClaudeCapacityRefreshState();
+    seedWindowAges(14 * 60_000, 0);
+    const stale = await maybeProbeClaudeCapacity(NOW_MS, { runner: successRunner() });
+    assert.equal(stale.probed, true);
+    assert.equal(stale.reason, "completed");
+    assert.equal(stale.ok, true);
+});
+test("a healthy refresh buys 14 minutes: no second attempt inside the interval", async () => {
+    seedWindowAges(20 * 60_000, 20 * 60_000);
+    let calls = 0;
+    const runner = async () => {
+        calls++;
+        return {
+            stdout: probeStreamFixture(new Date(NOW_MS).toISOString()),
+            exitCode: 0,
+            timedOut: false,
+            spawnError: null,
+        };
+    };
+    const first = await maybeProbeClaudeCapacity(NOW_MS, { runner });
+    assert.equal(first.ok, true);
+    assert.equal(calls, 1);
+    // A 5-second-poll cadence sees fresh rows and spawns nothing.
+    const poll = await maybeProbeClaudeCapacity(NOW_MS + 5_000, { runner: throwingRunner });
+    assert.deepEqual(poll, { probed: false, reason: "fresh" });
+    // Even if the rows go missing mid-interval (e.g. a reset passes), the
+    // attempt cooldown stamped by the healthy run holds — at most one
+    // refresh per 14 minutes, never a retry per poll.
+    clearAllCapacitySnapshots();
+    const missing = await maybeProbeClaudeCapacity(NOW_MS + 5 * 60_000, { runner: throwingRunner });
+    assert.deepEqual(missing, { probed: false, reason: "backoff" });
+    assert.equal(calls, 1);
+    // Past the interval the gate opens again.
+    const later = await maybeProbeClaudeCapacity(NOW_MS + 15 * 60_000, { runner });
+    assert.equal(later.probed, true);
+    assert.equal(calls, 2);
+});
+test("disabled refresh never spawns and stale readings stay honestly N/A", async () => {
+    process.env[CLAUDE_CAPACITY_REFRESH_ENV] = "off";
+    // 20 minutes old: past the 15-minute display freshness, inside expiry.
+    fs.writeFileSync(cacheFile, fullCacheFixture(NOW_MS - 20 * 60_000));
+    assert.equal(ingestClaudeLocalCache(NOW_MS), 2);
+    const outcome = await maybeProbeClaudeCapacity(NOW_MS, { runner: throwingRunner });
+    assert.deepEqual(outcome, { probed: false, reason: "disabled" });
+    const snap = getRuntimeCapacitySnapshot(NOW_MS);
+    const claude = snap.runtimes.find((r) => r.runtime === "claude_code");
+    for (const w of claude.windows) {
+        assert.equal(w.remainingPercent, null);
+        assert.equal(w.unavailableReason, "stale");
+    }
+});
 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);
@@ -561,10 +715,10 @@ test("probe failure preserves last-good rows and enters bounded backoff", async
     const second = await maybeProbeClaudeCapacity(NOW_MS + 60_000, { runner: failing });
     assert.deepEqual(second, { probed: false, reason: "backoff" });
     assert.equal(calls, 1);
-    // Exponential backoff: one failure doubles the 60-minute cooldown.
-    const during = await maybeProbeClaudeCapacity(NOW_MS + 61 * 60_000, { runner: failing });
+    // Exponential backoff: one failure doubles the 14-minute cooldown (28m).
+    const during = await maybeProbeClaudeCapacity(NOW_MS + 15 * 60_000, { runner: failing });
     assert.deepEqual(during, { probed: false, reason: "backoff" });
-    const after = await maybeProbeClaudeCapacity(NOW_MS + 121 * 60_000, { runner: failing });
+    const after = await maybeProbeClaudeCapacity(NOW_MS + 29 * 60_000, { runner: failing });
     assert.equal(after.probed, true);
     assert.equal(calls, 2);
 });