@neta-art/cohub-cli 7.1.2 → 8.0.0

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 / 请先确认 Runtime 中尚未确认的 Turn");
+            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 / Runtime 历史前缀已变化");
+                    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 / 无法识别 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 / Runtime 历史前缀已变化，原关联已保留");
+            }
+            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 / Runtime Turn 边界不明确");
+                    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 / 原生续聊不在完整 Runtime Turn 边界上");
+                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 / 原生分支位于已结束的 Turn 内，仅支持完整 Turn 分支");
+                    }
+                    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 / 原生 Turn 已变化，原回执已保留");
+                // 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 / 父 Turn 关联缺失");
+                }
+                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 / 原生 Runtime WS 不可用");
+                    remote = await transport.startNativeTurn(request, { signal });
+                    if (remote.turnId !== receipt.turnId)
+                        throw new Error("Server Turn identity mismatch / 服务端 Turn 身份不匹配");
+                    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 / 原生 Runtime WS 不可用");
+                // 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 / 原生 Turn 结果尚未确认");
+        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>;

package/dist/runtime/native-sync.js

@@ -0,0 +1,128 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createClient } from "../client.js";
+import { currentIdentityKey } from "../space.js";
+import { canonicalRuntimeRoot, getRuntimeSpaceBinding } from "./space-binding.js";
+import { readNativeTranscript } from "./native-transcript.js";
+import { findRuntimeNativeSession } from "./session-store.js";
+import { listNativeSyncStores, nativeIdentityHash, NativeSyncStore } from "./native-sync-store.js";
+export const nativeRuntimeRoot = (spaceId) => join(homedir(), ".local", "state", "cohub", "runtime", spaceId);
+export const nativeSyncConfigPath = (runtimeRoot, identity) => join(runtimeRoot, "native", nativeIdentityHash(identity), "config.json");
+export function nativeArchiveTransport(spaceId, identity) {
+    const client = createClient().space(spaceId);
+    const guard = async (task) => {
+        if (currentIdentityKey() !== identity)
+            throw new Error("Native sync account changed / 原生同步账号已变化");
+        const result = await task();
+        if (currentIdentityKey() !== identity)
+            throw new Error("Native sync account changed / 原生同步账号已变化");
+        return result;
+    };
+    return {
+        prepareRuntimeArchive: (...args) => guard(() => client.prepareRuntimeArchive(...args)),
+        commitRuntimeArchive: (...args) => guard(() => client.commitRuntimeArchive(...args)),
+        getRuntimeArchive: (...args) => guard(() => client.getRuntimeArchive(...args)),
+    };
+}
+export async function readNativeSyncConfig(runtimeRoot, identity) {
+    try {
+        const config = JSON.parse(await readFile(nativeSyncConfigPath(runtimeRoot, identity), "utf8"));
+        if (config.version !== 1 || config.identity !== identity || !Array.isArray(config.harnesses))
+            throw new Error("Invalid native sync configuration / 原生同步配置无效");
+        return config;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+const nativeStores = new Map();
+/** Local capture only. Neither Pi callbacks nor Codex hooks wait for Cohub's network. */
+export async function captureNativeSession(input) {
+    if (process.env.COHUB_TURN_ID || process.env.COHUB_EXECUTION_TOKEN)
+        return null;
+    const identity = currentIdentityKey();
+    if (!identity)
+        return null;
+    const root = await canonicalRuntimeRoot(input.cwd);
+    const space = await getRuntimeSpaceBinding(root, identity);
+    if (!space)
+        return null;
+    const runtimeRoot = nativeRuntimeRoot(space.spaceId);
+    const config = await readNativeSyncConfig(runtimeRoot, identity);
+    if (!config || config.root !== root || config.spaceId !== space.spaceId || !config.harnesses.includes(input.harness))
+        return null;
+    const path = await canonicalRuntimeRoot(input.path);
+    const transcript = await readNativeTranscript(path, input.harness, input);
+    if (await canonicalRuntimeRoot(transcript.cwd) !== root || input.nativeSessionId && transcript.nativeSessionId !== input.nativeSessionId)
+        throw new Error("Native transcript belongs to another project or Session / 原生记录属于其他项目或会话");
+    const key = JSON.stringify([identity, space.spaceId, input.harness, transcript.nativeSessionId, path]);
+    let store = nativeStores.get(key);
+    if (!store) {
+        const transport = nativeArchiveTransport(space.spaceId, identity);
+        const candidates = (await listNativeSyncStores(runtimeRoot, space.spaceId, identity, transport))
+            .filter((candidate) => candidate.options.harness === input.harness && candidate.options.nativeSessionId === transcript.nativeSessionId);
+        for (const candidate of candidates)
+            if ((await candidate.binding()).path === path) {
+                store = candidate;
+                break;
+            }
+        if (!store) {
+            const managed = await findRuntimeNativeSession(runtimeRoot, input.harness, transcript.nativeSessionId, path);
+            const managedPath = managed ? await canonicalRuntimeRoot(managed.path).catch((error) => { if (error.code === "ENOENT")
+                return null; throw error; }) : null;
+            if (candidates.length && managedPath !== path)
+                throw new Error("Native path changed; original bindings retained / 原生路径已变化，原关联已保留");
+            // Restored Pi working copies can share a native ID. Existing Cohub sidecars disambiguate them.
+            store = new NativeSyncStore({ runtimeRoot, spaceId: space.spaceId, identity, harness: input.harness, nativeSessionId: transcript.nativeSessionId,
+                instanceKey: managedPath === path ? path : undefined, transport });
+        }
+        if (nativeStores.size >= 256)
+            nativeStores.delete(nativeStores.keys().next().value ?? "");
+        nativeStores.set(key, store);
+    }
+    await store.capture(path, transcript);
+    return store;
+}
+/** The existing Runtime supervisor retries receipts even after the original terminal has exited. */
+export function nativeWebSocketTransport(spaceId, identity, send) {
+    const archive = nativeArchiveTransport(spaceId, identity);
+    return {
+        ...archive,
+        startNativeTurn: async (input) => await send({ type: "start", input }),
+        completeNativeTurn: async (sessionId, turnId, result) => await send({ type: "complete", sessionId, turnId, result }),
+        updateNativeTurn: async (sessionId, turnId, progress) => await send({ type: "progress", sessionId, turnId, progress }),
+        heartbeatNativeTurn: async (sessionId, turnId) => await send({ type: "heartbeat", sessionId, turnId }),
+    };
+}
+export async function flushNativeSessions(spaceId, identity, signal, report, transportOverride) {
+    if (currentIdentityKey() !== identity)
+        return;
+    const runtimeRoot = nativeRuntimeRoot(spaceId);
+    const config = await readNativeSyncConfig(runtimeRoot, identity);
+    if (!config || config.spaceId !== spaceId)
+        return;
+    const transport = transportOverride;
+    if (!transport)
+        return;
+    const stores = await listNativeSyncStores(runtimeRoot, spaceId, identity, transport);
+    for (const store of stores) {
+        signal.throwIfAborted();
+        const binding = await store.binding();
+        if (!config.harnesses.includes(binding.harness))
+            continue;
+        try {
+            // Codex hooks only push capture requests while its terminal lives; the Daemon keeps re-reading
+            // the transcript between hooks so Stop-flushed Turns are picked up even if a hook is missed.
+            if (binding.harness === "codex")
+                await store.capture(binding.path, await readNativeTranscript(binding.path, "codex"));
+            await store.flush(AbortSignal.any([signal, AbortSignal.timeout(30_000)]));
+        }
+        catch (error) {
+            if (!signal.aborted)
+                report(error);
+        }
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { ContentBlock, NativeTurnComplete, NativeTurnMessage } from "@neta-art/cohub";
+export type NativeTranscriptTurn = {
+    key: string;
+    parentKey: string | null;
+    cloudTurnId?: string;
+    userContent: ContentBlock[];
+    messages: NativeTurnMessage[];
+    startedAt: string;
+    startBytes: number;
+    endBytes: number;
+    contentEndBytes: number;
+    boundaries: Record<number, string>;
+    sha256: string;
+    result: NativeTurnComplete | null;
+};
+export type NativeTranscript = {
+    nativeSessionId: string;
+    cwd: string;
+    cloudSessionId?: string;
+    turns: NativeTranscriptTurn[];
+    prefixes: ReadonlyMap<number, string>;
+};
+/** Partial trailing records are retried, never parsed or acknowledged as complete. */
+export declare function readNativeTranscript(path: string, harness: "pi" | "codex", options?: {
+    settled?: boolean;
+    leafId?: string | null;
+}): Promise<NativeTranscript>;