@junghanacs/entwurf 0.38.1 → 0.40.0

package/pi-extensions/lib/remote-pair-send.ts

@@ -0,0 +1,325 @@
+/**
+ * remote-pair-send — the SENDING half of #107's one declared remote pair (rail 2a).
+ *
+ * It sits in front of the local v2 decider, at the surface. With no route declaration, or a target
+ * the declaration does not name, the local path runs unchanged. When the declaration names the
+ * target, any local trace of that gid (a record entry in any state, or anything at its control
+ * socket path) fails closed as an ambiguity before transport. Otherwise the call runs over one
+ * transport call: no synthetic record, no new backend, no new rail plan, and no retry.
+ *
+ * Sender: only the caller's authoritative envelope becomes the claim. It must be the declared local
+ * citizen; an anonymous envelope or another gid is refused before transport. The model chooses
+ * neither host nor command: both come from the operator's declaration.
+ *
+ * Remote command: ssh joins the remote words into one shell string. So the alias and the remote
+ * declaration path are held to a narrow POSIX-safe charset that needs no quoting, and the command
+ * is the fixed `entwurf remote-pair-receive --pair <path>`. There is no quoting engine here.
+ *
+ * Receipt: a result is decided only when the exit code and the one stdout JSON line agree
+ * (see {@link classifyRemoteReceipt}). Everything else is `remote-indeterminate`: the other host
+ * may or may not have enqueued. Read and answer stay unknown until a reply arrives.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { controlSocketPathIn } from "./control-socket-path.js";
+import type { SenderEnvelope } from "./entwurf-control-rpc.ts";
+import type { EntwurfV2SurfaceRendered, SurfaceEntwurfV2Params } from "./entwurf-v2-surface.ts";
+import { defaultMetaSessionsDir, metaRecordExistsByGardenId, requireGardenId } from "./meta-session.ts";
+import type { RemoteClaim, RemotePairRejectReason } from "./remote-pair-receive.ts";
+import { inspectControlSocketPath } from "./socket-discovery.ts";
+
+/** The SENDING host's declaration of its one remote pair. */
+export interface RemoteRouteDeclaration {
+	/** The target's garden id on the other host. */
+	remoteGardenId: string;
+	/** SSH alias for the other host (route label; never an identity). */
+	ssh: string;
+	/** The garden id on THIS host that may send to it. */
+	localGardenId: string;
+	/** Absolute path of the other host's pair declaration, passed to its receive entry. */
+	remotePairFile: string;
+}
+
+export interface RemoteTransportResult {
+	exitCode: number | null;
+	signal: string | null;
+	timedOut: boolean;
+	stdout: string;
+	stderr: string;
+}
+
+export interface RemoteTransport {
+	run(argv: readonly string[], stdin: string, timeoutMs: number): Promise<RemoteTransportResult>;
+}
+
+export type RemoteSendOutcome =
+	| { kind: "remote-accepted"; text: string }
+	| { kind: "remote-pair-refused"; reason: RemotePairRejectReason; detail: string }
+	| { kind: "remote-reported-error"; text: string }
+	| { kind: "remote-invalid"; detail: string }
+	| { kind: "remote-indeterminate"; why: string; exitCode: number | null; stderrTail: string };
+
+export class RemoteRouteDeclarationError extends Error {}
+
+const SSH_ALIAS = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const REMOTE_PATH = /^\/[A-Za-z0-9._/-]+$/;
+const CONNECT_TIMEOUT_SECONDS = 10;
+export const REMOTE_SEND_TIMEOUT_MS = 30_000;
+const PAIR_REJECT_REASONS: readonly string[] = ["remote-pair-from-mismatch", "remote-pair-target-mismatch"];
+
+export function parseRemoteRouteDeclaration(text: string): RemoteRouteDeclaration {
+	const what = "remote route declaration";
+	let raw: unknown;
+	try {
+		raw = JSON.parse(text);
+	} catch (err) {
+		throw new RemoteRouteDeclarationError(`${what}: not JSON (${err instanceof Error ? err.message : String(err)})`);
+	}
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+		throw new RemoteRouteDeclarationError(`${what}: must be a JSON object`);
+	}
+	const obj = raw as Record<string, unknown>;
+	const want = ["localGardenId", "remoteGardenId", "remotePairFile", "ssh"];
+	const got = Object.keys(obj).sort();
+	if (got.length !== want.length || got.some((k, i) => k !== want[i])) {
+		throw new RemoteRouteDeclarationError(`${what}: keys must be exactly ${want.join(", ")} (got ${got.join(", ")})`);
+	}
+	const { ssh, remotePairFile } = obj;
+	if (typeof ssh !== "string" || !SSH_ALIAS.test(ssh)) {
+		throw new RemoteRouteDeclarationError(`${what}: "ssh" must be an alias matching ${SSH_ALIAS}`);
+	}
+	if (
+		typeof remotePairFile !== "string" ||
+		!REMOTE_PATH.test(remotePairFile) ||
+		remotePairFile.split("/").includes("..")
+	) {
+		throw new RemoteRouteDeclarationError(
+			`${what}: "remotePairFile" must be an absolute path matching ${REMOTE_PATH} with no ".." segment`,
+		);
+	}
+	return {
+		remoteGardenId: requireGardenId(obj.remoteGardenId),
+		ssh,
+		localGardenId: requireGardenId(obj.localGardenId),
+		remotePairFile,
+	};
+}
+
+/** The one argv the transport runs. Every word is inside the no-quoting charset above. */
+export function remoteReceiveArgv(route: RemoteRouteDeclaration): string[] {
+	return [
+		"ssh",
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		`ConnectTimeout=${CONNECT_TIMEOUT_SECONDS}`,
+		route.ssh,
+		"entwurf",
+		"remote-pair-receive",
+		"--pair",
+		route.remotePairFile,
+	];
+}
+
+function tail(s: string): string {
+	return s.length > 400 ? s.slice(-400) : s;
+}
+
+/**
+ * Decide only on agreement. 0 + dispatched/!isError = accepted; 3 + rejected(pair reason) = pair
+ * refused; 4 + dispatched/isError = the other host reported an error while processing (its own text
+ * says what is known, e.g. `retry-safe: false` after a possible write; this line infers neither
+ * delivery nor non-delivery); 2 + invalid = it refused our
+ * input. Any other exit, a signal, a timeout, no line, more than one line, non-JSON, or a JSON
+ * kind/field that disagrees with the exit is indeterminate.
+ */
+export function classifyRemoteReceipt(r: RemoteTransportResult): RemoteSendOutcome {
+	const indeterminate = (why: string): RemoteSendOutcome => ({
+		kind: "remote-indeterminate",
+		why,
+		exitCode: r.exitCode,
+		stderrTail: tail(r.stderr),
+	});
+	if (r.timedOut) return indeterminate("timed out");
+	if (r.signal !== null) return indeterminate(`ended by signal ${r.signal}`);
+	if (r.exitCode === null) {
+		return indeterminate(
+			r.stderr.startsWith("spawn failed")
+				? "the transport did not start (spawn failed)"
+				: "did not exit (no exit code)",
+		);
+	}
+	if (![0, 2, 3, 4].includes(r.exitCode)) return indeterminate(`exit ${r.exitCode}`);
+	const nl = r.stdout.indexOf("\n");
+	if (nl === -1 || nl !== r.stdout.length - 1) return indeterminate("stdout is not exactly one line");
+	let j: unknown;
+	try {
+		j = JSON.parse(r.stdout);
+	} catch {
+		return indeterminate("stdout is not JSON");
+	}
+	if (j === null || typeof j !== "object" || Array.isArray(j)) return indeterminate("stdout is not a JSON object");
+	const o = j as Record<string, unknown>;
+	const keys = Object.keys(o).sort().join(",");
+	if (r.exitCode === 0 && keys === "isError,kind,text" && o.kind === "dispatched" && o.isError === false) {
+		if (typeof o.text === "string") return { kind: "remote-accepted", text: o.text };
+	}
+	if (r.exitCode === 4 && keys === "isError,kind,text" && o.kind === "dispatched" && o.isError === true) {
+		if (typeof o.text === "string") return { kind: "remote-reported-error", text: o.text };
+	}
+	if (r.exitCode === 3 && keys === "detail,kind,reason" && o.kind === "rejected") {
+		if (typeof o.reason === "string" && PAIR_REJECT_REASONS.includes(o.reason) && typeof o.detail === "string") {
+			return { kind: "remote-pair-refused", reason: o.reason as RemotePairRejectReason, detail: o.detail };
+		}
+	}
+	if (r.exitCode === 2 && keys === "detail,kind" && o.kind === "invalid" && typeof o.detail === "string") {
+		return { kind: "remote-invalid", detail: o.detail };
+	}
+	return indeterminate(`exit ${r.exitCode} disagrees with its receipt`);
+}
+
+function render(route: RemoteRouteDeclaration, o: RemoteSendOutcome): EntwurfV2SurfaceRendered {
+	const via = `via ${route.ssh}`;
+	switch (o.kind) {
+		case "remote-accepted":
+			return {
+				isError: false,
+				text: `entwurf_v2 remote ${via} → accepted by the other host (its fact; read/answer unknown until a reply arrives; paths below are on the other host)\n${o.text}`,
+			};
+		case "remote-reported-error":
+			// The other host's dispatch returned isError. That can follow a write (an enqueue whose
+			// stamp or signal then threw is `retry-safe: false`), so this header claims neither
+			// non-delivery nor safety to resend: the other host's own text below is the fact.
+			return {
+				isError: true,
+				text: `entwurf_v2 remote ${via} → the other host reported an error while processing; read its receipt below, delivery is not inferred from this line; not retried (paths below are on the other host)\n${o.text}`,
+			};
+		case "remote-pair-refused":
+			return {
+				isError: true,
+				text: `entwurf_v2 remote ${via} → refused by the other host's pair: ${o.reason} (${o.detail})`,
+			};
+		case "remote-invalid":
+			return { isError: true, text: `entwurf_v2 remote ${via} → the other host refused the input: ${o.detail}` };
+		case "remote-indeterminate":
+			return {
+				isError: true,
+				text:
+					`entwurf_v2 remote ${via} → indeterminate: ${o.why}. The other host may or may not have enqueued; ` +
+					`not retried.${o.stderrTail ? `\n${o.stderrTail}` : ""}`,
+			};
+	}
+}
+
+function refuse(text: string): EntwurfV2SurfaceRendered {
+	return { isError: true, text: `entwurf_v2 rejected: ${text}` };
+}
+
+export interface RemoteRouteOptions {
+	senderProvider: () => SenderEnvelope | undefined;
+	/** The declaration, already read; null = no remote pair on this host. */
+	route: RemoteRouteDeclaration | null;
+	/** Any local trace of this gid: a record entry in any state, or anything at its socket path. */
+	localTrace: (gardenId: string) => Promise<boolean>;
+	transport: RemoteTransport;
+	/** The existing local surface, run unchanged when the route does not apply. */
+	runLocal: (
+		params: SurfaceEntwurfV2Params,
+		opts: { senderProvider: () => SenderEnvelope | undefined },
+	) => Promise<EntwurfV2SurfaceRendered>;
+	timeoutMs?: number;
+}
+
+export async function runEntwurfV2WithRemoteRoute(
+	params: SurfaceEntwurfV2Params,
+	opts: RemoteRouteOptions,
+): Promise<EntwurfV2SurfaceRendered> {
+	const route = opts.route;
+	if (route === null || params.target !== route.remoteGardenId) {
+		return opts.runLocal(params, { senderProvider: opts.senderProvider });
+	}
+	if (await opts.localTrace(route.remoteGardenId)) {
+		return refuse(
+			`remote-route-local-conflict: ${route.remoteGardenId} is declared remote ${`via ${route.ssh}`} but this host also has a local trace of it; not choosing`,
+		);
+	}
+	const sender = opts.senderProvider();
+	if (!sender || sender.origin === "external-mcp" || sender.sessionId !== route.localGardenId) {
+		return refuse(
+			`remote-sender-not-declared: only ${route.localGardenId} may send over this route (sender: ${sender ? sender.sessionId : "none"})`,
+		);
+	}
+	const claim: RemoteClaim = {
+		from: sender.sessionId,
+		fromAgentId: sender.agentId,
+		fromCwd: sender.cwd,
+		target: route.remoteGardenId,
+		message: params.message,
+		wantsReply: params.wants_reply ?? false,
+	};
+	const result = await opts.transport.run(
+		remoteReceiveArgv(route),
+		JSON.stringify(claim),
+		opts.timeoutMs ?? REMOTE_SEND_TIMEOUT_MS,
+	);
+	return render(route, classifyRemoteReceipt(result));
+}
+
+/**
+ * The production local-trace fact: the store's own record-entry inspection (absent vs anything
+ * else — readable, unreadable, symlinked or drifted all count) and the control-socket path
+ * inspection, in EVERY socket dir the caller names. The bridge's `ENTWURF_DIR` can differ from the
+ * decider's canonical dir, so both are passed and a trace in either one means this host already
+ * answers to the gid.
+ */
+export function makeLocalTraceFact(dirs: { sessionsDir: string; controlSocketDirs: readonly string[] }) {
+	const socketDirs = [...new Set(dirs.controlSocketDirs.map((d) => path.resolve(d)))];
+	return async (gardenId: string): Promise<boolean> => {
+		if (metaRecordExistsByGardenId(gardenId, dirs.sessionsDir)) return true;
+		for (const dir of socketDirs) {
+			const inspection = await inspectControlSocketPath(controlSocketPathIn(dir, gardenId));
+			if (inspection.kind !== "absent") return true;
+		}
+		return false;
+	};
+}
+
+/** The operator's opt-in file name. One per host; it declares that host's one remote pair. */
+export const REMOTE_PAIR_OPT_IN_FILE = "entwurf-remote-pair.json";
+
+/**
+ * Where the opt-in file lives: beside the meta-record store, i.e. the pi agent dir unless an
+ * `ENTWURF_META_SESSIONS_DIR` override relocates the store (then the file follows the store it
+ * pairs). Read-only reuse of the existing root resolution; nothing here writes.
+ */
+export function remotePairOptInPath(): string {
+	return path.join(path.dirname(defaultMetaSessionsDir()), REMOTE_PAIR_OPT_IN_FILE);
+}
+
+/**
+ * Read the opt-in file once, at the moment of use (no cache). Absent is the ONLY "off". A
+ * symlink, a non-regular entry, an unreadable file or an invalid declaration throws: the operator
+ * opted in, so a broken opt-in is refused rather than read as off.
+ *
+ * The bridge this declares is the operator's to build and secure (for example a private network
+ * such as Tailscale, plus SSH authentication and permissions). Entwurf only walks the declared
+ * route: it installs, configures, discovers and verifies none of it, and never retries.
+ */
+export function readRemotePairOptIn(file: string): RemoteRouteDeclaration | null {
+	let st: fs.Stats;
+	try {
+		st = fs.lstatSync(file);
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+		throw err;
+	}
+	if (!st.isFile()) {
+		throw new RemoteRouteDeclarationError(`remote pair opt-in ${file} must be a regular non-symlink file`);
+	}
+	try {
+		return parseRemoteRouteDeclaration(fs.readFileSync(file, "utf8"));
+	} catch (err) {
+		throw new RemoteRouteDeclarationError(`${file}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}

package/pi-extensions/lib/remote-pair-transport.ts

@@ -0,0 +1,81 @@
+/**
+ * remote-pair-transport — the production process adapter behind #107's `RemoteTransport` (rail 2c).
+ *
+ * One child per send: `spawn(argv[0], argv.slice(1))` with no shell, stdin written once and closed,
+ * stdout and stderr captured separately. On the bound it signals ITS OWN child only (TERM, then KILL
+ * after a short grace); if the pipes are still held after one more grace, it closes its own read ends
+ * and settles as a timeout rather than waiting for a close that may never come. It is not a process manager: it tracks no
+ * other process, scans nothing, and never retries. Classification belongs to
+ * `classifyRemoteReceipt`; this module only reports what the child did.
+ */
+
+import { spawn } from "node:child_process";
+import type { RemoteTransport, RemoteTransportResult } from "./remote-pair-send.ts";
+
+const CAPTURE_CAP = 64 * 1024;
+const KILL_GRACE_MS = 2000;
+const FINAL_GRACE_MS = 2000;
+
+function capped(chunks: Buffer[], size: { n: number }, chunk: Buffer): void {
+	if (size.n >= CAPTURE_CAP) return;
+	const room = CAPTURE_CAP - size.n;
+	const piece = chunk.length > room ? chunk.subarray(0, room) : chunk;
+	chunks.push(piece);
+	size.n += piece.length;
+}
+
+export const processTransport: RemoteTransport = {
+	run(argv, stdin, timeoutMs): Promise<RemoteTransportResult> {
+		return new Promise((resolve) => {
+			const out: Buffer[] = [];
+			const err: Buffer[] = [];
+			const outN = { n: 0 };
+			const errN = { n: 0 };
+			let timedOut = false;
+			let spawnError: string | null = null;
+			let settled = false;
+			const child = spawn(argv[0], argv.slice(1), { shell: false, stdio: ["pipe", "pipe", "pipe"] });
+			let killTimer: NodeJS.Timeout | undefined;
+			let finalTimer: NodeJS.Timeout | undefined;
+			const settle = (code: number | null, signal: NodeJS.Signals | null): void => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(bound);
+				if (killTimer) clearTimeout(killTimer);
+				if (finalTimer) clearTimeout(finalTimer);
+				const stderr = Buffer.concat(err).toString("utf8");
+				resolve({
+					exitCode: spawnError ? null : code,
+					signal: spawnError ? null : signal,
+					timedOut,
+					stdout: Buffer.concat(out).toString("utf8"),
+					stderr: spawnError ? `spawn failed: ${spawnError}${stderr ? `\n${stderr}` : ""}` : stderr,
+				});
+			};
+			const bound = setTimeout(() => {
+				timedOut = true;
+				child.kill("SIGTERM");
+				killTimer = setTimeout(() => {
+					child.kill("SIGKILL");
+					// Something else may still hold our stdout/stderr pipes (an inherited descendant,
+					// an ssh ControlMaster). We do not chase it: after one more grace we close OUR read
+					// ends and settle as a timeout, which the receipt reads as indeterminate.
+					finalTimer = setTimeout(() => {
+						child.stdout.destroy();
+						child.stderr.destroy();
+						settle(child.exitCode, child.signalCode);
+					}, FINAL_GRACE_MS);
+				}, KILL_GRACE_MS);
+			}, timeoutMs);
+			child.stdout.on("data", (c: Buffer) => capped(out, outN, c));
+			child.stderr.on("data", (c: Buffer) => capped(err, errN, c));
+			child.on("error", (e) => {
+				spawnError = e.message;
+			});
+			// A child that exits before reading stdin closes the pipe; that is its outcome, not ours.
+			child.stdin.on("error", () => {});
+			child.on("close", (code, signal) => settle(code, signal));
+			child.stdin.end(stdin);
+		});
+	},
+};

package/pi-extensions/lib/socket-discovery.ts

@@ -57,6 +57,7 @@ import {
 	controlSocketPathIn,
 	defaultControlSocketDir,
 	gardenIdFromSocketFilename,
+	WIN32_PIPE_PREFIX,
 } from "./control-socket-path.js";
 import type { SocketProbe } from "./entwurf-facts.ts";
 import { SESSION_ID_RE } from "./session-id.js";
@@ -117,7 +118,9 @@ export type TargetSocketInspection =
  * `record-less-socket` reject (a diagnostic state) — no probe, no acceptance.
  */
 export function isRecordLessSocketCandidate(inspection: TargetSocketInspection): boolean {
-	return inspection.kind === "socket-file";
+	// A Windows pipe name (#78) is never lstat-ed (see inspectControlSocketPath), so its
+	// `socket-file` carries no presence evidence and cannot confirm a record-less socket.
+	return inspection.kind === "socket-file" && !inspection.socketPath.startsWith(WIN32_PIPE_PREFIX);
 }
 
 export interface LstatLike {
@@ -139,6 +142,11 @@ export async function inspectControlSocketPath(
 	socketPath: string,
 	lstatFn: (p: string) => Promise<LstatLike> = (p) => fs.lstat(p),
 ): Promise<TargetSocketInspection> {
+	// Windows (#78): the address is a named pipe. The pipe filesystem has no symlinks to
+	// catch, and opening the name to stat it would CONNECT to it and consume an instance.
+	// So the name is never stat-ed: it is safe to probe because the probe itself refuses a
+	// pipe whose owner is not this token's expected owner before any byte.
+	if (socketPath.startsWith(WIN32_PIPE_PREFIX)) return { kind: "socket-file", socketPath };
 	let st: LstatLike;
 	try {
 		st = await lstatFn(socketPath);
@@ -243,9 +251,12 @@ export async function scanSocketProbes(
 	deps: Partial<SocketScanDeps> = {},
 ): Promise<SocketScanResult> {
 	const dir = deps.dir ?? CONTROL_SOCKET_DIR;
+	// Windows (#78) has no socket files to list and nothing scans the pipe namespace: the
+	// candidates are the record-backed citizens alone.
 	const readdir =
 		deps.readdir ??
 		(async (d: string): Promise<SocketDirEntry[]> => {
+			if (process.platform === "win32") return [];
 			const dirents = await fs.readdir(d, { withFileTypes: true });
 			return dirents.map((e) => ({ name: e.name, isSymbolicLink: e.isSymbolicLink() }));
 		});

package/pi-extensions/lib/socket-probe.ts

@@ -29,6 +29,7 @@
  */
 
 import * as net from "node:net";
+import { win32Native } from "./win32-native.js";
 
 export type SocketLiveness = "alive" | "dead" | "indeterminate";
 
@@ -66,6 +67,7 @@ export async function probeSocketLiveness(
 	opts: { timeoutMs?: number } = {},
 ): Promise<SocketLiveness> {
 	const timeoutMs = opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+	if (process.platform === "win32") return await probePipeLiveness(socketPath, timeoutMs);
 	return await new Promise<SocketLiveness>((resolve) => {
 		const socket = net.createConnection(socketPath);
 		const timer = setTimeout(() => {
@@ -86,3 +88,21 @@ export async function probeSocketLiveness(
 		});
 	});
 }
+
+/**
+ * The Windows probe (#78): the control address is a named pipe, and a connect alone would
+ * talk to whoever holds the name. The addon connects within one deadline and refuses a pipe
+ * whose owner is not this token's expected owner (`EPERM`) before any byte. Only `ENOENT`
+ * (no instance) is dead; a refused owner, a busy pipe past the deadline and every Win32
+ * failure stay indeterminate. A missing or drifted addon is not a liveness fact: that
+ * refusal throws.
+ */
+async function probePipeLiveness(pipeName: string, timeoutMs: number): Promise<SocketLiveness> {
+	const native = win32Native();
+	try {
+		await native.pipeProbe(pipeName, Math.max(0, Math.floor(timeoutMs)));
+		return "alive";
+	} catch (err) {
+		return classifyConnectError((err as { code?: string }).code);
+	}
+}

package/pi-extensions/lib/win32-native.js

@@ -0,0 +1,198 @@
+/**
+ * win32-native — the Windows preview's native surface (#78), and the only way to reach it.
+ *
+ * Node cannot open a file without following a final-component reparse point on Windows
+ * (libuv `UV_FS_O_NOFOLLOW` is 0), and it cannot check who owns a named pipe before
+ * talking to it. Those two capabilities come from one Entwurf-owned N-API addon,
+ * `native/win32-x64/entwurf_win.node`, built in CI from `native/win32/entwurf_win.c` and
+ * shipped beside `native/win32-x64/manifest.json`. This module verifies the manifest and
+ * the addon bytes BEFORE `process.dlopen`, and refuses by name otherwise:
+ *
+ *   ENTWURF_WIN32_UNSUPPORTED     not win32-x64, no addon in this install (an ordinary
+ *                                 Linux pack), a Node without the N-API floor, or a
+ *                                 verified addon this host cannot load
+ *   ENTWURF_WIN32_NATIVE_DRIFT    the manifest is malformed, or the addon bytes are not the
+ *                                 bytes the manifest names
+ *
+ * There is no repair, no download and no fallback: a refusal is the whole answer.
+ *
+ * Authored as `.js` for the reason `control-socket-path.js` is: it is imported from the
+ * tsc-emit root program and from the strip-types lanes alike. `meta-session.ts` reaches it
+ * only through a win32-only `createRequire`, so the installers that copy `meta-session.ts`
+ * on their own are unchanged on Linux and macOS. Keep dependency-free except node builtins.
+ */
+
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const WIN32_UNSUPPORTED_CODE = "ENTWURF_WIN32_UNSUPPORTED";
+export const WIN32_DRIFT_CODE = "ENTWURF_WIN32_NATIVE_DRIFT";
+
+const PACKAGE_NAME = "@junghanacs/entwurf";
+const NATIVE_DIR = path.join("native", "win32-x64");
+const ADDON_FILE = "entwurf_win.node";
+const SHA256 = /^[0-9a-f]{64}$/;
+// The addon is built against exactly this N-API version (native/win32/binding.gyp, build.mjs). A
+// manifest that declares any other value describes some other build: drift, not a floor to honour.
+const ADDON_NAPI_VERSION = 8;
+// One addon object per process, even if two module instances of this file exist (a
+// transpiling loader and Node's own loader can each evaluate it once).
+const SLOT = Symbol.for("entwurf.win32-native.addon");
+// DOS device names open a device, not a file, at any directory. The addon's GetFileType
+// check refuses a non-disk handle anyway; this keeps the open from ever being attempted.
+const DOS_DEVICE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)$/i;
+
+/**
+ * @param {string} code
+ * @param {string} message
+ * @param {unknown} [cause]
+ * @returns {Error & { code: string }}
+ */
+function refusal(code, message, cause) {
+	const err = /** @type {Error & { code: string }} */ (new Error(message, cause === undefined ? undefined : { cause }));
+	err.code = code;
+	return err;
+}
+
+/**
+ * The package root, found from where THIS module lives: the source depth
+ * (`<root>/pi-extensions/lib/`) first, then the compiled depth
+ * (`<root>/mcp/entwurf-bridge/dist/pi-extensions/lib/`). The root is the directory whose
+ * `package.json` names this package; `null` when neither depth does.
+ *
+ * @param {string} [from]
+ * @returns {string | null}
+ */
+export function win32NativePackageRoot(from = path.dirname(fileURLToPath(import.meta.url))) {
+	for (const up of [
+		["..", ".."],
+		["..", "..", "..", "..", ".."],
+	]) {
+		const root = path.resolve(from, ...up);
+		let name;
+		try {
+			name = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"))?.name;
+		} catch {
+			continue;
+		}
+		if (name === PACKAGE_NAME) return root;
+	}
+	return null;
+}
+
+/**
+ * Verify `<root>/native/win32-x64/` and return the addon path to load. Pure apart from
+ * reading the two files, so the refusals are provable on any host.
+ *
+ * @param {string} root
+ * @param {{ napi?: string | undefined }} [versions]
+ * @returns {{ addonPath: string, sha256: string, napiVersion: number }}
+ */
+export function verifyWin32NativeAt(root, versions = process.versions) {
+	const dir = path.join(root, NATIVE_DIR);
+	const manifestPath = path.join(dir, "manifest.json");
+	let raw;
+	try {
+		raw = fs.readFileSync(manifestPath, "utf8");
+	} catch (err) {
+		if (/** @type {{ code?: unknown }} */ (err).code === "ENOENT") {
+			throw refusal(
+				WIN32_UNSUPPORTED_CODE,
+				`this entwurf install carries no Windows addon (${manifestPath} is absent): only the Windows preview ` +
+					"artifact runs on Windows; an ordinary pack does not.",
+			);
+		}
+		throw refusal(WIN32_DRIFT_CODE, `cannot read ${manifestPath}`, err);
+	}
+	let manifest;
+	try {
+		manifest = JSON.parse(raw);
+	} catch (err) {
+		throw refusal(WIN32_DRIFT_CODE, `${manifestPath} is not JSON`, err);
+	}
+	if (
+		manifest?.schema !== 1 ||
+		manifest.platform !== "win32" ||
+		manifest.arch !== "x64" ||
+		manifest.file !== ADDON_FILE ||
+		typeof manifest.sha256 !== "string" ||
+		!SHA256.test(manifest.sha256) ||
+		manifest.napiVersion !== ADDON_NAPI_VERSION
+	) {
+		throw refusal(WIN32_DRIFT_CODE, `${manifestPath} does not describe one win32-x64 ${ADDON_FILE}`);
+	}
+	const napi = Number(versions.napi);
+	if (!(napi >= ADDON_NAPI_VERSION)) {
+		throw refusal(
+			WIN32_UNSUPPORTED_CODE,
+			`the Windows addon needs N-API ${ADDON_NAPI_VERSION}; this Node offers ${versions.napi ?? "none"}`,
+		);
+	}
+	const addonPath = path.join(dir, ADDON_FILE);
+	let bytes;
+	try {
+		bytes = fs.readFileSync(addonPath);
+	} catch (err) {
+		throw refusal(WIN32_DRIFT_CODE, `the manifest names ${addonPath}, which cannot be read`, err);
+	}
+	const sha256 = createHash("sha256").update(bytes).digest("hex");
+	if (sha256 !== manifest.sha256) {
+		throw refusal(
+			WIN32_DRIFT_CODE,
+			`${addonPath} is not the addon its manifest names (sha256 ${sha256} != ${manifest.sha256})`,
+		);
+	}
+	return { addonPath, sha256, napiVersion: ADDON_NAPI_VERSION };
+}
+
+/**
+ * @typedef {object} Win32NativeAddon
+ * @property {(file: string) => Buffer} readNoFollow
+ * @property {(name: string, line: string, timeoutMs: number) => Promise<{ responseLine: string, serverPid: number }>} pipeRpc
+ * @property {(name: string, timeoutMs: number) => Promise<{ serverPid: number }>} pipeProbe
+ * @property {() => { live: number, cancelledIncomplete: number }} ioStats
+ */
+
+/** @returns {Win32NativeAddon} */
+export function win32Native() {
+	const held = /** @type {Record<symbol, Win32NativeAddon | undefined>} */ (/** @type {unknown} */ (process))[SLOT];
+	if (held) return held;
+	if (process.platform !== "win32" || process.arch !== "x64") {
+		throw refusal(
+			WIN32_UNSUPPORTED_CODE,
+			`the Windows native surface exists only on win32-x64, not ${process.platform}-${process.arch}`,
+		);
+	}
+	const root = win32NativePackageRoot();
+	if (root === null) {
+		throw refusal(WIN32_UNSUPPORTED_CODE, `cannot find the ${PACKAGE_NAME} package root beside this module`);
+	}
+	const { addonPath } = verifyWin32NativeAt(root);
+	const module = { exports: {} };
+	try {
+		process.dlopen(module, addonPath);
+	} catch (err) {
+		throw refusal(WIN32_UNSUPPORTED_CODE, `this host cannot load the verified Windows addon ${addonPath}`, err);
+	}
+	const addon = /** @type {Win32NativeAddon} */ (module.exports);
+	/** @type {Record<symbol, Win32NativeAddon | undefined>} */ (/** @type {unknown} */ (process))[SLOT] = addon;
+	return addon;
+}
+
+/**
+ * Read a record's bytes on Windows, refusing a final-component reparse point (`ELOOP`) and
+ * a non-regular entry (`ENTWURF_ENOTREG`) on the very handle the read uses. Over 16 MiB is
+ * `EFBIG`; other Win32 failures are `EWIN32_<n>`.
+ *
+ * @param {string} file
+ * @returns {Buffer}
+ */
+export function win32ReadNoFollow(file) {
+	const stem = path.win32.basename(file).split(".")[0].replace(/[ ]+$/, "");
+	if (DOS_DEVICE.test(stem)) {
+		throw refusal("ENTWURF_ENOTREG", `${path.win32.basename(file)} names a DOS device, never a record`);
+	}
+	return win32Native().readNoFollow(file);
+}