@phnx-labs/agents-cli 1.22.47 → 1.22.49

package/dist/lib/exec.js

@@ -8,7 +8,7 @@ import { spawn } from 'child_process';
 import { randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { ALL_MODES } from './types.js';
+import { ALL_MODES, REMOTE_INTERACTIVE_ENV } from './types.js';
 import { AGENTS, findInPath } from './agents.js';
 import { parseTimeout } from './scheduling/routines.js';
 import { compareVersions, getBinaryPath, getVersionHomePath, isVersionInstalled, listInstalledVersions, resolveVersion } from './installations/versions.js';
@@ -1176,36 +1176,47 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * Opting into tmux wrapping gives every interactive agent an exact, unique `%pane` handle so
- * `agents sessions --active` can tell co-located agents apart, and lets `agents
- * focus` re-attach a live session without forking it. Pure so the gate is unit-
- * tested independently of the (side-effecting) spawn.
+ * Wrapping serves two independent purposes, and they are gated differently:
  *
- * All seven guards must pass:
- *   - interactive     — a headless `-p` run has no TTY to attach; keep bare spawn.
- *   - not Windows     — no tmux path on win32.
- *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
- *   - not --raw       — explicit opt-out.
- *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
- *   - tmux.enabled    — this device explicitly opted into addressable tmux panes.
- *   - tmux installed  — otherwise there is nothing to wrap with.
+ *  - **Addressability** (`configEnabled`): a unique `%pane` handle so
+ *    `agents sessions --active` can tell co-located agents apart and `agents
+ *    focus` re-attaches without forking. That is a local preference — the
+ *    operator turns it on once tmux's mouse/clipboard/scrollback suits them.
+ *  - **Durability** (`remoteDispatch`): a run that arrived over SSH must outlive
+ *    the SSH client, because a bare remote spawn dies of SIGHUP the moment the
+ *    link blinks. That is not a preference, so it does not consult
+ *    `configEnabled` (RUSH-3125 — see {@link TmuxWrapContext.remoteDispatch}).
+ *
+ * The per-run opt-outs bind BOTH: `--raw` / `--no-tmux` / `AGENTS_NO_TMUX=1` are
+ * explicit "I want the bare process" requests, and honouring them over the
+ * durability rule keeps one escape hatch that always works.
+ *
+ * Pure, so the gate is unit-tested independently of the (side-effecting) spawn.
  */
-export function shouldWrapInTmux(ctx) {
+export function resolveTmuxWrap(ctx) {
+    // A headless `-p` run has no TTY to attach, Windows has no tmux path, and
+    // nesting tmux-in-tmux is pointless — none of these can wrap, and none of them
+    // is a remote interactive agent whose life depends on it.
     if (!ctx.interactive)
-        return false;
+        return { kind: 'bare' };
     if (ctx.platform === 'win32')
-        return false;
+        return { kind: 'bare' };
     if (ctx.inTmux)
-        return false;
+        return { kind: 'bare' };
+    // Explicit opt-outs win over the durability rule: `--raw` exists precisely to
+    // get the unwrapped process, and a flag that silently stopped working on a
+    // remote box would be worse than an undurable run the user asked for.
     if (ctx.raw)
-        return false;
+        return { kind: 'bare' };
     if (ctx.noTmuxEnv)
-        return false;
-    if (!ctx.configEnabled)
-        return false;
+        return { kind: 'bare' };
+    if (!ctx.configEnabled && !ctx.remoteDispatch)
+        return { kind: 'bare' };
+    // Fail loud rather than launch a remote agent that a blink would kill: the
+    // caller refuses the run instead of starting work that cannot be recovered.
     if (!ctx.tmuxAvailable)
-        return false;
-    return true;
+        return ctx.remoteDispatch ? { kind: 'undurable' } : { kind: 'bare' };
+    return { kind: 'wrap' };
 }
 /**
  * Build the shell command that runs an agent inside a tmux pane with the exact
@@ -1225,6 +1236,29 @@ export function shouldWrapInTmux(ctx) {
  * into SessionMeta.cmd on disk (tmux/session.ts). The launched command uses the
  * real values; the stored/informational copy uses the redacted form (RUSH-1758).
  */
+/**
+ * True when `options.sessionId` is an id the HARNESS actually received, and so a
+ * real, resumable handle — rather than one the launcher generated for its own
+ * bookkeeping and the agent never saw.
+ *
+ * Mirrors exactly the two branches in buildExecCommand that put the id on the
+ * command line: a native resume (any harness with a `resume` spec) and claude's
+ * create-with-`--session-id`. Everything else — `agents run codex --session-id X`
+ * without `--resume`, or a fresh non-claude launch whose real id only shows up
+ * later via the SessionStart hook — leaves the agent with an id of its own
+ * choosing, so `options.sessionId` must not be published as if it were that id.
+ *
+ * Keep in lockstep with buildExecCommand's resume/create branches: a harness
+ * that gains a forced-session-id flag must be reflected here in the SAME change,
+ * or this reports a genuine id as fabricated.
+ */
+export function isHarnessKnownSessionId(agent, sessionId, resume) {
+    if (!sessionId)
+        return false;
+    if (resume && AGENT_COMMANDS[agent]?.resume)
+        return true;
+    return agent === 'claude';
+}
 export function buildTmuxAgentCommand(executable, args, env, opts = {}) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     // envFile: source the values instead of inlining them, so no VALUE ever lands
@@ -1430,8 +1464,13 @@ async function runInTmux(options, executable, args) {
     const cmd = buildTmuxAgentCommand(executable, args, execEnv, { envFile });
     const metaCmd = buildTmuxAgentCommand(executable, args, execEnv, { redactEnvValues: true });
     const labels = { agent: options.agent };
-    if (options.sessionId)
+    // Only publish an id the harness actually received. createSession turns this
+    // label into the `@ag_session_id` tmux option that status bars read, and a
+    // launcher-internal id displayed there looks exactly like a resumable one
+    // while `ag focus <id>` rejects it.
+    if (isHarnessKnownSessionId(options.agent, options.sessionId, options.resume)) {
         labels.sessionId = options.sessionId;
+    }
     // Only a launched pane sources-and-unlinks the env file. If createSession
     // throws, the pane never runs, so the resolved secrets (incl. the master
     // passphrase) would linger on disk — remove it on that failure path
@@ -1616,19 +1655,36 @@ async function spawnAgent(options) {
         command: executable,
         args: redactArgs(args.slice(0, 10)),
     });
-    // Interactive spawn-wrap: when this device opts in on macOS/Linux, run the
-    // agent INSIDE a shared-socket tmux session (then attach this TTY) so it gets
-    // a unique, addressable %pane. Every failed guard keeps the bare spawn below.
-    const wrapInTmux = shouldWrapInTmux({
+    // Interactive spawn-wrap: run the agent INSIDE a shared-socket tmux session
+    // (then attach this TTY) so it gets a unique, addressable %pane — and, when
+    // the run arrived over `--device`, so it survives the SSH link that carries
+    // it. Every failed guard keeps the bare spawn below.
+    const tmuxWrap = resolveTmuxWrap({
         interactive,
         platform: process.platform,
         inTmux: !!process.env.TMUX,
         raw: options.raw === true,
         noTmuxEnv: process.env.AGENTS_NO_TMUX === '1',
         configEnabled: isTmuxEnabled(),
+        remoteDispatch: process.env[REMOTE_INTERACTIVE_ENV] === '1',
         tmuxAvailable: isTmuxInstalled(),
     });
-    if (wrapInTmux) {
+    if (tmuxWrap.kind === 'undurable') {
+        // Refuse rather than start work a blink would destroy. This is the ONLY
+        // check — `ensureHostReady` gates a `--device` dispatch on the peer being
+        // reachable and able to run the pinned agent, not on it having tmux, so
+        // there is no launcher-side probe ahead of this one. Failing here still
+        // fails before the agent starts, which is what matters; a pre-dispatch
+        // probe would only move the message earlier, at the cost of a round trip on
+        // every launch.
+        const msg = `agents: ${machineId()} has no tmux, so a --device run here could not survive a dropped connection.\n`
+            + `  install it:            (apt|dnf|brew) install tmux\n`
+            + `  or accept the risk:    agents run … --device ${machineId()} --raw\n`;
+        process.stderr.write(`\x1b[31m${msg}\x1b[0m`);
+        timer.end({ exitCode: 1, status: 'failed', error: 'remote interactive run has no tmux for durability' });
+        return { exitCode: 1, stdout: '', stderr: msg };
+    }
+    if (tmuxWrap.kind === 'wrap') {
         timer.mark('startup');
         try {
             const result = await runInTmux(options, executable, args);

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

package/dist/lib/helper-download.js

@@ -0,0 +1,194 @@
+/**
+ * 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 { execFileSync, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { getCacheDir } from './state.js';
+import { parseSha256Asset, sha256File } from './sha256-asset.js';
+import { helperTag } from './helper-versions.js';
+/** GitHub repo whose `v<version>` releases carry the helper assets. */
+export 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 const EXPECTED_TEAM_ID = '2HTP252L87';
+/** Cache dir for a downloaded helper, one subdir per release tag. */
+export function helperCacheDir(spec, version) {
+    return path.join(getCacheDir(), ...spec.cacheSubdir, `v${version}`);
+}
+/**
+ * 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 function helperAssetUrls(spec, version) {
+    const base = `https://github.com/${HELPER_RELEASE_REPO}/releases/download/${helperTag(spec.helper, version)}`;
+    // Asset names must not contain spaces: GitHub rewrites a space to a dot on
+    // upload, so a spaced name is requested at a URL that 404s forever. Caught on
+    // `Agents CLI.app.zip`, which GitHub served as `Agents.CLI.app.zip`. Use an
+    // underscore -- GitHub preserves it verbatim.
+    if (spec.assetName.includes(' ')) {
+        throw new Error(`helper asset name ${JSON.stringify(spec.assetName)} contains a space; GitHub rewrites it to a dot on `
+            + 'upload, so this URL would always 404. Use an underscore instead.');
+    }
+    return { zip: `${base}/${spec.assetName}`, sha256: `${base}/${spec.assetName}.sha256` };
+}
+/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
+ *  emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
+export function parseTeamId(codesignInfo) {
+    return codesignInfo.match(/TeamIdentifier=([A-Z0-9]+)/)?.[1] ?? 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 function readDesignatedRequirement(appPath) {
+    const r = spawnSync('/usr/bin/codesign', ['-d', '--requirements', '-', appPath], { encoding: 'utf8' });
+    return `${r.stdout ?? ''}${r.stderr ?? ''}`;
+}
+/**
+ * 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 function checkDesignatedRequirement(req, bundleId, teamId) {
+    const trimmed = req.trim();
+    const shown = trimmed ? JSON.stringify(trimmed.slice(0, 200)) : '<none>';
+    if (!trimmed.includes(`identifier "${bundleId}"`)) {
+        return (`helper designated requirement does not pin bundle id "${bundleId}" (read: ${shown}). ` +
+            `Installing it would revoke the Accessibility grant. Refusing to install.`);
+    }
+    if (!trimmed.includes(teamId)) {
+        return (`helper designated requirement does not pin Developer ID Team ${teamId} (read: ${shown}). ` +
+            `Installing it would revoke the Accessibility grant. Refusing to install.`);
+    }
+    return 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 function verifyDesignatedRequirement(appPath, bundleId, teamId) {
+    const err = checkDesignatedRequirement(readDesignatedRequirement(appPath), bundleId, teamId);
+    if (err)
+        throw new Error(err);
+}
+/**
+ * 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 function verifyHelperApp(appPath, spec) {
+    // 1. Structural + signature integrity.
+    try {
+        execFileSync('/usr/bin/codesign', ['--verify', '--deep', '--strict', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`code signature invalid for ${appPath}: ${e.message}`);
+    }
+    // 2. Team identity — must be our Developer ID, not some other valid signer.
+    // `codesign -dv` writes its details to STDERR even on success (exit 0), so we
+    // must read stderr, not stdout. spawnSync captures both streams regardless of
+    // exit code; execFileSync would return only (empty) stdout and the Team check
+    // would falsely reject every validly-signed helper.
+    const dv = spawnSync('/usr/bin/codesign', ['-dv', '--verbose=4', appPath], { encoding: 'utf8' });
+    const info = `${dv.stdout ?? ''}${dv.stderr ?? ''}`;
+    const team = parseTeamId(info);
+    if (team !== spec.expectedTeamId) {
+        throw new Error(`helper signed by unexpected Team (${team ?? 'none'}), expected ${spec.expectedTeamId}. Refusing to install.`);
+    }
+    // 3. Designated-requirement pin (menu-bar helper only) — before the Gatekeeper
+    //    assessment so a DR mismatch fails with its specific, actionable message
+    //    rather than a generic Gatekeeper rejection.
+    if (spec.expectedBundleId) {
+        verifyDesignatedRequirement(appPath, spec.expectedBundleId, spec.expectedTeamId);
+    }
+    // 4. Notarization / Gatekeeper — confirms Apple stapled a notarization ticket.
+    try {
+        execFileSync('/usr/sbin/spctl', ['--assess', '--type', 'execute', '--verbose', appPath], { stdio: 'pipe' });
+    }
+    catch (e) {
+        throw new Error(`helper is not notarized / rejected by Gatekeeper: ${e.message}. Refusing to install.`);
+    }
+}
+/**
+ * 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 async function downloadHelperApp(spec, version) {
+    const dir = helperCacheDir(spec, version);
+    const cachedApp = path.join(dir, spec.appName);
+    if (fs.existsSync(cachedApp)) {
+        // Re-verify a cached bundle cheaply; a tampered cache must not be trusted.
+        verifyHelperApp(cachedApp, spec);
+        return cachedApp;
+    }
+    // Name the HELPER's tag, not `v${version}`: after the per-helper split that
+    // string was a tag that does not exist, so a 404 pointed the reader at the
+    // wrong place to look.
+    const tag = helperTag(spec.helper, version);
+    const { zip: zipUrl, sha256: shaUrl } = helperAssetUrls(spec, version);
+    const missing = (status, url) => new Error(`no ${spec.assetName} release asset for tag ${tag} (HTTP ${status} on ${url}). ` +
+        `The macOS helper ships as a GitHub release asset on its own helper tag; ` +
+        `from a repo checkout you can build it locally instead: ${spec.localBuildHint}`);
+    // Checksum first: it is tiny and 404s fast when the tag has no assets.
+    const shaRes = await fetch(shaUrl, { signal: AbortSignal.timeout(30_000) });
+    if (!shaRes.ok)
+        throw missing(shaRes.status, shaUrl);
+    const expected = parseSha256Asset(await shaRes.text());
+    console.error(`Downloading ${spec.assetName} ${tag} from GitHub releases...`);
+    const zipRes = await fetch(zipUrl, { signal: AbortSignal.timeout(15 * 60_000) });
+    if (!zipRes.ok || !zipRes.body)
+        throw missing(zipRes.status, zipUrl);
+    fs.mkdirSync(dir, { recursive: true });
+    const partial = path.join(dir, `${spec.assetName}.download`);
+    try {
+        await pipeline(Readable.fromWeb(zipRes.body), fs.createWriteStream(partial));
+        const actual = await sha256File(partial);
+        if (actual !== expected) {
+            throw new Error(`sha256 mismatch for ${zipUrl}: expected ${expected}, got ${actual}`);
+        }
+        // Extract the zip (created with `ditto -c -k --keepParent`, so it contains
+        // <appName>/ at top level) into the version cache dir.
+        fs.rmSync(cachedApp, { recursive: true, force: true });
+        execFileSync('/usr/bin/ditto', ['-x', '-k', partial, dir], { stdio: 'pipe' });
+        if (!fs.existsSync(cachedApp)) {
+            throw new Error(`extracted asset did not contain ${spec.appName}`);
+        }
+        verifyHelperApp(cachedApp, spec);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
+    }
+    return cachedApp;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Which build of each native helper this CLI expects, and where its release
+ * lives — the module that decouples helper distribution from CLI releases.
+ *
+ * WHY THIS EXISTS. `helperAssetUrls` used to build
+ * `releases/download/v${cliVersion}/<asset>`, keying every helper to the CLI's
+ * own tag. That is coupled in BOTH directions and each one hurts:
+ *
+ *   - A CLI release had to re-stage every helper asset onto its new tag, or the
+ *     download 404'd. That is what chained an ordinary release to a Mac.
+ *   - A helper fix could not reach anyone without cutting a CLI release, because
+ *     no URL existed that a shipped CLI would look at.
+ *
+ * Helpers now publish to their OWN tags (`<helper>/v<x.y.z>`) and this table
+ * records the FLOOR — the build this CLI was tested against. A floor, not an
+ * exact pin: a pin would fix the first problem and leave the second, since an
+ * improved helper would still need a CLI release to be reachable. The floor is
+ * what a channel manifest can later resolve *upward* from (newest >= floor),
+ * without another rewrite of the download path.
+ *
+ * The floor is also the offline answer: it names an IMMUTABLE tag that always
+ * exists, so a machine that cannot reach a manifest still has exactly one
+ * correct URL rather than a guess.
+ *
+ * Bumping an entry here is a deliberate act — it says "this CLI has been tested
+ * against that helper build". It is not a mirror of the CLI version and must
+ * never be derived from `getCliVersion()`.
+ */
+/** The helpers that have their own release train. */
+export type HelperName = 'menubar' | 'keychain' | 'computer-mac' | 'computer-win';
+/** One helper's release identity. */
+export interface HelperRelease {
+    /** Tag prefix — the release is `<tagPrefix>/v<version>`. */
+    tagPrefix: string;
+    /**
+     * Lowest helper build this CLI is known to work with. Resolution may pick a
+     * NEWER build; it must never pick an older one.
+     */
+    floor: string;
+}
+/**
+ * Floors, by helper.
+ *
+ * `menubar` and `keychain` start at 1.0.0 — the first builds published under
+ * their own tags rather than the CLI's. They are not "version 1 of the helper";
+ * they are version 1 of its independent release train.
+ */
+export declare const HELPER_RELEASES: Readonly<Record<HelperName, HelperRelease>>;
+/** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
+export declare function helperTag(helper: HelperName, version: string): string;
+/** The floor build for one helper — the version used when nothing resolves higher. */
+export declare function helperFloor(helper: HelperName): string;

package/dist/lib/helper-versions.js

@@ -0,0 +1,58 @@
+/**
+ * Which build of each native helper this CLI expects, and where its release
+ * lives — the module that decouples helper distribution from CLI releases.
+ *
+ * WHY THIS EXISTS. `helperAssetUrls` used to build
+ * `releases/download/v${cliVersion}/<asset>`, keying every helper to the CLI's
+ * own tag. That is coupled in BOTH directions and each one hurts:
+ *
+ *   - A CLI release had to re-stage every helper asset onto its new tag, or the
+ *     download 404'd. That is what chained an ordinary release to a Mac.
+ *   - A helper fix could not reach anyone without cutting a CLI release, because
+ *     no URL existed that a shipped CLI would look at.
+ *
+ * Helpers now publish to their OWN tags (`<helper>/v<x.y.z>`) and this table
+ * records the FLOOR — the build this CLI was tested against. A floor, not an
+ * exact pin: a pin would fix the first problem and leave the second, since an
+ * improved helper would still need a CLI release to be reachable. The floor is
+ * what a channel manifest can later resolve *upward* from (newest >= floor),
+ * without another rewrite of the download path.
+ *
+ * The floor is also the offline answer: it names an IMMUTABLE tag that always
+ * exists, so a machine that cannot reach a manifest still has exactly one
+ * correct URL rather than a guess.
+ *
+ * Bumping an entry here is a deliberate act — it says "this CLI has been tested
+ * against that helper build". It is not a mirror of the CLI version and must
+ * never be derived from `getCliVersion()`.
+ */
+/**
+ * Floors, by helper.
+ *
+ * `menubar` and `keychain` start at 1.0.0 — the first builds published under
+ * their own tags rather than the CLI's. They are not "version 1 of the helper";
+ * they are version 1 of its independent release train.
+ */
+export const HELPER_RELEASES = {
+    menubar: { tagPrefix: 'menubar', floor: '1.0.0' },
+    keychain: { tagPrefix: 'keychain', floor: '1.0.0' },
+    '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' },
+};
+/** The release tag for one helper at one version, e.g. `menubar/v1.0.0`. */
+export function helperTag(helper, version) {
+    const release = HELPER_RELEASES[helper];
+    if (!release)
+        throw new Error(`unknown helper '${helper}' (want: ${Object.keys(HELPER_RELEASES).join(', ')})`);
+    return `${release.tagPrefix}/v${version}`;
+}
+/** The floor build for one helper — the version used when nothing resolves higher. */
+export function helperFloor(helper) {
+    const release = HELPER_RELEASES[helper];
+    if (!release)
+        throw new Error(`unknown helper '${helper}' (want: ${Object.keys(HELPER_RELEASES).join(', ')})`);
+    return release.floor;
+}

package/dist/lib/hooks/cache.js

@@ -283,6 +283,17 @@ def should_fire():
             if pm and pm not in allowed:
                 return False
 
+    v = m.get("permission_mode_not")
+    if v is not None:
+        denied = arr(v)
+        if denied:
+            # Negative form: naming the mode to SKIP keeps every unknown mode
+            # firing, so the failure direction is "ran unnecessarily", never
+            # "did not run". Absence of a mode fires, same as permission_mode.
+            pm = inp.get("permission_mode") or inp.get("permissionMode")
+            if pm and pm in denied:
+                return False
+
     v = m.get("tool_args_match")
     if v is not None:
         ta = inp.get("tool_args")

package/dist/lib/hooks/install.js

@@ -3255,8 +3255,8 @@ function resolveSessionTrackerRoot() {
     if (fs.existsSync(path.join(built, 'dist', 'hook.sh'))) {
         return built;
     }
-    // Source layout: apps/cli/src/lib/hooks/ -> repo root -> packages/session-tracker
-    const source = path.resolve(here, '..', '..', '..', '..', '..', 'packages', 'session-tracker');
+    // Source layout: cli/src/lib/hooks/ -> repo root (4 up) -> packages/session-tracker
+    const source = path.resolve(here, '..', '..', '..', '..', 'packages', 'session-tracker');
     if (fs.existsSync(path.join(source, 'src', 'hook.sh'))) {
         return source;
     }

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

@@ -6,7 +6,7 @@
  * codex/grok/gemini `auth.json`-style files — so the box booted logged-in. Every
  * one of those is a **rotating, interactive OAuth / session credential**, and
  * copying it between devices is forbidden by the fleet-auth contract
- * (`docs/specifications.md` SING-1b, `docs/credential-management.md` invariant 2):
+ * (`docs/specifications.md` SING-1b, `docs/secrets.md`):
  * a shared refresh token rotates server-side on the next refresh and invalidates
  * every other copy — the "droid collapsed 10 boxes to 1 overnight" failure.
  *