@phnx-labs/agents-cli 1.22.24 → 1.22.25

package/dist/lib/routine-process-cleanup.js

@@ -0,0 +1,73 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { isAlive, killTree } from './platform/index.js';
+import { getRunsDir } from './state.js';
+function processMatchesRun(meta) {
+    if (!meta.pid || !meta.spawnedAt)
+        return false;
+    try {
+        if (process.platform === 'win32') {
+            const startedAt = execFileSync('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `(Get-Process -Id ${meta.pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString("o")`,
+            ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim();
+            const processStart = Date.parse(startedAt);
+            return Number.isFinite(processStart) && Math.abs(processStart - meta.spawnedAt) < 30_000;
+        }
+        const elapsed = execFileSync('ps', ['-p', String(meta.pid), '-o', 'etime='], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (!elapsed)
+            return false;
+        const fields = elapsed.replace(/-/g, ':').split(':').reverse();
+        const seconds = Number(fields[0] ?? 0)
+            + Number(fields[1] ?? 0) * 60
+            + Number(fields[2] ?? 0) * 3600
+            + Number(fields[3] ?? 0) * 86400;
+        return Math.abs((Date.now() - seconds * 1000) - meta.spawnedAt) < 30_000;
+    }
+    catch {
+        return false;
+    }
+}
+/** Reap process groups whose durable run record is already terminal. */
+export function reapTerminalRoutineProcesses(opts = {}) {
+    const runsDir = opts.runsDir ?? getRunsDir();
+    const alive = opts.alive ?? isAlive;
+    const owns = opts.owns ?? processMatchesRun;
+    const terminate = opts.terminate ?? ((pid) => killTree(process.platform === 'win32' ? pid : -pid));
+    if (!fs.existsSync(runsDir))
+        return [];
+    const reaped = [];
+    for (const job of fs.readdirSync(runsDir, { withFileTypes: true })) {
+        if (!job.isDirectory())
+            continue;
+        const jobDir = path.join(runsDir, job.name);
+        for (const run of fs.readdirSync(jobDir, { withFileTypes: true })) {
+            if (!run.isDirectory())
+                continue;
+            try {
+                const meta = JSON.parse(fs.readFileSync(path.join(jobDir, run.name, 'meta.json'), 'utf-8'));
+                if (!['failed', 'timeout'].includes(meta.status) || !meta.pid || meta.hostTaskId || meta.cloudTaskId)
+                    continue;
+                const completedAt = Date.parse(meta.completedAt ?? '');
+                if (!Number.isFinite(completedAt) || Date.now() - completedAt < 5_000)
+                    continue;
+                if (!alive(meta.pid))
+                    continue;
+                if (!owns(meta))
+                    continue;
+                terminate(meta.pid);
+                reaped.push(meta.pid);
+            }
+            catch {
+                // Corrupt or concurrently-replaced records are left untouched.
+            }
+        }
+    }
+    return reaped;
+}

package/dist/lib/runner.js

@@ -52,7 +52,7 @@ function activeRoutineRun(config) {
     const runs = listRuns(config.name);
     for (let i = runs.length - 1; i >= 0; i--) {
         const run = runs[i];
-        if (run.status !== 'running')
+        if (!['running', 'failed', 'timeout'].includes(run.status))
             continue;
         if (run.pid && isPidOurs(run.pid, run.spawnedAt))
             return run;
@@ -235,10 +235,10 @@ export function buildJobCommand(config, resolvedPrompt) {
         appendModelAndReasoning(cmd, config);
     }
     if (config.agent === 'cursor') {
-        // cursor-agent supports --plan, but the capability registry has not been
-        // upgraded yet. RUSH-2101 tracks adding that read-only mode after PR #1721.
-        const cursorMode = resolveHeadlessMode('cursor', mode, false, `routine ${config.name}`);
-        if (cursorMode === 'skip') {
+        if (mode === 'plan') {
+            cmd.push('--plan');
+        }
+        else if (mode === 'skip') {
             cmd.push('-f');
         }
         else {

package/dist/lib/secrets/bundles.js

@@ -55,19 +55,7 @@ const keychainStore = {
 const fileItemStore = {
     has: (item) => fileStore.has(item),
     get: (item) => fileStore.get(item),
-    getBatch: (items) => {
-        const out = new Map();
-        for (const item of items) {
-            try {
-                out.set(item, fileStore.get(item));
-            }
-            catch {
-                // Missing/undecryptable item — absent from the map, mirroring
-                // getKeychainTokens (caller decides whether that's an error).
-            }
-        }
-        return out;
-    },
+    getBatch: (items) => fileStore.getBatch(items),
     set: (item, value) => fileStore.set(item, value),
     setBatch: (items) => {
         for (const [item, value] of items) {
@@ -1340,13 +1328,6 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         : store.getBatch([...new Set([metaItem, ...secretItems])]);
     const json = fetched.get(metaItem);
     if (json === undefined) {
-        // For a file-backed bundle the metadata item is on disk (that's how
-        // bundleBackend resolved to 'file'); a missing decrypt means the wrong
-        // passphrase, not a missing bundle. getBatch swallowed the decrypt error,
-        // so distinguish here rather than report a misleading "not found".
-        if (backend === 'file' && fileStore.has(metaItem)) {
-            throw new Error(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store.`);
-        }
         if (vaultExists() && !getVaultSession().loggedIn) {
             throw new Error(`Synced secrets are locked. Run: agents login`);
         }

package/dist/lib/secrets/filestore.d.ts

@@ -53,6 +53,7 @@ export declare function encryptForFallback(plaintext: string, passphrase: string
 export declare function decryptForFallback(enc: EncFile, passphrase: string): string;
 declare function fileHas(item: string): boolean;
 declare function fileGet(item: string): string;
+declare function fileGetBatch(items: string[]): Map<string, string>;
 declare function fileSet(item: string, value: string): void;
 declare function fileDelete(item: string): boolean;
 declare function fileList(prefix: string): string[];
@@ -63,6 +64,7 @@ export declare function fileStoreHasItems(): boolean;
 export declare const fileStore: {
     has: typeof fileHas;
     get: typeof fileGet;
+    getBatch: typeof fileGetBatch;
     set: typeof fileSet;
     delete: typeof fileDelete;
     list: typeof fileList;

package/dist/lib/secrets/filestore.js

@@ -237,6 +237,18 @@ function fileGet(item) {
         throw new Error(`Failed to decrypt '${item}'. Wrong AGENTS_SECRETS_PASSPHRASE or tampered file.`);
     }
 }
+function fileGetBatch(items) {
+    const out = new Map();
+    for (const item of items) {
+        // A missing file is an absent item. Any error reading an existing file,
+        // especially an AES-GCM authentication failure, is a broken store and must
+        // stop the caller rather than silently produce an incomplete environment.
+        if (!fileHas(item))
+            continue;
+        out.set(item, fileGet(item));
+    }
+    return out;
+}
 function fileSet(item, value) {
     ensureFileDir();
     // Under the store lock: a write must not interleave with a rotation's swap.
@@ -283,6 +295,7 @@ export function fileStoreHasItems() {
 export const fileStore = {
     has: fileHas,
     get: fileGet,
+    getBatch: fileGetBatch,
     set: fileSet,
     delete: fileDelete,
     list: fileList,

package/dist/lib/secrets/rc-hygiene.d.ts

@@ -32,6 +32,20 @@ export interface RcSecretFinding {
     /** The file-store master passphrase gets called out separately — it is the highest-severity case. */
     isMasterPassphrase: boolean;
 }
+/** The file-store master key. Its own resolution prefers an off-env 0600 file, so
+ *  a shell-rc export is always wrong once the store exists (RUSH-1968). */
+export declare const MASTER_PASSPHRASE = "AGENTS_SECRETS_PASSPHRASE";
+/**
+ * True when the file-store master key is live in THIS process's environment.
+ *
+ * The scanner above reads FILES, and that leaves a hole: a value inherited by a
+ * long-lived process outlives the rc line that set it, so deleting the export
+ * makes `scanRcExports` report clean while every shell, editor and agent started
+ * beforehand still carries the key and passes it to everything it spawns.
+ * Returns a boolean — never the value — so a finding built from it can be
+ * printed, logged, or shipped without leaking the secret.
+ */
+export declare function masterPassphraseInEnv(): boolean;
 /** True if a variable name looks like it holds a credential value. */
 export declare function isCredentialName(name: string): boolean;
 /**

package/dist/lib/secrets/rc-hygiene.js

@@ -33,7 +33,20 @@ export const RC_FILENAMES = [
 ];
 /** The file-store master key. Its own resolution prefers an off-env 0600 file, so
  *  a shell-rc export is always wrong once the store exists (RUSH-1968). */
-const MASTER_PASSPHRASE = 'AGENTS_SECRETS_PASSPHRASE';
+export const MASTER_PASSPHRASE = 'AGENTS_SECRETS_PASSPHRASE';
+/**
+ * True when the file-store master key is live in THIS process's environment.
+ *
+ * The scanner above reads FILES, and that leaves a hole: a value inherited by a
+ * long-lived process outlives the rc line that set it, so deleting the export
+ * makes `scanRcExports` report clean while every shell, editor and agent started
+ * beforehand still carries the key and passes it to everything it spawns.
+ * Returns a boolean — never the value — so a finding built from it can be
+ * printed, logged, or shipped without leaking the secret.
+ */
+export function masterPassphraseInEnv() {
+    return (process.env[MASTER_PASSPHRASE] ?? '').length > 0;
+}
 /**
  * Last `_`-delimited segment values that mark a variable as credential-shaped.
  * Matched against the FINAL segment (segment equality, not substring) so

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

@@ -584,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
@@ -1041,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

@@ -131,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;

package/dist/lib/startup/command-registry.js

@@ -146,6 +146,11 @@ export const COMMAND_LOADERS = {
     registry: [loadPackages],
     search: [loadPackages],
     install: [loadPackages],
+    // packages.ts also registers `publish` at top level (commands/packages.ts:435).
+    // It was missing here, so `agents publish` only worked via the unknown-command
+    // fallback that registers the whole tree — and the --host router could not see
+    // it as a real command at all (RUSH-2022).
+    publish: [loadPackages],
     routines: [loadRoutines],
     monitors: [loadMonitors],
     projects: [loadProjects],
@@ -231,3 +236,40 @@ export const COMMAND_LOADERS = {
     funnel: [loadFunnel],
     humans: [loadHumans],
 };
+/**
+ * Top-level names that {@link COMMAND_LOADERS} does not carry because they are
+ * registered inline in src/index.ts — closures over entry-point state (the
+ * deprecated aliases and tombstones) plus the internal/upgrade commands. They are
+ * real commands, so anything that asks "does this command exist?" must count them.
+ */
+const INLINE_COMMAND_NAMES = [
+    'perms', // deprecated alias -> permissions
+    'exec', // deprecated alias -> run
+    'jobs', // deprecated alias -> routines
+    'cron', // deprecated alias -> routines
+    'check', // tombstone -> doctor --check
+    'resources', // tombstone -> view --merged
+    'hq', // tombstone
+    '_internal',
+    'upgrade',
+];
+/**
+ * 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 const KNOWN_TOP_LEVEL_COMMANDS = new Set([
+    ...Object.keys(COMMAND_LOADERS),
+    ...INLINE_COMMAND_NAMES,
+]);
+/** Whether `name` is a top-level command this CLI registers. See {@link KNOWN_TOP_LEVEL_COMMANDS}. */
+export function isKnownTopLevelCommand(name) {
+    return KNOWN_TOP_LEVEL_COMMANDS.has(name);
+}

package/dist/lib/teams/agents.js

@@ -197,7 +197,7 @@ export function buildTeammateSpawnEnv(envOverrides) {
  */
 export { captureProcessStartTime };
 /** Agent types the team runner supports. */
-const TEAM_AGENT_TYPES = ['codex', 'cursor', 'claude', 'opencode', 'grok', 'antigravity', 'kimi', 'droid'];
+const TEAM_AGENT_TYPES = ['codex', 'cursor', 'claude', 'opencode', 'grok', 'antigravity', 'kimi', 'droid', 'warp'];
 // Suffix appended to all prompts to ensure agents provide a summary
 const PROMPT_SUFFIX = `
 

package/dist/lib/teams/parsers.d.ts

@@ -1,5 +1,5 @@
 /** Supported agent CLI types for team spawning. */
-export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode' | 'grok' | 'antigravity' | 'kimi' | 'droid';
+export type AgentType = 'codex' | 'gemini' | 'cursor' | 'claude' | 'opencode' | 'grok' | 'antigravity' | 'kimi' | 'droid' | 'warp';
 /** Normalize a raw JSON event from any agent type into an array of unified event objects. */
 export declare function normalizeEvents(agentType: AgentType, raw: any): any[];
 /** Normalize a raw JSON event, returning only the first unified event (convenience wrapper). */

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' | 'muse';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi' | 'muse' | 'warp';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 export type RunEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';

package/dist/lib/versions.js

@@ -928,6 +928,21 @@ export function getBinaryPath(agent, version) {
             ? path.join(getHomeDir(), 'bin', 'muse.exe')
             : path.join(getHomeDir(), '.local', 'bin', 'muse');
     }
+    if (agent === 'warp') {
+        // Warp Agent CLI installs a single global, self-updating `oz` binary — brew
+        // cask on macOS, the `oz-stable` apt|yum|pacman package on Linux — so, unlike
+        // droid/muse (which land at ~/.local/bin), its install location is
+        // platform/package specific. Resolve the real binary on PATH (findInPath
+        // skips our own shims dir) so isVersionInstalled / agents view agree with
+        // what executes. When oz is not installed, fall back to a deterministic path
+        // that won't exist, so isVersionInstalled reports uninstalled honestly.
+        const onPath = findInPath('oz');
+        if (onPath)
+            return onPath;
+        return IS_WINDOWS
+            ? path.join(getHomeDir(), 'bin', 'oz.exe')
+            : '/opt/warpdotdev/oz-stable/oz';
+    }
     const versionDir = getVersionDir(agent, version);
     return path.join(versionDir, 'node_modules', '.bin', agentConfig.cliCommand);
 }
@@ -1539,7 +1554,7 @@ export async function installVersion(agent, version, onProgress, opts) {
         // exec itself forever. So we skip the resolver-backed agents here AND, for
         // everyone else, filter the shims dir out of the `which` candidates so the
         // same race can't bite a non-special-cased installScript agent.
-        if (agent !== 'grok' && agent !== 'droid' && agent !== 'muse') {
+        if (agent !== 'grok' && agent !== 'droid' && agent !== 'muse' && agent !== 'warp') {
             // findInPath is a pure-Node PATH scan that already skips our own shims
             // dir — so it returns the genuine install, never our dispatcher shim
             // (which sits ahead of ~/.local/bin on PATH and would otherwise be

package/dist/lib/watchdog/service.d.ts

@@ -0,0 +1,17 @@
+import { type ActiveSession } from '../session/active.js';
+import { type WatchdogThresholds, type WatchdogTickResult } from './runner.js';
+export interface WatchdogPassOptions {
+    nudge: boolean;
+    nudgeText?: string;
+    smart?: boolean;
+    smartAgent?: string;
+    thresholds?: WatchdogThresholds;
+    allowGhosttyFocus?: boolean;
+    sessions?: ActiveSession[];
+    stateDir?: string;
+    mailboxGc?: boolean;
+}
+export declare function loadWatchdogSessions(): Promise<ActiveSession[]>;
+export declare function runWatchdogMailboxGc(sessions: ActiveSession[]): void;
+/** Execute one watchdog pass from the daemon or the explicit CLI command. */
+export declare function runWatchdogPass(opts: WatchdogPassOptions): Promise<WatchdogTickResult>;

package/dist/lib/watchdog/service.js

@@ -0,0 +1,39 @@
+import * as path from 'path';
+import { gcMailbox } from '../mailbox-gc.js';
+import { mailboxIdForActiveSession } from '../mailbox-target.js';
+import { getActiveSessions } from '../session/active.js';
+import { loadLocalActiveSessions } from '../session/session-cache.js';
+import { getRuntimeStateDir } from '../state.js';
+import { runWatchdogTick } from './runner.js';
+export async function loadWatchdogSessions() {
+    const loaded = await loadLocalActiveSessions({
+        gather: () => getActiveSessions({ localOnly: true }),
+    });
+    return loaded.sessions;
+}
+export function runWatchdogMailboxGc(sessions) {
+    const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => Boolean(id)));
+    try {
+        gcMailbox(activeBoxIds);
+    }
+    catch {
+        // Housekeeping is retried by the next daemon tick.
+    }
+}
+/** Execute one watchdog pass from the daemon or the explicit CLI command. */
+export async function runWatchdogPass(opts) {
+    const sessions = opts.sessions ?? await loadWatchdogSessions();
+    const result = await runWatchdogTick({
+        nudge: opts.nudge,
+        nudgeText: opts.nudgeText,
+        smart: opts.smart,
+        smartAgent: opts.smartAgent,
+        thresholds: opts.thresholds,
+        allowGhosttyFocus: opts.allowGhosttyFocus,
+        stateDir: opts.stateDir ?? path.join(getRuntimeStateDir(), 'watchdog'),
+        sessions,
+    });
+    if (opts.mailboxGc !== false)
+        runWatchdogMailboxGc(sessions);
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.24",
+  "version": "1.22.25",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",