pi-crew 0.9.54 → 0.9.55

package/src/utils/sleep.ts

@@ -0,0 +1,54 @@
+import { execFileSync } from "node:child_process";
+
+/**
+ * Synchronous sleep using Atomics.wait (non-busy) with low-CPU fallback.
+ *
+ * WARNING: This blocks the Node.js main thread. Only use in sync I/O paths
+ * where blocking is acceptable (lock acquisition, rename retry).
+ * NOT safe to call from Pi extension async code paths.
+ */
+export function sleepSync(ms: number): void {
+	try {
+		const buffer = new SharedArrayBuffer(4);
+		Atomics.wait(new Int32Array(buffer), 0, 0, ms);
+	} catch {
+		// Fallback for environments without Atomics.wait (e.g. Windows).
+		// On Unix, try spawning the `sleep` command to avoid CPU busy-wait.
+		if (process.platform !== "win32" && ms >= 10) {
+			try {
+				execFileSync("sleep", [(ms / 1000).toFixed(3)], {
+					timeout: ms + 1000,
+					stdio: "pipe",
+				});
+				return;
+			} catch {
+				// sleep command unavailable — fall through to busy-wait
+			}
+		}
+		// Last resort: busy-wait. This burns CPU but is the only guaranteed
+		// synchronous delay on Windows without SharedArrayBuffer.
+		const deadline = Date.now() + ms;
+		while (Date.now() < deadline) {
+			// Busy-wait fallback for environments without Atomics.wait.
+		}
+	}
+}
+
+/**
+ * Async sleep with optional AbortSignal support.
+ * Rejects immediately if the signal is already aborted, or when aborted during wait.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) return Promise.reject(new Error("aborted"));
+	return new Promise<void>((resolve, reject) => {
+		const timer = setTimeout(resolve, ms);
+		signal?.addEventListener(
+			"abort",
+			() => {
+				clearTimeout(timer);
+				reject(new Error("aborted"));
+			},
+			{ once: true },
+		);
+	});
+}

package/src/utils/socket-path.ts

@@ -0,0 +1,164 @@
+/**
+ * socket-path.ts — Canonical broker Unix-socket / named-pipe path utilities.
+ *
+ * Moved out of the parallel-work stub `src/runtime/crew-broker-deps.ts`.
+ * The public surface (hashSessionId, getBrokerSocketPath,
+ * prepareBrokerSocketDir, removeStaleBrokerSocket) is preserved verbatim
+ * so importers can be updated with a single import-path change.
+ *
+ * No internal dependencies on other src/ modules — only Node built-ins.
+ */
+
+import { createHash } from "node:crypto";
+import * as fsp from "node:fs/promises";
+import * as net from "node:net";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/** Default hash length for the short socket filename (8 hex chars). */
+const DEFAULT_PATH_HASH_LEN = 8;
+
+/** POSIX sun_path cap (108 bytes including the null terminator). Use 107 for the
+ *  string portion of the path. */
+const POSIX_SUN_PATH_BUDGET = 107;
+
+/** SHA-256 hex prefix of `sessionId`. `length` defaults to 8; must be in [4, 32]. */
+export function hashSessionId(sessionId: string, length: number = DEFAULT_PATH_HASH_LEN): string {
+	if (typeof sessionId !== "string" || sessionId.length === 0) {
+		throw new Error("hashSessionId: sessionId must be a non-empty string");
+	}
+	if (!Number.isInteger(length) || length < 4 || length > 32) {
+		throw new Error(`hashSessionId: length must be an integer in [4, 32] (got ${length})`);
+	}
+	const hex = createHash("sha256").update(sessionId, "utf8").digest("hex");
+	return hex.substring(0, length);
+}
+
+/** Resolve the current POSIX user id. Uses `process.getuid` (POSIX-only);
+ *  falls back to `os.userInfo().uid`, then 0. Never throws. */
+function getCurrentUid(): number {
+	try {
+		const uid = process.getuid?.();
+		if (typeof uid === "number") return uid;
+	} catch {
+		/* ignore */
+	}
+	try {
+		const info = os.userInfo();
+		if (typeof info.uid === "number") return info.uid;
+	} catch {
+		/* ignore */
+	}
+	return 0;
+}
+
+/** Resolve a per-user subdirectory under the runtime base for broker sockets.
+ *
+ *  `${base}/pi-crew-<uid>/` isolates each user's sockets so that
+ *  `prepareBrokerSocketDir` can chmod 0700 a user-owned dir instead of the
+ *  shared base (`/tmp` or `XDG_RUNTIME_DIR`). Chmod-ing the shared base under
+ *  root strips the sticky bit and breaks the system. On Windows, named pipes
+ *  have no enclosing dir, so an empty string is returned. */
+export function getPerUserSocketDir(platform: NodeJS.Platform = process.platform): string {
+	if (platform === "win32") return "";
+	const base = process.env.XDG_RUNTIME_DIR || os.tmpdir();
+	const uid = getCurrentUid();
+	return path.join(base, `pi-crew-${uid}`);
+}
+
+/** Resolve the broker endpoint for the given session.
+ *
+ *  - POSIX: `${XDG_RUNTIME_DIR || os.tmpdir()}/pi-crew-<uid>/pi-crew-<hash8>.sock`
+ *    (per-user dir 0700 enforced by `prepareBrokerSocketDir`; socket 0600 by
+ *    the server).
+ *  - Windows: `\\\\.\\pipe\\pi-crew-broker-<hash8>`.
+ *  - Throws if the encoded POSIX path exceeds sun_path (108 bytes) — the
+ *    caller cannot fix this without changing the hash length, so fail fast. */
+export function getBrokerSocketPath(sessionId: string, platform: NodeJS.Platform = process.platform): string {
+	const hash = hashSessionId(sessionId);
+	if (platform === "win32") {
+		return `\\\\.\\pipe\\pi-crew-broker-${hash}`;
+	}
+	const perUserDir = getPerUserSocketDir(platform);
+	const sock = path.join(perUserDir, `pi-crew-${hash}.sock`);
+	const encoded = Buffer.byteLength(sock, "utf8");
+	if (encoded > POSIX_SUN_PATH_BUDGET) {
+		throw new Error(
+			`broker socket path ${encoded} bytes exceeds sun_path budget (${POSIX_SUN_PATH_BUDGET}); check XDG_RUNTIME_DIR or use a shorter hash`,
+		);
+	}
+	return sock;
+}
+
+/** Create the parent directory of a broker socket with mode 0700 (POSIX).
+ *  Idempotent: if the directory already exists with the correct mode, leaves
+ *  it alone. Refuses to operate on a symlink. Windows is a no-op (named pipes
+ *  do not have an enclosing dir).
+ *
+ *  The parent is a per-user subdir (see `getPerUserSocketDir`), NOT the shared
+ *  runtime base, so chmod 0700 targets a user-owned dir rather than stripping
+ *  the sticky bit from `/tmp`. */
+export async function prepareBrokerSocketDir(sockPath: string): Promise<void> {
+	if (process.platform === "win32") return;
+	const dir = path.dirname(sockPath);
+	// mkdir with mode 0o700; recursive:true so nested paths work.
+	await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+	// Tighten mode if it already existed (mkdir with mode ignores on existing).
+	try {
+		await fsp.chmod(dir, 0o700);
+	} catch {
+		// ENOENT or EPERM on non-POSIX — best-effort.
+	}
+}
+
+/** Connect-then-unlink stale socket (herdr pattern). If a live broker is
+ *  listening, leave the endpoint intact (EADDRINUSE will surface on bind).
+ *  If a stale file exists with no listener, remove it. If the path is a
+ *  symlink, refuse rather than follow.
+ *
+ *  Returns "removed" when the stale entry was unlinked, "kept" when a live
+ *  listener was detected, "absent" when no entry existed, "refused"
+ *  when the entry is a symlink. */
+export async function removeStaleBrokerSocket(
+	sockPath: string,
+	probeTimeoutMs: number = 250,
+): Promise<"removed" | "kept" | "absent" | "refused"> {
+	// Reject symlinks outright.
+	let st: Awaited<ReturnType<typeof fsp.lstat>>;
+	try {
+		st = await fsp.lstat(sockPath);
+	} catch (e) {
+		const code = (e as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return "absent";
+		throw e;
+	}
+	if (st.isSymbolicLink()) return "refused";
+	// Bound the probe: connect with a short timeout. If anything answers, treat as live.
+	const live = await new Promise<boolean>((resolve) => {
+		let settled = false;
+		const sock = net.createConnection(sockPath);
+		const finish = (v: boolean) => {
+			if (settled) return;
+			settled = true;
+			try {
+				sock.destroy();
+			} catch {
+				/* ignore */
+			}
+			resolve(v);
+		};
+		sock.once("connect", () => finish(true));
+		sock.once("error", () => finish(false));
+		setTimeout(() => finish(false), probeTimeoutMs);
+	});
+	if (live) return "kept";
+	// Stale: remove.
+	try {
+		await fsp.unlink(sockPath);
+		return "removed";
+	} catch (e) {
+		const code = (e as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return "absent";
+		throw e;
+	}
+}

package/src/utils/sse-parser.ts

@@ -0,0 +1,131 @@
+/** A single Server-Sent Event */
+export interface ServerSentEvent {
+	event: string | null;
+	data: string;
+	raw: string[];
+}
+
+/** L1: Maximum number of raw lines before discarding an oversized event. */
+const MAX_EVENT_LINES = 1000;
+
+/** L2: Maximum data size per line to prevent unbounded memory usage. */
+const MAX_DATA_SIZE = 100000; // 100KB per line
+
+/** Read newline-delimited lines from a text ReadableStream, buffering partial chunks. */
+async function* readLines(stream: ReadableStream<string>, signal?: AbortSignal): AsyncGenerator<string> {
+	const reader = stream.getReader();
+	let buffer = "";
+	try {
+		while (true) {
+			if (signal?.aborted) return;
+			const { done, value } = await reader.read();
+			if (done) {
+				if (buffer.length > 0) yield buffer;
+				return;
+			}
+			buffer += value;
+			let idx: number;
+			while ((idx = buffer.indexOf("\n")) !== -1) {
+				const line = buffer.endsWith("\r\n", idx + 1) ? buffer.slice(0, idx - 1) : buffer.slice(0, idx);
+				yield line;
+				buffer = buffer.slice(idx + 1);
+			}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+/** Parse SSE events from a byte stream */
+export async function* readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<ServerSentEvent> {
+	const textStream = stream.pipeThrough(new TextDecoderStream() as unknown as TransformStream<Uint8Array, string>);
+	let currentEvent: string | null = null;
+	let currentData: string[] = [];
+	let currentRaw: string[] = [];
+
+	function flush(): ServerSentEvent | null {
+		if (currentData.length === 0 && currentEvent === null) return null;
+		const evt: ServerSentEvent = {
+			event: currentEvent,
+			data: currentData.join("\n"),
+			raw: currentRaw,
+		};
+		currentEvent = null;
+		currentData = [];
+		currentRaw = [];
+		return evt;
+	}
+
+	for await (const line of readLines(textStream, signal)) {
+		if (signal?.aborted) return;
+
+		// Empty line → dispatch
+		if (line === "") {
+			const evt = flush();
+			if (evt) yield evt;
+			continue;
+		}
+
+		// Comment
+		if (line.startsWith(":")) continue;
+
+		// [DONE] sentinel
+		if (line === "[DONE]") return;
+
+		const colonIdx = line.indexOf(":");
+		if (colonIdx === -1) {
+			// Field with no value
+			const field = line;
+			if (field === "event") {
+				currentEvent = "";
+			} else if (field === "data") {
+				currentData.push("");
+			}
+			currentRaw.push(line);
+			continue;
+		}
+
+		const field = line.slice(0, colonIdx);
+		let value = line.slice(colonIdx + 1);
+		// Remove leading space after colon per SSE spec
+		if (value.startsWith(" ")) value = value.slice(1);
+
+		currentRaw.push(line);
+
+		// L1: Guard against unbounded memory growth (line count)
+		if (currentRaw.length > MAX_EVENT_LINES) {
+			const evt = flush();
+			if (evt) yield evt;
+			continue;
+		}
+
+		// L2: Guard against unbounded memory growth (data size per line)
+		if (value.length > MAX_DATA_SIZE) {
+			// Truncate oversized data to prevent memory issues
+			value = value.slice(0, MAX_DATA_SIZE);
+		}
+
+		if (field === "event") {
+			currentEvent = value;
+		} else if (field === "data") {
+			currentData.push(value);
+		}
+		// id / retry fields ignored
+	}
+
+	// Flush any remaining event at end of stream
+	const evt = flush();
+	if (evt) yield evt;
+}
+
+/** Parse SSE events and yield parsed JSON data objects */
+export async function* readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T> {
+	for await (const evt of readSseEvents(stream, signal)) {
+		try {
+			const parsed: T = JSON.parse(evt.data) as T;
+			yield parsed;
+		} catch {
+			// intentional parse fallback
+		}
+	}
+}

package/src/utils/task-name-generator.ts

@@ -0,0 +1,337 @@
+/**
+ * Human-readable task name generator.
+ * Format: AdjectiveNoun (e.g., "SwiftFalcon", "CalmPanda")
+ *
+ * Curated lists of ~120 adjectives and ~120 animals/nouns.
+ * 120 × 120 = 14,400 combinations.
+ */
+
+const ADJECTIVES = [
+	"active",
+	"agile",
+	"alert",
+	"ancient",
+	"bold",
+	"brave",
+	"bright",
+	"brilliant",
+	"calm",
+	"capable",
+	"careful",
+	"charming",
+	"cheerful",
+	"clever",
+	"cloudy",
+	"cold",
+	"cool",
+	"curious",
+	"cute",
+	"daring",
+	"dark",
+	"deep",
+	"direct",
+	"eager",
+	"early",
+	"electric",
+	"elegant",
+	"energetic",
+	"enormous",
+	"epic",
+	"exact",
+	"exotic",
+	"fair",
+	"fancy",
+	"fast",
+	"fierce",
+	"firm",
+	"flat",
+	"flexible",
+	"fresh",
+	"friendly",
+	"full",
+	"fun",
+	"funny",
+	"gentle",
+	"global",
+	"golden",
+	"good",
+	"grand",
+	"grateful",
+	"great",
+	"green",
+	"happy",
+	"hard",
+	"heavy",
+	"hidden",
+	"honest",
+	"hot",
+	"huge",
+	"icy",
+	"ideal",
+	"keen",
+	"kind",
+	"large",
+	"lazy",
+	"light",
+	"lively",
+	"local",
+	"loud",
+	"lucky",
+	"magic",
+	"mighty",
+	"mild",
+	"modern",
+	"neat",
+	"new",
+	"nice",
+	"noble",
+	"odd",
+	"old",
+	"open",
+	"patient",
+	"perfect",
+	"plain",
+	"polite",
+	"popular",
+	"powerful",
+	"precise",
+	"pretty",
+	"proud",
+	"pure",
+	"quick",
+	"quiet",
+	"rapid",
+	"rare",
+	"real",
+	"rich",
+	"robust",
+	"round",
+	"royal",
+	"safe",
+	"sharp",
+	"short",
+	"shy",
+	"silent",
+	"simple",
+	"slim",
+	"smart",
+	"smooth",
+	"soft",
+	"solar",
+	"solid",
+	"steady",
+	"strange",
+	"strong",
+	"sunny",
+	"swift",
+	"tall",
+	"tame",
+	"tiny",
+	"tough",
+	"true",
+	"unique",
+	"vast",
+	"warm",
+	"wild",
+	"wise",
+	"zany",
+	"zen",
+] as const;
+
+const NOUNS = [
+	"albatross",
+	"ant",
+	"antelope",
+	"ape",
+	"archer",
+	"badger",
+	"bass",
+	"bat",
+	"bear",
+	"beaver",
+	"bee",
+	"beetle",
+	"bird",
+	"bison",
+	"boar",
+	"bobcat",
+	"bull",
+	"buzzard",
+	"camel",
+	"canary",
+	"carp",
+	"cat",
+	"cedar",
+	"cheetah",
+	"chicken",
+	"cobra",
+	"cod",
+	"condor",
+	"coral",
+	"cougar",
+	"crab",
+	"crane",
+	"cricket",
+	"crow",
+	"deer",
+	"dolphin",
+	"dove",
+	"dragon",
+	"duck",
+	"eagle",
+	"eel",
+	"elk",
+	"falcon",
+	"ferret",
+	"finch",
+	"flamingo",
+	"fox",
+	"frog",
+	"gazelle",
+	"gecko",
+	"ghost",
+	"gibbon",
+	"goat",
+	"goldfish",
+	"goose",
+	"gorilla",
+	"halibut",
+	"hamster",
+	"hare",
+	"hawk",
+	"heron",
+	"horse",
+	"hummingbird",
+	"hyena",
+	"ibis",
+	"iguana",
+	"impala",
+	"jackal",
+	"jaguar",
+	"jay",
+	"jellyfish",
+	"kangaroo",
+	"kite",
+	"kiwi",
+	"koala",
+	"krill",
+	"lark",
+	"lemur",
+	"leopard",
+	"lion",
+	"lizard",
+	"llama",
+	"lobster",
+	"lynx",
+	"macaw",
+	"magnet",
+	"mammoth",
+	"marmot",
+	"mink",
+	"mole",
+	"monkey",
+	"moose",
+	"moth",
+	"mouse",
+	"newt",
+	"ocelot",
+	"octopus",
+	"orca",
+	"ostrich",
+	"otter",
+	"owl",
+	"ox",
+	"panda",
+	"panther",
+	"parrot",
+	"peacock",
+	"pelican",
+	"penguin",
+	"pike",
+	"pony",
+	"python",
+	"quail",
+	"rabbit",
+	"raccoon",
+	"ram",
+	"raven",
+	"robin",
+	"rook",
+	"sable",
+	"salmon",
+	"scorpion",
+	"seal",
+	"shark",
+	"sheep",
+	"snail",
+	"sparrow",
+	"spider",
+	"squid",
+	"squirrel",
+	"stork",
+	"swan",
+	"tiger",
+	"toad",
+	"tortoise",
+	"toucan",
+	"trout",
+	"tuna",
+	"turkey",
+	"turtle",
+	"viper",
+	"vulture",
+	"walrus",
+	"wasp",
+	"whale",
+	"wolf",
+	"wombat",
+	"woodpecker",
+	"wren",
+	"yak",
+	"zebra",
+] as const;
+
+function capitalize(s: string): string {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+let usedNames = new Set<string>();
+
+/**
+ * Generate a unique two-word identifier (e.g., "SwiftFalcon").
+ * Resets and starts over if all combinations exhausted.
+ */
+export function generateTaskName(): string {
+	// Try random combinations first (50 attempts)
+	for (let attempt = 0; attempt < 50; attempt++) {
+		const adj = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)]!;
+		const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)]!;
+		const name = `${capitalize(adj)}${capitalize(noun)}`;
+		if (!usedNames.has(name)) {
+			usedNames.add(name);
+			return name;
+		}
+	}
+
+	// Exhaustive search if random fails
+	for (const adj of ADJECTIVES) {
+		for (const noun of NOUNS) {
+			const name = `${capitalize(adj)}${capitalize(noun)}`;
+			if (!usedNames.has(name)) {
+				usedNames.add(name);
+				return name;
+			}
+		}
+	}
+
+	// All combinations exhausted — reset and start over
+	usedNames.clear();
+	return generateTaskName();
+}
+
+/**
+ * Reset name generator state (for testing).
+ */
+export function resetTaskNames(): void {
+	usedNames = new Set<string>();
+}

package/src/utils/timings.ts

@@ -0,0 +1,33 @@
+/**
+ * Central timing instrumentation for startup profiling.
+ * Enable with PI_TIMING=1 environment variable.
+ */
+
+const ENABLED = process.env.PI_TIMING === "1";
+const timings: Array<{ label: string; ms: number }> = [];
+const MAX_TIMINGS = 500;
+let lastTime = Date.now();
+
+export function resetTimings(): void {
+	if (!ENABLED) return;
+	timings.length = 0;
+	lastTime = Date.now();
+}
+
+export function time(label: string): void {
+	if (!ENABLED) return;
+	if (timings.length >= MAX_TIMINGS) timings.shift();
+	const now = Date.now();
+	timings.push({ label, ms: now - lastTime });
+	lastTime = now;
+}
+
+export function printTimings(): void {
+	if (!ENABLED || timings.length === 0) return;
+	console.error("\n--- Startup Timings ---");
+	for (const t of timings) {
+		console.error(`  ${t.label}: ${t.ms}ms`);
+	}
+	console.error(`  TOTAL: ${timings.reduce((a, b) => a + b.ms, 0)}ms`);
+	console.error("------------------------\n");
+}