pi-famulus 0.1.4 → 0.1.6

package/README.md

@@ -20,8 +20,9 @@ Supported native packages:
 | Linux | arm64 | `pi-famulus-linux-arm64` |
 | macOS | Intel x64 | `pi-famulus-darwin-x64` |
 | macOS | Apple Silicon arm64 | `pi-famulus-darwin-arm64` |
+| Windows | x64 | `pi-famulus-win-x64` |
 
-Linux binaries are statically linked with musl. macOS binaries target macOS 13 or newer; your Node/pi runtime's requirements also apply. Windows and other CPU architectures are not supported.
+Linux binaries are statically linked with musl. macOS binaries target macOS 13 or newer; Windows x64 binaries use MSVC with the CRT linked statically. Windows ARM64 is not published until CI produces that tarball. Your Node/pi runtime's requirements also apply. In-place manager upgrade remains Unix-only.
 
 The npm package also exposes the `pi-famulus` CLI (`npx pi-famulus --help`). The extension's binary search order is:
 
@@ -31,6 +32,8 @@ The npm package also exposes the `pi-famulus` CLI (`npx pi-famulus --help`). The
 4. Executable `~/.pi/agent/pi-famulus/bin/pi-famulus` (or the equivalent beneath `PI_FAMULUS_HOME`).
 5. Executable `pi-famulus` on `PATH`.
 
+On Windows the file name in steps 4 and 5 (and inside the native package) is `pi-famulus.exe`.
+
 Configuration and runtime state remain in `~/.pi/agent/pi-famulus`. Installing/updating the npm package does not move that state or copy a binary into the shared home. The npm CLI uses the package's native executable; use the extension configuration above when intentionally running a separately built manager.
 
 If optional dependencies were omitted, reinstall with them enabled. The CLI reports an actionable error; the extension can still discover an explicitly installed manager and otherwise enters degraded mode. An arbitrary different-version native npm package is never substituted.

package/bin/pi-famulus.js

@@ -7,7 +7,7 @@ if (!binary) {
   const name = nativePackageName(process.platform, process.arch);
   console.error(name
     ? `pi-famulus: missing usable ${name}. Reinstall pi-famulus with optional dependencies enabled (npm install --include=optional pi-famulus).`
-    : `pi-famulus: unsupported ${process.platform}/${process.arch}; only Linux/macOS x64/arm64 are supported.`);
+    : `pi-famulus: unsupported ${process.platform}/${process.arch}; only Linux/macOS/Windows x64/arm64 are supported.`);
   process.exit(1);
 }
 const child = spawn(binary, process.argv.slice(2), { stdio: "inherit" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
   "type": "module",
   "license": "MIT",
@@ -15,7 +15,8 @@
   },
   "os": [
     "linux",
-    "darwin"
+    "darwin",
+    "win32"
   ],
   "cpu": [
     "x64",
@@ -30,10 +31,11 @@
     "pi-famulus": "./bin/pi-famulus.js"
   },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.4",
-    "pi-famulus-linux-arm64": "0.1.4",
-    "pi-famulus-darwin-x64": "0.1.4",
-    "pi-famulus-darwin-arm64": "0.1.4"
+    "pi-famulus-linux-x64": "0.1.6",
+    "pi-famulus-linux-arm64": "0.1.6",
+    "pi-famulus-darwin-x64": "0.1.6",
+    "pi-famulus-darwin-arm64": "0.1.6",
+    "pi-famulus-win-x64": "0.1.6"
   },
   "pi": {
     "extensions": [

package/src/bash-override.ts

@@ -18,11 +18,12 @@ import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Type, type Static } from "typebox";
-import type {
-  AgentToolResult,
-  BashToolDetails,
-  ExtensionContext,
-  ToolDefinition,
+import {
+  getShellConfig,
+  type AgentToolResult,
+  type BashToolDetails,
+  type ExtensionContext,
+  type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { taskOutputPath, type FamulusConfig } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
@@ -166,15 +167,29 @@ async function executeLocal(
 ): Promise<AgentToolResult<FamulusBashDetails | undefined>> {
   const timeoutMs = resolveTimeoutMs(params.timeout);
   const startedAtMs = clock.now();
-  const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
+  // pi's own choice (Git Bash on Windows, /bin/bash on Unix): commands are
+  // written for pi's bash tool, not for whatever $SHELL is.
+  let shell: ReturnType<typeof getShellConfig>;
+  try {
+    shell = getShellConfig();
+  } catch (err) {
+    throw new Error(`Failed to start shell: ${(err as Error).message}`);
+  }
+  const viaStdin = shell.commandTransport === "stdin";
 
   const output = await new Promise<{ text: string; exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
     (resolve, reject) => {
-      const child = spawn(shell, ["-c", params.command], {
+      const child = spawn(shell.shell, viaStdin ? shell.args : [...shell.args, params.command], {
         cwd: ctx.cwd,
         env: process.env,
-        stdio: ["ignore", "pipe", "pipe"],
+        stdio: [viaStdin ? "pipe" : "ignore", "pipe", "pipe"],
+        windowsHide: true,
       });
+      if (viaStdin) {
+        // Swallow EPIPE if the shell exits before consuming stdin (pi's runner does the same).
+        child.stdin?.on("error", () => {});
+        child.stdin?.end(params.command);
+      }
       const chunks: Buffer[] = [];
       let settled = false;
       let timedOut = false;

package/src/config.ts

@@ -6,7 +6,7 @@
  */
 import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, join } from "node:path";
+import { delimiter, join, win32 } from "node:path";
 import { nativePackageName, resolveNativeManagerPath } from "./native-manager.js";
 
 export interface FamulusConfig {
@@ -141,11 +141,43 @@ export function getFamulusHome(env: NodeJS.ProcessEnv = process.env): string {
   return join(homedir(), ".pi", "agent", "pi-famulus");
 }
 
+/** FNV-1a 64-bit over UTF-8 bytes — must match manager `sys::fnv1a64`. */
+export function fnv1a64(input: string): string {
+  let h = 0xcbf29ce484222325n;
+  for (const byte of Buffer.from(input, "utf8")) {
+    h ^= BigInt(byte);
+    h = (h * 0x0100000001b3n) & 0xffffffffffffffffn;
+  }
+  return h.toString(16);
+}
+
+/**
+ * Named-pipe identity of a home — must match manager `lifecycle::windows_pipe_ident`.
+ * The home is made absolute lexically (`path.win32.resolve` against `cwd`):
+ * `.` / `..` and repeated separators collapse, symlinks and junctions are
+ * not expanded. One spelling per directory (backslashes, no trailing
+ * separator except a drive root, lower case). The same relative home from
+ * two working directories must not share a pipe.
+ */
+export function windowsHomeKey(home: string, cwd: string = process.cwd()): string {
+  let s = win32.resolve(cwd, home);
+  while (s.length > 3 && s.endsWith("\\")) s = s.slice(0, -1);
+  return s.toLowerCase();
+}
+
+export function windowsPipeName(home: string, cwd: string = process.cwd()): string {
+  return `\\\\.\\pipe\\pi-famulus-${fnv1a64(windowsHomeKey(home, cwd))}`;
+}
+
 /** Well-known paths inside the pi-famulus home directory (design doc §3.1). */
-export function famulusPaths(home: string) {
+export function famulusPaths(home: string, platform: NodeJS.Platform = process.platform) {
+  const socket =
+    platform === "win32"
+      ? windowsPipeName(home)
+      : join(home, "manager.sock");
   return {
     home,
-    socket: join(home, "manager.sock"),
+    socket,
     pidFile: join(home, "manager.pid"),
     spawnLock: join(home, "manager.spawn.lock"),
     log: join(home, "manager.log"),
@@ -225,6 +257,9 @@ export function loadConfig(home: string = getFamulusHome()): FamulusConfig {
   return config;
 }
 
+/** File name of the manager in <home>/bin and on PATH: Windows only starts `.exe` images. */
+export const MANAGER_FILE_NAME = process.platform === "win32" ? "pi-famulus.exe" : "pi-famulus";
+
 /** Return why a candidate is unusable, or null for an executable regular file. */
 function managerCandidateProblem(path: string): string | null {
   try {
@@ -260,14 +295,15 @@ export function describeManagerSearch(
   tried.push(nativeName
     ? `npm ${nativeName}${native ? ` ${native}` : " (missing or unusable, ignored)"}`
     : `npm native manager (unsupported ${process.platform}/${process.arch})`);
-  tried.push(describeCandidate(join(home, "bin", "pi-famulus")));
+  tried.push(describeCandidate(join(home, "bin", MANAGER_FILE_NAME)));
   tried.push("pi-famulus on PATH");
   return tried.join("; ");
 }
 
 /**
  * Resolve an executable regular pi-famulus binary, or null if none is usable.
- * Priority: config.managerPath > PI_FAMULUS_MANAGER_PATH env > npm native package > <home>/bin/pi-famulus > PATH.
+ * Priority: config.managerPath > PI_FAMULUS_MANAGER_PATH env > npm native package > <home>/bin/pi-famulus > PATH
+ * (`pi-famulus.exe` on Windows).
  */
 export function resolveManagerPath(
   config: FamulusConfig,
@@ -279,11 +315,11 @@ export function resolveManagerPath(
   if (envPath && managerCandidateProblem(envPath) === null) return envPath;
   const native = resolveNativeManagerPath();
   if (native) return native;
-  const bundled = join(home, "bin", "pi-famulus");
+  const bundled = join(home, "bin", MANAGER_FILE_NAME);
   if (managerCandidateProblem(bundled) === null) return bundled;
   for (const dir of (env.PATH ?? "").split(delimiter)) {
     if (!dir) continue;
-    const candidate = join(dir, "pi-famulus");
+    const candidate = join(dir, MANAGER_FILE_NAME);
     if (managerCandidateProblem(candidate) === null) return candidate;
   }
   return null;

package/src/manager-client.ts

@@ -18,7 +18,7 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.4";
+const EXTENSION_VERSION = "0.1.6";
 // 5: speaks per-kind agent admission and queued acquire.
 const PROTOCOL = 5;
 const HELLO_TIMEOUT_MS = 5000;
@@ -631,7 +631,8 @@ export class ManagerClient {
     const deadline = this.now() + timeoutMs;
     for (;;) {
       this.checkStartupOpen();
-      if (existsSync(socketPath)) {
+      // A named pipe is not a file: existsSync does not see it, connecting does.
+      if (process.platform === "win32" || existsSync(socketPath)) {
         const ok = await this.openSocket(socketPath, Math.min(SOCKET_READY_POLL_MS, Math.max(0, deadline - this.now())))
           .then((probe) => { probe.destroy(); return true; }, () => false);
         if (ok) return;

package/src/native-manager.js

@@ -14,10 +14,15 @@ const resolutionErrorCodes = new Set([
 const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const resolveInstalled = createRequire(import.meta.url).resolve;
 
-/** The four native optional packages are selected by npm's os/cpu constraints. */
+/** The native optional packages are selected by npm's os/cpu constraints. */
 export function nativePackageName(platform, arch) {
-  if (!["linux", "darwin"].includes(platform) || !["x64", "arm64"].includes(arch)) return null;
-  return `pi-famulus-${platform}-${arch}`;
+  if (!["linux", "darwin", "win32"].includes(platform) || !["x64", "arm64"].includes(arch)) return null;
+  // Windows ARM64 has no release producer yet; manual binary lookup still works.
+  if (platform === "win32" && arch === "arm64") return null;
+  // npm package names use `win` (not `win32`) after unscoped `*-win32-*` names
+  // were blocked by registry spam detection on first publish.
+  const packageOs = platform === "win32" ? "win" : platform;
+  return `pi-famulus-${packageOs}-${arch}`;
 }
 
 /** Resolve the exact-version optional package without loading native executable bytes. */