@phnx-labs/agents-cli 1.22.23 → 1.22.25

package/dist/commands/watchdog.js

@@ -10,27 +10,21 @@
  *   agents watchdog --nudge            one tick, actually injects (explicit opt-in)
  *   agents watchdog --watch            manual poll loop (dry unless --nudge)
  *   agents watchdog --json             machine-readable tick output (for the menu-bar)
- *   agents watchdog on|off             turn the always-on watchdog routine on/off
+ *   agents watchdog on|off             turn the device-local daemon pass on/off
  *   agents watchdog policy <id> <p>    per-session policy: off | keep | handsoff
  *
- * The always-on watchdog is a daemon-fired ROUTINE, not a private sentinel + a
- * hand-rolled loop. Its immutable definition comes from the system DotAgents
- * repo; on/off only changes this device's routine membership.
+ * The agents daemon is the sole automatic watchdog scheduler. The menu bar reads
+ * persisted state; it never runs a tick.
  */
 import chalk from 'chalk';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { getRuntimeStateDir } from '../lib/state.js';
-import { readJob, setJobEnabled } from '../lib/routines.js';
-import { getActiveSessions } from '../lib/session/active.js';
-import { loadLocalActiveSessions } from '../lib/session/session-cache.js';
-import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
-import { gcMailbox } from '../lib/mailbox-gc.js';
-import { devicesWithRoutineEnabled, routineEnabledOnThisDevice } from '../lib/routine-activation.js';
-import { runWatchdogTick, writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
+import { getConfigValue, setConfigValue } from '../lib/device-config.js';
+import { writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
 import { isWatchdogRotateEnabled, listRotateStates, setWatchdogRotateEnabled } from '../lib/watchdog/rotate.js';
-const WATCHDOG_ROUTINE_NAME = 'watchdog';
+import { loadWatchdogSessions, runWatchdogPass } from '../lib/watchdog/service.js';
 /** Default state dir the runner and these subcommands share. */
 function stateDir() {
     return path.join(getRuntimeStateDir(), 'watchdog');
@@ -63,21 +57,6 @@ function humanMs(ms) {
         return `${Math.round(ms / 60_000)}m`;
     return `${Math.round(ms / 1000)}s`;
 }
-/**
- * Run the mailbox liveness sweep against the same session set the tick just used.
- * Idempotent and cheap: archiving a message twice is a no-op, and GC only scans
- * directories. Failures are swallowed so a mailbox-root problem cannot break the
- * watchdog tick.
- */
-async function runMailboxGc(sessions) {
-    const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => !!id));
-    try {
-        gcMailbox(activeBoxIds);
-    }
-    catch {
-        // GC is best-effort housekeeping; the next tick will retry.
-    }
-}
 function colorForOutcome(o) {
     if (o.injected)
         return chalk.green;
@@ -139,45 +118,35 @@ export function registerWatchdogCommand(program) {
         };
         // Injection gate: --nudge is the explicit opt-in to actually inject. Bare
         // `agents watchdog` (and `--watch` without `--nudge`) is dry. The always-on
-        // path is the daemon routine, which runs `agents watchdog --nudge` — so the
-        // routine's enabled state IS the on/off switch, not a flag read here.
+        // path is the daemon-owned pass. Device config is its on/off switch; this
+        // explicit command still requires --nudge before it can inject.
         const computeWillInject = () => opts.nudge === true;
-        const tickOnce = async (willInject, sessions) => runWatchdogTick({
+        const tickOnce = async (willInject, sessions) => runWatchdogPass({
             nudge: willInject,
             nudgeText: opts.text,
             smart: opts.smart === true,
             smartAgent: opts.smartAgent,
             thresholds,
             allowGhosttyFocus: opts.allowGhosttyFocus === true,
-            stateDir: stateDir(),
             sessions,
         });
         // RUSH-2062: share the daemon-warmed local active-session snapshot with
         // menubar/CLI/Factory instead of re-running a full gather every tick.
-        const loadWatchdogSessions = async () => {
-            const loaded = await loadLocalActiveSessions({
-                // Force a live gather only when the warm path is unavailable; the
-                // cache layer already re-gathers past DEFAULT_ACTIVE_CACHE_MAX_AGE_MS.
-                gather: () => getActiveSessions({ localOnly: true }),
-            });
-            return loaded.sessions;
-        };
         if (!opts.watch) {
             const willInject = computeWillInject();
             const sessions = await loadWatchdogSessions();
             const result = await tickOnce(willInject, sessions);
-            await runMailboxGc(sessions);
             if (opts.json)
                 console.log(JSON.stringify(result, null, 2));
             else
                 printTick(result, willInject);
             return;
         }
-        // Manual poll loop (for ad-hoc use; the always-on path is `enable`'s routine).
+        // Manual poll loop for ad-hoc use; the daemon owns the automatic cadence.
         const intervalMs = durationMsOr(opts.interval, 30_000);
         if (!computeWillInject() && !opts.json) {
             console.log(chalk.yellow(`watchdog --watch is DETECT-ONLY. Pass --nudge to inject, ` +
-                `or run 'agents watchdog on' for the always-on daemon routine.`));
+                `or run 'agents watchdog on' for the daemon-owned pass.`));
         }
         // eslint-disable-next-line no-constant-condition
         while (true) {
@@ -185,7 +154,6 @@ export function registerWatchdogCommand(program) {
             const willInject = computeWillInject();
             const sessions = await loadWatchdogSessions();
             const result = await tickOnce(willInject, sessions);
-            await runMailboxGc(sessions);
             if (opts.json)
                 console.log(JSON.stringify(result));
             else
@@ -207,10 +175,10 @@ export function registerWatchdogCommand(program) {
       # Machine-readable for the menu-bar
       agents watchdog --json
 
-      # Turn on the ALWAYS-ON watchdog (a daemon-fired routine)
+      # Turn on the daemon-owned watchdog pass (every three minutes)
       agents watchdog on
 
-      # Show the routine, rotate config, and any in-flight in-place rotates
+      # Show device enablement, rotate config, and in-flight rotates
       agents watchdog status
 
       # Leave one session detected-but-untouched
@@ -253,37 +221,32 @@ export function registerWatchdogCommand(program) {
       'watchdog.rotate: off' to ~/.agents/agents.yaml; nudging stays on).
       State machine: ~/.agents/.cache/state/watchdog/rotate/<sessionId>.json.
 
-      Always-on: 'agents watchdog on' enables the system-defined 'watchdog' routine
-      on this device and reloads the daemon; 'off' disables it here. Inspect it with
-      'agents routines list'. Defaults
-      OFF. Per-session policy: off (ignore), keep (default), handsoff (detect + flag).
+      Always-on: 'agents watchdog on' enables one daemon-owned pass every three
+      minutes on this device and reloads the daemon; 'off' disables it here.
+      Defaults OFF. Per-session policy: off (ignore), keep (default), handsoff
+      (detect + flag).
 
       State (tray-readable): ${path.join('~/.agents/.cache/state/watchdog', '{nudges,flags,last-tick}.json')}
     `,
     });
     // --- always-on enable/disable/status (backed by the daemon routine) --------
     const turnOn = async () => {
-        const routine = readJob(WATCHDOG_ROUTINE_NAME);
-        if (!routine)
-            throw new Error("Built-in routine 'watchdog' is missing. Run: agents repo pull system");
-        setJobEnabled(WATCHDOG_ROUTINE_NAME, true);
+        setConfigValue('watchdog.enabled', true);
         await reloadDaemonForRoutine(true);
-        console.log(chalk.green(`watchdog: ON on this device (${routine.schedule ?? 'event-triggered'})`));
+        console.log(chalk.green('watchdog: ON on this device (every 3 minutes)'));
     };
     const turnOff = async () => {
-        if (!readJob(WATCHDOG_ROUTINE_NAME))
-            throw new Error("Built-in routine 'watchdog' is missing. Run: agents repo pull system");
-        setJobEnabled(WATCHDOG_ROUTINE_NAME, false);
+        setConfigValue('watchdog.enabled', false);
         await reloadDaemonForRoutine(false);
         console.log(chalk.yellow('watchdog: OFF on this device'));
     };
     cmd.command('on')
-        .description('Enable the built-in watchdog routine on this device.')
+        .description('Enable the daemon watchdog pass on this device.')
         .action(async () => {
         await turnOn();
     });
     cmd.command('off')
-        .description('Disable the built-in watchdog routine on this device.')
+        .description('Disable the daemon watchdog pass on this device.')
         .action(async () => {
         await turnOff();
     });
@@ -304,7 +267,7 @@ export function registerWatchdogCommand(program) {
             chalk.dim(`(watchdog.rotate: ${s} in agents.yaml)`));
     });
     cmd.command('status')
-        .description('Show whether the always-on watchdog routine is enabled and where state is written.')
+        .description('Show whether the daemon watchdog pass is enabled and where state is written.')
         .option('--json', 'Emit status as JSON (for the menu-bar / scripts)')
         .action((_opts, command) => {
         // The parent `watchdog` command also declares --json and greedily parses it
@@ -312,16 +275,14 @@ export function registerWatchdogCommand(program) {
         // parent, not this subcommand. optsWithGlobals() merges both levels, so we
         // read it correctly regardless of which command commander bound it to.
         const json = command.optsWithGlobals().json === true;
-        const on = routineEnabledOnThisDevice(WATCHDOG_ROUTINE_NAME) === true;
-        const enabledDevices = devicesWithRoutineEnabled(WATCHDOG_ROUTINE_NAME);
+        const on = getConfigValue('watchdog.enabled').value === true;
         const rotate = isWatchdogRotateEnabled() ? 'on' : 'off';
         const rotates = listRotateStates(stateDir());
         const inflight = rotates.filter((r) => r.phase !== 'done' && r.phase !== 'failed');
         if (json) {
             console.log(JSON.stringify({
                 enabled: on,
-                enabledDevices,
-                routine: WATCHDOG_ROUTINE_NAME,
+                cadenceMs: 180_000,
                 stateDir: stateDir(),
                 rotate,
                 rotates: rotates.map((r) => ({
@@ -335,8 +296,7 @@ export function registerWatchdogCommand(program) {
             }));
             return;
         }
-        console.log(`always-on watchdog: ${on ? chalk.green('ON') : chalk.dim('off')} (routine '${WATCHDOG_ROUTINE_NAME}')`);
-        console.log(`enabled devices: ${enabledDevices.length > 0 ? enabledDevices.join(', ') : chalk.dim('none')}`);
+        console.log(`always-on watchdog: ${on ? chalk.green('ON') : chalk.dim('off')} (every 3 minutes on this device)`);
         console.log(`rotate: ${rotate === 'on' ? chalk.green('on') : chalk.yellow('off')} (watchdog.rotate in agents.yaml) · ${inflight.length} in-flight`);
         for (const r of inflight) {
             console.log(`  ${chalk.magenta(r.phase.padEnd(12))} ${chalk.bold(r.sessionId.slice(0, 8))} → ${r.newSessionId.slice(0, 8)}${r.error ? chalk.red(`  ${r.error}`) : ''}`);

package/dist/index.js

@@ -94,7 +94,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadModes, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadSnapshot, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadInsights, loadPerf, loadTrends, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadHumans, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
@@ -941,6 +941,7 @@ async function registerAllEagerCommands() {
     await reg(loadDefaults);
     await reg(loadSet);
     await reg(loadModels);
+    await reg(loadModes);
     await reg(loadPrune);
     await reg(loadTrash);
     await reg(loadRestore);
@@ -1034,7 +1035,23 @@ program.on('command:*', (operands) => {
     if (minDist === 1 && closest) {
         const args = process.argv.slice(2);
         args[0] = closest;
-        program.parse(['node', 'agents', ...args]);
+        // The typo'd name was unknown, so the top-level --host router (which ran
+        // before commander parsing, against the ORIGINAL name) could not have
+        // routed it - it correctly fell through to reach this handler at all
+        // (that fallthrough is this ticket's own fix). But falling through to a
+        // plain local re-parse means a routing flag on a corrected REAL
+        // host-routable command (e.g. `docto --host box`, corrected to `doctor`)
+        // silently ran LOCALLY instead of remotely, with no error - worse than
+        // the loud "does not support --host" this ticket replaced. Re-run the
+        // router with the CORRECTED name before falling through to local parse;
+        // it already no-ops when no routing flag is present. RUSH-2022 review r2.
+        void (async () => {
+            const { maybeRunOnHost } = await import('./lib/hosts/passthrough.js');
+            if (await maybeRunOnHost(closest, args)) {
+                process.exit(process.exitCode ?? 0);
+            }
+            program.parse(['node', 'agents', ...args]);
+        })();
         return;
     }
     console.error(`error: unknown command '${unknown}'`);
@@ -1073,6 +1090,9 @@ if (requestedCommand !== undefined && !helpOrVersionRequested && !requestedIsDis
 // Register only the command(s) this invocation actually uses. Lazy commands
 // (sessions/teams/cloud) are handled after applyGlobalHelpConventions below.
 const isLazyRequest = requestedCommand !== undefined && LAZY_COMMAND_NAMES.has(requestedCommand);
+// Set when the requested name maps to no command: the lazy tree is then also
+// registered below so the spellcheck can suggest `sessions`/`teams`/`cloud`.
+let requestedIsUnknown = false;
 if (requestedIsDisabled) {
     // The brand turned this command off: register the full tree so the "did you
     // mean" picker still works, then strip the disabled commands below so the
@@ -1086,6 +1106,7 @@ else if (requestedCommand !== undefined && !isLazyRequest) {
         // spellcheck and edit-distance-1 auto-correct (the command:* handler above)
         // see the same candidate set — and ordering — as main.
         await registerAllEagerCommands();
+        requestedIsUnknown = true;
     }
 }
 // When requestedCommand is undefined (bare invocation, --version, --help, -h) no
@@ -1101,6 +1122,21 @@ if (isLazyRequest && !requestedIsDisabled) {
     for (const loader of COMMAND_LOADERS[requestedCommand])
         await reg(loader);
 }
+else if (requestedIsUnknown) {
+    // Unknown command: the lazy names must be candidates too, or `agents session`
+    // (a typo for the very much lazy `sessions`) gets no "did you mean" at all —
+    // the miss the RUSH-2022 report walked into. Registration order still mirrors
+    // main: lazy commands come after applyGlobalHelpConventions.
+    const seen = new Set();
+    for (const name of LAZY_COMMAND_NAMES) {
+        for (const loader of COMMAND_LOADERS[name] ?? []) {
+            if (seen.has(loader))
+                continue;
+            seen.add(loader);
+            await reg(loader);
+        }
+    }
+}
 // White-label: remove any commands this brand disabled so they resolve as
 // unknown (the command:* handler then reports "unknown command"). Unbranded or
 // nothing-disabled → no-op. Done after all registration paths above.

package/dist/lib/agent-modes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Permission-mode catalog for a harness.
+ *
+ * Source of truth is AGENTS[id].capabilities.modes plus the native CLI flags
+ * in AGENT_COMMANDS.modeFlags. This is the modes analog of the model catalog
+ * (`agents models`) — what a human or orchestrating agent reads before
+ * `agents run <agent> --mode …` / `agents teams add … --mode …`.
+ */
+import type { AgentId, Mode } from './types.js';
+/** Human description for each canonical permission mode. */
+export declare const MODE_DESCRIPTIONS: Record<Mode, string>;
+export interface AgentModeEntry {
+    mode: Mode;
+    /** Native CLI flags agents-cli forwards for this mode (empty = harness default). */
+    flags: string[];
+    description: string;
+    /** First entry in capabilities.modes — the safest native mode. */
+    isDefault: boolean;
+}
+export interface AgentModesCatalog {
+    agent: AgentId;
+    /** Modes this harness natively supports, in declaration order. */
+    modes: AgentModeEntry[];
+    /** capabilities.modes[0] — safest native mode; run may still default elsewhere (e.g. CLI plan, teams edit). */
+    defaultMode: Mode;
+    /**
+     * Configured run.defaults mode for this agent@version, when set.
+     * Null means no pin — CLI default (plan for most harnesses) or modes[0] applies.
+     */
+    configuredMode: Mode | null;
+    configuredModeSource: string | null;
+    /**
+     * Whether plan works in a headless (`-p` / prompt) run. false means a headless
+     * --mode plan degrades (see resolveHeadlessMode). undefined = assumed true.
+     */
+    headlessPlan: boolean;
+    /** Canonical modes this harness does NOT list in capabilities.modes. */
+    unsupported: Mode[];
+    /** Notes an orchestrator should read before picking a mode. */
+    notes: string[];
+}
+/**
+ * Build the permission-mode catalog for one harness.
+ * `version` only affects the configured run.defaults lookup (modes themselves
+ * are per-agent today, not version-gated).
+ */
+export declare function getAgentModesCatalog(agent: AgentId, version?: string | null, cwd?: string): AgentModesCatalog;
+/** Format native flags for display, e.g. `--permission-mode plan` or `(harness default)`. */
+export declare function formatModeFlags(flags: string[]): string;

package/dist/lib/agent-modes.js

@@ -0,0 +1,70 @@
+/**
+ * Permission-mode catalog for a harness.
+ *
+ * Source of truth is AGENTS[id].capabilities.modes plus the native CLI flags
+ * in AGENT_COMMANDS.modeFlags. This is the modes analog of the model catalog
+ * (`agents models`) — what a human or orchestrating agent reads before
+ * `agents run <agent> --mode …` / `agents teams add … --mode …`.
+ */
+import { ALL_MODES } from './types.js';
+import { AGENTS } from './agents.js';
+import { AGENT_COMMANDS, defaultModeFor } from './exec.js';
+import { resolveRunDefaults } from './run-defaults.js';
+/** Human description for each canonical permission mode. */
+export const MODE_DESCRIPTIONS = {
+    plan: 'read-only investigation; no writes, no shell side-effects',
+    edit: 'may edit files; prompts for shell / risky operations',
+    auto: 'smart classifier auto-approves safe ops, prompts for risky',
+    skip: 'bypass every permission prompt (dangerously-skip-permissions)',
+};
+/**
+ * Build the permission-mode catalog for one harness.
+ * `version` only affects the configured run.defaults lookup (modes themselves
+ * are per-agent today, not version-gated).
+ */
+export function getAgentModesCatalog(agent, version, cwd = process.cwd()) {
+    const supported = AGENTS[agent].capabilities.modes;
+    const defaultMode = defaultModeFor(agent);
+    const modeFlags = AGENT_COMMANDS[agent]?.modeFlags ?? {};
+    const headlessPlan = AGENTS[agent].capabilities.headlessPlan !== false;
+    const modes = supported.map((mode) => ({
+        mode,
+        flags: modeFlags[mode] ?? [],
+        description: MODE_DESCRIPTIONS[mode],
+        isDefault: mode === defaultMode,
+    }));
+    const unsupported = ALL_MODES.filter((m) => !supported.includes(m));
+    const runDefaults = resolveRunDefaults(agent, version, cwd);
+    const configuredMode = runDefaults.mode ?? null;
+    const configuredModeSource = runDefaults.sources.mode ?? null;
+    const notes = [];
+    notes.push(`'full' is accepted as a silent alias for 'skip'.`);
+    if (unsupported.includes('auto')) {
+        notes.push(`--mode auto degrades to edit on ${agent} (no native auto classifier).`);
+    }
+    if (unsupported.includes('plan')) {
+        notes.push(`--mode plan degrades to ${defaultMode} on ${agent} (no native read-only mode).`);
+    }
+    if (!headlessPlan && supported.includes('plan')) {
+        notes.push(`headless --mode plan is not supported on ${agent}; a prompt-based plan run auto-downgrades (see resolveHeadlessMode).`);
+    }
+    if (unsupported.includes('skip')) {
+        notes.push(`${agent} has no skip/full bypass mode.`);
+    }
+    return {
+        agent,
+        modes,
+        defaultMode,
+        configuredMode,
+        configuredModeSource,
+        headlessPlan,
+        unsupported: [...unsupported],
+        notes,
+    };
+}
+/** Format native flags for display, e.g. `--permission-mode plan` or `(harness default)`. */
+export function formatModeFlags(flags) {
+    if (flags.length === 0)
+        return '(harness default)';
+    return flags.join(' ');
+}

package/dist/lib/agents.js

@@ -279,6 +279,7 @@ export const AGENTS = {
         color: 'cyan',
         cliCommand: 'cursor-agent',
         npmPackage: '',
+        cloudProvider: 'cursor',
         installScript: 'curl https://cursor.com/install -fsS | bash && mv ~/.local/bin/agent ~/.local/bin/cursor-agent && grep -q "/.local/bin" ~/.zshrc || echo \'export PATH="$HOME/.local/bin:$PATH"\' >> ~/.zshrc',
         configDir: path.join(HOME, '.cursor'),
         commandsDir: path.join(HOME, '.cursor', 'commands'),
@@ -306,7 +307,7 @@ export const AGENTS = {
         // See transformSubagentForCursor / https://cursor.com/docs/subagents.
         // interactiveRepl: false — cursor-agent exits immediately with no argv. It requires a
         // prompt to do anything useful; a bare invocation is not a REPL (RUSH-2185, EXEC-23a).
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '2026.1.22' }, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['edit', 'skip'], interactiveRepl: false }, // allowlist: ~/.cursor/cli-config.json
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: { since: '2026.1.22' }, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['plan', 'edit', 'skip'], interactiveRepl: false }, // allowlist: ~/.cursor/cli-config.json
     },
     opencode: {
         id: 'opencode',
@@ -811,6 +812,75 @@ export const AGENTS = {
             interactiveRepl: true,
         },
     },
+    // Warp Agent CLI (`oz`) — the standalone coding-agent CLI on Warp's "Oz"
+    // platform (the same shared Warp binary invoked via the `oz` symlink). Native
+    // binary via `brew install --cask oz` (macOS) / `oz-stable` apt|yum|pacman
+    // package (Linux); self-updating, no npm package. Config lives under `~/.warp/`
+    // (`.mcp.json`, `skills/`, `tab_configs/`, `worktrees/`, `remote-server`).
+    // Headless: `oz agent run --prompt "<task>" [--model <id>]` (local) /
+    // `oz agent run-cloud` (cloud). Auth: `oz login` (browser OAuth) or a
+    // `WARP_API_KEY` env token for headless/CI (`oz api-key create`). Rules/context
+    // file is `AGENTS.md` (also reads WARP.md / CLAUDE.md). Autonomy is governed by
+    // the selected agent profile (`--profile`), not a per-run permission flag.
+    // Sessions/conversations are stored SERVER-SIDE (retrieved with auth via
+    // `oz run conversation get <id>`), so there is no local transcript for
+    // `agents sessions` to index — warp is intentionally absent from SESSION_AGENTS.
+    // Docs: https://docs.warp.dev/reference/cli
+    warp: {
+        id: 'warp',
+        name: 'Warp',
+        color: 'blueBright',
+        cliCommand: 'oz',
+        npmPackage: '',
+        installScript: 'brew install --cask oz',
+        configDir: path.join(HOME, '.warp'),
+        commandsDir: '',
+        commandsSubdir: '',
+        skillsDir: path.join(HOME, '.warp', 'skills'),
+        hooksDir: 'hooks',
+        instructionsFile: 'AGENTS.md',
+        format: 'markdown',
+        variableSyntax: '$ARGUMENTS',
+        // Oz has no event->shell-command hook registration surface (its documented
+        // capabilities are agent-profiles-permissions, codebase-context,
+        // full-terminal-use, mcp, planning, rules, slash-commands — no hooks).
+        supportsHooks: false,
+        capabilities: {
+            hooks: false,
+            // MCP: Oz reads the Claude `{ "mcpServers": {...} }` schema from
+            // `.warp/.mcp.json` (user `~/.warp/.mcp.json`, project `<root>/.warp/.mcp.json`)
+            // and accepts `--mcp <path|json>` at run time; `oz mcp list` reads them
+            // back. stdio + http with headers, same schema as Claude's .mcp.json.
+            mcp: true,
+            mcpHttp: true,
+            mcpHeaders: true,
+            // Autonomy is governed by the selected agent profile
+            // (agent-profiles-permissions), not a Claude-style tool-name allow/deny
+            // list agents-cli can write — so no allowlist writer (mirrors muse).
+            allowlist: false,
+            // Skills: `--skill <spec>` + `oz agent skills`; searched in
+            // `.agents/skills/`, `.warp/skills/`, `.claude/skills/`, `.codex/skills/`.
+            skills: true,
+            // Slash-commands are native/server-managed (no droppable markdown
+            // command-file directory for agents-cli to sync into).
+            commands: false,
+            // No Claude marketplace / plugin manifest support.
+            plugins: false,
+            // Cloud agents + agent profiles are server-side; no installable
+            // subagent-definition directory to sync into (keeps the table truthful).
+            subagents: false,
+            rules: { file: 'AGENTS.md' },
+            workflows: false,
+            memory: false,
+            // Oz has no per-run permission flag; a single autonomous mode maps to no
+            // flags (the `--profile` selection governs autonomy). Mirrors hermes.
+            modes: ['edit'],
+            rulesImports: false,
+            // `oz agent run` requires a prompt (--prompt/--saved-prompt/--task-id/
+            // --skill), so a bare invocation opens no REPL.
+            interactiveRepl: false,
+        },
+    },
 };
 /** All current and legacy agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
@@ -1507,11 +1577,16 @@ function isValidOpenCodeCredential(value) {
 }
 /**
  * Whether a Muse Code `~/.config/muse/auth.json` document holds any usable
- * access token. The launcher stores per-provider slots (e.g. `meta`) each with
- * an `access_token` string; a top-level `access_token` is also accepted.
- * Never returns the secret itself — presence only.
+ * access token. Live shape from `muse login` (device OAuth, Muse Code 0.1.0):
+ *   { schema_version: 1, providers: { meta: { access_token, api_key, user_email, … } } }
+ * Also accept top-level or one-level-nested tokens for older/alternate writers.
+ * Recurses into objects so `providers.meta.access_token` is found — a flat
+ * one-level walk only saw `providers` and reported signed-out after a successful
+ * login (balanced then excluded the account). Never returns the secret itself.
  */
-function museAuthHasToken(value) {
+function museAuthHasToken(value, depth = 0) {
+    if (depth > 4)
+        return false;
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
     const root = value;
@@ -1520,16 +1595,31 @@ function museAuthHasToken(value) {
     if (typeof root.api_key === 'string' && root.api_key.length > 0)
         return true;
     for (const slot of Object.values(root)) {
-        if (!slot || typeof slot !== 'object' || Array.isArray(slot))
-            continue;
-        const entry = slot;
-        if (typeof entry.access_token === 'string' && entry.access_token.length > 0)
-            return true;
-        if (typeof entry.api_key === 'string' && entry.api_key.length > 0)
+        if (museAuthHasToken(slot, depth + 1))
             return true;
     }
     return false;
 }
+/** Best-effort email from a Muse auth.json (providers.meta.user_email, etc.). */
+function museAuthEmail(value, depth = 0) {
+    if (depth > 4)
+        return null;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const root = value;
+    if (typeof root.user_email === 'string' && root.user_email.includes('@')) {
+        return root.user_email;
+    }
+    if (typeof root.email === 'string' && root.email.includes('@')) {
+        return root.email;
+    }
+    for (const slot of Object.values(root)) {
+        const found = museAuthEmail(slot, depth + 1);
+        if (found)
+            return found;
+    }
+    return null;
+}
 /**
  * Whether a Claude version home's credential file is present but carries no
  * token — the "must have a real credential" floor (see
@@ -1924,10 +2014,8 @@ export async function getAccountInfo(agentId, home) {
             }
             case 'muse': {
                 // Muse Code authenticates with META_API_KEY (env, highest priority) or
-                // a stored OAuth/API credential at ~/.config/muse/auth.json. The auth
-                // file is launcher-managed JSON with per-provider slots holding
-                // access_token; there is no email claim, so we report signed-in + a
-                // stable identity key (env-key vs provider slots) like kimi/opencode.
+                // a stored OAuth/API credential at ~/.config/muse/auth.json. Live file
+                // shape nests under providers.meta (access_token + optional user_email).
                 if (process.env.META_API_KEY?.trim() || process.env.MODEL_API_KEY?.trim()) {
                     const accountKey = buildIdentityKey(agentId, [['auth', 'env']]);
                     return { ...empty, signedIn: true, accountId: 'env', accountKey, lastActive };
@@ -1938,13 +2026,18 @@ export async function getAccountInfo(agentId, home) {
                 const data = JSON.parse(await fs.promises.readFile(authPath, 'utf-8'));
                 if (!data || typeof data !== 'object')
                     return { ...empty, lastActive };
-                // auth.json shape: { meta?: { access_token }, … } or similar slots.
-                // Any object with a nested access_token (or a top-level one) counts.
-                const hasToken = museAuthHasToken(data);
-                if (!hasToken)
+                if (!museAuthHasToken(data))
                     return { ...empty, lastActive };
-                const accountKey = buildIdentityKey(agentId, [['auth', 'file']]);
-                return { ...empty, signedIn: true, accountId: 'file', accountKey, lastActive };
+                const email = museAuthEmail(data);
+                const accountKey = buildIdentityKey(agentId, email ? [['email', email]] : [['auth', 'file']]);
+                return {
+                    ...empty,
+                    signedIn: true,
+                    email,
+                    accountId: email ?? 'file',
+                    accountKey,
+                    lastActive,
+                };
             }
             default:
                 return { ...empty, lastActive };
@@ -2563,6 +2656,9 @@ export function getUserMcpConfigPath(agentId) {
         case 'muse':
             // Muse Code: MCP lives in ~/.config/muse/settings.json under mcp_servers.
             return path.join(agent.configDir, 'settings.json');
+        case 'warp':
+            // Oz reads user-scope MCP from ~/.warp/.mcp.json (Claude schema).
+            return path.join(agent.configDir, '.mcp.json');
         default:
             // Gemini and others use settings.json
             return path.join(agent.configDir, 'settings.json');
@@ -2603,6 +2699,8 @@ export function getMcpConfigPathForHome(agentId, home) {
             return path.join(home, '.omp', 'agent', '.mcp.json');
         case 'muse':
             return path.join(home, '.config', 'muse', 'settings.json');
+        case 'warp':
+            return path.join(home, '.warp', '.mcp.json');
         default:
             return path.join(home, agentConfigDirName(agentId), 'settings.json');
     }
@@ -2649,6 +2747,9 @@ export function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
             // Muse project MCP rides the same settings schema under .muse/settings.json
             // when present; otherwise fall back to the user settings path.
             return path.join(cwd, '.muse', 'settings.json');
+        case 'warp':
+            // Oz reads project MCP from <root>/.warp/.mcp.json (Claude schema).
+            return path.join(cwd, '.warp', '.mcp.json');
         default:
             return path.join(cwd, `.${agentId}`, 'settings.json');
     }
@@ -2796,6 +2897,10 @@ export const AGENT_NAME_ALIASES = {
     'muse-code': 'muse',
     'muse-spark': 'muse',
     'meta-muse': 'muse',
+    warp: 'warp',
+    oz: 'warp',
+    'warp-agent': 'warp',
+    'warp-cli': 'warp',
 };
 /**
  * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.