@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/commands/focus.js

@@ -1,26 +1,13 @@
-/**
- * `agents sessions focus [id]` — take me to a live session, however it's reachable.
- *
- * Same detection as `go`, but where `go` *refuses* an un-attachable session,
- * `focus` **opens a new tab and resumes it** — locally, or on the remote over SSH
- * (via the terminal launch engine's `openSurfaces`, `host` = the peer). So:
- *   - in tmux (local/remote)   -> attach the live pane (join it, no fork)
- *   - in Ghostty               -> focus its tab
- *   - headless / plain / etc.  -> new tab + `resume` (a copy if it's mid-run — the
- *                                  original keeps going; a clean continue if it's idle)
- *
- * NOTE: joining a live process without forking is only possible via tmux — that's
- * why `--tmux`-wrapped launches are worth it for sessions you'll want back live.
- */
 import fs from 'node:fs';
 import chalk from 'chalk';
 import { confirm } from '@inquirer/prompts';
 import { gatherLiveTargets, pickLiveTarget, pickLiveTargets, jumpTo, probeAttachRail, refuseFallback } from './go.js';
 import { sessionProcessIsLocal, sessionProcessHost, shortIdFromName } from '../lib/session/active.js';
-import { isAgentTmuxAlias } from '../lib/session/types.js';
+import { isAgentTmuxAlias } from '@phnx-labs/sessions-cli/reader';
 import { attachLocalLiveSelector } from '../lib/session/local-tmux-attach.js';
 export { looksLikeTmuxAlias, resolveTmuxAliasState, shouldAttachLocalTmuxAliasBeforeFleet } from '../lib/session/local-tmux-attach.js';
-import { buildSessionRecoveryCommand, filterSessionsByQuery, formatLiveStatusHeadline, formatPickerLabel, isRunningLiveSession, pickerColumnsFor, resumeSessionInPlace, resolveSessionMetadataValue, resolveSessionAgentName, requestedLiveStatuses, } from './sessions.js';
+import { buildSessionRecoveryCommand, filterSessionsByQuery, formatLiveStatusHeadline, formatPickerLabel, isRunningLiveSession, pickerColumnsFor, resumeSessionInPlace, resolveSessionMetadataValue, resolveSessionAgentName } from './sessions.js';
+import { requestedLiveStatuses } from './ps-roster.js';
 import { resolveBackend, CONFIRM_THRESHOLD } from './sessions-resume.js';
 import { runOnPeer } from '../lib/session/remote-list.js';
 import { discoverSessions, resolveIndexedSessionById } from '../lib/session/discover.js';
@@ -42,9 +29,6 @@ const INHERITED_FOCUS_OPTIONS = [
     'working', 'idle', 'waiting', 'orphan', 'orphaned', 'crashed',
     'closed', 'abandoned', 'queued', 'unknown',
 ];
-/** Commander gives overlapping `sessions` flags to the parent command, even
- * when they appear after `focus`. Fold only values explicitly provided there
- * into the child options; child defaults (limit/sort) otherwise stay intact. */
 export function inheritFocusOptions(child, parent) {
     if (!parent)
         return child;
@@ -57,11 +41,9 @@ export function inheritFocusOptions(child, parent) {
     }
     return merged;
 }
-/** Collect device targets from `--device`; repeatable. Returns a host list. */
 export function mergeFocusHosts(opts) {
     return [...(opts.device ?? [])];
 }
-/** Picker header that reflects the active filter + device, e.g. "Focus orphaned sessions on yosemite-s0:". */
 export function focusHeader(statuses, hosts) {
     const where = hosts.length ? ` on ${hosts.join(', ')}` : '';
     if (statuses.length === 0)
@@ -69,18 +51,13 @@ export function focusHeader(statuses, hosts) {
     const word = statuses.length === 1 ? statusWord(statuses[0]) : 'filtered';
     return `Focus ${word} sessions${where}:`;
 }
-/** The adjective shown in the header for a single live-state filter. */
 function statusWord(status) {
     return status === 'orphaned' ? 'orphaned' : status;
 }
-export function registerFocusCommand(program) {
+export function registerFocusCommand(program, opts = {}) {
+    const group = opts.group ?? 'sessions';
     const cmd = program
-        // Hidden, but deliberately NOT warned. `sessions resume <id>` dispatches by
-        // spawning `agents sessions focus <id>` (buildSessionLifecycleArgs), so a
-        // deprecation notice here would print on every ordinary resume. focus is now
-        // the internal lifecycle dispatcher; `resume` is the surface. Do not add a
-        // console.warn here without first removing that delegation.
-        .command('focus', { hidden: true })
+        .command('focus', { hidden: opts.hidden ?? true })
         .argument('[selector]', 'Session id/prefix, agent@version, or topic/path search')
         .option('--launch-id <id>', 'Target the run by its launcher AGENT_LAUNCH_ID instead of a session id (resolved from this machine\'s hook records)')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
@@ -125,22 +102,22 @@ export function registerFocusCommand(program) {
     setHelpSections(cmd, {
         examples: `
       # Focus a session directly (attach a living pane, otherwise recover it)
-      agents sessions focus a1b2c3d4
+      agents ${group} focus a1b2c3d4
 
       # Multi-select live sessions; each opens as a tab in this terminal
-      agents sessions focus
+      agents ${group} focus
 
       # Scope the picker to one device's orphaned sessions
-      agents sessions focus --orphan --device yosemite-s0
+      agents ${group} focus --orphan --device yosemite-s0
 
       # Resolve latest on yosemite-s0, then pick from that version's sessions
-      agents sessions focus claude@latest --device yosemite-s0
+      agents ${group} focus claude@latest --device yosemite-s0
 
       # Attach only — refuse if nothing is joinable
-      agents sessions focus a1b2c3d4 --attach-only
+      agents ${group} focus a1b2c3d4 --attach-only
 
       # Pick from live sessions on this machine only
-      agents sessions focus --local
+      agents ${group} focus --local
     `,
         notes: `
       - space toggles a session, enter opens the selected set; a single check + enter opens just one.
@@ -157,39 +134,19 @@ export function registerFocusCommand(program) {
     `,
     });
 }
-/**
- * Which fallback fires when a session has no attach rail. `--attach-only` (the old
- * `go`) refuses; the default opens a new tab and resumes a copy. Pure so it's testable
- * without touching `jumpTo`'s side effects.
- */
 export function selectFallback(attachOnly) {
     return attachOnly ? refuseFallback : resumeInNewTab;
 }
 export async function focusAction(id, opts) {
-    // RUSH-3125: `--launch-id` names the run by the handle its launcher minted,
-    // and this box holds the hook record that maps it to the real session id — a
-    // local read, so it still works when the network that started the run is gone.
-    // Resolved up front into the ordinary id path: everything below, including the
-    // attach-else-resume recovery, is identical once we know which session it is.
     if (opts.launchId) {
         if (id) {
             console.error(chalk.red('Pass a session id or --launch-id, not both — they name the same thing two ways.'));
             process.exitCode = 1;
             return;
         }
-        // Read the launch-id index directly rather than through
-        // `resolveHookSessionRecord`: that helper kind-guards every hit, which exists
-        // to stop a REUSED PID crossing harnesses. A launch id is a per-launch uuid
-        // and cannot collide, and the caller here is a reattach that deliberately
-        // does not assume which harness the peer picked (`run auto` chooses it
-        // remotely), so demanding a kind would reject the exact case this serves.
         const { loadHookSessionIndex } = await import('../lib/session/hook-sessions.js');
         const resolved = loadHookSessionIndex().byLaunchId.get(opts.launchId)?.session_id;
         if (!resolved) {
-            // Fail loud: a launch id with no record means the harness never got far
-            // enough to write one (it died at startup, or it has no SessionStart
-            // hook). Silently opening the picker here would strand an automated
-            // reattach in an interactive prompt nobody is watching.
             console.error(chalk.red(`No session recorded for launch id ${opts.launchId} on ${machineId()}.`));
             console.error(chalk.gray('  The run may have failed before its SessionStart hook fired.'));
             console.error(chalk.gray('  Look for it:  agents sessions --active'));
@@ -200,15 +157,11 @@ export async function focusAction(id, opts) {
     }
     const hosts = mergeFocusHosts(opts);
     const statuses = requestedLiveStatuses(opts);
-    // A device scope needs the cross-host sweep; --local only wins when no host is named.
     const local = !!opts.local && hosts.length === 0;
     const fallback = selectFallback(opts.attachOnly);
     const agentSelector = focusAgentSelector(id, opts);
     let textSelector = id && !agentSelector ? id : undefined;
     const filtered = !!id || hasFocusFilters(opts, statuses);
-    // Preserve the fast live multi-picker for an unqualified `focus`. Every
-    // selector/filter path below uses the sessions browser's shared candidate
-    // pipeline and rich preview.
     if (filtered) {
         if (!isInteractiveTerminal() && !looksLikeIdentitySelector(textSelector)) {
             console.error(chalk.red('focus selectors need an interactive terminal; pass a session id for direct focus.'));
@@ -223,34 +176,13 @@ export async function focusAction(id, opts) {
             process.exitCode = 1;
             return;
         }
-        // A live local tmux alias — or a bare 8-hex short id naming exactly one
-        // live local pane — attaches immediately, before any fleet SSH.
-        // `collectSessionCandidates` fans out twice (transcript pool + live
-        // roster), so a selector that is already a pane on THIS box used to print
-        // two unreachable-device lists and stall on offline peers (~2 min measured
-        // on yosemite-s0 for `sessions resume ag-claude-0145ab8f --attach-only`)
-        // and only then attach. SES-41 / PHNX-3292: an alive `ag-<agent>-<8hex>`
-        // pane is attached by name; the pane is sufficient, no fleet SSH needed. A
-        // dead/absent pane falls through to id resolution.
         if (await attachLocalLiveSelector(textSelector, hosts)) {
             return;
         }
-        // RUSH-2477: an id selector for a LOCAL indexed session resolves against the
-        // WAL index alone — a plain read, no write-heavy discovery scan (none of
-        // `tryClaimScan`/`releaseScan`'s `BEGIN IMMEDIATE` writer lock) and no
-        // boot-time fleet SSH fan-out. This is the crash-restart storm path: dozens
-        // of `sessions resume <id>` at once must not each take the writer lock or
-        // dial the not-yet-up tailnet. A genuine miss, an ambiguous prefix, or a
-        // peer-owned row falls through to the fleet resolver below unchanged — the
-        // narrow win is the exact case the storm hits, with no behaviour change for
-        // a session that lives on another box.
         if (idLookup && hosts.length === 0 && looksLikeIdSelector(textSelector)) {
             const self = machineId();
             const localMatch = dedupeSessionsByLogicalId(await resolveIndexedSessionById(textSelector), self);
             if (localMatch.length === 1 && !sessionProcessHost(localMatch[0], self)) {
-                // Local live index only (ps/tmux, no fleet sweep) so a still-live pane is
-                // still joined instead of resumed as a copy; a crashed session has no live
-                // row and recovers in place.
                 const { activeById } = await gatherLiveTargets(true, { statuses: [] });
                 await focusResolvedSession(localMatch[0], activeById, self, fallback, opts.attachOnly === true, opts.reconnectReattach === true);
                 return;
@@ -282,12 +214,6 @@ export async function focusAction(id, opts) {
         let exact = idSelector
             ? dedupeSessionsByLogicalId(sessions.filter((session) => session.id.toLowerCase().startsWith(idSelector)), self)
             : [];
-        // Not live (or remote-scoped): an alias still carries the session's shortid,
-        // so resolve by THAT rather than handing the whole `ag-<agent>-<shortid>`
-        // string to the resolver — which treats an unmatched alias as a keyword
-        // query and answered `"ag-claude-dead5678" matches 200 sessions` for a pane
-        // whose process had simply exited. SES-41 requires an alias to resolve to one
-        // canonical session id.
         if (textSelector && isAgentTmuxAlias(textSelector)) {
             const short = shortIdFromName(textSelector);
             if (short) {
@@ -298,10 +224,6 @@ export async function focusAction(id, opts) {
         if (exact.length === 0 && textSelector && looksLikeIdentitySelector(textSelector)) {
             const outcome = await resolveSessionMetadataValue(textSelector, { local, hosts });
             if (outcome.kind === 'partial') {
-                // RUSH-2492: an unreachable peer is a warning, not a hard failure. The
-                // resolver already resolves an id found on the reachable fleet (SES-9a),
-                // so reaching here means the session was not found on any device we COULD
-                // reach — it may live on an unreachable peer, which we could not check.
                 const offline = outcome.failedPeers;
                 console.error(chalk.yellow(`Warning: ${offline.length} device(s) unreachable, not checked: ${offline.join(', ')}`));
                 console.error(chalk.red(`No session matching "${textSelector}" on any reachable device (${offline.length} unreachable, not checked).`));
@@ -319,15 +241,6 @@ export async function focusAction(id, opts) {
                 process.exitCode = 1;
                 return;
             }
-            // The fleet resolver is authoritative for an id/identity selector — the same
-            // one `resume`/`preview` use, and it already fanned out across the reachable
-            // fleet. Focus the session it found even when that session falls outside the
-            // candidate-pool DISPLAY filters (project scope, time window, device): those
-            // filters scope the browsable list, not an exact id lookup. Requiring the
-            // resolved row to ALSO be in the filtered pool is what made focusing a
-            // peer-owned (or older / other-project) session need `--device`. Prefer the
-            // pool's row when it carries the already-gathered live status, else fall back
-            // to the resolved metadata (focusResolvedSession hops to the owner from it).
             const filteredMatch = sessions.find((session) => session.id === outcome.session.id);
             exact = [focusTargetForResolved(filteredMatch, outcome.session)];
         }
@@ -363,7 +276,6 @@ export async function focusAction(id, opts) {
         return;
     }
     const header = focusHeader(statuses, hosts);
-    // --attach-only keeps the old `go` single-jump: pick one, attach it in place (or refuse).
     if (opts.attachOnly) {
         const target = await pickLiveTarget(activeById, self, header, 'focus');
         if (!target)
@@ -371,13 +283,11 @@ export async function focusAction(id, opts) {
         await jumpTo(target, self, fallback);
         return;
     }
-    // Default: multi-select → open each selected session as a tab in this terminal.
     const targets = await pickLiveTargets(activeById, self, header);
     if (targets.length === 0)
         return;
     await openFocusTabs(targets, self);
 }
-/** A retained pane is not attachable merely because tmux can still display it. */
 export function isAttachableLiveSession(session) {
     return isRunningLiveSession(session);
 }
@@ -404,28 +314,9 @@ function looksLikeIdentitySelector(selector) {
     return !!selector && (/^[0-9a-f][0-9a-f-]{5,}$/i.test(selector) ||
         isAgentTmuxAlias(selector));
 }
-/**
- * Rank two rows that are the same logical session, best first.
- *
- * Prefer the row that can actually be acted on: a real transcript over a
- * phantom index entry (a purged copy indexes with an empty `filePath`), then
- * this machine's copy over a peer mirror — resuming is machine-bound, so the
- * local row is the one whose harness state exists here.
- */
 function sessionRowRank(s, self) {
     return (s.filePath ? 4 : 0) + (self && s.machine === self ? 2 : 0) + (s._remote ? 0 : 1);
 }
-/**
- * Collapse rows that are the SAME logical session.
- *
- * A transcript syncs across the fleet, so one session appears once per machine
- * holding a copy. SES-IF-2a: "Synced copies sharing the same full id MUST count
- * as one logical session." `fleetCandidatesByQuery` already groups this way, but
- * this path filtered raw rows instead — so `focus <full-uuid>` answered
- * "is ambiguous (2 sessions). Use more of the id." with no longer id to give.
- * Measured on zion: one of the two rows had no transcript at all
- * ("Session transcript not available (file no longer exists). Path: ").
- */
 export function dedupeSessionsByLogicalId(rows, self) {
     const byId = new Map();
     for (const row of rows) {
@@ -482,15 +373,6 @@ async function pickFocusCandidates(sessions, liveById, initialSearch) {
         throw err;
     }
 }
-/**
- * The session to focus once an id/identity selector has resolved across the
- * fleet. Prefer the already-gathered candidate-pool row (it carries the live
- * status collected for the picker), but fall back to the resolver's own metadata
- * when the resolved session is not in the filtered pool — a peer-owned, older, or
- * other-project session that the display filters excluded. Returning the resolved
- * session there (instead of rejecting it) is what lets `focus <id>` reach a
- * peer-owned session without `--device`, matching `resume`/`preview`.
- */
 export function focusTargetForResolved(poolMatch, resolved) {
     return poolMatch ?? resolved;
 }
@@ -506,10 +388,6 @@ export async function focusResolvedSession(meta, liveById, self, fallback, attac
         return;
     }
     if (reconnectReattach) {
-        // The reconnect loop expected this pane to be alive. It isn't — the peer
-        // rebooted, tmux crashed, or the agent exited while the link was down.
-        // Warn before any recovery attempt (local resume OR remote hop) so the
-        // user always knows their original context was not directly recovered.
         console.error(chalk.yellow(`\nWarning: ${meta.shortId}'s pane is gone (reboot, tmux crash, or agent exited).`));
         console.error(chalk.gray(`  Prior context is in the transcript — starting recovery.\n` +
             `  To see what happened: agents sessions preview ${meta.shortId}`));
@@ -526,8 +404,6 @@ export async function focusResolvedSession(meta, liveById, self, fallback, attac
     }
     await resumeSessionInPlace(meta);
 }
-/** Focus one row selected by the shared session browser through the same
- * attach/recover decision as `agents sessions focus <id>`. */
 export async function focusSelectedSession(meta, active, self) {
     if (active && !active.sessionId) {
         if (isAttachableLiveSession(active)) {
@@ -555,7 +431,6 @@ function activeFromMeta(meta) {
         machine: meta.machine,
     };
 }
-/** Human scope suffix for the empty-pool message, e.g. " (orphaned on yosemite-s0)". */
 function describeScope(statuses, hosts) {
     const parts = [];
     if (statuses.length)
@@ -564,12 +439,6 @@ function describeScope(statuses, hosts) {
         parts.push(`on ${hosts.join(', ')}`);
     return parts.length ? ` (${parts.join(' ')})` : '';
 }
-/**
- * Shell that resolves a tmux pane to its session and attaches it — the exact form
- * `jumpTo` uses, minus the pre-select-window nicety, so a batch tab joins the live
- * session (a second client) without forking. Reused for local and (wrapped in ssh)
- * remote panes.
- */
 export function tmuxAttachScript(mux) {
     const sock = mux.socket ? `-S ${shellQuote(mux.socket)} ` : '';
     const p = shellQuote(mux.pane);
@@ -578,17 +447,10 @@ export function tmuxAttachScript(mux) {
         `sess=$(tmux ${sock}display-message -pt ${p} '#{session_name}' 2>/dev/null); ` +
         `exec tmux ${sock}attach-session -t "\${sess:-${p}}"`);
 }
-/**
- * Decide how one live session opens as a tab. Pure over the session + a
- * `resumeCommandFor` resolver (injected so the local version-pinned resume command
- * and the tests stay decoupled from `discoverSessions`).
- */
 export function planFocusSurface(s, self, resumeCommandFor, rail = { state: 'alive' }) {
     const remote = sessionProcessHost(s, self);
     const mux = s.provenance?.mux;
     const sid = shortId(s);
-    // Join rail = tmux only (local or remote over SSH). A new tab attaching the live
-    // tmux session is a second client: join, no fork.
     if (mux?.kind === 'tmux' && mux.pane && rail.state === 'alive') {
         const script = tmuxAttachScript({ socket: mux.socket, pane: mux.pane });
         if (remote) {
@@ -601,10 +463,7 @@ export function planFocusSurface(s, self, resumeCommandFor, rail = { state: 'ali
         }
         return { kind: 'attach', command: ['sh', '-c', shellQuote(script)], note: `attach ${mux.pane}` };
     }
-    // No join rail → resume a copy (never a silent drop).
     if (remote) {
-        // Recover ON the peer so health and installed versions are resolved where
-        // the transcript actually originated.
         const command = resumeCommandFor(s);
         if (!command)
             return { kind: 'skip', note: `${sid} has no recovery command` };
@@ -620,21 +479,16 @@ export function planFocusSurface(s, self, resumeCommandFor, rail = { state: 'ali
         return { kind: 'skip', note: `${sid} — ${s.kind} sessions can't be resumed, and it has no live tmux to join` };
     return { kind: 'resume', command: cmd, note: 'resume a copy (no live tmux to join)' };
 }
-/**
- * Open each selected live session as a tab: attach its live pane where one exists,
- * else resume a copy. Reuses `resume`'s backend resolution + flood guard.
- */
 export async function openFocusTabs(targets, self, deps = {}) {
     const open = deps.open ?? openSurfaces;
     const probe = deps.probe ?? probeAttachRail;
-    // Resolve rich indexed metas ONCE so local resume commands stay version-pinned.
     let byId = new Map((deps.metas ?? []).map((m) => [m.id, m]));
     if (!deps.metas) {
         try {
             const metas = await discoverSessions({ all: true, since: '90d', limit: 2000 });
             byId = new Map(metas.map((m) => [m.id, m]));
         }
-        catch { /* fall back to synthesized metas per session */ }
+        catch { }
     }
     const metaFor = (s) => byId.get(s.sessionId ?? '') ?? metaFromActive(s);
     const resumeCommandFor = (s) => {
@@ -647,7 +501,6 @@ export async function openFocusTabs(targets, self, deps = {}) {
         const rail = await probe(s, self);
         return { s, plan: planFocusSurface(s, self, resumeCommandFor, rail) };
     }));
-    // Skips are reported, never silently dropped.
     for (const p of planned)
         if (p.plan.kind === 'skip')
             console.log(chalk.yellow(`  skip ${p.plan.note}`));
@@ -659,14 +512,11 @@ export async function openFocusTabs(targets, self, deps = {}) {
     const backend = deps.backend ?? (await resolveBackend({}, currentContext(), openable.length));
     if (backend === 'cancel')
         return;
-    // Guard against opening a flood of live agents at once.
     if (openable.length > CONFIRM_THRESHOLD) {
         const proceed = await confirm({ message: `Open ${openable.length} sessions at once?`, default: false }).catch(() => false);
         if (!proceed)
             return;
     }
-    // No tab-capable terminal (off-macOS, not in tmux): fall back to the single
-    // foreground jump for the first, and say the rest need a tab-capable terminal.
     if (backend === 'inplace') {
         if (openable.length > 1) {
             console.log(chalk.yellow(`This terminal can't open tabs — jumping to the first; open in Ghostty/iTerm/tmux to focus several at once.`));
@@ -675,9 +525,6 @@ export async function openFocusTabs(targets, self, deps = {}) {
         return;
     }
     console.log(chalk.gray(`Opening ${openable.length} session${openable.length === 1 ? '' : 's'} in ${backend} (tabs)…`));
-    // Pass agent + sessionId so the vscodium-agent backend can stamp the tab
-    // chip without sniffing the local process tree (remote attach has no agent
-    // binary on this box — #2478).
     const results = await open(openable.map((p) => ({
         cwd: cwdFor(p.s, byId),
         command: p.plan.command,
@@ -697,7 +544,6 @@ export async function openFocusTabs(targets, self, deps = {}) {
     });
     console.log(chalk.gray(`\nOpened ${opened}/${openable.length} in ${backend}.`));
 }
-/** A real cwd for the tab: the session's indexed cwd if it still exists, else here. */
 function cwdFor(s, byId) {
     const cwd = byId.get(s.sessionId ?? '')?.cwd ?? s.cwd;
     return cwd && fs.existsSync(cwd) ? cwd : process.cwd();
@@ -705,7 +551,6 @@ function cwdFor(s, byId) {
 function shortId(s) {
     return (s.sessionId ?? '').slice(0, 8) || '-';
 }
-/** Minimal SessionMeta for a live session, enough for `buildResumeCommand` + placement. */
 export function metaFromActive(s) {
     return {
         id: s.sessionId ?? '',
@@ -716,7 +561,6 @@ export function metaFromActive(s) {
         cwd: s.cwd,
     };
 }
-/** Look up the rich indexed SessionMeta by id so `version` survives (version-pinned resume). */
 async function richMetaById(id) {
     try {
         const metas = await discoverSessions({ all: true, since: '90d', limit: 2000 });
@@ -726,23 +570,12 @@ async function richMetaById(id) {
         return undefined;
     }
 }
-/**
- * `focus`'s fallback for a session with no attach rail: reopen it and hand you to it.
- *   - remote → resume ON the peer over SSH (foreground) — the peer resolves the pinned
- *              version and holds the transcript, and `-tt` delivers you there.
- *   - local  → resume in a new tab in your terminal, version-pinned via the indexed meta.
- * Note: for a session that's still mid-run, this opens a COPY (the original keeps going);
- * only tmux can *join* a live one without forking (see the header).
- */
 const resumeInNewTab = async (s, remote) => {
     const id = s.sessionId ?? '';
     if (!id) {
         console.log(chalk.yellow('This session has no id to resume.'));
         return;
     }
-    // Remote: the transcript + pinned version live on the peer, so resume THERE over SSH.
-    // runOnPeer runs `agents sessions resume <id>` with a real TTY (`-tt`) in the foreground —
-    // it actually delivers you to the session (the peer picks the right version + HOME).
     if (remote) {
         console.log(chalk.gray(`${shortId(s)} has no live terminal on ${remote} — resuming it there over SSH…`));
         const rc = await runOnPeer(sessionRecoveryRunArgs({ id }), remote, { tty: true, sessionId: id });
@@ -752,15 +585,12 @@ const resumeInNewTab = async (s, remote) => {
         }
         return;
     }
-    // Local: resume in a new tab. Use the indexed meta so the version-pinned binary
-    // resumes in the same isolated HOME the transcript was written in.
     const meta = (await richMetaById(id)) ?? metaFromActive(s);
     const command = buildSessionRecoveryCommand(meta);
     const cwd = meta.cwd && fs.existsSync(meta.cwd) ? meta.cwd : process.cwd();
     const ctx = currentContext();
     const backend = detectCurrentBackend(ctx) ?? availableBackends(ctx)[0]?.id;
     if (!backend) {
-        // No tab-capable surface (off-macOS, not in tmux) — resume in this process.
         await resumeSessionInPlace(meta);
         return;
     }

package/dist/commands/fork.d.ts

@@ -2,39 +2,18 @@ import type { Command } from 'commander';
 interface ForkOptions {
     name?: string;
     device?: string;
-    /** Open the sibling in a real terminal tab instead of in-place; optional backend. */
     terminal?: string | boolean;
 }
-/**
- * The two process boundaries fork crosses — a preview subprocess (cross-fleet
- * resolve + digest) and the sibling launch. Injectable so the resolve→recap→run
- * argv logic is unit-tested without spawning real CLIs.
- */
 export interface ForkDeps {
-    /** Run `agents sessions preview <sub…>` and capture stdout + exit status. */
     runPreview: (sub: string[]) => {
         status: number | null;
         stdout: string;
     };
-    /** Launch `agents <sub…>` inheriting stdio; returns its exit status. */
     launch: (sub: string[]) => {
         status: number | null;
     };
 }
-/**
- * Resolve the source cross-fleet, build a recap from its preview digest, and
- * launch a same-harness sibling seeded with that recap. Shared by
- * `agents sessions fork` and the `agents fork` alias.
- */
 export declare function runFork(sessionArg: string, options: ForkOptions, deps?: ForkDeps): Promise<void>;
-/**
- * Register `agents sessions fork <session>` — the canonical surface (fork is a
- * session operation, so it lives under the `sessions` group).
- */
 export declare function registerSessionsForkCommand(sessionsCmd: Command): void;
-/**
- * Register the hidden top-level `agents fork` alias. Kept working for back-compat
- * and muscle memory; the canonical, discoverable surface is `agents sessions fork`.
- */
 export declare function registerForkCommand(program: Command): void;
 export {};

package/dist/commands/fork.js

@@ -1,17 +1,3 @@
-/**
- * `agents sessions fork <session>` — branch an existing conversation into a new,
- * independent same-harness sibling, seeded with a recap so it picks up where the
- * original left off. The original is untouched. Also exposed as the hidden
- * top-level alias `agents fork` (back-compat).
- *
- * The source is resolved CROSS-FLEET (the same path `agents sessions preview`
- * uses), so a session that lives on another device forks fine — the sibling is
- * handed a plain-text recap as its opening input and never has to reach the
- * source transcript. Because the seed is text, any REPL harness can be forked,
- * not just Claude.
- *
- * Thin command layer; the pure recap text lives in `lib/session/fork.ts`.
- */
 import { spawnSync } from 'child_process';
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
@@ -21,13 +7,11 @@ function defaultDeps() {
     return {
         runPreview: (sub) => {
             const p = getCliLaunch(['sessions', 'preview', ...sub]);
-            // stderr inherited so preview's own resolution errors reach the user verbatim.
             const r = spawnSync(p.command, p.args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'inherit'] });
             return { status: r.status, stdout: r.stdout ?? '' };
         },
         launch: (sub) => {
             const l = getCliLaunch(sub);
-            // In-place stdio so the sibling takes over this terminal.
             const r = spawnSync(l.command, l.args, { stdio: 'inherit' });
             return { status: r.status };
         },
@@ -57,19 +41,7 @@ const FORK_HELP = {
     - Resolve the source the same way as resume: an exact or prefix id fragment.
   `,
 };
-/**
- * Resolve the source cross-fleet, build a recap from its preview digest, and
- * launch a same-harness sibling seeded with that recap. Shared by
- * `agents sessions fork` and the `agents fork` alias.
- */
 export async function runFork(sessionArg, options, deps = defaultDeps()) {
-    // Resolve + digest in one cross-fleet hop by shelling the existing preview
-    // verb: it resolves the id across the fleet (SSH fan-out + peer hop), computes
-    // the digest on the OWNING device, and prints it as JSON — so a remote source
-    // resolves fine and we never re-implement resolution or digesting here.
-    // --terminal opens a tab on THIS machine; --device dispatches over SSH. `agents
-    // run` refuses the combination, so reject it here with a fork-specific message
-    // before resolving anything, rather than after an overpromising progress line.
     if (options.device && options.terminal !== undefined) {
         console.error(chalk.red('Pick one placement: --terminal opens a tab here; --device places the sibling on another box. They cannot combine.'));
         process.exitCode = 1;
@@ -77,7 +49,6 @@ export async function runFork(sessionArg, options, deps = defaultDeps()) {
     }
     const res = deps.runPreview([sessionArg, '--json']);
     if (res.status !== 0) {
-        // preview already explained why on stderr; propagate its exit code.
         process.exitCode = res.status ?? 1;
         return;
     }
@@ -97,11 +68,6 @@ export async function runFork(sessionArg, options, deps = defaultDeps()) {
         return;
     }
     const digest = data?.preview ?? undefined;
-    // Most sessions have no explicit --name label; fall back to the shared headline
-    // ladder the rest of the CLI shows, not the raw short id. Pass `source` whole
-    // rather than re-listing fields: an object literal that omits `generatedTitle`
-    // still type-checks (the key is optional) and would silently drop the
-    // daemon-generated title rung — the PHNX-3797 bug shape.
     const label = forkLabelFor(source);
     const recap = buildForkRecap({
         agent: source.agent,
@@ -114,9 +80,6 @@ export async function runFork(sessionArg, options, deps = defaultDeps()) {
         lastAssistant: digest?.lastAssistant,
         changes: digest?.changes,
     });
-    // Launch a NEW same-harness session, load-balanced across accounts (balanced),
-    // seeded with the recap as its opening input. Runs here by default; --device
-    // places it on the fleet; --terminal opens it in a fresh tab where the user works.
     const runArgs = ['run', source.agent, recap, '-i', '--strategy', 'balanced', '--name', options.name || `fork of ${label}`];
     if (options.device)
         runArgs.push('--device', options.device);
@@ -130,10 +93,6 @@ export async function runFork(sessionArg, options, deps = defaultDeps()) {
     const child = deps.launch(runArgs);
     process.exitCode = child.status ?? 0;
 }
-/**
- * Register `agents sessions fork <session>` — the canonical surface (fork is a
- * session operation, so it lives under the `sessions` group).
- */
 export function registerSessionsForkCommand(sessionsCmd) {
     const cmd = sessionsCmd
         .command('fork <session>')
@@ -144,10 +103,6 @@ export function registerSessionsForkCommand(sessionsCmd) {
     setHelpSections(cmd, FORK_HELP);
     cmd.action((session, options) => runFork(session, options));
 }
-/**
- * Register the hidden top-level `agents fork` alias. Kept working for back-compat
- * and muscle memory; the canonical, discoverable surface is `agents sessions fork`.
- */
 export function registerForkCommand(program) {
     const cmd = program
         .command('fork <session>', { hidden: true })

package/dist/commands/funnel.d.ts

@@ -1,5 +1,2 @@
-/**
- * `agents daemon funnel` — thin Tailscale Funnel wrapper for webhook ingress nodes.
- */
 import type { Command } from 'commander';
 export declare function registerFunnelCommand(program: Command): void;