@phnx-labs/agents-cli 1.22.22 → 1.22.23

package/dist/lib/session/parse.js

@@ -160,6 +160,9 @@ export function parseSession(filePath, agent, opts = {}) {
         case 'cursor':
             events = parseCursor(filePath);
             break;
+        case 'muse':
+            events = parseMuse(filePath);
+            break;
     }
     // Chokepoint: every string field that originated in an untrusted session
     // file gets stripped of terminal escapes here, so renderers downstream can
@@ -206,6 +209,13 @@ export function detectAgent(filePath) {
         return 'droid';
     if (filePath.includes('/.cursor/') || filePath.includes('\\.cursor\\'))
         return 'cursor';
+    // Muse sessions: ~/.local/share/muse/sessions/YYYY/MM/DD/<uuid>/session.jsonl
+    if (filePath.includes('/muse/sessions/') ||
+        filePath.includes('\\muse\\sessions\\') ||
+        filePath.includes('/.local/share/muse/') ||
+        filePath.includes('\\.local\\share\\muse\\')) {
+        return 'muse';
+    }
     // Cloud convention: cloud-sessions/<id>/session.<format>.jsonl
     const cloudMatch = filePath.match(/session\.(claude|codex|rush)\.jsonl(?:$|[?#])/);
     if (cloudMatch)
@@ -1504,6 +1514,94 @@ export function parseRush(filePath) {
 //     system_prompt, message_count, messages: [{role, content}, ...] }
 // Content may be a string or an array of text parts.
 // ---------------------------------------------------------------------------
+/**
+ * Muse Code session.jsonl → normalized events.
+ *
+ * Muse records an append-only event log. We map:
+ *   - runtime.command_intake.received / turn_submit → user message
+ *   - assistant_message_committed → assistant message
+ *   - model_completed.usage → usage
+ *   - tool-related events when present
+ */
+export function parseMuse(filePath) {
+    const content = safeReadSessionFile(filePath);
+    const lines = content.split('\n').filter((l) => l.trim());
+    const events = [];
+    const museTs = (raw) => {
+        if (typeof raw?.recorded_at === 'number') {
+            const v = raw.recorded_at;
+            const ms = v > 1e14 ? Math.floor(v / 1000) : v;
+            return new Date(ms).toISOString();
+        }
+        return new Date().toISOString();
+    };
+    for (const line of lines) {
+        let raw;
+        try {
+            raw = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const timestamp = museTs(raw);
+        const payloadType = raw.payload_type;
+        const payload = raw.payload;
+        const event = payload?.event ?? payload;
+        if (payloadType === 'runtime.command_intake.received') {
+            const cmd = payload?.record?.command;
+            if (cmd?.kind === 'turn_submit' && typeof cmd.prompt === 'string' && cmd.prompt.trim()) {
+                events.push({
+                    type: 'message',
+                    agent: 'muse',
+                    timestamp,
+                    role: 'user',
+                    content: cmd.prompt.trim(),
+                });
+            }
+            continue;
+        }
+        if (event?.kind === 'assistant_message_committed' && typeof event.text === 'string') {
+            events.push({
+                type: 'message',
+                agent: 'muse',
+                timestamp,
+                role: 'assistant',
+                content: event.text,
+            });
+            continue;
+        }
+        if (event?.kind === 'model_completed' && event.usage && typeof event.usage === 'object') {
+            const u = event.usage;
+            events.push({
+                type: 'usage',
+                agent: 'muse',
+                timestamp,
+                content: JSON.stringify({
+                    input_tokens: u.input_tokens ?? 0,
+                    output_tokens: u.output_tokens ?? 0,
+                    cached_tokens: u.cached_tokens ?? 0,
+                    reasoning_tokens: u.reasoning_tokens ?? 0,
+                }),
+            });
+            continue;
+        }
+        // Tool call / result shapes when Muse records them under task events
+        if (event?.kind === 'tool_call' || event?.kind === 'tool.called') {
+            const tool = event.tool || event.name || event.tool_name;
+            if (typeof tool === 'string') {
+                events.push({
+                    type: 'tool_use',
+                    agent: 'muse',
+                    timestamp,
+                    tool,
+                    args: typeof event.args === 'object' ? event.args : undefined,
+                    callId: typeof event.call_id === 'string' ? event.call_id : undefined,
+                });
+            }
+        }
+    }
+    return events;
+}
 /** Parse a Hermes session JSON file into normalized events. */
 export function parseHermes(filePath) {
     let session;

package/dist/lib/session/remote-list.d.ts

@@ -73,7 +73,16 @@ export declare function isAutomaticSessionPeer(d: DeviceProfile, self: string):
  * address. `forwardedArgs` are the caller's own sessions args (query + filters,
  * already `--json`) so every peer returns the same slice this machine asked for.
  */
-export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[]): Promise<RemoteListResult>;
+export interface GatherRemoteListOptions {
+    /**
+     * Opt-in early-exit for a globally-unique id lookup (a full UUID): the first
+     * peer to return the matching row resolves the fan-out and cancels the rest.
+     * Omitted for browse/label/prefix sweeps, which must wait for every peer to
+     * know whether the match is unique or conflicting.
+     */
+    isDefinitive?: (session: SessionMeta, machine: string) => boolean;
+}
+export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[], opts?: GatherRemoteListOptions): Promise<RemoteListResult>;
 export interface RemoteToolSearchResult {
     envelopes: Array<{
         machine: string;

package/dist/lib/session/remote-list.js

@@ -191,19 +191,13 @@ export function isAutomaticSessionPeer(d, self) {
         return false;
     return d.platform === 'windows' || d.platform === 'linux' || d.platform === 'macos';
 }
-/**
- * Gather listing sessions from other machines. With an explicit `hosts` list
- * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
- * online devices from `ag devices`, excluding this machine and any without an
- * address. `forwardedArgs` are the caller's own sessions args (query + filters,
- * already `--json`) so every peer returns the same slice this machine asked for.
- */
-export async function gatherRemoteList(forwardedArgs, hosts) {
+export async function gatherRemoteList(forwardedArgs, hosts, opts) {
     const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
     const result = await gatherRemoteAgentsJson({
         args: forwardedArgs,
         noFanoutEnv: NO_FANOUT_ENV,
         hosts,
+        earlyExit: opts?.isDefinitive ? { isDefinitive: opts.isDefinitive } : undefined,
         parse: (stdout, machine) => parseRemoteListPayload(stdout, machine, safeResolver),
     });
     return {

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

@@ -54,20 +54,74 @@ export declare function classifySshFailure(res: {
     error?: Error | null;
     status: number | null;
 }): SshOutcome;
+/**
+ * How long a successful remote fetch may be served without re-SSHing.
+ * Short on purpose: session listings must stay near-live (RUSH-2062). Match the
+ * active-session snapshot window so surfaces share one freshness model.
+ */
+export declare const REMOTE_CACHE_MAX_AGE_MS = 15000;
 /**
  * Deterministic cache path for a (host, forwarded-args) pair. The forwarded args
  * are hashed so distinct queries cache independently; the host stays readable in
  * the filename (sanitised so `user@host` and aliases are filesystem-safe).
  */
 export declare function remoteCachePath(host: string, forwardedArgs: string[]): string;
+/**
+ * Pure freshness check for a remote-sessions cache entry. A reachable host
+ * skips SSH only while this returns true; unreachable fallback ignores age.
+ */
+export declare function isRemoteCacheFresh(mtimeMs: number, nowMs: number, maxAgeMs?: number): boolean;
+export interface RemoteCacheHit {
+    output: string;
+    mtimeMs: number;
+}
+/**
+ * Read a cached remote fetch. When `maxAgeMs` is set, returns null if the
+ * entry is older than the window (cache-first path for reachable hosts).
+ * Omit `maxAgeMs` to accept any age (unreachable fallback).
+ */
+export declare function readRemoteCache(host: string, forwardedArgs: string[], opts?: {
+    maxAgeMs?: number;
+    nowMs?: number;
+}): RemoteCacheHit | null;
 /** Banner shown above replayed cache rows when the peer is offline. */
 export declare function formatStaleBanner(host: string, mtimeMs: number): string;
 /** Message shown when a host is unreachable and there is no cache to fall back to. */
 export declare function formatUnreachable(host: string): string;
+/** Persist a successful fetch for later cache-first / offline replay.
+ * Best-effort: a cache write must never break the live query. Exported for tests. */
+export declare function writeRemoteCache(host: string, forwardedArgs: string[], output: string): void;
+/**
+ * Serve a *fresh* cache entry for a reachable-host skip (no banner — the data
+ * is still within the freshness window). Returns false when missing/stale so
+ * the caller SSHes. RUSH-2062: without this, a reachable host never skipped SSH
+ * even when the cache was just written.
+ */
+export declare function serveWarmRemoteCache(host: string, forwardedArgs: string[], opts?: {
+    maxAgeMs?: number;
+    nowMs?: number;
+}): boolean;
+/** Replay a cached fetch for an unreachable host (any age). Banner goes to
+ * stderr (so a piped stdout stays exactly the cached rows); returns false when
+ * nothing is cached for this exact (host, query). */
+export declare function replayRemoteCache(host: string, forwardedArgs: string[]): boolean;
+export interface RunRemoteSessionsOptions {
+    /** Skip warm cache and SSH every host (force-refresh). */
+    forceRefresh?: boolean;
+    /** Override freshness window for the warm path. */
+    maxAgeMs?: number;
+    /** Clock (tests). */
+    nowMs?: number;
+}
 /**
  * Run the current `agents sessions` invocation on one or more remote machines over
- * SSH, writing each remote's output to the terminal. A successful fetch is cached;
- * an unreachable host falls back to that cache (with a stale banner) when present.
+ * SSH, writing each remote's output to the terminal.
+ *
+ * Cache policy (RUSH-2062):
+ * - **Default:** serve a fresh cache hit without SSH; SSH only on miss/stale.
+ * - **`forceRefresh`:** always SSH, then rewrite the cache.
+ * - **Unreachable:** fall back to any cached output (with a stale banner).
+ *
  * Sets `process.exitCode = 1` if any host could not be answered (live or cached).
  * Reads the invocation from `process.argv` (override via `argv` for testing).
  *
@@ -75,4 +129,4 @@ export declare function formatUnreachable(host: string): string;
  * Session output is small and the remote returns quickly, so buffering is
  * imperceptible; `maxBuffer` is generous for the rare large `--markdown <id>` dump.
  */
-export declare function runRemoteSessions(hosts: string[], argv?: string[]): void;
+export declare function runRemoteSessions(hosts: string[], argv?: string[], opts?: RunRemoteSessionsOptions): void;

package/dist/lib/session/remote.js

@@ -9,13 +9,14 @@
  * upfront copy, always current, but the peer must be reachable. SSH access is the
  * only auth — if you can `ssh <host>`, you own the box (no identity layer by design).
  *
- * Offline degradation (no sync, still fetch-first): every *successful* fetch is
+ * Cache-first (RUSH-2062) + offline degradation: every *successful* fetch is
  * cached to `~/.agents/.cache/remote-sessions/`, keyed by host + the exact query.
- * When a later run finds the host unreachable, the cache is replayed with a clearly
- * labelled "showing cached results" banner instead of returning nothing. The cache
- * is a byproduct of fetches you already made — never a background job, freely
- * deletable — so the fetch-don't-replicate model holds; this is just graceful
- * degradation when the peer is asleep.
+ * A later call with a *fresh* cache serves it without SSH (same daemon-warmed
+ * shared-cache shape as `stats-cache.ts`) so a reachable host is not re-probed
+ * on every menubar/CLI/watchdog tick. When the host is unreachable, any cache
+ * (even stale) is replayed with a clearly labelled "showing cached results"
+ * banner. The cache is a byproduct of fetches you already made — freely
+ * deletable — so the fetch-don't-replicate model holds.
  *
  * Mirrors the transport already used by `agents secrets export --host`
  * (`src/commands/secrets.ts`): `ssh -o BatchMode=yes <host> bash -lc '<cmd>'`,
@@ -145,6 +146,12 @@ export function classifySshFailure(res) {
 }
 /** Root of the offline-replay cache (`~/.agents/.cache/remote-sessions/`). */
 const REMOTE_CACHE_DIR = join(getCacheDir(), 'remote-sessions');
+/**
+ * How long a successful remote fetch may be served without re-SSHing.
+ * Short on purpose: session listings must stay near-live (RUSH-2062). Match the
+ * active-session snapshot window so surfaces share one freshness model.
+ */
+export const REMOTE_CACHE_MAX_AGE_MS = 15_000;
 /**
  * Deterministic cache path for a (host, forwarded-args) pair. The forwarded args
  * are hashed so distinct queries cache independently; the host stays readable in
@@ -155,6 +162,37 @@ export function remoteCachePath(host, forwardedArgs) {
     const safeHost = host.replace(/[^a-zA-Z0-9._@-]/g, '_');
     return join(REMOTE_CACHE_DIR, `${safeHost}__${hash}.txt`);
 }
+/**
+ * Pure freshness check for a remote-sessions cache entry. A reachable host
+ * skips SSH only while this returns true; unreachable fallback ignores age.
+ */
+export function isRemoteCacheFresh(mtimeMs, nowMs, maxAgeMs = REMOTE_CACHE_MAX_AGE_MS) {
+    if (!Number.isFinite(mtimeMs) || !Number.isFinite(maxAgeMs) || maxAgeMs < 0)
+        return false;
+    return nowMs - mtimeMs <= maxAgeMs;
+}
+/**
+ * Read a cached remote fetch. When `maxAgeMs` is set, returns null if the
+ * entry is older than the window (cache-first path for reachable hosts).
+ * Omit `maxAgeMs` to accept any age (unreachable fallback).
+ */
+export function readRemoteCache(host, forwardedArgs, opts = {}) {
+    try {
+        const p = remoteCachePath(host, forwardedArgs);
+        if (!existsSync(p))
+            return null;
+        const mtimeMs = statSync(p).mtimeMs;
+        if (opts.maxAgeMs !== undefined) {
+            const now = opts.nowMs ?? Date.now();
+            if (!isRemoteCacheFresh(mtimeMs, now, opts.maxAgeMs))
+                return null;
+        }
+        return { output: readFileSync(p, 'utf8'), mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
 /** Banner shown above replayed cache rows when the peer is offline. */
 export function formatStaleBanner(host, mtimeMs) {
     const ago = formatRelativeTime(new Date(mtimeMs).toISOString());
@@ -164,9 +202,9 @@ export function formatStaleBanner(host, mtimeMs) {
 export function formatUnreachable(host) {
     return chalk.red(`${host}: unreachable over SSH (asleep, offline, or host key changed?) — ConnectTimeout 10s`);
 }
-/** Persist a successful fetch for later offline replay. Best-effort: a cache
- * write must never break the live query. */
-function writeRemoteCache(host, forwardedArgs, output) {
+/** Persist a successful fetch for later cache-first / offline replay.
+ * Best-effort: a cache write must never break the live query. Exported for tests. */
+export function writeRemoteCache(host, forwardedArgs, output) {
     try {
         mkdirSync(REMOTE_CACHE_DIR, { recursive: true });
         writeFileSync(remoteCachePath(host, forwardedArgs), output);
@@ -175,26 +213,42 @@ function writeRemoteCache(host, forwardedArgs, output) {
         // ignore — caching is an optimisation, not a guarantee
     }
 }
-/** Replay a cached fetch for an unreachable host. Banner goes to stderr (so a
- * piped stdout stays exactly the cached rows); returns false when nothing is
- * cached for this exact (host, query). */
-function replayRemoteCache(host, forwardedArgs) {
-    try {
-        const p = remoteCachePath(host, forwardedArgs);
-        if (!existsSync(p))
-            return false;
-        process.stderr.write(formatStaleBanner(host, statSync(p).mtimeMs) + '\n');
-        process.stdout.write(readFileSync(p, 'utf8'));
-        return true;
-    }
-    catch {
+/**
+ * Serve a *fresh* cache entry for a reachable-host skip (no banner — the data
+ * is still within the freshness window). Returns false when missing/stale so
+ * the caller SSHes. RUSH-2062: without this, a reachable host never skipped SSH
+ * even when the cache was just written.
+ */
+export function serveWarmRemoteCache(host, forwardedArgs, opts = {}) {
+    const hit = readRemoteCache(host, forwardedArgs, {
+        maxAgeMs: opts.maxAgeMs ?? REMOTE_CACHE_MAX_AGE_MS,
+        nowMs: opts.nowMs,
+    });
+    if (!hit)
         return false;
-    }
+    process.stdout.write(hit.output);
+    return true;
+}
+/** Replay a cached fetch for an unreachable host (any age). Banner goes to
+ * stderr (so a piped stdout stays exactly the cached rows); returns false when
+ * nothing is cached for this exact (host, query). */
+export function replayRemoteCache(host, forwardedArgs) {
+    const hit = readRemoteCache(host, forwardedArgs); // no maxAge — any age ok
+    if (!hit)
+        return false;
+    process.stderr.write(formatStaleBanner(host, hit.mtimeMs) + '\n');
+    process.stdout.write(hit.output);
+    return true;
 }
 /**
  * Run the current `agents sessions` invocation on one or more remote machines over
- * SSH, writing each remote's output to the terminal. A successful fetch is cached;
- * an unreachable host falls back to that cache (with a stale banner) when present.
+ * SSH, writing each remote's output to the terminal.
+ *
+ * Cache policy (RUSH-2062):
+ * - **Default:** serve a fresh cache hit without SSH; SSH only on miss/stale.
+ * - **`forceRefresh`:** always SSH, then rewrite the cache.
+ * - **Unreachable:** fall back to any cached output (with a stale banner).
+ *
  * Sets `process.exitCode = 1` if any host could not be answered (live or cached).
  * Reads the invocation from `process.argv` (override via `argv` for testing).
  *
@@ -202,16 +256,26 @@ function replayRemoteCache(host, forwardedArgs) {
  * Session output is small and the remote returns quickly, so buffering is
  * imperceptible; `maxBuffer` is generous for the rare large `--markdown <id>` dump.
  */
-export function runRemoteSessions(hosts, argv = process.argv) {
+export function runRemoteSessions(hosts, argv = process.argv, opts = {}) {
     for (const host of hosts)
         assertValidSshTarget(host); // fail fast on any bad target
     const forwarded = ensureWholeIndex(buildForwardedArgs(argv, new Set(hosts)));
     const cols = terminalWidth();
     const multi = hosts.length > 1;
     let failures = 0;
+    const forceRefresh = opts.forceRefresh === true
+        || process.env.AGENTS_SESSIONS_FORCE_REFRESH === '1';
     for (const host of hosts) {
         if (multi)
             process.stdout.write(chalk.cyan(`\n── ${host} ──\n`));
+        // Cache-first: a warm hit skips SSH entirely so reachable hosts share one
+        // snapshot across menubar/CLI/watchdog instead of re-fanning every call.
+        if (!forceRefresh && serveWarmRemoteCache(host, forwarded, {
+            maxAgeMs: opts.maxAgeMs,
+            nowMs: opts.nowMs,
+        })) {
+            continue;
+        }
         // Per-host: a Windows peer needs a PowerShell command, POSIX peers `bash -lc`.
         const remoteCmd = buildRemoteCommand(forwarded, cols, resolveRemoteOsSync(host));
         const res = spawnSync('ssh', [...SSH_OPTS, ...controlOpts(), host, remoteCmd], {

package/dist/lib/session/resume-command.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The one public command used by UI and lifecycle consumers to reopen a session.
+ * `agents resume` owns identity resolution, source-device routing, version/home
+ * selection, and harness-specific continuation; callers must not recreate it.
+ */
+export declare function buildCanonicalResumeCommand(sessionId: string): string[];

package/dist/lib/session/resume-command.js

@@ -0,0 +1,8 @@
+/**
+ * The one public command used by UI and lifecycle consumers to reopen a session.
+ * `agents resume` owns identity resolution, source-device routing, version/home
+ * selection, and harness-specific continuation; callers must not recreate it.
+ */
+export function buildCanonicalResumeCommand(sessionId) {
+    return ['agents', 'resume', sessionId];
+}

package/dist/lib/session/session-cache.d.ts

@@ -0,0 +1,173 @@
+import type { ActiveSession } from './active.js';
+/**
+ * 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 declare const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 15000;
+/** Daemon warm interval — keep in sync with the setInterval in `lib/daemon.ts`. */
+export declare const SESSION_CACHE_WARM_INTERVAL_MS = 15000;
+/** Kick off the first warm ~25s after daemon start (staggered off other ticks). */
+export declare const SESSION_CACHE_WARM_KICKOFF_MS = 25000;
+/** Snapshot scope: this host only, or a fleet-wide merge written by a reader. */
+export type ActiveCacheScope = 'local' | 'fleet';
+export interface ActiveSessionsSnapshot {
+    version: 1;
+    scope: ActiveCacheScope;
+    /** Epoch ms the sessions array was captured. */
+    capturedAt: number;
+    sessions: ActiveSession[];
+    /** Peer count from the last fleet gather (fleet scope only). */
+    remoteDeviceCount?: number;
+}
+/**
+ * Per-session fields that are stable until the transcript changes. Keyed on
+ * transcript mtime so a rewrite invalidates them. Live status is intentionally
+ * absent — see {@link LIVE_STATUS_KEYS}.
+ */
+export interface ImmutableSessionFields {
+    topic?: string;
+    label?: string;
+    name?: string;
+    cwd?: string;
+    project?: string | null;
+    attachments?: ActiveSession['attachments'];
+    startedAtMs?: number;
+    version?: string;
+    pr?: ActiveSession['pr'];
+    worktree?: ActiveSession['worktree'];
+    ticket?: ActiveSession['ticket'];
+    createdTickets?: string[];
+    spawnedTeam?: string;
+    sessionFile?: string;
+    owner?: string;
+    assignedTask?: string;
+    kind?: string;
+    context?: ActiveSession['context'];
+}
+/** Keys stored in the immutable memo (transcript-stable). */
+export declare const IMMUTABLE_FIELD_KEYS: readonly ["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 declare const LIVE_STATUS_KEYS: readonly ["status", "activity", "preview", "tokPerSec", "awaitingReason", "question", "todos", "tail", "lastActivityMs", "hostLink", "presence", "pidAlive", "tmuxClients", "windowHeartbeatMs", "provenance", "rateLimited", "plan"];
+/** Test seam: redirect the snapshot file. Returns the previous override. */
+export declare function setActiveSessionsSnapshotPathForTest(p: string | null): string | null;
+/** Test seam: redirect the immutable-memo file. Returns the previous override. */
+export declare function setImmutableMemoPathForTest(p: string | null): string | null;
+/** Read one scope from the snapshot file (best-effort; missing/corrupt → null). */
+export declare function readActiveSessionsCache(scope: ActiveCacheScope): ActiveSessionsSnapshot | 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 declare function writeActiveSessionsCache(scope: ActiveCacheScope, sessions: ActiveSession[], opts?: {
+    capturedAt?: number;
+    remoteDeviceCount?: number;
+}): ActiveSessionsSnapshot;
+/**
+ * True when a snapshot is still within the freshness window. Pure — the
+ * staleness invariant for live status lives here.
+ */
+export declare function isActiveSnapshotFresh(capturedAt: number, nowMs: number, maxAgeMs?: number): boolean;
+/** Pull only the transcript-stable fields from a live row. */
+export declare function pickImmutableFields(s: ActiveSession): ImmutableSessionFields;
+/**
+ * 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 declare function transcriptMtimeMs(s: ActiveSession): number | null;
+/**
+ * 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 declare function readImmutableMemo(sessionId: string, mtimeMs: number): ImmutableSessionFields | null;
+/** Persist immutable fields for `(sessionId, mtimeMs)`. Live keys are stripped. */
+export declare function writeImmutableMemo(sessionId: string, mtimeMs: number, fields: ImmutableSessionFields, nowMs?: number): void;
+/** Drop every live-status key from a field bag (defence in depth). */
+export declare function stripLiveStatusKeys<T extends Record<string, unknown>>(fields: T): T;
+/**
+ * True when `fields` contains no live-status key. The invariant the tests pin:
+ * the immutable memo never carries status/activity/preview/etc.
+ */
+export declare function assertNoLiveStatusFields(fields: Record<string, unknown>): boolean;
+/**
+ * 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 declare function updateImmutableMemos(sessions: ReadonlyArray<ActiveSession>, nowMs?: number): void;
+/**
+ * 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 declare function applyImmutableMemo(s: ActiveSession): ActiveSession;
+export interface LoadLocalActiveSessionsOptions {
+    /** Skip the cache and re-gather (the force-refresh path). */
+    forceRefresh?: boolean;
+    /** Freshness window; defaults to {@link DEFAULT_ACTIVE_CACHE_MAX_AGE_MS}. */
+    maxAgeMs?: number;
+    /** Clock (injectable for tests). */
+    nowMs?: number;
+    /**
+     * Live gather. Defaults to `getActiveSessions({ localOnly: true })` so a
+     * warm never dials a remote-host teammate (RUSH-2118).
+     */
+    gather?: () => Promise<ActiveSession[]>;
+    /** Injectable cache IO for tests. */
+    readCache?: typeof readActiveSessionsCache;
+    writeCache?: typeof writeActiveSessionsCache;
+}
+export interface LoadLocalActiveSessionsResult {
+    sessions: ActiveSession[];
+    /** True when the row set came from the warm snapshot, not a live gather. */
+    servedFromCache: boolean;
+    capturedAt: number;
+}
+/**
+ * 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 declare function loadLocalActiveSessions(opts?: LoadLocalActiveSessionsOptions): Promise<LoadLocalActiveSessionsResult>;
+export interface LoadFleetActiveSessionsOptions {
+    forceRefresh?: boolean;
+    maxAgeMs?: number;
+    nowMs?: number;
+    /** Live fleet gather (local + remote). Required — this module does not own SSH. */
+    gather: () => Promise<{
+        sessions: ActiveSession[];
+        remoteDeviceCount: number;
+    }>;
+    readCache?: typeof readActiveSessionsCache;
+    writeCache?: typeof writeActiveSessionsCache;
+}
+export interface LoadFleetActiveSessionsResult {
+    sessions: ActiveSession[];
+    remoteDeviceCount: number;
+    servedFromCache: boolean;
+    capturedAt: number;
+}
+/**
+ * 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 declare function loadFleetActiveSessions(opts: LoadFleetActiveSessionsOptions): Promise<LoadFleetActiveSessionsResult>;
+/**
+ * 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 declare function publishLocalActiveSessions(opts?: {
+    gather?: () => Promise<ActiveSession[]>;
+    nowMs?: number;
+}): Promise<{
+    sessions: ActiveSession[];
+    capturedAt: number;
+}>;