@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/commands/serve.js

@@ -1,15 +1,46 @@
 import chalk from 'chalk';
 import { startServeServer, DEFAULT_SERVE_PORT, SERVE_HOST } from '../lib/serve/server.js';
+import { startControlServer } from '../lib/serve/control.js';
+import { ensureControlToken } from '../lib/serve/token.js';
 export function registerServeCommand(program) {
     program
         .command('serve')
         .description('Read-only local web companion: team diffs, routines, and cloud status (binds 127.0.0.1 only).')
         .option('-p, --port <n>', `Port to bind on ${SERVE_HOST}`, String(DEFAULT_SERVE_PORT))
         .option('--interval <ms>', 'SSE refresh cadence in milliseconds', '3000')
+        .option('--control', 'Authenticated control mode (RUSH-1731): adds bearer-gated POST /api/run and /api/session/:id/message so the iOS cockpit can dispatch + steer. Enables binding beyond loopback — pair a device with `agents devices pair-ios`.', false)
+        .option('--bind <addr>', 'Address to bind in --control mode (e.g. your tailnet IP, or 0.0.0.0). Ignored without --control; read-only serve is always loopback.', SERVE_HOST)
         .action(async (opts) => {
         const port = parseInt(opts.port ?? '', 10) || DEFAULT_SERVE_PORT;
         const intervalMs = parseInt(opts.interval ?? '', 10) || 3000;
         try {
+            if (opts.control) {
+                const bind = opts.bind || SERVE_HOST;
+                const minted = ensureControlToken('default');
+                const { server, port: bound } = await startControlServer(port, bind, {
+                    cwd: process.cwd(),
+                    intervalMs,
+                });
+                const url = `http://${bind}:${bound}`;
+                console.log(`${chalk.green('agents serve --control')} ${chalk.dim('→')} ${chalk.cyan(url)}`);
+                if (minted.created) {
+                    console.log(chalk.yellow('New control token (shown once — store it in the cockpit now):'));
+                    console.log(`  ${chalk.bold(minted.token)}  ${chalk.dim(`(id ${minted.id})`)}`);
+                }
+                else {
+                    console.log(chalk.dim('Using existing control token(s). Issue another with `agents devices pair-ios`.'));
+                }
+                if (bind !== SERVE_HOST) {
+                    console.log(chalk.dim('bearer-gated · bind beyond loopback — keep this on the tailnet, never public Funnel · Ctrl-C to stop'));
+                }
+                else {
+                    console.log(chalk.dim('bearer-gated · loopback (pass --bind <tailnet-ip> to reach it from the phone) · Ctrl-C to stop'));
+                }
+                const shutdown = () => server.close(() => process.exit(0));
+                process.on('SIGINT', shutdown);
+                process.on('SIGTERM', shutdown);
+                return;
+            }
             const { server, port: bound } = await startServeServer(port, {
                 cwd: process.cwd(),
                 intervalMs,

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerSessionsExportCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-export.js

@@ -0,0 +1,284 @@
+/**
+ * `agents sessions export` — bundle N selected sessions into a portable,
+ * self-describing archive (RUSH-1710).
+ *
+ * The successor to background R2/CRDT sync for the durable-archive / hand-off
+ * case: instead of an always-on merge daemon, the user explicitly bundles the
+ * sessions they want to carry to an offline box or keep as an archive. The
+ * bundle format + placement live in ../lib/session/bundle.ts; this command owns
+ * only the SELECTION (which sessions) and the OUTPUT (file or stdout).
+ *
+ * Selection flags (`--since`, `-n/--limit`, `--all`, `-a/--agent`,
+ * `--no-redact`) are inherited from the parent `sessions` command and read via
+ * optsWithGlobals(), so they never shadow the parent's parsing; this command
+ * adds only the export-specific flags (`-o/--output`, `--stdout`, `--encrypt`).
+ *
+ * Rendered markdown/json of a single session is already served by
+ * `agents sessions <id> --markdown|--json`; export is specifically the portable,
+ * re-importable BUNDLE, so it does not re-expose those render formats.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import chalk from 'chalk';
+import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+import { filterSessionsByQuery, parseAgentFilter } from './sessions.js';
+import { listLocalTranscripts, SYNC_AGENTS } from '../lib/session/sync/agents.js';
+import { machineId } from '../lib/machine-id.js';
+import { getHistoryDir } from '../lib/state.js';
+import { loadR2Config } from '../lib/session/sync/config.js';
+import { resolveSyncEncKey, generateSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { buildRecord, makeHeader, mergeRecords, serializeBundle, writeBundleFile, specForAgent, } from '../lib/session/bundle.js';
+import { knownSecretValuesFromEnv } from '../lib/redact.js';
+import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
+import { setHelpSections } from '../lib/help.js';
+/** Default cap when exporting a scope (not explicit ids) and the user gave no -n. */
+const DEFAULT_LIMIT = 500;
+export function registerSessionsExportCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('export [selectors...]')
+        .description('Bundle sessions (by id, query, or the parent selection flags like --since/-a) into a portable archive.')
+        .option('-o, --output <path>', 'Write the bundle to this file')
+        .option('--stdout', 'Write the bundle to stdout (for piping into `sessions import -`)')
+        .option('--encrypt', 'Seal each transcript body with AES-256-GCM before writing');
+    setHelpSections(cmd, {
+        examples: `# Bundle the last week of sessions to a file
+agents sessions export --since 7d -o week.bundle
+
+# Bundle two specific sessions
+agents sessions export 4f8a2b1c 9d3e7a55 -o pair.bundle
+
+# Encrypt + pipe straight into another machine over SSH
+agents sessions export --since 7d --stdout --encrypt | agents ssh boxB 'agents sessions import - --decrypt <key>'`,
+        notes: `Selection uses the same flags as 'agents sessions' (--since, -n/--limit, --all,
+-a/--agent, --no-redact). Bundles are self-describing NDJSON: a header line + one
+line per transcript file. Secrets are redacted by default. Dir-shaped sessions
+(Kimi) carry all their files. Restore with 'agents sessions import'.`,
+    });
+    cmd.action(async (selectors, _options, command) => {
+        await runExport(selectors, command);
+    });
+}
+async function runExport(selectors, command) {
+    const g = command.optsWithGlobals();
+    // --host: export sessions that live on remote peer(s) — run export there and
+    // stream the bundle back over the existing SSH transport (RUSH-1712).
+    if (g.host && g.host.length > 0) {
+        await runRemoteExport(g, selectors, command);
+        return;
+    }
+    const explicitLimit = command.parent?.getOptionValueSource?.('limit') === 'cli';
+    const limit = explicitLimit ? Math.max(1, parseInt(String(g.limit), 10) || DEFAULT_LIMIT) : DEFAULT_LIMIT;
+    const agentFilter = parseAgentFilter(resolveAgentShorthand(g));
+    // 1. Discover candidate sessions in scope.
+    const metas = await discoverSessions({
+        all: g.all !== false,
+        agent: agentFilter.agent ?? undefined,
+        since: g.since,
+        limit,
+    });
+    // 2. Narrow to the selection (ids > query > everything-in-scope).
+    const selected = selectSessions(metas, selectors);
+    if (selected.length === 0) {
+        process.stderr.write(chalk.yellow('No sessions matched the selection.\n'));
+        process.exit(1);
+    }
+    if (!selectors.length && selected.length >= limit) {
+        process.stderr.write(chalk.yellow(`Note: capped at ${limit} sessions. Raise -n to bundle more.\n`));
+    }
+    // 3. Resolve each selected session to its on-disk file(s).
+    const index = buildLocalIndex();
+    const self = machineId();
+    const files = [];
+    const skippedAgents = new Set();
+    for (const meta of selected) {
+        const spec = specForAgent(meta.agent);
+        if (!spec) {
+            skippedAgents.add(meta.agent);
+            continue;
+        }
+        const machine = meta.machine || self;
+        const lt = index.get(`${meta.agent}:${meta.id}`);
+        if (lt) {
+            for (const f of lt.files) {
+                files.push({ agent: meta.agent, machine, sessionId: meta.id, relKey: f.relKey, absPath: f.absPath, label: meta.label });
+            }
+        }
+        else if (meta.filePath && fs.existsSync(meta.filePath)) {
+            // Not in the live-home index (e.g. a mirror of another machine): fall back
+            // to the single discovered file, deriving its subdir-relative key.
+            const relKey = relKeyFromPath(meta.filePath, meta.agent, machine, spec.subdir);
+            files.push({ agent: meta.agent, machine, sessionId: meta.id, relKey, absPath: meta.filePath, label: meta.label });
+        }
+    }
+    if (skippedAgents.size > 0) {
+        process.stderr.write(chalk.yellow(`Skipped agents with no portable format: ${[...skippedAgents].sort().join(', ')}.\n`));
+    }
+    if (files.length === 0) {
+        process.stderr.write(chalk.red('Selected sessions have no exportable transcript files.\n'));
+        process.exit(1);
+    }
+    // 4. Resolve encryption key (opt-in) + redaction (default on via parent --no-redact).
+    const encryptKey = g.encrypt ? resolveExportKey() : null;
+    const redact = g.redact !== false;
+    // Value-aware redaction: mask live credential values already in the
+    // environment (e.g. an injected secrets bundle) verbatim, whatever their
+    // format. Only meaningful when redacting.
+    const knownSecrets = redact ? knownSecretValuesFromEnv() : undefined;
+    // 5. Build records + header.
+    const records = [];
+    for (const f of files) {
+        try {
+            records.push(buildRecord(f, { redact, encryptKey, knownSecrets }));
+        }
+        catch (err) {
+            process.stderr.write(chalk.yellow(`Skipped ${f.agent}/${f.sessionId} (${f.relKey}): ${err.message}\n`));
+        }
+    }
+    if (records.length === 0) {
+        process.stderr.write(chalk.red('Nothing to export after reading files.\n'));
+        process.exit(1);
+    }
+    const header = makeHeader({
+        origin: self,
+        exportedAt: new Date().toISOString(),
+        encrypted: encryptKey !== null,
+        redacted: redact,
+        records,
+    });
+    emitBundle(header, records, g);
+}
+/**
+ * --host path: run `agents sessions export …` on each peer over SSH, stream the
+ * bundles back, merge (dedup by origin machine) and emit one local bundle.
+ * Encryption is not combined with a remote pull (each peer would seal under its
+ * own key); the SSH transport already encrypts the stream in transit.
+ */
+async function runRemoteExport(g, selectors, command) {
+    if (g.encrypt) {
+        process.stderr.write(chalk.yellow('Note: --encrypt is ignored with --host (the SSH stream is already encrypted). Encrypt a local bundle instead.\n'));
+    }
+    const { bundles, errors } = await pullBundlesFromHosts(g.host, forwardExportArgs(g, selectors, command));
+    for (const e of errors)
+        process.stderr.write(chalk.yellow(`  ${e}\n`));
+    const records = mergeRecords(bundles.map(b => b.records));
+    if (records.length === 0) {
+        process.stderr.write(chalk.red('No sessions pulled from the given host(s).\n'));
+        process.exit(1);
+    }
+    const header = makeHeader({
+        origin: g.host.join(','),
+        exportedAt: new Date().toISOString(),
+        encrypted: false,
+        redacted: g.redact !== false,
+        records,
+    });
+    emitBundle(header, records, g);
+}
+/** Reconstruct the export flags to forward to a peer's own `sessions export`. */
+function forwardExportArgs(g, selectors, command) {
+    const args = [...selectors];
+    if (g.since)
+        args.push('--since', g.since);
+    const agent = resolveAgentShorthand(g);
+    if (agent)
+        args.push('-a', agent);
+    if (g.all !== false)
+        args.push('--all');
+    if (g.redact === false)
+        args.push('--no-redact');
+    if (command.parent?.getOptionValueSource?.('limit') === 'cli' && g.limit)
+        args.push('-n', String(g.limit));
+    return args;
+}
+/** Write the assembled bundle to stdout or a file. */
+function emitBundle(header, records, g) {
+    const wire = serializeBundle(header, records);
+    if (g.stdout) {
+        process.stdout.write(wire);
+        return;
+    }
+    const outPath = g.output || defaultBundlePath();
+    writeBundleFile(outPath, wire);
+    process.stderr.write(chalk.green(`Exported ${header.sessions} session${header.sessions === 1 ? '' : 's'} ` +
+        `(${header.count} file${header.count === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ''}${header.redacted ? ', redacted' : ''}) ` +
+        `→ ${outPath}\n`));
+}
+/** Map the parent's agent shorthands (--claude, --codex, …) or -a/--agent to a filter string. */
+function resolveAgentShorthand(g) {
+    if (g.agent)
+        return g.agent;
+    if (g.claude)
+        return 'claude';
+    if (g.codex)
+        return 'codex';
+    if (g.kimi)
+        return 'kimi';
+    if (g.grok)
+        return 'grok';
+    if (g.opencode)
+        return 'opencode';
+    if (g.antigravity)
+        return 'antigravity';
+    return undefined;
+}
+/** ids > query > everything-in-scope. */
+function selectSessions(metas, selectors) {
+    if (selectors.length === 0)
+        return metas;
+    const byId = [];
+    const unmatched = [];
+    for (const sel of selectors) {
+        const hits = resolveSessionById(metas, sel);
+        if (hits.length > 0)
+            byId.push(...hits);
+        else
+            unmatched.push(sel);
+    }
+    if (byId.length > 0 && unmatched.length === 0) {
+        const seen = new Set();
+        return byId.filter(s => (seen.has(s.id) ? false : (seen.add(s.id), true)));
+    }
+    // Any selector that isn't an id → treat the whole thing as a text query.
+    return filterSessionsByQuery(metas, selectors.join(' '));
+}
+/** Build `${agent}:${sessionId}` → LocalTranscript across every sync agent (live home only). */
+function buildLocalIndex() {
+    const index = new Map();
+    for (const spec of SYNC_AGENTS) {
+        for (const lt of listLocalTranscripts(spec)) {
+            index.set(`${spec.id}:${lt.sessionId}`, lt);
+        }
+    }
+    return index;
+}
+/** Derive the subdir-relative key for a mirror file path, else fall back to the basename. */
+function relKeyFromPath(filePath, agent, machine, subdir) {
+    const prefix = path.join(getHistoryDir(), 'backups', agent, machine, subdir) + path.sep;
+    if (filePath.startsWith(prefix))
+        return filePath.slice(prefix.length);
+    return path.basename(filePath);
+}
+/**
+ * Resolve the AES key for --encrypt: prefer the fleet-shared R2_SYNC_ENC_KEY (so
+ * any machine on the sync bundle can decrypt), else mint an ephemeral key and
+ * print it once — it is NOT stored in the bundle.
+ */
+function resolveExportKey() {
+    try {
+        const key = resolveSyncEncKey(loadR2Config());
+        if (key)
+            return key;
+    }
+    catch {
+        // sync bundle not configured — fall through to an ephemeral key
+    }
+    const b64 = generateSyncEncKey();
+    process.stderr.write(chalk.yellow(`Bundle encrypted with a fresh key (not in the bundle). Decrypt with:\n` +
+        `  agents sessions import <bundle> --decrypt ${b64}\n`));
+    return Buffer.from(b64, 'base64');
+}
+/** Default output file when neither -o nor --stdout is given. */
+function defaultBundlePath() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
+    return path.join(process.cwd(), `agents-sessions-${stamp}.bundle`);
+}

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerSessionsImportCommand(sessionsCmd: Command): void;

package/dist/commands/sessions-import.js

@@ -0,0 +1,230 @@
+/**
+ * `agents sessions import <bundle|->` — restore an export bundle (RUSH-1711).
+ *
+ * The inverse of `sessions export`: read a bundle (file or stdin), validate it,
+ * and place each transcript where the cross-machine sync would — a mirror keyed
+ * by the session's ORIGIN machine (see bundle.ts / mirrorPath). Placement dedups
+ * byte-exact against what is already on disk and never clobbers this machine's
+ * own live sessions ("local always wins" falls out of the scanner's
+ * live-home-first dedup), so a re-import or an overlapping bundle is safe.
+ */
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { loadR2Config } from '../lib/session/sync/config.js';
+import { resolveSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { parseBundle, planImport, writeImport, mergeRecords, makeHeader, } from '../lib/session/bundle.js';
+import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
+import { setHelpSections } from '../lib/help.js';
+export function registerSessionsImportCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('import [bundle]')
+        .description('Restore an export bundle (file, - for stdin, or --from-host <h>) into the local session store, deduping against what you already have.')
+        .option('--dry-run', 'Show what would be placed without writing anything')
+        .option('--overwrite', 'Replace local files that differ from the bundle (default: keep local)')
+        .option('--decrypt [key]', 'Decrypt an encrypted bundle (key optional if the r2.backups sync key is configured)')
+        .option('--from-host <target...>', 'Pull sessions live from remote peer(s) over SSH instead of a file (repeatable)');
+    setHelpSections(cmd, {
+        examples: `# Preview what a bundle would restore
+agents sessions import week.bundle --dry-run
+
+# Restore it
+agents sessions import week.bundle
+
+# Pull straight off another machine (one command, over SSH)
+agents sessions import --from-host yosemite-s1 --since 7d
+
+# Or the equivalent raw pipe
+agents ssh boxB 'agents sessions export --since 7d --stdout' | agents sessions import -`,
+        notes: `Sessions land under the cross-machine mirror keyed by their origin machine, so
+they show up in 'agents sessions' tagged with that machine and never overwrite
+your own local sessions. Byte-exact duplicates are skipped. --from-host reuses
+the same SSH transport as the cross-machine listing (no R2, no daemon).`,
+    });
+    cmd.action(async (bundlePath, options, command) => {
+        const g = command.optsWithGlobals();
+        await runImport(bundlePath, { ...options, agent: g.agent }, g, command);
+    });
+}
+async function runImport(bundlePath, options, g, command) {
+    // 1. Obtain the bundle — from remote peer(s), stdin, or a file.
+    let bundle;
+    if (options.fromHost && options.fromHost.length > 0) {
+        bundle = await pullForImport(options.fromHost, bundlePath, g, command);
+    }
+    else {
+        if (!bundlePath) {
+            process.stderr.write(chalk.red('Provide a bundle path, - for stdin, or --from-host <host>.\n'));
+            process.exit(1);
+        }
+        let text;
+        try {
+            text = bundlePath === '-' ? await readStdin() : fs.readFileSync(bundlePath, 'utf-8');
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`Cannot read bundle: ${err.message}\n`));
+            process.exit(1);
+        }
+        try {
+            bundle = parseBundle(text);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`${err.message}\n`));
+            process.exit(1);
+        }
+    }
+    // 2. Optional agent filter.
+    if (options.agent) {
+        bundle = { header: bundle.header, records: bundle.records.filter(r => r.agent === options.agent) };
+        if (bundle.records.length === 0) {
+            process.stderr.write(chalk.yellow(`No records for agent '${options.agent}' in this bundle.\n`));
+            process.exit(1);
+        }
+    }
+    // 3. Resolve the decryption key if the bundle is encrypted.
+    const decryptKey = bundle.header.encrypted ? resolveDecryptKey(options.decrypt) : null;
+    // 4. Plan.
+    let plan;
+    try {
+        plan = planImport(bundle, { decryptKey });
+    }
+    catch (err) {
+        process.stderr.write(chalk.red(`${err.message}\n`));
+        process.exit(1);
+    }
+    if (options.dryRun) {
+        printDryRun(plan, bundle);
+        return;
+    }
+    // 5. Write.
+    const res = writeImport(plan, { overwrite: options.overwrite === true, decryptKey });
+    const parts = [];
+    if (res.placed)
+        parts.push(`${res.placed} placed`);
+    if (res.overwritten)
+        parts.push(`${res.overwritten} overwritten`);
+    if (res.skipped)
+        parts.push(`${res.skipped} duplicate${res.skipped === 1 ? '' : 's'} skipped`);
+    if (res.conflicts)
+        parts.push(chalk.yellow(`${res.conflicts} conflict${res.conflicts === 1 ? '' : 's'} kept local (use --overwrite)`));
+    if (res.unknown)
+        parts.push(chalk.yellow(`${res.unknown} unknown-agent skipped`));
+    process.stderr.write(chalk.green(`Imported: ${parts.join(', ') || 'nothing to do'}.\n`));
+}
+/** Drain all of stdin to a string. Works for pipes (non-seekable) and redirects
+ *  alike — unlike readFileSync(0), which fails on a pipe. */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf-8');
+}
+/**
+ * --from-host: run `agents sessions export …` on each peer over SSH and merge
+ * the streamed bundles into one for import. The optional positional acts as a
+ * remote selector (id/query); the parent selection flags (--since, -a, --all,
+ * -n) forward too.
+ */
+async function pullForImport(hosts, selector, g, command) {
+    const args = [];
+    if (selector && selector !== '-')
+        args.push(selector);
+    if (g.since)
+        args.push('--since', g.since);
+    const agent = command.optsWithGlobals().agent;
+    if (agent)
+        args.push('-a', agent);
+    if (g.all !== false)
+        args.push('--all');
+    if (command.parent?.getOptionValueSource?.('limit') === 'cli' && g.limit)
+        args.push('-n', String(g.limit));
+    const { bundles, errors } = await pullBundlesFromHosts(hosts, args);
+    for (const e of errors)
+        process.stderr.write(chalk.yellow(`  ${e}\n`));
+    const records = mergeRecords(bundles.map(b => b.records));
+    if (records.length === 0) {
+        process.stderr.write(chalk.red('No sessions pulled from the given host(s).\n'));
+        process.exit(1);
+    }
+    const header = makeHeader({
+        origin: hosts.join(','),
+        exportedAt: new Date().toISOString(),
+        encrypted: false,
+        redacted: bundles.some(b => b.header.redacted),
+        records,
+    });
+    return { header, records };
+}
+/**
+ * Decrypt-key resolution: an explicit `--decrypt <key>` (base64 or hex) wins;
+ * otherwise fall back to the fleet-shared R2_SYNC_ENC_KEY from the r2.backups
+ * bundle. Fails loudly when an encrypted bundle has no usable key.
+ */
+function resolveDecryptKey(decrypt) {
+    if (typeof decrypt === 'string' && decrypt.trim()) {
+        const raw = decrypt.trim();
+        const key = /^[0-9a-f]{64}$/i.test(raw) ? Buffer.from(raw, 'hex') : Buffer.from(raw, 'base64');
+        if (key.length !== 32) {
+            process.stderr.write(chalk.red(`--decrypt key must decode to 32 bytes (got ${key.length}).\n`));
+            process.exit(1);
+        }
+        return key;
+    }
+    try {
+        const key = resolveSyncEncKey(loadR2Config());
+        if (key)
+            return key;
+    }
+    catch {
+        // sync bundle not configured
+    }
+    process.stderr.write(chalk.red('This bundle is encrypted but no key is available. Pass --decrypt <key>, ' +
+        'or configure the r2.backups sync bundle so its shared key is used.\n'));
+    process.exit(1);
+}
+/** Print the dry-run table, grouped by session. Reads disk, writes nothing. */
+function printDryRun(plan, bundle) {
+    // Group file-level plan items by session for a readable table.
+    const bySession = new Map();
+    for (const item of plan) {
+        const key = `${item.record.agent}:${item.record.machine}:${item.record.sessionId}`;
+        let row = bySession.get(key);
+        if (!row)
+            bySession.set(key, (row = { agent: item.record.agent, machine: item.record.machine, sessionId: item.record.sessionId, statuses: new Set(), files: 0 }));
+        row.statuses.add(item.status);
+        row.files++;
+    }
+    process.stdout.write(chalk.bold(`Bundle: ${bundle.header.sessions} session(s), ${bundle.header.count} file(s), origin ${bundle.header.origin}${bundle.header.encrypted ? ', encrypted' : ''}\n\n`));
+    const header = `${pad('SESSION', 22)}${pad('AGENT', 10)}${pad('ORIGIN', 16)}${pad('FILES', 7)}STATUS`;
+    process.stdout.write(chalk.dim(header) + '\n');
+    for (const row of bySession.values()) {
+        const status = aggregateStatus(row.statuses);
+        process.stdout.write(pad(row.sessionId.slice(0, 20), 22) +
+            pad(row.agent, 10) +
+            pad(row.machine, 16) +
+            pad(String(row.files), 7) +
+            colorStatus(status) + '\n');
+    }
+    process.stdout.write(chalk.dim('\n(dry run — nothing was written)\n'));
+}
+function aggregateStatus(statuses) {
+    if (statuses.has('conflict'))
+        return 'conflict';
+    if (statuses.has('unknown'))
+        return 'unknown';
+    if (statuses.has('new'))
+        return statuses.has('dup') ? 'partial' : 'new';
+    return 'dup';
+}
+function colorStatus(status) {
+    switch (status) {
+        case 'new': return chalk.green(status);
+        case 'dup': return chalk.dim(status);
+        case 'partial': return chalk.cyan(status);
+        case 'conflict': return chalk.yellow(status);
+        case 'unknown': return chalk.red(status);
+        default: return status;
+    }
+}
+function pad(s, w) {
+    return s.length >= w ? s.slice(0, w - 1) + ' ' : s + ' '.repeat(w - s.length);
+}

package/dist/commands/sessions.d.ts

@@ -201,6 +201,22 @@ export declare function pickSessionInteractive(sessions: SessionMeta[], message?
  * binary is missing (ENOENT).
  */
 export declare function resumeSessionInPlace(session: SessionMeta): Promise<void>;
+/**
+ * Map a resume argv to the spawn(command, args, {shell}) triple.
+ *
+ * On Windows the agent launcher is a `.cmd`/PATHEXT shim and needs shell:true.
+ * With shell:true, Node concatenates args into the cmd.exe line unescaped
+ * (DEP0190 + injection). A session.id derived from a filename can carry
+ * metacharacters (`&|<>`); compose a fully-quoted line and pass an EMPTY args
+ * array so cmd.exe cannot reparse them (RUSH-1753). See composeWin32CommandLine.
+ *
+ * `platform` is injectable so the win32 shell path is unit-testable on any host.
+ */
+export declare function resumeSpawnInvocation(cmd: string[], platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
 /**
  * Build the shell command that resumes a picked session.
  *