@phnx-labs/agents-cli 1.22.114 → 1.22.115

package/dist/lib/computer/sessions-list.js

@@ -58,6 +58,10 @@
  * `sessionId` doesn't resolve (a rotated/unindexed session) but `launchId`
  * still does via the more authoritative pid registry.
  */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getCacheDir } from '../state.js';
+import { machineId } from '../machine-id.js';
 import { query, truncate } from '../feed/events.js';
 import { formatRelativeTime } from '../session/relative-time.js';
 import { getSessionById, listComputerSessionRecords, pruneToolSessions } from '../session/db.js';
@@ -70,6 +74,21 @@ export const TASK_PREVIEW_MAX_CHARS = 200;
  *  already reads newest-first and stops at this cutoff mid-scan, so raising
  *  it only ever costs as much as the history actually holds. */
 const DEFAULT_ACTION_LIMIT = 5000;
+/** A capture record, accepted only when the producer gave a real path + name. */
+function parseActionCapture(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    if (typeof record.path !== 'string' || !record.path)
+        return undefined;
+    const name = typeof record.name === 'string' && record.name ? record.name : path.basename(record.path);
+    return {
+        path: record.path,
+        kind: 'screenshot',
+        name,
+        ...(typeof record.bytes === 'number' ? { bytes: record.bytes } : {}),
+    };
+}
 function recordToAction(r) {
     if (typeof r.command !== 'string' || typeof r.pid !== 'number')
         return null;
@@ -91,8 +110,153 @@ function recordToAction(r) {
         agent: typeof r.agent === 'string' ? r.agent : undefined,
         machineId: typeof r.machineId === 'string' ? r.machineId : undefined,
         hostname: typeof r.hostname === 'string' ? r.hostname : undefined,
+        capture: parseActionCapture(r.capture),
     };
 }
+/**
+ * The standalone engine's OWN action ledger.
+ *
+ * `agents computer` is a thin consumer of the standalone `computer` engine
+ * (PHNX-4075), and that engine ALWAYS appends every action it performs to
+ * `<cache>/computer/actions/<day>.jsonl` — independently of whether agents-cli
+ * was in the call at all. So a `computer` command the operator ran directly
+ * appears ONLY here: it never reached `recordComputerAction`, so it is in
+ * neither the feed event ledger nor `computer_sessions`. Reading only those two
+ * meant the actions an operator actually performed were invisible to every
+ * agents-cli surface.
+ */
+export function standaloneComputerActionsDir() {
+    return path.join(getCacheDir(), 'computer', 'actions');
+}
+/**
+ * One line of the standalone ledger as a {@link ComputerAction}.
+ *
+ * The on-disk record is the same `computer.action` event the engine reports on
+ * fd 4 — the contract `computer-client.ts` `ComputerActionEvent` already
+ * describes and `recordComputerAction` already consumes — so this maps the same
+ * fields rather than inventing a second vocabulary. A record missing the two
+ * fields that make it an action at all (`command`, a parseable timestamp) is
+ * skipped, never defaulted: the file is plain JSONL another process may be
+ * mid-append to.
+ */
+function standaloneLineToAction(line, observer) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const record = parsed;
+    const verb = typeof record.command === 'string' ? record.command : undefined;
+    const ts = typeof record.ts === 'string' ? record.ts : undefined;
+    if (!verb || !ts)
+        return null;
+    const tsMs = Date.parse(ts);
+    if (Number.isNaN(tsMs))
+        return null;
+    const text = (key) => (typeof record[key] === 'string' ? record[key] : undefined);
+    const num = (key) => (typeof record[key] === 'number' ? record[key] : undefined);
+    // The producer identifies the DRIVEN host only for a remote run, and emits no
+    // `hostname`/`machineId` of its own at all. Defaulting those to the observing
+    // machine HERE, at the source, is what keeps a direct local action attributable:
+    // without it `groupIntoComputerRuns` fell back to `machine: 'unknown'`, the row's
+    // device read `unknown`, and every locally-run `computer` action vanished the
+    // moment a consumer filtered by device. The observer IS the machine that ran it
+    // — this ledger is per-machine by construction, written by the engine on the box
+    // it ran on — so the fallback is a fact, not a guess. An explicit `host` still
+    // wins, because that names a genuinely different driven machine.
+    return {
+        verb, ts, tsMs,
+        // The engine's pid is its own; a record without one still groups by
+        // invocationId, which is the identity that actually matters here.
+        pid: num('pid') ?? 0,
+        invocationId: text('invocationId'),
+        targetPid: num('targetPid'),
+        bundle: text('bundle'),
+        host: text('host'),
+        task: text('task'),
+        sessionId: text('sessionId'),
+        launchId: text('launchId'),
+        agent: text('agent'),
+        machineId: text('machineId'),
+        hostname: text('hostname') ?? observer,
+        capture: parseActionCapture(record.capture),
+    };
+}
+/**
+ * Read the standalone ledger, newest day first, bounded by `limit` actions.
+ *
+ * Bounded by construction: days are read newest-first and reading stops as soon
+ * as the budget is met, so a box with months of history costs the same as one
+ * with a day of it.
+ */
+export function listStandaloneComputerActions(opts = {}) {
+    const dir = opts.dir ?? standaloneComputerActionsDir();
+    const limit = opts.limit ?? DEFAULT_ACTION_LIMIT;
+    // This ledger is per-machine by construction, so "who ran it" is this machine
+    // unless the record names a driven remote host.
+    const observer = opts.observer ?? machineId();
+    let days;
+    try {
+        days = fs.readdirSync(dir).filter((name) => name.endsWith('.jsonl')).sort().reverse();
+    }
+    catch {
+        return []; // The engine has never run here, or is not installed.
+    }
+    const out = [];
+    for (const day of days) {
+        if (out.length >= limit)
+            break;
+        let lines;
+        try {
+            lines = fs.readFileSync(path.join(dir, day), 'utf8').split('\n');
+        }
+        catch {
+            continue; /* rotated or removed mid-read */
+        }
+        // Newest last within a day, and the budget favours the newest actions.
+        for (let index = lines.length - 1; index >= 0 && out.length < limit; index--) {
+            const line = lines[index];
+            if (!line)
+                continue;
+            const action = standaloneLineToAction(line, observer);
+            if (action)
+                out.push(action);
+        }
+    }
+    out.sort((a, b) => b.tsMs - a.tsMs);
+    return out;
+}
+/**
+ * Union the two ledgers, preferring the standalone record for any run present in
+ * both.
+ *
+ * Dedupe keys on `invocationId`, NOT on a timestamp or pid. When a command is
+ * forwarded through `agents computer`, BOTH stores receive it — and the
+ * forwarding rewrites `ts` and `pid` on the way through, so the two copies of one
+ * action do not agree on either. `invocationId` is minted by the engine and
+ * echoed unchanged, which makes it the only field that identifies the same run in
+ * both files. A legacy feed record with no invocationId cannot be matched to
+ * anything, so it is kept: dropping it would lose history the standalone ledger
+ * never had.
+ */
+export function mergeComputerActionSources(standalone, legacy) {
+    const standaloneRuns = new Set();
+    for (const action of standalone)
+        if (action.invocationId)
+            standaloneRuns.add(action.invocationId);
+    const merged = [...standalone];
+    for (const action of legacy) {
+        if (action.invocationId && standaloneRuns.has(action.invocationId))
+            continue;
+        merged.push(action);
+    }
+    merged.sort((a, b) => b.tsMs - a.tsMs);
+    return merged;
+}
 /** Read `computer.action` events straight from the durable event ledger,
  *  newest first, bounded by `limit`. Malformed/legacy records (missing
  *  `command` or `pid`, or an unparseable `ts`) are skipped, never thrown —
@@ -240,7 +404,10 @@ function appendPrunedRunsFromDb(rows, limit) {
  *  flat/`--json` printer's) data source. `machine` narrows to rows whose
  *  invoking hostname, machineId, or `--device` target contains the substring. */
 export function buildComputerSessionRows(opts = {}) {
-    const actions = listComputerActions({ limit: opts.limit });
+    const actions = mergeComputerActionSources(
+    // `observer` is threaded from the caller's scope so a row's device and the
+    // scope that reported it can never name the same box differently.
+    listStandaloneComputerActions({ limit: opts.limit, ...(opts.observer ? { observer: opts.observer } : {}) }), listComputerActions({ limit: opts.limit }));
     const index = buildLaunchSessionIndex();
     const rows = groupIntoComputerRuns(actions, (sessionId) => getSessionById(sessionId), (launchId) => resolveLaunchSession(index, launchId));
     // Retention runs here, on the listing path, never on the action hot path:

package/dist/lib/daemon/daemon.js

@@ -878,7 +878,7 @@ export async function runDaemon() {
     assertTestDaemonHome();
     // Lifecycle readers and launchers do not run services. Load their code only
     // in the daemon process, before it claims or publishes lifecycle state.
-    const [{ BrowserService }, { SessionIndexService }, { SessionSummarizerService }, { SessionTitleService }, { MonitorEngineService }, { AccountUsageService, AccountAuthService }, { CatchupService }, { BrowserIPCService }, { WatchdogService }, { DeviceProbeService }, { SelfHealService }, { SelfUpdateService }, { HarnessUpdateService }, { AuthSyncService }, { UsageSyncService }, { StateDirCheckService }, { SessionStateService }, { AttentionNotifyService }, { WebhookReceiverService }, { HeartbeatService }, { TmuxReapService }, { BrowserTaskReapService },] = await Promise.all([
+    const [{ BrowserService }, { SessionIndexService }, { SessionSummarizerService }, { SessionTitleService }, { MonitorEngineService }, { AccountUsageService, AccountAuthService }, { CatchupService }, { BrowserIPCService }, { WatchdogService }, { DeviceProbeService }, { SelfHealService }, { SelfUpdateService }, { HarnessUpdateService }, { AuthSyncService }, { UsageSyncService }, { StateDirCheckService }, { SessionStateService }, { FeedStreamService }, { AttentionNotifyService }, { WebhookReceiverService }, { HeartbeatService }, { TmuxReapService }, { BrowserTaskReapService },] = await Promise.all([
         import('../browser/service.js'),
         import('./session-index-service.js'),
         import('./session-summarizer-service.js'),
@@ -896,6 +896,7 @@ export async function runDaemon() {
         import('./usage-sync-service.js'),
         import('./state-dir-check-service.js'),
         import('./session-state-service.js'),
+        import('./feed-stream-service.js'),
         import('./attention-notify-service.js'),
         import('./webhook-receiver-service.js'),
         import('./heartbeat-service.js'),
@@ -1021,6 +1022,12 @@ export async function runDaemon() {
     }
     else
         log('INFO', 'Live session-state service disabled');
+    // The shared feed fan-out. Registered even when disabled at boot so a later
+    // `agents daemon services enable feed-stream` brings it up over SIGHUP, the
+    // same live-transition shape browser IPC uses.
+    supervisor.register(new FeedStreamService(), { enabled: isEnabled('feed-stream') });
+    if (!isEnabled('feed-stream'))
+        log('INFO', 'Shared feed stream service disabled');
     const monitorEngineSvc = new MonitorEngineService();
     if (isEnabled('monitors'))
         supervisor.register(monitorEngineSvc);

package/dist/lib/daemon/feed-stream-service.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The shared feed collector's lifecycle as a `DaemonService`.
+ *
+ * WHY THE DAEMON OWNS IT. Dialing every peer over ssh and holding those
+ * connections open is an ACTION on the fleet, so by the repo's one-scheduler /
+ * one-executor rule it belongs to the daemon and not to a UI surface. Before
+ * this service, every consumer of `agents feed watch --json` ran its own
+ * `watchFleetFeed`, which is N ssh children per peer for N readers. The daemon
+ * runs one, and the readers attach over a socket (`feed/hub-server.ts`).
+ *
+ * The server binds on start, but the fan-out itself is DEMAND-GATED by the hub:
+ * with no client connected there is no `watchFleetFeed`, so an idle box holds no
+ * peer connections — the same idle-cost rule `SessionStateService` follows for
+ * its gather.
+ */
+import { BaseDaemonService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+export declare class FeedStreamService extends BaseDaemonService {
+    readonly id: DaemonServiceId;
+    private server;
+    protected onStart(ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+}

package/dist/lib/daemon/feed-stream-service.js

@@ -0,0 +1,40 @@
+/**
+ * The shared feed collector's lifecycle as a `DaemonService`.
+ *
+ * WHY THE DAEMON OWNS IT. Dialing every peer over ssh and holding those
+ * connections open is an ACTION on the fleet, so by the repo's one-scheduler /
+ * one-executor rule it belongs to the daemon and not to a UI surface. Before
+ * this service, every consumer of `agents feed watch --json` ran its own
+ * `watchFleetFeed`, which is N ssh children per peer for N readers. The daemon
+ * runs one, and the readers attach over a socket (`feed/hub-server.ts`).
+ *
+ * The server binds on start, but the fan-out itself is DEMAND-GATED by the hub:
+ * with no client connected there is no `watchFleetFeed`, so an idle box holds no
+ * peer connections — the same idle-cost rule `SessionStateService` follows for
+ * its gather.
+ */
+import { BaseDaemonService } from './service.js';
+import { FeedHub } from '../feed/hub.js';
+import { FeedHubServer } from '../feed/hub-server.js';
+import { sharedLocalFeedHub, watchFleetFeed } from '../feed/watch.js';
+export class FeedStreamService extends BaseDaemonService {
+    id = 'feed-stream';
+    server = null;
+    async onStart(ctx) {
+        // Two collectors, one socket. The fleet hub holds one ssh child per peer plus
+        // this box's rows; the local hub is this box ONLY and cannot fan out, so a
+        // reader that wants just this machine never causes a peer dial. They are
+        // separate hubs rather than one filtered stream because demand must be
+        // separate too: a local-only reader must not start the fleet fan-out.
+        const fleet = new FeedHub({ watch: watchFleetFeed });
+        this.server = new FeedHubServer(fleet, undefined, sharedLocalFeedHub());
+        await this.server.start();
+        ctx.log('INFO', 'Feed stream hub listening (fan-out starts on first reader)');
+    }
+    async onStop() {
+        const server = this.server;
+        this.server = null;
+        if (server)
+            await server.stop();
+    }
+}

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'session-title' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer' | 'attention-notify' | 'harness-update';
+export type DaemonServiceId = 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'session-title' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'feed-stream' | 'session-summarizer' | 'attention-notify' | 'harness-update';
 /** Human-readable metadata for each service. */
 interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -92,6 +92,11 @@ export const DAEMON_SERVICES = [
         title: 'Live session state',
         description: 'Publishes this host\'s active session metadata for sessions watch and fleet consumers.',
     },
+    {
+        id: 'feed-stream',
+        title: 'Shared feed stream',
+        description: 'Owns the one fleet feed fan-out and serves it to every reader over a socket, so N consumers cost one ssh per peer instead of N.',
+    },
     {
         id: 'session-index',
         title: 'Session-index warm',

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

@@ -30,13 +30,43 @@ export declare function sshTargetFor(device: DeviceProfile): string;
  */
 export declare function fleetDialTarget(device: DeviceProfile): string;
 /**
- * Wrap a remote command for the device's shell. Windows devices speak
- * PowerShell, so a bare command is run through `powershell -NoProfile
- * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
- * shell parses it). Returns undefined when no command was given (interactive
+ * Render `cmd` as the single command string ssh sends to the peer.
+ *
+ * Windows devices speak PowerShell, so the result is run through
+ * `powershell -NoProfile -EncodedCommand`; POSIX devices get it as the remote
+ * login shell sees it. Returns undefined when no command was given (interactive
  * login).
+ *
+ * TWO MODES, and the difference is load-bearing rather than a convenience.
+ *
+ * The default joins the tokens RAW. That is not a bug to be tidied away: every
+ * existing caller of `agents ssh` relies on the remote shell interpreting what it
+ * is handed — `agents ssh box 'bash -lc "cd x && make"'` arrives as ONE token
+ * whose pipeline, globs and redirections the peer's shell must expand. Quoting
+ * that would ship the whole line as a literal argument and break it.
+ *
+ * `{ argv: true }` is for a caller that genuinely holds an argv ARRAY and needs
+ * each element delivered as exactly one token. Joining those raw destroys any
+ * token containing a space or a metacharacter — `['--title', 'two words']`
+ * arrives as three tokens, and `'a & b'` arrives as a backgrounded command — which
+ * is what a native client hitting this path actually hit.
+ *
+ * So fidelity is opt-in at the call site that knows which shape it has, and the
+ * quoting itself reuses the canonical helpers (`shellQuote`, {@link pwshQuote})
+ * rather than introducing a third escaping scheme.
  */
-export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
+export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[], opts?: {
+    argv?: boolean;
+    prelude?: string[];
+}): string | undefined;
+/**
+ * Single-quote one token for PowerShell's OWN parser. Inside a single-quoted pwsh
+ * string the only special character is `'`, escaped by doubling.
+ *
+ * This is correct for a value PowerShell itself consumes, and NOT sufficient for
+ * an argument handed on to a native program — see the Win32 note below.
+ */
+export declare function pwshQuote(token: string): string;
 /**
  * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
  * the standalone `browser` binary (`cli/package.json` `bin.browser` →
@@ -65,6 +95,19 @@ export declare function isAgentsBrowserDrive(cmd: string[]): boolean;
  * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
  * so nothing is doubled.
  */
+/**
+ * The provenance prefix as READY SHELL SYNTAX for the device's shell.
+ *
+ * These tokens are already quoted/escaped for their target shell — a POSIX
+ * `K=V` pair is `shellQuote`d here, and a PowerShell assignment is a complete
+ * statement with its own doubled quotes. That matters because argv mode quotes
+ * every token it is handed: quoting THESE again turns
+ * `'AGENTS_ACTOR=Some Name'` into `''\''AGENTS_ACTOR=Some Name'\'''` and turns a
+ * pwsh assignment into an inert string literal. So the prelude is composed
+ * SEPARATELY from the caller's argv rather than concatenated into it, and this is
+ * the single definition both paths use.
+ */
+export declare function fleetRemotePrelude(device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
@@ -136,6 +179,7 @@ export declare function deviceIdentityArgs(device: DeviceProfile): string[];
 export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions, opts?: {
     agentOnly?: boolean;
     interactiveCwd?: string;
+    argv?: boolean;
 }): {
     args: string[];
     env: Record<string, string>;

package/dist/lib/devices/connect.js

@@ -18,12 +18,14 @@ import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { resolveActor, actorEnv } from '../actor.js';
 import { getCliLaunch } from '../cli-entry.js';
-import { encodePwshBase64 } from '../pwsh.js';
+import { encodePwshBase64, pwshLiteral, pwshNativeExecStatements } from '../pwsh.js';
+import { quoteWin32ExecArg } from '../platform/exec.js';
 import { homeRemainder, remoteCdPrefix } from '../project-root.js';
 import { getCacheDir } from '../state.js';
 import { hostKeyCheckingOpts } from './known-hosts.js';
 import { hostNameFor } from './ssh-config.js';
 import { resolveDeviceProfile } from './resolve-profile.js';
+import { renderPowershellCommand, windowsAgentsInvocation } from '../hosts/remote-cmd.js';
 /** Env var the askpass shim reads to know which bundle holds the password. */
 export const ASKPASS_BUNDLE_ENV = 'AGENTS_SSH_BUNDLE';
 /** Env var the askpass shim reads to know which key in the bundle is the password. */
@@ -72,20 +74,139 @@ export function fleetDialTarget(device) {
     }
 }
 /**
- * Wrap a remote command for the device's shell. Windows devices speak
- * PowerShell, so a bare command is run through `powershell -NoProfile
- * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
- * shell parses it). Returns undefined when no command was given (interactive
+ * Render `cmd` as the single command string ssh sends to the peer.
+ *
+ * Windows devices speak PowerShell, so the result is run through
+ * `powershell -NoProfile -EncodedCommand`; POSIX devices get it as the remote
+ * login shell sees it. Returns undefined when no command was given (interactive
  * login).
+ *
+ * TWO MODES, and the difference is load-bearing rather than a convenience.
+ *
+ * The default joins the tokens RAW. That is not a bug to be tidied away: every
+ * existing caller of `agents ssh` relies on the remote shell interpreting what it
+ * is handed — `agents ssh box 'bash -lc "cd x && make"'` arrives as ONE token
+ * whose pipeline, globs and redirections the peer's shell must expand. Quoting
+ * that would ship the whole line as a literal argument and break it.
+ *
+ * `{ argv: true }` is for a caller that genuinely holds an argv ARRAY and needs
+ * each element delivered as exactly one token. Joining those raw destroys any
+ * token containing a space or a metacharacter — `['--title', 'two words']`
+ * arrives as three tokens, and `'a & b'` arrives as a backgrounded command — which
+ * is what a native client hitting this path actually hit.
+ *
+ * So fidelity is opt-in at the call site that knows which shape it has, and the
+ * quoting itself reuses the canonical helpers (`shellQuote`, {@link pwshQuote})
+ * rather than introducing a third escaping scheme.
  */
-export function wrapRemoteCommand(device, cmd) {
+export function wrapRemoteCommand(device, cmd, opts = {}) {
     if (cmd.length === 0)
         return undefined;
-    const joined = cmd.join(' ');
+    const prelude = opts.prelude ?? [];
+    let script;
+    if (opts.argv) {
+        // Quote EACH caller token so the peer receives it byte-for-byte, then prefix
+        // the prelude VERBATIM — it is already shell syntax and re-quoting it would
+        // break it (see `fleetRemotePrelude`).
+        if (device.shell === 'powershell') {
+            script = pwshExactArgvScript(cmd, prelude);
+        }
+        else {
+            script = [...prelude, ...cmd.map(shellQuote)].join(' ');
+        }
+    }
+    else {
+        // The default joins raw, which is what lets a caller hand the remote shell
+        // something to interpret. See the docblock above for why both must exist.
+        script = [...prelude, ...cmd].join(' ');
+    }
     if (device.shell === 'powershell') {
-        return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(joined)}`;
+        // Same renderer the Windows `agents` launcher uses, so a long script gets the
+        // compressed representation here too rather than only on that path. The
+        // interactive login route (`buildInteractiveShellCommand`, -NoExit) is
+        // deliberately left alone: it must stay an interactive session.
+        return renderPowershellCommand(script);
     }
-    return joined;
+    return script;
+}
+/**
+ * Single-quote one token for PowerShell's OWN parser. Inside a single-quoted pwsh
+ * string the only special character is `'`, escaped by doubling.
+ *
+ * This is correct for a value PowerShell itself consumes, and NOT sufficient for
+ * an argument handed on to a native program — see the Win32 note below.
+ */
+export function pwshQuote(token) {
+    return `'${token.replace(/'/g, "''")}'`;
+}
+/**
+ * Emit a PowerShell script that runs `cmd` with EXACT argv, for either kind of
+ * target a Windows peer can name.
+ *
+ * Windows has no argv array: a process receives ONE string and splits it itself.
+ * PowerShell 5.1 rebuilds that string when it invokes a native program, and its
+ * serializer is lossy — measured on a real peer, an EMPTY argument is dropped and
+ * an embedded `"` is discarded, so the callee's argv silently shifts.
+ *
+ * The obvious fix, the `--%` stop-parsing token, is NOT used, because measurement
+ * killed it three ways:
+ *   - it only applies to a NATIVE command, and `agents` on Windows resolves to
+ *     `agents.ps1`, so a script target received `--%` as a literal argument and
+ *     the whole remainder as one string;
+ *   - a token containing a NEWLINE terminates the directive, producing a parser
+ *     error;
+ *   - it performs cmd-style `%VAR%` expansion, so a literal `%PATH%` became six
+ *     arguments — the exact opposite of exact argv.
+ *
+ * So the script branches on what the peer's own command discovery finds:
+ *
+ *   - **native executable** — launched through `System.Diagnostics.Process` with a
+ *     pre-built `Arguments` string escaped by {@link quoteWin32ExecArg}. .NET hands
+ *     that string to `CreateProcess` essentially verbatim, so the child's
+ *     `CommandLineToArgvW` reconstructs the tokens exactly; no shell sees it, so
+ *     no `%VAR%` expansion and no newline sensitivity. `UseShellExecute = $false`
+ *     with no redirection leaves the child on the inherited handles, which is what
+ *     lets a binary stdout stream through unchanged.
+ *   - **anything else** (a `.ps1`/`.cmd` launcher, a function, a cmdlet, an alias)
+ *     — invoked with a splatted PowerShell array. That is an in-process call, so
+ *     the native serializer is never involved and every token survives as itself.
+ *
+ * The exit code is propagated in both branches; a script launcher that sets no
+ * `$LASTEXITCODE` is left alone rather than forced to 0.
+ */
+function pwshExactArgvScript(cmd, prelude) {
+    // The Agents CLI gets the canonical launcher, not the generic dispatch. On
+    // Windows `agents` is an npm `agents.ps1` whose own body splats `$args` into
+    // native node.exe — the PowerShell 5.1 lossy path — so even a perfectly
+    // splatted call into that script loses an embedded quote one layer deeper.
+    // `windowsAgentsInvocation` resolves the package's declared entry and runs it
+    // directly, which is the only way the real Agents parser sees exact tokens.
+    const bin = cmd[0];
+    if (bin === 'agents' || bin === 'ag') {
+        // `windowsAgentsInvocation` leaves the child's code in `$zq`.
+        return [...prelude, windowsAgentsInvocation(cmd.slice(1), bin), 'exit $zq'].join('\n');
+    }
+    const program = pwshQuote(cmd[0]);
+    const rest = cmd.slice(1);
+    const splat = rest.length > 0 ? `@(${rest.map(pwshQuote).join(', ')})` : '@()';
+    return [
+        ...prelude,
+        `$ErrorActionPreference='Stop'`,
+        `$__c = Get-Command -Name ${program} -ErrorAction Stop`,
+        `if ($__c.CommandType -eq 'Application') {`,
+        // One emitter for the .NET native-exec block, shared with the Windows
+        // `agents` launcher in `hosts/remote-cmd.ts`; a second copy would drift.
+        ...pwshNativeExecStatements('$__c.Source', pwshLiteral(rest.map(quoteWin32ExecArg).join(' '))).map((line) => `  ${line}`),
+        // `pwshNativeExecStatements` names the process handle `$zp`.
+        `  exit $zp.ExitCode`,
+        `}`,
+        // `@__a` SPLATS the array into separate arguments. `& $__c @(...)` on an
+        // array LITERAL does not splat — it passes one array-valued argument, which
+        // a real peer reported back as every token collapsed into one.
+        `$__a = ${splat}`,
+        `& $__c @__a`,
+        `if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }`,
+    ].join('\n');
 }
 /**
  * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
@@ -123,22 +244,43 @@ export function isAgentsBrowserDrive(cmd) {
  * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
  * so nothing is doubled.
  */
-export function markFleetRemote(cmd, device, provenanceEnv = actorEnv(resolveActor())) {
+/**
+ * The provenance prefix as READY SHELL SYNTAX for the device's shell.
+ *
+ * These tokens are already quoted/escaped for their target shell — a POSIX
+ * `K=V` pair is `shellQuote`d here, and a PowerShell assignment is a complete
+ * statement with its own doubled quotes. That matters because argv mode quotes
+ * every token it is handed: quoting THESE again turns
+ * `'AGENTS_ACTOR=Some Name'` into `''\''AGENTS_ACTOR=Some Name'\'''` and turns a
+ * pwsh assignment into an inert string literal. So the prelude is composed
+ * SEPARATELY from the caller's argv rather than concatenated into it, and this is
+ * the single definition both paths use.
+ */
+export function fleetRemotePrelude(device, provenanceEnv = actorEnv(resolveActor())) {
     if (device.shell === 'powershell') {
-        // Exact-match guard, symmetric with the POSIX branch below: the marker token
-        // is always this literal, so `startsWith` would only loosen it for no gain.
-        if (cmd[0] === `$env:AGENTS_FLEET_REMOTE='1';`)
-            return cmd;
-        const prelude = [
+        return [
             `$env:AGENTS_FLEET_REMOTE='1';`,
             ...Object.entries(provenanceEnv).map(([k, v]) => `$env:${k}='${v.replace(/'/g, "''")}';`),
         ];
-        return [...prelude, ...cmd];
     }
-    if (cmd[0] === 'env' && cmd[1] === 'AGENTS_FLEET_REMOTE=1')
+    return [
+        'env',
+        'AGENTS_FLEET_REMOTE=1',
+        ...Object.entries(provenanceEnv).map(([k, v]) => shellQuote(`${k}=${v}`)),
+    ];
+}
+/** True when `cmd` already carries the prelude {@link fleetRemotePrelude} emits. */
+function alreadyMarked(cmd, device) {
+    if (device.shell === 'powershell')
+        return cmd[0] === `$env:AGENTS_FLEET_REMOTE='1';`;
+    return cmd[0] === 'env' && cmd[1] === 'AGENTS_FLEET_REMOTE=1';
+}
+export function markFleetRemote(cmd, device, provenanceEnv = actorEnv(resolveActor())) {
+    // Exact-match guard: the marker token is always this literal, so `startsWith`
+    // would only loosen it for no gain.
+    if (alreadyMarked(cmd, device))
         return cmd;
-    const actorTokens = Object.entries(provenanceEnv).map(([k, v]) => shellQuote(`${k}=${v}`));
-    return ['env', 'AGENTS_FLEET_REMOTE=1', ...actorTokens, ...cmd];
+    return [...fleetRemotePrelude(device, provenanceEnv), ...cmd];
 }
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
@@ -229,10 +371,16 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}, o
     // Stamp the consent marker on the REMOTE command, not the local ssh env:
     // SSH_ASKPASS lives on this side; AGENTS_FLEET_REMOTE must be visible to the
     // process that runs on the peer.
-    const remoteCmd = !interactive && isAgentsBrowserDrive(cmd) ? markFleetRemote(cmd, device) : cmd;
+    // Provenance is composed as a PRELUDE, not prepended to the argv array. In argv
+    // mode every token handed to `wrapRemoteCommand` is quoted, and the prelude is
+    // already shell syntax — mixing them in meant the actor pairs were quoted twice
+    // (breaking any value with a space or a quote) and the pwsh assignments became
+    // inert string literals.
+    const needsProvenance = !interactive && isAgentsBrowserDrive(cmd) && !alreadyMarked(cmd, device);
+    const prelude = needsProvenance ? fleetRemotePrelude(device) : [];
     const remote = interactive
         ? buildInteractiveShellCommand(device, opts.interactiveCwd)
-        : wrapRemoteCommand(device, remoteCmd);
+        : wrapRemoteCommand(device, cmd, { ...(opts.argv ? { argv: true } : {}), ...(prelude.length > 0 ? { prelude } : {}) });
     const env = {};
     const args = [
         ...hostKeyCheckingOpts(hostKey.pinned ?? false, hostKey.knownHostsFile),