@phnx-labs/agents-cli 1.20.62 → 1.20.64

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

@@ -18,55 +18,83 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { R2Client } from './r2.js';
 import { loadR2Config, machineId } from './config.js';
-import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, SESSIONS_PREFIX, } from './agents.js';
+import { SYNC_AGENTS, listLocalTranscripts, localSessionIds, mirrorPath, objectKey, manifestKey, isMergeableFile, SESSIONS_PREFIX, } from './agents.js';
 import { mergeTranscripts, transcriptStats } from './crdt.js';
-import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, } from './manifest.js';
+import { resolveSyncEncKey, encryptTranscript, decryptTranscriptBody } from './transcript-crypto.js';
+import { emptyManifest, parseManifest, hashContent, loadLedger, saveLedger, ledgerUnchanged, ledgerRecord, loadLocalManifest, saveLocalManifest, loadPullState, savePullState, sourceSignature, manifestEntries, } from './manifest.js';
 const nowIso = () => new Date().toISOString();
 function specById(id) {
     return SYNC_AGENTS.find(s => s.id === id);
 }
 /** Upload this machine's changed transcripts and publish its manifest. */
-async function pushOwn(r2, me, opts, result) {
+async function pushOwn(r2, me, encKey, opts, result) {
     const ledger = loadLedger();
     const prev = loadLocalManifest();
     const manifest = emptyManifest(me, nowIso());
+    // The transcript body is sealed client-side before it leaves the machine
+    // (AES-256-GCM under the shared bundle key). Without a key we still upload —
+    // the feature predates encryption — but flag it LOUDLY once per cycle so an
+    // unencrypted upload never happens silently.
+    if (!encKey) {
+        result.warnings.push(`R2_SYNC_ENC_KEY not set in the r2.backups bundle — transcripts are uploaded UNENCRYPTED ` +
+            `(readable by anyone with bucket access). Add the shared key to enable client-side encryption.`);
+    }
     for (const spec of SYNC_AGENTS) {
         const agentManifest = {};
         for (const t of listLocalTranscripts(spec)) {
-            let stat;
-            try {
-                stat = fs.statSync(t.absPath);
-            }
-            catch {
-                continue;
-            }
-            const prevEntry = prev?.agents?.[spec.id]?.[t.sessionId];
-            if (prevEntry && ledgerUnchanged(ledger, t.absPath, stat.size, stat.mtimeMs)) {
-                agentManifest[t.sessionId] = prevEntry; // unchanged: reuse, no read, no upload
-                result.pushSkipped++;
-                continue;
-            }
-            let content;
-            try {
-                content = fs.readFileSync(t.absPath, 'utf-8');
-            }
-            catch {
-                continue;
-            }
-            const hash = hashContent(content);
-            const { lastTs } = transcriptStats(content);
-            const entry = { relKey: t.relKey, size: stat.size, hash, lastTs };
-            try {
-                await r2.put(objectKey(me, spec.id, t.sessionId), content, 'application/x-ndjson');
-                ledgerRecord(ledger, t.absPath, stat.size, stat.mtimeMs, hash);
-                agentManifest[t.sessionId] = entry;
-                result.pushed++;
-                if (opts.verbose)
-                    opts.log?.(`  push ${spec.id}/${t.sessionId.slice(0, 8)} (${stat.size}B)`);
-            }
-            catch (err) {
-                result.errors.push(`push ${spec.id}/${t.sessionId}: ${err.message}`);
+            // A session is one file (file-shaped) or many (dir-shaped). Push each file
+            // that changed, reusing the prior manifest entry (keyed by relKey) for the
+            // ones the ledger shows unchanged. Object keys nest under the session id for
+            // dir-shaped agents and stay flat for file-shaped ones (unchanged keys).
+            const prevVal = prev?.agents?.[spec.id]?.[t.sessionId];
+            const prevByRel = new Map((prevVal ? manifestEntries(prevVal) : []).map(e => [e.relKey, e]));
+            const entries = [];
+            for (const f of t.files) {
+                let stat;
+                try {
+                    stat = fs.statSync(f.absPath);
+                }
+                catch {
+                    continue;
+                }
+                const prevEntry = prevByRel.get(f.relKey);
+                if (prevEntry && ledgerUnchanged(ledger, f.absPath, stat.size, stat.mtimeMs)) {
+                    entries.push(prevEntry); // unchanged: reuse, no read, no upload
+                    result.pushSkipped++;
+                    continue;
+                }
+                let content;
+                try {
+                    content = fs.readFileSync(f.absPath, 'utf-8');
+                }
+                catch {
+                    continue;
+                }
+                // Identity for CRDT merge is the PLAINTEXT hash (ciphertext is
+                // non-deterministic), so hash + manifest are computed on cleartext; only
+                // the stored object body is sealed.
+                const hash = hashContent(content);
+                const lastTs = deriveLastTs(spec, f.relKey, content, stat.mtimeMs);
+                const entry = { relKey: f.relKey, size: stat.size, hash, lastTs };
+                const body = encKey ? encryptTranscript(content, encKey) : content;
+                const contentType = encKey ? 'application/json' : 'application/x-ndjson';
+                try {
+                    await r2.put(objectKey(me, spec.id, t.sessionId, spec.dirShaped ? f.relKey : undefined), body, contentType);
+                    ledgerRecord(ledger, f.absPath, stat.size, stat.mtimeMs, hash);
+                    entries.push(entry);
+                    result.pushed++;
+                    const label = spec.dirShaped ? `${t.sessionId.slice(0, 8)}/${f.relKey}` : t.sessionId.slice(0, 8);
+                    if (opts.verbose)
+                        opts.log?.(`  push ${spec.id}/${label} (${stat.size}B)`);
+                }
+                catch (err) {
+                    result.errors.push(`push ${spec.id}/${t.sessionId}/${f.relKey}: ${err.message}`);
+                }
             }
+            // File-shaped: store the single entry (byte-identical to the old format so
+            // older CLIs read it unchanged). Dir-shaped: store the per-file array.
+            if (entries.length > 0)
+                agentManifest[t.sessionId] = spec.dirShaped ? entries : entries[0];
         }
         if (Object.keys(agentManifest).length > 0)
             manifest.agents[spec.id] = agentManifest;
@@ -101,17 +129,60 @@ export function selectSessionsToFetch(copies, localIdsByAgent, pullState) {
     return pending;
 }
 /**
- * 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 function deriveLastTs(spec, relKey, content, mtimeMs) {
+    if (isMergeableFile(spec, relKey))
+        return transcriptStats(content).lastTs;
+    return new Date(mtimeMs).toISOString();
+}
 export function resolveMirrorWrite(spec, copies, contents) {
     const canonical = [...copies].sort((a, b) => (a.machine < b.machine ? -1 : a.machine > b.machine ? 1 : 0))[0];
-    const content = contents.length === 1 ? contents[0] : mergeTranscripts(contents);
+    let content;
+    if (contents.length === 1) {
+        content = contents[0];
+    }
+    else if (isMergeableFile(spec, canonical.entry.relKey)) {
+        content = mergeTranscripts(contents);
+    }
+    else {
+        // Last-writer-wins: highest (lastTs, hash) among the copies.
+        let win = 0;
+        for (let i = 1; i < copies.length; i++) {
+            const a = copies[i].entry, b = copies[win].entry;
+            if (a.lastTs > b.lastTs || (a.lastTs === b.lastTs && a.hash > b.hash))
+                win = i;
+        }
+        content = contents[win];
+    }
     return {
         dest: mirrorPath(spec, canonical.machine, canonical.entry.relKey),
         content,
-        merged: contents.length > 1,
+        // "merged" means an actual CRDT line-union happened — not a last-writer-wins
+        // pick of one mutable blob over another (that discards a copy, it doesn't merge).
+        merged: contents.length > 1 && isMergeableFile(spec, canonical.entry.relKey),
     };
 }
 /**
@@ -138,7 +209,7 @@ export function reconcileCopies(spec, copies, fetched) {
     return resolveMirrorWrite(spec, copies, contents);
 }
 /** Fetch other machines' manifests, union changed sessions into the mirror. */
-async function pullAndReconcile(r2, me, opts, result) {
+async function pullAndReconcile(r2, me, encKey, opts, result) {
     const prefixes = await r2.listPrefixes(SESSIONS_PREFIX); // sessions/<machine>/
     const machines = prefixes
         .map(p => p.slice(SESSIONS_PREFIX.length).replace(/\/$/, ''))
@@ -162,9 +233,13 @@ async function pullAndReconcile(r2, me, opts, result) {
             let byAgent = copies.get(agentId);
             if (!byAgent)
                 copies.set(agentId, (byAgent = new Map()));
-            for (const [sessionId, entry] of Object.entries(sessions)) {
+            for (const [sessionId, value] of Object.entries(sessions)) {
                 const list = byAgent.get(sessionId) ?? [];
-                list.push({ machine: m, entry });
+                // One RemoteCopy per (machine, file): file-shaped sessions contribute one,
+                // dir-shaped ones contribute an entry per constituent file. `manifestEntries`
+                // also normalizes a single-object entry written by an older CLI.
+                for (const entry of manifestEntries(value))
+                    list.push({ machine: m, entry });
                 byAgent.set(sessionId, list);
             }
         }
@@ -183,39 +258,85 @@ async function pullAndReconcile(r2, me, opts, result) {
     result.pullSkipped += candidates - pending.length; // local-owned or unchanged
     for (const { agentId, sessionId, copies: list, sig } of pending) {
         const spec = specById(agentId);
-        // Download each copy (could be a fork across >1 machine), keeping the
-        // result positionally aligned to `list` — null marks a copy we couldn't
-        // fetch this tick (404 / consistency lag / error).
-        const fetched = [];
+        // A dir-shaped session spans several files; reconcile each file independently
+        // (its copies across machines share one relKey). File-shaped sessions have a
+        // single group, so this collapses to the original one-file path.
+        const byRel = new Map();
         for (const c of list) {
-            try {
-                fetched.push(await r2.get(objectKey(c.machine, agentId, sessionId)));
-            }
-            catch (err) {
-                result.errors.push(`get ${c.machine}/${sessionId}: ${err.message}`);
-                fetched.push(null);
+            const g = byRel.get(c.entry.relKey);
+            if (g)
+                g.push(c);
+            else
+                byRel.set(c.entry.relKey, [c]);
+        }
+        // Resolve every file's write before touching disk. If ANY file's fetch is
+        // incomplete (a copy 404s / consistency lag), abandon the WHOLE session this
+        // tick — no writes, no pull-state stamp — so it retries intact next time
+        // rather than materializing half a session and stamping it done.
+        const writes = [];
+        let incomplete = false;
+        try {
+            for (const group of byRel.values()) {
+                const fetched = [];
+                for (const c of group) {
+                    try {
+                        const body = await r2.get(objectKey(c.machine, agentId, sessionId, spec.dirShaped ? c.entry.relKey : undefined));
+                        // Decrypt before the body reaches the CRDT union — merge + mirror always
+                        // operate on plaintext. A legacy plaintext object passes through
+                        // untouched; an envelope without a key throws (surfaced below).
+                        fetched.push(body === null ? null : decryptTranscriptBody(body, encKey));
+                    }
+                    catch (err) {
+                        result.errors.push(`get ${c.machine}/${sessionId}/${c.entry.relKey}: ${err.message}`);
+                        fetched.push(null);
+                    }
+                }
+                const resolved = reconcileCopies(spec, group, fetched);
+                if (!resolved) {
+                    incomplete = true;
+                    break;
+                }
+                writes.push(resolved);
             }
         }
-        // null ⇒ an incomplete fetch: skip the write AND the pull-state stamp so we
-        // retry next tick instead of persisting a partial union / abandoning a branch.
-        const resolved = reconcileCopies(spec, list, fetched);
-        if (!resolved)
+        catch (err) {
+            // `reconcileCopies` -> `mirrorPath` now rejects unsafe peer-controlled
+            // machine/relKey (C1 containment). That rejection must stay scoped to this
+            // one session: without this catch a single malicious/malformed manifest
+            // entry would throw out of the whole `pending` loop, skip the
+            // `savePullState` below, and re-throw every tick — a peer-triggered DoS on
+            // everyone else's session-sync. Record it and skip; never stamp pull-state
+            // for a rejected entry (so nothing marks the bad session "done").
+            result.errors.push(`resolve mirror ${agentId}/${sessionId}: ${err.message}`);
             continue;
-        const { dest, content, merged } = resolved;
+        }
+        if (incomplete)
+            continue; // retry next tick, session intact
         try {
-            let existing = null;
-            try {
-                existing = fs.readFileSync(dest, 'utf-8');
+            let changed = false;
+            let mergedAny = false;
+            for (const { dest, content, merged } of writes) {
+                let existing = null;
+                try {
+                    existing = fs.readFileSync(dest, 'utf-8');
+                }
+                catch { /* not present yet */ }
+                if (existing !== content) {
+                    fs.mkdirSync(path.dirname(dest), { recursive: true });
+                    fs.writeFileSync(dest, content, 'utf-8');
+                    changed = true;
+                    if (merged)
+                        mergedAny = true;
+                }
             }
-            catch { /* not present yet */ }
-            if (existing !== content) {
-                fs.mkdirSync(path.dirname(dest), { recursive: true });
-                fs.writeFileSync(dest, content, 'utf-8');
-                if (merged)
+            if (changed) {
+                if (mergedAny)
                     result.merged++;
                 result.pulled++;
                 if (opts.verbose) {
-                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)} <- ${list.map(c => c.machine).join('+')}`);
+                    const machines = [...new Set(list.map(c => c.machine))].join('+');
+                    const files = byRel.size > 1 ? ` (${byRel.size} files)` : '';
+                    opts.log?.(`  pull ${agentId}/${sessionId.slice(0, 8)}${files} <- ${machines}`);
                 }
             }
             else {
@@ -234,6 +355,7 @@ export async function syncSessions(opts = {}) {
     const cfg = loadR2Config();
     const me = machineId();
     const r2 = new R2Client(cfg);
+    const encKey = resolveSyncEncKey(cfg); // shared client-side transcript key, or null
     const result = {
         machine: me,
         pushed: 0,
@@ -242,10 +364,11 @@ export async function syncSessions(opts = {}) {
         merged: 0,
         pullSkipped: 0,
         errors: [],
+        warnings: [],
     };
     if (opts.push !== false)
-        await pushOwn(r2, me, opts, result);
+        await pushOwn(r2, me, encKey, opts, result);
     if (opts.pull !== false)
-        await pullAndReconcile(r2, me, opts, result);
+        await pullAndReconcile(r2, me, encKey, opts, result);
     return result;
 }

package/dist/lib/session/sync/transcript-crypto.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Client-side (zero-knowledge) encryption for session transcripts before they
+ * leave this machine for R2.
+ *
+ * R2 encrypts objects at rest server-side (AES-256, Cloudflare default), but
+ * that key is Cloudflare's — anyone with bucket-read access (or Cloudflare
+ * itself) can read the plaintext. Transcripts carry secrets, tokens, and
+ * absolute file paths, so "encrypted at rest by the provider" is not enough. We
+ * seal each transcript BODY client-side with AES-256-GCM under a key that never
+ * leaves the machines that share the sync bundle; Cloudflare only ever stores
+ * ciphertext.
+ *
+ * The key is a 32-byte secret (`R2_SYNC_ENC_KEY`) held in the same
+ * keychain-backed `r2.backups` bundle as the R2 credentials. Every machine in
+ * the sync fabric shares that bundle, so every machine derives the identical key
+ * and can decrypt its peers' objects. The key is deliberately SEPARATE from the
+ * R2 access key so that rotating the R2 token (RUSH-1464) never orphans
+ * transcripts already encrypted under the old one.
+ *
+ * Identity for CRDT merge stays over PLAINTEXT: the manifest hash is computed on
+ * the cleartext transcript (sync.ts), and pull decrypts before the G-Set union
+ * (crdt.ts) ever sees the bytes. Ciphertext is non-deterministic (a fresh random
+ * IV per seal), so it is never usable as an identity — which is exactly why the
+ * manifest, not the object body, carries the hash.
+ */
+import type { R2Config } from './config.js';
+/** Serialized envelope stored as the R2 object body when encryption is on. */
+export interface TranscriptEnvelope {
+    /** Envelope format version. */
+    v: 1;
+    alg: 'aes-256-gcm';
+    /** base64 12-byte GCM nonce, fresh per object. */
+    iv: string;
+    /** base64 ciphertext. */
+    ct: string;
+    /** base64 16-byte GCM auth tag. */
+    tag: string;
+}
+/**
+ * Decode the configured `R2_SYNC_ENC_KEY` into a 32-byte key, or null when the
+ * bundle does not carry one (encryption off — see pushOwn's warning path).
+ *
+ * Accepts hex (64 chars) or base64; both must decode to exactly 32 bytes. A key
+ * that is present but the wrong length THROWS rather than silently truncating —
+ * a malformed key is a configuration bug, not a reason to fall back to a weaker
+ * or wrong key.
+ */
+export declare function resolveSyncEncKey(cfg: Pick<R2Config, 'syncEncKey'>): Buffer | null;
+/** Generate a fresh 32-byte transcript key, base64-encoded (for provisioning). */
+export declare function generateSyncEncKey(): string;
+/** Seal a transcript body. Returns the serialized envelope to store in R2. */
+export declare function encryptTranscript(plaintext: string, key: Buffer): string;
+/**
+ * Parse a stored object body into an envelope, or null when it is not one.
+ *
+ * A plaintext transcript is NDJSON — many JSON objects, one per line — so it
+ * never parses as a single object carrying our `v`/`alg`/`ct`/`tag` fields. That
+ * makes envelope-vs-plaintext detection unambiguous and lets a puller read BOTH
+ * encrypted objects and any legacy plaintext already in the bucket (the beta
+ * uploaded plaintext before this landed). This is format-version handling for a
+ * real migration, not a "just in case" fallback.
+ */
+export declare function parseEnvelope(body: string): TranscriptEnvelope | null;
+/** True when a stored object body is one of our encryption envelopes. */
+export declare function isTranscriptEnvelope(body: string): boolean;
+/** Open a sealed envelope. Throws on a wrong key / tampered body (GCM tag mismatch). */
+export declare function decryptEnvelope(envelope: TranscriptEnvelope, key: Buffer): string;
+/**
+ * Return the plaintext transcript for a fetched object body, transparently
+ * decrypting when it is an envelope.
+ *
+ *  - Envelope + key  → decrypted plaintext.
+ *  - Envelope + no key → throws (the object is encrypted but this machine has no
+ *    key to read it — surfacing that beats silently mis-merging ciphertext).
+ *  - Plaintext body  → returned verbatim (legacy/unencrypted object).
+ */
+export declare function decryptTranscriptBody(body: string, key: Buffer | null): string;

package/dist/lib/session/sync/transcript-crypto.js

@@ -0,0 +1,147 @@
+/**
+ * Client-side (zero-knowledge) encryption for session transcripts before they
+ * leave this machine for R2.
+ *
+ * R2 encrypts objects at rest server-side (AES-256, Cloudflare default), but
+ * that key is Cloudflare's — anyone with bucket-read access (or Cloudflare
+ * itself) can read the plaintext. Transcripts carry secrets, tokens, and
+ * absolute file paths, so "encrypted at rest by the provider" is not enough. We
+ * seal each transcript BODY client-side with AES-256-GCM under a key that never
+ * leaves the machines that share the sync bundle; Cloudflare only ever stores
+ * ciphertext.
+ *
+ * The key is a 32-byte secret (`R2_SYNC_ENC_KEY`) held in the same
+ * keychain-backed `r2.backups` bundle as the R2 credentials. Every machine in
+ * the sync fabric shares that bundle, so every machine derives the identical key
+ * and can decrypt its peers' objects. The key is deliberately SEPARATE from the
+ * R2 access key so that rotating the R2 token (RUSH-1464) never orphans
+ * transcripts already encrypted under the old one.
+ *
+ * Identity for CRDT merge stays over PLAINTEXT: the manifest hash is computed on
+ * the cleartext transcript (sync.ts), and pull decrypts before the G-Set union
+ * (crdt.ts) ever sees the bytes. Ciphertext is non-deterministic (a fresh random
+ * IV per seal), so it is never usable as an identity — which is exactly why the
+ * manifest, not the object body, carries the hash.
+ */
+import * as crypto from 'crypto';
+const ALG = 'aes-256-gcm';
+const KEY_LEN = 32; // AES-256
+const IV_LEN = 12; // GCM standard nonce
+const TAG_LEN = 16;
+/**
+ * Decode the configured `R2_SYNC_ENC_KEY` into a 32-byte key, or null when the
+ * bundle does not carry one (encryption off — see pushOwn's warning path).
+ *
+ * Accepts hex (64 chars) or base64; both must decode to exactly 32 bytes. A key
+ * that is present but the wrong length THROWS rather than silently truncating —
+ * a malformed key is a configuration bug, not a reason to fall back to a weaker
+ * or wrong key.
+ */
+export function resolveSyncEncKey(cfg) {
+    const raw = cfg.syncEncKey?.trim();
+    if (!raw)
+        return null;
+    let key;
+    if (/^[0-9a-f]{64}$/i.test(raw)) {
+        key = Buffer.from(raw, 'hex');
+    }
+    else {
+        key = Buffer.from(raw, 'base64');
+    }
+    if (key.length !== KEY_LEN) {
+        throw new Error(`R2_SYNC_ENC_KEY must decode to ${KEY_LEN} bytes (got ${key.length}). ` +
+            `Provide 32 random bytes as hex (64 chars) or base64. ` +
+            `Generate one with: openssl rand -base64 32`);
+    }
+    return key;
+}
+/** Generate a fresh 32-byte transcript key, base64-encoded (for provisioning). */
+export function generateSyncEncKey() {
+    return crypto.randomBytes(KEY_LEN).toString('base64');
+}
+/** Seal a transcript body. Returns the serialized envelope to store in R2. */
+export function encryptTranscript(plaintext, key) {
+    const iv = crypto.randomBytes(IV_LEN);
+    const cipher = crypto.createCipheriv(ALG, key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const envelope = {
+        v: 1,
+        alg: ALG,
+        iv: iv.toString('base64'),
+        ct: ct.toString('base64'),
+        tag: tag.toString('base64'),
+    };
+    return JSON.stringify(envelope);
+}
+/**
+ * Parse a stored object body into an envelope, or null when it is not one.
+ *
+ * A plaintext transcript is NDJSON — many JSON objects, one per line — so it
+ * never parses as a single object carrying our `v`/`alg`/`ct`/`tag` fields. That
+ * makes envelope-vs-plaintext detection unambiguous and lets a puller read BOTH
+ * encrypted objects and any legacy plaintext already in the bucket (the beta
+ * uploaded plaintext before this landed). This is format-version handling for a
+ * real migration, not a "just in case" fallback.
+ */
+export function parseEnvelope(body) {
+    const trimmed = body.trimStart();
+    if (!trimmed.startsWith('{'))
+        return null; // NDJSON first line is an object too, but…
+    let obj;
+    try {
+        obj = JSON.parse(body); // …the WHOLE body must be one JSON value to be an envelope
+    }
+    catch {
+        return null;
+    }
+    if (obj && typeof obj === 'object' &&
+        obj.v === 1 &&
+        obj.alg === ALG &&
+        typeof obj.iv === 'string' &&
+        typeof obj.ct === 'string' &&
+        typeof obj.tag === 'string') {
+        return obj;
+    }
+    return null;
+}
+/** True when a stored object body is one of our encryption envelopes. */
+export function isTranscriptEnvelope(body) {
+    return parseEnvelope(body) !== null;
+}
+/** Open a sealed envelope. Throws on a wrong key / tampered body (GCM tag mismatch). */
+export function decryptEnvelope(envelope, key) {
+    const iv = Buffer.from(envelope.iv, 'base64');
+    const ct = Buffer.from(envelope.ct, 'base64');
+    const tag = Buffer.from(envelope.tag, 'base64');
+    if (tag.length !== TAG_LEN) {
+        throw new Error(`Transcript envelope has a malformed auth tag (${tag.length} bytes).`);
+    }
+    const decipher = crypto.createDecipheriv(ALG, key, iv);
+    decipher.setAuthTag(tag);
+    try {
+        return Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf-8');
+    }
+    catch {
+        throw new Error('Transcript decryption failed — wrong R2_SYNC_ENC_KEY or corrupt object.');
+    }
+}
+/**
+ * Return the plaintext transcript for a fetched object body, transparently
+ * decrypting when it is an envelope.
+ *
+ *  - Envelope + key  → decrypted plaintext.
+ *  - Envelope + no key → throws (the object is encrypted but this machine has no
+ *    key to read it — surfacing that beats silently mis-merging ciphertext).
+ *  - Plaintext body  → returned verbatim (legacy/unencrypted object).
+ */
+export function decryptTranscriptBody(body, key) {
+    const envelope = parseEnvelope(body);
+    if (!envelope)
+        return body; // legacy plaintext object
+    if (!key) {
+        throw new Error('Fetched an encrypted transcript but R2_SYNC_ENC_KEY is not set in the r2.backups bundle. ' +
+            'Add the shared key so this machine can decrypt peers\' sessions.');
+    }
+    return decryptEnvelope(envelope, key);
+}

package/dist/lib/ssh-tunnel.js

@@ -24,7 +24,7 @@ import { fileURLToPath } from 'url';
 import { randomBytes, createHash } from 'crypto';
 import { Readable } from 'stream';
 import { pipeline } from 'stream/promises';
-import { sshExec, SSH_OPTS } from './ssh-exec.js';
+import { sshExec, SSH_OPTS, assertValidSshTarget } from './ssh-exec.js';
 import { backgroundSpawnOptions } from './platform/process.js';
 import { encodePowerShell } from './browser/drivers/ssh.js';
 import { getDevice } from './devices/registry.js';
@@ -57,6 +57,18 @@ export function buildTunnelArgs(user, host, localPort, remotePort) {
  */
 export function startSSHTunnel(user, host, localPort, remotePort, opts = {}) {
     return new Promise((resolve, reject) => {
+        // `user`/`host` can originate from a browser ssh:// profile or a device
+        // record. buildTunnelArgs places `${user}@${host}` before `-N`/SSH_OPTS, so
+        // a `-`-leading user would be parsed as an ssh option flag (option
+        // injection). Validate at the spawn sink so every caller is covered; reject
+        // (rather than throw synchronously) to keep the Promise contract.
+        try {
+            assertValidSshTarget(`${user}@${host}`);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         const args = buildTunnelArgs(user, host, localPort, remotePort);
         const tunnel = spawn('ssh', args, {
             stdio: opts.detached ? 'ignore' : ['ignore', 'ignore', 'pipe'],

package/dist/lib/staleness/detectors/subagents.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Subagents detector. The installed-name enumeration for every agent's on-disk
+ * layout is declared once in the subagent registry; this detector is generic
+ * and delegates to `listInstalledSubagentNames` instead of a per-agent builder.
+ */
 import type { AgentId } from '../../types.js';
 import type { ResourceDetector } from './types.js';
 export declare const subagentsDetectors: Partial<Record<AgentId, ResourceDetector>>;