@phnx-labs/agents-cli 1.20.73 → 1.20.76

package/dist/commands/sessions.d.ts

@@ -33,6 +33,19 @@ export declare function liveGlyphAndPreview(a: ActiveSession | undefined): {
  * into a scannable column instead of jamming against a truncated topic.
  */
 export declare function ticketLabel(s: Pick<SessionMeta, 'ticketId' | 'prNumber'>): string;
+/**
+ * The row shape `agents sessions --active --json` emits. RUSH-1981: a watcher
+ * joins active sessions on ticketId + project, but the raw ActiveSession nests
+ * the ticket (`ticket.id`) and carries no `project` at all — so a naive join
+ * silently drops every row. Emit both as flat, always-present top-level keys
+ * (null when unknown) alongside the raw fields, so every active row is joinable.
+ * `project` uses the same derivation SessionMeta does — basename(cwd) (see
+ * discover.ts) — so the active view and the history view join identically.
+ */
+export declare function serializeActiveSessionsForJson(sessions: ActiveSession[]): Array<ActiveSession & {
+    ticketId: string | null;
+    project: string | null;
+}>;
 /** Grouped + sorted view of active sessions for the --active renderer. */
 export interface ActiveSessionsLayout {
     workspaces: Array<{
@@ -204,8 +217,8 @@ export declare function handlePickedSession(picked: PickedSession): Promise<void
  * Resume a session in the current terminal — a foreground takeover of this
  * process. Used by the single-select picker and by `sessions resume` when the
  * chosen destination is "in place" (unknown emulator / off-macOS, single pick).
- * Falls back to the current version via `/continue` when the version-pinned
- * binary is missing (ENOENT).
+ * Falls back to the same resume invocation against the current version when the
+ * version-pinned launcher is genuinely missing.
  */
 export declare function resumeSessionInPlace(session: SessionMeta): Promise<void>;
 /**
@@ -224,23 +237,33 @@ export declare function resumeSpawnInvocation(cmd: string[], platform?: NodeJS.P
     args: string[];
     shell: boolean;
 };
-/**
- * Build the shell command that resumes a picked session.
- *
- * When the session's originating version is known, uses the version-pinned
- * binary (e.g. `claude@2.1.138`) so the resume always runs in the same
- * isolated HOME where the JSONL was written — regardless of which version is
- * currently the default. Falls back to the bare shim when version is unknown.
- *
- * If the versioned binary is missing (version was removed), the ENOENT
- * handler in handlePickedSession retries via buildFallbackCommand.
- */
 export declare function buildResumeCommand(session: SessionMeta): string[] | null;
 interface AgentFilter {
     agent?: SessionAgentId;
     version?: string;
 }
 export declare function parseAgentFilter(agentName?: string): AgentFilter;
+/**
+ * How a `sessions <query>` argument was resolved against the pool.
+ *
+ * `byId` records that the rows came from an id lookup, so only then does an
+ * ambiguous result mean "your id prefix is too short". `completeId` records that
+ * the query was a whole session id: it is unique by construction, so a miss is
+ * final and must NOT widen into a text/content search.
+ */
+export interface SessionQueryResolution {
+    matches: SessionMeta[];
+    byId: boolean;
+    completeId: boolean;
+}
+/**
+ * The single entry point for turning a `sessions <query>` argument into rows.
+ *
+ * A complete session id resolves by id alone. Anything else keeps the existing
+ * ladder: id lookup first (so a short id still wins), then the ranked
+ * metadata+content search.
+ */
+export declare function resolveSessionQuery(pool: SessionMeta[], query: string): SessionQueryResolution;
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
 /** Register the `agents sessions` command with all its options and help text. */

package/dist/commands/sessions.js

@@ -26,14 +26,16 @@ import { gatherRemoteActive, NO_FANOUT_ENV } from '../lib/session/remote-active.
 import { gatherRemoteList, runOnPeer } from '../lib/session/remote-list.js';
 import { stringWidth, truncateToWidth, padToWidth, terminalWidth } from '../lib/session/width.js';
 import { inferSessionState } from '../lib/session/state.js';
-import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex, getSessionRoots } from '../lib/session/discover.js';
+import { discoverSessions, countSessionsInScope, resolveSessionById, isCompleteSessionId, searchContentIndex, getSessionRoots } from '../lib/session/discover.js';
+import { findSessionsById } from '../lib/session/db.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
 import { runRemoteSessions, buildForwardedArgs, ensureWholeIndex } from '../lib/session/remote.js';
 import { formatRelativeTime } from '../lib/session/relative-time.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
-import { colorAgent, resolveAgentName } from '../lib/agents.js';
+import { AGENTS, colorAgent, resolveAgentName } from '../lib/agents.js';
+import { getShimsDir } from '../lib/state.js';
 import { fuzzyMatch, FUZZY_PRESETS } from '../lib/fuzzy.js';
 import { resolveVersionAliasLoose } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -44,9 +46,12 @@ import { registerSessionsSyncCommand } from './sessions-sync.js';
 import { registerSessionsResumeCommand } from './sessions-resume.js';
 import { registerGoCommand } from './go.js';
 import { registerFocusCommand } from './focus.js';
+import { registerDetachCommand } from './detach.js';
+import { registerAttachCommand } from './attach.js';
 import { registerSessionsInjectCommand } from './sessions-inject.js';
 import { registerSessionsExportCommand } from './sessions-export.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
+import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { runBrowserSessions } from '../lib/browser/sessions-list.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 /**
@@ -176,6 +181,9 @@ function statusColor(status) {
         case 'idle': return chalk.gray;
         case 'queued': return chalk.blue;
         case 'input_required': return chalk.yellow;
+        // Alive but un-introspectable (a harness whose transcript we can't parse).
+        // Magenta so it never reads as the gray "idle" it used to be faked as.
+        case 'unknown': return chalk.magenta;
     }
 }
 function contextColor(context) {
@@ -274,7 +282,10 @@ export function liveGlyphAndPreview(a) {
         return { glyph: '', preview: '' };
     const waiting = a.status === 'input_required' || a.activity === 'waiting_input';
     const running = a.status === 'running' || a.activity === 'working';
-    const shape = waiting ? '◐' : running ? '●' : '○';
+    // `◌` (dotted) = alive but un-introspectable — visually distinct from `○` idle
+    // so an opaque harness is never mistaken for a finished one.
+    const unknown = a.status === 'unknown';
+    const shape = waiting ? '◐' : running ? '●' : unknown ? '◌' : '○';
     return { glyph: statusColor(a.status)(shape), preview: buildSessionDescription(a) };
 }
 /**
@@ -285,6 +296,22 @@ export function liveGlyphAndPreview(a) {
 export function ticketLabel(s) {
     return s.ticketId ?? (s.prNumber ? `PR#${s.prNumber}` : '');
 }
+/**
+ * The row shape `agents sessions --active --json` emits. RUSH-1981: a watcher
+ * joins active sessions on ticketId + project, but the raw ActiveSession nests
+ * the ticket (`ticket.id`) and carries no `project` at all — so a naive join
+ * silently drops every row. Emit both as flat, always-present top-level keys
+ * (null when unknown) alongside the raw fields, so every active row is joinable.
+ * `project` uses the same derivation SessionMeta does — basename(cwd) (see
+ * discover.ts) — so the active view and the history view join identically.
+ */
+export function serializeActiveSessionsForJson(sessions) {
+    return sessions.map((s) => ({
+        ...s,
+        ticketId: s.ticket?.id ?? null,
+        project: s.cwd ? path.basename(s.cwd) : null,
+    }));
+}
 /**
  * Compact, colour-coded badges for the durable/awaiting signals. Text-only (no
  * emoji, per repo convention): `plan` / `ask` / `perm` for why it's waiting,
@@ -573,15 +600,18 @@ async function runRemoteSessionsJson(hosts) {
     process.stdout.write(serializeSessionsJson(sessions));
 }
 /**
- * `running N · idle N · waiting N · queued N` for a bucket of sessions (zero
- * buckets omitted). Same bucketing as the grand-total summary so per-group
- * counts reconcile with the `(total)` beside the header. Empty when nothing.
+ * `running N · idle N · waiting N · queued N · unknown N` for a bucket of
+ * sessions (zero buckets omitted). Same bucketing as the grand-total summary so
+ * per-group counts reconcile with the `(total)` beside the header — the `unknown`
+ * bucket is what keeps an alive-but-opaque row from silently vanishing from the
+ * tally. Empty when nothing.
  */
 function groupTally(sessions) {
     const running = sessions.filter(s => s.status === 'running').length;
     const idle = sessions.filter(s => s.status === 'idle').length;
     const waiting = sessions.filter(s => s.status === 'input_required').length;
     const queued = sessions.filter(s => s.status === 'queued').length;
+    const unknown = sessions.filter(s => s.status === 'unknown').length;
     const parts = [];
     if (running)
         parts.push(`${running} running`);
@@ -591,6 +621,8 @@ function groupTally(sessions) {
         parts.push(`${waiting} waiting`);
     if (queued)
         parts.push(`${queued} queued`);
+    if (unknown)
+        parts.push(`${unknown} unknown`);
     return parts.join(' · ');
 }
 /** Print one machine's workspace tree, indented under its machine header. */
@@ -747,7 +779,7 @@ async function renderActiveSessions(asJson, waitingOnly = false, opts = {}) {
     // present so a supervising agent or hook can poll it as a gate.
     const sessions = waitingOnly ? merged.filter(s => s.status === 'input_required') : merged;
     if (asJson) {
-        process.stdout.write(JSON.stringify(sessions, null, 2) + '\n');
+        process.stdout.write(JSON.stringify(serializeActiveSessionsForJson(sessions), null, 2) + '\n');
         if (waitingOnly && sessions.length > 0)
             process.exitCode = 1;
         return;
@@ -835,10 +867,15 @@ function canonicalSessionsCommand(query, options) {
 async function renderSessionPreview(query, scope) {
     const discovered = await discoverSessions({ all: true, cwd: process.cwd(), limit: 5000 });
     const pool = applyScopeFilters(discovered, scope);
-    const matches = resolveSessionById(pool, query);
-    const session = (matches.length > 0 ? matches : filterSessionsByQuery(pool, query))[0];
+    const { matches, completeId } = resolveSessionQuery(pool, query);
+    const session = matches[0];
     if (!session) {
-        console.log(chalk.gray(`No session matches "${query}".`));
+        // A complete id that missed is not "no match for this text" — say which, and
+        // give the same fleet pointer the render paths give.
+        if (completeId)
+            notFoundByIdMessage(query).forEach(l => console.log(l));
+        else
+            console.log(chalk.gray(`No session matches "${query}".`));
         return;
     }
     console.log(buildPreview(session));
@@ -1043,11 +1080,14 @@ async function sessionsAction(query, options) {
             sortBy,
             origin: options.routine ? 'routine' : undefined,
         };
+        let hiddenUnmanaged = 0;
         let sessions = await discoverSessions({
             ...scope,
             limit,
             excludeTeamOrigin: !options.teams,
             onProgress: tracker.onProgress,
+            includeUnmanaged: options.unmanaged,
+            onHiddenUnmanaged: (n) => { hiddenUnmanaged = n; },
         });
         tracker.stop();
         spinner?.stop();
@@ -1121,6 +1161,9 @@ async function sessionsAction(query, options) {
             if (hiddenCount > 0) {
                 console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
             }
+            if (hiddenUnmanaged > 0) {
+                console.log(chalk.gray(formatUnmanagedHiddenFooter(hiddenUnmanaged)));
+            }
             return;
         }
         // The grouped project overview is the bare interactive default: a scannable
@@ -1130,7 +1173,7 @@ async function sessionsAction(query, options) {
             const liveIndex = await maybeLiveIndex(options);
             // Per-project row cap is fixed (--limit carries a default of 50 and drives
             // the fetch pool, not the display); `--all` expands every group instead.
-            printSessionOverview(sessions, hiddenCount, liveIndex, { perProjectCap: OVERVIEW_ROWS_PER_PROJECT, expand: !!options.all });
+            printSessionOverview(sessions, hiddenCount, liveIndex, { perProjectCap: OVERVIEW_ROWS_PER_PROJECT, expand: !!options.all, hiddenUnmanaged });
             return;
         }
         // --tree / --flat are printed listings, not an interactive pick — render them
@@ -1150,6 +1193,10 @@ async function sessionsAction(query, options) {
         const filtered = searchQuery ? filterSessionsByQuery(sessions, searchQuery) : sessions;
         const liveIndex = await maybeLiveIndex(options);
         printSessionTable(filtered, hiddenCount, options.tree === true, liveIndex);
+        // Every listing path must say what it dropped — a hidden default that stays
+        // silent in one render mode is the failure this footer exists to prevent.
+        if (hiddenUnmanaged > 0)
+            console.log(chalk.gray(formatUnmanagedHiddenFooter(hiddenUnmanaged)));
     }
     catch (err) {
         tracker.stop();
@@ -1158,8 +1205,14 @@ async function sessionsAction(query, options) {
         process.exit(1);
     }
 }
+/** Whether a query should route to the single-session render rather than the
+ * listing. The hex-ish test catches a bare id prefix; `isCompleteSessionId`
+ * additionally catches the prefixed whole ids (`session_…`, `ses_…`) that the
+ * hex test rejects — without it those never reach the id-only resolution and
+ * still content-search. */
 function looksLikeSessionId(query) {
-    return /^[0-9a-f-]{6,}$/i.test(query.trim());
+    const trimmed = query.trim();
+    return /^[0-9a-f-]{6,}$/i.test(trimmed) || isCompleteSessionId(trimmed);
 }
 function teamTag(session) {
     const origin = session.teamOrigin;
@@ -1337,6 +1390,8 @@ function printSessionOverview(pool, hiddenCount, liveIndex, opts) {
     console.log(parts.join(chalk.gray('  ·  ')));
     if (hiddenCount > 0)
         console.log(chalk.gray(formatTeamHiddenFooter(hiddenCount)));
+    if (opts.hiddenUnmanaged)
+        console.log(chalk.gray(formatUnmanagedHiddenFooter(opts.hiddenUnmanaged)));
 }
 function printSessionTable(sessions, hiddenCount = 0, tree = false, liveIndex) {
     if (tree) {
@@ -1720,8 +1775,8 @@ export async function handlePickedSession(picked) {
  * Resume a session in the current terminal — a foreground takeover of this
  * process. Used by the single-select picker and by `sessions resume` when the
  * chosen destination is "in place" (unknown emulator / off-macOS, single pick).
- * Falls back to the current version via `/continue` when the version-pinned
- * binary is missing (ENOENT).
+ * Falls back to the same resume invocation against the current version when the
+ * version-pinned launcher is genuinely missing.
  */
 export async function resumeSessionInPlace(session) {
     const cwd = session.cwd && fs.existsSync(session.cwd)
@@ -1738,11 +1793,17 @@ export async function resumeSessionInPlace(session) {
     // agent shim is a `.cmd`/`.ps1` and, under the shell needed to run it (see
     // spawnResumeCommand), a missing command exits non-zero rather than emitting
     // an ENOENT `error` event — so detect a removed version here instead of
-    // relying on that event, keeping the /continue fallback working on every OS.
-    if (!findExecutable(resume[0]) && session.version) {
+    // relying on that event, keeping the fallback working on every OS.
+    // `resume[0]` is an absolute alias path when one exists on disk, so only a bare
+    // name still needs a PATH lookup. Checking existsSync first is what keeps an
+    // isolated install (shims deliberately off PATH) out of the fallback.
+    const launcherFound = path.isAbsolute(resume[0])
+        ? fs.existsSync(resume[0])
+        : !!findExecutable(resume[0]);
+    if (!launcherFound && session.version) {
         const fallback = buildFallbackCommand(session);
         if (fallback) {
-            console.log(chalk.gray(`Version ${session.version} is not installed. Falling back to current version via /continue...`));
+            console.log(chalk.gray(`Version ${session.version} is not installed. Resuming with the current version instead...`));
             await spawnResumeCommand(fallback, cwd);
             return;
         }
@@ -1819,18 +1880,55 @@ function spawnResumeCommand(cmd, cwd) {
  * If the versioned binary is missing (version was removed), the ENOENT
  * handler in handlePickedSession retries via buildFallbackCommand.
  */
+/**
+ * The agent's own resume invocation, given whichever launcher we resolved.
+ * Keeping the verb in one place is what lets the version-pinned and fallback
+ * paths stay in agreement — they previously drifted into `/continue`, which is
+ * not a command either CLI has.
+ */
+function resumeArgv(agent, id, launcher) {
+    switch (agent) {
+        case 'claude': return [launcher, '--resume', id];
+        case 'codex': return [launcher, 'resume', id];
+        case 'opencode': return [launcher, '--session', id];
+        default: return null;
+    }
+}
+/**
+ * Absolute path of the on-disk versioned alias, or null when it isn't there.
+ *
+ * Resume must not resolve `<cli>@<version>` by bare name. The shims directory is
+ * deliberately absent from PATH for an isolated install — that is precisely what
+ * `--isolated` promises — so a PATH lookup can never find the alias, and resume
+ * degraded to the fallback 100% of the time for isolated copies. Mirrors the
+ * resolution `buildExecCommand` already does for `agents run`.
+ */
+function versionedAliasIfPresent(agent, version) {
+    const cli = AGENTS[agent]?.cliCommand ?? agent;
+    const base = path.join(getShimsDir(), `${cli}@${version}`);
+    if (process.platform === 'win32' && fs.existsSync(`${base}.cmd`))
+        return `${base}.cmd`;
+    if (fs.existsSync(base))
+        return base;
+    return null;
+}
 export function buildResumeCommand(session) {
     switch (session.agent) {
-        case 'claude':
-            if (session.version)
-                return [`claude@${session.version}`, '--resume', session.id];
-            return ['claude', '--resume', session.id];
-        case 'codex':
-            if (session.version)
-                return [`codex@${session.version}`, 'resume', session.id];
-            return ['codex', 'resume', session.id];
+        // opencode sessions are shared across versions, so resume is deliberately NOT
+        // version-pinned — it always goes through the plain launcher.
         case 'opencode':
-            return ['opencode', '--session', session.id];
+            return resumeArgv('opencode', session.id, 'opencode');
+        case 'claude':
+        case 'codex': {
+            const cli = AGENTS[session.agent]?.cliCommand ?? session.agent;
+            if (session.version) {
+                const alias = versionedAliasIfPresent(session.agent, session.version);
+                // Absolute path when the alias exists; otherwise the bare versioned name,
+                // which still resolves for a non-isolated install whose shims are on PATH.
+                return resumeArgv(session.agent, session.id, alias ?? `${cli}@${session.version}`);
+            }
+            return resumeArgv(session.agent, session.id, cli);
+        }
         case 'gemini':
         case 'antigravity':
         case 'openclaw':
@@ -1843,13 +1941,18 @@ export function buildResumeCommand(session) {
             return null;
     }
 }
-/** Fallback resume command when the versioned binary is unavailable (ENOENT). */
+/**
+ * Fallback when the pinned version really is gone: the same resume invocation
+ * against the current version.
+ *
+ * This used to spawn `<cli> "/continue <id>"`, feeding a slash command into the
+ * TUI as a prompt. Neither CLI has `/continue` — codex documents `/resume` — so
+ * the agent received an unrecognised command and the session was not resumed at
+ * all. Reusing resumeArgv keeps the two paths from drifting apart again.
+ */
 function buildFallbackCommand(session) {
-    switch (session.agent) {
-        case 'claude': return ['claude', `/continue ${session.id}`];
-        case 'codex': return ['codex', `/continue ${session.id}`];
-        default: return null;
-    }
+    const cli = AGENTS[session.agent]?.cliCommand ?? session.agent;
+    return resumeArgv(session.agent, session.id, cli);
 }
 // ---------------------------------------------------------------------------
 // Cloud session source (--cloud)
@@ -1956,6 +2059,51 @@ function formatSearchMessage(options) {
         return 'Search sessions:';
     return `Search sessions (${filters.join(', ')}):`;
 }
+/**
+ * The single entry point for turning a `sessions <query>` argument into rows.
+ *
+ * A complete session id resolves by id alone. Anything else keeps the existing
+ * ladder: id lookup first (so a short id still wins), then the ranked
+ * metadata+content search.
+ */
+export function resolveSessionQuery(pool, query) {
+    // Normalize ONCE here. isCompleteSessionId trims but resolveSessionById does
+    // not, so a padded id ("<uuid> ", e.g. pasted from a terminal) would classify
+    // as complete and then miss the id lookup — reporting a session that IS on
+    // this machine as absent.
+    const normalized = query.trim();
+    const completeId = isCompleteSessionId(normalized);
+    const byIdMatches = resolveSessionById(pool, normalized);
+    if (byIdMatches.length > 0)
+        return { matches: byIdMatches, byId: true, completeId };
+    if (completeId) {
+        // The pool is only what discoverSessions walked — a minority of the index
+        // (measured: 2,798 of 7,614 rows), because it re-reads live agent homes and
+        // skips whole classes of indexed session. Declaring absence from the pool
+        // alone denied 1,315 sessions whose transcript is on this disk right now.
+        // Ask the index itself, the same authoritative lookup `fork` and `exec` use.
+        return { matches: findSessionsById(normalized), byId: true, completeId };
+    }
+    return { matches: filterSessionsByQuery(pool, normalized), byId: false, completeId };
+}
+/** Explain an ambiguous resolution. Only a short id can be lengthened: a complete
+ * id is already maximal, and a search phrase was never an id to begin with. */
+function ambiguityHint(byId, completeId) {
+    if (completeId)
+        return 'That is already a complete id — these rows share it as a prefix.';
+    return byId
+        ? 'Pass a longer ID to narrow it down.'
+        : 'That matched on text, not an id. Pass a session id, or narrow the search.';
+}
+/** Explain a complete-id miss, which no local rephrasing can fix. Echoes the
+ * normalized id so a pasted, padded argument doesn't produce an unrunnable hint. */
+function notFoundByIdMessage(query) {
+    const id = query.trim();
+    return [
+        chalk.red(`No session with id ${id} on this machine.`),
+        chalk.gray(`Search the fleet with: agents sessions ${id} --device <host>`),
+    ];
+}
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export function filterSessionsByQuery(sessions, query) {
     const trimmed = query?.trim().toLowerCase() || '';
@@ -2086,11 +2234,13 @@ async function renderArtifactsGlobal(query, listAll, name, scope) {
         });
         tracker.stop();
         const allSessions = applyScopeFilters(discovered, scope);
-        const matches = resolveSessionById(allSessions, query);
-        const queryMatches = matches.length > 0 ? matches : filterSessionsByQuery(allSessions, query);
+        const { matches: queryMatches, byId, completeId } = resolveSessionQuery(allSessions, query);
         if (queryMatches.length === 0) {
             spinner.stop();
-            console.error(chalk.red(`No session found matching: ${query}`));
+            if (completeId)
+                notFoundByIdMessage(query).forEach(l => console.error(l));
+            else
+                console.error(chalk.red(`No session found matching: ${query}`));
             process.exit(1);
         }
         if (queryMatches.length > 1) {
@@ -2099,7 +2249,7 @@ async function renderArtifactsGlobal(query, listAll, name, scope) {
             for (const m of queryMatches.slice(0, 10)) {
                 console.error(chalk.cyan(`  ${m.shortId}  ${m.id}  ${m.label ?? m.topic ?? ''}`));
             }
-            console.error(chalk.gray('Pass a longer ID to narrow it down.'));
+            console.error(chalk.gray(ambiguityHint(byId, completeId)));
             process.exit(1);
         }
         spinner.stop();
@@ -2127,13 +2277,20 @@ async function renderOneSession(query, mode, scope) {
         tracker.stop();
         const allSessions = applyScopeFilters(discovered, scope);
         let session;
-        const matches = resolveSessionById(allSessions, query);
-        let queryMatches = matches.length > 0 ? matches : filterSessionsByQuery(allSessions, query);
-        if (queryMatches.length === 0) {
+        const resolution = resolveSessionQuery(allSessions, query);
+        let queryMatches = resolution.matches;
+        let byId = resolution.byId;
+        const completeId = resolution.completeId;
+        // Widen to the transcript content index only for a genuine search phrase. A
+        // complete id is unique, so widening could only ever surface a DIFFERENT
+        // session that happens to mention the id — which is what made `sessions
+        // <uuid>` render an unrelated transcript.
+        if (queryMatches.length === 0 && !completeId) {
             const contentResults = searchContentIndex(allSessions, query);
             if (contentResults.size > 0) {
                 const matchedSessions = Array.from(contentResults.values())
                     .sort((a, b) => (b._bm25Score ?? 0) - (a._bm25Score ?? 0));
+                byId = false;
                 if (matchedSessions.length === 1) {
                     session = matchedSessions[0];
                 }
@@ -2155,6 +2312,10 @@ async function renderOneSession(query, mode, scope) {
                     process.exit(1);
                 }
             }
+            else if (completeId) {
+                notFoundByIdMessage(query).forEach(l => console.error(l));
+                process.exit(1);
+            }
             else {
                 console.error(chalk.red(`No session found matching: ${query}`));
                 console.error(chalk.gray('Run "agents sessions" to browse sessions.'));
@@ -2168,7 +2329,7 @@ async function renderOneSession(query, mode, scope) {
                 for (const match of queryMatches.slice(0, 10)) {
                     console.error(chalk.cyan(`  ${match.shortId}  ${match.id}  ${match.label ?? match.topic ?? ''}`));
                 }
-                console.error(chalk.gray('Pass a longer ID to narrow it down.'));
+                console.error(chalk.gray(ambiguityHint(byId, completeId)));
                 process.exit(1);
             }
             else {
@@ -2205,6 +2366,7 @@ export function registerSessionsCommands(program) {
         .option('--grok', 'Shorthand for --agent grok')
         .option('--opencode', 'Shorthand for --agent opencode')
         .option('--all', 'Include sessions from every directory (not just current project)')
+        .option('--unmanaged', "Also show sessions from your own ~/.<agent> installs (hidden once agents-cli manages that agent)")
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--routine', 'Show only sessions archived from routine runs')
         .option('-p, --project <name>', 'Filter by project name (searches across all directories)')
@@ -2293,9 +2455,13 @@ export function registerSessionsCommands(program) {
     registerSessionsResumeCommand(sessionsCmd);
     registerGoCommand(sessionsCmd);
     registerFocusCommand(sessionsCmd);
+    registerDetachCommand(sessionsCmd);
+    registerAttachCommand(sessionsCmd);
     registerSessionsInjectCommand(sessionsCmd);
     registerSessionsExportCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
+    registerSessionsMigrateCommand(sessionsCmd);
+    registerSessionsMigrationsCommand(sessionsCmd);
 }
 function formatNoSessionsMessage(showAll, project) {
     const projectQuery = project?.trim();
@@ -2307,6 +2473,10 @@ function formatNoSessionsMessage(showAll, project) {
     const command = 'agents sessions --all';
     return `No sessions found for ${process.cwd()}. Run "${command}" to see sessions from every directory.`;
 }
+function formatUnmanagedHiddenFooter(hiddenCount) {
+    const noun = hiddenCount === 1 ? 'session' : 'sessions';
+    return `(${hiddenCount} ${noun} from your own unmanaged installs hidden — use --unmanaged to show)`;
+}
 function formatTeamHiddenFooter(hiddenCount) {
     const noun = hiddenCount === 1 ? 'team session' : 'team sessions';
     return `(${hiddenCount} ${noun} hidden — use --teams to show, or \`agents teams status\`)`;

package/dist/commands/setup-computer.js

@@ -37,7 +37,7 @@ export async function runComputerWizard() {
         return false;
     }
     // 1. Download + verify + install the signed, notarized helper.
-    console.log(chalk.bold('Installing the Computer Helper...'));
+    console.log(chalk.bold('Installing the Agents Computer helper...'));
     try {
         await installComputerHelperMacLocal();
     }
@@ -57,7 +57,7 @@ export async function runComputerWizard() {
     }
     // 3. Guide the two permission grants if not already trusted.
     if (!trusted) {
-        console.log(chalk.bold('\nGrant two permissions to "Computer Helper" (one-time):'));
+        console.log(chalk.bold('\nGrant two permissions to "Agents Computer" (one-time):'));
         console.log('  1. ' + chalk.cyan('Accessibility') + chalk.dim('     — lets it click/type'));
         console.log('  2. ' + chalk.cyan('Screen Recording') + chalk.dim('  — lets it screenshot windows'));
         console.log(chalk.dim('\nOpening System Settings > Privacy & Security ...'));

package/dist/commands/setup.js

@@ -16,7 +16,7 @@ import { isGitRepo, cloneIntoExisting, pullRepo } from '../lib/git.js';
 import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
 import { AGENTS, agentConfigDirName, getUnmanagedAgentInstalls, countSessionFiles, agentLabel } from '../lib/agents.js';
 import { setGlobalDefault } from '../lib/versions.js';
-import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions } from '../lib/shims.js';
+import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions, assertIsolationBoundary } from '../lib/shims.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSetupBrowserCommand, runBrowserWizard } from './setup-browser.js';
 import { registerSetupComputerCommand, runComputerWizard } from './setup-computer.js';
@@ -29,6 +29,11 @@ const HOME = os.homedir();
  */
 async function importAgent(agentId, version) {
     const agent = AGENTS[agentId];
+    // setup has its own hand-rolled adoption (rename + symlink inline, rather than
+    // calling switchConfigSymlink), so the primitive gates never see it. Check the
+    // boundary here, before the first mkdirSync — which would otherwise create the
+    // scaffolding this very check reads.
+    assertIsolationBoundary(agentId, 'adopt your existing install');
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
     const versionHome = path.join(versionsDir, agentId, version, 'home');