@phnx-labs/agents-cli 1.22.114 → 1.22.115

package/dist/lib/feed/watch.js

@@ -1,5 +1,4 @@
 import { SessionProjection } from '../session/projection.js';
-import { randomUUID } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { loadDevices, isDialableDevice } from '../devices/registry.js';
@@ -12,21 +11,26 @@ import { watchLocalSessions } from '../session/watch.js';
 import { readBlock, readResolution, blockIdForSession } from './feed.js';
 import { reconcileAttention } from './attention.js';
 import { ActivityStream } from './activity-stream.js';
+import { collectToolRows, watchToolActivity } from './tool-activity.js';
+import { FeedWatchState } from './envelope.js';
+import { FeedHub } from './hub.js';
+import { getCachedToolSetup, subscribeToolSetup } from '../setup-tool-status.js';
 import { PR_STATUS_TTL_MS, readPullRequestStatus, withPullRequestStatus } from './pr-status.js';
-export class FeedWatchState {
-    streamId;
-    sequence = 0;
-    constructor(streamId = randomUUID()) { this.streamId = streamId; }
-    emit(event) {
-        return { v: 1, streamId: this.streamId, sequence: ++this.sequence, ...event };
-    }
-}
+export { FeedWatchState } from './envelope.js';
 /** Reuse session ownership reconciliation for the combined operator stream. */
 export class FeedSessionProjection {
     state;
     sessions = new SessionProjection();
     observations = new Map();
     projectedAttention = new Map();
+    /**
+     * Tool rows per observing scope. A reset replaces one scope's rows and must
+     * not touch another's — the same per-scope rule the agent rows follow, and
+     * the reason a peer reconnecting cannot erase the local machine's tasks.
+     */
+    toolsByScope = new Map();
+    /** Whole-set per scope; see the `setup.snapshot` docblock in `envelope.ts`. */
+    setupByScope = new Map();
     constructor(state = new FeedWatchState()) {
         this.state = state;
     }
@@ -43,6 +47,8 @@ export class FeedSessionProjection {
                     attention.set(row.rowKey, item);
             }
             this.observations.set(scope, attention);
+            this.toolsByScope.set(scope, new Map(event.tools.map((tool) => [tool.rowKey, tool])));
+            this.setupByScope.set(scope, event.setup);
         }
         else if (event.type === 'agent.upsert') {
             sessionEvent = { ...base, type: 'upsert', rowKey: event.rowKey, row: event.agent };
@@ -59,6 +65,20 @@ export class FeedSessionProjection {
         else if (event.type === 'attention.remove') {
             this.observations.get(scope)?.delete(event.rowKey);
         }
+        else if (event.type === 'tool.upsert') {
+            if (!this.toolsByScope.has(scope))
+                this.toolsByScope.set(scope, new Map());
+            this.toolsByScope.get(scope).set(event.rowKey, event.tool);
+            return [this.state.emit({ type: 'tool.upsert', scope, rowKey: event.rowKey, tool: event.tool })];
+        }
+        else if (event.type === 'tool.remove') {
+            this.toolsByScope.get(scope)?.delete(event.rowKey);
+            return [this.state.emit({ type: 'tool.remove', scope, rowKey: event.rowKey })];
+        }
+        else if (event.type === 'setup.snapshot') {
+            this.setupByScope.set(scope, event.setup);
+            return [this.state.emit({ type: 'setup.snapshot', scope, capturedAt: event.capturedAt, setup: event.setup })];
+        }
         else {
             const { v: _v, streamId: _streamId, sequence: _sequence, ...payload } = event;
             return [this.state.emit(payload)];
@@ -77,7 +97,9 @@ export class FeedSessionProjection {
             if (rowEvent.type === 'reset') {
                 resetScopes.add(rowEvent.scope);
                 result.push(this.state.emit({ type: 'reset', scope: rowEvent.scope, capturedAt: rowEvent.capturedAt, agents: rowEvent.rows,
-                    attention: [...next.values()].filter(value => value.scope === rowEvent.scope).map(value => value.item) }));
+                    attention: [...next.values()].filter(value => value.scope === rowEvent.scope).map(value => value.item),
+                    tools: [...(this.toolsByScope.get(rowEvent.scope)?.values() ?? [])],
+                    setup: this.setupByScope.get(rowEvent.scope) ?? [] }));
             }
             else if (rowEvent.type === 'upsert') {
                 result.push(this.state.emit({ type: 'agent.upsert', scope: rowEvent.scope, rowKey: rowEvent.rowKey, agent: rowEvent.row }));
@@ -136,11 +158,11 @@ async function projectAgent(agent, gh) {
     const pullRequest = await pullRequestFor(agent, gh);
     return { agent: withPullRequestStatus(agent, pullRequest), attention: attentionFor(agent, pullRequest) };
 }
-export async function projectSessionEnvelope(event, state, gh) {
+export async function projectSessionEnvelope(event, state, gh, tools = [], setup = []) {
     if (event.type === 'reset') {
         const projected = await Promise.all(event.rows.map((row) => projectAgent(row, gh)));
         const attention = projected.map((p) => p.attention).filter((item) => item !== undefined);
-        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: projected.map((p) => p.agent), attention })];
+        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: projected.map((p) => p.agent), attention, tools, setup })];
     }
     if (event.type === 'upsert') {
         const { agent, attention } = await projectAgent(event.row, gh);
@@ -198,6 +220,23 @@ export async function watchLocalFeed(options) {
     // dropping it from a window the caller believes was covered.
     const activity = new ActivityStream();
     let activityCursor = Date.now();
+    // The tool rows as this machine last projected them. Held here rather than
+    // re-collected per reset: a session-watch reconnect emits a fresh reset, and
+    // re-reading the browser tree and the ledger for it would reintroduce exactly
+    // the per-render cost `tool-activity.ts` exists to remove.
+    let toolRows = collectToolRows(options.scope, options.tools?.sources).rows;
+    // Setup rows come from the setup teammate's cache, never from a probe here:
+    // `getCachedToolSetup` reads metadata plus the last EXPLICIT health check, so
+    // publishing it costs no subprocess and cannot unlock a secret store.
+    const readSetup = options.setup?.read ?? getCachedToolSetup;
+    let setupRows = (() => {
+        try {
+            return readSetup();
+        }
+        catch {
+            return [];
+        }
+    })();
     const agents = new Map();
     const attention = new Map();
     // The PR status last projected onto each row, so a merge or a check verdict
@@ -245,7 +284,30 @@ export async function watchLocalFeed(options) {
             await reconcileRows();
         });
     }, options.activityPollMs ?? 500);
-    const stopActivity = () => { clearInterval(activityTimer); stopAttentionWatch(); activity.close(); };
+    const toolWatch = watchToolActivity({
+        ...options.tools, scope: options.scope, signal: options.signal, initial: toolRows,
+        onDiff: (diff) => {
+            for (const tool of diff.upserts) {
+                toolRows = [...toolRows.filter((row) => row.rowKey !== tool.rowKey), tool];
+                options.emit(state.emit({ type: 'tool.upsert', scope: options.scope, rowKey: tool.rowKey, tool }));
+            }
+            for (const rowKey of diff.removes) {
+                toolRows = toolRows.filter((row) => row.rowKey !== rowKey);
+                options.emit(state.emit({ type: 'tool.remove', scope: options.scope, rowKey }));
+            }
+        },
+    });
+    // The setup cache is file-backed and notifies on change, so a Settings pane
+    // costs no polling: `subscribeToolSetup` is the invalidation the setup side
+    // publishes for exactly this consumer.
+    const stopSetupWatch = (options.setup?.subscribe ?? subscribeToolSetup)((rows) => {
+        const next = JSON.stringify(rows);
+        if (next === JSON.stringify(setupRows))
+            return;
+        setupRows = rows;
+        options.emit(state.emit({ type: 'setup.snapshot', scope: options.scope, capturedAt: Date.now(), setup: rows }));
+    });
+    const stopActivity = () => { clearInterval(activityTimer); stopAttentionWatch(); activity.close(); toolWatch.stop(); stopSetupWatch(); };
     options.signal.addEventListener('abort', stopActivity, { once: true });
     try {
         await watchLocalSessions({ ...options.sessions, scope: options.scope, signal: options.signal, emit: (event) => {
@@ -261,7 +323,7 @@ export async function watchLocalFeed(options) {
                     attention.delete(event.rowKey);
                     prStatus.delete(event.rowKey);
                 }
-                pending = pending.then(() => projectSessionEnvelope(event, state, options.gh)).then((events) => {
+                pending = pending.then(() => projectSessionEnvelope(event, state, options.gh, toolRows, setupRows)).then((events) => {
                     for (const projected of events) {
                         if (projected.type === 'reset') {
                             attention.clear();
@@ -301,6 +363,75 @@ function remoteFeedWatchCommand(os) {
         ? buildWindowsAgentsCommand({ args })
         : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
 }
+/**
+ * The one ingress for an envelope produced by ANOTHER agents-cli.
+ *
+ * `tools` was added to the `reset` payload within protocol v1, so a peer on an
+ * older CLI is a correct v1 producer that simply reports no tool rows — which is
+ * true of it, not a data defect to paper over. Normalizing HERE, at the single
+ * place a foreign envelope enters, is what keeps every consumer downstream able
+ * to treat the field as present instead of each re-checking it. A mixed-version
+ * fleet is the normal state during a rollout, so an absent field must not take
+ * the whole fan-out down.
+ */
+export function normalizePeerEnvelope(event) {
+    if (event.type !== 'reset')
+        return event;
+    if (Array.isArray(event.tools) && Array.isArray(event.setup))
+        return event;
+    return { ...event, tools: event.tools ?? [], setup: event.setup ?? [] };
+}
+/**
+ * The process-wide local collector, shared by refcount.
+ *
+ * `watchLocalFeed` is cheap per tick but NOT free to duplicate: each call builds
+ * its own `ActivityStream` cursor set over the activity directory, its own
+ * recursive tool watchers, its own feed/resolution watchers and its own
+ * setup subscription. Two callers in one process paid all of that twice and
+ * produced identical envelopes — and there are genuinely two callers on a daemon
+ * box: the fleet fan-out (which watches the local scope alongside every peer)
+ * and anything else that wants this machine's rows.
+ *
+ * One {@link FeedHub} over `watchLocalFeed` collapses them: the watcher starts on
+ * the first subscriber, stops on the last, and a late subscriber is caught up
+ * from held state instead of constructing a second cursor set.
+ *
+ * This is deliberately PROCESS-wide and not machine-wide. Making `feed watch
+ * --json --local` attach to the daemon instead would be the machine-wide
+ * version, and it would put a daemon dependency on the one command the fleet
+ * fan-out runs over ssh on every peer — a peer with a sick daemon would drop off
+ * the fleet stream entirely rather than degrade. The cross-process sharing that
+ * matters is the FLEET stream, which is what the daemon hub serves.
+ */
+let sharedLocal = null;
+/** The shared local collector, constructed on first use. Exposed for tests. */
+export function sharedLocalFeedHub() {
+    return sharedLocal ??= new FeedHub({
+        watch: (hubOptions) => watchLocalFeed({
+            scope: machineId(), signal: hubOptions.signal, emit: hubOptions.emit,
+        }),
+    });
+}
+/** Reset the shared collector. Tests only — it must not leak across cases. */
+export async function resetSharedLocalFeedHub() {
+    const hub = sharedLocal;
+    sharedLocal = null;
+    await hub?.close();
+}
+/**
+ * Subscribe to this machine's rows through the shared collector, until abort.
+ */
+export function subscribeSharedLocalFeed(options) {
+    const detach = sharedLocalFeedHub().subscribe(options.emit);
+    return new Promise((resolve) => {
+        if (options.signal.aborted) {
+            detach();
+            resolve();
+            return;
+        }
+        options.signal.addEventListener('abort', () => { detach(); resolve(); }, { once: true });
+    });
+}
 export async function watchFleetFeed(options) {
     const coordinator = new FeedWatchState();
     const projection = new FeedSessionProjection(coordinator);
@@ -308,7 +439,7 @@ export async function watchFleetFeed(options) {
         for (const projected of projection.apply(event))
             options.emit(projected);
     };
-    const local = watchLocalFeed({ scope: machineId(), signal: options.signal, emit: forward });
+    const local = subscribeSharedLocalFeed({ signal: options.signal, emit: forward });
     let devices;
     try {
         devices = await loadDevices();
@@ -331,7 +462,7 @@ export async function watchFleetFeed(options) {
                     const event = JSON.parse(line);
                     if (event.v !== 1)
                         return false;
-                    forward(event);
+                    forward(normalizePeerEnvelope(event));
                     return true;
                 }
                 catch {

package/dist/lib/format.d.ts

@@ -61,7 +61,7 @@ export declare function relTime(iso: string): string;
 export declare function humanDuration(ms: number): string;
 /**
  * Human-readable byte size. Previously copy-pasted into five files
- * (`commands/prune.ts`, `commands/share.ts`, `commands/inspect.ts`,
+ * (`commands/prune.ts`, `commands/inspect.ts`,
  * `commands/sessions.ts`, `lib/browser/sessions-list.ts`) — this is the
  * canonical home.
  */

package/dist/lib/format.js

@@ -115,7 +115,7 @@ export function humanDuration(ms) {
 }
 /**
  * Human-readable byte size. Previously copy-pasted into five files
- * (`commands/prune.ts`, `commands/share.ts`, `commands/inspect.ts`,
+ * (`commands/prune.ts`, `commands/inspect.ts`,
  * `commands/sessions.ts`, `lib/browser/sessions-list.ts`) — this is the
  * canonical home.
  */

package/dist/lib/git.d.ts

@@ -106,22 +106,6 @@ export declare function readRepoState(repoPath: string): RepoStateSnapshot | nul
 export declare function resolveSnapshotSha(repoRoot: string): string | undefined;
 /** Test seam: clear the memoized snapshot-sha cache between test cases. */
 export declare function _resetSnapshotShaCacheForTest(): void;
-/**
- * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
- *   1. `AGENTS_SHARE_GITHUB_USER` env override
- *   2. `git config --global github.user`
- * Falls back to null so callers can decide whether to require auth or proceed
- * without a namespace.
- */
-export declare function resolveGitHubUsernameSync(): string | null;
-/**
- * Resolve the GitHub username asynchronously. Order:
- *   1. `AGENTS_SHARE_GITHUB_USER` env override
- *   2. `gh api user --jq ".login"`
- *   3. `git config --global github.user`
- * Returns null if none succeed.
- */
-export declare function resolveGitHubUsername(): Promise<string | null>;
 /**
  * Get the remote URL for origin in a git repo.
  */

package/dist/lib/git.js

@@ -389,64 +389,6 @@ export function resolveSnapshotSha(repoRoot) {
 export function _resetSnapshotShaCacheForTest() {
     _snapshotShaCache.clear();
 }
-/**
- * Get the current GitHub username using gh CLI.
- * Returns null if gh is not installed or user is not authenticated.
- */
-async function getGitHubUsername() {
-    try {
-        const { exec } = await import('child_process');
-        const { promisify } = await import('util');
-        const execAsync = promisify(exec);
-        const { stdout } = await execAsync('gh api user --jq ".login"');
-        return stdout.trim() || null;
-    }
-    catch {
-        /* gh CLI not installed or not authenticated */
-        return null;
-    }
-}
-const GITHUB_USER_ENV = 'AGENTS_SHARE_GITHUB_USER';
-/** Best-effort sync read of `github.user` from git config. */
-function readGitConfigUser() {
-    try {
-        return execFileSync('git', ['config', '--global', 'github.user'], { stdio: ['ignore', 'pipe', 'ignore'] })
-            .toString()
-            .trim() || null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Resolve the GitHub username synchronously for `agents artifacts share`. Order:
- *   1. `AGENTS_SHARE_GITHUB_USER` env override
- *   2. `git config --global github.user`
- * Falls back to null so callers can decide whether to require auth or proceed
- * without a namespace.
- */
-export function resolveGitHubUsernameSync() {
-    const env = process.env[GITHUB_USER_ENV]?.trim();
-    if (env)
-        return env;
-    return readGitConfigUser();
-}
-/**
- * Resolve the GitHub username asynchronously. Order:
- *   1. `AGENTS_SHARE_GITHUB_USER` env override
- *   2. `gh api user --jq ".login"`
- *   3. `git config --global github.user`
- * Returns null if none succeed.
- */
-export async function resolveGitHubUsername() {
-    const env = process.env[GITHUB_USER_ENV]?.trim();
-    if (env)
-        return env;
-    const gh = await getGitHubUsername();
-    if (gh)
-        return gh;
-    return readGitConfigUser();
-}
 /**
  * Get the remote URL for origin in a git repo.
  */

package/dist/lib/helper-versions.js

@@ -41,7 +41,7 @@
  * it would claim a distribution responsibility agents-cli no longer has.
  */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.4.0' },
+    menubar: { tagPrefix: 'menubar', floor: '1.5.0' },
 };
 /** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
 export function helperTag(helper, version) {

package/dist/lib/hosts/remote-cmd.d.ts

@@ -158,12 +158,62 @@ export declare const POWERSHELL_PROGRESS_SILENCE = "$ProgressPreference = 'Silen
  * every remote-JSON boundary regardless of the peer's OS.
  */
 export declare function stripClixml(stdout: string): string;
+/**
+ * Statements that run the Agents CLI on a Windows peer with EXACT argv, leaving the
+ * child's exit code in `$zq`.
+ *
+ * `& agents …` cannot be used, and the reason is not our quoting. On Windows
+ * `agents` is an npm-generated `agents.ps1`, whose body ends in
+ *
+ *     & "node$exe" --no-warnings=… "$basedir/node_modules/@phnx-labs/agents-cli/dist/index.js" $args
+ *
+ * — `$args` splatted into a NATIVE program, which is the PowerShell 5.1 lossy
+ * serializer. So the loss happens INSIDE the user's shim, after our tokens were
+ * already correct: measured on a real peer, `no-such-"menu"-proof` reached the
+ * Agents parser as `no-such-menu-proof`. Quoting harder upstream cannot fix that,
+ * and rewriting a user's npm shim is not ours to do.
+ *
+ * Instead the shim is bypassed the same way `getCliLaunch` (`lib/cli-entry.ts`)
+ * resolves a launch locally: a node-script entry becomes `<node> <entry> …args`.
+ * The entry and runtime are resolved ON THE PEER from the launcher's own location —
+ * the identical two-step the shim itself performs — and executed through .NET with
+ * a `CommandLineToArgvW`-escaped argument string.
+ *
+ * A peer whose `agents` is already a native executable is used directly. A peer
+ * where neither resolves FAILS LOUD: falling back to `& agents` would silently
+ * restore the argument loss, which is worse than an error naming what is missing.
+ *
+ * The entry comes from the package's DECLARED `bin` rather than a literal
+ * `dist/index.js`, so it follows the package instead of needing to be kept in sync
+ * with it.
+ */
+export declare function windowsAgentsInvocation(args: string[], binName?: 'agents' | 'ag'): string;
 export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
 /**
  * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a
- * Windows remote: a `powershell -NoProfile -EncodedCommand <base64>` call. The
+ * Windows remote: a rendered `powershell -NoProfile` call. The
  * Windows counterpart of `bash -lc '<...>'`, shared by every `--device` site.
  */
+/**
+ * Render a PowerShell script as the single command string ssh sends to a Windows
+ * peer, compressing it when that is genuinely shorter.
+ *
+ * The plain route is `-EncodedCommand <base64 of UTF-16LE>`, which inflates the
+ * script by ~2.67x. That matters because OpenSSH-for-Windows caps the whole remote
+ * command far below cmd.exe's 8191 — bisected against a live peer, 2934 characters
+ * succeed and 3102 fail — so a longer script eats the headroom a caller's
+ * arguments, `--remote-cwd` and forwarded env need.
+ *
+ * The alternative is to deflate the UTF-8 script and emit a small fixed bootstrap
+ * that inflates it back. That trades ~2.67x for ~1.33x on the compressible part,
+ * which on scripts of this shape is a large net win. The variable-free bootstrap
+ * uses `-Command` with a base64 payload and leaves stdin available to the child.
+ *
+ * Applied ONLY when the result is actually shorter: for a small script the fixed
+ * bootstrap costs more than it saves, so picking the shorter of the two keeps the
+ * plain form in play for every small caller and is obviously correct either way.
+ */
+export declare function renderPowershellCommand(script: string): string;
 export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): string;
 /**
  * Build the `ssh <target> <cmd>` string for `agents secrets import` on a Windows

package/dist/lib/hosts/remote-cmd.js

@@ -8,6 +8,9 @@
  * (`sshExec`/`sshStream`); orchestration lives in `passthrough.ts`.
  */
 import { shellQuote } from '../ssh-exec.js';
+import { pwshLiteral, pwshNativeExecStatements } from '../pwsh.js';
+import { quoteWin32ExecArg } from '../platform/exec.js';
+import * as zlib from 'node:zlib';
 /**
  * Remove routing flags (and their values) from a command's args, leaving the
  * rest untouched and in order so they forward verbatim to the remote binary.
@@ -136,8 +139,6 @@ export const RUN_OPTION_FORWARDING = {
     // On a --device dispatch the remote box runs its own run-exit sync, so this
     // flag is never forwarded — it is a local-exit-behavior toggle, not remote.
     traceSync: 'local-only',
-    // Deprecated alias for --device auto; resolved on the launching box before SSH.
-    smart: 'local-only',
     // Broadcast mode (agents run --broadcast) is its own fan-out dispatch — mutually
     // exclusive with --host. All broadcast options are local-only; exec.ts handles them
     // before any SSH dispatch path is reached.
@@ -293,30 +294,146 @@ export function stripClixml(stdout) {
         .replace(/#< CLIXML[^\n]*\r?\n?(?:\s*<Objs\b[\s\S]*?<\/Objs>)*/g, '')
         .trim();
 }
+/**
+ * Statements that run the Agents CLI on a Windows peer with EXACT argv, leaving the
+ * child's exit code in `$zq`.
+ *
+ * `& agents …` cannot be used, and the reason is not our quoting. On Windows
+ * `agents` is an npm-generated `agents.ps1`, whose body ends in
+ *
+ *     & "node$exe" --no-warnings=… "$basedir/node_modules/@phnx-labs/agents-cli/dist/index.js" $args
+ *
+ * — `$args` splatted into a NATIVE program, which is the PowerShell 5.1 lossy
+ * serializer. So the loss happens INSIDE the user's shim, after our tokens were
+ * already correct: measured on a real peer, `no-such-"menu"-proof` reached the
+ * Agents parser as `no-such-menu-proof`. Quoting harder upstream cannot fix that,
+ * and rewriting a user's npm shim is not ours to do.
+ *
+ * Instead the shim is bypassed the same way `getCliLaunch` (`lib/cli-entry.ts`)
+ * resolves a launch locally: a node-script entry becomes `<node> <entry> …args`.
+ * The entry and runtime are resolved ON THE PEER from the launcher's own location —
+ * the identical two-step the shim itself performs — and executed through .NET with
+ * a `CommandLineToArgvW`-escaped argument string.
+ *
+ * A peer whose `agents` is already a native executable is used directly. A peer
+ * where neither resolves FAILS LOUD: falling back to `& agents` would silently
+ * restore the argument loss, which is worse than an error naming what is missing.
+ *
+ * The entry comes from the package's DECLARED `bin` rather than a literal
+ * `dist/index.js`, so it follows the package instead of needing to be kept in sync
+ * with it.
+ */
+export function windowsAgentsInvocation(args, binName = 'agents') {
+    const escaped = pwshLiteral(args.map(quoteWin32ExecArg).join(' '));
+    return [
+        // Set before any resolution: a non-terminating failure below would otherwise
+        // leave the exit code null, and `exit $null` reports 0.
+        `$ErrorActionPreference = 'Stop'`,
+        `$zc = Get-Command ${powershellQuote(binName)} -ErrorAction Stop`,
+        `$ze = $zc.Source`,
+        `$zr = ''`,
+        // A real native executable needs no interpreter prefix. `CommandType` alone is
+        // NOT that test: `Get-Command` reports `Application` for `agents.cmd` too, and
+        // a .cmd launcher re-parses through cmd.exe with the same argument loss as the
+        // .ps1 one — so a cmd-only install must not bypass this either.
+        `if ($zc.CommandType -ne 'Application' -or $ze -match '\\.(cmd|bat)$') {`,
+        `  $zb = Split-Path $ze`,
+        `  $zk = Join-Path $zb 'node_modules\\@phnx-labs\\agents-cli'`,
+        // The package's DECLARED bin, so the entry follows the package rather than a
+        // hand-synced `dist/index.js` literal that would rot on upgrade. One check
+        // covers a missing bin AND the single-string `bin` form (which yields $null).
+        `  $zl = (Get-Content -Raw (Join-Path $zk 'package.json') | ConvertFrom-Json).bin.${binName}`,
+        `  if (-not $zl) { throw "agents package at $zk declares no bin.${binName}" }`,
+        `  $zt = Join-Path $zk $zl`,
+        `  if (-not [IO.File]::Exists($zt)) { throw "agents CLI entry not found at $zt" }`,
+        // The npm shim prefers a node.exe beside itself before PATH; match that.
+        `  $zd = Join-Path $zb 'node.exe'`,
+        `  $ze = if ([IO.File]::Exists($zd)) { $zd } else { 'node' }`,
+        // A Windows path cannot contain `"`, so wrapping is sufficient escaping here.
+        `  $zr = '--no-warnings=ExperimentalWarning "' + $zt + '" '`,
+        `}`,
+        ...pwshNativeExecStatements('$ze', `$zr + ${escaped}`),
+        // Reported through a plain variable rather than by assigning the automatic
+        // $LASTEXITCODE, which nothing set here since no PowerShell command ran.
+        `$zq = $zp.ExitCode`,
+        // Never let an unknown outcome read as success.
+        `if ($null -eq $zq) { $zq = 1 }`,
+        // NEWLINE-joined, and that is required rather than stylistic: the caller joins
+        // its parts with `'; '`, which between a closing `}` and `else`/an indented block
+        // would produce invalid PowerShell.
+    ].join('\n');
+}
 export function windowsAgentsScript(cmd) {
     const { args, env, cwd, propagateExit = true, remapExit255 = false } = cmd;
-    const parts = [POWERSHELL_PROGRESS_SILENCE];
+    // `Stop` FIRST, before the env assignments and the Set-Location: a failing
+    // `Set-Location` (a cwd that does not exist on the peer) must abort rather than
+    // continue into the launcher and run the command in the wrong directory.
+    const parts = [POWERSHELL_PROGRESS_SILENCE, `$ErrorActionPreference = 'Stop'`];
     if (env)
         for (const [k, v] of Object.entries(env))
             parts.push(`$env:${k} = ${powershellQuote(v)}`);
     if (cwd)
         parts.push(`Set-Location -LiteralPath ${powershellQuote(cwd)}`);
-    parts.push(`& ${['agents', ...args].map(powershellQuote).join(' ')}`);
+    parts.push(windowsAgentsInvocation(args));
     if (propagateExit) {
         if (remapExit255)
-            parts.push('$agentsExit = $LASTEXITCODE', 'if ($agentsExit -eq 255) { exit 254 }', 'exit $agentsExit');
+            parts.push('if ($zq -eq 255) { exit 254 }', 'exit $zq');
         else
-            parts.push('exit $LASTEXITCODE');
+            parts.push('exit $zq');
     }
     return parts.join('; ');
 }
 /**
  * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a
- * Windows remote: a `powershell -NoProfile -EncodedCommand <base64>` call. The
+ * Windows remote: a rendered `powershell -NoProfile` call. The
  * Windows counterpart of `bash -lc '<...>'`, shared by every `--device` site.
  */
+/**
+ * Render a PowerShell script as the single command string ssh sends to a Windows
+ * peer, compressing it when that is genuinely shorter.
+ *
+ * The plain route is `-EncodedCommand <base64 of UTF-16LE>`, which inflates the
+ * script by ~2.67x. That matters because OpenSSH-for-Windows caps the whole remote
+ * command far below cmd.exe's 8191 — bisected against a live peer, 2934 characters
+ * succeed and 3102 fail — so a longer script eats the headroom a caller's
+ * arguments, `--remote-cwd` and forwarded env need.
+ *
+ * The alternative is to deflate the UTF-8 script and emit a small fixed bootstrap
+ * that inflates it back. That trades ~2.67x for ~1.33x on the compressible part,
+ * which on scripts of this shape is a large net win. The variable-free bootstrap
+ * uses `-Command` with a base64 payload and leaves stdin available to the child.
+ *
+ * Applied ONLY when the result is actually shorter: for a small script the fixed
+ * bootstrap costs more than it saves, so picking the shorter of the two keeps the
+ * plain form in play for every small caller and is obviously correct either way.
+ */
+export function renderPowershellCommand(script) {
+    const plain = `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+    // Raw DEFLATE (RFC 1951) — what .NET's `DeflateStream` reads. `deflateSync`
+    // would prepend a zlib header that `DeflateStream` rejects.
+    const packed = zlib.deflateRawSync(Buffer.from(script, 'utf-8'), { level: 9 }).toString('base64');
+    // The blob is embedded DIRECTLY in a `-Command` string rather than wrapped in a
+    // second `-EncodedCommand`: routing an already-base64 payload through the encoded
+    // form would inflate it by another 2.67x and cancel most of the compression.
+    //
+    // The bootstrap is deliberately VARIABLE-FREE — one nested expression, no `$`
+    // anywhere. A `$b = …` form is unsafe here: OpenSSH-for-Windows may have
+    // PowerShell as its `DefaultShell`, in which case the outer double-quoted string
+    // is parsed by PowerShell first and `$b` would be expanded before our script ever
+    // runs. With no `$`, no `%`, no backtick and no cmd metacharacter — base64's
+    // alphabet is `A-Za-z0-9+/=` and the rest is ASCII punctuation neither shell
+    // touches inside quotes — the same text survives either default shell. stdin is
+    // untouched by both routes.
+    const bootstrap = 'iex ([IO.StreamReader]::new([IO.Compression.DeflateStream]::new('
+        + `[IO.MemoryStream]::new([Convert]::FromBase64String('${packed}')),`
+        + '[IO.Compression.CompressionMode]::Decompress),[Text.Encoding]::UTF8).ReadToEnd())';
+    const compressed = `powershell -NoProfile -Command "${bootstrap}"`;
+    // Only when genuinely shorter: for a small script the fixed bootstrap costs more
+    // than it saves, so this keeps the plain form in play for every small caller.
+    return compressed.length < plain.length ? compressed : plain;
+}
 export function buildWindowsAgentsCommand(cmd) {
-    return `powershell -NoProfile -EncodedCommand ${encodePowershell(windowsAgentsScript(cmd))}`;
+    return renderPowershellCommand(windowsAgentsScript(cmd));
 }
 /**
  * Build the `ssh <target> <cmd>` string for `agents secrets import` on a Windows

package/dist/lib/hosts/remote-cmd.test-fixture.d.ts

@@ -0,0 +1,2 @@
+/** The script behind either render route. Throws if the command is neither. */
+export declare function decodeRenderedPowershell(command: string): string;

package/dist/lib/hosts/remote-cmd.test-fixture.js

@@ -0,0 +1,22 @@
+/**
+ * Test-only decoder for a rendered remote PowerShell command.
+ *
+ * `renderPowershellCommand` emits whichever of two representations is shorter: the
+ * plain `-EncodedCommand <base64 UTF-16LE>`, or a `-Command` bootstrap carrying a
+ * deflated UTF-8 payload. Tests assert on the SCRIPT, not the representation, so
+ * every suite needs both — and four copies of that parsing is exactly how one of
+ * them silently stops decoding the form it was meant to check.
+ *
+ * Named `*.test-fixture.ts` after the existing `daemon.test-fixture.ts`.
+ */
+import * as zlib from 'node:zlib';
+/** The script behind either render route. Throws if the command is neither. */
+export function decodeRenderedPowershell(command) {
+    const encoded = /-EncodedCommand (\S+)\s*$/.exec(command);
+    if (encoded)
+        return Buffer.from(encoded[1], 'base64').toString('utf16le');
+    const packed = /FromBase64String\('([A-Za-z0-9+/=]+)'\)/.exec(command);
+    if (!packed)
+        throw new Error(`not a rendered PowerShell command: ${command}`);
+    return zlib.inflateRawSync(Buffer.from(packed[1], 'base64')).toString('utf-8');
+}