@neta-art/cohub-cli 7.1.2 → 8.0.0

package/dist/runtime/native-transcript.js

@@ -0,0 +1,281 @@
+import { createReadStream } from "node:fs";
+import { createHash } from "node:crypto";
+import { piContent } from "./harness.js";
+import { codexTokenTotals, codexUsage } from "./codex-usage.js";
+import { record } from "./json-rpc.js";
+const text = (value) => typeof value === "string" ? value : "";
+const list = (value) => Array.isArray(value) ? value : [];
+const iso = (value) => {
+    const date = new Date(typeof value === "number" || typeof value === "string" ? value : 0);
+    if (!Number.isFinite(date.getTime()))
+        throw new Error("Invalid native timestamp / 原生时间无效");
+    return date.toISOString();
+};
+/** Partial trailing records are retried, never parsed or acknowledged as complete. */
+export async function readNativeTranscript(path, harness, options = {}) {
+    const lines = [];
+    const prefixes = new Map();
+    let fragments = [], pendingBytes = 0, offset = 0;
+    const checksum = createHash("sha256");
+    const append = (bytes) => {
+        if (!bytes.length)
+            return;
+        fragments.push(bytes);
+        pendingBytes += bytes.length;
+        checksum.update(bytes);
+        if (pendingBytes > 32 * 1024 * 1024)
+            throw new Error("Native record is too large / 原生记录过大");
+        if (offset + pendingBytes > 128 * 1024 * 1024)
+            throw new Error("Native transcript exceeds the capture limit; original retained / 原生记录超出采集上限，原件已保留");
+    };
+    for await (const chunk of createReadStream(path)) {
+        let start = 0;
+        for (let end = chunk.indexOf(10); end >= 0; end = chunk.indexOf(10, start)) {
+            append(chunk.subarray(start, end + 1));
+            // Concatenate once per record, not once per read chunk (large base64 images stay linear).
+            const bytes = fragments.length === 1 ? fragments[0] : Buffer.concat(fragments, pendingBytes);
+            const line = bytes.subarray(0, bytes.length - 1);
+            const startBytes = offset;
+            offset += pendingBytes;
+            fragments = [];
+            pendingBytes = 0;
+            const sha256 = checksum.copy().digest("hex");
+            prefixes.set(offset, sha256);
+            if (line.length) {
+                let value;
+                try {
+                    value = record(JSON.parse(line.toString("utf8")));
+                }
+                catch {
+                    throw new Error("Invalid native JSON record; original retained / 原生 JSON 记录无效，原件已保留");
+                }
+                lines.push({ value, startBytes, endBytes: offset, sha256 });
+            }
+            start = end + 1;
+        }
+        append(chunk.subarray(start));
+    }
+    if (!lines.length)
+        throw new Error("Native transcript is empty / 原生记录为空");
+    return { ...(harness === "pi" ? parsePiTranscript(lines, options) : parseCodexTranscript(lines)), prefixes };
+}
+function parsePiTranscript(lines, options) {
+    const header = lines[0]?.value ?? {};
+    if (header.type !== "session" || !text(header.id))
+        throw new Error("Invalid Pi session / Pi 会话无效");
+    const entries = new Map(lines.slice(1).filter((line) => text(line.value.id)).map((line) => [text(line.value.id), line]));
+    const branch = [];
+    let leaf = options.leafId ?? (lines.length > 1 ? text(lines.at(-1)?.value.id) : "");
+    const visited = new Set();
+    while (leaf) {
+        if (visited.has(leaf))
+            throw new Error("Cyclic Pi history / Pi 历史存在循环");
+        visited.add(leaf);
+        const entry = entries.get(leaf);
+        if (!entry)
+            throw new Error("Pi parent history is missing / Pi 父历史缺失");
+        branch.push(entry);
+        leaf = text(entry.value.parentId);
+    }
+    branch.reverse();
+    const turns = [];
+    let cloudSessionId = text(record(header.cohub).sessionId) || text(record(header.affinity).sessionId);
+    let current = null;
+    let messages = [];
+    let completedAt = iso(header.timestamp);
+    const finish = (settled) => {
+        if (!current)
+            return;
+        const last = messages.at(-1);
+        if (settled)
+            current.result = { messages, completedAt, status: !last || ["aborted", "pending", "toolUse"].includes(last.stopReason ?? "") ? "interrupted" : last?.errorMessage || last?.stopReason === "error" ? "failed" : "completed" };
+        turns.push(current);
+    };
+    for (const line of branch) {
+        const entry = line.value;
+        if (entry.type !== "message") {
+            if (current) {
+                current.endBytes = line.endBytes;
+                current.sha256 = line.sha256;
+                current.boundaries[line.endBytes] = line.sha256;
+            }
+            continue;
+        }
+        const message = record(entry.message);
+        if (!["user", "assistant", "toolResult"].includes(text(message.role))) {
+            // Native-only UI / shell records remain in raw archives; they do not rewrite a settled agent Turn.
+            if (current) {
+                current.endBytes = line.endBytes;
+                current.sha256 = line.sha256;
+                current.boundaries[line.endBytes] = line.sha256;
+            }
+            continue;
+        }
+        const timestamp = iso(entry.timestamp ?? message.timestamp);
+        if (message.role === "user") {
+            finish(true);
+            completedAt = timestamp;
+            const cloudTurnId = text(record(message.meta).turnId);
+            if (cloudTurnId && !text(record(header.cohub).sessionId) && !text(record(header.affinity).sessionId))
+                cloudSessionId = text(record(message.meta).sourceSessionId) || cloudSessionId;
+            current = { key: text(entry.id), parentKey: turns.at(-1)?.key ?? null, ...(cloudTurnId ? { cloudTurnId } : {}), userContent: typeof message.content === "string" ? [{ type: "text", text: message.content }] : piContent(message.content), messages: [], startedAt: completedAt, startBytes: line.startBytes, endBytes: line.endBytes, contentEndBytes: line.endBytes, boundaries: {}, sha256: line.sha256, result: null };
+            messages = current.messages;
+        }
+        else if (current && message.role === "assistant") {
+            messages.push({ content: piContent(message.content), provider: text(message.provider) || null, model: text(message.model) || null,
+                usage: record(message.usage), stopReason: text(message.stopReason) || null, errorMessage: text(message.errorMessage) || null });
+        }
+        else if (current && message.role === "toolResult") {
+            const assistant = messages.at(-1);
+            if (!assistant)
+                throw new Error("Pi tool result has no assistant Turn / Pi 工具结果缺少所属 Turn");
+            assistant.content.push({ type: "tool_result", tool_use_id: text(message.toolCallId), content: typeof message.content === "string" ? message.content : piContent(message.content), is_error: Boolean(message.isError) });
+        }
+        if (current) {
+            current.endBytes = line.endBytes;
+            current.contentEndBytes = line.endBytes;
+            current.sha256 = line.sha256;
+            current.boundaries[line.endBytes] = line.sha256;
+        }
+        completedAt = timestamp;
+    }
+    finish(Boolean(options.settled));
+    return { nativeSessionId: text(header.id), cwd: text(header.cwd), cloudSessionId: cloudSessionId || undefined, turns };
+}
+function codexContent(value) {
+    return list(value).flatMap((item) => {
+        const block = record(item);
+        if (["input_text", "output_text", "text"].includes(text(block.type)))
+            return [{ type: "text", text: text(block.text) }];
+        if (block.type === "input_image" && text(block.image_url)) {
+            const data = /^data:([^;]+);base64,(.*)$/s.exec(text(block.image_url));
+            return [{ type: "image", source: data ? { type: "base64", media_type: data[1] ?? "image/png", data: data[2] ?? "" } : { type: "url", url: text(block.image_url) } }];
+        }
+        return [];
+    });
+}
+function parseCodexTranscript(lines) {
+    const header = lines[0]?.value ?? {};
+    const metadata = record(header.payload);
+    if (header.type !== "session_meta" || !text(metadata.id))
+        throw new Error("Invalid Codex session / Codex 会话无效");
+    if (metadata.history_base || metadata.fork_source)
+        throw new Error("Codex history references another rollout; retain the original and materialize its full history first / Codex 历史引用其他记录，请保留原件并先导出完整历史");
+    const turns = [];
+    let current = null;
+    let messages = [];
+    let model = null;
+    let cloudSessionId = text(record(metadata.cohub).sessionId);
+    let provider = text(metadata.model_provider) || null;
+    let userFromResponse = false;
+    const usageByTurn = new Map();
+    const assistant = () => {
+        let last = messages.at(-1);
+        if (!last) {
+            last = { content: [], model, provider };
+            messages.push(last);
+        }
+        return last;
+    };
+    for (const line of lines.slice(1)) {
+        const entry = line.value, payload = record(entry.payload);
+        if (entry.type === "turn_context") {
+            model = text(payload.model) || model;
+            provider = text(payload.model_provider) || provider;
+        }
+        if (entry.type === "event_msg" && ["turn_started", "task_started"].includes(text(payload.type))) {
+            if (current)
+                turns.push(current);
+            current = { key: text(payload.turn_id), parentKey: turns.at(-1)?.key ?? null, userContent: [], messages: [], startedAt: iso(entry.timestamp), startBytes: line.startBytes, endBytes: line.endBytes, contentEndBytes: line.endBytes, boundaries: {}, sha256: line.sha256, result: null };
+            if (!current.key)
+                throw new Error("Codex Turn identity is missing / Codex Turn 身份缺失");
+            messages = current.messages;
+            userFromResponse = false;
+        }
+        if (entry.type === "token_usage_record") {
+            const usage = record(payload.turn_token_usage);
+            if (typeof usage.total_tokens === "number")
+                usageByTurn.set(text(payload.turn_id), codexUsage(codexTokenTotals({ inputTokens: usage.input_tokens, outputTokens: usage.output_tokens, cachedInputTokens: usage.cached_input_tokens, cacheWriteInputTokens: usage.cache_write_input_tokens, totalTokens: usage.total_tokens })));
+        }
+        if (!current) {
+            const previous = turns.at(-1);
+            if (previous) {
+                previous.endBytes = line.endBytes;
+                previous.sha256 = line.sha256;
+                previous.boundaries[line.endBytes] = line.sha256;
+            }
+            continue;
+        }
+        current.endBytes = line.endBytes;
+        current.sha256 = line.sha256;
+        current.boundaries[line.endBytes] = line.sha256;
+        current.contentEndBytes = line.endBytes;
+        if (entry.type === "response_item") {
+            const cohub = record(record(entry.metadata).cohub);
+            if (typeof cohub.turnId === "string") {
+                current.cloudTurnId = cohub.turnId;
+                if (!text(record(metadata.cohub).sessionId))
+                    cloudSessionId = text(cohub.sessionId) || cloudSessionId;
+            }
+            if (payload.type === "message" && payload.role === "user") {
+                if (!userFromResponse)
+                    current.userContent = [];
+                current.userContent.push(...codexContent(payload.content));
+                userFromResponse = true;
+            }
+            else if (payload.type === "message" && payload.role === "assistant") {
+                const content = codexContent(payload.content);
+                if (!messages.length || messages.at(-1)?.content.length)
+                    messages.push({ content, model, provider });
+                else
+                    assistant().content.push(...content);
+            }
+            else if (payload.type === "reasoning") {
+                const thinking = list(payload.summary).map((item) => text(record(item).text)).join("\n");
+                if (thinking)
+                    assistant().content.push({ type: "thinking", thinking });
+            }
+            else if (["function_call", "custom_tool_call"].includes(text(payload.type))) {
+                let input;
+                try {
+                    input = payload.type === "custom_tool_call" ? { input: payload.input } : record(JSON.parse(text(payload.arguments)));
+                }
+                catch {
+                    input = { raw: payload.arguments };
+                }
+                assistant().content.push({ type: "tool_use", id: text(payload.call_id), name: text(payload.name), input });
+            }
+            else if (["function_call_output", "custom_tool_call_output"].includes(text(payload.type))) {
+                assistant().content.push({ type: "tool_result", tool_use_id: text(payload.call_id), content: typeof payload.output === "string" ? payload.output : JSON.stringify(payload.output ?? null) });
+            }
+        }
+        if (entry.type === "event_msg" && payload.type === "user_message" && !userFromResponse) {
+            current.userContent = [{ type: "text", text: text(payload.message) }];
+            userFromResponse = true;
+        }
+        if (entry.type === "event_msg" && ["turn_complete", "task_complete", "turn_aborted"].includes(text(payload.type))) {
+            if (payload.turn_id && payload.turn_id !== current.key)
+                throw new Error("Codex Turn boundary mismatch / Codex Turn 边界不匹配");
+            if (!messages.length && text(payload.last_agent_message))
+                messages.push({ content: [{ type: "text", text: text(payload.last_agent_message) }], model, provider });
+            const errorMessage = text(record(payload.error).message);
+            const status = payload.type === "turn_aborted" ? "interrupted" : errorMessage ? "failed" : "completed";
+            const final = assistant();
+            final.stopReason = status === "interrupted" ? "aborted" : status === "failed" ? "error" : "stop";
+            if (errorMessage)
+                final.errorMessage = errorMessage;
+            current.result = { messages, completedAt: iso(entry.timestamp), status };
+            turns.push(current);
+            current = null;
+            messages = [];
+        }
+    }
+    if (current && userFromResponse)
+        turns.push(current);
+    for (const turn of turns) {
+        const last = turn.result?.messages.at(-1);
+        if (last && usageByTurn.has(turn.key))
+            last.usage = usageByTurn.get(turn.key);
+    }
+    return { nativeSessionId: text(metadata.id), cwd: text(metadata.cwd), cloudSessionId: cloudSessionId || undefined, turns };
+}

package/dist/runtime/presentation.d.ts

@@ -0,0 +1,21 @@
+import type { RuntimeDiagnostic, RuntimeDiagnosticLevel } from "./diagnostics.js";
+export declare const diagnosticLevels: RuntimeDiagnosticLevel[];
+export declare const atLeastLevel: (level: RuntimeDiagnosticLevel, minimum: RuntimeDiagnosticLevel) => boolean;
+export declare const runtimeWebUrl: (spaceId: string) => string;
+export declare function formatDiagnostic(event: RuntimeDiagnostic, verbose?: boolean): string;
+/** File logs retain every event; repeated terminal warnings are coalesced. */
+export declare function createDiagnosticConsole(verbose?: boolean, write?: (line: string) => boolean): (event: RuntimeDiagnostic) => void;
+export type RuntimeSummary = {
+    spaceId: string;
+    runtimeId: string;
+    root: string;
+    harnesses: string[];
+    pid: number;
+    state: "starting" | "ready" | "reconnecting" | "attention" | "stopping";
+    harnessConnected: boolean;
+    workspaceConnected: boolean;
+    diagnosticsPath: string;
+    background: boolean;
+    nativeSync?: boolean;
+};
+export declare function printRuntimeSummary(summary: RuntimeSummary, json?: boolean, reused?: boolean): void;

package/dist/runtime/presentation.js

@@ -0,0 +1,76 @@
+import { resolveCohubEnvironment } from "@neta-art/cohub";
+export const diagnosticLevels = ["debug", "info", "warn", "error"];
+export const atLeastLevel = (level, minimum) => diagnosticLevels.indexOf(level) >= diagnosticLevels.indexOf(minimum);
+export const runtimeWebUrl = (spaceId) => `https://${resolveCohubEnvironment() === "prod" ? "" : "dev."}cohub.live/spaces/${spaceId}`;
+const messages = {
+    "runtime.ready": "Harness connected / Harness 已连接",
+    "runtime.available": "Runtime ready / Runtime 已就绪",
+    "runtime.websocket.closed": "Connection lost; reconnecting / 连接中断，正在重连",
+    "runtime.heartbeat_timeout": "Connection timed out; reconnecting / 连接超时，正在重连",
+    "runtime.auth_token_failed": "Cannot obtain credentials; retrying / 暂时无法获取凭证，正在重试",
+    "runtime.auth_required": "Sign in with cohub auth login / 请运行 cohub auth login 登录",
+    "runtime.stopped": "Runtime stopped / Runtime 已停止",
+    "runtime.failed": "Runtime needs attention / Runtime 需要处理",
+    "runtime.turn_failed": "Turn failed; local files retained / 执行失败，本地文件已保留",
+    "runtime.connection_failed": "Connection attempt failed; retrying / 连接失败，将继续重试",
+    "runtime.execution_transport_lost": "Execution disconnected; outcome needs reconciliation / 执行连接中断，结果待确认",
+    "archive.upload_pending": "Archive upload pending; local data retained / 归档待上传，本地数据已保留",
+    "native.sync_pending": "Native sync pending; local records retained / 原生同步待处理，本地记录已保留",
+    "archive.capture_pending": "Archive capture pending / 归档待处理",
+    "archive.capture_unavailable": "Archive unavailable; original receipt retained / 归档不可用，原始回执已保留",
+    "archive.restore_failed": "Native restore unavailable; using saved history / 原生恢复不可用，使用已保存历史",
+    "sandboxd.process_exit": "File bridge stopped; restarting / 文件桥接已退出，正在重启",
+    "sandboxd.download": "Preparing file bridge / 正在准备文件桥接",
+    "sandboxd.connected": "File bridge connected / 文件桥接已连接",
+    "sandboxd.disconnected": "File bridge disconnected; reconnecting / 文件桥接已断开，正在重连",
+};
+export function formatDiagnostic(event, verbose = false) {
+    const text = messages[event.event] ?? (typeof event.data?.message === "string" ? event.data.message : event.event);
+    const detail = event.error?.message ? ` — ${event.error.message}` : "";
+    const context = verbose ? ` ${JSON.stringify({ ...event.data, runtimeId: event.runtimeId, sessionId: event.sessionId, turnId: event.turnId })}` : "";
+    return `${event.timestamp.slice(11, 19)} ${event.level.toUpperCase().padEnd(5)} ${text}${detail}${context}\n`;
+}
+/** File logs retain every event; repeated terminal warnings are coalesced. */
+export function createDiagnosticConsole(verbose = false, write = (line) => process.stderr.write(line)) {
+    const last = new Map();
+    return (event) => {
+        if (!verbose && (event.level === "debug" || !atLeastLevel(event.level, "warn") && !messages[event.event]))
+            return;
+        const key = `${event.component}:${event.event}:${event.level}:${event.error?.message ?? event.data?.message ?? ""}`;
+        const previous = last.get(key);
+        const now = Date.now();
+        if (!verbose && previous && now - previous.at < 30_000 && atLeastLevel(event.level, "warn")) {
+            previous.suppressed++;
+            return;
+        }
+        if (last.size >= 256)
+            last.delete(last.keys().next().value ?? "");
+        last.set(key, { at: now, suppressed: 0 });
+        const repeated = previous?.suppressed ? ` (+${previous.suppressed} repeated / 重复)` : "";
+        write(`${formatDiagnostic(event, verbose).trimEnd()}${repeated}\n`);
+    };
+}
+export function printRuntimeSummary(summary, json = false, reused = false) {
+    const value = { ...summary, url: runtimeWebUrl(summary.spaceId), reused };
+    if (json) {
+        process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+        return;
+    }
+    const label = summary.state === "ready" ? "Runtime ready / Runtime 已就绪" : `Runtime ${summary.state} / Runtime 尚未就绪`;
+    process.stdout.write(`\n${label}${reused ? " · reused / 已复用" : ""}\n\n`);
+    const rows = [
+        ["Space / 空间", summary.spaceId],
+        ["URL / 链接", value.url],
+        ["Directory / 目录", summary.root],
+        ["Harness", summary.harnesses.join(" · ")],
+        ["Mode / 模式", summary.background ? "Background / 后台" : "Foreground / 前台"],
+        ["PID", String(summary.pid)],
+        ["Logs / 日志", summary.diagnosticsPath],
+    ];
+    for (const [name, text] of rows)
+        process.stdout.write(`  ${name}  ${text}\n`);
+    process.stdout.write(`\n  cohub runtime logs --space ${summary.spaceId} --follow\n  cohub runtime down --space ${summary.spaceId}\n`);
+    if (!summary.background && !reused)
+        process.stdout.write("  Ctrl+C to stop / 按 Ctrl+C 停止\n");
+    process.stdout.write("\n");
+}

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

@@ -30,6 +30,8 @@ export type NativeSession = {
     sourceFingerprint?: string | null;
     nativeLeafId?: string | null;
 };
+/** Reverse lookup for native clients; the existing Runtime state remains authoritative. */
+export declare function findRuntimeNativeSession(root: string, harness: "pi" | "codex", nativeSessionId: string, path?: string): Promise<NativeSession | null>;
 /** Local references are hints validated against actual native files, never cloud existence claims. */
 export declare class RuntimeSessionStore {
     readonly root: string;

package/dist/runtime/session-store.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, open, readFile, readdir, rename, rm } from "node:fs/promises";
+import { mkdir, open, readFile, readdir, realpath, rename, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { RUNTIME_RECOVERY_BATCH_SIZE, runtimeEventSchema, serializeProjectionRecords } from "@neta-art/cohub";
@@ -9,6 +9,35 @@ import { serializeDiagnosticError } from "./diagnostics.js";
 import { ProjectionStore, rebindProjectionNativeSession } from "./projection-store.js";
 export class ContextRequiredError extends Error {
 }
+/** Reverse lookup for native clients; the existing Runtime state remains authoritative. */
+export async function findRuntimeNativeSession(root, harness, nativeSessionId, path) {
+    const directory = join(root, harness);
+    const names = await readdir(directory).catch((error) => { if (error.code === "ENOENT")
+        return []; throw error; });
+    const matches = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const state = JSON.parse(await readFile(join(directory, name), "utf8"));
+        if (state.version === 1 && state.harness === harness && state.nativeSessionId === nativeSessionId)
+            matches.push(state);
+    }
+    if (path && matches.length) {
+        const canonical = await realpath(path);
+        const exact = [];
+        for (const state of matches) {
+            const candidate = await realpath(state.path).catch((error) => { if (error.code === "ENOENT")
+                return null; throw error; });
+            if (candidate === canonical)
+                exact.push(state);
+        }
+        if (exact.length === 1)
+            return exact[0] ?? null;
+    }
+    if (matches.length > 1)
+        throw new Error("Native Session has ambiguous Runtime bindings / 原生会话存在多个 Runtime 关联");
+    return matches[0] ?? null;
+}
 const checksum = (data) => createHash("sha256").update(data).digest("hex");
 const missing = (error) => error?.code === "ENOENT";
 class CaptureUnavailableError extends Error {
@@ -240,7 +269,6 @@ export class RuntimeSessionStore {
                 }
                 catch (error) {
                     this.diagnostics?.log("error", "runtime.session_state_unreadable", { path: join(directory, name), error: serializeDiagnosticError(error) });
-                    console.error(`Runtime session state unreadable: ${join(directory, name)}`, error);
                 }
             }
         }
@@ -295,11 +323,9 @@ export class RuntimeSessionStore {
                     });
                     await rm(join(captures, name), { force: true });
                     this.diagnostics?.log("error", "archive.capture_unavailable", { reason: error.message, receipt: true }, { component: "archive" });
-                    console.error("Archive capture unavailable; receipt retained:", error.message);
                 }
                 else {
                     this.diagnostics?.log("warn", "archive.capture_pending", { error: serializeDiagnosticError(error) }, { component: "archive" });
-                    console.error("Archive capture pending:", error);
                 }
             }
         }
@@ -368,6 +394,16 @@ export class RuntimeSessionStore {
                 }
             }
         }
+        if (previous) {
+            const previousPath = previous.path;
+            const canonical = await realpath(previousPath).catch((error) => { if (missing(error))
+                return previousPath; throw error; });
+            const externallyOwned = await readFile(join(this.root, "native-owners", `${checksum(canonical)}.json`), "utf8").then(() => true).catch((error) => { if (missing(error))
+                return false; throw error; });
+            // Interactive clients own their native files, including symlink aliases. Use an independent projection.
+            if (externallyOwned)
+                previous = null;
+        }
         if (previous) {
             try {
                 const nativeChecksum = await checksumNativeFile(previous.path);
@@ -408,7 +444,6 @@ export class RuntimeSessionStore {
             catch (error) {
                 signal?.throwIfAborted();
                 this.diagnostics?.log("warn", "archive.restore_failed", { error: serializeDiagnosticError(error) }, { component: "archive" });
-                console.error("Native archive unavailable; rebuilding from durable history:", error);
             }
         }
         return await this.syncNativeProjection(input, cwd, state, signal);

package/dist/runtime/space-binding.d.ts

@@ -39,6 +39,9 @@ export declare function resolveRuntimeSpace(input: {
     root: string;
     identityKey: string | null | undefined;
     explicitSpaceId?: string | null;
+    /** Explicit new selection; compare the binding observed before prompting. */
+    newSpace?: boolean;
+    expectedSpaceId?: string | null;
     createSpace: () => Promise<string>;
     validateSpace?: (spaceId: string) => Promise<void>;
     path?: string;

package/dist/runtime/space-binding.js

@@ -99,7 +99,7 @@ function upsertRuntimeSpaceBinding(file, binding) {
     bindings[index] = nextBinding;
     return { file: { version: 1, bindings }, changed: true };
 }
-async function writeRuntimeSpaceBindings(path, file) {
+async function writeRuntimeJson(path, file) {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
     const temporary = `${path}.${randomUUID()}.tmp`;
     try {
@@ -248,7 +248,7 @@ async function persistRuntimeSpaceBinding(path, binding) {
         const file = await readRuntimeSpaceBindings(path);
         const result = upsertRuntimeSpaceBinding(file, binding);
         if (result.changed)
-            await writeRuntimeSpaceBindings(path, result.file);
+            await writeRuntimeJson(path, result.file);
     }, { path, lockPath: `${path}${GLOBAL_LOCK_SUFFIX}` });
 }
 export async function getRuntimeSpaceBinding(root, key, path = runtimeSpaceBindingsPath()) {
@@ -281,25 +281,62 @@ export async function resolveRuntimeSpace(input) {
     const lockPath = bindingLockPath(path, root, bindingKey);
     return withRuntimeSpaceBindingsLock(async () => {
         const file = await readRuntimeSpaceBindings(path);
+        const receiptPath = `${lockPath}.creation.json`;
         if (explicitSpaceId) {
             await input.validateSpace?.(explicitSpaceId);
             await persistRuntimeSpaceBinding(path, { root, key: bindingKey, spaceId: explicitSpaceId });
+            // Preserve an ambiguous creation receipt for diagnosis, rather than deleting it.
+            if (await statIfPresent(receiptPath))
+                await rename(receiptPath, `${receiptPath}.${randomUUID()}.resolved`);
             return { spaceId: explicitSpaceId, source: "explicit" };
         }
         const existing = findRuntimeSpaceBinding(file, { root, key: bindingKey });
-        if (existing) {
+        if (input.newSpace && (existing?.spaceId ?? null) !== (input.expectedSpaceId ?? null)) {
+            throw new RuntimeSpaceBindingsError("Directory binding changed; run up again / 目录绑定已变化，请重新运行 up");
+        }
+        if (existing && !input.newSpace) {
             await input.validateSpace?.(existing.spaceId);
             return { spaceId: existing.spaceId, source: "binding" };
         }
-        // Remote creation and the local binding commit are separate durability
-        // domains; a server-side idempotency key is needed to close this crash window.
-        const createdSpaceId = await input.createSpace();
+        // Fail closed across the remote-create/local-commit crash window. A saved ID
+        // resumes binding; an ambiguous request must be resolved with --space, never replayed.
+        let receipt = null;
+        try {
+            receipt = JSON.parse(await readFile(receiptPath, "utf8"));
+            if (!receipt || !nonEmptyString(receipt.operationId) || receipt.spaceId !== undefined && !nonEmptyString(receipt.spaceId)) {
+                throw new RuntimeSpaceBindingsError(`Invalid creation receipt; original retained / 创建回执无效，原始信息已保留: ${receiptPath}`);
+            }
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        if (receipt && !receipt.spaceId)
+            throw new RuntimeSpaceBindingsError(`A previous Space creation has an unknown outcome. Check your Spaces and use --space <id> / 上次创建结果未知，请检查 Space 后使用 --space <id>。${receiptPath}`);
+        if (!receipt) {
+            receipt = { operationId: randomUUID() };
+            await writeRuntimeJson(receiptPath, receipt);
+        }
+        let createdSpaceId = receipt.spaceId;
+        if (!createdSpaceId) {
+            try {
+                createdSpaceId = await input.createSpace();
+            }
+            catch (error) {
+                const status = error?.status;
+                if (status && status >= 400 && status < 500 && status !== 408)
+                    await rm(receiptPath);
+                throw error;
+            }
+            await writeRuntimeJson(receiptPath, { ...receipt, spaceId: createdSpaceId });
+        }
         if (!nonEmptyString(createdSpaceId)) {
             throw new RuntimeSpaceBindingsError("Local Runtime Space creation returned no Space ID");
         }
         const spaceId = createdSpaceId.trim();
         await input.validateSpace?.(spaceId);
         await persistRuntimeSpaceBinding(path, { root, key: bindingKey, spaceId });
+        await rm(receiptPath);
         return { spaceId, source: "created" };
     }, { path, lockPath });
 }

package/dist/runtime/supervisor.d.ts

@@ -0,0 +1,16 @@
+import { type RuntimeCapabilities } from "@neta-art/cohub";
+import { type HarnessOptions } from "./harness.js";
+import { type RuntimeDiagnostic, type RuntimeDiagnosticLevel } from "./diagnostics.js";
+import { type RuntimeSummary } from "./presentation.js";
+export type RuntimeLaunch = {
+    spaceId: string;
+    root: string;
+    identity: string;
+    harnesses: ("pi" | "codex")[];
+    executables: HarnessOptions;
+    capabilities?: RuntimeCapabilities;
+    background: boolean;
+    verbose?: boolean;
+};
+export declare function sandboxOutputLevel(value: unknown, stream: "stdout" | "stderr"): RuntimeDiagnosticLevel;
+export declare function runRuntime(config: RuntimeLaunch, onState: (status: RuntimeSummary) => void, externalSignal?: AbortSignal, onDiagnostic?: (event: RuntimeDiagnostic) => void): Promise<void>;