agent-dealer 1.2.2 → 1.2.3

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/index.js

@@ -46,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();

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

@@ -7,7 +7,8 @@ import { listLinearCandidates, lookupLinearIssue, parseLinearIssueRef, } from ".
 import { getLinearUsageSnapshot } from "../adapters/linear-graphql.js";
 import { listRuntimeModels } from "../runners/models.js";
 import { configuredCapacityRuntimes, getRuntimeCapacitySnapshot } from "../capacity/service.js";
-import { maybeRefreshMuseCapacityFromServe } from "../capacity/muse.js";
+import { refreshClaudeCapacityIfStale } from "../capacity/claude-local-cache.js";
+import { maybeRefreshMuseCapacityFromHost } from "../capacity/muse-host.js";
 import { refreshCodexCapacityIfStale } from "../capacity/codex-app-server.js";
 import { getCursorTeamBillingSnapshot, refreshCursorTeamBillingIfStale, } from "../capacity/cursor-team.js";
 import { getCursorIndividualBillingSnapshot, refreshCursorIndividualBillingIfStale, refreshCursorIndividualCapacityIfStale, } from "../capacity/cursor-individual.js";
@@ -62,22 +63,38 @@ export async function registerRoutes(app) {
     // NOT-245: provider-neutral capacity read model — one entry per configured
     // runtime account with its windows, freshness, and explicit unavailable
     // reasons. Normalized snapshots only; evidence stays server-side.
-    // NOT-247: the only production trigger for the Muse adapter — a throttled
-    // (default 5 min), bounded, best-effort refresh when `muse_code` is
-    // configured. The refresh runs in the background without blocking the
-    // read: GET serves the last-known snapshot immediately so a slow or
-    // hanging `muse serve` (bounded by the capacity timeout) can never stall
-    // the Agents page. Failures persist as N/A and never fail the read.
+    // NOT-270: the only production trigger for Muse capacity — a throttled
+    // (default 5 min), bounded, best-effort refresh through the server-owned
+    // long-lived `muse serve` host when `muse_code` is configured. The
+    // refresh runs in the background without blocking the read: GET serves
+    // the last-known snapshot immediately so a slow or hanging host (bounded
+    // by the capacity timeout) can never stall the Agents page. Failures
+    // preserve last-good rows as N/A and never fail the read.
     // NOT-246: on-demand Codex refresh — when the stored Codex snapshot is
     // stale the read triggers one bounded, non-billable App Server poll
     // (single-flight, never health rows, never throws); fresh snapshots and
     // runtimes without a configured Codex account serve stored data with no
     // subprocess.
+    // NOT-268: Claude local-first ladder — one background refresh ingests
+    // Claude Code's own free cache (plain file read, never a spawn) and then
+    // considers the paid probe without blocking the read: a bounded Haiku
+    // probe fires at most once per hour and only under the explicit
+    // `AGENT_DEALER_CLAUDE_CAPACITY_REFRESH=paid-after-1h` opt-in when every
+    // valid 5H/1W observation is older than 60 minutes. Disabled is a strict
+    // no-op (no spawn, no spend). Failures never break the read below.
     app.get("/api/runtime-capacity", async () => {
+        try {
+            void refreshClaudeCapacityIfStale().catch(() => {
+                // Best-effort: failures persist via the probe diagnostic log.
+            });
+        }
+        catch {
+            // Best-effort: serve the last-known snapshot below.
+        }
         try {
             if (configuredCapacityRuntimes().includes("muse_code")) {
-                void maybeRefreshMuseCapacityFromServe().catch(() => {
-                    // Best-effort: failures persist as N/A via the ingest path.
+                void maybeRefreshMuseCapacityFromHost().catch(() => {
+                    // Best-effort: failures preserve last-good rows via the ingest path.
                 });
             }
         }

package/bundle/server/dist/routes/runtime-capacity.test.js

@@ -15,12 +15,17 @@ process.env.AGENT_DEALER_SKIP_AGENT_HEALTH = "1";
 // Never spawn a real provider from route tests: the on-demand Codex refresh is
 // covered against the fake App Server in codex-app-server.test.ts.
 process.env.AGENT_DEALER_CODEX_CAPACITY_REFRESH = "off";
+// NOT-268: the route also ingests the real ~/.claude.json cache on every read. Point it at a
+// path that never exists so a developer's own Claude usage never leaks extra windows into the
+// fixture-controlled assertions below (this passed in CI, which has no such file, but failed
+// deterministically on any machine that actually uses Claude Code).
+process.env.AGENT_DEALER_CLAUDE_CACHE_FILE = path.join(process.env.AGENT_DEALER_HOME, "no-such-claude-cache.json");
 const { migrate } = await import("../db/index.js");
 const { createAgent } = await import("../repository/agents.js");
 const { clearAllCapacitySnapshots, listCapacitySnapshots, recordCapacitySnapshots } = await import("../repository/runtime-capacity.js");
 const { fixtureMultiWindowAdapter, normalizeAdapterWindow } = await import("../capacity/adapter.js");
 const { refreshCapacityFromAdapters } = await import("../capacity/service.js");
-const { resetMuseCapacityRefreshState } = await import("../capacity/muse.js");
+const { resetMuseCapacityHostForTests } = await import("../capacity/muse-host.js");
 const { refreshCodexCapacityFromAppServer } = await import("../capacity/codex-app-server.js");
 const { registerRoutes } = await import("./index.js");
 const { RuntimeCapacityResponse } = await import("@agent-dealer/shared");
@@ -58,11 +63,12 @@ test("GET /api/runtime-capacity returns normalized entries without evidence", as
     await app.close();
 });
 test("GET triggers the Muse refresh when muse_code is configured", async () => {
-    // NOT-247: the route is the only production trigger for the Muse adapter.
-    // No credential here (env key removed, empty login dir), so the refresh
-    // short-circuits to a `missing` sentinel without spawning anything live.
+    // NOT-270: the route is the only production trigger for Muse capacity
+    // (owned host). No credential here (env key removed, empty login dir),
+    // so the refresh short-circuits to a `missing` sentinel without spawning
+    // anything live.
     clearAllCapacitySnapshots();
-    resetMuseCapacityRefreshState();
+    await resetMuseCapacityHostForTests();
     const prevKey = process.env.META_API_KEY;
     const prevXdg = process.env.XDG_CONFIG_HOME;
     delete process.env.META_API_KEY;
@@ -103,7 +109,7 @@ test("GET triggers the Muse refresh when muse_code is configured", async () => {
             delete process.env.XDG_CONFIG_HOME;
         else
             process.env.XDG_CONFIG_HOME = prevXdg;
-        resetMuseCapacityRefreshState();
+        await resetMuseCapacityHostForTests();
     }
 });
 test("GET serves one logical Codex pair after a dedup refresh of legacy duplicates", async () => {

package/bundle/server/dist/runners/muse-code-jsonl.js

@@ -252,7 +252,13 @@ export function parseMuseRun(input) {
         events: normalizeMuseRun({ sessionId, confirmedModel, tools: toolList, finalText, usage, failure }),
     };
 }
-function normalizeMuseRun(r) {
+/**
+ * NOT-270: shared by the exec parser above and the serve execution lane
+ * (runners/muse-serve-session.ts) so both runners write byte-identical
+ * normalized log evidence — every downstream log reader works unchanged
+ * whichever lane ran the session.
+ */
+export function normalizeMuseRun(r) {
     const out = [];
     if (r.sessionId) {
         out.push({

package/bundle/server/dist/runners/muse-serve-session.js

@@ -0,0 +1,313 @@
+// packages/server/src/runners/muse-serve-session.ts
+//
+// NOT-270: run a real Dealer Muse developer turn through the server-owned
+// `muse serve` host (the NOT-269 proven lifecycle). Only a host that
+// observes the account's provider traffic can answer `usage/read`, so the
+// observation opportunity IS the real session: `session/start` +
+// `turn/start` on the owned host, then the session-boundary `usage/read`
+// (the existing refresh hook) populates 5H/1W. No synthetic prompt is ever
+// sent — the turn below carries the genuine Dealer developer prompt.
+//
+// Wire contract (stable MSP, Muse 1.4.x):
+//   session/start {commandId UUIDv7, workspaceRoot, modelId, approvalMode}
+//   turn/start    {commandId UUIDv7, sessionId, input:[{type:"text",text}]}
+//   await         turn/completed {sessionId, terminal, usage, error?}
+//   session/read  {sessionId, excludeItems:false} for transcript + tools
+//   turn/cancel   on timeout/abort only
+// Forbidden on this lane (asserted by the host): `session/resume`
+// (state-changing, carries no usage — NOT-269 leg 2), `turn/steer`,
+// approval writes. A capacity read never touches this lane.
+//
+// Posture vs `muse exec` (NOT-270 scope decision, recorded in
+// capacity/muse-host.ts): the decision accepts exactly two gaps —
+// `--disable-web-tools` and `--no-foreign-personal-context` have no wire-
+// or host-level equivalent in this Muse version (1.4.0). Network sandbox
+// parity is exact (the owned host starts with `--sandbox-network
+// restricted`, the same constant every exec invocation passes) and worker
+// posture matches via the host's server-owned config home (no MCP servers,
+// no subagents/workflows/reminders, same as the exec per-attempt settings).
+// Known deltas OUTSIDE the recorded decision (not accepted — need product
+// sign-off or a wire equivalent): approvalMode `denyUnmatched` stands in
+// for `--approval-mode never` (the wire enum has no `never`;
+// never-prompts behavior unverified live), and `--approval-judge off` /
+// `--max-model-steps` have no wire equivalent at all — a runaway loop is
+// bounded only by the attempt wall-clock timeout + `turn/cancel` here.
+// Re-verify all of the above with a free `--provider echo` session/turn;
+// the production smoke check on Muse 1.4.x remains.
+//
+// Admission rule: anything that fails BEFORE the turn is admitted
+// (host unavailable, session/start rejected, turn/start rejected) returns
+// `admitted:false` having started no model work — the caller falls back to
+// the legacy `muse exec` subprocess. After admission there is no fallback:
+// the turn is real, billable work and its verdict is reported honestly.
+import { museUuidv7 } from "../capacity/muse.js";
+export const MUSE_SERVE_APPROVAL_MODE = "denyUnmatched";
+/** Monotonic suffix so concurrent turns never share a JSON-RPC request id. */
+let serveReqSeq = 0;
+function serveReqId(prefix) {
+    serveReqSeq += 1;
+    return `muse-${prefix}-${Date.now()}-${serveReqSeq}`;
+}
+function asRecord(v) {
+    return v && typeof v === "object" && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+function asString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+function asFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+const AUTH_RE = /login is no longer valid|authentication failed|missing \w+ credentials|api key .*rejected|unauthenticated|unauthorized|unauthori[sz]ed|not (signed|logged) in|sign in|\b401\b|\b403\b|forbidden|authRequired/i;
+const USAGE_CAP_RE = /rate[\s_-]*limit|usage[\s_-]*limit|quota|\b429\b|rate_limited/i;
+const STEPS_RE = /stepLimit|did not reach a terminal state within \d+ step/i;
+function nullUsage() {
+    return {
+        inputTokens: null,
+        outputTokens: null,
+        cacheReadTokens: null,
+        cacheWriteTokens: null,
+        reasoningTokens: null,
+        modelDurationMs: null,
+        costUsd: null,
+    };
+}
+function usageFromTokenUsage(u, durationMs) {
+    const base = nullUsage();
+    const r = asRecord(u);
+    if (!r)
+        return { ...base, modelDurationMs: durationMs };
+    return {
+        inputTokens: asFiniteNumber(r.inputTokens),
+        outputTokens: asFiniteNumber(r.outputTokens),
+        cacheReadTokens: asFiniteNumber(r.cacheReadTokens),
+        cacheWriteTokens: asFiniteNumber(r.cacheWriteTokens),
+        reasoningTokens: asFiniteNumber(r.reasoningTokens),
+        modelDurationMs: durationMs,
+        costUsd: null,
+    };
+}
+function classifyTurnError(kind, message) {
+    const k = typeof kind === "string" ? kind : "";
+    const m = typeof message === "string" && message ? message : k || "turn failed";
+    const text = `${k} ${m}`;
+    if (STEPS_RE.test(text))
+        return { kind: "max_steps", message: m.slice(0, 500) };
+    if (AUTH_RE.test(text))
+        return { kind: "auth", message: m.slice(0, 500) };
+    if (USAGE_CAP_RE.test(text))
+        return { kind: "usage_cap", message: m.slice(0, 500) };
+    return { kind: "other", message: m.slice(0, 500) };
+}
+function unadmitted() {
+    return {
+        admitted: false,
+        sessionId: null,
+        terminal: null,
+        finalText: null,
+        confirmedModel: null,
+        tools: [],
+        usage: nullUsage(),
+        failure: null,
+        timedOut: false,
+        durationMs: null,
+        viewItems: [],
+    };
+}
+/**
+ * Fold `session/read` history items into transcript/tools/confirmed-model.
+ * Unknown kinds are ignored (schema says clients must render them
+ * generically; the runner only needs text + tool names). Items from other
+ * turns are skipped when `turnId` is present.
+ */
+export function foldServeViewItems(items, turnId) {
+    const texts = [];
+    const tools = [];
+    if (!Array.isArray(items))
+        return { finalText: null, tools };
+    for (const raw of items) {
+        const it = asRecord(raw);
+        if (!it)
+            continue;
+        if (turnId !== null && it.turnId !== undefined && it.turnId !== turnId)
+            continue;
+        if (typeof it.kind !== "string")
+            continue;
+        if (it.kind === "agentMessage") {
+            const t = asString(it.text);
+            if (t)
+                texts.push(t);
+        }
+        else if (it.kind === "toolCall") {
+            const name = asString(it.tool);
+            const callId = asString(it.callId) ?? `tool-${tools.length}`;
+            const failed = it.failureKind !== undefined ||
+                it.failureReason !== undefined ||
+                it.status === "failed";
+            tools.push({
+                callId,
+                name: name ?? null,
+                outcome: it.status === "inProgress" ? null : failed ? "failure" : "success",
+                error: asString(it.failureReason) ?? null,
+            });
+        }
+    }
+    const finalText = texts.length > 0 ? texts.join("\n") : null;
+    return { finalText, tools };
+}
+function confirmedModelFromSession(session) {
+    const r = asRecord(session);
+    if (!r)
+        return null;
+    return asString(r.modelId) ?? null;
+}
+export async function runMuseServeTurn(input) {
+    if (!input.model.trim())
+        throw new Error("muse: model must be set explicitly");
+    if (!input.prompt.trim())
+        throw new Error("muse: prompt must not be empty");
+    if (input.prompt.startsWith("-"))
+        throw new Error("muse: prompt must not start with '-'");
+    const { host } = input;
+    const rpcTimeoutMs = Math.min(input.rpcTimeoutMs ?? 30_000, input.timeoutMs);
+    const started = await host.ensureStarted();
+    if (!started)
+        return unadmitted();
+    const startReply = await host.execRequest(serveReqId("serve-session"), "session/start", {
+        commandId: museUuidv7(),
+        workspaceRoot: input.cwd,
+        modelId: input.model,
+        approvalMode: MUSE_SERVE_APPROVAL_MODE,
+    }, rpcTimeoutMs);
+    if (!startReply || startReply.error)
+        return unadmitted();
+    const session = asRecord(startReply.result)?.session;
+    const sessionId = asRecord(session)?.sessionId;
+    if (typeof sessionId !== "string" || !sessionId)
+        return unadmitted();
+    let confirmedModel = confirmedModelFromSession(session);
+    const turnReply = await host.execRequest(serveReqId("serve-turn"), "turn/start", {
+        commandId: museUuidv7(),
+        sessionId,
+        input: [{ type: "text", text: input.prompt }],
+    }, rpcTimeoutMs);
+    if (!turnReply || turnReply.error)
+        return unadmitted();
+    // The turn is admitted from here: real, billable work may be running.
+    // No exec fallback past this point — every exit below reports honestly.
+    try {
+        input.onAdmitted?.(sessionId);
+    }
+    catch {
+        // The admission flag is advisory; a throwing listener must not break the turn.
+    }
+    const turnId = asString(asRecord(turnReply.result)?.turnId) ?? null;
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+    };
+    input.signal?.addEventListener("abort", onAbort, { once: true });
+    const deadlineMs = Date.now() + input.timeoutMs;
+    let completed = null;
+    try {
+        while (completed === null) {
+            if (aborted)
+                break;
+            // Host death resolves waiters null — re-subscribing on a dead host
+            // would spin until the deadline, so stop waiting and settle below.
+            if (!host.isConnected())
+                break;
+            const remaining = deadlineMs - Date.now();
+            if (remaining <= 0)
+                break;
+            completed = await host.waitForHostNotification((m) => m.method === "turn/completed" && asRecord(m.params)?.sessionId === sessionId, Math.min(remaining, 30_000));
+            // waitForHostNotification resolves null on chunk timeout too — loop
+            // until the turn completes or the deadline passes. (Subscribe happens
+            // microseconds after the turn/start ack while a real completion takes
+            // seconds, so no completion can slip between admit and subscribe.)
+        }
+    }
+    finally {
+        input.signal?.removeEventListener("abort", onAbort);
+    }
+    const timedOut = completed === null && !aborted;
+    if (completed === null) {
+        // Timeout or abort: cancel the turn, then take whatever terminal the
+        // host settles on (usually `cancelled`) as the honest record.
+        await host.cancelExecTurn(sessionId, turnId ?? undefined);
+        completed = await host.waitForHostNotification((m) => m.method === "turn/completed" && asRecord(m.params)?.sessionId === sessionId, 10_000);
+    }
+    const params = asRecord(completed?.params);
+    const terminalRaw = asString(params?.terminal);
+    const terminal = terminalRaw === "completed" || terminalRaw === "failed" || terminalRaw === "cancelled"
+        ? terminalRaw
+        : null;
+    const turnError = asRecord(params?.error);
+    const durationMs = asFiniteNumber(params?.durationMs);
+    const usage = usageFromTokenUsage(params?.usage, durationMs);
+    // Folded history for transcript + tool activity (best-effort: a turn whose
+    // history cannot be read still reports its terminal + usage honestly).
+    let finalText = null;
+    let tools = [];
+    let viewItems = [];
+    try {
+        const readReply = await host.execRequest(serveReqId("serve-read"), "session/read", { sessionId, excludeItems: false }, rpcTimeoutMs);
+        const readResult = asRecord(readReply?.result);
+        const readSession = readResult?.session;
+        confirmedModel = confirmedModelFromSession(readSession) ?? confirmedModel;
+        const history = asRecord(readResult?.history);
+        const items = history?.items;
+        if (Array.isArray(items))
+            viewItems = items;
+        const folded = foldServeViewItems(items, turnId);
+        finalText = folded.finalText;
+        tools = folded.tools;
+    }
+    catch {
+        // Best-effort: keep terminal + usage.
+    }
+    let failure = null;
+    if (aborted && terminal !== "completed") {
+        failure = { kind: "other", message: "aborted" };
+    }
+    else if (terminal === "failed") {
+        failure = classifyTurnError(turnError?.kind, turnError?.message);
+    }
+    else if (terminal === "cancelled") {
+        failure = timedOut
+            ? { kind: "other", message: "turn timed out and was cancelled" }
+            : { kind: "other", message: `turn cancelled${asString(params?.reason) ? `: ${asString(params?.reason)}` : ""}`.slice(0, 500) };
+    }
+    else if (terminal === "completed") {
+        const wrong = confirmedModel !== null && confirmedModel !== input.model;
+        if (wrong) {
+            failure = {
+                kind: "model_mismatch",
+                message: `configured ${input.model}, server confirmed ${confirmedModel}`.slice(0, 500),
+            };
+        }
+        else if (confirmedModel === null) {
+            failure = { kind: "model_mismatch", message: `server did not confirm model ${input.model}` };
+        }
+    }
+    else {
+        // No completion observed even after cancel (host died mid-turn).
+        failure = timedOut
+            ? { kind: "other", message: "turn timed out with no completion observed" }
+            : { kind: "other", message: "no turn completion observed" };
+    }
+    return {
+        admitted: true,
+        sessionId,
+        terminal,
+        finalText: finalText === "" ? null : finalText,
+        confirmedModel,
+        tools,
+        usage,
+        failure,
+        timedOut,
+        durationMs,
+        viewItems,
+    };
+}