@phnx-labs/agents-cli 1.22.26 → 1.22.28

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

@@ -21,11 +21,25 @@
  *     the raw file count rather than quietly differing.
  */
 import type { SessionEvent } from './types.js';
+/**
+ * Minimum quiet time after the assistant's last event before a user message
+ * is classified as an **agent silent stall**: the model went quiet on its own
+ * and sat idle until the human resumed. Shorter gaps are normal turn-taking.
+ * 5 minutes is long enough to exclude "user typing the next instruction" and
+ * short enough to catch "went silent mid-task until I said continue."
+ */
+export declare const SILENT_STALL_SECONDS = 300;
 /** Behavioural facets of one session. Serialized as JSON into `session_insights`. */
 export interface InsightFacets {
     toolCounts: Record<string, number>;
     /** Per-model assistant turn counts. `/insights` has no model dimension at all. */
     models: Record<string, number>;
+    /**
+     * Silent stalls attributed to the model that last spoke before the idle gap
+     * (from the nearest preceding `usage`/message model tag). Some models go
+     * quiet more often — this is the laziness split. Key = shortened model id.
+     */
+    silentStallsByModel: Record<string, number>;
     languages: Record<string, number>;
     /** Slash commands the user invoked, by name. */
     slashCommands: Record<string, number>;
@@ -84,6 +98,11 @@ export interface InsightFacets {
  * can be re-bucketed for a different display timezone without re-parsing.
  */
 export declare function computeInsightFacets(events: SessionEvent[], timezoneOffsetMinutes?: number): InsightFacets;
+/**
+ * Classify a long quiet gap after the assistant's last event as an agent silent stall.
+ * Optionally also marks an explicit resume nudge ("continue", …) after that silence.
+ */
+export declare function classifySilentStall(gapSeconds: number, userText: string, friction: Record<string, number>, corrections: Record<string, number>): void;
 /** Percentile of a numeric sample, nearest-rank. Returns 0 for an empty sample. */
 export declare function percentile(values: number[], p: number): number;
 /** Bucket response gaps for display. Returns every bucket, including empty ones. */

package/dist/lib/session/insights.js

@@ -47,18 +47,35 @@ const ERROR_CATEGORIES = [
     [['exit code', 'command failed', 'error:'], 'Command Failed'],
 ];
 /**
- * Gaps longer than this are someone leaving and coming back, not a reply latency.
- * Counted separately rather than silently dropped.
+ * Gaps longer than this leave the reply-latency percentiles (someone left for
+ * lunch / overnight). They still count as silent stalls when the assistant
+ * was the last speaker — the agent had already stopped before the user left.
  */
 const GAP_CEILING_SECONDS = 3600;
+/**
+ * Minimum quiet time after the assistant's last event before a user message
+ * is classified as an **agent silent stall**: the model went quiet on its own
+ * and sat idle until the human resumed. Shorter gaps are normal turn-taking.
+ * 5 minutes is long enough to exclude "user typing the next instruction" and
+ * short enough to catch "went silent mid-task until I said continue."
+ */
+export const SILENT_STALL_SECONDS = 300;
 /** Response-gap buckets, in ascending order. Upper bound is exclusive. */
 const GAP_BUCKETS = [
     ['<10s', 10], ['10-30s', 30], ['30s-1m', 60], ['1-2m', 120],
     ['2-5m', 300], ['5-15m', 900], ['15-60m', Infinity],
 ];
+/** Silent-stall duration buckets (agent idle after its last event). */
+const SILENT_STALL_BUCKETS = [
+    // label, min inclusive, max exclusive (Infinity = open)
+    ['silent stall: 5-15m', 300, 900],
+    ['silent stall: 15-60m', 900, 3600],
+    ['silent stall: 1h+', 3600, Infinity],
+];
 function emptyFacets() {
     return {
-        toolCounts: {}, models: {}, languages: {}, slashCommands: {}, errorCategories: {},
+        toolCounts: {}, models: {}, silentStallsByModel: {}, languages: {},
+        slashCommands: {}, errorCategories: {},
         interruptions: 0, responseGaps: [], gapsOverCeiling: 0,
         linesTouchedBefore: 0, linesTouchedAfter: 0, editingToolCalls: 0,
         filesCreated: 0, filesModified: 0, filesDeleted: 0, gitCommits: 0, gitPushes: 0,
@@ -142,10 +159,18 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
     // reported p50 by 63% (143s against a true 88s), because fast replies are common and
     // dropping them all shifts the median right. A 0-second reply is a real reply.
     //
-    // The upper bound stays: past an hour the user went away and came back, which is not
-    // a reply latency. It censors 5.5% of gaps, and `gapsOverCeiling` reports how many so
-    // the number is never quietly truncated.
+    // The upper bound stays for *percentiles only*: past an hour the user often left the
+    // desk, which is not "reply latency." Those gaps still feed silent-stall classification
+    // (the agent had already stopped). `gapsOverCeiling` reports how many so percentiles
+    // are never quietly truncated.
+    //
+    // Silent stall (agent idle): when the gap after the assistant's last event is long
+    // enough that the model clearly stopped mid-session and waited for a human nudge
+    // ("continue", "keep going", or any later message after minutes of silence). This is
+    // the inverse framing of reply latency: same timestamps, attributed to the agent.
     let lastAssistantTs = null;
+    /** Shortened model id of the last assistant activity (for stall attribution). */
+    let lastAssistantModel = null;
     let lastFailedTool = null;
     for (const e of events) {
         const ts = new Date(e.timestamp).getTime();
@@ -157,8 +182,14 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
             case 'usage':
                 // shortenModel so the label matches `agents sessions <id>` and `insights mix`
                 // rather than printing the raw id beside their shortened one.
-                if (e.model)
-                    bump(f.models, shortenModel(e.model));
+                if (e.model) {
+                    const m = shortenModel(e.model);
+                    bump(f.models, m);
+                    // Usage rows are the reliable model tag for Claude turns; keep as
+                    // "last model" even when the timestamp is missing so a following
+                    // tool_use still attributes a stall correctly.
+                    lastAssistantModel = m;
+                }
                 break;
             case 'error':
                 bump(f.errorCategories, categorizeError(e.content ?? e.output ?? ''));
@@ -175,12 +206,18 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                 if (e.role === 'assistant') {
                     if (hasTs)
                         lastAssistantTs = ts;
+                    if (e.model)
+                        lastAssistantModel = shortenModel(e.model);
                     break;
                 }
                 if (e.role !== 'user')
                     break;
-                if (!e._synthetic)
-                    classifyCorrection(e.content ?? '', f.correctionSignals);
+                // Synthetic user rows (stop-hook feedback, injected meta) are not a human
+                // resume — skip correction/stall classification and leave lastAssistantTs so
+                // the next real user message still measures the full idle gap.
+                if (e._synthetic)
+                    break;
+                classifyCorrection(e.content ?? '', f.correctionSignals);
                 if (hasTs) {
                     // Local-time hour. parse.ts falls back to `new Date()` for a record with no
                     // timestamp; those are indistinguishable here, but they are rare and would
@@ -196,6 +233,11 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                             f.responseGaps.push(gap);
                         else if (gap >= GAP_CEILING_SECONDS)
                             f.gapsOverCeiling++;
+                        // Agent silent stall: model stopped; session sat idle until this message.
+                        if (gap >= SILENT_STALL_SECONDS) {
+                            classifySilentStall(gap, e.content ?? '', f.frictionSignals, f.correctionSignals);
+                            bump(f.silentStallsByModel, lastAssistantModel ?? 'unknown');
+                        }
                     }
                 }
                 lastAssistantTs = null;
@@ -207,6 +249,8 @@ export function computeInsightFacets(events, timezoneOffsetMinutes = new Date().
                     break;
                 if (hasTs)
                     lastAssistantTs = ts;
+                if (e.model)
+                    lastAssistantModel = shortenModel(e.model);
                 const args = e.args ?? {};
                 const toolName = e.tool ?? '';
                 if (/askuserquestion/i.test(toolName))
@@ -257,6 +301,24 @@ const CORRECTION_PATTERNS = [
     [/\b(?:check now|check again|try now|did it work)\b/i, 'check now'],
     [/\b(?:don'?t ask|just do it|run what)\b/i, "don't ask / just do it"],
 ];
+/** User text that is a pure resume nudge after the agent went silent. */
+const RESUME_NUDGE_PATTERN = /\b(?:continue|keep going|don'?t stop|resume|pick up|you stopped|still there|wake up|hello\??|are you (?:there|stuck)|go on)\b/i;
+/**
+ * Classify a long quiet gap after the assistant's last event as an agent silent stall.
+ * Optionally also marks an explicit resume nudge ("continue", …) after that silence.
+ */
+export function classifySilentStall(gapSeconds, userText, friction, corrections) {
+    for (const [label, min, max] of SILENT_STALL_BUCKETS) {
+        if (gapSeconds >= min && gapSeconds < max) {
+            bump(friction, label);
+            break;
+        }
+    }
+    const normalized = userText.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    if (normalized && RESUME_NUDGE_PATTERN.test(normalized)) {
+        bump(corrections, 'resume after silent stall');
+    }
+}
 const AUTOMATION_PATTERNS = [
     [/\bgh pr (?:checks|view|merge)\b/i, 'PR babysitting'],
     [/\bagents secrets (?:list|exec|unlock|export)\b/i, 'secrets unlock dance'],
@@ -360,6 +422,8 @@ export function mergeFacets(into, add) {
         bump(into.toolCounts, k, v);
     for (const [k, v] of Object.entries(add.models))
         bump(into.models, k, v);
+    for (const [k, v] of Object.entries(add.silentStallsByModel ?? {}))
+        bump(into.silentStallsByModel, k, v);
     for (const [k, v] of Object.entries(add.languages))
         bump(into.languages, k, v);
     for (const [k, v] of Object.entries(add.slashCommands))
@@ -406,6 +470,7 @@ export function topEntries(counts, limit) {
 export function buildInsightActions(sessions) {
     const specs = [
         { source: 'correctionSignals', label: 'continue / keep going', category: 'rule', action: 'Keep working through the delivery chain without waiting for another “continue”.' },
+        { source: 'correctionSignals', label: 'resume after silent stall', category: 'rule', action: 'Never stop mid-task waiting for a human ping — finish the current goal or park with an explicit blocker; keep driving CI/review/merge without going idle.' },
         { source: 'correctionSignals', label: 'approval repeated', category: 'rule', action: 'Treat the original build or ship request as authorization for routine follow-through.' },
         { source: 'correctionSignals', label: 'done end-to-end?', category: 'rule', action: 'Verify the user-visible outcome before declaring the task complete.' },
         { source: 'correctionSignals', label: 'did you merge?', category: 'automation', action: 'Automate PR review, CI watching, and merge-on-green as one durable workflow.' },
@@ -416,6 +481,9 @@ export function buildInsightActions(sessions) {
         { source: 'correctionSignals', label: "Ask stall: what's next?", category: 'rule', action: 'Remove workflow-stall “what next?” prompts from agent guidance.' },
         { source: 'correctionSignals', label: 'Ask stall: merge / reconcile', category: 'skill', action: 'Encode the safe merge and reconcile path in the git workflow skill.' },
         { source: 'correctionSignals', label: 'Ask stall: direction / approach', category: 'rule', action: 'Let agents choose implementation details after scope is clear.' },
+        { source: 'frictionSignals', label: 'silent stall: 5-15m', category: 'rule', action: 'Stop ending turns while work remains open — after a tool batch, take the next step or schedule a real background wait that re-invokes you; do not sit idle until the user says continue.' },
+        { source: 'frictionSignals', label: 'silent stall: 15-60m', category: 'rule', action: 'Long idle after the assistant last spoke is an agent stop, not a user pause — drive open PRs/CI/todos to completion or name a true external blocker instead of going silent.' },
+        { source: 'frictionSignals', label: 'silent stall: 1h+', category: 'rule', action: 'Sessions that sit idle for an hour+ after the model stops are stranded work — use stop-gates, background watches, and queue drain so a human is not the only resume signal.' },
         { source: 'frictionSignals', label: 'blocked guard', category: 'product', action: 'Make guard failures return the safe next command and exact blocked operation.' },
         { source: 'frictionSignals', label: 'CI red loop', category: 'automation', action: 'Deduplicate CI watchers and turn repeated red checks into one stateful wait.' },
         { source: 'frictionSignals', label: 'merge conflict', category: 'skill', action: 'Standardize conflict diagnosis and fix-forward reconciliation.' },

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

@@ -5,6 +5,7 @@ export type SessionRecoveryTarget = {
     mode: 'native';
     agent: AgentId;
     version: string;
+    cwd?: string;
     reason: string;
 } | {
     mode: 'continue';
@@ -12,6 +13,13 @@ export type SessionRecoveryTarget = {
     version: string;
     reason: string;
 };
+export type NativeResumeInspection = {
+    available: true;
+    cwd?: string;
+} | {
+    available: false;
+    reason: string;
+};
 export declare class SessionRecoveryError extends Error {
     constructor(message: string);
 }
@@ -21,6 +29,14 @@ export declare function sessionOriginDevice(session: Pick<SessionMeta, 'machine'
 export declare function sessionRecoveryPeer(session: Pick<SessionMeta, 'machine'>, selfCheck?: (host: string) => boolean): string | undefined;
 /** Whether an explicit placement names the session's origin device. */
 export declare function sessionRecoveryDestinationMatches(session: Pick<SessionMeta, 'machine'>, requestedHost: string, self?: string): boolean;
+/**
+ * Prove that the indexed transcript is reachable from the exact active version
+ * home that would receive native resume. Retained trash/backup transcripts are
+ * intentionally rejected here: they remain readable by `/continue`, but a new
+ * installation with the same version number must not native-resume an empty
+ * isolated home.
+ */
+export declare function inspectNativeResumeSession(session: SessionMeta, versionHome: string): NativeResumeInspection;
 /**
  * Decide how a durable session resumes on the device that owns it.
  *
@@ -29,7 +45,7 @@ export declare function sessionRecoveryDestinationMatches(session: Pick<SessionM
  * same harness and uses `/continue`, whose indexed transcript reader can reach
  * retained version trash. No healthy same-harness account is a loud failure.
  */
-export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean): SessionRecoveryTarget;
+export declare function resolveSessionRecoveryFromCandidates(session: SessionMeta, candidates: RotateCandidate[], supportsNative?: (agent: AgentId, version?: string) => boolean, nativeInspection?: NativeResumeInspection): SessionRecoveryTarget;
 export declare function resolveSessionRecovery(session: SessionMeta): Promise<SessionRecoveryTarget>;
 /** Stable self-command used by focus, resume, and attach. The owning device runs
  * the recovery resolver above; callers must not native-resume another version's

package/dist/lib/session/recovery.js

@@ -1,8 +1,11 @@
-import { AGENTS } from '../agents.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS, agentConfigDirName } from '../agents.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { nativeResume } from '../exec.js';
 import { machineId, normalizeHost } from '../machine-id.js';
 import { collectRunCandidates, formatNoHealthyAccountError, pickBalancedCandidate, readinessFromCandidate, } from '../rotate.js';
+import { getVersionHomePath } from '../versions.js';
 export class SessionRecoveryError extends Error {
     constructor(message) {
         super(message);
@@ -41,6 +44,99 @@ function sourceReason(session, candidates) {
         ? `origin ${session.agent}@${session.version} has no native resume form`
         : `origin ${session.agent}@${session.version} is ${readiness.reason}`;
 }
+function isPathInside(candidate, dir) {
+    const rel = path.relative(dir, candidate);
+    return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+function existingDirectory(dir) {
+    if (!dir)
+        return undefined;
+    try {
+        return fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory() ? dir : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the launch cwd Claude used to choose its projects/<cwd-key> directory.
+ * Claude can record attachment envelopes before the first user turn, and those
+ * envelopes retain the actual launch cwd even after the session changes dirs. */
+function readClaudeLaunchCwd(filePath) {
+    const maxBytes = 2 * 1024 * 1024;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const chunk = Buffer.alloc(maxBytes);
+        const bytesRead = fs.readSync(fd, chunk, 0, maxBytes, 0);
+        const lines = chunk.toString('utf8', 0, bytesRead).split('\n');
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed?.cwd !== 'string' || !path.isAbsolute(parsed.cwd))
+                    continue;
+                if (existingDirectory(parsed.cwd))
+                    return parsed.cwd;
+            }
+            catch {
+                // A malformed line or vanished cwd cannot identify a usable native home.
+            }
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return undefined;
+}
+/**
+ * Prove that the indexed transcript is reachable from the exact active version
+ * home that would receive native resume. Retained trash/backup transcripts are
+ * intentionally rejected here: they remain readable by `/continue`, but a new
+ * installation with the same version number must not native-resume an empty
+ * isolated home.
+ */
+export function inspectNativeResumeSession(session, versionHome) {
+    let realFile;
+    try {
+        realFile = fs.realpathSync(session.filePath);
+    }
+    catch {
+        return { available: false, reason: 'the indexed transcript is no longer present in the origin home' };
+    }
+    const roots = [versionHome, path.join(versionHome, agentConfigDirName(session.agent))];
+    const owned = roots.some((root) => {
+        try {
+            return isPathInside(realFile, fs.realpathSync(root));
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!owned) {
+        return {
+            available: false,
+            reason: `the indexed transcript is retained outside the active ${session.agent}@${session.version ?? 'unknown'} home`,
+        };
+    }
+    if (session.agent === 'claude') {
+        const cwd = readClaudeLaunchCwd(realFile);
+        if (!cwd) {
+            return {
+                available: false,
+                reason: 'the Claude transcript does not identify an existing original project directory',
+            };
+        }
+        return { available: true, cwd };
+    }
+    const cwd = existingDirectory(session.cwd);
+    return { available: true, cwd };
+}
 /**
  * Decide how a durable session resumes on the device that owns it.
  *
@@ -49,7 +145,7 @@ function sourceReason(session, candidates) {
  * same harness and uses `/continue`, whose indexed transcript reader can reach
  * retained version trash. No healthy same-harness account is a loud failure.
  */
-export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume) {
+export function resolveSessionRecoveryFromCandidates(session, candidates, supportsNative = nativeResume, nativeInspection) {
     const agent = runnableSessionAgent(session);
     const device = sessionOriginDevice(session);
     const source = session.version
@@ -69,11 +165,22 @@ export function resolveSessionRecoveryFromCandidates(session, candidates, suppor
     }
     const version = selection.picked.version;
     if (session.version === version && supportsNative(agent, version)) {
+        const inspection = nativeInspection
+            ?? inspectNativeResumeSession(session, getVersionHomePath(agent, version));
+        if (inspection.available) {
+            return {
+                mode: 'native',
+                agent,
+                version,
+                cwd: inspection.cwd,
+                reason: `origin ${agent}@${version} is installed, healthy, and owns the indexed transcript`,
+            };
+        }
         return {
-            mode: 'native',
+            mode: 'continue',
             agent,
             version,
-            reason: `origin ${agent}@${version} is installed and healthy`,
+            reason: `${inspection.reason}; continuing with healthy ${agent}@${version}`,
         };
     }
     return {

package/dist/lib/session/remote-bundle.js

@@ -40,7 +40,7 @@ export async function pullBundlesFromHosts(hosts, exportArgs) {
     for (const t of targets) {
         const cmd = remoteAgentsCommand(['sessions', 'export', ...exportArgs, '--stdout'], t.os);
         process.stderr.write(chalk.dim(`Pulling sessions from ${t.name}…\n`));
-        const res = sshExec(t.target, cmd, { timeoutMs: REMOTE_EXPORT_TIMEOUT_MS });
+        const res = sshExec(t.target, cmd, { timeoutMs: REMOTE_EXPORT_TIMEOUT_MS, extraSshArgs: t.extraSshArgs });
         if (res.timedOut) {
             errors.push(`${t.name}: timed out after ${Math.round(REMOTE_EXPORT_TIMEOUT_MS / 1000)}s`);
             continue;

package/dist/lib/session/remote-list.d.ts

@@ -2,20 +2,12 @@ import { type DeviceProfile } from '../devices/registry.js';
 import { type RemoteAgentsJsonParseResult } from '../remote-agents-json.js';
 import type { SessionMeta } from './types.js';
 import { type ToolProgramCountEnvelope, type ToolSearchEnvelope } from './tool-index.js';
-export declare const REMOTE_STDOUT_MAX_BYTES: number;
+export { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../ssh-exec.js';
 export declare const REMOTE_TOOL_AGGREGATE_MAX_BYTES: number;
 export interface RemoteToolByteBudget {
     remainingBytes: number;
     exhausted: boolean;
 }
-/** Preserve UTF-8 code points when SSH splits them across stdout chunks. */
-export declare class RemoteUtf8Accumulator {
-    private readonly decoder;
-    private value;
-    write(chunk: Buffer): void;
-    end(): string;
-    current(): string;
-}
 /** Claim received bytes against one fleet-query budget before retaining them. */
 export declare function consumeRemoteToolByteBudget(budget: RemoteToolByteBudget, bytes: number): boolean;
 /** Charge sanitized, machine-stamped evidence because redaction may expand it. */
@@ -130,7 +122,16 @@ export declare function resolvePeerTarget(machine: string): Promise<{
  * not via a local `--host` hop, which would discover locally and dead-end for a
  * session that exists only on the peer. Resolves 'no-target' when the machine
  * isn't a dialable registered device; the caller surfaces a clear message.
+ *
+ * `opts.env` adds variables to the remote command. It deliberately does NOT
+ * carry `AGENTS_FLEET_REMOTE` the way the `--host` passthrough does: that marker
+ * gates consent-sensitive actions on the far side
+ * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
+ * that would inherit it for its whole life — `agents browser start` inside it
+ * would then be refused as a cross-machine drive. A one-shot `--host` command
+ * can carry the marker; a session cannot.
  */
 export declare function runOnPeer(args: string[], machine: string, opts?: {
     tty?: boolean;
+    env?: Record<string, string>;
 }): Promise<'ok' | 'no-target'>;

package/dist/lib/session/remote-list.js

@@ -14,13 +14,12 @@
  * never fatal — one asleep laptop must not blank the list.
  */
 import { spawn } from 'child_process';
-import { StringDecoder } from 'string_decoder';
 import chalk from 'chalk';
-import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
+import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote, REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator, } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
 import { resolveExplicitTargetSet } from '../devices/resolve-target.js';
 import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
-import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { remoteShellFor, buildWindowsAgentsCommand, stripClixml } from '../hosts/remote-cmd.js';
 import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
 import { machineId, normalizeHost } from './sync/config.js';
 import { NO_FANOUT_ENV } from './remote-active.js';
@@ -30,23 +29,12 @@ import { mapBounded } from '../concurrency.js';
 import { TOOL_QUERY_MAX_CLAUSE_BYTES, TOOL_QUERY_MAX_CALL_ROWS, TOOL_QUERY_MAX_CLAUSES, TOOL_QUERY_MAX_RESULT_SESSIONS, TOOL_QUERY_MAX_SERIALIZED_BYTES, serializedToolSearchEnvelopeBytes, } from './tool-index.js';
 import { TOOL_ERROR_OUTPUT_MAX_BYTES, TOOL_INPUT_MAX_BYTES, TOOL_SUCCESS_OUTPUT_MAX_BYTES, sanitizeToolEvidenceText, } from './tool-calls.js';
 const REMOTE_TOOL_TIMEOUT_MS = 60_000;
-export const REMOTE_STDOUT_MAX_BYTES = 16 * 1024 * 1024;
+// The per-peer stdout ceiling and the UTF-8-safe accumulator live in ssh-exec.ts
+// (the shared SSH transport both this reader and the top-level `remote-agents-json`
+// fan-out import), so the bound is defined once. Re-exported here for the existing
+// consumers/tests that reach them through this module.
+export { REMOTE_STDOUT_MAX_BYTES, RemoteUtf8Accumulator } from '../ssh-exec.js';
 export const REMOTE_TOOL_AGGREGATE_MAX_BYTES = TOOL_QUERY_MAX_SERIALIZED_BYTES;
-/** Preserve UTF-8 code points when SSH splits them across stdout chunks. */
-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;
-    }
-}
 /** Claim received bytes against one fleet-query budget before retaining them. */
 export function consumeRemoteToolByteBudget(budget, bytes) {
     if (budget.exhausted || bytes > budget.remainingBytes) {
@@ -91,7 +79,7 @@ export function remoteListCommand(forwardedArgs, os) {
 export function parseRemoteList(stdout, machine) {
     let parsed;
     try {
-        parsed = JSON.parse(stdout);
+        parsed = JSON.parse(stripClixml(stdout));
     }
     catch {
         return [];
@@ -117,7 +105,7 @@ function isSafeResolverRow(value) {
 export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
     let parsed;
     try {
-        parsed = JSON.parse(stdout);
+        parsed = JSON.parse(stripClixml(stdout));
     }
     catch {
         return { items: [], valid: false };
@@ -375,6 +363,10 @@ function parseRemoteToolSession(value, machine) {
     };
 }
 export function parseRemoteToolSearch(stdout, machine, expectedClauses) {
+    // The fleet tool-search fan-out reads a raw sshCapture (not the stripped
+    // gatherRemoteAgentsJson wrapper), so a Windows peer's PowerShell CLIXML banner
+    // must be removed here too or the box reads as "no envelope" (RUSH-2286).
+    stdout = stripClixml(stdout);
     if (Buffer.byteLength(stdout) > REMOTE_STDOUT_MAX_BYTES)
         return undefined;
     try {
@@ -540,6 +532,14 @@ export async function resolvePeerTarget(machine) {
  * not via a local `--host` hop, which would discover locally and dead-end for a
  * session that exists only on the peer. Resolves 'no-target' when the machine
  * isn't a dialable registered device; the caller surfaces a clear message.
+ *
+ * `opts.env` adds variables to the remote command. It deliberately does NOT
+ * carry `AGENTS_FLEET_REMOTE` the way the `--host` passthrough does: that marker
+ * gates consent-sensitive actions on the far side
+ * (lib/browser/remote-control.ts), and a resumed agent is a long-lived session
+ * that would inherit it for its whole life — `agents browser start` inside it
+ * would then be refused as a cross-machine drive. A one-shot `--host` command
+ * can carry the marker; a session cannot.
  */
 export async function runOnPeer(args, machine, opts = {}) {
     const peer = await resolvePeerTarget(machine);
@@ -547,9 +547,11 @@ export async function runOnPeer(args, machine, opts = {}) {
         return 'no-target';
     assertValidSshTarget(peer.target); // registry-sourced, but validate like the fan-out does
     const cols = terminalWidth();
+    const env = { ...(cols > 0 ? { COLUMNS: String(cols) } : {}), ...opts.env };
+    const assignments = Object.entries(env).map(([k, v]) => `${k}=${shellQuote(v)}`);
     const remoteCmd = remoteShellFor(peer.os) === 'powershell'
-        ? buildWindowsAgentsCommand({ args, env: cols > 0 ? { COLUMNS: String(cols) } : undefined })
-        : `bash -lc ${shellQuote((cols > 0 ? [`COLUMNS=${cols}`] : []).concat(['agents', ...args].map(shellQuote)).join(' '))}`;
+        ? buildWindowsAgentsCommand({ args, env: assignments.length ? env : undefined })
+        : `bash -lc ${shellQuote(assignments.concat(['agents', ...args].map(shellQuote)).join(' '))}`;
     const sshArgs = [...SSH_OPTS, ...controlOpts()];
     if (opts.tty)
         sshArgs.push('-tt'); // force a PTY so the resumed agent is interactive

package/dist/lib/session/resume-owner.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 type { SessionMeta } from './types.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 declare 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 declare function consumeResumePinned(): boolean;
+/**
+ * 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 declare function sessionOwnerDevice(session: Pick<SessionMeta, 'machine'>): string | undefined;