agent-dealer 1.2.1 → 1.2.2

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

@@ -1,29 +1,31 @@
 // packages/server/src/capacity/muse.ts
 //
 // NOT-247: Muse Code capacity adapter — read stable MSP usage windows.
+// NOT-263: handshake repaired against the stable schema embedded in the
+// shipped binary (`muse schema generate-json-schema`).
 //
-// Reads observed capacity through the versioned `muse serve` Session Protocol
-// (MSP 1.3) without sending a prompt and without consuming model tokens: a
-// single `usage/read` JSON-RPC request over a one-shot managed `muse serve`
-// stdio connection, then shutdown. `usage/changed` notifications received
-// while the connection is alive are recorded. The client enforces a read-only
-// allowlist (`usage/read`) — any other method throws before it is written, so
-// polling can never start a session, send a prompt, or run model work. It
-// never touches the Keychain or undocumented endpoints.
+// Reads observed capacity through the stable Muse Session Protocol without
+// sending a prompt and without consuming model tokens: `muse serve` over a
+// one-shot managed stdio connection, then `initialize` → `initialized` → one
+// `usage/read`, then shutdown. `usage/changed` notifications received while
+// the connection is alive are recorded. The client enforces a read-only
+// allowlist (`initialize`, `initialized`, `usage/read`) — any other method
+// throws before it is written, so polling can never start a session, send a
+// prompt, or run model work. It never touches the Keychain or undocumented
+// endpoints.
 //
-// MSP 1.3 `usage/read` shape (per the contract):
+// Stable `usage/read` shape:
 //   result: {
-//     protocol: "msp/1.3",
 //     usage?: {
 //       observedAtMs: number,
 //       tier: string,                       // dropped: never persisted, never served
-//       rolling?: { usedPercent, resetsAtMs, windowDurationMins },
+//       window?: { usedPercent, resetsAtMs, windowDurationMins },
 //       weekly?: { usedPercent, resetsAtMs }
 //     }
 //   }
 // `usage` may be omitted when Muse has no observation — preserved as N/A
-// (`missing`). The rolling label is derived from `windowDurationMins` by the
-// shared normalization, never hardcoded.
+// (`missing`). The rolling (`window`) label is derived from
+// `windowDurationMins` by the shared normalization, never hardcoded.
 //
 // Failure semantics (shared CapacityUnavailableReason enum only):
 // - No credential (no META_API_KEY and no login file) / `usage` omitted /
@@ -42,7 +44,16 @@ import { MUSE_CLI_ENV, resolveMuseAuthFile, resolveMuseBin } from "../cli-env.js
 import { normalizeAdapterWindow, normalizeUnavailableWindow, } from "./adapter.js";
 export const MUSE_RUNTIME = "muse_code";
 /** Methods this client may ever send. Anything else throws before write. */
-export const MSP_READ_ONLY_METHODS = ["usage/read"];
+export const MSP_READ_ONLY_METHODS = ["initialize", "initialized", "usage/read"];
+/**
+ * Client identity sent in the `initialize` handshake. The stable schema
+ * requires `clientInfo.name` to match `^[a-z0-9_]+$` plus a version string.
+ * Version is kept in sync with `packages/server/package.json`.
+ */
+export const MUSE_CLIENT_INFO = {
+    name: "agent_dealer",
+    version: "1.2.1",
+};
 /** Notification the client records (never sends) while connected. */
 export const MSP_USAGE_CHANGED = "usage/changed";
 /** Methods that would start billable model work — never sent, asserted in tests. */
@@ -61,21 +72,18 @@ function readOnlyRequest(id, method, params) {
     assertMuseReadOnlyMethod(method);
     return `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
 }
+function readOnlyNotification(method, params) {
+    assertMuseReadOnlyMethod(method);
+    return `${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`;
+}
 /**
- * Versioned Session Protocol argv. Fixed: capacity reads never `exec`.
- *
- * Caveat: this argv and the handshake-free single `usage/read` below were
- * built from the ticket contract brief — the official Muse Code docs were
- * unreachable at implementation time, so they are unverified against the
- * published MSP surface. The committed fake (`fixtures/fake-muse-serve.mjs`)
- * likewise enforces no handshake, so tests cannot catch a handshake
- * requirement either. If a live `muse serve` demands an `initialize` step,
- * the read-only allowlist will reject it and every live read will fail
- * closed as `missing`/`unparsable` (never billed); re-check the argv against
- * the docs before debugging any live failure.
+ * Stable Session Protocol argv. Fixed: capacity reads never `exec`, and the
+ * host takes no `--protocol` flag — `muse serve` with that flag exits 2
+ * against the shipped binary, so this stays exactly `["serve"]`.
  */
-export const MUSE_SERVE_ARGV = ["serve", "--protocol", "msp/1.3"];
-/** Single JSON-RPC request id for the one-shot read. */
+export const MUSE_SERVE_ARGV = ["serve"];
+/** JSON-RPC request ids for the one-shot read (init handshake, then usage). */
+export const MSP_INITIALIZE_ID = "muse-capacity-init";
 export const MSP_USAGE_READ_ID = "muse-capacity-1";
 /** Weekly windows carry no duration in MSP 1.3; a week in minutes. */
 export const MUSE_WEEKLY_DURATION_MINUTES = 10080;
@@ -133,6 +141,9 @@ function windowReadingFromEntry(kind, entry, observedAt) {
         resetAt,
         observedAt,
         source: "supported_protocol",
+        // Muse reports exactly this one rolling/weekly pair — it is always the
+        // account-wide critical window, never a model-specific extra.
+        criticalRole: kind === "rolling" ? "five_hour" : "weekly",
     };
 }
 /**
@@ -153,7 +164,7 @@ function extractUsageObject(payload) {
             return { error: "usage is not an object" };
         return { usage: usage };
     }
-    if ("observedAtMs" in result || "rolling" in result || "weekly" in result) {
+    if ("observedAtMs" in result || "window" in result || "rolling" in result || "weekly" in result) {
         return { usage: result };
     }
     const keys = Object.keys(result);
@@ -162,25 +173,27 @@ function extractUsageObject(payload) {
     return { error: "result carries no usage observation" };
 }
 /**
- * Normalize MSP 1.3 `usage` into adapter readings. Returns null when the
- * payload carries no observation or is malformed (callers needing the
- * distinction check the payload shape first). Entries that are individually
- * malformed are skipped — the caller re-reports present-but-bad keys as
- * per-window `unparsable` readings so a bad sibling never sinks a good
- * window.
+ * Normalize stable `usage` into adapter readings. The rolling window arrives
+ * as `usage.window` (a legacy `usage.rolling` spelling is tolerated and maps
+ * to the same `rolling_all_models` snapshot). Returns null when the payload
+ * carries no observation or is malformed (callers needing the distinction
+ * check the payload shape first). Entries that are individually malformed
+ * are skipped — the caller re-reports present-but-bad keys as per-window
+ * `unparsable` readings so a bad sibling never sinks a good window.
  */
 export function museUsageToReadings(payload, observedAt = new Date().toISOString()) {
     const { usage, error } = extractUsageObject(payload);
     if (error !== undefined || usage === undefined)
         return null;
     const u = usage;
-    const hasRolling = u.rolling !== undefined;
+    const rollingEntry = u.window !== undefined ? u.window : u.rolling;
+    const hasRolling = rollingEntry !== undefined;
     const hasWeekly = u.weekly !== undefined;
     const observedAtMs = typeof u.observedAtMs === "number" && Number.isFinite(u.observedAtMs) ? u.observedAtMs : null;
     const observed = observedAtMs !== null ? new Date(observedAtMs).toISOString() : observedAt;
     const out = [];
     if (hasRolling) {
-        const rolling = windowReadingFromEntry("rolling", u.rolling, observed);
+        const rolling = windowReadingFromEntry("rolling", rollingEntry, observed);
         if (rolling)
             out.push(rolling);
     }
@@ -200,11 +213,15 @@ export function museBadWindowKinds(payload) {
     if (error !== undefined || usage === undefined)
         return [];
     const u = usage;
+    const entries = {
+        rolling: u.window !== undefined ? u.window : u.rolling,
+        weekly: u.weekly,
+    };
     const bad = [];
     for (const kind of ["rolling", "weekly"]) {
-        if (u[kind] === undefined)
+        if (entries[kind] === undefined)
             continue;
-        const probe = windowReadingFromEntry(kind, u[kind], new Date().toISOString());
+        const probe = windowReadingFromEntry(kind, entries[kind], new Date().toISOString());
         if (!probe)
             bad.push(kind);
     }
@@ -253,10 +270,11 @@ function hasMuseCredential(env, authFilePath) {
     }
 }
 /**
- * Spawn `muse serve`, send one `usage/read`, record any `usage/changed`
- * notifications, then shut the connection down. Never throws for
- * provider-side failures — those come back as `failure.kind`. Never sends
- * anything outside MSP_READ_ONLY_METHODS.
+ * Spawn `muse serve`, run the stable handshake (`initialize` with a
+ * `clientInfo` identity, then the `initialized` notification), send one
+ * `usage/read`, record any `usage/changed` notifications, then shut the
+ * connection down. Never throws for provider-side failures — those come back
+ * as `failure.kind`. Never sends anything outside MSP_READ_ONLY_METHODS.
  */
 export function requestMuseUsage(opts = {}) {
     const command = opts.command ?? resolveMuseBin();
@@ -272,6 +290,7 @@ export function requestMuseUsage(opts = {}) {
         let settled = false;
         let child;
         let buffer = "";
+        let initResolve = null;
         let readResolve = null;
         const finish = (out) => {
             if (settled)
@@ -298,7 +317,12 @@ export function requestMuseUsage(opts = {}) {
                     updates.push(msg.params ?? null);
                 return;
             }
-            if (msg.id === MSP_USAGE_READ_ID && readResolve) {
+            if (msg.id === MSP_INITIALIZE_ID && initResolve) {
+                const cb = initResolve;
+                initResolve = null;
+                cb(msg);
+            }
+            else if (msg.id === MSP_USAGE_READ_ID && readResolve) {
                 const cb = readResolve;
                 readResolve = null;
                 cb(msg);
@@ -361,6 +385,28 @@ export function requestMuseUsage(opts = {}) {
             }
         };
         void (async () => {
+            if (!write(readOnlyRequest(MSP_INITIALIZE_ID, "initialize", { clientInfo: { ...MUSE_CLIENT_INFO } }))) {
+                fail("unavailable");
+                return;
+            }
+            const init = await new Promise((res) => {
+                initResolve = res;
+            });
+            if (settled)
+                return;
+            if (!init || init.error) {
+                if (init?.error && errorLooksAuth(init.error))
+                    fail("unauthenticated");
+                else if (init?.error && init.error.code === -32601)
+                    fail("unsupported");
+                else
+                    fail("unavailable");
+                return;
+            }
+            if (!write(readOnlyNotification("initialized", {}))) {
+                fail("unavailable");
+                return;
+            }
             if (!write(readOnlyRequest(MSP_USAGE_READ_ID, "usage/read", {}))) {
                 fail("unavailable");
                 return;
@@ -504,6 +550,11 @@ export async function readMuseCapacity(opts = {}) {
             durationMinutes: kind === "weekly" ? MUSE_WEEKLY_DURATION_MINUTES : null,
             reason: "unparsable",
             observedAt,
+            // This unavailable reading still stands in for the account-wide
+            // critical half it replaces — untagging it would make the client
+            // synthesize a second, duplicate N/A row for the same half (NOT-264
+            // review finding).
+            criticalRole: kind === "rolling" ? "five_hour" : "weekly",
         });
     }
     if (windows.length === 0 && unavailable.length === 0) {

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

@@ -1,19 +1,23 @@
 // 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, museRefreshThrottleMs, museUsageToReadings, maybeRefreshMuseCapacityFromServe, normalizeMuseResetsAt, normalizeMuseUnavailable, readMuseCapacity, refreshMuseCapacityFromServe, requestMuseUsage, resetMuseCapacityRefreshState, } 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 { clearAllRuntimeAvailability, runtimeAvailability, } = await import("../repository/runtime-availability.js");
@@ -40,6 +44,14 @@ function fakeOpts(mode, extra = {}) {
         },
     };
 }
+test("serve argv is the shipping contract: no --protocol flag", () => {
+    assert.deepEqual([...MUSE_SERVE_ARGV], ["serve"]);
+    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();

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/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";
@@ -64,6 +65,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");
+}