@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/lib/secrets/usage-db.js

@@ -0,0 +1,236 @@
+/**
+ * SQLite-backed usage read-model for `agents secrets`.
+ *
+ * A small local database at ~/.agents/secrets/secrets.db that records one
+ * value-free row for every secret lifecycle/access event a bundle accrues over
+ * its life — created, imported, exported, viewed, accessed (read for injection),
+ * unlocked. It is the queryable, per-bundle counterpart to the append-only
+ * ~/.agents/events.jsonl audit log: the SAME chokepoint (`emitSecretAudit`,
+ * lib/secrets/audit.ts) feeds both, and this store answers "how often / how
+ * recently / by whom was THIS bundle used?" without scanning the whole event
+ * stream. It is a DERIVED index fed off the real access flow — the way
+ * sessions.db indexes session metadata — never a second write path an operation
+ * has to remember to call.
+ *
+ * Contract, mirroring the audit log: NEVER a secret value. Only metadata — the
+ * bundle name, the event kind, key counts, the resolving agent/host, a status.
+ *
+ * Every write is best-effort: a failure here (missing runtime SQLite, a locked
+ * db, a read-only fs) is swallowed so usage telemetry can never break secret
+ * resolution. Set AGENTS_NO_USAGE_TRACK=1 to disable recording entirely (used by
+ * tests and by callers that must stay perfectly silent).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import Database from '../sqlite.js';
+import { getSecretsDbPath } from '../state.js';
+/** All event kinds, in the order `view` prints them. */
+export const SECRET_USAGE_EVENTS = [
+    'access',
+    'unlock',
+    'import',
+    'export',
+    'create',
+    'view',
+];
+/** Events older than this are pruned on open so the history table stays bounded. */
+const EVENT_RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS usage_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts TEXT NOT NULL,
+  bundle TEXT NOT NULL,
+  event TEXT NOT NULL,
+  agent TEXT,
+  host TEXT,
+  source TEXT,
+  status TEXT,
+  key_count INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_usage_bundle ON usage_events(bundle);
+CREATE INDEX IF NOT EXISTS idx_usage_bundle_event ON usage_events(bundle, event);
+CREATE INDEX IF NOT EXISTS idx_usage_ts ON usage_events(ts DESC);
+`;
+// Cached handle keyed by the resolved path, so a test that redirects
+// AGENTS_SECRETS_DB to a fresh temp file transparently reopens instead of
+// reusing a stale handle pointed at the previous path.
+let cached = null;
+function emptyEvents() {
+    return {
+        access: { count: 0, last: null },
+        unlock: { count: 0, last: null },
+        import: { count: 0, last: null },
+        export: { count: 0, last: null },
+        create: { count: 0, last: null },
+        view: { count: 0, last: null },
+    };
+}
+/**
+ * Open (creating if needed) the usage DB, returning null on any failure so
+ * every caller degrades to a no-op rather than throwing into secret resolution.
+ */
+function open() {
+    const dbPath = getSecretsDbPath();
+    if (cached && cached.path === dbPath)
+        return cached.db;
+    if (cached) {
+        try {
+            cached.db.close();
+        }
+        catch { /* ignore */ }
+        cached = null;
+    }
+    try {
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+        const db = new Database(dbPath);
+        // WAL + a busy timeout so concurrent agent runs writing usage rows don't
+        // fail each other under load; every write is still best-effort besides.
+        db.pragma('journal_mode = WAL');
+        db.pragma('busy_timeout = 2000');
+        db.exec(SCHEMA);
+        // Bounded retention: this is a usage history for operators, not a compliance
+        // log (that is events.jsonl). Prune once per open on a 90-day window.
+        try {
+            db.prepare(`DELETE FROM usage_events WHERE ts < ?`).run(new Date(Date.now() - EVENT_RETENTION_MS).toISOString());
+        }
+        catch { /* prune is best-effort */ }
+        cached = { path: dbPath, db };
+        return db;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Record one usage event. Best-effort and value-free — swallows every error and
+ * honors AGENTS_NO_USAGE_TRACK so telemetry never blocks or slows a read. Rows
+ * with an empty bundle name are ignored (usage is per-bundle by definition).
+ *
+ * This is called from ONE place only — `emitSecretAudit` (lib/secrets/audit.ts)
+ * — so every recorded event has already been written to the events.jsonl audit
+ * log through the same chokepoint. Do not call it from a command handler; emit
+ * the audit event instead.
+ */
+export function recordSecretUsage(p) {
+    if (process.env.AGENTS_NO_USAGE_TRACK)
+        return;
+    if (!p.bundle)
+        return;
+    const db = open();
+    if (!db)
+        return;
+    try {
+        db.prepare(`INSERT INTO usage_events (ts, bundle, event, agent, host, source, status, key_count)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), p.bundle, p.event, p.agent ?? null, p.host ?? null, p.source ?? null, p.status ?? 'success', p.keyCount ?? null);
+    }
+    catch {
+        // Telemetry must never break secret resolution.
+    }
+}
+function toSummary(bundle, rows, byAgent) {
+    const events = emptyEvents();
+    let total = 0;
+    let lastUsedAt = null;
+    let firstUsedAt = null;
+    for (const r of rows) {
+        if (r.event in events) {
+            const stat = events[r.event];
+            stat.count = r.n;
+            stat.last = r.last;
+        }
+        total += r.n;
+        if (r.last && (!lastUsedAt || r.last > lastUsedAt))
+            lastUsedAt = r.last;
+        if (r.first && (!firstUsedAt || r.first < firstUsedAt))
+            firstUsedAt = r.first;
+    }
+    return { bundle, total, events, lastUsedAt, firstUsedAt, byAgent };
+}
+/**
+ * Usage summary for one bundle, or undefined when nothing has ever been
+ * recorded (or the DB is unavailable). Never throws.
+ */
+export function getBundleUsage(bundle) {
+    const db = open();
+    if (!db)
+        return undefined;
+    try {
+        const rows = db
+            .prepare(`SELECT event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+           FROM usage_events WHERE bundle = ? GROUP BY event`)
+            .all(bundle);
+        if (rows.length === 0)
+            return undefined;
+        const agents = db
+            .prepare(`SELECT agent, COUNT(*) AS n FROM usage_events
+           WHERE bundle = ? AND agent IS NOT NULL GROUP BY agent ORDER BY n DESC`)
+            .all(bundle);
+        return toSummary(bundle, rows, agents.map((a) => ({ agent: a.agent, count: a.n })));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Usage summaries for every bundle that has any recorded event, keyed by bundle
+ * name. Powers `secrets list --sort uses|used`. Empty map when the DB is
+ * unavailable or has no rows. Never throws.
+ */
+export function getAllBundleUsage() {
+    const out = new Map();
+    const db = open();
+    if (!db)
+        return out;
+    try {
+        const rows = db
+            .prepare(`SELECT bundle, event, COUNT(*) AS n, MAX(ts) AS last, MIN(ts) AS first
+           FROM usage_events GROUP BY bundle, event`)
+            .all();
+        const byBundle = new Map();
+        for (const r of rows) {
+            const list = byBundle.get(r.bundle) ?? [];
+            list.push(r);
+            byBundle.set(r.bundle, list);
+        }
+        for (const [bundle, list] of byBundle)
+            out.set(bundle, toSummary(bundle, list, []));
+        return out;
+    }
+    catch {
+        return out;
+    }
+}
+/**
+ * Recent events for the `secrets activity` timeline — one bundle when named,
+ * else across all bundles — newest first. Empty when the DB is unavailable.
+ * Never throws.
+ */
+export function getUsageHistory(bundle, limit = 20) {
+    const db = open();
+    if (!db)
+        return [];
+    try {
+        const sql = bundle
+            ? `SELECT ts, bundle, event, agent, host, source, status, key_count AS keyCount
+           FROM usage_events WHERE bundle = ? ORDER BY ts DESC, id DESC LIMIT ?`
+            : `SELECT ts, bundle, event, agent, host, source, status, key_count AS keyCount
+           FROM usage_events ORDER BY ts DESC, id DESC LIMIT ?`;
+        const rows = bundle
+            ? db.prepare(sql).all(bundle, limit)
+            : db.prepare(sql).all(limit);
+        return rows;
+    }
+    catch {
+        return [];
+    }
+}
+/** Close the cached handle. Used by tests between temp-db swaps. */
+export function closeSecretsUsageDb() {
+    if (cached) {
+        try {
+            cached.db.close();
+        }
+        catch { /* ignore */ }
+        cached = null;
+    }
+}

package/dist/lib/session/active.d.ts

@@ -265,6 +265,14 @@ export declare function activeStatusFromCloudStatus(status: CloudTaskStatus): Ac
 export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
+    /**
+     * A `--local` query: this machine only. Never dial a remote-host teammate
+     * (one dispatched via `agents teams add --device`) over ssh — report its
+     * last-persisted meta.json state instead of polling it. RUSH-2118: without
+     * this, `agents sessions --active --local` still fired one ssh round-trip
+     * per remote-host teammate (finished or not) on every call.
+     */
+    localOnly?: boolean;
 }
 /**
  * A live process can only borrow an indexed session file if that transcript
@@ -421,8 +429,14 @@ export declare function computeLiveSignals(kind: string, sessionFile: string | u
  * and truncates. Exported for tests.
  */
 export declare function summarizeMission(prompt: string | null | undefined): string | undefined;
-/** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
-export declare function listTeamsActive(): Promise<ActiveSession[]>;
+/**
+ * Live teams teammates. Reuses AgentManager which already polls PIDs via
+ * `kill -0`. `localOnly` (RUSH-2118) skips the ssh round-trip AgentManager
+ * would otherwise issue for every distributed (remote-host) teammate.
+ */
+export declare function listTeamsActive(opts?: {
+    localOnly?: boolean;
+}): Promise<ActiveSession[]>;
 /** Live editor-terminal agents across every IDE window. */
 export declare function listTerminalsActive(): Promise<ActiveSession[]>;
 /** Cloud tasks still in a non-terminal state. `tasks.db` may not exist; that's fine. */

package/dist/lib/session/active.js

@@ -697,9 +697,13 @@ export function summarizeMission(prompt) {
         return undefined;
     return cleaned.length > 80 ? `${cleaned.slice(0, 79)}…` : cleaned;
 }
-/** Live teams teammates. Reuses AgentManager which already polls PIDs via `kill -0`. */
-export async function listTeamsActive() {
-    const mgr = new AgentManager();
+/**
+ * Live teams teammates. Reuses AgentManager which already polls PIDs via
+ * `kill -0`. `localOnly` (RUSH-2118) skips the ssh round-trip AgentManager
+ * would otherwise issue for every distributed (remote-host) teammate.
+ */
+export async function listTeamsActive(opts = {}) {
+    const mgr = new AgentManager(undefined, undefined, undefined, undefined, undefined, opts.localOnly ?? false);
     const running = await mgr.listRunning();
     return running.map((a) => {
         // The teammate's OWN transcript is `remoteSessionId` (captured from its first
@@ -1438,7 +1442,7 @@ export async function listTmuxAgentSessions() {
 export async function getActiveSessions(opts = {}) {
     const [tmuxAgents, teams, terminals, cloud] = await Promise.all([
         listTmuxAgentSessions().catch(() => []),
-        listTeamsActive().catch(() => []),
+        listTeamsActive({ localOnly: opts.localOnly }).catch(() => []),
         listTerminalsActive().catch(() => []),
         Promise.resolve(listCloudActive()),
     ]);

package/dist/lib/session/bundle.js

@@ -19,12 +19,16 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import * as crypto from 'crypto';
 import { SYNC_AGENTS, mirrorPath } from './sync/agents.js';
-import { hashContent } from './sync/manifest.js';
 import { redactSecrets } from '../redact.js';
 import { encryptTranscript, decryptTranscriptBody } from './sync/transcript-crypto.js';
 export const BUNDLE_KIND = 'agents-session-bundle';
 export const BUNDLE_VERSION = 1;
+/** SHA-256 of a file body, used for the bundle's dedup/conflict check on import. */
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
 /** Look up the sync spec for an agent id (undefined → agent not sync-representable). */
 export function specForAgent(agentId) {
     return SYNC_AGENTS.find(s => s.id === agentId);

package/dist/lib/session/remote-active.d.ts

@@ -25,5 +25,9 @@ export interface RemoteActiveResult {
  * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
  * online devices from `ag devices`, excluding this machine and any without an
  * address. Results from all peers run in parallel and are flattened.
+ * `opts.quiet` suppresses the per-device stderr line for callers that report
+ * skipped peers once, compactly, themselves.
  */
-export declare function gatherRemoteActive(hosts?: string[]): Promise<RemoteActiveResult>;
+export declare function gatherRemoteActive(hosts?: string[], opts?: {
+    quiet?: boolean;
+}): Promise<RemoteActiveResult>;

package/dist/lib/session/remote-active.js

@@ -56,13 +56,16 @@ export function parseRemoteActive(stdout, machine) {
  * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
  * online devices from `ag devices`, excluding this machine and any without an
  * address. Results from all peers run in parallel and are flattened.
+ * `opts.quiet` suppresses the per-device stderr line for callers that report
+ * skipped peers once, compactly, themselves.
  */
-export async function gatherRemoteActive(hosts) {
+export async function gatherRemoteActive(hosts, opts) {
     const result = await gatherRemoteAgentsJson({
         args: ['sessions', '--active', '--json'],
         noFanoutEnv: NO_FANOUT_ENV,
         hosts,
         parse: parseRemoteActive,
+        quiet: opts?.quiet,
     });
     return { sessions: result.items, deviceCount: result.deviceCount };
 }

package/dist/lib/session/remote-list.d.ts

@@ -1,12 +1,4 @@
 import type { SessionMeta } from './types.js';
-/**
- * The command run on each peer: answer for itself, as JSON, without recursing.
- * `forwardedArgs` carry the caller's own query/filters (already including the
- * leading `sessions` and a `--json`) so each peer returns a comparable slice.
- * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
- * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
- */
-export declare function remoteListCommand(forwardedArgs: string[], os?: string): string;
 /**
  * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
  * with `machine`. Defensive against version skew / partial output: non-JSON or
@@ -17,15 +9,9 @@ export declare function remoteListCommand(forwardedArgs: string[], os?: string):
  */
 export declare function parseRemoteList(stdout: string, machine: string): SessionMeta[];
 export declare function parseRemoteListPayload(stdout: string, machine: string, safeResolver?: boolean): {
-    sessions: SessionMeta[];
+    items: SessionMeta[];
     valid: boolean;
 };
-/** Convert one completed peer process into the exact aggregation result. This
- * is the production parent/peer seam and is exercised with real child output. */
-export declare function remoteListCaptureResult(code: number | null, stdout: string, machine: string, display: string, safeResolver?: boolean): {
-    sessions: SessionMeta[];
-    unreachable?: string;
-};
 export interface RemoteListResult {
     sessions: SessionMeta[];
     /** How many peer machines we attempted to reach (drives the empty-fleet tip). */

package/dist/lib/session/remote-list.js

@@ -17,32 +17,12 @@ import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from '../devices/connect.js';
-import { resolveExplicitTargets } from '../devices/resolve-target.js';
-import { loadDevices, isControlDevice, isDialableDevice } from '../devices/registry.js';
+import { loadDevices } from '../devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
-import { machineId, normalizeHost } from './sync/config.js';
+import { gatherRemoteAgentsJson } from '../remote-agents-json.js';
+import { normalizeHost } from './sync/config.js';
 import { NO_FANOUT_ENV } from './remote-active.js';
 import { terminalWidth } from './width.js';
-/** Per-host SSH budget. Slightly above SSH_OPTS' ConnectTimeout=10 so a
- * reachable-but-slow remote still answers before we give up. */
-const REMOTE_TIMEOUT_MS = 12_000;
-/**
- * The command run on each peer: answer for itself, as JSON, without recursing.
- * `forwardedArgs` carry the caller's own query/filters (already including the
- * leading `sessions` and a `--json`) so each peer returns a comparable slice.
- * A Windows peer gets a PowerShell invocation (ssh lands in cmd.exe/PowerShell
- * there, where `bash -lc` is not a command); every other OS keeps `bash -lc`.
- */
-export function remoteListCommand(forwardedArgs, os) {
-    if (remoteShellFor(os) === 'powershell') {
-        return buildWindowsAgentsCommand({
-            args: forwardedArgs,
-            env: { [NO_FANOUT_ENV]: '1' },
-        });
-    }
-    const inner = [`${NO_FANOUT_ENV}=1`, 'agents', ...forwardedArgs].map((t, i) => i === 0 ? t : shellQuote(t)).join(' ');
-    return `bash -lc ${shellQuote(inner)}`;
-}
 /**
  * Parse a peer's `sessions --json` stdout into `SessionMeta[]`, tagging each
  * with `machine`. Defensive against version skew / partial output: non-JSON or
@@ -83,61 +63,22 @@ export function parseRemoteListPayload(stdout, machine, safeResolver = false) {
         parsed = JSON.parse(stdout);
     }
     catch {
-        return { sessions: [], valid: false };
+        return { items: [], valid: false };
     }
     if (!Array.isArray(parsed))
-        return { sessions: [], valid: false };
+        return { items: [], valid: false };
     const out = [];
     for (const x of parsed) {
         if (!x || typeof x !== 'object' || Array.isArray(x))
-            return { sessions: [], valid: false };
+            return { items: [], valid: false };
         if (safeResolver && !isSafeResolverRow(x)) {
-            return { sessions: [], valid: false };
+            return { items: [], valid: false };
         }
         // `_remote` marks these as living on the peer's disk (not a local mirror),
         // so the picker routes read/resume back over SSH instead of the local FS.
         out.push({ ...x, machine, _remote: true });
     }
-    return { sessions: out, valid: true };
-}
-/** Convert one completed peer process into the exact aggregation result. This
- * is the production parent/peer seam and is exercised with real child output. */
-export function remoteListCaptureResult(code, stdout, machine, display, safeResolver = false) {
-    if (code !== 0)
-        return { sessions: [], unreachable: display };
-    const parsed = parseRemoteListPayload(stdout, machine, safeResolver);
-    return parsed.valid ? { sessions: parsed.sessions } : { sessions: [], unreachable: display };
-}
-/** Run one remote `agents sessions … --json` and capture stdout. Resolves
- * `{ code: null }` on spawn error or timeout (host treated as dead). */
-function sshCapture(target, remoteCmd, timeoutMs) {
-    assertValidSshTarget(target);
-    return new Promise((resolve) => {
-        const args = [...SSH_OPTS, ...controlOpts(), target, remoteCmd];
-        const child = spawn('ssh', args, { stdio: ['ignore', 'pipe', 'ignore'] });
-        let stdout = '';
-        let settled = false;
-        const done = (code) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve({ code, stdout });
-        };
-        const timer = setTimeout(() => { child.kill('SIGKILL'); done(null); }, timeoutMs);
-        child.stdout.on('data', (d) => { stdout += d.toString(); });
-        child.on('error', () => done(null));
-        child.on('close', (code) => done(code));
-    });
-}
-async function fetchByTarget(target, machine, display, forwardedArgs, os) {
-    const { code, stdout } = await sshCapture(target, remoteListCommand(forwardedArgs, os), REMOTE_TIMEOUT_MS);
-    const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
-    const result = remoteListCaptureResult(code, stdout, machine, display, safeResolver);
-    if (result.unreachable) {
-        process.stderr.write(chalk.gray(`  ${display}: unreachable or no agents CLI — skipped\n`));
-    }
-    return result;
+    return { items: out, valid: true };
 }
 /**
  * Gather listing sessions from other machines. With an explicit `hosts` list
@@ -147,51 +88,21 @@ async function fetchByTarget(target, machine, display, forwardedArgs, os) {
  * already `--json`) so every peer returns the same slice this machine asked for.
  */
 export async function gatherRemoteList(forwardedArgs, hosts) {
-    const self = machineId();
-    const targets = [];
-    if (hosts && hosts.length > 0) {
-        // Resolve each token through the device registry so an explicit --host/--device
-        // dials the exact same address (and machine id) as the auto-discovery sweep.
-        targets.push(...await resolveExplicitTargets(hosts));
-    }
-    else {
-        let reg;
-        try {
-            reg = await loadDevices();
-        }
-        catch {
-            return { sessions: [], deviceCount: 0, unreachable: ['device registry'] };
-        }
-        for (const d of Object.values(reg)) {
-            // Live SSH-probe verdict first, cached tailscale snapshot only as a
-            // fallback — see isDialableDevice. A manually-registered device has no
-            // tailscale peer entry, so gating on `online` alone hid its sessions.
-            if (!isDialableDevice(d))
-                continue;
-            if (normalizeHost(d.name) === self)
-                continue;
-            // Control-only devices (a phone/tablet running the cockpit) drive the fleet
-            // but never run agents — never dial them, whatever their platform reads as.
-            if (isControlDevice(d))
-                continue;
-            // Only machines that can actually run the CLI. iOS/tablet nodes register as
-            // `unknown` platform and can never answer, so skip them rather than burn a
-            // full ConnectTimeout on each.
-            if (d.platform !== 'windows' && d.platform !== 'linux' && d.platform !== 'macos')
-                continue;
-            try {
-                targets.push({ target: sshTargetFor(d), machine: normalizeHost(d.name), name: d.name, os: d.platform });
-            }
-            catch {
-                // No address on the profile — nothing to dial; skip silently.
-            }
-        }
-    }
-    const results = await Promise.all(targets.map((t) => fetchByTarget(t.target, t.machine, t.name, forwardedArgs, t.os)));
+    const safeResolver = forwardedArgs.includes('--resolve-safe-v1');
+    const result = await gatherRemoteAgentsJson({
+        args: forwardedArgs,
+        noFanoutEnv: NO_FANOUT_ENV,
+        hosts,
+        parse: (stdout, machine) => parseRemoteListPayload(stdout, machine, safeResolver),
+    });
     return {
-        sessions: results.flatMap((r) => r.sessions),
-        deviceCount: targets.length,
-        unreachable: results.map((r) => r.unreachable).filter((n) => !!n),
+        sessions: result.items,
+        deviceCount: result.deviceCount,
+        unreachable: [
+            ...(result.discoveryFailed ? ['device registry'] : []),
+            ...result.skipped,
+            ...result.parseFailed,
+        ],
     };
 }
 /** Resolve a peer's SSH target (and OS) from the device registry by its

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

@@ -1,7 +1,15 @@
 /**
- * Configuration for cross-machine session sync: R2 credentials and this
- * machine's stable identity. Credentials come from the `r2.backups` secrets
- * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ * R2 credential resolution + this machine's stable identity. The only field
+ * `agents sessions export --encrypt` / `import` actually consume is the
+ * shared `R2_SYNC_ENC_KEY` transcript key (`resolveSyncEncKey`); the other R2
+ * fields (account/bucket/access keys) are validated here as a presence gate —
+ * no `r2.backups` bundle configured means no shared key, so export/import
+ * fall back to an ephemeral one. There is no R2 network client in this
+ * codebase today (it moved with the rest of the R2/CRDT background sync this
+ * bundle used to back — see git history for `./r2.ts`); a future R2-backed
+ * feature (an export destination, a fleet cache) would add one where it's
+ * actually wired. Credentials come from the `r2.backups` secrets bundle (OS
+ * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
 /** Secrets bundle holding the R2 credentials. */
 export declare const SYNC_BUNDLE = "r2.backups";
@@ -16,8 +24,8 @@ export interface R2Config {
      * Shared 32-byte key (hex or base64) for client-side transcript encryption,
      * held in the bundle as `R2_SYNC_ENC_KEY`. Optional and deliberately separate
      * from the R2 credentials so rotating the access token never orphans already
-     * encrypted objects. When absent, transcripts upload unencrypted (with a loud
-     * per-cycle warning) — see transcript-crypto.ts + pushOwn.
+     * encrypted bundles. `agents sessions export --encrypt` prefers this key when
+     * present, else mints and prints an ephemeral one — see transcript-crypto.ts.
      */
     syncEncKey?: string;
 }

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

@@ -1,7 +1,15 @@
 /**
- * Configuration for cross-machine session sync: R2 credentials and this
- * machine's stable identity. Credentials come from the `r2.backups` secrets
- * bundle (OS keychain on macOS, libsecret on Linux) — never from env or disk.
+ * R2 credential resolution + this machine's stable identity. The only field
+ * `agents sessions export --encrypt` / `import` actually consume is the
+ * shared `R2_SYNC_ENC_KEY` transcript key (`resolveSyncEncKey`); the other R2
+ * fields (account/bucket/access keys) are validated here as a presence gate —
+ * no `r2.backups` bundle configured means no shared key, so export/import
+ * fall back to an ephemeral one. There is no R2 network client in this
+ * codebase today (it moved with the rest of the R2/CRDT background sync this
+ * bundle used to back — see git history for `./r2.ts`); a future R2-backed
+ * feature (an export destination, a fleet cache) would add one where it's
+ * actually wired. Credentials come from the `r2.backups` secrets bundle (OS
+ * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
 import { readAndResolveBundleEnv, isHeadlessSecretsContext } from '../../secrets/bundles.js';
 /** Secrets bundle holding the R2 credentials. */
@@ -12,13 +20,13 @@ export const SYNC_BUNDLE = 'r2.backups';
  * without real credentials (no silent fallback).
  */
 function resolveR2Config() {
-    // The daemon monitor loop is headless by construction (no TTY, ever), so
-    // isHeadlessSecretsContext() is true here and this resolves broker-only — a
-    // broker miss can never pop an unattended Touch ID sheet on the user's screen
-    // (the same broker-only-when-headless rationale the secrets readers use). Using
-    // the shared predicate rather than a literal keeps it consistent with the other callers
-    // and lets any interactive caller of loadR2Config still prompt.
-    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'sessions-sync', agentOnly: isHeadlessSecretsContext() });
+    // A headless caller (no TTY — e.g. a routine or SSH-dispatched command) must
+    // resolve broker-only: isHeadlessSecretsContext() true means a broker miss
+    // can never pop an unattended Touch ID sheet on the user's screen (the same
+    // broker-only-when-headless rationale the secrets readers use). Using the
+    // shared predicate rather than a literal keeps it consistent with the other
+    // callers and lets any interactive caller of loadR2Config still prompt.
+    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'session-transport', agentOnly: isHeadlessSecretsContext() });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
     const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();
@@ -31,7 +39,7 @@ function resolveR2Config() {
         !secretAccessKey && 'R2_SECRET_ACCESS_KEY',
     ].filter(Boolean);
     if (missing.length > 0) {
-        throw new Error(`Sessions sync: bundle '${SYNC_BUNDLE}' is missing ${missing.join(', ')}. ` +
+        throw new Error(`Session R2 transport: bundle '${SYNC_BUNDLE}' is missing ${missing.join(', ')}. ` +
             `Add them with: agents secrets add ${SYNC_BUNDLE} <KEY>`);
     }
     return {
@@ -40,8 +48,8 @@ function resolveR2Config() {
         accessKeyId: accessKeyId,
         secretAccessKey: secretAccessKey,
         // Default to the account's R2 endpoint; an explicit R2_ENDPOINT override
-        // points sync at any S3-compatible store (MinIO, another provider) — which
-        // is also how the feature is verified end-to-end without live R2.
+        // points at any S3-compatible store (MinIO, another provider) — which is
+        // also how the feature is verified end-to-end without live R2.
         endpoint: env.R2_ENDPOINT?.trim() || `https://${accountId}.r2.cloudflarestorage.com`,
         syncEncKey,
     };