@phnx-labs/agents-cli 1.22.102 → 1.22.104

package/dist/lib/computer-client.js

@@ -0,0 +1,222 @@
+/**
+ * computer-client.ts — the ONE process client through which agents-cli talks to
+ * the standalone `computer` CLI (PHNX-4075).
+ *
+ * This is the agents-owned half of the computer extraction, and it is
+ * deliberately small. agents-cli no longer carries a helper daemon, an RPC
+ * transport, an element cache, an RFB client, or an autonomous loop — the
+ * standalone engine owns all of it, exactly as `secrets` took the keychain
+ * engine (PHNX-3989) and `sessions` took the transcript engine (PHNX-4012).
+ * What stays here is what only the fleet CLI can know: which apps the
+ * permissions layer allows, which device a `--device` name resolves to, who the
+ * acting session is, and where an action must be recorded.
+ *
+ * THERE IS NO FALLBACK. A missing executable throws `COMPUTER_BIN_MISSING` with
+ * install guidance (DIST-1) rather than silently driving a bundled engine —
+ * agents-cli has none to drive, and a fallback would re-couple the two release
+ * trains this extraction exists to separate.
+ *
+ * Transport — inherited-fd passthrough, not request/response:
+ *
+ * The engine's ENVIRONMENT is inherited verbatim — no overlay. Transport
+ * selection (`COMPUTER_HELPER_TCP`, `COMPUTER_HELPER_VNC`,
+ * `COMPUTER_HELPER_SOCKET`) is the engine's: it opens the `--device` tunnel and
+ * hydrates its own endpoint AND the auth token that goes with it. Publishing a
+ * bare endpoint from here would hand the daemon a connection it then rejects
+ * with `auth_failed`.
+ *
+ *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
+ *     stdout is the command's stdout, its `--json` is the command's `--json`,
+ *     its prompts reach a real tty. agents-cli never re-formats engine output,
+ *     which is what keeps the surface honest as the engine evolves.
+ *   - fd 3 (`COMPUTER_CONTEXT_FD`) carries ONE JSON object — the consumer
+ *     context built by `lib/computer/context.ts` — written and closed
+ *     immediately, so the engine reads to EOF and proceeds.
+ *   - fd 4 (`COMPUTER_EVENTS_FD`) carries NDJSON action events back: one JSON
+ *     object per line, each an action the engine actually performed. agents-cli
+ *     turns those into feed events and `sessions --computer` history
+ *     (`lib/computer/record.ts`). The engine may emit none; it must never block
+ *     on this pipe.
+ *
+ * Both fds are anonymous pipes on the child's side, the same shape
+ * `secrets-client.ts` settled on after a named FIFO wedged macOS reads. The
+ * context is pushed rather than pulled so the engine needs no callback into
+ * agents-cli — one direction each way, no reentrancy.
+ */
+import { spawn } from 'node:child_process';
+import { realpathSync, existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { findInPath } from './agent-spec/agents.js';
+const INSTALL_HINT = 'npm i -g @phnx-labs/computer-cli';
+/** fd the engine reads its one-shot JSON context from. */
+export const COMPUTER_CONTEXT_FD = 3;
+/** fd the engine writes NDJSON action events to. */
+export const COMPUTER_EVENTS_FD = 4;
+export class ComputerClientError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ComputerClientError';
+    }
+}
+export function isComputerClientError(err) {
+    return err instanceof ComputerClientError;
+}
+let cachedBin;
+function computerEntrypoint(bin) {
+    if (!/\.(cmd|ps1)$/i.test(bin))
+        return bin;
+    const launcher = path.join(path.dirname(bin), 'node_modules', '@phnx-labs', 'computer-cli', 'bin', 'computer.cjs');
+    return existsSync(launcher) ? launcher : bin;
+}
+export function isStandaloneComputer(bin) {
+    let real = computerEntrypoint(bin);
+    try {
+        real = realpathSync(real);
+    }
+    catch { /* spawn reports missing explicit paths */ }
+    return !/\.(cmd|ps1)$/i.test(real) && !real.endsWith(path.join('dist', 'computer.js'));
+}
+/**
+ * Resolve the standalone executable. `COMPUTER_BIN` wins so a dev build can be
+ * driven without touching PATH.
+ *
+ * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims`. That skip
+ * is load-bearing here for the same reason it is in `sessions-client.ts`: a
+ * leftover `computer` alias shim execs `agents computer`, and resolving it would
+ * recurse into this process (the 1.22.85 secrets fork bomb, agi-cli#3532).
+ */
+export function resolveComputerBin() {
+    if (cachedBin)
+        return cachedBin;
+    const explicit = process.env.COMPUTER_BIN?.trim();
+    const resolved = explicit && explicit.length > 0 ? (isStandaloneComputer(explicit) ? explicit : null) : findInPath('computer', { accept: isStandaloneComputer });
+    if (!resolved) {
+        throw new ComputerClientError('COMPUTER_BIN_MISSING', 'The standalone `computer` CLI was not found. Install it with:\n' +
+            `  ${INSTALL_HINT}\n` +
+            'or point $COMPUTER_BIN at its executable.');
+    }
+    cachedBin = computerEntrypoint(resolved);
+    return cachedBin;
+}
+/** A `.js` bin is run through this runtime; a real executable is exec'd directly. */
+export function invocation(bin) {
+    if (/\.[mc]?js$/.test(bin))
+        return { command: process.execPath, prefix: [bin] };
+    return { command: bin, prefix: [] };
+}
+/**
+ * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
+ * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
+ * trailing partial line carried forward — are unit-testable without a spawn.
+ *
+ * A malformed line is dropped, not thrown: these events are telemetry riding
+ * alongside a user-visible action that already happened. Failing the command
+ * because its receipt was unreadable would be strictly worse than losing the
+ * receipt. The action itself already failed loud on its own channel if it failed.
+ */
+export function parseEventLines(buffer) {
+    const events = [];
+    const parts = buffer.split('\n');
+    const rest = parts.pop() ?? '';
+    for (const line of parts) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && typeof parsed.command === 'string') {
+                events.push(parsed);
+            }
+        }
+        catch {
+            // Unreadable receipt — see above.
+        }
+    }
+    return { events, rest };
+}
+/**
+ * Run the standalone engine with the consumer context on fd 3 and the action
+ * event stream on fd 4. Resolves with the engine's exit code; the caller
+ * propagates it so `agents computer` exits exactly as the engine did.
+ *
+ * Throws `COMPUTER_BIN_MISSING` when the standalone is not installed. Every
+ * other failure is the engine's own, reported on the inherited stderr.
+ */
+export async function runComputer(opts) {
+    const bin = resolveComputerBin();
+    const { command, prefix } = invocation(bin);
+    const child = spawn(command, [...prefix, ...opts.argv], {
+        stdio: ['inherit', opts.capture ? 'pipe' : 'inherit', 'inherit', 'pipe', 'pipe'],
+        env: {
+            ...process.env,
+            COMPUTER_CONTEXT_FD: String(COMPUTER_CONTEXT_FD),
+            COMPUTER_EVENTS_FD: String(COMPUTER_EVENTS_FD),
+        },
+    });
+    const contextPipe = child.stdio[COMPUTER_CONTEXT_FD];
+    const eventsPipe = child.stdio[COMPUTER_EVENTS_FD];
+    if (contextPipe) {
+        // An engine that exits before reading the context (bad argv, `--help`)
+        // closes fd 3 and we get EPIPE. That is a normal race, not a failure.
+        contextPipe.on('error', () => { });
+        contextPipe.end(JSON.stringify(opts.context) + '\n');
+    }
+    let stdout = '';
+    if (opts.capture && child.stdout) {
+        child.stdout.setEncoding('utf-8');
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk;
+        });
+    }
+    let pending = '';
+    const drained = new Promise((resolve) => {
+        if (!eventsPipe)
+            return resolve();
+        eventsPipe.setEncoding('utf-8');
+        eventsPipe.on('data', (chunk) => {
+            const { events, rest } = parseEventLines(pending + chunk);
+            pending = rest;
+            for (const event of events)
+                opts.onEvent?.(event);
+        });
+        eventsPipe.on('error', () => resolve());
+        eventsPipe.on('end', () => {
+            // A final line with no trailing newline still counts.
+            const { events } = parseEventLines(pending.endsWith('\n') ? pending : pending + '\n');
+            pending = '';
+            for (const event of events)
+                opts.onEvent?.(event);
+            resolve();
+        });
+    });
+    const exitCode = await new Promise((resolve, reject) => {
+        child.on('error', (err) => {
+            reject(new ComputerClientError('COMPUTER_SPAWN_FAILED', `Could not run \`${bin}\`: ${err.message}`));
+        });
+        child.on('close', (code, signal) => {
+            // A signalled child has no exit code; report the conventional 128+n so
+            // callers and shells see a non-zero status instead of a false success.
+            if (code == null)
+                return resolve(signal ? 128 + (osSignalNumber(signal) ?? 0) : 1);
+            resolve(code);
+        });
+    });
+    await drained;
+    return { exitCode, stdout };
+}
+/** Signal name → number for the 128+n exit convention. Only the ones a tunnelled
+ * or interrupted engine realistically dies on; anything else contributes 0 and
+ * still yields a non-zero status. */
+function osSignalNumber(signal) {
+    const table = {
+        SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGPIPE: 13, SIGTERM: 15,
+    };
+    return table[signal];
+}
+/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
+export function _resetComputerClientForTest() {
+    cachedBin = undefined;
+}
+export const COMPUTER_INSTALL_HINT = INSTALL_HINT;

package/dist/lib/exec.js

@@ -18,7 +18,7 @@ import { emit, createTimer, redactPrompt, redactArgs } from './feed/events.js';
 import { sanitizeProcessEnv } from './secrets-client.js';
 import { resolveActor, actorEnv } from './actor.js';
 import { expandLocalHome } from './project-root.js';
-import { getShimsDir, getHistoryDir, getRuntimeStateDir } from './state.js';
+import { getShimsDir, getHistoryDir, getUserAgentsDir, getRuntimeStateDir } from './state.js';
 import { readCodexConfiguredModel } from './installations/shims.js';
 import { withInstallationLease } from './installations/launch-gate.js';
 import { getCliLaunch, getAgentsBinPath } from './cli-entry.js';
@@ -41,6 +41,7 @@ import { applyAddDirs } from './add-dir.js';
 import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
 import { applySystemResourcesAtRun } from './system-run-sync.js';
 import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js';
+import { claudeWorkerLoginTrapPreflight } from './harness/adapters/claude.js';
 import { resolveConfigVersion } from './harness/exec-config-version.js';
 import { getAccountInfo } from './agents.js';
 import { getUsageLookupKey, noteClaudeSessionLimit, noteClaudeOutOfCredits, clearClaudeAccountRefusal, parseClaudeSessionLimitReset } from './accounting/usage.js';
@@ -399,6 +400,13 @@ export function buildExecEnv(options) {
         result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
     }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
+    // The agent's own `secrets …` calls must hit the same store agents-cli reads
+    // for it: the process client points the standalone at the user agents dir
+    // (buildServeEnv, MIG-1), while a bare `secrets` defaults to ~/.secrets. Left
+    // unset, an agent's `secrets exec` ran against a second broker and a second
+    // event log, and an unlock in one was invisible in the other. An explicit
+    // SECRETS_HOME in the launching environment wins, matching buildServeEnv.
+    result.SECRETS_HOME = result.SECRETS_HOME ?? getUserAgentsDir();
     // Durable SessionStart metadata. The hook joins these launch facts to the
     // harness-provided real session id and writes them under the shared history
     // directory, so a later resume can restore the permission boundary without
@@ -1797,6 +1805,32 @@ async function spawnAgentLeased(options) {
             }
         }
     }
+    // Fail loud before an INTERACTIVE claude run on a worker with no synced
+    // credential falls through to Claude Code's "Select login method" screen — an
+    // interactive OAuth on a headless box that never persists, the 10-minute
+    // re-login loop (PHNX-3502 sibling). A worker authenticates from the
+    // setup-token; when none resolves for the selected account, refuse with the
+    // real fix instead of the useless login prompt. Headless already fails loud
+    // (401), so the gate is interactive-only (the preflight enforces that).
+    if (options.agent === 'claude') {
+        const { versionHome } = resolveExecConfigHome(options);
+        // A credential reaches the child if the worker setup-token resolves for the
+        // selected account OR the caller passed an explicit --env override
+        // (buildExecEnv merges options.env last, so it wins even the worker strip).
+        const hasWorkerCredential = Boolean(options.env?.CLAUDE_CODE_OAUTH_TOKEN) ||
+            (versionHome ? resolveClaudeSetupToken(versionHome) !== null : false);
+        const loginTrap = claudeWorkerLoginTrapPreflight({
+            agent: options.agent,
+            interactive,
+            deviceRole: selfConfiguredDeviceRole(),
+            hasWorkerCredential,
+            machine: machineId(),
+        });
+        if (loginTrap) {
+            process.stderr.write(`\x1b[31m${loginTrap}\x1b[0m\n`);
+            return { exitCode: 1, stdout: '', stderr: loginTrap };
+        }
+    }
     // Budget live kill-switch (issue #346). For headless runs we incrementally
     // parse stream-json usage off stdout, accumulate cost, and kill the child the
     // moment a configured cap is crossed — exactly like the --timeout path, but

package/dist/lib/harness/adapters/claude.d.ts

@@ -1,2 +1,39 @@
+import type { AgentId } from '../../types.js';
 import type { HarnessAdapter } from '../adapter.js';
+import { type ConfiguredDeviceRole } from '../../device-config.js';
 export declare const claudeAdapter: HarnessAdapter;
+/**
+ * Fail-loud preflight for the worker login-screen trap — the sibling of the
+ * PHNX-3502 fix. On an EXPLICIT `role: worker` device every Claude run
+ * authenticates from the synced `setup-token`, never an interactive login (owner
+ * rule / credential-management invariant 7). When NO setup-token resolves for the
+ * account this run selected, `applyExecConfigEnv` strips any ambient token and
+ * the harness launches with no credential. A HEADLESS run then fails loud with a
+ * 401 — but an INTERACTIVE dispatched TUI (`agents run claude --interactive
+ * --device <worker>`, the usual `--device auto` landing) instead drops to Claude
+ * Code's own "Select login method" screen. Answering it does an interactive OAuth
+ * on a headless box, minting a native login the worker path never reads and never
+ * syncs; Anthropic later expires it and the next run repeats the prompt — the
+ * 10-minute re-login loop the operator sees.
+ *
+ * This gate refuses that run BEFORE spawn with the real fix (pin or mint a
+ * durable account) instead of the useless login prompt. It is interactive-only
+ * because the headless 401 is already loud. Pure: the caller (spawnAgentLeased)
+ * resolves the inputs and renders the returned message, exactly like
+ * codexSandboxPreflight. Returns null when the run may proceed.
+ */
+export declare function claudeWorkerLoginTrapPreflight(args: {
+    agent: AgentId;
+    interactive: boolean;
+    deviceRole?: ConfiguredDeviceRole;
+    /**
+     * Will a Claude credential actually reach the child at spawn? The caller ORs
+     * the resolved worker setup-token with an explicit `--env
+     * CLAUDE_CODE_OAUTH_TOKEN=…` override — `buildExecEnv` merges `options.env`
+     * LAST and unconditionally, so that override wins even the worker branch's
+     * strip and authenticates the run. Gating on the setup-token alone would
+     * falsely refuse that sanctioned escape hatch (forwarded across `--device`).
+     */
+    hasWorkerCredential: boolean;
+    machine?: string;
+}): string | null;

package/dist/lib/harness/adapters/claude.js

@@ -111,6 +111,11 @@ if [ "\$(uname -s)" = "Linux" ] && [ -z "\${CLAUDE_CODE_OAUTH_TOKEN:-}" ] && [ -
 fi
 `;
     },
+    // NOTE: the worker branch above strips the token and returns; a MISSING worker
+    // credential is caught before spawn by claudeWorkerLoginTrapPreflight (below),
+    // which fails loud for an interactive run instead of letting Claude Code fall
+    // through to its "Select login method" screen. A headless run keeps the
+    // strip-and-401 behavior.
     routineModeArgs(cmd, ctx) {
         const mode = ctx.mode;
         if (mode === 'edit') {
@@ -131,3 +136,67 @@ fi
         }
     },
 };
+/**
+ * Fail-loud preflight for the worker login-screen trap — the sibling of the
+ * PHNX-3502 fix. On an EXPLICIT `role: worker` device every Claude run
+ * authenticates from the synced `setup-token`, never an interactive login (owner
+ * rule / credential-management invariant 7). When NO setup-token resolves for the
+ * account this run selected, `applyExecConfigEnv` strips any ambient token and
+ * the harness launches with no credential. A HEADLESS run then fails loud with a
+ * 401 — but an INTERACTIVE dispatched TUI (`agents run claude --interactive
+ * --device <worker>`, the usual `--device auto` landing) instead drops to Claude
+ * Code's own "Select login method" screen. Answering it does an interactive OAuth
+ * on a headless box, minting a native login the worker path never reads and never
+ * syncs; Anthropic later expires it and the next run repeats the prompt — the
+ * 10-minute re-login loop the operator sees.
+ *
+ * This gate refuses that run BEFORE spawn with the real fix (pin or mint a
+ * durable account) instead of the useless login prompt. It is interactive-only
+ * because the headless 401 is already loud. Pure: the caller (spawnAgentLeased)
+ * resolves the inputs and renders the returned message, exactly like
+ * codexSandboxPreflight. Returns null when the run may proceed.
+ */
+export function claudeWorkerLoginTrapPreflight(args) {
+    if (args.agent !== 'claude')
+        return null;
+    // A headless run with no token fails loud with a 401 already; only an
+    // interactive run falls through to Claude Code's login screen.
+    if (!args.interactive)
+        return null;
+    // Gate ONLY an EXPLICIT `role: worker` box — not a headed box, and NOT an
+    // UNMARKED one. The owner rule guarantees a real worker holds no native login
+    // (it authenticates from the synced setup-token), so no token there genuinely
+    // means the login screen with nothing behind it. A headed box authenticates
+    // from its own native login (its login prompt is the correct first-run flow).
+    // An UNMARKED box is deliberately spared: it never receives a synced setup-token
+    // (auth-sync pushes only to `role=worker` peers), so it is typically an ordinary
+    // machine authenticating from a native login the operator just never marked —
+    // gating it would false-refuse every such laptop, a far larger surface than the
+    // marked-worker case this closes. `--device auto` lands on an explicit worker
+    // once any worker is marked in the fleet (filterAutoPool), which is the primary
+    // trap; a directly-named `--device <unmarked-box>` is left as it was on main
+    // (unprotected — a bootstrap-window residual, not a regression).
+    if (args.deviceRole !== 'worker')
+        return null;
+    // A credential will reach the child (worker setup-token, or an explicit
+    // --env CLAUDE_CODE_OAUTH_TOKEN override) — proceed.
+    if (args.hasWorkerCredential)
+        return null;
+    const where = args.machine ? `worker '${args.machine}'` : 'this worker';
+    return [
+        `No Claude worker credential is available on ${where} for the account this run selected.`,
+        `A worker authenticates from a synced setup-token, never an interactive login — so`,
+        `Claude Code's "Select login method" screen here would not persist (it is the source`,
+        `of the repeated re-login). Do one of these instead:`,
+        ``,
+        `  • Pin a live account for this run:   agents run claude#<name> …   (e.g. claude#work)`,
+        `  • Or set the fleet-wide default:     agents accounts default claude <name>`,
+        `  • If that account has no token yet, mint it on a HEADED box (e.g. your laptop):`,
+        `        agents accounts login claude#<name>`,
+        ``,
+        // NB: keep this text clear of RATE_LIMIT_PATTERNS (exec.ts) — this string is
+        // returned as spawn stderr, which runWithFallback scans; a stray "rate limit"
+        // / "quota" phrase here would spuriously trigger an account-rotation fallback.
+        `See which accounts are LIVE (signed in, with headroom) with:  agents accounts list`,
+    ].join('\n');
+}

package/dist/lib/helper-download.d.ts

@@ -10,7 +10,7 @@
  * then verifies the code signature (Developer ID Team + notarization — and, for
  * the menu-bar helper, its designated requirement) before it is ever installed.
  *
- * `computer/download.ts` (ComputerHelper) and `menubar/download-menubar.ts`
+ * `menubar/download-menubar.ts`
  * (MenubarHelper) are thin per-helper wrappers over the primitives here — one
  * download+verify machinery, two specs — so a fix to the verify/download logic
  * lands for both helpers at once.

package/dist/lib/helper-download.js

@@ -10,7 +10,7 @@
  * then verifies the code signature (Developer ID Team + notarization — and, for
  * the menu-bar helper, its designated requirement) before it is ever installed.
  *
- * `computer/download.ts` (ComputerHelper) and `menubar/download-menubar.ts`
+ * `menubar/download-menubar.ts`
  * (MenubarHelper) are thin per-helper wrappers over the primitives here — one
  * download+verify machinery, two specs — so a fix to the verify/download logic
  * lands for both helpers at once.

package/dist/lib/helper-versions.d.ts

@@ -27,7 +27,7 @@
  * never be derived from `getCliVersion()`.
  */
 /** The helpers that have their own release train. */
-export type HelperName = 'menubar' | 'computer-mac' | 'computer-win';
+export type HelperName = 'menubar';
 /** One helper's release identity. */
 export interface HelperRelease {
     /** Tag prefix — the release is `<tagPrefix>/v<version>`. */
@@ -43,9 +43,14 @@ export interface HelperRelease {
  *
  * `menubar` starts at 1.0.0 — the first build published under its own tag
  * rather than the CLI's. It is not "version 1 of the helper"; it is version 1
- * of its independent release train. The keychain helper moved with the
- * standalone `secrets` engine (PHNX-3989) — it downloads and verifies its own
- * helper release now, off this table entirely.
+ * of its independent release train.
+ *
+ * Two helper families have since left this table entirely, both for the same
+ * reason: their engine became a standalone CLI that resolves and verifies its
+ * OWN helper release. The keychain helper went with `secrets` (PHNX-3989); the
+ * macOS and Windows computer helpers went with `computer` (PHNX-4075). A floor
+ * recorded here for a helper this CLI never downloads would be a lying table —
+ * it would claim a distribution responsibility agents-cli no longer has.
  */
 export declare const HELPER_RELEASES: Readonly<Record<HelperName, HelperRelease>>;
 /** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */

package/dist/lib/helper-versions.js

@@ -31,17 +31,17 @@
  *
  * `menubar` starts at 1.0.0 — the first build published under its own tag
  * rather than the CLI's. It is not "version 1 of the helper"; it is version 1
- * of its independent release train. The keychain helper moved with the
- * standalone `secrets` engine (PHNX-3989) — it downloads and verifies its own
- * helper release now, off this table entirely.
+ * of its independent release train.
+ *
+ * Two helper families have since left this table entirely, both for the same
+ * reason: their engine became a standalone CLI that resolves and verifies its
+ * OWN helper release. The keychain helper went with `secrets` (PHNX-3989); the
+ * macOS and Windows computer helpers went with `computer` (PHNX-4075). A floor
+ * recorded here for a helper this CLI never downloads would be a lying table —
+ * it would claim a distribution responsibility agents-cli no longer has.
  */
 export const HELPER_RELEASES = {
-    menubar: { tagPrefix: 'menubar', floor: '1.2.3' },
-    'computer-mac': { tagPrefix: 'computer-mac', floor: '1.0.0' },
-    // The Windows helper is a bare .exe, not an .app bundle, so it does not share
-    // helper-download.ts's zip/codesign/notarize machinery -- but it has the same
-    // URL problem, so it shares the tag namespace and the floor.
-    'computer-win': { tagPrefix: 'computer-win', floor: '1.0.0' },
+    menubar: { tagPrefix: 'menubar', floor: '1.3.0' },
 };
 /** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
 export function helperTag(helper, version) {

package/dist/lib/installations/shims.js

@@ -2189,11 +2189,15 @@ export function listShimFileNames() {
 }
 /**
  * Legacy command shims that are wrong even when their baked install is alive.
- * `secrets` (PHNX-3989) and `sessions` (PHNX-4012): the shim `exec`s
- * `agents <name>`, which is a passthrough to the STANDALONE binary — so the
- * shim re-enters itself (the 1.22.85 fork bomb). Pruned unconditionally.
+ * `secrets` (PHNX-3989), `sessions` (PHNX-4012) and `computer` (PHNX-4075): the
+ * shim `exec`s `agents <name>`, which is a passthrough to the STANDALONE binary —
+ * so the shim re-enters itself (the 1.22.85 fork bomb). Pruned unconditionally.
+ *
+ * `computer` is the sharpest of the three, because agents-cli USED to publish a
+ * `computer` bin of its own: a machine that installed an older CLI has a real
+ * shim on PATH under the name the standalone engine now owns.
  */
-const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets', 'sessions']);
+const LEGACY_SHIMS_ALWAYS_PRUNED = new Set(['secrets', 'sessions', 'computer']);
 /**
  * Prune a stale, orphaned shim: one that is NOT a managed agent shim and NOT a user
  * alias, whose baked `AGENTS_BIN` points at an install that no longer exists. These

package/dist/lib/menubar/download-menubar.d.ts

@@ -2,7 +2,8 @@
  * On-demand download + verification of the macOS menu-bar helper
  * ("MenubarHelper.app").
  *
- * Mirrors the ComputerHelper download model (`../computer/download.ts`): the
+ * Mirrors the ComputerHelper download model the computer subsystem used before
+ * it was extracted (PHNX-4075): the
  * helper ships as a signed + notarized `.app` zipped as a GitHub release asset
  * on the helper's own `menubar/v<x.y.z>` tag, NOT the CLI's tag (see
  * `helper-versions.ts`). A fresh `npm i -g` machine whose tarball lacks a

package/dist/lib/menubar/download-menubar.js

@@ -2,7 +2,8 @@
  * On-demand download + verification of the macOS menu-bar helper
  * ("MenubarHelper.app").
  *
- * Mirrors the ComputerHelper download model (`../computer/download.ts`): the
+ * Mirrors the ComputerHelper download model the computer subsystem used before
+ * it was extracted (PHNX-4075): the
  * helper ships as a signed + notarized `.app` zipped as a GitHub release asset
  * on the helper's own `menubar/v<x.y.z>` tag, NOT the CLI's tag (see
  * `helper-versions.ts`). A fresh `npm i -g` machine whose tarball lacks a

package/dist/lib/menubar/install-menubar.d.ts

@@ -70,6 +70,20 @@ export declare function menubarDisabledByUser(): boolean;
 export declare function menubarServiceInstalled(): boolean;
 /** Where a downloaded copy of the floor release sits once fetched and verified. */
 export declare function cachedFloorBundlePath(): string;
+/**
+ * Where the downloaded copy of the RESOLVED release sits (`cachedMenubarVersion`,
+ * so the floor's cache dir until this machine has resolved something newer).
+ * The startup self-heal installs from here, network-free.
+ */
+export declare function cachedReleaseBundlePath(): string;
+/**
+ * The release version an explicit install should fetch: the newest published
+ * build, but never below what this Mac already runs — a release deleted after
+ * it was installed must not roll the helper back through `setup`/`enable`.
+ */
+export declare function menubarVersionToInstall(opts?: {
+    force?: boolean;
+}): Promise<string>;
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export declare function codesignVerifies(appPath: string): boolean;
 /**
@@ -511,3 +525,45 @@ export declare function isMenubarProcessStaleAgainstBundle(pidStartedAtMs: numbe
  * remains the command that fixes what this reports.
  */
 export declare function buildMenubarDoctorReport(): MenubarDoctorReport;
+/** Outcome of one auto-update pass (`updateMenubarHelperIfNewer`). */
+export interface MenubarUpdateResult {
+    outcome: 'updated' | 'current' | 'skipped' | 'failed';
+    installed: string | null;
+    available: string;
+    detail: string;
+}
+/**
+ * Bring an installed release helper up to the newest published build, without
+ * a human running `agents menubar setup`.
+ *
+ * Runs from the daemon's self-heal tick and right after `agents upgrade`. It
+ * only ever moves a RELEASE install forward: a machine whose helper came from a
+ * local build (a dev checkout) keeps it, a machine that never enabled the menu
+ * bar or opted out is left alone, and the ownership contest that bounds
+ * multi-install churn (`mayInstallMenubarHelper`) still applies. The bundle is
+ * downloaded and verified by the same path every install uses (sha256,
+ * codesign, Team, designated-requirement pin, notarization), swapped
+ * atomically under the install lock at the same path and identity — which is
+ * what keeps the Accessibility grant — and the running helper is restarted
+ * from the new binary (`restartMenubarHelperAfterSwap`; launchd's KeepAlive
+ * relaunches it within seconds). `dryRun` reports what would happen. Never
+ * throws.
+ */
+/**
+ * Pure (no I/O): whether an auto-update pass should proceed, and why not.
+ * `shipped` is a bundle that ships WITH this install (never a downloaded
+ * release cache) — CLI upgrades own that one. Returns null to proceed.
+ */
+export declare function menubarUpdateSkipReason(opts: {
+    darwin: boolean;
+    disabledByUser: boolean;
+    serviceInstalled: boolean;
+    shipped: boolean;
+    installed: MenubarStamp | null;
+}): string | null;
+/** Pure (no I/O): what the pass does given the installed and available versions. */
+export declare function menubarUpdateOutcome(installed: string, available: string): 'current' | 'updated';
+export declare function updateMenubarHelperIfNewer(opts?: {
+    dryRun?: boolean;
+    force?: boolean;
+}): Promise<MenubarUpdateResult>;