@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/menubar/migrate-prefs.d.ts

@@ -1,53 +1,6 @@
-/**
- * One-time, CLI-owned migration of AGI Menu preferences from the macOS
- * UserDefaults domain `com.phnx-labs.agents-menubar` into the registered
- * `menubar.menu.*` config keys (PHNX-3999).
- *
- * Why here: before the preferences became `agents config` keys, the stable menu
- * bar stored them in its own UserDefaults. A user upgrading must keep those
- * settings, but the CLI is now the single source of truth and syncs fleet-wide,
- * so the values are lifted into config ONCE and then owned there.
- *
- * The rules (from the integration contract) are all fail-safe:
- *   - macOS only. On any other platform this is a no-op (Linux derives canonical
- *     config only).
- *   - The PRODUCTION domain only — never the dev bundle
- *     `com.phnx-labs.agents-menubar.dev` (we simply never read it).
- *   - Import only KNOWN keys ({@link MENUBAR_MENU_PROPERTIES}) that are still
- *     UNSET in config — an already-set (synced) value is never overridden.
- *   - One-shot, gated by a sentinel, so a later `agents config unset` cannot
- *     resurrect the legacy value on the next run.
- *
- * The stable app stores each preference under its FULL `menubar.menu.*` key name
- * (the Swift MenuPreferences local-cache key), so the migration matches on the
- * full name. If a key is stored under a different name, it simply is not matched
- * and the migration stays a safe no-op for it. The read uses `defaults export
- * <domain> -` piped through `plutil` (NOT `defaults read <domain> -json`, which
- * treats `-json` as a key and errors).
- */
-/**
- * Pure plan step: which UserDefaults entries should be imported. The stable app
- * stores each preference under its FULL `menubar.menu.*` key name (the Swift
- * MenuPreferences local-cache key), so we match on the full name — only known
- * keys that are present in `userDefaults` AND currently unset in config
- * (`isUnset`) are imported, so an already-set value is preserved. Values are
- * returned raw; the caller coerces + validates them against each key's spec.
- */
 export declare function planMenubarPrefMigration(userDefaults: Record<string, unknown>, isUnset: (fullName: string) => boolean): Array<{
     name: string;
     value: unknown;
 }>;
-/**
- * Coerce a raw UserDefaults value to the type its config key expects. The
- * `plutil` scalar output is text, but a bool can arrive as
- * 0/1 or "true"/"false" and an int as a numeric string, so normalize before
- * validation. Returns undefined for a value that cannot be coerced (skipped,
- * never forced).
- */
 export declare function coerceMenubarPrefValue(name: string, raw: unknown): unknown;
-/**
- * Run the one-shot migration. macOS only, gated by the sentinel, best-effort:
- * any failure is swallowed (a migration must never break the snapshot read that
- * calls it) and a failed read remains eligible for a later retry.
- */
 export declare function migrateMenubarPreferencesFromUserDefaults(): void;

package/dist/lib/menubar/migrate-prefs.js

@@ -1,50 +1,13 @@
-/**
- * One-time, CLI-owned migration of AGI Menu preferences from the macOS
- * UserDefaults domain `com.phnx-labs.agents-menubar` into the registered
- * `menubar.menu.*` config keys (PHNX-3999).
- *
- * Why here: before the preferences became `agents config` keys, the stable menu
- * bar stored them in its own UserDefaults. A user upgrading must keep those
- * settings, but the CLI is now the single source of truth and syncs fleet-wide,
- * so the values are lifted into config ONCE and then owned there.
- *
- * The rules (from the integration contract) are all fail-safe:
- *   - macOS only. On any other platform this is a no-op (Linux derives canonical
- *     config only).
- *   - The PRODUCTION domain only — never the dev bundle
- *     `com.phnx-labs.agents-menubar.dev` (we simply never read it).
- *   - Import only KNOWN keys ({@link MENUBAR_MENU_PROPERTIES}) that are still
- *     UNSET in config — an already-set (synced) value is never overridden.
- *   - One-shot, gated by a sentinel, so a later `agents config unset` cannot
- *     resurrect the legacy value on the next run.
- *
- * The stable app stores each preference under its FULL `menubar.menu.*` key name
- * (the Swift MenuPreferences local-cache key), so the migration matches on the
- * full name. If a key is stored under a different name, it simply is not matched
- * and the migration stays a safe no-op for it. The read uses `defaults export
- * <domain> -` piped through `plutil` (NOT `defaults read <domain> -json`, which
- * treats `-json` as a key and errors).
- */
 import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { assertValidValue, configKeySpec, getConfigValue, setConfigValue } from '../device-config.js';
 import { getRuntimeStateDir } from '../state.js';
 import { MENUBAR_MENU_PROPERTIES } from '../config-keys.js';
-/** The production menu-bar UserDefaults domain (NOT the `.dev` bundle). */
 const USER_DEFAULTS_DOMAIN = 'com.phnx-labs.agents-menubar';
-/** Sentinel marking the one-shot done; its presence blocks every later run. */
 function sentinelPath() {
     return path.join(getRuntimeStateDir(), 'menubar-prefs-migrated');
 }
-/**
- * Pure plan step: which UserDefaults entries should be imported. The stable app
- * stores each preference under its FULL `menubar.menu.*` key name (the Swift
- * MenuPreferences local-cache key), so we match on the full name — only known
- * keys that are present in `userDefaults` AND currently unset in config
- * (`isUnset`) are imported, so an already-set value is preserved. Values are
- * returned raw; the caller coerces + validates them against each key's spec.
- */
 export function planMenubarPrefMigration(userDefaults, isUnset) {
     const plan = [];
     for (const prop of MENUBAR_MENU_PROPERTIES) {
@@ -57,13 +20,6 @@ export function planMenubarPrefMigration(userDefaults, isUnset) {
     }
     return plan;
 }
-/**
- * Coerce a raw UserDefaults value to the type its config key expects. The
- * `plutil` scalar output is text, but a bool can arrive as
- * 0/1 or "true"/"false" and an int as a numeric string, so normalize before
- * validation. Returns undefined for a value that cannot be coerced (skipped,
- * never forced).
- */
 export function coerceMenubarPrefValue(name, raw) {
     const type = configKeySpec(name).type;
     if (type === 'bool') {
@@ -84,19 +40,6 @@ export function coerceMenubarPrefValue(name, raw) {
     }
     return typeof raw === 'string' ? raw : undefined;
 }
-/**
- * Read known scalar preferences from the production domain.
- *
- * `defaults read <domain> -json` does NOT exist — `defaults read` treats `-json`
- * as a KEY name and errors. The correct read is `defaults export <domain> -`,
- * which writes the domain's plist to stdout (an EMPTY plist, exit 0, when the
- * domain is absent — a legitimate "nothing to migrate"), read one known scalar key at a time with `plutil -extract … raw`. Other
- * defaults may contain dates or data that cannot be represented as JSON.
- *
- * Returns `{ ok }` so the caller can tell a genuine read/convert FAILURE (do not
- * write the sentinel — retry next run) from an ABSENT domain (ok, empty values —
- * mark done). A failure never fabricates an empty map.
- */
 function readUserDefaultsDomain() {
     try {
         const plist = execFileSync('defaults', ['export', USER_DEFAULTS_DOMAIN, '-'], {
@@ -112,22 +55,14 @@ function readUserDefaultsDomain() {
                 }).trimEnd();
             }
             catch {
-                // Missing or non-scalar legacy keys are outside the preference contract.
             }
         }
         return { ok: true, values };
     }
     catch {
-        // `defaults`/`plutil` missing, a non-zero exit, or malformed output — a real
-        // failure. Do NOT claim an empty domain; the caller must retry.
         return { ok: false, values: {} };
     }
 }
-/**
- * Run the one-shot migration. macOS only, gated by the sentinel, best-effort:
- * any failure is swallowed (a migration must never break the snapshot read that
- * calls it) and a failed read remains eligible for a later retry.
- */
 export function migrateMenubarPreferencesFromUserDefaults() {
     if (process.platform !== 'darwin')
         return;
@@ -135,9 +70,6 @@ export function migrateMenubarPreferencesFromUserDefaults() {
     if (fs.existsSync(sentinel))
         return;
     const { ok, values } = readUserDefaultsDomain();
-    // A genuine read/convert failure must NOT mark the migration done — retry on a
-    // later run rather than silently skipping the user's real settings forever. An
-    // ABSENT domain reads ok with empty values and legitimately marks done.
     if (!ok)
         return;
     try {
@@ -145,7 +77,7 @@ export function migrateMenubarPreferencesFromUserDefaults() {
         for (const { name, value } of plan) {
             const coerced = coerceMenubarPrefValue(name, value);
             if (coerced === undefined)
-                continue; // unrepresentable — skip, never force
+                continue;
             try {
                 assertValidValue(configKeySpec(name), coerced);
             }
@@ -163,6 +95,5 @@ export function migrateMenubarPreferencesFromUserDefaults() {
         fs.writeFileSync(sentinel, new Date().toISOString() + '\n');
     }
     catch {
-        /* if we cannot mark it, a later run retries — still safe (idempotent) */
     }
 }

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

@@ -1,101 +1,19 @@
-/**
- * Branded desktop notifications for daemon-originated events (RUSH-2030).
- *
- * The one place the daemon (overdue routines, heal, routine start/finish/output)
- * emits a native desktop notification. On macOS it routes through the installed
- * `MenubarHelper.app` companion — a one-shot `"AGI Menu" --notify` invocation —
- * so the notification is attributed to that bundle and carries the agents-cli
- * mark instead of the generic AppleScript icon. A banner carries two images: the
- * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
- * harness, that agent's avatar on the RIGHT (`agent`, rendered by
- * AgentAvatar.swift) — the same layout macOS gives a YouTube notification, app on
- * the left and the channel on the right. When the companion
- * app is not installed (menu bar disabled, a Linux package, a dev checkout), it
- * degrades to `osascript` so an overdue/heal notice is never silently lost — the
- * generic icon is the acceptable cost of preserving delivery, not a bug hidden by
- * a fallback. On Linux it uses `notify-send`; every other platform is a no-op.
- *
- * All delivery is best-effort and fully detached: a missing binary surfaces as an
- * async 'error' event (not a synchronous throw), so every spawn attaches an
- * 'error' listener — without it Node re-throws ENOENT as an uncaught exception and
- * takes the whole daemon down (the exact crash overdue.test.ts guards).
- */
 import { type ChildProcess } from 'child_process';
 export interface DesktopNotification {
-    /** Bold first line. */
     title: string;
-    /** Notification body text. */
     body: string;
-    /** Secondary line under the title (macOS only). */
     subtitle?: string;
-    /**
-     * Deep-link the companion app runs when the notification is clicked. Encoded
-     * as `<verb>:<arg>` — `open:/abs/path` opens a file (a run report or log) in the
-     * default app; `routines:list` opens the runs folder (~/.agents/.history/runs)
-     * in Finder. Best-effort and
-     * macOS-only (osascript / notify-send have no click target). See routine-notify.ts.
-     */
     action?: string;
-    /**
-     * Harness the notification is ABOUT (`claude`, `codex`, … — an `AgentId`).
-     * macOS draws two images on a banner: the sending bundle's app icon on the
-     * LEFT and `contentImage` on the RIGHT. The companion renders this id as the
-     * right-hand avatar (AgentAvatar.swift), so a banner reads "agents-cli, about
-     * Claude" the way a YouTube notification reads "YouTube, from this channel".
-     * Omit it when no single harness owns the event (a daemon heal, a fan-out
-     * across several agents) — the right slot then stays empty rather than
-     * 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[];
-/** AppleScript for the osascript degradation path. Exported for tests. */
 export declare function buildOsascriptNotifyArgs(n: DesktopNotification): string[];
-/**
- * Spawn one detached, best-effort notifier process with a bounded lifetime.
- *
- * The child is detached + unref'd so it never blocks the daemon, but — unlike a
- * pure fire-and-forget — it is supervised: a watchdog SIGKILLs it after
- * `timeoutMs` so a stalled notifier can never linger (the pile-up this fixes).
- * The common path (a sub-second post + self-exit) clears the watchdog on the
- * child's own 'exit', so the kill only ever fires for a genuinely hung child.
- *
- * `timeoutMs` is injectable so the bounded-lifetime behaviour is testable against
- * a real long-running child without a multi-second wait. Returns the child so a
- * caller/test can observe it; callers in this module ignore it.
- */
 export declare function spawnDetachedQuiet(command: string, args: string[], timeoutMs?: number): ChildProcess;
-/**
- * Fire a native desktop notification, branded via the "AGI Menu" companion on
- * macOS. Best-effort — any failure is swallowed so a notification hiccup never
- * blocks or crashes the daemon.
- */
 export declare function notifyDesktop(n: DesktopNotification): void;

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

@@ -1,38 +1,7 @@
-/**
- * Branded desktop notifications for daemon-originated events (RUSH-2030).
- *
- * The one place the daemon (overdue routines, heal, routine start/finish/output)
- * emits a native desktop notification. On macOS it routes through the installed
- * `MenubarHelper.app` companion — a one-shot `"AGI Menu" --notify` invocation —
- * so the notification is attributed to that bundle and carries the agents-cli
- * mark instead of the generic AppleScript icon. A banner carries two images: the
- * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
- * harness, that agent's avatar on the RIGHT (`agent`, rendered by
- * AgentAvatar.swift) — the same layout macOS gives a YouTube notification, app on
- * the left and the channel on the right. When the companion
- * app is not installed (menu bar disabled, a Linux package, a dev checkout), it
- * degrades to `osascript` so an overdue/heal notice is never silently lost — the
- * generic icon is the acceptable cost of preserving delivery, not a bug hidden by
- * a fallback. On Linux it uses `notify-send`; every other platform is a no-op.
- *
- * All delivery is best-effort and fully detached: a missing binary surfaces as an
- * async 'error' event (not a synchronous throw), so every spawn attaches an
- * 'error' listener — without it Node re-throws ENOENT as an uncaught exception and
- * takes the whole daemon down (the exact crash overdue.test.ts guards).
- */
 import { spawn } from 'child_process';
 import * as os from 'os';
 import { resolveInstalledMenubarExecutable } from './install-menubar.js';
-/**
- * Hard ceiling on a one-shot notifier's lifetime. A notifier posts and exits in
- * well under a second on the happy path; if delivery stalls (locked screen, a
- * WindowServer/XPC hiccup) a detached GUI helper can hang indefinitely and pile
- * up in the menu bar. This is above the Swift one-shot's own 0.6s flush + its 3s
- * self-terminate watchdog, so Node's kill is the last-resort guarantee that runs
- * only if the child never self-exits.
- */
 const NOTIFY_TIMEOUT_MS = 4000;
-/** Argv for the "AGI Menu" one-shot notify mode. Exported for tests. */
 export function buildMenubarNotifyArgs(n) {
     const args = ['--notify', '--title', n.title, '--body', n.body];
     if (n.subtitle)
@@ -47,14 +16,10 @@ export function buildMenubarNotifyArgs(n) {
         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. */
 export function buildOsascriptNotifyArgs(n) {
     const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
     let script = `display notification "${esc(n.body)}" with title "${esc(n.title)}"`;
@@ -62,70 +27,37 @@ export function buildOsascriptNotifyArgs(n) {
         script += ` subtitle "${esc(n.subtitle)}"`;
     return ['-e', script];
 }
-/**
- * Spawn one detached, best-effort notifier process with a bounded lifetime.
- *
- * The child is detached + unref'd so it never blocks the daemon, but — unlike a
- * pure fire-and-forget — it is supervised: a watchdog SIGKILLs it after
- * `timeoutMs` so a stalled notifier can never linger (the pile-up this fixes).
- * The common path (a sub-second post + self-exit) clears the watchdog on the
- * child's own 'exit', so the kill only ever fires for a genuinely hung child.
- *
- * `timeoutMs` is injectable so the bounded-lifetime behaviour is testable against
- * a real long-running child without a multi-second wait. Returns the child so a
- * caller/test can observe it; callers in this module ignore it.
- */
 export function spawnDetachedQuiet(command, args, timeoutMs = NOTIFY_TIMEOUT_MS) {
     const child = spawn(command, args, { detached: true, stdio: 'ignore' });
-    // Bound the lifetime: a stalled notifier is hard-killed after the timeout. The
-    // timer is unref'd so it never keeps a short-lived caller's event loop alive.
     const watchdog = setTimeout(() => {
         try {
             child.kill('SIGKILL');
         }
         catch {
-            /* already gone */
         }
     }, timeoutMs);
     watchdog.unref();
-    // A missing binary (headless box with no osascript/notify-send, or a helper
-    // that vanished) arrives as an async 'error' event — the process never started,
-    // so cancel the watchdog. Without a listener Node re-throws ENOENT as an
-    // uncaught exception and crashes the daemon; having one swallows it.
     child.on('error', () => clearTimeout(watchdog));
-    // Fast, self-driven exit (the common path) — cancel the watchdog.
     child.on('exit', () => clearTimeout(watchdog));
     child.unref();
     return child;
 }
-/**
- * Fire a native desktop notification, branded via the "AGI Menu" companion on
- * macOS. Best-effort — any failure is swallowed so a notification hiccup never
- * blocks or crashes the daemon.
- */
 export function notifyDesktop(n) {
     const platform = os.platform();
     try {
         if (platform === 'darwin') {
             const exec = resolveInstalledMenubarExecutable();
             if (exec) {
-                // Branded path: the notification is attributed to MenubarHelper.app
-                // ("AGI Menu" on disk), so it shows the agents-cli mark and its click
-                // action is handled by the running helper's UNUserNotificationCenter delegate.
                 spawnDetachedQuiet(exec, buildMenubarNotifyArgs(n));
                 return;
             }
-            // Companion app absent — degrade to osascript so delivery is preserved
-            // (generic icon; no click action). See the module header.
             spawnDetachedQuiet('osascript', buildOsascriptNotifyArgs(n));
             return;
         }
         if (platform === 'linux') {
             spawnDetachedQuiet('notify-send', [n.title, n.body]);
         }
-        // Other platforms: no native desktop notifier wired — no-op.
     }
     catch {
-        // Notification is best-effort; nothing to do.
     }
 }

package/dist/lib/menubar/resolve-version.d.ts

@@ -1,24 +1,3 @@
-/**
- * Which menu-bar helper build to install: the newest published release at or
- * above this CLI's floor.
- *
- * `helper-versions.ts` records a FLOOR (the build this CLI was tested against)
- * and promised that resolution "may pick a NEWER build; it must never pick an
- * older one". Until now nothing resolved upward: every install path downloaded
- * the floor, so a helper fix reached a machine only after a CLI release bumped
- * the floor and the user ran `agents menubar setup`. This module is the
- * missing half — discovery — and it is what makes the helper auto-update.
- *
- * Discovery reads the public release list of `phnx-labs/agi-cli` and keeps
- * only tags shaped `menubar/v<x.y.z>` that carry the helper asset AND its
- * sha256 sidecar (a half-uploaded release is not a candidate). The answer is
- * cached for a day under the CLI's cache dir so the sync startup path and the
- * daemon read a file, never the network; the floor stays the offline answer
- * whenever the network or the cache cannot do better. The verified download
- * (`downloadMenubarHelperApp`: sha256, codesign, Team, designated-requirement
- * pin, notarization) is unchanged — resolution only chooses the version.
- */
-/** One release as the resolver sees it — the subset of the GitHub shape it reads. */
 export interface ReleaseCandidate {
     tagName: string;
     assets: string[];
@@ -26,23 +5,11 @@ export interface ReleaseCandidate {
     prerelease?: boolean;
 }
 interface MenubarResolveCache {
-    /** Epoch ms of the release-list read this answer came from. */
     checkedAt: number;
-    /** The newest published helper version at that time (never below the floor then). */
     version: string;
 }
-/**
- * Pure: the newest candidate at or above `floor`, else the floor. A tag must be
- * exactly `menubar/v<x.y.z>` (no pre-release suffix), not a draft or
- * pre-release, and carry both the zip and its `.sha256`.
- */
 export declare function pickNewestMenubarVersion(candidates: ReleaseCandidate[], floor: string): string;
 export declare function readMenubarResolveCache(file: string): MenubarResolveCache | null;
-/**
- * The cached answer when it is usable offline: at or above the floor, of any
- * age. Sync and network-free — this is what the startup self-heal and the
- * status/doctor displays read.
- */
 export declare function cachedMenubarVersion(opts?: {
     floor?: string;
     cacheFile?: string;
@@ -55,14 +22,6 @@ type FetchLike = (input: string, init?: {
     status: number;
     json(): Promise<unknown>;
 }>;
-/**
- * The helper version to install now: the newest published build >= floor.
- *
- * Reads the day-old cache first; re-reads the release list when the cache is
- * missing, stale, or `force` is set; falls back to the cached answer, then the
- * floor, when the network cannot answer. Never throws, never returns a version
- * below the floor.
- */
 export declare function resolveMenubarVersion(opts?: {
     floor?: string;
     cacheFile?: string;

package/dist/lib/menubar/resolve-version.js

@@ -1,23 +1,3 @@
-/**
- * Which menu-bar helper build to install: the newest published release at or
- * above this CLI's floor.
- *
- * `helper-versions.ts` records a FLOOR (the build this CLI was tested against)
- * and promised that resolution "may pick a NEWER build; it must never pick an
- * older one". Until now nothing resolved upward: every install path downloaded
- * the floor, so a helper fix reached a machine only after a CLI release bumped
- * the floor and the user ran `agents menubar setup`. This module is the
- * missing half — discovery — and it is what makes the helper auto-update.
- *
- * Discovery reads the public release list of `phnx-labs/agi-cli` and keeps
- * only tags shaped `menubar/v<x.y.z>` that carry the helper asset AND its
- * sha256 sidecar (a half-uploaded release is not a candidate). The answer is
- * cached for a day under the CLI's cache dir so the sync startup path and the
- * daemon read a file, never the network; the floor stays the offline answer
- * whenever the network or the cache cannot do better. The verified download
- * (`downloadMenubarHelperApp`: sha256, codesign, Team, designated-requirement
- * pin, notarization) is unchanged — resolution only chooses the version.
- */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { getCacheDir } from '../state.js';
@@ -25,16 +5,9 @@ import { compareVersions } from '../agent-spec/primitives.js';
 import { helperFloor } from '../helper-versions.js';
 import { getCliVersion } from '../version.js';
 import { MENUBAR_HELPER_ASSET } from './download-menubar.js';
-/** The repo whose releases carry `menubar/v*` tags (same as the download URL). */
 const MENUBAR_RELEASES_API = 'https://api.github.com/repos/phnx-labs/agi-cli/releases?per_page=100';
-/** How long a resolved answer is trusted before the release list is re-read. */
 const MENUBAR_RESOLVE_TTL_MS = 24 * 60 * 60 * 1000;
 const TAG = /^menubar\/v(\d+\.\d+\.\d+)$/;
-/**
- * Pure: the newest candidate at or above `floor`, else the floor. A tag must be
- * exactly `menubar/v<x.y.z>` (no pre-release suffix), not a draft or
- * pre-release, and carry both the zip and its `.sha256`.
- */
 export function pickNewestMenubarVersion(candidates, floor) {
     let best = floor;
     for (const c of candidates) {
@@ -50,7 +23,6 @@ export function pickNewestMenubarVersion(candidates, floor) {
     }
     return best;
 }
-/** Where the resolved answer lives: beside the helper's own download cache. */
 function menubarResolveCachePath() {
     return path.join(getCacheDir(), 'menubar', 'latest.json');
 }
@@ -61,7 +33,7 @@ export function readMenubarResolveCache(file) {
             return { checkedAt: parsed.checkedAt, version: parsed.version };
         }
     }
-    catch { /* absent or unreadable: no cache */ }
+    catch { }
     return null;
 }
 function writeMenubarResolveCache(file, cache) {
@@ -71,19 +43,13 @@ function writeMenubarResolveCache(file, cache) {
         fs.writeFileSync(tmp, JSON.stringify(cache));
         fs.renameSync(tmp, file);
     }
-    catch { /* a cache that cannot be written is just a cache miss next time */ }
+    catch { }
 }
-/**
- * The cached answer when it is usable offline: at or above the floor, of any
- * age. Sync and network-free — this is what the startup self-heal and the
- * status/doctor displays read.
- */
 export function cachedMenubarVersion(opts = {}) {
     const floor = opts.floor ?? helperFloor('menubar');
     const cache = readMenubarResolveCache(opts.cacheFile ?? menubarResolveCachePath());
     return cache && compareVersions(cache.version, floor) >= 0 ? cache.version : floor;
 }
-/** Read the release list. Unauthenticated: release metadata is public and this runs at most once a day per machine. */
 async function fetchMenubarReleaseCandidates(fetchImpl = fetch) {
     const res = await fetchImpl(MENUBAR_RELEASES_API, {
         headers: {
@@ -105,14 +71,6 @@ async function fetchMenubarReleaseCandidates(fetchImpl = fetch) {
         assets: (r.assets ?? []).map((a) => a.name ?? ''),
     }));
 }
-/**
- * The helper version to install now: the newest published build >= floor.
- *
- * Reads the day-old cache first; re-reads the release list when the cache is
- * missing, stale, or `force` is set; falls back to the cached answer, then the
- * floor, when the network cannot answer. Never throws, never returns a version
- * below the floor.
- */
 export async function resolveMenubarVersion(opts = {}) {
     const floor = opts.floor ?? helperFloor('menubar');
     const file = opts.cacheFile ?? menubarResolveCachePath();