@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/board/src/commands/attach-decision.mjs

@@ -0,0 +1,66 @@
+/**
+ * Attach decision tables for the agent-board attach flow (issue #70).
+ *
+ * Pure mapping functions extracted from the two near-duplicate attach()
+ * implementations (src/commands/attach-flow.ts and the private copy in
+ * src/commands/agent-board.ts) so the branching contract is node-testable.
+ * Both TS files consume these for their prelude and resolver-result
+ * branching; they must stay free of I/O, service calls, and UI.
+ */
+
+/** Default message surfaced when the resolver reports pending without a reason. */
+export const ATTACH_PENDING_DEFAULT_MESSAGE = "Session host is starting — try again shortly.";
+
+/**
+ * Prelude facts as observed from a dashboard row.
+ * @typedef {{ rowAlive: boolean, rowHostActive: boolean, stopFirst: boolean }} AttachPreludeFacts
+ */
+
+/**
+ * Map the attach prelude guards to a plan.
+ *
+ * The prelude only guards live JSON-runner rows (alive with no host claim):
+ * a row with an active host (starting/alive/stopping) passes straight
+ * through to the async resolver — attaching must not block or warn while a
+ * host is starting (issue #70).
+ *
+ * @param {AttachPreludeFacts} facts
+ * @returns {{ plan: "warn-running" } | { plan: "stop-first" } | { plan: "proceed" }}
+ */
+export function planAttachPrelude({ rowAlive, rowHostActive, stopFirst }) {
+	if (rowAlive && !rowHostActive) {
+		return stopFirst ? { plan: "stop-first" } : { plan: "warn-running" };
+	}
+	return { plan: "proceed" };
+}
+
+/**
+ * Map a `resolveAttachTarget()` result to the attach action plan.
+ *
+ * `socketPath` is typed `string | null` upstream; a pty resolution without a
+ * usable path is a transient resolver inconsistency and maps to
+ * notify-pending (retry later) rather than a misleading "missing".
+ *
+ * @param {{ kind: "pty", socketPath: string | null, sessionFile?: string, instanceId?: string | null } |
+ *          { kind: "session", sessionFile: string } |
+ *          { kind: "pending", sessionFile?: string, reason?: string } |
+ *          { kind: "missing" }} resolved
+ * @returns {{ plan: "open-pty", socketPath: string } |
+ *           { plan: "session-switch", sessionFile: string } |
+ *           { plan: "notify-pending", reason: string } |
+ *           { plan: "notify-missing" }}
+ */
+export function planAttachResolved(resolved) {
+	switch (resolved?.kind) {
+		case "pty":
+			return resolved.socketPath != null
+				? { plan: "open-pty", socketPath: resolved.socketPath }
+				: { plan: "notify-pending", reason: ATTACH_PENDING_DEFAULT_MESSAGE };
+		case "session":
+			return { plan: "session-switch", sessionFile: resolved.sessionFile };
+		case "pending":
+			return { plan: "notify-pending", reason: resolved.reason ?? ATTACH_PENDING_DEFAULT_MESSAGE };
+		default:
+			return { plan: "notify-missing" };
+	}
+}

package/packages/board/src/commands/attach-flow.ts

@@ -0,0 +1,251 @@
+/**
+ * Reusable attach-flow helpers shared by the `agent-board` and `bg` commands.
+ *
+ * Pure helpers (paths, prompts, current-view lookup) plus the resolver-driven
+ * attach flow: since issue #70 the attach path calls the async
+ * `resolveAttachTarget()` once and plans via `attach-decision.mjs`, instead of
+ * the old attachTarget-hint → ensureHost double path.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { restoreChrome } from "../ui/chrome.ts";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { createService } from "../runtime/service.mjs";
+import { planAttachPrelude, planAttachResolved } from "./attach-decision.mjs";
+import { screenLogPath } from "../core/paths.mjs";
+import { appendDiagnostic } from "../core/diagnostics.mjs";
+import { PtyAttachComponent, type PtyAttachResult } from "../ui/pty-attach.js";
+import type { DashboardResult } from "../ui/dashboard.js";
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+export type AttachOutcome = { action: "detached" | "closed" | "switched" | "none" };
+
+/** Open the PTY-attach UI for a live agent session. */
+export async function openPtyAttach(
+	ctx: ExtensionCommandContext,
+	root: string,
+	viewId: string,
+	name: string,
+	socketPath: string,
+): Promise<PtyAttachResult> {
+	ctx.ui.setWorkingVisible(false);
+	ctx.ui.setHeader(() => ({ render: () => [], invalidate() {} }));
+	ctx.ui.setFooter(() => ({ render: () => [], invalidate() {} }));
+	ctx.ui.setTitle(`agent-board: ${name}`);
+	try {
+		return await ctx.ui.custom<PtyAttachResult>(
+			(tui, theme, keybindings, done) =>
+				new PtyAttachComponent(tui, theme as never, keybindings, done, {
+					socketPath,
+					screenLogPath: root ? screenLogPath(root, viewId) : undefined,
+					title: name,
+					onDiagnostic: root
+						? (event) => {
+								// Best effort, like every other diagnostics writer.
+								try {
+									appendDiagnostic(root, viewId, event as never);
+								} catch {
+									/* diagnostics must never break attach */
+								}
+							}
+						: undefined,
+				}),
+			{
+				overlay: true,
+				overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+			},
+		);
+	} finally {
+		restoreChrome(ctx);
+	}
+}
+
+/** Show a brief overlay while the session switch is being initiated. */
+export async function showSwitchingOverlay(
+	ctx: ExtensionCommandContext,
+	name: string,
+	reason: string,
+): Promise<{ hide(): void } | null> {
+	let handle: { hide(): void } | null = null;
+	void ctx.ui.custom<null>(
+		(tui, theme) => ({
+			render(width: number): string[] {
+				const height = tui.terminal?.rows ?? 24;
+				const out = Array.from({ length: Math.max(0, Math.floor(height / 2) - 2) }, () => "");
+				out.push(clipLine(theme.fg("accent", theme.bold(`Switching to "${name}"…`)), width));
+				out.push(clipLine(theme.fg("dim", `Starting fallback session switch (${reason})`), width));
+				while (out.length < height) out.push("");
+				return out;
+			},
+			invalidate() {},
+		}),
+		{
+			overlay: true,
+			overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 },
+			onHandle: (h) => {
+				handle = h;
+			},
+		},
+	);
+	await sleep(50);
+	return handle;
+}
+
+function clipLine(text: string, width: number): string {
+	return truncateToWidth(text, width);
+}
+
+/** Return the viewId of whichever agent session matches the current pi session file. */
+export function currentViewId(
+	ctx: ExtensionCommandContext,
+	service: ReturnType<typeof createService>,
+): string | null {
+	const currentSessionFile = ctx.sessionManager.getSessionFile();
+	if (!currentSessionFile) return null;
+	return service.rows().find((r) => samePath(r.meta.sessionFile, currentSessionFile))?.meta.id ?? null;
+}
+
+export function samePath(a: string, b: string): boolean {
+	return resolve(a) === resolve(b);
+}
+
+/**
+ * Attach to an agent session through the single async resolver entry point.
+ * PTY readiness is decided by `resolveAttachTarget()` (real connect + hello
+ * probe, with bounded recovery); this function only maps its result to UI
+ * actions (issue #70 — no more attachTarget-hint → ensureHost double path).
+ */
+export async function attach(
+	ctx: ExtensionCommandContext,
+	service: ReturnType<typeof createService>,
+	root: string,
+	viewId: string,
+	stopFirst: boolean,
+): Promise<AttachOutcome> {
+	const row = service.row(viewId);
+	if (!row) {
+		ctx.ui.notify("Session no longer exists.", "warning");
+		return { action: "none" };
+	}
+	const prelude = planAttachPrelude({ rowAlive: row.alive, rowHostActive: row.hostActive, stopFirst });
+	if (prelude.plan === "warn-running") {
+		ctx.ui.notify("Session is still running. Stop it before attaching, or confirm from the dashboard.", "warning");
+		return { action: "none" };
+	}
+	if (prelude.plan === "stop-first") {
+		service.stop(viewId);
+		// Give the runner a moment to terminate the worker and release the session file.
+		await sleep(500);
+	}
+
+	const plan = planAttachResolved(await service.resolveAttachTarget(viewId));
+	if (plan.plan === "open-pty") {
+		void service.markVisited?.(viewId)?.catch(() => {});
+		const result = await openPtyAttach(ctx, root, row.meta.id, row.meta.name, plan.socketPath);
+		void service.markVisited?.(viewId)?.catch(() => {});
+		if (result.action === "quit") {
+			ctx.shutdown();
+			return { action: "switched" }; // Nothing to come back to.
+		}
+		return { action: result.action === "closed" ? "closed" : "detached" };
+	}
+	if (plan.plan === "session-switch") {
+		const latest = service.row(viewId) ?? row;
+		if (!existsSync(latest.meta.sessionFile)) {
+			ctx.ui.notify("Session file isn't ready yet — try again once the run has started.", "warning");
+			return { action: "none" };
+		}
+		const name = latest.meta.name;
+		void service.markVisited?.(viewId)?.catch(() => {});
+		const switchingOverlay = await showSwitchingOverlay(ctx, name, "PTY unavailable");
+		const result = await ctx.switchSession(latest.meta.sessionFile, {
+			withSession: async (replaced) => {
+				replaced.ui.notify(`Attached to "${name}". Press ← on empty input to return to agent board.`, "info");
+				installBackToDashboard(replaced, service, openDashboardFn);
+			},
+		}).finally(() => {
+			try {
+				switchingOverlay?.hide();
+			} catch {}
+		});
+		if (result.cancelled) {
+			ctx.ui.notify("Attach cancelled.", "warning");
+			return { action: "none" };
+		}
+		return { action: "switched" };
+	}
+	if (plan.plan === "notify-pending") {
+		ctx.ui.notify(plan.reason, "info");
+		return { action: "none" };
+	}
+	ctx.ui.notify("Session no longer exists.", "warning");
+	return { action: "none" };
+}
+
+/**
+ * The openDashboard function reference used by installBackToDashboard when called
+ * from attach(). This is set at module initialisation time by agent-board.ts via
+ * setOpenDashboardFn so that attach-flow.ts does not need to import from agent-board.ts
+ * (which would create a circular dependency).
+ */
+type OpenDashboardFn = (
+	ctx: Pick<ExtensionCommandContext, "ui" | "cwd" | "modelRegistry" | "model">,
+	service: ReturnType<typeof createService>,
+	options?: { initialSelectedId?: string | null },
+) => Promise<DashboardResult>;
+
+let openDashboardFn: OpenDashboardFn = async () => {
+	throw new Error("openDashboardFn not initialised — call setOpenDashboardFn first");
+};
+
+/** Called once by agent-board.ts to wire up the openDashboard dependency. */
+export function setOpenDashboardFn(fn: OpenDashboardFn): void {
+	openDashboardFn = fn;
+}
+
+/**
+ * Install the ← keybinding that opens the dashboard from inside an attached session.
+ * `openDashboard` is accepted as a parameter to avoid a circular import between
+ * agent-board.ts and attach-flow.ts.
+ */
+export function installBackToDashboard(
+	ctx: ExtensionCommandContext,
+	service: ReturnType<typeof createService>,
+	openDashboard: OpenDashboardFn,
+): void {
+	ctx.ui.setStatus("agent-board.back", ctx.ui.theme.fg("muted", "← board"));
+	let opening = false;
+	ctx.ui.onTerminalInput((data: string) => {
+		if (opening || !matchesKey(data, Key.left)) return undefined;
+		// Do not steal normal cursor-left while the user is composing a message.
+		if (ctx.ui.getEditorText().length > 0) return undefined;
+		opening = true;
+		void (async () => {
+			try {
+				let selectedId = currentViewId(ctx, service);
+				while (true) {
+					if (selectedId) void service.markVisited?.(selectedId)?.catch(() => {});
+					void service.reconcile().catch(() => {});
+					const result = await openDashboard(ctx, service, { initialSelectedId: selectedId });
+					if (result.action !== "attach") return;
+					selectedId = result.viewId;
+					const target = service.row(result.viewId);
+					const currentSessionFile = ctx.sessionManager.getSessionFile();
+					if (target && currentSessionFile && samePath(target.meta.sessionFile, currentSessionFile)) {
+						ctx.ui.notify("Already attached to this session.", "info");
+						continue;
+					}
+					const outcome = await attach(ctx, service, service.root, result.viewId, result.stopFirst);
+					if (outcome.action === "switched") return;
+				}
+			} catch (err) {
+				ctx.ui.notify(`Couldn't open agent board: ${err instanceof Error ? err.message : String(err)}`, "error");
+			} finally {
+				opening = false;
+			}
+		})();
+		return { consume: true };
+	});
+}

package/packages/board/src/commands/bg.ts

@@ -0,0 +1,103 @@
+/** `/bg` command: adopt the current interactive Pi session into Agent Board. */
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { createService } from "../runtime/service.mjs";
+import { dashboardAttachLoop } from "./agent-board.js";
+
+const NEW_SESSION = "new session";
+
+export interface BgCommandOptions {
+	root: string;
+	runnerScript: string;
+	ptyRunnerScript?: string;
+	titleRunnerScript?: string;
+	piCommand: string;
+	piArgsPrefix: string[];
+	getThinkingLevel: () => "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+}
+
+export function registerBgCommand(pi: ExtensionAPI, opts: BgCommandOptions): void {
+	pi.registerCommand("bg", {
+		description: "Adopt the current session into Agent Board and optionally queue a prompt",
+		handler: async (args, ctx) => {
+			await handleBgCommand(args, ctx, opts);
+		},
+	});
+}
+
+async function handleBgCommand(args: string, ctx: ExtensionCommandContext, opts: BgCommandOptions): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify("/bg requires interactive mode.", "warning");
+		return;
+	}
+	const sessionFile = ctx.sessionManager.getSessionFile();
+	const service = createService({
+		root: opts.root,
+		runnerScript: opts.runnerScript,
+		ptyRunnerScript: opts.ptyRunnerScript,
+		titleRunnerScript: opts.titleRunnerScript,
+		piCommand: opts.piCommand,
+		piArgsPrefix: opts.piArgsPrefix,
+		defaultCwd: ctx.cwd,
+		// Stale-defaultModel launch guard (issue #90): live list, undefined
+		// when the registry is unavailable so validation conservatively skips.
+		availableModels: () => {
+			try {
+				return ctx.modelRegistry.getAvailable();
+			} catch {
+				return undefined;
+			}
+		},
+	});
+	// A session that isn't saved anywhere has nothing to come back to, but the board still opens.
+	if (!sessionFile) {
+		await dashboardAttachLoop(ctx, service, opts.root, null, opts.getThinkingLevel);
+		return;
+	}
+	const model = modelRef(ctx.model as any);
+	// adoptSession is async (routes through the view-state coordinator, issue #91).
+	const adopted = await service.adoptSession({
+		sessionFile,
+		cwd: ctx.cwd,
+		model,
+		thinkingLevel: opts.getThinkingLevel(),
+		// A row that exists keeps its name, which may be one you gave it.
+		name: hasOwnName(service, sessionFile) ? undefined : sessionName(ctx),
+	});
+	if (!adopted.ok || !adopted.viewId) {
+		ctx.ui.notify(adopted.error ?? "Could not background current session.", "warning");
+		return;
+	}
+	const prompt = String(args || "").trim();
+	if (prompt) {
+		const reply = service.queueFollowUp(adopted.viewId, prompt, { delivery: "queue", source: "bg-command" }) as { ok: boolean; error?: string };
+		if (!reply.ok) ctx.ui.notify(reply.error ?? "Could not queue background prompt.", "warning");
+		else ctx.ui.notify("Prompt queued for background session.", "info");
+	}
+	await dashboardAttachLoop(ctx, service, opts.root, adopted.viewId, opts.getThinkingLevel);
+}
+
+function hasOwnName(service: ReturnType<typeof createService>, sessionFile: string): boolean {
+	const row = service.rows().find((candidate) => candidate.meta.sessionFile === sessionFile);
+	return row !== undefined && row.meta.name !== NEW_SESSION;
+}
+
+/** Its name if it has one, then what you first asked. A session with neither is new. */
+function sessionName(ctx: ExtensionCommandContext): string {
+	const named = ctx.sessionManager.getSessionName?.();
+	if (named) return named;
+	for (const entry of ctx.sessionManager.getEntries() as any[]) {
+		if (entry.type !== "message" || entry.message?.role !== "user") continue;
+		const content = entry.message.content;
+		const text = typeof content === "string" ? content : (content ?? []).map((part: any) => part.text ?? "").join(" ");
+		const line = String(text).trim().split("\n")[0];
+		if (line) return line.slice(0, 48);
+	}
+	return NEW_SESSION;
+}
+
+function modelRef(model: any): string | null {
+	if (!model || typeof model !== "object") return null;
+	if (typeof model.provider === "string" && typeof model.id === "string") return `${model.provider}/${model.id}`;
+	if (typeof model.id === "string") return model.id;
+	return null;
+}

package/packages/board/src/commands/board-model.ts

@@ -0,0 +1,21 @@
+/** `/board-model`: which model writes the board's titles, summaries and states. */
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { readConfig, setHelperModel } from "../core/config.mjs";
+
+const OFF = "Off: use built-in rules, no model calls";
+
+export function registerBoardModelCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("board-model", {
+		description: "Choose the model for the board's titles, summaries and states, or turn it off",
+		handler: async (_args, ctx: ExtensionCommandContext) => {
+			if (!ctx.hasUI) return;
+			const refs = ctx.modelRegistry.getAvailable().map((model) => `${model.provider}/${model.id}`);
+			const current = readConfig().model;
+			const choice = await ctx.ui.select(`Board helper model (now: ${current ?? "off"})`, [OFF, ...refs]);
+			if (choice === undefined) return;
+			const model = choice === OFF ? null : choice;
+			setHelperModel(model);
+			ctx.ui.notify(model ? `The board's helper calls now use ${model}.` : "The board's helper model calls are off.", "info");
+		},
+	});
+}

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

@@ -0,0 +1,184 @@
+/**
+ * Atomic + crash-tolerant file helpers used across the extension and the runner.
+ *
+ * Writes go to a temp sibling then `rename()` (atomic on the same filesystem) so a
+ * reader never observes a half-written JSON file. Reads tolerate missing/corrupt files.
+ */
+import { randomBytes } from "node:crypto";
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+
+/** Retry backoff (ms) for rename retries; index i is the delay after attempt i. */
+export const RENAME_RETRY_BACKOFF_MS = [10, 50, 250];
+/** Error codes that mean "transient sharing violation" — retryable on Windows. */
+export const RENAME_RETRY_ERROR_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
+
+/** @param {string} dir */
+export function ensureDir(dir) {
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/**
+ * rename() with retries for Windows sharing-violation races.
+ *
+ * On Windows, libuv opens files without FILE_SHARE_DELETE, so replacing an
+ * existing target while any other process holds it open for reading throws
+ * EPERM/EBUSY/EACCES. The reader window is microseconds, so a few retries
+ * with a short backoff succeed almost always. Non-whitelisted errors
+ * (e.g. EISDIR) are configuration errors and throw immediately.
+ * @param {string} tmp
+ * @param {string} file
+ * @param {{ rename?: (a: string, b: string) => void, delays?: number[], errorCodes?: Set<string> }} [opts]
+ */
+export function renameWithRetry(tmp, file, opts = {}) {
+	const rename = opts.rename ?? renameSync;
+	const delays = opts.delays ?? RENAME_RETRY_BACKOFF_MS;
+	const errorCodes = opts.errorCodes ?? RENAME_RETRY_ERROR_CODES;
+	for (let attempt = 0; ; attempt++) {
+		try {
+			rename(tmp, file);
+			return;
+		} catch (err) {
+			const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+			if (!errorCodes.has(code) || attempt >= delays.length) {
+				// Exhausted or non-transient: leave no .tmp litter behind, then
+				// surface the original error so callers can degrade deliberately.
+				try { unlinkSync(tmp); } catch { /* best effort */ }
+				throw err;
+			}
+		}
+		// Synchronous sleep (Atomics.wait) — atomicWrite is a sync API.
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delays[attempt]);
+	}
+}
+
+/**
+ * Atomically write a string to `file` (creates parent dirs).
+ * @param {string} file
+ * @param {string} data
+ */
+export function atomicWrite(file, data) {
+	ensureDir(path.dirname(file));
+	const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+	writeFileSync(tmp, data, "utf8");
+	renameWithRetry(tmp, file);
+}
+
+/**
+ * Atomically write a value as pretty JSON.
+ * @param {string} file
+ * @param {unknown} value
+ */
+export function atomicWriteJson(file, value) {
+	atomicWrite(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/**
+ * Read and parse JSON, returning `fallback` when the file is missing or unparseable.
+ * @template T
+ * @param {string} file
+ * @param {T} fallback
+ * @returns {T}
+ */
+export function readJson(file, fallback) {
+	try {
+		if (!existsSync(file)) return fallback;
+		const raw = readFileSync(file, "utf8");
+		if (!raw.trim()) return fallback;
+		return /** @type {T} */ (JSON.parse(raw));
+	} catch {
+		return fallback;
+	}
+}
+
+/**
+ * Append one line (a trailing newline is added) to a log/jsonl file.
+ * @param {string} file
+ * @param {string} line
+ */
+export function appendLine(file, line) {
+	ensureDir(path.dirname(file));
+	appendFileSync(file, line.endsWith("\n") ? line : `${line}\n`, "utf8");
+}
+
+/**
+ * Append one JSON value as a JSONL record.
+ * @param {string} file
+ * @param {unknown} value
+ */
+export function appendJsonl(file, value) {
+	appendLine(file, JSON.stringify(value));
+}
+
+/**
+ * Read a JSONL file into parsed objects, skipping blank/corrupt lines.
+ * @param {string} file
+ * @returns {any[]}
+ */
+export function readJsonl(file) {
+	try {
+		if (!existsSync(file)) return [];
+		const out = [];
+		for (const line of readFileSync(file, "utf8").split("\n")) {
+			const t = line.trim();
+			if (!t) continue;
+			try {
+				out.push(JSON.parse(t));
+			} catch {
+				/* skip corrupt line */
+			}
+		}
+		return out;
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Read the newest `limit` JSONL records. Corrupt lines are skipped.
+ * @param {string} file
+ * @param {number} [limit]
+ * @returns {any[]}
+ */
+export function readJsonlTail(file, limit = 50) {
+	const all = readJsonl(file);
+	const n = Math.max(0, Math.floor(Number(limit) || 0));
+	return n > 0 ? all.slice(-n) : all;
+}
+
+/**
+ * Best-effort delete helper used by cleanup actions.
+ * @param {string} file
+ * @returns {boolean}
+ */
+export function removeFile(file) {
+	try {
+		if (!existsSync(file)) return false;
+		unlinkSync(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Read a file's text, returning `fallback` if missing.
+ * @param {string} file
+ * @param {string} [fallback]
+ * @returns {string}
+ */
+export function readText(file, fallback = "") {
+	try {
+		return existsSync(file) ? readFileSync(file, "utf8") : fallback;
+	} catch {
+		return fallback;
+	}
+}

package/packages/board/src/core/attach-delete.mjs

@@ -0,0 +1,24 @@
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+
+/**
+ * Issue #147: key resolution for the in-attach delete gesture. Pure — never
+ * reads socket/connection/editor state, so the gesture works even while the
+ * host is down. Second ctrl+x is swallowed (cancel-swallow, user adjudication
+ * 2026-10-10): the chord is a confirm toggle here, and forwarding it would
+ * inject one message.copy into the child Pi.
+ * @param {{ confirmArmed: boolean }} state
+ * @param {string} data raw key chunk
+ * @returns {{ action: "arm" | "confirm" | "cancel" | "cancel-swallow" | "forward", confirmArmed: boolean }}
+ */
+export function resolveAttachDeleteKey(state, data) {
+	if (matchesKey(data, Key.ctrl("x"))) {
+		return state.confirmArmed ? { action: "cancel-swallow", confirmArmed: false } : { action: "arm", confirmArmed: true };
+	}
+	if (state.confirmArmed) {
+		if (data === "y" || data === "Y" || matchesKey(data, Key.enter)) {
+			return { action: "confirm", confirmArmed: false };
+		}
+		return { action: "cancel", confirmArmed: false };
+	}
+	return { action: "forward", confirmArmed: false };
+}