@junghanacs/entwurf 0.38.1 → 0.39.0

package/mcp/entwurf-bridge/dist/pi-extensions/lib/win32-native.js

@@ -0,0 +1,182 @@
+/**
+ * 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);
+}

package/mcp/entwurf-bridge/src/index.ts

@@ -108,6 +108,7 @@ import {
 } from "../../../pi-extensions/lib/meta-session.ts";
 import { RESUME_CALL_REJECT_HINT, resumeCall } from "../../../pi-extensions/lib/mux-resume-call.ts";
 import { registerNativeConversation } from "../../../pi-extensions/lib/native-push/register.ts";
+import { probeSocketLiveness } from "../../../pi-extensions/lib/socket-probe.ts";
 
 const HOME = os.homedir();
 
@@ -137,6 +138,14 @@ try {
 // ENTWURF_DIR override the pi side does not. The path GRAMMAR is the shared leaf.
 const ENTWURF_DIR = process.env.ENTWURF_DIR ?? defaultControlSocketDir(HOME);
 
+/** Is this session's own control address up? A socket file's presence on Linux/macOS. On
+ * Windows (#78) the address is a named pipe, which has no file to look at and must not be
+ * opened by a stat (that connects): the owner-validated probe answers instead. */
+async function controlAddressPresent(socketPath: string): Promise<boolean> {
+	if (process.platform === "win32") return (await probeSocketLiveness(socketPath)) === "alive";
+	return existsSync(socketPath);
+}
+
 // ============================================================================
 // Live control-socket discovery for entwurf_peers lives in the TS fact-provider
 // (pi-extensions/lib/entwurf-fact-provider.ts → listEntwurfFacts), which the
@@ -219,7 +228,7 @@ class EntwurfSenderIdentityError extends Error {
 	}
 }
 
-function buildStrictPiSenderEnvelope(): SenderEnvelope {
+async function buildStrictPiSenderEnvelope(): Promise<SenderEnvelope> {
 	const sessionId = process.env.PI_SESSION_ID?.trim();
 	const agentId = process.env.PI_AGENT_ID?.trim();
 	const cwd = process.cwd();
@@ -239,7 +248,7 @@ function buildStrictPiSenderEnvelope(): SenderEnvelope {
 	const socketPath = controlSocketPathIn(ENTWURF_DIR, sessionId as string);
 	const self = computeSelfAddressability({
 		origin: "pi-session",
-		socketAlive: existsSync(socketPath),
+		socketAlive: await controlAddressPresent(socketPath),
 		socketPathComputable: true,
 	});
 	return {
@@ -338,7 +347,7 @@ async function resolveAuthoritativeSender(
 ): Promise<AuthoritativeSelf | null> {
 	const sessionId = process.env.PI_SESSION_ID?.trim();
 	const agentId = process.env.PI_AGENT_ID?.trim();
-	const pi = sessionId && agentId && cwd ? buildStrictPiSenderEnvelope() : null;
+	const pi = sessionId && agentId && cwd ? await buildStrictPiSenderEnvelope() : null;
 	const marker = resolveTrustedMetaSenderIdentity({
 		markerPath: process.env.ENTWURF_META_SENDER_MARKER?.trim() || undefined,
 	});
@@ -559,7 +568,7 @@ server.tool(
 				// live socket). The old code synthesized the path and printed it as if
 				// it existed — a lie when the session has no --entwurf-control (SE-1).
 				const socketPath = controlSocketPathIn(ENTWURF_DIR, sender.sessionId);
-				const socketState = existsSync(socketPath) ? "alive" : "expected";
+				const socketState = (await controlAddressPresent(socketPath)) ? "alive" : "expected";
 				extra.socketPath = socketPath;
 				extra.socketState = socketState;
 				lines.push(

package/native/win32-x64/manifest.json

@@ -0,0 +1,45 @@
+{
+	"schema": 1,
+	"platform": "win32",
+	"arch": "x64",
+	"file": "entwurf_win.node",
+	"sha256": "9837893521ec1d033913ca6cd1b705cb6e942e8d5c288948a1ed0ca0e28655e5",
+	"napiVersion": 8,
+	"builtWith": {
+		"node": "24.18.1",
+		"nodeGyp": "13.1.0",
+		"platformToolset": "v145",
+		"windowsTargetPlatformVersion": "10.0.26100.0",
+		"visualStudio": {
+			"displayName": "Visual Studio Enterprise 2026",
+			"installationVersion": "18.10.12224.181"
+		}
+	},
+	"source": {
+		"entwurf_win.c": "aa8a2994833d6dbbbf56c78687d42df52f645f3f35073943d897f58169219c31",
+		"binding.gyp": "be95dcfb152a91377a011aedbadd7943965ede251612394eacb405b20689f18e",
+		"package.json": "6ba65c909857f18a5d8e16b63fa55201b1d17261cc4afb1f2eea10514b2cac6a",
+		"package-lock.json": "d7dc3c48d003f2356d961972ad5515f192f2c846af8d0b551fa08d20ce155ede",
+		"build.mjs": "68120f85289e9598f440b1e0be506feb50a37897414d234ffc6698b754b2988e"
+	},
+	"provenance": {
+		"statement": "tracked C + declared upstream build glue",
+		"compiled": {
+			"entwurf_win.c": "tracked source",
+			"node-gyp/src/win_delay_load_hook.cc": {
+				"version": "13.1.0",
+				"sha256": "ec2357ffdf512151c21a52326ad3396aaa650b83e5c4a31153d216a155f68ecc",
+				"license": "MIT",
+				"notice": "LICENSES/node-gyp.txt",
+				"licenseSha256": "662a1b0115251cfb29c6aed0f221f8847bc49c6365d1c53a62c9f4bccc2489c3"
+			}
+		},
+		"declaredLinkInputs": [
+			"advapi32.lib",
+			"kernel32.lib",
+			"node.lib (import library, Node v24.18.1 win-x64)",
+			"MSVC static CRT (/MT)"
+		],
+		"headers": "Node v24.18.1 headers tarball (MIT), declarations only"
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@junghanacs/entwurf",
-	"version": "0.38.1",
+	"version": "0.39.0",
 	"description": "Visible sibling sessions across independent agent harnesses: launch in Herdr or tmux, reopen pi in tmux, and deliver messages by garden id; native bridges and Claude/Cortex ACP adapters.",
 	"license": "MIT",
 	"author": {
@@ -41,6 +41,8 @@
 	"files": [
 		"protocol.js",
 		"pi-extensions/",
+		"native/win32-x64/",
+		"LICENSES/node-gyp.txt",
 		"mcp/",
 		"scripts/",
 		"prompts/",
@@ -194,7 +196,7 @@
 		"check:core": "pnpm run check:toolchain && pnpm run check:vitest && pnpm run check:contracts",
 		"check:toolchain": "pnpm lint && pnpm typecheck",
 		"check:vitest": "./run.sh check-mux-fresh-call && ./run.sh check-acp-sdk-surface && ./run.sh check-pi-queue-oracle && ./run.sh check-tests-beside-behavior",
-		"check:contracts": "./run.sh check-demo-reproducibility && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-acp-foreground-only && ./run.sh check-acp-set-model-readback && ./run.sh check-acp-vendor-rejection && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push && ./run.sh check-pi-durable-beside && ./run.sh check-pi-durable-carrier && ./run.sh check-pi-durable-native-module",
+		"check:contracts": "./run.sh check-demo-reproducibility && ./run.sh check-shell-quote && ./run.sh check-entwurf-session-identity && ./run.sh check-meta-session && ./run.sh check-meta-v3-record && ./run.sh check-mailbox-receipt-state && ./run.sh check-entwurf-capabilities && ./run.sh check-harness-admission-parity && ./run.sh check-capability-bundle-reach && ./run.sh check-meta-mailbox-state-write && ./run.sh check-meta-receiver-marker && ./run.sh check-meta-capability-source && ./run.sh check-model-lock && ./run.sh check-dep-versions && ./run.sh check-node-floor-coherence && ./run.sh check-claude-floor-coherence && ./run.sh check-copilot-statusline && ./run.sh check-pi-import-surface && ./run.sh check-env-namespace && ./run.sh check-pi-runtime-version && ./run.sh check-pi-preflight && ./run.sh check-project-trust-handler && ./run.sh check-entwurf-v2-contract && ./run.sh check-entwurf-v2-send && ./run.sh check-entwurf-v2-runner && ./run.sh check-control-send-receipt && ./run.sh check-compaction-send-guard && ./run.sh check-entwurf-resume-args && ./run.sh check-entwurf-v2-native-push && ./run.sh check-entwurf-v2-production && ./run.sh check-entwurf-v2-surface && ./run.sh check-entwurf-bridge-pi-free && ./run.sh check-resume-launch-identity && ./run.sh check-mux-placement && ./run.sh check-mux-launch && ./run.sh check-mux-resume-call && ./run.sh check-mux-parent-artifact && ./run.sh check-mux-launcher-fence && ./run.sh check-entwurf-v2-visible-resume && ./run.sh check-control-socket-path && ./run.sh check-win32-preview && ./run.sh check-pack-win32-carrier && ./run.sh check-meta-listing && ./run.sh check-entwurf-fact-provider && ./run.sh check-herdr-placement && ./run.sh check-herdr-fresh-call && ./run.sh check-herdr-supply && ./run.sh check-fresh-call-dispatch && ./run.sh check-entwurf-peers-surface && ./run.sh check-entwurf-self-address && ./run.sh check-entwurf-deliverability && ./run.sh check-native-push-adapter && ./run.sh check-native-push-register && ./run.sh check-auth-boundary && ./run.sh check-acp-overlay && ./run.sh check-acp-tool-surface && ./run.sh check-acp-event-mapper && ./run.sh check-acp-prompt-builder && ./run.sh check-acp-config && ./run.sh check-acp-session-store && ./run.sh check-acp-carrier-augment && ./run.sh check-acp-foreground-only && ./run.sh check-acp-set-model-readback && ./run.sh check-acp-vendor-rejection && ./run.sh check-codex-sender-identity && ./run.sh check-codex-native-push && ./run.sh check-pi-durable-beside && ./run.sh check-pi-durable-carrier && ./run.sh check-pi-durable-native-module",
 		"check:hermetic": "./run.sh check-bridge-delivery && ./run.sh smoke-pi-attach && ./run.sh check-fresh-cut-gate && ./run.sh check-hook-launch-topology && ./run.sh check-meta-hook-session-switch && ./run.sh check-copilot-birth-hook && ./run.sh check-copilot-receive-arm && ./run.sh check-copilot-launch && ./run.sh check-pi-launch && ./run.sh check-codex-app-server-launch && ./run.sh check-meta-identity-consumers && ./run.sh check-socket-probe && ./run.sh smoke-meta-honesty && ./run.sh check-meta-doctor-oracle && ./run.sh check-agy-permission-matrix && ./run.sh smoke-agy-statusline-state && ./run.sh smoke-copilot-statusline-state && ./run.sh smoke-copilot-mcp-state && ./run.sh smoke-omp-bridge-state && ./run.sh smoke-omp-mcp-state && ./run.sh smoke-omp-receive-state && ./run.sh check-omp-birth-hook && ./run.sh check-omp-receive-arm && ./run.sh check-omp-fresh-preflight && ./run.sh smoke-agy-hooks-state && ./run.sh smoke-pi-provider-state && ./run.sh smoke-user-scope-citizen && ./run.sh smoke-meta-prune && ./run.sh smoke-meta-keyset-guard && ./run.sh check-meta-manifest-schema && ./run.sh check-entwurf-control-rpc && ./run.sh check-entwurf-bridge-boot && ./run.sh check-probe-bridge-command && ./run.sh check-meta-facts && ./run.sh check-peer-facts && ./run.sh check-herdr-plugin && ./run.sh check-herdr-plugin-profile && ./run.sh check-herdr-plugin-build && ./run.sh check-herdr-runtime-bootstrap && ./run.sh check-herdr-activation && ./run.sh check-agy-sender-identity && ./run.sh check-acp-provider-surface && ./run.sh check-acp-stop-reason && ./run.sh check-acp-prompt-lifecycle && ./run.sh check-acp-usage-accounting && ./run.sh check-acp-launch-namespace && ./run.sh check-acp-stream-hooks && ./run.sh check-acp-backend-preflight && ./run.sh check-acp-session-reuse && ./run.sh check-typing-call-fence && ./run.sh check-gate-manifests && ./run.sh check-release-gate-outcomes && ./run.sh check-probe-ordering && ./run.sh check-probe-cli-shim && ./run.sh check-acp-cortex && ./run.sh check-codex-bridge-identity && ./run.sh check-pi-bridge-sender && ./run.sh check-pi-mcp-register && ./run.sh check-pi-mcp-bridge && ./run.sh check-codex-birth-hook && ./run.sh smoke-codex-config-state && ./run.sh smoke-codex-birth && ./run.sh check-herdr-sandbox",
 		"check:package": "./run.sh check-install-surface && ./run.sh smoke-meta-install-state && ./run.sh smoke-agy-install-state && ./run.sh smoke-setup-verdict && ./run.sh check-pack-pin-matcher && ./run.sh check-pack-consumer-roots && ./run.sh check-package-source-routing && ./run.sh check-install-preflight && ./run.sh check-pack"
 	},

package/pi-extensions/entwurf-control.ts

@@ -147,8 +147,12 @@ async function ensureControlDir(): Promise<void> {
 	await fs.mkdir(ENTWURF_DIR, { recursive: true });
 }
 
+// On Windows the control address is a named pipe (`\\.\pipe\…`, #78): the kernel owns the
+// name and drops it with the last handle, so there is no file to unlink and none to sweep.
+const PIPE_ADDRESSED = process.platform === "win32";
+
 async function removeSocket(socketPath: string | null): Promise<void> {
-	if (!socketPath) return;
+	if (!socketPath || PIPE_ADDRESSED) return;
 	try {
 		await fs.unlink(socketPath);
 	} catch (error) {
@@ -162,6 +166,7 @@ async function removeSocket(socketPath: string | null): Promise<void> {
 // alias-era artifacts. Runs once per startControlServer call. We only touch
 // entries that are demonstrably dead — a live peer's socket survives.
 async function gcStaleSockets(): Promise<void> {
+	if (PIPE_ADDRESSED) return;
 	let entries: import("node:fs").Dirent[];
 	try {
 		entries = await fs.readdir(ENTWURF_DIR, { withFileTypes: true });

package/pi-extensions/lib/control-socket-path.js

@@ -24,9 +24,18 @@
  * adapter keeps its own root policy: the pi side derives from HOME, the MCP
  * bridge honours `ENTWURF_DIR`. What is unified is the grammar, not the policy.
  *
- * Keep dependency-free except `node:path`.
+ * Windows (#78) has no socket files: the address is a named pipe,
+ * `\\.\pipe\entwurf-<sha256(canonRoot(dir))[:16]>-<gardenId>`. The digest keeps two
+ * store roots on one host apart without putting a path in the pipe namespace; it is not
+ * a new address axis (still the garden id plus the store root). The inverse grammar has
+ * no Windows half because nothing scans the pipe namespace: candidates come from records.
+ *
+ * Keep dependency-free except node builtins (`node:path`, and `node:crypto`/`node:fs`
+ * for the Windows root canonicalisation only).
  */
 
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
 import * as path from "node:path";
 
 /** Control-socket filename suffix. The stem is a bare garden id. */
@@ -51,9 +60,55 @@ export function defaultControlSocketDir(home) {
  * @returns {string}
  */
 export function controlSocketPathIn(dir, gardenId) {
+	if (process.platform === "win32") return win32PipeNameFor(dir, gardenId);
 	return path.join(dir, `${gardenId}${CONTROL_SOCKET_SUFFIX}`);
 }
 
+/** Every Windows control pipe this package names starts here. */
+export const WIN32_PIPE_PREFIX = "\\\\.\\pipe\\entwurf-";
+
+/**
+ * The one spelling of a Windows store root, so Pi A, Pi B, the bridge and peer-facts
+ * derive the same pipe name from differently written paths. The nearest EXISTING ancestor
+ * of `path.win32.resolve(dir)` goes through `realpath` (8.3 names expanded, case from the
+ * filesystem); the components below it are appended as written. Separators become `\`,
+ * there is no trailing separator, and the whole string is lower-cased. Nothing is created
+ * or touched, so the control dir need not exist yet. A failure other than ENOENT throws.
+ *
+ * @param {string} dir
+ * @param {(p: string) => string} [realpath]
+ * @returns {string}
+ */
+export function canonRootWin32(dir, realpath = fs.realpathSync.native) {
+	let head = path.win32.resolve(dir);
+	/** @type {string[]} */
+	const tail = [];
+	for (;;) {
+		try {
+			const joined = path.win32.join(realpath(head), ...tail);
+			return joined.replace(/[\\/]+$/, "").toLowerCase();
+		} catch (err) {
+			const parent = path.win32.dirname(head);
+			if (/** @type {{ code?: unknown }} */ (err).code !== "ENOENT" || parent === head) throw err;
+			tail.unshift(path.win32.basename(head));
+			head = parent;
+		}
+	}
+}
+
+/**
+ * Forward grammar on Windows: `\\.\pipe\entwurf-<16 hex>-<gardenId>`.
+ *
+ * @param {string} dir
+ * @param {string} gardenId
+ * @param {(p: string) => string} [realpath]
+ * @returns {string}
+ */
+export function win32PipeNameFor(dir, gardenId, realpath) {
+	const digest = createHash("sha256").update(canonRootWin32(dir, realpath), "utf8").digest("hex").slice(0, 16);
+	return `${WIN32_PIPE_PREFIX}${digest}-${gardenId}`;
+}
+
 /**
  * Inverse grammar: a socket filename back to its garden id, or `null` when the
  * name does not carry the suffix.

package/pi-extensions/lib/entwurf-control-rpc.ts

@@ -15,6 +15,7 @@
  */
 
 import * as net from "node:net";
+import { win32Native } from "./win32-native.js";
 
 // `sender` carries the transparency envelope (agentId / sessionId / cwd /
 // timestamp). All four fields are mandatory whenever `sender` is present —
@@ -199,6 +200,7 @@ export async function sendRpcCommand(
 	options: RpcClientOptions = {},
 ): Promise<{ response: RpcResponse }> {
 	const { timeout = 5000 } = options;
+	if (process.platform === "win32") return await sendPipeRpcCommand(socketPath, command, timeout);
 
 	return new Promise((resolve, reject) => {
 		const socket = net.createConnection(socketPath);
@@ -277,3 +279,33 @@ export async function sendRpcCommand(
 		});
 	});
 }
+
+/**
+ * The Windows client (#78). The addon makes one owner-validated connect, writes the request
+ * line and returns the first response line, all inside one deadline; a timeout is
+ * `ETIMEDOUT`, a pipe owned by anyone but this token's expected owner is `EPERM` before any
+ * byte. The protocol is request-bound on its own connection, so that first line IS the
+ * answer: anything other than this command's response is refused, never waited past.
+ */
+async function sendPipeRpcCommand(
+	pipeName: string,
+	command: RpcCommand,
+	timeout: number,
+): Promise<{ response: RpcResponse }> {
+	const { responseLine } = await win32Native().pipeRpc(
+		pipeName,
+		JSON.stringify(command),
+		Math.max(0, Math.floor(timeout)),
+	);
+	let msg: unknown;
+	try {
+		msg = JSON.parse(responseLine.trim());
+	} catch {
+		throw new Error(`control pipe answered ${command.type} with a line that is not JSON`);
+	}
+	const response = msg as RpcResponse & { type?: unknown };
+	if (response?.type !== "response" || response.command !== command.type) {
+		throw new Error(`control pipe answered something other than the ${command.type} response`);
+	}
+	return { response };
+}

package/pi-extensions/lib/meta-session.ts

@@ -53,6 +53,7 @@
 import { execFileSync } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import * as os from "node:os";
 import * as path from "node:path";
 import { generateSessionId, SESSION_ID_RE } from "./session-id.js";
@@ -1017,6 +1018,7 @@ const O_NONBLOCK_FLAG = typeof fs.constants.O_NONBLOCK === "number" ? fs.constan
  * Shaping a message is the job of the caller that knows what the answer is FOR.
  */
 export function readStoreRecordFile(file: string): string {
+	if (process.platform === "win32") return win32RecordReader()(file).toString("utf8");
 	if (O_NOFOLLOW_FLAG === 0) {
 		throw new MetaRecordError(
 			`cannot read meta-record ${path.basename(file)} safely: this platform exposes no O_NOFOLLOW, so a record ` +
@@ -1039,6 +1041,18 @@ export function readStoreRecordFile(file: string): string {
 	}
 }
 
+/**
+ * Windows has no `O_NOFOLLOW` (libuv defines it as 0), so the same three decisions — a
+ * final-component reparse point refused as `ELOOP`, a non-regular entry as
+ * `ENTWURF_ENOTREG`, both on the handle the read uses — are made by the preview addon
+ * (#78). It is reached only here and only on win32, through `createRequire`, so the
+ * installers that copy this file without its siblings never load it on Linux or macOS.
+ */
+function win32RecordReader(): (file: string) => Buffer {
+	const native = createRequire(import.meta.url)("./win32-native.js") as typeof import("./win32-native.js");
+	return native.win32ReadNoFollow;
+}
+
 /** The reader every store-WIDE scan pairs with {@link readActiveStoreEntries}. The
  * caller's entry kind decides the POLICY — whether a non-regular entry is a defect
  * (certification), a diagnostic (listing) or a non-candidate (the rival scan) — because

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);
+	}
+}