@phnx-labs/agents-cli 1.22.22 → 1.22.23

package/dist/commands/focus.js

@@ -14,20 +14,51 @@
  */
 import fs from 'node:fs';
 import chalk from 'chalk';
-import { gatherLiveTargets, pickLiveTarget, jumpTo, refuseFallback } from './go.js';
-import { buildResumeCommand, resumeSessionInPlace } from './sessions.js';
-import { runOnPeer } from '../lib/session/remote-list.js';
+import { confirm } from '@inquirer/prompts';
+import { gatherLiveTargets, pickLiveTarget, pickLiveTargets, jumpTo, refuseFallback } from './go.js';
+import { requestedLiveStatuses, resolveSessionMetadataValue } from './sessions.js';
+import { resolveBackend, CONFIRM_THRESHOLD, resumeSelectorInPlace } from './sessions-resume.js';
 import { discoverSessions } from '../lib/session/discover.js';
+import { shellQuote, assertValidSshTarget } from '../lib/ssh-exec.js';
 import { openSurfaces, currentContext, availableBackends, detectCurrentBackend, } from '../lib/terminal/index.js';
 import { isInteractiveTerminal } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
+import { buildCanonicalResumeCommand } from '../lib/session/resume-command.js';
+/** `--device` is an alias of `--host`; both are repeatable. Merge into one host list. */
+export function mergeFocusHosts(opts) {
+    return [...(opts.host ?? []), ...(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)
+        return `Focus a live session${where}:`;
+    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) {
     const cmd = program
         .command('focus')
         .argument('[id]', 'Short/full session id to focus; omit for an interactive picker')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
         .option('--attach-only', 'Attach only — never open a new tab / resume a copy (the old `go` behavior)')
-        .description('Focus a live session — attach its terminal, or open a new tab and resume it')
+        .option('-H, --host <target...>', 'Scope the picker to live sessions on these devices (host alias or user@host; repeatable)')
+        .option('--device <target...>', 'Alias for --host (device alias from `agents devices`; repeatable)')
+        .option('--working', 'Only live sessions currently doing work')
+        .option('--idle', 'Only live sessions that have stopped between turns')
+        .option('--waiting', 'Only live sessions waiting on your input')
+        .option('--orphan', 'Only sessions whose process outlived its terminal client')
+        .option('--orphaned', 'Alias for --orphan')
+        .option('--crashed', 'Only sessions whose terminal disappeared with the process')
+        .option('--closed', 'Only recently observed sessions whose process exited normally')
+        .option('--abandoned', 'Only sessions with no transcript progress for the abandonment window')
+        .option('--queued', 'Only queued sessions that have not started running')
+        .option('--unknown', 'Only sessions whose live state cannot be determined')
+        .description('Focus live sessions — multi-select and open each as a tab (attach its pane, or resume a copy)')
         .action(async (id, opts) => {
         await focusAction(id, opts);
     });
@@ -36,6 +67,12 @@ export function registerFocusCommand(program) {
       # Jump to a live session (attach pane/tab, or open a new tab and resume)
       agents sessions focus a1b2c3d4
 
+      # Multi-select live sessions; each opens as a tab in this terminal
+      agents sessions focus
+
+      # Scope the picker to one device's orphaned sessions
+      agents sessions focus --orphan --device yosemite-s0
+
       # Attach only — refuse if nothing is joinable (old sessions go)
       agents sessions focus a1b2c3d4 --attach-only
 
@@ -43,6 +80,10 @@ export function registerFocusCommand(program) {
       agents sessions focus --local
     `,
         notes: `
+      - space toggles a session, enter opens the selected set; a single check + enter opens just one.
+      - Each selected session opens as a new tab in the terminal you're in (Ghostty / iTerm / tmux, auto-detected).
+      - A live tmux session is JOINED in the tab (a second client, no fork) — local or remote over SSH; a session with no attach rail resumes a copy in the tab, reported never silently dropped.
+      - --host/--device scopes the pool to those devices; the live-state filters (--orphan/--crashed/…) narrow by status and compose with the device scope.
       Lifecycle siblings (not synonyms):
         focus              live jump (default "take me there")
         focus --attach-only  attach only; never fork (replaces go)
@@ -61,24 +102,40 @@ export function selectFallback(attachOnly) {
     return attachOnly ? refuseFallback : resumeInNewTab;
 }
 export async function focusAction(id, opts) {
-    const { self, activeById } = await gatherLiveTargets(!!opts.local);
+    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 { self, activeById } = await gatherLiveTargets(local, { hosts, statuses });
     const fallback = selectFallback(opts.attachOnly);
     if (id) {
-        const q = id.toLowerCase();
-        const matches = [...activeById.values()].filter((s) => s.sessionId.toLowerCase().startsWith(q));
-        if (matches.length === 1) {
-            await jumpTo(matches[0], self, fallback);
+        const outcome = await resolveSessionMetadataValue(id.trim(), { local, hosts });
+        if (outcome.kind === 'partial') {
+            console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
+            process.exitCode = 2;
             return;
         }
-        if (matches.length > 1) {
-            console.error(chalk.red(`"${id}" is ambiguous (${matches.length} live matches). Use more of the id.`));
+        if (outcome.kind === 'ambiguous') {
+            console.error(chalk.red(`"${id}" matches ${outcome.candidates.length} sessions. Pass a longer id or alias.`));
             process.exitCode = 1;
             return;
         }
-        // Not live — it's a past session; resume is the right tool (multi-select + placement).
-        console.log(chalk.yellow(`No live session matching "${id}".`) +
-            chalk.gray(`\nTo resume a past session: agents sessions resume ${id}`));
-        process.exitCode = 1;
+        if (outcome.kind === 'not-found') {
+            console.error(chalk.red(`No session matching "${id}".`));
+            process.exitCode = 1;
+            return;
+        }
+        const live = activeById.get(outcome.session.id);
+        if (live && isAttachableLiveSession(live)) {
+            await jumpTo(live, self, fallback);
+            return;
+        }
+        if (opts.attachOnly) {
+            console.error(chalk.red(`${outcome.session.shortId} has no live terminal to attach.`));
+            process.exitCode = 1;
+            return;
+        }
+        await recoverResolvedSession(outcome.session);
         return;
     }
     if (!isInteractiveTerminal()) {
@@ -87,13 +144,152 @@ export async function focusAction(id, opts) {
         return;
     }
     if (activeById.size === 0) {
-        console.log(chalk.gray('No live sessions to focus. To resume a past one: agents sessions resume'));
+        const scope = describeScope(statuses, hosts);
+        console.log(chalk.gray(`No live sessions to focus${scope}. To resume a past one: agents sessions resume`));
         return;
     }
-    const target = await pickLiveTarget(activeById, self, 'Focus a live session:', 'focus');
-    if (!target)
+    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)
+            return;
+        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 session.pidAlive !== false && session.status !== 'closed' && session.status !== 'crashed';
+}
+async function recoverResolvedSession(session) {
+    const command = buildCanonicalResumeCommand(session.id);
+    const cwd = session.cwd && fs.existsSync(session.cwd) ? session.cwd : process.cwd();
+    const ctx = currentContext();
+    const backend = detectCurrentBackend(ctx) ?? availableBackends(ctx)[0]?.id;
+    if (!backend) {
+        await resumeSelectorInPlace(session.id);
         return;
-    await jumpTo(target, self, fallback);
+    }
+    console.log(chalk.gray(`${session.shortId} is not live — opening a ${backend} tab and resuming it.`));
+    const [result] = await openSurfaces([{ cwd, command }], { backend, packing: 'tabs' });
+    if (!result?.ok) {
+        console.error(chalk.red(`Failed to open ${session.shortId}: ${result?.error ?? 'unknown error'}`));
+        process.exitCode = 1;
+    }
+}
+/** Human scope suffix for the empty-pool message, e.g. " (orphaned on yosemite-s0)". */
+function describeScope(statuses, hosts) {
+    const parts = [];
+    if (statuses.length)
+        parts.push(statuses.map(statusWord).join('/'));
+    if (hosts.length)
+        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);
+    return (`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) {
+    const remote = s.machine && s.machine !== self ? s.machine : undefined;
+    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) {
+        const script = tmuxAttachScript({ socket: mux.socket, pane: mux.pane });
+        if (remote) {
+            assertValidSshTarget(remote);
+            return {
+                kind: 'attach',
+                command: ['ssh', '-tt', remote, shellQuote(script)],
+                note: `attach ${mux.pane} on ${remote}`,
+            };
+        }
+        return { kind: 'attach', command: ['sh', '-c', shellQuote(script)], note: `attach ${mux.pane}` };
+    }
+    // No join rail → the canonical command resolves the owner device itself.
+    const cmd = resumeCommandFor(s);
+    if (!cmd)
+        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;
+    // The canonical resume command resolves metadata itself; active cwd is enough
+    // to place the terminal without another transcript scan.
+    const byId = new Map();
+    const resumeCommandFor = (s) => s.sessionId ? buildCanonicalResumeCommand(s.sessionId) : null;
+    const planned = targets.map((s) => ({ s, plan: planFocusSurface(s, self, resumeCommandFor) }));
+    // Skips are reported, never silently dropped.
+    for (const p of planned)
+        if (p.plan.kind === 'skip')
+            console.log(chalk.yellow(`  skip ${p.plan.note}`));
+    const openable = planned.filter((p) => p.plan.kind !== 'skip');
+    if (openable.length === 0) {
+        console.log(chalk.gray('Nothing to open in the selection.'));
+        return;
+    }
+    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.`));
+        }
+        await jumpTo(openable[0].s, self, selectFallback(false));
+        return;
+    }
+    console.log(chalk.gray(`Opening ${openable.length} session${openable.length === 1 ? '' : 's'} in ${backend} (tabs)…`));
+    const results = await open(openable.map((p) => ({ cwd: cwdFor(p.s, byId), command: p.plan.command })), { backend, packing: 'tabs' });
+    let opened = 0;
+    results.forEach((r, i) => {
+        const p = openable[i];
+        if (r.ok) {
+            opened++;
+            console.log(chalk.green(`  opened ${shortId(p.s)}`) + chalk.gray(` — tab — (${p.plan.note})`));
+        }
+        else {
+            console.log(chalk.red(`  failed ${shortId(p.s)} — ${r.error}`));
+        }
+    });
+    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();
 }
 function shortId(s) {
     return (s.sessionId ?? '').slice(0, 8) || '-';
@@ -127,38 +323,21 @@ async function richMetaById(id) {
  * 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 resumeInNewTab = async (s) => {
     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(['sessions', 'resume', id], remote, { tty: true });
-        if (rc === 'no-target') {
-            console.log(chalk.red(`${remote} isn't reachable as a device. Try: agents devices sync`));
-            console.log(chalk.gray(`  or run it yourself: ssh ${remote} 'agents sessions resume ${shortId(s)}'`));
-        }
-        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.
+    // The canonical command resolves the source device and pinned launch metadata.
     const meta = (await richMetaById(id)) ?? metaFromActive(s);
-    const command = buildResumeCommand(meta);
-    if (!command) {
-        console.log(chalk.yellow(`${meta.shortId} — ${meta.agent} sessions aren't resumable, so there's no way to reopen it.`));
-        return;
-    }
+    const command = buildCanonicalResumeCommand(meta.id);
     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);
+        await resumeSelectorInPlace(meta.id);
         return;
     }
     console.log(chalk.gray(`${shortId(s)} has no live terminal to attach — opening a new ${backend} tab and resuming a copy.`));

package/dist/commands/fork.d.ts

@@ -1,9 +1,27 @@
 /**
- * `agents fork <session>` — branch an existing conversation into a new,
+ * `agents sessions fork <session>` — branch an existing conversation into a new,
  * independent session you can continue separately. The original is untouched.
+ * Also exposed as the hidden top-level alias `agents fork` (back-compat).
  *
  * Thin command layer; the copy/register logic lives in `lib/session/fork.ts`.
  */
 import type { Command } from 'commander';
-/** Register the top-level `agents fork` command. */
+interface ForkOptions {
+    name?: string;
+}
+/**
+ * Resolve the source session, copy it under a fresh id, and print how to
+ * continue the fork. Shared by `agents sessions fork` and the `agents fork` alias.
+ */
+export declare function runFork(sessionArg: string, options: ForkOptions): 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

@@ -3,71 +3,98 @@ import { setHelpSections } from '../lib/help.js';
 import { findSessionsById } from '../lib/session/db.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { forkSession, isForkableAgent, FORKABLE_AGENTS } from '../lib/session/fork.js';
-/** Register the top-level `agents fork` command. */
-export function registerForkCommand(program) {
-    const cmd = program
+const FORK_HELP = {
+    examples: `
+    # Fork a session by (partial) id, then continue the fork
+    agents sessions fork 4f3a9c21
+    agents sessions resume <new-id>
+
+    # Give the fork a name
+    agents sessions fork 4f3a9c21 --name "try redis instead"
+  `,
+    notes: `
+    - 'resume' continues the SAME conversation; 'fork' copies it under a new id so the two diverge.
+    - The fork is a full copy of the conversation so far; continuing it never touches the original.
+    - Resolve the session the same way as resume: an exact or prefix id fragment.
+    - Native copy currently supports: ${FORKABLE_AGENTS.join(', ')}. For other harnesses, branch by
+      starting a fresh agent and seeding it with '/continue <id>' — the source stays put.
+  `,
+};
+/**
+ * Resolve the source session, copy it under a fresh id, and print how to
+ * continue the fork. Shared by `agents sessions fork` and the `agents fork` alias.
+ */
+export async function runFork(sessionArg, options) {
+    // Resolve the source. Try the index first; only pay for a rescan if the id
+    // isn't found yet (mirrors the resume path's freshen-then-lookup).
+    let matches = findSessionsById(sessionArg, {});
+    if (matches.length === 0) {
+        await discoverSessions({});
+        matches = findSessionsById(sessionArg, {});
+    }
+    if (matches.length === 0) {
+        // Errors go to stderr and set a non-zero exit code so a script chaining on
+        // `agents sessions fork <id> && agents sessions resume <new>` doesn't proceed
+        // on a failed fork.
+        console.error(chalk.red(`No session matching "${sessionArg}".`));
+        console.error(chalk.gray('List candidates with: agents sessions'));
+        process.exitCode = 1;
+        return;
+    }
+    if (matches.length > 1) {
+        console.error(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
+        for (const m of matches.slice(0, 8)) {
+            console.error(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
+        }
+        process.exitCode = 1;
+        return;
+    }
+    const source = matches[0];
+    if (!isForkableAgent(source.agent)) {
+        // A native copy needs the agent's transcript to be resumable by id; harnesses
+        // without that can still be branched by hand. Fail loud with the manual path
+        // rather than a silent no-op or a fake copy.
+        console.error(chalk.yellow(`A native fork copy isn't supported for ${source.agent} sessions yet (supported: ${FORKABLE_AGENTS.join(', ')}).`));
+        console.error(chalk.gray(`  Branch it by hand — start a fresh ${source.agent} and seed it with the source's context:`));
+        console.error(chalk.gray(`    agents run ${source.agent} --terminal   # then, in the new session:`));
+        console.error(chalk.gray(`    /continue ${source.shortId}`));
+        process.exitCode = 1;
+        return;
+    }
+    let result;
+    try {
+        result = forkSession(source, { name: options.name });
+    }
+    catch (err) {
+        console.error(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));
+    console.log(chalk.gray(`  Label:    ${result.label}`));
+    console.log(chalk.gray(`  Continue: agents sessions resume ${result.shortId}`));
+    console.log(chalk.gray(`  Original ${source.shortId} is untouched.`));
+}
+/**
+ * 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>')
         .description('Branch a session into a new, independent copy you can continue separately. The original is untouched.')
         .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
-    setHelpSections(cmd, {
-        examples: `
-      # Fork a session by (partial) id, then continue the fork
-      agents fork 4f3a9c21
-      agents resume <new-id>
-
-      # Give the fork a name
-      agents fork 4f3a9c21 --name "try redis instead"
-    `,
-        notes: `
-      - 'resume' continues the SAME conversation; 'fork' copies it under a new id so the two diverge.
-      - The fork is a full copy of the conversation so far; continuing it never touches the original.
-      - Resolve the session the same way as resume: an exact or prefix id fragment.
-      - Currently supports: ${FORKABLE_AGENTS.join(', ')}. Other agents are a planned follow-up.
-    `,
-    });
-    cmd.action(async (sessionArg, options) => {
-        // Resolve the source. Try the index first; only pay for a rescan if the id
-        // isn't found yet (mirrors the resume path's freshen-then-lookup).
-        let matches = findSessionsById(sessionArg, {});
-        if (matches.length === 0) {
-            await discoverSessions({});
-            matches = findSessionsById(sessionArg, {});
-        }
-        if (matches.length === 0) {
-            // Errors go to stderr and set a non-zero exit code so a script chaining on
-            // `agents fork <id> && agents resume <new>` doesn't proceed on a failed fork.
-            console.error(chalk.red(`No session matching "${sessionArg}".`));
-            console.error(chalk.gray('List candidates with: agents sessions'));
-            process.exitCode = 1;
-            return;
-        }
-        if (matches.length > 1) {
-            console.error(chalk.yellow(`"${sessionArg}" is ambiguous — ${matches.length} sessions match. Use a longer id:`));
-            for (const m of matches.slice(0, 8)) {
-                console.error(chalk.gray(`  ${m.shortId}  ${m.agent}  ${m.label || m.topic || ''}`));
-            }
-            process.exitCode = 1;
-            return;
-        }
-        const source = matches[0];
-        if (!isForkableAgent(source.agent)) {
-            console.error(chalk.yellow(`fork does not support ${source.agent} sessions yet.`));
-            console.error(chalk.gray(`  Supported: ${FORKABLE_AGENTS.join(', ')}.`));
-            process.exitCode = 1;
-            return;
-        }
-        let result;
-        try {
-            result = forkSession(source, { name: options.name });
-        }
-        catch (err) {
-            console.error(chalk.red(`Could not fork ${source.shortId}: ${err.message}`));
-            process.exitCode = 1;
-            return;
-        }
-        console.log(chalk.green(`Forked ${source.shortId} -> ${result.shortId}`));
-        console.log(chalk.gray(`  Label:    ${result.label}`));
-        console.log(chalk.gray(`  Continue: agents resume ${result.shortId}`));
-        console.log(chalk.gray(`  Original ${source.shortId} is untouched.`));
-    });
+    setHelpSections(cmd, FORK_HELP);
+    cmd.action(runFork);
+}
+/**
+ * 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 })
+        .description('Alias for `agents sessions fork` — branch a session into a new, independent copy.')
+        .option('--name <label>', 'Label for the fork (default: "fork of <original>")');
+    cmd.action(runFork);
 }

package/dist/commands/go.d.ts

@@ -16,21 +16,46 @@
 import type { Command } from 'commander';
 import { type ActiveSession } from '../lib/session/active.js';
 import type { SessionMeta } from '../lib/session/types.js';
+import { type LiveStatusFilter } from './sessions.js';
 export declare function registerGoCommand(program: Command): void;
+/**
+ * Scope a live-session pool by device and live status. Pure so the `focus`
+ * device/status filters are unit-testable without touching the sweep. `hosts`
+ * keeps only sessions whose `machine` is in the set (local rows carry `self`,
+ * remote rows carry their peer tag); `statuses` reuses `--active`'s exact
+ * `matchesLiveStatus` derivation rather than a parallel status table.
+ */
+export declare function filterLivePool(sessions: ActiveSession[], opts?: {
+    hosts?: string[];
+    statuses?: LiveStatusFilter[];
+}): ActiveSession[];
 /**
  * Live jump targets (local + remote), keyed by session id. Cloud is excluded by
  * default (it has no local pid to attach), but `detach` opts in with
  * `includeCloud` so it can resolve a cloud id and refuse it with a clear message
  * instead of a bare "no live session".
+ *
+ * `hosts` scopes the sweep to named devices — the fan-out only dials them, and the
+ * pool is then filtered to `s.machine ∈ hosts` so a stray local row can't leak in.
+ * `statuses` narrows to the live-state words `--active` uses (orphan/crashed/…).
  */
 export declare function gatherLiveTargets(local: boolean, opts?: {
     includeCloud?: boolean;
+    hosts?: string[];
+    statuses?: LiveStatusFilter[];
 }): Promise<{
     self: string;
     activeById: Map<string, ActiveSession>;
 }>;
 /** Interactive pick over the live sessions' rich SessionMeta; returns the chosen live session. */
 export declare function pickLiveTarget(activeById: Map<string, ActiveSession>, self: string, message: string, enterHint: string): Promise<ActiveSession | null>;
+/**
+ * Multi-select over the live sessions' rich SessionMeta (same rows as
+ * `pickLiveTarget`, but a checkbox picker) — the plural sibling that lets `focus`
+ * open several sessions at once. Mirrors `sessions resume`'s `multiItemPicker`
+ * wiring; returns the chosen live sessions in pick order, or `[]` on cancel.
+ */
+export declare function pickLiveTargets(activeById: Map<string, ActiveSession>, self: string, message: string): Promise<ActiveSession[]>;
 /**
  * Map each live session to its rich SessionMeta (worktree/PR/changes/tools/tests
  * via the shared picker), reusing `discoverSessions`. Remote or unindexed live