@phnx-labs/agents-cli 1.20.56 → 1.20.58

package/dist/commands/view.js

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

package/dist/lib/agents.d.ts

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

package/dist/lib/agents.js

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

package/dist/lib/daemon.d.ts

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

package/dist/lib/daemon.js

@@ -306,6 +306,28 @@ export async function runDaemon() {
     catch (err) {
         log('ERROR', `Stray daemon reaper failed: ${err.message}`);
     }
+    // #416: host the secrets broker socket-first — before the scheduler and the
+    // heavy browser/session-sync services — so `agents secrets` resolves within
+    // ms of daemon start. Only host when no broker is already reachable, so we
+    // never orphan a live standalone broker's clients (that broker stays the
+    // server until it idle-exits or the daemon restarts). Best-effort: a failure
+    // here must not stop the daemon. Retiring the standalone launchd service is
+    // the follow-on (#416 step 2 / #417).
+    let hostedBroker = null;
+    try {
+        const { agentPing, startHostedBroker } = await import('./secrets/agent.js');
+        if ((await agentPing()).reachable) {
+            log('INFO', 'Secrets broker already running (standalone); daemon not hosting it');
+        }
+        else {
+            hostedBroker = await startHostedBroker();
+            if (hostedBroker)
+                log('INFO', 'Secrets broker hosted in daemon (socket-first)');
+        }
+    }
+    catch (err) {
+        log('WARN', `Secrets broker host skipped: ${err.message}`);
+    }
     const scheduler = new JobScheduler(async (config) => {
         log('INFO', `Triggering job '${config.name}' (agent: ${config.agent})`);
         try {
@@ -594,6 +616,7 @@ export async function runDaemon() {
         clearTimeout(tmuxReconcileKickoff);
         clearInterval(launchHealthInterval);
         clearTimeout(launchHealthKickoff);
+        hostedBroker?.close();
         removeDaemonPid();
         removeHeartbeat();
         process.exit(0);
@@ -651,8 +674,7 @@ export function writeOwnerOnlyServiceManifest(filePath, content) {
     fs.writeFileSync(filePath, content, { encoding: 'utf-8', mode: 0o600 });
 }
 /** Generate a macOS launchd plist for auto-starting the daemon. */
-export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken()) {
-    const agentsBin = getAgentsBinPath();
+export function generateLaunchdPlist(oauthToken = readDaemonClaudeOAuthToken(), agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const logPath = getLogPath();
     const oauthEntry = oauthToken
@@ -681,7 +703,7 @@ ${[launch.command, ...launch.args].map((arg) => `    <string>${xmlEscape(arg)}</
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin</string>${oauthEntry}
+    <string>${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:${os.homedir()}/.bun/bin</string>${oauthEntry}
   </dict>
 </dict>
 </plist>`;
@@ -691,8 +713,7 @@ function systemdExecArg(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
 /** Generate a Linux systemd user unit for auto-starting the daemon. */
-export function generateSystemdUnit(oauthToken = readDaemonClaudeOAuthToken()) {
-    const agentsBin = getAgentsBinPath();
+export function generateSystemdUnit(oauthToken = readDaemonClaudeOAuthToken(), agentsBin = getAgentsBinPath()) {
     const launch = getDaemonLaunch(agentsBin);
     const execStart = [launch.command, ...launch.args].map(systemdExecArg).join(' ');
     const oauthLine = oauthToken
@@ -707,7 +728,7 @@ Type=simple
 ExecStart=${execStart}
 Restart=always
 RestartSec=10
-Environment=PATH=/usr/local/bin:/usr/bin:/bin:${os.homedir()}/.nvm/versions/node/v24.0.0/bin${oauthLine}
+Environment=PATH=${daemonNodeBinDir()}:/usr/local/bin:/usr/bin:/bin${oauthLine}
 
 [Install]
 WantedBy=default.target`;
@@ -779,7 +800,7 @@ function readServiceManagerPid(platform = os.platform()) {
     return null;
 }
 /** Start the daemon via launchd, systemd, or as a detached process. */
-export function startDaemon() {
+export function startDaemon(agentsBin) {
     if (isDaemonRunning()) {
         const pid = readDaemonPid();
         return { pid, method: 'already-running' };
@@ -791,7 +812,7 @@ export function startDaemon() {
         return { pid, method: 'already-starting' };
     }
     try {
-        return startDaemonLocked();
+        return startDaemonLocked(agentsBin ?? getAgentsBinPath());
     }
     finally {
         releaseLock();
@@ -815,7 +836,7 @@ export function ensureDaemonStarted() {
         return null;
     }
 }
-function startDaemonLocked() {
+function startDaemonLocked(agentsBin) {
     const platform = os.platform();
     if (platform === 'darwin') {
         try {
@@ -826,7 +847,7 @@ function startDaemonLocked() {
             }
             // The plist may embed a long-lived OAuth token in EnvironmentVariables;
             // create owner-only atomically (no world-readable window before chmod).
-            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist());
+            writeOwnerOnlyServiceManifest(plistPath, generateLaunchdPlist(undefined, agentsBin));
             try {
                 execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
@@ -844,7 +865,7 @@ function startDaemonLocked() {
         catch {
             // load threw — fall through to detached spawn
         }
-        return startDetached();
+        return startDetached({ agentsBin });
     }
     if (platform === 'linux') {
         try {
@@ -854,7 +875,7 @@ function startDaemonLocked() {
                 fs.mkdirSync(unitDir, { recursive: true });
             }
             // May embed a long-lived OAuth token in an Environment= line; owner-only.
-            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit());
+            writeOwnerOnlyServiceManifest(unitPath, generateSystemdUnit(undefined, agentsBin));
             execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
             execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });
@@ -867,9 +888,9 @@ function startDaemonLocked() {
         catch {
             // start threw — fall through to detached spawn
         }
-        return startDetached();
+        return startDetached({ agentsBin });
     }
-    return startDetached();
+    return startDetached({ agentsBin });
 }
 /**
  * Environment for the detached daemon fallback. The launchd/systemd paths
@@ -902,18 +923,68 @@ export function buildDetachedDaemonEnv(baseEnv = process.env, oauthToken = readD
  * Going through `process.execPath` means a real PE/binary is spawned with
  * `detached: true` and no console, so nothing signals the daemon after launch.
  *
- * When the entry isn't a JS file (e.g. a native launcher resolved via
- * `which agents`), run it directly — it owns its own runtime resolution.
+ * When the entry isn't a Node script (e.g. a native compiled launcher), run it
+ * directly — it owns its own runtime resolution.
  */
 export function getDaemonLaunch(agentsBin = getAgentsBinPath()) {
     const { warnings } = validateDaemonBinary(agentsBin);
     for (const w of warnings)
         process.stderr.write(`[agents] ${w}\n`);
-    if (/\.(c|m)?js$/.test(agentsBin)) {
+    if (isNodeScriptEntry(agentsBin)) {
         return { command: process.execPath, args: [agentsBin, 'daemon', '_run'] };
     }
     return { command: agentsBin, args: ['daemon', '_run'] };
 }
+/**
+ * A daemon entry must be launched through the Node runtime when it is a Node
+ * script — a `.js`/`.cjs`/`.mjs` file, OR a symlink/extension-less shim whose
+ * shebang names `node`. Package installs link `bin/agents` to a `dist/index.js`
+ * (a symlink) or drop an extension-less `#!/usr/bin/env node` shim, so an
+ * extension check alone misses them and they get run directly. Executing such an
+ * entry then relies on the shebang resolving `node` off the daemon's PATH — and
+ * when that PATH points at a pruned nvm version (or an ancient system node), the
+ * daemon crash-loops at import (`node:util` has no `styleText` on Node 18). A
+ * real compiled binary (Mach-O/ELF/PE) has no `#!node` shebang, so it takes the
+ * direct branch and owns its own runtime resolution.
+ */
+function isNodeScriptEntry(agentsBin) {
+    let resolved = agentsBin;
+    try {
+        resolved = fs.realpathSync(agentsBin);
+    }
+    catch {
+        // Unresolvable (e.g. a template path that does not exist on this box): fall
+        // back to the extension check on the path as given.
+    }
+    if (/\.(c|m)?js$/.test(resolved))
+        return true;
+    try {
+        const fd = fs.openSync(resolved, 'r');
+        try {
+            const buf = Buffer.alloc(128);
+            const n = fs.readSync(fd, buf, 0, 128, 0);
+            const firstLine = buf.toString('utf-8', 0, n).split('\n', 1)[0];
+            return firstLine.startsWith('#!') && /\bnode\b/.test(firstLine);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The directory of the Node runtime that generated this service manifest, kept
+ * first on the daemon's PATH. Both the shim's shebang and any child routine
+ * process then resolve the exact Node that installed the service — never an
+ * ancient system node or a pruned nvm version. Replaces the old hardcoded
+ * `~/.nvm/versions/node/v24.0.0/bin`, which went stale the moment that patch
+ * release was upgraded away and bricked the daemon fleet-wide.
+ */
+function daemonNodeBinDir() {
+    return path.dirname(process.execPath);
+}
 /**
  * Build the argv to relaunch the `agents` CLI with the given subcommand args.
  *

package/dist/lib/git.d.ts

@@ -107,6 +107,15 @@ export declare function isGitRepo(dir: string): boolean;
  * {@link isGitRepo} above). Throws if `dir` is not inside a git repository.
  */
 export declare function getGitRoot(dir: string): Promise<string>;
+/**
+ * Return the absolute path to the **main** working-tree root for `dir`.
+ *
+ * Unlike {@link getGitRoot}, this stays correct when `dir` is inside a *linked*
+ * worktree: `--show-toplevel` there returns the worktree's own path, but the
+ * common git dir (`--git-common-dir`) always points at the primary repo's
+ * `.git`, whose parent is the main checkout. Throws if `dir` is not in a repo.
+ */
+export declare function getMainRepoRoot(dir: string): Promise<string>;
 /**
  * Initialize a git repo in an existing directory.
  */

package/dist/lib/git.js

@@ -427,6 +427,18 @@ export async function getGitRoot(dir) {
     const root = await simpleGit(dir).revparse(['--show-toplevel']);
     return root.trim();
 }
+/**
+ * Return the absolute path to the **main** working-tree root for `dir`.
+ *
+ * Unlike {@link getGitRoot}, this stays correct when `dir` is inside a *linked*
+ * worktree: `--show-toplevel` there returns the worktree's own path, but the
+ * common git dir (`--git-common-dir`) always points at the primary repo's
+ * `.git`, whose parent is the main checkout. Throws if `dir` is not in a repo.
+ */
+export async function getMainRepoRoot(dir) {
+    const common = await simpleGit(dir).raw(['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    return path.dirname(common.trim());
+}
 /**
  * Initialize a git repo in an existing directory.
  */

package/dist/lib/hosts/dispatch.d.ts

@@ -10,11 +10,32 @@
  */
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
+/**
+ * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
+ *
+ * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
+ * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
+ * for that segment — the remote login shell expands it — and shell-quote the
+ * remainder. Any other path (absolute or relative) is quoted verbatim.
+ */
+export declare function remoteCdPrefix(remoteCwd?: string): string;
+/**
+ * Launch a detached login-shell command in its own Unix session/process group.
+ *
+ * Node is already a hard requirement for a host that can run `agents`. Its
+ * `detached: true` contract calls setsid(2) on Unix, unlike `nohup ... &` under
+ * a non-interactive shell where the background wrapper can remain in the SSH
+ * shell's process group. Returning the group leader PID makes `kill(-pid)` a
+ * reliable whole-tree operation for both normal stops and rollback cleanup.
+ */
+export declare function buildDetachedLaunchCommand(inner: string): string;
 export interface DispatchResult {
     task: HostTask;
     /** Exit code when followed; undefined when detached (--no-follow). */
     exitCode?: number;
 }
+/** Terminate a detached dispatch that its caller could not persist locally. */
+export declare function terminateDispatchedTask(task: HostTask): void;
 export interface DispatchOptions {
     agent: string;
     prompt: string;

package/dist/lib/hosts/dispatch.js

@@ -20,6 +20,77 @@ import { followHostTask } from './progress.js';
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
 const REMOTE_DIR = '$HOME/.agents/.cache/hosts';
+/**
+ * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
+ * remainder (no leading slash), else null. Callers that want a local-home
+ * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
+ * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
+ * `--remote-cwd` is left literal and so is never re-rooted here.
+ */
+function homeRemainder(p) {
+    if (p === '~' || p === '$HOME')
+        return '';
+    if (p.startsWith('~/'))
+        return p.slice(2);
+    if (p.startsWith('$HOME/'))
+        return p.slice(6);
+    return null;
+}
+/**
+ * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
+ *
+ * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
+ * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
+ * for that segment — the remote login shell expands it — and shell-quote the
+ * remainder. Any other path (absolute or relative) is quoted verbatim.
+ */
+export function remoteCdPrefix(remoteCwd) {
+    if (!remoteCwd)
+        return '';
+    const rest = homeRemainder(remoteCwd);
+    if (rest === '')
+        return 'cd "$HOME" && ';
+    if (rest !== null)
+        return `cd "$HOME"/${shellQuote(rest)} && `;
+    return `cd ${shellQuote(remoteCwd)} && `;
+}
+/**
+ * Launch a detached login-shell command in its own Unix session/process group.
+ *
+ * Node is already a hard requirement for a host that can run `agents`. Its
+ * `detached: true` contract calls setsid(2) on Unix, unlike `nohup ... &` under
+ * a non-interactive shell where the background wrapper can remain in the SSH
+ * shell's process group. Returning the group leader PID makes `kill(-pid)` a
+ * reliable whole-tree operation for both normal stops and rollback cleanup.
+ */
+export function buildDetachedLaunchCommand(inner) {
+    const nodeScript = [
+        "const { spawn } = require('node:child_process');",
+        `const child = spawn('/bin/bash', ['-lc', ${JSON.stringify(inner)}], { detached: true, stdio: 'ignore' });`,
+        "child.once('error', error => { console.error(error.message); process.exitCode = 1; });",
+        "child.once('spawn', () => { console.log(child.pid); child.unref(); });",
+    ].join(' ');
+    return `bash -lc ${shellQuote(`node -e ${shellQuote(nodeScript)}`)}`;
+}
+function terminateRemoteLaunch(task) {
+    if (!task.pid)
+        throw new Error(`Cannot terminate remote task ${task.id}: launch returned no PID.`);
+    const pid = task.pid;
+    const command = `if kill -TERM -- -${pid} 2>/dev/null; then ` +
+        `sleep 1; kill -KILL -- -${pid} 2>/dev/null || true; ` +
+        `elif kill -0 -- -${pid} 2>/dev/null; then exit 1; fi; ` +
+        `rm -f ${task.remoteLog} ${task.remoteExit}`;
+    const result = sshExec(task.target, command, { timeoutMs: 10000, multiplex: true });
+    if (result.code !== 0) {
+        throw new Error(`Failed to terminate remote task ${task.id} on ${task.host}: ` +
+            `${(result.stderr || result.stdout).trim() || 'ssh error'}`);
+    }
+}
+/** Terminate a detached dispatch that its caller could not persist locally. */
+export function terminateDispatchedTask(task) {
+    terminateRemoteLaunch(task);
+    updateTask(task.id, terminalPatch(143));
+}
 /**
  * The launch + task-record + optional follow core. Both `dispatchToHost` (run)
  * and `dispatchAgentsCommand` (teams) build their `forwardedArgs` and call here,
@@ -45,10 +116,11 @@ async function launchDetached(host, target, opts) {
     const remoteExit = `${REMOTE_DIR}/${id}.exit`;
     // Inner command run under a login shell so PATH resolves `agents`.
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
-    const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
+    const cwd = remoteCdPrefix(opts.remoteCwd);
     const inner = `${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
-    // Outer: ensure dir, launch detached under bash -lc, print the PID.
-    const launch = `mkdir -p ${REMOTE_DIR}; nohup bash -lc ${shellQuote(inner)} >/dev/null 2>&1 & echo $!`;
+    // Outer: ensure dir, launch the login-shell wrapper as a new process-group
+    // leader, and print that leader PID.
+    const launch = `mkdir -p ${REMOTE_DIR}; ${buildDetachedLaunchCommand(inner)}`;
     const res = sshExec(target, launch, { timeoutMs: 30000, multiplex: true });
     if (res.code !== 0) {
         throw new Error(`Failed to launch on "${host.name}": ${(res.stderr || res.stdout).trim() || 'ssh error'}`);
@@ -68,7 +140,18 @@ async function launchDetached(host, target, opts) {
         status: 'running',
         createdAt: new Date().toISOString(),
     };
-    saveTask(task);
+    try {
+        saveTask(task);
+    }
+    catch (err) {
+        try {
+            terminateRemoteLaunch(task);
+        }
+        catch (cleanupErr) {
+            throw new Error(`Failed to persist remote task ${task.id}; cleanup also failed: ${cleanupErr.message}`, { cause: err });
+        }
+        throw err;
+    }
     if (opts.follow === false) {
         return { task };
     }
@@ -146,7 +229,7 @@ export async function runInteractiveOnHost(host, opts) {
     for (const w of warnings)
         process.stderr.write(`[hosts] warning: ${w}\n`);
     const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
-    const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
+    const cwd = remoteCdPrefix(opts.remoteCwd);
     const remoteCmd = `${cwd}${invocation}`;
     return sshStream(target, remoteCmd, { tty: process.stdin.isTTY, multiplex: true });
 }

package/dist/lib/permissions.d.ts

@@ -1,4 +1,4 @@
-import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, OpenCodePermissions, CodexPermissions } from './types.js';
+import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, CursorPermissions, OpenCodePermissions, CodexPermissions } from './types.js';
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
 export type ParsedRules = PermissionSet;
@@ -99,6 +99,11 @@ export declare function removePermissionSet(name: string): {
  * Claude uses: { permissions: { allow: ["Bash(*)", "Read(**)"], deny: [] } }
  */
 export declare function convertToClaudeFormat(set: PermissionSet): ClaudePermissions;
+/**
+ * Convert canonical permission set to Cursor CLI format
+ * (`~/.cursor/cli-config.json` permissions.allow/deny).
+ */
+export declare function convertToCursorFormat(set: PermissionSet): CursorPermissions;
 /**
  * Convert canonical permission set to Gemini format.
  * Gemini reads tool allow-lists from settings.json under `tools.allowed`.
@@ -152,6 +157,19 @@ export type KimiRule = {
     decision: 'allow' | 'deny';
     pattern: string;
 };
+export type KiroRule = {
+    capability: string;
+    effect: 'allow' | 'deny';
+    match?: string[];
+    exclude?: string[];
+};
+/**
+ * Convert canonical permissions to Kiro CLI v3 capability rules.
+ * Kiro stores these rules in ~/.kiro/settings/permissions.yaml.
+ */
+export declare function convertToKiroFormat(set: PermissionSet): {
+    rules: KiroRule[];
+};
 /**
  * Convert a canonical permission set to Kimi Code's `[permission].rules` format.
  * Kimi (`~/.kimi-code/config.toml`) reads rules of the form