agent-dealer 1.2.1 → 1.2.3

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

@@ -1,21 +1,25 @@
 // packages/server/src/capacity/muse.test.ts
 //
 // NOT-247: Muse serve adapter — fake-subprocess coverage only, never a live
-// Muse request. A fake MSP 1.3 server returns rolling + weekly usage (two
+// Muse request. A fake stable MSP server returns window + weekly usage (two
 // independent snapshots with correct remaining percents and reset times), the
 // rolling label derives from `windowDurationMins` (never hardcoded),
 // failure modes map to explicit N/A reasons without touching runtime health,
-// and the recorded protocol traffic proves the client never sends a prompt.
+// and the recorded protocol traffic proves the client runs the
+// initialize → initialized → usage/read handshake and never sends a prompt.
+// NOT-263: the fake enforces the stable contract (no `--protocol` argv,
+// handshake order, `usage.window` field names).
 import { test, before } from "node:test";
 import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
 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-cap-"));
-import { assertMuseReadOnlyMethod, createMuseCapacityAdapter, MSP_FORBIDDEN_MODEL_METHODS, museRefreshThrottleMs, museUsageToReadings, maybeRefreshMuseCapacityFromServe, normalizeMuseResetsAt, normalizeMuseUnavailable, readMuseCapacity, refreshMuseCapacityFromServe, requestMuseUsage, resetMuseCapacityRefreshState, } from "./muse.js";
-import { normalizeAdapterWindow } from "./adapter.js";
+import { assertMuseReadOnlyMethod, createMuseCapacityAdapter, MSP_FORBIDDEN_MODEL_METHODS, MUSE_CLIENT_INFO, MUSE_SERVE_ARGV, museUsageToReadings, normalizeMuseResetsAt, normalizeMuseUnavailable, readMuseCapacity, requestMuseUsage, } from "./muse.js";
+import { normalizeAdapterWindow, normalizeUnavailableWindow } from "./adapter.js";
 const { migrate } = await import("../db/index.js");
-const { clearAllCapacitySnapshots, listCapacitySnapshots } = await import("../repository/runtime-capacity.js");
+const { clearAllCapacitySnapshots } = await import("../repository/runtime-capacity.js");
 const { clearAllRuntimeAvailability, runtimeAvailability, } = await import("../repository/runtime-availability.js");
 const { refreshCapacityFromAdapters } = await import("./service.js");
 const FAKE = new URL("./fixtures/fake-muse-serve.mjs", import.meta.url).pathname;
@@ -40,6 +44,14 @@ function fakeOpts(mode, extra = {}) {
         },
     };
 }
+test("serve argv is the shipping contract: no --protocol flag, restricted network", () => {
+    assert.deepEqual([...MUSE_SERVE_ARGV], ["serve", "--sandbox-network", "restricted"]);
+    assert.ok(!MUSE_SERVE_ARGV.includes("--protocol"), "muse serve takes no --protocol flag");
+});
+test("handshake identity matches the stable clientInfo shape", () => {
+    assert.match(MUSE_CLIENT_INFO.name, /^[a-z0-9_]+$/);
+    assert.ok(MUSE_CLIENT_INFO.version.length > 0, "versioned client identity required");
+});
 test("usage windows keep identity, percent, duration, and reset", () => {
     const now = Date.now();
     const parsed = museUsageToReadings({
@@ -47,7 +59,7 @@ test("usage windows keep identity, percent, duration, and reset", () => {
         usage: {
             observedAtMs: now,
             tier: "contributor",
-            rolling: { usedPercent: 60, resetsAtMs: now + 2 * 3600_000, windowDurationMins: 300 },
+            window: { usedPercent: 60, resetsAtMs: now + 2 * 3600_000, windowDurationMins: 300 },
             weekly: { usedPercent: 25, resetsAtMs: now + 3 * 24 * 3600_000 },
         },
     }, new Date(now).toISOString());
@@ -62,16 +74,30 @@ test("usage windows keep identity, percent, duration, and reset", () => {
     const normalized = normalizeAdapterWindow("muse_code", rolling, now);
     assert.equal(normalized.displayLabel, "5H");
     assert.equal(normalized.remainingPercent, 40);
+    assert.equal(normalized.criticalRole, "five_hour");
     const weekly = parsed.windows.find((w) => w.windowKey === "weekly_all_models");
     assert.equal(normalizeAdapterWindow("muse_code", weekly, now).displayLabel, "1W");
     assert.equal(normalizeAdapterWindow("muse_code", weekly, now).remainingPercent, 75);
+    assert.equal(normalizeAdapterWindow("muse_code", weekly, now).criticalRole, "weekly");
+});
+test("legacy rolling spelling maps to the same snapshot", () => {
+    const now = Date.now();
+    const parsed = museUsageToReadings({
+        usage: {
+            observedAtMs: now,
+            rolling: { usedPercent: 60, resetsAtMs: now + 2 * 3600_000, windowDurationMins: 300 },
+        },
+    }, new Date(now).toISOString());
+    assert.ok(parsed);
+    assert.equal(parsed.windows.length, 1);
+    assert.equal(parsed.windows[0].windowKey, "rolling_all_models");
 });
 test("rolling label derives from windowDurationMins, never a hardcoded 5H", () => {
     const now = Date.now();
     const parsed = museUsageToReadings({
         usage: {
             observedAtMs: now,
-            rolling: { usedPercent: 10, resetsAtMs: now + 6 * 3600_000, windowDurationMins: 720 },
+            window: { usedPercent: 10, resetsAtMs: now + 6 * 3600_000, windowDurationMins: 720 },
         },
     }, new Date(now).toISOString());
     assert.ok(parsed);
@@ -86,7 +112,7 @@ test("payloads without an observation read null, not empty", () => {
     assert.equal(museUsageToReadings({ protocol: "msp/1.3" }), null);
     assert.equal(museUsageToReadings({ usage: null }), null);
     assert.equal(museUsageToReadings({ usage: { observedAtMs: Date.now() } }).windows.length, 0);
-    assert.equal(museUsageToReadings({ usage: { observedAtMs: Date.now(), rolling: { windowDurationMins: 300 } } })
+    assert.equal(museUsageToReadings({ usage: { observedAtMs: Date.now(), window: { windowDurationMins: 300 } } })
         .windows.length, 0);
 });
 test("resetsAtMs accepts ms, seconds, and ISO; rejects garbage", () => {
@@ -99,7 +125,9 @@ test("resetsAtMs accepts ms, seconds, and ISO; rejects garbage", () => {
     assert.equal(normalizeMuseResetsAt(null), null);
     assert.equal(normalizeMuseResetsAt(-5), null);
 });
-test("only usage/read can be sent; session prompts throw before write", () => {
+test("only the handshake and usage/read can be sent; session prompts throw before write", () => {
+    assertMuseReadOnlyMethod("initialize");
+    assertMuseReadOnlyMethod("initialized");
     assertMuseReadOnlyMethod("usage/read");
     for (const m of ["session/start", "session/prompt", "session/resume", "exec", "usage/write"]) {
         assert.throws(() => assertMuseReadOnlyMethod(m), /refusing non-read method/);
@@ -144,31 +172,85 @@ test("usage/changed notifications are consumed while the connection is alive", a
     assert.equal(read.failure, null);
     assert.equal(read.updates.length, 1);
 });
-test("protocol traffic is read-only: usage/read and nothing else", async () => {
+test("protocol traffic is the stable handshake then exactly one usage/read", async () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-record-"));
     const recordPath = path.join(dir, "methods.jsonl");
     const { opts } = fakeOpts("full", { env: { FAKE_MSP_RECORD: recordPath } });
     await readMuseCapacity(opts);
-    const methods = fs
+    const lines = fs
         .readFileSync(recordPath, "utf8")
         .split("\n")
         .filter(Boolean)
-        .map((l) => String(JSON.parse(l).method));
-    assert.ok(methods.length >= 1, `expected a read, got ${methods}`);
+        .map((l) => JSON.parse(l));
+    const methods = lines.map((l) => String(l.method));
+    assert.deepEqual(methods, ["initialize", "initialized", "usage/read"]);
+    const init = lines[0];
+    assert.equal(init.params?.clientInfo?.name, MUSE_CLIENT_INFO.name);
+    assert.match(String(init.params?.clientInfo?.name ?? ""), /^[a-z0-9_]+$/);
+    assert.equal(init.params?.clientInfo?.version, MUSE_CLIENT_INFO.version);
     for (const m of methods) {
-        assert.equal(m, "usage/read");
         assert.ok(!/session|prompt|exec|message|turn|thread/i.test(m), `billable method ${m}`);
     }
 });
+test("fake rejects the removed --protocol argv like the shipped binary", async () => {
+    clearAllCapacitySnapshots();
+    const now = Date.now();
+    const result = await readMuseCapacity({
+        command: process.execPath,
+        args: [FAKE, "--protocol", "msp/1.3"],
+        env: { META_API_KEY: "test-fake-key", FAKE_MSP_MODE: "full" },
+        timeoutMs: 10_000,
+        nowMs: now,
+    });
+    assert.equal(result.windows.length, 0);
+    assert.equal(result.unavailable.length, 1);
+    assert.equal(result.unavailable[0].windowKey, "muse_account_usage");
+    assert.equal(result.unavailable[0].reason, "missing");
+});
+test("fake requires initialize before usage/read", async () => {
+    const child = spawn(process.execPath, [FAKE], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: { ...process.env, FAKE_MSP_MODE: "full", META_API_KEY: "test-fake-key" },
+    });
+    try {
+        const first = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new Error("timed out waiting for fake response")), 5000);
+            timer.unref?.();
+            let buf = "";
+            child.stdout.on("data", (chunk) => {
+                buf += chunk.toString();
+                const idx = buf.indexOf("\n");
+                if (idx >= 0) {
+                    clearTimeout(timer);
+                    resolve(buf.slice(0, idx));
+                }
+            });
+            child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: "bare-read", method: "usage/read", params: {} })}\n`);
+        });
+        const msg = JSON.parse(first);
+        assert.ok(msg.error, "bare usage/read is rejected before the handshake");
+        assert.match(String(msg.error?.message ?? ""), /initialize/i);
+    }
+    finally {
+        child.kill();
+    }
+});
 test("a malformed sibling window does not sink the good one", async () => {
     clearAllCapacitySnapshots();
     const { opts } = fakeOpts("partial-bad-weekly");
     const result = await readMuseCapacity(opts);
     assert.equal(result.windows.length, 1);
     assert.equal(result.windows[0].windowKey, "rolling_all_models");
+    assert.equal(result.windows[0].criticalRole, "five_hour");
     assert.equal(result.unavailable.length, 1);
     assert.equal(result.unavailable[0].windowKey, "weekly_all_models");
     assert.equal(result.unavailable[0].reason, "unparsable");
+    // NOT-264 review finding: the unavailable half must still carry its
+    // criticalRole, or the client can't find it and synthesizes a second,
+    // duplicate N/A row for the same half instead of one.
+    assert.equal(result.unavailable[0].criticalRole, "weekly");
+    const normalizedUnavailable = normalizeUnavailableWindow("muse_code", result.unavailable[0]);
+    assert.equal(normalizedUnavailable.criticalRole, "weekly");
 });
 async function expectUnavailable(mode, reason, extra = {}) {
     clearAllCapacitySnapshots();
@@ -223,53 +305,10 @@ test("no credential short-circuits to missing without spawning", async () => {
     assert.equal(result.windows.length, 0);
     assert.equal(result.unavailable[0].reason, "missing");
 });
-test("a successful refresh clears the failure sentinel", async () => {
-    clearAllCapacitySnapshots();
-    await refreshMuseCapacityFromServe(fakeOpts("crash").opts);
-    assert.deepEqual(listCapacitySnapshots("muse_code").map((w) => w.windowKey), ["muse_account_usage"]);
-    const snap = await refreshMuseCapacityFromServe(fakeOpts("full").opts);
-    const keys = listCapacitySnapshots("muse_code")
-        .map((w) => w.windowKey)
-        .sort();
-    assert.deepEqual(keys, ["rolling_all_models", "weekly_all_models"]);
-    const muse = snap.runtimes.find((r) => r.runtime === "muse_code");
-    assert.ok(muse);
-    assert.equal(muse.windows.length, 2);
-    assert.equal(muse.unavailableReason, null);
-});
-test("a read with every window unparsable clears the stale sentinel", async () => {
-    clearAllCapacitySnapshots();
-    await refreshMuseCapacityFromServe(fakeOpts("crash").opts);
-    assert.deepEqual(listCapacitySnapshots("muse_code").map((w) => w.windowKey), ["muse_account_usage"]);
-    const result = await readMuseCapacity(fakeOpts("all-bad-windows").opts);
-    assert.equal(result.windows.length, 0);
-    assert.ok(result.unavailable.length > 0);
-    assert.ok(result.unavailable.every((u) => u.windowKey !== "muse_account_usage"));
-    await refreshMuseCapacityFromServe(fakeOpts("all-bad-windows").opts);
-    const keys = listCapacitySnapshots("muse_code").map((w) => w.windowKey);
-    assert.ok(!keys.includes("muse_account_usage"), `stale sentinel cleared, got ${keys}`);
-    assert.ok(keys.length > 0, "per-window unparsable rows persist");
-});
-test("production refresh is throttled and can be disabled", async () => {
-    clearAllCapacitySnapshots();
-    resetMuseCapacityRefreshState();
-    const { opts } = fakeOpts("full");
-    try {
-        assert.equal(museRefreshThrottleMs(), 5 * 60 * 1000);
-        const first = await maybeRefreshMuseCapacityFromServe(opts);
-        assert.ok(first, "first refresh runs");
-        assert.equal(await maybeRefreshMuseCapacityFromServe(opts), null, "second refresh throttled");
-        process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS = "off";
-        resetMuseCapacityRefreshState();
-        assert.equal(await maybeRefreshMuseCapacityFromServe(opts), null, "refresh disabled");
-        process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS = "garbage";
-        assert.equal(museRefreshThrottleMs(), 5 * 60 * 1000);
-    }
-    finally {
-        delete process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS;
-        resetMuseCapacityRefreshState();
-    }
-});
+// NOT-270: the one-shot production poll is retired (see muse-host.test.ts
+// for the owned-host refresh, sentinel, and throttle coverage). The adapter
+// read primitive above stays unit-tested; production ingest moved to
+// `ingestMuseUsagePayload` newest-observedAtMs-wins.
 test("no token, tier, or raw account payload reaches the adapter output", async () => {
     const { opts } = fakeOpts("full");
     const result = await readMuseCapacity(opts);

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

@@ -47,6 +47,7 @@ export async function ingestAdapterResult(result) {
         source: w.source,
         unavailableReason: w.unavailableReason,
         evidenceRef: w.evidenceRef,
+        criticalRole: w.criticalRole,
     })));
 }
 /** Classify a stored window at read time (freshness/expiry/reset, not just flags). */

package/bundle/server/dist/coordinator/muse-spawn.js

@@ -25,8 +25,19 @@ import { resolveMuseAuthFile, resolveMuseBin } from "../cli-env.js";
 import { ensureWorktreeExcluded } from "../adapters/worktree-exclude.js";
 import { buildMuseDeveloperInvocation } from "../runners/muse-code-args.js";
 import { buildMuseDeveloperSettings } from "../runners/muse-code-settings.js";
-import { parseMuseRun } from "../runners/muse-code-jsonl.js";
+import { normalizeMuseRun, parseMuseRun, } from "../runners/muse-code-jsonl.js";
+import { runMuseServeTurn } from "../runners/muse-serve-session.js";
 import { spawnCli } from "../runners/spawn-cli.js";
+/**
+ * NOT-270: execution lane selection. Default is the server-owned serve host
+ * (real turns through it are the NOT-269 precondition for 5H/1W capacity).
+ * `AGENT_DEALER_MUSE_RUNNER=exec` forces the legacy `muse exec` subprocess
+ * lane — the operator escape hatch if the serve lane ever misbehaves in
+ * production (capacity then reads honest N/A until serve runs again).
+ */
+function museServeLaneEnabled() {
+    return process.env.AGENT_DEALER_MUSE_RUNNER !== "exec";
+}
 /** Worktree-relative home of every per-attempt Muse config/data dir. */
 export const MUSE_ATTEMPT_ROOT = ".dealer-muse";
 /**
@@ -103,9 +114,136 @@ function splitSpawnLog(raw) {
         ? { stdout: raw, stderr: "" }
         : { stdout: raw.slice(0, idx), stderr: raw.slice(idx + STDERR_MARKER.length) };
 }
+/**
+ * NOT-270: reuse real Dealer Muse work as the observation opportunity. After
+ * a genuine Muse session ends, kick one bounded, best-effort refresh
+ * through the server-owned serve host — the proven safe point for the final
+ * `usage/read`. This deliberately bypasses the GET-route throttle
+ * (`maybeRefreshMuseCapacityFromHost` shares it): the final read at the
+ * safe point is contractual, not opportunistic — a recent Agents-page poll
+ * must never skip it. This creates no model turn of its own (the capacity
+ * client only ever sends the read-only handshake/`usage/read` allowlist)
+ * and never affects the session result. Serve-lane turns observed the host,
+ * so this hook is the final read that populates 5H/1W; after an exec-lane
+ * fallback the host stays unobserved by construction (the NOT-269
+ * structural precondition) and the read stays honest N/A with last-good
+ * rows preserved.
+ */
+function refreshMuseCapacityAfterSession() {
+    void (async () => {
+        try {
+            const [{ configuredCapacityRuntimes }, { refreshMuseCapacityFromHost }] = await Promise.all([import("../capacity/service.js"), import("../capacity/muse-host.js")]);
+            if (!configuredCapacityRuntimes().includes("muse_code"))
+                return;
+            await refreshMuseCapacityFromHost();
+        }
+        catch {
+            // Best-effort: capacity must never break or delay a session result.
+        }
+    })();
+}
+/**
+ * NOT-270: run the real developer turn through the server-owned serve host.
+ * Returns null when no turn was admitted (host unavailable, session/start
+ * or turn/start rejected) — the caller then runs the legacy `muse exec`
+ * lane. Never returns null after admission: an admitted turn is real work
+ * and its verdict is reported honestly, never retried on the other lane.
+ *
+ * The serve lane needs no per-attempt XDG config/data dirs: the host runs
+ * under its own server-owned home (`prepareMuseServeHome` in
+ * capacity/muse-host.ts — same worker settings as the exec lane's
+ * per-attempt settings.json plus a symlink to the ambient login, so runner
+ * and capacity can never diverge on identity or posture). `onSpawn` is
+ * deliberately not called: there is no per-attempt pid to persist, and
+ * recovery must never treat the shared host as an attempt process.
+ */
+async function runMuseServeLane(input, model, onAdmitted) {
+    const { getMuseCapacityHost } = await import("../capacity/muse-host.js");
+    // Only this call may fall back: it resolves `admitted:false` (or throws)
+    // strictly before any model work starts. Everything below runs after
+    // admission — the caller's no-double-execution rule (via onAdmitted)
+    // keeps those errors loud instead of falling back to exec.
+    const turn = await runMuseServeTurn({
+        host: getMuseCapacityHost(),
+        prompt: input.prompt,
+        model,
+        cwd: input.cwd,
+        timeoutMs: input.timeoutMs,
+        signal: input.signal,
+        onAdmitted: () => onAdmitted(),
+    });
+    if (!turn.admitted)
+        return null;
+    const cronCalls = turn.tools
+        .map((t) => t.name)
+        .filter((n) => n !== null && CRON_TOOL_RE.test(n));
+    const summary = {
+        museSessionId: turn.sessionId ?? randomUUID(),
+        confirmedModel: turn.confirmedModel,
+        usage: turn.usage,
+        failure: turn.failure,
+        cronCalls,
+        runCount: 1,
+        rawLogPath: null,
+    };
+    // Same normalized evidence both lanes write: the raw folded history, then
+    // the Claude/Cursor-shaped stream every existing log reader consumes.
+    const rawLogPath = `${input.logPath.replace(/\.ndjson$/, "")}.muse-raw.jsonl`;
+    try {
+        fs.writeFileSync(rawLogPath, `${turn.viewItems.map((i) => JSON.stringify(i)).join("\n")}\n`);
+        summary.rawLogPath = rawLogPath;
+    }
+    catch {
+        // evidence copy is best-effort; the normalized log below still carries the outcome
+    }
+    const events = normalizeMuseRun({
+        sessionId: summary.museSessionId,
+        confirmedModel: turn.confirmedModel,
+        tools: turn.tools,
+        finalText: turn.finalText,
+        usage: turn.usage,
+        failure: turn.failure,
+    }).map((e) => e.type === "result" ? { ...e, muse: { ...summary, usage: turn.usage } } : e);
+    fs.writeFileSync(input.logPath, `${events.map((e) => JSON.stringify(e)).join("\n")}\n`);
+    // The real session above is the observation opportunity: kick the
+    // best-effort capacity refresh (no synthetic turn, never throws, never
+    // blocks this result).
+    refreshMuseCapacityAfterSession();
+    // A failed session must not read as success. 124 mirrors spawn-cli's
+    // timeout exit so timeout handling downstream sees the same signal.
+    const exitCode = turn.timedOut ? 124 : turn.failure ? 1 : turn.terminal === "completed" ? 0 : 1;
+    return {
+        exitCode,
+        transcript: turn.finalText ?? "",
+        logPath: input.logPath,
+        timedOut: turn.timedOut,
+        muse: summary,
+    };
+}
 export async function runMuseDeveloperSession(input) {
     const model = input.model ?? MUSE_CODE_CONTRIBUTOR_MODEL;
     const museSessionId = randomUUID();
+    // Serve-first: real turns through the owned host observe it (NOT-269
+    // precondition for 5H/1W). Pre-admission failure falls back to exec; an
+    // admitted turn never falls back — its errors propagate loudly instead of
+    // executing the work a second time on the exec lane.
+    // `AGENT_DEALER_MUSE_RUNNER=exec` skips the serve lane entirely
+    // (operator escape hatch).
+    if (museServeLaneEnabled()) {
+        let admitted = false;
+        try {
+            const served = await runMuseServeLane(input, model, () => {
+                admitted = true;
+            });
+            if (served)
+                return served;
+        }
+        catch (err) {
+            if (admitted)
+                throw err;
+            // Pre-admission serve-lane error: fall through to the exec lane below.
+        }
+    }
     const invocation = buildMuseDeveloperInvocation({
         model,
         maxModelSteps: input.maxModelSteps ?? DEFAULT_MUSE_MAX_MODEL_STEPS,
@@ -159,6 +297,10 @@ export async function runMuseDeveloperSession(input) {
     }
     const events = run.events.map((e) => e.type === "result" ? { ...e, muse: { ...summary, usage: run.usage } } : e);
     fs.writeFileSync(logPath, `${events.map((e) => JSON.stringify(e)).join("\n")}\n${stderr.trim() ? `${STDERR_MARKER}${stderr}` : ""}`);
+    // The real session above is the observation opportunity: kick the
+    // best-effort capacity refresh (no synthetic turn, never throws, never
+    // blocks this result).
+    refreshMuseCapacityAfterSession();
     return {
         // A failed session must not read as success just because Muse exited 0 (wrong model, no terminal event).
         exitCode: run.failure && spawned.exitCode === 0 ? 1 : spawned.exitCode,

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

@@ -389,6 +389,11 @@ export function migrate() {
         ON runtime_capacity_snapshots(runtime);
     `);
     }
+    // NOT-264 repair: critical_role on a table that predates it.
+    const capacityCols = db.prepare("PRAGMA table_info(runtime_capacity_snapshots)").all();
+    if (!capacityCols.some((c) => c.name === "critical_role")) {
+        db.exec("ALTER TABLE runtime_capacity_snapshots ADD COLUMN critical_role TEXT");
+    }
     // NOT-249: normalized Cursor-team billing snapshot for databases created
     // before schema.sql declared the table (same upgrade-path pattern as
     // runtime_capacity_snapshots above).
@@ -433,6 +438,31 @@ export function migrate() {
             db.exec("ALTER TABLE cursor_team_billing_snapshots ADD COLUMN member_limit_override_count REAL");
         }
     }
+    // NOT-250: normalized Cursor-individual billing snapshot for databases
+    // created before schema.sql declared the table (same upgrade-path pattern
+    // as cursor_team_billing_snapshots above).
+    const cursorIndividualBilling = db
+        .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'cursor_individual_billing_snapshots'")
+        .get();
+    if (!cursorIndividualBilling) {
+        db.exec(`
+      CREATE TABLE cursor_individual_billing_snapshots (
+        id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
+        cycle_label TEXT,
+        cycle_start TEXT,
+        cycle_end TEXT,
+        usage_value REAL,
+        usage_unit TEXT,
+        remaining_percent REAL,
+        source TEXT NOT NULL,
+        unavailable_reason TEXT,
+        observed_at TEXT NOT NULL,
+        fresh_until TEXT,
+        expires_at TEXT,
+        evidence_ref TEXT
+      );
+    `);
+    }
     // NOT-103: sequential issue admission queue.
     const queueEntries = db
         .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'queue_entries'")

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

@@ -400,6 +400,12 @@ CREATE TABLE IF NOT EXISTS runtime_capacity_snapshots (
   source TEXT NOT NULL,
   unavailable_reason TEXT,
   evidence_ref TEXT,
+  -- NOT-264 repair: which account-wide critical window this is ('five_hour'
+  -- / 'weekly'), set once by the adapter that knows the provider's own
+  -- identity (e.g. Codex's rateLimits aggregate, or the detailed limit pair
+  -- it collapsed into) — never re-derived client-side from a window key or
+  -- label, which cannot disambiguate multiple same-duration buckets.
+  critical_role TEXT,
   PRIMARY KEY (runtime, window_key)
 );
 
@@ -431,6 +437,27 @@ CREATE TABLE IF NOT EXISTS cursor_team_billing_snapshots (
   evidence_ref TEXT
 );
 
+-- NOT-250: normalized Cursor-individual billing snapshot (single row, id = 1).
+-- Experimental dashboard billing-cycle state, not per-runtime quota windows:
+-- independent of both runtime_capacity_snapshots and runtime_availability
+-- (NOT-111 health). Carries normalized values plus a static evidence pointer
+-- only — never credential material.
+CREATE TABLE IF NOT EXISTS cursor_individual_billing_snapshots (
+  id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1),
+  cycle_label TEXT,
+  cycle_start TEXT,
+  cycle_end TEXT,
+  usage_value REAL,
+  usage_unit TEXT,
+  remaining_percent REAL,
+  source TEXT NOT NULL,
+  unavailable_reason TEXT,
+  observed_at TEXT NOT NULL,
+  fresh_until TEXT,
+  expires_at TEXT,
+  evidence_ref TEXT
+);
+
 -- NOT-111: account-level runtime usage caps (keyed per runtime, not per agent profile).
 CREATE TABLE IF NOT EXISTS runtime_availability (
   runtime TEXT PRIMARY KEY,

package/bundle/server/dist/index.js

@@ -10,6 +10,7 @@ import { registerQueueRoutes } from "./routes/queue.js";
 import { registerHumanActionRoutes } from "./routes/human-actions.js";
 import { registerExecutionAnalysisRoutes } from "./routes/execution-analysis.js";
 import { registerExecutionReportRoutes } from "./routes/execution-report.js";
+import { registerRepositoryMappingsRoutes } from "./routes/repository-mappings.js";
 import { recoverCoordinator } from "./coordinator/recovery.js";
 import { startCoordinatorLoop } from "./coordinator/worker-loop.js";
 import { startLinearUsageSummary } from "./adapters/linear-graphql.js";
@@ -45,13 +46,26 @@ async function main() {
             "Stop it first, or point AGENT_DEALER_HOME at a different directory.");
         process.exit(1);
     }
+    // NOT-270: the server-owned Muse capacity host (`muse serve` child) must
+    // be released on shutdown — it is spawned with piped stdio, is not
+    // detached, and must not be assumed to exit on stdin EOF. Every handler
+    // below shuts it down before exiting so no host process leaks.
+    const shutdownCapacityHosts = async () => {
+        try {
+            const { shutdownMuseCapacityHost } = await import("./capacity/muse-host.js");
+            await shutdownMuseCapacityHost();
+        }
+        catch {
+            // Best-effort: shutdown must never block process exit.
+        }
+    };
     process.on("SIGINT", () => {
         removeServerPidFile();
-        process.exit(0);
+        void shutdownCapacityHosts().finally(() => process.exit(0));
     });
     process.on("SIGTERM", () => {
         removeServerPidFile();
-        process.exit(0);
+        void shutdownCapacityHosts().finally(() => process.exit(0));
     });
     process.on("exit", removeServerPidFile);
     migrate();
@@ -64,6 +78,7 @@ async function main() {
     await registerHumanActionRoutes(app);
     await registerExecutionAnalysisRoutes(app);
     await registerExecutionReportRoutes(app);
+    await registerRepositoryMappingsRoutes(app);
     const uiDist = await registerStaticUi(app);
     // Without this, getEffectHandler() falls back to the always-session_failed placeholders
     // (effect-registry.ts) and every started issue would burn its infra retries and

package/bundle/server/dist/repository/cursor-individual-billing.js

@@ -0,0 +1,84 @@
+// packages/server/src/repository/cursor-individual-billing.ts
+//
+// NOT-250: durable normalized Cursor-individual billing snapshot. Single-row
+// table (`id = 1`): the experimental dashboard adapter reports one
+// billing-cycle state, not per-window readings. Independent of
+// `runtime_availability` (NOT-111 connection health) and written alongside
+// (never instead of) `runtime_capacity_snapshots` — nothing here reads or
+// writes either table.
+//
+// Credential hygiene: this table carries normalized billing values and a
+// static evidence pointer only. The raw local-login token must never be
+// written here — the adapter never passes it to this module, and tests scan
+// stored rows for fixture secrets.
+import { getDb } from "../db/index.js";
+function rowToSnapshot(row) {
+    return {
+        cycleLabel: row.cycle_label,
+        cycleStart: row.cycle_start,
+        cycleEnd: row.cycle_end,
+        usageValue: row.usage_value,
+        usageUnit: row.usage_unit,
+        remainingPercent: row.remaining_percent,
+        source: row.source,
+        unavailableReason: row.unavailable_reason,
+        observedAt: row.observed_at,
+        freshUntil: row.fresh_until,
+        expiresAt: row.expires_at,
+        evidenceRef: row.evidence_ref,
+    };
+}
+/** Upsert the latest normalized individual billing observation (single row). */
+export function writeCursorIndividualBillingRow(input) {
+    getDb()
+        .prepare(`
+    INSERT INTO cursor_individual_billing_snapshots (
+      id, cycle_label, cycle_start, cycle_end, usage_value, usage_unit,
+      remaining_percent, source, unavailable_reason,
+      observed_at, fresh_until, expires_at, evidence_ref
+    )
+    VALUES (
+      1, @cycle_label, @cycle_start, @cycle_end, @usage_value, @usage_unit,
+      @remaining_percent, @source, @unavailable_reason,
+      @observed_at, @fresh_until, @expires_at, @evidence_ref
+    )
+    ON CONFLICT(id) DO UPDATE SET
+      cycle_label = excluded.cycle_label,
+      cycle_end = excluded.cycle_end,
+      cycle_start = excluded.cycle_start,
+      usage_value = excluded.usage_value,
+      usage_unit = excluded.usage_unit,
+      remaining_percent = excluded.remaining_percent,
+      source = excluded.source,
+      unavailable_reason = excluded.unavailable_reason,
+      observed_at = excluded.observed_at,
+      fresh_until = excluded.fresh_until,
+      expires_at = excluded.expires_at,
+      evidence_ref = excluded.evidence_ref
+  `)
+        .run({
+        cycle_label: input.cycleLabel,
+        cycle_start: input.cycleStart,
+        cycle_end: input.cycleEnd,
+        usage_value: input.usageValue,
+        usage_unit: input.usageUnit,
+        remaining_percent: input.remainingPercent,
+        source: input.source,
+        unavailable_reason: input.unavailableReason,
+        observed_at: input.observedAt,
+        fresh_until: input.freshUntil,
+        expires_at: input.expiresAt,
+        evidence_ref: input.evidenceRef,
+    });
+}
+/** The latest normalized individual billing observation, if any. */
+export function readCursorIndividualBillingRow() {
+    const row = getDb()
+        .prepare("SELECT * FROM cursor_individual_billing_snapshots WHERE id = 1")
+        .get();
+    return row ? rowToSnapshot(row) : null;
+}
+/** Test helper — clear the individual billing snapshot (leaves all other tables alone). */
+export function clearCursorIndividualBilling() {
+    getDb().exec("DELETE FROM cursor_individual_billing_snapshots");
+}