@neta-art/cohub-cli 7.1.2 → 8.0.1

package/dist/runtime/native-sync.js

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

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

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

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");
+                }
+                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");
+    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");
+        visited.add(leaf);
+        const entry = entries.get(leaf);
+        if (!entry)
+            throw new Error("Pi parent history is missing");
+        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");
+            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");
+    if (metadata.history_base || metadata.fork_source)
+        throw new Error("Codex history references another rollout; retain the original and materialize its full history first");
+    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");
+            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");
+            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,78 @@
+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",
+    "runtime.available": "Runtime ready",
+    "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",
+    "runtime.stopped": "Runtime stopped",
+    "runtime.failed": "Runtime needs attention",
+    "runtime.turn_failed": "Turn failed; local files retained",
+    "runtime.turn_cleanup_pending": "Turn result saved; tool cleanup still unconfirmed",
+    "runtime.connection_failed": "Connection attempt failed; retrying",
+    "runtime.execution_transport_detached": "Execution continues locally; result replays after reconnect",
+    "runtime.execution_transport_invalidated": "Execution interrupted; 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 ${summary.state}`;
+    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\n");
+    process.stdout.write("\n");
+}

package/dist/runtime/process-group.d.ts

@@ -1,3 +1,5 @@
 export declare class ProcessCleanupUncertainError extends Error {
 }
+/** True only when the process group is gone or holds nothing that can execute. */
+export declare function confirmQuiescentProcessGroup(pid: number): Promise<boolean>;
 export declare function stopProcessGroup(pid: number): Promise<void>;