@phnx-labs/agents-cli 1.22.22 → 1.22.24

package/dist/commands/harness.js

@@ -13,10 +13,10 @@
 import chalk from 'chalk';
 import { addProfile, ensureProviderToken, applyFromSecrets } from './profiles.js';
 import { isInteractiveTerminal } from './utils.js';
-import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, editProfile, renameProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, editProfile, renameProfile, profileFromHostModel, authEnvKeyForHost, modelEnvKeyForHost, baseUrlEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
 import { listPresets, getPreset } from '../lib/profiles-presets.js';
-import { listBundles } from '../lib/secrets/bundles.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
+import { runWizardSteps, createSteps, editSteps, defaultWizardIO, } from './harness-wizard.js';
 /** Short capability summary for a native harness — its supported run modes. */
 function nativeModes(id) {
     const modes = AGENTS[id]?.capabilities?.modes ?? [];
@@ -193,108 +193,93 @@ async function runForkFlow(source, name, opts) {
     console.log(chalk.green(`Harness '${name}' forked from ${source}.`));
     console.log(chalk.gray(`Try: agents run ${name} "hello"`));
 }
-/** The first `_MODEL`-suffixed env var in a preset's static env block, if any. */
-function presetModel(preset) {
-    return Object.entries(preset.env).find(([k]) => k.endsWith('_MODEL'))?.[1];
-}
 /**
  * Interactive `agents harness add`/`fork` wizard — runs when required info is
- * missing and stdout is a TTY (see {@link forkNeedsWizard}, {@link addNeedsWizard}).
- * Always resolves to the same `(source, name, opts)` shape {@link buildFork}
- * accepts via {@link runForkFlow}, so a wizard run and a hand-written fork call
- * build an identical profile.
+ * missing and stdin+stdout are a TTY (see {@link forkNeedsWizard}, {@link addNeedsWizard}).
+ * Drives the shared step engine ({@link createSteps}) and maps its finished draft
+ * back to the same `(source, name, opts)` shape {@link buildFork} accepts via
+ * {@link runForkFlow}, so a wizard run and a hand-written fork call build an
+ * identical profile.
  */
-async function runHarnessWizard() {
-    const { select, input } = await import('@inquirer/prompts');
-    const customNames = listProfiles().map((p) => p.name);
-    const source = await select({
-        message: 'Fork from',
-        choices: [
-            ...ALL_AGENT_IDS.map((id) => ({ name: `${AGENTS[id].name}  ${chalk.gray('(native)')}`, value: id })),
-            ...customNames.map((n) => ({ name: `${n}  ${chalk.gray('(custom harness)')}`, value: n })),
-        ],
-    });
-    const presets = listPresets();
-    const CUSTOM = '__custom__';
-    const presetChoice = await select({
-        message: 'Preset',
-        choices: [
-            ...presets.map((p) => ({ name: `${p.name}  ${chalk.gray(p.description.slice(0, 60))}`, value: p.name })),
-            { name: 'Build custom (host + model + provider)', value: CUSTOM },
-        ],
-    });
-    let model;
-    let baseUrl;
-    let authProvider;
-    let defaultName = source;
-    if (presetChoice === CUSTOM) {
-        model = await input({ message: 'Model id' });
-        const NO_AUTH = '__none__';
-        const providers = [...new Set(presets.map((p) => p.provider))];
-        const providerChoice = await select({
-            message: 'Provider',
-            choices: [
-                ...providers.map((p) => ({ name: p, value: p })),
-                { name: 'no auth / host manages its own login', value: NO_AUTH },
-            ],
-        });
-        authProvider = providerChoice === NO_AUTH ? undefined : providerChoice;
-        const baseUrlInput = await input({ message: 'Base URL (optional)', default: '' });
-        baseUrl = baseUrlInput || undefined;
+async function runCreateWizard() {
+    const io = await defaultWizardIO();
+    const draft = await runWizardSteps(createSteps(), { mode: 'create' }, io);
+    return {
+        source: draft.source,
+        name: draft.name,
+        opts: {
+            model: draft.model,
+            baseUrl: draft.baseUrl,
+            authProvider: draft.authProvider,
+            fromSecrets: draft.fromSecrets,
+        },
+    };
+}
+/**
+ * Map a finished edit-wizard draft onto {@link EditOptions}, keeping only the
+ * fields the user actually changed from the profile's current values. Unchanged
+ * accepts (the wizard pre-fills each prompt with the current value) drop out, so
+ * the resulting {@link buildEdit} touches nothing the user left alone — and the
+ * "no changes" case is detectable via {@link hasEditFlags}. Base-URL clearing is
+ * intentionally not expressed here: the flag path can't clear it either (an empty
+ * `--base-url` is a no-op in `forkProfile`), so the wizard matches that until a
+ * later subtask adds explicit clearing.
+ */
+export function draftToEditOptions(draft, original) {
+    const host = original.host.agent;
+    const curModel = original.env[modelEnvKeyForHost(host)];
+    const baseKey = baseUrlEnvKeyForHost(host);
+    const curBaseUrl = baseKey ? original.env[baseKey] : undefined;
+    const curVersion = original.host.version ?? '';
+    const curFallback = original.fallback_model ?? '';
+    const curDescription = original.description ?? '';
+    const opts = {};
+    if (draft.model !== undefined && draft.model !== curModel)
+        opts.model = draft.model;
+    if (draft.baseUrl && draft.baseUrl !== curBaseUrl)
+        opts.baseUrl = draft.baseUrl;
+    if (draft.authProvider !== undefined)
+        opts.authProvider = draft.authProvider;
+    if (draft.fromSecrets !== undefined)
+        opts.fromSecrets = draft.fromSecrets;
+    if (draft.version !== undefined && draft.version !== curVersion)
+        opts.version = draft.version;
+    if (draft.fallbackModel !== undefined && draft.fallbackModel !== curFallback)
+        opts.fallbackModel = draft.fallbackModel;
+    if (draft.description !== undefined && draft.description !== curDescription)
+        opts.description = draft.description;
+    return opts;
+}
+/**
+ * Interactive `agents harness edit <name>` wizard — runs when no edit flags were
+ * given and stdin+stdout are a TTY. Loads the profile, drives the shared step
+ * engine ({@link editSteps}) pre-filled with current values, then persists via the
+ * same build+write path as the flag-driven edit. `--key-stdin` is honored for the
+ * auth step's key entry. When the user changes nothing, it says so and writes
+ * nothing.
+ */
+async function runEditWizard(name, cliOpts) {
+    if (!profileExists(name)) {
+        throw new Error(`Harness '${name}' not found. Create it first: agents harness add ${name} ...`);
     }
-    else {
-        const preset = getPreset(presetChoice);
-        model = presetModel(preset);
-        baseUrl = preset.env.ANTHROPIC_BASE_URL || preset.env.OPENAI_BASE_URL;
-        authProvider = preset.authOptional ? undefined : preset.provider;
-        // Pre-fill with the preset's own name (e.g. 'deepseek'), not a model
-        // detail, so users aren't nudged toward baking one into the identity name.
-        defaultName = preset.name;
+    const original = readProfile(name);
+    const io = await defaultWizardIO();
+    const draft = await runWizardSteps(editSteps(original), { mode: 'edit', original, host: original.host.agent, name }, io);
+    const opts = { ...draftToEditOptions(draft, original), keyStdin: cliOpts.keyStdin };
+    if (!hasEditFlags(opts)) {
+        console.log(chalk.gray(`No changes made to '${name}'.`));
+        return;
     }
-    const name = await input({
-        message: 'Harness name',
-        default: defaultName,
-        validate: (v) => {
-            try {
-                validateProfileName(v);
-                return true;
-            }
-            catch (err) {
-                return err.message;
-            }
-        },
-    });
-    const opts = { model, baseUrl, authProvider };
-    if (authProvider) {
-        const bundles = listBundles();
-        const TYPE_NOW = 'type';
-        const FROM_SECRETS = 'secrets';
-        const keySource = bundles.length > 0
-            ? await select({
-                message: `How should '${authProvider}' get its key?`,
-                choices: [
-                    { name: 'Type a key now', value: TYPE_NOW },
-                    { name: 'Use an existing agents secrets bundle', value: FROM_SECRETS },
-                ],
-            })
-            : TYPE_NOW;
-        if (keySource === FROM_SECRETS) {
-            const bundleName = await select({
-                message: 'Bundle',
-                choices: bundles.map((b) => ({
-                    name: b.description ? `${b.name}  ${chalk.gray(b.description)}` : b.name,
-                    value: b.name,
-                })),
-            });
-            const bundle = bundles.find((b) => b.name === bundleName);
-            const keys = Object.keys(bundle.vars);
-            const key = keys.length === 1
-                ? keys[0]
-                : await select({ message: 'Key', choices: keys.map((k) => ({ name: k, value: k })) });
-            opts.fromSecrets = `${bundleName}:${key}`;
-        }
+    const edited = buildEdit(name, opts);
+    if (opts.fromSecrets) {
+        await applyFromSecrets(edited, opts.fromSecrets, opts.authProvider);
+    }
+    else if (opts.authProvider) {
+        await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
     }
-    return { source, name, opts };
+    writeProfile(edited);
+    console.log(chalk.green(`Harness '${name}' updated.`));
+    console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
 }
 export function registerHarnessCommands(program) {
     const cmd = program
@@ -354,7 +339,7 @@ Examples:
                 if (!isInteractiveTerminal()) {
                     throw new Error("'agents harness add' needs --preset or --host + --model (or a name and an interactive terminal for the wizard).");
                 }
-                const wiz = await runHarnessWizard();
+                const wiz = await runCreateWizard();
                 await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
                 return;
             }
@@ -399,7 +384,7 @@ Examples:
                 if (!isInteractiveTerminal()) {
                     throw new Error("'agents harness fork' needs <source> and <name> (or an interactive terminal for the wizard).");
                 }
-                const wiz = await runHarnessWizard();
+                const wiz = await runCreateWizard();
                 await runForkFlow(wiz.source, wiz.name, { ...wiz.opts, force: opts.force, keyStdin: opts.keyStdin });
                 return;
             }
@@ -412,7 +397,7 @@ Examples:
     });
     cmd
         .command('edit <name>')
-        .description('Edit an existing custom harness in place — model, endpoint, auth, version, description, fallback.')
+        .description('Edit an existing custom harness in place — model, endpoint, auth, version, description, fallback. Omit flags in a terminal for the interactive wizard.')
         .option('--model <id>', 'Swap the pinned model')
         .option('--base-url <url>', 'Swap the custom endpoint base URL')
         .option('--auth-provider <provider>', 'Repoint auth at a different provider (keychain-backed)')
@@ -437,9 +422,20 @@ Examples:
 
   # Copy a key out of an existing secrets bundle instead of typing it
   agents harness edit corp --from-secrets prod:OPENROUTER_KEY
+
+  # No flags, in an interactive terminal: a wizard walks each field pre-filled
+  agents harness edit deepseek
 `)
         .action(async (name, opts) => {
         try {
+            // No edit flags + a real terminal → the interactive wizard, pre-filled
+            // with current values. Any flag (or a non-interactive caller) takes the
+            // flag path unchanged; a flagless non-interactive call still errors via
+            // buildEdit's EDIT_FLAGS_HELP.
+            if (!hasEditFlags(opts) && isInteractiveTerminal()) {
+                await runEditWizard(name, opts);
+                return;
+            }
             const edited = buildEdit(name, opts);
             if (opts.fromSecrets) {
                 await applyFromSecrets(edited, opts.fromSecrets, opts.authProvider);

package/dist/commands/insights.js

@@ -340,7 +340,10 @@ async function insightsAction(options) {
         console.error(chalk.red('error: --min-messages must be a non-negative integer'));
         process.exit(1);
     }
-    const since = options.since ?? '30d';
+    // `--all` is the spelling people reach for; `--since all` is what the window parser
+    // speaks. Accept both rather than failing on an unknown option, and let an explicit
+    // --since win so `--all --since 7d` is not silently contradictory.
+    const since = options.since ?? (options.all ? 'all' : '30d');
     const sinceMs = since === 'all' ? undefined : parseTimeFilter(since);
     // Refresh the index first, exactly as `agents cost` does, so a report never silently
     // describes a stale picture of disk.
@@ -436,6 +439,7 @@ export function registerInsightsCommand(program) {
         .description('How you work — tools, friction, and rhythm, split by the account that did the work')
         .option('--json', 'Output the full report as JSON')
         .option('--since <time>', 'Window: 7d, 4w, 3mo, an ISO date, or "all" (default 30d)')
+        .option('--all', 'Every session ever indexed. Alias for --since all')
         .option('--by <dimension>', 'Group by: account (default), agent, project, or day')
         .option('--account <match>', 'Only sessions whose account key, email, or org contains this')
         .option('--agent <id>', 'Only one harness (claude, codex, droid, …)')
@@ -454,7 +458,7 @@ export function registerInsightsCommand(program) {
       agents insights --by project --since 90d
 
       # One account only, all of its history
-      agents insights --account "Turing Labs" --since all
+      agents insights --account "Turing Labs" --all
 
       # Machine-readable, for a dashboard or a slash command
       agents insights --json

package/dist/commands/inspect.js

@@ -22,12 +22,14 @@ import * as yaml from 'yaml';
 import { AGENTS, getCliState, resolveAgentName } from '../lib/agents.js';
 import { supports } from '../lib/capabilities.js';
 import { resolveConfiguredModel } from '../lib/models.js';
+import { getAgentModesCatalog } from '../lib/agent-modes.js';
 import { resolveSingleAgentTarget, AgentSpecError } from '../lib/agent-spec/index.js';
 import { readMeta, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
 import { getVersionHomePath, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
 import { getShimsDir, getVersionedAliasPath } from '../lib/shims.js';
 import { getAgentResources, listResources, } from '../lib/resources.js';
 import { listHookEntriesFromDir } from '../lib/hooks.js';
+import { getResourceInventory } from '../lib/resource-inventory.js';
 import { listMcpServerConfigs, discoverMcpConfigsFromRepo } from '../lib/mcp.js';
 import { discoverPlugins, discoverPluginsInDir, pluginResourceGroups } from '../lib/plugins.js';
 import { PLUGIN_GROUP_COLORS } from './plugins.js';
@@ -113,7 +115,7 @@ function truncateValueForPrefix(prefix, value) {
 // ─── Command registration ────────────────────────────────────────────────────
 export function registerInspectCommand(program) {
     const cmd = addHostOption(program.command('inspect <target>'))
-        .description('Inspect one installed agent at one version, or a DotAgents repo (user|system|project|alias|path) — paths, capabilities, resources, drill into any kind.')
+        .description('Inspect one installed agent harness at one version (not a model), or a DotAgents repo — paths, capabilities, resources, and hook capable/on-disk/wired state.')
         .option('--brief', 'header + capabilities only; skip resources/sessions')
         .option('--json', 'machine-readable JSON output');
     for (const kind of DRILLABLE_KINDS) {
@@ -575,12 +577,14 @@ async function renderSummary(agent, version, versionHome, options) {
     const isIsolatedDefault = isolated && getIsolatedDefault(agent) === version;
     const capabilities = collectCapabilities(agent, version);
     const itemsByKind = options.brief ? null : collectItemsByKind(agent, versionHome);
+    const hookInventory = options.brief ? null : getResourceInventory(agent, version, 'hooks');
     const hookByScript = options.brief ? null : hookManifestByScript(loadCentralHookManifest());
     const mcpConfigs = options.brief ? null : new Map(listMcpServerConfigs().map(s => [s.name, s.config]));
     const sessions = options.brief ? null : {
         total: safeCountSessions(agent),
     };
     if (options.json) {
+        const modeCat = getAgentModesCatalog(agent, version);
         const json = {
             agent,
             version,
@@ -594,7 +598,14 @@ async function renderSummary(agent, version, versionHome, options) {
             strategy,
             installedShim: cliState?.installed === true ? cliState.path : null,
             capabilities,
-            resources: itemsByKind ? summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) : null,
+            modes: {
+                supported: modeCat.modes.map((m) => m.mode),
+                defaultMode: modeCat.defaultMode,
+                configuredMode: modeCat.configuredMode,
+                headlessPlan: modeCat.headlessPlan,
+                unsupported: modeCat.unsupported,
+            },
+            resources: itemsByKind ? summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs, hookInventory) : null,
             sessions,
         };
         console.log(JSON.stringify(json, null, 2));
@@ -623,12 +634,23 @@ async function renderSummary(agent, version, versionHome, options) {
         const reason = res.ok ? '' : chalk.gray(`(${res.reason}${res.need ? ' ' + res.need : ''})`);
         console.log(`  ${cap.padEnd(10)} ${mark} ${reason}`);
     }
+    // Permission modes are a separate axis from the capability booleans above —
+    // same data as `agents modes <agent>`, kept next to the rest of the inspect
+    // surface so a human/agent does not have to leave this view.
+    {
+        const modeCat = getAgentModesCatalog(agent, version);
+        const modeList = modeCat.modes.map((m) => (m.isDefault ? `${m.mode}*` : m.mode)).join('/');
+        const cfg = modeCat.configuredMode ? chalk.gray(`  run default: ${modeCat.configuredMode}`) : '';
+        console.log(`  ${'modes'.padEnd(10)} ${chalk.cyan(modeList)}${cfg}`);
+        console.log(chalk.gray(`             agents modes ${agent}  ·  agents models ${agent}@${version}`));
+    }
     if (itemsByKind) {
         console.log('\n' + chalk.bold('Resources'));
         for (const kind of SIMPLE_KINDS) {
             printSimpleResourceRow(kind, itemsByKind[kind]);
         }
-        printExpandedSection('Hooks', hookRows(itemsByKind.hooks, hookByScript));
+        console.log(`  ${chalk.bold('Hooks')}  ${chalk.gray(formatHookInventoryCounts(hookInventory))}`);
+        printExpandedSection('Hook files', hookRows(itemsByKind.hooks, hookByScript));
         printExpandedSection('Plugins', pluginRows(itemsByKind.plugins));
         printExpandedSection('MCP', mcpRows(itemsByKind.mcp, mcpConfigs));
     }
@@ -769,13 +791,20 @@ function printSimpleResourceRow(kind, items) {
  * simple kinds add `names`, and the rich kinds add structured `items` (hook
  * events/predicates, mcp transport/url/command, plugin version + group counts).
  */
-function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) {
+function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs, hookInventory) {
     const out = {};
     for (const kind of DRILLABLE_KINDS) {
         const items = itemsByKind[kind];
         const base = { total: items.length, bySource: countBySource(items.map(i => i.source)) };
         if (kind === 'hooks') {
-            out[kind] = { ...base, items: items.map(i => {
+            out[kind] = { ...base,
+                capable: hookInventory.capable,
+                declared: hookInventory.declared,
+                onDisk: hookInventory.onDisk,
+                wired: hookInventory.wired,
+                unmanaged: hookInventory.unmanaged,
+                wiringSupported: hookInventory.wiringSupported,
+                items: items.map(i => {
                     const h = hookByScript.get(i.name);
                     return { name: i.name, source: i.source, events: h?.events ?? [], matcher: h?.matcher, matches: h?.matches, cache: h?.cache };
                 }) };
@@ -800,6 +829,11 @@ function summaryResourcesJson(itemsByKind, hookByScript, mcpConfigs) {
     }
     return out;
 }
+function formatHookInventoryCounts(inventory) {
+    const wired = inventory.wiringSupported ? String(inventory.wired.length) : 'unknown';
+    const unmanaged = inventory.unmanaged.length > 0 ? ` · unmanaged ${inventory.unmanaged.length}` : '';
+    return `capable ${inventory.capable ? 'yes' : 'no'} · on-disk ${inventory.onDisk.length} · wired ${wired}${unmanaged}`;
+}
 function collectKind(agent, versionHome, kind) {
     switch (kind) {
         case 'commands':

package/dist/commands/menubar.js

@@ -51,7 +51,12 @@ function printStatus(s, opts = {}) {
         console.log(chalk.gray('  End them with `agents menubar setup`.'));
     }
     if (s.stale) {
-        console.log(chalk.yellow('\n  Installed AGI Menu is stale — runs on next `agents` startup, or `agents menubar setup` now.'));
+        // Not "runs on next startup": the self-heal only reinstalls from the install
+        // that owns the helper, or from another one once the takeover cooldown has
+        // passed (mayInstallMenubarHelper) — so on a box with several agents-cli
+        // copies this can persist for a while. `setup` bypasses the gate and is the
+        // immediate fix.
+        console.log(chalk.yellow('\n  Installed AGI Menu is stale — `agents menubar setup` updates it now.'));
     }
     else if (!s.serviceInstalled && !s.disabledByUser) {
         console.log(chalk.gray('\n  Set it up with `agents menubar setup`.'));

package/dist/commands/models.js

@@ -72,6 +72,7 @@ export function registerModelsCommand(program) {
         if (!agentSpec && !all) {
             console.log(chalk.gray('\n  `agents models <agent>` for one harness · `--all` for the full model list'));
             console.log(chalk.gray('  `agents models tier set <agent> <tier> <model>` to override a tier'));
+            console.log(chalk.gray('  Permission modes (--mode plan|edit|auto|skip): `agents modes <agent>`'));
         }
     });
     // Override subcommands. These WRITE agents.yaml so the user never hand-edits it;

package/dist/commands/modes.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents modes` — list the permission modes a harness accepts for
+ * `agents run` / `agents teams add`.
+ *
+ * Mirror of `agents models`: humans and orchestrating agents read this before
+ * picking `--mode plan|edit|auto|skip`. Modes are per-agent today (not version-
+ * gated); `agent@version` is accepted so the configured run.defaults mode for
+ * that version can be shown beside the catalog.
+ */
+import type { Command } from 'commander';
+/** Register `agents modes [agent[@version]]`. */
+export declare function registerModesCommand(program: Command): void;

package/dist/commands/modes.js

@@ -0,0 +1,147 @@
+/**
+ * `agents modes` — list the permission modes a harness accepts for
+ * `agents run` / `agents teams add`.
+ *
+ * Mirror of `agents models`: humans and orchestrating agents read this before
+ * picking `--mode plan|edit|auto|skip`. Modes are per-agent today (not version-
+ * gated); `agent@version` is accepted so the configured run.defaults mode for
+ * that version can be shown beside the catalog.
+ */
+import chalk from 'chalk';
+import { AGENTS, ALL_AGENT_IDS, agentLabel, formatAgentError, resolveAgentName, } from '../lib/agents.js';
+import { formatModeFlags, getAgentModesCatalog, } from '../lib/agent-modes.js';
+import { setHelpSections } from '../lib/help.js';
+import { getGlobalDefault, listInstalledVersions, resolveVersion, resolveVersionAlias } from '../lib/versions.js';
+/** Agents that show in the no-arg overview (skip hard-deprecated). */
+const MODE_AGENTS = ALL_AGENT_IDS.filter((id) => !AGENTS[id].deprecated?.hard);
+/** Register `agents modes [agent[@version]]`. */
+export function registerModesCommand(program) {
+    const modes = program
+        .command('modes [agentSpec]')
+        .description('Show which permission modes (--mode plan|edit|auto|skip) a harness supports for agents run / teams add')
+        .option('--json', 'Output machine-readable JSON')
+        .action((agentSpec, options) => {
+        const targets = resolveTargets(agentSpec);
+        if (targets.length === 0)
+            process.exit(1);
+        if (options.json) {
+            const out = targets.map(({ agent, version }) => {
+                const catalog = getAgentModesCatalog(agent, version);
+                return {
+                    agent,
+                    version,
+                    defaultMode: catalog.defaultMode,
+                    configuredMode: catalog.configuredMode,
+                    configuredModeSource: catalog.configuredModeSource,
+                    headlessPlan: catalog.headlessPlan,
+                    modes: catalog.modes.map((m) => ({
+                        mode: m.mode,
+                        flags: m.flags,
+                        description: m.description,
+                        isDefault: m.isDefault,
+                    })),
+                    unsupported: catalog.unsupported,
+                    notes: catalog.notes,
+                };
+            });
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        let printed = 0;
+        for (const { agent, version, isDefault } of targets) {
+            if (printed > 0)
+                console.log();
+            printCatalog(getAgentModesCatalog(agent, version), version, isDefault);
+            printed++;
+        }
+        if (!agentSpec) {
+            console.log(chalk.gray('\n  `agents modes <agent>` for one harness · `agents modes claude@2.1.219` for a version\'s run default'));
+            console.log(chalk.gray('  Pass --mode on `agents run` / `agents teams add`. Models: `agents models <agent>`.'));
+        }
+    });
+    setHelpSections(modes, {
+        examples: `
+      agents modes
+      agents modes claude
+      agents modes claude@2.1.219
+      agents modes cursor --json
+    `,
+        notes: `
+      Permission modes control how much the agent can do (not which LLM model
+      runs — that is --model / agents models). Supported modes come from each
+      harness's capabilities table; unsupported requests degrade (auto→edit,
+      plan→safest native) or error (skip when missing).
+      'full' is a silent alias for skip.
+      agent@version is accepted so any configured run.defaults mode for that
+      version is shown; the mode list itself is per-agent today.
+    `,
+    });
+}
+function resolveTargets(agentSpec) {
+    if (!agentSpec) {
+        const targets = [];
+        for (const agent of MODE_AGENTS) {
+            const version = getGlobalDefault(agent) || listInstalledVersions(agent)[0] || null;
+            targets.push({ agent, version, isDefault: true });
+        }
+        return targets;
+    }
+    const [agentName, versionSpec] = agentSpec.split('@');
+    const agent = resolveAgentName(agentName);
+    if (!agent) {
+        console.error(chalk.red(formatAgentError(agentName, MODE_AGENTS)));
+        return [];
+    }
+    if (AGENTS[agent].deprecated?.hard) {
+        console.error(chalk.yellow(`${agent} is deprecated and no longer supports run modes.`));
+        return [];
+    }
+    if (versionSpec === 'all') {
+        const installed = listInstalledVersions(agent);
+        if (installed.length === 0) {
+            return [{ agent, version: null, isDefault: true }];
+        }
+        return installed.map((v) => ({
+            agent,
+            version: v,
+            isDefault: v === getGlobalDefault(agent),
+        }));
+    }
+    if (versionSpec) {
+        // resolveVersionAlias exits process if the concrete version is not installed.
+        const version = resolveVersionAlias(agent, versionSpec) ?? null;
+        return [{ agent, version, isDefault: version === getGlobalDefault(agent) }];
+    }
+    const version = resolveVersion(agent, process.cwd()) || getGlobalDefault(agent) || null;
+    return [{ agent, version, isDefault: true }];
+}
+function printCatalog(catalog, version, isDefault) {
+    const tag = version
+        ? ` ${chalk.bold(version)}${isDefault ? chalk.gray(' (default)') : ''}`
+        : chalk.gray(' (not installed)');
+    console.log(`${agentLabel(catalog.agent)}${tag}`);
+    console.log(chalk.gray('  modes:'));
+    for (const entry of catalog.modes) {
+        const star = entry.isDefault ? chalk.cyan('*') : ' ';
+        const flags = chalk.gray(formatModeFlags(entry.flags));
+        console.log(`  ${star} ${chalk.cyan(entry.mode.padEnd(6))} ${chalk.bold(entry.description)}  ${flags}`);
+    }
+    if (catalog.unsupported.length > 0) {
+        console.log(chalk.gray(`  unsupported: ${catalog.unsupported.join(', ')}`));
+    }
+    const defaultBits = [`native default ${chalk.white(catalog.defaultMode)}`];
+    if (catalog.configuredMode) {
+        const src = catalog.configuredModeSource ? chalk.gray(` (${catalog.configuredModeSource})`) : '';
+        defaultBits.push(`run default ${chalk.white(catalog.configuredMode)}${src}`);
+    }
+    console.log(chalk.gray(`  ${defaultBits.join(' · ')}`));
+    if (!catalog.headlessPlan && catalog.modes.some((m) => m.mode === 'plan')) {
+        console.log(chalk.yellow('  headless plan: not supported (interactive plan still works)'));
+    }
+    for (const note of catalog.notes) {
+        // Keep the full-alias note quiet; surface degrades more visibly.
+        if (note.startsWith("'full'"))
+            continue;
+        console.log(chalk.gray(`  note: ${note}`));
+    }
+}

package/dist/commands/resume.js

@@ -22,8 +22,8 @@ export function buildResumeRunArgs(session, prompt, options) {
 }
 export function registerResumeCommand(program) {
     const cmd = program
-        .command('resume <session-id> [prompt]')
-        .description('Resume a session with its original harness, version, device, account, cwd, and mode')
+        .command('resume <session> [prompt]')
+        .description('Resume a session by id, tmux alias, or exact label with its original harness, version, device, account, cwd, and mode. Searches the fleet automatically; a local full-id hit resumes with zero SSH.')
         .option('-m, --mode <mode>', 'Override the recorded launch mode')
         .option('-i, --interactive', 'Resume interactively even when a prompt is provided')
         .option('--headless', 'Resume headlessly (a prompt is required)')
@@ -71,10 +71,17 @@ export function registerResumeCommand(program) {
       # Resume and continue headlessly
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
 
+      # Resume by exact label (auto-resumes the one match)
+      agents resume "fix the flaky ssh test"
+
+      # Resume by durable tmux alias or its unique suffix
+      agents resume ag-codex-c1f3d813
+      agents resume c1f3d813
+
       # Deliberately change permissions
       agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
         notes: `
-      Full IDs resolve from the local session database first; an SSH fleet lookup runs only after a local miss.
+      A full ID resolves from the local session database first (zero SSH) and, on a local miss, fans out with the first peer holding it cancelling the rest. An exact label always consults the fleet (labels are not globally unique) and auto-resumes the one match; a cross-machine label collision surfaces as an ambiguity.
       Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
     });
 }