@phnx-labs/agents-cli 1.20.74 → 1.20.77

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

@@ -0,0 +1,44 @@
+/**
+ * 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 `MenubarHelper --notify` invocation —
+ * so the notification is attributed to that bundle and carries the agents-cli /
+ * Agentialized mark instead of the generic AppleScript icon. 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).
+ */
+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;
+}
+/** Argv for the MenubarHelper 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[];
+/**
+ * Fire a native desktop notification, branded via the MenubarHelper 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

@@ -0,0 +1,78 @@
+/**
+ * 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 `MenubarHelper --notify` invocation —
+ * so the notification is attributed to that bundle and carries the agents-cli /
+ * Agentialized mark instead of the generic AppleScript icon. 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';
+/** Argv for the MenubarHelper one-shot notify mode. Exported for tests. */
+export function buildMenubarNotifyArgs(n) {
+    const args = ['--notify', '--title', n.title, '--body', n.body];
+    if (n.subtitle)
+        args.push('--subtitle', n.subtitle);
+    if (n.action)
+        args.push('--action', n.action);
+    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)}"`;
+    if (n.subtitle)
+        script += ` subtitle "${esc(n.subtitle)}"`;
+    return ['-e', script];
+}
+/** Spawn one detached, best-effort notifier process; swallow async ENOENT. */
+function spawnDetachedQuiet(command, args) {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    // A missing binary (headless box with no osascript/notify-send, or a helper
+    // that vanished) arrives as an async 'error' event. Without this listener Node
+    // re-throws it as an uncaught exception and crashes the daemon — swallow it.
+    child.on('error', () => { });
+    child.unref();
+}
+/**
+ * Fire a native desktop notification, branded via the MenubarHelper 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, 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/migrate.d.ts

@@ -117,5 +117,21 @@ export declare function migrateExtrasExtrasToAgentsExtras(historyDir?: string):
  * Params default to the real routines dir; injectable for tests.
  */
 export declare function migrateRoutineDeviceToDevices(routinesDir?: string): void;
+/**
+ * Fold the legacy watchdog enable sentinel into the watchdog routine.
+ *
+ * The always-on watchdog used to be gated by a presence sentinel at
+ * `<runtime-state>/watchdog/enabled`; it is now a daemon routine. A user who had
+ * run `agents watchdog enable` under the old build has that file on disk — without
+ * this, upgrading would silently drop them back to OFF (the always-on nudge just
+ * stops), the worst failure mode for a "survives reboots" feature. If the sentinel
+ * exists, ensure the `watchdog` routine exists AND is enabled, then delete the
+ * sentinel so this runs exactly once. If ensuring the routine fails, the sentinel
+ * is left in place so a later run retries rather than silently losing the opt-in.
+ *
+ * Both seams are injectable so the migration is unit-testable without touching the
+ * real routines dir (and without racing the routine module's own tests).
+ */
+export declare function migrateWatchdogSentinelToRoutine(sentinelPath?: string, ensure?: (enabled: boolean) => void): void;
 /** Run all idempotent migrations. Safe to call multiple times. */
 export declare function runMigration(): Promise<void>;

package/dist/lib/migrate.js

@@ -13,6 +13,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { machineId } from './machine-id.js';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 import { createLink } from './platform/index.js';
+import { ensureWatchdogRoutine } from './watchdog/routine.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -1981,6 +1982,37 @@ export function migrateRoutineDeviceToDevices(routinesDir) {
         console.error(`Migrated ${migrated} routine${migrated === 1 ? '' : 's'}: device → devices`);
     }
 }
+/**
+ * Fold the legacy watchdog enable sentinel into the watchdog routine.
+ *
+ * The always-on watchdog used to be gated by a presence sentinel at
+ * `<runtime-state>/watchdog/enabled`; it is now a daemon routine. A user who had
+ * run `agents watchdog enable` under the old build has that file on disk — without
+ * this, upgrading would silently drop them back to OFF (the always-on nudge just
+ * stops), the worst failure mode for a "survives reboots" feature. If the sentinel
+ * exists, ensure the `watchdog` routine exists AND is enabled, then delete the
+ * sentinel so this runs exactly once. If ensuring the routine fails, the sentinel
+ * is left in place so a later run retries rather than silently losing the opt-in.
+ *
+ * Both seams are injectable so the migration is unit-testable without touching the
+ * real routines dir (and without racing the routine module's own tests).
+ */
+export function migrateWatchdogSentinelToRoutine(sentinelPath = path.join(CACHE_DIR, 'state', 'watchdog', 'enabled'), ensure = ensureWatchdogRoutine) {
+    if (!fs.existsSync(sentinelPath))
+        return;
+    try {
+        ensure(true);
+    }
+    catch (err) {
+        console.error(`watchdog sentinel migration: could not create the routine (${err.message}); leaving the sentinel for a later retry`);
+        return;
+    }
+    try {
+        fs.rmSync(sentinelPath);
+    }
+    catch { /* already gone */ }
+    console.error('Migrated watchdog: legacy enable sentinel → watchdog routine (kept enabled)');
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
@@ -2039,6 +2071,10 @@ export async function runMigration() {
     migrateExtrasExtrasToAgentsExtras();
     // Rewrite routine YAML files: singular `device:` -> plural `devices: []`.
     migrateRoutineDeviceToDevices();
+    // Fold the legacy watchdog enable sentinel into the watchdog routine so a user
+    // who opted in under the old build stays opted in after upgrading. After the
+    // routine rewrites above so the routines dir is in its canonical shape.
+    migrateWatchdogSentinelToRoutine();
     // Symlink repair runs LAST so it can find the post-move version homes.
     repairAgentConfigSymlinks();
     // Repair self-referential node_modules/.bin/<cli> symlinks (the droid

package/dist/lib/models.d.ts

@@ -96,6 +96,33 @@ export declare function resolveModel(agent: AgentId, version: string, requested:
  * like `${agent}-default`.
  */
 export declare function resolveEffectiveModel(agent: AgentId, version: string, requested?: string): string | null;
+/** Where the model a given agent+version will actually run with came from. */
+export type ConfiguredModelSource = 'run-default' | 'config' | 'cli-default';
+export interface ConfiguredModel {
+    /** The model id the agent will run with (e.g. `opus`, `gpt-5-codex`). */
+    model: string;
+    source: ConfiguredModelSource;
+}
+/**
+ * The model a given agent+version is actually configured to use right now, with
+ * where that selection comes from. First hit wins:
+ *   1. run-default — the user's agents-cli `run.defaults` in agents.yaml
+ *   2. config      — the agent's OWN native settings.json `model` field
+ *   3. cli-default — the CLI's built-in default: the catalog's `isDefault` model
+ *                    if one is flagged (e.g. Kimi), otherwise the literal
+ *                    `default` for a model-capable agent whose runtime picks its
+ *                    own default (Claude/Codex don't flag one — Claude's own UI
+ *                    calls this "Default").
+ * Each layer is a real source the agent consults; `version` must be concrete.
+ * Returns null only when the agent exposes no model catalog at all.
+ */
+export declare function resolveConfiguredModel(agent: AgentId, version: string): ConfiguredModel | null;
+/**
+ * Join the identity cluster — `agent@version · model · account` — with a dim
+ * separator, dropping empty pieces. Pieces are pre-colored by the caller so the
+ * same cluster reads identically across `view`, `use`, `add`, and `status`.
+ */
+export declare function formatAgentIdentity(...parts: Array<string | null | undefined>): string;
 /**
  * Build the per-agent CLI flags for a unified reasoning effort knob.
  *

package/dist/lib/models.js

@@ -10,8 +10,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { getVersionDir } from './versions.js';
+import chalk from 'chalk';
+import { getVersionDir, getVersionHomePath } from './versions.js';
 import { getModelsCachePath } from './state.js';
+import { agentConfigDirName } from './agents.js';
+import { resolveRunDefaults } from './run-defaults.js';
 const CACHE_PATH = getModelsCachePath();
 /**
  * Bump when the extractor logic changes shape in an incompatible way so cached
@@ -864,6 +867,56 @@ export function resolveEffectiveModel(agent, version, requested) {
     const def = catalog.models.find((m) => m.isDefault);
     return def?.id ?? null;
 }
+/**
+ * The model a given agent+version is actually configured to use right now, with
+ * where that selection comes from. First hit wins:
+ *   1. run-default — the user's agents-cli `run.defaults` in agents.yaml
+ *   2. config      — the agent's OWN native settings.json `model` field
+ *   3. cli-default — the CLI's built-in default: the catalog's `isDefault` model
+ *                    if one is flagged (e.g. Kimi), otherwise the literal
+ *                    `default` for a model-capable agent whose runtime picks its
+ *                    own default (Claude/Codex don't flag one — Claude's own UI
+ *                    calls this "Default").
+ * Each layer is a real source the agent consults; `version` must be concrete.
+ * Returns null only when the agent exposes no model catalog at all.
+ */
+export function resolveConfiguredModel(agent, version) {
+    const runModel = resolveRunDefaults(agent, version).model;
+    if (runModel && runModel.trim() !== '')
+        return { model: runModel, source: 'run-default' };
+    const nativeModel = readNativeConfigModel(agent, version);
+    if (nativeModel)
+        return { model: nativeModel, source: 'config' };
+    const catalog = getModelCatalog(agent, version);
+    if (catalog) {
+        const flagged = catalog.models.find((m) => m.isDefault);
+        return { model: flagged?.id ?? 'default', source: 'cli-default' };
+    }
+    return null;
+}
+/**
+ * Best-effort read of the agent's own `model` from its native settings.json
+ * (e.g. `~/.agents/.history/versions/claude/<ver>/home/.claude/settings.json`).
+ * A missing/malformed file is a fall-through, not an error.
+ */
+function readNativeConfigModel(agent, version) {
+    try {
+        const settingsPath = path.join(getVersionHomePath(agent, version), agentConfigDirName(agent), 'settings.json');
+        const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        return typeof parsed.model === 'string' && parsed.model.trim() !== '' ? parsed.model : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Join the identity cluster — `agent@version · model · account` — with a dim
+ * separator, dropping empty pieces. Pieces are pre-colored by the caller so the
+ * same cluster reads identically across `view`, `use`, `add`, and `status`.
+ */
+export function formatAgentIdentity(...parts) {
+    return parts.filter((p) => !!p && p.length > 0).join(` ${chalk.gray('·')} `);
+}
 /** Find the closest matching model ids/aliases using edit distance. */
 function pickSuggestions(requested, catalog) {
     const all = [...catalog.models.map((m) => m.id), ...Object.keys(catalog.aliases)];

package/dist/lib/overdue.d.ts

@@ -21,6 +21,10 @@ export interface OverdueJob {
 /** Return every enabled, recurring job whose most recent expected fire was
  *  missed. One-shot jobs are excluded — they fire at most once. */
 export declare function detectOverdueJobs(now?: Date): OverdueJob[];
-/** Fire a native desktop notification listing the overdue jobs. Best-effort —
- *  failures (missing `osascript`/`notify-send`, no display) are swallowed. */
+/**
+ * Fire a branded desktop notification listing the overdue jobs. Routed through
+ * the MenubarHelper companion (notify-desktop.ts) so it carries the agents-cli
+ * mark; clicking opens the runs folder (~/.agents/.history/runs). Best-effort —
+ * a missing notifier or absent display is swallowed and never crashes the daemon.
+ */
 export declare function notifyOverdue(jobs: OverdueJob[]): void;

package/dist/lib/overdue.js

@@ -12,9 +12,8 @@
  * `agents routines catchup` command that runs them on demand.
  */
 import { Cron } from 'croner';
-import * as os from 'os';
-import { spawn } from 'child_process';
 import { listJobs, getLatestRun, jobRunsOnThisDevice } from './routines.js';
+import { notifyDesktop } from './menubar/notify-desktop.js';
 // Tolerance between "expected fire" and "recorded run start" — accounts for
 // the small gap between the cron tick and when the runner writes meta.json.
 const GRACE_MS = 60_000;
@@ -76,44 +75,19 @@ export function detectOverdueJobs(now = new Date()) {
     }
     return overdue;
 }
-/** Fire a native desktop notification listing the overdue jobs. Best-effort —
- *  failures (missing `osascript`/`notify-send`, no display) are swallowed. */
+/**
+ * Fire a branded desktop notification listing the overdue jobs. Routed through
+ * the MenubarHelper companion (notify-desktop.ts) so it carries the agents-cli
+ * mark; clicking opens the runs folder (~/.agents/.history/runs). Best-effort —
+ * a missing notifier or absent display is swallowed and never crashes the daemon.
+ */
 export function notifyOverdue(jobs) {
     if (jobs.length === 0)
         return;
-    const title = jobs.length === 1
-        ? `Routine overdue: ${jobs[0].name}`
-        : `${jobs.length} routines overdue`;
+    const title = jobs.length === 1 ? 'Routine overdue' : `${jobs.length} routines overdue`;
+    const subtitle = jobs.length === 1 ? jobs[0].name : undefined;
     const body = jobs.length === 1
         ? `Missed ${jobs[0].expectedAt.toLocaleString()}. Run: agents routines catchup`
         : `${jobs.map((j) => j.name).join(', ')} — agents routines catchup`;
-    const platform = os.platform();
-    try {
-        if (platform === 'darwin') {
-            const safeTitle = title.replace(/"/g, '\\"');
-            const safeBody = body.replace(/"/g, '\\"');
-            const child = spawn('osascript', ['-e', `display notification "${safeBody}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
-            // A missing binary surfaces as an async 'error' event, NOT a synchronous
-            // throw the try/catch would catch. Without a listener Node re-throws it as
-            // an uncaught exception and takes the whole daemon down. Swallow it — the
-            // notification is best-effort.
-            child.on('error', () => { });
-            child.unref();
-        }
-        else if (platform === 'linux') {
-            const child = spawn('notify-send', [title, body], {
-                detached: true,
-                stdio: 'ignore',
-            });
-            // Headless Linux boxes have no `notify-send` (libnotify-bin); its ENOENT
-            // arrives as an async 'error' event, not a throw. Without this listener
-            // the daemon crashes on every overdue routine and systemd restart-loops it
-            // (which also tears down the browser IPC socket). Swallow — best-effort.
-            child.on('error', () => { });
-            child.unref();
-        }
-    }
-    catch {
-        // Notification is best-effort; nothing to do.
-    }
+    notifyDesktop({ title, subtitle, body, action: 'routines:list' });
 }

package/dist/lib/picker.js

@@ -343,7 +343,10 @@ export function dynamicPicker(config) {
         const [loading, setLoading] = useState(true);
         const [query, setQuery] = useState('');
         const [mode, setMode] = useState('nav');
-        const [previewOpen, setPreviewOpen] = useState(false);
+        // Default the preview pane open when the caller supplies a preview builder —
+        // matches the static `itemPicker`, so the session browser shows a live preview
+        // as you arrow through rows instead of hiding it behind `tab`.
+        const [previewOpen, setPreviewOpen] = useState(Boolean(cfg.buildPreview));
         const [active, setActive] = useState(0);
         const [flash, setFlash] = useState('');
         const prefix = usePrefix({ status, theme });

package/dist/lib/platform/process.d.ts

@@ -49,3 +49,20 @@ export declare function backgroundSpawnOptions(opts?: {
  * throw from `process.kill(pid, 0)` as "not running".
  */
 export declare function isAlive(pid: number): boolean;
+/**
+ * A stable identifier for the process at `pid` as of when it started, or null if
+ * unknowable. Used to defeat PID reuse: acting on a pid is only safe when the
+ * process still occupies the slot we observed earlier. The value is only ever
+ * compared for equality against an earlier capture of the SAME pid, so the format
+ * need only be stable, not parseable.
+ *
+ * Linux:   field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
+ * macOS:   `ps -o lstart= -p <pid>`.
+ * Windows: CreationDate from Win32_Process, as a culture-independent FILETIME.
+ *
+ * This is the single source of truth. `pty-server.ts` and `teams/agents.ts` each
+ * carried their own copy; the Windows branch was missing from both, so every
+ * caller there silently ran with NO pid-reuse protection — including
+ * `agents teams stop`, which is how it could SIGKILL an unrelated process group.
+ */
+export declare function captureProcessStartTime(pid: number): string | null;

package/dist/lib/platform/process.js

@@ -2,6 +2,7 @@
  * Process liveness / control, platform-aware.
  */
 import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
 /**
  * Forcefully terminate a process AND its descendant tree.
  *
@@ -80,3 +81,72 @@ export function isAlive(pid) {
         return false;
     }
 }
+/** Memoized per pid: a process's start time cannot change while it lives, and a
+ *  recycled pid is precisely what the caller is trying to detect — so a stale
+ *  hit still compares unequal against the recorded value. Bounded by the pids a
+ *  single CLI invocation asks about. */
+const startTimeByPid = new Map();
+/**
+ * A stable identifier for the process at `pid` as of when it started, or null if
+ * unknowable. Used to defeat PID reuse: acting on a pid is only safe when the
+ * process still occupies the slot we observed earlier. The value is only ever
+ * compared for equality against an earlier capture of the SAME pid, so the format
+ * need only be stable, not parseable.
+ *
+ * Linux:   field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
+ * macOS:   `ps -o lstart= -p <pid>`.
+ * Windows: CreationDate from Win32_Process, as a culture-independent FILETIME.
+ *
+ * This is the single source of truth. `pty-server.ts` and `teams/agents.ts` each
+ * carried their own copy; the Windows branch was missing from both, so every
+ * caller there silently ran with NO pid-reuse protection — including
+ * `agents teams stop`, which is how it could SIGKILL an unrelated process group.
+ */
+export function captureProcessStartTime(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    const cached = startTimeByPid.get(pid);
+    if (cached !== undefined)
+        return cached;
+    const value = readProcessStartTime(pid);
+    startTimeByPid.set(pid, value);
+    return value;
+}
+function readProcessStartTime(pid) {
+    try {
+        if (process.platform === 'win32') {
+            // ToFileTimeUtc() rather than the raw DateTime: the default string form is
+            // rendered in the current culture, so a persisted fingerprint would stop
+            // comparing equal across a locale change.
+            const out = execFileSync('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CreationDate.ToFileTimeUtc()`,
+            ], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true, timeout: 5000 });
+            const trimmed = out.trim();
+            return trimmed.length > 0 ? trimmed : null;
+        }
+        if (process.platform === 'linux') {
+            const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+            // The comm field (#2) is parenthesized and may contain spaces, so split
+            // off everything after the last ')' to get a clean field list.
+            const lastParen = stat.lastIndexOf(')');
+            if (lastParen < 0)
+                return null;
+            const fields = stat.slice(lastParen + 2).split(' ');
+            // After comm we are at field 3; starttime is field 22, so index 19 here.
+            return fields[19] || null;
+        }
+        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        });
+        const trimmed = out.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/profiles-presets.js

@@ -4,7 +4,9 @@
  * Each preset bundles a host CLI, API base URL, default model, and provider
  * name so users can `agents profiles add kimi` without manual configuration.
  */
-// Model IDs verified against openrouter.ai/api/v1/models on 2026-04-20.
+// Model IDs verified against openrouter.ai/api/v1/models on 2026-07-31
+// (spark presets corrected from the never-served meta/claude-spark-1.1 to the
+// live meta/muse-spark-1.1, confirmed on both OpenRouter and OpenCode id:meta).
 // Presets target the top-ranked open-source model per provider based on
 // SWE-bench Verified, LiveCodeBench, HumanEval, and Chatbot Arena rankings.
 //
@@ -100,18 +102,18 @@ export const PRESETS = [
     },
     {
         name: 'claude-spark',
-        description: 'Meta Claude Spark 1.1 via OpenRouter inside Claude Code (open alternative). Model: meta/claude-spark-1.1 — free via opencode, now usable in Claude Code UI. HEADLESS-SAFE. For open-claude spark usage.',
+        description: 'Meta Muse Spark 1.1 via OpenRouter inside Claude Code (open alternative). Model: meta/muse-spark-1.1 — now usable in the Claude Code UI. HEADLESS-SAFE. For open-claude spark usage.',
         ...OPENROUTER_AUTH,
         env: {
             ANTHROPIC_BASE_URL: OPENROUTER_BASE,
-            ANTHROPIC_MODEL: 'meta/claude-spark-1.1',
-            ANTHROPIC_SMALL_FAST_MODEL: 'meta/claude-spark-1.1',
+            ANTHROPIC_MODEL: 'meta/muse-spark-1.1',
+            ANTHROPIC_SMALL_FAST_MODEL: 'meta/muse-spark-1.1',
         },
     },
     // ----- OpenCode CLI (open-claude harness) -----
     {
         name: 'opencode',
-        description: 'OpenCode default — uses your configured model via opencode auth. Run `opencode auth` to login, then `agents run opencode --model meta/claude-spark-1.1 "prompt"` for spark usage.',
+        description: 'OpenCode default — uses your configured model via opencode auth. Run `opencode auth` to login, then `agents run opencode --model meta/muse-spark-1.1 "prompt"` for spark usage.',
         provider: 'opencode',
         host: 'opencode',
         authEnvVar: 'OPENCODE_API_KEY',
@@ -120,13 +122,13 @@ export const PRESETS = [
     },
     {
         name: 'opencode-spark',
-        description: 'Meta Claude Spark 1.1 via OpenCode (free, headless-safe). Pinned to meta/claude-spark-1.1 — best for open-claude usage with opencode harness.',
+        description: 'Meta Muse Spark 1.1 via OpenCode (free, headless-safe). Pinned to meta/muse-spark-1.1 — best for open-claude usage with opencode harness.',
         provider: 'opencode',
         host: 'opencode',
         authEnvVar: 'OPENCODE_API_KEY',
         authOptional: true,
         env: {
-            OPENCODE_MODEL: 'meta/claude-spark-1.1',
+            OPENCODE_MODEL: 'meta/muse-spark-1.1',
         },
     },
     {

package/dist/lib/profiles.d.ts

@@ -19,6 +19,13 @@ export interface Profile {
         envVar: string;
         keychainItem: string;
     };
+    /**
+     * When true, the host manages its own login and the keychain token named by
+     * `auth` is optional: if it is not stored, no auth env var is injected and the
+     * run proceeds on the host's own credentials (e.g. `opencode auth`). Without
+     * this flag a missing keychain item is a hard error at exec time.
+     */
+    authOptional?: boolean;
     description?: string;
     preset?: string;
     provider?: string;
@@ -92,6 +99,30 @@ export declare function profileSummary(profile: Profile): ProfileSummary;
  * for the OpenRouter key exactly once.
  */
 export declare function profileFromPreset(profileName: string, preset: Preset, version?: string): Profile;
+/** Return the model-override env var for a host (known hosts mapped; else `<HOST>_MODEL`). */
+export declare function modelEnvKeyForHost(host: AgentId): string;
+/** Return the base-URL env var for a host, or null when the host has no known override var. */
+export declare function baseUrlEnvKeyForHost(host: AgentId): string | null;
+/** Return the auth-token env var for a host, or null when unknown. */
+export declare function authEnvKeyForHost(host: AgentId): string | null;
+/** Options for {@link profileFromHostModel}. */
+export interface HostModelOptions {
+    version?: string;
+    /** Base URL for OpenAI/Anthropic-compatible hosts (claude, codex). Ignored for hosts without a known var. */
+    baseUrl?: string;
+    /** Provider label + keychain namespace; only needed when the host requires a token. */
+    provider?: string;
+    /** Env var the host reads its auth token from; pair with `provider` to attach keychain auth. */
+    authEnvVar?: string;
+    description?: string;
+}
+/**
+ * Build a custom-harness profile from a host CLI + model in one shot, without a
+ * preset. The model lands on the host's model env var ({@link modelEnvKeyForHost});
+ * auth is attached only when both `provider` and `authEnvVar` are supplied
+ * (hosts that manage their own login — e.g. opencode — need neither).
+ */
+export declare function profileFromHostModel(name: string, host: AgentId, model: string, opts?: HostModelOptions): Profile;
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the