@xynogen/pix-runtime 0.10.1 → 0.12.2

package/src/pix-command.ts

@@ -6,6 +6,7 @@
  * Headless hosts get a notify summary instead of the overlay.
  */
 
+import { dirname } from "node:path";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
 	Key,
@@ -15,6 +16,7 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
+import { createBinariesTab } from "./binaries-tab.ts";
 import { icon } from "./icon-catalog.ts";
 import type { PixRuntime } from "./runtime.ts";
 import type { DeepPartial, SectionHandle } from "./schema.ts";
@@ -184,6 +186,13 @@ const SETTINGS: SettingRow<unknown>[] = [
 	}),
 ];
 
+/** Env whose agent dir is the folder holding pix.json (binary.json lives beside it). */
+function binariesEnv(runtime: PixRuntime): NodeJS.ProcessEnv {
+	return { ...process.env, PI_CODING_AGENT_DIR: dirname(runtime.path) };
+}
+
+const TABS = ["Settings", "Binaries"] as const;
+
 function buildSummary(runtime: PixRuntime): string {
 	const lines = [`Pix Settings (${runtime.path})`, ""];
 	let lastSection = "";
@@ -197,6 +206,12 @@ function buildSummary(runtime: PixRuntime): string {
 		const isDefault = value === row.read(row.handle.defaults);
 		lines.push(`  ${row.label}: ${value}${isDefault ? "" : " *"}`);
 	}
+	const binaries = createBinariesTab({
+		env: binariesEnv(runtime),
+		theme: { fg: (_c, t) => t, bold: (t) => t },
+		requestRender: () => {},
+	});
+	lines.push("", "[Binaries]", ...binaries.summary());
 	return lines.join("\n");
 }
 
@@ -236,6 +251,29 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 					let visibleBodyLines = 1;
 					let maxBodyOffset = 0;
 					let inspectingPage = false;
+					let tab: (typeof TABS)[number] = "Settings";
+					let binaries: ReturnType<typeof createBinariesTab> | undefined;
+					const binariesTab = () => {
+						binaries ??= createBinariesTab({
+							env: binariesEnv(runtime),
+							theme,
+							requestRender: () => tui.requestRender(),
+						});
+						return binaries;
+					};
+					const tabBar = () =>
+						TABS.map((name) =>
+							name === tab
+								? theme.fg("accent", theme.bold(`  ${name}  `))
+								: theme.fg("muted", `  ${name}  `),
+						).join(theme.fg("muted", "│"));
+					const switchTab = (direction: -1 | 1) => {
+						const next = (TABS.indexOf(tab) + direction + TABS.length) % TABS.length;
+						tab = TABS[next] ?? "Settings";
+						bodyOffset = 0;
+						inspectingPage = false;
+						if (tab === "Binaries") binariesTab().refresh();
+					};
 
 					const cycle = (direction: -1 | 1) => {
 						const row = SETTINGS[selected];
@@ -274,6 +312,40 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 
 					return {
 						render: (width: number) => {
+							const frame = {
+								width,
+								maxHeight: modalHeight(
+									tui.terminal?.rows,
+									runtime.get(prettySection).maxRenderHeight,
+								),
+								title: `${icon("settings")} Pix Settings`,
+								titleColor: (s: string) => theme.fg("accent", theme.bold(s)),
+								color: (s: string) => theme.fg("accent", s),
+								bg: (s: string) => theme.bg("customMessageBg", s),
+							};
+							const tabGuide = guide("tab", "switch tab");
+							if (tab === "Binaries") {
+								const bt = binariesTab();
+								const view = bt.view(width);
+								const hints = view.footer.map(([key, action]) => guide(key, action)).join(guideSep);
+								const result = frameModal({
+									...frame,
+									header: [tabBar(), "", ...view.header],
+									body: view.body,
+									footer: [
+										"",
+										bt.editing
+											? hints
+											: hints + guideSep + tabGuide + guideSep + guide("esc", "close"),
+									],
+									bodyOffset,
+									selectedBodyLine: inspectingPage ? undefined : view.selectedBodyLine,
+								});
+								bodyOffset = result.bodyOffset;
+								visibleBodyLines = Math.max(1, result.visibleBodyLines);
+								maxBodyOffset = result.maxBodyOffset;
+								return result.lines;
+							}
 							const labelW = Math.max(...SETTINGS.map((r) => r.label.length));
 							const body: string[] = [];
 							const settingBodyLines: number[] = [];
@@ -295,14 +367,8 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								body.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
 							}
 							const result = frameModal({
-								width,
-								maxHeight: modalHeight(
-									tui.terminal?.rows,
-									runtime.get(prettySection).maxRenderHeight,
-								),
-								title: `${icon("settings")} Pix Settings`,
-								titleColor: (s: string) => theme.fg("accent", theme.bold(s)),
-								header: [""],
+								...frame,
+								header: [tabBar(), ""],
 								body,
 								footer: [
 									"",
@@ -312,12 +378,12 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 										guideSep +
 										guide("PgUp/PgDn", "inspect") +
 										guideSep +
+										tabGuide +
+										guideSep +
 										guide("esc", "close"),
 								],
 								bodyOffset,
 								selectedBodyLine: inspectingPage ? undefined : settingBodyLines[selected],
-								color: (s: string) => theme.fg("accent", s),
-								bg: (s: string) => theme.bg("customMessageBg", s),
 							});
 							bodyOffset = result.bodyOffset;
 							visibleBodyLines = Math.max(1, result.visibleBodyLines);
@@ -326,6 +392,24 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 						},
 						invalidate: () => {},
 						handleInput: (data: string) => {
+							if (tab === "Binaries" && binariesTab().editing) {
+								// The filter input takes ↑↓ to move through its matches.
+								const nav = !binariesTab().editingPath;
+								binariesTab().handleInput(data, {
+									up: nav && kb.matches(data, "tui.select.up"),
+									down: nav && kb.matches(data, "tui.select.down"),
+									enter: false,
+								});
+								inspectingPage = false;
+								tui.requestRender();
+								return;
+							}
+							const shiftTab = matchesKey(data, Key.shift(Key.tab));
+							if (shiftTab || matchesKey(data, Key.tab)) {
+								switchTab(shiftTab ? -1 : 1);
+								tui.requestRender();
+								return;
+							}
 							const pageUp = kb?.matches(data, "tui.select.pageUp") || matchesKey(data, Key.pageUp);
 							const pageDown =
 								kb?.matches(data, "tui.select.pageDown") || matchesKey(data, Key.pageDown);
@@ -340,9 +424,25 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 							// for letters and special keys alike — raw string compares like
 							// `data === "k"` silently fail under the Kitty keyboard protocol.
 							if (kb.matches(data, "tui.select.cancel")) {
+								if (tab === "Binaries" && binariesTab().clearFilter()) {
+									tui.requestRender();
+									return;
+								}
 								done(null);
 								return;
 							}
+							if (tab === "Binaries") {
+								const handled = binariesTab().handleInput(data, {
+									up: kb.matches(data, "tui.select.up"),
+									down: kb.matches(data, "tui.select.down"),
+									enter: kb.matches(data, "tui.select.confirm"),
+								});
+								if (handled) {
+									inspectingPage = false;
+									tui.requestRender();
+								}
+								return;
+							}
 							if (kb.matches(data, "tui.select.up")) move(-1);
 							else if (kb.matches(data, "tui.select.down")) move(1);
 							else if (matchesKey(data, Key.left)) cycle(-1);

package/src/platform.ts

@@ -0,0 +1,75 @@
+/**
+ * platform.ts — one host description for binary selection and OS branches.
+ *
+ * Pure except for two cached probes (glibc via `process.report`, WSL via
+ * `/proc/version`); every input is injectable so tests cover all hosts.
+ */
+
+import { readFileSync } from "node:fs";
+
+export type HostOs = "win32" | "linux" | "darwin" | "android";
+export type HostArch = "x64" | "arm64";
+
+export interface HostPlatform {
+	os: HostOs;
+	arch: HostArch;
+	/** Linux C library; undefined elsewhere. */
+	libc?: "glibc" | "musl";
+	/** Linux kernel under Windows Subsystem for Linux. */
+	wsl: boolean;
+	/** Termux on Android. */
+	termux: boolean;
+	/** Executable suffix. */
+	exe: "" | ".exe";
+}
+
+export interface HostProbe {
+	platform?: NodeJS.Platform;
+	arch?: string;
+	env?: NodeJS.ProcessEnv;
+	/** glibc runtime version, or undefined on musl. */
+	glibcVersion?: () => string | undefined;
+	/** Contents of `/proc/version`, or undefined when unreadable. */
+	procVersion?: () => string | undefined;
+}
+
+function defaultGlibc(): string | undefined {
+	try {
+		const report = process.report?.getReport() as { header?: { glibcVersionRuntime?: string } };
+		return report?.header?.glibcVersionRuntime;
+	} catch {
+		return undefined;
+	}
+}
+
+function defaultProcVersion(): string | undefined {
+	try {
+		return readFileSync("/proc/version", "utf-8");
+	} catch {
+		return undefined;
+	}
+}
+
+/** Describe the current host (or an injected one). */
+export function hostPlatform(probe: HostProbe = {}): HostPlatform {
+	const platform = probe.platform ?? process.platform;
+	const env = probe.env ?? process.env;
+	const arch: HostArch = (probe.arch ?? process.arch) === "arm64" ? "arm64" : "x64";
+	const termux = Boolean(env.TERMUX_VERSION) || platform === "android";
+	if (platform === "win32") return { os: "win32", arch, wsl: false, termux: false, exe: ".exe" };
+	if (platform === "darwin") return { os: "darwin", arch, wsl: false, termux: false, exe: "" };
+	if (termux) return { os: "android", arch, wsl: false, termux: true, exe: "" };
+	const glibc = (probe.glibcVersion ?? defaultGlibc)();
+	const wsl =
+		Boolean(env.WSL_DISTRO_NAME || env.WSLENV) ||
+		/microsoft|wsl/i.test((probe.procVersion ?? defaultProcVersion)() ?? "");
+	return { os: "linux", arch, libc: glibc ? "glibc" : "musl", wsl, termux: false, exe: "" };
+}
+
+let cached: HostPlatform | undefined;
+
+/** Cached {@link hostPlatform} for the running process. */
+export function currentPlatform(): HostPlatform {
+	cached ??= hostPlatform();
+	return cached;
+}

package/src/runtime.ts

@@ -6,7 +6,6 @@
  * after a lazy load; writes are serialized and atomic.
  */
 
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { DiagnosticSink } from "./diagnostics.ts";
 import {
 	type ConfigChange,
@@ -18,8 +17,9 @@ import {
 	type SubscribeOptions,
 } from "./events.ts";
 import { importOptimizerSidecar, migrate } from "./migrations.ts";
+import { agentDir } from "./paths.ts";
 import {
-	ConfigWriteError,
+	ConfigParseError,
 	FileStorage,
 	parseRawDocument,
 	type StorageAdapter,
@@ -99,7 +99,7 @@ class RuntimeImpl implements PixRuntime {
 	private readOnly = false;
 
 	constructor(adapters: RuntimeAdapters = {}) {
-		this.agentDir = adapters.agentDir ?? getAgentDir();
+		this.agentDir = adapters.agentDir ?? agentDir();
 		this.storage = adapters.storage ?? new FileStorage(this.agentDir);
 		this.registry = adapters.registry ?? new SectionRegistry();
 	}
@@ -139,16 +139,45 @@ class RuntimeImpl implements PixRuntime {
 		try {
 			doc = parseRawDocument(this.storage.readRaw());
 		} catch (err) {
-			this.sink.push({
-				code: "READ_FAILED",
-				severity: "warning",
-				message: "config read failed; using defaults",
-				cause: err,
-			});
+			if (err instanceof ConfigParseError) this.parseFailed(err);
+			else
+				this.sink.push({
+					code: "READ_FAILED",
+					severity: "warning",
+					message: "config read failed; using defaults",
+					cause: err,
+				});
 		}
 		return this.publish(this.resolve(doc));
 	}
 
+	/** A malformed pix.json stays untouched: defaults apply, writes are refused. */
+	private parseFailed(err: ConfigParseError, path?: string): void {
+		this.sink.push({
+			code: "PARSE_ERROR",
+			severity: "error",
+			path,
+			message: `${this.storage.path}: ${err.message}. File left unchanged; fix it to save settings.`,
+			cause: err,
+		});
+	}
+
+	/** Migration + sidecar import for one raw file read. Pure except `ctx`. */
+	private planInit(raw: string | undefined, ctx: ParseContext) {
+		const doc = parseRawDocument(raw);
+		const migrated = migrate(doc, ctx);
+		const readOnly = migrated.document.$version !== CONFIG_FORMAT_VERSION;
+		let needsWrite = migrated.changed;
+		let archive: (() => void) | undefined;
+		if (!readOnly) {
+			const sidecar = importOptimizerSidecar(migrated.document, this.agentDir, ctx);
+			if (sidecar.changed) needsWrite = true;
+			archive = sidecar.archive;
+		}
+		// Do not normalize a future-version file.
+		return { working: readOnly ? doc : migrated.document, readOnly, needsWrite, archive };
+	}
+
 	snapshot(): ConfigSnapshot {
 		return this.current ?? this.lazyLoad();
 	}
@@ -182,36 +211,38 @@ class RuntimeImpl implements PixRuntime {
 			const hadLazy = this.current !== null;
 			const previous = this.current;
 			this.storage.ensureDir();
-			const doc = parseRawDocument(this.storage.readRaw());
-			const ctx = this.parseContext();
-
-			const migrated = migrate(doc, ctx);
-			this.readOnly = migrated.document.$version !== CONFIG_FORMAT_VERSION;
-
-			let working = migrated.document;
-			let needsWrite = migrated.changed;
-			let archive: (() => void) | undefined;
-
-			if (!this.readOnly) {
-				const sidecar = importOptimizerSidecar(working, this.agentDir, ctx);
-				if (sidecar.changed) needsWrite = true;
-				archive = sidecar.archive;
-			}
-
-			if (needsWrite && !this.readOnly) {
-				try {
-					this.persist(working);
-					archive?.();
-				} catch (err) {
-					this.sink.push({
-						code: "WRITE_FAILED",
-						severity: "error",
-						message: "initial migration write failed",
-						cause: err,
-					});
+			let working: RawDocument = {};
+			let needsWrite = false;
+			try {
+				// Unlocked probe: most sessions need no write, so they never take the lock.
+				let plan = this.planInit(this.storage.readRaw(), this.parseContext());
+				this.readOnly = plan.readOnly;
+				working = plan.working;
+				if (plan.needsWrite && !plan.readOnly) {
+					try {
+						// Re-plan under the lock so a concurrent writer's change survives.
+						this.storage.transact((raw) => {
+							plan = this.planInit(raw, { diagnostic: () => {} });
+							working = plan.working;
+							needsWrite = plan.needsWrite && !plan.readOnly;
+							return needsWrite ? serializeRawDocument(plan.working) : undefined;
+						});
+						if (needsWrite) plan.archive?.();
+					} catch (err) {
+						needsWrite = false;
+						if (err instanceof ConfigParseError) throw err;
+						this.sink.push({
+							code: "WRITE_FAILED",
+							severity: "error",
+							message: "initial migration write failed",
+							cause: err,
+						});
+					}
 				}
-			} else if (this.readOnly) {
-				working = doc; // do not normalize a future-version file
+			} catch (err) {
+				if (!(err instanceof ConfigParseError)) throw err;
+				this.parseFailed(err);
+				working = {};
 			}
 
 			const values = this.resolve(working);
@@ -242,6 +273,10 @@ class RuntimeImpl implements PixRuntime {
 			}
 			return snapshot;
 		});
+		// A failed init (unreadable agent dir) must not stay cached: the next call retries.
+		this.initPromise.catch(() => {
+			this.initPromise = null;
+		});
 		return this.initPromise;
 	}
 
@@ -267,10 +302,6 @@ class RuntimeImpl implements PixRuntime {
 		return stripDefaults(copy, defaults) > 0 ? copy : undefined;
 	}
 
-	private persist(doc: RawDocument): void {
-		this.storage.writeAtomic(serializeRawDocument(doc));
-	}
-
 	private changedPaths(prev: ConfigSnapshot, next: ConfigSnapshot): string[] {
 		const out: string[] = [];
 		for (const section of this.registry.all()) {
@@ -339,49 +370,56 @@ class RuntimeImpl implements PixRuntime {
 		}
 
 		const previous = this.snapshot();
-		const base = parseRawDocument(this.storage.readRaw());
 		const ctx = this.parseContext();
+		let values: Map<string, unknown> | undefined;
 
-		// Re-resolve all sections from the latest on-disk doc so unknown fields
-		// and sibling sections survive.
-		const values = new Map<string, unknown>();
-		for (const s of this.registry.all()) values.set(s.key, s.parse(base[s.key], ctx));
-
-		// Guard against a version-skewed second runtime copy whose registry
-		// lacks this section (e.g. an old npm copy handling a new handle). The
-		// functional updater would otherwise crash the whole process on
-		// `undefined`. Fall back to the handle's own parse of the raw doc.
-		const currentValue = (
-			values.has(section.key)
-				? values.get(section.key)
-				: section.__section.parse(base[section.key], ctx)
-		) as Readonly<T>;
-		const mergedValue =
-			typeof updater === "function"
-				? (updater as (c: Readonly<T>) => T)(currentValue)
-				: deepMerge(currentValue as T, updater);
-
-		// Re-validate through the section's own parse so a bad patch (NaN,
-		// Infinity, wrong type) can never enter the live snapshot.
-		const nextValue = section.__section.parse(mergedValue, ctx) as T;
-
-		if (JSON.stringify(currentValue) === JSON.stringify(nextValue)) return undefined;
-		values.set(section.key, nextValue);
-
-		const doc = this.buildRawFromValues(values, base);
 		try {
-			this.persist(doc);
-		} catch (err) {
-			this.sink.push({
-				code: "WRITE_FAILED",
-				severity: "error",
-				path: section.key,
-				message: "config write failed; snapshot unchanged",
-				cause: err,
+			// Read, patch, and write under one lock hold: a second Pi process cannot
+			// write between our read and our write, so its change is not lost.
+			this.storage.transact((raw) => {
+				const base = parseRawDocument(raw);
+
+				// Re-resolve all sections from the latest on-disk doc so unknown fields
+				// and sibling sections survive.
+				const next = new Map<string, unknown>();
+				for (const s of this.registry.all()) next.set(s.key, s.parse(base[s.key], ctx));
+
+				// Guard against a version-skewed second runtime copy whose registry
+				// lacks this section (e.g. an old npm copy handling a new handle). The
+				// functional updater would otherwise crash the whole process on
+				// `undefined`. Fall back to the handle's own parse of the raw doc.
+				const currentValue = (
+					next.has(section.key)
+						? next.get(section.key)
+						: section.__section.parse(base[section.key], ctx)
+				) as Readonly<T>;
+				const mergedValue =
+					typeof updater === "function"
+						? (updater as (c: Readonly<T>) => T)(currentValue)
+						: deepMerge(currentValue as T, updater);
+
+				// Re-validate through the section's own parse so a bad patch (NaN,
+				// Infinity, wrong type) can never enter the live snapshot.
+				const nextValue = section.__section.parse(mergedValue, ctx) as T;
+
+				if (JSON.stringify(currentValue) === JSON.stringify(nextValue)) return undefined;
+				next.set(section.key, nextValue);
+				values = next;
+				return serializeRawDocument(this.buildRawFromValues(next, base));
 			});
-			if (err instanceof ConfigWriteError) return undefined;
+		} catch (err) {
+			if (err instanceof ConfigParseError) this.parseFailed(err, section.key);
+			else
+				this.sink.push({
+					code: "WRITE_FAILED",
+					severity: "error",
+					path: section.key,
+					message: "config write failed; snapshot unchanged",
+					cause: err,
+				});
 			return undefined;
 		}
+		if (!values) return undefined;
 
 		const snapshot = this.publish(values);
 		const change: ConfigChange = {
@@ -401,7 +439,15 @@ class RuntimeImpl implements PixRuntime {
 	reload(options: ReloadOptions = {}): Promise<ConfigChange | undefined> {
 		return this.queue.run(async () => {
 			const previous = this.snapshot();
-			const doc = parseRawDocument(this.storage.readRaw());
+			let doc: RawDocument;
+			try {
+				doc = parseRawDocument(this.storage.readRaw());
+			} catch (err) {
+				// Keep the last good snapshot. Do not reset live settings to defaults.
+				if (!(err instanceof ConfigParseError)) throw err;
+				this.parseFailed(err);
+				return undefined;
+			}
 			const values = this.resolve(doc);
 			const snapshot = this.publish(values);
 			const changed = this.changedPaths(previous, snapshot);

package/src/safe-path.ts

@@ -0,0 +1,101 @@
+/**
+ * safe-path.ts — pre-flight check before a tool writes to a model-chosen path.
+ *
+ * The rules differ per OS: system dirs, path separators, and case. Callers get
+ * one call and a reason they can show to the model.
+ */
+
+import { constants as fsConstants } from "node:fs";
+import { access, lstat } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { homeDir } from "./paths.ts";
+import { currentPlatform, type HostPlatform } from "./platform.ts";
+
+export type PathValidation = { ok: true; path: string } | { ok: false; reason: string };
+
+export interface SafePathOptions {
+	env?: NodeJS.ProcessEnv;
+	host?: HostPlatform;
+}
+
+/** Absolute prefixes that never get tool output, for this host. */
+export function sensitivePrefixes(opts: SafePathOptions = {}): string[] {
+	const host = opts.host ?? currentPlatform();
+	const env = opts.env ?? process.env;
+	const p = host.os === "win32" ? win32 : posix;
+	const home = homeDir(env, host.os);
+	const secrets = [".ssh", ".aws", ".gnupg", p.join(".config", "gh")].map((d) => p.join(home, d));
+	if (host.os !== "win32") return ["/etc", "/proc", "/sys", "/boot", ...secrets];
+	const sys = [env.SystemRoot ?? "C:\\Windows", env.ProgramFiles, env["ProgramFiles(x86)"]];
+	const appData = env.APPDATA ?? p.join(home, "AppData", "Roaming");
+	return [...sys, p.join(appData, "GitHub CLI"), ...secrets].filter((d): d is string => !!d);
+}
+
+/** True when `path` is `prefix` or inside it. Case-insensitive on Windows. */
+function isUnder(path: string, prefix: string, host: HostPlatform): boolean {
+	const p = host.os === "win32" ? win32 : posix;
+	// win32.relative already compares case-insensitively.
+	const rel = p.relative(p.resolve(prefix), p.resolve(path));
+	return rel !== ".." && !rel.startsWith(`..${p.sep}`) && !p.isAbsolute(rel);
+}
+
+/**
+ * Rejects null bytes, sensitive system locations, symlinks (target or any
+ * existing parent — Windows junctions count), existing directories, and paths
+ * with no writable existing ancestor.
+ */
+export async function validateOutputPath(
+	absPath: string,
+	opts: SafePathOptions = {},
+): Promise<PathValidation> {
+	const host = opts.host ?? currentPlatform();
+	const p = host.os === "win32" ? win32 : posix;
+	if (absPath.includes("\0")) return { ok: false, reason: "path contains a null byte" };
+	// `\\?\C:\Windows\x` and `\\.\C:\...` reach the same files as `C:\Windows\x`, but
+	// win32.relative() sees another root, so isUnder() would miss them. Normal
+	// output paths never need a device or namespace prefix.
+	if (host.os === "win32" && /^[\\/]{2}[?.][\\/]|^\\\?\?\\/.test(absPath))
+		return { ok: false, reason: `refusing a Windows device or namespace path: ${absPath}` };
+
+	for (const prefix of sensitivePrefixes({ ...opts, host })) {
+		if (isUnder(absPath, prefix, host))
+			return { ok: false, reason: `refusing to write under ${prefix}` };
+	}
+
+	// lstat does not follow symlinks. That is the point here.
+	try {
+		const st = await lstat(absPath);
+		if (st.isSymbolicLink()) return { ok: false, reason: `target is a symlink: ${absPath}` };
+		if (st.isDirectory())
+			return { ok: false, reason: `target is an existing directory: ${absPath}` };
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT")
+			return { ok: false, reason: `cannot stat target: ${(err as Error).message}` };
+	}
+
+	// Every existing ancestor must not be a symlink (stops a safe-looking dir → /etc
+	// redirect). The nearest one must be writable so mkdir -p works.
+	const parent = p.dirname(absPath);
+	let nearest: string | null = null;
+	for (let cursor = parent; cursor !== p.dirname(cursor); cursor = p.dirname(cursor)) {
+		let st: Awaited<ReturnType<typeof lstat>>;
+		try {
+			st = await lstat(cursor);
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code === "ENOENT") continue;
+			return { ok: false, reason: `cannot stat parent: ${(err as Error).message}` };
+		}
+		if (st.isSymbolicLink()) return { ok: false, reason: `parent is a symlink: ${cursor}` };
+		if (st.isDirectory() && nearest === null) nearest = cursor;
+	}
+	if (nearest === null)
+		return { ok: false, reason: `no existing ancestor directory for ${parent}` };
+	try {
+		// ponytail: W_OK reads only the read-only attribute on Windows, not ACLs.
+		// A denied ACL still fails later at mkdir/writeFile with a clear EPERM.
+		await access(nearest, fsConstants.W_OK);
+	} catch {
+		return { ok: false, reason: `no writable ancestor directory: ${nearest}` };
+	}
+	return { ok: true, path: absPath };
+}

package/src/testing.ts

@@ -3,9 +3,9 @@
  * never touch the real agent directory or the process singleton.
  */
 
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { mkdtempSync, rmSync, symlinkSync } from "node:fs";
 import { join } from "node:path";
+import { tempDir } from "./paths.ts";
 import { FileStorage } from "./persistence.ts";
 import { createRuntime, type PixRuntime } from "./runtime.ts";
 
@@ -16,9 +16,25 @@ export interface IsolatedRuntime {
 	cleanup(): void;
 }
 
+/**
+ * True when this process may create symlinks. Windows allows it only in Developer
+ * Mode or as admin (else EPERM). Use it to skip symlink tests: `it.skipIf(!canSymlink())`.
+ */
+export function canSymlink(): boolean {
+	const dir = mkdtempSync(join(tempDir(), "pix-symlink-probe-"));
+	try {
+		symlinkSync(dir, join(dir, "link"), "dir");
+		return true;
+	} catch {
+		return false;
+	} finally {
+		rmSync(dir, { recursive: true, force: true });
+	}
+}
+
 /** Create a runtime backed by a fresh temp directory. */
 export function createIsolatedRuntime(): IsolatedRuntime {
-	const agentDir = mkdtempSync(join(tmpdir(), "pix-runtime-"));
+	const agentDir = mkdtempSync(join(tempDir(), "pix-runtime-"));
 	const runtime = createRuntime({ agentDir, storage: new FileStorage(agentDir) });
 	return {
 		runtime,