@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/core/host-crash.mjs

@@ -0,0 +1,79 @@
+/**
+ * Crash-time finalization for PTY hosts (used by pty-runner's uncaughtException
+ * handler). Pure enough to unit-test: writes a failed host.json + a diagnostic.
+ * Never throws — this runs on the crash path.
+ */
+import { appendDiagnostic } from "./diagnostics.mjs";
+import { updateOwnedHost, writeHost } from "./store.mjs";
+
+/**
+ * @param {string} root
+ * @param {string} viewId
+ * @param {object|null} host
+ * @param {unknown} error
+ * @param {{ expectedInstanceId?: string|null }} [opts] When `expectedInstanceId`
+ *   is set (new ownership protocol, issue #70), the failed state is written via
+ *   the owner-fenced `updateOwnedHost` — a superseded instance can never
+ *   clobber the replacement's live record; the skip is recorded as a
+ *   `host_crash_owner_changed` diagnostic. Without it the legacy wholesale
+ *   `writeHost` behavior is preserved exactly.
+ * @returns {object}
+ */
+export function finalizeHostCrash(root, viewId, host, error, opts = {}) {
+	const message = error instanceof Error ? error.message : String(error);
+	const failed = {
+		...(host ?? { version: 1, viewId, mode: "pty", socketPath: null, startedAt: Date.now() }),
+		state: "failed",
+		endedAt: Date.now(),
+		lastSeenAt: Date.now(),
+		exitCode: 1,
+		error: message,
+	};
+	if (opts.expectedInstanceId != null) {
+		try {
+			// Build the terminal state from the LIVE record inside the host-meta
+			// lock — never from the possibly-stale `host` snapshot.
+			const result = updateOwnedHost(root, viewId, opts.expectedInstanceId, (cur) => ({
+				...cur,
+				state: "failed",
+				endedAt: Date.now(),
+				lastSeenAt: Date.now(),
+				exitCode: 1,
+				error: message,
+			}));
+			if (result.updated && result.host) {
+				appendCrashDiagnostic(root, viewId, message);
+				return result.host;
+			}
+			// ownerChanged, or the meta lock was briefly busy: never write unfenced.
+			try {
+				appendDiagnostic(root, viewId, {
+					source: "runner",
+					level: "warn",
+					code: "host_crash_owner_changed",
+					message: `Skipped crash finalize: host record no longer belongs to this instance (${message})`,
+					details: { error: message, ownerChanged: result.ownerChanged },
+				});
+			} catch { /* best effort */ }
+		} catch { /* best effort */ }
+		return failed;
+	}
+	try {
+		writeHost(root, failed);
+	} catch { /* best effort */ }
+	appendCrashDiagnostic(root, viewId, message);
+	return failed;
+}
+
+/** @param {string} root @param {string} viewId @param {string} message */
+function appendCrashDiagnostic(root, viewId, message) {
+	try {
+		appendDiagnostic(root, viewId, {
+			source: "runner",
+			level: "error",
+			code: "host_crashed",
+			message: `PTY host crashed: ${message}`,
+			details: { error: message },
+		});
+	} catch { /* best effort */ }
+}

package/packages/board/src/core/host-probe.mjs

@@ -0,0 +1,207 @@
+/**
+ * Real control-endpoint probe (issue #70).
+ *
+ * Connects to a PTY host control socket/pipe, performs the JSONL hello
+ * handshake, and classifies the outcome via `classifyProbeResult`. This is
+ * the ONLY "is this endpoint actually usable" authority — path existence and
+ * host.json state are hints, never proof (spec §7.1).
+ *
+ * Side-effectful by design (net + fs); all pure decisions live in
+ * host-coordination.mjs.
+ */
+import { createConnection } from "node:net";
+import { lstatSync } from "node:fs";
+import { classifyProbeResult } from "./host-coordination.mjs";
+import { resolveTestMs } from "./test-knobs.mjs";
+
+/** Default probe timeout. */
+export const HOST_PROBE_TIMEOUT_MS = 250;
+/** Poll cadence between attach-resolver probes / retries (issue #70 Task 12). */
+export const HOST_PROBE_RETRY_MS = 150;
+
+/**
+ * Dynamic reader for HOST_PROBE_TIMEOUT_MS (issue #95 F4): env set after module
+ * load must still reach the probe, so read the knob at each use site.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number}
+ */
+export function resolveHostProbeTimeoutMs(env = process.env) {
+	return resolveTestMs(env, "AGENT_BOARD_TEST_HOST_PROBE_TIMEOUT_MS", HOST_PROBE_TIMEOUT_MS);
+}
+
+/**
+ * @typedef {object} ProbeResult
+ * @property {"ready"|"starting"|"stale"|"occupied"|"missing"|"unknown"} classification
+ * @property {boolean} connected
+ * @property {boolean} protocolValid
+ * @property {boolean} ready
+ * @property {string|null} viewId
+ * @property {string|null} instanceId
+ * @property {string|null} state
+ * @property {string|null} errorCode
+ */
+
+/**
+ * Probe a host control endpoint via a real connection + JSONL hello.
+ *
+ * `connect` is injectable for tests; the default accepts anything
+ * `net.createConnection` accepts (a socket path / pipe name, or a
+ * `{ host, port }` address object) and must return a socket-like object with
+ * the usual `'connect' | 'data' | 'error'` events and a `.destroy()`.
+ *
+ * The probe socket is ALWAYS destroyed before the promise resolves.
+ *
+ * @param {string|{host:string,port:number}} socketPath
+ * @param {{ timeoutMs?: number, expectedViewId?: string|null, expectedInstanceId?: string|null, connect?: (target: any) => any }} [opts]
+ * @returns {Promise<ProbeResult>}
+ */
+export function probeHost(socketPath, opts = {}) {
+	const timeoutMs = opts.timeoutMs ?? resolveHostProbeTimeoutMs();
+	const expectedViewId = opts.expectedViewId ?? null;
+	const expectedInstanceId = opts.expectedInstanceId ?? null;
+	const connect = opts.connect ?? createConnection;
+
+	return new Promise((resolve) => {
+		/** @type {any} */ let socket;
+		/** @type {NodeJS.Timeout|null} */ let timer = null;
+		let settled = false;
+		let buffer = "";
+		/** @type {ProbeResult} */ let result;
+
+		const finish = () => {
+			if (settled) return;
+			settled = true;
+			if (timer) clearTimeout(timer);
+			try { socket?.destroy(); } catch { /* best effort */ }
+			resolve(result);
+		};
+
+		/** @param {string} errorCode */ const finishError = (errorCode) => {
+			const snapshot = {
+				connected: false,
+				protocolValid: false,
+				errorCode,
+				isSocket: false,
+			};
+			// Only a refused Unix-domain socket path can be considered stale, and
+			// even then only when the path really is a socket file (a plain file
+			// or directory at the same path must stay "unknown" — never unlink it).
+			if (errorCode === "ECONNREFUSED" && process.platform !== "win32" && typeof socketPath === "string") {
+				try {
+					snapshot.isSocket = lstatSync(socketPath).isSocket() === true;
+				} catch {
+					snapshot.isSocket = false;
+				}
+			}
+			result = buildResult(snapshot, null);
+			finish();
+		};
+
+		try {
+			socket = connect(socketPath);
+		} catch (err) {
+			result = buildResult({ connected: false, protocolValid: false, errorCode: errCode(err), isSocket: false }, null);
+			finish();
+			return;
+		}
+
+		timer = setTimeout(() => finishError("TIMEOUT"), timeoutMs);
+
+		socket.on("error", (err) => {
+			finishError(errCode(err));
+		});
+
+		socket.on("connect", () => {
+			try {
+				socket.write(JSON.stringify({ type: "hello", clientId: "probe", wantOutput: false }) + "\n");
+			} catch (err) {
+				finishError(errCode(err));
+			}
+		});
+
+		socket.on("data", (chunk) => {
+			if (settled) return;
+			buffer += chunk.toString("utf8");
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			const line = buffer.slice(0, newline).trim();
+			const parsed = parseReply(line);
+			result = buildResultFromReply(parsed, expectedViewId, expectedInstanceId);
+			finish();
+		});
+
+		// A close before any data settles the probe as an error-path unknown.
+		socket.on("close", () => {
+			if (!settled) finishError("CLOSED");
+		});
+	});
+}
+
+/**
+ * @param {string} line
+ * @returns {{ ok: boolean, status: any }}
+ */
+function parseReply(line) {
+	if (!line) return { ok: false, status: null };
+	try {
+		const msg = JSON.parse(line);
+		if (!msg || typeof msg !== "object") return { ok: false, status: null };
+		if (msg.type !== "hello" && msg.type !== "status") return { ok: false, status: null };
+		if (!msg.status || typeof msg.status !== "object") return { ok: false, status: null };
+		return { ok: true, status: msg.status };
+	} catch {
+		return { ok: false, status: null };
+	}
+}
+
+/**
+ * Assemble the classify snapshot from a parsed reply.
+ * @param {{ ok: boolean, status: any }} parsed
+ * @param {string|null} expectedViewId
+ * @param {string|null} expectedInstanceId
+ */
+function buildResultFromReply(parsed, expectedViewId, expectedInstanceId) {
+	const status = parsed.ok ? parsed.status : null;
+	const viewMatch = expectedViewId == null ? true : status?.viewId === expectedViewId;
+	const instanceMatch = expectedInstanceId == null ? true : status?.instanceId === expectedInstanceId;
+	// Legacy hosts (pre-instanceId protocol) report alive without a readyAt
+	// field; a legacy probe (no expectedInstanceId) must still classify them
+	// ready so upgrade-window attach keeps working (spec §10.1 / Task 2 ruling).
+	const readyAt = status?.readyAt ?? (expectedInstanceId == null && status?.state === "alive" ? 1 : null);
+	return buildResult(
+		{
+			connected: true,
+			protocolValid: parsed.ok,
+			viewMatch,
+			instanceMatch,
+			state: status?.state ?? null,
+			readyAt,
+		},
+		status,
+	);
+}
+
+/**
+ * @param {{ connected: boolean, protocolValid: boolean, viewMatch?: boolean, instanceMatch?: boolean, state?: string|null, readyAt?: number|null, errorCode?: string|null, isSocket?: boolean }} snapshot
+ * @param {any} status
+ * @returns {ProbeResult}
+ */
+function buildResult(snapshot, status) {
+	const classification = classifyProbeResult(snapshot);
+	return {
+		classification,
+		connected: snapshot.connected === true,
+		protocolValid: snapshot.protocolValid === true,
+		ready: classification === "ready",
+		viewId: status?.viewId ?? null,
+		instanceId: status?.instanceId ?? null,
+		state: snapshot.state ?? null,
+		errorCode: snapshot.errorCode ?? null,
+	};
+}
+
+/** @param {unknown} err */
+function errCode(err) {
+	if (err && typeof err === "object" && typeof /** @type {any} */ (err).code === "string") return /** @type {any} */ (err).code;
+	return "UNKNOWN";
+}

package/packages/board/src/core/host-protocol.mjs

@@ -0,0 +1,73 @@
+/** Control-socket client identity helpers (issue #103).
+ *
+ * Client ids travel in the `hello` handshake. `helloBookkeeping` turns the
+ * classification into the explicit socket policy: probes and the resident
+ * editor-state reporter stay out of `attachedClients` / `attachedEver`, and
+ * probes additionally never trigger a host.json write — counting or writing
+ * either would pin every host against warm-host reclaim (issue #75 / #103 §C /
+ * #130).
+ */
+
+/** Read-only endpoint probe (attach resolver); never counts as attached. */
+export const CLIENT_ID_PROBE = "probe";
+/** Resident editor-state reporter inside a hosted child; never counts as attached. */
+export const CLIENT_ID_EDITOR_REPORTER = "editor-reporter";
+/**
+ * Resident frame-witness reporter inside a hosted child (issue #222 FW-03/FW-04).
+ * Bookkeeping-only like the editor reporter: it must never keep a host attached or flip
+ * attachedEver, or warm-host reclaim never fires.
+ */
+export const CLIENT_ID_FRAME_REPORTER = "frame-reporter";
+
+/**
+ * @param {{ type?: string, clientId?: string } | null | undefined} msg
+ * @returns {"probe" | "editor-reporter" | "frame-reporter" | "client"}
+ */
+export function classifyClientHello(msg) {
+	const clientId = msg && typeof msg.clientId === "string" ? msg.clientId : "";
+	if (clientId === CLIENT_ID_PROBE) return "probe";
+	if (clientId === CLIENT_ID_EDITOR_REPORTER) return "editor-reporter";
+	if (clientId === CLIENT_ID_FRAME_REPORTER) return "frame-reporter";
+	return "client";
+}
+
+/**
+ * Socket bookkeeping implied by a hello classification (issue #103 §C / #130).
+ *
+ * `probe` and `editor-reporter` are bookkeeping-only: neither may keep
+ * `attachedClients` — whose sole source is the runner's `clients` set —
+ * non-zero, or warm-host reclaim never fires and hosts leak (issue #75). Both
+ * therefore leave `clients` at hello time, while their socket stays writable so
+ * probe replies and editor_state keep flowing.
+ *
+ * `persist: false` for probes is deliberate: the attach resolver probes every
+ * HOST_PROBE_RETRY_MS (see host-probe.mjs), so one host.json write per probe
+ * would amplify fenced writes — the exact cost the runner's probe-socket write
+ * suppression exists to avoid. Dropping the socket from `clients` already makes
+ * the in-memory count right, and the next heartbeat (<=1s) persists it.
+ *
+ * `suppressCloseWrite: true` is the other half of that suppression: close is the
+ * wrong moment to flush a record a probe never changed.
+ *
+ * An unrecognized kind falls back to the real-client row on purpose — counting
+ * an unknown connection is the conservative direction (it can only delay
+ * reclaim, never risk killing a host with a live client).
+ *
+ * @param {"probe" | "editor-reporter" | "frame-reporter" | "client"} kind
+ * @returns {{ keepInClients: boolean, registerReporter: boolean,
+ *             flipAttachedEver: boolean, persist: boolean, suppressCloseWrite: boolean }}
+ */
+export function helloBookkeeping(kind) {
+	switch (kind) {
+		case "probe":
+			return { keepInClients: false, registerReporter: false, flipAttachedEver: false, persist: false, suppressCloseWrite: true };
+		case "editor-reporter":
+			return { keepInClients: false, registerReporter: true, flipAttachedEver: false, persist: true, suppressCloseWrite: false };
+		case "frame-reporter":
+			// Same policy as the editor reporter (issue #222 FW-04): bookkeeping-only, no
+			// attachEver flip, but the socket stays writable so enable/intent keep flowing.
+			return { keepInClients: false, registerReporter: false, flipAttachedEver: false, persist: true, suppressCloseWrite: false };
+		default:
+			return { keepInClients: true, registerReporter: false, flipAttachedEver: true, persist: true, suppressCloseWrite: false };
+	}
+}

package/packages/board/src/core/ids.mjs

@@ -0,0 +1,35 @@
+/** ID generation for views and runs. */
+import { randomBytes } from "node:crypto";
+
+/** @param {string} prefix @returns {string} e.g. "view_8f3a1c2b". */
+export function genId(prefix) {
+	return `${prefix}_${randomBytes(5).toString("hex")}`;
+}
+
+/** @returns {string} a new view (row) id. */
+export const newViewId = () => genId("view");
+
+/** @returns {string} a new run id. */
+export const newRunId = () => genId("run");
+
+/** @returns {string} a new follow-up queue item id. */
+export const newFollowUpId = () => genId("follow");
+
+/**
+ * Derive a short, filesystem-safe slug from a free-text task, for display names.
+ * @param {string} text
+ * @param {number} [maxWords]
+ * @returns {string}
+ */
+export function slugifyTask(text, maxWords = 5) {
+	const words = String(text)
+		.toLowerCase()
+		.replace(/[`'"]/g, "")
+		.replace(/[^a-z0-9]+/g, " ")
+		.trim()
+		.split(/\s+/)
+		.filter(Boolean)
+		.slice(0, maxWords);
+	const slug = words.join("-");
+	return slug || "task";
+}

package/packages/board/src/core/ime-cursor-coalesce.mjs

@@ -0,0 +1,193 @@
+/**
+ * IME cursor-rect flicker fix (issue #28).
+ *
+ * pi-tui's doRender() emits each frame as separate terminal.write() calls:
+ *
+ *   1. ESC[?2026h ...content... ESC[?2026l   (differential/full frame, sync block)
+ *   2. ESC[<n>A/B ESC[<col>G                  (positionHardwareCursor park write)
+ *   3. ESC[?25l                               (hideCursor - bypasses write())
+ *
+ * The park sequences sit OUTSIDE the synchronized-output block. Terminals that
+ * honor ?2026 (WezTerm et al.) present a frame and report the IME cursor
+ * rectangle at each ?2026l boundary, so every frame produces two cursor-rect
+ * reports at different positions (diff-write end vs parked input line) and the
+ * IME candidate window bounces at frame rate. E2E measured on WezTerm + fcitx5:
+ * ~20 position changes / 4s with the split writes, 0 with the park inside the
+ * block (see issue #28 for the full experiment).
+ *
+ * This module wraps a Terminal instance's write/hideCursor/showCursor at runtime
+ * and folds the out-of-block park/hide sequences back INSIDE the frame's sync
+ * block, re-emitting the frame as a single write. Content is byte-identical up
+ * to reordering of the trailing ?2026l; nothing is dropped or added.
+ *
+ * Safety properties (issue #28):
+ * - No match -> passthrough: any write that isn't a pure cursor-park/hide
+ *   sequence flushes the held frame unchanged first, preserving byte order.
+ * - The three writes happen inside one synchronous doRender() stack, so a
+ *   process.nextTick flush is enough to see them all; the added latency is
+ *   sub-millisecond.
+ * - Uninstall restores the original methods; a WeakMap makes overlapping
+ *   installs on the same terminal refcounted and idempotent.
+ * - Kill switch: AGENT_BOARD_IME_FIX=0 disables installation entirely.
+ *
+ * If pi-tui ever folds positionHardwareCursor into the sync block upstream,
+ * the "pure park sequence following a sync-end write" pattern stops matching
+ * and this wrapper degrades to a passthrough (one buffered write per frame,
+ * same bytes) - no behavior change.
+ */
+
+const ESC = String.fromCharCode(27);
+/** ESC[?2026l - end of a synchronized-output block. */
+const SYNC_END = ESC + "[?2026l";
+
+/**
+ * Cursor sequences positionHardwareCursor() emits after a frame: relative row
+ * moves (ESC[<n>A / ESC[<n>B, n optional) and an absolute column set
+ * (ESC[<col>G), plus the cursor visibility toggles (ESC[?25l/h). These are
+ * the ONLY sequences safe to fold into the block - anything else (line clears,
+ * absolute positioning, OSC/DCS queries, content) flushes the held frame.
+ */
+const PARK_SEQUENCE = new RegExp(
+	"^(?:" + ESC + "\\[\\d*[AB]|" + ESC + "\\[\\d+G|" + ESC + "\\[\\?25[hl])*$",
+);
+
+/** True when a write ends a synchronized-output block (pi-tui frame writes do). */
+export function endsWithSyncEnd(data) {
+	return typeof data === "string" && data.endsWith(SYNC_END);
+}
+
+/** True when data is exclusively cursor park/visibility sequences (see above). */
+export function isPureCursorParking(data) {
+	return typeof data === "string" && data.length > 0 && PARK_SEQUENCE.test(data);
+}
+
+/** Insert seq just before the trailing SYNC_END of a held frame write. */
+export function mergeIntoSyncBlock(held, seq) {
+	return held.slice(0, held.length - SYNC_END.length) + seq + SYNC_END;
+}
+
+/** terminal -> active wrapper, so overlapping installs share one wrapper. */
+const activeWrappers = new WeakMap();
+
+/**
+ * Each wrapTerminalWrites() call returns its own guarded handle: idempotent
+ * per handle, refcounted across handles — the patch is torn down only when
+ * the LAST caller uninstalls (CR round 1, issue-1).
+ */
+function refcountedUninstall(entry) {
+	let done = false;
+	return () => {
+		if (done) return;
+		done = true;
+		entry.refs -= 1;
+		if (entry.refs > 0) return;
+		entry.teardown();
+	};
+}
+
+/**
+ * Patch write/hideCursor/showCursor on a terminal instance so each frame's
+ * out-of-block park/hide sequences are folded into the frame's sync block and
+ * emitted as one write. Returns an uninstall function (idempotent, drops the
+ * patch when the last caller uninstalls).
+ */
+export function wrapTerminalWrites(terminal) {
+	if (!terminal || typeof terminal.write !== "function" || typeof terminal.hideCursor !== "function" || typeof terminal.showCursor !== "function") {
+		throw new Error("terminal must expose write/hideCursor/showCursor");
+	}
+	const existing = activeWrappers.get(terminal);
+	if (existing) {
+		existing.refs += 1;
+		return refcountedUninstall(existing);
+	}
+
+	const original = {
+		write: terminal.write.bind(terminal),
+		hideCursor: terminal.hideCursor.bind(terminal),
+		showCursor: terminal.showCursor.bind(terminal),
+	};
+	/** Frame write ending in SYNC_END, accumulating park/hide merges. */
+	let held = null;
+	let flushScheduled = false;
+
+	const flush = () => {
+		if (held === null) return;
+		const out = held;
+		held = null;
+		original.write(out);
+	};
+
+	const scheduleFlush = () => {
+		if (flushScheduled) return;
+		flushScheduled = true;
+		process.nextTick(() => {
+			flushScheduled = false;
+			flush();
+		});
+	};
+
+	/** Fold a park/hide seq into the held frame, or emit it standalone. */
+	const mergeOrEmit = (seq, directEmit) => {
+		if (held !== null) {
+			held = mergeIntoSyncBlock(held, seq);
+			return;
+		}
+		directEmit();
+	};
+
+	terminal.write = (data) => {
+		if (typeof data !== "string" || data.length === 0) {
+			flush();
+			original.write(data);
+			return;
+		}
+		if (held !== null) {
+			// Only a pure park/hide burst may join the held frame; anything
+			// else means this isn't a doRender park tail - flush unchanged.
+			if (isPureCursorParking(data)) {
+				held = mergeIntoSyncBlock(held, data);
+				return;
+			}
+			flush();
+		}
+		if (endsWithSyncEnd(data)) {
+			held = data;
+			scheduleFlush();
+			return;
+		}
+		original.write(data);
+	};
+
+	terminal.hideCursor = () => mergeOrEmit(ESC + "[?25l", original.hideCursor);
+	terminal.showCursor = () => mergeOrEmit(ESC + "[?25h", original.showCursor);
+
+	const entry = { refs: 1, teardown: null };
+	entry.teardown = () => {
+		flush();
+		terminal.write = original.write;
+		terminal.hideCursor = original.hideCursor;
+		terminal.showCursor = original.showCursor;
+		activeWrappers.delete(terminal);
+	};
+
+	activeWrappers.set(terminal, entry);
+	return refcountedUninstall(entry);
+}
+
+/**
+ * Install the coalescer on a TUI's terminal. Never throws: on any surprise
+ * (shape change upstream, kill switch) it returns null and behavior stays
+ * exactly as today.
+ */
+export function installImeCursorCoalesce(tui) {
+	if (process.env.AGENT_BOARD_IME_FIX === "0") return null;
+	try {
+		const terminal = tui && tui.terminal;
+		if (!terminal || typeof terminal.write !== "function" || typeof terminal.hideCursor !== "function" || typeof terminal.showCursor !== "function") {
+			return null;
+		}
+		return wrapTerminalWrites(terminal);
+	} catch {
+		return null;
+	}
+}

package/packages/board/src/core/invocation.mjs

@@ -0,0 +1,43 @@
+/**
+ * Resolve how to invoke the `pi` worker and the `node` runner across install shapes:
+ *  - pi as `dist/cli.js` under system node  → piCommand=node, piArgsPrefix=[cli.js]
+ *  - pi as a bun-compiled binary            → piCommand="pi" (on PATH)
+ *  - generic node/bun runtime               → piCommand=execPath
+ * Mirrors the logic in the official subagent example's getPiInvocation().
+ */
+import { existsSync } from "node:fs";
+import * as path from "node:path";
+
+/** @returns {boolean} true when process.execPath is a generic node/bun runtime (not a compiled app). */
+function isGenericRuntime() {
+	const name = path.basename(process.execPath).toLowerCase();
+	return /^(node|bun)(\.exe)?$/.test(name);
+}
+
+/**
+ * Compute `{ piCommand, piArgsPrefix }` for spawning the pi worker.
+ * @returns {{ piCommand: string, piArgsPrefix: string[] }}
+ */
+export function resolvePiInvocation() {
+	const script = process.argv[1];
+	const isBunVirtual = typeof script === "string" && script.startsWith("/$bunfs/root/");
+	if (script && !isBunVirtual && existsSync(script)) {
+		// Running the pi cli script under a runtime — re-run the same script.
+		return { piCommand: process.execPath, piArgsPrefix: [script] };
+	}
+	if (!isGenericRuntime()) {
+		// Compiled pi binary invoked directly.
+		return { piCommand: process.execPath, piArgsPrefix: [] };
+	}
+	// Fallback: rely on `pi` being on PATH.
+	return { piCommand: "pi", piArgsPrefix: [] };
+}
+
+/**
+ * Resolve a real `node` executable to run the detached `.mjs` runner.
+ * @returns {string}
+ */
+export function resolveNode() {
+	if (isGenericRuntime()) return process.execPath;
+	return "node";
+}