@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/browser/task-index.js

@@ -0,0 +1,180 @@
+/**
+ * Local task → device index.
+ *
+ * `tasks.json` is per-profile and lives in that profile's cache dir on the
+ * machine running the browser daemon, so a later verb issued from a different
+ * box cannot see where task `post` lives. The machine that STARTS a task
+ * records the binding here — a small JSON file in THIS box's browser cache.
+ * No fleet state, no sync: the agent that opens a task is the agent that
+ * drives it.
+ *
+ * Kind is not stored. A missing name fails loud and lists the open tasks;
+ * it never guesses, never opens a new browser, never falls back to a default
+ * profile.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getBrowserRuntimeDir } from '../state.js';
+import { machineId } from '../machine-id.js';
+export const REJECT_DEVICE_MESSAGE = '--device is only valid on `agents browser start`.\n' +
+    'The task is bound to a device at start; later verbs resolve it from --task.\n' +
+    'Next: agents browser start --task <name> --device <device>';
+export function taskIndexPath() {
+    return path.join(getBrowserRuntimeDir(), 'task-index.json');
+}
+export function readTaskIndex() {
+    const file = taskIndexPath();
+    if (!fs.existsSync(file))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Cannot read browser task index at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Cannot read browser task index at ${file}: document root must be a map.`);
+    }
+    return parsed;
+}
+function writeTaskIndex(index) {
+    const file = taskIndexPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(index, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+}
+export function getTaskBinding(name) {
+    return readTaskIndex()[name];
+}
+export function listTaskBindings() {
+    return Object.entries(readTaskIndex())
+        .map(([name, binding]) => ({ name, ...binding }))
+        .sort((a, b) => a.createdAt - b.createdAt);
+}
+export function bindTask(name, binding) {
+    if (!name) {
+        throw new Error('Cannot bind a browser task with an empty name.');
+    }
+    if (!binding.device) {
+        throw new Error(`Cannot bind browser task "${name}" without a device.`);
+    }
+    const index = readTaskIndex();
+    index[name] = { ...binding };
+    writeTaskIndex(index);
+}
+export function updateTaskBinding(name, patch) {
+    const index = readTaskIndex();
+    const existing = index[name];
+    if (!existing)
+        return;
+    index[name] = { ...existing, ...patch };
+    writeTaskIndex(index);
+}
+export function unbindTask(name) {
+    const index = readTaskIndex();
+    if (!(name in index))
+        return;
+    delete index[name];
+    writeTaskIndex(index);
+}
+/** Drop every binding recorded under this profile (after `stop --profile` / gc). */
+export function unbindTasksForProfile(profile) {
+    const index = readTaskIndex();
+    let changed = false;
+    for (const [name, binding] of Object.entries(index)) {
+        if (binding.profile === profile) {
+            delete index[name];
+            changed = true;
+        }
+    }
+    if (changed)
+        writeTaskIndex(index);
+}
+export function tasksForCaller(sessionId, launchId) {
+    return listTaskBindings().filter((entry) => {
+        if (sessionId && entry.sessionId === sessionId)
+            return true;
+        if (launchId && entry.launchId === launchId)
+            return true;
+        return false;
+    });
+}
+function formatAge(createdAt, now = Date.now()) {
+    const ageMs = Math.max(0, now - createdAt);
+    if (ageMs < 60_000)
+        return `${Math.round(ageMs / 1000)}s`;
+    return `${Math.round(ageMs / 60_000)}m`;
+}
+export function formatOpenTaskList(entries, now = Date.now()) {
+    if (entries.length === 0)
+        return '  (no open tasks)';
+    return entries
+        .map((entry) => {
+        const url = entry.url && entry.url.length > 0 ? entry.url : '-';
+        return `  ${entry.name}  url=${url}  device=${entry.device}  age=${formatAge(entry.createdAt, now)}`;
+    })
+        .join('\n');
+}
+export function unknownTaskMessage(name, entries = listTaskBindings()) {
+    return [
+        `Unknown browser task "${name}".`,
+        'Open tasks:',
+        formatOpenTaskList(entries),
+        'Next: agents browser start --task <name> [--device <device>]',
+    ].join('\n');
+}
+export function ambiguousTasksMessage(entries) {
+    return [
+        'Multiple browser tasks for this session — pass --task <name>:',
+        formatOpenTaskList(entries),
+        'Next: agents browser status',
+    ].join('\n');
+}
+/**
+ * Decide where a page verb should run.
+ *
+ * `--device` on a later verb is always rejected (bind it at start).
+ * A named task that is not in the local index fails loud with the open-task
+ * list. Two or more tasks for this caller, with no `--task`, fail the same way.
+ * Zero matches with no `--task` proceeds locally — the daemon still resolves
+ * from caller identity for the first implicit create.
+ */
+export function resolveTaskRoute(opts) {
+    if (opts.device) {
+        return { kind: 'reject-device', message: REJECT_DEVICE_MESSAGE };
+    }
+    const self = opts.self ?? machineId();
+    if (opts.task) {
+        const binding = getTaskBinding(opts.task);
+        if (!binding) {
+            return { kind: 'unknown', task: opts.task, message: unknownTaskMessage(opts.task) };
+        }
+        return { kind: 'proceed', task: opts.task, device: binding.device };
+    }
+    const matches = tasksForCaller(opts.sessionId, opts.launchId);
+    if (matches.length > 1) {
+        return { kind: 'ambiguous', message: ambiguousTasksMessage(matches) };
+    }
+    if (matches.length === 1) {
+        const only = matches[0];
+        return { kind: 'proceed', task: only.name, device: only.device };
+    }
+    return { kind: 'proceed', device: self };
+}
+/**
+ * The daemon sandboxes screenshot writes to the browser runtime dir, so `-o`
+ * outside that dir is ignored there. The CLI process honors `-o` by copying
+ * the captured file to the requested path. Same path → no copy.
+ */
+export function honorScreenshotOutput(requested, daemonPath) {
+    if (!requested)
+        return daemonPath;
+    const dest = path.resolve(requested);
+    if (path.resolve(daemonPath) === dest)
+        return dest;
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(daemonPath, dest);
+    return dest;
+}

package/dist/lib/browser/types.d.ts

@@ -287,7 +287,7 @@ export interface ReapResult {
     /** Tasks left alone this pass: still live, still inside the idle window, or recording. */
     skipped: number;
 }
-export type IPCAction = 'start' | 'gc' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
+export type IPCAction = 'start' | 'show' | 'gc' | 'record-start' | 'record-stop' | 'done' | 'stop' | 'status' | 'history' | 'navigate' | 'tab-add' | 'tab-focus' | 'tab-close' | 'tab-list' | 'evaluate' | 'screenshot' | 'pdf' | 'refs' | 'click' | 'type' | 'press' | 'hover' | 'scroll' | 'set-viewport' | 'set-device' | 'console' | 'errors' | 'requests' | 'response-body' | 'wait' | 'set-download-path' | 'wait-download' | 'upload' | 'getAppLogs' | 'version';
 export interface IPCRequest {
     action: IPCAction;
     task?: string;
@@ -366,6 +366,17 @@ export interface IPCRequest {
      * for `computer.action` events, so both tool surfaces key on one signal.
      */
     sessionId?: string;
+    /**
+     * True when the CLI process that issued this request was itself dispatched to
+     * this machine by a fleet `--device` hop.
+     *
+     * Stamped client-side for the same reason actor/launchId are — and
+     * additionally because the daemon may have been auto-started BY a fleet-remote
+     * CLI and inherited AGENTS_FLEET_REMOTE for its whole life (startDetached
+     * passes `env: opts.env ?? process.env`). The daemon's own env is therefore
+     * not a truthful signal about the CURRENT caller; only the request is.
+     */
+    fleetRemote?: boolean;
 }
 /** Subset of IPCResponse describing a recording start result. */
 export interface RecordStartFields {

package/dist/lib/byok-usage.js

@@ -150,12 +150,12 @@ export function renderByokBar(result) {
         return '';
     const { budget } = result;
     if (budget.limitUsd === null) {
-        const bar = renderBar(0, 10, 0);
+        const bar = renderBar(0, 10);
         const credit = budget.remainingUsd !== null ? `$${budget.remainingUsd.toFixed(2)} credit, ` : '';
         return `$: ${bar} ${credit}$${budget.usedUsd.toFixed(2)} used (no spending limit)`;
     }
     const pct = budget.usedPercent ?? 0;
-    const bar = renderBar(pct, 10, pct > 0 ? 1 : 0);
+    const bar = renderBar(pct, 10);
     const color = getUsageColor(pct);
     const remaining = budget.remainingUsd !== null ? `$${budget.remainingUsd.toFixed(2)}` : '?';
     const limit = `$${budget.limitUsd.toFixed(2)}`;

package/dist/lib/claude-statusline.d.ts

@@ -0,0 +1,29 @@
+export declare const CLAUDE_STATUSLINE_COMMAND = "agents __claude-statusline";
+interface ClaudeStatusLinePayload {
+    cwd?: string;
+    workspace?: {
+        current_dir?: string;
+    };
+    model?: {
+        display_name?: string;
+        id?: string;
+    };
+    rate_limits?: {
+        five_hour?: {
+            used_percentage?: number;
+            resets_at?: number;
+        };
+        seven_day?: {
+            used_percentage?: number;
+            resets_at?: number;
+        };
+    };
+}
+export declare function ingestClaudeStatusLineUsage(payload: ClaudeStatusLinePayload, versionHome: string): boolean;
+export declare function renderClaudeStatusLine(payload: ClaudeStatusLinePayload, host?: string, delegated?: string): string;
+export declare function runClaudeStatusLine(): Promise<number>;
+export declare function installClaudeStatusLine(versionHome: string): {
+    changed: boolean;
+    error?: string;
+};
+export {};

package/dist/lib/claude-statusline.js

@@ -0,0 +1,139 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { readClaudeHomeConfig } from './agent-spec/agents.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { mergeClaudeUsageCacheWindows } from './accounting/usage.js';
+export const CLAUDE_STATUSLINE_COMMAND = 'agents __claude-statusline';
+const DELEGATE_FILE = path.join('.agents', 'claude-statusline-delegate');
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function versionHomeFromEnv(env) {
+    const configDir = env.CLAUDE_CONFIG_DIR?.trim();
+    return configDir ? path.dirname(configDir) : null;
+}
+function windowFromNative(key, value) {
+    if (!value || !Number.isFinite(value.used_percentage))
+        return null;
+    const resetSeconds = value.resets_at;
+    return {
+        key,
+        label: key === 'session' ? 'Current session' : 'Current week',
+        shortLabel: key === 'session' ? 'S' : 'W',
+        usedPercent: Math.max(0, Math.min(100, value.used_percentage)),
+        resetsAt: Number.isFinite(resetSeconds) ? new Date(resetSeconds * 1000) : null,
+        windowMinutes: key === 'session' ? 300 : 10_080,
+    };
+}
+export function ingestClaudeStatusLineUsage(payload, versionHome) {
+    const identity = readClaudeHomeConfig(versionHome)?.identity;
+    if (!identity?.usageKey || !payload.rate_limits)
+        return false;
+    const windows = [
+        windowFromNative('session', payload.rate_limits.five_hour),
+        windowFromNative('week', payload.rate_limits.seven_day),
+    ].filter((value) => value !== null);
+    if (windows.length === 0)
+        return false;
+    mergeClaudeUsageCacheWindows(identity.usageKey, {
+        source: 'live',
+        sourceLabel: 'Claude response rate limits',
+        capturedAt: new Date(),
+        windows,
+    });
+    return true;
+}
+function delegatePath(versionHome) {
+    return path.join(versionHome, DELEGATE_FILE);
+}
+function renderDelegate(payload, versionHome) {
+    let command = '';
+    try {
+        command = fs.readFileSync(delegatePath(versionHome), 'utf8').trim();
+    }
+    catch {
+        return '';
+    }
+    if (!command || command === CLAUDE_STATUSLINE_COMMAND)
+        return '';
+    const result = spawnSync(command, {
+        shell: true,
+        input: payload,
+        encoding: 'utf8',
+        env: process.env,
+    });
+    return result.status === 0 ? result.stdout.trim() : '';
+}
+export function renderClaudeStatusLine(payload, host = os.hostname().split('.')[0] || os.hostname(), delegated = '') {
+    const model = payload.model?.display_name?.trim() || payload.model?.id?.trim() || 'model pending';
+    const parts = [host, model];
+    if (delegated)
+        parts.push(delegated);
+    const fiveHour = payload.rate_limits?.five_hour?.used_percentage;
+    const sevenDay = payload.rate_limits?.seven_day?.used_percentage;
+    if (Number.isFinite(fiveHour))
+        parts.push(`5h ${Math.round(fiveHour)}%`);
+    if (Number.isFinite(sevenDay))
+        parts.push(`7d ${Math.round(sevenDay)}%`);
+    return parts.join(' · ');
+}
+export async function runClaudeStatusLine() {
+    const raw = await new Promise((resolve, reject) => {
+        let input = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => { input += chunk; });
+        process.stdin.on('end', () => resolve(input));
+        process.stdin.on('error', reject);
+    });
+    let payload;
+    try {
+        const parsed = JSON.parse(raw);
+        payload = isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        payload = {};
+    }
+    const versionHome = versionHomeFromEnv(process.env);
+    if (versionHome)
+        ingestClaudeStatusLineUsage(payload, versionHome);
+    process.stdout.write(renderClaudeStatusLine(payload, undefined, versionHome ? renderDelegate(raw, versionHome) : ''));
+    return 0;
+}
+export function installClaudeStatusLine(versionHome) {
+    const settingsPath = path.join(versionHome, '.claude', 'settings.json');
+    try {
+        let settings = {};
+        if (fs.existsSync(settingsPath)) {
+            const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            if (!isRecord(parsed))
+                return { changed: false, error: 'settings.json is not an object' };
+            settings = parsed;
+        }
+        const priorStatusLine = isRecord(settings.statusLine) ? settings.statusLine : {};
+        const existing = typeof priorStatusLine.command === 'string'
+            ? priorStatusLine.command.trim()
+            : '';
+        if (existing === CLAUDE_STATUSLINE_COMMAND)
+            return { changed: false };
+        if (existing) {
+            fs.mkdirSync(path.dirname(delegatePath(versionHome)), { recursive: true });
+            atomicWriteFileSync(delegatePath(versionHome), `${existing}\n`);
+        }
+        else {
+            fs.rmSync(delegatePath(versionHome), { force: true });
+        }
+        settings.statusLine = {
+            ...priorStatusLine,
+            type: 'command',
+            command: CLAUDE_STATUSLINE_COMMAND,
+        };
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        atomicWriteFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+        return { changed: true };
+    }
+    catch (error) {
+        return { changed: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/lib/cloud/host.d.ts

@@ -6,7 +6,7 @@
  * launch as `agents run --device`, and the resulting task shows up in BOTH
  * `agents cloud ps` and `agents devices ps` — one store (the host-task sidecars
  * under ~/.agents/.cache/hosts/), two views. No new transport, no relay: SSH
- * is the only wire, exactly like the rest of the hosts design (docs/hosts.md).
+ * is the only wire, exactly like the rest of the host design (docs/fleet.md).
  *
  * Status semantics follow reconcile.ts's prime rule: completion is only ever
  * CONFIRMED from the remote `.exit` file — an unreachable host leaves a task

package/dist/lib/cloud/host.js

@@ -6,7 +6,7 @@
  * launch as `agents run --device`, and the resulting task shows up in BOTH
  * `agents cloud ps` and `agents devices ps` — one store (the host-task sidecars
  * under ~/.agents/.cache/hosts/), two views. No new transport, no relay: SSH
- * is the only wire, exactly like the rest of the hosts design (docs/hosts.md).
+ * is the only wire, exactly like the rest of the host design (docs/fleet.md).
  *
  * Status semantics follow reconcile.ts's prime rule: completion is only ever
  * CONFIRMED from the remote `.exit` file — an unreachable host leaves a task

package/dist/lib/cloud/rush.js

@@ -290,7 +290,7 @@ export class RushCloudProvider {
                     `placement does not securely inject them yet. Create and sync one with:`,
                     `    agents accounts add <name> --provider anthropic --auth api-key    # or: --auth setup-token`,
                     `    agents accounts sync <name> <device>`,
-                    `then run locally or on that device with --account <name>. See docs/credential-management.md (SING-1b).`,
+                    `then run locally or on that device with --account <name>. See docs/secrets.md (SING-1b).`,
                 ].join('\n'));
             }
         }

package/dist/lib/codex-policy.d.ts

@@ -1,6 +1,7 @@
-export type CodexPolicyMode = 'plan' | 'edit' | 'skip';
+export type CodexPolicyMode = 'plan' | 'edit' | 'auto' | 'skip';
 export declare const CODEX_PLAN_PROFILE = "agents-plan";
 export declare const CODEX_EDIT_PROFILE = "agents-edit";
+export declare const CODEX_AUTO_PROFILE = "agents-auto";
 /**
  * Writable roots for Codex's `edit` profile: the managed user `.agents` dir, the
  * baseline toolchain caches, and — when `cwd` is inside a repo — that repo's
@@ -17,6 +18,15 @@ export declare function codexPermissionProfileConfig(mode: Exclude<CodexPolicyMo
  * Config overrides are deliberately used instead of the legacy `--sandbox`
  * flags: named permission profiles are the only Codex surface that can keep a
  * plan run filesystem-read-only while independently enabling network access.
+ *
+ * `auto` and `edit` share one sandbox (`:workspace` plus the writable roots) and
+ * differ only in `approval_policy`. `edit` is `on-request`: a command the sandbox
+ * denies comes back as an approval prompt, which is right when someone is sitting
+ * at the terminal. `auto` is `never`: nothing prompts, and a denied command
+ * surfaces to the model as a plain command failure — the only behavior that works
+ * for an unattended run, where a prompt nobody answers is an agent that has
+ * stopped. Autonomy is the approval axis only; neither widens the sandbox, and
+ * `skip` remains the sole mode that removes it.
  */
 export declare function codexPolicyArgs(mode: CodexPolicyMode, writableRoots?: string[]): string[];
 /** Preserve whether --mode was omitted when a run is re-dispatched remotely. */

package/dist/lib/codex-policy.js

@@ -4,6 +4,7 @@ import { codexDefaultWritableRoots } from './permissions.js';
 import { repoAgentsDirForCwd } from './project-key.js';
 export const CODEX_PLAN_PROFILE = 'agents-plan';
 export const CODEX_EDIT_PROFILE = 'agents-edit';
+export const CODEX_AUTO_PROFILE = 'agents-auto';
 function unique(values) {
     return [...new Set(values)];
 }
@@ -28,25 +29,39 @@ function inlineWorkspaceRoots(roots) {
 }
 export function codexPermissionProfileConfig(mode, writableRoots = codexEditWritableRoots()) {
     const parent = mode === 'plan' ? ':read-only' : ':workspace';
-    const roots = mode === 'edit'
-        ? `, workspace_roots = { ${inlineWorkspaceRoots(unique(writableRoots))} }`
-        : '';
+    const roots = mode === 'plan'
+        ? ''
+        : `, workspace_roots = { ${inlineWorkspaceRoots(unique(writableRoots))} }`;
     return `{ extends = ${JSON.stringify(parent)}${roots}, network = { enabled = true, allow_local_binding = true } }`;
 }
+const CODEX_PROFILES = {
+    plan: CODEX_PLAN_PROFILE,
+    edit: CODEX_EDIT_PROFILE,
+    auto: CODEX_AUTO_PROFILE,
+};
 /**
  * Canonical Codex safety policy used by every native launch path.
  *
  * Config overrides are deliberately used instead of the legacy `--sandbox`
  * flags: named permission profiles are the only Codex surface that can keep a
  * plan run filesystem-read-only while independently enabling network access.
+ *
+ * `auto` and `edit` share one sandbox (`:workspace` plus the writable roots) and
+ * differ only in `approval_policy`. `edit` is `on-request`: a command the sandbox
+ * denies comes back as an approval prompt, which is right when someone is sitting
+ * at the terminal. `auto` is `never`: nothing prompts, and a denied command
+ * surfaces to the model as a plain command failure — the only behavior that works
+ * for an unattended run, where a prompt nobody answers is an agent that has
+ * stopped. Autonomy is the approval axis only; neither widens the sandbox, and
+ * `skip` remains the sole mode that removes it.
  */
 export function codexPolicyArgs(mode, writableRoots = codexEditWritableRoots()) {
     if (mode === 'skip')
         return ['--dangerously-bypass-approvals-and-sandbox'];
-    const profile = mode === 'plan' ? CODEX_PLAN_PROFILE : CODEX_EDIT_PROFILE;
+    const profile = CODEX_PROFILES[mode];
     return [
         '-c',
-        'approval_policy="on-request"',
+        `approval_policy=${mode === 'auto' ? '"never"' : '"on-request"'}`,
         '-c',
         `default_permissions=${JSON.stringify(profile)}`,
         '-c',

package/dist/lib/computer/computer-rpc.js

@@ -174,8 +174,8 @@ export function writeComputerPeers(allowedExecPaths) {
 export function resolveHelperExec() {
     const here = path.dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        // Local build (running from the agents-cli checkout). apps/cli/dist/lib/computer -> repo root (5 up) -> native/computer-mac.
-        path.resolve(here, '..', '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
+        // Local build (running from the agents-cli checkout). cli/dist/lib/computer -> repo root (4 up) -> native/computer-mac.
+        path.resolve(here, '..', '..', '..', '..', 'native', 'computer-mac', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
         // Bundled with the npm package (dist/lib/computer -> dist/).
         path.resolve(here, '..', '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
     ];

package/dist/lib/computer/download.d.ts

@@ -3,25 +3,28 @@
  * ("ComputerHelper.app").
  *
  * The helper is a signed + notarized universal `.app` bundle published as a
- * GitHub release asset per tagged CLI version — the same distribution model as
- * the Windows helper (see `lib/computer/ssh-tunnel.ts`). A fresh `npm i -g` machine has
- * no local build, so `agents computer setup` / `agents setup computer` fetch the
- * asset for the running CLI version, verify its sha256 against the published
+ * GitHub release asset on its own `computer-mac/v<x.y.z>` tag (see
+ * `helper-versions.ts`). The Windows helper (`lib/computer/ssh-tunnel.ts`) does
+ * NOT yet follow this model — it still keys its exe to the CLI's own tag.
+ *
+ * A fresh `npm i -g` machine has no local build, so `agents computer setup` / `agents setup computer` fetch the
+ * asset for the pinned helper version, verify its sha256 against the published
  * `.sha256`, then verify the code signature (Developer ID Team + notarization)
  * before it is ever copied to /Applications.
  *
- * A `.app` is a directory, so the asset is a zip (`ditto -c -k --keepParent`);
- * we extract it with `ditto -x -k` after the checksum passes.
+ * The download + verify machinery is shared with the menu-bar helper in
+ * `../helper-download.ts`; this file is the ComputerHelper spec + its wrappers,
+ * keeping the historical export surface (`verifyMacHelper`, `downloadMacHelperApp`,
+ * `ensureMacHelperApp`, …) stable for existing callers. ComputerHelper does NOT
+ * pin a designated requirement (no `expectedBundleId`), matching its verification
+ * strength before the shared primitive existed.
  */
-/** GitHub repo whose `v<version>` releases carry the helper asset. */
-export declare const HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+import { EXPECTED_TEAM_ID, HELPER_RELEASE_REPO, parseTeamId } from '../helper-download.js';
+export { EXPECTED_TEAM_ID, HELPER_RELEASE_REPO, parseTeamId };
 /** The zipped `.app` release asset name. */
 export declare const MAC_HELPER_ASSET = "ComputerHelper.app.zip";
 /** The bundle directory name once extracted. */
 export declare const MAC_HELPER_APP_NAME = "ComputerHelper.app";
-/** Apple Developer ID Team the helper must be signed by (defense in depth on top
- * of `spctl` notarization assessment). "Developer ID Application: Muqit Nawaz". */
-export declare const EXPECTED_TEAM_ID = "2HTP252L87";
 /** Cache dir for the downloaded helper, one subdir per release tag. */
 export declare function macHelperCacheDir(version: string): string;
 /** Release-asset URLs for the helper zip + its checksum at one `v<version>` tag. */
@@ -29,9 +32,6 @@ export declare function macHelperAssetUrls(version: string): {
     zip: string;
     sha256: string;
 };
-/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
- * emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
-export declare function parseTeamId(codesignInfo: string): string | null;
 /**
  * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
  * Team, and notarized (Gatekeeper-accepted). Throws with an actionable message
@@ -48,7 +48,7 @@ export declare function downloadMacHelperApp(version: string): Promise<string>;
 /**
  * Resolve the helper `.app` to install from: a local build / bundled copy first
  * (repo checkout), else the checksum + signature-verified release-asset download
- * for the running CLI version. Throws with the tag it checked when neither
+ * for the pinned helper version. Throws with the tag it checked when neither
  * exists. macOS only.
  */
 export declare function ensureMacHelperApp(version?: string): Promise<string>;