@phnx-labs/agents-cli 1.20.56 → 1.20.58

package/CHANGELOG.md

@@ -2,10 +2,35 @@
 
 ## 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`).
+- **The always-on daemon now hosts the secrets broker (socket-first) — one supervised backbone instead of a separate service (#416, step 1).** `runDaemon()` binds the broker via the new `startHostedBroker()` before the scheduler and the heavy browser/session-sync services, so `agents secrets` resolves within ms of daemon start. It serves the same socket + wire protocol as the standalone broker (no `PROTOCOL_VERSION` bump — `agentGetSync`/`agentPing`/`agentAutoLoadSync` are unchanged), but is daemon-safe: no pid-guard, no `process.exit`/signal handlers/self-heal-exit (which would take the daemon down), TTL-eviction only. `ensureAgentRunning()` gains a Path 0 that prefers the daemon and falls back to the standalone `com.phnx-labs.agents-secrets-agent` launchd service, and the daemon only hosts when no broker is already reachable, so a live standalone broker is never orphaned. Retiring the standalone service (a gated `launchctl bootout` migration) and child-spawning the heavy services are the follow-on (#417). Source: `apps/cli/src/lib/secrets/agent.ts` (`startHostedBroker`, `ensureAgentRunning` Path 0, `agentPing` exported), `apps/cli/src/lib/daemon.ts` (`runDaemon` broker host + shutdown).
+- **Clarified `agents secrets list` POLICY column labels.** The column previously mixed policy names, runtime state, and implementation jargon (`daily · 7d left`, `always ask`, `never · NO ACL`). It now uses a consistent `policy · state` form: `daily`, `daily · held 7d`, `always · prompt`, and `never · no prompt`. Source: `apps/cli/src/commands/secrets.ts` (`renderPolicyCol`).
+
 ## 1.20.56
 
 - **Fix native routine schedulers rejecting the published CLI as a Bun virtual path.** Bun's standalone runtime reports the embedded `/$bunfs/root/agents` entry as existing at `process.argv[1]`, while the real physical executable lives at `process.execPath`. Daemon resolution now substitutes that physical executable before generating launchd/systemd manifests or detached launches; the existing virtual-path guard still rejects any virtual path that reaches supervision. Source: `apps/cli/src/lib/daemon.ts`.
-
 - **Fix: `agents teams`, `agents message`, and `agents profiles check` work again on the signed standalone binary (regression from #315).** When `agents` resolves to the bun-compiled Mach-O (shipped since 1.20.53), three self-spawn sites relaunched the CLI as `[process.execPath, process.argv[1], …]` — but under a bun standalone executable `process.argv[1]` is the virtual entry `/$bunfs/root/agents`, so the child died with `unknown command '/$bunfs/root/agents'` (or `/bin/sh: /$bunfs/root/agents: No such file or directory`). Every teammate spawned by a compiled-binary install failed in 0s. New shared `getAgentsInvocation(subArgs)` (`apps/cli/src/lib/daemon.ts`) resolves the real on-disk binary — mapping the `/$bunfs/root/…` virtual path to `process.execPath`, running a `.js` entry under node, and a native binary directly — and `teams/agents.ts`, `commands/message.ts`, and `commands/profiles.ts` route through it. Verified end-to-end: a teammate spawned by the freshly-compiled binary runs to `completed` with no `$bunfs` error. Source: `apps/cli/src/lib/daemon.ts` (`getAgentsInvocation`), `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/commands/{message,profiles}.ts`.
 ## 1.20.55
 

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.d.ts

@@ -66,8 +66,9 @@ export declare function buildSecretsExecEnv(parentEnv: NodeJS.ProcessEnv, secret
  * parse, so multi-line values are rejected rather than silently corrupted.
  */
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
-/** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
- * hint when a `daily` bundle is currently held by the secrets-agent. `held`
+/** The POLICY column for `secrets list`: the prompt policy, plus a concise
+ * state hint. `daily` shows `held Nh` when the secrets-agent is currently
+ * caching the bundle; `always` and `never` show whether they prompt. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
 export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
 /** Register the `agents secrets` command tree. */

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';
@@ -387,17 +387,18 @@ function compactRemaining(expiresAt) {
         return `${hours}h`;
     return `${Math.round(hours / 24)}d`;
 }
-/** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
- * hint when a `daily` bundle is currently held by the secrets-agent. `held`
+/** The POLICY column for `secrets list`: the prompt policy, plus a concise
+ * state hint. `daily` shows `held Nh` when the secrets-agent is currently
+ * caching the bundle; `always` and `never` show whether they prompt. `held`
  * maps bundle name → expiry epoch-ms (from agentStatus()). */
 export function renderPolicyCol(b, held) {
     // `never` is loud on purpose — it's the only tier with no user-presence gate.
     if (bundlePolicy(b) === 'never')
-        return chalk.red.bold('never · NO ACL');
+        return chalk.red.bold('never · no prompt');
     if (bundlePolicy(b) === 'always')
-        return chalk.yellow('always ask');
+        return chalk.yellow('always · prompt');
     const exp = held?.get(b.name);
-    return exp ? chalk.green(`daily · ${compactRemaining(exp)} left`) : chalk.gray('daily');
+    return exp ? chalk.green(`daily · held ${compactRemaining(exp)}`) : chalk.gray('daily');
 }
 /** Below this width the fixed date columns no longer fit; `list` uses cards. */
 const SECRETS_WIDE = 96;
@@ -657,7 +658,7 @@ export function registerSecretsCommands(program) {
             return;
         }
         // Cross-reference the secrets-agent so `daily` bundles that are currently
-        // held can show "· Nh left". Soft-fails to no hint if the broker is down.
+        // held can show "· held Nh". Soft-fails to no hint if the broker is down.
         const held = new Map();
         if (process.platform === 'darwin') {
             try {
@@ -1769,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;
@@ -1829,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;
         }
@@ -1886,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/teams.d.ts

@@ -6,7 +6,26 @@
  * dependencies between teammates, and clean up when work is done.
  */
 import type { Command } from 'commander';
-import { AgentManager } from '../lib/teams/agents.js';
+import { AgentManager, AgentStatus } from '../lib/teams/agents.js';
+/** Where `teams message`/`teams resume` routes a follow-up, by teammate status. */
+export type TeamMessageRoute = {
+    kind: 'steer';
+} | {
+    kind: 'resume';
+} | {
+    kind: 'need-message';
+} | {
+    kind: 'not-started';
+};
+/**
+ * Decide how a follow-up to a teammate is delivered from its reconciled status.
+ * Pure — the source of truth for the routing table, unit-tested without I/O.
+ *   - pending                       -> not-started (tell them to `teams start`)
+ *   - running     + message         -> steer (mailbox)
+ *   - stopped/etc + message         -> resume (re-enter session)
+ *   - any actionable + no message   -> need-message
+ */
+export declare function decideTeamMessageRoute(status: AgentStatus, hasMessage: boolean): TeamMessageRoute;
 /**
  * Register the generic cloud dispatcher — staged cloud teammates get
  * dispatched when their --after deps resolve, using repo/branch stored on

package/dist/commands/teams.js

@@ -3,7 +3,8 @@ import { die, relTime, truncate, isJsonMode, padRight } from '../lib/format.js';
 import * as fs from 'fs/promises';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as path from 'path';
-import { AgentManager, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { AgentManager, AgentStatus, checkCliSignedIn, collectTeamsDoctorData, getAgentsDir, VALID_TASK_TYPES, } from '../lib/teams/agents.js';
+import { mailboxDir, enqueue } from '../lib/mailbox.js';
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { emit } from '../lib/events.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
@@ -126,6 +127,23 @@ function parseTeammate(spec) {
 function shortId(id) {
     return id.slice(0, 8);
 }
+/**
+ * Decide how a follow-up to a teammate is delivered from its reconciled status.
+ * Pure — the source of truth for the routing table, unit-tested without I/O.
+ *   - pending                       -> not-started (tell them to `teams start`)
+ *   - running     + message         -> steer (mailbox)
+ *   - stopped/etc + message         -> resume (re-enter session)
+ *   - any actionable + no message   -> need-message
+ */
+export function decideTeamMessageRoute(status, hasMessage) {
+    if (status === AgentStatus.PENDING)
+        return { kind: 'not-started' };
+    if (!hasMessage)
+        return { kind: 'need-message' };
+    if (status === AgentStatus.RUNNING)
+        return { kind: 'steer' };
+    return { kind: 'resume' };
+}
 /**
  * Preamble injected into every factory worker's prompt. Tells the worker
  * which team + teammate name + task-type it is, and how to file new tasks.
@@ -816,6 +834,12 @@ export function registerTeamsCommands(program) {
       # Delta-poll status without rereading everything
       agents teams status pricing-page --since 2026-04-24T09:00:00-07:00
 
+      # Nudge a teammate that stopped with more to do — resumes its own session
+      agents teams resume pricing-page backend "Review's in — rebase-merge the PR, then release"
+
+      # Steer a still-running teammate mid-flight (delivered at its next tool call)
+      agents teams message pricing-page qa "Skip the flaky screenshot test for now"
+
       # Wind everyone down when shipped
       agents teams disband pricing-page
     `,
@@ -1646,7 +1670,7 @@ export function registerTeamsCommands(program) {
     });
     // stop
     addHostOption(teams.command('stop [team] [teammate]'))
-        .description('Stop a running teammate. Can be restarted later. Cleans up worktree if no uncommitted changes.')
+        .description('Stop a running teammate. Resume it later with `agents teams resume`. Cleans up worktree if no uncommitted changes.')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, ref, opts) => {
         const mgr = mkManager();
@@ -1733,6 +1757,85 @@ export function registerTeamsCommands(program) {
             console.log(chalk.yellow(`Worktree '${agent.worktreeName}' has uncommitted changes. Keeping it at: ${agent.worktreePath}`));
         }
     });
+    // message / resume — send a follow-up message to a teammate. Routes by the
+    // teammate's reconciled status: a RUNNING teammate is STEERED via its mailbox
+    // (delivered at its next tool call); a STOPPED one (completed/failed/stopped)
+    // is RESUMED — re-entering its own session with the message as the next user
+    // turn, re-attaching it to the team as live.
+    async function teamMessageAction(team, ref, message, opts) {
+        const mgr = mkManager();
+        const lookup = await mgr.resolveAgentIdInTask(team, ref);
+        if (lookup.kind === 'none')
+            die(`No teammate matching '${ref}' in team ${team}`, 2);
+        if (lookup.kind === 'ambiguous') {
+            const shorts = lookup.matches.map(shortId).join(', ');
+            die(`'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
+        }
+        const agentId = lookup.agentId;
+        // mgr.get reconciles the teammate's status (PID + start-time guard / remote
+        // .exit sentinel / exit-code reap) before we branch — so running-vs-stopped
+        // is a fact, not a guess.
+        const agent = await mgr.get(agentId);
+        if (!agent)
+            die(`Teammate ${shortId(agentId)} vanished from team ${team}.`);
+        const display = agent.name || shortId(agentId);
+        const status = agent.status;
+        const hasMessage = message != null && message.trim().length > 0;
+        const route = decideTeamMessageRoute(status, hasMessage);
+        switch (route.kind) {
+            case 'not-started':
+                die(`Teammate '${display}' hasn't started yet (waiting on --after deps). Run \`agents teams start ${team}\` to launch it.`);
+                return;
+            case 'need-message':
+                if (status === AgentStatus.RUNNING) {
+                    die(`Teammate '${display}' is running — pass a message to steer it.`);
+                }
+                die(`Teammate '${display}' is ${status} — pass a message to resume it: \`agents teams resume ${team} ${display} "<message>"\`.`);
+                return;
+            case 'steer': {
+                // Running -> steer via mailbox; never re-launch (that forks a 2nd session).
+                enqueue(mailboxDir(agentId), { to: agentId, text: message, from: opts.from });
+                if (isJsonMode(opts)) {
+                    console.log(JSON.stringify({ team, agent_id: agentId, name: agent.name ?? null, action: 'steer', status }, null, 2));
+                    return;
+                }
+                console.log(chalk.green(`Steering ${chalk.cyan(display)} (running) — `) +
+                    chalk.dim('message queued; it will see it at its next tool call.'));
+                return;
+            }
+            case 'resume': {
+                // Stopped / completed / failed -> resume its own session with the message.
+                try {
+                    await mgr.resumeTeammate(agentId, message);
+                }
+                catch (err) {
+                    die(err.message);
+                }
+                if (isJsonMode(opts)) {
+                    console.log(JSON.stringify({ team, agent_id: agentId, name: agent.name ?? null, action: 'resume', prior_status: status }, null, 2));
+                    return;
+                }
+                console.log(chalk.green(`Resuming ${chalk.cyan(display)} `) +
+                    chalk.dim(`(was ${status}) in team ${team} — re-entering its session with your message.`));
+                console.log(chalk.dim(`Track it with \`agents teams status ${team}\`.`));
+                return;
+            }
+        }
+    }
+    addHostOption(teams.command('message <team> <teammate> <message>'))
+        .description('Send a follow-up message to a teammate. A running teammate is steered via its mailbox; a stopped one is resumed — re-entering its own session with the message.')
+        .option('--from <who>', 'Label recorded as the sender of this message')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (team, ref, message, opts) => {
+        await teamMessageAction(team, ref, message, opts);
+    });
+    addHostOption(teams.command('resume <team> <teammate> [message]'))
+        .description("Resume a stopped teammate (completed/failed/stopped) by re-entering its own session with a message as the next user turn. If the teammate is still running, the message is steered via its mailbox instead.")
+        .option('--from <who>', 'Label recorded as the sender of this message')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (team, ref, message, opts) => {
+        await teamMessageAction(team, ref, message, opts);
+    });
     // remove
     teams
         .command('remove [team] [teammate]')

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) {