@neta-art/cohub-cli 8.2.0 → 8.3.1

package/dist/runtime/native/install.d.ts

@@ -0,0 +1,9 @@
+export declare const piAgentDirectory: () => string;
+/** The extension shipped with this CLI: one self-contained module, loadable by Pi as is. */
+export declare const piExtensionSource: () => string;
+export type PiExtensionState = "installed" | "outdated" | "missing" | "foreign";
+export declare function piExtensionState(): Promise<PiExtensionState>;
+/** Install or upgrade the Pi extension in the user's Pi configuration. */
+export declare function installPiExtension(): Promise<PiExtensionState>;
+/** Remove the Codex hooks earlier releases installed; Cohub now reads Codex's own files instead. */
+export declare function removeLegacyCodexHooks(): Promise<boolean>;

package/dist/runtime/native/install.js

@@ -0,0 +1,113 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, extname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { withRuntimeSpaceBindingsLock } from "../space-binding.js";
+const missing = (error) => error.code === "ENOENT";
+/** First line of the installed extension; a file without it belongs to someone else. */
+const PI_EXTENSION_HEADER = "// Cohub control extension for Pi. Managed by `cohub runtime`; local edits are replaced on upgrade.\n";
+/** CLI 8.0–8.2 installed a re-export under this comment; its module is gone, so Pi fails to start while it remains. */
+const LEGACY_PI_EXTENSION_HEADER = "// Cohub native Turn sync";
+/** Earlier releases installed Codex hooks; they are removed on upgrade. */
+const LEGACY_CODEX_HOOKS = /\n*# BEGIN COHUB NATIVE SYNC\n[\s\S]*?# END COHUB NATIVE SYNC\n?/;
+export const piAgentDirectory = () => process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent");
+const codexConfigPath = () => join(process.env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "config.toml");
+/** The extension shipped with this CLI: one self-contained module, loadable by Pi as is. */
+export const piExtensionSource = () => fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "./pi-extension.ts" : "./pi-extension.js", import.meta.url));
+const piExtensionPath = (extension) => join(piAgentDirectory(), "extensions", `cohub${extension}`);
+const readOptional = (path) => readFile(path, "utf8").catch((error) => { if (missing(error))
+    return null; throw error; });
+const isLegacy = (text) => Boolean(text?.startsWith(LEGACY_PI_EXTENSION_HEADER));
+export async function piExtensionState() {
+    const source = piExtensionSource();
+    const [expected, current, legacy] = await Promise.all([readFile(source, "utf8"), readOptional(piExtensionPath(extname(source))), readOptional(piExtensionPath(".ts"))]);
+    if (isLegacy(legacy))
+        return "outdated";
+    if (current === null)
+        return "missing";
+    if (current === PI_EXTENSION_HEADER + expected)
+        return "installed";
+    return current.startsWith(PI_EXTENSION_HEADER) ? "outdated" : "foreign";
+}
+/** Install or upgrade the Pi extension in the user's Pi configuration. */
+export async function installPiExtension() {
+    const source = piExtensionSource();
+    const content = PI_EXTENSION_HEADER + await readFile(source, "utf8");
+    const target = piExtensionPath(extname(source));
+    await writeManaged(target, (existing) => {
+        if (existing !== null && !existing.startsWith(PI_EXTENSION_HEADER) && !isLegacy(existing))
+            throw new Error(`${target} exists and is not managed by Cohub; move it aside, then retry`);
+        return content;
+    }, { backup: false });
+    // Pi loads every file here: drop a legacy or managed copy under the other extension.
+    for (const other of [".ts", ".js"].map(piExtensionPath).filter((path) => path !== target)) {
+        const text = await readOptional(other).catch(() => null);
+        if (isLegacy(text) || text?.startsWith(PI_EXTENSION_HEADER))
+            await rm(other, { force: true });
+    }
+    return "installed";
+}
+/** Remove the Codex hooks earlier releases installed; Cohub now reads Codex's own files instead. */
+export async function removeLegacyCodexHooks() {
+    const path = codexConfigPath();
+    // Read first: the lock would create `~/.codex` for someone who never used Codex.
+    if (!LEGACY_CODEX_HOOKS.test(await readOptional(path) ?? ""))
+        return false;
+    let removed = false;
+    await writeManaged(path, (existing) => {
+        if (existing === null || !LEGACY_CODEX_HOOKS.test(existing))
+            return existing;
+        removed = true;
+        return existing.replace(LEGACY_CODEX_HOOKS, "\n");
+    }).catch((error) => { if (!missing(error))
+        throw error; });
+    return removed;
+}
+/** Replace a user configuration file atomically, keeping one backup of what was there. */
+async function writeManaged(path, update, options = { backup: true }) {
+    await withRuntimeSpaceBindingsLock(async () => {
+        const info = await lstat(path).catch((error) => { if (missing(error))
+            return null; throw error; });
+        if (info && (!info.isFile() || info.isSymbolicLink()))
+            throw new Error(`Refusing to replace a non-regular file: ${path}`);
+        const original = info ? await readFile(path, "utf8") : null;
+        const next = update(original);
+        if (next === null || next === original)
+            return;
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        if (original !== null && options.backup) {
+            const backup = `${path}.cohub-backup-${createHash("sha256").update(original).digest("hex").slice(0, 16)}`;
+            const file = await open(backup, "wx", 0o600).catch((error) => { if (error.code === "EEXIST")
+                return null; throw error; });
+            if (file) {
+                try {
+                    await file.writeFile(original);
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+            }
+        }
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            const file = await open(temporary, "wx", info?.mode ?? 0o600);
+            try {
+                await file.writeFile(next);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            const current = await readFile(path, "utf8").catch((error) => { if (missing(error))
+                return null; throw error; });
+            if (current !== original)
+                throw new Error(`Configuration changed during installation: ${path}`);
+            await rename(temporary, path);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }, { lockPath: `${path}.cohub-lock` });
+}

package/dist/runtime/native/pi-extension.d.ts

@@ -0,0 +1,35 @@
+/** Bumped when the daemon and the extension must be installed together. */
+export declare const COHUB_PI_PROTOCOL = 1;
+type PiContext = {
+    cwd: string;
+    sessionManager: {
+        getSessionFile(): string | undefined;
+        getSessionId(): string;
+    };
+    isIdle(): boolean;
+    abort(): void;
+    modelRegistry?: {
+        find(provider: string, id: string): unknown;
+    };
+};
+type Content = string | Array<{
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+}>;
+type Pi = {
+    on(event: string, handler: (event: unknown, context: PiContext) => unknown): void;
+    sendUserMessage(content: Content, options?: {
+        deliverAs?: "steer" | "followUp";
+    }): void;
+    appendEntry(customType: string, data?: unknown): void;
+    setModel?(model: unknown): Promise<boolean> | boolean;
+    setThinkingLevel?(level: string): void;
+};
+/** Runtime directory shared with the CLI; one socket per bound directory, hashed to stay short. */
+export declare function controlSocketPath(root: string): string;
+export default function cohub(pi: Pi): void;
+export {};

package/dist/runtime/native/pi-extension.js

@@ -0,0 +1,160 @@
+// Cohub control bridge for Pi. Self-contained: Node built-ins only, so it installs as one file.
+import { createHash } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Bumped when the daemon and the extension must be installed together. */
+export const COHUB_PI_PROTOCOL = 1;
+/** Pi's tools read the process environment when they run, so this reaches the next tool call. */
+function applyEnvironment(env) {
+    for (const [key, value] of Object.entries(env ?? {})) {
+        if (!key.startsWith("COHUB_"))
+            continue;
+        if (value === null)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+}
+/** Runtime directory shared with the CLI; one socket per bound directory, hashed to stay short. */
+export function controlSocketPath(root) {
+    const state = process.env.XDG_STATE_HOME?.trim() || join(homedir(), ".local", "state");
+    return join(state, "cohub", "control", `${createHash("sha256").update(root).digest("hex").slice(0, 32)}.sock`);
+}
+/** The nearest bound ancestor of `cwd`: a Runtime bound to a parent directory owns its subdirectories. */
+function locateSocket(cwd) {
+    let directory;
+    try {
+        directory = realpathSync(cwd);
+    }
+    catch {
+        return null;
+    }
+    for (;;) {
+        const socket = controlSocketPath(directory);
+        if (existsSync(socket))
+            return socket;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+/** How often a missing or lost Runtime is looked for again. */
+const RECONNECT_MS = 3_000;
+/** Streamed events the daemon uses; everything else Pi emits stays local. */
+const FORWARDED = new Set(["agent_start", "agent_end", "agent_settled", "turn_start", "turn_end", "message_start", "message_update", "message_end", "tool_execution_start", "tool_execution_update", "tool_execution_end"]);
+export default function cohub(pi) {
+    // Cohub may load this file explicitly into a Pi it starts; never attach twice.
+    const marker = Symbol.for("cohub.pi.control");
+    const globals = globalThis;
+    if (globals[marker])
+        return;
+    globals[marker] = true;
+    let socket = null;
+    let context = null;
+    let buffer = "";
+    let retry = null;
+    let probedAt = 0;
+    const send = (message) => { if (socket && !socket.destroyed)
+        socket.write(`${JSON.stringify(message)}\n`); };
+    const run = async (command) => {
+        if (!context)
+            throw new Error("Pi session is not ready");
+        if (command.type === "abort") {
+            context.abort();
+            return { idle: context.isIdle() };
+        }
+        if (command.type === "context") {
+            applyEnvironment(command.env);
+            return { idle: context.isIdle() };
+        }
+        const idle = context.isIdle();
+        // A Cohub Turn is a Turn of its own. If the terminal user started one first, nothing is written
+        // and Cohub waits for it to settle: queued behind it, the marker and the events would
+        // interleave.
+        if (command.turnId && !idle)
+            return { idle, accepted: false };
+        if (idle && command.model && context.modelRegistry && pi.setModel) {
+            const model = context.modelRegistry.find(command.model.provider, command.model.id);
+            if (!model || !await pi.setModel(model))
+                throw new Error("Model is unavailable in this Pi");
+        }
+        if (idle && command.thinkingLevel && pi.setThinkingLevel)
+            pi.setThinkingLevel(command.thinkingLevel);
+        // Choosing the model awaited; the terminal may have started meanwhile.
+        if (command.turnId && !context.isIdle())
+            return { idle: false, accepted: false };
+        // The marker precedes the user message, so the transcript itself records which cloud Turn it is.
+        applyEnvironment(command.env);
+        if (command.turnId)
+            pi.appendEntry("cohub.turn", { turnId: command.turnId });
+        pi.sendUserMessage(command.content, idle ? undefined : { deliverAs: command.deliverAs ?? "followUp" });
+        return { idle, accepted: true };
+    };
+    const attach = (ctx) => {
+        context = ctx;
+        if (socket && !socket.destroyed)
+            return;
+        if (Date.now() - probedAt < RECONNECT_MS)
+            return;
+        probedAt = Date.now();
+        const path = locateSocket(ctx.cwd);
+        if (!path)
+            return;
+        const current = connect(path);
+        socket = current;
+        buffer = "";
+        current.on("connect", () => send({
+            type: "hello", protocol: COHUB_PI_PROTOCOL, pid: process.pid, cwd: ctx.cwd,
+            sessionId: ctx.sessionManager.getSessionId(), sessionFile: ctx.sessionManager.getSessionFile() ?? null, idle: ctx.isIdle(),
+        }));
+        current.on("data", (bytes) => {
+            buffer += bytes.toString("utf8");
+            for (let end = buffer.indexOf("\n"); end >= 0; end = buffer.indexOf("\n")) {
+                const line = buffer.slice(0, end);
+                buffer = buffer.slice(end + 1);
+                if (!line)
+                    continue;
+                let command;
+                try {
+                    command = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                run(command).then((result) => send({ type: "result", id: command.id, ...result }), (error) => send({ type: "error", id: command.id, message: error instanceof Error ? error.message : String(error) }));
+            }
+        });
+        // A Runtime that restarts is reached again on the next event; nothing is buffered meanwhile.
+        current.on("error", () => undefined);
+        current.on("close", () => {
+            if (socket === current)
+                socket = null;
+            retry ??= setTimeout(() => { retry = null; if (context)
+                attach(context); }, RECONNECT_MS);
+            retry.unref?.();
+        });
+    };
+    pi.on("session_start", (_event, ctx) => attach(ctx));
+    for (const name of FORWARDED) {
+        pi.on(name, (event, ctx) => {
+            context = ctx;
+            if (!socket)
+                attach(ctx);
+            send({ type: "event", sessionId: ctx.sessionManager.getSessionId(), event: { ...event, type: name } });
+        });
+    }
+    // Pi replaces this instance on /new, /resume, /fork and /reload, and loads the next one only
+    // after this shutdown; the next instance attaches with its own session.
+    pi.on("session_shutdown", () => {
+        if (retry)
+            clearTimeout(retry);
+        retry = null;
+        socket?.end();
+        socket = null;
+        context = null;
+        globals[marker] = false;
+    });
+}

package/dist/runtime/native/pi-link.d.ts

@@ -0,0 +1,67 @@
+import type { Version } from "./version.js";
+/**
+ * Oldest Pi whose extension API Cohub relies on (`agent_settled`, `appendEntry`, steer and follow-
+ * up delivery).
+ */
+export declare const PI_MIN_VERSION: Version;
+/** Delivered to a session's subscribers when its Pi goes away. */
+export declare const PI_DISCONNECTED = "cohub_disconnected";
+/** A Pi process that is connected and can be driven: a terminal session or one Cohub started. */
+export type PiSessionLink = {
+    pid: number;
+    cwd: string;
+    sessionId: string;
+    sessionFile: string | null;
+    idle: boolean;
+    settledAt: number;
+};
+/**
+ * The Pi half of the control plane. Cohub never instructs Pi through a private channel it owns: the
+ * extension inside the running Pi process is the single interface, so a terminal session and one
+ * Cohub started behave identically.
+ */
+export declare class PiLink {
+    private readonly options;
+    private server;
+    unavailable: string | null;
+    private readonly sessions;
+    private readonly listeners;
+    private counter;
+    constructor(options: {
+        socketPath: string;
+        owns: (cwd: string) => boolean;
+        onEvent?: (session: PiSessionLink, event: Record<string, unknown>) => void;
+        onConnect?: (session: PiSessionLink) => void;
+        onDisconnect?: (session: PiSessionLink) => void;
+    });
+    get socketPath(): string;
+    subscribe(sessionId: string, listener: (event: Record<string, unknown>) => void): () => void;
+    waitFor(match: {
+        sessionId: string;
+        sessionFile: string;
+    }, signal: AbortSignal, timeoutMs?: number): Promise<PiSessionLink>;
+    idle(sessionId: string, signal: AbortSignal): Promise<void>;
+    listen(signal: AbortSignal): Promise<void>;
+    list(): PiSessionLink[];
+    find(sessionId: string): PiSessionLink | null;
+    isStreaming(sessionId: string): boolean | null;
+    prompt(sessionId: string, input: {
+        turnId?: string;
+        content: unknown;
+        deliverAs?: "steer" | "followUp";
+        model?: {
+            provider: string;
+            id: string;
+        } | null;
+        thinkingLevel?: string | null;
+        env?: Record<string, string | null>;
+    }): Promise<{
+        accepted: boolean;
+    }>;
+    context(sessionId: string, env: Record<string, string | null>): Promise<void>;
+    abort(sessionId: string): Promise<void>;
+    close(): Promise<void>;
+    private request;
+    private accept;
+    private hello;
+}

package/dist/runtime/native/pi-link.js

@@ -0,0 +1,238 @@
+import { createServer } from "node:net";
+import { chmod, mkdir, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { COHUB_PI_PROTOCOL } from "./pi-extension.js";
+const MAX_LINE_BYTES = 8 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 20 * 60_000;
+/**
+ * Oldest Pi whose extension API Cohub relies on (`agent_settled`, `appendEntry`, steer and follow-
+ * up delivery).
+ */
+export const PI_MIN_VERSION = [0, 85, 1];
+/** Delivered to a session's subscribers when its Pi goes away. */
+export const PI_DISCONNECTED = "cohub_disconnected";
+/**
+ * The Pi half of the control plane. Cohub never instructs Pi through a private channel it owns: the
+ * extension inside the running Pi process is the single interface, so a terminal session and one
+ * Cohub started behave identically.
+ */
+export class PiLink {
+    options;
+    server = null;
+    unavailable = null;
+    sessions = new Map();
+    listeners = new Map();
+    counter = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    get socketPath() { return this.options.socketPath; }
+    subscribe(sessionId, listener) {
+        let set = this.listeners.get(sessionId);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(sessionId, set);
+        }
+        set.add(listener);
+        return () => { set?.delete(listener); if (!set?.size)
+            this.listeners.delete(sessionId); };
+    }
+    async waitFor(match, signal, timeoutMs = 30_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            signal.throwIfAborted();
+            const found = this.list().find((session) => session.sessionId === match.sessionId || session.sessionFile === match.sessionFile);
+            if (found)
+                return found;
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        throw new Error("Pi did not attach to the Runtime; check that the Cohub extension loads");
+    }
+    async idle(sessionId, signal) {
+        if (this.sessions.get(sessionId)?.idle !== false)
+            return;
+        await new Promise((resolve, reject) => {
+            const finish = (error) => { off(); signal.removeEventListener("abort", onAbort); if (error)
+                reject(error);
+            else
+                resolve(); };
+            const onAbort = () => finish(signal.reason instanceof Error ? signal.reason : new Error("Aborted"));
+            const off = this.subscribe(sessionId, (event) => {
+                if (event.type === "agent_settled")
+                    finish();
+                if (event.type === PI_DISCONNECTED)
+                    finish(new Error("Pi disconnected"));
+            });
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    async listen(signal) {
+        const { socketPath } = this.options;
+        // The socket accepts commands that drive the user's agent: only this user may reach it.
+        await mkdir(dirname(socketPath), { recursive: true, mode: 0o700 });
+        if (process.platform !== "win32")
+            await chmod(dirname(socketPath), 0o700);
+        await rm(socketPath, { force: true });
+        const server = createServer((socket) => this.accept(socket));
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(socketPath, () => { server.removeListener("error", reject); resolve(); });
+        });
+        if (process.platform !== "win32")
+            await chmod(socketPath, 0o600);
+        this.server = server;
+        signal.addEventListener("abort", () => {
+            for (const session of this.sessions.values())
+                session.socket.destroy();
+            this.sessions.clear();
+            server.close();
+            void rm(socketPath, { force: true }).catch(() => undefined);
+        }, { once: true });
+    }
+    list() {
+        return [...this.sessions.values()].map(({ socket: _socket, pending: _pending, ...link }) => link);
+    }
+    find(sessionId) {
+        const live = this.sessions.get(sessionId);
+        if (!live)
+            return null;
+        const { socket: _socket, pending: _pending, ...link } = live;
+        return link;
+    }
+    isStreaming(sessionId) {
+        const live = this.sessions.get(sessionId);
+        return live ? !live.idle : null;
+    }
+    async prompt(sessionId, input) {
+        const result = await this.request(sessionId, { type: "prompt", ...input });
+        // A Cohub Turn is refused while the terminal runs one of its own; nothing was written then.
+        return { accepted: result?.accepted !== false };
+    }
+    async context(sessionId, env) {
+        await this.request(sessionId, { type: "context", env });
+    }
+    async abort(sessionId) {
+        await this.request(sessionId, { type: "abort" });
+    }
+    async close() {
+        for (const session of this.sessions.values())
+            session.socket.destroy();
+        this.sessions.clear();
+        await new Promise((resolve) => this.server?.close(() => resolve()) ?? resolve());
+    }
+    request(sessionId, command) {
+        const live = this.sessions.get(sessionId);
+        if (!live || live.socket.destroyed)
+            return Promise.reject(new Error("Pi is not connected"));
+        const id = `cohub-${++this.counter}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { live.pending.delete(id); reject(new Error("Pi did not answer in time")); }, REQUEST_TIMEOUT_MS);
+            live.pending.set(id, { resolve, reject, timer });
+            live.socket.write(`${JSON.stringify({ ...command, id })}\n`);
+        });
+    }
+    accept(socket) {
+        let buffer = "";
+        /** This connection's link; a newer connection for the same session replaces it in the map. */
+        let own = null;
+        socket.setNoDelay?.(true);
+        socket.on("error", () => socket.destroy());
+        socket.on("close", () => {
+            if (!own)
+                return;
+            const live = own;
+            for (const pending of live.pending.values()) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error("Pi disconnected"));
+            }
+            live.pending.clear();
+            if (this.sessions.get(live.sessionId) !== live)
+                return;
+            this.sessions.delete(live.sessionId);
+            for (const listener of this.listeners.get(live.sessionId) ?? [])
+                listener({ type: PI_DISCONNECTED });
+            const { socket: _socket, pending: _pending, ...link } = live;
+            this.options.onDisconnect?.(link);
+        });
+        socket.on("data", (bytes) => {
+            buffer += bytes.toString("utf8");
+            if (buffer.length > MAX_LINE_BYTES) {
+                socket.destroy();
+                return;
+            }
+            for (let end = buffer.indexOf("\n"); end >= 0; end = buffer.indexOf("\n")) {
+                const line = buffer.slice(0, end);
+                buffer = buffer.slice(end + 1);
+                if (!line)
+                    continue;
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (message.type === "hello") {
+                    // One session per connection; a Pi that switches sessions reconnects.
+                    const attached = own ? null : this.hello(socket, message);
+                    if (!attached) {
+                        socket.destroy();
+                        return;
+                    }
+                    own = attached;
+                    continue;
+                }
+                const live = own && this.sessions.get(own.sessionId) === own ? own : null;
+                if (!live)
+                    continue;
+                if (message.type === "event") {
+                    const event = (message.event ?? {});
+                    if (event.type === "agent_start")
+                        live.idle = false;
+                    if (event.type === "agent_settled") {
+                        live.idle = true;
+                        live.settledAt = Date.now();
+                    }
+                    const { socket: _socket, pending: _pending, ...link } = live;
+                    this.options.onEvent?.(link, event);
+                    for (const listener of this.listeners.get(live.sessionId) ?? [])
+                        listener(event);
+                    continue;
+                }
+                const id = typeof message.id === "string" ? message.id : null;
+                const pending = id ? live.pending.get(id) : null;
+                if (!pending || !id)
+                    continue;
+                live.pending.delete(id);
+                clearTimeout(pending.timer);
+                if (message.type === "error")
+                    pending.reject(new Error(typeof message.message === "string" ? message.message : "Pi rejected the command"));
+                else
+                    pending.resolve(message);
+            }
+        });
+    }
+    hello(socket, message) {
+        if (message.protocol !== COHUB_PI_PROTOCOL)
+            return null;
+        const cwd = typeof message.cwd === "string" ? message.cwd : "";
+        const sessionId = typeof message.sessionId === "string" ? message.sessionId : "";
+        const pid = typeof message.pid === "number" ? message.pid : 0;
+        if (!sessionId || !this.options.owns(cwd))
+            return null;
+        const live = {
+            pid, cwd, sessionId,
+            sessionFile: typeof message.sessionFile === "string" ? message.sessionFile : null,
+            idle: message.idle !== false,
+            settledAt: message.idle !== false ? Date.now() : 0,
+            socket,
+            pending: new Map(),
+        };
+        // A Pi that reconnects after a Runtime restart replaces its stale link.
+        this.sessions.get(sessionId)?.socket.destroy();
+        this.sessions.set(sessionId, live);
+        const { socket: _socket, pending: _pending, ...link } = live;
+        this.options.onConnect?.(link);
+        return live;
+    }
+}

package/dist/runtime/native/results.d.ts

@@ -0,0 +1,41 @@
+import { type RuntimeExecutionEvent, type RuntimePendingExecution, type RuntimeTurnInput } from "@neta-art/cohub";
+import type { NativeSession } from "./sessions.js";
+export declare class ContextRequiredError extends Error {
+}
+type Receipt = {
+    version: 2;
+    requestId: string | null;
+    sessionId: string;
+    turnId: string;
+    session: NativeSession;
+    events?: RuntimeExecutionEvent[];
+    uncertainCleanup?: {
+        processGroupId: number;
+        error: string;
+        confirmedAt?: string;
+    };
+};
+export type RecoveredResult = {
+    session: NativeSession;
+    events: RuntimeExecutionEvent[];
+};
+/** One small receipt per Cohub-executed Turn until the server acknowledges its result. */
+export declare class ExecutionResults {
+    private readonly root;
+    constructor(root: string);
+    private path;
+    private read;
+    /**
+     * Admit a new Turn. An unacknowledged earlier Turn is released once the server has settled it;
+     * otherwise the server must decide first, so a result is never overwritten unseen.
+     */
+    admit(input: RuntimeTurnInput): Promise<string | null>;
+    start(session: NativeSession, input: Pick<RuntimeTurnInput, "sessionId" | "turnId">, requestId: string | null): Promise<void>;
+    record(session: NativeSession, input: Pick<RuntimeTurnInput, "sessionId" | "turnId">, requestId: string | null, events: RuntimeExecutionEvent[], uncertainCleanup?: Receipt["uncertainCleanup"]): Promise<void>;
+    recover(input: Pick<RuntimeTurnInput, "sessionId" | "turnId" | "harness">, requestId?: string): Promise<RecoveredResult | null>;
+    acknowledge(sessionId: string, turnId: string): Promise<void>;
+    pendingTurnIds(sessionId: string): Promise<string[]>;
+    pendingBatches(): AsyncGenerator<RuntimePendingExecution[]>;
+    private fromTranscript;
+}
+export {};