@phnx-labs/agents-cli 1.20.57 → 1.20.59

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 1.20.59
+
+- **Fix: remote secrets now choose the Windows PowerShell wrapper from the original `--host` name, not the resolved `user@ip` SSH target.** Inline enrolled Windows hosts resolve to address-based SSH targets, but the OS registry is keyed by the host name; `agents secrets view/list/exec --host <windows>`, `agents run --secrets bundle@<windows>`, and remote secrets unlock/export paths now pass that original name into command construction so Windows hosts no longer fall back to `bash -lc`. Source: `apps/cli/src/lib/secrets/remote.ts`, `apps/cli/src/commands/secrets.ts`, `apps/cli/src/commands/exec.ts`. (RUSH-1431)
+- **Wire Droid skills support (RUSH-1397).** Droid loads skills from `.factory/skills/` (since 0.26.0). Flip `skills: { since: '0.26.0' }`, register generic skills writer/detector. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/__tests__/capabilities.test.ts`.
+- **Wire skills support for Goose CLI (RUSH-1394).** Goose reads skills directly from `~/.agents/skills/` via the Summon extension (block-goose-cli >= 1.25.0). Flip `skills: { since: '1.25.0' }`, register generic skills writer/detector. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/staleness/writers/commands.ts`.
+- **Wire Droid allowlist support (RUSH-1396).** Droid stores allow/deny in `.factory/settings.json` (`commandAllowlist`/`commandDenylist`). Flip `allowlist: true` since 0.57.5, add `convertToDroidFormat`, wire writer/detector. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/permissions.ts`.
+- **Wire Codex permissions/allowlist support (RUSH-1566).** Codex stores allow/deny in `.codex/config.toml` (`approval_policy`, `sandbox_mode`). Flip `allowlist: true` since 0.128.0, add `convertToCodexFormat`, wire writer/detector. Source: `apps/cli/src/lib/agents.ts`, `apps/cli/src/lib/permissions.ts`.
+- **OpenCode permissions write to the loaded config path (RUSH-1623).** Global config is `~/.config/opencode/opencode.jsonc` (not `~/.opencode/`); project config is `opencode.jsonc` at the project root. Source: `apps/cli/src/lib/permissions.ts`, `apps/cli/src/lib/agents.ts`.
+- **Catch-up publishes now require the exact CI-tested release tree and its full green matrix.** A package version already present on `main` no longer counts as release validation by itself: `release.sh` resolves the merged `release/v<version>` PR, requires its merge commit to be current `main`, fetches the PR head that ran CI, requires that head tree to equal current `main`, and rechecks every expected CI context before publishing. This closes the path that let 1.20.58 reach npm before its tag-triggered Windows matrix exposed failures. Source: `apps/cli/scripts/release.sh`.
+- **Windows release validation now matches portable path behavior.** Home-relative project paths normalize native separators to `/` before they are stored as `~/…`, and the systemd-manifest and remote-shell assertions now compare the escaped/quoted forms that the runtime deliberately emits. This restores the Windows Node 22/24 release matrix without weakening command escaping. Source: `apps/cli/src/lib/project-root.ts`, `apps/cli/src/lib/{project-root,daemon}.test.ts`, `apps/cli/src/lib/hosts/dispatch.test.ts`.
+## 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,9 +855,10 @@ 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 | >= 1.23.0 | `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 |
+| Droid | yes | yes | yes | >= 0.57.5 | >= 0.26.0 | yes | yes | yes | `AGENTS.md` | no |
 
 **Legend:** `yes` / `no` = synced or skipped at install time. `skills ($name)` = no file-based slash-command dir; behavior ships as a generated skill invoked with `$command`. `gateway` = OpenClaw resolves slash commands at runtime, not from synced files. Version suffixes are enforced at sync time — out-of-range versions are skipped with a clear message.
 
@@ -845,14 +876,19 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 | Grok Build | -- | yes | yes |
 | Antigravity | -- | yes | -- |
 | Copilot | -- | -- | yes |
-| OpenClaw, Amp, Kiro, Goose, Roo | -- | -- | -- |
+| OpenClaw, Amp, Goose, Roo | -- | -- | -- |
+| Kiro | -- | -- | -- |
 
 ### Version-gated sync
 
 | Capability | Agent | Gate |
 |------------|-------|------|
 | Hooks | Codex | >= 0.116.0 |
+| Subagents | Kiro | >= 1.23.0 |
+| Skills | Droid | >= 0.26.0 |
+| Permissions | Droid | >= 0.57.5 |
 | 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,
@@ -1203,7 +1227,7 @@ export function registerRunCommand(program) {
                     // Remote bundle (`bundle@host`): resolve over SSH and inject
                     // ephemerally — values never touch this machine's keychain or disk.
                     const target = await resolveSshTarget(host);
-                    const bundleEnv = await remoteResolveEnv(target, bundleName);
+                    const bundleEnv = await remoteResolveEnv(target, bundleName, { osLookupName: host });
                     console.log(chalk.gray(`[secrets] Resolved ${bundleName}@${host}: ${Object.keys(bundleEnv).length} keys (remote, ephemeral)`));
                     secretsEnv = { ...secretsEnv, ...bundleEnv };
                 }

package/dist/commands/output.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Output command — productivity: token *burn* vs shipped *output*.
+ *
+ * `agents cost` answers "what did we burn?" (dollars + duration). This joins that
+ * burn to what actually shipped — real generated (output) tokens plus PRs and
+ * commits across every git identity — so you can see burn-vs-output and ratios
+ * like $/PR and output-tokens/$. Pure SQLite + local git/gh, no server, no
+ * telemetry — the same offline spirit as `cost`.
+ *
+ * Why not just show `token_count`? Because that number sums cache-read/-write
+ * context re-counted every turn and is dominated by cheap re-reads (often ~100x
+ * the real generation). `output_tokens` (scanned per-agent into the session DB)
+ * is the honest "work produced" signal, and it is what this command leads with.
+ *
+ * `--all-hosts` fans the same rollup across every online device (`ag devices`)
+ * over SSH and merges — one fleet-wide burn-vs-output view.
+ */
+import type { Command } from 'commander';
+export declare function registerOutputCommand(program: Command): void;

package/dist/commands/output.js

@@ -0,0 +1,333 @@
+import chalk from 'chalk';
+import * as os from 'os';
+import * as path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { addHostOption } from '../lib/hosts/option.js';
+import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
+import { queryUsageRollup } from '../lib/session/db.js';
+import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
+import { formatDuration } from '../lib/session/render.js';
+import { terminalWidth, truncateToWidth, padToWidth } from '../lib/session/width.js';
+import { collectGitOutput } from '../lib/output/git-output.js';
+import { loadDevices } from '../lib/devices/registry.js';
+import { machineId } from '../lib/session/sync/config.js';
+const execFileAsync = promisify(execFile);
+export function registerOutputCommand(program) {
+    addHostOption(program.command('output'))
+        .description('Productivity rollup — token burn vs shipped output (PRs, commits) across agents')
+        .option('--json', 'Output the rollup as JSON')
+        .option('--since <time>', 'Only sessions/commits newer than this: 1h, 24h, 7d, 4w, 1mo, 1y, or ISO date (default 7d)')
+        .option('--by <dimension>', 'Group the burn/output breakdown by: agent (default), project, or day')
+        .option('--repos-dir <dir>', 'Root scanned for git repos (default ~/src)')
+        .option('--author <email...>', 'Count commits by these author emails (default: your git identities)')
+        .option('--login <login...>', 'Count PRs for these GitHub logins (default: current gh user)')
+        .option('--no-prs', 'Skip the GitHub PR lookup (commits only)')
+        .option('--all-hosts', 'Aggregate across every online device (ag devices) over SSH')
+        .addHelpText('after', `
+Examples:
+  agents output                       Last 7 days: burn, output tokens, PRs, commits, ratios
+  agents output --since 24h           Last 24 hours
+  agents output --since 1mo           Last month  (units: 1h 24h 7d 4w 1mo 1y, or ISO date)
+  agents output --all-hosts           Fleet-wide, folding in every online machine
+  agents output --by day --json       Machine-readable daily burn/output rollup
+
+Burn (cost) is computed offline from a versioned per-model price table (${PRICING_VERSION}).
+Output tokens are the real generated tokens — NOT the cache-inflated total token count.
+`)
+        .action(async (options) => {
+        await outputAction(options);
+    });
+}
+function resolveGroup(by) {
+    if (by === undefined)
+        return 'agent';
+    if (by === 'agent' || by === 'project' || by === 'day')
+        return by;
+    console.error(chalk.red('error: --by must be one of: agent, project, day'));
+    process.exit(1);
+}
+/** Compact token formatter: 38.6M, 4.1K, 10.6B. */
+function formatCompact(n) {
+    const abs = Math.abs(n);
+    if (abs >= 1e9)
+        return `${(n / 1e9).toFixed(1)}B`;
+    if (abs >= 1e6)
+        return `${(n / 1e6).toFixed(1)}M`;
+    if (abs >= 1e3)
+        return `${(n / 1e3).toFixed(1)}K`;
+    return String(n);
+}
+function emptyBurn() {
+    return { costUsd: 0, outputTokens: 0, tokenCount: 0, sessionCount: 0, durationMs: 0 };
+}
+function sumBurn(rows) {
+    return rows.reduce((acc, r) => {
+        acc.costUsd += r.costUsd;
+        acc.outputTokens += r.outputTokens;
+        acc.tokenCount += r.tokenCount;
+        acc.sessionCount += r.sessionCount;
+        acc.durationMs += r.durationMs;
+        return acc;
+    }, emptyBurn());
+}
+/** Compute this machine's payload from the local session DB + git. */
+async function computeLocalPayload(options, includePrs) {
+    const since = options.since ?? '7d';
+    const sinceMs = parseTimeFilter(since);
+    // Ensure the index is fresh (and migrated to v12 so output_tokens is populated).
+    await discoverSessions({ all: true, since, limit: 1 });
+    const filter = { sinceMs };
+    const groupBy = resolveGroup(options.by);
+    const breakdown = queryUsageRollup({ ...filter, groupBy });
+    const burn = sumBurn(breakdown);
+    const reposDir = options.reposDir ?? path.join(os.homedir(), 'src');
+    const git = await collectGitOutput({
+        reposDir,
+        sinceMs,
+        authors: options.author,
+        logins: options.login,
+        includePrs,
+    });
+    return {
+        machine: machineId(),
+        pricingVersion: PRICING_VERSION,
+        since,
+        burn,
+        output: {
+            commits: git.commits,
+            commitShas: git.commitShas,
+            prsOpened: git.prsOpened,
+            prsMerged: git.prsMerged,
+            reposScanned: git.reposScanned,
+            ghAvailable: git.ghAvailable,
+            authors: git.authors,
+            logins: git.logins,
+        },
+        breakdown: { by: groupBy, rows: breakdown },
+        uncostedAgents: groupBy === 'agent' ? breakdown.filter(r => r.costUsd === 0).map(r => r.key) : [],
+    };
+}
+/** Fetch one remote device's payload by re-invoking `agents output --json --host <name>`. */
+async function fetchRemotePayload(device, options) {
+    const args = ['output', '--json', '--no-prs', '--host', device, '--since', options.since ?? '7d'];
+    if (options.by)
+        args.push('--by', options.by);
+    if (options.reposDir)
+        args.push('--repos-dir', options.reposDir);
+    for (const a of options.author ?? [])
+        args.push('--author', a);
+    try {
+        const { stdout } = await execFileAsync('agents', args, {
+            timeout: 120_000,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        const parsed = JSON.parse(stdout);
+        parsed.machine = parsed.machine || device;
+        return parsed;
+    }
+    catch (err) {
+        return {
+            machine: device,
+            pricingVersion: PRICING_VERSION,
+            since: options.since ?? '7d',
+            burn: emptyBurn(),
+            output: { commits: 0, commitShas: [], prsOpened: 0, prsMerged: 0, reposScanned: 0, ghAvailable: false, authors: [], logins: [] },
+            breakdown: { by: resolveGroup(options.by), rows: [] },
+            uncostedAgents: [],
+            error: (err?.stderr || err?.message || 'unreachable').toString().split('\n')[0].slice(0, 120),
+        };
+    }
+}
+async function outputAction(options) {
+    const includePrs = options.prs !== false;
+    if (!options.allHosts) {
+        const payload = await computeLocalPayload(options, includePrs);
+        if (options.json) {
+            process.stdout.write(JSON.stringify(withRatios(payload, [payload]), null, 2) + '\n');
+            return;
+        }
+        renderSingle(payload);
+        return;
+    }
+    // Fleet: local payload + every online device, folded in over SSH.
+    const self = machineId();
+    const registry = await loadDevices();
+    const remotes = Object.values(registry)
+        .filter(d => d.tailscale?.online && d.name !== self)
+        .map(d => d.name);
+    if (!options.json)
+        console.error(chalk.gray(`Folding in ${remotes.length} online device${remotes.length !== 1 ? 's' : ''}…`));
+    // PRs are global (gh search by author, not machine-bound) — compute once, locally.
+    const local = await computeLocalPayload(options, includePrs);
+    const remotePayloads = await Promise.all(remotes.map(d => fetchRemotePayload(d, options)));
+    const machines = [local, ...remotePayloads];
+    if (options.json) {
+        process.stdout.write(JSON.stringify(withRatios(mergeMachines(machines, options), machines), null, 2) + '\n');
+        return;
+    }
+    renderFleet(machines, options);
+}
+/** Merge per-machine payloads into a combined one (burn + commits summed; PRs local-only). */
+function mergeMachines(machines, options) {
+    const burn = emptyBurn();
+    const byKey = new Map();
+    // Union commit SHAs across machines: shared repos (cloned on several boxes)
+    // expose the same commits to `git log` on each, so summing counts would
+    // multi-count. A commit's SHA is its global identity — union, don't add.
+    const allShas = new Set();
+    const uncosted = new Set();
+    for (const m of machines) {
+        burn.costUsd += m.burn.costUsd;
+        burn.outputTokens += m.burn.outputTokens;
+        burn.tokenCount += m.burn.tokenCount;
+        burn.sessionCount += m.burn.sessionCount;
+        burn.durationMs += m.burn.durationMs;
+        for (const s of m.output.commitShas)
+            allShas.add(s);
+        for (const a of m.uncostedAgents)
+            uncosted.add(a);
+        for (const r of m.breakdown.rows) {
+            const cur = byKey.get(r.key) ?? { key: r.key, costUsd: 0, durationMs: 0, sessionCount: 0, tokenCount: 0, outputTokens: 0 };
+            cur.costUsd += r.costUsd;
+            cur.durationMs += r.durationMs;
+            cur.sessionCount += r.sessionCount;
+            cur.tokenCount += r.tokenCount;
+            cur.outputTokens += r.outputTokens;
+            byKey.set(r.key, cur);
+        }
+    }
+    const rows = [...byKey.values()].sort((a, b) => b.costUsd - a.costUsd);
+    // PRs from the local machine only (machines[0]) — gh search is not machine-scoped.
+    const localGit = machines[0].output;
+    return {
+        machine: 'fleet',
+        pricingVersion: PRICING_VERSION,
+        since: options.since ?? '7d',
+        burn,
+        output: { ...localGit, commits: allShas.size, commitShas: [...allShas] },
+        breakdown: { by: resolveGroup(options.by), rows },
+        uncostedAgents: [...uncosted],
+    };
+}
+/** Attach burn-vs-output ratios to a payload for JSON output. */
+function withRatios(payload, machines) {
+    const prsTotal = payload.output.prsOpened + payload.output.prsMerged;
+    return {
+        ...payload,
+        ratios: {
+            costPerPr: prsTotal > 0 ? payload.burn.costUsd / prsTotal : null,
+            costPerCommit: payload.output.commits > 0 ? payload.burn.costUsd / payload.output.commits : null,
+            outputTokensPerUsd: payload.burn.costUsd > 0 ? payload.burn.outputTokens / payload.burn.costUsd : null,
+        },
+        machines: machines.length > 1 ? machines.map(m => ({ machine: m.machine, burn: m.burn, commits: m.output.commits, error: m.error })) : undefined,
+    };
+}
+/** Shared header line: burned · output tokens · PRs · commits, plus ratios. */
+function headerLines(payload) {
+    const prsTotal = payload.output.prsOpened + payload.output.prsMerged;
+    const out = [];
+    out.push('  ' +
+        `${chalk.green(formatUsd(payload.burn.costUsd))} burned` +
+        chalk.gray('  ·  ') +
+        `${chalk.cyan(formatCompact(payload.burn.outputTokens))} output tokens` +
+        chalk.gray('  ·  ') +
+        `${chalk.yellow(String(prsTotal))} PRs ${chalk.gray(`(${payload.output.prsMerged} merged)`)}` +
+        chalk.gray('  ·  ') +
+        `${chalk.yellow(String(payload.output.commits))} commits`);
+    const ratios = [];
+    if (prsTotal > 0)
+        ratios.push(`${formatUsd(payload.burn.costUsd / prsTotal)}/PR`);
+    if (payload.output.commits > 0)
+        ratios.push(`${formatUsd(payload.burn.costUsd / payload.output.commits)}/commit`);
+    if (payload.burn.costUsd > 0)
+        ratios.push(`${formatCompact(Math.round(payload.burn.outputTokens / payload.burn.costUsd))} out-tok/$`);
+    if (ratios.length > 0)
+        out.push(chalk.gray('  ' + ratios.join('  ·  ')));
+    return out;
+}
+/** Render the per-group burn/output table. */
+function renderBreakdown(rows, groupBy) {
+    const out = [chalk.bold(`By ${groupBy}`)];
+    if (rows.length === 0)
+        return out;
+    const cols = terminalWidth();
+    const burnW = Math.max(...rows.map(r => formatUsd(r.costUsd).length), 4);
+    const outW = Math.max(...rows.map(r => formatCompact(r.outputTokens).length), 6);
+    const sessW = Math.max(...rows.map(r => String(r.sessionCount).length), 3);
+    const fixedW = 2 + 2 + burnW + 2 + outW + 2 + sessW + 8;
+    const keyW = Math.max(8, Math.min(Math.max(...rows.map(r => r.key.length), groupBy.length), cols - fixedW));
+    out.push('  ' + chalk.gray(padToWidth('', keyW)) + '  ' + chalk.gray(padToWidth('burn', burnW)) + '  ' + chalk.gray(padToWidth('output', outW)) + '  ' + chalk.gray('sessions'));
+    for (const r of rows) {
+        out.push('  ' +
+            padToWidth(truncateToWidth(r.key, keyW), keyW) +
+            '  ' +
+            chalk.green(padToWidth(formatUsd(r.costUsd), burnW)) +
+            '  ' +
+            chalk.cyan(padToWidth(formatCompact(r.outputTokens), outW)) +
+            '  ' +
+            chalk.gray(padToWidth(String(r.sessionCount), sessW)));
+    }
+    return out;
+}
+function renderSingle(payload) {
+    const out = [];
+    out.push(chalk.bold('Output') + chalk.gray(`  ·  pricing ${payload.pricingVersion}  ·  since ${payload.since}`));
+    out.push(...headerLines(payload));
+    out.push('');
+    if (payload.burn.sessionCount === 0) {
+        out.push(chalk.gray('No sessions with cost data found. Run `agents sessions --all` to index, then retry.'));
+        console.log(out.join('\n'));
+        return;
+    }
+    out.push(...renderBreakdown(payload.breakdown.rows, payload.breakdown.by));
+    out.push('');
+    out.push(chalk.bold('Shipped'));
+    out.push(`  ${chalk.yellow(String(payload.output.commits))} commits across ${payload.output.reposScanned} repos` + chalk.gray(`  (authors: ${payload.output.authors.length > 0 ? payload.output.authors.join(', ') : 'none detected'})`));
+    if (payload.output.ghAvailable) {
+        out.push(`  ${chalk.yellow(String(payload.output.prsOpened))} PRs opened, ${chalk.yellow(String(payload.output.prsMerged))} merged` + chalk.gray(`  (logins: ${payload.output.logins.join(', ')})`));
+    }
+    else {
+        out.push(chalk.gray('  PRs: gh unavailable or unauthed — not counted'));
+    }
+    out.push('');
+    out.push(chalk.gray(notCountedLine(payload.uncostedAgents)));
+    if (payload.burn.durationMs > 0)
+        out.push(chalk.gray(`agent wall-clock: ${formatDuration(payload.burn.durationMs)}`));
+    console.log(out.join('\n'));
+}
+function renderFleet(machines, options) {
+    const merged = mergeMachines(machines, options);
+    const out = [];
+    out.push(chalk.bold('Output') + chalk.gray(`  ·  fleet (${machines.length} machines)  ·  pricing ${merged.pricingVersion}  ·  since ${merged.since}`));
+    out.push(...headerLines(merged));
+    out.push('');
+    // By machine.
+    out.push(chalk.bold('By machine'));
+    const nameW = Math.max(...machines.map(m => m.machine.length), 7);
+    const burnW = Math.max(...machines.map(m => formatUsd(m.burn.costUsd).length), 4);
+    for (const m of machines) {
+        const note = m.error ? chalk.red(`  (${m.error})`) : '';
+        out.push('  ' +
+            padToWidth(m.machine, nameW) +
+            '  ' +
+            chalk.green(padToWidth(formatUsd(m.burn.costUsd), burnW)) +
+            '  ' +
+            chalk.cyan(padToWidth(formatCompact(m.burn.outputTokens), 7)) +
+            '  ' +
+            chalk.gray(`${m.burn.sessionCount} sessions, ${m.output.commits} commits`) +
+            note);
+    }
+    out.push('');
+    out.push(...renderBreakdown(merged.breakdown.rows, merged.breakdown.by));
+    out.push('');
+    out.push(chalk.gray(notCountedLine(merged.uncostedAgents)));
+    console.log(out.join('\n'));
+}
+function notCountedLine(uncosted) {
+    const notes = [];
+    if (uncosted.length > 0)
+        notes.push(`no price table for: ${[...new Set(uncosted)].join(', ')} (burn undercounts)`);
+    notes.push('cloud runs (Rush/Codex/Factory) not counted');
+    return 'not counted: ' + notes.join('  ·  ');
+}