@phnx-labs/agents-cli 1.20.78 → 1.20.82

package/dist/lib/fleet/auth-sync.js

@@ -23,7 +23,6 @@ import * as path from 'path';
 export const FLEET_AUTH_FILES = {
     claude: [{ rel: '.claude/.credentials.json', mode: 0o600 }],
     codex: [{ rel: '.codex/auth.json', mode: 0o600 }],
-    gemini: [{ rel: '.gemini/oauth_creds.json', mode: 0o600 }],
     grok: [{ rel: '.grok/auth.json', mode: 0o600 }],
     kimi: [{ rel: '.kimi-code/credentials/kimi-code.json', mode: 0o600 }],
     opencode: [{ rel: '.local/share/opencode/auth.json', mode: 0o600 }],
@@ -35,9 +34,30 @@ export const FLEET_AUTH_FILES = {
 };
 /** Agents whose macOS credentials live in the ACL-bound login keychain. */
 export const KEYCHAIN_BOUND_ON_MAC = new Set(['claude', 'antigravity']);
+/**
+ * Agents whose OAuth credentials rely on single-use refresh tokens that rotate
+ * server-side on every exchange. Copying these credential files across machines
+ * is fatal: the first refresh on any box invalidates every other holder's token,
+ * collapsing the fleet to a single working login (droid/WorkOS collapsed 10 boxes
+ * to 1 overnight — RUSH-1958). Add any newly-discovered single-use-rotation
+ * harness here; the predicate below is the one place the propagation decision is
+ * made. See also `remote-login.ts` and `usage.ts` for the per-machine-login policy.
+ */
+export const SINGLE_USE_ROTATING_REFRESH_AGENTS = new Set(['droid']);
+/** True when `agent`'s portable credential file(s) are safe to copy between
+ *  machines. Single-use rotating refresh tokens are never safe; keychain-bound
+ *  tokens are handled separately by the caller via {@link KEYCHAIN_BOUND_ON_MAC}. */
+export function isCredentialSafeToPropagate(agent) {
+    return !SINGLE_USE_ROTATING_REFRESH_AGENTS.has(agent);
+}
+/** True when the agent stores credentials in portable files we can read. This
+ *  does NOT mean it is safe to propagate — check {@link isCredentialSafeToPropagate}. */
+export function hasPortableAuthFiles(agent) {
+    return agent in FLEET_AUTH_FILES;
+}
 /** Which agents `apply` can propagate auth for at all. */
 export function isPropagatableAgent(agent) {
-    return agent in FLEET_AUTH_FILES;
+    return hasPortableAuthFiles(agent) && isCredentialSafeToPropagate(agent);
 }
 /** The success-file for an agent — the primary portable credential (first spec). */
 function successFileFor(agent) {
@@ -107,14 +127,6 @@ export const FLEET_LOGIN_FLOWS = {
         flowType: 'loopback',
         successFile: successFileFor('antigravity'),
     },
-    // gemini: bare `gemini`, Google login on launch. Not characterized as a
-    // device-code flow (typically loopback) and no captured pattern — mark unknown
-    // so it is flagged non-remotable rather than mis-driven.
-    gemini: {
-        loginCommand: 'gemini',
-        flowType: 'unknown',
-        successFile: successFileFor('gemini'),
-    },
     // opencode: `opencode auth login`. No captured pattern — unknown/non-remotable.
     opencode: {
         loginCommand: 'opencode auth login',
@@ -144,7 +156,9 @@ export function snapshotAuth(agents, opts) {
     for (const agent of agents) {
         const specs = FLEET_AUTH_FILES[agent];
         if (!specs)
-            continue; // not propagatable — caller surfaces separately if desired
+            continue; // no portable file — caller surfaces separately if desired
+        if (!isCredentialSafeToPropagate(agent))
+            continue; // single-use rotating refresh tokens are never copied
         if (opts.platform === 'darwin' && KEYCHAIN_BOUND_ON_MAC.has(agent)) {
             bound.push(agent);
             continue;

package/dist/lib/fleet/remote-login.js

@@ -9,6 +9,11 @@
  * each verification URL + user code, and surfacing them all in ONE local browser
  * page so the human enters codes back-to-back instead of babysitting N terminals.
  *
+ * The propagation gate lives in `auth-sync.ts`: {@link isCredentialSafeToPropagate}
+ * and {@link SINGLE_USE_ROTATING_REFRESH_AGENTS} are the single place where the
+ * "is this credential safe to copy?" decision is made, shared by `agents apply`
+ * and any other propagation path.
+ *
  * Layering — pure vs I/O, so the valuable logic is unit-testable without SSH:
  *  - `scrapeLogin` / `classifyLoginFlow` / `selectLoginTargets` /
  *    `buildRemoteLoginSshCommand` / `buildDashboardHtml` are PURE.

package/dist/lib/git.d.ts

@@ -248,20 +248,6 @@ export declare function displayHomePath(dir: string): string;
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
-/**
- * Auto-commit the machine's OWN generated per-device meta file
- * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
- *
- * That file is committed + synced (so every machine can introspect every other
- * machine's pins), but each box rewrites its own copy whenever a pin changes —
- * leaving the tree perpetually dirty and wedging `agents repo pull` (which
- * refuses a dirty tree). This durably commits just that one path (explicit
- * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
- * untouched and still (correctly) block the pull. No-op when the meta path isn't
- * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
- * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
- */
-export declare function commitOwnDeviceMeta(dir: string, metaAbs?: string): Promise<string | null>;
 export declare function pullRepo(dir: string): Promise<{
     success: boolean;
     commit: string;
@@ -341,3 +327,17 @@ export declare function tryAutoPull(dir: string): Promise<{
     pulled: boolean;
     error?: string;
 }>;
+/**
+ * How many commits `dir`'s checked-out branch is behind its upstream, read from
+ * the LAST-FETCHED remote-tracking ref — no network call. Returns null when the
+ * dir is not a git repo, has no upstream configured, or git errors.
+ *
+ * Used by `agents doctor` to flag a source layer (`~/.agents`, `~/.agents/.system`)
+ * that is reconciled against stale truth. Staleness relative to origin is a
+ * background auto-pull concern; this surfaces the same fact synchronously in the
+ * per-version verdict.
+ */
+export declare function commitsBehindUpstream(dir: string): {
+    behind: number;
+    branch: string;
+} | null;

package/dist/lib/git.js

@@ -11,7 +11,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { IS_WINDOWS, isWindowsAbsolutePath } from './platform/index.js';
-import { getPackageLocalPath, getDeviceMetaPath } from './state.js';
+import { getPackageLocalPath } from './state.js';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from './types.js';
 /**
  * Validate that a clone/pull source uses a safe git transport before it is
@@ -803,48 +803,13 @@ export function displayHomePath(dir) {
  * branch reconciles instead of failing with "Need to specify how to reconcile
  * divergent branches".
  */
-/**
- * Auto-commit the machine's OWN generated per-device meta file
- * (`devices/<machineId>/agents.yaml`) if it's the dirty state blocking a pull.
- *
- * That file is committed + synced (so every machine can introspect every other
- * machine's pins), but each box rewrites its own copy whenever a pin changes —
- * leaving the tree perpetually dirty and wedging `agents repo pull` (which
- * refuses a dirty tree). This durably commits just that one path (explicit
- * pathspec) so the pull can proceed; genuine user edits to OTHER files are left
- * untouched and still (correctly) block the pull. No-op when the meta path isn't
- * inside `dir` (system/extra repos) or isn't dirty. Returns the committed rel
- * path, or null. `metaAbs` is injectable for tests; defaults to the live path.
- */
-export async function commitOwnDeviceMeta(dir, metaAbs = getDeviceMetaPath()) {
-    const resolvedDir = path.resolve(dir);
-    const resolvedMeta = path.resolve(metaAbs);
-    if (resolvedMeta !== resolvedDir && !resolvedMeta.startsWith(resolvedDir + path.sep)) {
-        return null; // meta lives outside this repo — not ours to commit here
-    }
-    const rel = path.relative(resolvedDir, resolvedMeta).split(path.sep).join('/');
-    try {
-        const git = simpleGit(dir);
-        const status = await git.status();
-        const dirty = status.files.some((f) => f.path === rel);
-        if (!dirty)
-            return null;
-        await git.add([rel]);
-        const machine = path.basename(path.dirname(resolvedMeta));
-        await git.commit(`chore(devices): snapshot ${machine} agent pins`, [rel]);
-        return rel;
-    }
-    catch {
-        return null; // best-effort — never let this block the pull path
-    }
-}
 export async function pullRepo(dir) {
     try {
         const git = simpleGit(dir);
         // A rebase left in progress by an earlier run must be reported as itself.
         // Without this the dirty-tree guard below claims "Blocked by local changes",
         // which is both wrong and actively harmful advice mid-rebase on a detached
-        // HEAD. Checked BEFORE commitOwnDeviceMeta so we never commit into one.
+        // HEAD.
         // Ask git where the state dirs live rather than assuming `<dir>/.git/` is a
         // directory. In a worktree `.git` is a FILE containing `gitdir: <path>`, so
         // path.join(dir, '.git', 'rebase-merge') can never exist and the check would
@@ -874,9 +839,6 @@ export async function pullRepo(dir) {
                     `  git rebase --abort      # to discard the attempt`,
             };
         }
-        // Commit this machine's own device-meta first so a per-machine pin change
-        // never wedges the pull. Genuine edits elsewhere still block below.
-        await commitOwnDeviceMeta(dir);
         const status = await git.status();
         if (!status.isClean()) {
             return {
@@ -934,10 +896,8 @@ export async function pullRepo(dir) {
         }
         try {
             // Rebase, not --ff-only. Fast-forward refuses ANY divergence, conflict or
-            // not, so a single local commit — including the one commitOwnDeviceMeta
-            // makes just above — permanently wedged the pull with nothing actually in
-            // conflict. Every device carries its own devices/<host>/ path, so those
-            // replay cleanly. Matches syncRepoGit (below) and this function's own doc.
+            // not, so a single local commit permanently wedged the pull with nothing
+            // actually in conflict. Matches syncRepoGit (below) and this function's doc.
             //
             // Pull the RESOLVED tracking ref, not `branch`: when the local branch has
             // no tracking config the block above falls back to origin's default head,
@@ -1211,3 +1171,40 @@ export async function tryAutoPull(dir) {
         return { pulled: false, error: err.message };
     }
 }
+/**
+ * How many commits `dir`'s checked-out branch is behind its upstream, read from
+ * the LAST-FETCHED remote-tracking ref — no network call. Returns null when the
+ * dir is not a git repo, has no upstream configured, or git errors.
+ *
+ * Used by `agents doctor` to flag a source layer (`~/.agents`, `~/.agents/.system`)
+ * that is reconciled against stale truth. Staleness relative to origin is a
+ * background auto-pull concern; this surfaces the same fact synchronously in the
+ * per-version verdict.
+ */
+export function commitsBehindUpstream(dir) {
+    if (!isGitRepo(dir))
+        return null;
+    const run = (args) => {
+        try {
+            return execFileSync('git', ['-C', dir, ...args], {
+                stdio: ['ignore', 'pipe', 'ignore'],
+                encoding: 'utf8',
+            }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    // Name of the upstream ref (e.g. `origin/main`) for the human-readable message.
+    const branch = run(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+    if (!branch)
+        return null;
+    // `--count HEAD..@{upstream}` = commits on upstream not yet in HEAD = behind.
+    const raw = run(['rev-list', '--count', 'HEAD..@{upstream}']);
+    if (raw === null)
+        return null;
+    const behind = parseInt(raw, 10);
+    if (!Number.isFinite(behind))
+        return null;
+    return { behind, branch };
+}

package/dist/lib/hooks.d.ts

@@ -59,6 +59,48 @@ export declare function getVersionHooksDir(agent: AgentId, version: string): str
  * List hook entries in a specific version home.
  */
 export declare function listHooksInVersionHome(agent: AgentId, version: string): HookEntry[];
+export interface HookWiringIssue {
+    /** Hook name (script basename minus extension). */
+    name: string;
+    /** Native lifecycle event the hook should be wired to (Stop, PreToolUse, …). */
+    event: string;
+    /** Matcher group the hook belongs to under `event` (`''` = the catch-all
+     *  group). Real hooks scope by matcher — ask-user-question-guard=AskUserQuestion,
+     *  user-message-guard=Bash — so wiring is verified per (event, matcher). */
+    matcher: string;
+    /** The command settings.json should reference for this hook under `event`. */
+    command: string;
+}
+export interface HookWiringReport {
+    /** Whether this agent's hook config format is understood by the inspector. */
+    supported: boolean;
+    /** Absolute path of the settings file inspected (when supported). */
+    settingsPath?: string;
+    /** Number of hooks the manifest says should be wired for this version. */
+    expected?: number;
+    /** settings.json does not exist — nothing declared can be wired. */
+    settingsMissing?: boolean;
+    /** settings.json exists but is not valid JSON — wiring can't be verified. */
+    settingsUnparseable?: boolean;
+    /** Hooks whose file is present/resolvable but that are NOT referenced in the
+     *  event array settings.json should carry them in. */
+    unwired: HookWiringIssue[];
+}
+/**
+ * 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 declare function checkVersionHookWiring(agent: AgentId, version: string): HookWiringReport;
 export interface VersionHookDiff {
     agent: AgentId;
     version: string;

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(); }
@@ -148,7 +147,7 @@ function isStaleSiblingVersionCommand(command, current) {
     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';
+import { generateHookShim, getHookShimPath, isValidHookShimName, parseCacheConfig, removeHookShim } from './hooks/cache.js';
 import { getHookShimsDir } from './state.js';
 /**
  * Resolve the command path to register for a hook.
@@ -488,6 +487,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 +1059,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 +1121,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 +1306,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 = [];
@@ -1387,12 +1500,17 @@ 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));
+            group.hooks = group.hooks.filter((h) => (!isManagedHookCommand(h.command, managedPrefixes) || currentManifestPaths.has(h.command)) &&
+                !isStaleSiblingVersionCommand(h.command, currentVh));
         }
     }
     for (const [event, eventGroups] of Object.entries(hooksFile.hooks)) {
@@ -1436,7 +1554,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 +1648,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;