@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/hosts/remote-session-id.js

@@ -0,0 +1,84 @@
+/**
+ * Resolve a remote-created session id back to an interactive `--host` launcher.
+ *
+ * A headless `--host` run captures the remote-coined id from the followed log
+ * (the `--emit-session-id` marker — see session-marker.ts). An INTERACTIVE run
+ * has no followed log: the local TTY is wired straight through `sshStream`
+ * (stdio:'inherit'), so nothing can tap the stream for a marker without breaking
+ * the agent's raw-mode TUI. Instead we correlate by AGENT_LAUNCH_ID.
+ *
+ * The launcher forwards a launch id it controls (`--env AGENT_LAUNCH_ID=<id>`);
+ * the remote `agents run` adopts it (exec.ts `resolveLaunchId`), so the remote
+ * SessionStart hook records the agent's REAL session id under that exact key in
+ * `~/.agents/.cache/terminals/sessions/<pid>.json`. After the stream returns we
+ * do ONE ssh read of that dir and pick the record whose `launch_id` matches —
+ * the same launch-id join `agents sessions --active` uses locally
+ * (session/hook-sessions.ts), just across the SSH hop.
+ *
+ * This gives the interactive path a real per-agent id to register in the local
+ * session index and to reconnect against, for Codex/Kimi/Grok/Gemini — closing
+ * the gap RUSH-2033 left for every non-Claude agent (Claude still forces its own
+ * id up front and never reaches here).
+ */
+import { sshExec } from '../ssh-exec.js';
+/**
+ * Pick the real session id for `launchId` from the remote hook records.
+ *
+ * `recordsJson` is the newline-delimited JSON the remote read emits — one record
+ * per line (a `cat` of every `sessions/*.json`). Scan for the record whose
+ * `launch_id` matches and return its `session_id`; when several match (pid reuse,
+ * a lingering file) the NEWEST by `ts` wins, mirroring the local reader's
+ * keep-newest tie-break (session/hook-sessions.ts). Pure so the correlation is
+ * unit-testable from fixtures with no SSH. Returns undefined when no record
+ * carries the launch id (the hook hasn't landed yet, or a hookless harness).
+ */
+export function pickRemoteSessionId(recordsJson, launchId) {
+    if (!launchId)
+        return undefined;
+    let best;
+    for (const line of recordsJson.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // a partial/garbled line — skip, never throw
+        }
+        if (rec.launch_id !== launchId)
+            continue;
+        if (typeof rec.session_id !== 'string' || !rec.session_id)
+            continue;
+        const ts = typeof rec.ts === 'number' ? rec.ts : 0;
+        // Strict `>` so the FIRST record wins a tie — matches keepNewest (hook-sessions.ts).
+        if (!best || ts > best.ts)
+            best = { sid: rec.session_id, ts };
+    }
+    return best?.sid;
+}
+/**
+ * Read the remote hook-session dir over ssh and resolve the real session id the
+ * remote run recorded under `launchId`. One round-trip, best-effort: any ssh
+ * failure, a missing dir, or an absent record yields undefined — the caller then
+ * keeps the un-mapped run rather than a fabricated id.
+ *
+ * `$HOME` expands on the REMOTE login shell (never the local box). The glob is a
+ * literal path with no user input, so it is injection-safe; a `2>/dev/null` on a
+ * globless dir keeps the command quiet when the dir is empty or absent.
+ */
+export function resolveRemoteSessionId(target, launchId, timeoutMs = 6000) {
+    if (!launchId)
+        return undefined;
+    // `cat` every record onto its own line. `head -c` caps a runaway file; the
+    // trailing `true` keeps the pipeline's exit 0 even when the glob matches nothing.
+    const cmd = 'cat "$HOME"/.agents/.cache/terminals/sessions/*.json 2>/dev/null | head -c 1048576 || true';
+    const res = sshExec(target, cmd, { timeoutMs, multiplex: true });
+    if (res.code !== 0 && !res.stdout)
+        return undefined;
+    // Each record is a single-line JSON object; `cat` may run them together, so
+    // normalise `}{` boundaries onto separate lines before scanning.
+    const normalised = res.stdout.replace(/\}\s*\{/g, '}\n{');
+    return pickRemoteSessionId(normalised, launchId);
+}

package/dist/lib/hosts/run-target.d.ts

@@ -45,6 +45,8 @@ export interface HostPromptRun {
     name?: string;
     /** Resume an existing session on the host by concrete id. */
     resume?: string;
+    /** Explicit id for a new Claude session. */
+    sessionId?: string;
     /** Working directory on the host, already made remote-portable by the caller. */
     remoteCwd?: string;
     /** Stream progress and block until completion (default true). */
@@ -74,11 +76,21 @@ export interface HostPromptRun {
     /** Copy runtime credentials to the host before the run and shred them after. */
     copyCreds?: HostCredentials;
 }
+/** Resolve the id the remote host will adopt for a fresh Claude session. */
+export declare function resolveHostSessionId(agent: string, resume?: string, sessionId?: string): string | undefined;
 /**
- * Dispatch a headless prompt run onto a resolved host: mint the forced session
- * id (Claude is the only agent that accepts `--session-id`; on resume the
- * remote session keeps its id), launch detached over SSH, and register the run
- * in the LOCAL session index. Returns the task record and the remote exit code
- * (`-1` = follow window closed while the run continues).
+ * Dispatch a headless prompt run onto a resolved host, then relate the run's
+ * session id back to this launcher for EVERY agent — not just Claude.
+ *
+ * Claude is the only agent that accepts a forced `--session-id`, so we mint one
+ * up front and know it immediately. For every other agent the remote run coins
+ * its OWN id; we forward `--emit-session-id` so the remote prints that id as a
+ * stdout sentinel (hosts/session-marker.ts), and once the follow returns we parse
+ * it out of the mirrored local log and stamp it on the task before registering —
+ * so `agents sessions`/resume-by-id can map the discovered session home. On
+ * resume the remote session keeps its existing id (passed through, no capture).
+ *
+ * Returns the task record and the remote exit code (`-1` = follow window closed
+ * while the run continues).
  */
 export declare function dispatchPromptToHost(host: Host, opts: HostPromptRun): Promise<DispatchResult>;

package/dist/lib/hosts/run-target.js

@@ -17,7 +17,7 @@
 import { randomUUID } from 'crypto';
 import { resolveHost, resolveHostByCap } from './registry.js';
 import { dispatchToHost } from './dispatch.js';
-import { registerHostSession } from './session-index.js';
+import { registerHostSession, captureRemoteSessionId } from './session-index.js';
 /**
  * Resolution failed with a user-actionable message the caller should print
  * verbatim. Distinct from `DeviceOffloadUnsupportedError` (which propagates to
@@ -53,15 +53,31 @@ export async function resolveHostRunTarget(name, opts = {}) {
         throw new HostResolutionError(`Unknown host "${name}". List hosts: agents hosts list`);
     return host;
 }
+/** Resolve the id the remote host will adopt for a fresh Claude session. */
+export function resolveHostSessionId(agent, resume, sessionId) {
+    return agent === 'claude' && !resume ? sessionId ?? randomUUID() : undefined;
+}
 /**
- * Dispatch a headless prompt run onto a resolved host: mint the forced session
- * id (Claude is the only agent that accepts `--session-id`; on resume the
- * remote session keeps its id), launch detached over SSH, and register the run
- * in the LOCAL session index. Returns the task record and the remote exit code
- * (`-1` = follow window closed while the run continues).
+ * Dispatch a headless prompt run onto a resolved host, then relate the run's
+ * session id back to this launcher for EVERY agent — not just Claude.
+ *
+ * Claude is the only agent that accepts a forced `--session-id`, so we mint one
+ * up front and know it immediately. For every other agent the remote run coins
+ * its OWN id; we forward `--emit-session-id` so the remote prints that id as a
+ * stdout sentinel (hosts/session-marker.ts), and once the follow returns we parse
+ * it out of the mirrored local log and stamp it on the task before registering —
+ * so `agents sessions`/resume-by-id can map the discovered session home. On
+ * resume the remote session keeps its existing id (passed through, no capture).
+ *
+ * Returns the task record and the remote exit code (`-1` = follow window closed
+ * while the run continues).
  */
 export async function dispatchPromptToHost(host, opts) {
-    const sessionId = opts.agent === 'claude' && !opts.resume ? randomUUID() : undefined;
+    const forcedSessionId = resolveHostSessionId(opts.agent, opts.resume, opts.sessionId);
+    // Ask the remote to print its resolved id whenever we did NOT force one (every
+    // non-Claude agent, and Claude-on-resume where the id is already known). No-op
+    // when the run isn't followed — nothing tails the log to catch the marker.
+    const emitSessionId = !forcedSessionId && !opts.resume && opts.follow !== false;
     const result = await dispatchToHost(host, {
         agent: opts.agent,
         prompt: opts.prompt,
@@ -69,7 +85,8 @@ export async function dispatchPromptToHost(host, opts) {
         mode: opts.mode,
         model: opts.model,
         remoteCwd: opts.remoteCwd,
-        sessionId,
+        sessionId: forcedSessionId,
+        emitSessionId,
         name: opts.name,
         resume: opts.resume,
         follow: opts.follow !== false,
@@ -94,6 +111,9 @@ export async function dispatchPromptToHost(host, opts) {
         passthroughArgs: opts.passthroughArgs,
         copyCreds: opts.copyCreds,
     });
-    registerHostSession(result.task, { cwd: opts.cwd ?? process.cwd(), prompt: opts.prompt });
-    return result;
+    // Capture the remote-coined id from the followed log (non-Claude); harmlessly a
+    // no-op when the task already carries a forced/resumed id or no marker landed.
+    const task = emitSessionId ? captureRemoteSessionId(result.task) ?? result.task : result.task;
+    registerHostSession(task, { cwd: opts.cwd ?? process.cwd(), prompt: opts.prompt });
+    return { ...result, task };
 }

package/dist/lib/hosts/session-index.d.ts

@@ -13,7 +13,7 @@
  * `[cloud/<status>]` convention.
  */
 import type { SessionMeta } from '../session/types.js';
-import type { HostTask } from './tasks.js';
+import { type HostTask } from './tasks.js';
 export interface HostSessionContext {
     /** Local directory the `agents run --host` was invoked from. */
     cwd: string;
@@ -32,6 +32,23 @@ export declare function hostSessionMeta(task: HostTask, ctx: HostSessionContext)
  * break the dispatch itself, which has already been launched on the host.
  */
 export declare function registerHostSession(task: HostTask, ctx: HostSessionContext): void;
+/**
+ * Relate a remote-created session id back to a followed host dispatch.
+ *
+ * The remote run (dispatched with `--emit-session-id`) prints its resolved id as
+ * a stdout sentinel (see session-marker.ts) that rides the followed log into the
+ * task's local mirror. Read that mirror, parse the id, and stamp it on the task
+ * so `findTaskBySessionId` and the session-index registration work for agents
+ * that never take a forced `--session-id` — closing the gap where every
+ * non-Claude host run was orphaned.
+ *
+ * Returns the updated task when an id was captured (and differs from what's on
+ * the record), else null. A task that already carries an id (Claude's forced id,
+ * a resume) is left untouched — the marker only fills a genuinely empty slot, so
+ * it can never overwrite an authoritative id with a stale echo. Best-effort: a
+ * missing/unreadable mirror or absent marker yields null, never an exception.
+ */
+export declare function captureRemoteSessionId(task: HostTask): HostTask | null;
 export interface InteractiveHostSessionContext {
     cwd: string;
     host: string;

package/dist/lib/hosts/session-index.js

@@ -12,8 +12,12 @@
  * local run. The `[host/<name>]` label mirrors the cloud path's
  * `[cloud/<status>]` convention.
  */
+import * as fs from 'fs';
 import { upsertSession } from '../session/db.js';
-import { SESSION_AGENTS } from '../session/types.js';
+import { isSessionTrackedAgent } from '../session/types.js';
+import { localLogPath, updateTask } from './tasks.js';
+import { parseSessionIdMarker } from './session-marker.js';
+import { deriveShortId } from '../session/short-id.js';
 /**
  * Build the SessionMeta for a host-dispatched run. Returns null when the run has
  * no captured session id (nothing stable to key/resume on) or its agent isn't a
@@ -23,11 +27,11 @@ export function hostSessionMeta(task, ctx) {
     const id = task.sessionId;
     if (!id)
         return null;
-    if (!SESSION_AGENTS.includes(task.agent))
+    if (!isSessionTrackedAgent(task.agent))
         return null;
     return {
         id,
-        shortId: id.slice(0, 8),
+        shortId: deriveShortId(id),
         agent: task.agent,
         timestamp: task.createdAt,
         cwd: ctx.cwd,
@@ -57,6 +61,37 @@ export function registerHostSession(task, ctx) {
         /* index write is best-effort; the run is already live on the host */
     }
 }
+/**
+ * Relate a remote-created session id back to a followed host dispatch.
+ *
+ * The remote run (dispatched with `--emit-session-id`) prints its resolved id as
+ * a stdout sentinel (see session-marker.ts) that rides the followed log into the
+ * task's local mirror. Read that mirror, parse the id, and stamp it on the task
+ * so `findTaskBySessionId` and the session-index registration work for agents
+ * that never take a forced `--session-id` — closing the gap where every
+ * non-Claude host run was orphaned.
+ *
+ * Returns the updated task when an id was captured (and differs from what's on
+ * the record), else null. A task that already carries an id (Claude's forced id,
+ * a resume) is left untouched — the marker only fills a genuinely empty slot, so
+ * it can never overwrite an authoritative id with a stale echo. Best-effort: a
+ * missing/unreadable mirror or absent marker yields null, never an exception.
+ */
+export function captureRemoteSessionId(task) {
+    if (task.sessionId)
+        return null;
+    let text;
+    try {
+        text = fs.readFileSync(localLogPath(task.id), 'utf8');
+    }
+    catch {
+        return null; // no local mirror (unfollowed run, or read raced the follow)
+    }
+    const captured = parseSessionIdMarker(text);
+    if (!captured)
+        return null;
+    return updateTask(task.id, { sessionId: captured });
+}
 /**
  * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
  * local session index. Unlike detached host runs, there is no remote log/exit
@@ -64,12 +99,12 @@ export function registerHostSession(task, ctx) {
  * surface and resume it by id.
  */
 export function registerInteractiveHostSession(ctx) {
-    if (!SESSION_AGENTS.includes(ctx.agent))
+    if (!isSessionTrackedAgent(ctx.agent))
         return;
     try {
         upsertSession({
             id: ctx.sessionId,
-            shortId: ctx.sessionId.slice(0, 8),
+            shortId: deriveShortId(ctx.sessionId),
             agent: ctx.agent,
             timestamp: ctx.createdAt ?? new Date().toISOString(),
             cwd: ctx.cwd,

package/dist/lib/hosts/session-marker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Relate a remote-created session id back to the launching agent.
+ *
+ * A host dispatch (`agents run --host`) launches `agents run` on the remote box.
+ * Only Claude accepts a forced `--session-id`, so for every OTHER agent the
+ * remote run coins its OWN session id (via its SessionStart hook) and the
+ * launcher never learns it — the run is orphaned in `agents sessions`.
+ *
+ * This module closes that gap without an extra SSH round-trip: the dispatch
+ * forwards `--emit-session-id`, which makes the remote `agents run` print its
+ * resolved session id as a stable one-line sentinel to stdout. That line rides
+ * the same combined log the follow already mirrors locally, so the launcher
+ * parses the id straight out of the streamed output and stamps it on the task.
+ *
+ * The marker is a fixed ASCII frame with the id on its own line. A real session
+ * id (`[A-Za-z0-9._-]`) never contains the marker's own bytes, so the parser can
+ * scan for the LAST occurrence and stay robust to an agent echoing the token in
+ * its own output.
+ */
+/**
+ * The single line the remote run prints to stdout so the launcher can capture
+ * the session id the remote coined. Newline-framed on both sides so it lands on
+ * its own line regardless of what the agent last wrote.
+ */
+export declare function sessionIdMarkerLine(sessionId: string): string;
+/**
+ * Extract the session id from a chunk of followed remote output, or null when no
+ * marker is present. Scans for the LAST marker (so an id echoed into the log
+ * earlier can never mask the real trailing sentinel) and validates the captured
+ * token against the session-id charset — a malformed frame yields null rather
+ * than a bogus id that could never match a real session.
+ */
+export declare function parseSessionIdMarker(text: string): string | null;

package/dist/lib/hosts/session-marker.js

@@ -0,0 +1,51 @@
+/**
+ * Relate a remote-created session id back to the launching agent.
+ *
+ * A host dispatch (`agents run --host`) launches `agents run` on the remote box.
+ * Only Claude accepts a forced `--session-id`, so for every OTHER agent the
+ * remote run coins its OWN session id (via its SessionStart hook) and the
+ * launcher never learns it — the run is orphaned in `agents sessions`.
+ *
+ * This module closes that gap without an extra SSH round-trip: the dispatch
+ * forwards `--emit-session-id`, which makes the remote `agents run` print its
+ * resolved session id as a stable one-line sentinel to stdout. That line rides
+ * the same combined log the follow already mirrors locally, so the launcher
+ * parses the id straight out of the streamed output and stamps it on the task.
+ *
+ * The marker is a fixed ASCII frame with the id on its own line. A real session
+ * id (`[A-Za-z0-9._-]`) never contains the marker's own bytes, so the parser can
+ * scan for the LAST occurrence and stay robust to an agent echoing the token in
+ * its own output.
+ */
+const MARKER_PREFIX = '@@AGENTS_SESSION_ID ';
+const MARKER_SUFFIX = '@@';
+/** Only characters a real agent session id can hold — no marker bytes, no spaces. */
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/;
+/**
+ * The single line the remote run prints to stdout so the launcher can capture
+ * the session id the remote coined. Newline-framed on both sides so it lands on
+ * its own line regardless of what the agent last wrote.
+ */
+export function sessionIdMarkerLine(sessionId) {
+    return `\n${MARKER_PREFIX}${sessionId}${MARKER_SUFFIX}\n`;
+}
+/**
+ * Extract the session id from a chunk of followed remote output, or null when no
+ * marker is present. Scans for the LAST marker (so an id echoed into the log
+ * earlier can never mask the real trailing sentinel) and validates the captured
+ * token against the session-id charset — a malformed frame yields null rather
+ * than a bogus id that could never match a real session.
+ */
+export function parseSessionIdMarker(text) {
+    const last = text.lastIndexOf(MARKER_PREFIX);
+    if (last === -1)
+        return null;
+    const start = last + MARKER_PREFIX.length;
+    const end = text.indexOf(MARKER_SUFFIX, start);
+    if (end === -1)
+        return null;
+    const id = text.slice(start, end).trim();
+    if (!SESSION_ID_RE.test(id))
+        return null;
+    return id;
+}

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

@@ -24,10 +24,14 @@ export interface HostTask {
      */
     name?: string;
     /**
-     * The agent session id the remote run was launched with (Claude only — the
-     * only agent that accepts `--session-id` to force a NEW session's id). Lets
-     * `agents sessions`/resume-by-id map a discovered session back to the host it
-     * lives on. Absent for agents that don't take an explicit session id.
+     * The remote run's agent session id, so `agents sessions`/resume-by-id can map
+     * a discovered session back to the host it lives on. Two sources: for Claude
+     * (the only agent that accepts `--session-id`) it's the id we FORCED at
+     * dispatch; for every other agent it's the id the remote COINED, captured from
+     * the run's stdout sentinel (`--emit-session-id`, see session-marker.ts) once
+     * the follow returns and stamped on the record via `captureRemoteSessionId`.
+     * Absent only until that capture lands — e.g. an unfollowed (`--no-follow`)
+     * non-Claude run whose id the reconcile path fills in later.
      */
     sessionId?: string;
     /** Remote paths (under the host's ~/.agents/.cache/hosts/). */

package/dist/lib/import.d.ts

@@ -127,10 +127,12 @@ export declare function resolvePackageDirFromBinary(binaryPath: string): string
  */
 export declare function seedIsolatedConfigFromLocal(agentId: AgentId, version: string, opts?: {
     withAuth?: boolean;
+    all?: boolean;
 }): {
     seeded: boolean;
     from: string;
     to: string;
     skippedAuth: string[];
+    skippedRuntime: string[];
     error?: string;
 };

package/dist/lib/import.js

@@ -263,13 +263,35 @@ export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
     const versionHome = path.join(getVersionsDir(), agentId, version, 'home');
     // Mirror importAgentConfig's derivation so nested config dirs (e.g. Antigravity's
     // ~/.gemini/antigravity-cli) land where the shim expects them.
-    const dest = path.join(versionHome, path.relative(os.homedir(), configDir));
-    const result = { seeded: false, from: configDir, to: dest, skippedAuth: [] };
+    let dest = path.join(versionHome, path.relative(os.homedir(), configDir));
+    // Codex uses a SUN_LEN-safe CODEX_HOME: `home/.codex` is a SYMLINK to
+    // `~/.agents/.codex-homes/<version>/.codex`, because the real path is too long for a
+    // unix socket. cpSync cannot overwrite a symlink with a directory (it fails with
+    // "Cannot overwrite non-directory"), and writing beside it would put settings
+    // somewhere the agent never reads. Follow the link and seed the actual home.
+    try {
+        if (fs.lstatSync(dest).isSymbolicLink())
+            dest = fs.realpathSync(dest);
+    }
+    catch {
+        /* not created yet — the plain path is correct */
+    }
+    const result = { seeded: false, from: configDir, to: dest, skippedAuth: [], skippedRuntime: [] };
     if (!fs.existsSync(configDir))
         return result;
     // Known credential paths, relative to the config dir. `authFiles` covers the agents
     // that declare them for cross-version carry; the rest are verified filenames for
     // agents that do not declare any (codex `auth.json`, claude `.credentials.json`).
+    // Runtime state, not settings. Seeding a sandbox with the user's session history,
+    // logs and caches duplicated 757MB on a real machine — 349MB of `sessions` alone —
+    // for a copy that wants config. These are regenerated by the agent as it runs, and
+    // an isolated copy keeps its own; carrying them over also drags conversation history
+    // into a sandbox the user may have created precisely to keep separate.
+    const RUNTIME_PREFIXES = ['sessions', 'log', 'logs', 'cache', '.tmp', 'tmp', 'generated_images'];
+    const RUNTIME_FILES = ['history.jsonl', 'session_index.jsonl'];
+    const isRuntime = (rel) => !opts.all && (RUNTIME_FILES.includes(rel) ||
+        /\.sqlite(-shm|-wal)?$/.test(rel) ||
+        RUNTIME_PREFIXES.some((d) => rel === d || rel.startsWith(d + path.sep)));
     const authRel = new Set([
         ...(agent.authFiles ?? []),
         'auth.json',
@@ -282,12 +304,23 @@ export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
         const inside = agentsDir + path.sep;
         fs.cpSync(configDir, dest, {
             recursive: true,
+            // `force: true` is Node's default, but Bun drops it when a `filter` is supplied —
+            // existing files are then silently left alone. `dist/bin/agents` is bun-compiled,
+            // so this is a production path, not just a test artifact. State it explicitly.
+            force: true,
             filter: (src) => {
                 const rel = path.relative(configDir, src);
                 if (!opts.withAuth && rel && (authRel.has(rel) || rel.startsWith('credentials' + path.sep))) {
                     result.skippedAuth.push(rel);
                     return false;
                 }
+                if (rel && isRuntime(rel)) {
+                    // Record only the top-level name so the report stays one line per item.
+                    const top = rel.split(path.sep)[0];
+                    if (!result.skippedRuntime.includes(top))
+                        result.skippedRuntime.push(top);
+                    return false;
+                }
                 // Same rule as the export path: a link into ~/.agents would dangle for a copy
                 // that is supposed to stand on its own.
                 try {

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

@@ -14,10 +14,39 @@
  * migration (`installMenubarLaunchAgent` in migrate.ts) honors, so a disabled
  * menu bar never silently comes back on the next release.
  */
+/**
+ * Absolute path to the installed MenubarHelper executable if it exists on disk,
+ * else null. The desktop notifier (notify-desktop.ts) routes daemon
+ * notifications through this one-shot (`MenubarHelper --notify ...`) so they
+ * carry the agents-cli mark rather than the generic osascript icon. Null on
+ * non-darwin or when the helper is not installed (menu bar disabled, a Linux
+ * package, or a dev checkout without a built bundle).
+ */
+export declare function resolveInstalledMenubarExecutable(): string | null;
 /** True if the user explicitly disabled the menu bar (don't auto-enable on upgrade). */
 export declare function menubarDisabledByUser(): boolean;
 /** True if the launchd plist for the menu-bar service is installed. */
 export declare function menubarServiceInstalled(): boolean;
+/** True when the bundle carries a signature the kernel will accept at launch. */
+export declare function codesignVerifies(appPath: string): boolean;
+/**
+ * Guarantee the installed bundle has a valid signature on THIS machine.
+ *
+ * npm's pack/extract strips the ad-hoc/linker signature the release baked into
+ * the helper, leaving `code object is not signed at all`. On macOS 26+ the
+ * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
+ * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
+ * an ad-hoc release helper crash-loops forever and its unstable identity makes
+ * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
+ * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
+ * matching cdhash, which the kernel accepts.
+ *
+ * A Developer-ID-signed helper survives npm untouched — its embedded signature
+ * still verifies — so we leave it alone and only re-sign when verification
+ * fails. Returns whether the bundle ends up validly signed. No-op cost on the
+ * common (already-valid) path is a single `codesign --verify`.
+ */
+export declare function ensureValidSignature(appPath: string): boolean;
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships

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

@@ -57,6 +57,20 @@ function readInstalledMenubarVersion() {
 function installedExecutablePath() {
     return path.join(installedAppPath(), 'Contents', 'MacOS', 'MenubarHelper');
 }
+/**
+ * Absolute path to the installed MenubarHelper executable if it exists on disk,
+ * else null. The desktop notifier (notify-desktop.ts) routes daemon
+ * notifications through this one-shot (`MenubarHelper --notify ...`) so they
+ * carry the agents-cli mark rather than the generic osascript icon. Null on
+ * non-darwin or when the helper is not installed (menu bar disabled, a Linux
+ * package, or a dev checkout without a built bundle).
+ */
+export function resolveInstalledMenubarExecutable() {
+    if (!onDarwin())
+        return null;
+    const exec = installedExecutablePath();
+    return fs.existsSync(exec) ? exec : null;
+}
 /** ~/Library/LaunchAgents/com.phnx-labs.agents-menubar.plist */
 function servicePlistPath() {
     return path.join(os.homedir(), 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
@@ -135,6 +149,37 @@ function copyAppBundle(src, dest) {
         throw new Error(`Failed to copy ${src} -> ${dest}: ${msg || 'unknown error'}`);
     }
 }
+/** True when the bundle carries a signature the kernel will accept at launch. */
+export function codesignVerifies(appPath) {
+    const r = spawnSync('codesign', ['--verify', '--strict', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+    return r.status === 0;
+}
+/**
+ * Guarantee the installed bundle has a valid signature on THIS machine.
+ *
+ * npm's pack/extract strips the ad-hoc/linker signature the release baked into
+ * the helper, leaving `code object is not signed at all`. On macOS 26+ the
+ * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
+ * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
+ * an ad-hoc release helper crash-loops forever and its unstable identity makes
+ * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
+ * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
+ * matching cdhash, which the kernel accepts.
+ *
+ * A Developer-ID-signed helper survives npm untouched — its embedded signature
+ * still verifies — so we leave it alone and only re-sign when verification
+ * fails. Returns whether the bundle ends up validly signed. No-op cost on the
+ * common (already-valid) path is a single `codesign --verify`.
+ */
+export function ensureValidSignature(appPath) {
+    if (codesignVerifies(appPath))
+        return true;
+    // Drop any quarantine/xattrs the tarball round-trip added (they can break
+    // codesign), then re-sign ad-hoc under the helper's stable bundle identifier.
+    spawnSync('xattr', ['-cr', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+    spawnSync('codesign', ['--force', '--sign', '-', '--identifier', SERVICE_LABEL, appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+    return codesignVerifies(appPath);
+}
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships
@@ -147,9 +192,14 @@ export function ensureMenubarAppInstalled(opts = {}) {
     if (!src)
         return null;
     const dest = installedAppPath();
-    if (!opts.forceReinstall && fs.existsSync(dest))
+    if (!opts.forceReinstall && fs.existsSync(dest)) {
+        // Self-heal an already-installed bundle whose signature npm stripped on a
+        // prior upgrade (macOS 26+ SIGKILLs it otherwise) without a forced recopy.
+        ensureValidSignature(dest);
         return installedExecutablePath();
+    }
     copyAppBundle(src, dest);
+    ensureValidSignature(dest);
     return installedExecutablePath();
 }
 function xmlEscape(s) {
@@ -241,6 +291,14 @@ export function enableMenubarService(opts = { clearOptOut: true }) {
     const exec = ensureMenubarAppInstalled({ forceReinstall: true });
     if (!exec)
         return false;
+    // Never bootstrap a helper the kernel will kill on launch: an invalid
+    // signature under launchd KeepAlive is an infinite crash loop. If the bundle
+    // can't be made valid (re-sign already attempted in ensureMenubarAppInstalled),
+    // skip the service rather than spin the loop.
+    if (!codesignVerifies(installedAppPath())) {
+        process.stderr.write('agents: menu-bar helper has no valid code signature; skipping launch to avoid a crash loop.\n');
+        return false;
+    }
     if (opts.clearOptOut) {
         try {
             fs.rmSync(disabledSentinelPath(), { force: true });