@phnx-labs/agents-cli 1.20.63 → 1.20.64

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

@@ -0,0 +1,150 @@
+/**
+ * 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 { type SyncAgentSpec } from './sync/agents.js';
+export declare const BUNDLE_KIND = "agents-session-bundle";
+export declare const BUNDLE_VERSION = 1;
+/** First line of a bundle: what it is and how the bodies are encoded. */
+export interface BundleHeader {
+    kind: typeof BUNDLE_KIND;
+    version: number;
+    /** ISO timestamp the bundle was produced. */
+    exportedAt: string;
+    /** Machine that produced the bundle (informational; per-record `machine` is authoritative for placement). */
+    origin: string;
+    /** True when record bodies are AES-256-GCM envelopes (see transcript-crypto). */
+    encrypted: boolean;
+    /** True when bodies were secret-scrubbed before hashing/sealing. */
+    redacted: boolean;
+    /** Number of file records that follow. */
+    count: number;
+    /** Distinct session count across those records. */
+    sessions: number;
+}
+/** One constituent file of one session. Dir-shaped sessions emit several, sharing `sessionId`. */
+export interface BundleRecord {
+    /** SYNC_AGENTS id (claude, codex, kimi, …). */
+    agent: string;
+    /** ORIGIN machine of this session — where placement mirrors it to. */
+    machine: string;
+    sessionId: string;
+    /** Storage-relative key within the agent's subdir (preserved on import). */
+    relKey: string;
+    /** Byte length of the plaintext body. */
+    size: number;
+    /** SHA-256 of the plaintext body — identity + byte-exact dedup. */
+    hash: string;
+    /** Human label carried from SessionMeta, if any. */
+    label?: string;
+    /** True when `body` is an encryption envelope rather than plaintext. */
+    encrypted: boolean;
+    /** File content: plaintext, or a transcript-crypto envelope when `encrypted`. */
+    body: string;
+}
+export interface ParsedBundle {
+    header: BundleHeader;
+    records: BundleRecord[];
+}
+/** A single file selected for export, resolved to an absolute on-disk path. */
+export interface FileToExport {
+    agent: string;
+    /** Origin machine of the session (self for live-home, the peer for a mirror). */
+    machine: string;
+    sessionId: string;
+    relKey: string;
+    absPath: string;
+    label?: string;
+}
+export interface BuildRecordOpts {
+    /** Scrub secrets from the body before hashing/sealing (default-on at the command layer). */
+    redact: boolean;
+    /** Non-null → seal each body with this key; null → plaintext bodies. */
+    encryptKey: Buffer | null;
+}
+/** Look up the sync spec for an agent id (undefined → agent not sync-representable). */
+export declare function specForAgent(agentId: string): SyncAgentSpec | undefined;
+/** True when an agent's sessions can be represented in a bundle (has a sync spec). */
+export declare function isExportableAgent(agentId: string): boolean;
+/**
+ * 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 declare function buildRecord(file: FileToExport, opts: BuildRecordOpts): BundleRecord;
+/** Build the header for a set of records. */
+export declare function makeHeader(args: {
+    origin: string;
+    exportedAt: string;
+    encrypted: boolean;
+    redacted: boolean;
+    records: BundleRecord[];
+}): BundleHeader;
+/**
+ * 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 declare function mergeRecords(sets: BundleRecord[][]): BundleRecord[];
+/** Serialize a bundle to its NDJSON wire form (header line + one line per record). */
+export declare function serializeBundle(header: BundleHeader, records: BundleRecord[]): string;
+/** Parse an NDJSON bundle, validating the header kind + version. Throws on malformed input. */
+export declare function parseBundle(text: string): ParsedBundle;
+/** Placement outcome for one record, computed against what is already on disk. */
+export type ImportStatus = 'new' | 'dup' | 'conflict' | 'unknown';
+export interface ImportPlanItem {
+    record: BundleRecord;
+    /** Absolute path the file lands at (empty for `unknown` agents). */
+    targetPath: string;
+    status: ImportStatus;
+}
+export interface PlanImportOpts {
+    /** Key to open encrypted record bodies (null → only plaintext bodies readable). */
+    decryptKey: Buffer | null;
+}
+/**
+ * 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 declare function planImport(bundle: ParsedBundle, opts: PlanImportOpts): ImportPlanItem[];
+export interface WriteResult {
+    /** New files written. */
+    placed: number;
+    /** Byte-exact dups skipped. */
+    skipped: number;
+    /** Conflicts replaced (only with overwrite). */
+    overwritten: number;
+    /** Conflicts left in place (overwrite off). */
+    conflicts: number;
+    /** Records for agents with no sync spec. */
+    unknown: number;
+}
+export interface WriteImportOpts {
+    overwrite: boolean;
+    decryptKey: Buffer | null;
+}
+/**
+ * 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 declare function writeImport(plan: ImportPlanItem[], opts: WriteImportOpts): WriteResult;

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,23 +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
@@ -38,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/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/sync.d.ts

@@ -55,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;