@phnx-labs/agents-cli 1.20.78 → 1.20.83

package/dist/lib/hooks.js

@@ -13,9 +13,8 @@ import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import * as TOML from 'smol-toml';
-import { AGENTS, agentConfigDirName } from './agents.js';
+import { AGENTS, agentConfigDirName, isAgentHardDeprecated } from './agents.js';
 import { supports, explainSkip, capableAgents } from './capabilities.js';
-import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 import { getHooksDir as getSystemHooksDir, getUserHooksDir, getUserAgentsDir, getSystemAgentsDir, getProjectAgentsDir, getTrashHooksDir, getEnabledExtraRepos, getResolvedRulesDir, getUserRulesDir } from './state.js';
 import { collectSubruleHooksFromState } from './rules/compose.js';
 function getCentralHooksDir() { return getUserHooksDir(); }
@@ -147,9 +146,113 @@ function isStaleSiblingVersionCommand(command, current) {
     const id = versionHomeIdentity(command);
     return id !== null && id.agent === current.agent && id.version !== current.version;
 }
-import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
-import { generateHookShim, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
+function hookResourceName(command) {
+    const withoutArgs = command.trim().split(/\s+/)[0];
+    return path.basename(withoutArgs).replace(/\.[^.]+$/, '');
+}
+/**
+ * Collapse version-scoped registrations by logical resource identity rather
+ * than absolute command path. When the same resource is present in several
+ * homes, the active home's command wins even if it appears later. Commands
+ * outside version homes are user-owned and remain untouched.
+ */
+export function deduplicateVersionHookCommands(commands, activeVersionHome) {
+    const active = versionHomeIdentity(activeVersionHome);
+    if (!active)
+        return [...commands];
+    const selected = new Map();
+    const passthrough = [];
+    for (const command of commands) {
+        const identity = versionHomeIdentity(command);
+        if (!identity || identity.agent !== active.agent) {
+            passthrough.push(command);
+            continue;
+        }
+        const key = `${identity.agent}\0${hookResourceName(command)}`;
+        const candidateIsActive = identity.version === active.version;
+        const prior = selected.get(key);
+        if (!prior || (!prior.active && candidateIsActive)) {
+            selected.set(key, { command, active: candidateIsActive });
+        }
+    }
+    return [...passthrough, ...Array.from(selected.values(), ({ command }) => command)];
+}
+/**
+ * Collapse a matcher group's hook entries down to the deduplicated command
+ * multiset {@link deduplicateVersionHookCommands} returns, preserving order and
+ * the concrete entry objects. The deduped list is honored as a per-command
+ * budget, NOT a membership set: two identical active-version entries collapse to
+ * one because the budget for that command is one. (A membership `Set.has` test
+ * would keep both — the bug this replaces.) Passthrough (user / non-version-home)
+ * commands keep their original multiplicity, so genuine user hooks are untouched.
+ */
+function collapseVersionHookEntries(entries, activeVersionHome) {
+    const budget = new Map();
+    for (const command of deduplicateVersionHookCommands(entries.map((e) => e.command), activeVersionHome)) {
+        budget.set(command, (budget.get(command) ?? 0) + 1);
+    }
+    return entries.filter((e) => {
+        const remaining = budget.get(e.command) ?? 0;
+        if (remaining <= 0)
+            return false;
+        budget.set(e.command, remaining - 1);
+        return true;
+    });
+}
+import { getEffectiveHome, getVersionHomePath, listInstalledVersions, resolveVersion } from './versions.js';
+import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
+function hookContentHash(scriptPath) {
+    return crypto.createHash('sha256').update(fs.readFileSync(scriptPath)).digest('hex');
+}
+/**
+ * Inspect every installed hooks-capable harness without assuming a native
+ * settings format. Same-name copies with one content hash are installation
+ * noise; multiple hashes are drift. The active version is always selected as
+ * the authoritative copy when it participates in the group.
+ */
+export function inspectDuplicateVersionHooks(cwd = process.cwd()) {
+    const byResource = new Map();
+    for (const { agent, version } of iterHooksCapableVersions()) {
+        const activeVersion = resolveVersion(agent, cwd);
+        for (const entry of listHooksInVersionHome(agent, version)) {
+            let hash;
+            try {
+                hash = hookContentHash(entry.scriptPath);
+            }
+            catch {
+                continue;
+            }
+            const copy = {
+                agent,
+                version,
+                name: entry.name,
+                path: entry.scriptPath,
+                hash,
+                active: version === activeVersion,
+            };
+            const key = `${agent}\0${entry.name}`;
+            const copies = byResource.get(key) ?? [];
+            copies.push(copy);
+            byResource.set(key, copies);
+        }
+    }
+    const findings = [];
+    for (const copies of byResource.values()) {
+        if (copies.length < 2)
+            continue;
+        copies.sort((a, b) => a.version.localeCompare(b.version, undefined, { numeric: true }));
+        const authoritative = copies.find((copy) => copy.active) ?? copies[copies.length - 1];
+        findings.push({
+            agent: authoritative.agent,
+            name: authoritative.name,
+            kind: new Set(copies.map((copy) => copy.hash)).size === 1 ? 'duplicate' : 'drift',
+            authoritative,
+            copies,
+        });
+    }
+    return findings.sort((a, b) => `${a.agent}/${a.name}`.localeCompare(`${b.agent}/${b.name}`));
+}
 /**
  * Resolve the command path to register for a hook.
  *
@@ -488,6 +591,130 @@ export function getVersionHooksDir(agent, version) {
 export function listHooksInVersionHome(agent, version) {
     return listHookEntriesFromDir(getVersionHooksDir(agent, version));
 }
+// ─── wiring inspection (settings.json family: claude, droid) ──────────────────
+/**
+ * Agents whose hooks register through {@link registerHooksForClaude} — a native
+ * settings.json shaped `hooks[event] = [{ matcher, hooks: [{ command }] }]`, with
+ * no event renaming. These are the only agents this read-only wiring inspector
+ * understands; every other harness uses a divergent config format and/or event
+ * map (Gemini/Antigravity settings.json variants, Codex config.toml, the OpenCode
+ * plugin, …), so it reports them unsupported rather than risk a false verdict.
+ */
+const SETTINGS_JSON_HOOK_FAMILY = ['claude', 'droid'];
+/**
+ * Verify that every hook the manifest says should be wired for a (claude|droid)
+ * version is actually REFERENCED in that version's native settings.json — not
+ * merely present as a file on disk.
+ *
+ * `agents doctor` compares hook FILES against source (see diffHooks in
+ * doctor-diff.ts) but never checks the wiring, so a hook whose script is
+ * byte-identical to source yet missing from settings.json's PreToolUse/Stop/…
+ * array reads as "ok" while it never fires. This closes that blind spot.
+ *
+ * Read-only by construction: it mirrors registerHooksForClaude's command
+ * resolution WITHOUT the shim-generation / chmod side effects that
+ * resolveHookCommand performs, so it never mutates the version home.
+ */
+export function checkVersionHookWiring(agent, version) {
+    if (!AGENTS[agent].supportsHooks || !SETTINGS_JSON_HOOK_FAMILY.includes(agent)) {
+        return { supported: false, unwired: [] };
+    }
+    const versionHome = getVersionHomePath(agent, version);
+    const settingsPath = path.join(versionHome, agentConfigDirName(agent), 'settings.json');
+    const localHooksDir = getVersionHooksDir(agent, version);
+    // Resolve ONLY to a script that was actually synced for THIS agent+version: the
+    // copy in the version home hooks dir, or an absolute subrule-dir path (those are
+    // registered in place, never copied). Deliberately NO central-source fallback —
+    // sync wires `selectHookManifest(parseHookManifest(), hooksToSync)` where
+    // hooksToSync is the per-agent selected set (versions.ts), so a hook the manifest
+    // declares but that was never synced into THIS version home (e.g. a claude-scoped
+    // hook viewed for droid) must not be expected here. A missing-but-declared hook
+    // is a FILE gap that diffHooks reports as `missing`, not a wiring gap.
+    // No ensureExecutable — that chmods, and this path must not touch disk.
+    const resolveScript = (script) => {
+        if (path.isAbsolute(script) && fs.existsSync(script))
+            return script;
+        return resolveContainedHookPath(localHooksDir, script);
+    };
+    // Read-only mirror of resolveHookCommand — same command string, no shim write.
+    const expectedCommand = (name, hookDef) => {
+        const scriptPath = resolveScript(hookDef.script);
+        if (!scriptPath)
+            return null;
+        if (!isValidHookShimName(name))
+            return null;
+        const cache = parseCacheConfig(hookDef.cache);
+        const hasMatches = hookDef.matches != null && Object.keys(hookDef.matches).length > 0;
+        if (!cache && !hasMatches)
+            return toPortableCommand(scriptPath);
+        return toPortableCommand(getHookShimPath(name));
+    };
+    const manifest = parseHookManifest({ warn: false });
+    const expected = [];
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const command = expectedCommand(name, hookDef);
+        if (!command)
+            continue; // script unresolved — a file gap, reported by diffHooks
+        // Mirror registerHooksForClaude: a hook registers under the matcher group
+        // `hookDef.matcher || ''` for each of its events.
+        const matcher = hookDef.matcher || '';
+        for (const event of hookDef.events)
+            expected.push({ name, event, matcher, command });
+    }
+    if (!fs.existsSync(settingsPath)) {
+        return {
+            supported: true,
+            settingsPath,
+            expected: expected.length,
+            settingsMissing: expected.length > 0,
+            unwired: [],
+        };
+    }
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        return {
+            supported: true,
+            settingsPath,
+            expected: expected.length,
+            settingsUnparseable: true,
+            unwired: [],
+        };
+    }
+    // Command strings actually referenced, keyed by (event, matcher) — a hook wired
+    // under the WRONG matcher group must NOT read as wired, so scope by matcher and
+    // not just by event.
+    const wiredByGroup = new Map();
+    const groupKey = (event, matcher) => `${event}\n${matcher}`;
+    const hooks = config.hooks && typeof config.hooks === 'object'
+        ? config.hooks
+        : {};
+    for (const [event, groups] of Object.entries(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!group || !Array.isArray(group.hooks))
+                continue;
+            const matcher = typeof group.matcher === 'string' ? group.matcher : '';
+            const key = groupKey(event, matcher);
+            let cmds = wiredByGroup.get(key);
+            if (!cmds) {
+                cmds = new Set();
+                wiredByGroup.set(key, cmds);
+            }
+            for (const h of group.hooks) {
+                if (h && typeof h.command === 'string')
+                    cmds.add(h.command);
+            }
+        }
+    }
+    const unwired = expected.filter((e) => !wiredByGroup.get(groupKey(e.event, e.matcher))?.has(e.command));
+    return { supported: true, settingsPath, expected: expected.length, unwired };
+}
 /**
  * Check if a hook installed in a specific version matches central content.
  */
@@ -936,6 +1163,9 @@ function sweepOrphanShims(manifest) {
     }
 }
 export function registerHooksToSettings(agentId, versionHome, hookManifest, agentsDirOverride) {
+    if (isAgentHardDeprecated(agentId)) {
+        return { registered: [], errors: [] };
+    }
     const manifest = hookManifest || parseHookManifest();
     if (Object.keys(manifest).length === 0) {
         if (agentId === 'opencode') {
@@ -995,9 +1225,6 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'codex') {
         return registerHooksForCodex(versionHome, manifest, resolveScript, managedPrefixes);
     }
-    if (agentId === 'gemini') {
-        return registerHooksForGemini(versionHome, manifest, resolveScript, managedPrefixes);
-    }
     if (agentId === 'antigravity') {
         return registerHooksForAntigravity(versionHome, manifest, resolveScript, managedPrefixes);
     }
@@ -1183,16 +1410,6 @@ const ANTIGRAVITY_EVENT_MAP = {
     Stop: 'on_loop_stop',
     OnError: 'on_error',
 };
-/**
- * Gemini has no native UserPromptSubmit event — map it to BeforeAgent,
- * the closest lifecycle phase that fires before the model sees the prompt.
- * Note: gemini's BeforeAgent can only APPEND via additionalContext — it
- * cannot replace the prompt. The hook script branches on caller to emit
- * the correct protocol.
- */
-const GEMINI_EVENT_MAP = {
-    UserPromptSubmit: 'BeforeAgent',
-};
 function registerHooksForClaude(versionHome, manifest, resolveScript, managedPrefixes, configDirName = '.claude') {
     const registered = [];
     const errors = [];
@@ -1238,8 +1455,9 @@ function registerHooksForClaude(versionHome, manifest, resolveScript, managedPre
         for (const group of eventEntries) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
                 !isStaleSiblingVersionCommand(h.command, currentVh));
+            group.hooks = collapseVersionHookEntries(managed, versionHome);
         }
     }
     // Remove empty matcher groups left after cleanup
@@ -1387,12 +1605,18 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
         if (resolved)
             currentManifestPaths.add(resolved);
     }
+    // Identity of the version home being synced. Codex stores hooks in a shared
+    // hooks.json per CODEX_HOME, but agents-cli registers version-scoped command
+    // paths; without this, old version entries keep firing after upgrades.
+    const currentVh = versionHomeIdentity(versionHome);
     // Remove stale entries from all event groups
     for (const eventGroups of Object.values(hooksFile.hooks)) {
         for (const group of eventGroups) {
             if (!group.hooks)
                 continue;
-            group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
+            const managed = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+                !isStaleSiblingVersionCommand(h.command, currentVh));
+            group.hooks = collapseVersionHookEntries(managed, versionHome);
         }
     }
     for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
@@ -1436,7 +1660,8 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
                 group.hooks = [];
             }
             const existingIdx = group.hooks.findIndex((h) => h.command === commandPath);
-            const hookEntry = { type: 'command', command: commandPath, timeout };
+            const eventTimeout = event === 'SessionEnd' ? Math.min(timeout, 3) : timeout;
+            const hookEntry = { type: 'command', command: commandPath, timeout: eventTimeout };
             if (existingIdx >= 0) {
                 group.hooks[existingIdx] = hookEntry;
             }
@@ -1529,81 +1754,6 @@ function registerHooksForCodex(versionHome, manifest, resolveScript, managedPref
     }
     return { registered, errors };
 }
-function registerHooksForGemini(versionHome, manifest, resolveScript, managedPrefixes) {
-    const registered = [];
-    const errors = [];
-    const settingsPath = path.join(versionHome, '.gemini', 'settings.json');
-    try {
-        updateGeminiSettings(settingsPath, (config) => {
-            setGeminiAutoUpdateDisabled(config);
-            if (!config.hooks || typeof config.hooks !== 'object') {
-                config.hooks = {};
-            }
-            const hooks = config.hooks;
-            const currentManifestPaths = new Set();
-            for (const [hookName, hookDef] of Object.entries(manifest)) {
-                if (!hookDef.events || hookDef.events.length === 0)
-                    continue;
-                const resolved = resolveHookCommand(hookName, hookDef, resolveScript);
-                if (resolved)
-                    currentManifestPaths.add(resolved);
-            }
-            for (const eventEntries of Object.values(hooks)) {
-                if (!Array.isArray(eventEntries))
-                    continue;
-                for (const group of eventEntries) {
-                    if (!group.hooks)
-                        continue;
-                    group.hooks = group.hooks.filter((h) => !isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command));
-                }
-            }
-            for (const [event, eventEntries] of Object.entries(hooks)) {
-                if (!Array.isArray(eventEntries))
-                    continue;
-                hooks[event] = eventEntries.filter((g) => g.hooks && g.hooks.length > 0);
-            }
-            for (const [name, hookDef] of Object.entries(manifest)) {
-                if (!hookDef.events || hookDef.events.length === 0)
-                    continue;
-                const commandPath = resolveHookCommand(name, hookDef, resolveScript);
-                if (!commandPath) {
-                    errors.push(`${name}: script not found in user or system hooks dir`);
-                    continue;
-                }
-                const timeoutMs = (hookDef.timeout || 600) * 1000;
-                for (const event of hookDef.events) {
-                    const geminiEvent = GEMINI_EVENT_MAP[event] ?? event;
-                    if (!hooks[geminiEvent]) {
-                        hooks[geminiEvent] = [];
-                    }
-                    const eventEntries = hooks[geminiEvent];
-                    const matcher = hookDef.matcher || '';
-                    let matcherGroup = eventEntries.find((e) => (e.matcher || '') === matcher);
-                    if (!matcherGroup) {
-                        matcherGroup = { matcher, hooks: [] };
-                        eventEntries.push(matcherGroup);
-                    }
-                    if (!matcherGroup.hooks) {
-                        matcherGroup.hooks = [];
-                    }
-                    const existingIdx = matcherGroup.hooks.findIndex((h) => h.command === commandPath);
-                    const hookEntry = { name, type: 'command', command: commandPath, timeout: timeoutMs };
-                    if (existingIdx >= 0) {
-                        matcherGroup.hooks[existingIdx] = hookEntry;
-                    }
-                    else {
-                        matcherGroup.hooks.push(hookEntry);
-                    }
-                    registered.push(`${name} -> ${geminiEvent}`);
-                }
-            }
-        });
-    }
-    catch (err) {
-        errors.push(`Failed to write gemini settings.json: ${err.message}`);
-    }
-    return { registered, errors };
-}
 /**
  * Register hooks into antigravity's (agy) settings.json. Unlike gemini, agy uses
  * a flat per-event array of `{ command }` entries (no matcher groups). Events

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

@@ -11,6 +11,18 @@
 import type { Host } from './types.js';
 import { type HostTask } from './tasks.js';
 import { type HostCredentials } from './credentials.js';
+/**
+ * Derive the remote directory to mirror from the local cwd, for a host run the
+ * caller gave no `--cwd`/`--remote-cwd`.
+ *
+ * Without this a `--host` run lands in the remote `$HOME`, so an agent launched
+ * from a repo starts with no project context and the user has to `cd` by hand.
+ * Only a cwd under the LOCAL home is mirrored — that is the part with a
+ * meaningful remote analogue (`~/src/x` re-roots onto the remote home). A path
+ * outside home returns undefined: `/opt/thing` on this box says nothing about
+ * the target's filesystem, so the run keeps the remote home.
+ */
+export declare function deriveMirroredCwd(localCwd: string): string | undefined;
 /**
  * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
  *
@@ -18,8 +30,19 @@ import { type HostCredentials } from './credentials.js';
  * 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.
+ *
+ * `mirror` marks a directory the caller DERIVED from the local cwd rather than
+ * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
+ * the same home-relative path on both boxes is the common fleet layout, so
+ * mirroring lands the remote agent in the project instead of `$HOME`. It is a
+ * best-effort mirror by definition — the host may simply not have that checkout
+ * — so a missing directory falls back to the remote home instead of failing the
+ * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
+ * directory, so a missing one must surface as a `cd` error.
  */
-export declare function remoteCdPrefix(remoteCwd?: string): string;
+export declare function remoteCdPrefix(remoteCwd?: string, opts?: {
+    mirror?: boolean;
+}): string;
 /**
  * Merge the resolved actor's provenance env UNDER a caller-supplied env, so every
  * remote `agents …` invocation forwards `AGENTS_ACTOR*` / `GIT_*` across the SSH
@@ -103,6 +126,8 @@ export interface DispatchOptions {
     /** Native-CLI passthrough (everything after `--`), appended last. */
     passthroughArgs?: string[];
     remoteCwd?: string;
+    /** `remoteCwd` was derived from the local cwd — mirror it, don't fail on it. */
+    mirrorCwd?: boolean;
     /**
      * Force the remote run's NEW session to use this exact id (Claude only, via
      * `agents run --session-id`). Captured on the task record so the run is
@@ -165,6 +190,8 @@ export interface InteractiveDispatchOptions {
     /** Route through the Agent Client Protocol. */
     acp?: boolean;
     remoteCwd?: string;
+    /** `remoteCwd` was derived from the local cwd — mirror it, don't fail on it. */
+    mirrorCwd?: boolean;
     sessionId?: string;
     name?: string;
     resume?: string;

package/dist/lib/hosts/dispatch.js

@@ -19,6 +19,7 @@ import { saveTask, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { wrapHostCommandWithCredentials } from './credentials.js';
 import { hostKeyCheckingOpts } from '../devices/known-hosts.js';
+import { toRemotePortable } from '../project-root.js';
 // Use $HOME (not ~) so the path is correct whether or not it's quoted and
 // regardless of the run's cwd. Task ids are 8 hex chars, so these paths are
 // injection-safe to interpolate unquoted into remote commands.
@@ -39,6 +40,21 @@ function homeRemainder(p) {
         return p.slice(6);
     return null;
 }
+/**
+ * Derive the remote directory to mirror from the local cwd, for a host run the
+ * caller gave no `--cwd`/`--remote-cwd`.
+ *
+ * Without this a `--host` run lands in the remote `$HOME`, so an agent launched
+ * from a repo starts with no project context and the user has to `cd` by hand.
+ * Only a cwd under the LOCAL home is mirrored — that is the part with a
+ * meaningful remote analogue (`~/src/x` re-roots onto the remote home). A path
+ * outside home returns undefined: `/opt/thing` on this box says nothing about
+ * the target's filesystem, so the run keeps the remote home.
+ */
+export function deriveMirroredCwd(localCwd) {
+    const portable = toRemotePortable(localCwd);
+    return homeRemainder(portable) === null ? undefined : portable;
+}
 /**
  * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
  *
@@ -46,15 +62,26 @@ function homeRemainder(p) {
  * 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.
+ *
+ * `mirror` marks a directory the caller DERIVED from the local cwd rather than
+ * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
+ * the same home-relative path on both boxes is the common fleet layout, so
+ * mirroring lands the remote agent in the project instead of `$HOME`. It is a
+ * best-effort mirror by definition — the host may simply not have that checkout
+ * — so a missing directory falls back to the remote home instead of failing the
+ * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
+ * directory, so a missing one must surface as a `cd` error.
  */
-export function remoteCdPrefix(remoteCwd) {
+export function remoteCdPrefix(remoteCwd, opts = {}) {
     if (!remoteCwd)
         return '';
     const rest = homeRemainder(remoteCwd);
     if (rest === '')
         return 'cd "$HOME" && ';
-    if (rest !== null)
-        return `cd "$HOME"/${shellQuote(rest)} && `;
+    if (rest !== null) {
+        const dir = `"$HOME"/${shellQuote(rest)}`;
+        return opts.mirror ? `{ cd ${dir} || cd "$HOME"; } && ` : `cd ${dir} && `;
+    }
     return `cd ${shellQuote(remoteCwd)} && `;
 }
 /**
@@ -190,7 +217,7 @@ async function launchDetached(host, target, opts) {
     // resolved actor provenance first so the detached remote run inherits it
     // instead of re-resolving from this box's SSH_CONNECTION (RUSH-2028).
     const invocation = ['agents', ...opts.forwardedArgs].map(shellQuote).join(' ');
-    const cwd = remoteCdPrefix(opts.remoteCwd);
+    const cwd = remoteCdPrefix(opts.remoteCwd, { mirror: opts.mirrorCwd });
     const actorExports = posixEnvExports(withActorEnv());
     const prelude = actorExports ? `${actorExports}; ` : '';
     let inner = `${prelude}${cwd}${invocation} > ${remoteLog} 2>&1; echo $? > ${remoteExit}`;
@@ -385,7 +412,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 = remoteCdPrefix(opts.remoteCwd);
+    const cwd = remoteCdPrefix(opts.remoteCwd, { mirror: opts.mirrorCwd });
     // Forward actor provenance so the interactive remote run inherits it rather
     // than re-resolving from this box's SSH_CONNECTION (RUSH-2028).
     const actorExports = posixEnvExports(withActorEnv());
@@ -413,6 +440,7 @@ export async function dispatchToHost(host, opts) {
     return launchDetached(host, target, {
         forwardedArgs: buildRunForwardedArgs(opts),
         remoteCwd: opts.remoteCwd,
+        mirrorCwd: opts.mirrorCwd,
         follow: opts.follow,
         timeoutMs: opts.timeoutMs,
         agentLabel: opts.agent,

package/dist/lib/hosts/option.js

@@ -12,8 +12,8 @@
 /** Attach the standard `--host` flag family to a command and return it (chainable). */
 export function addHostOption(cmd) {
     return cmd
-        .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, a registered host, or user@host. See `agents devices` / `agents hosts`.')
-        .option('--device <name>', 'Alias of --host: run this command on a registered device (from `agents devices`).')
+        .option('-H, --host <name>', 'Run this command on another machine over SSH instead of locally — a device, a registered host, user@host, or `all` to fan out across every registered device. See `agents devices` / `agents hosts`.')
+        .option('--device <name>', 'Alias of --host: run this command on a registered device (from `agents devices`), or `all` to run it across the whole fleet.')
         .option('--remote-cwd <dir>', "Working directory on the host for --host runs. Resolves on the REMOTE host — pass a '$HOME'-relative path (single-quoted so your local shell doesn't expand it) or a valid remote absolute path; a local ~ expands here and won't exist there (/Users/you vs /home/you). No effect on 'teams add'.")
         .option('--no-tty', 'Force non-interactive output for --host runs even from a terminal.')
         .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');

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

@@ -16,8 +16,28 @@
  * table or, when `--host`/`--device` is present, exits with a clear
  * "not supported" message — never commander's raw `unknown option`.
  */
+import { type DeviceRegistry } from '../devices/registry.js';
+import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
+/** Per-command remote behaviour. Absence from this map = not host-routable here. */
+interface RemoteSpec {
+    /** Flags appended when running non-interactively (no local TTY / `--no-tty`). */
+    nonInteractive?: string[];
+}
 /** Pull the value of `--host`/`-H`/`--remote-cwd` (any form) out of an argv. */
 export declare function flagValue(args: string[], long: string, short?: string): string | undefined;
+/** Injectable dependencies for {@link runFleetPassthrough} — used by tests. */
+export interface FleetPassthroughOptions {
+    /** Override the device registry loader (tests). */
+    loadDevices?: () => Promise<DeviceRegistry>;
+    /** Override the per-device runner (tests). Defaults to `runOnDevice`. */
+    runner?: typeof runOnDevice;
+    /** Override the local runner for the self device (tests). Defaults to `runLocalCommand`. */
+    localRunner?: typeof runLocalCommand;
+    /** Override this machine's id (tests). Defaults to `machineId()`. */
+    self?: string;
+}
+/** Run `agents <command> …` across every registered device and render the roster. */
+export declare function runFleetPassthrough(command: string, allArgs: string[], spec: RemoteSpec, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**
  * Route `agents <command> … --host <name>` to a remote if the command is
  * host-routable and a `--host` (or its `--device` alias) was given. Returns
@@ -30,4 +50,5 @@ export declare function flagValue(args: string[], long: string, short?: string):
  * @param command the resolved subcommand name (`process.argv`'s first non-flag).
  * @param allArgs `process.argv.slice(2)` — the command name followed by its args.
  */
-export declare function maybeRunOnHost(command: string, allArgs: string[]): Promise<boolean>;
+export declare function maybeRunOnHost(command: string, allArgs: string[], opts?: FleetPassthroughOptions): Promise<boolean>;
+export {};