@phnx-labs/agents-cli 1.22.115 → 1.22.117

package/dist/lib/fleet/auth-sync.d.ts

@@ -1,5 +1,5 @@
 /**
- * Native-login inventory for `agents apply` and `agents fleet login`.
+ * Native-login inventory for `agents apply`.
  * Native OAuth/session files are identified only to report device readiness;
  * agents-cli never serializes or materializes them on another device.
  *
@@ -28,7 +28,7 @@ export declare const KEYCHAIN_BOUND_ON_MAC: ReadonlySet<string>;
  * collapsing the fleet to a single working login (droid/WorkOS collapsed 10 boxes
  * to 1 overnight — RUSH-1958). Add any newly-discovered single-use-rotation
  * harness here; the predicate below is the one place the propagation decision is
- * made. See also `remote-login.ts` and `usage.ts` for the per-machine-login policy.
+ * made. See also `usage.ts` for the per-machine-login policy.
  */
 export declare const SINGLE_USE_ROTATING_REFRESH_AGENTS: ReadonlySet<string>;
 /**
@@ -48,59 +48,6 @@ export declare function isCredentialSafeToPropagate(_agent: string): boolean;
 export declare function hasPortableAuthFiles(agent: string): boolean;
 /** Which agents `apply` can propagate auth for at all. */
 export declare function isPropagatableAgent(agent: string): boolean;
-/**
- * The shape of a login flow — enough for `agents fleet login` to drive a remote
- * box's device-code OAuth over SSH and scrape the verification URL + user code.
- *
- * `flowType` decides remotability:
- *  - `device-code` — the remote box prints a URL + short code the human enters in
- *    a browser on THIS machine. The only flow `fleet login` can orchestrate.
- *  - `loopback`    — the CLI opens a browser and listens on 127.0.0.1 on the
- *    remote box; the redirect must reach that box's own loopback, so it can only
- *    be completed with a browser on the same machine. Non-remotable.
- *  - `api-key`     — a pasted key, not an OAuth handshake. Non-remotable.
- *  - `unknown`     — flow not yet characterized (no captured output). Non-remotable
- *    until someone captures the real pattern and fills the regexes.
- */
-export type LoginFlowType = 'device-code' | 'loopback' | 'api-key' | 'unknown';
-export interface LoginFlow {
-    /**
-     * The exact command that starts the login flow on the remote box, run as
-     * `ssh -tt <box> <loginCommand>`. Bare `<cli>` for agents whose device flow
-     * starts on launch (droid, kimi, antigravity), `<cli> login` for
-     * codex/grok, `<cli> auth login` for opencode.
-     */
-    loginCommand: string;
-    flowType: LoginFlowType;
-    /**
-     * Keystrokes sent after launch to force the device-code path when the CLI
-     * presents a menu (codex: pick "Sign in with Device Code") or requires a
-     * sub-command inside a TUI (kimi: `/login`). Sent verbatim through the PTY,
-     * so it must include the submitting CR (`\r`). Absent when the flow needs no
-     * steering.
-     */
-    deviceCodeSelect?: string;
-    /** Captures the verification URL from scraped login output (group 1 preferred). */
-    verificationUrlRegex?: RegExp;
-    /** Captures the user code from scraped login output (group 1 preferred). */
-    userCodeRegex?: RegExp;
-    /**
-     * Home-relative credential file that appears / bumps mtime on success — the
-     * completion signal. Mirrors {@link FLEET_AUTH_FILES} (first entry for agents
-     * with several).
-     */
-    successFile: string;
-}
-/**
- * Per-agent login flows, populated from live login-output captures (the only
- * ground truth — no fixtures exist upstream). Agents whose real device-code
- * output has not been captured are marked honestly (`unknown` / no regexes) so
- * `fleet login` flags them non-remotable instead of guessing.
- *
- * Only the `device-code` entries are ones `fleet login` drives; the rest are
- * carried so the command can explain WHY a logged-out pair is not remotable.
- */
-export declare const FLEET_LOGIN_FLOWS: Record<string, LoginFlow>;
 export interface SnapshotOptions {
     /** Home directory to read credential files from. */
     home: string;

package/dist/lib/fleet/auth-sync.js

@@ -1,5 +1,5 @@
 /**
- * Native-login inventory for `agents apply` and `agents fleet login`.
+ * Native-login inventory for `agents apply`.
  * Native OAuth/session files are identified only to report device readiness;
  * agents-cli never serializes or materializes them on another device.
  *
@@ -35,7 +35,7 @@ export const KEYCHAIN_BOUND_ON_MAC = new Set(['claude', 'antigravity']);
  * collapsing the fleet to a single working login (droid/WorkOS collapsed 10 boxes
  * to 1 overnight — RUSH-1958). Add any newly-discovered single-use-rotation
  * harness here; the predicate below is the one place the propagation decision is
- * made. See also `remote-login.ts` and `usage.ts` for the per-machine-login policy.
+ * made. See also `usage.ts` for the per-machine-login policy.
  */
 export const SINGLE_USE_ROTATING_REFRESH_AGENTS = new Set(['droid']);
 /**
@@ -61,93 +61,6 @@ export function hasPortableAuthFiles(agent) {
 export function isPropagatableAgent(agent) {
     return hasPortableAuthFiles(agent) && isCredentialSafeToPropagate(agent);
 }
-/** The success-file for an agent — the primary portable credential (first spec). */
-function successFileFor(agent) {
-    const specs = FLEET_AUTH_FILES[agent];
-    if (!specs || specs.length === 0)
-        throw new Error(`no auth file spec for agent '${agent}'`);
-    return specs[0].rel;
-}
-/**
- * Per-agent login flows, populated from live login-output captures (the only
- * ground truth — no fixtures exist upstream). Agents whose real device-code
- * output has not been captured are marked honestly (`unknown` / no regexes) so
- * `fleet login` flags them non-remotable instead of guessing.
- *
- * Only the `device-code` entries are ones `fleet login` drives; the rest are
- * carried so the command can explain WHY a logged-out pair is not remotable.
- */
-export const FLEET_LOGIN_FLOWS = {
-    // droid: launches its TUI and prints, verbatim:
-    //   "If the link does not open automatically, please visit
-    //    https://auth.factory.ai/device and enter code MJQW-NQRM to complete
-    //    authentication." then "Waiting for authentication to complete...".
-    droid: {
-        loginCommand: 'droid',
-        flowType: 'device-code',
-        verificationUrlRegex: /please visit\s+(https:\/\/\S+?)\s+and enter code/i,
-        userCodeRegex: /enter code\s+([A-Z0-9]{4}-[A-Z0-9]{4})/i,
-        successFile: successFileFor('droid'),
-    },
-    // codex login shows a numbered menu; option 2 ("Sign in with Device Code",
-    // "Sign in from another device with a one-time code") is the remotable one.
-    // The post-selection URL/code output was not captured this session, so the
-    // regexes are best-effort generic device-code patterns — TODO: tighten once a
-    // real codex device-code screen is captured.
-    codex: {
-        loginCommand: 'codex login',
-        flowType: 'device-code',
-        deviceCodeSelect: '\x1b[B\r', // down-arrow once (to option 2) + Enter
-        verificationUrlRegex: /(https:\/\/\S*(?:device|activate|login|auth)\S*)/i,
-        userCodeRegex: /\b([A-Z0-9]{4}-[A-Z0-9]{4})\b/,
-        successFile: successFileFor('codex'),
-    },
-    // kimi: launch bare `kimi`, then `/login` inside the TUI, which prints
-    // "Select a platform and authenticate". Post-selection URL/code not captured —
-    // best-effort regexes, TODO: tighten with a real capture.
-    kimi: {
-        loginCommand: 'kimi',
-        flowType: 'device-code',
-        deviceCodeSelect: '/login\r',
-        verificationUrlRegex: /(https:\/\/\S+)/i,
-        userCodeRegex: /\b([A-Z0-9]{4}-[A-Z0-9]{4})\b/,
-        successFile: successFileFor('kimi'),
-    },
-    // grok: `grok login`. No captured pattern this session — flowType is
-    // device-code (best guess for the remotable path) but regexes are left unset
-    // (TODO: capture grok's login output), so scrapeLogin yields nothing until a
-    // real pattern is added and driveRemoteLogin will time out rather than guess.
-    grok: {
-        loginCommand: 'grok login',
-        flowType: 'device-code',
-        successFile: successFileFor('grok'),
-    },
-    // antigravity: bare `agy`, Google OAuth. Keychain-bound on macOS and loopback
-    // (browser + 127.0.0.1 listener on the box itself) — non-remotable.
-    antigravity: {
-        loginCommand: 'agy',
-        flowType: 'loopback',
-        successFile: successFileFor('antigravity'),
-    },
-    // opencode: `opencode auth login`. No captured pattern — unknown/non-remotable.
-    opencode: {
-        loginCommand: 'opencode auth login',
-        flowType: 'unknown',
-        successFile: successFileFor('opencode'),
-    },
-    // claude: interactive `/login` inside the TUI is a loopback browser flow, and
-    // the token is keychain-bound on macOS. That native login stays per-box and
-    // is never copied. The shareable `claude setup-token` mint is a different
-    // credential class — minted by `agents accounts add claude [name]` /
-    // `agents accounts login claude#<name>` (`lib/auth-mint.ts`), not as a
-    // fleet-login device-code flow (a setup-token is account-scoped, not
-    // per-machine).
-    claude: {
-        loginCommand: 'claude',
-        flowType: 'loopback',
-        successFile: successFileFor('claude'),
-    },
-};
 /**
  * Capture portable credential files for the given agents from a source home.
  * Returns the readable file payloads plus the list of agents whose auth is

package/dist/lib/harness-auth-capabilities.js

@@ -1,14 +1,19 @@
 export const HARNESS_AUTH = {
     claude: { login: ['auth', 'login'], status: ['auth', 'status'], identity: 'strong', worker: 'setup-token', slotEnv: 'CLAUDE_CONFIG_DIR' },
     codex: { login: ['login'], status: ['login', 'status'], identity: 'strong', worker: ['api-key:OPENAI_API_KEY', 'per-device:device-auth'], slotEnv: 'CODEX_HOME' },
-    grok: { login: ['login'], status: null, identity: 'strong', worker: 'api-key:XAI_API_KEY', slotEnv: 'GROK_HOME' },
+    // `--device-auth` pins the device-code flow: bare `grok login` defaults to
+    // `--oauth`, the loopback browser flow, which opens whatever browser profile
+    // the OS defaults to. The device-code screen prints the URL + code instead,
+    // so the human finishes it in the browser profile they choose — which is
+    // what makes it usable over an SSH shell on a worker.
+    grok: { login: ['login', '--device-auth'], status: null, identity: 'strong', worker: 'api-key:XAI_API_KEY', slotEnv: 'GROK_HOME' },
     // auth.json has no email claim; identity is the sorted provider-id join
     // (`resolveOpenCodeAccountId`). NATIVE_ACCOUNT_CAPABILITIES.opencode.inspection
     // is already 'opaque'.
     opencode: { login: ['auth', 'login'], status: ['auth', 'list'], identity: 'opaque', worker: 'api-key:provider', slotEnv: 'XDG_DATA_HOME' },
     cursor: { login: ['login'], status: ['status'], identity: 'strong', worker: 'api-key:CURSOR_API_KEY', slotEnv: null },
     // No finite login argv — launch bare `kimi`, then `/login` in the TUI
-    // (`loginHint('kimi') === 'kimi'`, fleet/auth-sync `loginCommand: 'kimi'`).
+    // (`loginHint('kimi') === 'kimi'`).
     kimi: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: 'KIMI_CODE_HOME' },
     antigravity: { login: null, status: null, identity: 'opaque', worker: 'none', slotEnv: null },
     droid: { login: null, status: null, identity: 'opaque', worker: 'api-key:FACTORY_API_KEY', slotEnv: null },

package/dist/lib/hosts/dispatch.d.ts

@@ -1,4 +1,5 @@
 import type { Host } from './types.js';
+import { remoteShellFor } from './remote-cmd.js';
 import { type HostTask } from './tasks.js';
 import { type HostCredentials } from './credentials.js';
 import { deriveMirroredCwd, homeRemainder, remoteCdPrefix } from '../project-root.js';
@@ -31,6 +32,13 @@ export declare function withActorEnv(env?: Record<string, string>): Record<strin
  * place.
  */
 export declare function remoteRunShellPrelude(agent: string, extra?: Record<string, string>): string;
+/**
+ * The env every remote `agents run` dispatch carries across the SSH hop —
+ * actor provenance, the `run auto` chain-hop guard, and the caller's path
+ * markers. `remoteRunShellPrelude` renders it as POSIX exports; a Windows peer
+ * gets the same record as `$env:` assignments in its PowerShell script.
+ */
+export declare function remoteRunEnv(agent: string, extra?: Record<string, string>): Record<string, string>;
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *
@@ -146,7 +154,7 @@ export interface DispatchOptions {
     copyCreds?: HostCredentials;
 }
 export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
-interface InteractiveDispatchOptions {
+export interface InteractiveDispatchOptions {
     agent: string;
     /** Explicit agent version pin (e.g. "2.1.207") to forward as `agent@version`. */
     version?: string;
@@ -199,6 +207,17 @@ interface InteractiveDispatchOptions {
  * infer headless from the prompt).
  */
 export declare function buildInteractiveRunForwardedArgs(opts: InteractiveDispatchOptions): string[];
+/**
+ * The remote command of an interactive host dispatch, by peer shell.
+ *
+ * A Windows peer's sshd hands the command to PowerShell, which cannot parse the
+ * POSIX `export …; { cd … || cd "$HOME"; } && agents …` form (a `run --device
+ * <windows box>` from a TTY died with `At line:1 char:420` at the `||`). That
+ * peer gets the rendered PowerShell every other `--device` site uses — env,
+ * mirrored cwd and argv inside one `-EncodedCommand` — the interactive analogue
+ * of `buildWindowsDetachedLaunchCommand`.
+ */
+export declare function buildInteractiveRemoteCommand(remoteShell: ReturnType<typeof remoteShellFor>, opts: InteractiveDispatchOptions): string;
 /**
  * Run an agent interactively on a host, forwarding the local TTY over SSH.
  * Returns the SSH exit code. The remote `agents` CLI is responsible for its own

package/dist/lib/hosts/dispatch.js

@@ -13,7 +13,7 @@ import { randomUUID } from 'crypto';
 import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { hostIdentityArgs, sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
-import { encodePowershell, powershellQuote, remoteShellFor, posixEnvExports } from './remote-cmd.js';
+import { buildWindowsAgentsCommand, encodePowershell, powershellQuote, remoteShellFor, posixEnvExports, windowsRemotePath, windowsSetLocation } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { resolveActor, actorEnv } from '../actor.js';
 import { saveTask, updateTask, terminalPatch } from './tasks.js';
@@ -85,10 +85,19 @@ export function withActorEnv(env) {
  * place.
  */
 export function remoteRunShellPrelude(agent, extra = {}) {
-    const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
-    const exports = posixEnvExports(withActorEnv({ ...guard, ...extra }));
+    const exports = posixEnvExports(remoteRunEnv(agent, extra));
     return exports ? `${exports}; ` : '';
 }
+/**
+ * The env every remote `agents run` dispatch carries across the SSH hop —
+ * actor provenance, the `run auto` chain-hop guard, and the caller's path
+ * markers. `remoteRunShellPrelude` renders it as POSIX exports; a Windows peer
+ * gets the same record as `$env:` assignments in its PowerShell script.
+ */
+export function remoteRunEnv(agent, extra = {}) {
+    const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
+    return withActorEnv({ ...guard, ...extra });
+}
 /**
  * Launch a detached login-shell command in its own Unix session/process group.
  *
@@ -107,21 +116,12 @@ export function buildDetachedLaunchCommand(inner) {
     ].join(' ');
     return `bash -lc ${shellQuote(`node -e ${shellQuote(nodeScript)}`)}`;
 }
-function windowsRemotePath(path) {
-    return path.startsWith('$HOME/')
-        ? `(Join-Path $HOME ${powershellQuote(path.slice('$HOME/'.length))})`
-        : powershellQuote(path);
-}
 /** Build the detached PowerShell launch protocol used by Windows SSH hosts. */
 export function buildWindowsDetachedLaunchCommand(opts) {
     const log = windowsRemotePath(opts.remoteLog);
     const exit = windowsRemotePath(opts.remoteExit);
     const env = Object.entries(opts.env).map(([key, value]) => `$env:${key} = ${powershellQuote(value)}`);
-    const cwd = opts.remoteCwd
-        ? opts.mirrorCwd
-            ? `try { Set-Location -LiteralPath ${powershellQuote(opts.remoteCwd)} } catch { Set-Location -LiteralPath $HOME }`
-            : `Set-Location -LiteralPath ${powershellQuote(opts.remoteCwd)}`
-        : '';
+    const cwd = opts.remoteCwd ? windowsSetLocation(opts.remoteCwd, opts.mirrorCwd) : '';
     const inner = [
         `$ProgressPreference = 'SilentlyContinue'`,
         `$PSDefaultParameterValues['Out-File:Encoding'] = 'utf8'`,
@@ -273,7 +273,7 @@ async function launchDetached(host, target, opts) {
             mirrorCwd: opts.mirrorCwd,
             remoteLog,
             remoteExit,
-            env: withActorEnv(opts.agentLabel === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {}),
+            env: remoteRunEnv(opts.agentLabel),
         })
         : `mkdir -p ${REMOTE_DIR}; ${buildDetachedLaunchCommand(inner)}`;
     const res = sshExec(target, launch, {
@@ -471,19 +471,17 @@ export function buildInteractiveRunForwardedArgs(opts) {
     return args;
 }
 /**
- * Run an agent interactively on a host, forwarding the local TTY over SSH.
- * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
- * tmux wrapping; the local machine is just the transport.
+ * The remote command of an interactive host dispatch, by peer shell.
+ *
+ * A Windows peer's sshd hands the command to PowerShell, which cannot parse the
+ * POSIX `export …; { cd … || cd "$HOME"; } && agents …` form (a `run --device
+ * <windows box>` from a TTY died with `At line:1 char:420` at the `||`). That
+ * peer gets the rendered PowerShell every other `--device` site uses — env,
+ * mirrored cwd and argv inside one `-EncodedCommand` — the interactive analogue
+ * of `buildWindowsDetachedLaunchCommand`.
  */
-export async function runInteractiveOnHost(host, opts) {
-    const target = sshTargetFor(host);
-    // Concrete version pins fail loud here (RUSH-2313) so we never open a TTY
-    // to a box that cannot run the pin.
-    const { warnings } = ensureHostReady(host, { agent: opts.agent, version: opts.version });
-    for (const w of warnings)
-        process.stderr.write(`[hosts] warning: ${w}\n`);
-    const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
-    const cwd = remoteCdPrefix(opts.remoteCwd, { mirror: opts.mirrorCwd });
+export function buildInteractiveRemoteCommand(remoteShell, opts) {
+    const forwardedArgs = buildInteractiveRunForwardedArgs(opts);
     // Forward actor provenance so the interactive remote run inherits it rather
     // than re-resolving from this box's SSH_CONNECTION (RUSH-2028); a `run auto`
     // dispatch also gets the chain-hop guard (remoteRunShellPrelude).
@@ -496,11 +494,35 @@ export async function runInteractiveOnHost(host, opts) {
     // longer forces the tmux wrap on a TTY-followed run — the peer's
     // tmux.enabled decides that. Set here, on the interactive path only:
     // `launchDetached` already setsids the headless one.
-    const prelude = remoteRunShellPrelude(opts.agent, { [REMOTE_INTERACTIVE_ENV]: '1' });
-    let remoteCmd = `${prelude}${cwd}${invocation}`;
-    if (opts.copyCreds) {
-        remoteCmd = wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds);
+    const env = { [REMOTE_INTERACTIVE_ENV]: '1' };
+    if (remoteShell === 'powershell') {
+        if (opts.copyCreds)
+            throw new Error('--copy-creds cannot ride an interactive dispatch to a Windows host');
+        return buildWindowsAgentsCommand({
+            args: forwardedArgs,
+            env: remoteRunEnv(opts.agent, env),
+            cwd: opts.remoteCwd,
+            mirrorCwd: opts.mirrorCwd,
+        });
     }
+    const invocation = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
+    const cwd = remoteCdPrefix(opts.remoteCwd, { mirror: opts.mirrorCwd });
+    const remoteCmd = `${remoteRunShellPrelude(opts.agent, env)}${cwd}${invocation}`;
+    return opts.copyCreds ? wrapHostCommandWithCredentials(remoteCmd, opts.copyCreds) : remoteCmd;
+}
+/**
+ * Run an agent interactively on a host, forwarding the local TTY over SSH.
+ * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
+ * tmux wrapping; the local machine is just the transport.
+ */
+export async function runInteractiveOnHost(host, opts) {
+    const target = sshTargetFor(host);
+    // Concrete version pins fail loud here (RUSH-2313) so we never open a TTY
+    // to a box that cannot run the pin.
+    const { warnings } = ensureHostReady(host, { agent: opts.agent, version: opts.version });
+    for (const w of warnings)
+        process.stderr.write(`[hosts] warning: ${w}\n`);
+    const remoteCmd = buildInteractiveRemoteCommand(remoteShellFor(host.os ?? resolveRemoteOsSync(host.name)), opts);
     // Credentials ride this stream when --copy-creds is set: verify the host key
     // strictly against the managed pin and force a fresh connection so a stale
     // accept-new control socket can't bypass the check (RUSH-1767).

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;
@@ -188,6 +194,21 @@ export declare function stripClixml(stdout: string): string;
  * 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

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

@@ -10,6 +10,7 @@
 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
@@ -108,6 +109,7 @@ export const RUN_OPTION_FORWARDING = {
     disableTmux: 'local-only',
     device: 'local-only',
     where: 'local-only', // expands into host/lease before dispatch; never re-forwarded
+    local: 'local-only', // this machine by definition — a local run never reaches the SSH boundary
     on: 'local-only',
     computer: 'local-only',
     any: 'local-only',
@@ -363,8 +365,31 @@ export function windowsAgentsInvocation(args, binName = 'agents') {
         // 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 { 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.
@@ -373,7 +398,7 @@ export function windowsAgentsScript(cmd) {
         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(windowsSetLocation(cwd, mirrorCwd));
     parts.push(windowsAgentsInvocation(args));
     if (propagateExit) {
         if (remapExit255)

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/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>;