@phnx-labs/agents-cli 1.22.107 → 1.22.110

package/dist/commands/sessions-backfill.js

@@ -7,6 +7,7 @@ import { SESSION_AGENTS } from '../lib/session/types.js';
 import { ensureToolIndex, readToolIndexCoverage } from '../lib/session/tool-index.js';
 import { NO_FANOUT_ENV } from '../lib/session/remote-active.js';
 import { backfillResourceUsage } from '../lib/session/db.js';
+import { runSessionTitleTick, SESSION_TITLE_MAX_PER_TICK } from '../lib/session/title.js';
 const BACKFILL_REMOTE_TIMEOUT_MS = 10 * 60_000;
 function parseAgent(value) {
     if (!value)
@@ -181,6 +182,31 @@ export async function runResourceBackfill(options) {
         ...result,
     };
 }
+/**
+ * Generate session headlines NOW instead of waiting for the daemon's sweep — the
+ * explicit-refresh half of PHNX-3797. Same code path the `session-title` service
+ * ticks, so there is one generator: this only changes when it runs, how many it
+ * does, and (with `--refresh`) whether an already-current title is regenerated.
+ */
+export async function runTitlesBackfill(options) {
+    const parsedLimit = options.limit ? Number.parseInt(options.limit, 10) : undefined;
+    if (options.limit !== undefined && (!Number.isFinite(parsedLimit) || parsedLimit < 1)) {
+        throw new Error(`--limit must be a positive integer (got "${options.limit}")`);
+    }
+    const result = await runSessionTitleTick({
+        ...(options.session ? { id: options.session } : {}),
+        ...(options.run ? { run: options.run } : {}),
+        limit: parsedLimit ?? (options.session ? 1 : SESSION_TITLE_MAX_PER_TICK * 5),
+        force: Boolean(options.refresh),
+    });
+    return {
+        schemaVersion: 1,
+        kind: 'titles-backfill',
+        generatedAt: new Date().toISOString(),
+        machine: machineId(),
+        ...result,
+    };
+}
 export function registerSessionsBackfillCommand(sessionsCmd) {
     const backfill = sessionsCmd.command('backfill').description('Populate derived session data explicitly.');
     const tools = backfill.command('tools').description('Parse historical tool calls once into the local SQLite index.');
@@ -265,4 +291,50 @@ export function registerSessionsBackfillCommand(sessionsCmd) {
             process.exitCode = 1;
         }
     });
+    const titles = backfill
+        .command('titles')
+        .description('Generate the session-row headline (a short technical title) now, instead of waiting for the daemon.')
+        .option('--session <id>', 'Title one session (full or short id), even if it is old or already titled')
+        .option('--limit <n>', 'Maximum titles to generate in this run')
+        .option('--refresh', 'Regenerate even when the stored title still matches the session\'s first user message')
+        .option('--json', 'Emit the machine-readable result');
+    setHelpSections(titles, {
+        examples: `
+      # Catch this machine up now (the daemon otherwise does a couple every 2 min)
+      agents sessions backfill titles
+
+      # Re-title one session after correcting its first message
+      agents sessions backfill titles --session 6fc1db18 --refresh
+
+      # Machine-readable
+      agents sessions backfill titles --limit 20 --json
+    `,
+        notes: `
+      - The headline ladder is: \`/rename\` label > this generated title > the user's first message. It is never the agent's latest turn.
+      - One cheap-model call per session (\`--model cheap\`, read-only plan mode), generated ONCE and persisted; a session whose first message has not changed is a pure cache hit.
+      - Local-only: each box titles its own sessions and publishes them to the fleet via the session mirror, so a peer's rows already carry their titles.
+      - Best-effort. With no signed-in harness nothing is generated and rows keep showing the user's own words.
+    `,
+    });
+    titles.action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        try {
+            const envelope = await runTitlesBackfill(options);
+            if (options.json)
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            else {
+                console.log(`${envelope.machine}: generated ${envelope.generated.toLocaleString()} title${envelope.generated === 1 ? '' : 's'}; ` +
+                    `${envelope.cached.toLocaleString()} already current, ${envelope.scanned.toLocaleString()} scanned.`);
+                for (const { id, title } of envelope.titles)
+                    console.log(`  ${chalk.cyan(id.slice(0, 8))}  ${title}`);
+                if (envelope.failed > 0) {
+                    console.log(chalk.yellow(`${envelope.failed.toLocaleString()} session${envelope.failed === 1 ? '' : 's'} produced no usable title; rerun to retry.`));
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/commands/sessions-backup-setup.d.ts

@@ -0,0 +1,12 @@
+import type { Command } from 'commander';
+interface BackupSetupOptions {
+    bundle: string;
+    worker: string;
+    bucket: string;
+    account?: string;
+    token?: string;
+    domain: string;
+}
+export declare function handleSessionsBackupSetup(opts: BackupSetupOptions): Promise<void>;
+export declare function registerSessionsBackupSetupCommand(sessionsCmd: Command): void;
+export {};

package/dist/commands/sessions-backup-setup.js

@@ -0,0 +1,65 @@
+// `agents sessions backup-setup` — the OPERATOR command that provisions the
+// managed session-backup endpoint (`sessions.agents-cli.sh`): the Cloudflare
+// Worker + R2 bucket a signed-in user's `sessions export --to-r2` talks to with
+// NO `r2.backups` bucket of their own. It is the deploy producer for that
+// endpoint — first-party infrastructure, not a per-user step. The zero-knowledge
+// `--byo` backup path uses the user's own R2 bucket directly and never touches
+// this Worker, so there is nothing here for an ordinary user to run.
+//
+// Mirrors `agents traces setup`: the same `readCloudflareCreds` bundle plumbing,
+// the same idempotent `deployWorker`/`createBucket` primitives. Provisioning is
+// idempotent — re-running redeploys the current Worker template in place.
+import chalk from 'chalk';
+import { DEFAULT_CF_BUNDLE, readCloudflareCreds } from '../lib/share/config.js';
+import { PHOENIX_ID_BASE } from '../lib/identity/client.js';
+import { provisionSessions } from '../lib/session/sync/provision.js';
+import { DEFAULT_SESSIONS_BUCKET_NAME, DEFAULT_SESSIONS_DOMAIN, DEFAULT_SESSIONS_WORKER_NAME, } from '../lib/session/sync/managed-config.js';
+import { setHelpSections } from '../lib/help.js';
+export async function handleSessionsBackupSetup(opts) {
+    const { input } = await import('@inquirer/prompts');
+    const { apiToken, accountId: bundledAccountId } = readCloudflareCreds(opts.bundle, {
+        apiToken: opts.token,
+        accountId: opts.account,
+    });
+    const accountId = opts.account ?? bundledAccountId ?? await input({ message: 'Cloudflare account id' });
+    if (!accountId)
+        throw new Error('A Cloudflare account id is required.');
+    const result = await provisionSessions({
+        apiToken,
+        accountId,
+        workerName: opts.worker,
+        bucketName: opts.bucket,
+        domain: opts.domain,
+        phoenixIdBase: PHOENIX_ID_BASE,
+    });
+    console.log(chalk.green(`Managed session-backup endpoint ready → ${chalk.bold(result.baseUrl)}`));
+    console.log(chalk.dim('Signed-in users now back up with `agents sessions export --to-r2` — no r2.backups bucket.'));
+}
+const BACKUP_SETUP_EXAMPLES = `
+  $ agents secrets exec cloudflare -- agents sessions backup-setup
+  Provision the managed session-backup Worker + R2 bucket (creds from the bundle).
+
+  $ agents sessions backup-setup --account <id> --domain sessions.example.com
+  Provision against a private account service and custom domain.
+`.trimStart();
+export function registerSessionsBackupSetupCommand(sessionsCmd) {
+    const cmd = sessionsCmd
+        .command('backup-setup')
+        .description('(operator) Provision the managed session-backup Worker + R2 bucket — NOT a per-user step; signing in with `agents auth login` backs sessions up with zero setup')
+        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
+        .option('--worker <name>', 'Worker name', DEFAULT_SESSIONS_WORKER_NAME)
+        .option('--bucket <name>', 'R2 bucket name', DEFAULT_SESSIONS_BUCKET_NAME)
+        .option('--account <id>', 'Cloudflare account id (else read from the bundle / prompt)')
+        .option('--token <token>', 'Cloudflare API token (else read from the --bundle)')
+        .option('--domain <host>', 'custom domain to map', DEFAULT_SESSIONS_DOMAIN)
+        .action(async (opts) => {
+        try {
+            await handleSessionsBackupSetup(opts);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+    setHelpSections(cmd, { examples: BACKUP_SETUP_EXAMPLES });
+}

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

@@ -43,9 +43,9 @@ export declare function matchInjectSelector(session: ActiveSession, token: strin
  * merges the parent `sessions` command's variadic `-D, --device <target...>` over
  * this subcommand's scalar `--device`, so a single `--device box` arrives as
  * `['box']` — which flowed straight into `sshExec` and crashed on
- * `host.startsWith` (PHNX-3688). Coerce the array to its one element; fail loud on
- * several, since inject delivers to exactly one terminal (a fan-out spelling is a
- * user error, not a first-of-list guess).
+ * `host.startsWith` (PHNX-3688). Delegates to the shared
+ * {@link normalizeSingleDeviceOption} (also used by `sessions resume`,
+ * PHNX-3940) rather than re-implementing the array/scalar coercion here.
  */
 export declare function normalizeInjectDevice(value: string | string[] | undefined): string | undefined;
 /**

package/dist/commands/sessions-inject.js

@@ -19,6 +19,7 @@ import { sshExec, shellQuote } from '../lib/ssh-exec.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { setHelpSections } from '../lib/help.js';
+import { normalizeSingleDeviceOption } from './utils.js';
 /**
  * Whether an active session is the one `sessions inject <token>` means. Matches
  * a resolvable session id (exact or unique prefix) AND — for a tmux-hosted row
@@ -47,19 +48,12 @@ export function matchInjectSelector(session, token) {
  * merges the parent `sessions` command's variadic `-D, --device <target...>` over
  * this subcommand's scalar `--device`, so a single `--device box` arrives as
  * `['box']` — which flowed straight into `sshExec` and crashed on
- * `host.startsWith` (PHNX-3688). Coerce the array to its one element; fail loud on
- * several, since inject delivers to exactly one terminal (a fan-out spelling is a
- * user error, not a first-of-list guess).
+ * `host.startsWith` (PHNX-3688). Delegates to the shared
+ * {@link normalizeSingleDeviceOption} (also used by `sessions resume`,
+ * PHNX-3940) rather than re-implementing the array/scalar coercion here.
  */
 export function normalizeInjectDevice(value) {
-    const list = value == null ? [] : Array.isArray(value) ? value : [value];
-    const hosts = list.map((v) => String(v).trim()).filter((v) => v.length > 0);
-    if (hosts.length === 0)
-        return undefined;
-    if (hosts.length > 1) {
-        throw new Error(`sessions inject targets a single device, but --device named ${hosts.length}: ${hosts.join(', ')}.`);
-    }
-    return hosts[0];
+    return normalizeSingleDeviceOption(value, 'sessions inject');
 }
 /**
  * The `agents sessions inject` argv to re-run ON a device (its tmux panes live

package/dist/commands/sessions-picker.js

@@ -106,6 +106,7 @@ function sanitizeMeta(s) {
         topic: clean(s.topic),
         firstUserMessage: clean(s.firstUserMessage),
         label: clean(s.label),
+        generatedTitle: clean(s.generatedTitle),
         ticketId: clean(s.ticketId),
         prUrl: clean(s.prUrl),
         // A remote row's meta is peer-supplied JSON that parseRemoteList hands over
@@ -303,6 +304,7 @@ function previewCacheKey(session, remote) {
     // independently (label/ticket/PR/live scanner enrichment) also rides the key.
     return JSON.stringify([
         remote ?? '', remoteDigestState, session.id, fileStamp, session.lastActivity, session.label,
+        session.generatedTitle,
         session.topic, session.ticketId, session.prUrl, session.messageCount,
         session.tokenCount, session.model, session.todos, session.plan,
         session.recentDirectoriesTouched, session.skillsUsed,
@@ -489,13 +491,14 @@ function formatHeader(session, events) {
         line4.push(chalk.blue(linkUrl(session.prUrl, label)));
     }
     // Lead with the session's human title: `session.label` — an agent-generated
-    // name / `/rename`, else the `--name` launch handle. NOT `session.topic`: the
-    // topic is the derived first-prompt, already shown on the `Prompt:` line, so
-    // using it here too would print the same text twice. Unlabelled sessions keep
-    // that `Prompt:` line as their topic indicator and simply lead with the agent
-    // line. Wrapped to the pane (the header sits at column 0, full terminal width);
-    // nothing renders when there is no label.
-    const title = (session.label || '').trim();
+    // name / `/rename`, else the `--name` launch handle — else the daemon-generated
+    // title (PHNX-3797), which is a short technical NAME, not a restatement of the
+    // prompt. NOT `session.topic`: the topic is the derived first-prompt, already
+    // shown on the `Prompt:` line, so using it here too would print the same text
+    // twice. A session with neither keeps that `Prompt:` line as its topic
+    // indicator and simply leads with the agent line. Wrapped to the pane (the
+    // header sits at column 0, full terminal width).
+    const title = (session.label || session.generatedTitle || '').trim();
     const titleLines = title
         ? wrapToWidth(title, terminalWidth()).map(l => chalk.bold.white(l))
         : [];

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

@@ -1,6 +1,6 @@
-import type { Command } from 'commander';
+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 Backend, type SurfaceItem, 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;
@@ -24,6 +24,8 @@ export interface ResumeOptions extends StrictResumeOptions {
     runArgs?: string[];
 }
 export declare function registerSessionsResumeCommand(sessionsCmd: Command): void;
+/** Keep explicit parent options without replacing resume's own defaults. */
+export declare function resolveResumeOptions(cmd: Command, local: ResumeOptions): ResumeOptions;
 export declare function sessionsResumeAction(query: string | undefined, prompt: string | undefined, options: ResumeOptions): Promise<void>;
 /** Preserve run options and lifecycle intent when the picker opens its selected rows. */
 export declare function buildSelectedResumeArgs(id: string, prompt: string | undefined, options: ResumeOptions): string[];
@@ -33,6 +35,15 @@ export declare function isDirectResumeSelector(query: string): boolean;
 /** 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>;
+/**
+ * Local preflight cannot inspect a peer's files or index. Leave peer validation
+ * to the existing origin-device recovery hop. --here without a remote surface
+ * opts into local recovery and therefore uses the local transcript guard.
+ */
+export declare function partitionResumableSelections(chosen: SessionMeta[], options?: Pick<ResumeOptions, 'here' | 'device'>): {
+    resumable: SessionMeta[];
+    skipped: SessionMeta[];
+};
 /** 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. */
@@ -42,6 +53,10 @@ export declare function resumeUsesLifecycleDispatch(query: string | undefined, p
 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;
+/** Surface commands use shell words; spawnCliInPlace keeps the original argv. */
+export declare function buildSelectedResumeSurface(session: SessionMeta, prompt: string | undefined, options: ResumeOptions): SurfaceItem & {
+    session: SessionMeta;
+};
 export declare function resumeHostMismatch(session: Pick<SessionMeta, 'shortId' | 'machine'>, requestedHost: string, self?: string): string | null;
 /**
  * Decide which backend to launch into. Returns a concrete backend, `'inplace'`

package/dist/commands/sessions-resume.js

@@ -12,6 +12,7 @@
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
+import { Option } from 'commander';
 import { isAgentTmuxAlias } from '../lib/session/types.js';
 import { discoverSessions } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
@@ -19,16 +20,18 @@ import { multiItemPicker, itemPicker } from '../lib/picker.js';
 import { buildPreview } from './sessions-picker.js';
 import { formatPickerLabel, pickerColumnsFor, resolveSessionMetadataValue, parseAgentFilter, } from './sessions.js';
 import { sessionMatchesQuery } from './sessions-browser.js';
-import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, } from '../lib/terminal/index.js';
-import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { openSurfaces, availableBackends, detectCurrentBackend, currentContext, shellQuote, } from '../lib/terminal/index.js';
+import { isInteractiveTerminal, isPromptCancelled, normalizeSingleDeviceOption } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
 import { confirm } from '@inquirer/prompts';
 import { spawn } from 'node:child_process';
 import { looksLikeSessionId } from '../lib/session/discover.js';
 import { machineId } from '../lib/session/sync/config.js';
-import { sessionOriginDevice, sessionRecoveryDestinationMatches } from '../lib/session/recovery.js';
+import { sessionOriginDevice, sessionRecoveryDestinationMatches, sessionRecoveryPeer, sessionTranscriptReadable } from '../lib/session/recovery.js';
 import { buildResumeRemoteArgs, runStrictResume, wantsStrictResume } from './resume.js';
+import { toRemotePortable } from '../lib/project-root.js';
 import { attachLocalLiveSelector } from '../lib/session/local-tmux-attach.js';
+import { sessionHeadline } from '../lib/session/title.js';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
 export function registerSessionsResumeCommand(sessionsCmd) {
@@ -44,6 +47,8 @@ export function registerSessionsResumeCommand(sessionsCmd) {
         .option('--teams', 'Include team-spawned sessions (hidden by default)')
         .option('--since <time>', 'Only sessions newer than this (e.g., 2h, 7d, 4w, or ISO date)')
         .option('-n, --limit <n>', 'Maximum number of sessions to load into the picker', '200')
+        .addOption(new Option('--resume-device <alias>').hideHelp()
+        .argParser((value, previous = []) => [...previous, value]))
         .option('--device <alias>', 'Open on the session origin device over SSH; the device must match every selected session')
         .option('--iterm', 'Force the iTerm backend')
         .option('--ghostty', 'Force the Ghostty backend')
@@ -98,13 +103,39 @@ export function registerSessionsResumeCommand(sessionsCmd) {
       - --vscodium opens each session as an agent terminal tab in VSCodium via the swarm-ext extension (works with --device too).
       - --device <alias> opens the terminal surface on that device only when it is the selected sessions' origin; recovery never migrates a session to another device.
       - Recovery uses the installed harness and the conversation's account on its origin device. Context replay requires an explicit choice.
+      - Local picks without transcripts are skipped before opening a tab. Remote picks are validated on their origin device.
       - agents run claude --resume opens this same picker; claude#work filters it with --account work.
     `,
     });
     cmd.action(async (query, prompt, options) => {
-        await sessionsResumeAction(query, prompt, options);
+        await sessionsResumeAction(query, prompt, resolveResumeOptions(cmd, options));
     });
 }
+/** Flag names `sessions resume` declares that also exist on its parent `sessions`
+ *  command. Booleans and strings only — `device` collides too but needs its own
+ *  array-merge handling below, so it is not in this list. */
+const RESUME_PARENT_COLLISION_FLAGS = ['agent', 'all', 'teams', 'since', 'limit', 'local'];
+/** Keep explicit parent options without replacing resume's own defaults. */
+export function resolveResumeOptions(cmd, local) {
+    const parent = cmd.parent;
+    const { resumeDevice, ...resolved } = local;
+    const parentOpts = parent?.opts();
+    for (const key of RESUME_PARENT_COLLISION_FLAGS) {
+        if (parent?.getOptionValueSource(key) === 'cli') {
+            resolved[key] = parentOpts?.[key];
+        }
+    }
+    const rawDeviceTargets = [
+        ...(resumeDevice ?? []),
+        ...(local.device ? [local.device] : []),
+        ...(parentOpts?.device ?? []),
+        ...(parentOpts?.devices ?? []),
+    ];
+    if (rawDeviceTargets.length > 0) {
+        resolved.device = normalizeSingleDeviceOption(rawDeviceTargets, 'sessions resume');
+    }
+    return resolved;
+}
 export async function sessionsResumeAction(query, prompt, options) {
     if (options.attachOnly && (prompt !== undefined || options.agent || options.account || options.model || options.mode || options.interactive || options.headless || options.cwd || options.here)) {
         throw new Error('--attach-only cannot be combined with --agent, a follow-up prompt, or options that change the running session. Pass the session ID without filters.');
@@ -232,12 +263,16 @@ export async function sessionsResumeAction(query, prompt, options) {
         }
     }
     // 2. Route every selection through the owning device's recovery resolver.
-    const items = [];
-    for (const s of chosen) {
-        const command = ['agents', ...buildSelectedResumeArgs(s.id, prompt, options)];
-        const cwd = s.cwd && fs.existsSync(s.cwd) ? s.cwd : process.cwd();
-        items.push({ session: s, cwd, command });
+    const { resumable, skipped } = partitionResumableSelections(chosen, options);
+    for (const s of skipped) {
+        console.log(chalk.yellow(`Skipping ${s.shortId} — nothing to resume (no transcript was written).`));
     }
+    if (resumable.length === 0) {
+        console.error(chalk.red('Nothing to resume — no selected session has a transcript.'));
+        process.exitCode = 1;
+        return;
+    }
+    const items = resumable.map((session) => buildSelectedResumeSurface(session, prompt, options));
     // 3. Resolve the backend (and host).
     const ctx = currentContext();
     const backend = await resolveBackend(options, ctx, items.length);
@@ -279,7 +314,7 @@ export async function sessionsResumeAction(query, prompt, options) {
         command: it.command,
         agent: it.session.agent || undefined,
         sessionId: it.session.id || undefined,
-        title: it.session.label || it.session.topic || undefined,
+        title: sessionHeadline(it.session),
     })), { backend, host: options.device, packing });
     let opened = 0;
     results.forEach((r, i) => {
@@ -294,6 +329,8 @@ export async function sessionsResumeAction(query, prompt, options) {
         }
     });
     console.log(chalk.gray(`\nOpened ${opened}/${items.length} in ${where}.`));
+    if (opened !== items.length)
+        process.exitCode = 1;
 }
 /** Preserve run options and lifecycle intent when the picker opens its selected rows. */
 export function buildSelectedResumeArgs(id, prompt, options) {
@@ -307,6 +344,7 @@ export function buildSelectedResumeArgs(id, prompt, options) {
         // The outer surface already placed this terminal on the selected device.
         if (options.device) {
             let remoteCwd;
+            let localCwd;
             for (let i = 0; i < args.length && args[i] !== '--'; i++) {
                 if (args[i] === '--remote-cwd') {
                     remoteCwd = args[i + 1];
@@ -316,6 +354,14 @@ export function buildSelectedResumeArgs(id, prompt, options) {
                     remoteCwd = args[i].slice('--remote-cwd='.length);
                     args.splice(i--, 1);
                 }
+                else if (args[i] === '--cwd') {
+                    localCwd = args[i + 1];
+                    args.splice(i--, 2);
+                }
+                else if (args[i].startsWith('--cwd=')) {
+                    localCwd = args[i].slice('--cwd='.length);
+                    args.splice(i--, 1);
+                }
                 else if (['-D', '--device', '--host', '--where', '--on', '--computer'].includes(args[i])) {
                     args.splice(i, 2);
                     i--;
@@ -325,9 +371,10 @@ export function buildSelectedResumeArgs(id, prompt, options) {
                     i--;
                 }
             }
-            if (remoteCwd !== undefined) {
+            const effectiveCwd = remoteCwd ?? options.cwd ?? (localCwd ? toRemotePortable(localCwd) : undefined);
+            if (effectiveCwd !== undefined) {
                 const end = args.indexOf('--');
-                args.splice(end < 0 ? args.length : end, 0, '--cwd', remoteCwd);
+                args.splice(end < 0 ? args.length : end, 0, '--cwd', effectiveCwd);
             }
         }
         return args;
@@ -352,6 +399,20 @@ export function isDirectResumeSelector(query) {
 export async function resumeSelectorInPlace(selector) {
     await spawnCliInPlace(['sessions', 'resume', selector]);
 }
+/**
+ * Local preflight cannot inspect a peer's files or index. Leave peer validation
+ * to the existing origin-device recovery hop. --here without a remote surface
+ * opts into local recovery and therefore uses the local transcript guard.
+ */
+export function partitionResumableSelections(chosen, options = {}) {
+    const resumable = [];
+    const skipped = [];
+    for (const s of chosen) {
+        const deferredToPeer = (!options.here || !!options.device) && sessionRecoveryPeer(s);
+        (deferredToPeer || sessionTranscriptReadable(s) ? resumable : skipped).push(s);
+    }
+    return { resumable, skipped };
+}
 /** 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. */
@@ -395,6 +456,21 @@ async function spawnCliInPlace(args) {
 export function resolveResumePacking(options) {
     return options.splits ? 'two-per-tab' : 'tabs';
 }
+/** Surface commands use shell words; spawnCliInPlace keeps the original argv. */
+export function buildSelectedResumeSurface(session, prompt, options) {
+    const requestedCwd = options.cwd || session.cwd;
+    if (options.device && !requestedCwd) {
+        throw new Error(`Cannot open ${session.shortId} on ${options.device} without a recorded working directory. Pass --cwd <path>.`);
+    }
+    const cwd = options.device
+        ? requestedCwd
+        : requestedCwd && fs.existsSync(requestedCwd) ? requestedCwd : process.cwd();
+    return {
+        session,
+        cwd,
+        command: ['agents', ...buildSelectedResumeArgs(session.id, prompt, options)].map(shellQuote),
+    };
+}
 export function resumeHostMismatch(session, requestedHost, self = machineId()) {
     const origin = sessionOriginDevice(session, self);
     return sessionRecoveryDestinationMatches(session, requestedHost, self)