@phnx-labs/agents-cli 1.22.88 → 1.22.90

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}`);
@@ -67,6 +75,8 @@ export class AuthSyncService extends BasePeriodicService {
         // the only transport — provisioning (above) writes only locally (invariant 1).
         try {
             const stores = await syncReservedStores();
+            if (stores.adopted.length > 0)
+                ctx.log('INFO', `auth-sync: adopted ${stores.adopted.length} legacy reserved item(s) into their bundle: ${stores.adopted.map((a) => `${a.bundle} ${a.key}`).join(', ')}`);
             for (const p of stores.pushed)
                 ctx.log('INFO', `auth-sync: pushed ${p.bundle} (${p.keys.length} key(s)) to ${p.device}`);
             for (const err of stores.errors)

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/secrets-policy.d.ts

@@ -171,6 +171,11 @@ export declare function readDeliveryMemo(root?: string): Record<string, string>;
 export declare function peerPresentKeys(peer: string, accounts: ReservedSyncAccount[], memo: Record<string, string>, legacyAuthReady: boolean): Record<string, ReadonlySet<string>>;
 export interface ReservedStoreSyncResult {
     publisher: string | null;
+    /** Legacy raw reserved items adopted into their bundle on this box before planning (local repair). */
+    adopted: Array<{
+        bundle: string;
+        key: string;
+    }>;
     pushed: Array<{
         device: string;
         bundle: string;
@@ -197,6 +202,18 @@ export interface ReservedStoreSyncDeps {
     localReady?: boolean;
     /** Does THIS publisher hold (bundle, key) to push? Defaults to a local bundle read. */
     hasLocalKey?: (bundle: string, key: string) => boolean;
+    /** Adopt pre-bundle raw reserved items locally before planning; defaults to `adoptLegacyReservedStoreItems`. */
+    adoptLegacy?: (meta: Pick<Meta, 'accounts' | 'deviceAccounts'>) => Promise<{
+        adopted: Array<{
+            bundle: string;
+            key: string;
+        }>;
+        errors: Array<{
+            bundle: string;
+            key: string;
+            message: string;
+        }>;
+    }>;
     push?: (bundle: string, host: string) => Promise<PushBundleResult>;
     sshTarget?: (device: DeviceProfile) => string;
 }

package/dist/lib/secrets-policy.js

@@ -375,11 +375,24 @@ function defaultHasLocalKey(bundle, key) {
  * there is no second scheduler. The daemon runs this each tick.
  */
 export async function syncReservedStores(deps = {}) {
-    const result = { publisher: null, pushed: [], skipped: [], errors: [] };
+    const result = { publisher: null, adopted: [], pushed: [], skipped: [], errors: [] };
     const localName = deps.localName ?? machineId();
     const localNorm = normalizeHost(localName);
     const root = deps.userAgentsDir ?? getUserAgentsDir();
     const meta = (deps.readMetaFn ?? readMeta)();
+    // Local repair first: a reserved key written by 1.22.84–1.22.89 is a bare
+    // file item with no bundle record, which the push below cannot read. Adopt
+    // it into its bundle here so the plan sees it; nothing leaves the box.
+    const adopt = deps.adoptLegacy ?? (async (m) => (await import('./auth-mint.js')).adoptLegacyReservedStoreItems(m));
+    try {
+        const adoption = await adopt(meta);
+        result.adopted.push(...adoption.adopted);
+        for (const err of adoption.errors)
+            result.errors.push({ device: localName, message: `adopt ${err.bundle} ${err.key}: ${err.message}` });
+    }
+    catch (err) {
+        result.errors.push({ device: localName, message: `adopt legacy reserved items: ${err.message}` });
+    }
     const hasLocalKey = deps.hasLocalKey ?? defaultHasLocalKey;
     const targets = reservedSyncTargets(meta).filter((t) => hasLocalKey(t.bundle, t.key));
     const devices = (deps.listDevices ?? defaultDevices)().filter((d) => normalizeHost(d.name) !== localNorm);