@neta-art/cohub-cli 8.1.1 → 8.2.0

package/dist/commands/runtime.js

@@ -115,10 +115,11 @@ export function registerRuntime(program) {
                 },
             });
             const candidates = discovered.candidates.filter((candidate) => !options.session || candidate.nativeSessionId === options.session);
+            const superseded = discovered.superseded.filter((skip) => !options.session || skip.nativeSessionId === options.session);
             const result = {
                 spaceId, root, harnesses, candidates, errors: discovered.errors,
-                imported: 0, failed: [], skipped: [], dryRun: Boolean(options.dryRun),
-                complete: discovered.errors.length === 0,
+                imported: 0, pendingTurns: 0, failed: [], skipped: [], superseded, dryRun: Boolean(options.dryRun),
+                complete: discovered.errors.length === 0 && superseded.length === 0,
             };
             if (jsonRequested(options) && options.dryRun) {
                 result.complete = result.complete && result.failed.length === 0;
@@ -132,8 +133,13 @@ export function registerRuntime(program) {
                     process.exitCode = 1;
                 if (jsonRequested(options))
                     outJson(result);
-                else
+                else {
                     process.stdout.write("No existing native conversations found\n");
+                    for (const error of discovered.errors)
+                        process.stdout.write(`Skipped ${error.path}: ${error.message}\n`);
+                    for (const skip of superseded)
+                        process.stdout.write(`Superseded ${skip.path}: ${skip.message}\n`);
+                }
                 return;
             }
             if (options.dryRun) {
@@ -145,6 +151,8 @@ export function registerRuntime(program) {
                         process.stdout.write(`  ${candidate.harness} ${candidate.nativeSessionId} ${candidate.turnCount} Turn${candidate.turnCount === 1 ? "" : "s"} ${candidate.path}\n`);
                     for (const error of discovered.errors)
                         process.stdout.write(`Skipped ${error.path}: ${error.message}\n`);
+                    for (const skip of superseded)
+                        process.stdout.write(`Superseded ${skip.path}: ${skip.message}\n`);
                 }
                 if (!result.complete)
                     process.exitCode = 1;
@@ -169,26 +177,43 @@ export function registerRuntime(program) {
                     rl.close();
                 }
             }
+            let processed = 0;
             for (const candidate of candidates) {
+                if (controller.signal.aborted)
+                    break;
                 try {
                     const response = await requestNativeDaemon({ harness: candidate.harness, cwd: root, path: candidate.path, nativeSessionId: candidate.nativeSessionId,
                         sessionStartedAt: candidate.sessionStartedAt, origin: "local_import", settled: true });
                     applyNativeImportResponse(result, candidate.path, response);
+                    if (response.ok)
+                        result.pendingTurns += response.pendingTurns;
                 }
                 catch (error) {
-                    result.failed.push({ path: candidate.path, message: error instanceof Error ? error.message : String(error) });
+                    if (!controller.signal.aborted)
+                        result.failed.push({ path: candidate.path, message: error instanceof Error ? error.message : String(error) });
+                }
+                finally {
+                    processed += 1;
+                    if (!jsonRequested(options) && !controller.signal.aborted) {
+                        process.stderr.write(`\rSubmitted ${result.imported}/${candidates.length} · pending ${result.pendingTurns} Turns`);
+                    }
                 }
             }
-            result.complete = result.complete && result.failed.length === 0;
+            const cancelled = controller.signal.aborted;
+            result.complete = result.complete && result.failed.length === 0 && !cancelled;
             if (jsonRequested(options))
-                outJson(result);
+                outJson({ ...result, cancelled, processed });
             else {
-                process.stdout.write(`Imported ${result.imported}/${candidates.length} native conversation${candidates.length === 1 ? "" : "s"}\n`);
+                if (processed)
+                    process.stderr.write("\n");
+                process.stdout.write(`Submitted ${result.imported}/${candidates.length} native conversation${candidates.length === 1 ? "" : "s"}${cancelled ? " (interrupted)" : ""}\n`);
                 for (const error of [...discovered.errors, ...result.skipped, ...result.failed])
                     process.stdout.write(`Skipped ${error.path}: ${error.message}\n`);
-                process.stdout.write("Uploads continue in the local Runtime background\n");
+                for (const skip of result.superseded)
+                    process.stdout.write(`Superseded ${skip.path}: ${skip.message}\n`);
+                process.stdout.write("Uploads continue in the local Runtime background; use runtime status to check confirmation\n");
             }
-            if (!result.complete)
+            if (!result.complete && !cancelled)
                 process.exitCode = 1;
         }
         catch (cause) {

package/dist/runtime/archive-store.d.ts

@@ -15,6 +15,10 @@ export type ArchiveTransport = {
         signal?: AbortSignal;
     }): Promise<RuntimeArchivePage>;
 };
+/** Raised when local capture bytes fail integrity checks (checksum, truncation, boundary); retryable via cache rebuild. */
+export declare class ArchiveCaptureIntegrityError extends Error {
+    constructor(message: string);
+}
 export declare function checksumNativeFile(path: string): Promise<string>;
 export declare function atomicRuntimeJson(path: string, value: unknown): Promise<void>;
 /** Immutable local segments are the outbox. Model acknowledgements never remove them. */

package/dist/runtime/archive-store.js

@@ -4,6 +4,10 @@ import { mkdir, open, readFile, readdir, rename, rm, stat, link } from "node:fs/
 import { dirname, join } from "node:path";
 import { RUNTIME_ARCHIVE_SEGMENT_BYTES, harnessArchiveIndexSchema, validateArchiveBoundary, } from "@neta-art/cohub";
 const missing = (error) => error?.code === "ENOENT";
+/** Raised when local capture bytes fail integrity checks (checksum, truncation, boundary); retryable via cache rebuild. */
+export class ArchiveCaptureIntegrityError extends Error {
+    constructor(message) { super(message); this.name = "ArchiveCaptureIntegrityError"; }
+}
 const hash = (bytes, algorithm = "sha256") => createHash(algorithm).update(bytes).digest("hex");
 export async function checksumNativeFile(path) {
     const digest = createHash("sha256");
@@ -118,7 +122,7 @@ export class RuntimeArchiveStore {
             if (saved.sessionId !== state.sessionId || saved.harness !== state.harness)
                 throw new Error("Archive identity mismatch");
             if (state.expectedChecksum && state.expectedChecksum !== saved.sha256)
-                throw new Error("Native Turn bytes changed; original archive retained");
+                throw new ArchiveCaptureIntegrityError("Native Turn bytes changed; original archive retained");
             const committed = await stat(join(this.root, "ready", `${turnId}.json`)).catch((error) => { if (missing(error))
                 return null; throw error; });
             if (!committed)
@@ -133,10 +137,10 @@ export class RuntimeArchiveStore {
         try {
             const before = await file.stat();
             if (!before.isFile() || !before.size)
-                throw new Error("Native archive is empty");
+                throw new ArchiveCaptureIntegrityError("Native archive is empty");
             const sizeBytes = state.sizeBytes ?? before.size;
             if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 1 || sizeBytes > before.size)
-                throw new Error("Native archive boundary is unavailable");
+                throw new ArchiveCaptureIntegrityError("Native archive boundary is unavailable");
             const buffer = Buffer.alloc(RUNTIME_ARCHIVE_SEGMENT_BYTES);
             let offset = 0;
             let digest = createHash("sha256");
@@ -172,14 +176,14 @@ export class RuntimeArchiveStore {
             }
             const after = await stat(state.path);
             if (before.ino !== after.ino || after.size < sizeBytes || state.sizeBytes === undefined && (before.size !== after.size || before.mtimeMs !== after.mtimeMs))
-                throw new Error("Native file changed during capture");
+                throw new ArchiveCaptureIntegrityError("Native file changed during capture");
             if (state.sizeBytes !== undefined) {
                 // Native clients may append while an earlier Turn is captured. Validate the exact prefix twice.
                 const verified = createHash("sha256");
                 for await (const bytes of createReadStream(state.path, { end: sizeBytes - 1 }))
                     verified.update(bytes);
                 if (verified.digest("hex") !== digest.copy().digest("hex"))
-                    throw new Error("Native prefix changed during capture");
+                    throw new ArchiveCaptureIntegrityError("Native prefix changed during capture");
             }
             if (process.platform !== "win32") {
                 const directory = await open(join(this.root, "objects"), "r");
@@ -195,7 +199,7 @@ export class RuntimeArchiveStore {
                 sizeBytes, sha256: digest.digest("hex"), segments });
             validateArchiveBoundary(index, parent);
             if (state.expectedChecksum && index.sha256 !== state.expectedChecksum)
-                throw new Error("Native Turn bytes changed during capture; original retained");
+                throw new ArchiveCaptureIntegrityError("Native Turn bytes changed during capture; original retained");
         }
         finally {
             await file.close();

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

@@ -1,4 +1,8 @@
 import { type CodexTokenTotals } from "./codex-usage.js";
+/** A structurally unrestorable archive (e.g. its history reference is not carried); never retried. */
+export declare class ArchiveNotRestorableError extends Error {
+    constructor(message: string);
+}
 export declare function readCodexArchiveTotals(path: string): Promise<CodexTokenTotals | undefined>;
 /** Change only the header of a working copy. Raw archive bytes remain untouched. */
 export declare function importNativeArchive(input: {

package/dist/runtime/native-archive.js

@@ -5,6 +5,10 @@ import { dirname } from "node:path";
 import { RUNTIME_MAX_FRAME_BYTES } from "@neta-art/cohub";
 import { JsonLineDecoder } from "./json-rpc.js";
 import { codexArchiveTotals } from "./codex-usage.js";
+/** A structurally unrestorable archive (e.g. its history reference is not carried); never retried. */
+export class ArchiveNotRestorableError extends Error {
+    constructor(message) { super(message); this.name = "ArchiveNotRestorableError"; }
+}
 export async function readCodexArchiveTotals(path) {
     let totals;
     const decoder = new JsonLineDecoder((row) => { totals = codexArchiveTotals([row]) ?? totals; });
@@ -35,6 +39,10 @@ export async function importNativeArchive(input) {
         else {
             if (header?.type !== "session_meta" || header.payload?.id !== input.nativeSessionId)
                 throw new Error("Codex archive identity mismatch");
+            // A leaf archive does not carry its ancestor rollout. Importing it as-is would resume with
+            // silently truncated history; failing lets the caller rebuild from durable cloud Turns.
+            if (header.payload?.history_base != null)
+                throw new ArchiveNotRestorableError("Codex archive references history it does not carry; rebuild from the Session instead");
             header.payload.id = input.id;
             if (header.payload.session_id != null)
                 header.payload.session_id = input.id;

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

@@ -20,6 +20,16 @@ type NativeBinding = {
         sizeBytes: number;
         sha256: string;
     }>;
+    /** After a Codex rollover: the superseded rollout's settled boundary, addressed by rollout id. */
+    ancestor?: {
+        rolloutId: string;
+        throughBytes: number;
+        anchors: Array<{
+            turnId: string;
+            sizeBytes: number;
+            sha256: string;
+        }>;
+    };
 };
 export type NativeTurnReceipt = {
     version: 1;
@@ -35,6 +45,8 @@ export type NativeTurnReceipt = {
     sessionStartedAt?: string;
     origin?: "local_import";
     progress?: NativeTurnProgress;
+    /** Merged lineage order across Codex rollout files. */
+    sequence?: number;
 };
 export type NativeSyncTransport = ArchiveTransport & {
     startNativeTurn?(input: NativeTurnStart, options?: {
@@ -80,12 +92,14 @@ export declare class NativeSyncStore {
     private acknowledgementPath;
     private pendingPath;
     private requestPath;
+    private retryPath;
     private cloudBindingPath;
     binding(): Promise<NativeBinding>;
     private initialize;
     capture(path: string, transcript: NativeTranscript, context?: {
         sessionStartedAt?: string;
         origin?: "local_import";
+        signal?: AbortSignal;
     }): Promise<void>;
     receipts(pendingOnly?: boolean): Promise<NativeTurnReceipt[]>;
     status(): Promise<{

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

@@ -1,9 +1,10 @@
 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 { basename, join } from "node:path";
 import { nativeTurnCompleteSchema, nativeTurnStartSchema, nativeTurnProgressSchema, harnessArchiveIndexSchema } from "@neta-art/cohub";
-import { RuntimeArchiveStore, atomicRuntimeJson } from "./archive-store.js";
+import { ArchiveCaptureIntegrityError, RuntimeArchiveStore, atomicRuntimeJson } from "./archive-store.js";
+import { codexRolloutCachePath, codexRolloutIdOf, codexRolloutBytes, ensurePlainCodexRollout } from "./native-transcript.js";
 import { findRuntimeNativeSession } from "./session-store.js";
 import { withRuntimeSpaceBindingsLock } from "./space-binding.js";
 const missing = (error) => error.code === "ENOENT";
@@ -23,6 +24,26 @@ async function readJson(path) {
         throw error;
     }
 }
+/** Whole-Turn archive checkpoints only; native offsets never become cloud fork anchors. */
+function matchAnchor(turn, anchors) {
+    return anchors.filter((anchor) => anchor.sizeBytes >= turn.contentEndBytes && turn.boundaries[anchor.sizeBytes] === anchor.sha256);
+}
+/** Archive checkpoints of one managed session, optionally bounded by a byte prefix. */
+async function collectArchiveAnchors(runtimeRoot, managed, throughBytes = Number.POSITIVE_INFINITY) {
+    const anchors = [];
+    const versions = join(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 });
+        }
+    }
+    return anchors;
+}
 /** Turn receipts are append-only. Capture never waits for the network; network ACKs live in separate files. */
 export class NativeSyncStore {
     options;
@@ -50,6 +71,7 @@ export class NativeSyncStore {
     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`); }
+    retryPath(id) { return join(this.root, "retries", `${id}.json`); }
     cloudBindingPath(id) { return join(this.root, "bindings", `${id}.json`); }
     async binding() {
         const value = await readJson(this.bindingPath());
@@ -57,10 +79,31 @@ export class NativeSyncStore {
             throw new Error("Native binding mismatch");
         return value;
     }
-    async initialize(path, transcript) {
+    async initialize(path, transcript, signal) {
         const existing = await readJson(this.bindingPath());
         if (existing) {
             const binding = await this.binding();
+            // Codex rollover keeps the thread id but moves appends to a fresh rollout that references
+            // the old one as its history base. Follow the reference instead of failing — matched by
+            // rollout id, so archiving or compressing the ancestor still migrates cleanly. When the
+            // previous rollout is the leaf itself (the same file merely moved or compressed), the
+            // byte boundary stays valid: only the path changes.
+            const previousRolloutId = codexRolloutIdOf(basename(binding.path));
+            const lineageRolloutIds = transcript.lineageRolloutIds ?? [];
+            if (binding.path !== path && previousRolloutId && lineageRolloutIds.includes(previousRolloutId)) {
+                const sameRollout = lineageRolloutIds.at(-1) === previousRolloutId;
+                let moved = { ...binding, path };
+                if (!sameRollout) {
+                    // Byte offsets from the old rollout no longer address the new one; the settled
+                    // boundary moves into the ancestor record and the binding restarts at the leaf.
+                    moved = { ...moved, throughBytes: 0, anchors: [] };
+                    if (binding.throughBytes > 0)
+                        moved.ancestor = { rolloutId: previousRolloutId, throughBytes: binding.throughBytes, anchors: binding.anchors };
+                }
+                await atomicRuntimeJson(join(this.options.runtimeRoot, "native-owners", `${hash(path)}.json`), { path, nativeSessionId: binding.nativeSessionId });
+                await atomicRuntimeJson(this.bindingPath(), moved);
+                return moved;
+            }
             if (binding.path !== path)
                 throw new Error("Native path changed; original binding retained");
             return binding;
@@ -71,6 +114,42 @@ export class NativeSyncStore {
         if (managed) {
             if (managed.pendingTurnId)
                 throw new Error("Reconcile the managed Turn before native continuation");
+            // A Codex rollover before the first native capture: the managed projection lives on an
+            // ancestor rollout now. Its byte boundary addresses the ancestor, so express it as the
+            // ancestor record instead of validating it against the new leaf.
+            const managedRolloutId = codexRolloutIdOf(basename(managed.path));
+            const lineageRolloutIds = transcript.lineageRolloutIds ?? [];
+            const managedInLineage = this.options.harness === "codex" && managedRolloutId != null && lineageRolloutIds.slice(0, -1).includes(managedRolloutId);
+            if (managedInLineage && managed.throughTurnId) {
+                anchors.push(...await collectArchiveAnchors(this.options.runtimeRoot, managed));
+                // The managed projection is the whole ancestor rollout: verify its bytes still match the
+                // recorded checksum, measured on the logical JSONL (decompressed when the file is cold).
+                const ancestorIndex = lineageRolloutIds.indexOf(managedRolloutId);
+                const ancestorPath = transcript.lineagePaths?.[ancestorIndex] ?? managed.path;
+                const checksum = createHash("sha256");
+                let ancestorBytes = 0;
+                for await (const bytes of codexRolloutBytes(ancestorPath, null, signal)) {
+                    checksum.update(bytes);
+                    ancestorBytes += bytes.length;
+                }
+                if (!managed.checksum)
+                    throw new Error("Managed rollout has no checksum to validate its settled boundary");
+                if (checksum.digest("hex") !== managed.checksum)
+                    throw new Error("Runtime history prefix changed");
+                // The verified whole-file boundary is a synthetic anchor, mirroring the regular first
+                // binding: trailing records after the last Turn (e.g. usage) make contentEndBytes
+                // undershoot the file size, and matchAnchor resolves through `boundaries`.
+                anchors.push({ turnId: managed.throughTurnId, sizeBytes: ancestorBytes, sha256: managed.checksum });
+                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, throughTurnId: managed.throughTurnId, throughBytes: 0, anchors: [],
+                    ancestor: { rolloutId: managedRolloutId, throughBytes: ancestorBytes, anchors } };
+                // Persist like any first binding: the owner marker keeps the managed Runtime out of this
+                // leaf file, and flush/status read binding.json before touching any receipt.
+                await atomicRuntimeJson(join(this.options.runtimeRoot, "native-owners", `${hash(path)}.json`), { path, nativeSessionId: binding.nativeSessionId });
+                await atomicRuntimeJson(this.bindingPath(), binding);
+                return binding;
+            }
             if (managed.throughTurnId) {
                 const index = await readJson(join(this.options.runtimeRoot, "archives", "versions", `${managed.throughTurnId}.json`));
                 if (index) {
@@ -91,17 +170,7 @@ export class NativeSyncStore {
                     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 });
-                    }
-                }
+                anchors.push(...await collectArchiveAnchors(this.options.runtimeRoot, managed, throughBytes));
             }
         }
         const binding = { version: 1, identity: this.options.identity, spaceId: this.options.spaceId, harness: this.options.harness,
@@ -113,10 +182,11 @@ export class NativeSyncStore {
         return binding;
     }
     async capture(path, transcript, context = {}) {
+        const signal = context.signal;
         if (transcript.nativeSessionId !== this.options.nativeSessionId)
             throw new Error("Native session identity mismatch");
         await withRuntimeSpaceBindingsLock(async () => {
-            const binding = await this.initialize(path, transcript);
+            const binding = await this.initialize(path, transcript, signal);
             if (binding.throughBytes > 0) {
                 const anchor = binding.anchors.find((entry) => entry.sizeBytes === binding.throughBytes);
                 if (!anchor || transcript.prefixes.get(binding.throughBytes) !== anchor.sha256)
@@ -125,10 +195,14 @@ export class NativeSyncStore {
             let parentKey = null;
             let parentCloudTurnId = binding.throughTurnId;
             let knownBoundary = binding.throughBytes === 0;
+            const ancestor = binding.ancestor;
+            const leafRolloutId = transcript.lineageRolloutIds?.at(-1);
             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);
+                // Lineage Turns keep their own rollout's offsets; only Turns from the binding's rollout
+                // (the leaf, however it is now represented on disk) address the binding's byte boundary.
+                const inLeafRollout = !turn.rolloutId || turn.rolloutId === leafRolloutId;
+                if (inLeafRollout && turn.startBytes < binding.throughBytes) {
+                    const matches = matchAnchor(turn, binding.anchors ?? []);
                     if (new Set(matches.map((anchor) => anchor.turnId)).size > 1)
                         throw new Error("Ambiguous Runtime Turn boundary");
                     parentCloudTurnId = matches[0]?.turnId ?? null;
@@ -142,28 +216,65 @@ export class NativeSyncStore {
                     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");
                     }
+                    // Receipts written before lineage support lack the merged order; backfill it from the immutable chain.
+                    if (turn.sequence != null && old.sequence == null)
+                        await atomicRuntimeJson(this.receiptPath(turnId), { ...old, sequence: turn.sequence });
                     parentKey = turn.key;
                     continue;
                 }
+                // After a rollover, ancestor Turns below the superseded rollout's settled boundary are
+                // already durable cloud history (the retained ancestor record); anything above it is
+                // new native work — including Turns whose pending receipts still need finishing.
+                if (ancestor && turn.rolloutId === ancestor.rolloutId && turn.contentEndBytes <= ancestor.throughBytes) {
+                    const matches = matchAnchor(turn, ancestor.anchors);
+                    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 (!parentKey && !knownBoundary)
+                    throw new Error("Native continuation is not at a complete Runtime Turn boundary");
                 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,
+                    ...(turn.sequence != null ? { sequence: turn.sequence } : {}),
                     ...(context.sessionStartedAt ? { sessionStartedAt: context.sessionStartedAt } : {}),
                     ...(context.origin ? { origin: context.origin } : {}),
                     ...(!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 (result) {
+                    const cache = join(this.options.runtimeRoot, "native", "cache", "rollouts");
+                    const source = turn.path ?? path;
+                    const state = { sessionId: binding.originSessionId, harness: binding.harness, nativeSessionId: binding.nativeSessionId, sizeBytes: turn.endBytes, expectedChecksum: turn.sha256 };
+                    const stage = async () => this.archives.stage({ ...state, path: await ensurePlainCodexRollout(source, cache, signal) }, turnId);
+                    try {
+                        await stage();
+                    }
+                    catch (error) {
+                        // A corrupted `.zst` cache copy (bad checksum, truncation) is rebuilt once. A
+                        // mismatch against an already-saved index is not a cache problem: that index is
+                        // immutable, so rebuilding would only repeat a full decompression before failing.
+                        if (!source.endsWith(".zst") || !(error instanceof ArchiveCaptureIntegrityError))
+                            throw error;
+                        const savedIndex = await readJson(join(this.archives.root, "versions", `${turnId}.json`)).catch(() => { throw error; });
+                        if (!savedIndex) {
+                            await rm(codexRolloutCachePath(source, cache), { force: true });
+                            await stage();
+                        }
+                        else
+                            throw error;
+                    }
+                }
                 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 });
@@ -191,7 +302,7 @@ export class NativeSyncStore {
                 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));
+        return receipts.sort((a, b) => (a.sequence ?? Infinity) - (b.sequence ?? Infinity) || a.endBytes - b.endBytes || a.turnId.localeCompare(b.turnId));
     }
     async status() {
         const binding = await this.binding();
@@ -224,6 +335,9 @@ export class NativeSyncStore {
                 if (processed.has(receipt.key))
                     return false;
                 processed.add(receipt.key);
+                const retry = await readJson(this.retryPath(receipt.turnId));
+                if (retry && retry.nextAt > Date.now())
+                    return false;
                 let parent = null;
                 if (receipt.parentKey) {
                     const parentId = this.turnId(receipt.parentKey);
@@ -285,6 +399,7 @@ export class NativeSyncStore {
                     throw new Error("Native artifacts are pending; completion replays later");
                 }
                 await rm(backoffPath, { force: true });
+                await rm(this.retryPath(receipt.turnId), { force: true });
                 await atomicRuntimeJson(this.acknowledgementPath(receipt.turnId), remote);
                 await rm(this.pendingPath(receipt.turnId), { force: true });
                 return true;
@@ -296,6 +411,11 @@ export class NativeSyncStore {
                         await visit(receipt);
                     }
                     catch (error) {
+                        const previous = await readJson(this.retryPath(receipt.turnId));
+                        const attempt = Math.min((previous?.attempt ?? 0) + 1, 6);
+                        const base = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
+                        const jitter = base * (0.8 + Math.random() * 0.4);
+                        await atomicRuntimeJson(this.retryPath(receipt.turnId), { attempt, nextAt: Date.now() + Math.round(jitter) });
                         failures.push(error);
                     }
                 }
@@ -303,6 +423,7 @@ export class NativeSyncStore {
             // 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");
+            let archiveBlocked = false;
             const indexes = await readdir(archivePending).catch((error) => { if (missing(error))
                 return []; throw error; });
             for (const name of indexes) {
@@ -311,6 +432,11 @@ export class NativeSyncStore {
                 try {
                     const path = join(archivePending, name);
                     const index = harnessArchiveIndexSchema.parse(await readJson(path));
+                    const retry = await readJson(this.retryPath(index.turnId));
+                    if (retry && retry.nextAt > Date.now()) {
+                        archiveBlocked = true;
+                        continue;
+                    }
                     const resolved = await this.cloudArchive(index);
                     if (JSON.stringify(index) !== JSON.stringify(resolved))
                         await atomicRuntimeJson(path, resolved);
@@ -320,7 +446,8 @@ export class NativeSyncStore {
                 }
             }
             this.archiveFailure = undefined;
-            await this.archives.flush(signal);
+            if (!archiveBlocked)
+                await this.archives.flush(signal);
             if (failures.length)
                 throw failures[0];
             if (this.archiveFailure)

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

@@ -31,6 +31,11 @@ export declare function discoverNativeImportCandidates(root: string, harnesses:
         path: string;
         message: string;
     }[];
+    superseded: {
+        path: string;
+        nativeSessionId: string;
+        message: 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>;
@@ -44,7 +49,17 @@ export declare function captureNativeSession(input: {
     leafId?: string | null;
     sessionStartedAt?: string;
     origin?: "local_import";
+    signal?: AbortSignal;
 }): 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 const NATIVE_SYNC_SESSION_CONCURRENCY = 4;
+export declare function runNativeSyncPool<T>(items: readonly T[], concurrency: number, signal: AbortSignal, processItem: (item: T) => Promise<void>): Promise<void>;
+export declare function summarizeNativeSyncErrors(errors: unknown[]): {
+    name: string;
+    message: string;
+    code?: string;
+    status?: number;
+    count: number;
+}[];
 export declare function flushNativeSessions(spaceId: string, identity: string, signal: AbortSignal, report: (error: unknown) => void, transportOverride?: NativeSyncTransport): Promise<boolean>;