@phnx-labs/agents-cli 1.22.22 → 1.22.23

package/dist/lib/session/session-cache.js

@@ -0,0 +1,399 @@
+/**
+ * Daemon-warmed cross-surface cache for live session status (RUSH-2062).
+ *
+ * Problem: menubar / Factory / watchdog / CLI each independently run a full
+ * `sessions --active` gather (~9s wall / ~170MB) with no sharing. Measured on
+ * zion: back-to-back runs were 9.22s then 8.16s — no speedup, full SSH fan-out
+ * every call.
+ *
+ * Pattern mirrors {@link ../devices/stats-cache.ts} / {@link ../fleet-status.ts}:
+ *
+ * - **Daemon warm:** each daemon publishes THIS host's local active sessions
+ *   on a short tick (`publishLocalActiveSessions`). Publish-own only — no
+ *   cross-host SSH from the daemon (avoids the N² fan-out of RUSH-2061).
+ * - **Readers** (`loadLocalActiveSessions`, fleet path in `gatherActiveSessions`)
+ *   serve the warm snapshot when it is within {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS};
+ *   `forceRefresh` / age expiry re-gathers live.
+ * - **Immutable memo:** per-session fields that only change when the transcript
+ *   does (topic, label, cwd, …) are keyed on `(sessionId, transcriptMtimeMs)`.
+ *   Live status fields (`status`, `activity`, `preview`, `pidAlive`, …) are
+ *   NEVER stored in that memo — they only ride the short-lived snapshot.
+ *
+ * Best-effort disk IO: a missing/corrupt cache never throws; the caller falls
+ * through to a live gather.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getCacheDir } from '../state.js';
+/** Snapshot file under `getCacheDir()` (regenerable, gitignored). */
+const SNAPSHOT_FILE = '.active-sessions.json';
+/** Immutable-field memo file (keyed by sessionId + transcript mtime). */
+const IMMUTABLE_FILE = '.active-session-immutable.json';
+/**
+ * How long a snapshot may be served before a reader re-gathers.
+ * Short on purpose: live status (running/idle/waiting) must not go stale.
+ * The daemon warm tick uses the same cadence (see {@link SESSION_CACHE_WARM_INTERVAL_MS}).
+ */
+export const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 15_000;
+/** Daemon warm interval — keep in sync with the setInterval in `lib/daemon.ts`. */
+export const SESSION_CACHE_WARM_INTERVAL_MS = 15_000;
+/** Kick off the first warm ~25s after daemon start (staggered off other ticks). */
+export const SESSION_CACHE_WARM_KICKOFF_MS = 25_000;
+/** Keys stored in the immutable memo (transcript-stable). */
+export const IMMUTABLE_FIELD_KEYS = [
+    'topic',
+    'label',
+    'name',
+    'cwd',
+    'project',
+    'attachments',
+    'startedAtMs',
+    'version',
+    'pr',
+    'worktree',
+    'ticket',
+    'createdTickets',
+    'spawnedTeam',
+    'sessionFile',
+    'owner',
+    'assignedTask',
+    'kind',
+    'context',
+];
+/**
+ * Live / volatile fields that MUST NOT be served from the immutable memo.
+ * They either change without a transcript write (pid death, attach state) or
+ * are short-window signals (preview, tok/s). The short snapshot TTL is the
+ * only cache that may carry them — and only as a whole-row snapshot.
+ */
+export const LIVE_STATUS_KEYS = [
+    'status',
+    'activity',
+    'preview',
+    'tokPerSec',
+    'awaitingReason',
+    'question',
+    'todos',
+    'tail',
+    'lastActivityMs',
+    'hostLink',
+    'presence',
+    'pidAlive',
+    'tmuxClients',
+    'windowHeartbeatMs',
+    'provenance',
+    'rateLimited',
+    'plan',
+];
+// ── path overrides (test seam) ─────────────────────────────────────────────
+let snapshotPathOverride = null;
+let immutablePathOverride = null;
+/** Test seam: redirect the snapshot file. Returns the previous override. */
+export function setActiveSessionsSnapshotPathForTest(p) {
+    const prev = snapshotPathOverride;
+    snapshotPathOverride = p;
+    return prev;
+}
+/** Test seam: redirect the immutable-memo file. Returns the previous override. */
+export function setImmutableMemoPathForTest(p) {
+    const prev = immutablePathOverride;
+    immutablePathOverride = p;
+    return prev;
+}
+function snapshotPath() {
+    return snapshotPathOverride ?? path.join(getCacheDir(), SNAPSHOT_FILE);
+}
+function immutablePath() {
+    return immutablePathOverride ?? path.join(getCacheDir(), IMMUTABLE_FILE);
+}
+// ── snapshot read / write ──────────────────────────────────────────────────
+/** Read one scope from the snapshot file (best-effort; missing/corrupt → null). */
+export function readActiveSessionsCache(scope) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(snapshotPath(), 'utf-8'));
+        if (!parsed || parsed.version !== 1 || !parsed.entries)
+            return null;
+        const entry = parsed.entries[scope];
+        if (!entry || !Array.isArray(entry.sessions) || typeof entry.capturedAt !== 'number')
+            return null;
+        return entry;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a snapshot for one scope (best-effort). Other scopes are preserved
+ * so a local warm never drops a fleet snapshot a reader just wrote.
+ */
+export function writeActiveSessionsCache(scope, sessions, opts = {}) {
+    const snap = {
+        version: 1,
+        scope,
+        capturedAt: opts.capturedAt ?? Date.now(),
+        sessions,
+        ...(opts.remoteDeviceCount !== undefined ? { remoteDeviceCount: opts.remoteDeviceCount } : {}),
+    };
+    try {
+        const dir = path.dirname(snapshotPath());
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        let entries = {};
+        try {
+            const prev = JSON.parse(fs.readFileSync(snapshotPath(), 'utf-8'));
+            if (prev?.entries && typeof prev.entries === 'object')
+                entries = { ...prev.entries };
+        }
+        catch {
+            // empty
+        }
+        entries[scope] = snap;
+        const body = { version: 1, entries };
+        // Atomic replace so a concurrent reader never sees a partial write.
+        const tmp = `${snapshotPath()}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(body));
+        fs.renameSync(tmp, snapshotPath());
+    }
+    catch {
+        // best-effort
+    }
+    return snap;
+}
+/**
+ * True when a snapshot is still within the freshness window. Pure — the
+ * staleness invariant for live status lives here.
+ */
+export function isActiveSnapshotFresh(capturedAt, nowMs, maxAgeMs = DEFAULT_ACTIVE_CACHE_MAX_AGE_MS) {
+    if (!Number.isFinite(capturedAt) || !Number.isFinite(maxAgeMs))
+        return false;
+    if (maxAgeMs < 0)
+        return false;
+    return nowMs - capturedAt <= maxAgeMs;
+}
+// ── immutable memo ─────────────────────────────────────────────────────────
+/** Pull only the transcript-stable fields from a live row. */
+export function pickImmutableFields(s) {
+    const out = {};
+    for (const k of IMMUTABLE_FIELD_KEYS) {
+        const v = s[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Transcript mtime used as the memo key. Prefer {@link ActiveSession.lastActivityMs}
+ * (the transcript's last write); fall back to `startedAtMs` when no activity
+ * stamp exists. Returns null when neither is known — caller must not memoize.
+ */
+export function transcriptMtimeMs(s) {
+    if (typeof s.lastActivityMs === 'number' && Number.isFinite(s.lastActivityMs))
+        return s.lastActivityMs;
+    if (typeof s.startedAtMs === 'number' && Number.isFinite(s.startedAtMs))
+        return s.startedAtMs;
+    return null;
+}
+function readImmutableFile() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(immutablePath(), 'utf-8'));
+        if (parsed && parsed.version === 1 && parsed.entries && typeof parsed.entries === 'object') {
+            return parsed;
+        }
+    }
+    catch {
+        // missing/corrupt
+    }
+    return { version: 1, entries: {} };
+}
+/**
+ * Read memoized immutable fields for `(sessionId, mtimeMs)`.
+ * Returns null when missing OR when the stored mtime does not match — a
+ * transcript rewrite must force re-derivation of topic/label/etc.
+ */
+export function readImmutableMemo(sessionId, mtimeMs) {
+    if (!sessionId || !Number.isFinite(mtimeMs))
+        return null;
+    const file = readImmutableFile();
+    const entry = file.entries[sessionId];
+    if (!entry || entry.mtimeMs !== mtimeMs)
+        return null;
+    // Defence in depth: strip any live-status key that snuck into a bad write.
+    return stripLiveStatusKeys({ ...entry.fields });
+}
+/** Persist immutable fields for `(sessionId, mtimeMs)`. Live keys are stripped. */
+export function writeImmutableMemo(sessionId, mtimeMs, fields, nowMs = Date.now()) {
+    if (!sessionId || !Number.isFinite(mtimeMs))
+        return;
+    try {
+        const dir = path.dirname(immutablePath());
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        const file = readImmutableFile();
+        file.entries[sessionId] = {
+            mtimeMs,
+            fields: stripLiveStatusKeys({ ...fields }),
+            writtenAt: nowMs,
+        };
+        const tmp = `${immutablePath()}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(file));
+        fs.renameSync(tmp, immutablePath());
+    }
+    catch {
+        // best-effort
+    }
+}
+/** Drop every live-status key from a field bag (defence in depth). */
+export function stripLiveStatusKeys(fields) {
+    const out = { ...fields };
+    for (const k of LIVE_STATUS_KEYS) {
+        if (k in out)
+            delete out[k];
+    }
+    return out;
+}
+/**
+ * True when `fields` contains no live-status key. The invariant the tests pin:
+ * the immutable memo never carries status/activity/preview/etc.
+ */
+export function assertNoLiveStatusFields(fields) {
+    for (const k of LIVE_STATUS_KEYS) {
+        if (k in fields && fields[k] !== undefined)
+            return false;
+    }
+    return true;
+}
+/**
+ * Write immutable memos for every session that has an id + transcript mtime.
+ * Called after a live gather so the next gather (when mtime is unchanged) can
+ * refill identity fields without re-deriving them.
+ */
+export function updateImmutableMemos(sessions, nowMs = Date.now()) {
+    for (const s of sessions) {
+        if (!s.sessionId)
+            continue;
+        const mtime = transcriptMtimeMs(s);
+        if (mtime === null)
+            continue;
+        writeImmutableMemo(s.sessionId, mtime, pickImmutableFields(s), nowMs);
+    }
+}
+/**
+ * Fill missing immutable fields on a live row from the memo when the transcript
+ * mtime matches. Never overwrites a field the live gather already set, and
+ * never copies live-status keys.
+ */
+export function applyImmutableMemo(s) {
+    if (!s.sessionId)
+        return s;
+    const mtime = transcriptMtimeMs(s);
+    if (mtime === null)
+        return s;
+    const memo = readImmutableMemo(s.sessionId, mtime);
+    if (!memo)
+        return s;
+    for (const k of IMMUTABLE_FIELD_KEYS) {
+        if (s[k] === undefined && memo[k] !== undefined) {
+            s[k] = memo[k];
+        }
+    }
+    return s;
+}
+/**
+ * Cache-first load of THIS host's active sessions. Default path serves the
+ * daemon-warmed snapshot when fresh; `forceRefresh` or an expired snapshot
+ * re-gathers and rewrites the cache.
+ */
+export async function loadLocalActiveSessions(opts = {}) {
+    const now = opts.nowMs ?? Date.now();
+    const maxAge = opts.maxAgeMs ?? DEFAULT_ACTIVE_CACHE_MAX_AGE_MS;
+    const readCache = opts.readCache ?? readActiveSessionsCache;
+    const writeCache = opts.writeCache ?? writeActiveSessionsCache;
+    if (!opts.forceRefresh) {
+        const cached = readCache('local');
+        if (cached && isActiveSnapshotFresh(cached.capturedAt, now, maxAge)) {
+            return {
+                sessions: cached.sessions,
+                servedFromCache: true,
+                capturedAt: cached.capturedAt,
+            };
+        }
+    }
+    const gather = opts.gather ??
+        (async () => {
+            const { getActiveSessions } = await import('./active.js');
+            return getActiveSessions({ localOnly: true });
+        });
+    const sessions = await gather();
+    for (const s of sessions)
+        applyImmutableMemo(s);
+    updateImmutableMemos(sessions, now);
+    const snap = writeCache('local', sessions, { capturedAt: now });
+    return { sessions, servedFromCache: false, capturedAt: snap.capturedAt };
+}
+/**
+ * Cache-first load of the fleet-wide active set. A prior gather (or any surface
+ * that just paid the SSH cost) leaves a fleet snapshot; subsequent menubar /
+ * Factory / CLI / watchdog calls within the freshness window share it.
+ */
+export async function loadFleetActiveSessions(opts) {
+    const now = opts.nowMs ?? Date.now();
+    const maxAge = opts.maxAgeMs ?? DEFAULT_ACTIVE_CACHE_MAX_AGE_MS;
+    const readCache = opts.readCache ?? readActiveSessionsCache;
+    const writeCache = opts.writeCache ?? writeActiveSessionsCache;
+    if (!opts.forceRefresh) {
+        const cached = readCache('fleet');
+        if (cached && isActiveSnapshotFresh(cached.capturedAt, now, maxAge)) {
+            return {
+                sessions: cached.sessions,
+                remoteDeviceCount: cached.remoteDeviceCount ?? 0,
+                servedFromCache: true,
+                capturedAt: cached.capturedAt,
+            };
+        }
+    }
+    const live = await opts.gather();
+    for (const s of live.sessions)
+        applyImmutableMemo(s);
+    updateImmutableMemos(live.sessions, now);
+    const snap = writeCache('fleet', live.sessions, {
+        capturedAt: now,
+        remoteDeviceCount: live.remoteDeviceCount,
+    });
+    // Also refresh the local slice so a `--local` reader benefits from this gather.
+    // Identity is machineId() when available; fall back to "rows with no machine
+    // stamp" so a pure-local gather that never set machine still warms the cache.
+    let self;
+    try {
+        const { machineId } = await import('../machine-id.js');
+        self = machineId();
+    }
+    catch {
+        self = undefined;
+    }
+    // Always rewrite the local slice when we know self — including the empty
+    // case. If the last local session just died, leaving a still-fresh snapshot
+    // with ghost rows would make watchdog / `--local` report sessions that are
+    // gone (review on RUSH-2062 / PR #2116).
+    if (self !== undefined) {
+        const localOnly = live.sessions.filter((s) => !s.machine || s.machine === self);
+        writeCache('local', localOnly, { capturedAt: now });
+    }
+    return {
+        sessions: live.sessions,
+        remoteDeviceCount: live.remoteDeviceCount,
+        servedFromCache: false,
+        capturedAt: snap.capturedAt,
+    };
+}
+/**
+ * Daemon warm entry point: live-gather THIS host and write the local snapshot.
+ * Never SSHes. Returns the published row count for the daemon log line.
+ */
+export async function publishLocalActiveSessions(opts = {}) {
+    const result = await loadLocalActiveSessions({
+        forceRefresh: true,
+        gather: opts.gather,
+        nowMs: opts.nowMs,
+    });
+    return { sessions: result.sessions, capturedAt: result.capturedAt };
+}

package/dist/lib/session/types.d.ts

@@ -7,7 +7,7 @@
  * speaks these types.
  */
 /** Agents that store session data on disk and can be discovered by `agents sessions`. */
-export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'antigravity' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi' | 'droid' | 'cursor';
+export type SessionAgentId = 'claude' | 'codex' | 'gemini' | 'antigravity' | 'opencode' | 'openclaw' | 'rush' | 'hermes' | 'grok' | 'kimi' | 'droid' | 'cursor' | 'muse';
 /** Effective permissions mode used to launch a managed agent session. */
 export type SessionRunMode = 'plan' | 'edit' | 'auto' | 'skip';
 /** All agents with session discovery support, in display order. */

package/dist/lib/session/types.js

@@ -7,7 +7,7 @@
  * speaks these types.
  */
 /** All agents with session discovery support, in display order. */
-export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'antigravity', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid', 'cursor'];
+export const SESSION_AGENTS = ['claude', 'codex', 'gemini', 'antigravity', 'opencode', 'openclaw', 'rush', 'hermes', 'grok', 'kimi', 'droid', 'cursor', 'muse'];
 /**
  * True when `agent` stores session data `agents sessions` can discover (a member
  * of {@link SESSION_AGENTS}). The single predicate every session-index writer

package/dist/lib/session/width.d.ts

@@ -8,7 +8,7 @@
  * cell measures and truncates through this module so alignment is computed once,
  * correctly, from the same source of truth.
  */
-/** Strip SGR colour escapes so width is measured on visible characters only. */
+/** Strip SGR colour + OSC-8 hyperlink escapes so width is measured on visible characters only. */
 export declare function stripAnsi(s: string): string;
 /** Visible display width of a string, ANSI-aware and wide-char-aware. */
 export declare function stringWidth(s: string): number;

package/dist/lib/session/width.js

@@ -10,9 +10,19 @@
  */
 /** SGR colour sequences emitted by chalk (e.g. `\x1b[32m`). */
 const SGR_REGEX = /\x1b\[[0-9;]*m/g;
-/** Strip SGR colour escapes so width is measured on visible characters only. */
+/**
+ * OSC-8 hyperlink sequences (`\x1b]8;;<url>\x1b\\` … `\x1b]8;;\x1b\\`, or with a
+ * BEL `\x07` terminator) emitted by `osc8()` in render.ts for clickable
+ * ticket/PR/path badges. These carry the URL, which is NOT visible — leaving it
+ * in over-counts width and, worse, lets a truncation land *inside* the escape and
+ * corrupt it. Stripping both the opener and closer leaves only the visible label
+ * between them, so width is measured on what the user sees and `truncateToWidth`
+ * can never cut a hyperlink in half.
+ */
+const OSC8_REGEX = /\x1b\]8;[^;]*;.*?(?:\x1b\\|\x07)/g;
+/** Strip SGR colour + OSC-8 hyperlink escapes so width is measured on visible characters only. */
 export function stripAnsi(s) {
-    return s.replace(SGR_REGEX, '');
+    return s.replace(OSC8_REGEX, '').replace(SGR_REGEX, '');
 }
 /**
  * Display cells for one code point: 0 for zero-width combining/ZWJ/variation

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 27;
+export declare const SHIM_SCHEMA_VERSION = 28;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -160,7 +160,7 @@ export declare function removeShim(agent: AgentId): boolean;
  *        the versioned home (installer run with GROK_HOME set, or grok
  *        self-update under the shim).
  */
-export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 13;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 14;
 /**
  * Agents whose config directory can be relocated by an environment variable
  * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).

package/dist/lib/shims.js

@@ -18,6 +18,7 @@ import { getShimsDir, getVersionsDir, getBackupsDir, getHistoryDir, ensureAgents
 export { getShimsDir };
 import { AGENTS, agentConfigDirName, readAuthAccountIdentity } from './agents.js';
 import { codexHomeShimBash } from './codex-home.js';
+import { codexPolicyArgs } from './codex-policy.js';
 /**
  * Files and directories to always skip during conflict detection and migration.
  * These are never user config that should be migrated.
@@ -222,12 +223,19 @@ async function promptConflictStrategy(conflictInfos) {
 //        The old dispatcher checked only the global dir, so a pinned grok that
 //        installed into the versioned home fell through to the "not installed"
 //        error.
-export const SHIM_SCHEMA_VERSION = 27;
+export const SHIM_SCHEMA_VERSION = 28;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function codexShimLaunchArgs() {
+    return [
+        '-c',
+        'check_for_update_on_startup=false',
+        ...codexPolicyArgs('edit'),
+    ].map(shellQuote).join(' ');
+}
 function getAgentsBinForGeneratedShim() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'index.js');
 }
@@ -292,7 +300,7 @@ export OPENCODE_CONFIG_DIR="$VERSION_DIR/home/.config/opencode"
 export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
 `
                             : '';
-    const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
+    const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # Shim for ${agentConfig.name}
@@ -549,6 +557,22 @@ elif [ "$AGENT" = "droid" ]; then
       esac
     fi
   fi
+elif [ "$AGENT" = "muse" ]; then
+  # Muse Code installs a self-updating launcher at ~/.local/bin/muse (curl
+  # installer from dev.meta.ai). No npm package. Same shims-dir re-exec guard
+  # as droid.
+  BINARY=$(adopted_original_bin || echo "")
+  if [ -z "$BINARY" ]; then
+    MUSE_BINARY="$HOME/.local/bin/muse"
+    if [ -x "$MUSE_BINARY" ] && [ "$(readlink -f "$MUSE_BINARY" 2>/dev/null)" != "$(readlink -f "$AGENTS_USER_DIR/.cache/shims/$CLI_COMMAND" 2>/dev/null)" ]; then
+      BINARY="$MUSE_BINARY"
+    else
+      BINARY=$(command -v muse 2>/dev/null || echo "")
+      case "$(readlink -f "$BINARY" 2>/dev/null)" in
+        "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+      esac
+    fi
+  fi
 else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 fi
@@ -847,7 +871,7 @@ export function removeShim(agent) {
  *        the versioned home (installer run with GROK_HOME set, or grok
  *        self-update under the shim).
  */
-export const VERSIONED_ALIAS_SCHEMA_VERSION = 13;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 14;
 /** Internal marker string used to embed the schema version in versioned alias scripts. */
 const VERSIONED_ALIAS_VERSION_MARKER = 'agents-versioned-alias-version:';
 // The version string is interpolated into a generated bash script and into
@@ -933,7 +957,7 @@ export OPENCODE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/
 export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
                             : '';
-    const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
+    const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
     // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native
     // binary to ~/.grok/downloads and Droid (Factory AI) installs a standalone
@@ -987,7 +1011,18 @@ else
     "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
   esac
 fi`
-            : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
+            : agent === 'muse'
+                ? `# Muse Code installs a self-updating launcher at ~/.local/bin/muse.
+MUSE_BINARY="$HOME/.local/bin/muse"
+if [ -x "$MUSE_BINARY" ]; then
+  BINARY="$MUSE_BINARY"
+else
+  BINARY=$(command -v muse 2>/dev/null || echo "")
+  case "$BINARY" in
+    "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+  esac
+fi`
+                : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
 # ${VERSIONED_ALIAS_VERSION_MARKER} ${VERSIONED_ALIAS_SCHEMA_VERSION}

package/dist/lib/staleness/writers/hooks.js

@@ -90,7 +90,7 @@ function buildHooksWriter(agent) {
             // registerHooksForGrok — file copy alone only sees top-level available.hooks
             // names (RUSH-1353). Copilot/Kiro/Goose load managed *.json under their
             // hooks dirs the same way.
-            if (agent === 'claude' || agent === 'codex' || agent === 'antigravity' || agent === 'kimi' || agent === 'droid' || agent === 'copilot' || agent === 'kiro' || agent === 'goose' || agent === 'cursor' || agent === 'grok' || agent === 'hermes') {
+            if (agent === 'claude' || agent === 'codex' || agent === 'antigravity' || agent === 'kimi' || agent === 'droid' || agent === 'copilot' || agent === 'kiro' || agent === 'goose' || agent === 'cursor' || agent === 'grok' || agent === 'hermes' || agent === 'muse') {
                 registerHooksToSettings(agent, versionHome);
             }
             return { synced };

package/dist/lib/types.d.ts

@@ -8,7 +8,7 @@
 import type { CloudProviderId } from './cloud/types.js';
 import type { FeedBroadcastConfig } from './feed-broadcast.js';
 /** Unique identifier for a current or legacy AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi' | 'muse';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /**

package/dist/lib/usage.d.ts

@@ -141,6 +141,10 @@ declare const USAGE_SOURCES: {
         readonly fetch: typeof getAntigravityUsageInfo;
         readonly network: true;
     };
+    readonly muse: {
+        readonly fetch: typeof getMuseUsageInfo;
+        readonly network: true;
+    };
 };
 export declare const USAGE_SOURCE_AGENT_IDS: (keyof typeof USAGE_SOURCES)[];
 /** Fetch usage info for a given agent through the canonical source registry. */
@@ -510,6 +514,15 @@ export declare function renderBar(usedPercent: number, length: number, minimumVi
 export declare function getUsageColor(usedPercent: number): (text: string) => string;
 /** Parse the latest billing info from Grok's unified log. */
 declare function getGrokUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
+/**
+ * Muse Code usage.
+ *
+ * Prefer live Meta Model API rate-limit headers when a key is available
+ * (META_API_KEY / MODEL_API_KEY / ~/.config/muse/auth.json). Fall back to
+ * aggregating `model_completed.usage` from local session.jsonl logs under
+ * ~/.local/share/muse/sessions for a last-7-days token window.
+ */
+declare function getMuseUsageInfo(options?: UsageOptions): Promise<UsageInfo>;
 /** Per-model bucket in Cursor's /api/usage response. */
 interface CursorUsageModel {
     numRequests?: number | null;