@phnx-labs/agents-cli 1.22.70 → 1.22.71

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.22.71
+
+- **The daemon now keeps itself current instead of running stale code for days (PHNX-3695).** The long-running daemon (`agents __daemon-run`) deliberately opted out of the interactive CLI's auto-update (`AGENTS_CLI_DISABLE_AUTO_UPDATE=1` forced on for `__daemon-run`), so new agents-cli code never reached a running daemon until a human ran `agents daemon restart` — R5 ("the installed CLI auto-updates") silently did not hold for the one process that runs unattended the longest. A new supervised `self-update` service checks npm roughly every 75 minutes, installs and byte-verifies a newer version with the same primitives `agents upgrade` already uses (never a bare `npm install -g`), best-effort pulls the `.system` companion repo and reconciles with `agents sync --local`, then exits so the OS supervisor (launchd `KeepAlive` / systemd `Restart=always`) relaunches it onto the new code — clients reconnect on their own, and the scheduler's atomic `(routine, scheduledFor)` claim dedupes any routine mid-fire across the restart. It fails closed on every step: an install or verify failure leaves the running daemon untouched and retries next tick, and it no-ops on a dev build or a shadowed install. A version-skewed browser-IPC client no longer just prints "run agents daemon restart" — `reconcileDaemonVersion` now asks the daemon to run this same fail-closed path on demand (`request-self-update`), sharing one in-flight attempt with the periodic tick so concurrent requests can't race two installs. That on-demand trigger is DECOUPLED from the install: because every version-skewed `agents browser <verb>` routes through it, the daemon kicks the self-update off in the background and answers "triggered" immediately rather than making the browser verb wait out the whole check→download→install→verify (tens of seconds, worst case ~15 min) — the daemon installs, verifies, and exits on its own, and the browser reconnects. Source: `cli/src/lib/daemon/self-update-service.ts`, `cli/src/lib/browser/ipc.ts`.
+
+- **The daemon's event loop is no longer starved by synchronous subprocess spawns on its service ticks (PHNX-3695).** Every daemon background service runs on one Node event loop, so a synchronous `execFileSync`/`readFileSync` inside a service tick froze that loop for the whole call — and while frozen the supervisor's per-tick deadline timer could not fire and the browser IPC server could not answer, which is the "accept but never reply" wedge the trivial `version` probe (`cli/src/lib/browser/ipc.ts`) surfaces. A new async, deadline-bounded, process-group-killable exec helper (`cli/src/lib/exec-bounded.ts` `execFileBounded`) replaces the tick-reachable sync spawns. The heartbeat tick is now fully async: it reaps exited routine children through `reapExitedRunningJobs` (an async twin of the sync `monitorRunningJobs`, sharing one reconciliation core so the CLI `routines list/status` builders keep their synchronous, off-loop path) with an `execFileBounded`-bounded `ps` identity probe and an async `sshExecAsync` read of a `host:`-placed run's remote exit (a synchronous `ssh` there would freeze the loop on a host timeout), plus the async terminal-routine reaper; the self-heal and state-dir-check service ticks moved their `existsSync`/`readFileSync` to `fs/promises`. The worst halt was the event-log **file lock** (`withFileLock` → `lockfile.lockSync` + `Atomics.wait`, up to 30s), reached from every `ctx.log` on every tick as well as the watchdog and routine-reaper emits; a new `withFileLockAsync` + `emitAsync` (`cli/src/lib/fs-atomic.ts`, `cli/src/lib/feed/events.ts`) acquire it without freezing the loop. The other unconditional every-tick halts are converted the same way: usage-sync/auth-sync publish through `updateFleetSharedDeviceStateAsync`, keychain-reap's whole-process-table `ps` uses `execFileBounded`, watchdog/browser-task-reap read config via async paths, and tmux-reap's `/proc` scan uses `fs/promises`. A structural guard test (`cli/src/lib/daemon/guard-no-sync-io.test.ts`) scans every `*-service.ts` tick/start body for a synchronous fs/exec/lock call AND pins that each hot tick call site uses its async variant (failing if a fix is reverted to its sync twin). Startup and stop/uninstall lifecycle code (pid/lock, `launchctl`/`systemctl`, the `ps` daemon-identity probe) stays synchronous — it runs in a short-lived CLI process, never on the served loop. Source: `cli/src/lib/{exec-bounded,fs-atomic,device-config,fleet-shared-state}.ts`, `cli/src/lib/feed/events.ts`, `cli/src/lib/secrets/{reaper,reserved-sync}.ts`, `cli/src/lib/accounting/usage-sync.ts`, `cli/src/lib/tmux/{session,orphan-reap}.ts`, `cli/src/lib/daemon/{runner,daemon,heartbeat-service,watchdog-service,usage-sync-service,auth-sync-service,keychain-reap-service,browser-task-reap-service,self-heal-service,state-dir-check-service}.ts`, `cli/src/lib/hosts/reconcile.ts`, `cli/src/lib/routine-process-cleanup.ts`, `cli/src/lib/daemon/AGENTS.md`.
+
+- **The required PR check no longer reinstalls 273 packages on every run.** Measured across recent Linux required runs, `bun install` took 14–22s on *every* run — whether the impact plan selected 78 test files or 2 — while a release check's actual test execution is 0.27s. The install was a fixed cost every pull request paid, and the largest single item in the required-check budget. `tests.yml` now restores `~/.bun/install/cache`, `cli/node_modules`, and `packages/session-tracker/node_modules` from an `actions/cache` keyed on **both** `cli/bun.lock` and `packages/session-tracker/bun.lock` — keying on the CLI lockfile alone would have left the session-tracker tree outside its own key. The key also carries a `node -v`/`bun -v` fingerprint, because `cli/package.json` trusts a native addon (`@homebridge/node-pty-prebuilt-multiarch`) whose prebuilt binary is Node-ABI-specific and nothing pins the runner's Node. `restore-keys` is deliberately omitted: a prefix fallback would let bun install on top of a *different* lockfile's modules, and `--frozen-lockfile` only guarantees the tree matches the lock from a clean or exact-match state — correctness beats a warmer cache when an attestation binds the tested tree to the published tarball. A dependency change misses the cache and reinstalls, which is exactly the previous behavior, so a miss can never be slower than not caching. Source: `.github/workflows/tests.yml`.
+
+- **The CI dependency cache now actually hits.** The cache added a change earlier was dead weight in practice: GitHub scopes caches per ref — a run can restore only from its own branch or the default branch — and the required `test` job runs on `pull_request` only, so every entry it saved landed under `refs/pull/<N>/merge`, invisible to every other pull request. Measured after it shipped: `deps-cache-hit=0` with `packages installed [21.63s]` on unrelated PRs, i.e. a permanent cold miss for everyone except a re-run of the same PR. A push-to-`main` `warm-dep-cache` job now writes the identical key and paths, so the first PR after any lockfile or toolchain change pays the install once and every later PR restores it. The job is push-only and never joins the required check identity. `tests-gate.test.ts` pins the two keys equal, because drift between them would be silent — the warm job would populate an entry the required job never asks for, and the cache would look healthy while never hitting. Source: `.github/workflows/tests.yml`.
+
+- **Managed session backup: harden the storage boundary (PHNX-3726).** Follow-up security fixes to the managed sessions Worker landed in the same ticket. The Worker is now **Phoenix-only** — the static `WRITE_TOKEN` principal is removed (and no longer provisioned): the zero-knowledge `--byo` path talks to your own R2 bucket directly and never reaches this Worker, so a token here was only a Phoenix-and-quota bypass. Mandatory encryption is now enforced at the storage boundary, not just client-side: a PUT whose body is not an encrypted bundle is rejected `422`, and a managed restore fails loud on any plaintext object instead of importing it. DELETE now refunds the per-user quota ledger via a delta CAS applied BEFORE the object is removed, and fails loud (503, object left intact and charged) when that CAS stays contended — instead of deleting first and silently dropping the refund on a contended ledger. Source: `cli/src/lib/session/sync/{worker-template,provision}.ts`, `cli/src/commands/sessions-import.ts`, `cli/docs/specifications.md`.
+
+- **Signed-in users back sessions up off-box with NO `r2.backups` bucket to set up (PHNX-3726).** `agents sessions export --to-r2` / `import --from-r2` now default to a managed, Phoenix-gated store (`sessions.agents-cli.sh`) when you are signed in (`agents auth login`) — the same zero-setup pattern `agents artifacts share` and `agents traces sync` already use, resolved through the one shared `selectStorageBackendKind` policy. It is **managed-first**: a signed-in user backs up to managed even with a stale `r2.backups` bundle present; only `--byo` / `AGENTS_SESSIONS_BACKEND=byo` flips to your own bucket. Every managed backup is **mandatorily** AES-256-GCM encrypted under a per-account key that is minted once, cached at `~/.agents/.cache/state/sessions-backup-key.json` (mode 0600), and escrowed at the bearer-gated, immutable Worker key `<userId>/__key/backup-dek` so a fresh box signing in recovers it and decrypts prior backups with zero setup — the managed path never uploads plaintext. Both the command and Worker reject plaintext/malformed managed objects, and restore revalidates every at-rest bundle before decryption. Honest trust boundary: confidential vs a raw R2/Cloudflare bucket read (ciphertext at rest) but NOT zero-knowledge vs Phoenix (the DEK is escrowed on Phoenix infra); `--byo` keeps the zero-knowledge own-bucket path (the key stays only in your `r2.backups` bundle). The isolated Worker verifies the Phoenix bearer on every PUT/GET/LIST/DELETE, enforces `segments[0] == userId` (401/403, no public GET), and meters a per-user CAS quota (`__usage`, 413 over quota). Same-key managed PUT/DELETE operations share an expiring R2 lease; every object change is etag-conditioned, DELETE leaves a GET-404/LIST-hidden tombstone, and expired recovery fences the predecessor's etag before settling quota. The ledger retains an idempotent pending delta plus a terminal generation per path in the same CAS object, preventing late predecessor charges, replacement deletes, double refunds, stranded paths, and phantom quota. A CAS-reserved historical-path budget is consumed before persistent per-path state is created and is not refunded on DELETE, so authenticated create/delete churn cannot grow tombstones, leases, or ledger history past the hard cap. Reserved `__usage`/`__key` prefixes are never listed. The BYO object layout is byte-for-byte unchanged (the `<userId>/` prefix is added inside the client) and the Worker is integration-tested against real workerd. Source: `cli/src/lib/session/sync/{backend,managed-config,managed-key,net-client,provision,worker-template}.ts`, `cli/src/commands/sessions-export.ts`, `cli/src/commands/sessions-import.ts`, `cli/docs/{sessions,specifications}.md`.
+
+- **Daemon: a host-placed run finishing on the heartbeat tick no longer freezes the event loop (PHNX-3727).** Fast-follow to PHNX-3695. `finalizeHostRunAsync` (the async, tick-reachable finalize path reached via `reapExitedRunningJobs`) called `applyHealedHostRun`, which ended by emitting routine-end through the **synchronous** `emitRoutineEnd` — whose event-log file lock (`withFileLock` → `lockSync` + `Atomics.wait`, up to 30s under contention) is exactly the loop-freeze PHNX-3695 removed elsewhere, on a path `guard-no-sync-io` couldn't see (it lives in `runner.ts`, not a `*-service.ts`). So a `host:`-placed routine run completing could still wedge the browser-IPC "accept but never reply" state under lock contention. `applyHealedHostRun` now takes an injected emitter: `finalizeHostRun` (sync CLI path) keeps the synchronous emit, while `finalizeHostRunAsync` (the tick) passes `emitRoutineEndAsync` (`withFileLockAsync`), so no daemon tick reaches the synchronous lock. `guard-no-sync-io` gains a call-site pin so reverting it fails loud. Source: `cli/src/lib/daemon/runner.ts`, `cli/src/lib/daemon/guard-no-sync-io.test.ts`.
+
+- **`agents traces sync` now surfaces silent behavioral failures as ranked issues, not just a friction counter (RUSH-2988).** A session where the agent went idle after its last event and a human had to nudge it is a real failure with **no error code**, so it never clustered through `computeInsights` (which only groups `outcome === 'error'` tool calls) and was previously only a `needsAttention` severity input. The per-session silent-stall friction (`silent stall: 5-15m/15-60m/1h+`, already computed by `computeInsightFacets`) is now promoted into cross-session `FailurePattern`s with a new `behavioral` failure cause (`cli/src/lib/traces/insights.ts` `computeBehavioralPatterns`), ranked into the same top-K `failurePatterns` by wasted idle time (a bucket's midpoint, bounded by the same 30-min `MAX_GAP_ATTRIBUTION_MS` cap the tool-error path uses) and summed into `wastedMsTotal`. `TraceFailureCause` gains `behavioral` (`cli/src/lib/traces/classify.ts`); it is producer-derived and never returned by `classifyCause`, so the `failures.byCause` tool-error split reports it as `0`. The console renders the new cause in a follow-up web change.
+
 ## 1.22.70
 
 - **`agents browser stop --profile` is now gated by the remote-control consent gate (PHNX-3317).** `stop --profile <name>` (no `--task`) is handled entirely by `bindTask`'s early return in `ipc.ts`, so it never reached `resolveOrCreateTask` — the one chokepoint every other page/close/attach verb's `assertRemoteControlAllowedForRequest` gate runs through — and `case 'stop'` called `BrowserService.stopProfile()` directly with no consent check at all. That left one destructive fleet-remote path (kills the profile's browser process, clears its runtime dir) reachable from `browser --device <device> stop --profile` even with `remote-control off` on the target. `stopProfile()` now takes the same `{ fleetRemote, actor }` opts as `start`/`showUrl`/`resolveOrCreateTask` and asserts the gate first; a local (non-fleet-remote) call is unaffected. Source: `cli/src/lib/browser/service.ts`, `cli/src/lib/browser/ipc.ts`.

package/README.md

@@ -402,6 +402,31 @@ Sharing a session uses `agents sessions render <id> -o session.md`, not the raw
 
 `agents sessions share <id>` goes one step further and publishes that document as a self-contained web page on your own share endpoint, printing the link. It is **unlisted** unless you pass `--public` — a transcript carries file paths, command output, and error text that a plan does not, so it stays out of your public gallery by default, and emails are masked on top of the render's own redaction. The slug is `session-<shortId>`, so re-sharing one session updates one URL.
 
+### Back up sessions off-box
+
+Signed-in Phoenix users can back sessions up without creating a Cloudflare bucket or
+an `r2.backups` secrets bundle:
+
+```bash
+agents sessions export --since 30d --to-r2
+agents sessions import --from-r2 --dry-run
+agents sessions import --from-r2
+```
+
+The managed path encrypts every transcript body locally with AES-256-GCM before
+upload. Its per-account key is escrowed behind the same Phoenix bearer so another
+signed-in device can restore with zero setup. This protects transcript contents from
+a raw storage-bucket read, but it is not zero-knowledge against Phoenix because
+Phoenix-operated infrastructure stores the recovery key. Use `--byo` with your own
+`r2.backups` bundle and `R2_SYNC_ENC_KEY` when Phoenix must never possess the key:
+
+```bash
+agents sessions export --since 30d --to-r2 --byo
+agents sessions import --from-r2 --byo
+```
+
+Both targets are on-demand backups only; neither enables background session sync.
+
 ### Resume anywhere — and stay resumed
 
 Pick up any past conversation and drop it back into a terminal:
@@ -1261,8 +1286,13 @@ agents daemon doctor                        # one-shot health check; non-zero ex
 ```
 
 Each hosted responsibility (secrets broker, browser IPC, scheduler, monitors,
-watchdog, device probe, self-heal, keychain reap, account-state refresh,
+watchdog, device probe, self-heal, self-update, keychain reap, account-state refresh,
 state-dir checks) is an independent toggle in `~/.agents/daemon/services.yaml`.
+Self-update checks npm on its own schedule, installs + verifies a newer
+agents-cli with the same primitives `agents upgrade` uses, then exits so the OS
+supervisor relaunches the daemon onto the new code — the daemon used to run
+with auto-update forced off and only picked up new code on a manual
+`agents daemon restart`.
 `agents daemon services list` shows every service; `enable|disable <id>` flips
 one. Missing keys default to enabled, so upgrades are no-ops. Most services take
 effect on the next daemon start; browser IPC is registered even when boot-disabled

package/dist/bootstrap.js

@@ -328,7 +328,7 @@ async function installResolvedPackage(metadata) {
         // every subsequent upgrade dead-ends there forever. bun does not use
         // npm's retire-path staging scheme, so this only needs to run once, ahead
         // of both package-manager branches below.
-        sweepStaleInstallStaging(packageRoot);
+        await sweepStaleInstallStaging(packageRoot);
         // Upgrade with the package manager that owns this install. A bun global
         // install lives at <bunGlobalDir>/node_modules/... (no `lib` segment), so an
         // `npm install --prefix` would write to <bunGlobalDir>/lib/node_modules and
@@ -349,8 +349,8 @@ async function installResolvedPackage(metadata) {
             /* leave it for the OS temp sweep */
         }
     }
-    verifyInstalledVersion(packageRoot, metadata.version);
-    refreshAliasShims(packageRoot);
+    await verifyInstalledVersion(packageRoot, metadata.version);
+    await refreshAliasShims(packageRoot);
     // PHNX-2768: the npm install above can leave the package at the new version
     // but the global bin links GONE — the state that stranded zion (package at
     // 1.22.40, `/opt/homebrew/bin/{agents,ag,browser,computer}` missing, every
@@ -361,7 +361,7 @@ async function installResolvedPackage(metadata) {
     // own bin shims and are out of scope.
     if (detectPackageManager(packageRoot) !== 'bun' && process.platform !== 'win32') {
         const prefix = deriveGlobalPrefix(packageRoot);
-        const repairs = ensureGlobalBinLinks(packageRoot, prefix);
+        const repairs = await ensureGlobalBinLinks(packageRoot, prefix);
         const repaired = repairs.filter((r) => r.action === 'repaired');
         const failed = repairs.filter((r) => r.action === 'failed');
         if (repaired.length > 0) {

package/dist/commands/repo.js

@@ -60,7 +60,7 @@ function syncMarketplacesForDefaults() {
 /** Write this device's account metadata before the user repo is committed. */
 async function publishUserRepoAccountState(provisionAuth) {
     const { publishUsageSnapshotToSharedStore } = await import('../lib/accounting/usage-sync.js');
-    const usage = publishUsageSnapshotToSharedStore();
+    const usage = await publishUsageSnapshotToSharedStore();
     if (usage.error)
         console.error(chalk.yellow(`Usage snapshot: ${usage.error}`));
     if (provisionAuth) {
@@ -73,7 +73,7 @@ async function publishUserRepoAccountState(provisionAuth) {
         return;
     }
     const { publishReservedAuthVerdict } = await import('../lib/secrets/reserved-sync.js');
-    const auth = publishReservedAuthVerdict();
+    const auth = await publishReservedAuthVerdict();
     if (auth.error)
         console.error(chalk.yellow(`Auth verdict: ${auth.device}: ${auth.error}`));
 }

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

@@ -1,5 +1,6 @@
 import type { Command } from 'commander';
 import type { SessionMeta } from '../lib/session/types.js';
+import { type SessionsBackupClient } from '../lib/session/sync/net-client.js';
 import { type BundleHeader, type BundleRecord } from '../lib/session/bundle.js';
 export declare function registerSessionsExportCommand(sessionsCmd: Command): void;
 interface GlobalSelection {
@@ -10,6 +11,7 @@ interface GlobalSelection {
     redact?: boolean;
     encrypt?: boolean;
     toR2?: boolean;
+    byo?: boolean;
     output?: string;
     stdout?: boolean;
     host?: string[];
@@ -36,7 +38,9 @@ interface GlobalSelection {
  * its test drive the exact same decision.
  */
 export declare function r2ExportGateError(g: Pick<GlobalSelection, 'toR2' | 'host'>, isConfigured: boolean): string | null;
-export declare function uploadToR2(header: BundleHeader, records: BundleRecord[]): Promise<void>;
+export declare function uploadToR2(header: BundleHeader, records: BundleRecord[], resolvedClient?: SessionsBackupClient): Promise<void>;
+/** Fail-closed guard at the managed transport boundary, not only at record construction. */
+export declare function managedUploadEncryptionError(header: BundleHeader, records: BundleRecord[]): string | null;
 /** R2 object key for one record — dir-shaped agents key by relKey, file-shaped by session. */
 export declare function r2KeyForRecord(rec: BundleRecord): string;
 /**

package/dist/commands/sessions-export.js

@@ -27,8 +27,11 @@ import { listLocalTranscripts, objectKey, SYNC_AGENTS } from '../lib/session/syn
 import { machineId } from '../lib/machine-id.js';
 import { getHistoryDir } from '../lib/state.js';
 import { isSyncConfigured, loadR2Config } from '../lib/session/sync/config.js';
-import { resolveSyncEncKey, generateSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { resolveSyncEncKey, generateSyncEncKey, isTranscriptEnvelope, } from '../lib/session/sync/transcript-crypto.js';
 import { R2Client } from '../lib/session/sync/r2.js';
+import { resolveSessionsBackend } from '../lib/session/sync/backend.js';
+import { SessionsHttpClient } from '../lib/session/sync/net-client.js';
+import { resolveManagedBackupKey } from '../lib/session/sync/managed-key.js';
 import { buildRecord, makeHeader, mergeRecords, serializeBundle, writeBundleFile, specForAgent, } from '../lib/session/bundle.js';
 import { knownSecretValuesFromEnv } from '../lib/redact.js';
 import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
@@ -42,7 +45,8 @@ export function registerSessionsExportCommand(sessionsCmd) {
         .option('-o, --output <path>', 'Write the bundle to this file')
         .option('--stdout', 'Write the bundle to stdout (for piping into `sessions import -`)')
         .option('--encrypt', 'Seal each transcript body with AES-256-GCM before writing')
-        .option('--to-r2', 'Back the selected sessions up to Cloudflare R2 (requires the r2.backups bundle) instead of a local file');
+        .option('--to-r2', 'Back the selected sessions up off-box (managed Phoenix store when signed in; your own r2.backups bucket with --byo) instead of a local file')
+        .option('--byo', 'With --to-r2: force your own r2.backups bucket instead of the managed Phoenix store');
     setHelpSections(cmd, {
         examples: `# Bundle the last week of sessions to a file
 agents sessions export --since 7d -o week.bundle
@@ -53,17 +57,22 @@ agents sessions export 4f8a2b1c 9d3e7a55 -o pair.bundle
 # Encrypt + pipe straight into another machine over SSH
 agents sessions export --since 7d --stdout --encrypt | agents ssh boxB 'agents sessions import - --decrypt <key>'
 
-# Back the last month up off-box to Cloudflare R2 (encrypted with the shared key)
-agents sessions export --since 30d --to-r2`,
+# Back the last month up off-box (managed Phoenix store — no bucket to set up)
+agents sessions export --since 30d --to-r2
+
+# Or to your own r2.backups bucket (R2_SYNC_ENC_KEY keeps it zero-knowledge)
+agents sessions export --since 30d --to-r2 --byo`,
         notes: `Selection uses the same flags as 'agents sessions' (--since, -n/--limit, --all,
 -a/--agent, --no-redact). Bundles are self-describing NDJSON: a header line + one
 line per transcript file. Secrets are redacted by default. Dir-shaped sessions
 (Kimi) carry all their files. Restore with 'agents sessions import'.
 
---to-r2 uploads each session to the r2.backups bucket instead of a local file,
-one encrypted object per transcript keyed by machine/agent/session. Bodies are
-sealed with the shared R2_SYNC_ENC_KEY when present. Restore on any box on the
-same bundle with 'agents sessions import --from-r2'.`,
+--to-r2 backs each session up off-box, one encrypted object per transcript keyed
+by machine/agent/session. When you are signed in ('agents auth login') it uploads
+to the MANAGED Phoenix store — no Cloudflare or r2.backups bucket to set up — and
+every body is sealed with a per-account key (mandatory; never plaintext). --byo
+forces your own r2.backups bucket instead; with R2_SYNC_ENC_KEY, neither Phoenix
+nor the storage provider can decrypt it. Restore with 'agents sessions import --from-r2'.`,
     });
     cmd.action(async (selectors, _options, command) => {
         await runExport(selectors, command);
@@ -71,13 +80,42 @@ same bundle with 'agents sessions import --from-r2'.`,
 }
 async function runExport(selectors, command) {
     const g = command.optsWithGlobals();
-    // --to-r2 preflight: reject the impossible --host combo and fail loud when the
-    // backup target is not configured, rather than silently producing a local file.
-    // isSyncConfigured() is consulted only on the --to-r2 path (it reads the keychain).
+    // --to-r2 preflight. MANAGED-FIRST: a signed-in user backs up to the managed
+    // Phoenix store with no bucket to set up; --byo (or an unauthenticated user
+    // with an r2.backups bundle) uses their own bucket. isSyncConfigured() is
+    // consulted ONLY on the BYO path (it reads the keychain); the managed path
+    // authenticates with the Phoenix session and skips it entirely.
+    let sessionsClient;
+    let managedClient;
+    let managedBackupUserId;
+    if (g.byo && !g.toR2) {
+        process.stderr.write(chalk.red('--byo is only valid with --to-r2.\n'));
+        process.exit(1);
+    }
     if (g.toR2) {
-        const gateErr = r2ExportGateError(g, isSyncConfigured());
-        if (gateErr) {
-            process.stderr.write(chalk.red(gateErr + '\n'));
+        if (g.host && g.host.length > 0) {
+            process.stderr.write(chalk.red("--to-r2 backs up THIS machine's sessions; it cannot be combined with --device.\n"));
+            process.exit(1);
+        }
+        try {
+            const backend = resolveSessionsBackend({ byo: g.byo });
+            if (backend.kind === 'managed') {
+                managedClient = new SessionsHttpClient({ baseUrl: backend.baseUrl, userId: backend.userId, token: backend.token });
+                sessionsClient = managedClient;
+                managedBackupUserId = backend.userId;
+            }
+            else {
+                // Preserve the explicit BYO gate used by the on-demand backup path and
+                // daemon sync cycle. resolveSessionsBackend already loaded the bundle,
+                // so this is a cached, non-prompting verification.
+                const gateErr = r2ExportGateError(g, isSyncConfigured());
+                if (gateErr)
+                    throw new Error(gateErr);
+                sessionsClient = new R2Client(backend.r2);
+            }
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`Session backup: ${err.message}\n`));
             process.exit(1);
         }
     }
@@ -142,9 +180,23 @@ async function runExport(selectors, command) {
         process.exit(1);
     }
     // 4. Resolve encryption key (opt-in) + redaction (default on via parent --no-redact).
-    //    An R2 backup uses the fleet-shared R2_SYNC_ENC_KEY (an ephemeral key would be
-    //    unrecoverable on a fresh box), so it never takes the resolveExportKey path.
-    const encryptKey = g.toR2 ? resolveR2BackupKey() : g.encrypt ? resolveExportKey() : null;
+    //    A BYO R2 backup uses the fleet-shared R2_SYNC_ENC_KEY (an ephemeral key would
+    //    be unrecoverable on a fresh box). A MANAGED backup resolves a per-account DEK
+    //    that is MANDATORY and never null — the managed path never uploads plaintext —
+    //    minting + escrowing one on first use so a fresh box recovers it with zero setup.
+    let encryptKey;
+    if (g.toR2 && managedBackupUserId) {
+        encryptKey = await resolveManagedBackupKey(managedClient, managedBackupUserId);
+    }
+    else if (g.toR2) {
+        encryptKey = resolveR2BackupKey();
+    }
+    else if (g.encrypt) {
+        encryptKey = resolveExportKey();
+    }
+    else {
+        encryptKey = null;
+    }
     const redact = g.redact !== false;
     // Value-aware redaction: mask live credential values already in the
     // environment (e.g. an injected secrets bundle) verbatim, whatever their
@@ -172,7 +224,7 @@ async function runExport(selectors, command) {
         records,
     });
     if (g.toR2) {
-        await uploadToR2(header, records);
+        await uploadToR2(header, records, sessionsClient);
         return;
     }
     emitBundle(header, records, g);
@@ -205,13 +257,28 @@ export function r2ExportGateError(g, isConfigured) {
     }
     return null;
 }
-export async function uploadToR2(header, records) {
+export async function uploadToR2(header, records, resolvedClient) {
+    // The resolved client (managed HTTP or BYO R2) is passed in by the command.
+    // The no-client overload preserves the original BYO-only signature for the
+    // direct unit test (loadR2Config() from the r2.backups bundle).
     let client;
-    try {
-        client = new R2Client(loadR2Config());
+    if (resolvedClient) {
+        client = resolvedClient;
+    }
+    else {
+        try {
+            client = new R2Client(loadR2Config());
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`R2 backup: ${err.message}\n`));
+            process.exit(1);
+        }
     }
-    catch (err) {
-        process.stderr.write(chalk.red(`R2 backup: ${err.message}\n`));
+    const encryptionError = client.kind === 'managed'
+        ? managedUploadEncryptionError(header, records)
+        : null;
+    if (encryptionError) {
+        process.stderr.write(chalk.red(`${encryptionError}\n`));
         process.exit(1);
     }
     let uploaded = 0;
@@ -234,7 +301,16 @@ export async function uploadToR2(header, records) {
         uploaded++;
     }
     process.stderr.write(chalk.green(`Backed up ${header.sessions} session${header.sessions === 1 ? '' : 's'} ` +
-        `(${uploaded} object${uploaded === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ', UNENCRYPTED'}) → R2.\n`));
+        `(${uploaded} object${uploaded === 1 ? '' : 's'}${header.encrypted ? ', encrypted' : ', UNENCRYPTED'}) → ` +
+        `${client.kind === 'managed' ? 'managed Phoenix store' : 'R2'}.\n`));
+}
+/** Fail-closed guard at the managed transport boundary, not only at record construction. */
+export function managedUploadEncryptionError(header, records) {
+    if (!header.encrypted ||
+        records.some(record => !record.encrypted || !isTranscriptEnvelope(record.body))) {
+        return 'Managed session backups require AES-256-GCM envelopes; refusing to upload plaintext.';
+    }
+    return null;
 }
 /** R2 object key for one record — dir-shaped agents key by relKey, file-shaped by session. */
 export function r2KeyForRecord(rec) {

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

@@ -1,4 +1,5 @@
 import type { Command } from 'commander';
+import { type SessionsBackupClient } from '../lib/session/sync/net-client.js';
 import { type ParsedBundle } from '../lib/session/bundle.js';
 export declare function registerSessionsImportCommand(sessionsCmd: Command): void;
 /**
@@ -16,4 +17,4 @@ export declare function registerSessionsImportCommand(sessionsCmd: Command): voi
  * the command and its test drive the same decision.
  */
 export declare function r2ImportGateError(fromR2: boolean, isConfigured: boolean): string | null;
-export declare function pullFromR2(): Promise<ParsedBundle>;
+export declare function pullFromR2(resolvedClient?: SessionsBackupClient): Promise<ParsedBundle>;

package/dist/commands/sessions-import.js

@@ -11,9 +11,12 @@
 import * as fs from 'fs';
 import chalk from 'chalk';
 import { isSyncConfigured, loadR2Config } from '../lib/session/sync/config.js';
-import { resolveSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
+import { isTranscriptEnvelope, resolveSyncEncKey } from '../lib/session/sync/transcript-crypto.js';
 import { R2Client } from '../lib/session/sync/r2.js';
 import { SESSIONS_PREFIX } from '../lib/session/sync/agents.js';
+import { resolveSessionsBackend } from '../lib/session/sync/backend.js';
+import { SessionsHttpClient } from '../lib/session/sync/net-client.js';
+import { resolveManagedBackupKey } from '../lib/session/sync/managed-key.js';
 import { parseBundle, planImport, writeImport, mergeRecords, makeHeader, } from '../lib/session/bundle.js';
 import { pullBundlesFromHosts } from '../lib/session/remote-bundle.js';
 import { setHelpSections } from '../lib/help.js';
@@ -25,7 +28,8 @@ export function registerSessionsImportCommand(sessionsCmd) {
         .option('--overwrite', 'Replace local files that differ from the bundle (default: keep local)')
         .option('--decrypt [key]', 'Decrypt an encrypted bundle (key optional if the r2.backups sync key is configured)')
         .option('--from-host <target...>', 'Pull sessions live from remote peer(s) over SSH instead of a file (repeatable)')
-        .option('--from-r2', 'Restore session backups from Cloudflare R2 (requires the r2.backups bundle)');
+        .option('--from-r2', 'Restore session backups from the off-box store (managed Phoenix store when signed in; your own r2.backups bucket with --byo)')
+        .option('--byo', 'With --from-r2: restore from your own r2.backups bucket instead of the managed Phoenix store');
     setHelpSections(cmd, {
         examples: `# Preview what a bundle would restore
 agents sessions import week.bundle --dry-run
@@ -46,9 +50,12 @@ they show up in 'agents sessions' tagged with that machine and never overwrite
 your own local sessions. Byte-exact duplicates are skipped. --from-host reuses
 the same SSH transport as the cross-machine listing (no R2, no daemon).
 
---from-r2 downloads every session backup in the r2.backups bucket and restores
-it through the same placement, using the shared R2_SYNC_ENC_KEY to decrypt (or
-pass --decrypt <key>). It is the inverse of 'sessions export --to-r2'.`,
+--from-r2 downloads every session backup from the off-box store and restores it
+through the same placement. When signed in it restores from the MANAGED Phoenix
+store and decrypts with your per-account key (recovered automatically, even on a
+fresh box); --byo restores from your own r2.backups bucket with its shared
+R2_SYNC_ENC_KEY (or pass --decrypt <key>). It is the inverse of
+'sessions export --to-r2'.`,
     });
     cmd.action(async (bundlePath, options, command) => {
         const g = command.optsWithGlobals();
@@ -58,13 +65,39 @@ pass --decrypt <key>). It is the inverse of 'sessions export --to-r2'.`,
 async function runImport(bundlePath, options, g, command) {
     // 1. Obtain the bundle — from R2, remote peer(s), stdin, or a file.
     let bundle;
+    // A managed restore recovers the per-account DEK (from the local cache or the
+    // Worker escrow) and decrypts with it; BYO falls back to the r2.backups key.
+    let managedDecryptKey;
+    if (options.byo && !options.fromR2) {
+        process.stderr.write(chalk.red('--byo is only valid with --from-r2.\n'));
+        process.exit(1);
+    }
     if (options.fromR2) {
-        const gateErr = r2ImportGateError(true, isSyncConfigured());
-        if (gateErr) {
-            process.stderr.write(chalk.red(gateErr + '\n'));
+        let client;
+        let managedClient;
+        let managedUserId;
+        try {
+            const backend = resolveSessionsBackend({ byo: options.byo });
+            if (backend.kind === 'managed') {
+                managedClient = new SessionsHttpClient({ baseUrl: backend.baseUrl, userId: backend.userId, token: backend.token });
+                client = managedClient;
+                managedUserId = backend.userId;
+            }
+            else {
+                const gateErr = r2ImportGateError(true, isSyncConfigured());
+                if (gateErr)
+                    throw new Error(gateErr);
+                client = new R2Client(backend.r2);
+            }
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`R2 restore: ${err.message}\n`));
             process.exit(1);
         }
-        bundle = await pullFromR2();
+        bundle = await pullFromR2(client);
+        if (managedUserId) {
+            managedDecryptKey = await resolveManagedBackupKey(managedClient, managedUserId);
+        }
     }
     else if (options.fromHost && options.fromHost.length > 0) {
         bundle = await pullForImport(options.fromHost, bundlePath, g, command);
@@ -98,8 +131,12 @@ async function runImport(bundlePath, options, g, command) {
             process.exit(1);
         }
     }
-    // 3. Resolve the decryption key if the bundle is encrypted.
-    const decryptKey = bundle.header.encrypted ? resolveDecryptKey(options.decrypt) : null;
+    // 3. Resolve the decryption key if the bundle is encrypted. A managed restore
+    //    already recovered the per-account DEK; otherwise fall back to an explicit
+    //    --decrypt <key> or the shared r2.backups key.
+    const decryptKey = bundle.header.encrypted
+        ? (managedDecryptKey ?? resolveDecryptKey(options.decrypt))
+        : null;
     // 4. Plan.
     let plan;
     try {
@@ -193,21 +230,33 @@ export function r2ImportGateError(fromR2, isConfigured) {
     }
     return null;
 }
-export async function pullFromR2() {
+export async function pullFromR2(resolvedClient) {
+    // The resolved client (managed HTTP or BYO R2) is passed in by the command; the
+    // no-client overload preserves the original BYO-only signature (loadR2Config)
+    // for the direct unit test. The managed client's list() ignores the prefix and
+    // enumerates the whole owner namespace, so one call site serves both.
     let client;
     let bucket;
-    try {
-        const cfg = loadR2Config();
-        bucket = cfg.bucket;
-        client = new R2Client(cfg);
+    if (resolvedClient) {
+        client = resolvedClient;
+        bucket = resolvedClient.kind === 'managed' ? 'managed' : 'byo';
     }
-    catch (err) {
-        process.stderr.write(chalk.red(`R2 restore: ${err.message}\n`));
-        process.exit(1);
+    else {
+        try {
+            const cfg = loadR2Config();
+            bucket = cfg.bucket;
+            client = new R2Client(cfg);
+        }
+        catch (err) {
+            process.stderr.write(chalk.red(`R2 restore: ${err.message}\n`));
+            process.exit(1);
+        }
     }
     let keys;
     try {
-        keys = await client.list(SESSIONS_PREFIX);
+        keys = client.kind === 'managed'
+            ? await client.list()
+            : await client.list(SESSIONS_PREFIX);
     }
     catch (err) {
         process.stderr.write(chalk.red(`R2 restore: listing failed: ${err.message}\n`));
@@ -239,6 +288,19 @@ export async function pullFromR2() {
             skipped++;
             continue;
         }
+        // Managed transcripts are mandatory AES-256-GCM (SES-51). A plaintext object
+        // in the managed store is a contract violation — an older/buggy writer or
+        // tampering — so fail loud rather than importing readable plaintext. Check
+        // the header AND every record body (matching the Worker's per-record
+        // isEncryptedManagedBundle boundary guard), never just the header flag.
+        if (client.kind === 'managed') {
+            const plaintext = !parsed.header.encrypted
+                || parsed.records.some(rec => !rec.encrypted || !isTranscriptEnvelope(rec.body));
+            if (plaintext) {
+                process.stderr.write(chalk.red(`R2 restore: managed backup ${key} is not encrypted — managed transcripts are always sealed; refusing to import plaintext.\n`));
+                process.exit(1);
+            }
+        }
         records.push(...parsed.records);
         if (parsed.header.encrypted)
             encryptedAny = true;
@@ -250,7 +312,9 @@ export async function pullFromR2() {
     }
     const deduped = mergeRecords([records]);
     if (deduped.length === 0) {
-        process.stderr.write(chalk.red(`No session backups found in R2 bucket '${bucket}'.\n`));
+        process.stderr.write(chalk.red(bucket === 'managed'
+            ? 'No session backups found in the managed store.\n'
+            : `No session backups found in R2 bucket '${bucket}'.\n`));
         process.exit(1);
     }
     const header = makeHeader({

package/dist/lib/accounting/usage-sync.d.ts

@@ -28,7 +28,7 @@ export interface PublishUsageSnapshotResult {
     path: string | null;
 }
 /** Publish this headed device's stable usage snapshot into its owned store file. */
-export declare function publishUsageSnapshotToSharedStore(options?: PublishUsageSnapshotOptions): PublishUsageSnapshotResult;
+export declare function publishUsageSnapshotToSharedStore(options?: PublishUsageSnapshotOptions): Promise<PublishUsageSnapshotResult>;
 export interface ConsumeUsageSnapshotsOptions {
     userAgentsDir?: string;
     cachePath?: string;

package/dist/lib/accounting/usage-sync.js

@@ -8,12 +8,12 @@
  * There is deliberately no device-to-device SSH in this module or its tick.
  */
 import { isHeadedDeviceRole, listConfiguredDeviceRoles, selfConfiguredDeviceRole } from '../device-config.js';
-import { readFleetSharedDeviceStates, updateFleetSharedDeviceState, } from '../fleet-shared-state.js';
+import { readFleetSharedDeviceStates, updateFleetSharedDeviceStateAsync, } from '../fleet-shared-state.js';
 import { getUserAgentsDir } from '../state.js';
 import { machineId, normalizeHost } from '../session/sync/config.js';
 import { exportClaudeUsageCacheRows, ingestPeerClaudeUsageRows, } from './usage.js';
 /** Publish this headed device's stable usage snapshot into its owned store file. */
-export function publishUsageSnapshotToSharedStore(options = {}) {
+export async function publishUsageSnapshotToSharedStore(options = {}) {
     const result = {
         published: false,
         changed: false,
@@ -32,7 +32,7 @@ export function publishUsageSnapshotToSharedStore(options = {}) {
         return result;
     }
     try {
-        const write = updateFleetSharedDeviceState(options.device ?? machineId(), { usage: { rows } }, options.userAgentsDir ?? getUserAgentsDir());
+        const write = await updateFleetSharedDeviceStateAsync(options.device ?? machineId(), { usage: { rows } }, options.userAgentsDir ?? getUserAgentsDir());
         result.published = true;
         result.changed = write.changed;
         result.path = write.path;

package/dist/lib/browser/ipc.d.ts

@@ -3,6 +3,16 @@ import { BrowserService } from './service.js';
 import type { IPCRequest, IPCResponse } from './types.js';
 export interface IPCRequestOptions {
     autoStartDaemon?: boolean;
+    /**
+     * Opt-in client-side deadline in ms — most IPC actions (browser automation,
+     * long-running recordings) have no fixed budget and must NOT get one by
+     * default. Set explicitly for a request that genuinely has one, e.g.
+     * `request-self-update`, whose handler answers immediately (it kicks the
+     * install off in the background — see `triggerSelfUpdateInBackground`), so its
+     * client deadline (`DAEMON_SELF_UPDATE_TRIGGER_TIMEOUT_MS`) is a short
+     * "did the daemon accept the trigger?" bound, not a wait on the install.
+     */
+    timeoutMs?: number;
 }
 export declare class BrowserServiceNotRunningError extends Error {
     constructor();
@@ -148,6 +158,23 @@ export declare class BrowserIPCServer {
  * owns the shared process.
  */
 export declare function shouldRecommendDaemonRefresh(daemonVersion: string | undefined, clientVersion: string): boolean;
+/**
+ * Reconcile the running daemon's version with ours without evicting it. If the
+ * daemon is serving stale code, ask the daemon to run its OWN self-update path
+ * (`request-self-update`, same fail-closed check/install/verify/exit
+ * SelfUpdateService's periodic tick runs, self-update-service.ts) rather than
+ * telling a human to run `agents daemon restart` by hand. A browser client
+ * still owns neither the shared supervisor nor its sibling services, so
+ * version skew can never be permission for THIS client to stop or restart
+ * that process directly (PHNX-3605 holds) — it only asks the daemon to run a
+ * path the daemon already runs on its own schedule, which only exits once the
+ * daemon itself has verified the new version is good. If self-update declines
+ * (dev build, shadowed install, already current, or a real failure) this
+ * degrades to the same "nothing changed" outcome PHNX-3605 shipped.
+ */
+export declare function reconcileDaemonVersion(): Promise<void>;
+/** Test-only: `reconcileDaemonVersion` runs at most once per real process — this clears that latch so a test file can drive more than one branch. */
+export declare function resetVersionReconciliationForTest(): void;
 export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;
 /**
  * Fill actor / launchId / sessionId from the calling process when the request
@@ -160,3 +187,10 @@ export declare function stampCallerIdentity(request: IPCRequest, env?: NodeJS.Pr
  * only the client process and IPC socket lifetime differ.
  */
 export declare function connectBrowserIPC(opts?: IPCRequestOptions): Promise<BrowserIPCConnection>;
+/**
+ * Exported (rather than kept module-private) so `ipc.test.ts` can drive the
+ * `opts.timeoutMs` client-side deadline directly against a raw `net.Server`
+ * test double that never responds — the hermetic way to prove the timeout
+ * actually fires without needing a slow real IPC action to provoke it.
+ */
+export declare function sendRawIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;