pi-crew 0.1.45 → 0.1.49

package/src/runtime/yield-handler.ts

@@ -0,0 +1,189 @@
+import { subprocessToolRegistry, type SubprocessToolEvent } from "./subprocess-tool-registry.ts";
+
+// G3: Full AJV-based schema validation for yield data.
+// Falls back to lightweight validation if AJV is unavailable.
+
+let _ajv: Awaited<ReturnType<typeof getAjvInternal>> | null | undefined;
+
+async function getAjvInternal() {
+	const mod = await import("ajv");
+	const AjvCtor = ("default" in mod ? (mod as Record<string, unknown>).default : mod) as unknown as new (opts: Record<string, unknown>) => { compile: (schema: unknown) => { (data: unknown): boolean; errors?: unknown[] }; errorsText: (errors?: unknown[]) => string };
+	return new AjvCtor({ allErrors: true, strict: false, logger: false });
+}
+
+async function getAjv() {
+	if (_ajv === undefined) {
+		try {
+			_ajv = await getAjvInternal();
+		} catch {
+			_ajv = null;
+		}
+	}
+	return _ajv;
+}
+
+export interface SchemaValidationResult {
+	valid: boolean;
+	error?: string;
+}
+
+/**
+ * Validate yield data against a JSON Schema.
+ * Uses AJV when available (hoisted dep from pi-ai), falls back to
+ * lightweight type checking when not.
+ */
+export async function validateYieldData(data: unknown, schema: unknown): Promise<SchemaValidationResult> {
+	if (!schema) return { valid: true };
+	if (data === undefined || data === null) return { valid: false, error: "Yield data is null or undefined." };
+
+	// Try AJV first
+	const ajv = await getAjv();
+	if (ajv) {
+		try {
+			const validate = ajv.compile(schema as Record<string, unknown>);
+			const valid = validate(data);
+			if (!valid) {
+				return { valid: false, error: ajv.errorsText(validate.errors ?? undefined) };
+			}
+			return { valid: true };
+		} catch {
+			// AJV compile failed — fall through to lightweight
+		}
+	}
+
+	// Lightweight fallback
+	return lightweightValidate(data, schema);
+}
+
+function lightweightValidate(data: unknown, schema: unknown): SchemaValidationResult {
+	if (typeof schema === "boolean") return { valid: schema };
+	if (typeof schema !== "object" || Array.isArray(schema)) return { valid: true };
+	const schemaObj = schema as Record<string, unknown>;
+
+	// Check type constraint
+	if (typeof schemaObj.type === "string") {
+		const expected = schemaObj.type;
+		const actual = Array.isArray(data) ? "array" : typeof data;
+		if (expected === "object" && (typeof data !== "object" || Array.isArray(data))) return { valid: false, error: `Expected type '${expected}' but got '${actual}'.` };
+		if (expected === "array" && !Array.isArray(data)) return { valid: false, error: `Expected type 'array' but got '${actual}'.` };
+		if (expected === "string" && typeof data !== "string") return { valid: false, error: `Expected type 'string' but got '${actual}'.` };
+		if (expected === "number" && typeof data !== "number") return { valid: false, error: `Expected type 'number' but got '${actual}'.` };
+		if (expected === "boolean" && typeof data !== "boolean") return { valid: false, error: `Expected type 'boolean' but got '${actual}'.` };
+	}
+
+	// Check required fields
+	if (Array.isArray(schemaObj.required) && typeof data === "object" && data !== null && !Array.isArray(data)) {
+		const dataObj = data as Record<string, unknown>;
+		for (const field of schemaObj.required) {
+			if (typeof field === "string" && !(field in dataObj)) {
+				return { valid: false, error: `Missing required field '${field}'.` };
+			}
+		}
+	}
+
+	return { valid: true };
+}
+
+export interface YieldResult {
+	summary: string;
+	artifacts?: Record<string, string>;
+	structuredData?: Record<string, unknown>;
+	toolCallId: string;
+}
+
+export interface YieldConfig {
+	enabled: boolean;
+	maxReminders: number;
+	reminderPrompt: string;
+}
+
+export const DEFAULT_YIELD_CONFIG: YieldConfig = {
+	enabled: true,
+	maxReminders: 3,
+	reminderPrompt: "You must call the submit_result tool to return your results.",
+};
+
+/** Tool name used by workers to yield their result. */
+export const YIELD_TOOL_NAME = "submit_result";
+
+/**
+ * Check if a value is a plain object record (non-null, non-array object).
+ */
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Check if a value is a record with all string values.
+ */
+function isStringRecord(value: unknown): value is Record<string, string> {
+	if (!isObjectRecord(value)) return false;
+	return Object.values(value).every((v) => typeof v === "string");
+}
+
+/**
+ * Shared helper to extract yield data from tool call arguments.
+ * Used by both `extractYieldResult` and `registerYieldTool.extractData`
+ * to avoid duplicating parsing logic.
+ */
+export function extractYieldDataFromArgs(args: unknown, toolCallId: string): YieldResult | undefined {
+	if (!isObjectRecord(args)) return undefined;
+	const summary = typeof args.summary === "string" ? args.summary : "";
+	if (!summary) return undefined;
+	const result: YieldResult = { summary, toolCallId };
+	if (args.artifacts && isStringRecord(args.artifacts)) {
+		result.artifacts = args.artifacts;
+	}
+	if (args.structuredData && isObjectRecord(args.structuredData)) {
+		result.structuredData = args.structuredData;
+	}
+	return result;
+}
+
+/**
+ * Check if a JSON event represents a yield/submit_result tool call.
+ * Supports event types: tool_execution_start, toolCall, tool_call.
+ */
+export function isYieldEvent(event: Record<string, unknown>): boolean {
+	const type = event.type;
+	if (type !== "tool_execution_start" && type !== "toolCall" && type !== "tool_call") return false;
+	const toolName = event.toolName ?? event.name ?? event.tool;
+	return toolName === YIELD_TOOL_NAME;
+}
+
+/**
+ * Extract structured result from a yield event.
+ */
+export function extractYieldResult(event: Record<string, unknown>): YieldResult | undefined {
+	if (!isYieldEvent(event)) return undefined;
+	const toolCallId = typeof event.toolCallId === "string" ? event.toolCallId : "";
+	return extractYieldDataFromArgs(event.args, toolCallId);
+}
+
+/**
+ * Check if a worker output sequence contains a yield.
+ */
+export function hasYieldInOutput(events: Record<string, unknown>[]): boolean {
+	return events.some((event) => isYieldEvent(event));
+}
+
+/**
+ * Build a reminder prompt for workers that haven't yielded.
+ */
+export function buildYieldReminder(attempt: number, maxAttempts: number, reminderPrompt?: string): string {
+	return `[Yield Reminder ${attempt}/${maxAttempts}] ${reminderPrompt ?? DEFAULT_YIELD_CONFIG.reminderPrompt}`;
+}
+
+/**
+ * Register the submit_result tool handler in the subprocess tool registry.
+ */
+export function registerYieldTool(): void {
+	subprocessToolRegistry.register<YieldResult>(YIELD_TOOL_NAME, {
+		extractData(event: SubprocessToolEvent): YieldResult | undefined {
+			return extractYieldDataFromArgs(event.args, event.toolCallId);
+		},
+		shouldTerminate(): boolean {
+			return true;
+		},
+	});
+}

package/src/schema/config-schema.ts

@@ -39,6 +39,7 @@ export const PiTeamsRuntimeConfigSchema = Type.Object({
 	groupJoinAckTimeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
 	requirePlanApproval: Type.Optional(Type.Boolean()),
 	completionMutationGuard: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("warn"), Type.Literal("fail")])),
+	effectivenessGuard: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("warn"), Type.Literal("block"), Type.Literal("fail")])),
 }, { additionalProperties: false });
 
 export const PiTeamsControlConfigSchema = Type.Object({
@@ -76,6 +77,11 @@ export const PiTeamsTelemetryConfigSchema = Type.Object({
 	enabled: Type.Optional(Type.Boolean()),
 }, { additionalProperties: false });
 
+export const PiTeamsPolicyConfigSchema = Type.Object({
+	requireIntentForDestructiveActions: Type.Optional(Type.Boolean()),
+	disabledCapabilities: Type.Optional(Type.Array(Type.String())),
+}, { additionalProperties: false });
+
 export const PiTeamsNotificationsConfigSchema = Type.Object({
 	enabled: Type.Optional(Type.Boolean()),
 	severityFilter: Type.Optional(Type.Array(Type.Union([Type.Literal("info"), Type.Literal("warning"), Type.Literal("error"), Type.Literal("critical")]))),
@@ -141,6 +147,7 @@ export const PiTeamsConfigSchema = Type.Object({
 	agents: Type.Optional(PiTeamsAgentsConfigSchema),
 	tools: Type.Optional(PiTeamsToolsConfigSchema),
 	telemetry: Type.Optional(PiTeamsTelemetryConfigSchema),
+	policy: Type.Optional(PiTeamsPolicyConfigSchema),
 	notifications: Type.Optional(PiTeamsNotificationsConfigSchema),
 	observability: Type.Optional(PiTeamsObservabilityConfigSchema),
 	reliability: Type.Optional(PiTeamsReliabilityConfigSchema),

package/src/schema/team-tool-schema.ts

@@ -1,10 +1,10 @@
 import { Type } from "typebox";
 
 const SkillOverride = Type.Unsafe({
-	description: "Skill name(s) to inject, array of skill names, or false to disable role defaults.",
+	description: "Skill name(s) to add to role/default skills, an array of skill names, or false to disable all injected skills for this run.",
 	anyOf: [
-		{ type: "string" },
-		{ type: "array", items: { type: "string" } },
+		{ type: "string", maxLength: 2048 },
+		{ type: "array", maxItems: 32, items: { type: "string", maxLength: 80 } },
 		{ type: "boolean" },
 	],
 });
@@ -18,6 +18,7 @@ const FreeformConfig = Type.Unsafe({
 export const TeamToolParams = Type.Object({
 	action: Type.Optional(Type.Union([
 		Type.Literal("run"),
+		Type.Literal("parallel"),
 		Type.Literal("plan"),
 		Type.Literal("status"),
 		Type.Literal("list"),
@@ -85,10 +86,13 @@ export const TeamToolParams = Type.Object({
 	force: Type.Optional(Type.Boolean({ description: "Override reference checks for destructive management actions." })),
 	keep: Type.Optional(Type.Integer({ minimum: 0, description: "Number of finished runs to keep for prune." })),
 	updateReferences: Type.Optional(Type.Boolean({ description: "When renaming agents or workflows, update team references in the same project/user scope." })),
+	replyTo: Type.Optional(Type.String({ description: "ID of the original mailbox message this is a reply to." })),
+	replyFrom: Type.Optional(Type.String({ description: "Task ID sending the reply." })),
+	replyDeadline: Type.Optional(Type.Integer({ description: "Ms epoch deadline for a reply." })),
 });
 
 export interface TeamToolParamsValue {
-	action?: "run" | "plan" | "status" | "list" | "get" | "cancel" | "resume" | "respond" | "create" | "update" | "delete" | "doctor" | "cleanup" | "events" | "artifacts" | "worktrees" | "forget" | "summary" | "prune" | "export" | "import" | "imports" | "help" | "validate" | "config" | "init" | "recommend" | "autonomy" | "api" | "settings";
+	action?: "run" | "parallel" | "plan" | "status" | "list" | "get" | "cancel" | "retry" | "resume" | "respond" | "create" | "update" | "delete" | "doctor" | "cleanup" | "events" | "artifacts" | "worktrees" | "forget" | "summary" | "prune" | "export" | "import" | "imports" | "help" | "validate" | "config" | "init" | "recommend" | "autonomy" | "api" | "settings";
 	resource?: "agent" | "team" | "workflow";
 	team?: string;
 	workflow?: string;
@@ -112,4 +116,10 @@ export interface TeamToolParamsValue {
 	force?: boolean;
 	keep?: number;
 	updateReferences?: boolean;
+	/** ID of the original mailbox message this is a reply to. */
+	replyTo?: string;
+	/** Task ID sending the reply. */
+	replyFrom?: string;
+	/** Ms epoch deadline for a reply. */
+	replyDeadline?: number;
 }

package/src/skills/discover-skills.ts

@@ -0,0 +1,67 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { logInternalError } from "../utils/internal-error.ts";
+import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
+
+const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+
+export interface SkillDescriptor {
+	name: string;
+	description: string;
+	source: "project" | "package";
+	path: string;
+}
+
+function listSkillDirs(cwd: string): Array<{ root: string; source: "project" | "package" }> {
+	return [
+		{ root: path.resolve(cwd, "skills"), source: "project" },
+		{ root: PACKAGE_SKILLS_DIR, source: "package" },
+	];
+}
+
+function frontmatterDescription(content: string): string | undefined {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!match) return undefined;
+	const line = match[1].split(/\r?\n/).find((entry) => entry.startsWith("description:"));
+	return line?.slice("description:".length).trim();
+}
+
+export function discoverSkills(cwd: string): SkillDescriptor[] {
+	const results: SkillDescriptor[] = [];
+	for (const dir of listSkillDirs(cwd)) {
+		if (!fs.existsSync(dir.root)) continue;
+		try {
+			for (const entry of fs.readdirSync(dir.root, { withFileTypes: true })) {
+				if (!entry.isDirectory()) continue;
+				if (!isSafePathId(entry.name)) continue;
+				const skillDirPath = path.join(dir.root, entry.name);
+				try {
+					if (fs.lstatSync(skillDirPath).isSymbolicLink()) continue;
+				} catch { continue; }
+				const skillMdRelative = path.join(entry.name, "SKILL.md");
+				let skillMdPath: string;
+				try {
+					skillMdPath = resolveContainedPath(dir.root, skillMdRelative);
+				} catch { continue; }
+				if (!fs.existsSync(skillMdPath)) continue;
+				try {
+					if (fs.lstatSync(skillMdPath).isSymbolicLink()) continue;
+				} catch { continue; }
+				let description = "";
+				try {
+					const realPath = resolveRealContainedPath(dir.root, skillMdRelative);
+					const content = fs.readFileSync(realPath, "utf-8");
+					description = frontmatterDescription(content) ?? "";
+					skillMdPath = realPath;
+				} catch (error) {
+					logInternalError("discoverSkills.readSkill", error, `skill=${entry.name}`);
+				}
+				results.push({ name: entry.name, description, source: dir.source, path: skillMdPath });
+			}
+		} catch (error) {
+			logInternalError("discoverSkills.readdir", error, `root=${dir.root}`);
+		}
+	}
+	return results;
+}

package/src/state/active-run-registry.ts

@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DEFAULT_CACHE, DEFAULT_PATHS } from "../config/defaults.ts";
+import type { TeamRunManifest } from "./types.ts";
+import { atomicWriteJson } from "./atomic-write.ts";
+import { userCrewRoot } from "../utils/paths.ts";
+import { isSafePathId } from "../utils/safe-paths.ts";
+import { sharedScanCache } from "../utils/scan-cache.ts";
+
+export interface ActiveRunRegistryEntry {
+	runId: string;
+	cwd: string;
+	stateRoot: string;
+	manifestPath: string;
+	updatedAt: string;
+}
+
+function registryPath(): string {
+	return path.join(userCrewRoot(), DEFAULT_PATHS.state.runsSubdir, "active-run-index.json");
+}
+
+function registryLockPath(): string {
+	return `${registryPath()}.lock`;
+}
+
+function sleepSync(ms: number): void {
+	try {
+		Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+	} catch {
+		const deadline = Date.now() + ms;
+		while (Date.now() < deadline) {
+			// Best-effort fallback for rare runtimes without Atomics.wait.
+		}
+	}
+}
+
+function lockCreatedAt(raw: string): number | undefined {
+	try {
+		const parsed = JSON.parse(raw) as { createdAt?: unknown };
+		if (typeof parsed.createdAt !== "string") return undefined;
+		const time = Date.parse(parsed.createdAt);
+		return Number.isNaN(time) ? undefined : time;
+	} catch {
+		return undefined;
+	}
+}
+
+function removeStaleRegistryLock(lockPath: string, staleMs: number): boolean {
+	try {
+		const stat = fs.statSync(lockPath);
+		const createdAt = lockCreatedAt(fs.readFileSync(lockPath, "utf-8")) ?? stat.mtimeMs;
+		if (Date.now() - createdAt <= staleMs) return false;
+		fs.rmSync(lockPath, { force: true });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function withRegistryLock<T>(fn: () => T): T {
+	const filePath = registryLockPath();
+	const staleMs = 30_000;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	let attempt = 0;
+	const deadline = Date.now() + staleMs * 2;
+	while (true) {
+		try {
+			const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
+			try {
+				fs.writeSync(fd, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+			} finally {
+				fs.closeSync(fd);
+			}
+			break;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "EEXIST") throw error;
+			if (!removeStaleRegistryLock(filePath, staleMs) && Date.now() > deadline) throw new Error("Active-run registry is locked by another operation.");
+			sleepSync(Math.min(250, 25 * 2 ** attempt));
+			attempt += 1;
+		}
+	}
+	try {
+		return fn();
+	} finally {
+		try {
+			fs.rmSync(filePath, { force: true });
+		} catch {
+			// Best-effort cleanup.
+		}
+	}
+}
+
+function normalizeEntry(value: unknown): ActiveRunRegistryEntry | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const runId = typeof record.runId === "string" ? record.runId : undefined;
+	const cwd = typeof record.cwd === "string" ? record.cwd : undefined;
+	const stateRoot = typeof record.stateRoot === "string" ? record.stateRoot : undefined;
+	const manifestPath = typeof record.manifestPath === "string" ? record.manifestPath : undefined;
+	const updatedAt = typeof record.updatedAt === "string" ? record.updatedAt : undefined;
+	if (!runId || !isSafePathId(runId) || !cwd || !stateRoot || !manifestPath || !updatedAt) return undefined;
+	if (path.basename(stateRoot) !== runId) return undefined;
+	if (path.resolve(manifestPath) !== path.resolve(path.join(stateRoot, DEFAULT_PATHS.state.manifestFile))) return undefined;
+	return { runId, cwd, stateRoot, manifestPath, updatedAt };
+}
+
+export function readActiveRunRegistry(maxEntries = DEFAULT_CACHE.manifestMaxEntries): ActiveRunRegistryEntry[] {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(fs.readFileSync(registryPath(), "utf-8"));
+	} catch {
+		return [];
+	}
+	const entries = Array.isArray(parsed) ? parsed.map(normalizeEntry).filter((entry): entry is ActiveRunRegistryEntry => entry !== undefined) : [];
+	const byId = new Map<string, ActiveRunRegistryEntry>();
+	for (const entry of entries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))) {
+		if (!byId.has(entry.runId)) byId.set(entry.runId, entry);
+	}
+	return [...byId.values()].slice(0, Math.max(0, maxEntries));
+}
+
+function writeEntries(entries: ActiveRunRegistryEntry[]): void {
+	fs.mkdirSync(path.dirname(registryPath()), { recursive: true });
+	atomicWriteJson(registryPath(), entries.slice(0, DEFAULT_CACHE.manifestMaxEntries));
+}
+
+export function registerActiveRun(manifest: TeamRunManifest): void {
+	const entry: ActiveRunRegistryEntry = {
+		runId: manifest.runId,
+		cwd: manifest.cwd,
+		stateRoot: manifest.stateRoot,
+		manifestPath: path.join(manifest.stateRoot, DEFAULT_PATHS.state.manifestFile),
+		updatedAt: manifest.updatedAt,
+	};
+	withRegistryLock(() => {
+		writeEntries([entry, ...readActiveRunRegistry().filter((item) => item.runId !== manifest.runId)]);
+	});
+}
+
+export function unregisterActiveRun(runId: string): void {
+	if (!isSafePathId(runId)) return;
+	withRegistryLock(() => {
+		writeEntries(readActiveRunRegistry().filter((entry) => entry.runId !== runId));
+	});
+}
+
+export function activeRunEntries(): ActiveRunRegistryEntry[] {
+	const entries: ActiveRunRegistryEntry[] = [];
+	for (const entry of readActiveRunRegistry()) {
+		try {
+			if (!fs.existsSync(entry.stateRoot) || !fs.existsSync(entry.manifestPath)) continue;
+			if (fs.lstatSync(entry.stateRoot).isSymbolicLink()) continue;
+			const cached = sharedScanCache.readAndCache("active-manifests", entry.runId, entry.manifestPath);
+			const manifest = (cached?.raw ?? JSON.parse(fs.readFileSync(entry.manifestPath, "utf-8"))) as { status?: unknown };
+			if (manifest.status !== "queued" && manifest.status !== "planning" && manifest.status !== "running" && manifest.status !== "blocked") continue;
+			entries.push(entry);
+		} catch {
+			// Ignore stale entries; callers filter active status from manifests.
+		}
+	}
+	return entries;
+}
+
+export function activeRunRoots(): string[] {
+	return [...new Set(activeRunEntries().map((entry) => path.dirname(entry.stateRoot)))];
+}

package/src/state/artifact-store.ts

@@ -99,7 +99,10 @@ function resolveInside(baseDir: string, relativePath: string): string {
 	const resolved = path.resolve(base, normalizedRelativePath);
 	const relative = path.relative(base, resolved);
 	if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`Invalid artifact path: ${relativePath}`);
-	return resolved;
+	// C1: Extra normalization guard for case-insensitive / symlinked filesystems
+	const normalized = path.normalize(resolved);
+	if (!normalized.startsWith(base + path.sep) && normalized !== base) throw new Error(`Invalid artifact path (traversal): ${relativePath}`);
+	return normalized;
 }
 
 export function writeArtifact(artifactsRoot: string, options: ArtifactWriteOptions): ArtifactDescriptor {

package/src/state/atomic-write.ts

@@ -4,6 +4,49 @@ import { logInternalError } from "../utils/internal-error.ts";
 
 const RETRYABLE_RENAME_CODES = new Set(["EPERM", "EBUSY", "EACCES"]);
 
+/**
+ * Symlink-safe file write guard (caveman-inspired).
+ * Returns true if the path is safe to write, false if it's a symlink or
+ * inside a symlinked directory owned by another user.
+ */
+function isSymlinkSafePath(filePath: string): boolean {
+	try {
+		const dir = path.dirname(filePath);
+		// Check if parent directory is a symlink
+		try {
+			const dirStat = fs.lstatSync(dir);
+			if (dirStat.isSymbolicLink()) {
+				// Resolve and verify ownership on Unix
+				const realDir = fs.realpathSync(dir);
+				const realStat = fs.statSync(realDir);
+				if (!realStat.isDirectory()) return false;
+				if (typeof process.getuid === "function" && realStat.uid !== process.getuid()) return false;
+			}
+		} catch {
+			// Directory doesn't exist yet — that's OK, mkdirSync will create it
+		}
+
+		// Check if target file itself is a symlink
+		try {
+			const fileStat = fs.lstatSync(filePath);
+			if (fileStat.isSymbolicLink()) return false;
+		} catch {
+			// File doesn't exist yet — that's OK
+		}
+
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Synchronous sleep using Atomics.wait (non-busy) with busy-wait fallback.
+ *
+ * WARNING: This blocks the Node.js main thread. Only used in atomic-write
+ * rename retry path where sync I/O is required by the caller.
+ * NOT safe to call from Pi extension async code paths.
+ */
 function sleepSync(ms: number): void {
 	try {
 		const buffer = new SharedArrayBuffer(4);
@@ -56,10 +99,15 @@ export async function __test__renameWithRetryAsync(tempPath: string, filePath: s
 }
 
 export function atomicWriteFile(filePath: string, content: string): void {
+	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
+	// Write temp with restrictive permissions
+	const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
 	try {
-		fs.writeFileSync(tempPath, content, "utf-8");
+		const fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o644);
+		fs.writeSync(fd, content, undefined, "utf-8");
+		fs.closeSync(fd);
 		__test__renameWithRetry(tempPath, filePath);
 	} catch (error) {
 		try {
@@ -73,6 +121,7 @@ export function atomicWriteFile(filePath: string, content: string): void {
 
 
 export async function atomicWriteFileAsync(filePath: string, content: string): Promise<void> {
+	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
 	const tempPath = `${filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
 	try {