@phnx-labs/agents-cli 1.20.93 → 1.21.0

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

@@ -1,119 +0,0 @@
-/**
- * CRDT merge for agent transcripts.
- *
- * A transcript (Claude JSONL, Codex JSONL, …) is an append-only log of
- * immutable events: each line is written once and never rewritten, and Claude
- * already tolerates branches within one file (parentUuid fan-out). That makes a
- * transcript a grow-only set (G-Set) of events, and merging two copies of the
- * same session is a set union — associative, commutative, idempotent. Two
- * machines that each appended to the same session therefore converge to the
- * exact same merged file regardless of sync order or timing, with zero conflict
- * resolution and zero data loss.
- *
- * Events are identified by the SHA-256 of their raw line bytes. We deliberately
- * do NOT key on a per-event `uuid`: Codex lines carry no id, and because an
- * event is written exactly once and then copied verbatim across machines, the
- * raw bytes are a stable, agent-agnostic identity. Multiplicity is preserved
- * (some transcripts contain legitimately identical lines, e.g. paired
- * `queue-operation` entries) by taking the per-hash max count across sources.
- */
-import * as crypto from 'crypto';
-/** Extract the top-level `timestamp` field both Claude and Codex stamp per line. */
-function lineTimestamp(raw) {
-    try {
-        const obj = JSON.parse(raw);
-        const ts = obj?.timestamp;
-        return typeof ts === 'string' ? ts : '';
-    }
-    catch {
-        return '';
-    }
-}
-/** Parse a transcript's raw text into events, skipping blank lines. */
-export function parseTranscript(content) {
-    const out = [];
-    for (const line of content.split('\n')) {
-        if (line.trim() === '')
-            continue;
-        out.push({
-            raw: line,
-            hash: crypto.createHash('sha256').update(line).digest('hex'),
-            ts: lineTimestamp(line),
-        });
-    }
-    return out;
-}
-/** Order events deterministically across machines: by timestamp, then hash. */
-function compareEvents(a, b) {
-    if (a.ts !== b.ts)
-        return a.ts < b.ts ? -1 : 1;
-    if (a.hash !== b.hash)
-        return a.hash < b.hash ? -1 : 1;
-    return 0;
-}
-/**
- * Merge copies of the same session into one transcript via G-Set union.
- *
- * Returns a source VERBATIM (no reordering, byte-identical) for the common
- * cases — one source, all sources identical, or one source a superset of the
- * rest — so the steady state never rewrites unchanged files. Only a true fork
- * (each side holds events the other lacks) produces a reordered union, sorted
- * by (timestamp, hash) so every machine derives identical bytes.
- */
-export function mergeTranscripts(contents) {
-    const sources = contents.filter(c => c.length > 0);
-    if (sources.length === 0)
-        return '';
-    if (sources.length === 1)
-        return sources[0];
-    const parsed = sources.map(parseTranscript);
-    // Per-source multiset of event hashes.
-    const counts = parsed.map(events => {
-        const m = new Map();
-        for (const e of events)
-            m.set(e.hash, (m.get(e.hash) ?? 0) + 1);
-        return m;
-    });
-    // Global max count per hash + a representative event for raw bytes / ts.
-    const maxCount = new Map();
-    const rep = new Map();
-    for (let i = 0; i < parsed.length; i++) {
-        for (const e of parsed[i])
-            if (!rep.has(e.hash))
-                rep.set(e.hash, e);
-        for (const [h, c] of counts[i])
-            maxCount.set(h, Math.max(maxCount.get(h) ?? 0, c));
-    }
-    // Superset fast path: a source whose multiset already equals the global max
-    // is the union — return it byte-for-byte (covers identical/subset/prefix).
-    for (let i = 0; i < sources.length; i++) {
-        let isSuperset = true;
-        for (const [h, c] of maxCount) {
-            if ((counts[i].get(h) ?? 0) !== c) {
-                isSuperset = false;
-                break;
-            }
-        }
-        if (isSuperset)
-            return sources[i];
-    }
-    // True fork: emit each distinct event maxCount times, deterministically ordered.
-    const distinct = [...rep.values()].sort(compareEvents);
-    const lines = [];
-    for (const e of distinct) {
-        const n = maxCount.get(e.hash) ?? 1;
-        for (let k = 0; k < n; k++)
-            lines.push(e.raw);
-    }
-    const trailing = sources.some(s => s.endsWith('\n')) ? '\n' : '';
-    return lines.join('\n') + trailing;
-}
-/** Count distinct + total events across copies (for logging / manifest stats). */
-export function transcriptStats(content) {
-    const parsed = parseTranscript(content);
-    let lastTs = '';
-    for (const e of parsed)
-        if (e.ts > lastTs)
-            lastTs = e.ts;
-    return { events: parsed.length, lastTs };
-}

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

@@ -1,62 +0,0 @@
-/**
- * Manifests and the local upload ledger.
- *
- * Each machine publishes one manifest object (sessions/<machine>/manifest.json)
- * listing every session it holds, keyed by session id, with content hash + size
- * + last event timestamp. Pulling machines diff manifests to fetch only changed
- * objects — no per-tick LIST of thousands of keys.
- *
- * The local upload ledger (cache, per machine) records (size, mtime, hash) of
- * files already pushed, so a tick re-uploads only files that actually grew.
- */
-export interface ManifestEntry {
-    /** Storage-relative key, preserved into the mirror layout on the puller. */
-    relKey: string;
-    size: number;
-    /** SHA-256 of the full transcript file. */
-    hash: string;
-    /** Latest event timestamp in the transcript. */
-    lastTs: string;
-}
-/**
- * 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 | entry[]) */
-    agents: Record<string, AgentManifest>;
-}
-export declare function emptyManifest(machine: string, updatedAt: string): Manifest;
-export declare function parseManifest(text: string): Manifest | null;
-export declare function hashContent(content: string | Uint8Array): string;
-export declare function loadLocalManifest(): Manifest | null;
-export declare function saveLocalManifest(m: Manifest): void;
-/** key `${agent}/${sessionId}` -> signature of applied source hashes */
-export type PullState = Record<string, string>;
-export declare function loadPullState(): PullState;
-export declare function savePullState(s: PullState): void;
-/** Order-independent signature of the source hashes feeding one mirrored session. */
-export declare function sourceSignature(hashes: string[]): string;
-interface LedgerRow {
-    size: number;
-    mtimeMs: number;
-    hash: string;
-}
-type Ledger = Record<string, LedgerRow>;
-export declare function loadLedger(): Ledger;
-export declare function saveLedger(ledger: Ledger): void;
-/** True if the file at absPath is unchanged since we last uploaded it. */
-export declare function ledgerUnchanged(ledger: Ledger, absPath: string, size: number, mtimeMs: number): boolean;
-export declare function ledgerRecord(ledger: Ledger, absPath: string, size: number, mtimeMs: number, hash: string): void;
-export {};

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

@@ -1,100 +0,0 @@
-/**
- * Manifests and the local upload ledger.
- *
- * Each machine publishes one manifest object (sessions/<machine>/manifest.json)
- * listing every session it holds, keyed by session id, with content hash + size
- * + last event timestamp. Pulling machines diff manifests to fetch only changed
- * objects — no per-tick LIST of thousands of keys.
- *
- * The local upload ledger (cache, per machine) records (size, mtime, hash) of
- * files already pushed, so a tick re-uploads only files that actually grew.
- */
-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: {} };
-}
-export function parseManifest(text) {
-    try {
-        const m = JSON.parse(text);
-        if (m && typeof m.machine === 'string' && m.agents && typeof m.agents === 'object')
-            return m;
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
-export function hashContent(content) {
-    return crypto.createHash('sha256').update(content).digest('hex');
-}
-function stateDir() {
-    return path.join(getCacheDir(), 'state', 'sessions-sync');
-}
-// --- local cached copy of our published manifest ---------------------------
-function localManifestPath() {
-    return path.join(stateDir(), 'manifest.json');
-}
-export function loadLocalManifest() {
-    try {
-        return parseManifest(fs.readFileSync(localManifestPath(), 'utf-8'));
-    }
-    catch {
-        return null;
-    }
-}
-export function saveLocalManifest(m) {
-    const p = localManifestPath();
-    fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, JSON.stringify(m), 'utf-8');
-}
-function pullStatePath() {
-    return path.join(stateDir(), 'pull-state.json');
-}
-export function loadPullState() {
-    try {
-        return JSON.parse(fs.readFileSync(pullStatePath(), 'utf-8'));
-    }
-    catch {
-        return {};
-    }
-}
-export function savePullState(s) {
-    const p = pullStatePath();
-    fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, JSON.stringify(s), 'utf-8');
-}
-/** Order-independent signature of the source hashes feeding one mirrored session. */
-export function sourceSignature(hashes) {
-    return [...hashes].sort().join(',');
-}
-function ledgerPath() {
-    return path.join(getCacheDir(), 'state', 'sessions-sync', 'upload-ledger.json');
-}
-export function loadLedger() {
-    try {
-        return JSON.parse(fs.readFileSync(ledgerPath(), 'utf-8'));
-    }
-    catch {
-        return {};
-    }
-}
-export function saveLedger(ledger) {
-    const p = ledgerPath();
-    fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, JSON.stringify(ledger), 'utf-8');
-}
-/** True if the file at absPath is unchanged since we last uploaded it. */
-export function ledgerUnchanged(ledger, absPath, size, mtimeMs) {
-    const row = ledger[absPath];
-    return !!row && row.size === size && row.mtimeMs === Math.floor(mtimeMs);
-}
-export function ledgerRecord(ledger, absPath, size, mtimeMs, hash) {
-    ledger[absPath] = { size, mtimeMs: Math.floor(mtimeMs), hash };
-}

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

@@ -1,49 +0,0 @@
-/**
- * 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

@@ -1,91 +0,0 @@
-/**
- * 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/r2.d.ts

@@ -1,32 +0,0 @@
-/**
- * Minimal S3-compatible client for Cloudflare R2, built on aws4fetch (SigV4
- * over the platform `fetch` + WebCrypto — works identically under Bun and
- * Node >= 22). Only the verbs sync needs: put / get / head / list / delete.
- *
- * No mounting, no FUSE: this is a plain object-store client driven by a polling
- * loop, which is the only approach that is seamless on both macOS and Linux
- * (Mountpoint for S3 is Linux-only; rclone-mount needs macFUSE).
- */
-import type { R2Config } from './config.js';
-export interface HeadResult {
-    size: number;
-    etag: string;
-}
-export declare class R2Client {
-    private aws;
-    private base;
-    constructor(cfg: R2Config);
-    private url;
-    /** Upload an object. Overwrites unconditionally. */
-    put(key: string, body: string | Uint8Array, contentType?: string): Promise<void>;
-    /** Fetch an object as text, or null if it does not exist (404). */
-    get(key: string): Promise<string | null>;
-    /** HEAD an object for size + etag, or null if it does not exist. */
-    head(key: string): Promise<HeadResult | null>;
-    /** Delete an object (no error if it is already absent). */
-    delete(key: string): Promise<void>;
-    /** List immediate sub-prefixes under a prefix (delimiter '/'), e.g. machine dirs. */
-    listPrefixes(prefix: string): Promise<string[]>;
-    /** List all object keys under a prefix (handles pagination). */
-    list(prefix: string): Promise<string[]>;
-}

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

@@ -1,121 +0,0 @@
-/**
- * Minimal S3-compatible client for Cloudflare R2, built on aws4fetch (SigV4
- * over the platform `fetch` + WebCrypto — works identically under Bun and
- * Node >= 22). Only the verbs sync needs: put / get / head / list / delete.
- *
- * No mounting, no FUSE: this is a plain object-store client driven by a polling
- * loop, which is the only approach that is seamless on both macOS and Linux
- * (Mountpoint for S3 is Linux-only; rclone-mount needs macFUSE).
- */
-import { AwsClient } from 'aws4fetch';
-export class R2Client {
-    aws;
-    base;
-    constructor(cfg) {
-        this.aws = new AwsClient({
-            accessKeyId: cfg.accessKeyId,
-            secretAccessKey: cfg.secretAccessKey,
-            service: 's3',
-            region: 'auto',
-        });
-        this.base = `${cfg.endpoint}/${encodeURIComponent(cfg.bucket)}`;
-    }
-    url(key) {
-        const encoded = key.split('/').map(encodeURIComponent).join('/');
-        return `${this.base}/${encoded}`;
-    }
-    /** Upload an object. Overwrites unconditionally. */
-    async put(key, body, contentType = 'application/octet-stream') {
-        const res = await this.aws.fetch(this.url(key), {
-            method: 'PUT',
-            body,
-            headers: { 'content-type': contentType },
-        });
-        if (!res.ok)
-            throw new Error(`R2 PUT ${key} failed: ${res.status} ${await safeText(res)}`);
-    }
-    /** Fetch an object as text, or null if it does not exist (404). */
-    async get(key) {
-        const res = await this.aws.fetch(this.url(key), { method: 'GET' });
-        if (res.status === 404)
-            return null;
-        if (!res.ok)
-            throw new Error(`R2 GET ${key} failed: ${res.status} ${await safeText(res)}`);
-        return await res.text();
-    }
-    /** HEAD an object for size + etag, or null if it does not exist. */
-    async head(key) {
-        const res = await this.aws.fetch(this.url(key), { method: 'HEAD' });
-        if (res.status === 404)
-            return null;
-        if (!res.ok)
-            throw new Error(`R2 HEAD ${key} failed: ${res.status}`);
-        return {
-            size: Number(res.headers.get('content-length') ?? '0'),
-            etag: (res.headers.get('etag') ?? '').replace(/"/g, ''),
-        };
-    }
-    /** Delete an object (no error if it is already absent). */
-    async delete(key) {
-        const res = await this.aws.fetch(this.url(key), { method: 'DELETE' });
-        if (!res.ok && res.status !== 404) {
-            throw new Error(`R2 DELETE ${key} failed: ${res.status}`);
-        }
-    }
-    /** List immediate sub-prefixes under a prefix (delimiter '/'), e.g. machine dirs. */
-    async listPrefixes(prefix) {
-        const prefixes = [];
-        let token;
-        do {
-            const params = new URLSearchParams({ 'list-type': '2', prefix, delimiter: '/' });
-            if (token)
-                params.set('continuation-token', token);
-            const res = await this.aws.fetch(`${this.base}?${params.toString()}`, { method: 'GET' });
-            if (!res.ok)
-                throw new Error(`R2 LIST(prefixes) ${prefix} failed: ${res.status} ${await safeText(res)}`);
-            const xml = await res.text();
-            for (const m of xml.matchAll(/<CommonPrefixes><Prefix>([^<]+)<\/Prefix><\/CommonPrefixes>/g)) {
-                prefixes.push(decodeXml(m[1]));
-            }
-            const truncated = /<IsTruncated>true<\/IsTruncated>/.test(xml);
-            token = truncated ? xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/)?.[1] : undefined;
-        } while (token);
-        return prefixes;
-    }
-    /** List all object keys under a prefix (handles pagination). */
-    async list(prefix) {
-        const keys = [];
-        let token;
-        do {
-            const params = new URLSearchParams({ 'list-type': '2', prefix });
-            if (token)
-                params.set('continuation-token', token);
-            const res = await this.aws.fetch(`${this.base}?${params.toString()}`, { method: 'GET' });
-            if (!res.ok)
-                throw new Error(`R2 LIST ${prefix} failed: ${res.status} ${await safeText(res)}`);
-            const xml = await res.text();
-            for (const m of xml.matchAll(/<Key>([^<]+)<\/Key>/g)) {
-                keys.push(decodeXml(m[1]));
-            }
-            const truncated = /<IsTruncated>true<\/IsTruncated>/.test(xml);
-            token = truncated ? xml.match(/<NextContinuationToken>([^<]+)<\/NextContinuationToken>/)?.[1] : undefined;
-        } while (token);
-        return keys;
-    }
-}
-function decodeXml(s) {
-    return s
-        .replace(/&amp;/g, '&')
-        .replace(/&lt;/g, '<')
-        .replace(/&gt;/g, '>')
-        .replace(/&quot;/g, '"')
-        .replace(/&apos;/g, "'");
-}
-async function safeText(res) {
-    try {
-        return (await res.text()).slice(0, 200);
-    }
-    catch {
-        return '';
-    }
-}

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

@@ -1,106 +0,0 @@
-/**
- * Cross-machine session sync orchestration.
- *
- *  PUSH  this machine's transcripts (changed since last tick) to its own R2
- *        prefix, then publish a manifest. Single-writer prefixes mean no two
- *        machines ever write the same object — zero remote contention.
- *
- *  PULL  every other machine's manifest, fetch changed transcripts, CRDT-union
- *        copies of the same session, and write the result into the local mirror
- *        (a scan root). The existing scanner indexes it; sessions present in the
- *        live home always win, so the mirror only fills in remote-origin sessions.
- *
- * Invariants:
- *  - Live home transcripts are only ever READ + uploaded, never rewritten.
- *  - Union is idempotent, so once sets match nothing is transferred (quiescence).
- */
-import { type SyncAgentSpec } from './agents.js';
-import { type ManifestEntry, type PullState } from './manifest.js';
-export interface SyncResult {
-    machine: string;
-    pushed: number;
-    pushSkipped: number;
-    pulled: number;
-    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;
-    log?: (msg: string) => void;
-    /** Upload this machine's transcripts (default true). */
-    push?: boolean;
-    /** Download + merge other machines' transcripts (default true). A machine
-     *  with read-only R2 credentials can still pull. */
-    pull?: boolean;
-}
-export interface RemoteCopy {
-    machine: string;
-    entry: ManifestEntry;
-}
-export interface PendingSession {
-    agentId: string;
-    sessionId: string;
-    copies: RemoteCopy[];
-    /** Signature of source hashes — stored in pull state once applied. */
-    sig: string;
-}
-/**
- * Decide which remote sessions need fetching this tick. Pure: no I/O.
- * Skips sessions we hold locally (home wins) and sessions whose source set is
- * unchanged since we last materialized them (pull-state hit → quiescence).
- */
-export declare function selectSessionsToFetch(copies: Map<string, Map<string, RemoteCopy[]>>, localIdsByAgent: Map<string, Set<string>>, pullState: PullState): PendingSession[];
-/**
- * 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 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;
-    merged: boolean;
-};
-/**
- * Decide how to reconcile one session's fetched copies. Pure: no I/O.
- *
- * `fetched` is positionally aligned to `copies` — a `null` slot means that
- * copy's object wasn't retrievable this tick (R2 404 / LIST→GET consistency
- * lag / a transient get error). If ANY listed copy is missing, returns `null`:
- * the caller must then skip the mirror write AND skip stamping pull-state, so
- * the session is retried next tick. Writing a partial set instead would
- * materialize a non-converged union and — because pull-state would record the
- * full source signature — abandon the missing branch forever (the bug this
- * guards: a signature match in selectSessionsToFetch never re-fetches it).
- */
-export declare function reconcileCopies(spec: SyncAgentSpec, copies: RemoteCopy[], fetched: Array<string | null>): {
-    dest: string;
-    content: string;
-    merged: boolean;
-} | null;
-/** Run one full sync cycle: push this machine's changes, pull everyone else's. */
-export declare function syncSessions(opts?: SyncOptions): Promise<SyncResult>;