@neta-art/cohub-cli 7.0.0 → 7.1.0

package/README.md

@@ -72,33 +72,41 @@ cohub -s <spaceId> spaces invites revoke <code> --yes
 cohub -s <spaceId> run -- git status
 ```
 
-Many space-scoped commands need a target Space:
+Many space-scoped commands need a target Space. Without an explicit target, commands
+also use the Space remembered for the current directory before falling back to Home:
 
 ```bash
 cohub -s <spaceId> spaces prompt "message" --json
 COHUB_SPACE_ID=<spaceId> cohub spaces prompt "message" --json
 ```
 
-## Local Runtime / 本地 Runtime
+## Local Runtime
 
 Connect one local workspace to a Space and select Pi or Codex per turn.
-将一个本地工作区连接到 Space，每轮可选择 Pi 或 Codex。
 
 ```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 -s <spaceId> spaces prompt "Continue" --harness codex
 cohub runtime status --space <spaceId>
+cohub runtime logs --space <spaceId> --follow
 ```
 
+Runtime diagnostics stay as redacted JSONL under the local Runtime state directory and
+are never uploaded automatically. Use `runtime logs --json` to export a failure report;
+events carry the local `runtimeId` plus server `requestId` / `traceparent` when a turn has
+reached the Agent trace.
+
 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.
-See [Runtime details](../../docs/local-runtime.md).
+When a result genuinely cannot be determined, the affected Chat offers an explicit stop
+confirmation. See [Runtime details](../../docs/local-runtime.md).
 
-Runtime 使用 WebSocket、原生 Pi RPC / Codex app-server 和现有云端流式链路。
-需要本机已安装并登录对应程序。Runtime 断线重连和结果核对自动完成，无需恢复命令。
-仅在无法确定结果时，由 Space 页头提供异常确认。旧 `sandbox up` 命令已移除。
+When `--space` is omitted, Runtime remembers a Space for the canonical local directory,
+account, and environment in `~/.config/cohub/runtime-spaces.json`. The first start creates
+and records a local Space; later starts reuse it. An explicit `--space` or `COHUB_SPACE_ID`
+overrides and updates the directory binding.
 
 ## Chats and prompts
 
@@ -378,7 +386,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", "Deprecated: clear legacy scope metadata / 已废弃：清除旧权限元数据")
+        .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,7 +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("--extend", "Add scopes without replacing active grants")
         .option("--json", "Output as JSON")
         .action(async (appRef, opts) => {
         const client = createClient();

package/dist/commands/desktop.d.ts

@@ -1,5 +1,14 @@
 import { resolveOpenSurface } from "@neta-art/cohub";
 import type { Command } from "commander";
 export { resolveOpenSurface };
+/**
+ * Optional disambiguation for file:// vs app://. Unlike ordinary
+ * Space-scoped commands, an unbound directory must not fall back to Home:
+ * the plain target should remain eligible for App resolution.
+ */
+export declare function resolveOptionalSpaceId(command: Command, options?: {
+    cwd?: string;
+    bindingsPath?: string;
+}): Promise<string | undefined>;
 export declare function registerDesktop(program: Command): void;
 export declare function registerLegacyUi(program: Command): void;

package/dist/commands/desktop.js

@@ -2,13 +2,18 @@ import { readFileSync } from "node:fs";
 import { HttpError, parseAppRef, resolveOpenSurface, DESKTOP_COMMAND_DEFAULT_TIMEOUT_MS, DESKTOP_COMMAND_MAX_TIMEOUT_MS, } from "@neta-art/cohub";
 import { createClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok } from "../output.js";
+import { resolveBoundSpace } from "../space.js";
 import { getAppByRef } from "../app-ref.js";
 export { resolveOpenSurface };
 const FILE_SCHEME = "file://";
 const APP_SCHEME = "app://";
 const LEGACY_WORK_SCHEME = "work://";
-/** Optional disambiguation for file:// vs app:// — do not fall back to Home. */
-function optionalSpaceId(command) {
+/**
+ * Optional disambiguation for file:// vs app://. Unlike ordinary
+ * Space-scoped commands, an unbound directory must not fall back to Home:
+ * the plain target should remain eligible for App resolution.
+ */
+export async function resolveOptionalSpaceId(command, options = {}) {
     let current = command;
     while (current) {
         const opts = current.opts();
@@ -16,7 +21,10 @@ function optionalSpaceId(command) {
             return opts.space.trim();
         current = current.parent ?? null;
     }
-    return process.env.COHUB_SPACE_ID?.trim() || undefined;
+    const fromEnvironment = process.env.COHUB_SPACE_ID?.trim();
+    if (fromEnvironment)
+        return fromEnvironment;
+    return (await resolveBoundSpace(options)) ?? undefined;
 }
 function parseFilePath(value) {
     const path = value.slice(FILE_SCHEME.length).trim();
@@ -86,7 +94,7 @@ async function resolveOpenTarget(client, command, value) {
         return { kind: "file", path: parseFilePath(value) };
     if (hasAppScheme(value))
         return resolveAppTarget(client, value);
-    const spaceId = optionalSpaceId(command);
+    const spaceId = await resolveOptionalSpaceId(command);
     if (spaceId) {
         try {
             await client.space(spaceId).files.read(value);
@@ -190,7 +198,7 @@ const OPEN_NOTES = `
 Notes:
   - Use file:// and app:// to make the target explicit; the legacy work://
     scheme is still accepted.
-  - A plain target checks the current Space for a file before resolving an app.
+  - A plain target checks the explicit Space or current directory Runtime binding for a file before resolving an app; it does not fall back to Home.
   - Opening a window is idempotent; repeating it re-activates the same tab.
   - --as picks the surface: window (a preview tab) or overlay (a transparent
     layer above the workspace). Without it, an App published with

package/dist/commands/run.d.ts

@@ -1,2 +1,13 @@
+type RunCliOptions = {
+    spaceId: string;
+    json: boolean;
+    async: boolean;
+    command: string;
+};
+export declare function parseRunCliOptions(argv: string[], spaceOptions?: {
+    cwd?: string;
+    bindingsPath?: string;
+}): Promise<RunCliOptions>;
 export declare function printRunHelp(): void;
 export declare function maybeHandleRunCommand(argv: string[]): Promise<boolean>;
+export {};

package/dist/commands/run.js

@@ -1,6 +1,6 @@
 import { createClient } from "../client.js";
 import { error, handleHttp, json as outJson, spinner } from "../output.js";
-import { missingSpaceError, resolveDefaultSpace } from "../space.js";
+import { resolveSpaceTarget } from "../space.js";
 const DEFAULT_WAIT_TIMEOUT_MS = (6 * 60 * 60 + 60) * 1000;
 const DEFAULT_POLL_INTERVAL_MS = 1500;
 function shellQuote(value) {
@@ -44,7 +44,7 @@ function parseSpaceId(tokens) {
     }
     return undefined;
 }
-async function parseRunCliOptions(argv) {
+export async function parseRunCliOptions(argv, spaceOptions = {}) {
     const runIndex = topLevelRunIndex(argv);
     if (runIndex < 0)
         return error("Invalid invocation", "Use `cohub run [options] <command>`");
@@ -104,7 +104,7 @@ async function parseRunCliOptions(argv) {
     if (!command) {
         return error("No command", "Pass --command <shell command>, or use `--` followed by the command.");
     }
-    const spaceId = explicitSpaceId || (await resolveDefaultSpace().catch(handleHttp)) || missingSpaceError();
+    const spaceId = await resolveSpaceTarget(explicitSpaceId, spaceOptions);
     return { spaceId, json, async, command };
 }
 export function printRunHelp() {
@@ -125,7 +125,7 @@ Examples:
   cohub -s <spaceId> run -- git status -sb
 
 Notes:
-  - Without -s or COHUB_SPACE_ID, the command targets your Home space.
+  - Without -s or COHUB_SPACE_ID, the command uses the current directory Runtime binding, then Home.
   - Use --command for commands that contain leading flags, or use -- before the shell command.
   - The command runs in /workspace.
 `);

package/dist/commands/runtime.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { stat } from "node:fs/promises";
 import { basename, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -6,45 +7,111 @@ import { isLocalHarness, resolveCohubEnvironment, resolveWebsocketUrl } from "@n
 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 { currentIdentityKey, explicitSpace, resolveSpace } from "../space.js";
+import { canonicalRuntimeRoot, resolveRuntimeSpace } from "../runtime/space-binding.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";
+import { readRuntimeDiagnosticEvents, RuntimeDiagnosticReader, RuntimeDiagnostics, runtimeDiagnosticsDirectory, serializeDiagnosticError, } from "../runtime/diagnostics.js";
 export const resolveLocalSpaceName = (root, name) => name?.trim() || basename(root) || "local-space";
+function sandboxOutputLevel(value, stream) {
+    const level = typeof value === "string" ? value.toLowerCase() : "";
+    if (level.includes("error"))
+        return "error";
+    if (level.includes("warn"))
+        return "warn";
+    return stream === "stderr" ? "error" : "debug";
+}
+function captureSandboxOutput(stream, streamName, diagnostics) {
+    if (!stream)
+        return;
+    let pending = "";
+    const consume = (chunk) => {
+        pending += Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
+        let newline = pending.indexOf("\n");
+        while (newline >= 0) {
+            const line = pending.slice(0, newline).trim();
+            pending = pending.slice(newline + 1);
+            if (line)
+                recordSandboxOutput(line, streamName, diagnostics);
+            newline = pending.indexOf("\n");
+        }
+    };
+    stream.on("data", consume);
+    stream.on("end", () => {
+        if (pending.trim())
+            recordSandboxOutput(pending.trim(), streamName, diagnostics);
+    });
+}
+function recordSandboxOutput(line, streamName, diagnostics) {
+    let parsed = null;
+    try {
+        const value = JSON.parse(line);
+        if (value && typeof value === "object" && !Array.isArray(value))
+            parsed = value;
+    }
+    catch {
+        // Older or third-party binaries may still emit text logs.
+    }
+    const level = sandboxOutputLevel(parsed?.level, streamName);
+    const message = typeof parsed?.msg === "string" ? parsed.msg : line;
+    const data = parsed
+        ? Object.fromEntries(Object.entries(parsed).filter(([key]) => !["msg", "level", "time"].includes(key)))
+        : { message: line };
+    diagnostics.log(level, "sandboxd.log", {
+        stream: streamName,
+        message,
+        ...(level === "error" ? { error: { message } } : {}),
+        ...data,
+    }, { component: "sandboxd" });
+}
+function printDiagnostic(event) {
+    const scope = [event.component, event.event].filter(Boolean).join(".");
+    const context = [
+        event.connectionId && `connection=${event.connectionId}`,
+        event.sessionId && `session=${event.sessionId}`,
+        event.turnId && `turn=${event.turnId}`,
+        event.traceContext?.requestId && `request=${event.traceContext.requestId}`,
+        event.traceContext?.traceId && `trace=${event.traceContext.traceId}`,
+    ].filter(Boolean).join(" ");
+    const data = event.data && Object.keys(event.data).length > 0 ? ` ${JSON.stringify(event.data)}` : "";
+    process.stdout.write(`${event.timestamp} ${event.level.toUpperCase().padEnd(5)} ${scope}${context ? ` ${context}` : ""}${data}${event.error ? ` ${JSON.stringify(event.error)}` : ""}\n`);
+}
 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 / Harness 必须是 pi 或 codex");
+        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 / 连接本地工作区");
+    const runtime = program.command("runtime").description("Connect a local workspace");
     runtime.command("up [dir]")
-        .description("Connect local Harnesses and files / 连接本地 Harness 与文件")
-        .option("-s, --space <id>", "Target Space / 目标 Space")
-        .option("-n, --name <name>", "New Space name / 新 Space 名称")
-        .option("--harness <name>", "Pi or Codex; repeatable / Pi 或 Codex，可重复", (value, previous) => [...previous, value], [])
-        .option("--pi <path>", "Pi executable / Pi 可执行文件")
-        .option("--codex <path>", "Codex executable / Codex 可执行文件")
-        .option("-y, --yes", "Accept local execution access / 同意本机执行权限")
-        .option("--json", "JSON output / JSON 输出")
+        .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 requestedRoot = resolve(dir ?? process.cwd());
+            if (!(await stat(requestedRoot)).isDirectory())
+                throw new Error("Workspace is not a directory");
+            const root = await canonicalRuntimeRoot(requestedRoot);
             const harnesses = parseRuntimeHarnesses(options.harness);
             if (!options.yes) {
                 if (!process.stdin.isTTY)
-                    throw new Error("Use --yes to authorize local execution / 请使用 --yes 授权本机执行");
+                    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.\n连接此目录？Space 协作者可使用当前系统用户执行命令，权限不限于此目录。 [y/N] `);
+                    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;
                 }
@@ -54,64 +121,208 @@ export function registerRuntime(program) {
             }
             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 / Space 不是本地 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();
+            const requested = options.space?.trim() || explicitSpace(program);
+            const validateLocalRuntime = async (spaceId) => {
+                const sandbox = (await client.space(spaceId).sandbox.get()).sandbox;
+                if (sandbox?.provider !== "local")
+                    throw new Error("Space does not have a local Runtime");
+            };
+            const { spaceId } = await resolveRuntimeSpace({
+                root,
+                identityKey: currentIdentityKey(),
+                explicitSpaceId: requested,
+                createSpace: async () => (await client.spaces.create({
+                    name: resolveLocalSpaceName(root, options.name),
+                    config: { sandbox: { provider: "local" } },
+                })).space.id,
+                validateSpace: validateLocalRuntime,
+            });
+            const spaceClient = client.space(spaceId);
+            const store = new RuntimeSessionStore(spaceId, { projectionSource: spaceClient });
+            const runtimeId = randomUUID();
+            const diagnostics = new RuntimeDiagnostics({ root: store.root, spaceId, runtimeId });
+            store.setDiagnostics(diagnostics);
+            diagnostics.log("info", "runtime.cli_started", {
+                platform: process.platform,
+                arch: process.arch,
+                node: process.versions.node,
+                harnesses,
+                proxyConfigured: ["HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY"].some((key) => Boolean(process.env[key]?.trim())),
+            });
             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 / Runtime 已连接: ${webUrl}`);
-                    },
+                const binary = await ensureSandboxdBinary({
+                    onStatus: (message) => diagnostics.log("info", "sandboxd.download", { message }, { component: "sandboxd" }),
                 });
+                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();
+                let announced = false;
+                const token = await requireAccessToken();
+                try {
+                    await serveRuntime({
+                        spaceId,
+                        cwd: root,
+                        url: url.toString(),
+                        capabilities,
+                        harnesses: options,
+                        runtimeId,
+                        diagnostics,
+                        token: requireAccessToken,
+                        signal: controller.signal,
+                        store,
+                        onReady: () => {
+                            if (!bridge) {
+                                bridge = spawn(binary, ["--local", "--space", spaceId, "--root", root, "--relay", process.env.COHUB_RELAY_URL?.trim() || relay.toString()], {
+                                    stdio: ["ignore", "pipe", "pipe"],
+                                    env: {
+                                        ...process.env,
+                                        COHUB_RELAY_TOKEN: token,
+                                        COHUB_RUNTIME_ID: runtimeId,
+                                        COHUB_LOG_FORMAT: "json",
+                                    },
+                                });
+                                captureSandboxOutput(bridge.stdout, "stdout", diagnostics);
+                                captureSandboxOutput(bridge.stderr, "stderr", diagnostics);
+                                bridgeClosed = new Promise((resolveClosed) => bridge?.once("close", () => resolveClosed()));
+                                bridge.on("error", (cause) => {
+                                    diagnostics.log("error", "sandboxd.process_error", { error: serializeDiagnosticError(cause) }, { component: "sandboxd" });
+                                    console.error(cause);
+                                    controller.abort();
+                                });
+                                bridge.once("exit", (code, signal) => {
+                                    diagnostics.log(code === 0 ? "info" : "error", "sandboxd.process_exit", { code, signal }, { component: "sandboxd" });
+                                    controller.abort();
+                                });
+                            }
+                            if (announced)
+                                return;
+                            announced = true;
+                            const webUrl = `${resolveCohubEnvironment() === "prod" ? "https://cohub.live" : "https://dev.cohub.live"}/spaces/${spaceId}`;
+                            if (jsonRequested(options))
+                                outJson({ spaceId, root, harnesses, runtimeId, diagnosticsPath: diagnostics.logPath, url: webUrl });
+                            else
+                                console.error(`Runtime connected: ${webUrl} (runtimeId=${runtimeId}, logs=${diagnostics.logPath})`);
+                        },
+                    });
+                }
+                finally {
+                    if (bridge) {
+                        const child = bridge;
+                        child.kill("SIGTERM");
+                        const timeout = setTimeout(() => child.kill("SIGKILL"), 3000);
+                        await bridgeClosed;
+                        clearTimeout(timeout);
+                    }
+                }
+            }
+            catch (cause) {
+                diagnostics.log("error", "runtime.start_failed", { error: serializeDiagnosticError(cause) });
+                throw cause;
             }
             finally {
-                if (bridge) {
-                    const child = bridge;
-                    child.kill("SIGTERM");
-                    const timeout = setTimeout(() => child.kill("SIGKILL"), 3000);
-                    await bridgeClosed;
-                    clearTimeout(timeout);
-                }
+                await diagnostics.close().catch((error) => console.error("Runtime diagnostics close failed:", error));
             }
         }
         catch (cause) {
             if (!controller.signal.aborted)
-                error("Runtime failed / Runtime 失败", cause instanceof Error ? cause.message : String(cause));
+                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 / Runtime 状态").option("-s, --space <id>", "Target Space / 目标 Space").action(async (options) => {
+    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 client = createClient();
+        const spaceClient = client.space(spaceId);
+        const store = new RuntimeSessionStore(spaceId, { projectionSource: spaceClient });
         const [status, pendingLocalArchives, failedLocalArchives] = await Promise.all([
-            createClient().space(spaceId).getRuntime(), archives.pendingCount(), archives.failedCaptureCount(),
+            spaceClient.getRuntime(),
+            store.archives.pendingCount(),
+            store.archives.failedCaptureCount(),
         ]);
-        outJson({ ...status, pendingLocalArchives, failedLocalArchives });
+        outJson({
+            ...status,
+            diagnosticsPath: runtimeDiagnosticsDirectory(store.root),
+            pendingLocalArchives,
+            failedLocalArchives,
+        });
+    });
+    runtime.command("logs")
+        .description("Read local Runtime diagnostics")
+        .option("-s, --space <id>", "Target Space")
+        .option("-l, --limit <count>", "Number of events", "100")
+        .option("--follow", "Keep watching for new events")
+        .option("--json", "Print raw diagnostic events")
+        .action(async (options) => {
+        const spaceId = options.space?.trim() || await resolveSpace(program);
+        const store = new RuntimeSessionStore(spaceId, { projectionSource: createClient().space(spaceId) });
+        const limit = Number(options.limit ?? "100");
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 10_000)
+            return error("Invalid diagnostic limit", "Use an integer between 1 and 10000 / 使用 1 到 10000 之间的整数");
+        const asJson = jsonRequested(options);
+        const reader = options.follow ? new RuntimeDiagnosticReader(store.root) : null;
+        const render = async () => {
+            const fresh = options.follow
+                ? await reader?.read({ limit }) ?? []
+                : await readRuntimeDiagnosticEvents(store.root, { limit });
+            if (options.follow && fresh.length === 0)
+                return;
+            if (asJson && options.follow) {
+                for (const event of fresh)
+                    process.stdout.write(`${JSON.stringify(event)}\n`);
+            }
+            else if (asJson) {
+                outJson(fresh);
+            }
+            else if (fresh.length === 0) {
+                process.stdout.write("No Runtime diagnostics / 未找到 Runtime 诊断记录\n");
+            }
+            else {
+                for (const event of fresh)
+                    printDiagnostic(event);
+            }
+        };
+        try {
+            await render();
+            if (!options.follow)
+                return;
+            await new Promise((resolve) => {
+                let timer = null;
+                let stopped = false;
+                const stop = () => {
+                    stopped = true;
+                    if (timer)
+                        clearTimeout(timer);
+                    process.removeListener("SIGINT", stop);
+                    process.removeListener("SIGTERM", stop);
+                    resolve();
+                };
+                const poll = async () => {
+                    if (stopped)
+                        return;
+                    try {
+                        await render();
+                    }
+                    catch {
+                        stop();
+                        return;
+                    }
+                    if (!stopped)
+                        timer = setTimeout(() => void poll(), 2_000);
+                };
+                timer = setTimeout(() => void poll(), 2_000);
+                process.once("SIGINT", stop);
+                process.once("SIGTERM", stop);
+            });
+        }
+        catch (cause) {
+            error("Runtime logs failed", cause instanceof Error ? cause.message : String(cause));
+        }
     });
 }

package/dist/commands/sandboxd-binary.d.ts

@@ -2,6 +2,8 @@ export declare const SANDBOXD_VERSION = "v1.82.4";
 export declare class SandboxdDownloadError extends Error {
     name: string;
 }
+export declare function validSandboxdArchiveEntries(entries: string[], version?: string): boolean;
+export declare function validateSandboxdArchive(archivePath: string, version?: string): Promise<string[]>;
 export type EnsureSandboxdOptions = {
     version?: string;
     onStatus?: (message: string) => void;