@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/commands/sessions-migrate.js

@@ -15,7 +15,7 @@
  *   - 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 --host` uses;
+ *     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).
  *
@@ -33,9 +33,7 @@ import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
 import { buildResumeCommand } from './sessions.js';
 import { injectTargetFromReplyRail } from '../lib/session/inject.js';
-import { injectIntoTerminal } from '../lib/terminal/index.js';
-import { iLoginShell } from '../lib/terminal/shell.js';
-import { shellQuote as quoteArg } from '../lib/terminal/quote.js';
+import { injectIntoTerminal, iLoginShell, shellQuote as quoteArg } from '../lib/terminal/index.js';
 import { killSession } from '../lib/tmux/session.js';
 import { getDefaultSocketPath } from '../lib/tmux/paths.js';
 import { listAllHosts, resolveHost } from '../lib/hosts/registry.js';
@@ -57,7 +55,7 @@ export function registerSessionsMigrateCommand(sessionsCmd) {
         .alias('relocate')
         .description('Relocate a running session onto another machine (fleet worker, device, or ephemeral box), then stop the source here.')
         .option('--auto', 'Pick the best target host automatically (idle fleet worker preferred)')
-        .option('--host <name>', 'Explicit target: an enrolled host, a device, or a warm ephemeral box slug')
+        .option('--device <name>', 'Explicit target: an enrolled host, device, or a warm ephemeral box slug')
         .option('--lease', 'Provision a fresh ephemeral crabbox box as the target')
         .option('--mode <mode>', 'rehydrate (default: the target agent reads the transported transcript) or resume (best-effort native --resume)', 'rehydrate')
         .option('--keep', 'Copy, not move — do NOT stop the source after resuming on the target')
@@ -68,13 +66,13 @@ export function registerSessionsMigrateCommand(sessionsCmd) {
       agents sessions migrate --auto
 
       # Move a specific session onto a named host
-      agents sessions migrate a1b2c3d4 --host yosemite-s1
+      agents sessions migrate a1b2c3d4 --device yosemite-s1
 
       # Spin up a fresh ephemeral box and move onto it
       agents sessions migrate --lease
 
       # Copy (don't stop the source), letting the agent wrap up its own dirty tree
-      agents sessions migrate --host box-a --keep --agent-wrapup
+      agents sessions migrate --device box-a --keep --agent-wrapup
     `,
         notes: `
       - Without a [session-id], migrate resolves the session running in THIS tmux pane ($TMUX_PANE).
@@ -87,17 +85,8 @@ export function registerSessionsMigrateCommand(sessionsCmd) {
       - Every migrate appends to the ledger — see 'agents sessions migrations' for where each session went.
     `,
     });
-    cmd.action(async (sessionId, options, command) => {
-        // commander 15: the parent `sessions` command owns a global `-H, --host` (the
-        // listing fan-out), which shadows this subcommand's own --host — the value
-        // lands in the merged globals, not `options.host`. Read it from there so
-        // `agents sessions migrate --host <name>` binds.
-        const globals = command.optsWithGlobals();
-        const hosts = Array.isArray(globals.host) ? globals.host : globals.host ? [globals.host] : [];
-        if (hosts.length > 1) {
-            console.error(chalk.yellow(`Multiple --host values given; migrating to the first (${hosts[0]}).`));
-        }
-        await sessionsMigrateAction(sessionId, { ...options, host: hosts[0] });
+    cmd.action(async (sessionId, options) => {
+        await sessionsMigrateAction(sessionId, options);
     });
 }
 function fail(message) {
@@ -141,7 +130,7 @@ function statsByName() {
     const cache = readStatsCache();
     return new Map(Object.entries(cache));
 }
-/** Enumerate + rank targets, honoring --host / --auto / --lease. */
+/** Enumerate + rank targets, honoring --device / --auto / --lease. */
 async function resolveTarget(options, source) {
     const selfHostname = os.hostname();
     const ctx = {
@@ -162,17 +151,17 @@ async function resolveTarget(options, source) {
         warm = []; // crabbox not configured — fleet-only targets
     }
     const stats = statsByName();
-    if (options.host) {
+    if (options.device) {
         // Explicit target: a fleet host/device, or a warm box slug.
-        const box = warm.find((b) => b.slug === options.host);
+        const box = warm.find((b) => b.slug === options.device);
         if (box) {
             return { name: box.slug, kind: 'ephemeral', os: 'linux', headroom: 'unknown', box };
         }
-        const host = await resolveHost(options.host);
+        const host = await resolveHost(options.device);
         if (!host)
-            fail(`No host, device, or warm box named "${options.host}".`);
+            fail(`No host, device, or warm box named "${options.device}".`);
         if (host.name.toLowerCase() === selfHostname.toLowerCase()) {
-            fail(`"${options.host}" is this machine — migrate needs a different target.`);
+            fail(`"${options.device}" is this machine — migrate needs a different target.`);
         }
         return { name: host.name, kind: 'fleet', os: host.os, headroom: 'unknown', host };
     }
@@ -186,7 +175,7 @@ async function resolveTarget(options, source) {
     }
     // Interactive: rank the candidates and let the user pick.
     if (!isInteractiveTerminal()) {
-        fail('Pass --auto, --host <name>, or --lease to choose a target (no interactive picker without a tty).');
+        fail('Pass --auto, --device <name>, or --lease to choose a target (no interactive picker without a tty).');
     }
     const ranked = rankTargets(enumerateTargets(hosts, warm, stats, ctx), ctx);
     if (ranked.length === 0) {
@@ -447,7 +436,7 @@ export function buildMigrateResumeCommands(opts) {
 }
 /**
  * Resume the session on the target through the SAME host path as
- * `sessions resume --host` (tmux backend). Returns true when the resume launched.
+ * `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);
@@ -459,7 +448,7 @@ async function resumeOnTarget(sshTarget, source, remoteCwd, mode) {
     // 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 --host`.
+    // 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

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

@@ -1,4 +1,5 @@
 import type { SessionEvent, SessionMeta, TodoProgress } from '../lib/session/types.js';
+import { fetchPeerPreviewDigest } from '../lib/session/remote-list.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractSkills } from '../lib/session/highlights.js';
 /**
@@ -32,6 +33,18 @@ export interface SessionPickerConfig {
     /** Lines the caller printed above the prompt (hidden-session footer). */
     linesAbovePrompt?: number;
 }
+export declare function setRemotePreviewRepaint(repaint?: () => void): void;
+export declare function setPeerDigestFetcherForTest(fetcher?: typeof fetchPeerPreviewDigest): void;
+export declare function clearRemoteDigestCacheForTest(): void;
+/**
+ * Validate + scrub a peer-supplied preview digest before any of it reaches this
+ * terminal. Peer JSON is untrusted at this boundary — the same rule
+ * `sanitizeMeta` applies to fan-out rows — so every string is stripped of
+ * terminal escapes and every list re-shaped field by field. Anything that
+ * doesn't look like the v1 digest is rejected, so a version-skewed peer
+ * degrades to the metadata card instead of a corrupted pane.
+ */
+export declare function sanitizeRemoteDigest(raw: unknown): SessionPreviewDigest | undefined;
 export declare function clearPreviewMemoryCacheForTest(): void;
 export declare function loadSessionPreviewDigest(session: SessionMeta): {
     digest?: SessionPreviewDigest;

package/dist/commands/sessions-picker.js

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import chalk from 'chalk';
 import { truncate, humanDuration } from '../lib/format.js';
+import { fetchPeerPreviewDigest } from '../lib/session/remote-list.js';
 import { parseSession, sanitizeForTerminal, SNAPSHOT_TODO_TOOLS } from '../lib/session/parse.js';
 import { safeTeamText } from '../lib/session/team-filter.js';
 import { cleanSessionPrompt, extractSessionTopic, isSyntheticUserMessage } from '../lib/session/prompt.js';
@@ -23,9 +24,10 @@ import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkil
 import { getSessionPlugins, readSessionPreviewCache, writeSessionPreviewCache, readSessionContent, readArchivedSessionPreview } from '../lib/session/db.js';
 /** A session whose transcript FILE is on another machine (folded in over the
  * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
- * preview can't parse it locally — it shows metadata + a "resume there" note
- * instead. Keys off `_remote`, not the machine tag, so locally-readable synced
- * mirrors still parse their file normally.
+ * preview can't parse it locally — it fetches the peer's digest over SSH and
+ * shows metadata + a "resume there" note until that lands. Keys off `_remote`,
+ * not the machine tag, so locally-readable synced mirrors still parse their
+ * file normally.
  *
  * This is the READ rule and only the read rule. Whether a session may be
  * RESUMED here is a different question with a different answer — a mirror is
@@ -106,6 +108,155 @@ const previewCache = createMemoryCache({
     max: 256,
     ttlMs: 5 * 60_000,
 });
+const remoteDigestCache = createMemoryCache({
+    max: 256,
+    ttlMs: 5 * 60_000,
+});
+function remoteDigestKey(sessionId, machine) {
+    return `${machine}:${sessionId}`;
+}
+/**
+ * The open picker's repaint trigger. The peer fetch resolves while the pane is
+ * already painted, so completion has to nudge the picker into re-rendering —
+ * pickers register their trigger here (via `registerPreviewRepaint`) and clear
+ * it when they close, making a late fetch after close a no-op.
+ */
+let remotePreviewRepaint;
+export function setRemotePreviewRepaint(repaint) {
+    remotePreviewRepaint = repaint;
+}
+/** Seam for tests: the real fetcher opens an SSH connection to the peer. */
+let peerDigestFetcher = fetchPeerPreviewDigest;
+export function setPeerDigestFetcherForTest(fetcher) {
+    peerDigestFetcher = fetcher ?? fetchPeerPreviewDigest;
+}
+export function clearRemoteDigestCacheForTest() {
+    remoteDigestCache.clear();
+}
+/**
+ * Look up (or start fetching) the peer digest for a remote row. Returns the
+ * current entry synchronously — `buildPreview` renders whatever state exists
+ * now, and the fetch's completion repaints the pane through the registered
+ * trigger.
+ */
+function remoteDigestForPreview(session, machine) {
+    const key = remoteDigestKey(session.id, machine);
+    const existing = remoteDigestCache.get(key);
+    if (existing)
+        return existing;
+    const pending = { state: 'pending' };
+    remoteDigestCache.set(key, pending);
+    void peerDigestFetcher(session.id, machine)
+        .then((raw) => {
+        const digest = sanitizeRemoteDigest(raw);
+        remoteDigestCache.set(key, digest ? { state: 'ready', digest } : { state: 'failed' });
+    })
+        .catch(() => {
+        remoteDigestCache.set(key, { state: 'failed' });
+    })
+        .then(() => remotePreviewRepaint?.());
+    return pending;
+}
+/**
+ * Validate + scrub a peer-supplied preview digest before any of it reaches this
+ * terminal. Peer JSON is untrusted at this boundary — the same rule
+ * `sanitizeMeta` applies to fan-out rows — so every string is stripped of
+ * terminal escapes and every list re-shaped field by field. Anything that
+ * doesn't look like the v1 digest is rejected, so a version-skewed peer
+ * degrades to the metadata card instead of a corrupted pane.
+ */
+export function sanitizeRemoteDigest(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const d = raw;
+    if (d.schemaVersion !== 1)
+        return undefined;
+    const str = (v) => (typeof v === 'string' ? sanitizeForTerminal(v) : '');
+    const optStr = (v) => (typeof v === 'string' ? sanitizeForTerminal(v) : undefined);
+    const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+    const optNum = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+    const strList = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string').map(sanitizeForTerminal) : [];
+    const objList = (v, map) => Array.isArray(v)
+        ? v.flatMap((x) => {
+            if (!x || typeof x !== 'object' || Array.isArray(x))
+                return [];
+            const mapped = map(x);
+            return mapped === undefined ? [] : [mapped];
+        })
+        : [];
+    let todos;
+    if (d.todos && typeof d.todos === 'object' && !Array.isArray(d.todos)) {
+        const t = d.todos;
+        const items = objList(t.items, (it) => {
+            const content = str(it.content ?? it.text);
+            if (!content)
+                return undefined;
+            const status = it.status === 'completed' || it.status === 'in_progress' ? it.status : 'pending';
+            return { content, status, activeForm: optStr(it.activeForm) };
+        });
+        todos = { items, done: num(t.done), total: num(t.total), activeForm: optStr(t.activeForm) };
+    }
+    const changes = d.changes && typeof d.changes === 'object' && !Array.isArray(d.changes)
+        ? {
+            created: num(d.changes.created),
+            modified: num(d.changes.modified),
+            deleted: num(d.changes.deleted),
+        }
+        : { created: 0, modified: 0, deleted: 0 };
+    let test;
+    if (d.test && typeof d.test === 'object' && !Array.isArray(d.test)) {
+        const t = d.test;
+        const runner = str(t.runner);
+        if (runner) {
+            test = { runner, ok: t.ok === true, ts: num(t.ts), passed: optNum(t.passed), failed: optNum(t.failed) };
+        }
+    }
+    return {
+        schemaVersion: 1,
+        firstUser: str(d.firstUser),
+        lastAssistant: str(d.lastAssistant),
+        filesRead: num(d.filesRead),
+        toolCalls: num(d.toolCalls),
+        planFile: str(d.planFile),
+        todos,
+        subAgentCount: num(d.subAgentCount),
+        toolTags: strList(d.toolTags),
+        changes,
+        dirs: strList(d.dirs),
+        repos: strList(d.repos),
+        artifacts: objList(d.artifacts, (a) => {
+            const p = str(a.path);
+            const basename = str(a.basename);
+            if (!p || !basename)
+                return undefined;
+            const bucket = a.bucket === 'artifacts' || a.bucket === 'plans' || a.bucket === 'reports' ? a.bucket : 'docs';
+            return { path: p, basename, bucket };
+        }),
+        skills: objList(d.skills, (s) => {
+            const name = str(s.name);
+            return name ? { name, count: num(s.count) } : undefined;
+        }),
+        plugins: strList(d.plugins),
+        hooks: objList(d.hooks, (h) => {
+            const name = str(h.name);
+            return name ? { name, event: optStr(h.event), count: num(h.count), failed: num(h.failed) } : undefined;
+        }),
+        links: objList(d.links, (l) => {
+            const url = str(l.url);
+            const label = str(l.label);
+            // Only http(s) URLs render as OSC 8 hyperlinks — anything else a peer
+            // sends (file:, a bare payload) is dropped rather than linkified.
+            return /^https?:\/\//.test(url) && label ? { kind: 'other', url, label } : undefined;
+        }),
+        errorCount: num(d.errorCount),
+        firstError: optStr(d.firstError),
+        toolHistogram: objList(d.toolHistogram, (h) => {
+            const tool = str(h.tool);
+            return tool ? { tool, count: num(h.count) } : undefined;
+        }),
+        test,
+    };
+}
 function previewCacheKey(session, remote) {
     let fileStamp = '';
     if (!remote && session.filePath) {
@@ -117,10 +268,16 @@ function previewCacheKey(session, remote) {
             fileStamp = 'missing';
         }
     }
+    // A remote row's rendered pane depends on the fetched digest's state
+    // (none → pending → ready/failed), so the state rides the key — otherwise the
+    // memoized metadata-only card would keep serving after the digest arrived.
+    const remoteDigestState = remote
+        ? remoteDigestCache.get(remoteDigestKey(session.id, remote))?.state ?? 'none'
+        : '';
     // The transcript stamp invalidates derived activity. Metadata that can change
     // independently (label/ticket/PR/live scanner enrichment) also rides the key.
     return JSON.stringify([
-        remote ?? '', session.id, fileStamp, session.lastActivity, session.label,
+        remote ?? '', remoteDigestState, session.id, fileStamp, session.lastActivity, session.label,
         session.topic, session.ticketId, session.prUrl, session.messageCount,
         session.tokenCount, session.model, session.todos, session.plan,
         session.recentDirectoriesTouched, session.skillsUsed,
@@ -181,13 +338,26 @@ export function buildPreview(session) {
         return cached;
     const safe = sanitizeMeta(session);
     // Remote session: the transcript is on the peer's disk, so there is nothing to
-    // parse here. Show the metadata header (agent, cwd, msgs, tokens — all carried
-    // over in the fan-out) plus where it lives and how to open it.
+    // parse here. Fetch the peer's already-computed digest over SSH (kicked off on
+    // first render; the pane repaints when it lands) and render the same compact
+    // preview a local row gets. Until it arrives — or when the peer can't answer —
+    // show the metadata header (agent, cwd, msgs, tokens — all carried over in the
+    // fan-out) plus where it lives and how to open it.
     if (remote) {
         const note = '  ' + chalk.gray(`on `) + chalk.bold.white(remote)
             + chalk.gray(` — enter to resume there, or space then enter to read it over SSH`);
+        const entry = remoteDigestForPreview(session, remote);
+        if (entry.state === 'ready') {
+            const body = formatCompactPreview(entry.digest, safe);
+            const output = [formatHeader(safe, []), '', note, body].filter(Boolean).join('\n');
+            previewCache.set(cacheKey, output);
+            return output;
+        }
+        const fetching = entry.state === 'pending'
+            ? '  ' + chalk.gray(`fetching preview from ${remote} over SSH…`)
+            : '';
         const metaBody = formatMetaOnlyBody(safe);
-        const output = [formatHeader(safe, []), '', note, metaBody].filter(Boolean).join('\n');
+        const output = [formatHeader(safe, []), '', note, fetching, metaBody].filter(Boolean).join('\n');
         previewCache.set(cacheKey, output);
         return output;
     }
@@ -895,13 +1065,17 @@ export async function sessionPicker(config) {
         filter: config.filter,
         labelFor: config.labelFor,
         buildPreview,
+        // A remote row's digest arrives over SSH after the pane painted — this is
+        // what lets its completion swap the metadata card for the full preview.
+        registerPreviewRepaint: setRemotePreviewRepaint,
         shortIdFor: (s) => s.shortId,
         pageSize: config.pageSize,
         initialSearch: config.initialSearch,
         emptyMessage: 'No sessions match.',
         enterHint: config.enterHint ?? 'resume',
         linesAbovePrompt: config.linesAbovePrompt,
-    });
+        // A late digest fetch must not poke a closed prompt.
+    }).finally(() => setRemotePreviewRepaint(undefined));
     if (!picked)
         return null;
     return { session: picked.item, action: 'resume' };

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

@@ -1,15 +1,16 @@
 import type { Command } from 'commander';
 import { type SessionMeta } from '../lib/session/types.js';
 import { type Backend, type EngineContext, type Packing } from '../lib/terminal/index.js';
+import { type StrictResumeOptions } from './resume.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export declare const CONFIRM_THRESHOLD = 5;
-export interface ResumeOptions {
+export interface ResumeOptions extends StrictResumeOptions {
     agent?: string;
     all?: boolean;
     teams?: boolean;
     since?: string;
     limit?: string;
-    host?: string;
+    device?: string;
     iterm?: boolean;
     ghostty?: boolean;
     tmux?: boolean;
@@ -24,12 +25,15 @@ export declare function registerSessionsResumeCommand(sessionsCmd: Command): voi
 /** IDs and tmux aliases are actions, not picker search text. Human phrases keep
  * the existing pre-filtered picker, while an explicit identity resumes directly. */
 export declare function isDirectResumeSelector(query: string): boolean;
-/** Re-enter through the top-level command so fleet routing and harness policy
+/** Re-enter through sessions resume so fleet routing and harness policy
  * stay centralized. The child inherits this terminal for a real interactive resume. */
 export declare function resumeSelectorInPlace(selector: string): Promise<void>;
 /** Direct identities use focus as the lifecycle dispatcher: it rechecks the
  * live fleet, attaches a healthy pane, and falls through to `agents resume`
  * only when the process is no longer attachable. */
+/** True when `sessions resume <id> --attach-only|--local` must go through
+ *  `sessions focus` instead of `runStrictResume` (which can fork a copy). */
+export declare function resumeUsesLifecycleDispatch(query: string | undefined, prompt: string | undefined, options: Pick<ResumeOptions, 'attachOnly' | 'local' | 'mode' | 'interactive' | 'headless' | 'here'>): boolean;
 export declare function dispatchSessionLifecycleInPlace(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): Promise<void>;
 export declare function buildSessionLifecycleArgs(selector: string, hosts?: string[], attachOnly?: boolean, local?: boolean): string[];
 export declare function resolveResumePacking(options: Pick<ResumeOptions, 'splits'>): Packing;