@phnx-labs/agents-cli 1.20.76 → 1.20.78

package/dist/lib/devices/fleet-divergence.js

@@ -0,0 +1,188 @@
+/**
+ * Cross-device harness divergence for `agents doctor` (RUSH-2027).
+ *
+ * `agents fleet status` already fans out `agents doctor --json` per device and
+ * builds a {@link FleetHealthReport} of coarse device health (reachable, CLIs
+ * installed, agents-cli version skew, local sync drift). It deliberately does
+ * NOT compare fine-grained *resource presence* across devices — so a plugin like
+ * `swarm` installed on one box but missing on another is silent until a user
+ * types `/swarm:run` on the wrong machine and gets `Unknown command`.
+ *
+ * This module is the missing comparison. Each device self-reports its installed
+ * inventory (resource kinds, per-agent version sets, `.agents`/`.system` repo
+ * state) in its `doctor --json` payload; {@link compareFleetInventories} takes
+ * the collected per-device inventories and, treating the local machine as the
+ * baseline, flags:
+ *
+ *   1. Resource presence gaps  — a resource present on one device, missing on
+ *      another (either direction relative to the local baseline).
+ *   2. Agent version gaps      — an agent version installed on one device but
+ *      not another (e.g. `yosemite-s0 missing claude@2.1.220`).
+ *   3. `.agents`/`.system` repo drift — a device whose config-repo HEAD, branch,
+ *      or dirty state diverges from the local baseline.
+ *
+ * Pure and SSH-free: the SSH fan-out lives in the doctor command; this module
+ * only consumes the already-collected payloads, so the divergence logic is
+ * unit-tested against fixture inventories with no live fleet.
+ */
+export const FLEET_RESOURCE_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'rules',
+    'mcp',
+    'permissions',
+    'subagents',
+    'plugins',
+    'promptcuts',
+    'workflows',
+];
+function sortedUnique(list) {
+    return Array.from(new Set(list)).sort();
+}
+function repoLabel(repo) {
+    return repo === 'agents' ? '.agents' : '.system';
+}
+/** Describe how a remote repo state diverges from the local baseline, or null
+ *  when they match. Compares HEAD first (the load-bearing difference), then
+ *  branch, then a dirty tree on either side (naming which side is dirty). */
+function describeRepoDrift(local, remote) {
+    if (local.head && remote.head && local.head !== remote.head) {
+        return `HEAD ${remote.head} != local ${local.head}`;
+    }
+    if (local.branch !== remote.branch) {
+        return `branch ${remote.branch ?? 'detached'} != local ${local.branch ?? 'detached'}`;
+    }
+    // Flag a dirty tree on EITHER side (symmetric with HEAD/branch above), and name
+    // the side that has the uncommitted changes — the remote, or the local baseline.
+    if (remote.dirty !== local.dirty) {
+        return remote.dirty
+            ? 'remote tree has uncommitted changes'
+            : 'local tree has uncommitted changes';
+    }
+    return null;
+}
+/**
+ * Compare a set of per-device inventories against the local baseline and emit
+ * every cross-device divergence. The baseline is the device whose name equals
+ * {@link baselineName} (the local machine); if that device has no inventory the
+ * report is empty (nothing to compare against). Devices with no inventory are
+ * recorded under `skippedDevices` and never produce false "missing" findings.
+ *
+ * Ordering is deterministic (device, then category, then name) so the human and
+ * JSON output — and the tests — are stable.
+ */
+export function compareFleetInventories(devices, baselineName) {
+    const baseline = devices.find((d) => d.name === baselineName)?.inventory ?? null;
+    const remotes = devices.filter((d) => d.name !== baselineName);
+    const comparedDevices = [];
+    const skippedDevices = [];
+    const divergences = [];
+    if (!baseline) {
+        // No local baseline to compare against — record every remote as skipped so
+        // the caller can say so, but emit no divergences (we can't know the truth).
+        for (const d of remotes)
+            skippedDevices.push(d.name);
+        return {
+            baseline: baselineName,
+            divergences: [],
+            comparedDevices: [],
+            skippedDevices: skippedDevices.sort(),
+            hasDivergence: false,
+        };
+    }
+    for (const remote of remotes) {
+        if (!remote.inventory) {
+            skippedDevices.push(remote.name);
+            continue;
+        }
+        comparedDevices.push(remote.name);
+        const inv = remote.inventory;
+        // 1) Resource presence, both directions.
+        for (const kind of FLEET_RESOURCE_KINDS) {
+            const localSet = new Set(baseline.resources[kind] ?? []);
+            const remoteSet = new Set(inv.resources[kind] ?? []);
+            for (const name of sortedUnique(baseline.resources[kind] ?? [])) {
+                if (!remoteSet.has(name)) {
+                    divergences.push({
+                        kind: 'resource-missing-remote',
+                        device: remote.name,
+                        category: kind,
+                        name,
+                        message: `${remote.name} is missing ${kind.replace(/s$/, '')} '${name}' (present on ${baselineName})`,
+                    });
+                }
+            }
+            for (const name of sortedUnique(inv.resources[kind] ?? [])) {
+                if (!localSet.has(name)) {
+                    divergences.push({
+                        kind: 'resource-missing-local',
+                        device: remote.name,
+                        category: kind,
+                        name,
+                        message: `${baselineName} is missing ${kind.replace(/s$/, '')} '${name}' (present on ${remote.name})`,
+                    });
+                }
+            }
+        }
+        // 2) Agent version parity, both directions, per agent id.
+        const agentIds = sortedUnique([
+            ...Object.keys(baseline.agentVersions),
+            ...Object.keys(inv.agentVersions),
+        ]);
+        for (const agent of agentIds) {
+            const localVers = new Set(baseline.agentVersions[agent] ?? []);
+            const remoteVers = new Set(inv.agentVersions[agent] ?? []);
+            for (const v of sortedUnique(baseline.agentVersions[agent] ?? [])) {
+                if (!remoteVers.has(v)) {
+                    divergences.push({
+                        kind: 'agent-version-missing-remote',
+                        device: remote.name,
+                        category: agent,
+                        name: v,
+                        message: `${remote.name} is missing ${agent}@${v} (installed on ${baselineName})`,
+                    });
+                }
+            }
+            for (const v of sortedUnique(inv.agentVersions[agent] ?? [])) {
+                if (!localVers.has(v)) {
+                    divergences.push({
+                        kind: 'agent-version-missing-local',
+                        device: remote.name,
+                        category: agent,
+                        name: v,
+                        message: `${baselineName} is missing ${agent}@${v} (installed on ${remote.name})`,
+                    });
+                }
+            }
+        }
+        // 3) `.agents` / `.system` repo drift vs the local baseline.
+        for (const repo of ['agents', 'system']) {
+            const localRepo = baseline.repos[repo];
+            const remoteRepo = inv.repos[repo];
+            if (!localRepo || !remoteRepo)
+                continue; // one side isn't a readable repo
+            const drift = describeRepoDrift(localRepo, remoteRepo);
+            if (drift) {
+                divergences.push({
+                    kind: 'repo-drift',
+                    device: remote.name,
+                    category: repo,
+                    name: repoLabel(repo),
+                    message: `${remote.name} ${repoLabel(repo)} repo diverged: ${drift}`,
+                });
+            }
+        }
+    }
+    divergences.sort((a, b) => a.device.localeCompare(b.device) ||
+        a.kind.localeCompare(b.kind) ||
+        a.category.localeCompare(b.category) ||
+        a.name.localeCompare(b.name));
+    return {
+        baseline: baselineName,
+        divergences,
+        comparedDevices: comparedDevices.sort(),
+        skippedDevices: skippedDevices.sort(),
+        hasDivergence: divergences.length > 0,
+    };
+}

package/dist/lib/devices/fleet-inventory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Build the self-reported harness inventory a device emits in `doctor --json`
+ * for cross-device divergence detection (RUSH-2027).
+ *
+ * Kept separate from {@link ../devices/fleet-divergence.js} — which stays a pure,
+ * SSH-free comparator — because this reads the live install (resource dirs,
+ * installed version homes, config repos). One call produces the {@link
+ * FleetInventory} that both the local baseline and every remote box serialize
+ * into their doctor payload; the comparator then diffs those payloads.
+ */
+import { type FleetInventory } from './fleet-divergence.js';
+/**
+ * Collect this machine's harness inventory: installed resources per kind,
+ * installed version ids per agent, and `.agents`/`.system` repo state. Pure
+ * reads — never mutates the install. `promptcuts` (a single present/absent bit
+ * in {@link getAvailableResources}) is surfaced as a one-element list so it
+ * compares like any other named resource.
+ */
+export declare function collectLocalFleetInventory(cwd?: string): FleetInventory;

package/dist/lib/devices/fleet-inventory.js

@@ -0,0 +1,57 @@
+/**
+ * Build the self-reported harness inventory a device emits in `doctor --json`
+ * for cross-device divergence detection (RUSH-2027).
+ *
+ * Kept separate from {@link ../devices/fleet-divergence.js} — which stays a pure,
+ * SSH-free comparator — because this reads the live install (resource dirs,
+ * installed version homes, config repos). One call produces the {@link
+ * FleetInventory} that both the local baseline and every remote box serialize
+ * into their doctor payload; the comparator then diffs those payloads.
+ */
+import { getAvailableResources, listInstalledVersions } from '../versions.js';
+import { getUserAgentsDir, getSystemAgentsDir } from '../state.js';
+import { readRepoState } from '../git.js';
+import { ALL_AGENT_IDS } from '../agents.js';
+import { FLEET_RESOURCE_KINDS } from './fleet-divergence.js';
+function toRepoState(snap) {
+    if (!snap)
+        return null;
+    return { branch: snap.branch, head: snap.head, dirty: snap.dirty };
+}
+/**
+ * Collect this machine's harness inventory: installed resources per kind,
+ * installed version ids per agent, and `.agents`/`.system` repo state. Pure
+ * reads — never mutates the install. `promptcuts` (a single present/absent bit
+ * in {@link getAvailableResources}) is surfaced as a one-element list so it
+ * compares like any other named resource.
+ */
+export function collectLocalFleetInventory(cwd = process.cwd()) {
+    const available = getAvailableResources(cwd);
+    const resources = {};
+    for (const kind of FLEET_RESOURCE_KINDS) {
+        if (kind === 'promptcuts') {
+            resources[kind] = available.promptcuts ? ['promptcuts.yaml'] : [];
+        }
+        else if (kind === 'rules') {
+            // getAvailableResources exposes top-level rules under `memory`.
+            resources[kind] = [...available.memory].sort();
+        }
+        else {
+            resources[kind] = [...(available[kind] ?? [])].sort();
+        }
+    }
+    const agentVersions = {};
+    for (const agent of ALL_AGENT_IDS) {
+        const versions = listInstalledVersions(agent);
+        if (versions.length > 0)
+            agentVersions[agent] = [...versions].sort();
+    }
+    return {
+        resources,
+        agentVersions,
+        repos: {
+            agents: toRepoState(readRepoState(getUserAgentsDir())),
+            system: toRepoState(readRepoState(getSystemAgentsDir())),
+        },
+    };
+}

package/dist/lib/devices/fleet.d.ts

@@ -136,5 +136,20 @@ export interface RunFleetOptions {
  * recorded as `failed` so one bad device never aborts the rest.
  */
 export declare function runFleet(targets: FleetTarget[], cmd: string[], opts?: RunFleetOptions): FleetRunResult[];
+export interface FanOutDeviceOptions {
+    /**
+     * Per-device deadline in milliseconds. When set, any probe that does not
+     * settle within this window is abandoned via `Promise.race` against a
+     * rejection timer and recorded as a `failed` result with the message
+     * `'timed out'`. There is no AbortController — the underlying probe
+     * continues running in the background; cancellation of the in-flight work
+     * is the caller's responsibility. In practice `probeRemoteAuth` relies on
+     * `sshExecAsync`'s own 15 s timer to kill the ssh child independently.
+     * The per-device ssh timeout passed directly to {@link sshExecAsync} is
+     * the first line of defence; this acts as a hard backstop so one slow
+     * device can never stall the entire fan-out past its budget.
+     */
+    perDeviceTimeoutMs?: number;
+}
 /** Run one async probe per device in parallel, preserving input order. */
-export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>): Promise<FanOutDeviceResult<T>[]>;
+export declare function fanOutDevices<T, Target extends FanOutDeviceTarget = FanOutDeviceTarget>(targets: Target[], probe: (target: Target) => Promise<T>, opts?: FanOutDeviceOptions): Promise<FanOutDeviceResult<T>[]>;

package/dist/lib/devices/fleet.js

@@ -212,7 +212,7 @@ export function runFleet(targets, cmd, opts = {}) {
     return results;
 }
 /** Run one async probe per device in parallel, preserving input order. */
-export async function fanOutDevices(targets, probe) {
+export async function fanOutDevices(targets, probe, opts = {}) {
     return Promise.all(targets.map(async (target) => {
         if (target.skip) {
             return {
@@ -222,10 +222,18 @@ export async function fanOutDevices(targets, probe) {
             };
         }
         try {
+            let probePromise = probe(target);
+            if (opts.perDeviceTimeoutMs) {
+                const timeoutMs = opts.perDeviceTimeoutMs;
+                probePromise = Promise.race([
+                    probePromise,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('timed out')), timeoutMs)),
+                ]);
+            }
             return {
                 name: target.name,
                 status: 'ok',
-                value: await probe(target),
+                value: await probePromise,
             };
         }
         catch (err) {

package/dist/lib/devices/health-report.d.ts

@@ -1,6 +1,7 @@
 import { type DeviceStats } from './health.js';
 import { type HostAuthSummary } from '../auth-health.js';
 import type { OnlineState } from './reachability.js';
+import { type FleetInventory } from './fleet-divergence.js';
 export interface FleetCliStatus {
     installed: boolean;
     path: string | null;
@@ -40,9 +41,14 @@ export interface FleetHealthRow {
      *  an offline row. Sourced from the registry's tailscale snapshot / reachability
      *  verdict. Undefined when never recorded. */
     lastSeen?: string;
+    /** This host's self-reported harness inventory (resources / agent versions /
+     *  repo state) from its `doctor --json` `fleet` field, for cross-device
+     *  divergence detection (RUSH-2027). Undefined for an unreachable box or an
+     *  older CLI that doesn't emit it. */
+    inventory?: FleetInventory;
 }
 export interface FleetWarning {
-    kind: 'unreachable' | 'drift' | 'cli' | 'version-skew';
+    kind: 'unreachable' | 'drift' | 'cli' | 'version-skew' | 'divergence';
     devices: string[];
     message: string;
 }
@@ -53,7 +59,9 @@ export interface FleetHealthReport {
     hasWarnings: boolean;
     hasDrift: boolean;
 }
-export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Date): FleetHealthReport;
+export declare function buildFleetHealthReport(rows: FleetHealthRow[], now?: Date, opts?: {
+    self?: string;
+}): FleetHealthReport;
 export declare function renderFleetWarnings(report: FleetHealthReport): string[];
 export declare function renderFleetMatrix(report: FleetHealthReport): string[];
 /**

package/dist/lib/devices/health-report.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 import { padToWidth, stringWidth, terminalWidth, truncateToWidth } from '../session/width.js';
 import { fmtBytes, headroom } from './health.js';
 import { formatCheckedAge } from '../auth-health.js';
+import { compareFleetInventories } from './fleet-divergence.js';
 function driftRows(row) {
     return row.sync.filter((s) => s.status !== 'fresh');
 }
@@ -12,7 +13,7 @@ function installedCliCount(row) {
         total: statuses.length,
     };
 }
-export function buildFleetHealthReport(rows, now = new Date()) {
+export function buildFleetHealthReport(rows, now = new Date(), opts = {}) {
     const warnings = [];
     const unreachable = rows
         .filter((r) => r.error || r.skipped)
@@ -60,6 +61,25 @@ export function buildFleetHealthReport(rows, now = new Date()) {
             message: `agents-cli version skew: ${Array.from(versions.keys()).sort().join(', ')}`,
         });
     }
+    // Cross-device harness divergence (RUSH-2027): compare every device's
+    // self-reported inventory against the local baseline and roll the findings up
+    // into one warning per affected device. Only runs when a baseline (`self`) is
+    // named and at least one device carries an inventory — an older-CLI fleet with
+    // no `fleet` field simply produces no divergence warning.
+    if (opts.self && rows.some((r) => r.inventory)) {
+        const divergence = compareFleetInventories(rows.map((r) => ({ name: r.name, inventory: r.inventory ?? null })), opts.self);
+        const byDevice = new Map();
+        for (const d of divergence.divergences)
+            byDevice.set(d.device, (byDevice.get(d.device) ?? 0) + 1);
+        for (const device of Array.from(byDevice.keys()).sort()) {
+            const n = byDevice.get(device);
+            warnings.push({
+                kind: 'divergence',
+                devices: [device],
+                message: `${device} diverges from ${opts.self} (${n} resource/version/repo gap${n === 1 ? '' : 's'})`,
+            });
+        }
+    }
     return {
         generatedAt: now.toISOString(),
         devices: rows,
@@ -326,6 +346,17 @@ export function buildFleetAttentionItems(report, now = Date.now()) {
             .join(' · ');
         items.push({ glyph: 'warn', subject: 'version skew', detail: summary, fix: 'agents upgrade --fleet' });
     }
+    // 4) Cross-device harness divergence — one item per diverged box (RUSH-2027).
+    for (const w of report.warnings) {
+        if (w.kind !== 'divergence')
+            continue;
+        items.push({
+            glyph: 'warn',
+            subject: w.devices[0] ?? 'fleet',
+            detail: w.message.replace(`${w.devices[0]} `, ''),
+            fix: `agents apply ${w.devices[0] ?? ''}`.trim(),
+        });
+    }
     return items;
 }
 /** Right-aligned `<content>` on the same line as `left`, clamped so it never

package/dist/lib/events.d.ts

@@ -12,7 +12,7 @@
  * - Performance tracking: withTiming() wrapper for any async function
  */
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;

package/dist/lib/exec.d.ts

@@ -197,6 +197,22 @@ export declare function inferredInteractiveWithoutTty(options: Pick<ExecOptions,
 export declare function shouldTapStdout(interactive: boolean, piped: boolean, capsActive: boolean, captureTail?: boolean): boolean;
 /** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
+/**
+ * Resolve the launch id a run exports as `AGENT_LAUNCH_ID`.
+ *
+ * The launch id is the stable correlation key the SessionStart hook records
+ * alongside the agent's real session id (terminals/sessions/<pid>.json), so it
+ * is what maps a launch to its exact session even when the hook runs under a
+ * different pid (tmux pane leaf / cmd.exe wrapper) — and, across an SSH hop, what
+ * lets a `--host` launcher resolve the remote-coined id for agents that never
+ * accept a forced `--session-id`.
+ *
+ * ADOPT a caller-supplied `AGENT_LAUNCH_ID` (a `--host` launcher forwards one via
+ * `--env` so it controls the key end-to-end); MINT a fresh one otherwise (every
+ * local run, which passes none). A malformed inbound value is ignored in favour
+ * of a fresh mint — the key must be a real correlation id, never an empty string.
+ */
+export declare function resolveLaunchId(envLaunchId: string | undefined): string;
 /**
  * Build the process environment for an agent invocation.
  * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME

package/dist/lib/exec.js

@@ -218,6 +218,25 @@ export function parseExecEnv(entries) {
     }
     return Object.fromEntries(entries.map(parseExecEnvEntry));
 }
+/**
+ * Resolve the launch id a run exports as `AGENT_LAUNCH_ID`.
+ *
+ * The launch id is the stable correlation key the SessionStart hook records
+ * alongside the agent's real session id (terminals/sessions/<pid>.json), so it
+ * is what maps a launch to its exact session even when the hook runs under a
+ * different pid (tmux pane leaf / cmd.exe wrapper) — and, across an SSH hop, what
+ * lets a `--host` launcher resolve the remote-coined id for agents that never
+ * accept a forced `--session-id`.
+ *
+ * ADOPT a caller-supplied `AGENT_LAUNCH_ID` (a `--host` launcher forwards one via
+ * `--env` so it controls the key end-to-end); MINT a fresh one otherwise (every
+ * local run, which passes none). A malformed inbound value is ignored in favour
+ * of a fresh mint — the key must be a real correlation id, never an empty string.
+ */
+export function resolveLaunchId(envLaunchId) {
+    const inbound = envLaunchId?.trim();
+    return inbound ? inbound : randomUUID();
+}
 /**
  * Build the process environment for an agent invocation.
  * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
@@ -1172,15 +1191,19 @@ async function spawnAgent(options) {
     // timeout. Spend is recorded to the shared ledger in the close handler. The
     // watcher is dormant (and zero-cost) when no caps are configured.
     const cwd = options.cwd || process.cwd();
-    // Mint the launch id once. It doubles as the budget watcher's run id AND is
+    // Resolve the launch id once. It doubles as the budget watcher's run id AND is
     // exported to the child as AGENT_LAUNCH_ID, so the agent's SessionStart hook
     // records the SAME id in its own state file (terminals/sessions/<pid>.json).
     // That id is the join key that reconciles this launch's pid-registry entry
     // with the hook's authoritative session id even when the hook runs under a
     // different pid (tmux pane leaf / cmd.exe wrapper) — see pid-registry.ts and
-    // session/hook-sessions.ts. Injected into options.env so every downstream env
-    // build (the bare spawn below AND the tmux env prefix in runInTmux) carries it.
-    const launchId = randomUUID();
+    // session/hook-sessions.ts. ADOPT a launch id a `--host` launcher already
+    // forwarded (via `--env AGENT_LAUNCH_ID=…`) so ONE correlation key spans the
+    // SSH hop and the launcher can resolve this run's real session id for every
+    // agent, not just Claude (RUSH-2034); mint a fresh one for every local run.
+    // Injected into options.env so every downstream env build (the bare spawn
+    // below AND the tmux env prefix in runInTmux) carries it.
+    const launchId = resolveLaunchId(options.env?.AGENT_LAUNCH_ID);
     const runId = launchId;
     options = { ...options, env: { ...options.env, AGENT_LAUNCH_ID: launchId } };
     const watcherState = await setupBudgetWatcher(options, cwd, runId);

package/dist/lib/feed.d.ts

@@ -172,7 +172,7 @@ export declare function removeBlock(blockId: string, root?: string): boolean;
  * Embedded so it ships with the compiled CLI and can be installed to the
  * CLI-writable user hooks dir without a separate file in the npm tarball.
  */
-export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior.\n    controls = payload.get(\"tool_input\", {}) if hook_event != \"Notification\" else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n# Codex emits a PermissionRequest event (not Claude's Notification) when it\n# blocks on an approval prompt. Claude never fires PermissionRequest, so the\n# same script handles both: PermissionRequest maps to an approval-class block\n# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        # A matcher-less PostToolUse clear (registered for Codex so an approved\n        # tool clears its approval card) must NOT wipe an open AskUserQuestion\n        # while an unrelated tool runs mid-question -- those are cleared only by\n        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a\n        # 'question' block; approval/notification blocks clear once the tool runs.\n        if hook_event == \"PostToolUse\":\n            try:\n                with open(target) as existing_file:\n                    existing = json.load(existing_file)\n                if existing.get(\"kind\") == \"question\" and payload.get(\"tool_name\") != \"AskUserQuestion\":\n                    return\n            except Exception:\n                pass\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    codex_approval = False\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    elif hook_event == \"PermissionRequest\":\n        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,\n        # tool_input) but carries no questions -- Codex is asking to run a tool,\n        # not asking the operator a multiple-choice question. Publish it as a\n        # notification-kind approval block naming the tool so the feed and the\n        # phone notifier can surface it, and so the Factory extension can bridge\n        # it to a VS Code notification.\n        tool_name = payload.get(\"tool_name\") or \"a tool\"\n        tool_input = payload.get(\"tool_input\", {})\n        command = \"\"\n        if isinstance(tool_input, dict):\n            command = (\n                tool_input.get(\"command\")\n                or tool_input.get(\"cmd\")\n                or tool_input.get(\"path\")\n                or \"\"\n            )\n            if isinstance(command, list):\n                command = \" \".join(str(c) for c in command)\n        detail = f\": {command}\" if command else \"\"\n        normalized_questions = [{\n            \"text\": f\"Codex needs approval to run {tool_name}{detail}\",\n            \"header\": \"Approval needed\",\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n        notification_type = \"permission_prompt\"\n        codex_approval = True\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # A Codex PermissionRequest is a real approval gate: mark it approval-class\n    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent\n    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default\n    # 'medium') and pages the phone. A plain 'deny' is the safe default.\n    if codex_approval:\n        block[\"blockClass\"] = \"approval\"\n        block[\"costOfDelay\"] = \"high\"\n        block[\"safeDefault\"] = \"deny\"\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex\n    # PermissionRequest carries tool ARGS in tool_input (command/path), not\n    # operator controls, so it is excluded here -- its class/cost is stamped\n    # above from codex_approval.\n    controls = payload.get(\"tool_input\", {}) if hook_event not in (\"Notification\", \"PermissionRequest\") else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
 /** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
 export declare const FEED_PUBLISH_HOOK_MANIFEST: {
     name: string;
@@ -188,6 +188,12 @@ export declare const FEED_NOTIFICATION_HOOK_MANIFEST: {
     script: string;
     timeout: number;
 };
+export declare const FEED_PERMISSION_HOOK_MANIFEST: {
+    name: string;
+    events: string[];
+    script: string;
+    timeout: number;
+};
 export declare const FEED_ANSWERED_HOOK_MANIFEST: {
     name: string;
     events: string[];