@phnx-labs/agents-cli 1.22.23 → 1.22.25

package/dist/lib/secrets/reaper.js

@@ -90,25 +90,47 @@ export function planKeychainReap(snapshots, now, prevCandidates) {
     }
     return { kill, nextCandidates };
 }
+/**
+ * Parse macOS `ps -o etime=` elapsed time into whole seconds.
+ *
+ * BSD `etime` renders as `[[dd-]hh:]mm:ss` (e.g. `05:03`, `01:02:03`,
+ * `14-04:10:52`). This is the portable keyword: `etimes` (raw seconds) is a
+ * GNU/Linux procps extension that macOS `ps` rejects with a non-zero exit, so
+ * the reaper — which only ever runs on darwin — must read `etime`.
+ * Returns null for an unparseable value so the caller drops the row.
+ */
+export function parseEtimeToSeconds(raw) {
+    const m = raw.match(/^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/);
+    if (!m)
+        return null;
+    const days = m[1] ? parseInt(m[1], 10) : 0;
+    const hours = m[2] ? parseInt(m[2], 10) : 0;
+    const mins = parseInt(m[3], 10);
+    const secs = parseInt(m[4], 10);
+    if ([days, hours, mins, secs].some(isNaN))
+        return null;
+    return ((days * 24 + hours) * 60 + mins) * 60 + secs;
+}
 /**
  * Parse one `ps` output line.
  *
- * Expected format from `ps -ax -o pid=,ppid=,etimes=,command=`:
- *   "<pid> <ppid> <etimes> <command...>"
- * The command field is the remainder of the line and may contain spaces.
+ * Expected format from `ps -ax -o pid=,ppid=,etime=,command=`:
+ *   "<pid> <ppid> <etime> <command...>"
+ * where `<etime>` is BSD elapsed time (`[[dd-]hh:]mm:ss`). The command field is
+ * the remainder of the line and may contain spaces.
  */
 function parsePsLine(line) {
     const trimmed = line.trim();
     if (!trimmed)
         return null;
-    const m = trimmed.match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/);
+    const m = trimmed.match(/^(\d+)\s+(\d+)\s+(\S+)\s+(.*)$/);
     if (!m)
         return null;
     const pid = parseInt(m[1], 10);
     const ppid = parseInt(m[2], 10);
-    const elapsedSec = parseInt(m[3], 10);
+    const elapsedSec = parseEtimeToSeconds(m[3]);
     const command = m[4];
-    if (isNaN(pid) || isNaN(ppid) || isNaN(elapsedSec))
+    if (isNaN(pid) || isNaN(ppid) || elapsedSec == null)
         return null;
     return { pid, ppid, elapsedSec, command };
 }
@@ -142,7 +164,7 @@ export function reapOrphanedKeychainProcesses() {
     }
     let out;
     try {
-        out = execFileSync('ps', ['-ax', '-o', 'pid=,ppid=,etimes=,command='], {
+        out = execFileSync('ps', ['-ax', '-o', 'pid=,ppid=,etime=,command='], {
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'ignore'],
         });
@@ -150,7 +172,7 @@ export function reapOrphanedKeychainProcesses() {
     catch (err) {
         return { reaped: 0, details: [`ps failed: ${err.message}`], plan: { kill: [], nextCandidates: new Map() } };
     }
-    const snapshots = [];
+    const rows = [];
     for (const line of out.split('\n')) {
         const parsed = parsePsLine(line);
         if (!parsed)
@@ -159,14 +181,27 @@ export function reapOrphanedKeychainProcesses() {
         // Exact path-match: the helper invocation's command line begins with the
         // absolute helper path, followed by a space and its arguments (or nothing).
         const isHelper = command === helperPath || command.startsWith(`${helperPath} `);
-        snapshots.push({
-            pid,
-            ppid,
-            elapsedSec,
-            startTime: captureProcessStartTime(pid),
-            isHelper,
-        });
+        rows.push({ pid, ppid, elapsedSec, isHelper, startTime: null });
+    }
+    const rowByPid = new Map(rows.map((r) => [r.pid, r]));
+    for (const row of rows) {
+        if (!row.isHelper)
+            continue;
+        row.startTime = captureProcessStartTime(row.pid);
+        if (row.ppid !== 1 && row.elapsedSec > STUCK_GRACE_SEC) {
+            const parent = rowByPid.get(row.ppid);
+            if (parent && parent.startTime === null) {
+                parent.startTime = captureProcessStartTime(row.ppid);
+            }
+        }
     }
+    const snapshots = rows.map((r) => ({
+        pid: r.pid,
+        ppid: r.ppid,
+        elapsedSec: r.elapsedSec,
+        startTime: r.startTime,
+        isHelper: r.isHelper,
+    }));
     const plan = planKeychainReap(snapshots, Date.now(), stuckParentCandidates);
     stuckParentCandidates = plan.nextCandidates;
     for (const pid of plan.kill) {

package/dist/lib/secrets/sync-passphrase.d.ts

@@ -0,0 +1,27 @@
+/** The current variable for transport/sync passphrases. */
+export declare const SYNC_PASSPHRASE_ENV = "AGENTS_SYNC_PASSPHRASE";
+/** The file-store master key, honoured for sync only as a deprecated fallback. */
+export declare const LEGACY_PASSPHRASE_ENV = "AGENTS_SECRETS_PASSPHRASE";
+/** Reset the one-shot warning latches. Tests only — production never re-warns. */
+export declare function resetSyncPassphraseWarnings(): void;
+/** Where a resolved sync passphrase came from, so callers can report honestly. */
+export type SyncPassphraseSource = 'sync-env' | 'legacy-env' | null;
+export interface ResolvedSyncPassphrase {
+    value: string | null;
+    source: SyncPassphraseSource;
+}
+/**
+ * Read the transport passphrase from the environment, preferring the current
+ * variable and falling back to the deprecated one with a single warning.
+ * Returns `{ value: null }` when neither is set — the caller decides whether to
+ * prompt (TTY) or fail (headless). Never prompts, never throws.
+ */
+export declare function resolveSyncPassphraseFromEnv(): ResolvedSyncPassphrase;
+/**
+ * The one-shot reminder that an env-sourced passphrase is readable by other
+ * same-user processes. Separate from the deprecation notice above so a caller
+ * using the CURRENT variable still gets the readability warning exactly once.
+ */
+export declare function warnEnvPassphraseReadableOnce(): void;
+/** The message a headless caller shows when no passphrase is available. */
+export declare function missingSyncPassphraseMessage(): string;

package/dist/lib/secrets/sync-passphrase.js

@@ -0,0 +1,78 @@
+/**
+ * The passphrase that seals a bundle for TRANSPORT — `secrets push`/`pull` and
+ * the portable `export --to-file` / `import --from-file` envelope.
+ *
+ * This is deliberately a DIFFERENT secret from the file store's master key
+ * (`AGENTS_SECRETS_PASSPHRASE`, `filestore.ts:getPassphrase`). The two were one
+ * variable, and that overload is what put a master key into `~/.zshenv` on seven
+ * worker boxes (RUSH-1968): the file store stopped needing a passphrase once it
+ * auto-provisioned a machine-local key, but headless `push`/`pull` still hard-
+ * failed without one, so an operator exported the master key fleet-wide to make
+ * sync work — handing every same-user process the key to the whole store.
+ *
+ * Splitting them means a box that only needs headless sync sets
+ * `AGENTS_SYNC_PASSPHRASE` and never has the store's master key in its
+ * environment at all.
+ *
+ * Resolution order:
+ *   1. `AGENTS_SYNC_PASSPHRASE`        — the current name.
+ *   2. `AGENTS_SECRETS_PASSPHRASE`     — deprecated fallback, warns once.
+ *   3. (caller prompts, or fails)
+ *
+ * The fallback exists so already-scripted CI and release automation keep working
+ * across the upgrade; it is not a second supported spelling.
+ */
+import chalk from 'chalk';
+/** The current variable for transport/sync passphrases. */
+export const SYNC_PASSPHRASE_ENV = 'AGENTS_SYNC_PASSPHRASE';
+/** The file-store master key, honoured for sync only as a deprecated fallback. */
+export const LEGACY_PASSPHRASE_ENV = 'AGENTS_SECRETS_PASSPHRASE';
+/** Warn at most once per process: a `--all` push over many bundles must not
+ *  flood stderr with the same notice. */
+let deprecatedVarWarned = false;
+/** Same, for the "this came from an env var at all" readability notice. */
+let envPassphraseWarned = false;
+/** Reset the one-shot warning latches. Tests only — production never re-warns. */
+export function resetSyncPassphraseWarnings() {
+    deprecatedVarWarned = false;
+    envPassphraseWarned = false;
+}
+/**
+ * Read the transport passphrase from the environment, preferring the current
+ * variable and falling back to the deprecated one with a single warning.
+ * Returns `{ value: null }` when neither is set — the caller decides whether to
+ * prompt (TTY) or fail (headless). Never prompts, never throws.
+ */
+export function resolveSyncPassphraseFromEnv() {
+    const current = process.env[SYNC_PASSPHRASE_ENV];
+    if (current)
+        return { value: current, source: 'sync-env' };
+    const legacy = process.env[LEGACY_PASSPHRASE_ENV];
+    if (legacy) {
+        if (!deprecatedVarWarned) {
+            deprecatedVarWarned = true;
+            process.stderr.write(chalk.yellow(`warn: ${LEGACY_PASSPHRASE_ENV} is deprecated for sync — it is the file store's master key, ` +
+                `not a transport passphrase. Set ${SYNC_PASSPHRASE_ENV} instead; the old name still works ` +
+                'for now. Keeping the master key in the environment exposes the whole store to every ' +
+                'same-user process (RUSH-1968).\n'));
+        }
+        return { value: legacy, source: 'legacy-env' };
+    }
+    return { value: null, source: null };
+}
+/**
+ * The one-shot reminder that an env-sourced passphrase is readable by other
+ * same-user processes. Separate from the deprecation notice above so a caller
+ * using the CURRENT variable still gets the readability warning exactly once.
+ */
+export function warnEnvPassphraseReadableOnce() {
+    if (envPassphraseWarned)
+        return;
+    envPassphraseWarned = true;
+    process.stderr.write(chalk.yellow('warn: using a sync passphrase from the environment. Env vars are readable by other ' +
+        'same-user processes (/proc, ps, crash dumps, CI logs) — rotate after CI use.\n'));
+}
+/** The message a headless caller shows when no passphrase is available. */
+export function missingSyncPassphraseMessage() {
+    return `A sync passphrase is required. Run from a TTY, or set ${SYNC_PASSPHRASE_ENV}.`;
+}

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

@@ -126,6 +126,10 @@ export interface ActiveSession {
      */
     lastActivityMs?: number;
     status: ActiveStatus;
+    /** Indexed launch origin, backfilled by the sessions command for JSON consumers. */
+    origin?: 'cli' | 'routine';
+    /** Routine definition name when origin is `routine`. */
+    routineName?: string;
     /**
      * Foreground/background presence for the detach/attach model:
      *   `attached`   — live interactive TUI you're watching;

package/dist/lib/session/db.js

@@ -12,7 +12,7 @@ import Database from '../sqlite.js';
 import { parseSession } from './parse.js';
 import { extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
 import { getSessionsDir, getSessionsDbPath } from '../state.js';
-import { query as queryEvents } from '../events.js';
+import { query as queryEvents, queryToolUsageForSessions } from '../events.js';
 import { machineForSessionFile } from './origin-machine.js';
 import { loadSessionActorIndex, readSessionActorRecord } from './actor-sidecar.js';
 import { toolCallsFromEvents } from './tool-calls.js';
@@ -1648,6 +1648,12 @@ export function upsertSessionsBatch(entries) {
         }
     });
     const writtenEntries = [];
+    // Pre-compute browser/computer usage for all sessions outside the write
+    // transaction. detectToolUsage scans all event log files (O(files) I/O
+    // per call) and holding the SQLite write lock during that scan is what
+    // causes the "DB locked" errors (RUSH-2006). One pass for the whole batch
+    // costs O(files) total instead of O(N × files) inside the lock.
+    const toolUsageBySession = queryToolUsageForSessions(new Set(enrichedEntries.map(e => e.meta.id)));
     const txn = db.transaction((items) => {
         // Re-read the ledger now that we hold the write lock. Any file committed
         // by a concurrent process since our pre-scan is visible here.
@@ -1678,7 +1684,7 @@ export function upsertSessionsBatch(entries) {
             // back when the error escapes `fn`, so catching + skipping here leaves the txn valid
             // and committable. We deliberately do NOT stamp the ledger for a skipped row, so the
             // next scan re-tries it (self-healing once the underlying parser is fixed).
-            const toolUsage = detectToolUsage(meta.id);
+            const toolUsage = toolUsageBySession.get(meta.id) ?? { usedBrowser: false, usedComputer: false };
             // claude/codex skip enrichCachedSessionMeta above (preserving their
             // resumable-parse optimization) — write their pre-computed
             // skillsUsed/slashCommandsUsed (folded incrementally by discover.ts's

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

@@ -0,0 +1,37 @@
+import { type RotateCandidate } from '../rotate.js';
+import type { AgentId } from '../types.js';
+import type { SessionMeta } from './types.js';
+export type SessionRecoveryTarget = {
+    mode: 'native';
+    agent: AgentId;
+    version: string;
+    reason: string;
+} | {
+    mode: 'continue';
+    agent: AgentId;
+    version: string;
+    reason: string;
+};
+export declare class SessionRecoveryError extends Error {
+    constructor(message: string);
+}
+/** Canonical origin-device label for every recovery consumer. */
+export declare function sessionOriginDevice(session: Pick<SessionMeta, 'machine'>, self?: string): string;
+/** The peer that must execute recovery, or undefined when this is the origin. */
+export declare function sessionRecoveryPeer(session: Pick<SessionMeta, 'machine'>, selfCheck?: (host: string) => boolean): string | undefined;
+/** Whether an explicit placement names the session's origin device. */
+export declare function sessionRecoveryDestinationMatches(session: Pick<SessionMeta, 'machine'>, requestedHost: string, self?: string): boolean;
+/**
+ * Decide how a durable session resumes on the device that owns it.
+ *
+ * Native resume is legal only in the exact origin version's isolated home and
+ * only while that account is healthy. Every other successful path stays on the
+ * same harness and uses `/continue`, whose indexed transcript reader can reach
+ * retained version trash. No healthy same-harness account is a loud failure.
+ */
+export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean): SessionRecoveryTarget;
+export declare function resolveSessionRecovery(session: SessionMeta): Promise<SessionRecoveryTarget>;
+/** Stable self-command used by focus, resume, and attach. The owning device runs
+ * the recovery resolver above; callers must not native-resume another version's
+ * isolated home themselves. */
+export declare function sessionRecoveryRunArgs(session: Pick<SessionMeta, 'id'>): string[];

package/dist/lib/session/recovery.js

@@ -0,0 +1,95 @@
+import { AGENTS } from '../agents.js';
+import { isSelfHost } from '../devices/self-host.js';
+import { nativeResume } from '../exec.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { collectRunCandidates, formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../rotate.js';
+export class SessionRecoveryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SessionRecoveryError';
+    }
+}
+/** Canonical origin-device label for every recovery consumer. */
+export function sessionOriginDevice(session, self = machineId()) {
+    return normalizeHost(session.machine ?? self);
+}
+/** The peer that must execute recovery, or undefined when this is the origin. */
+export function sessionRecoveryPeer(session, selfCheck = isSelfHost) {
+    if (!session.machine || selfCheck(session.machine))
+        return undefined;
+    return normalizeHost(session.machine);
+}
+/** Whether an explicit placement names the session's origin device. */
+export function sessionRecoveryDestinationMatches(session, requestedHost, self = machineId()) {
+    const requested = normalizeHost(requestedHost.split('@').pop() || requestedHost);
+    return requested === sessionOriginDevice(session, self);
+}
+function runnableSessionAgent(session) {
+    if (!(session.agent in AGENTS)) {
+        throw new SessionRecoveryError(`Session ${session.shortId} belongs to ${session.agent}, which is indexed but cannot be launched by agents run.`);
+    }
+    return session.agent;
+}
+function sourceReason(session, candidates) {
+    if (!session.version)
+        return 'the origin version was not recorded';
+    const source = candidates.find((candidate) => candidate.version === session.version);
+    if (!source)
+        return `origin ${session.agent}@${session.version} is not installed`;
+    const readiness = readinessFromCandidate(source);
+    return readiness.ready
+        ? `origin ${session.agent}@${session.version} has no native resume form`
+        : `origin ${session.agent}@${session.version} is ${readiness.reason}`;
+}
+/**
+ * Decide how a durable session resumes on the device that owns it.
+ *
+ * Native resume is legal only in the exact origin version's isolated home and
+ * only while that account is healthy. Every other successful path stays on the
+ * same harness and uses `/continue`, whose indexed transcript reader can reach
+ * retained version trash. No healthy same-harness account is a loud failure.
+ */
+export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume) {
+    const agent = runnableSessionAgent(session);
+    const device = sessionOriginDevice(session);
+    const source = session.version
+        ? candidates.find((candidate) => candidate.version === session.version)
+        : undefined;
+    const sourceReady = source ? readinessFromCandidate(source).ready : false;
+    // An exact healthy origin is deterministic: preserve its isolated home. If
+    // native resume is unavailable for that harness, /continue still launches in
+    // that same healthy home. Only an unusable/missing origin enters balanced
+    // account selection.
+    const selection = sourceReady
+        ? { picked: source }
+        : pickBalancedCandidate(candidates);
+    if (!selection) {
+        const detail = formatNoHealthyAccountError(agent, 'balanced', candidates);
+        throw new SessionRecoveryError(`Cannot recover session ${session.shortId} on ${device}; origin ${agent}@${session.version ?? 'unknown'}. ${detail}`);
+    }
+    const version = selection.picked.version;
+    if (session.version === version && supportsNative(agent, version)) {
+        return {
+            mode: 'native',
+            agent,
+            version,
+            reason: `origin ${agent}@${version} is installed and healthy`,
+        };
+    }
+    return {
+        mode: 'continue',
+        agent,
+        version,
+        reason: `${sourceReason(session, candidates)}; continuing with healthy ${agent}@${version}`,
+    };
+}
+export async function resolveSessionRecovery(session) {
+    const agent = runnableSessionAgent(session);
+    return resolveSessionRecoveryFromCandidates(session, await collectRunCandidates(agent));
+}
+/** Stable self-command used by focus, resume, and attach. The owning device runs
+ * the recovery resolver above; callers must not native-resume another version's
+ * isolated home themselves. */
+export function sessionRecoveryRunArgs(session) {
+    return ['run', 'auto', '--resume', session.id, '--interactive'];
+}

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

@@ -81,6 +81,8 @@ export interface GatherRemoteListOptions {
      * know whether the match is unique or conflicting.
      */
     isDefinitive?: (session: SessionMeta, machine: string) => boolean;
+    /** Per-peer deadline for slower indexed browse queries. */
+    timeoutMs?: number;
 }
 export declare function gatherRemoteList(forwardedArgs: string[], hosts?: string[], opts?: GatherRemoteListOptions): Promise<RemoteListResult>;
 export interface RemoteToolSearchResult {

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

@@ -197,6 +197,7 @@ export async function gatherRemoteList(forwardedArgs, hosts, opts) {
         args: forwardedArgs,
         noFanoutEnv: NO_FANOUT_ENV,
         hosts,
+        timeoutMs: opts?.timeoutMs,
         earlyExit: opts?.isDefinitive ? { isDefinitive: opts.isDefinitive } : undefined,
         parse: (stdout, machine) => parseRemoteListPayload(stdout, machine, safeResolver),
     });

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

@@ -4,11 +4,11 @@ import type { ActiveSession } from './active.js';
  * 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;
+export declare const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS: number;
 /** 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;
+export declare const SESSION_CACHE_WARM_INTERVAL_MS: number;
+/** Kick off the first warm 30s after daemon start (staggered off other ticks). */
+export declare const SESSION_CACHE_WARM_KICKOFF_MS = 30000;
 /** Snapshot scope: this host only, or a fleet-wide merge written by a reader. */
 export type ActiveCacheScope = 'local' | 'fleet';
 export interface ActiveSessionsSnapshot {

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

@@ -34,11 +34,11 @@ const IMMUTABLE_FILE = '.active-session-immutable.json';
  * 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;
+export const DEFAULT_ACTIVE_CACHE_MAX_AGE_MS = 4 * 60_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;
+export const SESSION_CACHE_WARM_INTERVAL_MS = 3 * 60_000;
+/** Kick off the first warm 30s after daemon start (staggered off other ticks). */
+export const SESSION_CACHE_WARM_KICKOFF_MS = 30_000;
 /** Keys stored in the immutable memo (transcript-stable). */
 export const IMMUTABLE_FIELD_KEYS = [
     'topic',

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 = 28;
+export declare const SHIM_SCHEMA_VERSION = 29;
 /**
  * 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 = 14;
+export declare const VERSIONED_ALIAS_SCHEMA_VERSION = 15;
 /**
  * Agents whose config directory can be relocated by an environment variable
  * (the per-agent `managedEnv` block in `generateVersionedAliasScript` below).

package/dist/lib/shims.js

@@ -223,7 +223,7 @@ 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 = 28;
+export const SHIM_SCHEMA_VERSION = 29;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -299,7 +299,18 @@ export OPENCODE_CONFIG_DIR="$VERSION_DIR/home/.config/opencode"
 # mcp.json, sessions, skills, hooks). Point it at the versioned home.
 export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
 `
-                            : '';
+                            : agent === 'muse'
+                                ? `
+# Muse Code has no MUSE_CONFIG_DIR. It resolves config via XDG:
+#   $XDG_CONFIG_HOME/muse  (settings, skills, hooks, auth)
+#   $XDG_DATA_HOME/muse    (sessions, plugins)
+# Pin XDG into the version home so managed runs never walk the adopt-time
+# ~/.config/muse -> version-home symlink — Muse refuses agent-definition
+# sources that are SymlinkOrReparse (exit 1). Same idea as CLAUDE_CONFIG_DIR.
+export XDG_CONFIG_HOME="$VERSION_DIR/home/.config"
+export XDG_DATA_HOME="$VERSION_DIR/home/.local/share"
+`
+                                : '';
     const launchArgs = agent === 'codex' ? ` ${codexShimLaunchArgs()}` : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
@@ -573,6 +584,18 @@ elif [ "$AGENT" = "muse" ]; then
       esac
     fi
   fi
+elif [ "$AGENT" = "warp" ]; then
+  # Warp Agent CLI installs a global, self-updating oz binary (brew cask on
+  # macOS, the oz-stable apt|yum|pacman package on Linux) -- a platform/package
+  # specific location, not ~/.local/bin -- so resolve it from PATH with the same
+  # shims-dir re-exec guard as droid/muse.
+  BINARY=$(adopted_original_bin || echo "")
+  if [ -z "$BINARY" ]; then
+    BINARY=$(command -v oz 2>/dev/null || echo "")
+    case "$(readlink -f "$BINARY" 2>/dev/null)" in
+      "$AGENTS_USER_DIR/.cache/shims/"*) BINARY="" ;;
+    esac
+  fi
 else
   BINARY="$VERSION_DIR/node_modules/.bin/$CLI_COMMAND"
 fi
@@ -871,7 +894,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 = 14;
+export const VERSIONED_ALIAS_SCHEMA_VERSION = 15;
 /** 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
@@ -898,7 +921,7 @@ function assertSafeVersion(version) {
  * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
  * The colocated test `shims.isolation-capability.test.ts` enforces this.
  */
-export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi', 'opencode'];
+export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi', 'opencode', 'muse'];
 /**
  * Whether an agent supports a clean `--isolated` install — i.e. its config
  * location can be redirected by an env var so the isolated copy stays fully
@@ -956,7 +979,15 @@ export OPENCODE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/
 # mcp.json, sessions, skills, hooks). Point direct aliases at the versioned home.
 export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                            : '';
+                            : agent === 'muse'
+                                ? `
+# Muse Code: no dedicated config env var. Pin XDG so config/sessions live under
+# the version home as real directories (not via the adopt symlink at
+# ~/.config/muse, which Muse rejects with SymlinkOrReparse).
+export XDG_CONFIG_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.config"
+export XDG_DATA_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/.local/share"
+`
+                                : '';
     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
@@ -1022,7 +1053,15 @@ else
     "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
   esac
 fi`
-                : `BINARY="${versionDir}/node_modules/.bin/${agentConfig.cliCommand}"`;
+                : agent === 'warp'
+                    ? `# Warp Agent CLI installs a global self-updating \`oz\` binary (brew cask on
+# macOS, oz-stable apt|yum|pacman on Linux) — a platform-specific location, not
+# ~/.local/bin — so resolve it from PATH, refusing anything under our shims dir.
+BINARY=$(command -v oz 2>/dev/null || echo "")
+case "$BINARY" in
+  "$HOME/.agents/.cache/shims/"*) BINARY="" ;;
+esac`
+                    : `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/signin-badge.js

@@ -24,6 +24,8 @@ export function loginHint(agentId) {
             return `${cli}, then /login`;
         case 'codex':
         case 'grok':
+        // Warp Agent CLI: `oz login` opens a browser sign-in (or set WARP_API_KEY).
+        case 'warp':
             return `${cli} login`;
         case 'opencode':
             return `${cli} auth login`;

package/dist/lib/startup/command-registry.d.ts

@@ -51,6 +51,7 @@ export declare const loadFork: ModuleLoader;
 export declare const loadDefaults: ModuleLoader;
 export declare const loadSet: ModuleLoader;
 export declare const loadModels: ModuleLoader;
+export declare const loadModes: ModuleLoader;
 export declare const loadPrune: ModuleLoader;
 export declare const loadTrash: ModuleLoader;
 export declare const loadRestore: ModuleLoader;
@@ -130,3 +131,18 @@ export declare const LAZY_COMMAND_NAMES: ReadonlySet<string>;
  * are handled directly in src/index.ts.
  */
 export declare const COMMAND_LOADERS: Record<string, ModuleLoader[]>;
+/**
+ * Every top-level command name the CLI answers to — the loader table plus the
+ * inline aliases/tombstones above. This is the "does this command exist?"
+ * predicate for code that runs BEFORE commander parses, most importantly the
+ * `--host`/`--device` router (lib/hosts/passthrough.ts): without it a typo'd
+ * command carrying `--host` reported a flag-support error instead of
+ * `unknown command` (RUSH-2022).
+ *
+ * Commander sub-aliases (`sessions ls`, `teams rm`, …) are deliberately absent —
+ * this set is top-level only. `command-registry.test.ts` pins it against the real
+ * registered command tree so a new command can never drift out of it.
+ */
+export declare const KNOWN_TOP_LEVEL_COMMANDS: ReadonlySet<string>;
+/** Whether `name` is a top-level command this CLI registers. See {@link KNOWN_TOP_LEVEL_COMMANDS}. */
+export declare function isKnownTopLevelCommand(name: string): boolean;