@phnx-labs/agents-cli 1.22.88 → 1.22.89

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 1.22.89
+
+- **Worker daemons now actually relaunch onto a new agents-cli release, so a fix
+  that ships reaches every worker without a hand `agents daemon restart`
+  (PHNX-3940 rollout).** Two defects kept every fleet daemon on the code it
+  booted with: `resolveRunningPackageRoot(__dirname)` resolved one level up from
+  the calling module, which from `dist/lib/daemon/self-update-service.js` is
+  `dist/lib`, so every self-update tick failed with `… is not an npm-managed
+  install` (eight Linux workers logged it for days and ran 1.22.79 code while the
+  disk sat at 1.22.88); and the tick only exited after an install it performed
+  itself, so an install written by an operator's `agents` command never relaunched
+  the daemon, and on a box with a second `agents` on PATH the tick declined
+  silently. The resolver now walks up to the `package.json` naming this package;
+  the tick compares the on-disk version with the version it booted with and, when
+  the disk is newer and the install has settled (`package.json` at rest for a
+  minute and every `bin` entry present, because bun's write is not atomic), exits
+  for the OS-supervisor relaunch without downloading anything. The shadow decline
+  is logged once per daemon process, and `auth-sync` logs accounts skipped
+  because their durable key is not readable on the box. Source:
+  `cli/src/lib/self-update.ts`, `cli/src/lib/daemon/self-update-service.ts`,
+  `cli/src/lib/daemon/auth-sync-service.ts`.
+
+- **AGI Menu palette: real projects, Linear from the binding, pin, live screenshots, image paste (PHNX-4001).**
+  The `Cmd-Shift-O` palette now picks a **project**, not a directory: it lists every
+  `agents projects` definition by name (with a type-ahead filter and the root as a
+  tooltip) instead of the last eight session working directories, so a project you
+  have not worked in today is still one keystroke away, and two definitions that
+  share a checkout — `prix` and `rush` both live in the same monorepo — stay two
+  entries. Dispatch passes `--project <name>`; recent session cwds now only offer a
+  worktree or subdirectory *inside* the chosen project. The ticket list is scoped by
+  the project's own Linear **binding** rather than by matching folder names against
+  Linear project names, which is why picking `agi` now shows the AGI board instead of
+  "no Linear project matches agents-cli"; a project with no binding says so and prints
+  `agents projects link <name> --linear`. The palette can be **pinned** (header button,
+  or press `Cmd-Shift-O` while it is already focused) so it survives another app
+  taking focus. The screenshot strip is **live** — a shot taken while the palette is
+  open appears within about a second, with no re-summon — and images can be pasted
+  with `Cmd-V` or dropped onto the panel; `Backspace` on a focused thumbnail removes
+  it. Attachments now travel to the agent as `<host>:<abs-path>` references (the same
+  form `Cmd-Shift-V` types), so a dispatch to another device can fetch them. The
+  ticket list starts folded and `Cmd-T` toggles it, remembered. On a machine with no
+  projects defined the palette falls back to recent session working directories, and
+  with neither a project nor a recent directory it now refuses to dispatch instead of
+  launching an agent with no working directory (which resolved to `/`).
+  Source: `cli/menubar/Sources/MenubarHelper/PromptPanel.swift`,
+  `cli/menubar/Sources/MenubarHelper/ScreenshotWatcher.swift`,
+  `cli/menubar/Sources/MenubarHelper/LinearTickets.swift`.
+
+- **The CLI now posts one actionable desktop banner per new attention item, so a
+  session asking a question, a permission prompt, or a plan review is answerable
+  straight from the notification (PHNX-4004).** A new supervised `attention-notify`
+  daemon service (tick 5 s, reader-independent) reconciles this host's live
+  sessions each tick and posts a banner carrying the category, the attention key,
+  the session id, and the answerable choices — Approve / Approve for session / Deny
+  for a permission, the options plus a typed reply for a question, Approve / Send
+  back for a plan review, Open terminal for a stall — which the macOS helper routes
+  back through `agents feed answer <key> --choice <id>`. A `deny`/`send-back`
+  choice delivers a real Escape keystroke (no trailing Enter) rather than the
+  letters "esc", so cancelling a permission or plan prompt never confirms it.
+  `agents run --notify` finish banners now carry `category: done|failure`; the
+  finish-notification shape also carries the session id and open-report / open-pr
+  choices when the caller supplies a session id, report path, or PR url.
+  Idempotency is a filesystem ledger under `~/.agents/.history/feed/notified/`,
+  pruned at 14 days, so a daemon restart never re-posts a banner already sent. The
+  `--notify` argv gains `--category`, `--key`, `--session`, and repeated
+  `--choice <id>=<label>` (see `docs/menubar.md` → Actionable notifications).
+  Source: `src/lib/menubar/notify-desktop.ts`,
+  `src/lib/daemon/attention-notify-service.ts`, `src/lib/feed/attention.ts`,
+  `src/lib/answer-router.ts`, `src/lib/run-notify.ts`.
+
 ## 1.22.88
 
 - **`agents run` no longer fails with `secrets request failed: spawnSync sh

package/dist/lib/answer-router.d.ts

@@ -32,6 +32,13 @@ export interface AnswerRoute {
         sessionId: string;
         agent: string;
     };
+    /**
+     * Whether to append Enter after the injected payload. Default (omitted) is
+     * true. A cancel keystroke (Escape, from a deny / send-back choice) sets this
+     * false — the ESC byte itself dismisses the prompt, and a trailing newline
+     * would submit a stray empty line into the composer behind it.
+     */
+    enter?: boolean;
 }
 export interface AnswerRouterInput {
     /** Resolved mailbox / session id. */
@@ -56,6 +63,7 @@ export declare function matchOptionIndex(answer: string, options: Array<Pick<Blo
 export declare function keystrokesForAnswer(answer: string, options?: Array<Pick<BlockOption, 'label'>>): {
     payload: string;
     matched: 'option' | 'free-text' | 'other';
+    enter?: boolean;
 };
 /** True when the session is waiting on user input (parked on a question/plan). */
 export declare function isParkedOnInput(session: ActiveSession | null | undefined): boolean;

package/dist/lib/answer-router.js

@@ -1,5 +1,7 @@
 import { addressabilityRecoveryHint } from './terminal/resolve.js';
 import { injectTargetFromReplyRail } from './session/inject.js';
+/** The Escape keystroke as its raw control byte — what a PTY/tmux/iterm rail reads as a real Escape. */
+const ESCAPE_KEY = '\u001b';
 /**
  * Match free-text answer against question options.
  * Exact (case-insensitive) > startsWith > includes. Returns 0-based index or -1.
@@ -31,6 +33,15 @@ export function keystrokesForAnswer(answer, options) {
         // AskUserQuestion / plan select-lists are 1-indexed digits.
         return { payload: `${idx + 1}`, matched: 'option' };
     }
+    // A symbolic cancel token — the `esc` deliveryKey a deny / send-back choice
+    // carries — is the Escape KEY, not the letters "esc". Send the ESC control
+    // byte (a real cancel on every raw pty/tmux/iterm rail) and suppress the
+    // trailing Enter, so the prompt is dismissed rather than confirmed by a stray
+    // newline. Runs after the option match so an option literally labelled "esc"
+    // still wins as a selection.
+    if (/^(?:esc|escape)$/i.test(answer.trim())) {
+        return { payload: ESCAPE_KEY, matched: 'other', enter: false };
+    }
     if (options?.length) {
         const otherIdx = options.findIndex((o) => /^other$/i.test((o.label ?? '').trim()));
         if (otherIdx >= 0) {
@@ -92,7 +103,7 @@ export function resolveAnswerRoute(input) {
         session?.question?.options?.map((o) => ({ label: o.label }));
     if (openQ && parked && session) {
         const inject = injectTargetForSession(session);
-        const { payload, matched } = keystrokesForAnswer(answer, options);
+        const { payload, matched, enter } = keystrokesForAnswer(answer, options);
         if (inject) {
             const kind = inject.backend === 'tmux' ? 'tmux'
                 : inject.backend === 'iterm' ? 'iterm'
@@ -103,6 +114,7 @@ export function resolveAnswerRoute(input) {
                 reason: `Parked on open question — drive ${inject.backend} selection (${matched}).`,
                 payload,
                 inject,
+                ...(enter === false ? { enter: false } : {}),
             };
         }
         // Headless / no rail: re-enter via resume.

package/dist/lib/daemon/attention-notify-service.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Attention desktop banners as a supervised periodic service (PHNX-4004).
+ *
+ * Each tick reconciles this host's live sessions into attention items through
+ * the CLI-owned reconciler (feed/attention.ts — never re-deriving detection) and
+ * posts ONE actionable desktop banner per attention key not yet notified. The
+ * banner carries the category, the attention key, the session id, and the
+ * answerable choices, so the macOS companion can offer Approve / Approve for
+ * session / Deny (permission), the options plus a typed reply (question),
+ * Approve / Send back (plan review), or Open terminal (a stall/failure), and
+ * route the answer back through `agents feed answer <key> --choice <id>`.
+ *
+ * Idempotency is a filesystem ledger, not memory: one sidecar file per notified
+ * key under `~/.agents/.history/feed/notified/`, so a daemon restart never
+ * re-posts a banner already sent — the ledger is the truth. It is pruned with
+ * the feed's 14-day retention rule.
+ *
+ * Reader-independent: unlike the session-state publisher this does NOT gate on a
+ * live `sessions watch` reader — an attention banner must fire whether or not
+ * anyone is watching the stream. `done` banners are deliberately NOT produced
+ * here; they ride the run process's own exit (`run-notify.ts`).
+ */
+import { type ActiveSession } from '../session/active.js';
+import { type AttentionItem } from '../feed/attention.js';
+import { type DesktopNotification } from '../menubar/notify-desktop.js';
+import { BasePeriodicService, type DaemonContext } from './service.js';
+import type { DaemonServiceId } from '../daemon-services.js';
+/**
+ * The banner for one attention item, or `undefined` when its kind does not
+ * notify (`done` comes from the run process; `declared`/`review` are surfaced in
+ * the feed, not as a native banner). Pure — the service and its test both build
+ * through here, so what ships is what is asserted.
+ */
+export declare function buildAttentionNotification(item: AttentionItem, session: ActiveSession): DesktopNotification | undefined;
+export interface AttentionNotifyServiceOptions {
+    /** Live-session source (default: the real active-session query). Injected in tests. */
+    getSessions?: () => Promise<ActiveSession[]>;
+    /** Notifier (default: the real desktop notifier). Injected in tests to capture posts. */
+    notify?: (n: DesktopNotification) => void;
+    /** Feed store root (default: the real feed dir). Overridden in tests. */
+    feedRoot?: string;
+    /** Notified-ledger dir (default: `<feedRoot>/notified`). Overridden in tests. */
+    ledgerDir?: string;
+    /** Clock (default: `Date.now`). Injected in tests. */
+    now?: () => number;
+}
+export declare class AttentionNotifyService extends BasePeriodicService {
+    readonly id: DaemonServiceId;
+    readonly intervalMs = 5000;
+    readonly deadlineMs = 10000;
+    private readonly getSessions;
+    private readonly notify;
+    private readonly feedRoot?;
+    private readonly ledgerDir;
+    private readonly now;
+    private lastPruneMs;
+    constructor(opts?: AttentionNotifyServiceOptions);
+    protected onStart(_ctx: DaemonContext): Promise<void>;
+    protected onStop(): Promise<void>;
+    protected onTick(ctx: DaemonContext): Promise<void>;
+    /** Filesystem-safe sidecar name for an attention key (`host/session/generation`). */
+    private ledgerPath;
+    private hasNotified;
+    private markNotified;
+    private pruneLedger;
+}

package/dist/lib/daemon/attention-notify-service.js

@@ -0,0 +1,185 @@
+/**
+ * Attention desktop banners as a supervised periodic service (PHNX-4004).
+ *
+ * Each tick reconciles this host's live sessions into attention items through
+ * the CLI-owned reconciler (feed/attention.ts — never re-deriving detection) and
+ * posts ONE actionable desktop banner per attention key not yet notified. The
+ * banner carries the category, the attention key, the session id, and the
+ * answerable choices, so the macOS companion can offer Approve / Approve for
+ * session / Deny (permission), the options plus a typed reply (question),
+ * Approve / Send back (plan review), or Open terminal (a stall/failure), and
+ * route the answer back through `agents feed answer <key> --choice <id>`.
+ *
+ * Idempotency is a filesystem ledger, not memory: one sidecar file per notified
+ * key under `~/.agents/.history/feed/notified/`, so a daemon restart never
+ * re-posts a banner already sent — the ledger is the truth. It is pruned with
+ * the feed's 14-day retention rule.
+ *
+ * Reader-independent: unlike the session-state publisher this does NOT gate on a
+ * live `sessions watch` reader — an attention banner must fire whether or not
+ * anyone is watching the stream. `done` banners are deliberately NOT produced
+ * here; they ride the run process's own exit (`run-notify.ts`).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { atomicWriteFile } from '../fs-atomic.js';
+import { getFeedDir } from '../state.js';
+import { machineId } from '../machine-id.js';
+import { getActiveSessions } from '../session/active.js';
+import { blockIdForSession, readBlock, readResolution } from '../feed/feed.js';
+import { reconcileAttention, harnessOf } from '../feed/attention.js';
+import { notifyDesktop } from '../menubar/notify-desktop.js';
+import { BasePeriodicService } from './service.js';
+const ATTENTION_NOTIFY_TICK_MS = 5_000;
+const ATTENTION_NOTIFY_DEADLINE_MS = 10_000;
+/** Feed retention: a notified-ledger sidecar older than this is pruned. */
+const LEDGER_RETENTION_MS = 14 * 24 * 60 * 60 * 1000;
+/** Prune the ledger at most this often — the dir is tiny, but a dir walk every 5s is waste. */
+const LEDGER_PRUNE_EVERY_MS = 60 * 60 * 1000;
+/** UNUserNotificationCenter caps action buttons; the argv contract is ≤ 6 choices. */
+const MAX_CHOICES = 6;
+/** Body cap — a banner truncates anyway, and a wall of text is noise. */
+const BODY_MAX = 200;
+/** Which attention kinds produce a banner, and the category + title verb each carries. */
+const BANNER_KINDS = {
+    permission: { category: 'permission', label: 'Command approval' },
+    question: { category: 'question', label: 'Question' },
+    plan_review: { category: 'plan_review', label: 'Plan review' },
+    stall: { category: 'failure', label: 'Failed' },
+    failure: { category: 'failure', label: 'Failed' },
+};
+function shorten(text, max = BODY_MAX) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * The banner for one attention item, or `undefined` when its kind does not
+ * notify (`done` comes from the run process; `declared`/`review` are surfaced in
+ * the feed, not as a native banner). Pure — the service and its test both build
+ * through here, so what ships is what is asserted.
+ */
+export function buildAttentionNotification(item, session) {
+    const spec = BANNER_KINDS[item.kind];
+    if (!spec)
+        return undefined;
+    const shortId = item.sessionId ? item.sessionId.slice(0, 8) : 'session';
+    const who = session.label?.trim() || session.title?.trim() || shortId;
+    const n = {
+        title: `${who} · ${spec.label}`,
+        body: shorten(item.question?.text?.trim() || spec.label),
+        category: spec.category,
+        key: item.key,
+    };
+    const agent = harnessOf(session);
+    if (agent)
+        n.agent = agent;
+    if (item.sessionId)
+        n.sessionId = item.sessionId;
+    const subtitle = [item.host, item.project].filter(Boolean).join(' · ');
+    if (subtitle)
+        n.subtitle = subtitle;
+    // A stall/failure has no answerable option list — it offers one button that
+    // opens the session's terminal. Everything else carries the reconciled choices.
+    const choices = spec.category === 'failure'
+        ? [{ id: 'open-terminal', label: 'Open terminal' }]
+        : (item.choices ?? []).slice(0, MAX_CHOICES).map((c) => ({ id: c.id, label: c.label }));
+    if (choices.length)
+        n.choices = choices;
+    return n;
+}
+export class AttentionNotifyService extends BasePeriodicService {
+    id = 'attention-notify';
+    intervalMs = ATTENTION_NOTIFY_TICK_MS;
+    deadlineMs = ATTENTION_NOTIFY_DEADLINE_MS;
+    getSessions;
+    notify;
+    feedRoot;
+    ledgerDir;
+    now;
+    lastPruneMs = 0;
+    constructor(opts = {}) {
+        super();
+        this.getSessions = opts.getSessions ?? (() => getActiveSessions());
+        this.notify = opts.notify ?? notifyDesktop;
+        this.feedRoot = opts.feedRoot;
+        this.ledgerDir = opts.ledgerDir ?? path.join(opts.feedRoot ?? getFeedDir(), 'notified');
+        this.now = opts.now ?? Date.now;
+    }
+    async onStart(_ctx) {
+        // No handles to open — each tick re-reads sessions and the ledger.
+    }
+    async onStop() {
+        // Nothing to release — the supervisor's timer teardown is the only cleanup.
+    }
+    async onTick(ctx) {
+        const sessions = await this.getSessions();
+        const host = machineId();
+        for (const session of sessions) {
+            if (!session.sessionId)
+                continue;
+            // ActiveSession.host names the terminal app; the reconciler's host is the
+            // device scope, so the attention key is fleet-routable (mirrors watch.ts).
+            const projected = { ...session, host };
+            const blockId = blockIdForSession(session.sessionId);
+            const item = reconcileAttention({
+                block: readBlock(blockId, this.feedRoot),
+                session: projected,
+                resolution: readResolution(blockId, this.feedRoot),
+                nowMs: this.now(),
+            });
+            if (!item || !BANNER_KINDS[item.kind])
+                continue;
+            if (await this.hasNotified(item.key))
+                continue;
+            const notification = buildAttentionNotification(item, projected);
+            if (!notification)
+                continue;
+            this.notify(notification);
+            await this.markNotified(item.key);
+            ctx.log('INFO', `attention-notify: posted ${item.kind} banner for ${item.key}`);
+        }
+        await this.pruneLedger();
+    }
+    /** Filesystem-safe sidecar name for an attention key (`host/session/generation`). */
+    ledgerPath(key) {
+        return path.join(this.ledgerDir, encodeURIComponent(key));
+    }
+    async hasNotified(key) {
+        // fs/promises has no existsSync; a stat that rejects with ENOENT is the miss.
+        try {
+            await fs.promises.stat(this.ledgerPath(key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async markNotified(key) {
+        await fs.promises.mkdir(this.ledgerDir, { recursive: true });
+        await atomicWriteFile(this.ledgerPath(key), JSON.stringify({ key, postedAt: new Date(this.now()).toISOString() }), 'utf-8');
+    }
+    async pruneLedger() {
+        const nowMs = this.now();
+        if (nowMs - this.lastPruneMs < LEDGER_PRUNE_EVERY_MS)
+            return;
+        this.lastPruneMs = nowMs;
+        let names;
+        try {
+            names = await fs.promises.readdir(this.ledgerDir);
+        }
+        catch {
+            return; // No ledger dir yet — nothing to prune.
+        }
+        for (const name of names) {
+            const filePath = path.join(this.ledgerDir, name);
+            try {
+                const stat = await fs.promises.stat(filePath);
+                if (nowMs - stat.mtimeMs > LEDGER_RETENTION_MS)
+                    await fs.promises.rm(filePath, { force: true });
+            }
+            catch {
+                // A file that vanished mid-walk is already gone; skip it.
+            }
+        }
+    }
+}

package/dist/lib/daemon/auth-sync-service.js

@@ -36,6 +36,14 @@ export class AuthSyncService extends BasePeriodicService {
                 ctx.log('INFO', `auth-sync: provisioned worker slot(s) for ${slots.provisioned.join(', ')}`);
             for (const err of slots.errors)
                 ctx.log('WARN', `auth-sync: worker slot ${err.accountId}: ${err.message}`);
+            // A row skipped for a key this box cannot read is the one silent outcome
+            // an operator needs to see: it is what "0 slots after the daemon restart"
+            // looked like on yosemite-m0 (2026-09-07), where the durable key was in
+            // the bundle but the `secrets` on the daemon's PATH could not decrypt it.
+            const waiting = slots.skipped.filter((s) => s.reason === 'durable key not synced yet');
+            if (waiting.length > 0) {
+                ctx.log('WARN', `auth-sync: ${waiting.length} registered account(s) have no readable durable key on this box yet; slot not provisioned (${waiting.map((s) => s.accountId).join(', ')})`);
+            }
         }
         catch (err) {
             ctx.log('WARN', `auth-sync: worker slot reconcile: ${err.message}`);

package/dist/lib/daemon/daemon.js

@@ -45,6 +45,7 @@ import { AuthSyncService } from './auth-sync-service.js';
 import { UsageSyncService } from './usage-sync-service.js';
 import { StateDirCheckService } from './state-dir-check-service.js';
 import { SessionStateService } from './session-state-service.js';
+import { AttentionNotifyService } from './attention-notify-service.js';
 import { WebhookReceiverService } from './webhook-receiver-service.js';
 import { HeartbeatService } from './heartbeat-service.js';
 import { TmuxReapService } from './tmux-reap-service.js';
@@ -1051,6 +1052,14 @@ export async function runDaemon() {
         supervisor.register(new SessionSummarizerService());
     else
         log('INFO', 'Session summarizer service disabled');
+    // Attention desktop banners (PHNX-4004) — posts one actionable native banner
+    // per new attention key. Reader-independent: it fires whether or not a
+    // `sessions watch` reader is present, and the notified-ledger is its
+    // idempotency truth across daemon restarts.
+    if (isEnabled('attention-notify'))
+        supervisor.register(new AttentionNotifyService());
+    else
+        log('INFO', 'Attention-notify service disabled');
     // Watchdog, device-probe, and self-heal are all periodic services managed
     // by the ServiceSupervisor (RUSH-3193 P3). Each is gated the same way as
     // the socket services above; state-dir-check is registered separately,

package/dist/lib/daemon/self-update-service.d.ts

@@ -61,7 +61,12 @@ interface NpmLatestMetadata {
  * branch exists in the exported logic itself.
  */
 export interface SelfUpdateDeps {
+    /** The version this process BOOTED with (memoized at startup). */
     currentVersion(): string;
+    /** The version of the install on disk right now — differs from `currentVersion` once another process upgraded it. */
+    installedVersion(): string;
+    /** True when the install on disk looks complete (see `installLooksSettled`) — the gate before relaunching onto a version another process wrote. */
+    installedIsSettled(): boolean;
     isDevBuild(): boolean;
     detectShadow(): boolean;
     packageRoot(): string;
@@ -162,6 +167,10 @@ export declare function triggerSelfUpdateInBackground(ctx: DaemonContext, deps?:
  * reason, or `null` to proceed to the (backgrounded) install path.
  */
 export declare function selfUpdateSyncDeclineReason(deps?: SelfUpdateDeps): string | null;
+export declare const DEV_BUILD_DECLINE = "dev build \u2014 self-update is a no-op";
+export declare const SHADOW_DECLINE = "another agents binary shadows this install \u2014 self-update is a no-op";
+/** True when the package on disk is a strictly newer release than the one this process booted with. */
+export declare function installedIsNewerThanRunning(installed: string, running: string): boolean;
 export declare class SelfUpdateService extends BasePeriodicService {
     readonly id: DaemonServiceId;
     readonly intervalMs: number;

package/dist/lib/daemon/self-update-service.js

@@ -34,11 +34,11 @@
  * relaunch-loop on a broken install.
  */
 import { BasePeriodicService } from './service.js';
-import { getCliVersion } from '../version.js';
+import { getCliVersion, getCliVersionFresh } from '../version.js';
 import { isDevVersionStamp } from '../startup/dev-build.js';
 import { detectAgentsBinaryShadows } from '../binary-shadow.js';
 import { compareVersions } from '../agent-spec/primitives.js';
-import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, downloadVerifiedTarball, ensureGlobalBinLinks, installPackageIntoPrefix, installPackageWithBun, refreshAliasShims, resolveRunningPackageRoot, sweepStaleInstallStaging, verifyInstalledVersion, } from '../self-update.js';
+import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, downloadVerifiedTarball, ensureGlobalBinLinks, installPackageIntoPrefix, installLooksSettled, installPackageWithBun, refreshAliasShims, resolveRunningPackageRoot, sweepStaleInstallStaging, verifyInstalledVersion, } from '../self-update.js';
 import { tryAutoPullSystemRepo } from '../git.js';
 import { getSystemAgentsDir } from '../state.js';
 import { runUmbrellaSync } from '../sync-umbrella.js';
@@ -151,6 +151,8 @@ export async function installAndVerifyDefault(metadata, packageRoot, signal) {
 export function defaultSelfUpdateDeps() {
     return {
         currentVersion: () => getCliVersion(),
+        installedVersion: () => getCliVersionFresh(),
+        installedIsSettled: () => installLooksSettled(resolveRunningPackageRoot(__dirname)),
         isDevBuild: () => isDevVersionStamp(getCliVersion()),
         detectShadow: () => detectAgentsBinaryShadows().length > 0,
         packageRoot: () => resolveRunningPackageRoot(__dirname),
@@ -214,10 +216,33 @@ export async function attemptSelfUpdateAndExit(ctx, signal, deps = defaultSelfUp
     }
 }
 async function runSelfUpdateAttempt(ctx, signal, deps) {
+    // One decline source for the periodic tick and the on-demand IPC path
+    // (`selfUpdateSyncDeclineReason`): dev build; shadowed install — except when
+    // the install on disk is already newer than the running code, because a
+    // relaunch installs nothing and a second `agents` on the box is irrelevant to
+    // it (otherwise a shadowed worker never leaves the release it booted on).
     const syncDecline = selfUpdateSyncDeclineReason(deps);
     if (syncDecline)
         return { updated: false, reason: syncDecline };
+    // Another agents process (an operator's `agents` command auto-updating, an
+    // `agents upgrade`, the installer) may already have replaced the install
+    // under this daemon. The code on disk is then newer than the code in memory
+    // and there is nothing to download — that path verified its install before
+    // it returned. Exit for the OS-supervisor relaunch, once the install has
+    // settled: npm's reify is atomic but bun's is not, so a version bump alone
+    // could be bun mid-extraction (`installLooksSettled`). Waiting one tick is
+    // cheap; relaunching into a half-written tree is a supervisor crash-loop.
     const current = deps.currentVersion();
+    const installed = deps.installedVersion();
+    if (installedIsNewerThanRunning(installed, current)) {
+        if (!deps.installedIsSettled()) {
+            ctx.log('INFO', `self-update: the install on disk is ${installed} (this daemon is running ${current}) but it is still settling; relaunch deferred to the next tick`);
+            return { updated: false, reason: 'installed version still settling' };
+        }
+        ctx.log('INFO', `self-update: the install on disk is ${installed} but this daemon is still running ${current}; ` +
+            'exiting for OS-supervisor relaunch onto the installed code');
+        return { updated: true };
+    }
     let metadata;
     try {
         metadata = await deps.fetchLatestMetadata(signal);
@@ -329,11 +354,24 @@ export function triggerSelfUpdateInBackground(ctx, deps = defaultSelfUpdateDeps(
  */
 export function selfUpdateSyncDeclineReason(deps = defaultSelfUpdateDeps()) {
     if (deps.isDevBuild())
-        return 'dev build — self-update is a no-op';
-    if (deps.detectShadow())
-        return 'another agents binary shadows this install — self-update is a no-op';
+        return DEV_BUILD_DECLINE;
+    // A stale install is never declined by a shadow: the relaunch installs nothing.
+    // (Whether that install has SETTLED is the attempt's call, not a decline.)
+    if (deps.detectShadow() && !installedIsNewerThanRunning(deps.installedVersion(), deps.currentVersion())) {
+        return SHADOW_DECLINE;
+    }
     return null;
 }
+export const DEV_BUILD_DECLINE = 'dev build — self-update is a no-op';
+export const SHADOW_DECLINE = 'another agents binary shadows this install — self-update is a no-op';
+/** True when the package on disk is a strictly newer release than the one this process booted with. */
+export function installedIsNewerThanRunning(installed, running) {
+    if (installed === 'unknown' || running === 'unknown')
+        return false;
+    return compareVersions(installed, running) > 0;
+}
+/** The shadow decline is logged once per daemon process — a silent permanent no-op is how eight workers sat on stale code unnoticed (2026-09-07). */
+let shadowDeclineLogged = false;
 export class SelfUpdateService extends BasePeriodicService {
     id = 'self-update';
     intervalMs = SELF_UPDATE_TICK_MS;
@@ -347,7 +385,14 @@ export class SelfUpdateService extends BasePeriodicService {
     }
     async onTick(ctx, signal) {
         const outcome = await attemptSelfUpdateAndExit(ctx, signal);
-        if (outcome.updated)
+        if (outcome.updated) {
             scheduleSelfUpdateExit();
+            return;
+        }
+        if (outcome.reason === SHADOW_DECLINE && !shadowDeclineLogged) {
+            shadowDeclineLogged = true;
+            ctx.log('WARN', `self-update: ${outcome.reason}; this daemon will only move to a new release after another agents ` +
+                'process upgrades the install (`agents doctor` lists the shadow copy)');
+        }
     }
 }

package/dist/lib/daemon-services.d.ts

@@ -7,7 +7,7 @@
  * enabled without pulling in the whole daemon lifecycle.
  */
 /** Every service the daemon can host. IDs are kebab-case and stable. */
-export type DaemonServiceId = 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer' | 'harness-update';
+export type DaemonServiceId = 'scheduler' | 'catchup' | 'monitors' | 'browser-ipc' | 'webhook-receiver' | 'self-heal' | 'self-update' | 'account-state' | 'account-auth' | 'watchdog' | 'device-probe' | 'state-dir-check' | 'session-index' | 'auth-sync' | 'usage-sync' | 'daemon-heartbeat' | 'tmux-reap' | 'browser-task-reap' | 'session-state' | 'session-summarizer' | 'attention-notify' | 'harness-update';
 /** Human-readable metadata for each service. */
 export interface DaemonServiceDef {
     id: DaemonServiceId;

package/dist/lib/daemon-services.js

@@ -102,6 +102,11 @@ export const DAEMON_SERVICES = [
         title: 'Session summarizer',
         description: 'Computes a per-session goal / progress checkpoints / checklist off the request path and delivers them on the session stream. Off unless summarizer.enabled and a local model endpoint are configured (PHNX-3939).',
     },
+    {
+        id: 'attention-notify',
+        title: 'Attention desktop banners',
+        description: 'Posts one actionable desktop banner per new attention item (question / permission / plan review / stall) so the macOS helper can answer it through agents feed answer (PHNX-4004).',
+    },
     {
         id: 'auth-sync',
         title: 'Auth bundle sync',

package/dist/lib/feed/answer.js

@@ -106,7 +106,7 @@ export async function claimAndRouteAttentionAnswer(input) {
         else {
             if (!route.inject || route.payload == null)
                 throw new Error(`Incomplete ${route.kind} reply rail.`);
-            const delivered = await injectIntoTerminal(route.inject, route.payload, { enter: true, combined: false });
+            const delivered = await injectIntoTerminal(route.inject, route.payload, { enter: route.enter ?? true, combined: false });
             if (!delivered.ok)
                 throw new Error(delivered.error ?? `Failed to deliver over ${route.kind}.`);
             msgId = `inject-${Date.now()}`;

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

@@ -68,6 +68,8 @@ export interface PullRequestAttentionSignal {
  * share a fingerprint for batch triage.
  */
 export declare function attentionFingerprint(kind: AttentionKind, question?: BlockQuestion): string;
+/** Harness id behind a session — the profile name when set, else the host process. */
+export declare function harnessOf(session: ActiveSession): string;
 /**
  * Reconcile the feed block ledger, the session lifecycle, a CLI-supplied PR
  * signal, and the latest resolution tombstone into one attention item — or

package/dist/lib/fs-atomic.d.ts

@@ -18,6 +18,13 @@ export declare function atomicWriteFileSync(filePath: string, content: string, o
  * only the `JSON.stringify`.
  */
 export declare function atomicWriteJsonSync(filePath: string, data: unknown): void;
+/**
+ * Async counterpart of {@link atomicWriteFileSync} for callers on the daemon's
+ * shared event loop (PHNX-3695): a `writeFileSync`/`renameSync` on a tick freezes
+ * every service and the browser IPC server until the disk write returns. Same
+ * tmp-then-rename atomicity, but every syscall is awaited via `fs/promises`.
+ */
+export declare function atomicWriteFile(filePath: string, content: string, options?: fs.WriteFileOptions): Promise<void>;
 /**
  * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
  * releases the lock. Retries with capped linear back-off until either the lock

package/dist/lib/fs-atomic.js

@@ -64,6 +64,26 @@ export function atomicWriteFileSync(filePath, content, options = 'utf-8') {
 export function atomicWriteJsonSync(filePath, data) {
     atomicWriteFileSync(filePath, JSON.stringify(data, null, 2));
 }
+/**
+ * Async counterpart of {@link atomicWriteFileSync} for callers on the daemon's
+ * shared event loop (PHNX-3695): a `writeFileSync`/`renameSync` on a tick freezes
+ * every service and the browser IPC server until the disk write returns. Same
+ * tmp-then-rename atomicity, but every syscall is awaited via `fs/promises`.
+ */
+export async function atomicWriteFile(filePath, content, options = 'utf-8') {
+    const tmpPath = `${filePath}.tmp-${process.pid}-${randomBytes(8).toString('hex')}`;
+    await fs.promises.writeFile(tmpPath, content, options);
+    try {
+        await fs.promises.rename(tmpPath, filePath);
+    }
+    catch (err) {
+        try {
+            await fs.promises.unlink(tmpPath);
+        }
+        catch { /* best-effort cleanup */ }
+        throw err;
+    }
+}
 export function withFileLock(filePath, fn, opts = {}) {
     let release = null;
     let lastError;

package/dist/lib/menubar/notify-desktop.d.ts

@@ -47,6 +47,33 @@ export interface DesktopNotification {
      * repeating the left one. macOS-only; osascript / notify-send carry no image.
      */
     agent?: string;
+    /**
+     * What the banner is asking of the operator, so the companion can pick the
+     * UNUserNotificationCenter category (its action buttons) — a `permission`
+     * banner offers Approve / Approve for session / Deny; a `question` offers the
+     * options plus a typed reply; a `plan_review` offers Approve / Send back; a
+     * `done`/`failure` banner offers open-report / open-pr / open-terminal.
+     * macOS-only (the companion decides the buttons); osascript / notify-send
+     * carry no actions. See {@link choices} for the answerable set.
+     */
+    category?: 'permission' | 'question' | 'plan_review' | 'done' | 'failure';
+    /**
+     * The attention key (`AttentionItem.key`) the companion hands to
+     * `agents feed answer <key>` when the operator picks a choice. The stable
+     * handle the reply rail resolves against; carried verbatim in argv.
+     */
+    key?: string;
+    /** Session this banner belongs to, so the companion can open/focus it. */
+    sessionId?: string;
+    /**
+     * Ordered, answerable choices (≤ 6). Each `id` is `[a-z0-9-]+` and is what the
+     * companion echoes back to `agents feed answer --choice <id>`; `label` is the
+     * plain-text button caption. Carried one `--choice <id>=<label>` per entry.
+     */
+    choices?: {
+        id: string;
+        label: string;
+    }[];
 }
 /** Argv for the "AGI Menu" one-shot notify mode. Exported for tests. */
 export declare function buildMenubarNotifyArgs(n: DesktopNotification): string[];

package/dist/lib/menubar/notify-desktop.js

@@ -41,6 +41,17 @@ export function buildMenubarNotifyArgs(n) {
         args.push('--action', n.action);
     if (n.agent)
         args.push('--agent', n.agent);
+    if (n.category)
+        args.push('--category', n.category);
+    if (n.key)
+        args.push('--key', n.key);
+    if (n.sessionId)
+        args.push('--session', n.sessionId);
+    // Each choice is one argv pair `id=label`. ids are `[a-z0-9-]+` and labels are
+    // plain text; every field is its own argv entry (the child never sees a shell),
+    // so an `=` inside a label is inert — the companion splits on the FIRST `=`.
+    for (const c of n.choices ?? [])
+        args.push('--choice', `${c.id}=${c.label}`);
     return args;
 }
 /** AppleScript for the osascript degradation path. Exported for tests. */

package/dist/lib/run-notify.d.ts

@@ -12,6 +12,10 @@ export interface RunNotifyContext {
     host?: string;
     /** Clickable target — a PR/ticket URL the caller already knows. */
     url?: string;
+    /** Session id the run coined, so the banner can open/focus it. */
+    sessionId?: string;
+    /** Report/log path the run produced — becomes the `open-report` choice + `open:` action. */
+    reportPath?: string;
 }
 /**
  * The finish notification for one run. Pure — the exit handler and the tests

package/dist/lib/run-notify.js

@@ -31,17 +31,36 @@ export function buildRunFinishNotification(ctx, exitCode) {
     const label = ctx.name?.trim() || ctx.agent;
     const project = ctx.cwd ? path.basename(ctx.cwd) : undefined;
     const where = [project, ctx.host].filter(Boolean).join(' · ');
+    const ok = exitCode === 0;
     const n = {
-        title: exitCode === 0 ? `${label} finished` : `${label} failed`,
+        title: ok ? `${label} finished` : `${label} failed`,
         body: shorten(ctx.prompt?.trim() || `${ctx.agent} run`),
         // The harness that ran becomes the banner's right-hand avatar, so a finished
         // run is identifiable at a glance even when `--name` renamed the title.
         agent: ctx.agent,
+        // Categorize so the companion can offer the run's follow-up buttons; a
+        // failed run gets the failure category, a clean one the done category.
+        category: ok ? 'done' : 'failure',
     };
     if (where)
         n.subtitle = where;
-    if (ctx.url)
+    if (ctx.sessionId)
+        n.sessionId = ctx.sessionId;
+    // The primary click target: a report opens the report file, else the PR url.
+    if (ctx.reportPath)
+        n.action = `open:${ctx.reportPath}`;
+    else if (ctx.url)
         n.action = `url:${ctx.url}`;
+    // Follow-up buttons the companion renders: open the report when one exists,
+    // open the PR when a url is known. `open-report` reuses the `open:` action
+    // resolution; `open-pr` opens `ctx.url`.
+    const choices = [];
+    if (ctx.reportPath)
+        choices.push({ id: 'open-report', label: 'Open report' });
+    if (ctx.url)
+        choices.push({ id: 'open-pr', label: 'Open PR' });
+    if (choices.length)
+        n.choices = choices;
     return n;
 }
 /**

package/dist/lib/self-update.d.ts

@@ -104,18 +104,22 @@ export declare function resolveMultiInstallInventory(runningRoot: string, runnin
 /**
  * The on-disk package root of the copy that is currently running.
  *
- * For a plain JS install this is just `<__dirname>/..`. Under the compiled
- * standalone binary (shipped since 1.20.53) it is not: Bun sets `__dirname` to
- * its embedded virtual FS, so `<__dirname>/..` yields `/$bunfs` — a path that
- * exists nowhere. That phantom value was reported as a second install by the
- * multi-install check, and rejected by deriveGlobalPrefix as "not an
- * npm-managed install", so every self-upgrade from a compiled copy failed.
+ * For a plain JS install, walk up from the CALLING module's directory to the
+ * directory whose package.json names this package. Never assume a fixed depth:
+ * `<__dirname>/..` is the root only for a module directly under `dist/`, and
+ * from `dist/lib/daemon/self-update-service.js` it answered `dist/lib`, which
+ * deriveGlobalPrefix rejected as "not an npm-managed install" on every daemon
+ * self-update tick (2026-09-07 fleet incident).
  *
- * The physical executable is `process.execPath`, which ships inside the
- * package (`<packageRoot>/dist/bin/agents`). Walk up from it to the directory
- * whose package.json actually names this package rather than assuming a fixed
- * depth, so a change to the dist layout surfaces as a clear throw here instead
- * of a wrong prefix that npm would happily install into.
+ * Under the compiled standalone binary (shipped since 1.20.53) `__dirname` is
+ * Bun's embedded virtual FS, so walking up from it yields `/$bunfs` — a path
+ * that exists nowhere. That phantom value was reported as a second install by
+ * the multi-install check and rejected by deriveGlobalPrefix, so every
+ * self-upgrade from a compiled copy failed. The physical executable is
+ * `process.execPath`, which ships inside the package
+ * (`<packageRoot>/dist/bin/agents`); walk up from it instead. Either way a
+ * change to the dist layout surfaces as a clear throw here rather than a wrong
+ * prefix that npm would happily install into.
  */
 export declare function resolveRunningPackageRoot(dirname: string, execPath?: string): string;
 /**
@@ -175,8 +179,30 @@ export declare function installPackageIntoPrefix(spec: string, prefix: string, s
  * alias shims afterwards via refreshAliasShims() rather than relying on the
  * package's postinstall hook.
  *
+ * Unlike npm's arborist (see {@link sweepStaleInstallStaging}: retire-rename,
+ * then one final rename), bun's write into the package directory is NOT known
+ * to be atomic — files may land incrementally. Anything that trusts a version
+ * bump on disk written by ANOTHER process (the daemon's stale-install relaunch
+ * in `daemon/self-update-service.ts`) must therefore gate on
+ * {@link installLooksSettled} rather than on the version alone.
+ *
  * `signal` behaves exactly as documented on {@link installPackageIntoPrefix}.
  */
+/** How long an install's package.json must have been at rest before a foreign version bump is trusted. */
+export declare const INSTALL_SETTLE_MS = 60000;
+/**
+ * True when the install at `packageRoot` looks complete: its package.json has
+ * not been modified for at least `settleMs`, and every `bin` entry it declares
+ * exists on disk. This is the guard for trusting a version bump that a
+ * DIFFERENT process wrote (an operator's `agents` auto-update, `agents
+ * upgrade`, the installer) without re-running that process's own verification:
+ * npm's reify is an atomic rename, but bun's is not (see
+ * {@link installPackageWithBun}), so a reader can catch bun mid-extraction —
+ * package.json present, `dist/` still landing. An install finishes in seconds;
+ * a minute of quiet plus the bin entry present rules that window out. Any
+ * read error means "not settled".
+ */
+export declare function installLooksSettled(packageRoot: string, settleMs?: number, now?: number): boolean;
 export declare function installPackageWithBun(spec: string, signal?: AbortSignal): Promise<void>;
 /**
  * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)

package/dist/lib/self-update.js

@@ -240,37 +240,59 @@ function isPackageRoot(dir) {
 /**
  * The on-disk package root of the copy that is currently running.
  *
- * For a plain JS install this is just `<__dirname>/..`. Under the compiled
- * standalone binary (shipped since 1.20.53) it is not: Bun sets `__dirname` to
- * its embedded virtual FS, so `<__dirname>/..` yields `/$bunfs` — a path that
- * exists nowhere. That phantom value was reported as a second install by the
- * multi-install check, and rejected by deriveGlobalPrefix as "not an
- * npm-managed install", so every self-upgrade from a compiled copy failed.
+ * For a plain JS install, walk up from the CALLING module's directory to the
+ * directory whose package.json names this package. Never assume a fixed depth:
+ * `<__dirname>/..` is the root only for a module directly under `dist/`, and
+ * from `dist/lib/daemon/self-update-service.js` it answered `dist/lib`, which
+ * deriveGlobalPrefix rejected as "not an npm-managed install" on every daemon
+ * self-update tick (2026-09-07 fleet incident).
  *
- * The physical executable is `process.execPath`, which ships inside the
- * package (`<packageRoot>/dist/bin/agents`). Walk up from it to the directory
- * whose package.json actually names this package rather than assuming a fixed
- * depth, so a change to the dist layout surfaces as a clear throw here instead
- * of a wrong prefix that npm would happily install into.
+ * Under the compiled standalone binary (shipped since 1.20.53) `__dirname` is
+ * Bun's embedded virtual FS, so walking up from it yields `/$bunfs` — a path
+ * that exists nowhere. That phantom value was reported as a second install by
+ * the multi-install check and rejected by deriveGlobalPrefix, so every
+ * self-upgrade from a compiled copy failed. The physical executable is
+ * `process.execPath`, which ships inside the package
+ * (`<packageRoot>/dist/bin/agents`); walk up from it instead. Either way a
+ * change to the dist layout surfaces as a clear throw here rather than a wrong
+ * prefix that npm would happily install into.
  */
 export function resolveRunningPackageRoot(dirname, execPath = process.execPath) {
-    const fromDirname = path.resolve(dirname, '..');
-    if (!isBunVirtualPath(fromDirname))
-        return fromDirname;
+    if (!isBunVirtualPath(dirname)) {
+        // Walk up from the CALLING module's directory to the package.json that
+        // names this package. The previous `path.resolve(dirname, '..')` was only
+        // right for a module one level below the root (dist/bootstrap.js); from
+        // dist/lib/daemon/self-update-service.js it answered `dist/lib`, so
+        // `deriveGlobalPrefix` threw "not an npm-managed install" on every daemon
+        // self-update tick, fleet-wide, and no daemon ever relaunched onto a
+        // release (2026-09-07: eight workers still running 1.22.79 code four
+        // releases later).
+        const found = findPackageRootAbove(dirname);
+        if (found)
+            return found;
+        throw new Error(`Cannot locate the running agents-cli install: no ${NPM_PACKAGE_NAME} package.json above ` +
+            `${dirname}. Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
+    }
     if (!execPath || isBunVirtualPath(execPath)) {
-        throw new Error(`Cannot locate the running agents-cli install: __dirname is the Bun virtual path ${fromDirname} ` +
+        throw new Error(`Cannot locate the running agents-cli install: __dirname is the Bun virtual path ${dirname} ` +
             `and process.execPath (${execPath || '(empty)'}) is not a real file. ` +
             `Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
     }
-    let dir = path.dirname(path.resolve(execPath));
+    const found = findPackageRootAbove(path.dirname(path.resolve(execPath)));
+    if (found)
+        return found;
+    throw new Error(`Cannot locate the running agents-cli install: no ${NPM_PACKAGE_NAME} package.json above ` +
+        `${execPath}. Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
+}
+/** Nearest ancestor of `start` (inclusive) whose package.json names this package, or null. */
+function findPackageRootAbove(start) {
+    let dir = path.resolve(start);
     for (;;) {
         if (isPackageRoot(dir))
             return dir;
         const parent = path.dirname(dir);
-        if (parent === dir) {
-            throw new Error(`Cannot locate the running agents-cli install: no ${NPM_PACKAGE_NAME} package.json above ` +
-                `${execPath}. Reinstall with: npm install -g ${NPM_PACKAGE_NAME}`);
-        }
+        if (parent === dir)
+            return null;
         dir = parent;
     }
 }
@@ -376,8 +398,43 @@ export async function installPackageIntoPrefix(spec, prefix, signal) {
  * alias shims afterwards via refreshAliasShims() rather than relying on the
  * package's postinstall hook.
  *
+ * Unlike npm's arborist (see {@link sweepStaleInstallStaging}: retire-rename,
+ * then one final rename), bun's write into the package directory is NOT known
+ * to be atomic — files may land incrementally. Anything that trusts a version
+ * bump on disk written by ANOTHER process (the daemon's stale-install relaunch
+ * in `daemon/self-update-service.ts`) must therefore gate on
+ * {@link installLooksSettled} rather than on the version alone.
+ *
  * `signal` behaves exactly as documented on {@link installPackageIntoPrefix}.
  */
+/** How long an install's package.json must have been at rest before a foreign version bump is trusted. */
+export const INSTALL_SETTLE_MS = 60_000;
+/**
+ * True when the install at `packageRoot` looks complete: its package.json has
+ * not been modified for at least `settleMs`, and every `bin` entry it declares
+ * exists on disk. This is the guard for trusting a version bump that a
+ * DIFFERENT process wrote (an operator's `agents` auto-update, `agents
+ * upgrade`, the installer) without re-running that process's own verification:
+ * npm's reify is an atomic rename, but bun's is not (see
+ * {@link installPackageWithBun}), so a reader can catch bun mid-extraction —
+ * package.json present, `dist/` still landing. An install finishes in seconds;
+ * a minute of quiet plus the bin entry present rules that window out. Any
+ * read error means "not settled".
+ */
+export function installLooksSettled(packageRoot, settleMs = INSTALL_SETTLE_MS, now = Date.now()) {
+    try {
+        const pkgJsonPath = path.join(packageRoot, 'package.json');
+        const stat = fs.statSync(pkgJsonPath);
+        if (now - stat.mtimeMs < settleMs)
+            return false;
+        const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
+        const bins = typeof pkg.bin === 'string' ? [pkg.bin] : Object.values(pkg.bin ?? {});
+        return bins.every((rel) => fs.existsSync(path.join(packageRoot, rel)));
+    }
+    catch {
+        return false;
+    }
+}
 export async function installPackageWithBun(spec, signal) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.88",
+  "version": "1.22.89",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",