@phnx-labs/agents-cli 1.20.57 → 1.20.58

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 1.20.58
+
+- **Self-updating agent CLIs are represented as one live installation.** `agents view` no longer invents version-home rows for single-binary installers such as Droid, Grok, Cursor, Kiro, Goose, and Hermes; it reports the version returned by the installed binary and folds away stale per-version directories. `agents add <agent>@<version>` now installs or keeps that agent's current release instead of rejecting an unsupported pinned install. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/versions.ts`, `apps/cli/src/commands/{versions,view}.ts`. (RUSH-1321)
+- **Stopped teammate resumes are transactional from launch through persistence.** If a local or remote resume fails, the existing teammate record, directory, runtime metadata, stdout mirror, and log cursor are restored; any replacement wrapper and its descendants are terminated as one process group. A successful resume whose log was truncated restarts parsing at byte zero, and a secondary restore-write failure retains the original launch error as its cause. Source: `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/lib/hosts/dispatch.ts`. (#1104, #1108)
+- **Wire allowlist support for Cursor CLI.** Cursor agent CLI stores allow/deny in `~/.cursor/cli-config.json` (`permissions.allow`/`deny` with Shell/Read/Write/WebFetch/Mcp). Flip `allowlist: true`, add `convertToCursorFormat` (Bash→Shell), and write via `applyPermissionsToVersion` + detector. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/permissions.ts`. (RUSH-1387)
+- **GitHub Copilot CLI subagents now sync (RUSH-1390).** Installed subagents flatten into GitHub Copilot custom-agent profiles at `~/.copilot/agents/<name>.agent.md` (the Droid custom-droid format), gated to Copilot CLI ≥ 0.0.353. `agents subagents list/view` now surfaces synced Copilot agents and `agents subagents remove` soft-deletes their `.agent.md` files to trash — both previously skipped `copilot` entirely. Source: `apps/cli/src/lib/subagents.ts` (`listSubagentsForAgent`, `removeSubagentFromVersion`, `transformSubagentForCopilot`), `apps/cli/src/lib/staleness/writers/subagents.ts`, `apps/cli/src/lib/staleness/detectors/subagents.ts`, `apps/cli/src/lib/agents.ts`.
+- **Menu-bar Quick Dispatch preserves typed drafts when focus is stolen (RUSH-1592).** If another app activates while the `Cmd-Shift-O` capture panel is open, the panel can hide without destroying the note; the next summon restores the draft text plus selected screenshots, action, and agents. Return submits and clears the draft; Escape clears without dispatching. Source: `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`, `apps/cli/docs/menubar.md`.
+- **Wire subagents support for Kiro CLI.** Kiro custom agents are JSON files under `~/.kiro/agents/*.json` (introduced in kiro-cli v1.23.0). Flip Kiro's `subagents: { since: '1.23.0' }`, add `transformSubagentForKiro`, and wire the subagents writer, detector, install/remove, and orphan-detection paths. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/subagents.ts`, `apps/cli/src/lib/staleness/{writers,detectors}/subagents.ts`. (RUSH-1393)
+- **Menu-bar ticket agents now carry every selected screenshot into the Linear issue (RUSH-1668).** `Cmd-Shift-O` already passed selected file paths to the ticket agent, but the prompt only asked it to inspect them, so agents could create text-only issues and stop. The brief now identifies every selected path as user-provided ticket material, requires each file to be uploaded, supplies the existing `linear update <id> --proof <path>` path as a reliable default, and leaves description/comment/other placement to the agent's judgment. Source: `apps/cli/menubar/Sources/MenubarHelper/{AgentsCLI,IssueSelfTest}.swift`, `apps/cli/docs/menubar.md`.
+- **`agents sessions --active --json` now carries session attachment metadata for Factory previews (RUSH-1524).** Claude and Droid prompt image/document blocks that reference local files are preserved as `{ path, name, mediaType, sizeBytes }`, and the active-session state dedupes them into `attachments` so consumers can render screenshot thumbnails and open the original files instead of only seeing an attachment count. Source: `apps/cli/src/lib/session/parse.ts`, `apps/cli/src/lib/session/state.ts`, `apps/cli/src/lib/session/active.ts`.
+- **Retired the standalone `com.phnx-labs.agents-secrets-agent` launchd service — the always-on daemon is now the sole broker host (#416, step 2).** `ensureAgentRunning()` no longer installs a separate launchd service: it retires any leftover plist via the new `retireLegacySecretsAgentService()` and relies on the daemon (Path 0), with a one-off detached broker as the only fallback. The upgrade migration (`scripts/postinstall.js` → `healLongRunningProcesses`) now `launchctl bootout`s the legacy service **first**, then (re)starts the daemon so it takes over the broker socket, instead of kickstarting the old service onto new code. `agents secrets start` is now a thin alias that brings the daemon up (and waits for the broker to answer); `agents secrets stop` locks all bundles and retires any leftover legacy service while leaving the always-on daemon running; `agents secrets status` reports broker reachability (daemon-hosted vs standalone) rather than "service installed". The stale broker teardown (version-skew self-heal) retires the legacy service instead of kickstarting it. Source: `apps/cli/src/lib/secrets/agent.ts` (`retireLegacySecretsAgentService`, `ensureAgentRunning`, `teardownStaleBroker`, `uninstallSecretsAgentService`; removed `installSecretsAgentService`/`kickstartSecretsAgentService`/`generateServicePlist`), `apps/cli/scripts/postinstall.js` (`healLongRunningProcesses`), `apps/cli/src/commands/secrets.ts` (`start`/`stop`/`status`).
+
+- **Clarify the native escape hatch behind `--mode skip`.** The README and bundled `run` skill now discourage `skip`, list its exact direct-exec per-harness flag mappings and ACP `allow_always` behavior, replace an older recommendation of unsafe `full` for ordinary writes, and distinguish Codex `auto` (sandboxed `edit`, which can still prompt) from Codex `skip` (`--dangerously-bypass-approvals-and-sandbox`, equivalent to unsandboxed `--yolo`). Documentation only; runtime behavior is unchanged. Source: `README.md`, `skills/run/SKILL.md`.
+- **Wire allowlist support for Kiro CLI.** Kiro 2.8.0+ permission groups now sync into `~/.kiro/settings/permissions.yaml` as v3 capability rules for shell, filesystem, and web access; existing user-authored rules are preserved and duplicate generated rules are removed. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/permissions.ts`, `apps/cli/src/lib/staleness/detectors/permissions.ts`. (RUSH-1392)
+- **Fix: remote `agents secrets view <bundle>@host --reveal` no longer leaves a 60-second SSH control master behind.** The interactive `-tt` reveal path now opts out of default SSH multiplexing (`multiplex: false`), matching the transport guidance for one-shot commands that must not keep a `ControlPersist` socket open after a Touch ID/passphrase reveal. Source: `apps/cli/src/lib/secrets/remote.ts` (`remoteSecretsRaw`).
+- **`agents run --host <host> --cwd <dir>` now sets the working directory ON the host (and a new `--project` shorthand jumps to a project by name).** Previously `--cwd` was silently dropped for `--host` runs — only the separate `--remote-cwd` flag worked — so `agents run claude --host s1 --cwd ~/src/foo` landed in the remote login-shell's default directory with no warning. `--cwd` is now forwarded as the host working directory, and a home-anchored path (`~/…`, `$HOME/…`, or a local-home absolute the shell already expanded like `/Users/me/…`) is re-rooted at the *remote* `$HOME` so it resolves correctly across machines with different home paths (`/Users/me` → `/home/me`). `--remote-cwd` remains as the explicit override. New `-P, --project <slug>[@worktree]` resolves a bare project name against your projects root (e.g. `~/src/github.com/<user>`) — auto-inferred from the repo you launch inside and cached in `agents.yaml`, or set/shown with `agents defaults project-root [path]`; `--project foo@fix` targets the `fix` git worktree. Works for local and `--host` runs. Verified end-to-end: `agents run claude --host yosemite-s1 --project agents-cli` runs the remote agent with `pwd` = `/home/muqsit/src/github.com/muqsitnawaz/agents-cli`. Source: `apps/cli/src/lib/project-root.ts` (new), `apps/cli/src/lib/hosts/dispatch.ts` (`remoteCdPrefix`), `apps/cli/src/commands/exec.ts` (`--project`/`--cwd` host wiring), `apps/cli/src/commands/defaults.ts` (`project-root`).
+- **Fix daemon crash-looping when its pinned Node version is pruned (fleet-wide).** The routine daemon's launchd/systemd manifest hardcoded `~/.nvm/versions/node/v24.0.0/bin` on PATH, and launched the CLI entry bare when it was an extension-less shim or a `bin/agents → dist/index.js` symlink (an extension check on the link name missed it). The moment that exact nvm patch was upgraded away, the shim's `#!/usr/bin/env node` shebang fell through to an ancient system node (Node 18 → `SyntaxError: node:util has no export 'styleText'` from `@inquirer/core`), and the service crash-looped at import — observed at 100k+ restarts on Linux workers, silently killing all scheduled routines. `getDaemonLaunch` now detects Node-script entries by resolving symlinks and sniffing the shebang (not just the `.js`/`.cjs`/`.mjs` extension), so it pins them to `process.execPath`; and the generated PATH now leads with `path.dirname(process.execPath)` — the Node that installed the service — instead of a hardcoded nvm version, so both the shim and child routine processes always resolve a working runtime. Source: `apps/cli/src/lib/daemon.ts` (`getDaemonLaunch`, `isNodeScriptEntry`, `daemonNodeBinDir`, `generateSystemdUnit`, `generateLaunchdPlist`).
+- **Fix global npm upgrades restarting the routines daemon through `scripts/postinstall.js`.** The postinstall process is itself `process.argv[1]`, so its daemon self-heal could stamp `node scripts/postinstall.js daemon _run` into launchd. Daemon startup now accepts an explicit CLI entry and postinstall passes the resolved signed native binary (or JavaScript entrypoint), with the same value threaded through launchd, systemd, and detached startup. Source: `apps/cli/scripts/postinstall.js`, `apps/cli/src/lib/daemon.ts`.
+- **Fix a standalone secrets service stealing the daemon-hosted broker socket during postinstall.** The standalone and hosted brokers now bind through one race-safe owner arbitration path: an existing reachable broker wins without its socket being unlinked, a persistent losing service stays quiescent instead of triggering launchd restart churn, takes over if the owner stops, and releases its standby PID on service shutdown; only an unreachable stale socket is reclaimed. This covers the release ordering where postinstall restarts the daemon first and then kickstarts an installed standalone service. Source: `apps/cli/src/lib/secrets/agent.ts` (`bindBrokerSocket`, `runSecretsAgent`, `startHostedBroker`).
+
 ## 1.20.57
 
 - **`agents teams resume` / `agents teams message` — resume a stopped teammate with a follow-up message.** A teammate that ended its turn with more to do (PR open awaiting review, headless turn cap, a redirect after the fact) could not be reached: `agents message` resolves only *live* sessions, so a completed/stopped/failed teammate had no path back short of finishing the work by hand or spawning a fresh, context-less teammate. `teams resume <team> <teammate> <message>` re-enters the teammate's **own** session with the message as the next user turn, re-launching through the same backend (local process or remote host) in its original worktree and flipping it back to `running` so `teams status` tracks it live. `teams message` is the same command with automatic routing by reconciled status: a **running** teammate is steered via its mailbox (delivered at its next tool call, no re-launch); a **stopped** one is resumed; a **pending** one is refused with a pointer to `teams start`. Works for every harness — the resume delegates to `agents run --resume`, inheriting native resume for Claude/Codex and the universal `/continue` replay for the rest (OpenCode, Grok, Kimi, …); the resume target is the teammate's captured underlying session id (`remoteSessionId ?? agentId`), and a non-Claude teammate that died before emitting a session id is refused with a clear error rather than resumed into a fresh run. This also makes good on `teams stop`'s long-standing "can be restarted later" promise, which no code implemented. Source: `apps/cli/src/commands/teams.ts` (`message`/`resume` subcommands, `decideTeamMessageRoute`), `apps/cli/src/lib/teams/agents.ts` (`AgentManager.resumeTeammate`, resume-aware `buildRunArgv`/`buildCommand`/`launchProcess`/`launchRemoteProcess`).

package/README.md

@@ -155,7 +155,37 @@ agents run claude "Review PRs merged this week, summarize risks" \
   | agents run codex "Write regression tests for the top 3 risks"
 ```
 
-Supports plan (read-only) and edit modes, effort levels, JSON output for scripting, and timeout limits.
+Supports plan (read-only), edit, auto, and skip modes, effort levels, JSON output for scripting, and timeout limits.
+
+### What does `--mode skip` actually do?
+
+Treat `skip` as a last-resort escape hatch. In direct-exec runs (without `--acp`),
+agents-cli forwards the harness's native no-prompt flag; it does not add another
+safety layer. Prefer `auto` where the harness has a smart classifier (Claude Code and
+GitHub Copilot), or `edit` everywhere else. Harnesses without a native bypass flag
+reject direct-exec `skip`.
+
+| Harness | Direct-exec `--mode skip` becomes |
+|---|---|
+| Claude Code | `--dangerously-skip-permissions` |
+| Codex | `--dangerously-bypass-approvals-and-sandbox` (equivalent to `--yolo`) |
+| Gemini | `--yolo` |
+| Cursor | `-f` |
+| OpenClaw | `--mode full` |
+| GitHub Copilot | `--allow-all` (alias: `--yolo`) |
+| Antigravity | `--dangerously-skip-permissions` |
+| Grok | `--always-approve` |
+| Kimi | `--yolo` interactively; no extra flag in headless `-p` runs, which already auto-approve |
+| Droid | `--skip-permissions-unsafe` |
+
+With `--acp`, these native flags are not used. agents-cli instead grants `skip`
+permission requests at the ACP protocol layer with `allow_always`; the same
+last-resort warning applies.
+
+Codex has no native smart-classifier mode, so `agents run codex --mode auto` resolves
+to sandboxed `edit` and can still prompt. `agents run codex --mode skip` is different:
+it bypasses approvals **and** removes the sandbox. `full` remains an alias for `skip`,
+but new scripts should use the explicit `skip` name.
 
 ### One protocol, every harness
 
@@ -432,7 +462,7 @@ tools:
 ---
 ```
 
-Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit` or `--mode full`. `agents run` defaults to `--mode plan` (read-only), which deadlocks at `ExitPlanMode` in headless runs.
+Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit`, or `--mode auto` on Claude Code and GitHub Copilot. Reserve `--mode skip` (legacy alias: `full`) for last-resort bypasses. `agents run` defaults to `--mode plan` (read-only), which deadlocks at `ExitPlanMode` in headless runs.
 
 Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` overrides a same-named workflow in `~/.agents/workflows/`. Commit project workflows with your repo so teammates get the same pipeline.
 
@@ -825,7 +855,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 | OpenCode | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
 | Copilot | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
 | Amp | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
-| Kiro | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
+| Kiro | yes | no | yes | >= 2.8.0 | yes | yes | no | no | `AGENTS.md` | no |
 | Goose | yes | no | yes | no | no | no | no | no | `AGENTS.md` | no |
 | Roo Code | yes | no | yes | no | yes | yes | no | no | `AGENTS.md` | no |
 
@@ -853,6 +883,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 |------------|-------|------|
 | Hooks | Codex | >= 0.116.0 |
 | Hooks | Gemini | >= 0.26.0 |
+| Permissions | Kiro | >= 2.8.0 |
 | File-based commands | Codex | < 0.117.0 (0.117+ uses command-as-skill) |
 | Plugins | Codex | >= 0.128.0 |
 

package/dist/commands/defaults.js

@@ -6,6 +6,7 @@
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { listRunDefaults, setRunDefault, unsetRunDefault, } from '../lib/run-defaults.js';
+import { getProjectRoot, setProjectRoot } from '../lib/project-root.js';
 function formatRunDefault(entry) {
     const parts = [];
     if (entry.defaults.mode)
@@ -86,4 +87,27 @@ export function registerDefaultsCommands(program) {
             process.exit(1);
         }
     });
+    defaults
+        .command('project-root [path]')
+        .description('Show or set the projects root for `agents run --project` (auto-inferred when unset)')
+        .action((rootPath) => {
+        try {
+            if (!rootPath) {
+                const current = getProjectRoot();
+                if (current) {
+                    console.log(`Projects root: ${chalk.white(current)}`);
+                }
+                else {
+                    console.log(chalk.gray('Projects root not set — auto-inferred and cached on first `--project` use.'));
+                }
+                return;
+            }
+            const stored = setProjectRoot(rootPath);
+            console.log(chalk.green(`Set projects root: ${stored}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
 }

package/dist/commands/exec.js

@@ -211,7 +211,8 @@ export function registerRunCommand(program) {
         .option('--no-auto-secrets', 'Skip auto-injection of secrets declared by a workflow\'s frontmatter `secrets:` field. Has no effect on bare-agent runs.')
         .option('--secrets-keys <keys>', 'Inject only this comma-separated subset of keys from --secrets bundles (e.g. KEY1,KEY2). Missing keys are an error. Applies to all --secrets bundles on this run.')
         .option('--allow-expired', 'Inject secrets even if their expiry date has passed (overrides the pre-run expiry abort).')
-        .option('--cwd <dir>', 'Working directory for the agent (defaults to current directory)')
+        .option('--cwd <dir>', 'Working directory for the agent (defaults to current directory). With --host, the directory ON the host.')
+        .option('-P, --project <ref>', 'Project shorthand <slug>[@worktree], resolved against your projects root (auto-inferred, cached). Sets the cwd locally or on --host.')
         .option('--add-dir <dir>', 'Grant access to an additional directory outside the project (Claude and Codex, repeatable)', (val, prev) => [...prev, val], [])
         .option('--json', 'Stream events as JSON lines (for parsing by other tools)')
         .option('--quiet', 'Suppress preamble (rotation banner, "Running:" line). Useful when piping JSON events to a parser.', false)
@@ -238,7 +239,7 @@ export function registerRunCommand(program) {
         .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.')
         .option('--host <name>', 'Offload this run onto another machine over SSH instead of running locally — a device, a registered agent host, or user@host. See `agents devices` / `agents hosts`.')
         .option('--device <name>', 'Alias of --host: offload this run onto a registered device (from `agents devices`).')
-        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .option('--remote-cwd <dir>', 'Explicit host working directory for --host runs (overrides --cwd; usually --cwd suffices).')
         .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.')
         .option('--lease [backend]', 'Invent a disposable cloud box for this run and tear it down after (via crabbox). Optional backend selects the cloud (hetzner/aws/do). Unlike --host, no machine is registered.')
@@ -454,6 +455,24 @@ export function registerRunCommand(program) {
         // --host/--on/--computer: offload this run onto a registered agent host
         // over SSH instead of running locally. The three flags are aliases.
         const hostGiven = [options.host, options.device, options.on, options.computer].filter((v) => !!v);
+        // --project <slug>[@worktree]: resolve the projects-root shorthand into a
+        // cwd. On a host run it resolves home-relative (`~/…`, so the host expands
+        // it); locally it becomes an absolute path. It owns the working directory,
+        // so it is mutually exclusive with both --cwd and --remote-cwd.
+        if (options.project) {
+            if (options.cwd || options.remoteCwd) {
+                console.error(chalk.red('Pass --project alone — not with --cwd or --remote-cwd.'));
+                process.exit(1);
+            }
+            const { resolveProjectRef } = await import('../lib/project-root.js');
+            try {
+                options.cwd = await resolveProjectRef(options.project, { forRemote: hostGiven.length > 0 });
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         if (hostGiven.length > 0) {
             if (new Set(hostGiven).size > 1) {
                 console.error(chalk.red('Conflicting --host/--device values — pass just one.'));
@@ -488,6 +507,11 @@ export function registerRunCommand(program) {
             }
             try {
                 const runAgent = agentSpec.split('@')[0];
+                // Working directory on the host: an explicit --remote-cwd is used
+                // verbatim; --cwd/--project are made portable (a local-home absolute
+                // becomes `~/…` so the remote shell re-roots it at ITS home).
+                const { toRemotePortable } = await import('../lib/project-root.js');
+                const hostCwd = options.remoteCwd ?? (options.cwd ? toRemotePortable(options.cwd) : undefined);
                 // `--resume [id]`: commander yields the string id, or `true` when the
                 // flag is passed bare. A bare resume needs the interactive picker,
                 // which can't run over a detached remote dispatch — only forward a
@@ -528,7 +552,7 @@ export function registerRunCommand(program) {
                         prompt,
                         mode: options.mode,
                         model: options.model,
-                        remoteCwd: options.remoteCwd,
+                        remoteCwd: hostCwd,
                         sessionId: hostSessionId,
                         name: options.name,
                         resume: resumeId,
@@ -550,7 +574,7 @@ export function registerRunCommand(program) {
                     prompt,
                     mode: options.mode,
                     model: options.model,
-                    remoteCwd: options.remoteCwd,
+                    remoteCwd: hostCwd,
                     sessionId: hostSessionId,
                     name: options.name,
                     resume: resumeId,

package/dist/commands/secrets.js

@@ -12,14 +12,14 @@ import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/widt
 import * as fs from 'fs';
 import { SSH_TARGET_RE, assertValidSshTarget, sshExec } from '../lib/ssh-exec.js';
 import { quoteWin32ExecArg, composeWin32CommandLine } from '../lib/platform/index.js';
-import { ensureDaemonStarted } from '../lib/daemon.js';
+import { ensureDaemonStarted, isDaemonRunning } from '../lib/daemon.js';
 import { parseHostsOption, remoteResolveEnv, remoteSecretsRaw, remoteSecretsStream, resolveSshTarget, } from '../lib/secrets/remote.js';
 import { remoteShellFor, buildWindowsStdinImportCommand } from '../lib/hosts/remote-cmd.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { bundleExists, bundleItemStore, bundlePolicy, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readAndResolveBundleEnv, readBundle, renameBundle, rotateBundleSecret, sanitizeProcessEnv, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { getKeychainToken, getKeychainTokens, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
-import { DEFAULT_TTL_MS, agentLoad, agentLock, agentStatus, ensureAgentRunning, installSecretsAgentService, runAgentLoadFromStdin, runSecretsAgent, secretsAgentServiceInstalled, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { DEFAULT_TTL_MS, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { emit } from '../lib/events.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
@@ -1770,13 +1770,13 @@ Examples:
             ttlMs = secs * 1000;
         }
         if (!(await ensureAgentRunning())) {
-            console.error(chalk.red('Could not start the secrets-agent.'));
+            console.error(chalk.red('Could not start the secrets broker.'));
             process.exit(1);
         }
         // #415: the daemon should be always-on for any background need, not only
-        // after `routines add`. A user who only ever unlocks secrets still gets
-        // the daemon installed + running here. `ensureAgentRunning` above only
-        // brings up the standalone secrets broker, not the daemon. Idempotent
+        // after `routines add`. `ensureAgentRunning` prefers the daemon (it hosts
+        // the broker, #416), but can fall back to a one-off broker spawn when the
+        // daemon can't come up — so ensure the daemon is up regardless. Idempotent
         // (single-instance start lock, #414) and best-effort — never blocks unlock.
         ensureDaemonStarted();
         let loaded = 0;
@@ -1830,13 +1830,14 @@ Examples:
             console.log(chalk.gray('secrets-agent is macOS-only.'));
             return;
         }
-        console.log(chalk.gray('service: ') +
-            (secretsAgentServiceInstalled()
-                ? chalk.green('installed (persistent)')
-                : chalk.yellow('not installed — run `agents secrets start` for a persistent broker')));
+        const brokerUp = (await agentPing()).reachable;
+        console.log(chalk.gray('broker: ') +
+            (brokerUp
+                ? chalk.green('running') + chalk.gray(isDaemonRunning() ? ' (hosted by the daemon)' : ' (standalone)')
+                : chalk.yellow('not running — starts on demand, or run `agents secrets start` to bring the daemon up now')));
         const entries = await agentStatus();
         if (entries.length === 0) {
-            console.log(chalk.gray('No bundles unlocked. The secrets-agent is idle or not running.'));
+            console.log(chalk.gray('No bundles unlocked. The secrets broker is idle or not running.'));
             console.log(chalk.gray('Try: agents secrets unlock <bundle>'));
             return;
         }
@@ -1887,29 +1888,37 @@ Examples:
     });
     cmd
         .command('start')
-        .description('Install + start the secrets-agent as a persistent background service (macOS). Survives heavy load; reads connect instantly.')
+        .description('Bring up the always-on daemon that hosts the secrets broker (macOS). Survives heavy load; reads connect instantly.')
         .action(async () => {
         if (process.platform !== 'darwin') {
-            console.error(chalk.red('secrets-agent service is macOS-only.'));
+            console.error(chalk.red('The secrets broker is macOS-only.'));
             process.exit(1);
         }
-        process.stdout.write(chalk.gray('Installing launchd service…\n'));
-        if (await installSecretsAgentService()) {
-            console.log(chalk.green('secrets-agent service running.') + chalk.gray(' It stays up across your macOS login session; unlock/auto-cache now connect instantly.'));
+        process.stdout.write(chalk.gray('Starting the daemon…\n'));
+        ensureDaemonStarted();
+        // The daemon hosts the broker socket-first; wait briefly for it to answer.
+        const deadline = Date.now() + 10000;
+        let reachable = (await agentPing()).reachable;
+        while (!reachable && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 200));
+            reachable = (await agentPing()).reachable;
+        }
+        if (reachable) {
+            console.log(chalk.green('secrets broker running.') + chalk.gray(' Hosted by the always-on daemon; unlock/auto-cache now connect instantly.'));
         }
         else {
-            console.error(chalk.red('Service installed but did not become reachable in time (machine may be heavily loaded — launchd will keep retrying).'));
+            console.error(chalk.red('Daemon started but the broker did not become reachable in time (machine may be heavily loaded — it will keep retrying).'));
             process.exit(1);
         }
     });
     cmd
         .command('stop')
-        .description('Stop + remove the persistent secrets-agent service and wipe what it held.')
+        .description('Lock all bundles and retire any legacy standalone service. The always-on daemon (which hosts the broker) is left running.')
         .action(async () => {
         if (process.platform !== 'darwin')
             return;
         await uninstallSecretsAgentService();
-        console.log(chalk.green('secrets-agent service stopped and removed.'));
+        console.log(chalk.green('Locked all bundles.') + chalk.gray(' The broker stays hosted by the always-on daemon; a legacy standalone service, if any, was retired.'));
     });
     cmd
         .command('_agent-run', { hidden: true })

package/dist/commands/versions.js

@@ -4,7 +4,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import { select, confirm, checkbox } from '@inquirer/prompts';
-import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, warnAgentDeprecated, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, warnAgentDeprecated, isSelfUpdatingAgent, } from '../lib/agents.js';
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
@@ -67,7 +67,7 @@ async function setDefaultVersion(agent, installedVersion) {
     createVersionedAlias(agent, installedVersion);
     const symlinkResult = await switchConfigSymlink(agent, installedVersion);
     if (symlinkResult.success) {
-        console.log(chalk.green('  Set as default'));
+        console.log(chalk.green(isSelfUpdatingAgent(agent) ? '  Set as active config profile' : '  Set as default'));
         if (symlinkResult.backupPath) {
             console.log(chalk.gray(`  Backed up existing config to: ${symlinkResult.backupPath}`));
         }
@@ -752,7 +752,15 @@ export function registerVersionsCommands(program) {
                 warnIfShimShadowed(agentId);
                 const useEmail = await getAccountEmail(agentId, getVersionHomePath(agentId, finalVersion));
                 const useEmailStr = useEmail ? chalk.cyan(` (${useEmail})`) : '';
-                console.log(chalk.green(`Set ${agentLabel(agentConfig.id)}@${finalVersion} as global default`) + useEmailStr);
+                // Self-updating agents are one binary; `use` only swaps the config
+                // symlink (the profile), it does not change which binary runs — so say
+                // "profile", not "version", to match what actually happened.
+                if (isSelfUpdatingAgent(agentId)) {
+                    console.log(chalk.green(`Switched ${agentLabel(agentConfig.id)} to config profile ${finalVersion}`) + useEmailStr);
+                }
+                else {
+                    console.log(chalk.green(`Set ${agentLabel(agentConfig.id)}@${finalVersion} as global default`) + useEmailStr);
+                }
             }
         }
         catch (err) {

package/dist/commands/view.js

@@ -7,7 +7,7 @@ import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, } from '../lib/versions.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { resolveVersionFilter, AgentSpecError } from '../lib/agent-spec/index.js';
@@ -358,6 +358,19 @@ async function showInstalledVersions(filterAgentId) {
             profileOnly.push(agentId);
         }
     }
+    // For self-updating global-binary agents (droid) the on-disk version-dir name
+    // is a stale label — the real version is whatever `<cli> --version` reports.
+    // Resolve it once so every row/width pass shows the live version, while the
+    // per-version home + account lookups keep using the real dir name.
+    const liveVersionByAgent = new Map();
+    await Promise.all(versionManaged
+        .filter((agentId) => isGlobalBinaryAgent(agentId))
+        .map(async (agentId) => {
+        const live = await getLiveVersion(agentId);
+        if (live)
+            liveVersionByAgent.set(agentId, live);
+    }));
+    const displayVersion = (agentId, dirVersion) => liveVersionByAgent.get(agentId) ?? dirVersion;
     // Show version-managed agents
     if (versionManaged.length > 0) {
         // Calculate column widths across all agents for alignment
@@ -370,7 +383,8 @@ async function showInstalledVersions(filterAgentId) {
             const versions = listInstalledVersions(agentId);
             const globalDefault = getGlobalDefault(agentId);
             for (const v of versions) {
-                const label = v === globalDefault ? `${v} (default)` : v;
+                const shown = displayVersion(agentId, v);
+                const label = v === globalDefault ? `${shown} (default)` : shown;
                 maxVerLabel = Math.max(maxVerLabel, label.length);
                 const rawInfo = infoMap.get(`${agentId}:${v}`);
                 const info = rawInfo ? mergeCanonical(rawInfo) : undefined;
@@ -423,9 +437,10 @@ async function showInstalledVersions(filterAgentId) {
             });
             for (const version of sortedVersions) {
                 const isDefault = version === globalDefault;
-                const base = isDefault ? `${version} (default)` : version;
+                const shown = displayVersion(agentId, version);
+                const base = isDefault ? `${shown} (default)` : shown;
                 const padded = base.padEnd(maxVerLabel);
-                const label = isDefault ? `${version}${chalk.green(' (default)')}${' '.repeat(maxVerLabel - base.length)}` : padded;
+                const label = isDefault ? `${shown}${chalk.green(' (default)')}${' '.repeat(maxVerLabel - base.length)}` : padded;
                 const rawInfo = infoMap.get(`${agentId}:${version}`);
                 const vInfo = rawInfo ? mergeCanonical(rawInfo) : undefined;
                 const usageKey = getUsageLookupKey(vInfo);

package/dist/lib/agents.d.ts

@@ -34,6 +34,27 @@ export declare function findInPath(command: string): string | null;
 export declare const AGENTS: Record<AgentId, AgentConfig>;
 /** All registered agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
+/**
+ * A self-updating agent is a single global binary installed by an official
+ * `curl … | sh` / `brew install` script that carries NO version token — the
+ * installer can only ever fetch the *current* release, and the binary then keeps
+ * itself up to date in place (droid, grok, antigravity, cursor, hermes, forge,
+ * kiro, goose). There is no semver to pin, so agents-cli must not model these as
+ * having multiple installable version-homes the way it does for npm-packaged
+ * agents (claude, codex, kimi, …).
+ *
+ * The predicate is `!npmPackage && installScript && !installScript.includes('VERSION')`:
+ *   - `npmPackage` empty       → not installed from npm, so `agents add x@1.2.3`
+ *                                can't resolve a registry version.
+ *   - `installScript` present  → it IS installed by a script (not unmanaged).
+ *   - no `VERSION` placeholder → the script has no slot for a pinned version
+ *                                (contrast: an installer templated with `VERSION`
+ *                                could pin, and is NOT self-updating).
+ *
+ * Route every "is this a pinnable, multi-version agent?" decision through here —
+ * never a scattered `agent === 'droid'`.
+ */
+export declare function isSelfUpdatingAgent(agent: AgentId): boolean;
 /** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export declare function colorAgent(agentId: string): (s: string) => string;
 /** Return the agent's display name, colored. */

package/dist/lib/agents.js

@@ -290,7 +290,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: true, commands: true, plugins: true, subagents: false, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['edit', 'skip'] },
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: true, skills: true, commands: true, plugins: true, subagents: false, rules: { file: '.cursorrules' }, workflows: false, memory: false, modes: ['edit', 'skip'] }, // allowlist: ~/.cursor/cli-config.json
     },
     opencode: {
         id: 'opencode',
@@ -310,7 +310,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: { since: '1.1.1' }, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit'] }, // subagents: ~/.config/opencode/agents/*.md
+        capabilities: { hooks: false, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: { since: '1.1.1' }, skills: true, commands: true, plugins: true, subagents: true, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit'] },
     },
     openclaw: {
         id: 'openclaw',
@@ -353,7 +353,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit', 'auto', 'skip'] },
+        capabilities: { hooks: true, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: true, commands: true, plugins: true, subagents: { since: '0.0.353' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -393,7 +393,7 @@ export const AGENTS = {
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: true,
-        capabilities: { hooks: { since: '0.10.0' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['edit'] },
+        capabilities: { hooks: { since: '0.10.0' }, mcp: true, mcpHttp: false, mcpHeaders: false, allowlist: { since: '2.8.0' }, skills: true, commands: true, plugins: false, subagents: { since: '1.23.0' }, rules: { file: 'AGENTS.md' }, workflows: false, memory: false, modes: ['edit'] },
     },
     goose: {
         id: 'goose',
@@ -661,6 +661,30 @@ export const AGENTS = {
 };
 /** All registered agent IDs derived from the AGENTS registry. */
 export const ALL_AGENT_IDS = Object.keys(AGENTS);
+/**
+ * A self-updating agent is a single global binary installed by an official
+ * `curl … | sh` / `brew install` script that carries NO version token — the
+ * installer can only ever fetch the *current* release, and the binary then keeps
+ * itself up to date in place (droid, grok, antigravity, cursor, hermes, forge,
+ * kiro, goose). There is no semver to pin, so agents-cli must not model these as
+ * having multiple installable version-homes the way it does for npm-packaged
+ * agents (claude, codex, kimi, …).
+ *
+ * The predicate is `!npmPackage && installScript && !installScript.includes('VERSION')`:
+ *   - `npmPackage` empty       → not installed from npm, so `agents add x@1.2.3`
+ *                                can't resolve a registry version.
+ *   - `installScript` present  → it IS installed by a script (not unmanaged).
+ *   - no `VERSION` placeholder → the script has no slot for a pinned version
+ *                                (contrast: an installer templated with `VERSION`
+ *                                could pin, and is NOT self-updating).
+ *
+ * Route every "is this a pinnable, multi-version agent?" decision through here —
+ * never a scattered `agent === 'droid'`.
+ */
+export function isSelfUpdatingAgent(agent) {
+    const cfg = AGENTS[agent];
+    return !cfg.npmPackage && !!cfg.installScript && !cfg.installScript.includes('VERSION');
+}
 // Capability-filtered agent lists used to live here as `*_CAPABLE_AGENTS`
 // constants. They were a frequent source of silent-skip bugs (e.g. grok
 // rules sync gated on `COMMANDS_CAPABLE_AGENTS`). Use `capableAgents(cap)`

package/dist/lib/daemon.d.ts

@@ -82,12 +82,12 @@ export declare function readDaemonClaudeOAuthToken(opts?: {
  */
 export declare function writeOwnerOnlyServiceManifest(filePath: string, content: string): void;
 /** Generate a macOS launchd plist for auto-starting the daemon. */
-export declare function generateLaunchdPlist(oauthToken?: string | null): string;
+export declare function generateLaunchdPlist(oauthToken?: string | null, agentsBin?: string): string;
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
-export declare function generateSystemdUnit(oauthToken?: string | null): string;
+export declare function generateSystemdUnit(oauthToken?: string | null, agentsBin?: string): string;
 export declare function getAgentsBinPath(argv1?: string | undefined, execPath?: string): string;
 /** Start the daemon via launchd, systemd, or as a detached process. */
-export declare function startDaemon(): {
+export declare function startDaemon(agentsBin?: string): {
     pid: number | null;
     method: string;
 };
@@ -129,8 +129,8 @@ export declare function buildDetachedDaemonEnv(baseEnv?: NodeJS.ProcessEnv, oaut
  * Going through `process.execPath` means a real PE/binary is spawned with
  * `detached: true` and no console, so nothing signals the daemon after launch.
  *
- * When the entry isn't a JS file (e.g. a native launcher resolved via
- * `which agents`), run it directly — it owns its own runtime resolution.
+ * When the entry isn't a Node script (e.g. a native compiled launcher), run it
+ * directly — it owns its own runtime resolution.
  */
 export declare function getDaemonLaunch(agentsBin?: string): {
     command: string;