@neta-art/cohub-cli 6.12.0 → 7.0.1

package/README.md

@@ -79,6 +79,23 @@ cohub -s <spaceId> spaces prompt "message" --json
 COHUB_SPACE_ID=<spaceId> cohub spaces prompt "message" --json
 ```
 
+## Local Runtime
+
+Connect one local workspace to a Space and select Pi or Codex per turn.
+
+```bash
+cohub runtime up ./project --harness pi --harness codex
+cohub runtime up ./project --space <spaceId> --harness codex
+cohub -s <spaceId> spaces prompt "Continue" --harness codex
+cohub runtime status --space <spaceId>
+```
+
+The Runtime uses WebSockets, native Pi RPC / Codex app-server, and existing cloud
+streaming. Local executables and credentials are required. `sandbox up` has been
+removed. Reconnection and result reconciliation are automatic; no recovery command is needed.
+When a result genuinely cannot be determined, the affected Chat offers an explicit stop
+confirmation. See [Runtime details](../../docs/local-runtime.md).
+
 ## Chats and prompts
 
 Use `spaces prompt` for immediate sends, delayed sends, one-time schedules, recurring schedules, new Chats, and existing Chats.
@@ -357,7 +374,7 @@ legacy bare targets. A bare target checks the current Space for a file first, th
 falls back to the same App references as `apps get`. Showing a preview is
 idempotent: repeating it re-activates the same tab and refreshes any launch state
 carried by the reference. With `--call`, the command waits for the App to announce readiness, invokes the method,
-and waits for the App to complete the same UI command with `client.ui.reportResult()`.
+and waits for the App to complete the same UI command with `client.desktop.reportResult()`.
 
 App authors decide what is callable by registering handlers inside the App:
 

package/dist/commands/apps.js

@@ -508,7 +508,7 @@ export function registerApps(program) {
         .option("--app-scope <scope>", "Scope granted directly to the app runtime (space.view, session.view, file.view, file.edit, taskrun.view, session.prompt.readonly, session.prompt.fullaccess, command.execute)", collectOption, [])
         .option("--viewer-scope <scope>", "Deprecated: viewer grants are no longer gated by the app configuration", collectOption, [])
         .option("--clear-app-scopes", "Clear app runtime scopes")
-        .option("--clear-viewer-scopes", "Clear viewer-requestable scopes")
+        .option("--clear-viewer-scopes", "Deprecated: clear legacy scope metadata")
         .option("--meta <json>", "App metadata as a JSON object")
         .option("--hide-cohub-bar", "Hide the Cohub footer bar on the public app page")
         .option("--show-cohub-bar", "Show the Cohub footer bar on the public app page")
@@ -728,6 +728,7 @@ export function registerApps(program) {
         .description("Grant an app scopes as the current user")
         .requiredOption("--scope <scope>", "Scope to grant (repeatable)", collectOption, [])
         .option("--space <spaceId>", "Target space; defaults to the app's own space")
+        .option("--extend", "Add scopes without replacing active grants")
         .option("--json", "Output as JSON")
         .action(async (appRef, opts) => {
         const client = createClient();
@@ -736,6 +737,7 @@ export function registerApps(program) {
             const result = await client.apps.authorize(detail.app.id, {
                 scopes: opts.scope,
                 ...(opts.space ? { spaceId: opts.space } : {}),
+                ...(opts.extend ? { scopeMode: "extend" } : {}),
             });
             if (jsonRequested(opts))
                 return outJson(result);

package/dist/commands/runtime.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const resolveLocalSpaceName: (root: string, name?: string) => string;
+export declare function parseRuntimeHarnesses(values: string[]): ("pi" | "codex")[];
+export declare function registerRuntime(program: Command): void;

package/dist/commands/runtime.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { isLocalHarness, resolveCohubEnvironment, resolveWebsocketUrl } from "@neta-art/cohub";
+import { requireAccessToken } from "../auth.js";
+import { createClient } from "../client.js";
+import { error, json as outJson, jsonRequested } from "../output.js";
+import { resolveSpace } from "../space.js";
+import { discoverHarnesses } from "../runtime/harness.js";
+import { serveRuntime } from "../runtime/connection.js";
+import { RuntimeSessionStore } from "../runtime/session-store.js";
+import { ensureSandboxdBinary } from "./sandboxd-binary.js";
+export const resolveLocalSpaceName = (root, name) => name?.trim() || basename(root) || "local-space";
+export function parseRuntimeHarnesses(values) {
+    const names = values.flatMap((value) => value.split(",")).map((name) => name.trim()).filter(Boolean);
+    if (names.some((name) => !isLocalHarness(name)))
+        throw new Error("Harness must be pi or codex");
+    return [...new Set(names.length ? names : ["pi"])];
+}
+export function registerRuntime(program) {
+    const runtime = program.command("runtime").description("Connect a local workspace");
+    runtime.command("up [dir]")
+        .description("Connect local Harnesses and files")
+        .option("-s, --space <id>", "Target Space")
+        .option("-n, --name <name>", "New Space name")
+        .option("--harness <name>", "Pi or Codex; repeatable", (value, previous) => [...previous, value], [])
+        .option("--pi <path>", "Pi executable")
+        .option("--codex <path>", "Codex executable")
+        .option("-y, --yes", "Accept local execution access")
+        .option("--json", "JSON output")
+        .action(async (dir, options) => {
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+        try {
+            const root = resolve(dir ?? process.cwd());
+            if (!(await stat(root)).isDirectory())
+                throw new Error("Workspace is not a directory");
+            const harnesses = parseRuntimeHarnesses(options.harness);
+            if (!options.yes) {
+                if (!process.stdin.isTTY)
+                    throw new Error("Use --yes to authorize local execution");
+                const rl = createInterface({ input: process.stdin, output: process.stderr });
+                try {
+                    const answer = await rl.question(`Connect ${root}? Space collaborators can run commands as your OS user, beyond this folder. [y/N] `);
+                    if (!/^y(es)?$/i.test(answer.trim()))
+                        return;
+                }
+                finally {
+                    rl.close();
+                }
+            }
+            const capabilities = await discoverHarnesses(harnesses, options, root);
+            const client = createClient();
+            const requested = options.space?.trim() || program.opts().space?.trim();
+            const spaceId = requested || (await client.spaces.create({ name: resolveLocalSpaceName(root, options.name), config: { sandbox: { provider: "local" } } })).space.id;
+            const sandbox = (await client.space(spaceId).sandbox.get()).sandbox;
+            if (sandbox?.provider !== "local")
+                throw new Error("Space does not have a local Runtime");
+            const binary = await ensureSandboxdBinary();
+            const wsBase = resolveWebsocketUrl({ url: process.env.COHUB_WS_URL });
+            const url = new URL(wsBase);
+            url.pathname = "/runtime/relay";
+            const relay = new URL(wsBase);
+            relay.pathname = "/sandbox/relay";
+            let bridge = null;
+            let bridgeClosed = Promise.resolve();
+            const token = await requireAccessToken();
+            try {
+                await serveRuntime({
+                    spaceId, cwd: root, url: url.toString(), capabilities, harnesses: options,
+                    token: requireAccessToken, signal: controller.signal, store: new RuntimeSessionStore(spaceId, undefined, client.space(spaceId)),
+                    onReady: () => {
+                        if (!bridge) {
+                            bridge = spawn(binary, ["--local", "--space", spaceId, "--root", root, "--relay", process.env.COHUB_RELAY_URL?.trim() || relay.toString()], { stdio: ["ignore", "inherit", "inherit"], env: { ...process.env, COHUB_RELAY_TOKEN: token } });
+                            bridgeClosed = new Promise((resolveClosed) => bridge?.once("close", () => resolveClosed()));
+                            bridge.on("error", (cause) => { console.error(cause); controller.abort(); });
+                            bridge.once("exit", () => controller.abort());
+                        }
+                        const webUrl = `${resolveCohubEnvironment() === "prod" ? "https://cohub.live" : "https://dev.cohub.live"}/spaces/${spaceId}`;
+                        if (jsonRequested(options))
+                            outJson({ spaceId, root, harnesses, url: webUrl });
+                        else
+                            console.error(`Runtime connected: ${webUrl}`);
+                    },
+                });
+            }
+            finally {
+                if (bridge) {
+                    const child = bridge;
+                    child.kill("SIGTERM");
+                    const timeout = setTimeout(() => child.kill("SIGKILL"), 3000);
+                    await bridgeClosed;
+                    clearTimeout(timeout);
+                }
+            }
+        }
+        catch (cause) {
+            if (!controller.signal.aborted)
+                error("Runtime failed", cause instanceof Error ? cause.message : String(cause));
+        }
+        finally {
+            process.removeListener("SIGINT", stop);
+            process.removeListener("SIGTERM", stop);
+        }
+    });
+    runtime.command("status").description("Runtime status").option("-s, --space <id>", "Target Space").action(async (options) => {
+        const spaceId = options.space?.trim() || await resolveSpace(program);
+        const { archives } = new RuntimeSessionStore(spaceId);
+        const [status, pendingLocalArchives, failedLocalArchives] = await Promise.all([
+            createClient().space(spaceId).getRuntime(), archives.pendingCount(), archives.failedCaptureCount(),
+        ]);
+        outJson({ ...status, pendingLocalArchives, failedLocalArchives });
+    });
+}

package/dist/commands/sandboxd-binary.js

@@ -12,7 +12,7 @@ import { Readable } from "node:stream";
 //
 // IMPORTANT: this must point at a tag whose CDN artifacts have already been
 // published by .github/workflows/sandbox-binaries-build.yml. Only bump it AFTER
-// that tag's publish-cdn job has succeeded, otherwise `sandbox up` 404s on the
+// that tag's publish-cdn job has succeeded, otherwise `runtime up` 404s on the
 // default download.
 export const SANDBOXD_VERSION = "v1.82.4";
 const BINARY_NAME = "cohub-sandboxd";
@@ -117,7 +117,7 @@ const extractTarGz = (archivePath, cwd) => new Promise((res, rej) => {
     child.on("close", (code) => code === 0 ? res() : rej(new SandboxdDownloadError(`tar extraction failed: ${stderr.trim() || `exit ${code}`}`)));
 });
 // Cross-process lock via atomic mkdir, mirroring the CLI self-update lock so two
-// concurrent `sandbox up` invocations don't download the same archive twice.
+// concurrent `runtime up` invocations don't download the same archive twice.
 const withLock = async (version, fn) => {
     const lockPath = join(cacheDir(version), ".download.lock");
     await mkdir(dirname(lockPath), { recursive: true });

package/dist/commands/spaces.js

@@ -282,6 +282,7 @@ async function sendPrompt(command, words, opts) {
             content: promptContent,
             model: opts.model,
             provider: opts.provider,
+            harness: opts.harness,
             thinkingLevel: thinkingLevel,
             accessMode: opts.readOnly ? "read_only" : "full_access",
             intent: opts.steer ? "steer" : undefined,
@@ -388,6 +389,7 @@ export function registerPrompt(program) {
         .option("--title <title>", "Title for a newly created session or schedule")
         .option("-m, --model <model>", "Model name")
         .option("-p, --provider <provider>", "Provider name")
+        .option("--harness <harness>", "Harness: cohub, pi, or codex", "cohub")
         .option("--thinking-level <level>", "Thinking level: off|minimal|low|medium|high|xhigh|max")
         .option("--read-only", "Use read-only tools")
         .option("--steer", "Interrupt the current turn and run immediately")
@@ -615,6 +617,7 @@ export function registerSpaces(program) {
         .command("prompt [content...]", { hidden: true })
         .alias("send")
         .description("Send or schedule a prompt in the target space")
+        .option("--harness <harness>", "Harness: cohub, pi, or codex", "cohub")
         .option("--session <id>", "Target session ID")
         .option("--title <title>", "Title for a newly created session or schedule")
         .option("-m, --model <model>", "Model name")

package/dist/index.js

@@ -17,7 +17,7 @@ import { registerReferences } from "./commands/references.js";
 import { registerReferrals } from "./commands/referrals.js";
 import { registerPrompt, registerSpaces } from "./commands/spaces.js";
 import { maybeHandleRunCommand, printRunHelp } from "./commands/run.js";
-import { registerSandbox } from "./commands/sandbox.js";
+import { registerRuntime } from "./commands/runtime.js";
 import { registerTasks } from "./commands/tasks.js";
 import { registerDesktop, registerLegacyUi } from "./commands/desktop.js";
 import { registerApps } from "./commands/apps.js";
@@ -53,7 +53,7 @@ Common commands:
   cohub prompt "Fix the failing tests"
   cohub completion "Summarize AGENTS.md" --system-prompt AGENTS.md --stream
   cohub run -- git status
-  cohub sandbox up ./my-project
+  cohub runtime up ./my-project
   cohub search "release notes"
   cohub -s <space-id> boards inspect <board-id>
   cohub -s <space-id> spaces turns ls --author others
@@ -82,7 +82,7 @@ registerProfile(program);
 registerMe(program);
 registerPrompt(program);
 registerSpaces(program);
-registerSandbox(program);
+registerRuntime(program);
 registerChannels(program);
 registerGenerations(program);
 registerModels(program);

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

@@ -0,0 +1,44 @@
+import { type HarnessArchive, type HarnessArchiveIndex, type RuntimeArchivePage, type RuntimeArchiveUpload } from "@neta-art/cohub";
+export type ArchiveTransport = {
+    fetchObject?: typeof fetch;
+    prepareRuntimeArchive(index: HarnessArchiveIndex, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        uploads: RuntimeArchiveUpload[];
+    }>;
+    commitRuntimeArchive(index: HarnessArchiveIndex, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        ready: true;
+    }>;
+    getRuntimeArchive(sessionId: string, turnId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<RuntimeArchivePage>;
+};
+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. */
+export declare class RuntimeArchiveStore {
+    readonly root: string;
+    private readonly transport?;
+    private flushing;
+    private readonly capturing;
+    constructor(root: string, transport?: ArchiveTransport | undefined);
+    pendingCount(): Promise<number>;
+    failedCaptureCount(): Promise<number>;
+    hasCapture(turnId: string): Promise<boolean>;
+    private version;
+    private blob;
+    private saveBlob;
+    private readIndex;
+    stage(state: {
+        sessionId: string;
+        harness: "pi" | "codex";
+        nativeSessionId: string;
+        path: string;
+    }, turnId: string): Promise<HarnessArchive>;
+    private capture;
+    flush(signal: AbortSignal): Promise<void>;
+    private drain;
+    restore(reference: HarnessArchive, target: string, signal?: AbortSignal): Promise<HarnessArchiveIndex>;
+}

package/dist/runtime/archive-store.js

@@ -0,0 +1,353 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { mkdir, open, readFile, readdir, rename, rm, stat, link } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { RUNTIME_ARCHIVE_SEGMENT_BYTES, harnessArchiveIndexSchema, validateArchiveBoundary, } from "@neta-art/cohub";
+const missing = (error) => error?.code === "ENOENT";
+const hash = (bytes, algorithm = "sha256") => createHash(algorithm).update(bytes).digest("hex");
+export async function checksumNativeFile(path) {
+    const digest = createHash("sha256");
+    for await (const bytes of createReadStream(path))
+        digest.update(bytes);
+    return digest.digest("hex");
+}
+export async function atomicRuntimeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+        if (process.platform !== "win32") {
+            const directory = await open(dirname(path), "r");
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+        }
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Immutable local segments are the outbox. Model acknowledgements never remove them. */
+export class RuntimeArchiveStore {
+    root;
+    transport;
+    flushing = null;
+    capturing = new Map();
+    constructor(root, transport) {
+        this.root = root;
+        this.transport = transport;
+    }
+    async pendingCount() {
+        const pending = new Set();
+        for (const directory of ["pending", "captures"]) {
+            const names = await readdir(join(this.root, directory)).catch((error) => { if (missing(error))
+                return []; throw error; });
+            for (const name of names)
+                if (name.endsWith(".json"))
+                    pending.add(name);
+        }
+        return pending.size;
+    }
+    async failedCaptureCount() {
+        const names = await readdir(join(this.root, "failed", "captures")).catch((error) => { if (missing(error))
+            return []; throw error; });
+        return names.filter((name) => name.endsWith(".json")).length;
+    }
+    async hasCapture(turnId) { return Boolean(await this.readIndex(this.version(turnId))); }
+    version(turnId) { return join(this.root, "versions", `${turnId}.json`); }
+    blob(sha) { return join(this.root, "objects", sha); }
+    async saveBlob(sha, bytes) {
+        await mkdir(join(this.root, "objects"), { recursive: true, mode: 0o700 });
+        const target = this.blob(sha), temporary = `${target}.${randomUUID()}.tmp`;
+        try {
+            const output = await open(temporary, "wx", 0o600);
+            try {
+                await output.writeFile(bytes);
+                await output.sync();
+            }
+            finally {
+                await output.close();
+            }
+            await link(temporary, target).catch((error) => { if (error.code !== "EEXIST")
+                throw error; });
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async readIndex(path) {
+        try {
+            return harnessArchiveIndexSchema.parse(JSON.parse(await readFile(path, "utf8")));
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+    }
+    stage(state, turnId) {
+        const existing = this.capturing.get(turnId);
+        if (existing)
+            return existing;
+        const task = this.capture(state, turnId).finally(() => this.capturing.delete(turnId));
+        this.capturing.set(turnId, task);
+        return task;
+    }
+    async capture(state, turnId) {
+        const identity = { sessionId: state.sessionId, turnId, harness: state.harness };
+        const headPath = join(this.root, "heads", `${state.sessionId}.${state.harness}.json`);
+        const saved = await this.readIndex(this.version(turnId));
+        if (saved) {
+            if (saved.sessionId !== state.sessionId || saved.harness !== state.harness)
+                throw new Error("Archive identity mismatch");
+            const committed = await stat(join(this.root, "ready", `${turnId}.json`)).catch((error) => { if (missing(error))
+                return null; throw error; });
+            if (!committed)
+                await atomicRuntimeJson(join(this.root, "pending", `${turnId}.json`), saved);
+            if (!await this.readIndex(headPath))
+                await atomicRuntimeJson(headPath, saved);
+            return identity;
+        }
+        const previous = await this.readIndex(headPath);
+        const file = await open(state.path, "r");
+        let index;
+        try {
+            const before = await file.stat();
+            if (!before.isFile() || !before.size)
+                throw new Error("Native archive is empty");
+            const buffer = Buffer.alloc(RUNTIME_ARCHIVE_SEGMENT_BYTES);
+            let offset = 0;
+            let digest = createHash("sha256");
+            let parent = null;
+            // Hash the old prefix, not just its size: equal-size and growing rewrites are valid.
+            if (previous && previous.nativeSessionId === state.nativeSessionId && previous.sizeBytes <= before.size) {
+                while (offset < previous.sizeBytes) {
+                    const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, previous.sizeBytes - offset), offset);
+                    if (!bytesRead)
+                        throw new Error("Native file changed during capture");
+                    digest.update(buffer.subarray(0, bytesRead));
+                    offset += bytesRead;
+                }
+                if (digest.copy().digest("hex") === previous.sha256)
+                    parent = previous;
+            }
+            if (!parent) {
+                offset = 0;
+                digest = createHash("sha256");
+            }
+            const segments = [];
+            await mkdir(join(this.root, "objects"), { recursive: true, mode: 0o700 });
+            while (offset < before.size) {
+                const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, before.size - offset), offset);
+                if (!bytesRead)
+                    throw new Error("Native file changed during capture");
+                const bytes = buffer.subarray(0, bytesRead);
+                digest.update(bytes);
+                const segment = { offset, sizeBytes: bytesRead, sha256: hash(bytes), md5: hash(bytes, "md5") };
+                await this.saveBlob(segment.sha256, bytes);
+                segments.push(segment);
+                offset += bytesRead;
+            }
+            const after = await stat(state.path);
+            if (before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+                throw new Error("Native file changed during capture");
+            if (process.platform !== "win32") {
+                const directory = await open(join(this.root, "objects"), "r");
+                try {
+                    await directory.sync();
+                }
+                finally {
+                    await directory.close();
+                }
+            }
+            index = harnessArchiveIndexSchema.parse({ ...identity, version: 1, nativeSessionId: state.nativeSessionId,
+                nativeFormat: state.harness === "pi" ? "pi.jsonl" : "codex.rollout", parentTurnId: parent?.turnId ?? null,
+                sizeBytes: before.size, sha256: digest.digest("hex"), segments });
+            validateArchiveBoundary(index, parent);
+        }
+        finally {
+            await file.close();
+        }
+        // Publish the outbox before advancing the local head. Neither points at mutable files.
+        await atomicRuntimeJson(join(this.root, "pending", `${turnId}.json`), index);
+        await atomicRuntimeJson(this.version(turnId), index);
+        await atomicRuntimeJson(headPath, index);
+        return identity;
+    }
+    async flush(signal) {
+        if (!this.transport)
+            return;
+        if (this.flushing)
+            return this.flushing;
+        this.flushing = this.drain(signal).finally(() => { this.flushing = null; });
+        return this.flushing;
+    }
+    async drain(signal) {
+        const transport = this.transport;
+        if (!transport)
+            return;
+        const names = await readdir(join(this.root, "pending")).catch((error) => { if (missing(error))
+            return []; throw error; });
+        const pending = new Map();
+        for (const name of names) {
+            if (!name.endsWith(".json"))
+                continue;
+            const index = await this.readIndex(join(this.root, "pending", name));
+            if (index)
+                pending.set(index.turnId, index);
+        }
+        const children = new Map();
+        const queue = [];
+        for (const index of pending.values()) {
+            if (index.parentTurnId && pending.has(index.parentTurnId)) {
+                const siblings = children.get(index.parentTurnId) ?? [];
+                siblings.push(index);
+                children.set(index.parentTurnId, siblings);
+            }
+            else
+                queue.push(index);
+        }
+        if (pending.size && !queue.length)
+            throw new Error("Cyclic archive outbox");
+        for (let cursor = 0; cursor < queue.length; cursor++) {
+            signal.throwIfAborted();
+            const index = queue[cursor];
+            if (!index)
+                continue;
+            try {
+                const { uploads } = await transport.prepareRuntimeArchive(index, { signal: AbortSignal.any([signal, AbortSignal.timeout(30_000)]) });
+                if (uploads.length > index.segments.length)
+                    throw new Error("Upload plan mismatch");
+                const expected = new Set(index.segments.map((segment) => JSON.stringify(segment)));
+                for (const { segment, uploadUrl, headers } of uploads) {
+                    if (!expected.has(JSON.stringify(segment)))
+                        throw new Error("Upload segment mismatch");
+                    signal.throwIfAborted();
+                    const bytes = await readFile(this.blob(segment.sha256));
+                    if (bytes.length !== segment.sizeBytes || hash(bytes) !== segment.sha256)
+                        throw new Error("Local archive segment is corrupt");
+                    const response = await (transport.fetchObject ?? fetch)(uploadUrl, { method: "PUT", headers, body: bytes, redirect: "error", signal: AbortSignal.any([signal, AbortSignal.timeout(60_000)]) });
+                    // An immutable segment may already exist after a lost acknowledgement. Commit verifies it.
+                    if (!response.ok && ![409, 412].includes(response.status))
+                        throw new Error(`Archive upload failed: ${response.status}`);
+                }
+                await transport.commitRuntimeArchive(index, { signal: AbortSignal.any([signal, AbortSignal.timeout(30_000)]) });
+                await atomicRuntimeJson(join(this.root, "ready", `${index.turnId}.json`), { turnId: index.turnId, sha256: index.sha256 });
+                await rm(join(this.root, "pending", `${index.turnId}.json`), { force: true });
+                queue.push(...children.get(index.turnId) ?? []);
+            }
+            catch (error) {
+                if (!signal.aborted)
+                    console.error("Archive pending; native segments retained:", error);
+            }
+        }
+    }
+    async restore(reference, target, signal) {
+        if (!this.transport)
+            throw new Error("Archive transport unavailable");
+        const timeout = (ms) => signal ? AbortSignal.any([signal, AbortSignal.timeout(ms)]) : AbortSignal.timeout(ms);
+        const pages = [];
+        const visited = new Set();
+        let turnId = reference.turnId;
+        while (turnId) {
+            signal?.throwIfAborted();
+            if (visited.has(turnId))
+                throw new Error("Cyclic archive");
+            visited.add(turnId);
+            const page = await this.transport.getRuntimeArchive(reference.sessionId, turnId, { signal: timeout(30_000) });
+            const index = harnessArchiveIndexSchema.parse(page.index);
+            if (index.turnId !== turnId || index.sessionId !== reference.sessionId || index.harness !== reference.harness)
+                throw new Error("Archive identity mismatch");
+            pages.push({ ...page, index });
+            turnId = index.parentTurnId;
+        }
+        const head = pages[0]?.index;
+        if (!head)
+            throw new Error("Archive missing");
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        const temporary = `${target}.${randomUUID()}.restoring`;
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            let parent = null;
+            const digest = createHash("sha256");
+            for (const page of pages.reverse()) {
+                validateArchiveBoundary(page.index, parent);
+                if (page.segments.length !== page.index.segments.length)
+                    throw new Error("Missing archive segments");
+                for (const [ordinal, expected] of page.index.segments.entries()) {
+                    signal?.throwIfAborted();
+                    const cached = await readFile(this.blob(expected.sha256)).catch((error) => { if (missing(error))
+                        return null; throw error; });
+                    if (cached) {
+                        if (cached.length !== expected.sizeBytes || hash(cached) !== expected.sha256)
+                            throw new Error("Cached archive segment is corrupt");
+                        digest.update(cached);
+                        await file.writeFile(cached);
+                        continue;
+                    }
+                    let link = page.segments[ordinal];
+                    if (!link || JSON.stringify(link.segment) !== JSON.stringify(expected))
+                        throw new Error("Archive segment identity mismatch");
+                    let response = await (this.transport.fetchObject ?? fetch)(link.downloadUrl, { redirect: "error", signal: timeout(60_000) });
+                    if ([401, 403].includes(response.status)) {
+                        const refreshed = await this.transport.getRuntimeArchive(reference.sessionId, page.index.turnId, { signal: timeout(30_000) });
+                        link = refreshed.segments[ordinal];
+                        if (!link || JSON.stringify(link.segment) !== JSON.stringify(expected))
+                            throw new Error("Archive segment missing");
+                        response = await (this.transport.fetchObject ?? fetch)(link.downloadUrl, { redirect: "error", signal: timeout(60_000) });
+                    }
+                    if (!response.ok || !response.body)
+                        throw new Error(`Archive download failed: ${response.status}`);
+                    const segmentHash = createHash("sha256");
+                    let size = 0;
+                    const chunks = [];
+                    for await (const chunk of response.body) {
+                        size += chunk.length;
+                        if (size > expected.sizeBytes)
+                            throw new Error("Archive size mismatch");
+                        chunks.push(chunk);
+                        segmentHash.update(chunk);
+                        digest.update(chunk);
+                        await file.writeFile(chunk);
+                    }
+                    if (size !== expected.sizeBytes || segmentHash.digest("hex") !== expected.sha256)
+                        throw new Error("Archive checksum mismatch");
+                    await this.saveBlob(expected.sha256, Buffer.concat(chunks));
+                }
+                if (digest.copy().digest("hex") !== page.index.sha256)
+                    throw new Error("Archive version checksum mismatch");
+                parent = page.index;
+            }
+            if ((await file.stat()).size !== head.sizeBytes)
+                throw new Error("Archive length mismatch");
+            await file.sync();
+            await file.close();
+            await link(temporary, target);
+            if (process.platform !== "win32") {
+                const directory = await open(dirname(target), "r");
+                try {
+                    await directory.sync();
+                }
+                finally {
+                    await directory.close();
+                }
+            }
+            return head;
+        }
+        finally {
+            await file.close();
+            await rm(temporary, { force: true });
+        }
+    }
+}

package/dist/runtime/codex-usage.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimeMessage } from "@neta-art/cohub";
+declare const fields: readonly ["inputTokens", "outputTokens", "cachedInputTokens", "cacheWriteInputTokens", "totalTokens"];
+export type CodexTokenTotals = Record<typeof fields[number], number>;
+export declare const codexTokenTotals: (value: unknown) => CodexTokenTotals;
+export declare const subtractCodexTokens: (total: CodexTokenTotals, base: CodexTokenTotals) => CodexTokenTotals;
+export declare function codexUsage(total: CodexTokenTotals): NonNullable<RuntimeMessage["usage"]>;
+/** Seed portable imports from the original native counters, not a prior turn's `last`. */
+export declare function codexArchiveTotals(records: Record<string, unknown>[]): CodexTokenTotals | undefined;
+export {};