@phnx-labs/agents-cli 1.22.46 → 1.22.49

package/dist/lib/feed/watch.d.ts

@@ -0,0 +1,59 @@
+import { type SessionWatchEnvelope, type SessionWatchRow, type SessionWatchScopeStatus } from '../session/watch.js';
+import { type AttentionItem } from './attention.js';
+import { type ActivityEvent } from './activity.js';
+export declare const FEED_WATCH_VERSION: 1;
+type Base = {
+    v: 1;
+    type: string;
+    streamId: string;
+    sequence: number;
+    scope: string;
+};
+export type FeedWatchEnvelope = Base & {
+    type: 'reset';
+    capturedAt: number;
+    agents: SessionWatchRow[];
+    attention: AttentionItem[];
+} | Base & {
+    type: 'agent.upsert';
+    rowKey: string;
+    agent: SessionWatchRow;
+} | Base & {
+    type: 'attention.upsert';
+    rowKey: string;
+    attention: AttentionItem;
+} | Base & {
+    type: 'attention.remove';
+    rowKey: string;
+} | Base & {
+    type: 'activity.append';
+    event: ActivityEvent;
+} | Base & {
+    type: 'scope';
+    capturedAt: number;
+    status: SessionWatchScopeStatus;
+    reason?: string;
+} | Base & {
+    type: 'heartbeat';
+    capturedAt: number;
+};
+type FeedWatchPayload = FeedWatchEnvelope extends infer Envelope ? Envelope extends FeedWatchEnvelope ? Omit<Envelope, 'v' | 'streamId' | 'sequence'> : never : never;
+export declare class FeedWatchState {
+    readonly streamId: string;
+    private sequence;
+    constructor(streamId?: `${string}-${string}-${string}-${string}-${string}`);
+    emit(event: FeedWatchPayload): FeedWatchEnvelope;
+}
+export declare function projectSessionEnvelope(event: SessionWatchEnvelope, state: FeedWatchState): Promise<FeedWatchEnvelope[]>;
+export declare function watchLocalFeed(options: {
+    scope: string;
+    signal: AbortSignal;
+    emit: (event: FeedWatchEnvelope) => void;
+    activityPollMs?: number;
+}): Promise<void>;
+export declare function watchFleetFeed(options: {
+    signal: AbortSignal;
+    emit: (event: FeedWatchEnvelope) => void;
+    reconnectMs?: number;
+}): Promise<void>;
+export {};

package/dist/lib/feed/watch.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { loadDevices, isDialableDevice } from '../devices/registry.js';
+import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
+import { machineId, normalizeHost } from '../machine-id.js';
+import { SSH_OPTS, controlOpts, shellQuote } from '../ssh-exec.js';
+import { buildWindowsAgentsCommand, remoteShellFor } from '../hosts/remote-cmd.js';
+import { watchLocalSessions } from '../session/watch.js';
+import { readBlock, readResolution, blockIdForSession } from './feed.js';
+import { reconcileAttention } from './attention.js';
+import { readRecentActivity } from './activity.js';
+import { readPullRequestStatus } from './pr-status.js';
+export const FEED_WATCH_VERSION = 1;
+export class FeedWatchState {
+    streamId;
+    sequence = 0;
+    constructor(streamId = randomUUID()) { this.streamId = streamId; }
+    emit(event) {
+        return { v: 1, streamId: this.streamId, sequence: ++this.sequence, ...event };
+    }
+}
+async function attentionFor(agent) {
+    if (!agent.sessionId)
+        return undefined;
+    const blockId = blockIdForSession(agent.sessionId);
+    // ActiveSession.host names the terminal app; the feed contract's host is the
+    // device scope. Normalize only the reconciler input so lifecycle/PR keys are
+    // routable across the fleet while the projected agent row stays compatible.
+    const session = { ...agent, host: agent.sourceDevice, viewingIn: undefined };
+    return reconcileAttention({
+        block: readBlock(blockId), session,
+        resolution: readResolution(blockId),
+        pullRequest: await readPullRequestStatus(session), nowMs: Date.now(),
+    });
+}
+export async function projectSessionEnvelope(event, state) {
+    if (event.type === 'reset') {
+        const attention = (await Promise.all(event.rows.map(attentionFor))).filter((item) => item !== undefined);
+        return [state.emit({ type: 'reset', capturedAt: event.capturedAt, scope: event.scope, agents: event.rows, attention })];
+    }
+    if (event.type === 'upsert') {
+        const attention = await attentionFor(event.row);
+        return [
+            state.emit({ type: 'agent.upsert', scope: event.scope, rowKey: event.rowKey, agent: event.row }),
+            attention
+                ? state.emit({ type: 'attention.upsert', scope: event.scope, rowKey: event.rowKey, attention })
+                : state.emit({ type: 'attention.remove', scope: event.scope, rowKey: event.rowKey }),
+        ];
+    }
+    if (event.type === 'remove')
+        return [state.emit({ type: 'attention.remove', scope: event.scope, rowKey: event.rowKey })];
+    if (event.type === 'scope')
+        return [state.emit({ type: 'scope', capturedAt: event.capturedAt, scope: event.scope, status: event.status, ...(event.reason ? { reason: event.reason } : {}) })];
+    return [state.emit({ type: 'heartbeat', capturedAt: event.capturedAt, scope: event.scope })];
+}
+export async function watchLocalFeed(options) {
+    const state = new FeedWatchState();
+    let activityCursor = Date.now();
+    const agents = new Map();
+    const attention = new Map();
+    let pending = Promise.resolve();
+    const reconcileRows = async () => {
+        for (const [rowKey, agent] of agents) {
+            const item = await attentionFor(agent);
+            const next = item ? JSON.stringify(item) : '';
+            if (attention.get(rowKey) === next)
+                continue;
+            attention.set(rowKey, next);
+            options.emit(item
+                ? state.emit({ type: 'attention.upsert', scope: options.scope, rowKey, attention: item })
+                : state.emit({ type: 'attention.remove', scope: options.scope, rowKey }));
+        }
+    };
+    const activityTimer = setInterval(() => {
+        pending = pending.then(async () => {
+            const events = readRecentActivity({ sinceMs: activityCursor + 1 }).reverse();
+            for (const event of events) {
+                activityCursor = Math.max(activityCursor, Date.parse(event.ts));
+                options.emit(state.emit({ type: 'activity.append', scope: options.scope, event }));
+            }
+            await reconcileRows();
+        });
+    }, options.activityPollMs ?? 500);
+    const stopActivity = () => clearInterval(activityTimer);
+    options.signal.addEventListener('abort', stopActivity, { once: true });
+    try {
+        await watchLocalSessions({ scope: options.scope, signal: options.signal, emit: (event) => {
+                if (event.type === 'reset') {
+                    agents.clear();
+                    for (const row of event.rows)
+                        agents.set(row.rowKey, row);
+                }
+                else if (event.type === 'upsert')
+                    agents.set(event.rowKey, event.row);
+                else if (event.type === 'remove') {
+                    agents.delete(event.rowKey);
+                    attention.delete(event.rowKey);
+                }
+                pending = pending.then(() => projectSessionEnvelope(event, state)).then((events) => {
+                    for (const projected of events) {
+                        if (projected.type === 'reset') {
+                            attention.clear();
+                            for (const row of projected.agents)
+                                attention.set(row.rowKey, '');
+                            for (const item of projected.attention) {
+                                const row = projected.agents.find((agent) => agent.sessionId === item.sessionId);
+                                if (row)
+                                    attention.set(row.rowKey, JSON.stringify(item));
+                            }
+                        }
+                        else if (projected.type === 'attention.upsert')
+                            attention.set(projected.rowKey, JSON.stringify(projected.attention));
+                        else if (projected.type === 'attention.remove')
+                            attention.set(projected.rowKey, '');
+                        options.emit(projected);
+                    }
+                });
+            } });
+        await pending;
+    }
+    finally {
+        stopActivity();
+    }
+}
+function remoteFeedWatchCommand(os) {
+    const args = ['feed', 'watch', '--json', '--local'];
+    return remoteShellFor(os) === 'powershell'
+        ? buildWindowsAgentsCommand({ args })
+        : `bash -lc ${shellQuote(`agents ${args.map(shellQuote).join(' ')}`)}`;
+}
+export async function watchFleetFeed(options) {
+    const coordinator = new FeedWatchState();
+    const forward = (event) => {
+        const { v: _v, streamId: peerStreamId, sequence: peerSequence, ...payload } = event;
+        options.emit(coordinator.emit({ ...payload, peerStreamId, peerSequence }));
+    };
+    const local = watchLocalFeed({ scope: machineId(), signal: options.signal, emit: forward });
+    let devices;
+    try {
+        devices = await loadDevices();
+    }
+    catch {
+        await local;
+        return;
+    }
+    const self = machineId();
+    const peers = Object.values(devices).filter((device) => isDialableDevice(device) && normalizeHost(device.name) !== self && ['windows', 'linux', 'macos'].includes(device.platform));
+    const tasks = peers.map(async (device) => {
+        const scope = normalizeHost(device.name);
+        while (!options.signal.aborted) {
+            let target;
+            try {
+                target = sshTargetFor(device);
+            }
+            catch (error) {
+                options.emit(coordinator.emit({ type: 'scope', capturedAt: Date.now(), scope, status: 'unavailable', reason: String(error) }));
+                break;
+            }
+            const child = spawn('ssh', [...SSH_OPTS, ...controlOpts(), ...deviceIdentityArgs(device), target, remoteFeedWatchCommand(device.platform)], { stdio: ['ignore', 'pipe', 'ignore'] });
+            const stop = () => child.kill('SIGTERM');
+            options.signal.addEventListener('abort', stop, { once: true });
+            const reader = createInterface({ input: child.stdout });
+            reader.on('line', (line) => { try {
+                const event = JSON.parse(line);
+                if (event.v === 1)
+                    forward(event);
+            }
+            catch { /* protocol only */ } });
+            const code = await new Promise((resolve) => { child.once('error', () => resolve(null)); child.once('close', resolve); });
+            reader.close();
+            options.signal.removeEventListener('abort', stop);
+            if (options.signal.aborted)
+                break;
+            options.emit(coordinator.emit({ type: 'scope', capturedAt: Date.now(), scope, status: 'unavailable', reason: code == null ? 'ssh failed' : `ssh exited ${code}` }));
+            await new Promise((resolve) => { const timer = setTimeout(resolve, options.reconnectMs ?? 2_000); options.signal.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true }); });
+        }
+    });
+    await Promise.all([local, ...tasks]);
+}

package/dist/lib/fleet/capture.js

@@ -58,6 +58,12 @@ export function captureFleet(prev, inputs) {
     if (prev?.discovery && Object.keys(prev.discovery).length > 0) {
         manifest.discovery = { ...prev.discovery };
     }
+    // Dismissals are operator state, not live state — a capture must never wipe
+    // them (fleet.ignored syncs; losing it re-suggests every dismissed node
+    // fleet-wide). Carry forward verbatim, same contract as `discovery`.
+    if (prev?.ignored && prev.ignored.length > 0) {
+        manifest.ignored = prev.ignored.map((e) => ({ ...e }));
+    }
     const bundles = inputs.secretsBundles ?? prev?.secrets?.bundles;
     if (bundles && bundles.length > 0)
         manifest.secrets = { bundles: [...bundles].sort() };

package/dist/lib/fleet/remote-login.js

@@ -33,7 +33,7 @@ import { planFleetTargets } from '../devices/fleet.js';
 import { assertValidSshTarget, shellQuote, sshExecAsync } from '../ssh-exec.js';
 import { machineId } from '../session/sync/config.js';
 import { ptyRequest } from '../pty-client.js';
-import { openUrl } from '../open-url.js';
+import { showUrl } from '../open-url.js';
 import { readAuthHealthCache, } from '../auth-health.js';
 import { FLEET_LOGIN_FLOWS, KEYCHAIN_BOUND_ON_MAC, } from './auth-sync.js';
 /**
@@ -500,8 +500,13 @@ export async function runFleetLogin(opts = {}) {
     if (!opts.json) {
         console.log(`Dashboard: ${dashUrl}`);
     }
-    if (opts.open !== false)
-        openUrl(dashUrl);
+    if (opts.open !== false) {
+        const shown = await showUrl(dashUrl);
+        if (shown.via === 'none') {
+            console.error('Could not open a browser — open this yourself:');
+            console.error(`  ${dashUrl}`);
+        }
+    }
     const driver = opts.driver ?? defaultPtyDriver();
     const remotable = pending.filter((p) => p.remotable);
     const driveOne = async (p) => {

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

@@ -80,6 +80,23 @@ export interface FleetManifest {
      * machine's local device registry and is never committed.
      */
     discovery?: Record<string, 'approved' | 'ignored'>;
+    /**
+     * Tailnet node names the user dismissed from auto-discovery, with who
+     * dismissed each and when. Lives here rather than in a per-device doc because
+     * a dismissed node is deliberately NOT a device — it never enters the
+     * registry, so it has no per-device folder. Syncs fleet-wide with the rest of
+     * `agents.yaml`, so a dismissal on one box stops the suggestion on every box.
+     */
+    ignored?: IgnoredDeviceEntry[];
+}
+/** One dismissal record in {@link FleetManifest.ignored}. */
+export interface IgnoredDeviceEntry {
+    /** Tailscale node name the user dismissed. */
+    name: string;
+    /** ISO-8601 timestamp of the dismissal. */
+    ignoredAt: string;
+    /** machineId() of the box the dismissal was made on. */
+    ignoredOn: string;
 }
 /**
  * A device's desired state after merging defaults with its override and

package/dist/lib/harness/adapter.d.ts

@@ -28,6 +28,7 @@
  */
 import type { AgentId, Mode } from '../types.js';
 import type { JobConfig } from '../scheduling/routines.js';
+import type { ConfiguredDeviceRole } from '../device-config.js';
 /**
  * Context for the exec-time config-env pin (mapping A, exec.ts side). The caller
  * resolves the interactive/version facts once; the adapter only expresses the
@@ -42,6 +43,16 @@ export interface ExecConfigEnvCtx {
     versionHome: string | null;
     /** resolveInteractive(options) — computed once by the caller. */
     interactive: boolean;
+    /**
+     * The role marked on THIS machine (worker | personal | undefined), resolved
+     * once by the caller from selfConfiguredDeviceRole(). A `personal` device is
+     * the user's own interactive box: it holds a real per-version login and the
+     * credential decision MUST defer to it for EVERY run — interactive OR headless
+     * — never the worker-only setup-token (RUSH-2395). Injected as a plain value
+     * (not imported) to keep the adapter import-leaf. Absent/undefined is treated
+     * as non-personal (worker-equivalent).
+     */
+    deviceRole?: ConfiguredDeviceRole;
     /**
      * claude-account-token's resolveClaudeSetupToken, injected. The adapters MUST
      * stay import-leaf: claude-account-token pulls in the secrets stack, which

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

@@ -26,35 +26,49 @@ export const claudeAdapter = {
         }
         // The `auth` bundle's setup-token exists so a run with NO human present
         // authenticates without the Touch-ID-gated login item — usage probes,
-        // routines, dispatched runs (claude-account-token.ts). An interactive run
-        // has a human at the TTY, and their own per-version login is the credential
-        // they established and expect; overriding it made `/status` report
-        // `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal machine and took every
-        // hand-driven session off that login. macOS cannot cheaply confirm a home's
-        // login first (probing the Keychain raises an authorization sheet per
-        // installed version on the `agents run` hot path — agents.ts
-        // `isClaudeCredentialFileBlank`), so interactive simply defers to Claude
-        // Code, which prompts a present human to log in if the login is missing.
-        if (ctx.interactive) {
-            // Drop an INHERITED copy of OUR OWN setup-token: an interactive launch from
-            // inside a headless agent's shell inherits that agent's injected value via
-            // sanitizeProcessEnv(process.env) and would keep authenticating as it.
-            // Matched by VALUE, so a token the user exported deliberately is a different
-            // string and is left alone (#2383). This is NARROWER than the non-interactive
-            // path below, which overwrites-or-deletes unconditionally and never inspects
-            // the inherited value — a DIFFERENT account's inherited setup-token passing
-            // through this equality check is the adjacent hole RUSH-2360 leaves as
-            // follow-up (it does not silently run on a *shared, rotating* token, which is
-            // what caused the RUSH-1822 logout storm).
+        // routines, dispatched runs (claude-account-token.ts). It is a WORKER
+        // credential. Two kinds of run defer to the per-version login instead:
+        //
+        //   1. An interactive run: a human is at the TTY, and their per-version login
+        //      is the credential they established and expect. Overriding it made
+        //      `/status` report `Auth token: CLAUDE_CODE_OAUTH_TOKEN` on a personal
+        //      machine and took every hand-driven session off that login.
+        //   2. ANY run on a `personal` device — the user's own interactive box (zion),
+        //      marked `config.role: personal`. That box holds a real per-version login
+        //      and is the single origin of it, so every run there — interactive TUI OR
+        //      a headless one-shot like `agents run claude "fix the bug"` — MUST use
+        //      that login, not the setup-token. Gating on run mode ALONE
+        //      (resolveInteractive = "this opens a TUI", NOT "a human is present")
+        //      sent a headless run on the laptop onto the setup-token and hijacked the
+        //      login. Keying the credential on DEVICE ROLE is the fix — RUSH-2395.
+        //
+        // macOS cannot cheaply confirm a home's login first (probing the Keychain
+        // raises an authorization sheet per installed version on the `agents run` hot
+        // path — agents.ts `isClaudeCredentialFileBlank`), so this path defers to
+        // Claude Code, which reads its own ACL-trusted login item without a prompt and
+        // asks a present human to log in only if the login is missing.
+        const personalDevice = ctx.deviceRole === 'personal';
+        if (ctx.interactive || personalDevice) {
+            // Drop an INHERITED copy of OUR OWN setup-token: a launch from inside a
+            // headless agent's shell inherits that agent's injected value via
+            // sanitizeProcessEnv(process.env) and would keep authenticating as it,
+            // overriding the login this branch is protecting. Matched by VALUE, so a
+            // token the user exported deliberately is a different string and is left
+            // alone (#2383). This is NARROWER than the worker path below, which
+            // overwrites-or-deletes unconditionally and never inspects the inherited
+            // value — a DIFFERENT account's inherited setup-token passing through this
+            // equality check is the adjacent hole RUSH-2360 leaves as follow-up (it does
+            // not silently run on a *shared, rotating* token, which is what caused the
+            // RUSH-1822 logout storm).
             if (setupToken && result.CLAUDE_CODE_OAUTH_TOKEN === setupToken) {
                 delete result.CLAUDE_CODE_OAUTH_TOKEN;
             }
         }
         else {
-            // Non-interactive (routines, dispatched, provisioned box): mirror the routines
-            // path (`runner.ts:1017-1021`) UNCONDITIONALLY. Inject the per-account
-            // setup-token when one resolves — it replaces any ambient shared value
-            // inherited from the launcher. When NONE resolves, STRIP the ambient
+            // Headless run on a NON-personal device (worker, dispatched, provisioned
+            // box): mirror the routines path (`runner.ts`) UNCONDITIONALLY. Inject the
+            // per-account setup-token when one resolves — it replaces any ambient shared
+            // value inherited from the launcher. When NONE resolves, STRIP the ambient
             // CLAUDE_CODE_OAUTH_TOKEN so a run on a provisioned box can never silently
             // authenticate as the shared, rotating token an earlier version of this path
             // let through — the RUSH-1822 fleet-wide-logout hazard, tracked by RUSH-2360.

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

@@ -63,21 +63,19 @@ fi
 exec "$BINARY"${launchArgs} "$@"`;
     },
     execModeArgs(ctx) {
-        const policyMode = ctx.resolvedMode === 'plan' || ctx.resolvedMode === 'skip' ? ctx.resolvedMode : 'edit';
         const writableRoots = [
             ...codexEditWritableRoots(ctx.cwd),
             ...ctx.addDirs,
         ];
-        return codexPolicyArgs(policyMode, writableRoots);
+        return codexPolicyArgs(ctx.resolvedMode, writableRoots);
     },
     routineModeArgs(cmd, ctx) {
-        const policyMode = ctx.mode === 'plan' || ctx.mode === 'skip' ? ctx.mode : 'edit';
         const routineRoots = (ctx.config.allow?.dirs ?? []).map((dir) => {
             if (dir.startsWith('-')) {
                 throw new Error(`allow.dirs entries must not start with '-': ${JSON.stringify(dir)}`);
             }
             return dir.replace(/^~/, os.homedir());
         });
-        cmd.push(...codexPolicyArgs(policyMode, [...codexEditWritableRoots(), ...routineRoots]));
+        cmd.push(...codexPolicyArgs(ctx.mode, [...codexEditWritableRoots(), ...routineRoots]));
     },
 };

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

@@ -1,19 +1,16 @@
-import * as path from 'path';
 import { stripForeignConfigDir } from '../adapter.js';
 export const cursorAdapter = {
     id: 'cursor',
-    // Cursor has no config-dir env var (only CURSOR_API_KEY / CURSOR_API_ENDPOINT).
-    // Its OAuth token — the login gate — lives at $XDG_CONFIG_HOME/cursor/auth.json
-    // (verified empirically: relocating XDG_CONFIG_HOME relocates the login;
-    // ~/.cursor/cli-config.json holds only account metadata, not the token). Pin
-    // XDG_CONFIG_HOME into the version home so each installed Cursor account
-    // authenticates from its own token, isolated per run — no global ~/.cursor
-    // symlink swap, so concurrent runs on different accounts never clobber one
-    // another. cli-config.json (HOME-relative) has no override and stays on the
-    // shared home; only the token is per-account, which is what gates the login.
+    // Cursor defaults to one machine-global OS-keychain login on macOS, which
+    // ignores XDG_CONFIG_HOME. Select the file credential store; Cursor writes
+    // that store to HOME-relative ~/.cursor/auth.json, and buildExecEnv already
+    // swaps HOME to the selected version home. Existing keychain credentials
+    // remain untouched.
     applyExecConfigEnv(result, ctx) {
         if (ctx.versionHome) {
-            result.XDG_CONFIG_HOME = path.join(ctx.versionHome, '.config');
+            result.AGENTS_REAL_HOME ||= result.HOME;
+            result.HOME = ctx.versionHome;
+            result.AGENT_CLI_CREDENTIAL_STORE = 'file';
         }
         stripForeignConfigDir(result);
     },

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

@@ -0,0 +1,108 @@
+/**
+ * Shared on-demand download + verification for the macOS native helper `.app`
+ * bundles that ship as signed + notarized GitHub release assets on each helper's
+ * OWN tag (`ComputerHelper.app`, `MenubarHelper.app`, `Agents CLI.app`) — see
+ * `helper-versions.ts` for why they are no longer keyed to the CLI's tag.
+ *
+ * A `.app` is a directory, so each asset is a zip (`ditto -c -k --keepParent`);
+ * a fresh `npm i -g` machine with no bundled copy fetches the asset for the
+ * pinned helper version, verifies its sha256 against the published `.sha256`,
+ * 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`
+ * (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.
+ */
+import { type HelperName } from './helper-versions.js';
+/** GitHub repo whose `v<version>` releases carry the helper assets. */
+export declare const HELPER_RELEASE_REPO = "phnx-labs/agents-cli";
+/** Apple Developer ID Team every helper must be signed by ("Developer ID
+ *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
+export declare const EXPECTED_TEAM_ID = "2HTP252L87";
+/** One helper's identity + verification policy — everything that differs between
+ *  the computer helper and the menu-bar helper. */
+export interface HelperSpec {
+    /**
+     * Which helper this is — the key into the independent release train
+     * (`helper-versions.ts`). This is what makes the download URL a function of
+     * the HELPER's version rather than the CLI's.
+     */
+    helper: HelperName;
+    /** The zipped `.app` release asset name, e.g. `ComputerHelper.app.zip`. */
+    assetName: string;
+    /** The bundle directory name once extracted, e.g. `ComputerHelper.app`. */
+    appName: string;
+    /** Cache dir components under `getCacheDir()`, e.g. `['computer', 'mac-helper']`. */
+    cacheSubdir: string[];
+    /** Developer ID Team the bundle must be signed by. */
+    expectedTeamId: string;
+    /**
+     * When set, the bundle's designated requirement MUST pin this
+     * CFBundleIdentifier in addition to `expectedTeamId`. Used by the menu-bar
+     * helper: macOS keys the Accessibility (TCC) grant to this requirement, so a
+     * substituted bundle whose DR does not pin (id, team) would silently revoke
+     * the user's grant on the next paste. Left undefined for the computer helper,
+     * which has no such upgrade-stable grant to protect (matching its behavior
+     * before this shared primitive existed).
+     */
+    expectedBundleId?: string;
+    /** Local-build command named in the "asset missing" error, for a repo checkout. */
+    localBuildHint: string;
+}
+/** Cache dir for a downloaded helper, one subdir per release tag. */
+export declare function helperCacheDir(spec: HelperSpec, version: string): string;
+/**
+ * Release-asset URLs for one helper build, at that HELPER's own tag.
+ *
+ * The tag is `<helper>/v<version>` (e.g. `menubar/v1.0.0`), never the CLI's
+ * `v<cliVersion>`. Keying these to the CLI tag is what forced every CLI release
+ * to re-stage every helper asset, and simultaneously made a helper fix
+ * unreachable without a CLI release — see `helper-versions.ts` for the full why.
+ *
+ * `version` is a HELPER version. Passing a CLI version here yields a tag that
+ * does not exist; callers default it from {@link helperFloor}.
+ */
+export declare function helperAssetUrls(spec: HelperSpec, 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;
+/** Read the bundle's designated requirement string (`codesign -d --requirements -`).
+ *  codesign writes it to stdout, but capture both streams so a diagnostic on
+ *  stderr can never make the pin-check read empty and falsely pass. */
+export declare function readDesignatedRequirement(appPath: string): string;
+/**
+ * Pure predicate (no I/O) behind the DR pin: does the requirement string pin
+ * BOTH the expected CFBundleIdentifier and the Developer ID Team? Returns null
+ * when it does, else an actionable error message naming the missing pin. Kept
+ * pure so the truth table is unit-testable without a signed bundle or codesign.
+ * Mirrors the release-time gate in `scripts/verify-menubar-helper.sh` (identifier
+ * + team substring check against the same requirement string).
+ */
+export declare function checkDesignatedRequirement(req: string, bundleId: string, teamId: string): string | null;
+/**
+ * Verify the bundle's designated requirement pins the expected CFBundleIdentifier
+ * AND Developer ID Team. macOS re-validates each new version against this stored
+ * requirement to keep an Accessibility grant alive across upgrades; a downloaded
+ * bundle whose DR drops either pin would silently revoke that grant on the next
+ * paste, so refuse it.
+ */
+export declare function verifyDesignatedRequirement(appPath: string, bundleId: string, teamId: string): void;
+/**
+ * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
+ * Team, (for the menu-bar helper) pinned by its designated requirement, and
+ * notarized (Gatekeeper-accepted). Throws with an actionable message on any
+ * failure — a downloaded bundle is never trusted without this.
+ */
+export declare function verifyHelperApp(appPath: string, spec: HelperSpec): void;
+/**
+ * Download a helper release asset for `version`, verify sha256, extract the
+ * `.app`, and verify its signature (+ DR pin when the spec requires one).
+ * Returns the path to the extracted bundle. A missing asset is a hard error
+ * naming the exact tag — never a silent fallback to another release.
+ */
+export declare function downloadHelperApp(spec: HelperSpec, version: string): Promise<string>;