@neta-art/cohub-cli 7.1.2 → 8.0.1

package/dist/runtime/native-ipc.js

@@ -0,0 +1,101 @@
+import { createConnection, createServer } from "node:net";
+import { mkdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { nativeRuntimeRoot } from "./native-sync.js";
+import { currentIdentityKey } from "../space.js";
+import { canonicalRuntimeRoot, getRuntimeSpaceBinding } from "./space-binding.js";
+const MAX_LINE_BYTES = 4 * 1024 * 1024;
+const socketPath = (runtimeRoot) => join(runtimeRoot, "native", "daemon.sock");
+const parse = (raw) => {
+    const value = JSON.parse(raw);
+    if (value?.type !== "native.capture" || !["pi", "codex"].includes(value.harness)
+        || typeof value.cwd !== "string" || typeof value.path !== "string" || typeof value.nativeSessionId !== "string") {
+        throw new Error("Invalid native daemon request");
+    }
+    return value;
+};
+export async function nativeDaemonSocketFor(cwd) {
+    const identity = currentIdentityKey();
+    if (!identity)
+        return null;
+    const root = await canonicalRuntimeRoot(cwd);
+    const binding = await getRuntimeSpaceBinding(root, identity);
+    return binding ? socketPath(nativeRuntimeRoot(binding.spaceId)) : null;
+}
+export async function requestNativeDaemon(input) {
+    const path = await nativeDaemonSocketFor(input.cwd);
+    if (!path)
+        return { ok: false, message: "Native Runtime is not bound" };
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(path);
+        let buffer = "";
+        const timer = setTimeout(() => { socket.destroy(); reject(new Error("Native Runtime daemon timed out")); }, 15_000);
+        const finish = (error, result) => {
+            clearTimeout(timer);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve(result ?? { ok: false, message: "Empty daemon response" });
+        };
+        socket.once("error", (error) => finish(error));
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString();
+            if (Buffer.byteLength(buffer) > MAX_LINE_BYTES) {
+                finish(new Error("Native daemon response too large"));
+                return;
+            }
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            try {
+                finish(undefined, JSON.parse(buffer.slice(0, newline)));
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        socket.once("connect", () => socket.write(`${JSON.stringify({ type: "native.capture", ...input })}\n`));
+    });
+}
+export async function serveNativeDaemon(input) {
+    const path = socketPath(input.runtimeRoot);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await rm(path, { force: true });
+    const server = createServer((socket) => {
+        let buffer = "";
+        let closed = false;
+        const respond = (value) => {
+            if (closed)
+                return;
+            closed = true;
+            socket.end(`${JSON.stringify(value)}\n`);
+        };
+        socket.setTimeout(20_000, () => socket.destroy());
+        socket.once("error", () => { closed = true; });
+        socket.on("data", (chunk) => {
+            buffer += chunk.toString();
+            if (Buffer.byteLength(buffer) > MAX_LINE_BYTES) {
+                socket.destroy();
+                return;
+            }
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                return;
+            socket.removeAllListeners("data");
+            void (async () => {
+                const request = parse(buffer.slice(0, newline));
+                const result = await input.handle(request);
+                respond({ ok: true, pendingTurns: result.store ? (await result.store.status()).pendingTurns : 0 });
+            })().catch((error) => respond({ ok: false, message: error instanceof Error ? error.message : String(error) }));
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(path, () => { server.removeListener("error", reject); resolve(); });
+    });
+    return async () => {
+        await new Promise((resolve) => server.close(() => resolve()));
+        await rm(path, { force: true });
+    };
+}

package/dist/runtime/native-pi-extension.d.ts

@@ -0,0 +1,20 @@
+type PiContext = {
+    cwd: string;
+    sessionManager: {
+        getSessionFile(): string | undefined;
+        getSessionId(): string;
+        getLeafId(): string | null;
+    };
+    abort(): void;
+    isIdle(): boolean;
+    ui: {
+        notify(message: string, level: "info" | "warning" | "error"): void;
+        setStatus(key: string, value: string | undefined): void;
+    };
+};
+type PiExtension = {
+    on(event: string, handler: (event: unknown, context: PiContext) => Promise<void> | void): void;
+};
+/** Thin native adapter. The Runtime Daemon owns Cohub auth, WS, retries and archives. */
+export default function cohubNativeExtension(pi: PiExtension): void;
+export {};

package/dist/runtime/native-pi-extension.js

@@ -0,0 +1,47 @@
+import { requestNativeDaemon } from "./native-ipc.js";
+/** Thin native adapter. The Runtime Daemon owns Cohub auth, WS, retries and archives. */
+export default function cohubNativeExtension(pi) {
+    if (process.env.COHUB_TURN_ID || process.env.COHUB_EXECUTION_TOKEN)
+        return;
+    let context = null;
+    let captures = Promise.resolve();
+    let lastError = "";
+    let timer;
+    const report = (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message !== lastError)
+            context?.ui.notify(`Cohub sync pending: ${message}`, "warning");
+        lastError = message;
+    };
+    const capture = (ctx, settled = false) => {
+        context = ctx;
+        const path = ctx.sessionManager.getSessionFile();
+        if (!path)
+            return Promise.resolve();
+        captures = captures.then(async () => {
+            const result = await requestNativeDaemon({ harness: "pi", cwd: ctx.cwd, path, nativeSessionId: ctx.sessionManager.getSessionId(), leafId: ctx.sessionManager.getLeafId(), settled });
+            if (!result.ok)
+                throw new Error(result.message);
+            ctx.ui.setStatus("cohub", "Cohub");
+            lastError = "";
+        }).catch(report);
+        return captures;
+    };
+    pi.on("session_start", async (_event, ctx) => {
+        await capture(ctx, ctx.isIdle());
+        if (timer)
+            clearInterval(timer);
+        timer = setInterval(() => { void capture(ctx, ctx.isIdle()); }, 5000);
+        timer.unref();
+    });
+    pi.on("message_end", (_event, ctx) => capture(ctx));
+    pi.on("agent_settled", (_event, ctx) => capture(ctx, true));
+    pi.on("session_shutdown", async (_event, ctx) => {
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+        await captures;
+        ctx.ui.setStatus("cohub", undefined);
+        context = null;
+    });
+}

package/dist/runtime/native-sync-store.d.ts

@@ -0,0 +1,97 @@
+import type { NativeTurnBinding, NativeTurnComplete, NativeTurnStart, NativeTurnProgress } from "@neta-art/cohub";
+import { RuntimeArchiveStore, type ArchiveTransport } from "./archive-store.js";
+import type { NativeTranscript } from "./native-transcript.js";
+export declare const nativeIdentityHash: (identity: string) => string;
+export declare function nativeStableId(value: string): string;
+type NativeBinding = {
+    version: 1;
+    identity: string;
+    spaceId: string;
+    harness: "pi" | "codex";
+    nativeSessionId: string;
+    instanceKey?: string;
+    path: string;
+    originSessionId: string;
+    sessionId: string | null;
+    throughTurnId: string | null;
+    throughBytes: number;
+    anchors: Array<{
+        turnId: string;
+        sizeBytes: number;
+        sha256: string;
+    }>;
+};
+export type NativeTurnReceipt = {
+    version: 1;
+    turnId: string;
+    key: string;
+    parentKey: string | null;
+    parentCloudTurnId: string | null;
+    userContent: NativeTurnStart["userContent"];
+    startedAt: string;
+    endBytes: number;
+    contentEndBytes?: number;
+    result: NativeTurnComplete | null;
+    progress?: NativeTurnProgress;
+};
+export type NativeSyncTransport = ArchiveTransport & {
+    startNativeTurn?(input: NativeTurnStart, options?: {
+        signal?: AbortSignal;
+    }): Promise<NativeTurnBinding>;
+    completeNativeTurn?(sessionId: string, turnId: string, input: NativeTurnComplete, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        completed: true;
+        artifactsPending?: boolean;
+    }>;
+    heartbeatNativeTurn?(sessionId: string, turnId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        abortRequested: boolean;
+        status: string;
+    }>;
+    updateNativeTurn?(sessionId: string, turnId: string, input: NativeTurnProgress, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        accepted: boolean;
+    }>;
+};
+export type NativeSyncOptions = {
+    runtimeRoot: string;
+    spaceId: string;
+    identity: string;
+    harness: "pi" | "codex";
+    nativeSessionId: string;
+    instanceKey?: string;
+    transport?: NativeSyncTransport;
+};
+/** Turn receipts are append-only. Capture never waits for the network; network ACKs live in separate files. */
+export declare class NativeSyncStore {
+    readonly options: NativeSyncOptions;
+    readonly root: string;
+    readonly archives: RuntimeArchiveStore;
+    private archiveFailure;
+    constructor(options: NativeSyncOptions);
+    private bindingPath;
+    private turnId;
+    private receiptPath;
+    private acknowledgementPath;
+    private pendingPath;
+    private requestPath;
+    private cloudBindingPath;
+    binding(): Promise<NativeBinding>;
+    private initialize;
+    capture(path: string, transcript: NativeTranscript): Promise<void>;
+    receipts(pendingOnly?: boolean): Promise<NativeTurnReceipt[]>;
+    status(): Promise<{
+        harness: "codex" | "pi";
+        nativeSessionId: string;
+        sessionId: string | null;
+        pendingTurns: number;
+        pendingArchives: number;
+    }>;
+    flush(signal: AbortSignal, onAbort?: () => void): Promise<void>;
+    private cloudArchive;
+}
+export declare function listNativeSyncStores(runtimeRoot: string, spaceId: string, identity: string, transport?: NativeSyncTransport): Promise<NativeSyncStore[]>;
+export {};

package/dist/runtime/native-sync-store.js

@@ -0,0 +1,365 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, readFile, readdir, stat, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { nativeTurnCompleteSchema, nativeTurnStartSchema, nativeTurnProgressSchema, harnessArchiveIndexSchema } from "@neta-art/cohub";
+import { RuntimeArchiveStore, atomicRuntimeJson } from "./archive-store.js";
+import { findRuntimeNativeSession } from "./session-store.js";
+import { withRuntimeSpaceBindingsLock } from "./space-binding.js";
+const missing = (error) => error.code === "ENOENT";
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+export const nativeIdentityHash = (identity) => hash(identity);
+export function nativeStableId(value) {
+    const hex = hash(value);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+}
+/** Turn receipts are append-only. Capture never waits for the network; network ACKs live in separate files. */
+export class NativeSyncStore {
+    options;
+    root;
+    archives;
+    archiveFailure;
+    constructor(options) {
+        this.options = options;
+        const source = options.instanceKey ? JSON.stringify([options.nativeSessionId, options.instanceKey]) : options.nativeSessionId;
+        this.root = join(options.runtimeRoot, "native", nativeIdentityHash(options.identity), `${options.harness}-${hash(source)}`);
+        const transport = options.transport;
+        this.archives = new RuntimeArchiveStore(join(this.root, "archives"), transport ? {
+            prepareRuntimeArchive: async (index, request) => transport.prepareRuntimeArchive(await this.cloudArchive(index), request),
+            commitRuntimeArchive: async (index, request) => transport.commitRuntimeArchive(await this.cloudArchive(index), request),
+            getRuntimeArchive: (...args) => transport.getRuntimeArchive(...args),
+            fetchObject: transport.fetchObject,
+        } : undefined);
+        this.archives.setErrorReporter((error) => { this.archiveFailure = error; });
+    }
+    bindingPath() { return join(this.root, "binding.json"); }
+    turnId(key) {
+        return nativeStableId(JSON.stringify([this.options.identity, this.options.spaceId, this.options.harness, this.options.nativeSessionId, this.options.instanceKey ?? null, key]));
+    }
+    receiptPath(id) { return join(this.root, "turns", `${id}.json`); }
+    acknowledgementPath(id) { return join(this.root, "acknowledged", `${id}.json`); }
+    pendingPath(id) { return join(this.root, "pending", `${id}.json`); }
+    requestPath(id) { return join(this.root, "requests", `${id}.json`); }
+    cloudBindingPath(id) { return join(this.root, "bindings", `${id}.json`); }
+    async binding() {
+        const value = await readJson(this.bindingPath());
+        if (value?.version !== 1 || value.identity !== this.options.identity || value.spaceId !== this.options.spaceId || value.nativeSessionId !== this.options.nativeSessionId || value.instanceKey !== this.options.instanceKey || value.harness !== this.options.harness)
+            throw new Error("Native binding mismatch");
+        return value;
+    }
+    async initialize(path, transcript) {
+        const existing = await readJson(this.bindingPath());
+        if (existing) {
+            const binding = await this.binding();
+            if (binding.path !== path)
+                throw new Error("Native path changed; original binding retained");
+            return binding;
+        }
+        const managed = await findRuntimeNativeSession(this.options.runtimeRoot, this.options.harness, transcript.nativeSessionId, path);
+        let throughBytes = 0;
+        const anchors = [];
+        if (managed) {
+            if (managed.pendingTurnId)
+                throw new Error("Reconcile the managed Turn before native continuation");
+            if (managed.throughTurnId) {
+                const index = await readJson(join(this.options.runtimeRoot, "archives", "versions", `${managed.throughTurnId}.json`));
+                if (index) {
+                    const parsed = harnessArchiveIndexSchema.parse(index);
+                    const checksum = createHash("sha256");
+                    for await (const bytes of createReadStream(path, { end: parsed.sizeBytes - 1 }))
+                        checksum.update(bytes);
+                    if (checksum.digest("hex") !== parsed.sha256)
+                        throw new Error("Runtime history prefix changed");
+                    throughBytes = parsed.sizeBytes;
+                }
+                else {
+                    const checksum = createHash("sha256");
+                    for await (const bytes of createReadStream(path))
+                        checksum.update(bytes);
+                    if (checksum.digest("hex") !== managed.checksum)
+                        throw new Error("Cannot identify the last complete Runtime Turn");
+                    throughBytes = (await stat(path)).size;
+                    anchors.push({ turnId: managed.throughTurnId, sizeBytes: throughBytes, sha256: managed.checksum });
+                }
+                const versions = join(this.options.runtimeRoot, "archives", "versions");
+                const names = await readdir(versions).catch((error) => { if (missing(error))
+                    return []; throw error; });
+                for (const name of names) {
+                    if (!name.endsWith(".json"))
+                        continue;
+                    const version = harnessArchiveIndexSchema.parse(await readJson(join(versions, name)));
+                    if (version.sessionId === managed.sessionId && version.harness === managed.harness && version.nativeSessionId === managed.nativeSessionId && version.sizeBytes <= throughBytes) {
+                        anchors.push({ turnId: version.turnId, sizeBytes: version.sizeBytes, sha256: version.sha256 });
+                    }
+                }
+            }
+        }
+        const binding = { version: 1, identity: this.options.identity, spaceId: this.options.spaceId, harness: this.options.harness,
+            nativeSessionId: transcript.nativeSessionId, instanceKey: this.options.instanceKey, path, originSessionId: nativeStableId(`${this.root}:archive`),
+            sessionId: managed?.sessionId ?? transcript.cloudSessionId ?? null, throughTurnId: managed?.throughTurnId ?? null, throughBytes, anchors };
+        // A managed Runtime must rebuild a separate projection rather than write into an interactive client's file.
+        await atomicRuntimeJson(join(this.options.runtimeRoot, "native-owners", `${hash(path)}.json`), { path, nativeSessionId: binding.nativeSessionId });
+        await atomicRuntimeJson(this.bindingPath(), binding);
+        return binding;
+    }
+    async capture(path, transcript) {
+        if (transcript.nativeSessionId !== this.options.nativeSessionId)
+            throw new Error("Native session identity mismatch");
+        await withRuntimeSpaceBindingsLock(async () => {
+            const binding = await this.initialize(path, transcript);
+            if (binding.throughBytes > 0) {
+                const anchor = binding.anchors.find((entry) => entry.sizeBytes === binding.throughBytes);
+                if (!anchor || transcript.prefixes.get(binding.throughBytes) !== anchor.sha256)
+                    throw new Error("Runtime history prefix changed; original binding retained");
+            }
+            let parentKey = null;
+            let parentCloudTurnId = binding.throughTurnId;
+            let knownBoundary = binding.throughBytes === 0;
+            for (const turn of transcript.turns) {
+                if (turn.startBytes < binding.throughBytes) {
+                    // Native offsets only validate whole-Turn archive checkpoints; they never become cloud fork anchors.
+                    const matches = (binding.anchors ?? []).filter((anchor) => anchor.sizeBytes >= turn.contentEndBytes && turn.boundaries[anchor.sizeBytes] === anchor.sha256);
+                    if (new Set(matches.map((anchor) => anchor.turnId)).size > 1)
+                        throw new Error("Ambiguous Runtime Turn boundary");
+                    parentCloudTurnId = matches[0]?.turnId ?? null;
+                    knownBoundary = matches.length > 0;
+                    parentKey = null;
+                    continue;
+                }
+                if (turn.cloudTurnId) {
+                    parentCloudTurnId = turn.cloudTurnId;
+                    knownBoundary = binding.harness === "codex" ? turn.result !== null : !["toolUse", "pending"].includes(turn.messages.at(-1)?.stopReason ?? "pending");
+                    parentKey = null;
+                    continue;
+                }
+                if (!parentKey && !knownBoundary)
+                    throw new Error("Native continuation is not at a complete Runtime Turn boundary");
+                const turnId = this.turnId(turn.key);
+                const old = await readJson(this.receiptPath(turnId));
+                if (old?.result) {
+                    if (turn.contentEndBytes < (old.contentEndBytes ?? old.endBytes) || JSON.stringify(turn.userContent) !== JSON.stringify(old.userContent) || turn.result && JSON.stringify(nativeTurnCompleteSchema.parse(turn.result)) !== JSON.stringify(old.result)) {
+                        throw new Error("Native branch is inside a settled Turn; only whole-Turn forks are supported");
+                    }
+                    parentKey = turn.key;
+                    continue;
+                }
+                const result = turn.result ? nativeTurnCompleteSchema.parse(turn.result) : null;
+                const receipt = { version: 1, turnId, key: turn.key, parentKey, parentCloudTurnId: parentKey ? null : parentCloudTurnId,
+                    userContent: turn.userContent, startedAt: turn.startedAt, endBytes: turn.endBytes, contentEndBytes: turn.contentEndBytes, result,
+                    ...(!result ? { progress: nativeTurnProgressSchema.parse({ revision: turn.endBytes, messages: turn.messages }) } : {}) };
+                if (old && (JSON.stringify(old.userContent) !== JSON.stringify(receipt.userContent) || old.parentKey !== receipt.parentKey))
+                    throw new Error("Native Turn changed; original receipt retained");
+                // Capture immutable native bytes before publishing the completed receipt. Subsequent Turns may change the source.
+                if (result)
+                    await this.archives.stage({ sessionId: binding.originSessionId, harness: binding.harness, nativeSessionId: binding.nativeSessionId, path, sizeBytes: turn.endBytes, expectedChecksum: turn.sha256 }, turnId);
+                if (JSON.stringify(old) !== JSON.stringify(receipt)) {
+                    // The pending index precedes the receipt, so a crash cannot silently strand an unacknowledged Turn.
+                    await atomicRuntimeJson(this.pendingPath(turnId), { turnId });
+                    await atomicRuntimeJson(this.receiptPath(turnId), receipt);
+                }
+                parentKey = turn.key;
+            }
+        }, { lockPath: join(this.root, "capture.lock") });
+    }
+    async receipts(pendingOnly = false) {
+        const names = await readdir(join(this.root, pendingOnly ? "pending" : "turns")).catch((error) => { if (missing(error))
+            return []; throw error; });
+        const receipts = [];
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const receipt = await readJson(join(this.root, "turns", name));
+            if (pendingOnly && !receipt) {
+                // Crash window: the pending index was written but the receipt itself never landed.
+                // The pointer carries no data; drop it — the next capture rebuilds the receipt from the transcript.
+                await rm(join(this.root, "pending", name), { force: true });
+                continue;
+            }
+            if (receipt?.version !== 1 || receipt.turnId !== this.turnId(receipt.key))
+                throw new Error("Native receipt is corrupt; original retained");
+            receipts.push(receipt);
+        }
+        return receipts.sort((a, b) => a.endBytes - b.endBytes || a.turnId.localeCompare(b.turnId));
+    }
+    async status() {
+        const binding = await this.binding();
+        const receipts = await this.receipts();
+        let pendingTurns = 0;
+        let sessionId = binding.sessionId;
+        for (const receipt of receipts) {
+            const remote = await readJson(this.cloudBindingPath(receipt.turnId));
+            if (remote)
+                sessionId = remote.sessionId;
+            if (!await readJson(this.acknowledgementPath(receipt.turnId)))
+                pendingTurns++;
+        }
+        return { harness: binding.harness, nativeSessionId: binding.nativeSessionId, sessionId, pendingTurns, pendingArchives: await this.archives.pendingCount() };
+    }
+    async flush(signal, onAbort) {
+        const transport = this.options.transport;
+        if (!transport)
+            return;
+        await withRuntimeSpaceBindingsLock(async () => {
+            const binding = await this.binding();
+            const pending = new Map((await this.receipts(true)).map((receipt) => [receipt.key, receipt]));
+            const processed = new Set();
+            const visit = async (receipt) => {
+                signal.throwIfAborted();
+                if (await readJson(this.acknowledgementPath(receipt.turnId))) {
+                    await rm(this.pendingPath(receipt.turnId), { force: true });
+                    return true;
+                }
+                if (processed.has(receipt.key))
+                    return false;
+                processed.add(receipt.key);
+                let parent = null;
+                if (receipt.parentKey) {
+                    const parentId = this.turnId(receipt.parentKey);
+                    parent = await readJson(this.acknowledgementPath(parentId));
+                    if (!parent) {
+                        const predecessor = pending.get(receipt.parentKey);
+                        if (!predecessor || !await visit(predecessor))
+                            return false;
+                        parent = await readJson(this.acknowledgementPath(parentId));
+                    }
+                    if (!parent)
+                        throw new Error("Parent binding is missing");
+                }
+                let request = await readJson(this.requestPath(receipt.turnId));
+                if (!request) {
+                    request = nativeTurnStartSchema.parse({ turnId: receipt.turnId, sessionId: parent?.sessionId ?? binding.sessionId, parentTurnId: parent?.turnId ?? receipt.parentCloudTurnId,
+                        branchSessionId: nativeStableId(`${receipt.turnId}:branch`), harness: binding.harness, nativeSessionId: binding.nativeSessionId, userContent: receipt.userContent, startedAt: receipt.startedAt });
+                    await atomicRuntimeJson(this.requestPath(receipt.turnId), request);
+                }
+                let remote = await readJson(this.cloudBindingPath(receipt.turnId));
+                if (!remote) {
+                    if (!transport.startNativeTurn)
+                        throw new Error("Native Runtime WS is unavailable");
+                    remote = await transport.startNativeTurn(request, { signal });
+                    if (remote.turnId !== receipt.turnId)
+                        throw new Error("Server Turn identity mismatch");
+                    await atomicRuntimeJson(this.cloudBindingPath(receipt.turnId), remote);
+                }
+                if (!receipt.result) {
+                    if (receipt.progress?.messages.length && transport.updateNativeTurn) {
+                        const progressPath = join(this.root, "progress", `${receipt.turnId}.json`);
+                        const sent = await readJson(progressPath);
+                        if (!sent || sent.revision < receipt.progress.revision) {
+                            await transport.updateNativeTurn(remote.sessionId, remote.turnId, receipt.progress, { signal });
+                            await atomicRuntimeJson(progressPath, { revision: receipt.progress.revision });
+                        }
+                    }
+                    if (onAbort && transport.heartbeatNativeTurn) {
+                        const status = await transport.heartbeatNativeTurn(remote.sessionId, remote.turnId, { signal });
+                        if (status.abortRequested)
+                            onAbort?.();
+                    }
+                    return false;
+                }
+                if (!transport.completeNativeTurn)
+                    throw new Error("Native Runtime WS is unavailable");
+                // Artifact retries back off: the terminal state is durable, so hammering the completion
+                // endpoint every flush cycle (5s) while object storage is down only adds load.
+                const backoffPath = join(this.root, "backoff", `${receipt.turnId}.json`);
+                const backoff = await readJson(backoffPath);
+                if (backoff && Date.now() - backoff.at < 30_000)
+                    return false;
+                const completion = await transport.completeNativeTurn(remote.sessionId, remote.turnId, receipt.result, { signal });
+                if (completion.artifactsPending) {
+                    // Terminal state is durable; only the artifact snapshot is missing. Keep the receipt pending
+                    // and retry on the next flush cycle (>= 30s) until artifacts persist.
+                    await atomicRuntimeJson(backoffPath, { at: Date.now() });
+                    throw new Error("Native artifacts are pending; completion replays later");
+                }
+                await rm(backoffPath, { force: true });
+                await atomicRuntimeJson(this.acknowledgementPath(receipt.turnId), remote);
+                await rm(this.pendingPath(receipt.turnId), { force: true });
+                return true;
+            };
+            const failures = [];
+            for (const receipt of pending.values()) {
+                if (!processed.has(receipt.key)) {
+                    try {
+                        await visit(receipt);
+                    }
+                    catch (error) {
+                        failures.push(error);
+                    }
+                }
+            }
+            // Resolve Session identities before the archive dependency walk. A fork baseline must not
+            // wait for an unrelated parent Session's failed upload. Immutable local versions stay untouched.
+            const archivePending = join(this.archives.root, "pending");
+            const indexes = await readdir(archivePending).catch((error) => { if (missing(error))
+                return []; throw error; });
+            for (const name of indexes) {
+                if (!name.endsWith(".json"))
+                    continue;
+                try {
+                    const path = join(archivePending, name);
+                    const index = harnessArchiveIndexSchema.parse(await readJson(path));
+                    const resolved = await this.cloudArchive(index);
+                    if (JSON.stringify(index) !== JSON.stringify(resolved))
+                        await atomicRuntimeJson(path, resolved);
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+            this.archiveFailure = undefined;
+            await this.archives.flush(signal);
+            if (failures.length)
+                throw failures[0];
+            if (this.archiveFailure)
+                throw this.archiveFailure;
+        }, { lockPath: join(this.root, "flush.lock") });
+    }
+    async cloudArchive(index) {
+        const binding = await readJson(this.acknowledgementPath(index.turnId));
+        if (!binding)
+            throw new Error("Native Turn result is not confirmed");
+        if (index.parentTurnId) {
+            const parent = await readJson(this.acknowledgementPath(index.parentTurnId));
+            if (parent?.sessionId === binding.sessionId)
+                return { ...index, sessionId: binding.sessionId };
+            // Cross-Session archive parents are forbidden. Materialize a baseline using existing immutable segments.
+            const segments = [...index.segments];
+            const visited = new Set([index.turnId]);
+            let parentId = index.parentTurnId;
+            while (parentId) {
+                if (visited.has(parentId))
+                    throw new Error("Cyclic native archive");
+                visited.add(parentId);
+                const previous = harnessArchiveIndexSchema.parse(await readJson(join(this.archives.root, "versions", `${parentId}.json`)));
+                segments.unshift(...previous.segments);
+                parentId = previous.parentTurnId;
+            }
+            return harnessArchiveIndexSchema.parse({ ...index, sessionId: binding.sessionId, parentTurnId: null, segments });
+        }
+        return { ...index, sessionId: binding.sessionId };
+    }
+}
+export async function listNativeSyncStores(runtimeRoot, spaceId, identity, transport) {
+    const root = join(runtimeRoot, "native", nativeIdentityHash(identity));
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const stores = [];
+    for (const name of await readdir(root)) {
+        if (!/^(pi|codex)-[a-f0-9]{64}$/.test(name))
+            continue;
+        const binding = await readJson(join(root, name, "binding.json"));
+        if (!binding || binding.identity !== identity || binding.spaceId !== spaceId)
+            continue;
+        stores.push(new NativeSyncStore({ runtimeRoot, spaceId, identity, harness: binding.harness, nativeSessionId: binding.nativeSessionId, instanceKey: binding.instanceKey, transport }));
+    }
+    return stores;
+}

package/dist/runtime/native-sync.d.ts

@@ -0,0 +1,25 @@
+import { NativeSyncStore, type NativeSyncTransport } from "./native-sync-store.js";
+import type { NativeRuntimeEvent } from "@neta-art/cohub";
+export type NativeSyncConfig = {
+    version: 1;
+    identity: string;
+    spaceId: string;
+    root: string;
+    harnesses: ("pi" | "codex")[];
+};
+export declare const nativeRuntimeRoot: (spaceId: string) => string;
+export declare const nativeSyncConfigPath: (runtimeRoot: string, identity: string) => string;
+export declare function nativeArchiveTransport(spaceId: string, identity: string): Pick<NativeSyncTransport, "prepareRuntimeArchive" | "commitRuntimeArchive" | "getRuntimeArchive">;
+export declare function readNativeSyncConfig(runtimeRoot: string, identity: string): Promise<NativeSyncConfig | null>;
+/** Local capture only. Neither Pi callbacks nor Codex hooks wait for Cohub's network. */
+export declare function captureNativeSession(input: {
+    harness: "pi" | "codex";
+    cwd: string;
+    path: string;
+    nativeSessionId?: string;
+    settled?: boolean;
+    leafId?: string | null;
+}): Promise<NativeSyncStore | null>;
+/** The existing Runtime supervisor retries receipts even after the original terminal has exited. */
+export declare function nativeWebSocketTransport(spaceId: string, identity: string, send: (event: NativeRuntimeEvent) => Promise<unknown>): NativeSyncTransport;
+export declare function flushNativeSessions(spaceId: string, identity: string, signal: AbortSignal, report: (error: unknown) => void, transportOverride?: NativeSyncTransport): Promise<void>;