@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/lib/session/bundle.js

@@ -0,0 +1,189 @@
+/**
+ * Portable session bundle — the on-the-wire format behind `agents sessions
+ * export` / `import` (RUSH-1710 / RUSH-1711).
+ *
+ * A bundle is a self-describing NDJSON stream: the FIRST line is a
+ * {@link BundleHeader}, every subsequent line is one {@link BundleRecord} (one
+ * constituent file of a session). NDJSON — not tar — because the bundle has to
+ * pipe cleanly over `agents ssh … export --stdout | … import -` (RUSH-1712)
+ * without any external archiver on either box, stays inspectable with `head`,
+ * and lets each file body carry its own encryption envelope.
+ *
+ * This module owns the FORMAT and the import PLACEMENT only; selecting which
+ * sessions to export (which needs the session DB) lives in the export command.
+ * Placement reuses the sync mirror model verbatim: a foreign machine's session
+ * lands at {@link mirrorPath}(spec, originMachine, relKey), exactly where the
+ * cross-machine sync writes it — so the existing scanner indexes it as a
+ * machine-tagged row and "local always wins" falls out of the scanner's
+ * live-home-first dedup with no extra logic here.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+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;
+/** 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);
+}
+/** True when an agent's sessions can be represented in a bundle (has a sync spec). */
+export function isExportableAgent(agentId) {
+    return specForAgent(agentId) !== undefined;
+}
+/**
+ * Read one file and turn it into a bundle record. The hash and size are always
+ * computed over the PLAINTEXT (post-redaction) body, so they equal what lands on
+ * disk after import — keeping dedup byte-exact whether or not the bundle is
+ * encrypted.
+ */
+export function buildRecord(file, opts) {
+    let body = fs.readFileSync(file.absPath, 'utf-8');
+    if (opts.redact)
+        body = redactSecrets(body);
+    const hash = hashContent(body);
+    const size = Buffer.byteLength(body, 'utf-8');
+    let stored = body;
+    let encrypted = false;
+    if (opts.encryptKey) {
+        stored = encryptTranscript(body, opts.encryptKey);
+        encrypted = true;
+    }
+    const rec = {
+        agent: file.agent,
+        machine: file.machine,
+        sessionId: file.sessionId,
+        relKey: file.relKey,
+        size,
+        hash,
+        encrypted,
+        body: stored,
+    };
+    if (file.label)
+        rec.label = file.label;
+    return rec;
+}
+/** Build the header for a set of records. */
+export function makeHeader(args) {
+    const sessions = new Set(args.records.map(r => `${r.agent}:${r.machine}:${r.sessionId}`)).size;
+    return {
+        kind: BUNDLE_KIND,
+        version: BUNDLE_VERSION,
+        exportedAt: args.exportedAt,
+        origin: args.origin,
+        encrypted: args.encrypted,
+        redacted: args.redacted,
+        count: args.records.length,
+        sessions,
+    };
+}
+/**
+ * Merge record sets from several bundles (e.g. a fan-out pull across hosts),
+ * deduping by agent + origin machine + session + file so the same session seen
+ * from two peers lands once. First occurrence wins.
+ */
+export function mergeRecords(sets) {
+    const seen = new Set();
+    const out = [];
+    for (const set of sets) {
+        for (const r of set) {
+            const key = `${r.agent}:${r.machine}:${r.sessionId}:${r.relKey}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(r);
+        }
+    }
+    return out;
+}
+/** Serialize a bundle to its NDJSON wire form (header line + one line per record). */
+export function serializeBundle(header, records) {
+    const lines = [JSON.stringify(header)];
+    for (const r of records)
+        lines.push(JSON.stringify(r));
+    return lines.join('\n') + '\n';
+}
+/** Parse an NDJSON bundle, validating the header kind + version. Throws on malformed input. */
+export function parseBundle(text) {
+    const lines = text.split('\n').filter(l => l.trim().length > 0);
+    if (lines.length === 0)
+        throw new Error('Empty session bundle.');
+    let header;
+    try {
+        header = JSON.parse(lines[0]);
+    }
+    catch {
+        throw new Error('Malformed session bundle: first line is not JSON.');
+    }
+    if (!header || header.kind !== BUNDLE_KIND) {
+        throw new Error(`Not an agents session bundle (kind=${header?.kind ?? 'missing'}).`);
+    }
+    if (header.version !== BUNDLE_VERSION) {
+        throw new Error(`Unsupported bundle version ${header.version} — this CLI reads v${BUNDLE_VERSION}.`);
+    }
+    const records = [];
+    for (let i = 1; i < lines.length; i++) {
+        try {
+            records.push(JSON.parse(lines[i]));
+        }
+        catch {
+            throw new Error(`Malformed session bundle: record on line ${i + 1} is not JSON.`);
+        }
+    }
+    return { header, records };
+}
+/**
+ * Compute where each record lands and whether it duplicates / conflicts with an
+ * existing file. Pure w.r.t. the filesystem it reads (no writes). Dedup is
+ * byte-exact: a target that already holds an identical body is `dup`; a target
+ * that holds a DIFFERENT body is `conflict` (only overwritten with --overwrite).
+ * An agent with no sync spec is `unknown` and never placed.
+ */
+export function planImport(bundle, opts) {
+    return bundle.records.map((record) => {
+        const spec = specForAgent(record.agent);
+        if (!spec)
+            return { record, targetPath: '', status: 'unknown' };
+        const body = decryptTranscriptBody(record.body, opts.decryptKey);
+        const bodyHash = hashContent(body);
+        const targetPath = mirrorPath(spec, record.machine, record.relKey);
+        let status = 'new';
+        if (fs.existsSync(targetPath)) {
+            const existing = fs.readFileSync(targetPath, 'utf-8');
+            status = hashContent(existing) === bodyHash ? 'dup' : 'conflict';
+        }
+        return { record, targetPath, status };
+    });
+}
+/**
+ * Materialize a plan to disk. `dup` records are always skipped (local wins);
+ * `conflict` records are replaced only when `overwrite` is set; `unknown` records
+ * are counted and skipped.
+ */
+export function writeImport(plan, opts) {
+    const res = { placed: 0, skipped: 0, overwritten: 0, conflicts: 0, unknown: 0 };
+    for (const item of plan) {
+        if (item.status === 'unknown') {
+            res.unknown++;
+            continue;
+        }
+        if (item.status === 'dup') {
+            res.skipped++;
+            continue;
+        }
+        if (item.status === 'conflict' && !opts.overwrite) {
+            res.conflicts++;
+            continue;
+        }
+        const body = decryptTranscriptBody(item.record.body, opts.decryptKey);
+        fs.mkdirSync(path.dirname(item.targetPath), { recursive: true });
+        fs.writeFileSync(item.targetPath, body, 'utf-8');
+        if (item.status === 'conflict')
+            res.overwritten++;
+        else
+            res.placed++;
+    }
+    return res;
+}

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

@@ -0,0 +1,12 @@
+import { type ParsedBundle } from './bundle.js';
+export interface RemotePullResult {
+    bundles: ParsedBundle[];
+    errors: string[];
+}
+/**
+ * Run `agents sessions export …exportArgs --stdout` on each host and parse the
+ * streamed bundle. A host that fails (unreachable, remote error, bad output) is
+ * collected in `errors` and skipped — one asleep peer never aborts the pull.
+ * `exportArgs` must NOT contain --host (the remote export runs for itself only).
+ */
+export declare function pullBundlesFromHosts(hosts: string[], exportArgs: string[]): Promise<RemotePullResult>;

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

@@ -0,0 +1,61 @@
+/**
+ * Multi-device session transfer over the EXISTING SSH fleet transport
+ * (RUSH-1712) — no R2, no daemon. `agents sessions export --host <h>` and
+ * `agents sessions import --from-host <h>` both run `agents sessions export
+ * … --stdout` ON the peer and stream the bundle back over the same SSH path the
+ * cross-machine listing already uses (resolveExplicitTargets + ssh-exec), then
+ * either write it (export) or import it (import) locally.
+ *
+ * This deliberately reuses ssh-exec / resolve-target rather than adding a second
+ * transport: the raw form `agents ssh boxA 'agents sessions export --stdout' |
+ * agents sessions import -` works with plain export/import; this module is just
+ * the one-shot wrapper around it.
+ */
+import chalk from 'chalk';
+import { sshExec } from '../ssh-exec.js';
+import { shellQuote } from '../ssh-exec.js';
+import { resolveExplicitTargets } from '../devices/resolve-target.js';
+import { remoteShellFor, buildWindowsAgentsCommand } from '../hosts/remote-cmd.js';
+import { parseBundle } from './bundle.js';
+/** Remote export can traverse many sessions; give it a generous ceiling. */
+const REMOTE_EXPORT_TIMEOUT_MS = 300_000;
+/** Build `agents <args>` for the peer's login shell (bash or PowerShell). */
+function remoteAgentsCommand(args, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({ args });
+    }
+    const inner = ['agents', ...args].map((t, i) => (i === 0 ? t : shellQuote(t))).join(' ');
+    return `bash -lc ${shellQuote(inner)}`;
+}
+/**
+ * Run `agents sessions export …exportArgs --stdout` on each host and parse the
+ * streamed bundle. A host that fails (unreachable, remote error, bad output) is
+ * collected in `errors` and skipped — one asleep peer never aborts the pull.
+ * `exportArgs` must NOT contain --host (the remote export runs for itself only).
+ */
+export async function pullBundlesFromHosts(hosts, exportArgs) {
+    const targets = await resolveExplicitTargets(hosts);
+    const bundles = [];
+    const errors = [];
+    for (const t of targets) {
+        const cmd = remoteAgentsCommand(['sessions', 'export', ...exportArgs, '--stdout'], t.os);
+        process.stderr.write(chalk.dim(`Pulling sessions from ${t.name}…\n`));
+        const res = sshExec(t.target, cmd, { timeoutMs: REMOTE_EXPORT_TIMEOUT_MS });
+        if (res.timedOut) {
+            errors.push(`${t.name}: timed out after ${Math.round(REMOTE_EXPORT_TIMEOUT_MS / 1000)}s`);
+            continue;
+        }
+        if (res.code !== 0) {
+            const tail = res.stderr.trim().split('\n').filter(Boolean).pop();
+            errors.push(`${t.name}: remote export failed (${res.code ?? 'ssh error'})${tail ? ': ' + tail : ''}`);
+            continue;
+        }
+        try {
+            bundles.push(parseBundle(res.stdout));
+        }
+        catch (err) {
+            errors.push(`${t.name}: ${err.message}`);
+        }
+    }
+    return { bundles, errors };
+}

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

@@ -12,21 +12,54 @@
  * also exists locally always wins — the mirror only ever fills in sessions
  * originated on other machines.
  */
-export interface LocalTranscript {
+/** One constituent file of a session — a session has exactly one for file-shaped
+ *  agents (Claude, Codex, …), and many for directory-shaped ones (Kimi). */
+export interface SessionFile {
     /** Absolute path on this machine. */
     absPath: string;
-    /** Globally-unique session id (the grouping key across machines). */
-    sessionId: string;
     /** Path relative to the agent's subdir root — preserved in the mirror layout. */
     relKey: string;
 }
+export interface LocalTranscript {
+    /** Globally-unique session id (the grouping key across machines). */
+    sessionId: string;
+    /** Every file that makes up this session. Length 1 for file-shaped agents. */
+    files: SessionFile[];
+}
 export interface SyncAgentSpec {
     id: string;
     /** Config subdir under the agent home that holds transcripts. */
     subdir: string;
+    /** File extension to walk for this agent (defaults to .jsonl). */
+    ext?: string;
+    /**
+     * A session is a DIRECTORY of files (e.g. Kimi: state.json + agents/…/wire.jsonl
+     * + per-tool task sidecars), not a single transcript. When set, every file under
+     * the session dir (matching `exts`, passing `fileFilter`) syncs, is stored under
+     * its own R2 sub-key, and is mirrored at its own relative path — instead of the
+     * file-shaped "one transcript per session" model.
+     */
+    dirShaped?: boolean;
+    /** Extensions a dir-shaped agent walks (defaults to `[ext ?? '.jsonl']`). */
+    exts?: string[];
+    /** Optional per-file exclusion for dir-shaped agents (lock/scratch files, …). */
+    fileFilter?(relKey: string): boolean;
+    /**
+     * Extensions whose files are append-only event logs and therefore CRDT-mergeable
+     * (G-Set union across forked copies). A dir-shaped session usually mixes an
+     * append-only conversation log (`wire.jsonl`) with mutable metadata blobs
+     * (`state.json`) — line-unioning the latter would corrupt it, so any file NOT
+     * matching an entry here is reconciled last-writer-wins instead. Undefined (the
+     * file-shaped default) means every file is mergeable — the single `.jsonl`
+     * transcript keeps its existing union behaviour.
+     */
+    mergeableExts?: string[];
     /** Derive the session id from a storage-relative key. */
     sessionIdFromRelKey(relKey: string): string;
 }
+/** True when a file at `relKey` is an append-only log that CRDT-unions across
+ *  forks; false when it must be reconciled last-writer-wins (mutable blob). */
+export declare function isMergeableFile(spec: SyncAgentSpec, relKey: string): boolean;
 export declare const SYNC_AGENTS: SyncAgentSpec[];
 /**
  * List this machine's own transcript files for an agent, EXCLUDING the sync
@@ -36,10 +69,27 @@ export declare const SYNC_AGENTS: SyncAgentSpec[];
 export declare function listLocalTranscripts(spec: SyncAgentSpec): LocalTranscript[];
 /** Session ids this machine holds locally (live home), used to skip mirror writes. */
 export declare function localSessionIds(spec: SyncAgentSpec): Set<string>;
-/** Absolute mirror path for a remote machine's transcript — lands in a scan root. */
+/**
+ * Absolute mirror path for a remote machine's transcript — lands in a scan root.
+ *
+ * `machine` and `relKey` come from a peer's manifest (untrusted: any peer with
+ * write access to the shared bucket controls them). Unlike the push side, which
+ * already drops `relKey` starting with `..` when building the manifest, the pull
+ * side would otherwise `fs.writeFileSync` at this path with peer-controlled
+ * content. `machine` is constrained to a single segment and `relKey` (which may
+ * legitimately nest, e.g. `projects/x/y.jsonl`) is contained beneath the
+ * per-machine mirror root, so a crafted `relKey` like `../../../.ssh/authorized_keys`
+ * cannot write outside `~/.agents/.history/backups/<agent>/<machine>/<subdir>`.
+ */
 export declare function mirrorPath(spec: SyncAgentSpec, machine: string, relKey: string): string;
-/** R2 object key for a transcript: sessions/<machine>/<agent>/<sessionId>.jsonl */
-export declare function objectKey(machine: string, agentId: string, sessionId: string): string;
+/**
+ * R2 object key for a transcript.
+ *  - file-shaped (relKey omitted): sessions/<machine>/<agent>/<sessionId>.jsonl —
+ *    unchanged, so existing claude/codex/droid objects keep their keys.
+ *  - dir-shaped (relKey given): sessions/<machine>/<agent>/<sessionId>/<relKey> —
+ *    one object per constituent file of the session directory.
+ */
+export declare function objectKey(machine: string, agentId: string, sessionId: string, relKey?: string): string;
 /** R2 object key for a machine's manifest. */
 export declare function manifestKey(machine: string): string;
 /** Prefix under which all machine manifests live (for discovery). */

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

@@ -12,6 +12,14 @@ export interface R2Config {
     secretAccessKey: string;
     /** S3-compatible endpoint for the account (no bucket, no trailing slash). */
     endpoint: string;
+    /**
+     * 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.
+     */
+    syncEncKey?: string;
 }
 /** Window after a prompt-bearing resolution failure during which we skip
  *  re-attempting (and thus re-prompting). SIGHUP / restart bypasses it. */

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

@@ -17,6 +17,7 @@ function resolveR2Config() {
     const bucket = env.R2_BUCKET_NAME?.trim();
     const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();
     const secretAccessKey = env.R2_SECRET_ACCESS_KEY?.trim();
+    const syncEncKey = env.R2_SYNC_ENC_KEY?.trim() || undefined;
     const missing = [
         !accountId && 'R2_ACCOUNT_ID',
         !bucket && 'R2_BUCKET_NAME',
@@ -32,7 +33,11 @@ function resolveR2Config() {
         bucket: bucket,
         accessKeyId: accessKeyId,
         secretAccessKey: secretAccessKey,
-        endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+        // 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.
+        endpoint: env.R2_ENDPOINT?.trim() || `https://${accountId}.r2.cloudflarestorage.com`,
+        syncEncKey,
     };
 }
 // ── Resolution cache ────────────────────────────────────────────────────────

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

@@ -18,12 +18,23 @@ export interface ManifestEntry {
     /** Latest event timestamp in the transcript. */
     lastTs: string;
 }
-/** sessionId -> entry */
-export type AgentManifest = Record<string, ManifestEntry>;
+/**
+ * sessionId -> the session's file entries.
+ *  - file-shaped agents (claude/codex/droid) store a single `ManifestEntry`,
+ *    byte-identical to the pre-multi-file format, so a machine on an older CLI
+ *    reads them unchanged.
+ *  - dir-shaped agents (kimi) store a `ManifestEntry[]`, one per constituent file.
+ *    A machine that predates multi-file support skips these (an unknown agent is
+ *    skipped whole; a kimi-aware-but-file-shaped reader fails to find the flat
+ *    object key and simply retries — it never crashes or corrupts).
+ */
+export type AgentManifest = Record<string, ManifestEntry | ManifestEntry[]>;
+/** Normalize a manifest value to its file-entry list (single entry -> length-1). */
+export declare function manifestEntries(value: ManifestEntry | ManifestEntry[]): ManifestEntry[];
 export interface Manifest {
     machine: string;
     updatedAt: string;
-    /** agentId -> (sessionId -> entry) */
+    /** agentId -> (sessionId -> entry | entry[]) */
     agents: Record<string, AgentManifest>;
 }
 export declare function emptyManifest(machine: string, updatedAt: string): Manifest;

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

@@ -13,6 +13,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { getCacheDir } from '../../state.js';
+/** Normalize a manifest value to its file-entry list (single entry -> length-1). */
+export function manifestEntries(value) {
+    return Array.isArray(value) ? value : [value];
+}
 export function emptyManifest(machine, updatedAt) {
     return { machine, updatedAt, agents: {} };
 }

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

@@ -0,0 +1,49 @@
+/**
+ * Provisioning for cross-machine session sync: write the `r2.backups` secrets
+ * bundle and probe R2 connectivity. Pure logic — no prompts, no Commander — so
+ * it is unit-testable against the in-memory keychain seam. The interactive flow
+ * that collects the values lives in the command layer
+ * (`commands/sync-provision.ts`).
+ */
+/** Values a caller has already collected for the sync bundle. */
+export interface ProvisionInput {
+    accountId: string;
+    bucketName: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** Optional S3 endpoint override (MinIO / non-R2). Default derived from accountId. */
+    endpoint?: string;
+    /**
+     * Shared transcript-encryption key for a machine JOINING an existing fabric —
+     * paste the key the first machine generated. Omit on the first machine to mint
+     * a fresh one. Ignored if the bundle already carries a key (never overwritten).
+     */
+    encKey?: string;
+}
+export type EncKeyAction = 'generated' | 'reused' | 'provided';
+/**
+ * Create or update the `r2.backups` bundle from already-collected values.
+ *
+ * The four R2 credentials are always (over)written. The encryption key is
+ * handled carefully: an existing key is REUSED, never overwritten (overwriting
+ * would orphan every transcript peers already encrypted under it); otherwise a
+ * caller-supplied `encKey` is stored, or a fresh one minted on the first machine.
+ */
+export declare function writeSyncBundle(input: ProvisionInput): {
+    encKeyAction: EncKeyAction;
+};
+/** The shared encryption key currently stored (for display when handing it to peers). */
+export declare function readStoredEncKey(): string | null;
+/**
+ * Prove the configured bundle can read AND write its bucket: put a throwaway
+ * object, read it back, delete it. Returns a structured result instead of
+ * throwing so the caller (setup) never crashes on a bad credential. The probe
+ * key lives OUTSIDE the `sessions/` prefix so it can never be mistaken for a
+ * machine manifest by the pull path.
+ */
+export declare function probeR2Connectivity(): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}>;

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

@@ -0,0 +1,91 @@
+/**
+ * Provisioning for cross-machine session sync: write the `r2.backups` secrets
+ * bundle and probe R2 connectivity. Pure logic — no prompts, no Commander — so
+ * it is unit-testable against the in-memory keychain seam. The interactive flow
+ * that collects the values lives in the command layer
+ * (`commands/sync-provision.ts`).
+ */
+import { bundleExists, readBundle, writeBundle, bundleItemStore, keychainRef, } from '../../secrets/bundles.js';
+import { secretsKeychainItem } from '../../secrets/index.js';
+import { SYNC_BUNDLE, loadR2Config, clearR2ConfigCache } from './config.js';
+import { R2Client } from './r2.js';
+import { generateSyncEncKey, resolveSyncEncKey } from './transcript-crypto.js';
+import { machineId } from '../../machine-id.js';
+/**
+ * Create or update the `r2.backups` bundle from already-collected values.
+ *
+ * The four R2 credentials are always (over)written. The encryption key is
+ * handled carefully: an existing key is REUSED, never overwritten (overwriting
+ * would orphan every transcript peers already encrypted under it); otherwise a
+ * caller-supplied `encKey` is stored, or a fresh one minted on the first machine.
+ */
+export function writeSyncBundle(input) {
+    // Validate a joining machine's pasted key up front so a bad paste fails here,
+    // not silently at the next sync.
+    if (input.encKey)
+        resolveSyncEncKey({ syncEncKey: input.encKey });
+    const bundle = bundleExists(SYNC_BUNDLE)
+        ? readBundle(SYNC_BUNDLE)
+        : { name: SYNC_BUNDLE, description: 'Cross-machine session-sync R2 credentials', vars: {} };
+    const store = bundleItemStore(bundle.backend);
+    const setKey = (key, value) => {
+        store.set(secretsKeychainItem(SYNC_BUNDLE, key), value);
+        bundle.vars[key] = keychainRef(key);
+    };
+    setKey('R2_ACCOUNT_ID', input.accountId);
+    setKey('R2_BUCKET_NAME', input.bucketName);
+    setKey('R2_ACCESS_KEY_ID', input.accessKeyId);
+    setKey('R2_SECRET_ACCESS_KEY', input.secretAccessKey);
+    if (input.endpoint)
+        setKey('R2_ENDPOINT', input.endpoint);
+    let encKeyAction;
+    if (bundle.vars['R2_SYNC_ENC_KEY']) {
+        encKeyAction = 'reused';
+    }
+    else if (input.encKey) {
+        setKey('R2_SYNC_ENC_KEY', input.encKey);
+        encKeyAction = 'provided';
+    }
+    else {
+        setKey('R2_SYNC_ENC_KEY', generateSyncEncKey());
+        encKeyAction = 'generated';
+    }
+    writeBundle(bundle);
+    clearR2ConfigCache(); // so the next loadR2Config() sees the just-written values
+    return { encKeyAction };
+}
+/** The shared encryption key currently stored (for display when handing it to peers). */
+export function readStoredEncKey() {
+    clearR2ConfigCache();
+    try {
+        return loadR2Config().syncEncKey ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Prove the configured bundle can read AND write its bucket: put a throwaway
+ * object, read it back, delete it. Returns a structured result instead of
+ * throwing so the caller (setup) never crashes on a bad credential. The probe
+ * key lives OUTSIDE the `sessions/` prefix so it can never be mistaken for a
+ * machine manifest by the pull path.
+ */
+export async function probeR2Connectivity() {
+    try {
+        clearR2ConfigCache();
+        const cfg = loadR2Config();
+        const r2 = new R2Client(cfg);
+        const key = `.agents-provision-probe/${machineId()}.txt`;
+        const token = `agents-sync-probe-${machineId()}`;
+        await r2.put(key, token, 'text/plain');
+        const got = await r2.get(key);
+        await r2.delete(key);
+        if (got !== token)
+            return { ok: false, error: 'wrote a probe object but read back different bytes' };
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err.message };
+    }
+}

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

@@ -24,6 +24,9 @@ export interface SyncResult {
     merged: number;
     pullSkipped: number;
     errors: string[];
+    /** Non-fatal advisories (e.g. transcripts uploaded unencrypted). Unlike
+     *  `errors` these do not set a failing exit code. */
+    warnings: string[];
 }
 export interface SyncOptions {
     verbose?: boolean;
@@ -52,10 +55,31 @@ export interface PendingSession {
  */
 export declare function selectSessionsToFetch(copies: Map<string, Map<string, RemoteCopy[]>>, localIdsByAgent: Map<string, Set<string>>, pullState: PullState): PendingSession[];
 /**
- * Resolve the mirror destination + merged content for one session. Pure.
+ * Resolve the mirror destination + reconciled content for ONE file across its
+ * copies (every copy here is the same file — same relKey — held by a different
+ * machine). Pure.
+ *
  * The canonical path comes from the lexicographically-smallest machine so every
- * puller derives an identical location; the content is the CRDT union of copies.
+ * puller derives an identical location. The content depends on the file's kind
+ * (see `isMergeableFile`):
+ *  - append-only logs (a transcript `.jsonl`) take the CRDT G-Set union — every
+ *    machine converges to byte-identical output regardless of order.
+ *  - mutable blobs (Kimi `state.json`) can't be line-unioned without corruption,
+ *    so they resolve **last-writer-wins**: the copy with the latest event
+ *    timestamp, tie-broken by content hash so the pick is deterministic fleet-wide.
+ */
+/**
+ * The `lastTs` a manifest entry carries for one file. Append-only logs (a
+ * conversation `.jsonl`) embed per-line event timestamps, so their recency is
+ * the latest line timestamp (`transcriptStats`). Mutable blobs (Kimi
+ * `state.json`, the per-tool `tasks/*.json` sidecars) carry no event timestamp —
+ * their own `updatedAt`/`createdAt` fields are agent-specific and unreliable — so
+ * their "last written" signal is the file mtime. Without this, `transcriptStats`
+ * returns `''` for every blob and the last-writer-wins branch in
+ * `resolveMirrorWrite` silently degrades to "highest-hash-wins", which can pick a
+ * stale copy over the genuinely newer one.
  */
+export declare function deriveLastTs(spec: SyncAgentSpec, relKey: string, content: string, mtimeMs: number): string;
 export declare function resolveMirrorWrite(spec: SyncAgentSpec, copies: RemoteCopy[], contents: string[]): {
     dest: string;
     content: string;