@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/import.js

@@ -20,9 +20,9 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { AGENTS } from './agents.js';
-import { getVersionsDir } from './state.js';
+import { getUserAgentsDir, getVersionsDir } from './state.js';
 import { setGlobalDefault } from './versions.js';
-import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks } from './shims.js';
+import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks, assertIsolationBoundary } from './shims.js';
 const IMPORT_VERSION_RE = /^(?:latest|[A-Za-z0-9._+-]{1,64})$/;
 export function isValidImportVersion(version) {
     return IMPORT_VERSION_RE.test(version);
@@ -39,6 +39,12 @@ export async function importAgentConfig(agentId, version) {
     if (!isValidImportVersion(version)) {
         return { success: false, error: `Invalid version: ${JSON.stringify(version)}` };
     }
+    // Adoption, done inline rather than via switchConfigSymlink — so it needs the gate
+    // directly. commands/import.ts checks at its entry point too (it must: it registers
+    // a normal version first, which would un-protect the agent before this runs), but
+    // an exported function that moves the user's real config must not depend on every
+    // future caller remembering.
+    assertIsolationBoundary(agentId, 'adopt your existing install');
     const agent = AGENTS[agentId];
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
@@ -237,3 +243,102 @@ export function resolvePackageDirFromBinary(binaryPath) {
         return null;
     }
 }
+/**
+ * Seed an ISOLATED version's home from the user's real `~/.<agent>` — the mirror of
+ * {@link importAgentConfig}, which adopts.
+ *
+ * The difference is the whole point: this COPIES and leaves the original in place,
+ * never symlinks it, never sets a default, never creates a shim. So an isolated copy
+ * can start from the setup the user already has instead of from nothing, which was
+ * the only way to get a working sandbox before.
+ *
+ * Credentials are skipped by default and reported, not silently included. An isolated
+ * copy is a separate principal — `agents add --isolated` already tells the user to
+ * sign in on first run — and copying tokens into it should be a choice, not a side
+ * effect of wanting your settings. `--with-auth` opts in.
+ */
+export function seedIsolatedConfigFromLocal(agentId, version, opts = {}) {
+    const agent = AGENTS[agentId];
+    const configDir = agent.configDir;
+    const versionHome = path.join(getVersionsDir(), agentId, version, 'home');
+    // Mirror importAgentConfig's derivation so nested config dirs (e.g. Antigravity's
+    // ~/.gemini/antigravity-cli) land where the shim expects them.
+    let dest = path.join(versionHome, path.relative(os.homedir(), configDir));
+    // Codex uses a SUN_LEN-safe CODEX_HOME: `home/.codex` is a SYMLINK to
+    // `~/.agents/.codex-homes/<version>/.codex`, because the real path is too long for a
+    // unix socket. cpSync cannot overwrite a symlink with a directory (it fails with
+    // "Cannot overwrite non-directory"), and writing beside it would put settings
+    // somewhere the agent never reads. Follow the link and seed the actual home.
+    try {
+        if (fs.lstatSync(dest).isSymbolicLink())
+            dest = fs.realpathSync(dest);
+    }
+    catch {
+        /* not created yet — the plain path is correct */
+    }
+    const result = { seeded: false, from: configDir, to: dest, skippedAuth: [], skippedRuntime: [] };
+    if (!fs.existsSync(configDir))
+        return result;
+    // Known credential paths, relative to the config dir. `authFiles` covers the agents
+    // that declare them for cross-version carry; the rest are verified filenames for
+    // agents that do not declare any (codex `auth.json`, claude `.credentials.json`).
+    // Runtime state, not settings. Seeding a sandbox with the user's session history,
+    // logs and caches duplicated 757MB on a real machine — 349MB of `sessions` alone —
+    // for a copy that wants config. These are regenerated by the agent as it runs, and
+    // an isolated copy keeps its own; carrying them over also drags conversation history
+    // into a sandbox the user may have created precisely to keep separate.
+    const RUNTIME_PREFIXES = ['sessions', 'log', 'logs', 'cache', '.tmp', 'tmp', 'generated_images'];
+    const RUNTIME_FILES = ['history.jsonl', 'session_index.jsonl'];
+    const isRuntime = (rel) => !opts.all && (RUNTIME_FILES.includes(rel) ||
+        /\.sqlite(-shm|-wal)?$/.test(rel) ||
+        RUNTIME_PREFIXES.some((d) => rel === d || rel.startsWith(d + path.sep)));
+    const authRel = new Set([
+        ...(agent.authFiles ?? []),
+        'auth.json',
+        '.credentials.json',
+        'credentials.json',
+    ]);
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        const agentsDir = getUserAgentsDir();
+        const inside = agentsDir + path.sep;
+        fs.cpSync(configDir, dest, {
+            recursive: true,
+            // `force: true` is Node's default, but Bun drops it when a `filter` is supplied —
+            // existing files are then silently left alone. `dist/bin/agents` is bun-compiled,
+            // so this is a production path, not just a test artifact. State it explicitly.
+            force: true,
+            filter: (src) => {
+                const rel = path.relative(configDir, src);
+                if (!opts.withAuth && rel && (authRel.has(rel) || rel.startsWith('credentials' + path.sep))) {
+                    result.skippedAuth.push(rel);
+                    return false;
+                }
+                if (rel && isRuntime(rel)) {
+                    // Record only the top-level name so the report stays one line per item.
+                    const top = rel.split(path.sep)[0];
+                    if (!result.skippedRuntime.includes(top))
+                        result.skippedRuntime.push(top);
+                    return false;
+                }
+                // Same rule as the export path: a link into ~/.agents would dangle for a copy
+                // that is supposed to stand on its own.
+                try {
+                    const st = fs.lstatSync(src);
+                    if (st.isSymbolicLink()) {
+                        const tgt = path.resolve(path.dirname(src), fs.readlinkSync(src));
+                        if (tgt === agentsDir || tgt.startsWith(inside))
+                            return false;
+                    }
+                }
+                catch { /* let cpSync surface unreadable entries */ }
+                return true;
+            },
+        });
+        result.seeded = true;
+    }
+    catch (err) {
+        return { ...result, error: err.message };
+    }
+    return result;
+}

package/dist/lib/isolation-boundary-report.d.ts

@@ -0,0 +1,10 @@
+import { IsolationBoundaryError } from './shims.js';
+/**
+ * Turn an {@link IsolationBoundaryError} into guidance. The boundary is enforced by a
+ * throw so it cannot be forgotten; this is what keeps that from surfacing as a stack
+ * trace. The remedy is always the same shape, because the protection is derived from
+ * the isolated copies themselves: drop them and the agent is ordinary again.
+ */
+export declare function explainIsolationBoundary(err: IsolationBoundaryError): void;
+/** Run `fn`, converting a boundary refusal into guidance + a non-zero exit. */
+export declare function withIsolationBoundary<T>(fn: () => Promise<T> | T): Promise<T | undefined>;

package/dist/lib/isolation-boundary-report.js

@@ -0,0 +1,35 @@
+import chalk from 'chalk';
+import { IsolationBoundaryError } from './shims.js';
+import { listInstalledVersions } from './versions.js';
+/**
+ * Turn an {@link IsolationBoundaryError} into guidance. The boundary is enforced by a
+ * throw so it cannot be forgotten; this is what keeps that from surfacing as a stack
+ * trace. The remedy is always the same shape, because the protection is derived from
+ * the isolated copies themselves: drop them and the agent is ordinary again.
+ */
+export function explainIsolationBoundary(err) {
+    const versions = listInstalledVersions(err.agent);
+    console.error(chalk.red(`\n${err.agent} is installed only as isolated copies.`));
+    console.error(chalk.gray(`  Refused: ${err.operation} — that is exactly what --isolated promises not to do.`));
+    console.error(chalk.gray('\n  To keep the sandbox and act inside it:'));
+    console.error(chalk.gray(`    agents add ${err.agent}@<version> --isolated    # another isolated copy`));
+    console.error(chalk.gray(`    agents use ${err.agent}@<version>               # pick which one 'agents run ${err.agent}' uses`));
+    console.error(chalk.gray(`    agents export ${err.agent}                      # copy its config out to your real config dir`));
+    console.error(chalk.gray('\n  To manage this agent normally instead, remove the isolated copies first:'));
+    for (const v of versions) {
+        console.error(chalk.gray(`    agents remove ${err.agent}@${v} --isolated`));
+    }
+}
+/** Run `fn`, converting a boundary refusal into guidance + a non-zero exit. */
+export async function withIsolationBoundary(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        if (err instanceof IsolationBoundaryError) {
+            explainIsolationBoundary(err);
+            process.exit(1);
+        }
+        throw err;
+    }
+}

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

@@ -18,6 +18,26 @@
 export declare function menubarDisabledByUser(): boolean;
 /** True if the launchd plist for the menu-bar service is installed. */
 export declare function menubarServiceInstalled(): boolean;
+/** True when the bundle carries a signature the kernel will accept at launch. */
+export declare function codesignVerifies(appPath: string): boolean;
+/**
+ * Guarantee the installed bundle has a valid signature on THIS machine.
+ *
+ * npm's pack/extract strips the ad-hoc/linker signature the release baked into
+ * the helper, leaving `code object is not signed at all`. On macOS 26+ the
+ * kernel's code-signing monitor SIGKILLs an unsigned/invalid binary at launch
+ * (`SIGKILL (Code Signature Invalid)`), so under the launchd `KeepAlive` service
+ * an ad-hoc release helper crash-loops forever and its unstable identity makes
+ * the Accessibility grant (needed for the clip→paste keystroke in Clip.swift)
+ * re-prompt every time. A fresh ad-hoc re-sign gives the on-disk bytes a
+ * matching cdhash, which the kernel accepts.
+ *
+ * A Developer-ID-signed helper survives npm untouched — its embedded signature
+ * still verifies — so we leave it alone and only re-sign when verification
+ * fails. Returns whether the bundle ends up validly signed. No-op cost on the
+ * common (already-valid) path is a single `codesign --verify`.
+ */
+export declare function ensureValidSignature(appPath: string): boolean;
 /**
  * Copy the bundled `.app` to the stable user path (idempotent unless forced).
  * Returns the installed executable path, or null if no source bundle ships

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

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

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,11 @@ 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 native desktop notification. Best-effort — failures (missing
+ * `osascript`/`notify-send`, no display, headless box) are swallowed so a
+ * notification attempt can never take the daemon down.
+ */
+export declare function notifyDesktop(title: string, body: string): void;
+/** Fire a native desktop notification listing the overdue jobs. Best-effort. */
 export declare function notifyOverdue(jobs: OverdueJob[]): void;

package/dist/lib/overdue.js

@@ -76,17 +76,12 @@ 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. */
-export function notifyOverdue(jobs) {
-    if (jobs.length === 0)
-        return;
-    const title = jobs.length === 1
-        ? `Routine overdue: ${jobs[0].name}`
-        : `${jobs.length} routines overdue`;
-    const body = jobs.length === 1
-        ? `Missed ${jobs[0].expectedAt.toLocaleString()}. Run: agents routines catchup`
-        : `${jobs.map((j) => j.name).join(', ')} — agents routines catchup`;
+/**
+ * Fire a native desktop notification. Best-effort — failures (missing
+ * `osascript`/`notify-send`, no display, headless box) are swallowed so a
+ * notification attempt can never take the daemon down.
+ */
+export function notifyDesktop(title, body) {
     const platform = os.platform();
     try {
         if (platform === 'darwin') {
@@ -117,3 +112,15 @@ export function notifyOverdue(jobs) {
         // Notification is best-effort; nothing to do.
     }
 }
+/** Fire a native desktop notification listing the overdue jobs. Best-effort. */
+export function notifyOverdue(jobs) {
+    if (jobs.length === 0)
+        return;
+    const title = jobs.length === 1
+        ? `Routine overdue: ${jobs[0].name}`
+        : `${jobs.length} routines overdue`;
+    const body = jobs.length === 1
+        ? `Missed ${jobs[0].expectedAt.toLocaleString()}. Run: agents routines catchup`
+        : `${jobs.map((j) => j.name).join(', ')} — agents routines catchup`;
+    notifyDesktop(title, body);
+}

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;
+    }
+}