@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,183 @@
+/**
+ * Filesystem layout for the agent-board store.
+ *
+ * Every helper takes an explicit `root` so tests can point at a tmp dir.
+ * The live default is `~/.pi/agent/agent-board/` (override with $AGENT_BOARD_ROOT;
+ * legacy $AGENT_VIEW_ROOT is also honored for migration).
+ */
+import { createHash } from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** @returns {string} the live store root (env override or ~/.pi/agent/agent-board). */
+export function defaultRoot() {
+	if (process.env.AGENT_BOARD_ROOT) return path.resolve(process.env.AGENT_BOARD_ROOT);
+	if (process.env.AGENT_VIEW_ROOT) return path.resolve(process.env.AGENT_VIEW_ROOT);
+	return path.join(os.homedir(), ".pi", "agent", "agent-board");
+}
+
+/** @param {string} root */
+export const rosterPath = (root) => path.join(root, "roster.json");
+/** @param {string} root */
+export const launchPrefsPath = (root) => path.join(root, "launch-prefs.json");
+/** @param {string} root */
+export const gcHistoryPath = (root) => path.join(root, "gc-history.jsonl");
+/** @param {string} root */
+export const cwdStatsPath = (root) => path.join(root, "cwd-stats.json");
+/** @param {string} root */
+export const providersPath = (root) => path.join(root, "providers.json");
+
+/** @param {string} root */
+export const viewsDir = (root) => path.join(root, "views");
+/** @param {string} root @param {string} viewId */
+export const viewDir = (root, viewId) => path.join(root, "views", viewId);
+/** @param {string} root @param {string} viewId */
+export const metaPath = (root, viewId) => path.join(viewDir(root, viewId), "meta.json");
+/** @param {string} root @param {string} viewId */
+export const statePath = (root, viewId) => path.join(viewDir(root, viewId), "state.json");
+/** @param {string} root @param {string} viewId */
+export const hostPath = (root, viewId) => path.join(viewDir(root, viewId), "host.json");
+/** Durable control-command journal for a view's host (issue #91 phase 5, spec
+ *  D4): one JSONL line per durable-command lifecycle transition
+ *  (accepted/applied). Sibling of host.json in the view dir. */
+export const controlJournalPath = (root, viewId) => path.join(viewDir(root, viewId), "control-journal.jsonl");
+/** @param {string} root @param {string} viewId */
+export const hostConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "host-config.json");
+/**
+ * Per-instance host config path. Each host launch owns its own config file so a
+ * concurrent launch can never overwrite another instance's prompt/cwd/model (issue #70).
+ * @param {string} root @param {string} viewId @param {string} instanceId
+ */
+export const hostConfigPathFor = (root, viewId, instanceId) =>
+	path.join(viewDir(root, viewId), `host-config.${instanceId}.json`);
+/** @param {string} root @param {string} viewId */
+export const titleConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "title-config.json");
+/** @param {string} root @param {string} viewId */
+export const autoStateConfigPath = (root, viewId) => path.join(viewDir(root, viewId), "auto-state-config.json");
+/**
+ * Named pipe used for the host control socket on Windows. Named pipes are kernel
+ * objects, not filesystem entries, so existsSync/unlink never apply to them; they
+ * vanish automatically when the owning process exits. Names must be ≤ 256 chars.
+ * @param {string} viewId
+ */
+export const controlPipeName = (viewId) => `\\\\.\\pipe\\pi-agent-board-${viewId}`;
+/**
+ * Control socket address for a view, platform-aware. On Windows plain filesystem
+ * paths cannot be bound by node's net module (EACCES) — only `\\.\pipe\`-style
+ * names work (see libuv#458, nodejs/node#55979).
+ * @param {"win32"|"linux"|"darwin"} platform
+ * @param {string} root
+ * @param {string} viewId
+ */
+export function controlSocketPathFor(platform, root, viewId) {
+	if (platform === "win32") return controlPipeName(viewId);
+	return path.join(viewDir(root, viewId), "control.sock");
+}
+/** @param {string} root @param {string} viewId */
+export const controlSocketPath = (root, viewId) => controlSocketPathFor(process.platform, root, viewId);
+/**
+ * Endpoint a hosted child's editor-state reporter should connect to.
+ *
+ * The runner knows which endpoint it actually bound and injects it into the
+ * child env as AGENT_BOARD_CONTROL_SOCKET (issue #103): since #70 the owned
+ * runner binds a per-instance address, while the reporter kept dialing the
+ * stable per-view one, so it never connected and the attach gate lost its
+ * authoritative editor state. The injected value wins; the stable address
+ * remains the fallback for legacy hosts and older runners that predate the key.
+ * @param {{ envSocketPath?: string | null, platform: "win32"|"linux"|"darwin", root: string, viewId: string }} args
+ */
+export function resolveControlEndpoint({ envSocketPath, platform, root, viewId }) {
+	const injected = typeof envSocketPath === "string" ? envSocketPath.trim() : "";
+	return injected.length > 0 ? injected : controlSocketPathFor(platform, root, viewId);
+}
+/**
+ * Per-instance control endpoint. Each new host instance binds its own socket/pipe,
+ * so a superseded runner can never unlink the current owner's endpoint (issue #70).
+ * win32 pipe names embed an 8-hex hash of the instanceId to stay under the 256-char limit.
+ * @param {"win32"|"linux"|"darwin"} platform
+ * @param {string} root
+ * @param {string} viewId
+ * @param {string} instanceId
+ */
+export function hostEndpointPathFor(platform, root, viewId, instanceId) {
+	if (platform === "win32") {
+		const hash = createHash("sha256").update(String(instanceId)).digest("hex").slice(0, 8);
+		return `\\\\.\\pipe\\pi-agent-board-${viewId}-${hash}`;
+	}
+	return path.join(viewDir(root, viewId), `control.${instanceId}.sock`);
+}
+/** @param {string} root @param {string} viewId */
+export const screenLogPath = (root, viewId) => path.join(viewDir(root, viewId), "screen.log");
+/**
+ * Well-known endpoint for the board-root View State Coordinator (issue #91, spec D3).
+ * Exactly one coordinator may own a root (token-fenced lease), so one stable path
+ * suffices; a stale POSIX socket left by a crashed coordinator is unlinked by the
+ * new lease owner before bind. win32 pipe names embed a 16-hex hash of the
+ * *normalized* root to stay under the 256-char limit and keep per-root isolation.
+ * @param {"win32"|"linux"|"darwin"} platform
+ * @param {string} root
+ */
+export function coordinatorEndpointPathFor(platform, root) {
+	if (platform === "win32") {
+		// Normalize before hashing: the pipe name must be invariant to the root's
+		// spelling (C:/x vs C:\x, trailing separators, dot segments). The lock path
+		// derived from the same root already is (via path.join); a mismatch yields
+		// "same lock, two pipes" — the panel probes a pipe nobody bound, spawns
+		// replacements that cannot take the held lease, and locks itself out
+		// (issue #124). resolve() is idempotent on canonical roots, so coordinators
+		// already deployed keep their pipe name and need no restart.
+		// win32 semantics are named explicitly rather than using the ambient
+		// path.resolve: this branch must emit the same pipe name on every host OS
+		// (on POSIX, ambient resolve treats `C:\x` as a relative path: no
+		// drive-letter or backslash-separator semantics), so platform-injected
+		// tests and CI behave identically everywhere.
+		const normalized = path.win32.resolve(root);
+		const hash = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+		return `\\\\.\\pipe\\agent-board-coordinator-${hash}`;
+	}
+	return path.join(root, "coordinator.sock");
+}
+/** @param {string} root @param {string} viewId */
+export const hostPidPath = (root, viewId) => path.join(viewDir(root, viewId), "host-pid.json");
+/** @param {string} root @param {string} viewId */
+export const runsDir = (root, viewId) => path.join(viewDir(root, viewId), "runs");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const runDir = (root, viewId, runId) => path.join(runsDir(root, viewId), runId);
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const statusPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "status.json");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const eventsPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "events.jsonl");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const stdoutPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "stdout.log");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const stderrPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "stderr.log");
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const pidPath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "pid.json");
+/** @param {string} root @param {string} viewId */
+export const diagnosticsPath = (root, viewId) => path.join(viewDir(root, viewId), "diagnostics.jsonl");
+/** @param {string} root @param {string} viewId */
+export const evidencePath = (root, viewId) => path.join(viewDir(root, viewId), "evidence.json");
+/** @param {string} root @param {string} viewId */
+export const codeRefsPath = (root, viewId) => path.join(viewDir(root, viewId), "github.json");
+/** @param {string} root @param {string} viewId */
+export const viewEvidencePath = evidencePath;
+/** @param {string} root @param {string} viewId */
+export const followUpQueuePath = (root, viewId) => path.join(viewDir(root, viewId), "queue.json");
+/** @param {string} root @param {string} viewId */
+export const queuePath = followUpQueuePath;
+/** @param {string} root @param {string} viewId */
+export const steeringPath = (root, viewId) => path.join(viewDir(root, viewId), "steering.json");
+/** @param {string} root @param {string} viewId @param {string} name */
+export const viewLockPath = (root, viewId, name) => path.join(viewDir(root, viewId), `${name}.lock`);
+/** @param {string} root @param {string} viewId @param {string} runId */
+export const runEvidencePath = (root, viewId, runId) => path.join(runDir(root, viewId, runId), "evidence.json");
+
+/** @param {string} root */
+export const sessionsDir = (root) => path.join(root, "sessions");
+/** @param {string} root @param {string} viewId */
+export const sessionFilePath = (root, viewId) => path.join(sessionsDir(root), `${viewId}.jsonl`);
+
+/** @param {string} root */
+export const worktreesDir = (root) => path.join(root, "worktrees");
+/** @param {string} root @param {string} viewId */
+export const worktreePath = (root, viewId) => path.join(worktreesDir(root), viewId);

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

@@ -0,0 +1,75 @@
+/** Process liveness checks and process identity capture. */
+import { readFileSync } from "node:fs";
+
+/**
+ * Whether `pid` refers to a live process.
+ * `process.kill(pid, 0)` throws ESRCH when the process is gone, and EPERM when it
+ * exists but we lack permission to signal it — EPERM still means "alive".
+ * @param {number|null|undefined} pid
+ * @returns {boolean}
+ */
+export function isAlive(pid) {
+	if (!pid || pid <= 0) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return /** @type {NodeJS.ErrnoException} */ (err).code === "EPERM";
+	}
+}
+
+/**
+ * Try to terminate a process tree gently, then force after `graceMs`.
+ * Safe no-op if already dead.
+ * @param {number|null|undefined} pid
+ * @param {number} [graceMs]
+ */
+export function killProcess(pid, graceMs = 4000) {
+	if (!isAlive(pid)) return;
+	try {
+		process.kill(/** @type {number} */ (pid), "SIGTERM");
+	} catch {
+		/* ignore */
+	}
+	setTimeout(() => {
+		if (isAlive(pid)) {
+			try {
+				process.kill(/** @type {number} */ (pid), "SIGKILL");
+			} catch {
+				/* ignore */
+			}
+		}
+	}, graceMs).unref?.();
+}
+
+/**
+ * POSIX process start token — /proc/<pid>/stat field 22 (starttime), stable
+ * across exec(2). Distinguishes an owned-live pid from a reused one; null on
+ * failure or non-Linux platforms. This is the single synchronous implementation
+ * (issue #238 removed the runner copies); the cross-platform async reader in
+ * process-identity-probe.mjs layers a win32 creation-time token on top, and
+ * host-meta lease identity uses this function directly (issue #112).
+ * @param {number|null|undefined} pid
+ * @returns {string|null}
+ */
+export function captureStartToken(pid) {
+	if (process.platform !== "linux" || !pid) return null;
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+		// comm (field 2) may contain spaces and parens — fields resume AFTER the
+		// last ')'. fields[0] is state (field 3) → starttime (field 22) is [19].
+		const afterComm = stat.slice(stat.lastIndexOf(")") + 1).trimStart();
+		return afterComm.split(/\s+/)[19] ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Launch-time identity for the current process, as stamped on host-meta
+ * acquisitions (issue #112).
+ * @returns {{pid: number, startToken: string|null}}
+ */
+export function currentProcessIdentity() {
+	return { pid: process.pid, startToken: captureStartToken(process.pid) };
+}

package/packages/board/src/core/prewarm-schedule.mjs

@@ -0,0 +1,41 @@
+/**
+ * Single-flight debounce for dashboard prewarm.
+ *
+ * Arrow-key navigation must move the selection and repaint immediately; host
+ * prewarm (which may spawn a PTY host and re-scan rows) is deferred so bursts
+ * of keypresses trigger exactly one prewarm for the final resting selection.
+ */
+
+/**
+ * @param {() => void} prewarm Invoked (with errors swallowed) once scheduling
+ *   goes quiet for `delayMs`. Re-reads current state at fire time.
+ * @param {number} [delayMs=200]
+ * @returns {{ schedule: () => void, cancel: () => void }}
+ */
+export function createPrewarmScheduler(prewarm, delayMs = 200) {
+	/** @type {ReturnType<typeof setTimeout> | null} */
+	let timer = null;
+	const fire = () => {
+		timer = null;
+		try {
+			prewarm();
+		} catch {
+			/* prewarm is best-effort; never break navigation */
+		}
+	};
+	return {
+		schedule() {
+			if (timer !== null) clearTimeout(timer);
+			const pending = setTimeout(fire, delayMs);
+			// Never let a pending debounce hold the event loop open on exit.
+			if (typeof pending.unref === "function") pending.unref();
+			timer = pending;
+		},
+		cancel() {
+			if (timer !== null) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		},
+	};
+}

package/packages/board/src/core/process-identity-probe.mjs

@@ -0,0 +1,228 @@
+/**
+ * Cross-platform process identity probe (issue #217) and start-token reader
+ * (issue #238).
+ *
+ * The probe produces the two corroborating signals — process creation time and
+ * command line — that `classifyUnverifiableProcess` judges when a recorded
+ * start token is missing. `readProcessStartToken` produces the comparable token
+ * itself: linux reads `/proc` and win32 converts the probe's creation time into
+ * a `ct:<ms>` token. Pure parsers are exported for exhaustive unit tests;
+ * `readProcessIdentityProbe` is the only I/O layer (one async `execFile` per
+ * pid, never throwing).
+ *
+ * `readProcessStartToken` has no darwin path on purpose: `ps` reports elapsed
+ * time at second resolution, so two reads of one process drift by up to ~1 s
+ * and a token comparison would misclassify a live process as `foreign`.
+ * Returning `null` keeps callers on the "unverifiable" path instead of
+ * guessing. The probe itself stays off linux: the `/proc` token already
+ * identifies processes there, so probing would only add latency.
+ */
+import { execFile } from "node:child_process";
+import { captureStartToken } from "./pid.mjs";
+
+/** Hard cap on one probe: a hung PowerShell/ps must not stall recovery. */
+export const PROBE_TIMEOUT_MS = 3_000;
+
+/** Cap on captured stdout — a command line is small; anything larger is junk. */
+const PROBE_MAX_BUFFER = 64 * 1024;
+
+/**
+ * Format an absolute creation time as the comparable `ct:` identity token
+ * (issue #238): two reads of the same process yield the same token regardless
+ * of when they happen. Only positive safe integers format — anything else
+ * (missing creation time, a fractional or out-of-range value, a coerced
+ * string) would produce a token that can never match a recorded one.
+ * @param {number} creationTimeMs
+ * @returns {string|null}
+ */
+export function creationTimeToken(creationTimeMs) {
+	if (!Number.isSafeInteger(creationTimeMs) || creationTimeMs <= 0) return null;
+	return `ct:${creationTimeMs}`;
+}
+
+/**
+ * Read the comparable start token for a process (issue #238): the token is
+ * recorded next to a lease and compared later to tell "same process" from
+ * "reused pid".
+ *
+ * - linux: `captureStartToken(pid)` — `/proc/<pid>/stat` starttime.
+ * - win32: probe → `creationTimeToken(creationTimeMs)` — CIM creation time is
+ *   millisecond-resolution, so two reads of one process are strictly equal.
+ * - anything else, including darwin: `null`, and the probe is never called.
+ *
+ * A pid that is not a positive safe integer yields `null` before any I/O; a
+ * probe rejection or unusable result also yields `null` (unverifiable, never
+ * "foreign").
+ *
+ * @param {number} pid
+ * @param {{ platform?: string, probe?: typeof readProcessIdentityProbe }} [opts]
+ * @returns {Promise<string|null>}
+ */
+export async function readProcessStartToken(pid, {
+	platform = process.platform,
+	probe = readProcessIdentityProbe,
+} = {}) {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+	if (platform === "linux") return captureStartToken(pid);
+	if (platform !== "win32") return null;
+	try {
+		const observed = await probe(pid);
+		return observed ? creationTimeToken(observed.creationTimeMs) : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Parse an epoch-milliseconds value from CIM JSON output. Accepts decimal
+ * digits only: PowerShell can hand back an empty string or a negative number
+ * for protected processes, neither of which is a usable creation time.
+ * @param {string} text
+ * @returns {number|null}
+ */
+export function parseUnixMillis(text) {
+	const trimmed = String(text ?? "").trim();
+	if (!/^\d+$/.test(trimmed)) return null;
+	const millis = Number(trimmed);
+	return Number.isSafeInteger(millis) && millis > 0 ? millis : null;
+}
+
+/**
+ * Parse the compressed CIM object emitted for a Windows process:
+ * `{"creation":<unix ms>|null,"cmd":"<command line>"|null}`. Malformed JSON or
+ * a non-object payload yields `null` (the judgment layer reads that as
+ * `unknown`, which is always safe).
+ * @param {string} text
+ * @returns {{creationTimeMs:number|null, commandLine:string|null}|null}
+ */
+export function parseProbeJson(text) {
+	if (typeof text !== "string") return null;
+	const trimmed = text.trim();
+	if (!trimmed) return null;
+	/** @type {any} */ let parsed;
+	try {
+		parsed = JSON.parse(trimmed);
+	} catch {
+		return null;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+	return {
+		creationTimeMs: parseUnixMillis(parsed.creation),
+		commandLine: typeof parsed.cmd === "string" && parsed.cmd.trim() ? parsed.cmd : null,
+	};
+}
+
+/** `[DD-]HH:MM:SS` (ps drops leading units it does not need). */
+const PS_ELAPSED_PATTERN = /^(?:(\d+)-)?(?:(\d+):)?(\d+):(\d+)$/;
+
+/**
+ * Parse a POSIX `ps` elapsed-time field into milliseconds. Handles the three
+ * shapes `ps -o etime=` emits: `MM:SS`, `HH:MM:SS`, and `D-HH:MM:SS`.
+ * @param {string} text
+ * @returns {number|null}
+ */
+export function parsePsElapsedMs(text) {
+	const match = PS_ELAPSED_PATTERN.exec(String(text ?? "").trim());
+	if (!match) return null;
+	const days = match[1] == null ? 0 : Number(match[1]);
+	const hours = match[2] == null ? 0 : Number(match[2]);
+	const minutes = Number(match[3]);
+	const seconds = Number(match[4]);
+	if (minutes > 59 || seconds > 59) return null;
+	return ((days * 24 + hours) * 3600 + minutes * 60 + seconds) * 1000;
+}
+
+/**
+ * Parse one `ps -p <pid> -o etime=,command=` line: the first whitespace-
+ * separated token is the elapsed time, everything after it is the command.
+ * `ps` reports age, not creation time, so callers pass the clock reading.
+ * @param {string} text
+ * @param {number} nowMs Epoch ms at which the probe output was read.
+ * @returns {{creationTimeMs:number|null, commandLine:string|null}|null}
+ */
+export function parsePsProbeLine(text, nowMs) {
+	if (typeof text !== "string") return null;
+	const trimmed = text.trim();
+	if (!trimmed) return null;
+	const split = trimmed.search(/\s/);
+	const elapsedText = split === -1 ? trimmed : trimmed.slice(0, split);
+	const commandLine = split === -1 ? "" : trimmed.slice(split).trim();
+	const elapsedMs = parsePsElapsedMs(elapsedText);
+	if (elapsedMs == null) return null;
+	return {
+		creationTimeMs: nowMs - elapsedMs,
+		commandLine: commandLine || null,
+	};
+}
+
+/**
+ * Windows CIM query: one round trip returns creation time (converted to Unix
+ * milliseconds in PowerShell so the parent needs no date parsing) and the
+ * command line. `-ErrorAction SilentlyContinue` keeps a vanished pid from
+ * turning into a non-zero exit; the empty result is handled as "unavailable".
+ * @param {number} pid
+ * @returns {string}
+ */
+function windowsProbeScript(pid) {
+	return "$p = Get-CimInstance Win32_Process -Filter \"ProcessId=" + pid + "\" -ErrorAction SilentlyContinue; "
+		+ "if ($p) { [pscustomobject]@{creation=[long]([datetimeoffset]$p.CreationDate).ToUnixTimeMilliseconds(); cmd=$p.CommandLine} | ConvertTo-Json -Compress }";
+}
+
+/**
+ * Resolve the platform-specific probe command. Platforms without a probe
+ * (`linux` and everything else) and invalid pids return `null`, so callers
+ * never spawn anything for them.
+ * @param {string} platform
+ * @param {number} pid
+ * @returns {{command:string, args:string[]}|null}
+ */
+export function resolveProbeCommand(platform, pid) {
+	if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+	if (platform === "win32") {
+		return {
+			command: "powershell.exe",
+			args: ["-NoProfile", "-NonInteractive", "-Command", windowsProbeScript(pid)],
+		};
+	}
+	if (platform === "darwin") {
+		return { command: "ps", args: ["-p", String(pid), "-o", "etime=,command="] };
+	}
+	return null;
+}
+
+/**
+ * Read `{ creationTimeMs, commandLine }` for `pid`, or `null` when the process
+ * cannot be observed (unsupported platform, invalid pid, non-zero exit,
+ * timeout, or empty output). `null` means "unverifiable", never "foreign".
+ *
+ * `execFileFn` is injectable for tests; the default is Node's async
+ * `execFile`. `windowsHide` mirrors `launchRun`'s detached spawn (issue #49):
+ * without it a console window flashes on Windows 11 25H2.
+ *
+ * @param {number} pid
+ * @param {{ platform?: string, execFileFn?: typeof execFile, timeoutMs?: number, nowMs?: () => number }} [opts]
+ * @returns {Promise<{creationTimeMs:number|null, commandLine:string|null}|null>}
+ */
+export async function readProcessIdentityProbe(pid, {
+	platform = process.platform,
+	execFileFn = execFile,
+	timeoutMs = PROBE_TIMEOUT_MS,
+	nowMs = Date.now,
+} = {}) {
+	const resolved = resolveProbeCommand(platform, pid);
+	if (!resolved) return null;
+	return new Promise((resolve) => {
+		execFileFn(resolved.command, resolved.args, { timeout: timeoutMs, windowsHide: true, maxBuffer: PROBE_MAX_BUFFER }, (error, stdout) => {
+			if (error) {
+				resolve(null);
+				return;
+			}
+			const text = String(stdout ?? "").trim();
+			if (!text) {
+				resolve(null);
+				return;
+			}
+			resolve(platform === "win32" ? parseProbeJson(text) : parsePsProbeLine(text, nowMs()));
+		});
+	});
+}

package/packages/board/src/core/prompt-transport.mjs

@@ -0,0 +1,13 @@
+/** Helpers for safely delivering prompts to Pi child processes. */
+
+/**
+ * Protect a prompt that is delivered as a positional CLI argument.
+ * Pi parses argv before it knows which tokens are prompt text, so a leading `-`
+ * would be treated as another flag and abort the run.
+ * @param {string} text
+ * @returns {string}
+ */
+export function encodePromptForCliArg(text) {
+	const raw = String(text ?? "");
+	return /^\s*-/.test(raw) ? ` ${raw}` : raw;
+}