@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/commands/sessions.js

@@ -26,27 +26,33 @@ 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 { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList, linkUrl } from '../lib/session/render.js';
+import { linearIssueUrl } from '../lib/session/linear.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';
-import { sessionPicker, buildPreview } from './sessions-picker.js';
+import { sessionPicker, buildPreview, formatTodoCompact, githubRepoUrlFromCwd, } from './sessions-picker.js';
 import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 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 +182,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) {
@@ -218,15 +227,24 @@ export function cleanPreview(text) {
         .trim();
 }
 /**
- * Build the live description for an active session: prefer the state engine's
- * preview (the latest turn), then a user label, then the first-prompt topic.
+ * Build the live description for an active session: checklist progress (when
+ * present) plus the state engine's preview (the latest turn), a user label, or
+ * the first-prompt topic. Used by both the flat listing's `doing` cell and as
+ * the snippet half of the --active row (identity is layered on in printActiveRow).
+ *
+ * Covers every ActiveSession context: terminal (interactive), headless, teams,
+ * cloud, and sub-agent rows that share the same ActiveSession.todos field.
  */
 function buildSessionDescription(s) {
+    const todo = formatTodoCompact(s.todos);
     if (s.context === 'cloud') {
-        return cleanPreview(s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`);
+        const base = s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`;
+        return cleanPreview([todo, base].filter(Boolean).join(' · '));
     }
     if (s.context === 'teams') {
         const parts = [s.teamName];
+        if (todo)
+            parts.push(todo);
         if (s.preview)
             parts.push(s.preview);
         else if (s.label)
@@ -235,8 +253,53 @@ function buildSessionDescription(s) {
             parts.push(s.topic);
         return cleanPreview(parts.filter(Boolean).join(' · '));
     }
-    // Terminal or headless: prefer the live preview, then label, then topic.
-    return cleanPreview(s.preview || s.label || s.topic || '');
+    // Terminal, headless, or sub-agent: todos + live preview, then label, then topic.
+    const base = s.preview || s.label || s.topic || '';
+    return cleanPreview([todo, base].filter(Boolean).join(' · '));
+}
+/**
+ * Identity + checklist + live snippet for an --active / cross-machine row.
+ * Surfaces agent-adjacent identity the flat table already has (label, project)
+ * with a clickable project when a GitHub URL is resolvable, then the checklist
+ * tally and the latest-turn snippet.
+ *
+ * Free-text fields are cleaned individually; OSC 8 hyperlinks are applied
+ * *after* cleaning so `cleanPreview` does not strip the clickable targets
+ * (RUSH-2045 review). Ticket is clickable via {@link signalBadges}, not here,
+ * so the id is not printed twice.
+ */
+export function formatActiveRowDescription(s) {
+    const parts = [];
+    const pushText = (t) => {
+        const c = t ? cleanPreview(t) : '';
+        if (c)
+            parts.push(c);
+    };
+    if (s.context === 'teams' && s.teamName)
+        pushText(s.teamName);
+    if (s.label)
+        pushText(s.label);
+    // Project = basename(cwd), same derivation as serializeActiveSessionsForJson.
+    const project = s.cwd ? path.basename(s.cwd) : '';
+    if (project && project !== s.label && project !== s.teamName) {
+        const label = cleanPreview(project);
+        const repoUrl = githubRepoUrlFromCwd(s.cwd);
+        parts.push(repoUrl ? linkUrl(repoUrl, label) : label);
+    }
+    const todo = formatTodoCompact(s.todos);
+    if (todo)
+        parts.push(todo);
+    // Latest-turn snippet — avoid repeating label/topic when already used as identity.
+    if (s.context === 'cloud') {
+        pushText(s.preview || `${s.cloudProvider ?? ''}${s.cloudTaskId ? ` · ${s.cloudTaskId.slice(0, 12)}` : ''}`);
+    }
+    else if (s.preview) {
+        pushText(s.preview);
+    }
+    else if (!s.label && s.topic) {
+        pushText(s.topic);
+    }
+    return parts.filter(Boolean).join(' · ');
 }
 /** Short human word for a session's activity (falls back to the coarse status). */
 function activityLabel(s) {
@@ -274,7 +337,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 +351,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,
@@ -298,10 +380,15 @@ function signalBadges(s) {
         parts.push(chalk.yellow('ask'));
     else if (s.awaitingReason === 'permission')
         parts.push(chalk.yellow('perm'));
-    if (s.ticket)
-        parts.push(chalk.cyan(s.ticket.id));
-    if (s.pr)
-        parts.push(chalk.blue(`PR#${s.pr.number ?? '?'}`));
+    if (s.ticket) {
+        // Clickable when Linear workspace is resolvable (same helper as the picker header).
+        const url = linearIssueUrl(s.ticket.id);
+        parts.push(chalk.cyan(url ? linkUrl(url, s.ticket.id) : s.ticket.id));
+    }
+    if (s.pr) {
+        const label = `PR#${s.pr.number ?? '?'}`;
+        parts.push(chalk.blue(s.pr.url ? linkUrl(s.pr.url, label) : label));
+    }
     if (s.worktree)
         parts.push(chalk.magenta(`wt:${s.worktree.slug}`));
     return parts.join(' ');
@@ -316,8 +403,10 @@ function signalBadges(s) {
 function locatorBadge(s) {
     const p = s.provenance;
     const parts = [];
+    // An ssh-launched session shows where it was launched FROM when the client IP
+    // resolves to a registered device (`ssh←zion`); bare `ssh` when it doesn't.
     if (p?.transport === 'ssh')
-        parts.push(chalk.red('ssh'));
+        parts.push(chalk.red(p.origin ? `ssh←${p.origin.device}` : 'ssh'));
     if (p?.mux?.kind === 'tmux' && (s.tmuxTarget || p.mux.pane)) {
         parts.push(chalk.green(s.tmuxTarget ?? p.mux.pane));
         // For a tmux-hosted session, say which app+tab is looking at it right now
@@ -346,13 +435,17 @@ function locatorBadge(s) {
  * terminal width so the row never wraps.
  */
 function printActiveRow(s, indent) {
+    // shortId (8-char) · agent · host · status · badges · identity+todos+snippet
     const idCol = chalk.dim(padToWidth((s.sessionId?.slice(0, 8)) ?? '-', 9));
     const kindCol = colorAgent(s.kind)(padToWidth(truncateToWidth(s.kind, 8), 9));
     const hostCol = chalk.gray(padToWidth(truncateToWidth(s.host ?? '-', 8), 9));
     const statusCol = statusColor(s.status)(padToWidth(truncateToWidth(activityLabel(s), 8), 9));
     const fork = s.pidCount && s.pidCount > 1 ? chalk.dim(`×${s.pidCount} `) : '';
     const badges = (fork ? fork : '') + [signalBadges(s), locatorBadge(s)].filter(Boolean).join(' ');
-    const desc = buildSessionDescription(s) || '-';
+    // Identity (label/project/ticket clickable) + checklist + live snippet.
+    // Cross-machine rows use the same path — remote ActiveSession fields arrive
+    // via the SSH fan-out already populated (including todos when the peer has them).
+    const desc = formatActiveRowDescription(s) || '-';
     // Fill the remaining width with the preview so nothing wraps under tmux/SSH.
     const fixed = stringWidth(indent) + 9 + 9 + 9 + 9 + (badges ? stringWidth(badges) + 1 : 0);
     const room = Math.max(12, terminalWidth() - fixed - 1);
@@ -573,15 +666,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 +687,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 +845,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 +933,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 +1146,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 +1227,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 +1239,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 +1259,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 +1271,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;
@@ -1194,9 +1313,12 @@ function flatSessionRow(session, live, showTicket = false, cols = {}) {
     const tag = originTag(session) || teamTag(session);
     const label = session.label;
     const { glyph, preview } = liveGlyphAndPreview(live);
-    // A running session's live preview says what the agent is doing now; a
-    // resting one falls back to its opening topic.
-    const doing = preview || (tag ? `${tag}${session.topic ?? ''}` : session.topic);
+    // A running session's live preview (via liveGlyphAndPreview → buildSessionDescription)
+    // already folds in ActiveSession.todos. For resting / not-live rows, surface
+    // SessionMeta.todos when the scan attached it.
+    const restingTodo = !live ? formatTodoCompact(session.todos) : '';
+    const topicBase = tag ? `${tag}${session.topic ?? ''}` : session.topic;
+    const doing = [restingTodo, preview || topicBase].filter(Boolean).join(' · ') || undefined;
     const wt = session.worktreeSlug ? chalk.magenta(`wt:${session.worktreeSlug}`) : '';
     // The machine column only earns its width when the listing spans more than one
     // box (i.e. the cross-machine fan-out folded remotes in) — same rule and
@@ -1232,7 +1354,11 @@ function treeSessionRow(session, live) {
     const tag = originTag(session) || teamTag(session);
     const label = session.label;
     const { glyph, preview } = liveGlyphAndPreview(live);
-    const topic = (preview || (tag ? `${tag}${session.topic ?? ''}` : session.topic)) || '-';
+    // Match flatSessionRow: live preview already folds ActiveSession.todos; resting
+    // rows surface SessionMeta.todos when present (RUSH-2045).
+    const restingTodo = !live ? formatTodoCompact(session.todos) : '';
+    const topicBase = preview || (tag ? `${tag}${session.topic ?? ''}` : session.topic);
+    const topic = [restingTodo, topicBase].filter(Boolean).join(' · ') || '-';
     const badges = signalBadges(metaSignals(session));
     const badgeW = badges ? stringWidth(badges) + 1 : 0;
     const head = label ? `${label} · ${topic}` : topic;
@@ -1337,6 +1463,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) {
@@ -1597,10 +1725,18 @@ export function pickerColumnsFor(sessions) {
         showTicket: sessions.some((s) => ticketLabel(s) !== ''),
     };
 }
-export function formatPickerLabel(s, query, cols = {}) {
+export function formatPickerLabel(s, query, cols = {}, ssh) {
     const agentColor = colorAgent(s.agent);
     const when = formatRelativeTime(s.lastActivity ?? s.timestamp);
     const project = s.project || '-';
+    // SSH-launch origin (live rows only): mirrors the flat listing's `ssh←<device>`
+    // badge. Rendered as its OWN red segment before the topic cell — folding it into
+    // the topic string loses the colour, because renderTopicCell strips ANSI and
+    // re-whitens every slice. Its width is reserved from the topic budget below
+    // (exactly like `wt`), so the fixed-width columns stay aligned.
+    const sshPlain = ssh ? (ssh.device ? `ssh←${ssh.device} ` : 'ssh ') : '';
+    const sshSeg = sshPlain ? chalk.red(sshPlain) : '';
+    const sshW = sshPlain ? stringWidth(sshPlain) : 0;
     const tag = originTag(s) || teamTag(s);
     const label = s.label;
     const topic = tag ? `${tag}${s.topic ?? ''}` : s.topic;
@@ -1621,12 +1757,13 @@ export function formatPickerLabel(s, query, cols = {}) {
     const machineColW = cols.showMachine ? machineW : 0;
     const ticketW = cols.showTicket ? TICKET_W + 1 : 0;
     const wtW = wt ? stringWidth(wt) + 1 : 0;
-    const topicW = Math.max(16, terminalWidth() - gutter - (10 + 9 + 8 + 16) - machineColW - ticketW - wtW - stringWidth(when) - 1);
+    const topicW = Math.max(16, terminalWidth() - gutter - (10 + 9 + 8 + 16) - machineColW - ticketW - wtW - sshW - stringWidth(when) - 1);
     return (chalk.white(padRight(s.shortId, 10)) +
         agentColor(padRight(truncate(s.agent, 8), 9)) +
         chalk.yellow(padRight(truncate(versionStr, 7), 8)) +
         machineCell +
         chalk.cyan(padRight(truncate(project, 14), 16)) +
+        sshSeg +
         renderTopicCell(label, topic, query, topicW, topicW) +
         ticketCell +
         (wt ? wt + ' ' : '') +
@@ -1720,8 +1857,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 +1875,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 +1962,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 +2023,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 +2141,56 @@ function formatSearchMessage(options) {
         return 'Search sessions:';
     return `Search sessions (${filters.join(', ')}):`;
 }
+/**
+ * The single entry point for turning a `sessions <query>` argument into rows.
+ *
+ * An id-shaped query — a complete id OR a hex short-id/prefix (looksLikeSessionId)
+ * — resolves by id alone, through the index, and never falls back to content
+ * search (a bare id must not surface every transcript that merely mentions it).
+ * A genuine search phrase keeps 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 (looksLikeSessionId(normalized)) {
+        // Any id-shaped query — a complete id OR a bare hex short-id/prefix —
+        // resolves by id ONLY, never by content. The pool is 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, so a pool miss isn't absence:
+        // ask the index directly, the same authoritative lookup `fork` and `exec`
+        // use. And an id that resolves to nothing must report "no session with that
+        // id" — NOT fall back to fuzzy content search. A short id like "d3470b57"
+        // otherwise surfaces every transcript that merely MENTIONS the string (a
+        // resume prompt echoes the parent id into the body of many later sessions).
+        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 +2321,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 (byId)
+                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 +2336,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 +2364,23 @@ 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.
+        // ANY id-shaped query (a complete id OR a hex short-id/prefix) names a
+        // specific session; widening could only surface a DIFFERENT session that
+        // happens to MENTION the id — which is what made `sessions <uuid>` render an
+        // unrelated transcript and `sessions <shortid>` list every session that
+        // echoes the id in a resume prompt. Gate on looksLikeSessionId, not just
+        // completeId, so a short id resolves to "no match" rather than fuzzy content.
+        if (queryMatches.length === 0 && !looksLikeSessionId(query)) {
             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 +2402,10 @@ async function renderOneSession(query, mode, scope) {
                     process.exit(1);
                 }
             }
+            else if (byId) {
+                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 +2419,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 +2456,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)')
@@ -2215,10 +2467,10 @@ export function registerSessionsCommands(program) {
         .option('--markdown', 'Render the session as markdown (user, assistant, thinking, tool calls)')
         .option('--no-redact', 'Disable default secret redaction in rendered session output (--markdown and --json)')
         .option('--json', 'Output JSON (session list when browsing, event array when rendering one session)')
-        .option('--include <roles>', 'Only include these roles (comma-separated): user, assistant, thinking, tools')
+        .option('--include <roles>', 'Only include these roles (comma-separated): user, assistant, thinking, tools. "user" is genuine user turns only, not harness-injected scaffolding (bash-input, system-reminder)')
         .option('--exclude <roles>', 'Exclude these roles (comma-separated): user, assistant, thinking, tools')
-        .option('--first <n>', 'Keep only the first N turns (a turn starts at each user message)')
-        .option('--last <n>', 'Keep only the last N turns (a turn starts at each user message)')
+        .option('--first <n>', 'Keep only the first N turns (a turn starts at each genuine user message, not harness-injected scaffolding)')
+        .option('--last <n>', 'Keep only the last N turns (a turn starts at each genuine user message, not harness-injected scaffolding)')
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
@@ -2293,9 +2545,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 +2563,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\`)`;