@phnx-labs/agents-cli 1.22.26 → 1.22.28

package/dist/lib/session/resume-owner.js

@@ -0,0 +1,69 @@
+/**
+ * Where a session may be resumed — the one place that answers "does this
+ * transcript belong to another machine?" and, when it does, runs the resume
+ * THERE instead of here.
+ *
+ * A session's agent state lives on the box that produced it: the harness keeps
+ * its own conversation store under that machine's home, and `machine` on a
+ * SessionMeta records where the transcript originated (see session/types.ts).
+ * A row can reach this box two ways and BOTH are remote-owned:
+ *
+ *  - a **synced mirror** — locally readable at `backups/<agent>/<machine>/…`,
+ *    which is exactly why the old code could not tell: the transcript file is
+ *    right there, so nothing failed until the harness was asked to resume a
+ *    conversation it has never seen;
+ *  - a **live fan-out row** (`_remote`), whose `filePath` is on the peer's disk.
+ *
+ * Resuming either one locally starts the harness against state it does not
+ * have. Before RUSH-2022 that happened silently — `sessions-resume.ts` even fell
+ * back to `process.cwd()` when the recorded cwd did not exist locally, so a
+ * remote session resumed in whatever directory the user happened to be in.
+ *
+ * Callers act on the answer differently, and the difference is deliberate:
+ * `agents resume` and `agents sessions attach` HOP to the owner over SSH, while
+ * `resumeSessionInPlace` — the local takeover every routed caller reaches only
+ * after deciding — REFUSES. The batch `sessions resume` needs no check of its
+ * own: each of its tabs runs the canonical `agents resume <id>`
+ * (lib/session/resume-command.ts), which routes itself.
+ */
+import { isSelfHost } from '../devices/self-host.js';
+/**
+ * Set on the SSH hop that sends a resume to its owning device: the far side must
+ * run it, never route again.
+ *
+ * An env var rather than a flag, deliberately. The fleet is mixed-version — a
+ * peer on the released CLI would die on an unknown `--here` with
+ * `error: unknown option '--here'`, breaking the very hop this feature adds. An
+ * unrecognized exported variable is inert on every version, so routing works
+ * against old and new peers alike. The far side deletes it after reading
+ * ({@link consumeResumePinned}) so it cannot leak into the agent's own children.
+ */
+export const RESUME_PINNED_ENV = 'AGENTS_RESUME_PINNED';
+/**
+ * Whether this process was handed a resume by its owner-routing hop — read once,
+ * then cleared so a nested `agents resume` inside the running agent still routes
+ * normally.
+ */
+export function consumeResumePinned() {
+    const pinned = process.env[RESUME_PINNED_ENV] === '1';
+    delete process.env[RESUME_PINNED_ENV];
+    return pinned;
+}
+/**
+ * The peer that owns `session`'s state, or `undefined` when this machine does.
+ *
+ * Undefined is also the answer for an untagged row (`machine` unset — a session
+ * obtained outside `discoverSessions`): there is nothing to route to, so the
+ * caller keeps the local behaviour rather than inventing a target.
+ */
+export function sessionOwnerDevice(session) {
+    const owner = session.machine?.trim();
+    if (!owner)
+        return undefined;
+    // `isSelfHost` matches every identity this box answers to — `machineId()`
+    // itself, the tailnet dnsName and its short form, loopback (devices/
+    // self-host.ts `selfAliases`) — so a mirror tagged with this machine's tailnet
+    // name is local, not a peer (cf. RUSH-2114). No separate `machineId()`
+    // comparison: it is one of those aliases.
+    return isSelfHost(owner) ? undefined : owner;
+}

package/dist/lib/session/team-filter.d.ts

@@ -51,3 +51,68 @@ export interface FilterResult {
  * excluded and counted in `hiddenCount`.
  */
 export declare function filterTeamSessions(sessions: SessionMeta[], showTeams: boolean): FilterResult;
+/**
+ * Whether a team-origin session is a real `agents teams` teammate or a bare SDK
+ * spawn with no teammate record. The two share the `sdk-cli` entrypoint that
+ * sets `isTeamOrigin`, so they are told apart by whether a `meta.json` teammate
+ * record backs the origin ({@link TeamOrigin.source} === `'meta'`).
+ *
+ * `source` is newer than the rest of {@link TeamOrigin}, so a row that arrived
+ * from a pre-`source` peer over the `--host` fan-out carries none. There the
+ * meta-only fields settle it: the entrypoint fallback is a bare `{ handle }`, so
+ * any `team` / `mode` / `parentSessionId` / `startedAt` means a real teammate
+ * record produced it — otherwise a genuine teammate from an unupgraded peer
+ * would be misfiled into the no-team bucket, the exact conflation this splits.
+ */
+export declare function teamRowKind(origin: TeamOrigin | undefined): 'teammate' | 'subagent';
+/** A team-origin session with its resolved {@link TeamOrigin} guaranteed present. */
+type TeamSession = SessionMeta & {
+    teamOrigin: TeamOrigin;
+};
+/**
+ * Key/label for the residual bucket — sessions flagged `isTeamOrigin` (an SDK /
+ * `sdk-cli` entrypoint) that carry no teammate `meta.json`. In practice this is
+ * headless `agents run` spawns and teammates whose team record aged out; a true
+ * `Task` sub-agent's transcript is never indexed, so it cannot land here. Named
+ * "(no team)" rather than "(sub-agents)" so the label matches what it holds.
+ */
+export declare const NO_TEAM_GROUP_KEY = "(no team)";
+/** Key/label for teammates whose record carries no team name (`task_name`). */
+export declare const UNNAMED_TEAM_KEY = "(unnamed team)";
+/** One team's sessions, grouped for the `agents sessions --teams` view. */
+export interface TeamSessionGroup {
+    /**
+     * The grouping key: the team name, {@link UNNAMED_TEAM_KEY} for teammates that
+     * carry no `task_name`, or {@link NO_TEAM_GROUP_KEY} for the residual bucket.
+     */
+    key: string;
+    /** A named team of `agents teams` teammates vs the catch-all no-team bucket. */
+    kind: 'team' | 'noTeam';
+    /** Team name when this is a named team, else undefined. */
+    team?: string;
+    /**
+     * The orchestrator session id that spawned this team (`parent_session_id`),
+     * when every teammate agrees on one. Undefined for the no-team bucket, an
+     * unparented team, or a group whose teammates disagree.
+     */
+    spawnerSessionId?: string;
+    /** The team's rows, newest-active first. */
+    sessions: TeamSession[];
+    /** Most-recent activity across the group, for ordering groups. */
+    maxTs: string;
+    /** Earliest spawn time across the group (`started_at`, else `timestamp`). */
+    firstSpawnTs: string;
+}
+/**
+ * Group team-origin sessions for the `--teams` view: each named team becomes one
+ * group of its teammates, and every bare SDK spawn with no teammate record falls
+ * into a single trailing {@link NO_TEAM_GROUP_KEY} bucket, so a real teammate and
+ * a bare spawn are never shown as the same thing.
+ *
+ * Only rows with a resolved {@link TeamOrigin} participate (the caller has
+ * already run {@link filterTeamSessions}); any non-team session is ignored.
+ * Groups are ordered newest-active first; sub-agents always sort last. Pure —
+ * unit-tested.
+ */
+export declare function groupSessionsByTeam(sessions: SessionMeta[]): TeamSessionGroup[];
+export {};

package/dist/lib/session/team-filter.js

@@ -35,7 +35,7 @@ export function classifyTeamSession(session) {
     if (origin)
         return origin;
     if (session.isTeamOrigin) {
-        return { handle: session.id.slice(0, 8) };
+        return { handle: session.id.slice(0, 8), source: 'entrypoint' };
     }
     return null;
 }
@@ -54,12 +54,16 @@ function readTeamOrigin(metaPath, agentId) {
                 mode: str(meta.mode),
                 team: str(meta.task_name),
                 parentSessionId: str(meta.parent_session_id),
+                startedAt: str(meta.started_at),
+                source: 'meta',
             },
             sessionId: str(meta.remote_session_id),
         };
     }
     catch {
-        return { origin: { handle: agentId.slice(0, 8) } };
+        // An unreadable meta.json still lives under the teams agents dir, so the
+        // session IS a teammate — mark the source accordingly, just without fields.
+        return { origin: { handle: agentId.slice(0, 8), source: 'meta' } };
     }
 }
 /**
@@ -133,7 +137,8 @@ export function enrichTeamOrigins(sessions) {
         // here would find no local record and downgrade a named teammate to a bare id.
         if (session.teamOrigin)
             return session;
-        const origin = index.get(session.id) ?? (session.isTeamOrigin ? { handle: session.id.slice(0, 8) } : null);
+        const origin = index.get(session.id) ??
+            (session.isTeamOrigin ? { handle: session.id.slice(0, 8), source: 'entrypoint' } : null);
         return origin ? { ...session, teamOrigin: origin } : session;
     });
 }
@@ -162,3 +167,93 @@ export function filterTeamSessions(sessions, showTeams) {
     }
     return { visible, hiddenCount };
 }
+/**
+ * Whether a team-origin session is a real `agents teams` teammate or a bare SDK
+ * spawn with no teammate record. The two share the `sdk-cli` entrypoint that
+ * sets `isTeamOrigin`, so they are told apart by whether a `meta.json` teammate
+ * record backs the origin ({@link TeamOrigin.source} === `'meta'`).
+ *
+ * `source` is newer than the rest of {@link TeamOrigin}, so a row that arrived
+ * from a pre-`source` peer over the `--host` fan-out carries none. There the
+ * meta-only fields settle it: the entrypoint fallback is a bare `{ handle }`, so
+ * any `team` / `mode` / `parentSessionId` / `startedAt` means a real teammate
+ * record produced it — otherwise a genuine teammate from an unupgraded peer
+ * would be misfiled into the no-team bucket, the exact conflation this splits.
+ */
+export function teamRowKind(origin) {
+    if (!origin)
+        return 'subagent';
+    if (origin.source === 'meta')
+        return 'teammate';
+    if (origin.source === 'entrypoint')
+        return 'subagent';
+    return origin.team || origin.mode || origin.parentSessionId || origin.startedAt
+        ? 'teammate'
+        : 'subagent';
+}
+/**
+ * Key/label for the residual bucket — sessions flagged `isTeamOrigin` (an SDK /
+ * `sdk-cli` entrypoint) that carry no teammate `meta.json`. In practice this is
+ * headless `agents run` spawns and teammates whose team record aged out; a true
+ * `Task` sub-agent's transcript is never indexed, so it cannot land here. Named
+ * "(no team)" rather than "(sub-agents)" so the label matches what it holds.
+ */
+export const NO_TEAM_GROUP_KEY = '(no team)';
+/** Key/label for teammates whose record carries no team name (`task_name`). */
+export const UNNAMED_TEAM_KEY = '(unnamed team)';
+/** Recency signal for a row: last activity, else the creation timestamp. */
+function rowTs(s) {
+    return s.lastActivity ?? s.timestamp;
+}
+/** Spawn time for a row: the meta `started_at`, else the transcript creation time. */
+function spawnTs(s) {
+    return s.teamOrigin.startedAt ?? s.timestamp;
+}
+/**
+ * Group team-origin sessions for the `--teams` view: each named team becomes one
+ * group of its teammates, and every bare SDK spawn with no teammate record falls
+ * into a single trailing {@link NO_TEAM_GROUP_KEY} bucket, so a real teammate and
+ * a bare spawn are never shown as the same thing.
+ *
+ * Only rows with a resolved {@link TeamOrigin} participate (the caller has
+ * already run {@link filterTeamSessions}); any non-team session is ignored.
+ * Groups are ordered newest-active first; sub-agents always sort last. Pure —
+ * unit-tested.
+ */
+export function groupSessionsByTeam(sessions) {
+    const byKey = new Map();
+    for (const s of sessions) {
+        if (!s.teamOrigin)
+            continue;
+        const kind = teamRowKind(s.teamOrigin);
+        const key = kind === 'subagent'
+            ? NO_TEAM_GROUP_KEY
+            : safeTeamText(s.teamOrigin.team) ?? UNNAMED_TEAM_KEY;
+        const ts = s;
+        (byKey.get(key) ?? byKey.set(key, []).get(key)).push(ts);
+    }
+    const groups = [];
+    for (const [key, rows] of byKey) {
+        rows.sort((a, b) => (rowTs(a) < rowTs(b) ? 1 : rowTs(a) > rowTs(b) ? -1 : 0));
+        const kind = key === NO_TEAM_GROUP_KEY ? 'noTeam' : 'team';
+        // A single agreed-on spawner names the orchestrator for the whole team; a
+        // mix (or none) leaves it unset rather than claiming a wrong parent.
+        const parents = new Set(rows.map((r) => r.teamOrigin.parentSessionId).filter((p) => !!p));
+        groups.push({
+            key,
+            kind,
+            team: kind === 'team' && key !== UNNAMED_TEAM_KEY ? key : undefined,
+            spawnerSessionId: parents.size === 1 ? [...parents][0] : undefined,
+            sessions: rows,
+            maxTs: rowTs(rows[0]),
+            firstSpawnTs: rows.map(spawnTs).sort()[0],
+        });
+    }
+    // Newest-active team first; the no-team bucket always sinks to the bottom.
+    groups.sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === 'noTeam' ? 1 : -1;
+        return a.maxTs < b.maxTs ? 1 : a.maxTs > b.maxTs ? -1 : a.key.localeCompare(b.key);
+    });
+    return groups;
+}

package/dist/lib/session/types.d.ts

@@ -117,6 +117,24 @@ export interface TeamOrigin {
      * meta dir has aged past the teams cleanup window.
      */
     parentSessionId?: string;
+    /**
+     * Spawn time (`started_at` in the teammate meta.json) — when `agents teams`
+     * launched this teammate. Distinct from the session's own `timestamp` (first
+     * transcript line), and present even before the harness writes a transcript.
+     * Absent for the entrypoint-only fallback (no meta record).
+     */
+    startedAt?: string;
+    /**
+     * How this origin was established, which is what separates a real
+     * `agents teams` teammate from a plain SDK sub-agent (a `Task` / `Agent()`
+     * spawn). Both carry the `sdk-cli` entrypoint that sets `isTeamOrigin`, so the
+     * entrypoint flag alone cannot tell them apart — only a teammate has a
+     * `meta.json` under the teams agents dir.
+     *   - `'meta'`     — a teammate: read from its `meta.json` record.
+     *   - `'entrypoint'` — an SDK spawn with no team record (a sub-agent, or a
+     *                      teammate whose meta dir aged past the cleanup window).
+     */
+    source?: 'meta' | 'entrypoint';
 }
 /** Lightweight metadata for a discovered session, used in listings and pickers. */
 export interface SessionMeta {
@@ -144,8 +162,23 @@ export interface SessionMeta {
     tokenCount?: number;
     /** Real generated (output) tokens — excludes cache-read/-write context (issue: `agents output`). */
     outputTokens?: number;
+    /**
+     * Uncached input tokens, cache-read tokens, and cache-write (cache-creation)
+     * tokens — the burn split `agents output` reports, kept only for harnesses that
+     * record a per-message cache split (Claude/Codex/Gemini/Droid). Undefined for
+     * harnesses that expose no split (RUSH-2287).
+     */
+    inputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
     /** Total USD cost, computed at scan time from per-model token usage (issue #323). */
     costUsd?: number;
+    /**
+     * USD cost priced as if caching were off — cache read/write billed at the full
+     * input rate. Backs `agents output --pricing no-cache` (RUSH-2287). Undefined
+     * when the harness records no cache split (then no-cache == actual by definition).
+     */
+    costUsdNoCache?: number;
     /** Wall-clock duration in ms (lastTs − firstTs), persisted at scan time. */
     durationMs?: number;
     /** Underlying LLM model observed in the transcript, when the agent records one. */

package/dist/lib/smart-launch.d.ts

@@ -1,11 +1,13 @@
 /**
- * Device affinity for `--device auto` / `--host auto`.
+ * Device placement for `--device auto` / `--host auto`.
  *
- * Picks a host from 14d session usage (launches by machine), weighted sample
- * among online devices. Most-used has highest probability — not a hard lock.
+ * Explicit auto placement probes live fleet health and harness readiness.
+ * Historical affinity remains for generic host resolution callers.
  * Account selection is separate (`--strategy balanced` / rotate.ts).
  */
 import { type AffinityRow } from './session/db.js';
+import { type DevicePlacementSignal } from './teams/scheduler.js';
+import type { AgentType } from './teams/agents.js';
 /** Peakiness of usage weights; >1 amplifies the most-used option. */
 export declare const DEFAULT_AFFINITY_ALPHA = 1.3;
 export interface WeightedCandidate {
@@ -45,6 +47,29 @@ export interface DeviceAffinityPlan {
     deviceCandidates: WeightedCandidate[];
     pickedDeviceKey: string | null;
 }
+/** Live placement plan used by the explicit `--device auto` surface. */
+export interface DeviceAutoPlan {
+    /** null means the local machine won the comparison. */
+    host: string | null;
+    candidates: Array<{
+        key: string;
+        loadPercent?: number;
+        installed?: boolean;
+        signedIn?: boolean;
+    }>;
+    pickedDeviceKey: string;
+}
+/**
+ * Pick the least-loaded healthy device that can run `agent` when the harness is
+ * known. `run auto` omits the agent and ranks the same live health/load signals
+ * without an installed-harness filter. The local machine participates in the
+ * same probe; a fully unusable fleet degrades to local instead of stranding a run.
+ */
+export declare function resolveDeviceAuto(agent?: string, opts?: {
+    eligibleHosts?: string[];
+    localMachine?: string;
+    probe?: (pool: string[], agent?: AgentType) => Promise<Map<string, DevicePlacementSignal>>;
+}): Promise<DeviceAutoPlan>;
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
  */
@@ -81,6 +106,7 @@ export type DeviceAutoApplyResult = {
  * returns `skipped` — never throws; callers must not hard-exit.
  */
 export declare function applyDeviceAutoToOptions(options: DeviceAutoHostOptions, deps?: {
-    resolve?: () => DeviceAffinityPlan;
+    resolve?: () => DeviceAutoPlan | Promise<DeviceAutoPlan>;
+    agent?: string;
     accountPickerRequested?: boolean;
-}): DeviceAutoApplyResult;
+}): Promise<DeviceAutoApplyResult>;

package/dist/lib/smart-launch.js

@@ -1,14 +1,16 @@
 /**
- * Device affinity for `--device auto` / `--host auto`.
+ * Device placement for `--device auto` / `--host auto`.
  *
- * Picks a host from 14d session usage (launches by machine), weighted sample
- * among online devices. Most-used has highest probability — not a hard lock.
+ * Explicit auto placement probes live fleet health and harness readiness.
+ * Historical affinity remains for generic host resolution callers.
  * Account selection is separate (`--strategy balanced` / rotate.ts).
  */
 import { queryAffinityRollup } from './session/db.js';
 import { localMachineId } from './session/origin-machine.js';
 import { loadDevicesSync } from './devices/registry.js';
 import { normalizeHost } from './machine-id.js';
+import { probePoolSignals } from './teams/placement-probe.js';
+import { pickBestDevice } from './teams/scheduler.js';
 /** Peakiness of usage weights; >1 amplifies the most-used option. */
 export const DEFAULT_AFFINITY_ALPHA = 1.3;
 /**
@@ -62,6 +64,39 @@ export function listOnlineDeviceNames(localName = localMachineId()) {
     }
     return [...names];
 }
+/**
+ * Pick the least-loaded healthy device that can run `agent` when the harness is
+ * known. `run auto` omits the agent and ranks the same live health/load signals
+ * without an installed-harness filter. The local machine participates in the
+ * same probe; a fully unusable fleet degrades to local instead of stranding a run.
+ */
+export async function resolveDeviceAuto(agent, opts = {}) {
+    const local = normalizeHost(opts.localMachine ?? localMachineId());
+    const pool = [...new Set((opts.eligibleHosts ?? listOnlineDeviceNames(local)).map(normalizeHost))];
+    if (!pool.includes(local))
+        pool.push(local);
+    try {
+        const signals = await (opts.probe ?? probePoolSignals)(pool, agent);
+        const picked = pickBestDevice(pool, [], { signals, agentLabel: agent });
+        return {
+            host: picked === local ? null : picked,
+            pickedDeviceKey: picked,
+            candidates: pool.map((key) => ({
+                key,
+                loadPercent: signals.get(key)?.loadPercent,
+                installed: signals.get(key)?.installed,
+                signedIn: signals.get(key)?.signedIn,
+            })),
+        };
+    }
+    catch {
+        return {
+            host: null,
+            pickedDeviceKey: local,
+            candidates: [{ key: local }],
+        };
+    }
+}
 /**
  * Resolve host for `--device auto`. Does NOT pick harness or accounts.
  */
@@ -120,7 +155,7 @@ const HOST_SLOTS = ['host', 'device', 'on', 'computer'];
  * Mutates `options` in place. On affinity failure, clears auto slots (local) and
  * returns `skipped` — never throws; callers must not hard-exit.
  */
-export function applyDeviceAutoToOptions(options, deps = {}) {
+export async function applyDeviceAutoToOptions(options, deps = {}) {
     let deprecationSmart = false;
     if (options.smart) {
         const anyHost = HOST_SLOTS.some((k) => typeof options[k] === 'string' && options[k].trim() !== '');
@@ -133,7 +168,8 @@ export function applyDeviceAutoToOptions(options, deps = {}) {
         return { attempted: false, deprecationSmart };
     }
     try {
-        const plan = (deps.resolve ?? (() => resolveDeviceAffinity({})))();
+        const resolve = deps.resolve ?? (() => resolveDeviceAuto(deps.agent));
+        const plan = await resolve();
         const concrete = plan.host; // null = local
         for (const k of HOST_SLOTS) {
             if (isDeviceAuto(options[k])) {
@@ -145,9 +181,9 @@ export function applyDeviceAutoToOptions(options, deps = {}) {
             options.balanced = true;
         }
         const hostLabel = concrete ?? 'local';
-        const deviceHint = plan.deviceCandidates
+        const deviceHint = plan.candidates
             .slice(0, 4)
-            .map((c) => `${c.key}:${c.launches}`)
+            .map((c) => `${c.key}:${c.loadPercent === undefined ? '?' : `${Math.round(c.loadPercent)}%`}`)
             .join(', ');
         const acctNote = accountPickerRequested ? 'accounts=picker' : 'accounts=balanced';
         return {

package/dist/lib/ssh-exec.d.ts

@@ -28,6 +28,31 @@ export declare function shellQuote(s: string): string;
  * long-lived `-N` tunnel can't leave a zombie ssh + socket pinned on the laptop.
  */
 export declare const SSH_OPTS: readonly string[];
+/**
+ * Hard ceiling on the stdout one peer may return before its capture is aborted.
+ * A cross-machine fan-out streams every peer's `agents … --json` into memory in
+ * parallel, so an unbounded buffer means one runaway peer (a corrupt or
+ * pathologically large payload) can exhaust the caller's heap and take the whole
+ * sweep down with it — RUSH-2065 observed ~170MB retained across a single
+ * `--active` gather. 16 MiB is far above any legitimate JSON listing yet small
+ * enough that N peers in flight stay bounded. A peer that overflows is treated as
+ * unreachable rather than trusted with partial output.
+ */
+export declare const REMOTE_STDOUT_MAX_BYTES: number;
+/**
+ * Accumulate SSH stdout as UTF-8 without corrupting a multi-byte code point that
+ * a chunk boundary splits — the streaming `on('data')` callbacks hand us raw
+ * `Buffer`s, and a naive `buf.toString()` per chunk mangles any character the
+ * kernel cut in half. `StringDecoder` holds the trailing partial bytes until the
+ * next chunk completes them.
+ */
+export declare class RemoteUtf8Accumulator {
+    private readonly decoder;
+    private value;
+    write(chunk: Buffer): void;
+    end(): string;
+    current(): string;
+}
 export declare function controlOpts(): string[];
 /**
  * Compose an ssh connection-option prefix.
@@ -128,6 +153,8 @@ export interface SshStreamOptions {
      * interactive credential-copy path (RUSH-1767).
      */
     hostKeyOpts?: string[];
+    /** Additional OpenSSH argv placed before the target (for example `-i <path>`). */
+    extraSshArgs?: string[];
 }
 /**
  * Foreground counterpart to `sshExec`: run `remoteCmd` on `target` with the

package/dist/lib/ssh-exec.js

@@ -8,6 +8,7 @@
  * canonical definition; `commands/secrets.ts` re-exports it.
  */
 import { spawn, spawnSync } from 'child_process';
+import { StringDecoder } from 'string_decoder';
 import * as fs from 'fs';
 import * as path from 'path';
 import { getCacheDir } from './state.js';
@@ -46,6 +47,38 @@ export const SSH_OPTS = [
     '-o', 'ServerAliveInterval=15',
     '-o', 'ServerAliveCountMax=3',
 ];
+/**
+ * Hard ceiling on the stdout one peer may return before its capture is aborted.
+ * A cross-machine fan-out streams every peer's `agents … --json` into memory in
+ * parallel, so an unbounded buffer means one runaway peer (a corrupt or
+ * pathologically large payload) can exhaust the caller's heap and take the whole
+ * sweep down with it — RUSH-2065 observed ~170MB retained across a single
+ * `--active` gather. 16 MiB is far above any legitimate JSON listing yet small
+ * enough that N peers in flight stay bounded. A peer that overflows is treated as
+ * unreachable rather than trusted with partial output.
+ */
+export const REMOTE_STDOUT_MAX_BYTES = 16 * 1024 * 1024;
+/**
+ * Accumulate SSH stdout as UTF-8 without corrupting a multi-byte code point that
+ * a chunk boundary splits — the streaming `on('data')` callbacks hand us raw
+ * `Buffer`s, and a naive `buf.toString()` per chunk mangles any character the
+ * kernel cut in half. `StringDecoder` holds the trailing partial bytes until the
+ * next chunk completes them.
+ */
+export class RemoteUtf8Accumulator {
+    decoder = new StringDecoder('utf8');
+    value = '';
+    write(chunk) {
+        this.value += this.decoder.write(chunk);
+    }
+    end() {
+        this.value += this.decoder.end();
+        return this.value;
+    }
+    current() {
+        return this.value;
+    }
+}
 /**
  * OpenSSH connection-multiplexing options. The first connection to a host opens
  * a control socket; subsequent connections (even from a *separate* `agents`
@@ -292,7 +325,7 @@ export function sshStream(target, remoteCmd, opts = {}) {
     assertValidSshTarget(target);
     const mux = opts.multiplex === false ? [] : controlOpts();
     const tty = opts.tty ? ['-tt'] : [];
-    const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...tty, target, remoteCmd];
+    const args = [...sshConnectOpts(mux, opts.hostKeyOpts), ...(opts.extraSshArgs ?? []), ...tty, target, remoteCmd];
     const res = spawnSync('ssh', args, { stdio: 'inherit' });
     if (typeof res.status === 'number')
         return res.status;

package/dist/lib/ssh-tunnel.d.ts

@@ -27,13 +27,14 @@ export interface StartTunnelOptions {
      * of one CDP session and kills it on cleanup.
      */
     detached?: boolean;
+    extraSshArgs?: string[];
 }
 /** Build the ssh argv (after the `ssh` program name) for an `-L` tunnel. Pure.
  *
  * Composes the shared hardened baseline (`SSH_OPTS`) rather than re-listing it,
  * so the tunnel inherits the same options — crucially the keepalive, which lets
  * a dropped `-N` tunnel exit instead of lingering as a zombie on the laptop. */
-export declare function buildTunnelArgs(user: string, host: string, localPort: number, remotePort: number): string[];
+export declare function buildTunnelArgs(user: string, host: string, localPort: number, remotePort: number, extraSshArgs?: string[]): string[];
 /**
  * Spawn `ssh -L localPort:127.0.0.1:remotePort -N user@host`.
  *
@@ -151,7 +152,7 @@ export declare function scpRemotePath(remotePath: string): string;
  * assert the real binary copy path keeps BatchMode and does not route bytes
  * through a PowerShell decoder.
  */
-export declare function buildScpArgs(target: string, remotePath: string, filePath: string): string[];
+export declare function buildScpArgs(target: string, remotePath: string, filePath: string, extraSshArgs?: string[]): string[];
 /**
  * `setup --host`: push the exe, then register + start the LOGON task. Remote
  * PowerShell hops go through `sshExec` (BatchMode key auth — the same hardening