@phnx-labs/agents-cli 1.22.107 → 1.22.109

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 1.22.109
+
+- **`agents sessions backup-setup` provisions the managed session-backup endpoint (PHNX-3726).** The operator command that deploys `sessions.agents-cli.sh` — the Cloudflare Worker + R2 bucket a signed-in user's `agents sessions export --to-r2` backs up to with no `r2.backups` bucket of their own. Mirrors `agents traces setup`: reads Cloudflare credentials from the `cloudflare` secrets bundle (`agents secrets exec cloudflare -- agents sessions backup-setup`), idempotent (re-running redeploys the current Worker template in place). It is NOT a per-user step — signing in with `agents auth login` is all a user does; this is how the first-party endpoint itself is deployed. The Worker it deploys is Phoenix-only with no static token (PHNX-3726). Source: `cli/src/commands/sessions-backup-setup.ts`, `cli/src/lib/session/sync/provision.ts` (+ `provision.test.ts`), `cli/docs/sessions.md`.
+
+- **`agents doctor` flags a leaked daemon no owner record names (W4, PHNX-3736).**
+  A headless e2e session launched `agents __daemon-run` under
+  `HOME=/tmp/pin-e2e-<pid>` and never stopped it; the daemon ran 4+ days,
+  invisible to the pid-file takeover because it keeps its own pid file under the
+  temp home. `agents doctor` now reports any same-uid `__daemon-run` whose pid is
+  neither the service manager's unit main PID nor the recorded `daemon.pid` —
+  checked against both the caller's HOME and the real account home, so a
+  test-harness caller never accuses the production daemon — as a `leaked-daemon`
+  warning carrying the process's HOME and start time, with a `kill <pid>`
+  remediation. Source: `cli/src/lib/daemon/leaked-daemons.ts`,
+  `cli/src/lib/devices/doctor-findings.ts`.
+
+- **`agents daemon start` refuses under a redirected HOME unless
+  `AGENTS_ALLOW_TEST_DAEMON=1` (W4, PHNX-3736).** RUSH-3021 gated auto-start from
+  a sandbox/test HOME but left the explicit `startDaemon()` open — the path the
+  e2e harness took to leak the `/tmp/pin-e2e-<pid>` daemon. The launch now throws
+  `RedirectedHomeDaemonError` (printed without a stack, exit 1); a deliberate
+  test/e2e launch opts in with `AGENTS_ALLOW_TEST_DAEMON=1` and owns stopping
+  what it starts. Reporting an already-running daemon — and therefore
+  `agents daemon stop` of a leaked one — is not gated. Auto-start side effects
+  (`routines add`, webhook fires, `monitors add`) state the refusal and leave
+  the foreground command green, the same tier split as the auto-start circuit
+  breaker; only the explicit start commands fail loud. Source:
+  `cli/src/lib/daemon/daemon.ts` (`startDaemon`).
+
+- **The managed share Worker now proxies same-origin human collaboration to Prix (PHNX-3835).** The Cloudflare Worker that fronts a managed share gains a `/__collab/*` transport so authorized humans can review a hosted artifact together (comments now; agent mentions/wake-up later). It stays the trust boundary exactly as the page GET does: every `/__collab` request loads the R2 object FIRST (a missing/just-deleted share 404s, so existence is never enumerable), re-derives the share id (`SHA-256(ownerId + NUL + normalized path)`), current revision (etag), owner, visibility, org domain, and producer provenance SERVER-SIDE from R2 metadata — the browser-supplied `share` is a lookup key only, never trusted as identity — then reuses the EXACT page read gate (me/org identity gate + private viewer-token gate) with every denial normalized to 404. Public/unlisted readers may read anonymously; every write additionally requires a verified signed-in Phoenix human; private still requires its share token. It proxies to the Prix `/v1/artifact-collaboration` routes (`context`, `threads` list/create, thread replies, comment/thread PATCH, SSE `events`, and a best-effort authenticated `purge` on share delete) with the service token in `Authorization` (never surfaced to the browser) plus trusted `X-Artifact-*` / `X-Phoenix-Actor-*` headers, preserves the client `Idempotency-Key` and `Last-Event-ID`, streams SSE through unbuffered (cancel/disconnect propagated), and marks every collaboration response `no-store`. A visibility downgrade is immediate (re-gated per request) and a deleted share drops its comments the instant the object is gone. The whole surface fails closed (404) when `PRIX_ARTIFACT_COLLAB_BASE` / `ARTIFACT_COLLAB_SERVICE_TOKEN` are absent — so BYO endpoints (no Phoenix identity) never expose it and the artifact page GET is unaffected — and stays dormant until an operator sets both secrets, which `agents artifacts share update`/`setup` now apply on a managed deploy (both or neither). Because the Worker template changed, already-deployed managed endpoints read `outdated` until re-run through `agents artifacts share update`. Source: `cli/src/lib/share/worker-template.ts`, `cli/src/lib/share/provision.ts`, `cli/src/lib/share/backend.ts`, `cli/src/commands/share.ts`, `cli/docs/share.md`.
+
+- **`agents sync --dry-run` no longer mutates every native home (PHNX-3923).** The umbrella verb (bare `agents sync`, including `--local`/`--yes`/`--json`) ignored `--dry-run` entirely: it ran the full reconcile, evicted central browser profiles, verified, and repaired — mutating every installed version home despite the preview flag. The umbrella composes only mutating stages (repo `git pull`, `refresh()` reconcile, device sync, `repairAfterSync`) with no non-mutating preview, so it now refuses `--dry-run` LOUD and up front — before any change — and points at the scoped path (`agents sync <agent> --dry-run`), which honors it non-destructively. `--json` reports `{ ok: false, mode: 'umbrella', dryRun: true, error, hint, installedAgents }`. Source: `cli/src/commands/sync.ts`.
+
+- Terminal session resumes preserve follow-up prompts, including spaces and shell characters. Remote terminals use the origin directory or explicit `--cwd`; run pickers retain `--remote-cwd` precedence, and home-relative paths expand on the target. An invalid remote directory or failed terminal launch reports failure.
+
+- Publishes the session-resume fixes from the unshipped 1.22.108 candidate: account homes refresh their session tracker, Codex hook trust follows registration, empty local picks are skipped, and remote picks are validated on their origin device. The 1.22.108 tag is preserved; npm publication resumes with this patch after correcting its release notes.
+
+- **`agents view` shows OpenCode's real model, account, plan, and last-active (PHNX-3982).** The OpenCode row was the only one in the table with nothing usable in it — `1.18.15 (default)  default  id:meta+openai+opencode-go` — while every other harness showed a model, an email, and a plan. Three separate reads were pointed at the wrong place. (1) The model came from `<home>/.opencode/settings.json`, which is agents-cli's own plugin-enablement file; OpenCode reads `~/.config/opencode/opencode.{jsonc,json}`, and ships no catalog default, so the row fell through to the literal placeholder `default`. Both spellings are now read comment-tolerantly, and when nothing is configured the row shows the model OpenCode itself will start with, from the selection it persists to `$XDG_STATE_HOME/opencode/model.json`. (2) The account showed only the provider join because the code asserted OpenCode's `auth.json` carries no identity — it does, for `type: 'oauth'` providers, in the same namespaced JWT claims `case 'codex'` already decodes, so the email and plan now render (secrets are never read out, only claims). (3) `lastActive` was blank because the per-file session walk finds nothing for a harness that keeps every session in one sqlite file; it now dates from `opencode.db`. Live usage *windows* remain unavailable for OpenCode — it records no rate-limit state locally and each provider would need its own reader. Source: `cli/src/lib/agent-spec/agents.ts`, `cli/src/lib/models.ts`.
+
+## 1.22.108
+
+- Account sync now refreshes the native session-tracking hook in every account home, replacing stale registrations from previous CLI installations so new sessions retain their account identity. Codex tracker installation also refreshes hook trust so headless runs can execute the registered hook.
+
+- Resume selection validates peer-owned transcripts on their origin device instead of treating a missing local copy as a missing session. Local empty picks are still skipped; explicit local replay still requires readable local content.
+
+- **The resume picker skips a local session with no transcript before opening a
+  tab (PHNX-4080).** Empty local selections are reported as skipped, and a batch
+  with nothing left to resume exits 1. Peer-owned sessions and mirror entries are
+  validated on their origin device. Explicit local replay still requires readable
+  local content; the executing device refuses recovery when no transcript exists.
+  Source: `src/commands/sessions-resume.ts`, `src/lib/session/recovery.ts`.
+
 ## 1.22.107
 
 - **A bare interactive run places itself like `--device auto` (PHNX-4083).**

package/dist/commands/daemon.js

@@ -21,7 +21,8 @@ import { execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
-import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, getDaemonLogPath, isDaemonAutostartCircuitOpen, } from '../lib/daemon/daemon.js';
+import { getDaemonStatus, isDaemonRunning, isDaemonWedged, readDaemonLog, startDaemon, stopDaemon, signalDaemonReload, findSurvivingStateDirDaemons, getDaemonLogPath, isDaemonAutostartCircuitOpen, RedirectedHomeDaemonError, } from '../lib/daemon/daemon.js';
+import { listDaemonRunProcesses } from '../lib/daemon/leaked-daemons.js';
 import { getConfigValue, setConfigValue, isDaemonEnabled } from '../lib/device-config.js';
 import { readSubsystemHealth, readAllSubsystemHealth, SUBSYSTEM_BROWSER_IPC, SUBSYSTEM_DAEMON_START, } from '../lib/daemon-health.js';
 import { DAEMON_SERVICE_IDS, listDaemonServiceStates, setDaemonServiceEnabled, getDaemonServicesConfigPath, queueDaemonServiceRestart, } from '../lib/daemon-services.js';
@@ -32,6 +33,27 @@ import { parseDuration } from '../lib/hooks/cache.js';
 import { registerFunnelCommand } from './funnel.js';
 import { DEFAULT_WEBHOOK_PORT, DEFAULT_WEBHOOK_RATE_LIMIT, addHostedReceiver, getDaemonWebhooksConfigPath, hostedReceiverPort, readDaemonWebhooksConfig, removeHostedReceiver, } from '../lib/daemon-webhooks.js';
 import { parseFunnelPort } from '../lib/funnel.js';
+// ─── Process scanning — which install owns the pid, and every duplicate ──────
+/**
+ * startDaemon for the explicit start/restart commands: the redirected-HOME
+ * refusal (W4, PHNX-3736) is user-actionable, not an engineering bug, so it
+ * prints without a stack and exits 1. Anything else (a genuinely unspawnable
+ * binary) still throws. Kept local to this command rather than in bootstrap's
+ * catch list — a bootstrap.ts edit selects the 54s non-interactive suite into
+ * the required impact gate, and this change's budget cannot carry it.
+ */
+function startDaemonClean() {
+    try {
+        return startDaemon();
+    }
+    catch (err) {
+        if (err instanceof RedirectedHomeDaemonError) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        throw err;
+    }
+}
 /**
  * Provably absent, or null when unknowable.
  *
@@ -188,19 +210,14 @@ function entryFromTokens(tokens) {
     return tokens.length >= 2 ? tokens[tokens.length - 2] : null;
 }
 /**
- * Every live `__daemon-run` process on this box, regardless of which install
- * launched it or which state dir it serves. POSIX-only (uses `ps`); a no-op on
- * Windows.
- *
- * `getDaemonLaunch` always spawns `<node> <entry> __daemon-run` with nothing
- * after it — the ONLY argv `__daemon-run` ever appears in for a real daemon.
- * A substring/regex test anywhere in the full command line is not enough: an
- * `agents run claude "<prompt>"` invocation whose prompt happens to quote the
- * literal text `__daemon-run` (this ticket's own brief does) matches that test
- * too, and was observed producing false "duplicate daemon" rows. Requiring it
- * to be the LAST whitespace-delimited token is the actual invariant.
+ * Every live `__daemon-run` process on this box, enriched with display
+ * metadata (entry/version/entryMissing). The raw `ps` scan and its
+ * last-token `__daemon-run` invariant live in
+ * `lib/daemon/leaked-daemons.ts` (`listDaemonRunProcesses`) — shared with the
+ * doctor's leaked-daemon detection so the two can never disagree on what a
+ * daemon process is.
  *
- * This raw box-wide scan is deliberately NOT the duplicate-detection scope
+ * This box-wide scan is deliberately NOT the duplicate-detection scope
  * (RUSH-2368): a `__daemon-run` under a different HOME serves a different
  * `getDaemonDir()` and is not a duplicate of THIS device's daemon, however
  * `ps` sees it — a leaked vitest fixture under its own `/tmp` HOME matched
@@ -209,35 +226,14 @@ function entryFromTokens(tokens) {
  * `findSurvivingStateDirDaemons` has already confirmed as real duplicates.
  */
 function scanDaemonProcesses() {
-    if (process.platform === 'win32')
-        return [];
-    let out;
-    try {
-        out = execFileSync('ps', ['-eo', 'pid=,uid=,args='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
-    }
-    catch {
-        return [];
-    }
     const found = [];
-    for (const line of out.split('\n')) {
-        const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.*)$/);
-        if (!m)
-            continue;
-        const args = m[3].trim();
-        const tokens = args.split(/\s+/);
-        if (tokens.length === 0 || tokens[tokens.length - 1] !== '__daemon-run')
-            continue;
-        const pid = parseInt(m[1], 10);
-        if (isNaN(pid))
-            continue;
-        const uidParsed = parseInt(m[2], 10);
-        const uid = isNaN(uidParsed) ? null : uidParsed;
-        const entry = entryFromTokens(tokens);
-        const version = entry ? resolveVersionNear(entry, pid) : null;
+    for (const p of listDaemonRunProcesses()) {
+        const entry = entryFromTokens(p.tokens);
+        const version = entry ? resolveVersionNear(entry, p.pid) : null;
         // Asks whether the code is on disk for the NEXT launch -- what a restart and
         // every other reader will see -- not what this pid currently has mapped.
         const entryMissing = entry ? entryAbsent(entry) : false;
-        found.push({ pid, entry, version, entryMissing, uid });
+        found.push({ pid: p.pid, entry, version, entryMissing, uid: p.uid });
     }
     return found;
 }
@@ -905,6 +901,15 @@ export function registerDaemonCommand(program) {
       'agents daemon start' still starts it explicitly, same as
       'systemctl start' on a disabled unit.
 
+      Under a redirected HOME (a test/e2e harness), 'agents daemon start'
+      REFUSES to launch: a daemon started there keeps its own pid file under
+      the temp home and leaks, invisible to the real install (W4, PHNX-3736).
+      'daemon restart' inherits the same guard — it stops first, so run it
+      with the same opt-in. A deliberate test launch sets
+      AGENTS_ALLOW_TEST_DAEMON=1 — and the harness owns stopping what it
+      started. 'agents doctor' flags any leaked daemon that already exists,
+      with its HOME and start time.
+
       'agents daemon services enable|disable|restart <id>' applies live (no
       daemon restart) for supervisor-managed services that were registered at
       boot. browser-ipc is also registered while disabled, specifically so a
@@ -924,7 +929,7 @@ export function registerDaemonCommand(program) {
     cmd.command('start')
         .description('Start the daemon. Bypasses daemon.enabled — this is the deliberate override.')
         .action(() => {
-        const result = startDaemon();
+        const result = startDaemonClean();
         if (result.method === 'already-running') {
             console.log(chalk.yellow(`Daemon already running (PID: ${result.pid})`));
         }
@@ -977,7 +982,7 @@ export function registerDaemonCommand(program) {
             for (const s of stop.surviving)
                 console.log(chalk.red(`  surviving: ${s}`));
         }
-        const result = startDaemon();
+        const result = startDaemonClean();
         if (result.pid)
             console.log(chalk.green(`Daemon started (PID: ${result.pid}, ${result.method})`));
         else

package/dist/commands/doctor.js

@@ -16,6 +16,7 @@ import { hostIdentityArgs, sshTargetFor } from '../lib/hosts/types.js';
 import { deviceIdentityArgs } from '../lib/devices/connect.js';
 import { machineId, normalizeHost } from '../lib/session/sync/config.js';
 import { findAmbiguousDevicePins } from '../lib/scheduling/routines.js';
+import { findLeakedDaemons } from '../lib/daemon/leaked-daemons.js';
 import chalk from 'chalk';
 import { checkAllClis, collectTeamsDoctorData } from '../lib/teams/agents.js';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, getAccountInfo } from '../lib/agents.js';
@@ -478,6 +479,10 @@ async function runDevicesDoctor(opts) {
                 // remote boxes self-report it in their own `agents doctor --json`.
                 ownerSink: await probeOwnerSink(readMeta()),
                 binaryShadows: detectAgentsBinaryShadows(),
+                // A `__daemon-run` no unit main PID or daemon.pid owns (W4, PHNX-3736) —
+                // the /tmp/pin-e2e leak class the registry-scoped duplicate check cannot
+                // see. Local only: a remote box self-reports in its own doctor.
+                leakedDaemons: findLeakedDaemons(),
             }));
             accounts[localName] = r.inventory?.signIn ?? {};
             continue;
@@ -1478,6 +1483,8 @@ export function registerDoctorCommand(program) {
                 // Can the owner-delivery lane (feed/notify) escalate a block from this
                 // box? A factory that cannot escalate is not healthy (RUSH-2262).
                 ownerSink: await probeOwnerSink(readMeta()),
+                // A `__daemon-run` no unit main PID or daemon.pid owns (W4, PHNX-3736).
+                leakedDaemons: findLeakedDaemons(),
             });
             if (opts.json) {
                 const overviewPayload = {

package/dist/commands/exec.js

@@ -986,6 +986,8 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 throw new Error('--resume cannot be combined with --session-id, --loop, --fallback, --resume-checkpoint, or --lease.');
             }
             const { sessionsResumeAction } = await import('./sessions-resume.js');
+            const { toRemotePortable } = await import('../lib/project-root.js');
+            const device = options.host || options.device || options.on || options.computer;
             await sessionsResumeAction(undefined, prompt, {
                 agent: normalizedAgentSpec.split('#')[0] === RUN_AUTO_KEYWORD ? undefined : normalizedAgentSpec.split('#')[0],
                 account: options.account,
@@ -993,9 +995,9 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 mode: command.getOptionValueSource('mode') === 'default' ? undefined : options.mode,
                 interactive: options.interactive,
                 headless: options.headless,
-                cwd: options.cwd,
+                cwd: device ? options.remoteCwd ?? (options.cwd ? toRemotePortable(options.cwd) : undefined) : options.cwd,
                 quiet: options.quiet,
-                device: options.host || options.device || options.on || options.computer,
+                device,
                 runArgs: rawArgs.slice(2),
             });
             return;

package/dist/commands/monitors.js

@@ -12,7 +12,7 @@ import { withAliases } from '../lib/verbs.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { isDaemonRunning, signalDaemonReload, startDaemon, } from '../lib/daemon/daemon.js';
+import { isDaemonRunning, signalDaemonReload, startDaemon, RedirectedHomeDaemonError, } from '../lib/daemon/daemon.js';
 import { findDuplicateMonitor, monitorFingerprint } from '../lib/monitors/fingerprint.js';
 import { gatherFleetMonitors, NO_MONITOR_FANOUT_ENV } from '../lib/monitors/remote.js';
 import { listMonitors, readMonitor, writeMonitor, deleteMonitor, setMonitorEnabled, getMonitorPath, validateMonitor, monitorRunsOnThisDevice, requiresSingleOwner, monitorSharedInputOwner, parseInterval, } from '../lib/monitors/config.js';
@@ -246,7 +246,20 @@ function ensureDaemonRunning() {
         stderrLine(chalk.gray('Daemon reloaded'));
         return true;
     }
-    const result = startDaemon();
+    let result;
+    try {
+        result = startDaemon();
+    }
+    catch (err) {
+        // The redirected-HOME refusal (W4) is an auto-start policy, not a failure
+        // of the monitor just added — state it and leave the foreground command
+        // green. Anything else (a genuinely unspawnable binary) still fails loud.
+        if (err instanceof RedirectedHomeDaemonError) {
+            stderrLine(chalk.yellow(err.message));
+            return true;
+        }
+        throw err;
+    }
     if (result.pid) {
         console.log(chalk.green(`Daemon started (PID: ${result.pid}). It will watch monitors in the background.`));
         console.log(chalk.gray('Disable only monitor polling with: agents daemon services disable monitors'));

package/dist/commands/routines.js

@@ -10,7 +10,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { isDaemonRunning, signalDaemonReload, startDaemon, readDaemonLog, getDaemonStatus, getDaemonLogPath, } from '../lib/daemon/daemon.js';
+import { isDaemonRunning, signalDaemonReload, startDaemon, readDaemonLog, getDaemonStatus, getDaemonLogPath, RedirectedHomeDaemonError, } from '../lib/daemon/daemon.js';
 import { isDaemonServiceEnabled, setDaemonServiceEnabled } from '../lib/daemon-services.js';
 import { assertSchedulerEnabled, assertDaemonEnabled, isDaemonEnabled, isSchedulerEnabled, } from '../lib/device-config.js';
 import { parseAgentVersionSpec, isAgentHardDeprecated, hardDeprecationError, ROUTINE_AGENT_IDS } from '../lib/agents.js';
@@ -327,7 +327,22 @@ function ensureSchedulerRunning(opts = {}) {
         }
         return;
     }
-    const result = startDaemon();
+    let result;
+    try {
+        result = startDaemon();
+    }
+    catch (err) {
+        // The redirected-HOME refusal (W4) is an auto-start policy, not a failure
+        // of the routine just added — state it and leave the foreground command
+        // green, the same tier split as the auto-start circuit breaker. Anything
+        // else (a genuinely unspawnable binary) still fails loud.
+        if (err instanceof RedirectedHomeDaemonError) {
+            if (!opts.quiet)
+                log(chalk.yellow(err.message));
+            return;
+        }
+        throw err;
+    }
     if (opts.quiet)
         return;
     if (result.pid) {
@@ -1851,9 +1866,22 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.yellow(`Daemon is disabled (daemon.enabled=false) — run(s) below fire but are not monitored. Re-enable with: agents daemon enable`));
             }
             else {
-                const started = startDaemon();
-                if (started.pid) {
-                    console.log(chalk.gray(`Started scheduler (PID: ${started.pid}) so webhook runs are monitored.`));
+                try {
+                    const started = startDaemon();
+                    if (started.pid) {
+                        console.log(chalk.gray(`Started scheduler (PID: ${started.pid}) so webhook runs are monitored.`));
+                    }
+                }
+                catch (err) {
+                    // Same contract as the daemon.enabled=false branch above: a refused
+                    // auto-start (W4's redirected-HOME guard) never cancels the fire —
+                    // the runs below fire but are not monitored. Anything else rethrows.
+                    if (err instanceof RedirectedHomeDaemonError) {
+                        console.log(chalk.yellow(err.message));
+                    }
+                    else {
+                        throw err;
+                    }
                 }
             }
         }
@@ -2185,7 +2213,19 @@ export function registerRoutinesCommands(program) {
             process.exit(1);
         }
         setDaemonServiceEnabled('scheduler', true);
-        const result = startDaemon();
+        let result;
+        try {
+            result = startDaemon();
+        }
+        catch (err) {
+            // The redirected-HOME refusal (W4) is user-actionable — print it
+            // without a stack, same as the asserts above.
+            if (err instanceof RedirectedHomeDaemonError) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+            throw err;
+        }
         if (result.method === 'already-running') {
             // Signal a reload even here: if the daemon booted while this device had
             // scheduler.enabled=false, the reload re-evaluates the gate and boots

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-resume.d.ts

@@ -1,6 +1,6 @@
 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;
@@ -33,6 +33,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 +51,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

@@ -19,15 +19,16 @@ 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 { openSurfaces, availableBackends, detectCurrentBackend, currentContext, shellQuote, } from '../lib/terminal/index.js';
 import { isInteractiveTerminal, isPromptCancelled } 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';
 /** Opening more than this many live sessions at once asks for confirmation first. */
 export const CONFIRM_THRESHOLD = 5;
@@ -98,6 +99,7 @@ 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.
     `,
     });
@@ -232,12 +234,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);
@@ -294,6 +300,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 +315,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 +325,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 +342,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 +370,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 +427,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)

package/dist/commands/sessions.js

@@ -75,6 +75,7 @@ import { registerSessionsRenderCommand } from './sessions-render.js';
 import { registerSessionsTraceCommand } from './sessions-trace.js';
 import { registerSessionsShareCommand } from './sessions-share.js';
 import { registerSessionsImportCommand } from './sessions-import.js';
+import { registerSessionsBackupSetupCommand } from './sessions-backup-setup.js';
 import { registerSessionsMigrateCommand, registerSessionsMigrationsCommand } from './sessions-migrate.js';
 import { registerSessionsBackfillCommand } from './sessions-backfill.js';
 import { registerSessionsStatsCommand } from './sessions-stats.js';
@@ -5387,6 +5388,7 @@ export function registerSessionsCommands(program) {
     registerSessionsTraceCommand(sessionsCmd);
     registerSessionsShareCommand(sessionsCmd);
     registerSessionsImportCommand(sessionsCmd);
+    registerSessionsBackupSetupCommand(sessionsCmd);
     registerSessionsMigrateCommand(sessionsCmd);
     registerSessionsMigrationsCommand(sessionsCmd);
     registerSessionsBackfillCommand(sessionsCmd);