@phnx-labs/agents-cli 1.22.69 → 1.22.71

package/dist/lib/self-update.js

@@ -12,10 +12,13 @@
  * to PATH resolution.
  */
 import * as fs from 'fs';
+import * as fsp from 'fs/promises';
 import * as os from 'os';
 import * as path from 'path';
 import { createHash, timingSafeEqual } from 'crypto';
-import { spawnSync } from 'child_process';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
 // Leaf comparator only — do not pull the full versions.ts graph into every
 // bootstrap that imports self-update (RUSH-2331).
 import { compareVersions } from './agent-spec/primitives.js';
@@ -314,7 +317,7 @@ export function deriveGlobalPrefix(packageRoot) {
  * basename), so an unrelated dotfile in the same directory is left alone.
  * Best-effort per entry: one unremovable sibling must not block the rest.
  */
-export function sweepStaleInstallStaging(packageRoot) {
+export async function sweepStaleInstallStaging(packageRoot) {
     const resolved = path.resolve(packageRoot);
     const dir = path.dirname(resolved);
     const base = path.basename(resolved);
@@ -322,7 +325,7 @@ export function sweepStaleInstallStaging(packageRoot) {
     const stagingPattern = new RegExp(`^\\.${escapedBase}-[a-zA-Z0-9]+$`);
     let entries;
     try {
-        entries = fs.readdirSync(dir);
+        entries = await fsp.readdir(dir);
     }
     catch {
         return [];
@@ -333,7 +336,7 @@ export function sweepStaleInstallStaging(packageRoot) {
             continue;
         const full = path.join(dir, entry);
         try {
-            fs.rmSync(full, { recursive: true, force: true });
+            await fsp.rm(full, { recursive: true, force: true });
             swept.push(full);
         }
         catch {
@@ -347,14 +350,22 @@ export function sweepStaleInstallStaging(packageRoot) {
  * destination no matter which npm binary PATH resolves. `--ignore-scripts`
  * skips lifecycle scripts; the caller refreshes alias shims afterwards via
  * refreshAliasShims().
+ *
+ * `signal`, when passed, is wired into `execFile`'s own `signal` option —
+ * Node kills the child process on abort and the returned promise rejects,
+ * rather than the caller merely giving up on awaiting an orphaned process
+ * (self-update-service.ts's daemon tick needs a real kill here: on a
+ * deadline abort an un-killed `npm install -g` keeps writing into the same
+ * global prefix a subsequent retry then installs into concurrently).
  */
-export async function installPackageIntoPrefix(spec, prefix) {
+export async function installPackageIntoPrefix(spec, prefix, signal) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
     // On Windows `npm` is `npm.cmd`; execFile cannot run it without a shell (ENOENT).
     await execFileAsync('npm', ['install', '-g', '--prefix', prefix, spec, '--ignore-scripts'], {
         shell: needsWindowsShell('npm'),
+        signal,
     });
 }
 /**
@@ -364,8 +375,10 @@ export async function installPackageIntoPrefix(spec, prefix) {
  * in place. bun skips untrusted lifecycle scripts, so the caller refreshes
  * alias shims afterwards via refreshAliasShims() rather than relying on the
  * package's postinstall hook.
+ *
+ * `signal` behaves exactly as documented on {@link installPackageIntoPrefix}.
  */
-export async function installPackageWithBun(spec) {
+export async function installPackageWithBun(spec, signal) {
     const { execFile } = await import('child_process');
     const { promisify } = await import('util');
     const execFileAsync = promisify(execFile);
@@ -373,7 +386,7 @@ export async function installPackageWithBun(spec) {
     // --ignore-scripts: the tarball has already been integrity-verified, but its
     // lifecycle scripts must not run at install time (the caller refreshes shims
     // explicitly via refreshAliasShims()) — same fail-closed posture as the npm path.
-    await execFileAsync('bun', ['add', '-g', spec, '--ignore-scripts'], { shell: needsWindowsShell('bun') });
+    await execFileAsync('bun', ['add', '-g', spec, '--ignore-scripts'], { shell: needsWindowsShell('bun'), signal });
 }
 /**
  * Verify a downloaded tarball's bytes against a Subresource Integrity (SRI)
@@ -411,9 +424,14 @@ export function verifyTarballIntegrity(tarball, integrity) {
  * against the registry attestation. Fails closed: a non-200, a download error,
  * or a hash mismatch throws and no file path is returned, so the caller never
  * installs an unverified artifact.
+ *
+ * `signal`, when passed, aborts the fetch alongside the own `timeoutMs` timer
+ * (whichever fires first) — a real cancellation of the in-flight request, not
+ * just an abandoned await.
  */
-export async function downloadVerifiedTarball(tarballUrl, integrity, timeoutMs = 60_000) {
-    const response = await fetch(tarballUrl, { signal: AbortSignal.timeout(timeoutMs) });
+export async function downloadVerifiedTarball(tarballUrl, integrity, timeoutMs = 60_000, signal) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const response = await fetch(tarballUrl, { signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal });
     if (!response.ok) {
         throw new Error(`could not download tarball from ${tarballUrl} (HTTP ${response.status})`);
     }
@@ -425,15 +443,15 @@ export async function downloadVerifiedTarball(tarballUrl, integrity, timeoutMs =
     return file;
 }
 /** Read the version field of the package.json at `packageRoot`, fresh from disk. */
-export function readInstalledVersion(packageRoot) {
-    return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8')).version;
+export async function readInstalledVersion(packageRoot) {
+    return JSON.parse(await fsp.readFile(path.join(packageRoot, 'package.json'), 'utf-8')).version;
 }
 /**
  * Assert that the install at `packageRoot` now carries `expectedVersion`.
  * npm exiting 0 only proves it wrote *somewhere*; this proves it wrote *here*.
  */
-export function verifyInstalledVersion(packageRoot, expectedVersion) {
-    const actual = readInstalledVersion(packageRoot);
+export async function verifyInstalledVersion(packageRoot, expectedVersion) {
+    const actual = await readInstalledVersion(packageRoot);
     if (actual !== expectedVersion) {
         const manager = detectPackageManager(packageRoot);
         const hint = manualInstallHint(manager, packageRoot, `${NPM_PACKAGE_NAME}@${expectedVersion}`);
@@ -448,16 +466,21 @@ export function verifyInstalledVersion(packageRoot, expectedVersion) {
  * leaves the previous shims in place, which still point at the (now
  * upgraded) package root.
  */
-export function refreshAliasShims(packageRoot) {
-    spawnSync(process.execPath, [path.join(packageRoot, 'scripts', 'postinstall.js')], {
-        env: { ...process.env, AGENTS_POSTINSTALL_SHIMS_ONLY: '1' },
-        stdio: 'ignore',
-    });
+export async function refreshAliasShims(packageRoot, signal) {
+    try {
+        await execFileAsync(process.execPath, [path.join(packageRoot, 'scripts', 'postinstall.js')], {
+            env: { ...process.env, AGENTS_POSTINSTALL_SHIMS_ONLY: '1' },
+            signal,
+        });
+    }
+    catch {
+        /* best-effort — a failure here leaves the previous shims in place, same as the prior spawnSync (which ignored its exit code/stdio too) */
+    }
 }
 /** Resolve `p` through symlinks, or null when it does not resolve (missing/dangling). */
-function realpathOrNull(p) {
+async function realpathOrNull(p) {
     try {
-        return fs.realpathSync(p);
+        return await fsp.realpath(p);
     }
     catch {
         return null;
@@ -472,18 +495,18 @@ function realpathOrNull(p) {
  * repair that still does not resolve (target missing, unwritable bin dir) is
  * reported `failed` with the reason rather than silently swallowed.
  */
-function reconcileBinLink(name, linkPath, target) {
-    const wanted = realpathOrNull(target);
-    if (wanted !== null && realpathOrNull(linkPath) === wanted) {
+async function reconcileBinLink(name, linkPath, target) {
+    const wanted = await realpathOrNull(target);
+    if (wanted !== null && (await realpathOrNull(linkPath)) === wanted) {
         return { name, linkPath, target, action: 'ok' };
     }
     try {
-        fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+        await fsp.mkdir(path.dirname(linkPath), { recursive: true });
         // Replace whatever is there (a dangling link, a stale link, or nothing).
-        fs.rmSync(linkPath, { force: true });
-        fs.symlinkSync(path.relative(path.dirname(linkPath), target), linkPath);
-        const resolved = realpathOrNull(linkPath);
-        if (resolved !== null && resolved === realpathOrNull(target)) {
+        await fsp.rm(linkPath, { force: true });
+        await fsp.symlink(path.relative(path.dirname(linkPath), target), linkPath);
+        const resolved = await realpathOrNull(linkPath);
+        if (resolved !== null && resolved === (await realpathOrNull(target))) {
             return { name, linkPath, target, action: 'repaired' };
         }
         return {
@@ -524,10 +547,10 @@ function reconcileBinLink(name, linkPath, target) {
  * npm global prefix from {@link deriveGlobalPrefix}; the bun path uses its own
  * bin layout and is out of scope.
  */
-export function ensureGlobalBinLinks(packageRoot, prefix) {
+export async function ensureGlobalBinLinks(packageRoot, prefix) {
     let bin;
     try {
-        const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+        const pkg = JSON.parse(await fsp.readFile(path.join(packageRoot, 'package.json'), 'utf-8'));
         bin = pkg && typeof pkg.bin === 'object' && pkg.bin !== null ? pkg.bin : {};
     }
     catch (err) {
@@ -538,7 +561,7 @@ export function ensureGlobalBinLinks(packageRoot, prefix) {
     for (const [name, rel] of Object.entries(bin)) {
         if (typeof rel !== 'string' || !rel)
             continue;
-        repairs.push(reconcileBinLink(name, path.join(binDir, name), path.resolve(packageRoot, rel)));
+        repairs.push(await reconcileBinLink(name, path.join(binDir, name), path.resolve(packageRoot, rel)));
     }
     return repairs;
 }

package/dist/lib/session/cloud.js

@@ -15,6 +15,7 @@ import * as os from 'os';
 import * as yaml from 'yaml';
 import { deriveShortId } from '../text/short-id.js';
 import { getCacheDir } from '../state.js';
+import { isRushSessionExpired } from '../rush-session.js';
 const PROXY_BASE = process.env.RUSH_PROXY_BASE ?? 'https://api.prix.dev';
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 const CLOUD_CACHE_DIR = path.join(getCacheDir(), 'cloud-runs');
@@ -30,7 +31,7 @@ function readToken() {
         throw new Error('No session token in ~/.rush/user.yaml. Run `rush login` first.');
     }
     const expiresAt = data.session?.expires_at;
-    if (typeof expiresAt === 'number' && expiresAt <= Date.now() / 1000) {
+    if (isRushSessionExpired(expiresAt)) {
         const expiredAt = new Date(expiresAt * 1000).toISOString();
         throw new Error(`Rush session expired at ${expiredAt}. Run \`rush login\` to refresh.`);
     }

package/dist/lib/session/sync/backend.d.ts

@@ -0,0 +1,61 @@
+/**
+ * SessionsBackend — the token-source seam for `agents sessions export --to-r2` /
+ * `import --from-r2`.
+ *
+ * Two legitimate principals, picked once at backup time through the ONE shared
+ * managed-vs-BYO policy (`selectStorageBackendKind`):
+ *
+ *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
+ *     explicit BYO override. Token is the Phoenix access_token; endpoint is the
+ *     managed `sessions.agents-cli.sh` Worker; the namespace is the verified
+ *     userId. ZERO Cloudflare setup — the user never provisions an r2.backups
+ *     bucket. This is the whole point of the surface (the sessions analogue of
+ *     managed `agents traces sync`).
+ *   - **byo**: the existing `r2.backups` secrets bundle (`loadR2Config()`).
+ *     Unchanged for power users / self-hosters / a zero-knowledge backup that
+ *     Phoenix can never read.
+ *
+ * MANAGED-FIRST — the mere PRESENCE of an r2.backups bundle is NOT a BYO
+ * override. A signed-in user with a stale r2.backups bundle still backs up to
+ * managed unless they opt out explicitly: `--byo`, `AGENTS_SESSIONS_BACKEND=byo`,
+ * or a DI write token. This mirrors `lib/share/backend.ts` (a persisted BYO
+ * config is deliberately not an override) so the product's managed-first
+ * contract is identical across surfaces.
+ */
+import { type PhoenixSession } from '../../identity/client.js';
+import { type R2Config } from './config.js';
+export type SessionsBackendKind = 'managed' | 'byo';
+/** Env var that forces the BYO path. Value must be exactly `byo`. */
+export declare const SESSIONS_BACKEND_ENV = "AGENTS_SESSIONS_BACKEND";
+export interface ManagedSessionsBackend {
+    kind: 'managed';
+    /** Public base URL of the managed sessions Worker, no trailing slash. */
+    baseUrl: string;
+    /** Bearer sent as `Authorization`. The Phoenix access_token. */
+    token: string;
+    /** Phoenix userId — the object-store namespace prefix (path segment 0). */
+    userId: string;
+}
+export interface ByoSessionsBackend {
+    kind: 'byo';
+    /** The resolved r2.backups credentials for the S3-compatible client. */
+    r2: R2Config;
+}
+export type SessionsBackend = ManagedSessionsBackend | ByoSessionsBackend;
+export interface ResolveSessionsBackendOpts {
+    /** Force the BYO r2.backups path even when signed in. */
+    byo?: boolean;
+    /** DI seam — a static write token selects BYO (tests / self-host). */
+    writeToken?: string;
+    /** DI seam — override `readSession()`. `null` means explicitly signed out. */
+    session?: PhoenixSession | null;
+}
+/** True when the shared policy resolves to the managed principal for sessions. */
+export declare function shouldUseManagedSessions(opts?: ResolveSessionsBackendOpts): boolean;
+/**
+ * Resolve the backend for a session backup / restore. Managed when signed in and
+ * no explicit BYO override; otherwise BYO. Fails loud when neither principal can
+ * authenticate — the actionable message ("run auth login" or "add r2.backups")
+ * lives here, not in the shared policy.
+ */
+export declare function resolveSessionsBackend(opts?: ResolveSessionsBackendOpts): SessionsBackend;

package/dist/lib/session/sync/backend.js

@@ -0,0 +1,89 @@
+/**
+ * SessionsBackend — the token-source seam for `agents sessions export --to-r2` /
+ * `import --from-r2`.
+ *
+ * Two legitimate principals, picked once at backup time through the ONE shared
+ * managed-vs-BYO policy (`selectStorageBackendKind`):
+ *
+ *   - **managed**: the caller is signed in to Phoenix (`readSession()`), no
+ *     explicit BYO override. Token is the Phoenix access_token; endpoint is the
+ *     managed `sessions.agents-cli.sh` Worker; the namespace is the verified
+ *     userId. ZERO Cloudflare setup — the user never provisions an r2.backups
+ *     bucket. This is the whole point of the surface (the sessions analogue of
+ *     managed `agents traces sync`).
+ *   - **byo**: the existing `r2.backups` secrets bundle (`loadR2Config()`).
+ *     Unchanged for power users / self-hosters / a zero-knowledge backup that
+ *     Phoenix can never read.
+ *
+ * MANAGED-FIRST — the mere PRESENCE of an r2.backups bundle is NOT a BYO
+ * override. A signed-in user with a stale r2.backups bundle still backs up to
+ * managed unless they opt out explicitly: `--byo`, `AGENTS_SESSIONS_BACKEND=byo`,
+ * or a DI write token. This mirrors `lib/share/backend.ts` (a persisted BYO
+ * config is deliberately not an override) so the product's managed-first
+ * contract is identical across surfaces.
+ */
+import { readSession } from '../../identity/client.js';
+import { selectStorageBackendKind } from '../../storage/selection.js';
+import { loadR2Config } from './config.js';
+import { managedSessionsBaseUrl } from './managed-config.js';
+/** Env var that forces the BYO path. Value must be exactly `byo`. */
+export const SESSIONS_BACKEND_ENV = 'AGENTS_SESSIONS_BACKEND';
+/**
+ * The sessions surface's BYO-override signals: an explicit `--byo`, a
+ * caller-supplied static write token, or `AGENTS_SESSIONS_BACKEND=byo`. Detecting
+ * WHICH signals count is surface-specific; the managed-vs-BYO decision itself is
+ * the shared policy. A persisted r2.backups bundle is deliberately NOT an
+ * override — a signed-in user still backs up to managed unless they opt out.
+ */
+function sessionsByoOverride(opts) {
+    if (opts.byo === true)
+        return true;
+    if (opts.writeToken)
+        return true;
+    return (process.env[SESSIONS_BACKEND_ENV] ?? '').trim().toLowerCase() === 'byo';
+}
+/** True when the shared policy resolves to the managed principal for sessions. */
+export function shouldUseManagedSessions(opts = {}) {
+    return (selectStorageBackendKind({ byoOverride: sessionsByoOverride(opts), session: opts.session }) ===
+        'managed');
+}
+/**
+ * Resolve the backend for a session backup / restore. Managed when signed in and
+ * no explicit BYO override; otherwise BYO. Fails loud when neither principal can
+ * authenticate — the actionable message ("run auth login" or "add r2.backups")
+ * lives here, not in the shared policy.
+ */
+export function resolveSessionsBackend(opts = {}) {
+    // Resolve identity ONCE. Reading it for selection and then again for the
+    // backend creates a race where logout can flip the principal mid-preflight.
+    const session = opts.session === undefined ? readSession() : opts.session;
+    const explicitByo = sessionsByoOverride(opts);
+    if (selectStorageBackendKind({ byoOverride: explicitByo, session }) === 'managed') {
+        if (!session) {
+            throw new Error("Not signed in. Run 'agents auth login' to back up sessions to your Phoenix account.");
+        }
+        if (!session.access_token) {
+            throw new Error("Session has no access token. Run 'agents auth login' again.");
+        }
+        const userId = (session.userId ?? '').trim();
+        if (!userId) {
+            throw new Error("Signed in but the session has no user id. Run 'agents auth login' again.");
+        }
+        return { kind: 'managed', baseUrl: managedSessionsBaseUrl(), token: session.access_token, userId };
+    }
+    // BYO: the existing r2.backups bundle. loadR2Config throws an actionable error
+    // when the bundle is missing or locked.
+    try {
+        return { kind: 'byo', r2: loadR2Config() };
+    }
+    catch (err) {
+        // A user who is simply signed out (not an explicit --byo) and has no bundle
+        // should hear about the zero-setup managed path FIRST, then the BYO one.
+        if (!explicitByo) {
+            throw new Error("Not signed in, and no r2.backups bucket is configured. Run 'agents auth login' to " +
+                'back up to the managed Phoenix store (zero setup), or add the r2.backups bundle to ' +
+                'use your own bucket: agents secrets add r2.backups R2_ACCOUNT_ID R2_BUCKET_NAME R2_ACCESS_KEY_ID R2_SECRET_ACCESS_KEY');
+        }
+        throw err;
+    }
+}

package/dist/lib/session/sync/managed-config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Isolated Cloudflare resource choices for the managed session-backup store.
+ *
+ * The managed sessions backend is the Phoenix-gated, zero-setup path behind
+ * `agents sessions export --to-r2` / `import --from-r2` for a signed-in user —
+ * the sessions analogue of the managed `agents traces sync` store. A signed-in
+ * user never has to provision their own `r2.backups` bucket; the CLI talks to
+ * this already-live Worker under their Phoenix bearer.
+ *
+ * Mirrors `lib/traces/config.ts` + `managedTracesBaseUrl()`. The endpoint host
+ * is its own subdomain (a separate Worker + bucket from traces/share), so the
+ * blast radius of a bug or a quota exhaustion is one surface, not three.
+ */
+/** Managed sessions Worker domain — its own subdomain, separate from traces/share. */
+export declare const DEFAULT_SESSIONS_DOMAIN = "sessions.agents-cli.sh";
+/** Cloudflare Worker name for the managed sessions deployment. */
+export declare const DEFAULT_SESSIONS_WORKER_NAME = "agents-sessions";
+/** R2 bucket name backing the managed sessions Worker. */
+export declare const DEFAULT_SESSIONS_BUCKET_NAME = "agents-sessions";
+/** Isolated Cloudflare resources for the managed session-backup store. */
+export interface SessionsConfig {
+    baseUrl: string;
+    accountId: string;
+    workerName: string;
+    bucketName: string;
+    domain?: string;
+}
+/** Public base URL of the managed sessions Worker, no trailing slash. */
+export declare function managedSessionsBaseUrl(): string;

package/dist/lib/session/sync/managed-config.js

@@ -0,0 +1,23 @@
+/**
+ * Isolated Cloudflare resource choices for the managed session-backup store.
+ *
+ * The managed sessions backend is the Phoenix-gated, zero-setup path behind
+ * `agents sessions export --to-r2` / `import --from-r2` for a signed-in user —
+ * the sessions analogue of the managed `agents traces sync` store. A signed-in
+ * user never has to provision their own `r2.backups` bucket; the CLI talks to
+ * this already-live Worker under their Phoenix bearer.
+ *
+ * Mirrors `lib/traces/config.ts` + `managedTracesBaseUrl()`. The endpoint host
+ * is its own subdomain (a separate Worker + bucket from traces/share), so the
+ * blast radius of a bug or a quota exhaustion is one surface, not three.
+ */
+/** Managed sessions Worker domain — its own subdomain, separate from traces/share. */
+export const DEFAULT_SESSIONS_DOMAIN = 'sessions.agents-cli.sh';
+/** Cloudflare Worker name for the managed sessions deployment. */
+export const DEFAULT_SESSIONS_WORKER_NAME = 'agents-sessions';
+/** R2 bucket name backing the managed sessions Worker. */
+export const DEFAULT_SESSIONS_BUCKET_NAME = 'agents-sessions';
+/** Public base URL of the managed sessions Worker, no trailing slash. */
+export function managedSessionsBaseUrl() {
+    return `https://${DEFAULT_SESSIONS_DOMAIN}`;
+}

package/dist/lib/session/sync/managed-key.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Managed backup encryption key (DEK) — mint, cache, escrow, recover.
+ *
+ * On the MANAGED path, a session backup is NEVER uploaded in plaintext. Every
+ * transcript body is sealed with AES-256-GCM (the same `transcript-crypto.ts`
+ * primitives BYO uses) under a 32-byte data-encryption key (DEK) minted per
+ * Phoenix user.
+ *
+ * Where the DEK lives, and the honest trust boundary:
+ *   - **Local cache** at `~/.agents/.cache/state/sessions-backup-key.json`
+ *     (mode 0600), a `{ [userId]: <base64-dek> }` map so several Phoenix
+ *     accounts on one box stay isolated. The Worker escrow remains authoritative.
+ *   - **Escrow** at the bearer-gated Worker key `<userId>/__key/backup-dek`, so
+ *     a FRESH box that signs in with the same Phoenix account recovers the DEK
+ *     with zero setup and can decrypt its own prior backups.
+ *
+ * Trust boundary (documented honestly — SES-51):
+ *   - Confidential vs a raw R2 / Cloudflare bucket read: objects at rest are
+ *     ciphertext envelopes (SES-24 holds), and the DEK escrow object is itself
+ *     only reachable with the owner's bearer.
+ *   - NOT zero-knowledge vs Phoenix: the DEK is escrowed on Phoenix-operated
+ *     infrastructure, so the operator *can* recover the key and read a backup.
+ *     A user who needs a key Phoenix can never see uses BYO (`--byo`), which
+ *     keeps the DEK only in their own `r2.backups` bundle — that is the
+ *     zero-knowledge path.
+ */
+import type { ManagedSessionsBackupClient } from './net-client.js';
+/** Worker key (relative to the `<userId>/` namespace prefix the client prepends). */
+export declare const ESCROW_REL_KEY = "__key/backup-dek";
+/** Local per-user DEK cache file — a `{ [userId]: base64 }` map, mode 0600. */
+export declare function backupKeyCachePath(): string;
+/** The DEK cached locally for this Phoenix user, or null. */
+export declare function readCachedBackupKey(userId: string): Buffer | null;
+/** Persist a DEK (base64) for this Phoenix user in the local 0600 cache. */
+export declare function cacheBackupKey(userId: string, b64: string): void;
+/**
+ * Resolve the managed backup DEK for `userId`, minting + escrowing one on first
+ * use. NEVER returns null — the managed path must not upload plaintext.
+ *
+ * The escrow is authoritative. On a missing escrow, the local cache (if any) is
+ * restored with a conditional create; otherwise a new key is minted. Concurrent
+ * first-use devices race that create, then every loser reads the one winner
+ * before encrypting anything, so no backup can be orphaned under a losing DEK.
+ */
+export declare function resolveManagedBackupKey(client: ManagedSessionsBackupClient, userId: string): Promise<Buffer>;

package/dist/lib/session/sync/managed-key.js

@@ -0,0 +1,128 @@
+/**
+ * Managed backup encryption key (DEK) — mint, cache, escrow, recover.
+ *
+ * On the MANAGED path, a session backup is NEVER uploaded in plaintext. Every
+ * transcript body is sealed with AES-256-GCM (the same `transcript-crypto.ts`
+ * primitives BYO uses) under a 32-byte data-encryption key (DEK) minted per
+ * Phoenix user.
+ *
+ * Where the DEK lives, and the honest trust boundary:
+ *   - **Local cache** at `~/.agents/.cache/state/sessions-backup-key.json`
+ *     (mode 0600), a `{ [userId]: <base64-dek> }` map so several Phoenix
+ *     accounts on one box stay isolated. The Worker escrow remains authoritative.
+ *   - **Escrow** at the bearer-gated Worker key `<userId>/__key/backup-dek`, so
+ *     a FRESH box that signs in with the same Phoenix account recovers the DEK
+ *     with zero setup and can decrypt its own prior backups.
+ *
+ * Trust boundary (documented honestly — SES-51):
+ *   - Confidential vs a raw R2 / Cloudflare bucket read: objects at rest are
+ *     ciphertext envelopes (SES-24 holds), and the DEK escrow object is itself
+ *     only reachable with the owner's bearer.
+ *   - NOT zero-knowledge vs Phoenix: the DEK is escrowed on Phoenix-operated
+ *     infrastructure, so the operator *can* recover the key and read a backup.
+ *     A user who needs a key Phoenix can never see uses BYO (`--byo`), which
+ *     keeps the DEK only in their own `r2.backups` bundle — that is the
+ *     zero-knowledge path.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from '../../fs-atomic.js';
+import { getRuntimeStateDir } from '../../state.js';
+import { generateSyncEncKey } from './transcript-crypto.js';
+const KEY_LEN = 32; // AES-256
+/** Worker key (relative to the `<userId>/` namespace prefix the client prepends). */
+export const ESCROW_REL_KEY = '__key/backup-dek';
+/** Local per-user DEK cache file — a `{ [userId]: base64 }` map, mode 0600. */
+export function backupKeyCachePath() {
+    return path.join(getRuntimeStateDir(), 'sessions-backup-key.json');
+}
+function readCache() {
+    try {
+        const raw = fs.readFileSync(backupKeyCachePath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        const cache = Object.create(null);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return cache;
+        for (const [userId, value] of Object.entries(parsed)) {
+            if (typeof value === 'string')
+                cache[userId] = value;
+        }
+        return cache;
+    }
+    catch {
+        return Object.create(null);
+    }
+}
+/** Decode a base64/hex DEK into a 32-byte key, or null when it is malformed. */
+function decodeDek(raw) {
+    const s = (raw ?? '').trim();
+    if (!s)
+        return null;
+    const key = /^[0-9a-f]{64}$/i.test(s) ? Buffer.from(s, 'hex') : Buffer.from(s, 'base64');
+    return key.length === KEY_LEN ? key : null;
+}
+/** The DEK cached locally for this Phoenix user, or null. */
+export function readCachedBackupKey(userId) {
+    return decodeDek(readCache()[userId]);
+}
+/** Persist a DEK (base64) for this Phoenix user in the local 0600 cache. */
+export function cacheBackupKey(userId, b64) {
+    const file = backupKeyCachePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    ensureLockTarget(file, '{}', 0o700);
+    fs.chmodSync(file, 0o600);
+    withFileLock(file, () => {
+        const cache = readCache();
+        cache[userId] = b64;
+        atomicWriteFileSync(file, JSON.stringify(cache, null, 2), { encoding: 'utf-8', mode: 0o600 });
+        fs.chmodSync(file, 0o600);
+    });
+}
+function parseEscrow(body, expectedUserId) {
+    try {
+        const obj = JSON.parse(body);
+        if (obj && obj.v === 1 && obj.userId === expectedUserId &&
+            typeof obj.dek === 'string')
+            return decodeDek(obj.dek);
+    }
+    catch {
+        /* not an escrow envelope */
+    }
+    return null;
+}
+/**
+ * Resolve the managed backup DEK for `userId`, minting + escrowing one on first
+ * use. NEVER returns null — the managed path must not upload plaintext.
+ *
+ * The escrow is authoritative. On a missing escrow, the local cache (if any) is
+ * restored with a conditional create; otherwise a new key is minted. Concurrent
+ * first-use devices race that create, then every loser reads the one winner
+ * before encrypting anything, so no backup can be orphaned under a losing DEK.
+ */
+export async function resolveManagedBackupKey(client, userId) {
+    const escrowed = await client.get(ESCROW_REL_KEY);
+    if (escrowed !== null) {
+        const key = parseEscrow(escrowed, userId);
+        if (key) {
+            cacheBackupKey(userId, key.toString('base64'));
+            return key;
+        }
+        throw new Error('Managed session backup key escrow is corrupt or belongs to another account; ' +
+            'refusing to replace it because that would orphan existing encrypted backups.');
+    }
+    const cached = readCachedBackupKey(userId);
+    const b64 = cached?.toString('base64') ?? generateSyncEncKey();
+    const envelope = { v: 1, userId, dek: b64 };
+    const created = await client.putIfAbsent(ESCROW_REL_KEY, JSON.stringify(envelope), 'application/json');
+    if (created) {
+        cacheBackupKey(userId, b64);
+        return Buffer.from(b64, 'base64');
+    }
+    const winnerBody = await client.get(ESCROW_REL_KEY);
+    const winner = winnerBody === null ? null : parseEscrow(winnerBody, userId);
+    if (!winner) {
+        throw new Error('Managed session backup key escrow was contended but no valid winning key could be recovered.');
+    }
+    cacheBackupKey(userId, winner.toString('base64'));
+    return winner;
+}

package/dist/lib/session/sync/net-client.d.ts

@@ -0,0 +1,65 @@
+/**
+ * SessionsHttpClient — the managed transport for `agents sessions export
+ * --to-r2` / `import --from-r2` when the caller is signed in to Phoenix.
+ *
+ * Same put / get / list / delete surface as `R2Client` (`./r2.ts`), so the
+ * export/import command drives EITHER a managed HTTP client or a BYO S3 client
+ * through the one shared {@link SessionsBackupClient} interface. The difference
+ * is only the wire: this talks to the managed sessions Worker over `fetch` with
+ * a `Authorization: Bearer <phoenix-token>` header (the same request shape as
+ * `traces/sync.ts`), instead of SigV4 against R2 directly.
+ *
+ * The userId namespace prefix is prepended INSIDE this client
+ * (`${baseUrl}/${userId}/${key}`), so the caller passes the SAME object key it
+ * passes to `R2Client` (`sessions/<machine>/<agent>/<sessionId>.jsonl`). That
+ * keeps the BYO object layout (SES-27a) byte-identical while the managed Worker
+ * gets its required `segments[0] === userId` prefix.
+ */
+/**
+ * The verbs the session backup/restore path needs, satisfied by BOTH the
+ * managed {@link SessionsHttpClient} and the BYO `R2Client`. `list` takes an
+ * optional prefix: BYO passes the `sessions/` prefix; managed ignores it and
+ * enumerates the whole owner namespace server-side.
+ */
+export interface SessionsBackupClient {
+    readonly kind: 'managed' | 'byo';
+    put(key: string, body: string | Uint8Array, contentType?: string): Promise<void>;
+    get(key: string): Promise<string | null>;
+    list(prefix?: string): Promise<string[]>;
+    delete(key: string): Promise<void>;
+}
+/** Managed-only extension used to establish an immutable escrow key. */
+export interface ManagedSessionsBackupClient extends SessionsBackupClient {
+    readonly kind: 'managed';
+    putIfAbsent(key: string, body: string | Uint8Array, contentType?: string): Promise<boolean>;
+}
+export declare class SessionsHttpClient implements ManagedSessionsBackupClient {
+    readonly kind: "managed";
+    private base;
+    private userId;
+    private token;
+    constructor(opts: {
+        baseUrl: string;
+        userId: string;
+        token: string;
+    });
+    /** `${baseUrl}/<userId>/<key>` with every path segment percent-encoded. */
+    private objUrl;
+    private authHeaders;
+    /** Upload an object under this owner's namespace. Overwrites unconditionally. */
+    put(key: string, body: string | Uint8Array, contentType?: string): Promise<void>;
+    /** Create an object exactly once. A concurrent winner returns false. */
+    putIfAbsent(key: string, body: string | Uint8Array, contentType?: string): Promise<boolean>;
+    /** Fetch an object as text, or null if it does not exist (404). */
+    get(key: string): Promise<string | null>;
+    /**
+     * List this owner's object keys, each relative to the `<userId>/` prefix (so
+     * they feed straight back into `get`/`delete`). The `prefix` arg is accepted
+     * for interface parity with `R2Client` but ignored — the managed Worker
+     * enumerates the whole owner namespace and excludes the reserved `__` keys
+     * server-side.
+     */
+    list(_prefix?: string): Promise<string[]>;
+    /** Delete an object (the Worker refunds its bytes to the quota ledger). */
+    delete(key: string): Promise<void>;
+}