@phnx-labs/agents-cli 1.22.114 → 1.22.116

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

@@ -112,6 +112,12 @@ interface WindowsAgentsCommand {
     env?: Record<string, string>;
     /** Directory to enter before running (`--remote-cwd`). */
     cwd?: string;
+    /**
+     * `cwd` was DERIVED from the local cwd rather than named by the user (see
+     * `deriveMirroredCwd`): a directory the peer does not have falls back to
+     * `$HOME` instead of failing the run, exactly as `remoteCdPrefix({ mirror })`.
+     */
+    mirrorCwd?: boolean;
     /**
      * Append `exit $LASTEXITCODE` so a native `agents` exit code propagates out
      * through `powershell.exe` (which otherwise exits 0 regardless). Default true;
@@ -158,12 +164,77 @@ 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;
+/**
+ * PowerShell expression for a remote path. A home-anchored path (`~/x`,
+ * `$HOME/x`) re-roots onto the peer's `$HOME` through `Join-Path` — the Windows
+ * counterpart of `remoteCdPrefix`'s `"$HOME"/x` — so a directory mirrored from
+ * another box resolves on the peer. Any other path is quoted verbatim.
+ */
+export declare function windowsRemotePath(p: string): string;
+/**
+ * The `Set-Location` step of a Windows remote command. `-ErrorAction Stop` is
+ * spelled out because a missing directory is a NON-terminating error for
+ * `Set-Location`, which a `try`/`catch` would otherwise sail past: the mirrored
+ * form must genuinely land in `$HOME` when the peer lacks the checkout, and the
+ * explicit form must abort rather than run the command in the wrong directory.
+ */
+export declare function windowsSetLocation(cwd: string, mirror?: boolean): 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,10 @@
  * (`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 { homeRemainder } from '../project-root.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 +140,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 +295,169 @@ 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');
+}
+/**
+ * PowerShell expression for a remote path. A home-anchored path (`~/x`,
+ * `$HOME/x`) re-roots onto the peer's `$HOME` through `Join-Path` — the Windows
+ * counterpart of `remoteCdPrefix`'s `"$HOME"/x` — so a directory mirrored from
+ * another box resolves on the peer. Any other path is quoted verbatim.
+ */
+export function windowsRemotePath(p) {
+    const rest = homeRemainder(p);
+    if (rest === null)
+        return powershellQuote(p);
+    return rest === '' ? '$HOME' : `(Join-Path $HOME ${powershellQuote(rest)})`;
+}
+/**
+ * The `Set-Location` step of a Windows remote command. `-ErrorAction Stop` is
+ * spelled out because a missing directory is a NON-terminating error for
+ * `Set-Location`, which a `try`/`catch` would otherwise sail past: the mirrored
+ * form must genuinely land in `$HOME` when the peer lacks the checkout, and the
+ * explicit form must abort rather than run the command in the wrong directory.
+ */
+export function windowsSetLocation(cwd, mirror = false) {
+    const enter = `Set-Location -LiteralPath ${windowsRemotePath(cwd)} -ErrorAction Stop`;
+    return mirror ? `try { ${enter} } catch { Set-Location -LiteralPath $HOME }` : enter;
+}
 export function windowsAgentsScript(cmd) {
-    const { args, env, cwd, propagateExit = true, remapExit255 = false } = cmd;
-    const parts = [POWERSHELL_PROGRESS_SILENCE];
+    const { args, env, cwd, mirrorCwd = false, propagateExit = true, remapExit255 = false } = cmd;
+    // `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(windowsSetLocation(cwd, mirrorCwd));
+    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');
+}

package/dist/lib/mailbox.d.ts

@@ -22,6 +22,16 @@ export interface MailboxMessage {
      * receipts back to the feed store.
      */
     blockId?: string;
+    /**
+     * Which ASK of that block this message answers, and which claim sent it. A
+     * blockId is per SESSION and is reused by every generation of that session's
+     * questions, so without these a `consumed` receipt raised on drain cannot say
+     * WHICH question it acknowledges -- and a late one for question N would
+     * resolve question N+1 (PHNX-3999). Carried on the message so the binding
+     * survives the process that enqueued it.
+     */
+    generation?: string;
+    attempt?: string;
     /**
      * Drop reason when a message is archived without delivery (expired, dead box, etc.).
      * Set by the TTL/liveness layer, not by writers.
@@ -49,6 +59,8 @@ export declare function enqueue(boxDir: string, msg: {
     text: string;
     from?: string;
     blockId?: string;
+    generation?: string;
+    attempt?: string;
     ttlSeconds?: number;
 }): string;
 /** Parse a message file. Returns null on missing/corrupt/invalid-shape. */

package/dist/lib/mailbox.js

@@ -97,6 +97,8 @@ export function enqueue(boxDir, msg) {
         ts: now.toISOString(),
         text: msg.text,
         blockId: msg.blockId,
+        ...(msg.generation !== undefined ? { generation: msg.generation } : {}),
+        ...(msg.attempt !== undefined ? { attempt: msg.attempt } : {}),
     };
     const ttlSeconds = msg.ttlSeconds ?? resolveDefaultTtlSeconds();
     if (ttlSeconds > 0) {
@@ -128,7 +130,14 @@ export function readMessage(file) {
     if (typeof m?.msgId !== 'string' || typeof m?.to !== 'string' || typeof m?.text !== 'string') {
         return null;
     }
-    return { msgId: m.msgId, to: m.to, from: m.from, ts: m.ts ?? '', text: m.text, expiresAt: m.expiresAt, blockId: m.blockId, dropped: m.dropped };
+    // Field-by-field on purpose (an unknown key from a foreign writer is dropped),
+    // so EVERY field the receipt binding depends on must be listed here or it is
+    // silently lost on read and the binding it enables never fires.
+    return {
+        msgId: m.msgId, to: m.to, from: m.from, ts: m.ts ?? '', text: m.text,
+        expiresAt: m.expiresAt, blockId: m.blockId, generation: m.generation, attempt: m.attempt,
+        dropped: m.dropped,
+    };
 }
 /** True when a message has a parsed expiry in the past. */
 export function isExpired(msg, now = new Date()) {
@@ -230,7 +239,12 @@ function consumeClaimed(boxDir, name, expectedTo) {
     if (msg.blockId) {
         try {
             const feedRoot = process.env.AGENTS_FEED_DIR;
-            recordMessageReceipt(msg.blockId, { msgId: msg.msgId, status: 'consumed', at: new Date().toISOString(), from: msg.from }, feedRoot);
+            // The origin rides the message, so the receipt names the ask it answers.
+            recordMessageReceipt(msg.blockId, {
+                msgId: msg.msgId, status: 'consumed', at: new Date().toISOString(), from: msg.from,
+                ...(msg.generation !== undefined ? { generation: msg.generation } : {}),
+                ...(msg.attempt !== undefined ? { attempt: msg.attempt } : {}),
+            }, feedRoot);
         }
         catch {
             // Receipt surfacing is best-effort; never stall delivery.

package/dist/lib/mcp.js

@@ -380,25 +380,31 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
  * Uses: codex mcp add <name> -- <cmd> [args...]
  */
 function installMcpViaCodex(binaryPath, server, versionHome) {
-    if (server.config.transport === 'stdio') {
+    let args;
+    if (server.config.transport === 'http') {
+        if (!server.config.url)
+            throw new Error(`HTTP MCP '${server.name}' has no url`);
+        // codex mcp add <name> --url <url>
+        args = ['mcp', 'add', server.name, '--url', server.config.url];
+    }
+    else {
         // codex mcp add -- <name> <cmd> [args...]
-        const args = [
+        args = [
             'mcp', 'add',
             '--',
             server.name,
             server.config.command,
             ...(server.config.args || [])
         ];
-        // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
-        const spec = execFileShellSpec(binaryPath, args);
-        execFileSync(spec.command, spec.args, {
-            stdio: 'pipe',
-            timeout: 30000,
-            env: { ...process.env, HOME: versionHome },
-            shell: spec.shell,
-        });
     }
-    // Note: Codex may not support HTTP MCPs
+    // RUSH-1752: user-controlled MCP command/args must not reach cmd.exe unquoted.
+    const spec = execFileShellSpec(binaryPath, args);
+    execFileSync(spec.command, spec.args, {
+        stdio: 'pipe',
+        timeout: 30000,
+        env: { ...process.env, HOME: versionHome },
+        shell: spec.shell,
+    });
 }
 export async function registerMcpCommandToTargets(targets, name, commandSpec, scope = 'user', transport = 'stdio') {
     const results = [];

package/dist/lib/menubar/snapshot.d.ts

@@ -1,3 +1,4 @@
+import type { DeviceStats } from '../devices/health.js';
 import type { WatchdogTickResult } from '../watchdog/runner.js';
 /**
  * One registered fleet device, for the menu-bar's collapsible DEVICES section.
@@ -20,6 +21,47 @@ interface MenubarDevice {
     interactive: boolean;
     isLocal: boolean;
     preferred: boolean;
+    /**
+     * The operator's role mark — `worker` | `personal` | `desktop`, or `unknown`
+     * when the device was never marked (PHNX-3999 F25). Read from the same
+     * device-scope config `--device auto` consults, so the menu shows the fact that
+     * governs placement rather than a second notion of it.
+     */
+    role: string;
+    /**
+     * True when automatic placement (`agents run --device auto`) may pick this
+     * device: the verdict of the ONE canonical pool filter, so a `personal` box the
+     * user sits at reads as ineligible here exactly as it behaves there.
+     */
+    autoEligible: boolean;
+    /** Hardware facts and the current reading, or null when never observed. */
+    stats: MenubarDeviceStats | null;
+}
+/**
+ * One device's hardware facts and last reading, projected from the fleet-stats
+ * cache the CLI already keeps (`~/.agents/.cache/.fleet-stats.json`).
+ *
+ * Cache-only by construction: the snapshot never probes the fleet, so opening
+ * Settings costs nothing and a device nobody has measured says so. Every value
+ * is `null` when that number was not observed — never 0, which would render as a
+ * real "idle, empty disk" reading. `stale` carries the CLI's own freshness bound
+ * so the menu can label an old reading instead of showing it as live, and
+ * `observedAt` / `specsObservedAt` give the observation age F25 asks for
+ * (hardware totals survive an unreachable probe; current-state readings do not).
+ */
+interface MenubarDeviceStats {
+    reachable: boolean;
+    observedAt: string;
+    stale: boolean;
+    cpus: number | null;
+    memTotalBytes: number | null;
+    memFreeBytes: number | null;
+    memPercent: number | null;
+    diskTotalBytes: number | null;
+    diskFreeBytes: number | null;
+    diskUsedPercent: number | null;
+    loadPercent: number | null;
+    specsObservedAt: string | null;
 }
 interface MenubarSnapshot {
     version: 1;
@@ -55,6 +97,15 @@ interface MenubarSnapshot {
  * (only `defaultProject`) is omitted so the native app keeps its own default.
  */
 export declare function buildMenuPreferences(): Record<string, unknown>;
+/**
+ * Project one cached {@link DeviceStats} row into the snapshot shape, or `null`
+ * when the device has no cached reading at all.
+ *
+ * `?? null` rather than a default: an absent number means "not observed", and the
+ * menu renders that as unavailable. A 0 would be indistinguishable from a real
+ * measurement of an idle box or a full disk.
+ */
+export declare function projectDeviceStats(row: DeviceStats | undefined): MenubarDeviceStats | null;
 export declare function readLastWatchdogTick(stateDir?: string): WatchdogTickResult | null;
 /** One-process read model for AGI Menu's repeating three-minute refresh. */
 export declare function computeMenubarSnapshot(): Promise<MenubarSnapshot>;

package/dist/lib/menubar/snapshot.js

@@ -2,7 +2,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { buildRoutineListJson } from '../scheduling/routines.js';
 import { backfillActiveRowsFromIndex, isRunningLiveSession, serializeActiveSessionsForJson, serializeSessionsJson } from '../session/active.js';
-import { getConfigValue, loadAutoLaunchPreferences } from '../device-config.js';
+import { getConfigValue, listConfiguredDeviceRoles, loadAutoLaunchPreferences } from '../device-config.js';
+import { filterAutoPool } from '../devices/pool.js';
+import { isFreshDeviceStats, readStatsCache } from '../devices/stats-cache.js';
 import { MENUBAR_MENU_PROPERTIES } from '../config-keys.js';
 import { migrateMenubarPreferencesFromUserDefaults } from './migrate-prefs.js';
 import { loadDevices } from '../devices/registry.js';
@@ -35,12 +37,20 @@ export function buildMenuPreferences() {
  */
 async function buildMenubarDevices() {
     const reg = await loadDevices();
+    const roster = Object.keys(reg);
     // Pass the roster so a fleet-wide default (fleet.defaults.config) reaches
     // devices that have no doc of their own.
-    const prefs = loadAutoLaunchPreferences(Object.keys(reg));
+    const prefs = loadAutoLaunchPreferences(roster);
+    const roles = listConfiguredDeviceRoles(roster);
+    // The placement verdict from the one canonical filter — not a re-implementation
+    // of the role rule (`devices/pool.ts` owns it).
+    const autoEligible = new Set(filterAutoPool(roster, { roles, autoLaunch: prefs }));
+    // Cache read only: no ssh, no probe, so this still rides the existing snapshot
+    // poll (docs/menubar.md: the menu bar must not probe the fleet per render).
+    const stats = readStatsCache();
     const interactiveHost = getConfigValue('interactive.host').value;
     const self = machineId();
-    return Object.keys(reg)
+    return roster
         .sort()
         .map((name) => ({
         name,
@@ -50,8 +60,37 @@ async function buildMenubarDevices() {
         interactive: name === interactiveHost,
         isLocal: name === self,
         preferred: prefs[name]?.preferred === true,
+        role: roles[name] ?? 'unknown',
+        autoEligible: autoEligible.has(name),
+        stats: projectDeviceStats(stats[name]),
     }));
 }
+/**
+ * Project one cached {@link DeviceStats} row into the snapshot shape, or `null`
+ * when the device has no cached reading at all.
+ *
+ * `?? null` rather than a default: an absent number means "not observed", and the
+ * menu renders that as unavailable. A 0 would be indistinguishable from a real
+ * measurement of an idle box or a full disk.
+ */
+export function projectDeviceStats(row) {
+    if (!row)
+        return null;
+    return {
+        reachable: row.reachable,
+        observedAt: new Date(row.fetchedAt).toISOString(),
+        stale: !isFreshDeviceStats(row),
+        cpus: row.ncpu ?? null,
+        memTotalBytes: row.memTotalBytes ?? null,
+        memFreeBytes: row.memFreeBytes ?? null,
+        memPercent: row.memPercent ?? null,
+        diskTotalBytes: row.diskTotalBytes ?? null,
+        diskFreeBytes: row.diskFreeBytes ?? null,
+        diskUsedPercent: row.diskUsedPercent ?? null,
+        loadPercent: row.loadPercent ?? null,
+        specsObservedAt: row.specsFetchedAt ? new Date(row.specsFetchedAt).toISOString() : null,
+    };
+}
 export function readLastWatchdogTick(stateDir = path.join(getRuntimeStateDir(), 'watchdog')) {
     try {
         return JSON.parse(fs.readFileSync(path.join(stateDir, 'last-tick.json'), 'utf-8'));

package/dist/lib/open-url.js

@@ -9,10 +9,10 @@
  * The OS handler has none of that.
  *
  * Before this seam existed, `agents browser navigate` honoured the configured
- * profile and nothing else did: `fleet login`, `devices lease`, `feedback`, and
+ * profile and nothing else did: `devices lease`, `feedback`, and
  * the browser-session artifact opener each shelled straight to `open`/`xdg-open`,
  * so every one of them landed in whatever the OS handler happened to be. This
- * module replaces all of those call sites; do not add a sixth raw `open`.
+ * module replaces all of those call sites; do not add a new raw `open`.
  *
  * Never throws. A viewer that cannot be reached degrades to the OS handler with
  * one stderr line naming the reason, and a total failure returns `via: 'none'`

package/dist/lib/probe.d.ts

@@ -3,6 +3,9 @@
  * timeout — matching the `execFileAsync` contract the version probe had — and
  * reaps the probe's whole process group on every settle path.
  */
-export declare function probeCapture(cmd: string, args: string[], timeoutMs: number): Promise<{
+export declare function probeCapture(cmd: string, args: string[], timeoutMs: number, options?: {
+    acceptedExitCodes?: number[];
+    maxOutputBytes?: number;
+}): Promise<{
     stdout: string;
 }>;

package/dist/lib/probe.js

@@ -59,7 +59,7 @@ function reapGroup(pid) {
  * timeout — matching the `execFileAsync` contract the version probe had — and
  * reaps the probe's whole process group on every settle path.
  */
-export function probeCapture(cmd, args, timeoutMs) {
+export function probeCapture(cmd, args, timeoutMs, options = {}) {
     return new Promise((resolve, reject) => {
         const child = spawn(cmd, args, {
             detached: GROUP_REAP,
@@ -92,6 +92,9 @@ export function probeCapture(cmd, args, timeoutMs) {
         child.stdout?.setEncoding('utf8');
         child.stdout?.on('data', (d) => {
             out += d;
+            if (Buffer.byteLength(out) > (options.maxOutputBytes ?? 1024 * 1024)) {
+                settle(new Error(`probe output exceeded limit: ${cmd}`));
+            }
         });
         child.on('error', (e) => settle(e));
         // 'exit', not 'close': a forked grandchild inherits the stdout pipe, and
@@ -99,7 +102,7 @@ export function probeCapture(cmd, args, timeoutMs) {
         // process this helper exists to reap. Settle when the probed binary
         // itself exits; one tick's grace lets its final stdout chunks land.
         child.on('exit', (code) => {
-            setImmediate(() => settle(code === 0 ? null : new Error(`probe exited ${code}: ${cmd} ${args.join(' ')}`)));
+            setImmediate(() => settle(code !== null && (options.acceptedExitCodes ?? [0]).includes(code) ? null : new Error(`probe exited ${code}: ${cmd} ${args.join(' ')}`)));
         });
     });
 }

package/dist/lib/projects.d.ts

@@ -207,6 +207,29 @@ export declare function projectDirsAbs(def: ProjectDef, opts: {
  * home-relative variant lands (see docs/concepts.md).
  */
 export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
+export declare function listProjectDefsCached(): ProjectDef[];
+/** Drop the {@link listProjectDefsCached} memo — for tests that rewrite the dir within one mtime tick. */
+export declare function resetProjectDefsCache(): void;
+/**
+ * The **confirmed** project for a working directory, or `undefined` when the
+ * association is not confirmed (PHNX-3999 F08/F09).
+ *
+ * Confirmed means exactly one thing: a registered project definition
+ * ({@link projectNameForCwd}) whose root contains this path. Being inside *some*
+ * git repository is NOT a project association — a repo nobody registered, a
+ * checkout of someone else's code, or a loose directory that merely has a
+ * `.git` in it would each invent a project name out of a folder, which is the
+ * wrong-grouping the owner's recording shows at 01:30–01:56. So is a bare
+ * directory basename ({@link resolveProjectKey}, which always answers).
+ *
+ * A consumer renders `undefined` as Uncategorized and keeps the session
+ * reachable in its full list — nothing is hidden by not being grouped.
+ *
+ * Use {@link resolveProjectNameForCwd} instead when you want a best-effort
+ * bucket KEY for joining rows; use this when the answer is shown to a person as
+ * "this work belongs to that project".
+ */
+export declare function confirmedProjectForCwd(cwd: string | undefined | null, defs?: ProjectDef[]): string | undefined;
 /**
  * The canonical project label for a cwd, for every surface that buckets work by
  * project (the activity timeline, feed posts, the sessions overview): the