@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/sessions-migrate.d.ts

@@ -1,37 +1,11 @@
 import type { Command } from 'commander';
-import type { SessionMeta } from '../lib/session/types.js';
-/** Agents whose sessions cannot be faithfully --resume'd (buildResumeCommand → null). */
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 type MigrateMode = 'resume' | 'rehydrate';
-export declare function registerSessionsMigrateCommand(sessionsCmd: Command): void;
-/**
- * Harness-parity gate (pure, testable). `buildResumeCommand` returns null for the
- * non-resumable agents (gemini, antigravity, openclaw, rush, hermes, grok, kimi,
- * droid) — for those a faithful --resume is impossible, so a requested `resume`
- * transparently becomes `rehydrate`. A resumable agent honors the request.
- * Returns the effective mode plus whether it was downgraded, so the caller can
- * print the notice.
- */
+export declare function registerSessionsMigrateCommand(sessionsCmd: Command, group?: 'sessions' | 'ps'): void;
 export declare function effectiveMode(source: SessionMeta, requested: MigrateMode): {
     mode: MigrateMode;
     downgraded: boolean;
 };
-/**
- * Pure. The remote shell commands that create the target's tmux session on the
- * SAME socket its reaper queries, and that probe its liveness afterward.
- *
- * `homeRelSocketPath` is `getDefaultSocketPath()` expressed relative to the
- * LOCAL home dir (`path.relative(os.homedir(), getDefaultSocketPath())`) — a
- * portable suffix, not a resolved absolute path, because the local and remote
- * HOME can differ (different user, different OS). It is spliced in after a
- * literal, unquoted `$HOME/` so the REMOTE shell resolves it; `$HOME` MUST
- * NEVER be resolved locally (see AGENTS.md's remote-path guidance).
- *
- * Extracted as a pure function so the "does the migrated session land on the
- * agents socket, not tmux's bare default socket" invariant is unit-testable
- * without an SSH round-trip (RUSH-2521 review — a bare `tmux` here made the
- * migrated agent's helpers invisible to `readAllPaneOwners`, so the reaper's
- * next tick killed the still-live, just-migrated agent as `tmux-session-gone`).
- */
 export declare function buildMigrateResumeCommands(opts: {
     sessionName: string;
     homeRelSocketPath: string;
@@ -42,15 +16,6 @@ export declare function buildMigrateResumeCommands(opts: {
     probeCmd: string;
     socketFlag: string;
 };
-/**
- * Rehydrate command: launch a fresh agent that reads the transcript. For a
- * non-resumable agent there is no faithful --resume, so we start the agent with
- * a prompt pointing it at the imported transcript path.
- */
 export declare function rehydrateCommand(source: SessionMeta): string[];
-/**
- * `agents sessions migrations` — the border tracker: the append-only ledger of
- * every session handed off to/from another machine (RUSH-1977).
- */
 export declare function registerSessionsMigrationsCommand(sessionsCmd: Command): void;
 export {};

package/dist/commands/sessions-migrate.js

@@ -1,27 +1,3 @@
-/**
- * `agents sessions migrate` (alias `relocate`) — relocate a RUNNING agent session
- * from this machine onto another (a fleet worker, a registered device, or a warm
- * ephemeral crabbox box), then stop the source so the interactive machine
- * reclaims its compute (RUSH-1977).
- *
- * This is orchestration glue over primitives that already exist — it does not
- * reinvent transport, resume, or scoring:
- *   - resolve the source session from the current tmux pane via `getActiveSessions()`
- *     (`provenance.mux.pane` matched against $TMUX_PANE);
- *   - pick / verify the target with the pure scorer in
- *     `lib/session/migrate-targets.ts` + `readyProbe()` / `bootstrapAgentsCli()`;
- *   - wrap up a dirty working tree (mechanical WIP-PR by default, or delegate a
- *     wrap-up turn to the running agent with --agent-wrapup);
- *   - ship the transcript with the SAME bundle pipeline as
- *     `sessions export --stdout | sessions import -`, over `sshExec`;
- *   - resume on the target through the SAME `openSurfaces({ backend:'tmux', host })`
- *     path `sessions resume --device` uses;
- *   - only AFTER the target's prompt is confirmed live, kill the source tmux
- *     session (`killSession`). --keep skips the kill (copy, not move).
- *
- * INVARIANT: the source is never killed before the transcript + branch are
- * confirmed on the target.
- */
 import * as os from 'os';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -49,7 +25,7 @@ import { itemPicker } from '../lib/picker.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { recordMigration, readMigrations } from '../lib/session/migrations.js';
-export function registerSessionsMigrateCommand(sessionsCmd) {
+export function registerSessionsMigrateCommand(sessionsCmd, group = 'sessions') {
     const cmd = sessionsCmd
         .command('migrate [session-id]')
         .alias('relocate')
@@ -63,16 +39,16 @@ export function registerSessionsMigrateCommand(sessionsCmd) {
     setHelpSections(cmd, {
         examples: `
       # Move the session in THIS pane onto the least-busy fleet worker
-      agents sessions migrate --auto
+      agents ${group} migrate --auto
 
       # Move a specific session onto a named host
-      agents sessions migrate a1b2c3d4 --device yosemite-s1
+      agents ${group} migrate a1b2c3d4 --device yosemite-s1
 
       # Spin up a fresh ephemeral box and move onto it
-      agents sessions migrate --lease
+      agents ${group} migrate --lease
 
       # Copy (don't stop the source), letting the agent wrap up its own dirty tree
-      agents sessions migrate --device box-a --keep --agent-wrapup
+      agents ${group} migrate --device box-a --keep --agent-wrapup
     `,
         notes: `
       - Without a [session-id], migrate resolves the session running in THIS tmux pane ($TMUX_PANE).
@@ -93,11 +69,6 @@ function fail(message) {
     console.error(chalk.red(message));
     process.exit(1);
 }
-/**
- * Resolve the session to migrate. With an explicit id, resolve it from the
- * on-disk index. Without one, match the current tmux pane ($TMUX_PANE) against a
- * live session's `provenance.mux.pane` and resolve that id to its SessionMeta.
- */
 async function resolveSourceSession(sessionId) {
     if (sessionId) {
         const all = await discoverSessions({ all: true, sortBy: 'timestamp', limit: 2000 });
@@ -125,12 +96,10 @@ async function resolveSourceSession(sessionId) {
         fail(`This pane's session (${active.sessionId}) is not in the index yet.`);
     return { meta: matches[0], active };
 }
-/** Live headroom for the scorer: prefer the disk stats-cache (fast, no ssh). */
 function statsByName() {
     const cache = readStatsCache();
     return new Map(Object.entries(cache));
 }
-/** Enumerate + rank targets, honoring --device / --auto / --lease. */
 async function resolveTarget(options, source) {
     const selfHostname = os.hostname();
     const ctx = {
@@ -142,17 +111,16 @@ async function resolveTarget(options, source) {
         return await provisionEphemeralTarget();
     }
     const hosts = await listAllHosts();
-    await loadDevices(); // ensure device registry is warmed (listAllHosts folds it in)
+    await loadDevices();
     let warm = [];
     try {
         warm = reusableBoxes(crabboxList(), Math.floor(Date.now() / 1000));
     }
     catch {
-        warm = []; // crabbox not configured — fleet-only targets
+        warm = [];
     }
     const stats = statsByName();
     if (options.device) {
-        // Explicit target: a fleet host/device, or a warm box slug.
         const box = warm.find((b) => b.slug === options.device);
         if (box) {
             return { name: box.slug, kind: 'ephemeral', os: 'linux', headroom: 'unknown', box };
@@ -173,7 +141,6 @@ async function resolveTarget(options, source) {
         console.log(chalk.gray(`Auto-selected ${best.name} (${best.kind}, ${best.headroom}).`));
         return best;
     }
-    // Interactive: rank the candidates and let the user pick.
     if (!isInteractiveTerminal()) {
         fail('Pass --auto, --device <name>, or --lease to choose a target (no interactive picker without a tty).');
     }
@@ -200,7 +167,6 @@ async function resolveTarget(options, source) {
         throw err;
     }
 }
-/** Provision a fresh ephemeral crabbox box (tailnet) and wait for it to be ready. */
 async function provisionEphemeralTarget() {
     console.log(chalk.gray('Provisioning a fresh ephemeral box (crabbox)…'));
     const leased = await crabboxWarmup({ netMode: 'tailscale' });
@@ -208,7 +174,6 @@ async function provisionEphemeralTarget() {
     console.log(chalk.green(`Leased box ${ready.slug}.`));
     return { name: ready.slug, kind: 'ephemeral', os: 'linux', headroom: 'idle', box: ready };
 }
-/** Resolve the SSH target string for a migrate target (host alias or box address). */
 function sshTargetForTarget(target) {
     if (target.kind === 'fleet' && target.host)
         return sshTargetFor(target.host);
@@ -220,28 +185,13 @@ function sshTargetForTarget(target) {
     }
     fail(`Cannot resolve an SSH target for ${target.name}.`);
 }
-/**
- * Harness-parity gate (pure, testable). `buildResumeCommand` returns null for the
- * non-resumable agents (gemini, antigravity, openclaw, rush, hermes, grok, kimi,
- * droid) — for those a faithful --resume is impossible, so a requested `resume`
- * transparently becomes `rehydrate`. A resumable agent honors the request.
- * Returns the effective mode plus whether it was downgraded, so the caller can
- * print the notice.
- */
 export function effectiveMode(source, requested) {
     const resumable = buildResumeCommand(source) !== null;
     if (!resumable && requested === 'resume')
         return { mode: 'rehydrate', downgraded: true };
     return { mode: requested, downgraded: false };
 }
-/**
- * Verify the target can run the session's agent+version. Returns the effective
- * mode: a non-resumable agent (buildResumeCommand → null) forces rehydrate; a
- * missing agents-cli triggers a bootstrap; a missing agent (in rehydrate) is a
- * printed notice, not a failure.
- */
 function ensureTargetReady(target, sshTarget, source, requested) {
-    // buildResumeCommand gates faithful resume: null → only rehydrate is possible.
     const gated = effectiveMode(source, requested);
     let mode = gated.mode;
     if (gated.downgraded) {
@@ -270,12 +220,6 @@ function ensureTargetReady(target, sshTarget, source, requested) {
     }
     return mode;
 }
-/**
- * Wrap up the working tree so no local edits are stranded when the source stops.
- * Dirty → commit to a fresh branch + push + open a draft (WIP) PR. Clean-but-ahead
- * → push. --agent-wrapup instead injects a wrap-up turn into the running agent.
- * Returns the branch name to check out on an ephemeral target (or undefined).
- */
 async function wrapUpWorkingTree(source, active, options) {
     const cwd = source.cwd;
     if (!cwd || !fs.existsSync(cwd))
@@ -292,7 +236,6 @@ async function wrapUpWorkingTree(source, active, options) {
     }
     if (options.agentWrapup) {
         await delegateWrapupToAgent(source, active);
-        // The agent handles the commit/push; report its current branch for checkout.
         const after = await git.status();
         return after.current || undefined;
     }
@@ -300,7 +243,6 @@ async function wrapUpWorkingTree(source, active, options) {
         const branch = status.current && status.current !== 'main' && status.current !== 'master'
             ? status.current
             : `migrate/${source.shortId}`;
-        // Only create the branch when we're on the default branch (don't strand edits on main).
         if (status.current === 'main' || status.current === 'master') {
             console.log(chalk.gray(`  Working tree dirty on ${status.current} — committing to a new branch ${branch}.`));
             await git.checkoutLocalBranch(branch);
@@ -316,12 +258,10 @@ async function wrapUpWorkingTree(source, active, options) {
         openWipPr(cwd, branch);
         return branch;
     }
-    // Clean but ahead — push what's committed.
     console.log(chalk.gray(`  ${ahead} local commit(s) ahead — pushing before migrate.`));
     await git.push().catch((e) => console.log(chalk.yellow(`  push failed: ${e.message}`)));
     return status.current || undefined;
 }
-/** Open a draft (WIP) PR for the wrap-up branch. Best-effort; a failure is a notice. */
 function openWipPr(cwd, branch) {
     const r = spawnSync('gh', ['pr', 'create', '--draft', '--fill', '--head', branch], { cwd, encoding: 'utf-8' });
     if (r.status === 0) {
@@ -332,7 +272,6 @@ function openWipPr(cwd, branch) {
         console.log(chalk.yellow(`  Could not open a WIP PR (${(r.stderr || '').trim().split('\n').pop() || 'gh error'}). Branch ${branch} is pushed.`));
     }
 }
-/** --agent-wrapup: inject a wrap-up turn into the running agent's tmux pane. */
 async function delegateWrapupToAgent(source, active) {
     const rail = active?.provenance?.reply;
     if (!rail) {
@@ -353,17 +292,6 @@ async function delegateWrapupToAgent(source, active) {
         console.log(chalk.yellow(`  --agent-wrapup injection failed: ${res.error ?? 'unknown'}.`));
     }
 }
-/**
- * Ship the transcript to the target so `<agent> --resume` can find it there.
- *
- * The live transcript (`SessionMeta.filePath`) is copied to the SAME absolute
- * path on the target: claude/codex/opencode resolve a resumable session by the
- * cwd-derived project dir under $HOME, which is identical across the shared fleet
- * home, so a same-path copy is exactly what `--resume` reads. (`sessions import`
- * deliberately lands bundles in the browsable history mirror, not the agent's
- * live dir — right for reading a transcript on another box, wrong for resuming
- * it.) Reuses the same `sshExec` transport, streaming the file over stdin.
- */
 function shipTranscript(sshTarget, source) {
     const file = source.filePath;
     if (!file || !fs.existsSync(file)) {
@@ -378,7 +306,6 @@ function shipTranscript(sshTarget, source) {
     }
     console.log(chalk.green(`  Transcript shipped to the target (${file}).`));
 }
-/** Git-clone + checkout the (WIP) branch on an ephemeral box so the cwd resolves. */
 function prepareEphemeralCwd(sshTarget, source, branch) {
     const remote = spawnSync('git', ['-C', source.cwd || '.', 'remote', 'get-url', 'origin'], { encoding: 'utf-8' });
     const url = (remote.stdout || '').trim();
@@ -396,23 +323,6 @@ function prepareEphemeralCwd(sshTarget, source, branch) {
     }
     return dir;
 }
-/**
- * Pure. The remote shell commands that create the target's tmux session on the
- * SAME socket its reaper queries, and that probe its liveness afterward.
- *
- * `homeRelSocketPath` is `getDefaultSocketPath()` expressed relative to the
- * LOCAL home dir (`path.relative(os.homedir(), getDefaultSocketPath())`) — a
- * portable suffix, not a resolved absolute path, because the local and remote
- * HOME can differ (different user, different OS). It is spliced in after a
- * literal, unquoted `$HOME/` so the REMOTE shell resolves it; `$HOME` MUST
- * NEVER be resolved locally (see AGENTS.md's remote-path guidance).
- *
- * Extracted as a pure function so the "does the migrated session land on the
- * agents socket, not tmux's bare default socket" invariant is unit-testable
- * without an SSH round-trip (RUSH-2521 review — a bare `tmux` here made the
- * migrated agent's helpers invisible to `readAllPaneOwners`, so the reaper's
- * next tick killed the still-live, just-migrated agent as `tmux-session-gone`).
- */
 export function buildMigrateResumeCommands(opts) {
     const socketDirRelToHome = path.dirname(opts.homeRelSocketPath);
     const socketFlag = `-S "$HOME/${opts.homeRelSocketPath}"`;
@@ -420,46 +330,18 @@ export function buildMigrateResumeCommands(opts) {
     if (opts.cwd && opts.cwd !== '~')
         argv.push('-c', opts.cwd);
     argv.push(opts.inner);
-    // Mirror createSession's second half: keep remain-on-exit on THIS pane (the
-    // liveness probe below reads `pane_dead`), then put the server-wide default
-    // back to off. Leaving `-g on` set made every later pane on the target — user
-    // splits included — retain a corpse when its command finished.
     argv.push(';', 'set-option', '-t', opts.sessionName, '-p', 'remain-on-exit', 'on');
     argv.push(';', 'set-option', '-g', 'remain-on-exit', 'off');
-    // Unlike tmux's own scratch dir (auto-created under /tmp), the agents socket's
-    // parent may not exist yet on a fresh worker or ephemeral box that never ran a
-    // tmux-backed `agents` command — `mkdir -p` it before tmux tries to bind there.
     const launchCmd = `mkdir -p "$HOME/${socketDirRelToHome}" && tmux ${socketFlag} ` + argv.map(shellQuote).join(' ');
     const q = shellQuote(opts.sessionName);
     const probeCmd = `sleep 3; tmux ${socketFlag} has-session -t ${q} 2>/dev/null || exit 3; test "$(tmux ${socketFlag} list-panes -t ${q} -F '#{pane_dead}' 2>/dev/null | head -n1)" = 0 || exit 4`;
     return { launchCmd, probeCmd, socketFlag };
 }
-/**
- * Resume the session on the target through the SAME host path as
- * `sessions resume --device` (tmux backend). Returns true when the resume launched.
- */
 async function resumeOnTarget(sshTarget, source, remoteCwd, mode) {
     const command = mode === 'resume' ? buildResumeCommand(source) : rehydrateCommand(source);
     if (!command) {
         fail(`Cannot build a resume command for ${source.agent} (mode ${mode}).`);
     }
-    // Start a DETACHED tmux session on the target. The generic engine tmux backend
-    // uses `new-window`, which needs a live server — a fresh worker or ephemeral
-    // box has none ("no server running"), so we create the session (and thus the
-    // server) directly with `new-session -d`, mirroring the local `createSession`
-    // helper (remain-on-exit keeps the pane inspectable if the agent exits), over
-    // the same SSH transport as `sessions resume --device`.
-    //
-    // Each argv element is quoted BEFORE the zsh -ilc wrapper so a command that
-    // carries spaces or backticks (the rehydrate prompt) reaches the agent as one
-    // clean argument — an unquoted join would let the target shell split it and
-    // run its backticks.
-    //
-    // The pane exports AGENT_TMUX_SESSION_NAME the way a local `createSession`
-    // pane does, so the target's reaper can attribute the helpers this agent
-    // spawns and collect them when it exits (RUSH-2521, `lib/tmux/orphan-reap.ts`)
-    // — see {@link buildMigrateResumeCommands} for why the session MUST land on
-    // the agents socket rather than tmux's bare default socket.
     const sessionName = `migrate-${source.shortId}`;
     const homeRelSocketPath = path.relative(os.homedir(), getDefaultSocketPath());
     const inner = iLoginShell(`export AGENT_TMUX_SESSION_NAME=${sessionName}; exec ${command.map(quoteArg).join(' ')}`);
@@ -470,9 +352,6 @@ async function resumeOnTarget(sshTarget, source, remoteCwd, mode) {
         console.log(chalk.red(`  Resume on ${sshTarget} failed: ${launch.stderr.trim().split('\n').pop() || `tmux exited ${launch.code}`}`));
         return false;
     }
-    // Liveness gate for the invariant: give the agent a moment to boot, then require
-    // the pane to be ALIVE (not merely the session to exist) before the caller may
-    // stop the source. An agent that dies on launch → we refuse to move.
     const check = sshExec(sshTarget, probeCmd, { timeoutMs: 30000 });
     if (check.code !== 0) {
         const why = check.code === 4 ? 'the agent exited immediately on the target'
@@ -484,14 +363,7 @@ async function resumeOnTarget(sshTarget, source, remoteCwd, mode) {
     console.log(chalk.green(`  Resumed on the target in tmux session ${sessionName} (${command.join(' ')}).`));
     return true;
 }
-/**
- * Rehydrate command: launch a fresh agent that reads the transcript. For a
- * non-resumable agent there is no faithful --resume, so we start the agent with
- * a prompt pointing it at the imported transcript path.
- */
 export function rehydrateCommand(source) {
-    // Resolve the real executable — the session-agent id is not always the binary
-    // name (antigravity → `agy`), matching versionedAliasIfPresent/buildFallbackCommand.
     const cli = AGENTS[source.agent]?.cliCommand ?? source.agent;
     const origin = source.machine ? ` from ${source.machine}` : '';
     const prompt = [
@@ -507,25 +379,15 @@ async function sessionsMigrateAction(sessionId, options) {
     if (options.mode && options.mode !== 'resume' && options.mode !== 'rehydrate') {
         fail(`--mode must be 'resume' or 'rehydrate' (got "${options.mode}").`);
     }
-    // 1. Resolve the source session (current-pane unless an id is given).
     const { meta: source, active } = await resolveSourceSession(sessionId);
     console.log(chalk.bold(`Migrating ${source.agent} session ${source.shortId}`) + chalk.gray(` (${source.cwd ?? 'no cwd'})`));
-    // 2. Resolve the target host.
     const target = await resolveTarget(options, source);
     const sshTarget = sshTargetForTarget(target);
-    // 3. Verify the target can run the agent+version (bootstrap if missing); resolve the mode.
     const mode = ensureTargetReady(target, sshTarget, source, options.mode ?? 'resume');
-    // 4. Wrap up the working dir (WIP PR by default, or delegate to the agent).
     const branch = await wrapUpWorkingTree(source, active, options);
-    // 5. Transport the transcript to the target's live agent dir (same path) so
-    //    `<agent> --resume` finds it.
     shipTranscript(sshTarget, source);
-    // 6. For an ephemeral box, clone + checkout the branch so the cwd resolves.
     const remoteCwd = target.kind === 'ephemeral' ? prepareEphemeralCwd(sshTarget, source, branch) : source.cwd;
-    // 7. Resume on the target.
     const resumed = await resumeOnTarget(sshTarget, source, remoteCwd, mode);
-    // Ledger stub shared by the success and failure records (RUSH-1977). `at` is
-    // stamped from the CLI's real clock.
     const base = {
         sessionId: source.id,
         shortId: source.shortId,
@@ -541,26 +403,18 @@ async function sessionsMigrateAction(sessionId, options) {
         recordMigration({ ...base, status: 'failed', error: 'resume did not launch on the target' });
         fail('Resume on the target did not launch — the source is left running (nothing was stopped).');
     }
-    // 8. INVARIANT: only now that the transcript is on the target and the session
-    //    is confirmed live, stop the source. --keep skips this (copy, not move).
     if (options.keep) {
         console.log(chalk.gray('--keep: the source session is left running (copy, not move).'));
     }
     else {
         await stopSource(source, active);
     }
-    // 9. Record the handoff so the session stays trackable (agents sessions migrations).
     recordMigration({ ...base, status: 'completed' });
     console.log(chalk.green(`\nMigrated ${source.shortId} to ${target.name}${options.keep ? ' (copy)' : ''}.`) +
         chalk.gray(" Tracked in 'agents sessions migrations'."));
 }
-/** Stop the source tmux session (kill its tmux session by name via its socket). */
 async function stopSource(source, active) {
     const mux = active?.provenance?.mux;
-    // Fail closed: only the SOURCE's own pane, from its active-session provenance.
-    // Never fall back to $TMUX_PANE — that is the invoking shell's pane, so a
-    // migrate run by explicit id from a different pane (where `active` didn't
-    // resolve) would otherwise kill the user's OWN session, not the source.
     const pane = mux?.pane;
     const socket = mux?.socket;
     if (!pane) {
@@ -578,10 +432,6 @@ async function stopSource(source, active) {
     else
         console.log(chalk.yellow(`  Source tmux session ${name} was already gone.`));
 }
-/**
- * `agents sessions migrations` — the border tracker: the append-only ledger of
- * every session handed off to/from another machine (RUSH-1977).
- */
 export function registerSessionsMigrationsCommand(sessionsCmd) {
     sessionsCmd
         .command('migrations')
@@ -600,7 +450,6 @@ export function registerSessionsMigrationsCommand(sessionsCmd) {
             console.log(chalk.gray('No migrations recorded yet. Move one: agents sessions migrate --auto'));
             return;
         }
-        // Newest first — the most recent hop of a session is what you usually want.
         recs.reverse();
         console.log(chalk.bold('WHEN'.padEnd(18)) + chalk.bold('SESSION'.padEnd(11)) + chalk.bold('AGENT'.padEnd(9)) +
             chalk.bold('ROUTE'.padEnd(30)) + chalk.bold('MODE'.padEnd(11)) + chalk.bold('STATUS'));
@@ -615,7 +464,6 @@ export function registerSessionsMigrationsCommand(sessionsCmd) {
         }
     });
 }
-/** Map a tmux pane id to its session name via the same tmux binary the engine uses. */
 function resolveSessionNameForPane(pane, socket) {
     const args = socket ? ['-S', socket] : [];
     const r = spawnSync('tmux', [...args, 'display-message', '-pt', pane, '-p', '#{session_name}'], { encoding: 'utf-8' });

package/dist/commands/sessions-optimize.d.ts

@@ -1,14 +1,2 @@
-/**
- * `agents sessions optimize` — compact the FTS5 session/tool-call search index.
- *
- * The scanner delete+inserts a session's docs into the `tool_call_text` /
- * `session_text` FTS5 indexes on every rescan (and on every extractor-version
- * bump), and FTS5 never merges the resulting segments on its own. Over thousands
- * of sessions and re-index passes the `%_data` shadow tables bloat with hundreds
- * of thousands of unmerged segments — gigabytes of index for tens of MB of
- * actual content — and `agents sessions` queries slow to a crawl. This runs the
- * FTS5 `'optimize'` command to merge every segment into one and purge tombstones.
- * Non-destructive: no searchable content is lost.
- */
 import type { Command } from 'commander';
 export declare function registerSessionsOptimizeCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-picker-factory.d.ts

@@ -1,17 +1,10 @@
-/** Flag subset both twins share for the interactive-routing gate. */
 interface SessionsPickerGateOpts {
     interactive?: boolean;
     json?: boolean;
-    /** Present only on the browser twin; computer never sets it. */
     open?: string | boolean;
 }
 interface SessionsPickerCommandSpec<TRow, TOpts extends SessionsPickerGateOpts> {
-    /**
-     * Browser requires `opts.open === undefined` so `--open` (bare or with a
-     * selector) falls through to the flat printer. Computer has no `--open`.
-     */
     requireOpenUndefined?: boolean;
-    /** May be async — the browser spec's flat path awaits an artifact open. */
     runFlat: (opts: TOpts) => void | Promise<void>;
     buildRows: (opts: TOpts) => TRow[];
     emptyMessage: (opts: TOpts) => string;

package/dist/commands/sessions-picker-factory.js

@@ -1,11 +1,3 @@
-/**
- * Shared interactive-routing + browse loop for the task-first session
- * pickers (`browser-sessions-picker.ts`, `computer-sessions-picker.ts`).
- *
- * Each twin keeps its own row formatter, matcher, and enter-handler; this
- * factory owns the TTY/`--json`/`--no-interactive` (and optional `--open`)
- * gate, the empty-list message, and the cancel-aware `itemPicker` loop.
- */
 import { itemPicker } from '../lib/picker.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 function shouldOpenInteractiveSessions(opts, isTTY, requireOpenUndefined = false) {