@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/lib/session/parse.js

@@ -1014,44 +1014,144 @@ export function parseAntigravity(dbPath) {
  * Messages have role (user/assistant) and metadata.
  * Parts contain the actual content: text, tool, reasoning, patch, step-start/finish.
  */
+/**
+ * Parse a Grok (xAI CLI) session into normalized events.
+ *
+ * A Grok session dir holds several files; the conversation transcript is
+ * `chat_history.jsonl`, one JSON object per line with a `type`:
+ *   - `system`       — the system prompt (skipped; not conversational)
+ *   - `user`         — `content` is an array of `{ type: 'text', text }` blocks
+ *   - `assistant`    — `content` is a string, plus a `tool_calls[]` array of
+ *                      `{ id, name, arguments }` (arguments is a JSON string)
+ *   - `reasoning`    — chain-of-thought; text (when present) lives in `summary`
+ *   - `tool_result`  — `{ tool_call_id, content }`, correlated back to the call
+ *
+ * The scanner records `summary.json` as the session's filePath (see
+ * `readGrokMeta` in discover.ts), so resolve `chat_history.jsonl` from the same
+ * dir; also accept being handed the transcript file directly. Per-line
+ * timestamps aren't stored, so every event carries the session's `created_at`
+ * (from summary.json), falling back to the transcript's mtime.
+ */
 export function parseGrok(filePath) {
-    // Grok sessions are rich (summary.json + events.jsonl + chat_history.jsonl + updates.jsonl)
-    // This is a minimal stub for now so grok appears in `agents sessions`.
-    // Full parser (with subagents, tool calls, etc.) can be expanded later.
+    const sessionDir = path.dirname(filePath);
+    const historyPath = filePath.endsWith('chat_history.jsonl')
+        ? filePath
+        : path.join(sessionDir, 'chat_history.jsonl');
+    if (!fs.existsSync(historyPath))
+        return [];
+    let timestamp;
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
-        // If it's a summary.json, create a basic event
-        if (filePath.endsWith('summary.json')) {
-            const summary = JSON.parse(content);
-            return [{
-                    timestamp: summary.created_at || new Date().toISOString(),
-                    type: 'session_start',
-                    content: summary.session_summary || 'Grok session',
-                    agent: 'grok',
-                    metadata: { sessionId: summary.id, cwd: summary.cwd },
-                }];
+        const summaryPath = filePath.endsWith('summary.json')
+            ? filePath
+            : path.join(sessionDir, 'summary.json');
+        if (fs.existsSync(summaryPath)) {
+            const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf-8'));
+            if (typeof summary?.created_at === 'string')
+                timestamp = summary.created_at;
         }
-        // For JSONL files (events, chat_history, updates), return basic parsed lines
-        if (filePath.endsWith('.jsonl')) {
-            const lines = content.trim().split('\n').filter(Boolean);
-            return lines.slice(0, 50).map((line, i) => {
-                try {
-                    const obj = JSON.parse(line);
-                    return {
-                        timestamp: obj.timestamp || obj.ts || new Date().toISOString(),
-                        type: obj.type || obj.method || 'grok_event',
-                        content: typeof obj.content === 'string' ? obj.content : JSON.stringify(obj).slice(0, 200),
-                        agent: 'grok',
-                    };
+    }
+    catch { /* fall back to mtime below */ }
+    if (!timestamp) {
+        let mtime = null;
+        try {
+            mtime = fs.statSync(historyPath).mtime;
+        }
+        catch {
+            mtime = null;
+        }
+        timestamp = (mtime ?? new Date()).toISOString();
+    }
+    const content = safeReadSessionFile(historyPath);
+    const lines = content.split('\n').filter(l => l.trim());
+    const events = [];
+    const toolCallMap = new Map();
+    // Grok text is either a plain string (assistant) or an array of typed blocks
+    // (user: `{ type: 'text', text }`; reasoning summary: `{ text | summary_text }`).
+    const extractText = (raw) => {
+        if (typeof raw === 'string')
+            return raw.trim();
+        if (Array.isArray(raw)) {
+            return raw
+                .map((part) => typeof part?.text === 'string'
+                ? part.text
+                : typeof part?.summary_text === 'string'
+                    ? part.summary_text
+                    : '')
+                .join('')
+                .trim();
+        }
+        return '';
+    };
+    for (const line of lines) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = msg?.type;
+        if (type === 'user') {
+            const text = extractText(msg.content);
+            if (text)
+                events.push({ type: 'message', agent: 'grok', timestamp, role: 'user', content: text });
+        }
+        else if (type === 'assistant') {
+            const text = extractText(msg.content);
+            if (text)
+                events.push({ type: 'message', agent: 'grok', timestamp, role: 'assistant', content: text });
+            const calls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+            for (const call of calls) {
+                const toolName = typeof call?.name === 'string' ? call.name : 'unknown';
+                let args = {};
+                if (call?.arguments && typeof call.arguments === 'object') {
+                    args = call.arguments;
                 }
-                catch {
-                    return { timestamp: new Date().toISOString(), type: 'raw', content: line.slice(0, 200), agent: 'grok' };
+                else if (typeof call?.arguments === 'string') {
+                    try {
+                        args = JSON.parse(call.arguments);
+                    }
+                    catch {
+                        args = { _raw: call.arguments };
+                    }
                 }
+                if (typeof call?.id === 'string')
+                    toolCallMap.set(call.id, toolName);
+                events.push({
+                    type: 'tool_use',
+                    agent: 'grok',
+                    timestamp,
+                    tool: toolName,
+                    args,
+                    path: args.path || args.file_path || undefined,
+                    command: typeof args.command === 'string' ? args.command : undefined,
+                });
+            }
+        }
+        else if (type === 'reasoning') {
+            const text = extractText(msg.summary);
+            if (text)
+                events.push({ type: 'thinking', agent: 'grok', timestamp, content: text });
+        }
+        else if (type === 'tool_result') {
+            const callId = typeof msg.tool_call_id === 'string' ? msg.tool_call_id : undefined;
+            const toolName = (callId && toolCallMap.get(callId)) || 'unknown';
+            const output = typeof msg.content === 'string' ? msg.content : extractText(msg.content);
+            const isError = typeof output === 'string' && output.startsWith('Error:');
+            events.push({
+                type: isError ? 'error' : 'tool_result',
+                agent: 'grok',
+                timestamp,
+                tool: toolName,
+                success: !isError,
+                output: output.length > 500 ? output.slice(0, 497) + '...' : output,
             });
+            if (callId)
+                toolCallMap.delete(callId);
         }
+        // `system` lines are the system prompt — intentionally skipped.
     }
-    catch { }
-    return [];
+    return events;
 }
 export function parseOpenCode(filePath) {
     const [dbPath, sessionId] = filePath.split('#');

package/dist/lib/session/pid-registry.d.ts

@@ -4,6 +4,23 @@ export interface PidSessionEntry {
     /** The launch session id. Present for agents launched with a known id (Claude). */
     sessionId?: string;
     cwd?: string;
+    /**
+     * The launch id minted by `ag run` and exported to the child as
+     * `AGENT_LAUNCH_ID`. The agent's SessionStart hook records the SAME id in its
+     * own state file (`terminals/sessions/<pid>.json`, `launch_id`), so the two
+     * records reconcile by this key even when the hook runs under a DIFFERENT pid
+     * (tmux pane leaf, cmd.exe wrapper) — see resolveHookSessionId in
+     * session/hook-sessions.ts. This
+     * is how a non-Claude launch (whose id we don't know at spawn) gets an exact
+     * session id at listing time instead of the newest-jsonl heuristic.
+     */
+    launchId?: string;
+    /**
+     * `AGENT_TERMINAL_ID` when the launch inherited one (a Factory VS Code tab).
+     * A secondary join key to the hook's `terminal_id`, for agents the extension
+     * spawned. Best-effort — undefined outside the extension.
+     */
+    terminalId?: string;
     /**
      * `$TMUX_PANE` at launch — stored for diagnostics and possible future
      * disambiguation. NOT currently consulted on read: the listing path keys
@@ -18,5 +35,20 @@ export declare function extractSessionIdArg(args: string[]): string | undefined;
 export declare function writePidSessionEntry(entry: PidSessionEntry): void;
 /** Look up a live pid's recorded session. Returns undefined if absent/corrupt. */
 export declare function readPidSessionEntry(pid: number): PidSessionEntry | undefined;
-/** Remove entries whose pid is no longer alive. Best-effort housekeeping. */
-export declare function prunePidSessionRegistry(isAlive: (pid: number) => boolean): void;
+/**
+ * Every recorded launch, one entry per live-or-dead pid. Used to index launches
+ * by their `tmuxPane` so the authoritative tmux source can attribute a pane it did
+ * NOT wrap (an agent bare-spawned into an existing pane) to its exact launch —
+ * the caller filters to live pids. Best-effort: unreadable/corrupt files are
+ * skipped, a missing dir yields `[]`.
+ */
+export declare function listPidSessionEntries(): PidSessionEntry[];
+/**
+ * Remove entries whose pid is no longer alive. Best-effort housekeeping.
+ *
+ * `isAlive` receives the entry's recorded `startedAtMs` so it can reject a pid
+ * that a newer process recycled (a "zombie" registry entry), not just one that
+ * no longer exists. An unreadable/corrupt entry falls back to the pid-only
+ * check.
+ */
+export declare function prunePidSessionRegistry(isAlive: (pid: number, startedAtMs?: number) => boolean): void;

package/dist/lib/session/pid-registry.js

@@ -81,7 +81,43 @@ export function readPidSessionEntry(pid) {
     }
     return undefined;
 }
-/** Remove entries whose pid is no longer alive. Best-effort housekeeping. */
+/**
+ * Every recorded launch, one entry per live-or-dead pid. Used to index launches
+ * by their `tmuxPane` so the authoritative tmux source can attribute a pane it did
+ * NOT wrap (an agent bare-spawned into an existing pane) to its exact launch —
+ * the caller filters to live pids. Best-effort: unreadable/corrupt files are
+ * skipped, a missing dir yields `[]`.
+ */
+export function listPidSessionEntries() {
+    let files;
+    try {
+        files = fs.readdirSync(pidRegistryDir()).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(pidRegistryDir(), f), 'utf8'));
+            if (parsed && typeof parsed === 'object' && typeof parsed.pid === 'number') {
+                out.push(parsed);
+            }
+        }
+        catch {
+            /* raced with a writer/pruner, or corrupt — skip */
+        }
+    }
+    return out;
+}
+/**
+ * Remove entries whose pid is no longer alive. Best-effort housekeeping.
+ *
+ * `isAlive` receives the entry's recorded `startedAtMs` so it can reject a pid
+ * that a newer process recycled (a "zombie" registry entry), not just one that
+ * no longer exists. An unreadable/corrupt entry falls back to the pid-only
+ * check.
+ */
 export function prunePidSessionRegistry(isAlive) {
     let files;
     try {
@@ -92,7 +128,18 @@ export function prunePidSessionRegistry(isAlive) {
     }
     for (const f of files) {
         const pid = Number(f.slice(0, -'.json'.length));
-        if (!Number.isInteger(pid) || isAlive(pid))
+        if (!Number.isInteger(pid))
+            continue;
+        let startedAtMs;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(path.join(pidRegistryDir(), f), 'utf8'));
+            if (typeof parsed?.startedAtMs === 'number')
+                startedAtMs = parsed.startedAtMs;
+        }
+        catch {
+            /* unreadable/corrupt — fall back to the pid-only liveness check */
+        }
+        if (isAlive(pid, startedAtMs))
             continue;
         try {
             fs.unlinkSync(path.join(pidRegistryDir(), f));

package/dist/lib/session/render.d.ts

@@ -12,10 +12,15 @@ import type { SessionEvent, SessionMeta } from './types.js';
  */
 export declare function relativeToCwd(absPath: string, cwd?: string): string;
 /**
- * Wrap label in an OSC 8 hyperlink when the terminal supports it.
- * Degrades to plain label otherwise.
+ * Wrap a filesystem path label in an OSC 8 `file://` hyperlink when the terminal
+ * supports it. Degrades to the plain label otherwise.
  */
 export declare function linkPath(absPath: string, label: string): string;
+/**
+ * Wrap a label in an OSC 8 hyperlink to an arbitrary URL (a PR on GitHub, a Linear
+ * issue, …) when the terminal supports it. Degrades to the plain label otherwise.
+ */
+export declare function linkUrl(url: string, label: string): string;
 /**
  * Unwrap wrapper prefixes to find the actual executable.
  */

package/dist/lib/session/render.js

@@ -28,19 +28,31 @@ export function relativeToCwd(absPath, cwd) {
     }
     return absPath;
 }
-/**
- * Wrap label in an OSC 8 hyperlink when the terminal supports it.
- * Degrades to plain label otherwise.
- */
-export function linkPath(absPath, label) {
-    if (process.stdout.isTTY &&
+/** Best-effort feature-detect for OSC 8 hyperlink support in the current TTY. */
+function supportsHyperlinks() {
+    return Boolean(process.stdout.isTTY &&
         (process.env.TERM_PROGRAM ||
             process.env.WT_SESSION ||
             process.env.KITTY_WINDOW_ID ||
-            process.env.WEZTERM_PANE)) {
-        return `\x1b]8;;file://${absPath}\x1b\\${label}\x1b]8;;\x1b\\`;
-    }
-    return label;
+            process.env.WEZTERM_PANE));
+}
+/** Wrap `label` in an OSC 8 hyperlink to `target`. Callers gate on {@link supportsHyperlinks}. */
+function osc8(target, label) {
+    return `\x1b]8;;${target}\x1b\\${label}\x1b]8;;\x1b\\`;
+}
+/**
+ * Wrap a filesystem path label in an OSC 8 `file://` hyperlink when the terminal
+ * supports it. Degrades to the plain label otherwise.
+ */
+export function linkPath(absPath, label) {
+    return supportsHyperlinks() ? osc8(`file://${absPath}`, label) : label;
+}
+/**
+ * Wrap a label in an OSC 8 hyperlink to an arbitrary URL (a PR on GitHub, a Linear
+ * issue, …) when the terminal supports it. Degrades to the plain label otherwise.
+ */
+export function linkUrl(url, label) {
+    return supportsHyperlinks() ? osc8(url, label) : label;
 }
 // ── Command grouping ──────────────────────────────────────────────────────────
 /**

package/dist/lib/session/short-id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Canonical derivation of a session's 8-char `shortId`.
+ *
+ * Every session parser used to inline `id.slice(0, 8)` — some with a
+ * `.replace(prefix, '')` strip first (`session_`, `api-`, `ses_`). That strip is
+ * the bug: an id that is *only* its prefix (a bare `session_` directory, an id of
+ * exactly `api-`) strips to `''`, and `''.slice(0, 8)` is still `''`. An empty
+ * shortId then passes the `short_id TEXT NOT NULL` constraint (empty string is not
+ * NULL) yet matches nothing in the `short_id LIKE ?` picker lookups — a silently
+ * corrupt index row.
+ *
+ * This helper is the single source of truth: it strips the optional prefix, takes
+ * the first 8 chars, and — the whole point — guarantees a NON-EMPTY result by
+ * falling back to the unstripped id when the strip empties it, so a row always
+ * stays addressable by its shortId.
+ */
+export declare function deriveShortId(id: string, stripPrefix?: RegExp): string;

package/dist/lib/session/short-id.js

@@ -0,0 +1,20 @@
+/**
+ * Canonical derivation of a session's 8-char `shortId`.
+ *
+ * Every session parser used to inline `id.slice(0, 8)` — some with a
+ * `.replace(prefix, '')` strip first (`session_`, `api-`, `ses_`). That strip is
+ * the bug: an id that is *only* its prefix (a bare `session_` directory, an id of
+ * exactly `api-`) strips to `''`, and `''.slice(0, 8)` is still `''`. An empty
+ * shortId then passes the `short_id TEXT NOT NULL` constraint (empty string is not
+ * NULL) yet matches nothing in the `short_id LIKE ?` picker lookups — a silently
+ * corrupt index row.
+ *
+ * This helper is the single source of truth: it strips the optional prefix, takes
+ * the first 8 chars, and — the whole point — guarantees a NON-EMPTY result by
+ * falling back to the unstripped id when the strip empties it, so a row always
+ * stays addressable by its shortId.
+ */
+export function deriveShortId(id, stripPrefix) {
+    const stripped = stripPrefix ? id.replace(stripPrefix, '') : id;
+    return stripped.slice(0, 8) || id.slice(0, 8) || id;
+}

package/dist/lib/session/state.js

@@ -378,8 +378,12 @@ export function inferActivity(events, ctx = {}) {
         // A prose question takes a free-text reply (no select-list), so no options/keys.
         // Unlike the structural plan/ask signals above, the prose heuristic DECAYS: a
         // question nobody answered within PROSE_QUESTION_FRESH_MS is a session that
-        // ended, not one that needs you (RUSH-1522). Unknown mtime keeps the question.
-        const questionFresh = ctx.mtimeMs == null || Date.now() - ctx.mtimeMs < PROSE_QUESTION_FRESH_MS;
+        // ended, not one that needs you (RUSH-1522). A prose "?" is only "waiting on
+        // you" while the file is DEMONSTRABLY fresh — with no mtime signal at all we
+        // cannot assert freshness, so the heuristic must not fire (an unknown-age
+        // prose question is a session that ended, closing RUSH-1522's null-mtime hole
+        // where a null mtime kept the question forever).
+        const questionFresh = ctx.mtimeMs != null && Date.now() - ctx.mtimeMs < PROSE_QUESTION_FRESH_MS;
         if (questionFresh && looksLikeQuestion(last.content ?? '')) {
             const text = oneLine(last.content ?? '');
             return { ...base, activity: 'waiting_input', awaitingReason: 'question', question: { text, reason: 'question' } };

package/dist/lib/shims.d.ts

@@ -77,7 +77,7 @@ export interface ConflictInfo {
  *         top-level entry add/remove — deep edits to plugin contents won't
  *         trigger auto-resync, run `agents sync` for that.
  */
-export declare const SHIM_SCHEMA_VERSION = 26;
+export declare const SHIM_SCHEMA_VERSION = 27;
 /**
  * Generate the full bash shim script for the given agent. The returned string
  * is written to ~/.agents/shims/{cliCommand} and made executable.
@@ -508,6 +508,32 @@ export declare function addShimsToPath(overrides?: {
     shimsDir?: string;
 }): ShimPathResult;
 export declare function listAgentsWithInstalledVersions(): AgentId[];
+/**
+ * Thrown when an operation would carry an isolated-only agent across the isolation
+ * boundary. Callers that can explain the situation catch it and print guidance; the
+ * throw is what makes the boundary a property of the code rather than a convention
+ * every future call site has to remember.
+ */
+export declare class IsolationBoundaryError extends Error {
+    readonly agent: AgentId;
+    readonly operation: string;
+    constructor(agent: AgentId, operation: string);
+}
+/**
+ * True when EVERY installed version of `agent` is isolated (and at least one is).
+ *
+ * This is the switch: installing with `--isolated` is itself the act of opting in,
+ * so there is no mode to set and none to forget. It is per-agent, so an isolated
+ * codex constrains nothing about claude. And the escape hatch is inherent — remove
+ * the isolated copies and the agent is ordinary again, which means the state that
+ * grants protection is the same state you delete to drop it.
+ *
+ * An agent with any NORMAL version is not protected: that install already owns the
+ * launcher and the real `~/.<agent>`, so there is no boundary left to defend.
+ */
+export declare function isIsolationProtected(agent: AgentId): boolean;
+/** Refuse `operation` when `agent` is isolated-only. */
+export declare function assertIsolationBoundary(agent: AgentId, operation: string): void;
 export declare function listAgentsWithNonIsolatedInstalledVersions(): AgentId[];
 /**
  * Resource diff between two versions. Each field lists resources present in

package/dist/lib/shims.js

@@ -222,7 +222,7 @@ async function promptConflictStrategy(conflictInfos) {
 //        The old dispatcher checked only the global dir, so a pinned grok that
 //        installed into the versioned home fell through to the "not installed"
 //        error.
-export const SHIM_SCHEMA_VERSION = 26;
+export const SHIM_SCHEMA_VERSION = 27;
 /** Internal marker string used to embed the schema version in shim scripts. */
 const SHIM_VERSION_MARKER = 'agents-shim-version:';
 function shellQuote(value) {
@@ -278,13 +278,20 @@ export COPILOT_HOME="$VERSION_DIR/home/${configDirName}"
 # This gives agents-cli full versioned isolation + resource sync for grok.
 export GROK_HOME="$VERSION_DIR/home/.grok"
 `
-                    : agent === 'kimi'
+                    : agent === 'opencode'
                         ? `
+# OpenCode reads plugins, agents, commands, and other config-directory
+# resources from OPENCODE_CONFIG_DIR. Point it at the versioned global config
+# tree where agents-cli syncs OpenCode resources.
+export OPENCODE_CONFIG_DIR="$VERSION_DIR/home/.config/opencode"
+`
+                        : agent === 'kimi'
+                            ? `
 # Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
 # mcp.json, sessions, skills, hooks). Point it at the versioned home.
 export KIMI_CODE_HOME="$VERSION_DIR/home/${configDirName}"
 `
-                        : '';
+                            : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     return `#!/bin/bash
 # Auto-generated by agents-cli - do not edit
@@ -661,6 +668,9 @@ export function shimTargetsFor(platform) {
  * Create a shim for an agent.
  */
 export function createShim(agent) {
+    // A bare shim puts agents-cli first on PATH for this agent — the opposite of what
+    // an isolated-only install promises.
+    assertIsolationBoundary(agent, 'create the bare shim');
     ensureAgentsDir();
     const shimsDir = getShimsDir();
     const agentConfig = AGENTS[agent];
@@ -864,7 +874,7 @@ function assertSafeVersion(version) {
  * KEEP IN SYNC with the `managedEnv` switch in `generateVersionedAliasScript`.
  * The colocated test `shims.isolation-capability.test.ts` enforces this.
  */
-export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi'];
+export const CONFIG_ENV_ISOLATED_AGENTS = ['claude', 'codex', 'copilot', 'grok', 'kimi', 'opencode'];
 /**
  * Whether an agent supports a clean `--isolated` install — i.e. its config
  * location can be redirected by an env var so the isolated copy stays fully
@@ -909,13 +919,20 @@ export COPILOT_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${
 # aliases at the versioned home for isolation parity with the main shim.
 export GROK_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                    : agent === 'kimi'
+                    : agent === 'opencode'
                         ? `
+# OpenCode reads plugins, agents, commands, and other config-directory
+# resources from OPENCODE_CONFIG_DIR. Point direct aliases at the versioned
+# global config tree where agents-cli syncs OpenCode resources.
+export OPENCODE_CONFIG_DIR="$HOME/.agents/.history/versions/${agent}/${version}/home/.config/opencode"
+`
+                        : agent === 'kimi'
+                            ? `
 # Kimi Code CLI honors KIMI_CODE_HOME to relocate ~/.kimi-code (config.toml,
 # mcp.json, sessions, skills, hooks). Point direct aliases at the versioned home.
 export KIMI_CODE_HOME="$HOME/.agents/.history/versions/${agent}/${version}/home/${configDirName}"
 `
-                        : '';
+                            : '';
     const launchArgs = agent === 'codex' ? ' -c check_for_update_on_startup=false' : '';
     // Resolve the binary the same way the main shim does (see generateShimScript).
     // Grok and Droid do NOT ship into node_modules/.bin — Grok downloads a native
@@ -1322,6 +1339,8 @@ export function carryForwardAuthFiles(agent, toConfigDir) {
     }
 }
 export async function switchConfigSymlink(agent, version) {
+    // Moves the user's real ~/.<agent> aside and symlinks it into a version home.
+    assertIsolationBoundary(agent, 'repoint your real config directory');
     const configPath = getAgentConfigPath(agent);
     const versionConfigPath = getVersionConfigPath(agent, version);
     // Ensure version config directory exists
@@ -1426,6 +1445,8 @@ export async function switchConfigSymlink(agent, version) {
  * ALL installed versions so they inherit the current account.
  */
 export function switchHomeFileSymlinks(agent, version) {
+    // Same, for home-level files such as ~/.claude.json.
+    assertIsolationBoundary(agent, 'repoint your home-level config files');
     const agentConfig = AGENTS[agent];
     const homeFiles = agentConfig.homeFiles;
     if (!homeFiles || homeFiles.length === 0)
@@ -2076,6 +2097,9 @@ function canonicalOrNull(p) {
  * - Never records our own shim as the "original" (would loop).
  */
 export function adoptShadowingLauncher(agent, overrides) {
+    // Repoints the user's OWN launcher symlink at our shim — the most invasive thing
+    // in the codebase, and the one with no isolated-scoped equivalent at all.
+    assertIsolationBoundary(agent, 'adopt your launcher');
     const shimsDir = overrides?.shimsDir ?? getShimsDir();
     const shimPath = path.join(shimsDir, AGENTS[agent].cliCommand);
     const shimReal = canonical(shimPath);
@@ -2431,6 +2455,64 @@ export function listAgentsWithInstalledVersions() {
 function isInstalledVersionIsolated(agent, version) {
     return fs.existsSync(path.join(getVersionsDir(), agent, version, '.isolated'));
 }
+/**
+ * Thrown when an operation would carry an isolated-only agent across the isolation
+ * boundary. Callers that can explain the situation catch it and print guidance; the
+ * throw is what makes the boundary a property of the code rather than a convention
+ * every future call site has to remember.
+ */
+export class IsolationBoundaryError extends Error {
+    agent;
+    operation;
+    constructor(agent, operation) {
+        super(`${agent} is installed only as isolated copies; "${operation}" would adopt it into your local setup.`);
+        this.agent = agent;
+        this.operation = operation;
+        this.name = 'IsolationBoundaryError';
+    }
+}
+/**
+ * True when EVERY installed version of `agent` is isolated (and at least one is).
+ *
+ * This is the switch: installing with `--isolated` is itself the act of opting in,
+ * so there is no mode to set and none to forget. It is per-agent, so an isolated
+ * codex constrains nothing about claude. And the escape hatch is inherent — remove
+ * the isolated copies and the agent is ordinary again, which means the state that
+ * grants protection is the same state you delete to drop it.
+ *
+ * An agent with any NORMAL version is not protected: that install already owns the
+ * launcher and the real `~/.<agent>`, so there is no boundary left to defend.
+ */
+export function isIsolationProtected(agent) {
+    const agentVersionsDir = path.join(getVersionsDir(), agent);
+    let dirs;
+    try {
+        dirs = fs.readdirSync(agentVersionsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return false;
+    }
+    // Count only directories that are actually an install. A bare version dir is
+    // scaffolding, not a non-isolated version — and treating it as one would disable
+    // protection at exactly the wrong moment: an adopting path that does
+    // `mkdirSync(<version>/home)` before adopting would flip this to false with its own
+    // first line and then walk straight through the gates. Ignoring scaffolding biases
+    // the predicate toward protecting, which is the safe direction to fail in.
+    const installed = dirs.filter((v) => {
+        const dir = path.join(agentVersionsDir, v);
+        return fs.existsSync(path.join(dir, 'node_modules')) || fs.existsSync(path.join(dir, 'package.json'));
+    });
+    if (installed.length === 0)
+        return false;
+    return installed.every((v) => isInstalledVersionIsolated(agent, v));
+}
+/** Refuse `operation` when `agent` is isolated-only. */
+export function assertIsolationBoundary(agent, operation) {
+    if (isIsolationProtected(agent))
+        throw new IsolationBoundaryError(agent, operation);
+}
 export function listAgentsWithNonIsolatedInstalledVersions() {
     const versionsDir = getVersionsDir();
     if (!fs.existsSync(versionsDir)) {

package/dist/lib/sqlite.d.ts

@@ -3,8 +3,9 @@
  *
  * Picks `bun:sqlite` under Bun and `node:sqlite` under Node (>=22.5). Avoids
  * the native `better-sqlite3` addon entirely so there is no prebuild compile
- * and no Node/Bun ABI mismatch when the same source runs in tests (Bun) and
- * production (Node).
+ * and no Node/Bun ABI mismatch. Both runtimes are production: `dist/index.js`
+ * runs under Node, while the signed standalone `dist/bin/agents` (what the
+ * shims exec) embeds Bun.
  *
  * Exposes the small better-sqlite3-shaped surface area the rest of the
  * codebase already uses: `prepare/exec/pragma/transaction/close` on the DB,