@inixiative/agent-session 0.7.0 → 0.9.0

package/README.md

@@ -74,24 +74,37 @@ arrive as `rate_limit` events.
 ```ts
 import { createSession, TRANSPORTS } from "@inixiative/agent-session";
 
-const kind = "codex-app-server";            // or claude-cli, claude-agent-sdk
+const kind = "codex-app-server";            // or claude-cli, claude-agent-sdk, muse-serve
 if (TRANSPORTS[kind].capabilities.interrupt === "acknowledged") { /* … */ }
 const session = createSession(kind, { cwd, model: "gpt-6-luna", env: { CODEX_HOME: profile } });
 ```
 
-| | claude-cli | codex-app-server | claude-agent-sdk | acp | api |
-|---|---|---|---|---|---|
-| Status | ✅ live | ✅ live | ✅ live | stub | stub |
-| Resume / fork | native / native | native / – | native / native | – | – |
-| Interrupt | acknowledged | acknowledged | acknowledged | – | – |
-| Push | – | steer | – | – | – |
-| Approvals | callback | callback | callback | – | – |
-| Limits stream / poll | ✅ / ✅ | ✅ / ✅ | ✅ / – | – | – |
-| Primed reset | fork | fork | – | – | – |
+| | claude-cli | codex-app-server | muse-serve | claude-agent-sdk | acp | api |
+|---|---|---|---|---|---|---|
+| Status | ✅ live | ✅ live | ✅ live | ✅ live | stub | stub |
+| Resume / fork | native / native | native / – | native / native | native / native | – | – |
+| Interrupt | acknowledged | acknowledged | acknowledged | acknowledged | – | – |
+| Push | steer | steer | steer | – | – | – |
+| Approvals | callback | callback | callback | callback | – | – |
+| Limits stream / poll | ✅ / ✅ | ✅ / ✅ | ✅ / ✅ | ✅ / – | – | – |
+| Primed reset | fork | fork | – | – | – | – |
 
 Codex runs only over `codex app-server --listen stdio://` (`CodexAppServerSession`);
 Codex CLI 0.155 has no `mcp-server` subcommand.
 
+Muse Code runs over `muse serve` through Meta's `@muse-code/sdk` (`MuseSession`), pinned to
+the CLI's version (1.4.14): a host serving another version is refused at start. It bills the
+saved Muse login: metered keys and endpoints never reach it (nor Muse's own tool runs, which
+inherit its environment: a repo command needing `OPENAI_API_KEY` will not see it under Muse),
+and a resumed session must be on provider `meta`. Per-login isolation is `env: { XDG_CONFIG_HOME, XDG_DATA_HOME }` (login and
+sessions). `musePermissions(mode)` maps the host modes to an explicit permission profile, because
+the host default lets Muse's AI reviewer answer approvals instead of the gates. Questions arrive
+through `onUserInput()`; unanswered ones are cancelled with a reason. An approval offering
+no approve-once or reject choice is reported as an `error` event and left open (the turn ends
+at its timeout). Work Muse starts itself
+(cron firings, monitors, goals, reminder agents) is emitted too, marked
+`unattributedReason: "task"` with a `task` lifecycle typed `muse-cron`, `muse-monitor`, ….
+
 Full matrix, notes and what is stubbed: [docs/transports-pools-routing.md](docs/transports-pools-routing.md).
 
 ### Tool gate
@@ -254,6 +267,7 @@ snapshots in the artifact but do not fabricate a completed-turn total.
 | Claude Code | ✅ shipped |
 | Codex app-server | ✅ shipped (`CodexAppServerSession`, `CodexPrimedSessions`) |
 | Claude Agent SDK | ✅ shipped (`ClaudeAgentSdkSession`; caller supplies `query`) |
+| Muse Code | ✅ shipped (`MuseSession`, through `@muse-code/sdk`) |
 | ACP agents / direct API | typed stubs |
 | Gemini CLI | planned |
 | Grok CLI | planned (when its headless/stream mode matures) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions over interchangeable transports, with primed decision sessions, subscription pools, routing, limit polling and continuity.",
   "type": "module",
   "main": "src/index.ts",
@@ -36,11 +36,12 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.16.0"
+    "@inixiative/json-rules": "^3.16.0",
+    "@muse-code/sdk": "1.4.14"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.166",
+    "@inixiative/config": "^0.5.176",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/claude-agent-sdk-session.ts

@@ -23,6 +23,7 @@ import {
   type ClaudeCodeSessionConfig,
   type PipedSubprocess,
 } from './claude-code-session';
+import type { PushOutcome } from './harness-session';
 import { TRANSPORTS } from './transport';
 
 /** The subset of the SDK's Query this transport uses. */
@@ -429,6 +430,16 @@ export class ClaudeAgentSdkSession extends ClaudeCodeSession {
     this._sdk = config;
   }
 
+  /**
+   * Not wired here: the bridge forwards a steer's `priority` to the SDK's input, but whether the SDK
+   * stream surfaces the `command_lifecycle` frames a steer is tracked by has not been verified.
+   */
+  override async push(payload: { kind: string; text: string }): Promise<PushOutcome> {
+    const reason = 'the Agent SDK transport does not steer (not verified)';
+    this._emitPushIgnored(payload.kind, reason);
+    return { outcome: 'ignored', reason };
+  }
+
   /** get_usage is not reachable through the SDK Query API. */
   override async readLimits(): Promise<never> {
     throw Error(

package/src/claude-code-session.ts

@@ -51,6 +51,7 @@ import type {
   BeforeSendHook,
   HarnessSession,
   NativeInterruptOutcome,
+  PushOutcome,
   SessionArtifact,
   SessionEvent,
   SessionEventHandler,
@@ -218,8 +219,40 @@ interface QueuedTurn {
   timeout: number;
   resolve: (result: SessionResult) => void;
   reject: (error: Error) => void;
+  /**
+   * Messages push() wrote into this turn, by uuid, with their `command_lifecycle` state. One not yet
+   * `started` when a result arrives is answered after it, in a follow-on result of the same turn.
+   */
+  steers?: Map<string, SteerState>;
+  /** The turn reached a result while a steer was still waiting: it settles on the next result. */
+  held?: { nativeOutcome: 'completed'; tokens?: SessionTokens };
 }
 
+/** `written` until the CLI's `command_lifecycle` names it; `unconfirmed` after push() gave up waiting. */
+type SteerState = 'written' | 'queued' | 'started' | 'completed' | 'cancelled' | 'unconfirmed';
+const STEER_ACK_MS = 10_000;
+
+const TOKEN_KEYS = [
+  'input',
+  'output',
+  'cacheRead',
+  'cacheWrite',
+  'cacheWrite5m',
+  'cacheWrite1h',
+  'thinking',
+] as const;
+/** One turn's usage over several results (a steer answered after a result). Provider usage is the last result's. */
+const addTokens = (
+  a: SessionTokens | undefined,
+  b: SessionTokens | undefined,
+): SessionTokens | undefined => {
+  if (!a || !b) return b ?? a;
+  const sum: SessionTokens = { ...b };
+  for (const key of TOKEN_KEYS)
+    if (a[key] !== undefined || b[key] !== undefined) sum[key] = (a[key] ?? 0) + (b[key] ?? 0);
+  return sum;
+};
+
 // ---------------------------------------------------------------------------
 // Session
 // ---------------------------------------------------------------------------
@@ -342,6 +375,10 @@ export class ClaudeCodeSession implements HarnessSession {
   private _agentsDir?: string;
   /** Inbound control requests awaiting a gate decision, by request id. */
   private _inbound = new Map<string, AbortController>();
+  /** push() calls waiting for the CLI to name their message, by uuid. */
+  private _steerAcks = new Map<string, (state: SteerState) => void>();
+  /** Steers written and not yet ended natively: a late `completed` after their turn settled is theirs. */
+  private _steerUuids = new Set<string>();
   private readonly _hookCallbackId = `agent-session-pre-tool-${crypto.randomUUID()}`;
   private _limits?: LimitSnapshot;
   private _controlSeq = 0;
@@ -501,23 +538,128 @@ export class ClaudeCodeSession implements HarnessSession {
   }
 
   /**
-   * Mid-turn push. Claude Code's stream-json stdin accepts user messages
-   * only; there is no dedicated out-of-band signal channel. So the current
-   * behavior is to emit a "push_ignored" error event — callers observe it
-   * but the model does not see the payload until the next turn.
-   *
-   * A future improvement: push via the MCP bridge (FLOW.md Loop 4) so the
-   * signal reaches the in-flight turn as a tool result the model must read.
+   * Mid-turn steer: a stream-json user message with `priority: "next"` and its own `uuid`, written
+   * while the owned turn runs. The CLI answers `command_lifecycle` queued → started → completed for
+   * that uuid. It takes the message in at the turn's next model request (after a tool result), or,
+   * when the turn's reply was already final, runs it right after that result as a follow-on result:
+   * either way it is this turn's, and send() settles on the last result (validated against claude
+   * 2.1.316, fixtures/s0/claude-steer-*.jsonl).
    */
-  async push(payload: { kind: string; text: string }): Promise<void> {
+  async push(payload: { kind: string; text: string }): Promise<PushOutcome> {
+    const ignored = (reason: string): PushOutcome => {
+      this._emitPushIgnored(payload.kind, reason);
+      return { outcome: 'ignored', reason };
+    };
+    const turn = this._inflight;
+    const a = turn?.evidence;
+    if (!turn || !a || a.dispatch !== 'attempted' || a.nativeOutcome !== 'unknown')
+      return ignored('no owned in-flight turn');
+    if (!this._proc || !this._alive) return ignored('session not running');
+    const uuid = crypto.randomUUID();
+    turn.steers ??= new Map();
+    const steers = turn.steers;
+    steers.set(uuid, 'written');
+    this._steerUuids.add(uuid);
+    const acknowledged = new Promise<SteerState>((resolve) => this._steerAcks.set(uuid, resolve));
+    try {
+      this._proc.stdin.write(
+        `${JSON.stringify({
+          type: 'user',
+          message: { role: 'user', content: [{ type: 'text', text: payload.text }] },
+          uuid,
+          parent_tool_use_id: null,
+          priority: 'next',
+        })}\n`,
+      );
+      this._proc.stdin.flush();
+    } catch (error) {
+      steers.delete(uuid);
+      this._steerAcks.delete(uuid);
+      return ignored(`write failed: ${(error as Error).message.slice(0, 200)}`);
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const state = await Promise.race([
+      acknowledged,
+      new Promise<'unconfirmed'>((resolve) => {
+        timer = setTimeout(() => resolve('unconfirmed'), STEER_ACK_MS);
+      }),
+    ]).finally(() => clearTimeout(timer));
+    this._steerAcks.delete(uuid);
+    const identity = { ...a.identity, admissionId: a.admissionId };
+    if (state === 'cancelled')
+      return ignored('the runtime cancelled it before the turn took it in');
+    if (state === 'unconfirmed') {
+      // Never named by the CLI: it no longer holds the turn open.
+      if (steers.get(uuid) === 'written') steers.set(uuid, 'unconfirmed');
+      this._releaseHeld(turn);
+      this._emit({
+        ...identity,
+        kind: 'native_status',
+        timestamp: Date.now(),
+        raw: { type: 'push-unknown', kind: payload.kind },
+      });
+      return { outcome: 'unknown' };
+    }
+    this._emit({
+      ...identity,
+      kind: 'native_status',
+      timestamp: Date.now(),
+      raw: { type: 'push-steered', kind: payload.kind, uuid },
+    });
+    return { outcome: 'steered' };
+  }
+
+  protected _emitPushIgnored(kind: string, reason: string): void {
     this._emit({
       kind: 'error',
       timestamp: Date.now(),
-      text: `push_ignored: kind=${payload.kind} — stream-json stdin has no OOB channel`,
-      raw: payload,
+      text: `push_ignored: kind=${kind} — ${reason}`,
+      raw: { kind },
     });
   }
 
+  /** A steer of `turn` the CLI has not started yet (or not named yet). */
+  private _steerWaiting(turn: QueuedTurn): boolean {
+    for (const state of turn.steers?.values() ?? [])
+      if (state === 'written' || state === 'queued') return true;
+    return false;
+  }
+
+  /**
+   * A held turn settles with the result it already had once no steer can still produce a result:
+   * none waiting, and none started (a started steer of a held turn is its follow-on run).
+   */
+  private _releaseHeld(turn: QueuedTurn): void {
+    if (!turn.held || this._inflight !== turn || this._steerWaiting(turn)) return;
+    for (const state of turn.steers?.values() ?? []) if (state === 'started') return;
+    const a = turn.evidence;
+    a.tokens = turn.held.tokens;
+    a.nativeOutcome = turn.held.nativeOutcome;
+    turn.held = undefined;
+    this._resolveTurn();
+  }
+
+  /** Withdraw `turn`'s steers the CLI has not started, so none outlives it as an unowned turn. */
+  private async _withdrawSteers(turn: QueuedTurn, timeoutMs: number): Promise<void> {
+    const waiting = [...(turn.steers ?? [])].filter(
+      ([, state]) => state === 'queued' || state === 'written',
+    );
+    await Promise.all(
+      waiting.map(([uuid]) =>
+        this._controlRequest(
+          { subtype: 'cancel_async_message', message_uuid: uuid },
+          timeoutMs,
+        ).then(
+          (response) => {
+            if ((response.response as { cancelled?: unknown } | undefined)?.cancelled === true)
+              turn.steers?.set(uuid, 'cancelled');
+          },
+          () => {},
+        ),
+      ),
+    );
+  }
+
   // ---------------------------------------------------------------------------
   // start() — spawn the persistent process
   // ---------------------------------------------------------------------------
@@ -822,6 +964,10 @@ export class ClaudeCodeSession implements HarnessSession {
     if (turn?.evidence.dispatch !== 'attempted' || turn.evidence.nativeOutcome !== 'unknown')
       return 'no-turn';
     const deadline = Date.now() + (opts?.timeoutMs ?? 5_000);
+    // A stop is for the whole turn: a steer still waiting dies with it, never runs after it.
+    await this._withdrawSteers(turn, Math.max(1, Math.min(2_000, deadline - Date.now())));
+    this._releaseHeld(turn);
+    if (turn.evidence.nativeOutcome !== 'unknown') return 'acknowledged';
     try {
       await this._controlRequest({ subtype: 'interrupt' }, Math.max(1, deadline - Date.now()));
     } catch {
@@ -1278,6 +1424,30 @@ export class ClaudeCodeSession implements HarnessSession {
       return;
     }
 
+    // A steer's lifecycle: the CLI naming a message push() wrote into the owned turn.
+    if (raw.type === 'command_lifecycle' && typeof raw.command_uuid === 'string') {
+      const turn = this._inflight;
+      const state = raw.state;
+      const ours = this._steerUuids.has(raw.command_uuid);
+      if (ours && (state === 'completed' || state === 'cancelled'))
+        this._steerUuids.delete(raw.command_uuid);
+      if (
+        turn?.steers?.has(raw.command_uuid) &&
+        (state === 'queued' ||
+          state === 'started' ||
+          state === 'completed' ||
+          state === 'cancelled')
+      ) {
+        turn.steers.set(raw.command_uuid, state);
+        this._steerAcks.get(raw.command_uuid)?.(state);
+        if (state === 'cancelled') this._releaseHeld(turn);
+        return;
+      }
+      // A steer's own end after its turn settled (its follow-on result settled the turn first).
+      if (!ours) this._unattributed(raw, 'no-admission');
+      return;
+    }
+
     // Account limits are account-level evidence, never part of an admission's output.
     if (raw.type === 'rate_limit_event') {
       const snapshot = claudeRateLimitSnapshot(raw.rate_limit_info);
@@ -1353,6 +1523,7 @@ export class ClaudeCodeSession implements HarnessSession {
       correlation: 'ordered-stream',
     };
     const terminal = raw.type === 'result';
+    let holding = false;
     if (terminal) {
       if (terminalKey) this._seenTerminals.add(terminalKey);
       const subtype = typeof raw.subtype === 'string' ? raw.subtype : undefined;
@@ -1369,6 +1540,12 @@ export class ClaudeCodeSession implements HarnessSession {
         (status !== undefined && status >= 400) ||
         reason === 'api_error';
       a.nativeOutcome = failed ? 'failed' : subtype === 'success' ? 'completed' : 'unknown';
+      // A steer the CLI has not started yet runs after this result, still in this turn: the turn
+      // stays open (and this result reads as an intermediate one) until the steer's own result.
+      if (a.nativeOutcome === 'completed' && this._steerWaiting(turn)) {
+        holding = true;
+        a.nativeOutcome = 'unknown';
+      }
       a.terminal = {
         type: 'result',
         eventId: terminalKey,
@@ -1405,6 +1582,16 @@ export class ClaudeCodeSession implements HarnessSession {
       this._emit(e);
     }
     if (terminal) {
+      // Each result reports its own run's usage: the turn's is their sum.
+      const tokens = addTokens(turn.held?.tokens, a.tokens);
+      if (holding) {
+        turn.held = { nativeOutcome: 'completed', ...(tokens ? { tokens } : {}) };
+        a.tokens = tokens;
+        return;
+      }
+      turn.held = undefined;
+      a.tokens = tokens;
+      if (a.nativeOutcome === 'failed') void this._withdrawSteers(turn, 2_000);
       if (a.nativeOutcome !== 'unknown') this._resolveTurn();
       else
         this._rejectInflight(

package/src/codex-session.ts

@@ -20,6 +20,7 @@ import type {
   BeforeSendHook,
   HarnessSession,
   NativeInterruptOutcome,
+  PushOutcome,
   SessionArtifact,
   SessionEvent,
   SessionEventHandler,
@@ -886,15 +887,17 @@ export class CodexAppServerSession implements HarnessSession {
   }
 
   /** Mid-turn steer (turn/steer) into the owned in-flight turn; otherwise records push_ignored. */
-  async push(payload: { kind: string; text: string }): Promise<void> {
+  async push(payload: { kind: string; text: string }): Promise<PushOutcome> {
     const a = this._inflight?.evidence;
-    const ignored = (reason: string) =>
+    const ignored = (reason: string): PushOutcome => {
       this._emit({
         kind: 'error',
         timestamp: Date.now(),
         text: `push_ignored: kind=${payload.kind} — ${reason}`,
         raw: { kind: payload.kind },
       });
+      return { outcome: 'ignored', reason };
+    };
     if (
       a?.dispatch !== 'attempted' ||
       a.nativeOutcome !== 'unknown' ||
@@ -925,17 +928,19 @@ export class CodexAppServerSession implements HarnessSession {
         timestamp: Date.now(),
         raw: { type: 'push-steered', kind: payload.kind },
       });
+      return { outcome: 'steered' };
     } catch (error) {
       // A refusal is the runtime's answer; no answer leaves delivery unknown, never "ignored".
-      if (timedOut || !this._alive)
-        this._emit({
-          ...a.identity,
-          admissionId: a.admissionId,
-          kind: 'native_status',
-          timestamp: Date.now(),
-          raw: { type: 'push-unknown', kind: payload.kind },
-        });
-      else ignored(`turn/steer refused: ${(error as Error).message.slice(0, 200)}`);
+      if (!timedOut && this._alive)
+        return ignored(`turn/steer refused: ${(error as Error).message.slice(0, 200)}`);
+      this._emit({
+        ...a.identity,
+        admissionId: a.admissionId,
+        kind: 'native_status',
+        timestamp: Date.now(),
+        raw: { type: 'push-unknown', kind: payload.kind },
+      });
+      return { outcome: 'unknown' };
     } finally {
       clearTimeout(timer);
     }

package/src/harness-session.ts

@@ -11,7 +11,7 @@
 // captures every event for Oracle, and supports fork/interrupt.
 //
 // Implementations: ClaudeCodeSession, CodexAppServerSession,
-// ClaudeAgentSdkSession. How a model is reached is the session's transport
+// ClaudeAgentSdkSession, MuseSession. How a model is reached is the session's transport
 // (see transport.ts); every transport implements this one contract.
 // ---------------------------------------------------------------------------
 
@@ -84,12 +84,13 @@ export class SessionTurnError extends Error {
  * session's cwd and config home: Claude found no transcript ("No conversation found with session
  * ID": cleaned up, deleted, or kept under another project directory or `CLAUDE_CONFIG_DIR`), or
  * Codex found no rollout ("no rollout found for thread id": deleted, or under another
- * `CODEX_HOME`). No turn ran. The caller decides what comes next, typically a fresh session seeded
+ * `CODEX_HOME`), or Muse answered `sessionNotFound` (deleted, under another `XDG_DATA_HOME`, or
+ * an ephemeral host that died with it). No turn ran. The caller decides what comes next, typically a fresh session seeded
  * from its own record of the conversation; `cwd` says where the lookup was made.
  */
 export class NativeBindingMissingError extends Error {
   constructor(
-    readonly runtime: 'claude-code' | 'codex-app-server',
+    readonly runtime: 'claude-code' | 'codex-app-server' | 'muse',
     readonly binding: string,
     message: string,
     readonly cwd?: string,
@@ -410,6 +411,11 @@ export type ToolGate = (request: ToolRequest) => ToolDecision | Promise<ToolDeci
 /** `acknowledged`: the runtime confirmed the stop and the turn reached a native terminal. */
 export type NativeInterruptOutcome = 'acknowledged' | 'no-turn' | 'unacknowledged';
 
+/** What became of a push(): `steered` (the runtime took it into the owned turn), `unknown` (sent, never confirmed), `ignored` (not delivered; `reason` says why). */
+export type PushOutcome =
+  | { readonly outcome: 'steered' | 'unknown' }
+  | { readonly outcome: 'ignored'; readonly reason: string };
+
 export interface HarnessSession {
   /** How this session reaches its model, with the capabilities that transport declares. */
   readonly transport?: TransportDescriptor;
@@ -483,15 +489,15 @@ export interface HarnessSession {
   onToolRequest?(gate: ToolGate): () => void;
 
   /**
-   * Mid-turn push: out-of-band signal injected into an in-flight turn.
-   * Used by guards and Herald to deliver urgent feedback. Best-effort —
-   * the underlying runtime may or may not honor the push.
+   * Mid-turn push (steer): add input to the owned in-flight turn, where the transport declares
+   * `push: "steer"`. It never opens a turn of its own: the pushed text is answered inside the turn
+   * it was pushed into, whose send() settles once that turn (and everything pushed into it) ends.
    *
-   * Implementations that cannot support mid-turn push should emit a
-   * "push_ignored" error event rather than throw, so callers can observe
-   * that the push was attempted but not delivered.
+   * Never throws. `ignored` (with an emitted "push_ignored" error event) means nothing was
+   * delivered: no owned in-flight turn, the runtime refused, or the transport cannot steer.
+   * `unknown` means it was written but the runtime never confirmed it.
    */
-  push(payload: { kind: string; text: string }): Promise<void>;
+  push(payload: { kind: string; text: string }): Promise<PushOutcome>;
 
   /** Full session record for Oracle evaluation. */
   artifact(): SessionArtifact;

package/src/index.ts

@@ -67,8 +67,28 @@ export {
   type LimitWindow,
   limitUtilization,
   mergeLimits,
+  museLimitSnapshot,
 } from './limits';
 export { type LimitProbeOptions, probeClaudeLimits, probeCodexLimits } from './limits-probe';
+// Muse Code adapter: one `muse serve` host per session through Meta's @muse-code/sdk.
+export {
+  MUSE_SDK_VERSION,
+  type MuseApprovalMode,
+  type MuseConnect,
+  type MuseHost,
+  type MuseInitializeResult,
+  type MuseLaunch,
+  type MusePermissionProfile,
+  type MusePermissions,
+  type MuseReasoningEffort,
+  MuseSession,
+  type MuseSessionConfig,
+  type MuseUserInputAnswer,
+  type MuseUserInputHandler,
+  type MuseUserInputQuestion,
+  type MuseUserInputRequest,
+  musePermissions,
+} from './muse-session';
 export {
   ContinuityError,
   type ContinuityRefusal,

package/src/limits.ts

@@ -1,10 +1,10 @@
 // Subscription usage limits, normalized across runtimes. Account identity
 // (email, account/organization IDs) is never read into a snapshot.
 
-export type LimitRuntime = 'claude' | 'codex';
+export type LimitRuntime = 'claude' | 'codex' | 'muse';
 
 export interface LimitWindow {
-  /** Stable per runtime: Claude `five_hour`/`seven_day`/…, Codex `primary`/`secondary`. */
+  /** Stable per runtime: Claude `five_hour`/`seven_day`/…, Codex `primary`/`secondary`, Muse `window`/`weekly`. */
   readonly id: string;
   /** 0–100. */
   readonly usedPercent: number;
@@ -104,6 +104,42 @@ export function codexLimitSnapshot(
   };
 }
 
+/**
+ * Muse `usage/read` result (`{ usage }`) or `usage/changed` params (the usage itself): the plan's
+ * rolling `window` (five hours) and `weekly` windows, in percent used. Meta reports the windows from
+ * its latest model response, so a host that has not served a turn yet reports none. `tier` is not read:
+ * on the wire it is a numeric id (the CLI shows the plan's name), not a label known to be account-free.
+ */
+export function museLimitSnapshot(
+  value: unknown,
+  source: LimitSnapshot['source'],
+  observedAt = Date.now(),
+): LimitSnapshot | undefined {
+  const outer = object(value);
+  const usage = object(outer?.usage) ?? outer;
+  const rolling = object(usage?.window),
+    weekly = object(usage?.weekly);
+  const ms = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined);
+  const windows = [
+    ...window(
+      'window',
+      percent(rolling?.usedPercent),
+      ms(rolling?.resetsAtMs),
+      typeof rolling?.windowDurationMins === 'number' ? rolling.windowDurationMins : undefined,
+    ),
+    ...window('weekly', percent(weekly?.usedPercent), ms(weekly?.resetsAtMs), 10_080),
+  ];
+  if (!windows.length) return undefined;
+  return {
+    runtime: 'muse',
+    source,
+    observedAt: ms(usage?.observedAtMs) ?? observedAt,
+    windows,
+    // Explicit both ways, so a later report clears a block an earlier one (or a quota stop) set.
+    blocked: windows.some((w) => w.usedPercent >= 100),
+  };
+}
+
 /** Claude CLI stream-json `rate_limit_event.rate_limit_info`. Utilization is a 0–1 fraction. */
 export function claudeRateLimitSnapshot(
   info: unknown,