agent-dealer 1.2.2 → 1.2.3

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

@@ -0,0 +1,480 @@
+// packages/server/src/capacity/muse-host.test.ts
+//
+// NOT-270: owned long-lived Muse host — fake-subprocess coverage only,
+// never a live model call. The fake replays the exact sanitized MSP shapes
+// captured by NOT-269 (`usage/read` result with the `window` + `weekly`
+// pair; `usage/changed` params carrying `SubscriptionUsage` directly).
+// All payload values are synthetic stand-ins, never account data.
+//
+// Proven lifecycle under test (docs/research/NOT-269-muse-5h-1w-lifecycle.md):
+// - one server-owned host per process; concurrent readers share it;
+// - `usage/changed` ingested as received, final `usage/read` on the same
+//   host, races resolved by newest `observedAtMs`;
+// - fresh-host `missing` never overwrites a newer known pair;
+// - restart/crash/timeout/auth preserve last-good rows and leak no child;
+// - recovery clears the failure sentinel;
+// - a capacity read never sends a session, prompt, turn, tool, or other
+//   billable method.
+import { test, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-host-"));
+import { getMuseCapacityHost, maybeRefreshMuseCapacityFromHost, MuseCapacityHost, prepareMuseServeHome, refreshMuseCapacityFromHost, resetMuseCapacityHostForTests, resetMuseCapacityRefreshState, shutdownMuseCapacityHost, } from "./muse-host.js";
+import { ingestMuseUsagePayload, museRefreshThrottleMs, noteMuseCapacityFailure, } from "./muse.js";
+const { migrate } = await import("../db/index.js");
+const { clearAllCapacitySnapshots, listCapacitySnapshots } = await import("../repository/runtime-capacity.js");
+const { getRuntimeCapacitySnapshot } = await import("./service.js");
+const FAKE = new URL("./fixtures/fake-muse-serve.mjs", import.meta.url).pathname;
+beforeEach(async () => {
+    migrate();
+    clearAllCapacitySnapshots();
+    await resetMuseCapacityHostForTests();
+});
+function hostOpts(mode, extra = {}) {
+    const now = Date.now();
+    return {
+        command: process.execPath,
+        args: [FAKE],
+        env: {
+            META_API_KEY: "test-fake-key",
+            FAKE_MSP_MODE: mode,
+            FAKE_MSP_NOW_MS: String(now),
+            ...(extra.env ?? {}),
+        },
+        timeoutMs: extra.timeoutMs ?? 10_000,
+    };
+}
+/** Synthetic stand-in observation (NOT-269 sanitized shape, not account data). */
+function pairPayload(observedAtMs, windowUsed, weeklyUsed) {
+    return {
+        protocol: "msp/1.3",
+        usage: {
+            observedAtMs,
+            tier: "synthetic-stand-in",
+            window: {
+                usedPercent: windowUsed,
+                resetsAtMs: observedAtMs + 2 * 3600_000,
+                windowDurationMins: 300,
+            },
+            weekly: { usedPercent: weeklyUsed, resetsAtMs: observedAtMs + 3 * 24 * 3600_000 },
+        },
+    };
+}
+function keys() {
+    return listCapacitySnapshots("muse_code").map((w) => w.windowKey).sort();
+}
+test("observed host refresh serves exactly the 5H+1W pair to the browser shape", async () => {
+    const snap = await refreshMuseCapacityFromHost({ ...hostOpts("persistent-full"), nowMs: Date.now() });
+    const muse = snap.runtimes.find((r) => r.runtime === "muse_code");
+    // The entry exists only when muse_code is configured; assert the stored
+    // rows directly so this stays independent of agent configuration.
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    assert.ok(!keys().includes("muse_account_usage"), "no sentinel beside valid windows");
+    const stored = listCapacitySnapshots("muse_code");
+    const rolling = stored.find((w) => w.windowKey === "rolling_all_models");
+    const weekly = stored.find((w) => w.windowKey === "weekly_all_models");
+    assert.equal(rolling.remainingPercent, 40);
+    assert.equal(weekly.remainingPercent, 75);
+    assert.equal(rolling.unavailableReason, null);
+    assert.equal(weekly.unavailableReason, null);
+    const served = getRuntimeCapacitySnapshot();
+    const raw = JSON.stringify(served);
+    assert.ok(!raw.includes("contributor"), "no tier metadata reaches the browser shape");
+    assert.ok(!raw.includes("muse_account_usage"), "no sentinel label reaches the browser shape");
+    // Stored rows guarantee the entry, so assert the exact served pair.
+    const servedMuse = served.runtimes.find((r) => r.runtime === "muse_code");
+    assert.ok(servedMuse, "muse_code entry served");
+    assert.deepEqual(servedMuse.windows.map((w) => w.windowKey).sort(), ["rolling_all_models", "weekly_all_models"]);
+    assert.ok(servedMuse.windows.every((w) => w.unavailableReason === null), "both served windows are known");
+    assert.equal(servedMuse.windows.find((w) => w.windowKey === "rolling_all_models")?.remainingPercent, 40, "served 5H matches the stored row");
+    assert.equal(servedMuse.windows.find((w) => w.windowKey === "weekly_all_models")?.remainingPercent, 75, "served 1W matches the stored row");
+    assert.equal(muse?.runtime, "muse_code");
+    await shutdownMuseCapacityHost();
+});
+test("snapshot labels and critical roles are exactly 5H/five_hour and 1W/weekly", async () => {
+    await refreshMuseCapacityFromHost({ ...hostOpts("persistent-full"), nowMs: Date.now() });
+    const stored = listCapacitySnapshots("muse_code");
+    const byKey = new Map(stored.map((w) => [w.windowKey, w]));
+    assert.equal(byKey.get("rolling_all_models").displayLabel, "5H");
+    assert.equal(byKey.get("rolling_all_models").criticalRole, "five_hour");
+    assert.equal(byKey.get("weekly_all_models").displayLabel, "1W");
+    assert.equal(byKey.get("weekly_all_models").criticalRole, "weekly");
+    await shutdownMuseCapacityHost();
+});
+test("host lifetime traffic is the handshake plus usage/read — never billable", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-host-record-"));
+    const recordPath = path.join(dir, "methods.jsonl");
+    const host = new MuseCapacityHost(hostOpts("persistent-full", { env: { FAKE_MSP_RECORD: recordPath } }));
+    try {
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.equal((await host.readUsage()).status, "observed");
+        const lines = fs
+            .readFileSync(recordPath, "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .map((l) => JSON.parse(l));
+        const methods = lines.map((l) => String(l.method));
+        // One handshake for the whole host lifetime, then one usage/read per refresh.
+        assert.deepEqual(methods, ["initialize", "initialized", "usage/read", "usage/read", "usage/read"]);
+        for (const m of methods) {
+            assert.ok(!/session|prompt|turn|exec|tool|message|thread/i.test(m), `billable method ${m}`);
+        }
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("concurrent readers share the one host connection", async () => {
+    const host = new MuseCapacityHost(hostOpts("persistent-full"));
+    try {
+        const results = await Promise.all([
+            host.readUsage(),
+            host.readUsage(),
+            host.readUsage(),
+            host.readUsage(),
+            host.readUsage(),
+        ]);
+        assert.ok(results.every((r) => r.status === "observed"));
+        assert.equal(host.connectionEpoch, 1, "exactly one host per concurrent burst");
+        assert.ok(host.isConnected());
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("fresh-host missing never overwrites or deletes a newer known pair", async () => {
+    await refreshMuseCapacityFromHost({ ...hostOpts("persistent-full"), nowMs: Date.now() });
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    await resetMuseCapacityHostForTests();
+    const outcome = await getMuseCapacityHost(hostOpts("persistent-missing")).readUsage();
+    assert.equal(outcome.status, "missing");
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    const stored = listCapacitySnapshots("muse_code");
+    assert.equal(stored.find((w) => w.windowKey === "rolling_all_models").remainingPercent, 40);
+    await shutdownMuseCapacityHost();
+});
+test("usage/changed and final usage/read races resolve by newest observedAtMs", async () => {
+    const now = Date.now();
+    const first = await ingestMuseUsagePayload(pairPayload(now, 42, 17));
+    assert.deepEqual(first.written.sort(), ["rolling_all_models", "weekly_all_models"]);
+    // An older finishing read cannot clobber the newer rows.
+    const older = await ingestMuseUsagePayload(pairPayload(now - 60_000, 90, 90));
+    assert.deepEqual(older.written, []);
+    assert.deepEqual(older.skippedStale.sort(), ["rolling_all_models", "weekly_all_models"]);
+    const stored = listCapacitySnapshots("muse_code");
+    assert.equal(stored.find((w) => w.windowKey === "rolling_all_models").remainingPercent, 58);
+    assert.equal(stored.find((w) => w.windowKey === "weekly_all_models").remainingPercent, 83);
+    // A newer observation still wins afterwards.
+    const newer = await ingestMuseUsagePayload(pairPayload(now + 60_000, 10, 10));
+    assert.deepEqual(newer.written.sort(), ["rolling_all_models", "weekly_all_models"]);
+    const after = listCapacitySnapshots("muse_code");
+    assert.equal(after.find((w) => w.windowKey === "rolling_all_models").remainingPercent, 90);
+});
+test("bare usage/changed params ingest without a {usage} envelope", async () => {
+    const now = Date.now();
+    const params = {
+        observedAtMs: now,
+        tier: "synthetic-stand-in",
+        window: { usedPercent: 42, resetsAtMs: now + 3600_000, windowDurationMins: 300 },
+        weekly: { usedPercent: 17, resetsAtMs: now + 24 * 3600_000 },
+    };
+    const outcome = await ingestMuseUsagePayload(params);
+    assert.deepEqual(outcome.written.sort(), ["rolling_all_models", "weekly_all_models"]);
+});
+test("a same-stamp malformed sibling never relabels the valid half", async () => {
+    const now = Date.now();
+    await ingestMuseUsagePayload(pairPayload(now, 42, 17));
+    const partial = {
+        usage: {
+            observedAtMs: now,
+            tier: "synthetic-stand-in",
+            window: { usedPercent: 42, resetsAtMs: now + 3600_000, windowDurationMins: 300 },
+            weekly: { usedPercent: "high", resetsAtMs: now + 24 * 3600_000 },
+        },
+    };
+    const outcome = await ingestMuseUsagePayload(partial);
+    const stored = listCapacitySnapshots("muse_code");
+    const weekly = stored.find((w) => w.windowKey === "weekly_all_models");
+    assert.equal(weekly.remainingPercent, 83, "valid weekly row keeps its value");
+    assert.equal(weekly.unavailableReason, null, "no diagnostic relabels the valid half");
+    assert.ok(!outcome.written.includes("weekly_all_models"));
+});
+test("empty payload ingests nothing and deletes nothing", async () => {
+    const now = Date.now();
+    await ingestMuseUsagePayload(pairPayload(now, 42, 17));
+    const outcome = await ingestMuseUsagePayload({ protocol: "msp/1.3" });
+    assert.deepEqual(outcome.written, []);
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+});
+test("crash preserves last-good rows and writes no sentinel beside them", async () => {
+    const host = new MuseCapacityHost(hostOpts("persistent-full"));
+    try {
+        assert.equal((await host.readUsage()).status, "observed");
+    }
+    finally {
+        await host.shutdown();
+    }
+    await resetMuseCapacityHostForTests();
+    const crashed = new MuseCapacityHost(hostOpts("crash", { timeoutMs: 3000 }));
+    try {
+        const outcome = await crashed.readUsage();
+        assert.equal(outcome.status, "missing");
+        assert.ok(!crashed.isConnected(), "dead child released, none leaked");
+    }
+    finally {
+        await crashed.shutdown();
+    }
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+});
+test("timeout kills the hung child and preserves last-good rows", async () => {
+    await ingestMuseUsagePayload(pairPayload(Date.now(), 42, 17));
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    const host = new MuseCapacityHost(hostOpts("hang", { timeoutMs: 400 }));
+    try {
+        const outcome = await host.readUsage();
+        assert.equal(outcome.status, "missing");
+        assert.ok(!host.isConnected(), "hung child killed, none leaked");
+    }
+    finally {
+        await host.shutdown();
+    }
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    const stored = listCapacitySnapshots("muse_code");
+    assert.equal(stored.find((w) => w.windowKey === "rolling_all_models").remainingPercent, 58);
+});
+test("auth failure reads missing and preserves last-good rows", async () => {
+    await ingestMuseUsagePayload(pairPayload(Date.now(), 42, 17));
+    const host = new MuseCapacityHost(hostOpts("auth-error", { timeoutMs: 5000 }));
+    try {
+        assert.equal((await host.readUsage()).status, "missing");
+    }
+    finally {
+        await host.shutdown();
+    }
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+});
+test("failure with no known rows persists the sentinel; recovery clears it", async () => {
+    const bad = new MuseCapacityHost(hostOpts("crash", { timeoutMs: 3000 }));
+    try {
+        assert.equal((await bad.readUsage()).status, "missing");
+    }
+    finally {
+        await bad.shutdown();
+    }
+    assert.deepEqual(keys(), ["muse_account_usage"]);
+    await resetMuseCapacityHostForTests();
+    const snap = await refreshMuseCapacityFromHost({
+        ...hostOpts("persistent-full"),
+        nowMs: Date.now(),
+    });
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    assert.ok(snap !== null);
+    await shutdownMuseCapacityHost();
+});
+test("noteMuseCapacityFailure never sits beside valid windows", async () => {
+    assert.equal(await noteMuseCapacityFailure("missing"), "sentinel");
+    assert.deepEqual(keys(), ["muse_account_usage"]);
+    await ingestMuseUsagePayload(pairPayload(Date.now(), 42, 17));
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    assert.equal(await noteMuseCapacityFailure("missing"), "preserved");
+    assert.equal(await noteMuseCapacityFailure("unsupported"), "preserved");
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+});
+test("failure never adds a sentinel beside per-window unparsable rows", async () => {
+    const now = Date.now();
+    const outcome = await ingestMuseUsagePayload({
+        usage: {
+            observedAtMs: now,
+            tier: "synthetic-stand-in",
+            window: { usedPercent: "high", resetsAtMs: now + 3600_000, windowDurationMins: 300 },
+            weekly: { usedPercent: "high", resetsAtMs: now + 24 * 3600_000 },
+        },
+    });
+    assert.deepEqual(outcome.written.sort(), ["rolling_all_models", "weekly_all_models"]);
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+    const stored = listCapacitySnapshots("muse_code");
+    assert.ok(stored.every((w) => w.unavailableReason === "unparsable"), "both halves are per-window diagnostics");
+    assert.equal(await noteMuseCapacityFailure("missing"), "preserved");
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+});
+test("restart after observation restarts empty and re-observes", async () => {
+    const host = new MuseCapacityHost(hostOpts("exit-after-first-read"));
+    try {
+        assert.equal((await host.readUsage()).status, "observed");
+        const firstEpoch = host.connectionEpoch;
+        assert.equal(firstEpoch, 1);
+        const deadline = Date.now() + 8000;
+        while (host.isConnected() && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 25));
+        }
+        assert.ok(!host.isConnected(), "exited child detected, none leaked");
+        // Next read transparently restarts (state lost — the restarted fake
+        // re-observes, proving the host recovers without a second host).
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.equal(host.connectionEpoch, 2);
+        assert.ok(host.isConnected());
+    }
+    finally {
+        await host.shutdown();
+    }
+    assert.deepEqual(keys(), ["rolling_all_models", "weekly_all_models"]);
+});
+test("a stale child's late close cannot kill its replacement", async () => {
+    const host = new MuseCapacityHost(hostOpts("slow-term-full"));
+    try {
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.equal(host.connectionEpoch, 1);
+        // Shut down (SIGTERMs the slow child: it exits ~500 ms later) and
+        // restart immediately — the stale `close` lands on the live host.
+        await host.shutdown();
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.equal(host.connectionEpoch, 2);
+        await new Promise((r) => setTimeout(r, 900));
+        assert.ok(host.isConnected(), "stale close did not kill the replacement");
+        assert.equal(host.connectionEpoch, 2, "no second host per restart");
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.equal(host.connectionEpoch, 2, "replacement serves reads itself");
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("clean shutdown releases the child process", async () => {
+    const host = new MuseCapacityHost(hostOpts("persistent-full"));
+    assert.equal((await host.readUsage()).status, "observed");
+    assert.ok(host.isConnected());
+    await host.shutdown();
+    assert.ok(!host.isConnected(), "no host process left behind");
+});
+test("an unobserved host is released after the read — no lifetime child that can only answer missing", async () => {
+    const host = new MuseCapacityHost(hostOpts("persistent-missing"));
+    try {
+        assert.equal((await host.readUsage()).status, "missing");
+        assert.ok(!host.isConnected(), "unobserved host released, none parked");
+        // The next refresh transparently respawns (state was empty anyway).
+        assert.equal((await host.readUsage()).status, "missing");
+        assert.equal(host.connectionEpoch, 2, "respawned on demand, still one host at a time");
+        assert.ok(!host.isConnected(), "still-unobserved host released again");
+    }
+    finally {
+        await host.shutdown();
+    }
+    // Releasing the empty host never deletes last-good rows.
+    assert.deepEqual(keys(), ["muse_account_usage"]);
+});
+test("an observed host stays resident across reads", async () => {
+    const host = new MuseCapacityHost(hostOpts("persistent-full"));
+    try {
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.ok(host.isConnected(), "observed host held open");
+        assert.equal((await host.readUsage()).status, "observed");
+        assert.equal(host.connectionEpoch, 1, "no respawn while observed");
+        assert.ok(host.isConnected());
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("production refresh is throttled and can be disabled", async () => {
+    resetMuseCapacityRefreshState();
+    const opts = { ...hostOpts("persistent-full"), nowMs: Date.now() };
+    try {
+        assert.equal(museRefreshThrottleMs(), 5 * 60 * 1000);
+        const first = await maybeRefreshMuseCapacityFromHost(opts);
+        assert.ok(first, "first refresh runs");
+        assert.equal(await maybeRefreshMuseCapacityFromHost(opts), null, "second refresh throttled");
+        process.env.AGENT_DEALER_MUSE_CAPACITY_REFRESH_MS = "off";
+        resetMuseCapacityRefreshState();
+        assert.equal(await maybeRefreshMuseCapacityFromHost(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;
+        await resetMuseCapacityHostForTests();
+    }
+    await shutdownMuseCapacityHost();
+});
+test("serve host launches under a server-owned config home with worker settings", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-config-"));
+    const configRecord = path.join(dir, "config.json");
+    const host = new MuseCapacityHost(hostOpts("persistent-full", { env: { FAKE_MSP_RECORD_CONFIG: configRecord } }));
+    try {
+        assert.equal((await host.readUsage()).status, "observed");
+        const rec = JSON.parse(fs.readFileSync(configRecord, "utf8"));
+        const ambient = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+        assert.ok(rec.configHome, "host launches with an XDG config home");
+        assert.notEqual(rec.configHome, ambient, "config home is server-owned, not ambient");
+        assert.ok(String(rec.configHome).includes("dealer-muse-serve"), `server-owned home, got ${rec.configHome}`);
+        assert.ok(rec.dataHome, "host launches with an isolated data home");
+        assert.ok(!String(rec.dataHome).includes(".config"), "data home is not the operator's");
+        assert.equal(rec.settingsError, null, "settings.json parses on the launched host");
+        const settings = rec.settings;
+        // Same worker posture as the exec lane's per-attempt settings: no MCP
+        // servers, no subagent delegation, no workflows, no reminder child runs.
+        assert.ok(!("mcpServers" in settings), "workers get no MCP servers");
+        const run = settings.run;
+        assert.equal(run.workflow_trigger_mode, "off");
+        assert.equal(run.subagent_delegation_mode, "off");
+        const caps = settings.runtime_capabilities;
+        assert.ok(Object.keys(caps).length > 0, "reminder switches are present");
+        for (const [name, cap] of Object.entries(caps)) {
+            assert.equal(cap.enabled, false, `${name} stays disabled`);
+        }
+    }
+    finally {
+        await host.shutdown();
+    }
+});
+test("prepareMuseServeHome links the ambient login, or records API-key auth", async () => {
+    // File-backed login: linked, never copied.
+    const ambientRoot = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-ambient-"));
+    const ambientAuth = path.join(ambientRoot, "muse", "auth.json");
+    fs.mkdirSync(path.dirname(ambientAuth), { recursive: true });
+    fs.writeFileSync(ambientAuth, "{}\n");
+    const home = prepareMuseServeHome(ambientAuth);
+    try {
+        assert.equal(home.authLinked, true);
+        const linkPath = path.join(home.configHome, "muse", "auth.json");
+        assert.ok(fs.lstatSync(linkPath).isSymbolicLink(), "login is a symlink, never a copy");
+        assert.equal(fs.readlinkSync(linkPath), ambientAuth);
+    }
+    finally {
+        fs.rmSync(path.dirname(home.configHome), { recursive: true, force: true });
+    }
+    // API-key auth: no link, still a complete home.
+    const keyHome = prepareMuseServeHome(path.join(ambientRoot, "no-such-auth.json"));
+    try {
+        assert.equal(keyHome.authLinked, false);
+        const settings = JSON.parse(fs.readFileSync(path.join(keyHome.configHome, "muse", "settings.json"), "utf8"));
+        assert.equal(settings.run.workflow_trigger_mode, "off");
+        assert.ok(!("mcpServers" in settings));
+    }
+    finally {
+        fs.rmSync(path.dirname(keyHome.configHome), { recursive: true, force: true });
+    }
+    fs.rmSync(ambientRoot, { recursive: true, force: true });
+});
+test("no credential short-circuits to missing without spawning", async () => {
+    const noAuthDir = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-muse-host-noauth-"));
+    const env = { ...process.env, FAKE_MSP_MODE: "persistent-full" };
+    delete env.META_API_KEY;
+    const host = new MuseCapacityHost({
+        // Would report `unsupported` if ever spawned — `missing` proves it was not.
+        command: "/nonexistent/muse-xyz",
+        timeoutMs: 2000,
+        env,
+        authFilePath: path.join(noAuthDir, "auth.json"),
+    });
+    try {
+        assert.equal((await host.readUsage()).status, "missing");
+        assert.equal(host.connectionEpoch, 0, "no host spawned");
+    }
+    finally {
+        await host.shutdown();
+    }
+    assert.deepEqual(keys(), ["muse_account_usage"]);
+});

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

@@ -0,0 +1,97 @@
+// packages/server/src/capacity/muse-lifecycle.test.ts
+//
+// NOT-269: deterministic lifecycle contract for Muse 5H/1W acquisition.
+// Evidence: docs/research/NOT-269-muse-5h-1w-lifecycle.md (Muse Code 1.4.0,
+// stable schema fingerprint sha256:36466f63…, live fresh-host + session-log +
+// echo-exec probes). Fake-subprocess coverage only — never a live provider
+// request, never account data: all payload values below are synthetic
+// redacted stand-ins (obviously-fake percents), asserting shapes and the
+// user contract (Muse primary capacity is exactly 5H + 1W).
+//
+// Proven rules encoded here:
+// - a conforming observation always carries the window+weekly pair;
+// - a partial observation never fabricates the missing half;
+// - the first observation arrives as a `usage/changed` notification;
+// - a fresh/unobserved host reads `missing` (restart is fresh — the client
+//   holds no cross-process usage state);
+// - resume/turn methods are refused before write, so refresh can never
+//   manufacture a billable call.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { assertMuseReadOnlyMethod, museUsageToReadings, readMuseCapacity, requestMuseUsage, } from "./muse.js";
+import { normalizeAdapterWindow } from "./adapter.js";
+const FAKE = new URL("./fixtures/fake-muse-serve.mjs", import.meta.url).pathname;
+function fakeOpts(mode) {
+    const now = Date.now();
+    return {
+        command: process.execPath,
+        args: [FAKE],
+        env: { META_API_KEY: "test-fake-key", FAKE_MSP_MODE: mode, FAKE_MSP_NOW_MS: String(now) },
+        timeoutMs: 10_000,
+        nowMs: now,
+    };
+}
+/** Synthetic redacted stand-in for a conforming observation (not account data). */
+function syntheticFullPair(now) {
+    return {
+        protocol: "msp/1.3",
+        usage: {
+            observedAtMs: now,
+            tier: "synthetic-stand-in",
+            window: { usedPercent: 42, resetsAtMs: now + 2 * 3600_000, windowDurationMins: 300 },
+            weekly: { usedPercent: 17, resetsAtMs: now + 3 * 24 * 3600_000 },
+        },
+    };
+}
+test("lifecycle: a full observation carries exactly the 5H+1W pair", () => {
+    const now = Date.now();
+    const parsed = museUsageToReadings(syntheticFullPair(now), new Date(now).toISOString());
+    assert.ok(parsed);
+    assert.equal(parsed.windows.length, 2);
+    const labels = parsed.windows
+        .map((w) => normalizeAdapterWindow("muse_code", w, now).displayLabel)
+        .sort();
+    assert.deepEqual(labels, ["1W", "5H"]);
+    const rolling = parsed.windows.find((w) => w.windowKey === "rolling_all_models");
+    const weekly = parsed.windows.find((w) => w.windowKey === "weekly_all_models");
+    assert.equal(normalizeAdapterWindow("muse_code", rolling, now).remainingPercent, 58);
+    assert.equal(normalizeAdapterWindow("muse_code", weekly, now).remainingPercent, 83);
+    assert.equal(rolling.criticalRole, "five_hour");
+    assert.equal(weekly.criticalRole, "weekly");
+});
+test("lifecycle: a partial observation never fabricates the missing half", () => {
+    const now = Date.now();
+    const parsed = museUsageToReadings({
+        usage: {
+            observedAtMs: now,
+            window: { usedPercent: 42, resetsAtMs: now + 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("lifecycle: the first observation arrives as usage/changed with the pair", async () => {
+    const read = await requestMuseUsage(fakeOpts("full"));
+    assert.equal(read.failure, null);
+    assert.equal(read.updates.length, 1);
+    // Stable schema refs SubscriptionUsage directly at
+    // /notifications/usage/changed/params — not wrapped in {usage}.
+    const params = read.updates[0];
+    assert.ok(params && typeof params === "object");
+    assert.deepEqual(Object.keys(params).sort(), ["observedAtMs", "tier", "weekly", "window"]);
+});
+test("lifecycle: a fresh host with no observation reads missing — twice", async () => {
+    for (let i = 0; i < 2; i++) {
+        const result = await readMuseCapacity(fakeOpts("missing"));
+        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("lifecycle: refresh can never manufacture a session, turn, or prompt", () => {
+    for (const m of ["session/start", "session/resume", "session/prompt", "turn/start", "exec"]) {
+        assert.throws(() => assertMuseReadOnlyMethod(m), /refusing non-read method/);
+    }
+});