pi-crew 0.6.1 → 0.6.4

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

@@ -1,9 +1,9 @@
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { serialize, deserialize } from "node:v8";
 import { DEFAULT_CACHE, DEFAULT_PATHS } from "../config/defaults.ts";
 import type { TeamRunManifest } from "./types.ts";
-import { atomicWriteJson } from "./atomic-write.ts";
+import { atomicWriteJson, renameWithRetry, isSymlinkSafePath } from "./atomic-write.ts";
 import { userCrewRoot } from "../utils/paths.ts";
 import { isSafePathId } from "../utils/safe-paths.ts";
 import { sharedScanCache } from "../utils/scan-cache.ts";
@@ -13,6 +13,9 @@ import { logInternalError } from "../utils/internal-error.ts";
 /** Magic bytes prefix for binary registry to prevent deserialization of hostile files. */
 const BINARY_MAGIC = Buffer.from("PICREW2BIN", "utf-8");
 
+/** Binary format version for forward compatibility. */
+const BINARY_VERSION = 1;
+
 export interface ActiveRunRegistryEntry {
 	runId: string;
 	cwd: string;
@@ -64,7 +67,8 @@ function withRegistryLock<T>(fn: () => T): T {
 	const staleMs = 30_000;
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	let attempt = 0;
-	const deadline = Date.now() + staleMs * 2;
+	// FIX Issue 3: Reduced timeout from staleMs*2 (60s) to 10s max for responsive shutdown.
+	const deadline = Date.now() + 10_000;
 	while (true) {
 		try {
 			const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
@@ -109,16 +113,25 @@ function normalizeEntry(value: unknown): ActiveRunRegistryEntry | undefined {
 
 export function readActiveRunRegistry(maxEntries = DEFAULT_CACHE.manifestMaxEntries): ActiveRunRegistryEntry[] {
 	let parsed: unknown;
-	// 2.4 — prefer the binary mirror (single deserialize, no JSON.parse on
-	// large arrays). Fall back to JSON when the binary is missing or
-	// corrupt; this lets a 2-release migration co-exist with old readers.
+	// 2.4 — prefer the binary mirror (JSON after header for schema-safe deserialization).
+	// Fall back to JSON when the binary is missing or corrupt; this lets a 2-release
+	// migration co-exist with old readers.
 	try {
 		const buf = fs.readFileSync(registryBinaryPath());
-		// Security: verify magic bytes before deserializing to prevent RCE from hostile files
+		// Security: verify magic bytes before parsing to prevent hostile files
 		if (buf.length < BINARY_MAGIC.length || !buf.slice(0, BINARY_MAGIC.length).equals(BINARY_MAGIC)) {
 			throw new Error("Invalid binary registry: missing magic bytes");
 		}
-		parsed = deserialize(buf.slice(BINARY_MAGIC.length));
+		// FIX Issue 1: Verify version field for forward compatibility.
+		const versionOffset = BINARY_MAGIC.length;
+		const version = buf.readUInt32BE(versionOffset);
+		if (version !== BINARY_VERSION) {
+			throw new Error(`Unsupported binary registry version: ${version}`);
+		}
+		// FIX Issue 1: Use JSON.parse instead of v8 deserialize for schema-safe parsing.
+		// The magic+version header provides integrity at the file level.
+		const jsonSlice = buf.slice(versionOffset + 4);
+		parsed = JSON.parse(jsonSlice.toString("utf-8"));
 	} catch {
 		try {
 			parsed = JSON.parse(fs.readFileSync(registryPath(), "utf-8"));
@@ -134,50 +147,138 @@ export function readActiveRunRegistry(maxEntries = DEFAULT_CACHE.manifestMaxEntr
 	return [...byId.values()].slice(0, Math.max(0, maxEntries));
 }
 
-function writeEntries(entries: ActiveRunRegistryEntry[]): void {
+/**
+ * FIX Issues 1 & 2: Atomic binary write using O_CREAT|O_EXCL|O_NOFOLLOW pattern.
+ * Writes to temp file first, then renames. Includes version field for forward compatibility.
+ */
+function atomicWriteBinary(filePath: string, entries: ActiveRunRegistryEntry[]): void {
+	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write binary registry: target is a symlink or inside untrusted directory: ${filePath}`);
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	const tempPath = `${filePath}.${crypto.randomUUID()}.tmp`;
+	const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+	const fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
+	try {
+		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
+		const openedStat = fs.fstatSync(fd);
+		if (!openedStat.isFile()) {
+			fs.closeSync(fd);
+			throw new Error(`Refusing to write binary registry: opened path is not a regular file: ${tempPath}`);
+		}
+		// Write: magic (10 bytes) + version (4 bytes) + JSON data
+		const header = Buffer.allocUnsafe(14);
+		BINARY_MAGIC.copy(header, 0);
+		header.writeUInt32BE(BINARY_VERSION, BINARY_MAGIC.length);
+		// FIX Issue 1: Use JSON.stringify instead of v8 serialize for schema-safe output.
+		const jsonStr = JSON.stringify(entries);
+		const jsonBuf = Buffer.from(jsonStr, "utf-8");
+		fs.writeSync(fd, Buffer.concat([header, jsonBuf]));
+		fs.closeSync(fd);
+		renameWithRetry(tempPath, filePath);
+	} catch (error) {
+		try { fs.rmSync(tempPath, { force: true }); } catch { /* best-effort */ }
+		throw error;
+	}
+}
+
+function writeEntries(entries: ActiveRunRegistryEntry[], skipTerminalRunIds?: Set<string>): void {
 	const max = DEFAULT_CACHE.manifestMaxEntries;
-	// FIX: Emit warning when entries overflow the cap, instead of silent drop.
+	// FIX Issue 3: Gracefully prune oldest entries instead of throwing when cap is exceeded.
 	if (entries.length > max) {
-		logInternalError(
-			"active-run-registry.overflow",
-			new Error(`${entries.length - max} entries dropped (cap=${max})`),
-			JSON.stringify({ dropped: entries.length - max, total: entries.length, cap: max }),
-		);
+		const sorted = [...entries].sort((a, b) => (a.updatedAt ?? "").localeCompare(b.updatedAt ?? ""));
+		entries = sorted.slice(entries.length - max);
+	}
+	// FIX Issue 1: Skip entries that transitioned to terminal since filterAliveEntries was called.
+	// This closes the TOCTOU race between status check in filterAliveEntries and write.
+	if (skipTerminalRunIds?.size) {
+		entries = entries.filter((e) => !skipTerminalRunIds.has(e.runId));
 	}
-	const trimmed = entries.slice(0, max);
 	fs.mkdirSync(path.dirname(registryPath()), { recursive: true });
-	// 2.4 — dual-ship: write both formats. Readers prefer binary; legacy
-	// readers (other tools / older releases) keep using the JSON file.
-	atomicWriteJson(registryPath(), trimmed);
+	// FIX Issues 1 & 2: Write both to temp files first, then rename both atomically.
+	// If either rename fails, neither file is updated — registry stays consistent.
+	const tempJson = `${registryPath()}.${crypto.randomUUID()}.tmp`;
+	const tempBin = `${registryBinaryPath()}.${crypto.randomUUID()}.tmp`;
+	let jsonRenamed = false;
+	let binRenamed = false;
 	try {
-		const tempBin = `${registryBinaryPath()}.${process.pid}.${Date.now()}.tmp`;
-		fs.writeFileSync(tempBin, Buffer.concat([BINARY_MAGIC, serialize(trimmed)]));
-		fs.renameSync(tempBin, registryBinaryPath());
+		// Write JSON to temp first
+		atomicWriteJson(tempJson, entries);
+		// Write binary to temp (atomic pattern)
+		atomicWriteBinary(tempBin, entries);
+		// Both written successfully — rename both atomically
+		renameWithRetry(tempJson, registryPath());
+		jsonRenamed = true;
+		renameWithRetry(tempBin, registryBinaryPath());
+		binRenamed = true;
 	} catch (error) {
-		logInternalError("active-run-registry.binary-write", error);
-	}
+		// FIX Issue 5: Recovery when one rename succeeded — try to rename the other from its temp file
+		// instead of deleting both. This preserves whichever registry was successfully written.
+		if (jsonRenamed && !binRenamed) {
+			// JSON succeeded, binary failed — try to recover binary from temp
+			try { renameWithRetry(tempBin, registryBinaryPath()); binRenamed = true; } catch { /* recovery failed */ }
+		} else if (binRenamed && !jsonRenamed) {
+			// Binary succeeded, JSON failed — try to recover JSON from temp
+			try { renameWithRetry(tempJson, registryPath()); jsonRenamed = true; } catch { /* recovery failed */ }
+		}
+		// FIX Issue 2: If recovery failed, do NOT delete the final files — they may contain valid
+		// data from a prior write cycle. Leave temp files for manual recovery and throw error.
+		if (!binRenamed || !jsonRenamed) {
+			// Attempt to clean up temp files only (not final files)
+			try { fs.rmSync(tempJson, { force: true }); } catch { /* best-effort */ }
+			try { fs.rmSync(tempBin, { force: true }); } catch { /* best-effort */ }
+			throw error;
+		}
+		// FIX Issue 1: Ensure temp file cleanup executes even when recovery rename fails.
+		// If recovery throws, the error propagates before reaching the cleanup below.
+		// Wrapping in nested try-catch guarantees cleanup runs regardless of recovery outcome.
+		try { fs.rmSync(tempJson, { force: true }); } catch { /* best-effort */ }
+		try { fs.rmSync(tempBin, { force: true }); } catch { /* best-effort */ }
+		throw error;
+}
 }
 
 const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "blocked"]);
 
 /**
- * Filter out entries that are no longer active: terminal status or missing manifest.
- * This prevents unbounded growth of the active-run-index.json file.
+ * FIX Issue 1: Filter out entries that are no longer active: terminal status, missing manifest,
+ * or symlink-unsafe paths. This prevents unbounded growth and guards against symlink attacks.
+ *
+ * WARNING: This function reads manifest files WITHOUT holding the registry lock (TOCTOU race).
+ * Status filtering is best-effort at read time. The terminal runIds set is returned so callers
+ * can pass them to writeEntries to skip entries that transitioned to terminal since filtering.
  */
-function filterAliveEntries(entries: ActiveRunRegistryEntry[]): ActiveRunRegistryEntry[] {
-	return entries.filter((entry) => {
+function filterAliveEntries(entries: ActiveRunRegistryEntry[]): { alive: ActiveRunRegistryEntry[]; terminalRunIds: Set<string> } {
+	const terminalRunIds = new Set<string>();
+	const alive = entries.filter((entry) => {
 		try {
 			if (!fs.existsSync(entry.cwd)) return false;
 			if (!fs.existsSync(entry.manifestPath)) return false;
+			// FIX Issue 2: Guard against symlink attacks on stateRoot and manifestPath
+			if (!isSymlinkSafePath(entry.stateRoot)) return false;
+			if (!isSymlinkSafePath(entry.manifestPath)) return false;
 		} catch {
 			return false;
 		}
 		try {
 			const raw = JSON.parse(fs.readFileSync(entry.manifestPath, "utf-8")) as { status?: string; async?: { pid?: number }; updatedAt?: string };
-			if (TERMINAL_STATUSES.has(raw.status ?? "")) return false;
-			// Dead PID = stale async run
+			if (TERMINAL_STATUSES.has(raw.status ?? "")) {
+				terminalRunIds.add(entry.runId);
+				return false;
+			}
+			// FIX Issue 2: Robust PID liveness check - only ESRCH means process is dead.
+			// EPERM means process exists but we can't signal it (different security context).
+			// Also check manifest age to guard against PID reuse.
 			if (raw.async?.pid) {
-				try { process.kill(raw.async.pid, 0); } catch { return false; }
+				try { process.kill(raw.async.pid, 0); } catch (err) {
+					// Only treat "process does not exist" as dead (ESRCH/ENOENT).
+					// EPERM means process is alive but protected; treat as alive.
+					const code = (err as NodeJS.ErrnoException).code;
+					if (code !== "ESRCH" && code !== "ENOENT") return false;
+					return false;
+				}
+				// FIX Issue 2: Async runs older than 30 min are stale even if PID is alive.
+				// This guards against PID reuse after the original process exits.
+				const updatedAt = typeof raw.updatedAt === 'string' ? Date.parse(raw.updatedAt) : NaN;
+				if (Number.isFinite(updatedAt) && Date.now() - updatedAt > 30 * 60 * 1000) return false;
 			}
 			// 2.19 — Stale non-async run: live-session/scaffold runs older than 30 min
 			// Without this, test runs that crash/leak would stay in the registry forever.
@@ -190,6 +291,7 @@ function filterAliveEntries(entries: ActiveRunRegistryEntry[]): ActiveRunRegistr
 		}
 		return true;
 	});
+	return { alive, terminalRunIds };
 }
 
 export function registerActiveRun(manifest: TeamRunManifest): void {
@@ -204,28 +306,58 @@ export function registerActiveRun(manifest: TeamRunManifest): void {
 		const existing = readActiveRunRegistry().filter((item) => item.runId !== manifest.runId);
 		// Inline cleanup: remove terminal-status and stale entries before writing.
 		// This prevents unbounded growth between sessions.
-		const alive = filterAliveEntries(existing);
-		writeEntries([entry, ...alive]);
+		const { alive, terminalRunIds } = filterAliveEntries(existing);
+		// FIX Issue 4: Also filter the new entry being registered through filterAliveEntries
+		// to exclude it if it is terminal (e.g. completed between call and write).
+		const { alive: filteredAlive } = filterAliveEntries([entry]);
+		const filteredEntry = filteredAlive.length > 0 ? entry : null;
+		if (filteredEntry === null) {
+			throw new Error(`Cannot register run ${manifest.runId}: entry is terminal or paths are not symlink-safe`);
+		}
+		// FIX Issue 1: Pass terminal runIds from filterAliveEntries to writeEntries.
+		// writeEntries will skip these entries, closing the TOCTOU race between status check
+		// and write without re-reading manifest inside the lock.
+		const allTerminalRunIds = new Set(terminalRunIds);
+		if (filteredAlive.length === 0) allTerminalRunIds.add(entry.runId);
+		writeEntries([filteredEntry, ...alive], allTerminalRunIds);
 	});
 }
 
 export function unregisterActiveRun(runId: string): void {
-	if (!isSafePathId(runId)) return;
+	if (!isSafePathId(runId)) {
+		console.warn(`unregisterActiveRun: invalid runId ignored: ${runId}`);
+		return;
+	}
 	withRegistryLock(() => {
-		writeEntries(readActiveRunRegistry().filter((entry) => entry.runId !== runId));
+		// FIX Issue 1: Filter alive entries and pass terminal runIds to writeEntries,
+		// closing the TOCTOU race between status check and write (same pattern as registerActiveRun).
+		const { alive, terminalRunIds } = filterAliveEntries(readActiveRunRegistry().filter((entry) => entry.runId !== runId));
+		writeEntries(alive, terminalRunIds);
 	});
 }
 
+/**
+ * Status filtering is best-effort at read time — entries returned by this function may have
+ * transitioned to terminal status between the manifest read and the filter check.
+ * Callers must re-check status when opening individual run manifests.
+ */
 export function activeRunEntries(): ActiveRunRegistryEntry[] {
 	const entries: ActiveRunRegistryEntry[] = [];
 	for (const entry of readActiveRunRegistry()) {
 		try {
 			// Skip entries whose CWD no longer exists (temp test dirs, deleted projects)
 			if (!fs.existsSync(entry.cwd)) continue;
-			if (!fs.existsSync(entry.stateRoot) || !fs.existsSync(entry.manifestPath)) continue;
-			if (fs.lstatSync(entry.stateRoot).isSymbolicLink()) continue;
+			// FIX Issue 4: sharedScanCache.readAndCache does stat checks internally.
+			// Only check stateRoot/manifestPath existence here if cache miss (cached.raw is undefined).
 			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; updatedAt?: string; async?: { pid?: number } };
+			if (cached?.raw === undefined && (!fs.existsSync(entry.stateRoot) || !fs.existsSync(entry.manifestPath))) continue;
+			// FIX Issue 4: Check full ancestor chain for symlinks, not just immediate stateRoot.
+			if (!isSymlinkSafePath(entry.stateRoot)) continue;
+			// FIX Issue 4: Use cached manifest content directly when available.
+			// sharedScanCache.readAndCache already read the file; avoid redundant re-read.
+			const manifest = (cached?.raw !== undefined
+				? cached.raw
+				: JSON.parse(fs.readFileSync(entry.manifestPath, "utf-8"))) as { status?: unknown; updatedAt?: string; async?: { pid?: number } };
 			if (manifest.status !== "queued" && manifest.status !== "planning" && manifest.status !== "running" && manifest.status !== "blocked") continue;
 			// PID liveness check: async runs with dead PID are stale — don't surface them
 			if (manifest.async?.pid) {

package/src/state/artifact-store.ts

@@ -52,7 +52,7 @@ function shouldCleanup(artifactsRoot: string, markerFile: string, scanGraceMs: n
 
 export function writeCleanupMarker(artifactsRoot: string, markerFile: string): void {
 	fs.mkdirSync(artifactsRoot, { recursive: true });
-	fs.writeFileSync(path.join(artifactsRoot, markerFile), String(nowMs()), "utf-8");
+	atomicWriteFile(path.join(artifactsRoot, markerFile), String(nowMs()));
 }
 
 export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactCleanupOptions): void {
@@ -97,31 +97,43 @@ export function cleanupOldArtifacts(artifactsRoot: string, options: ArtifactClea
 }
 
 function resolveInside(baseDir: string, relativePath: string): string {
+	// Check if baseDir is a symlink on every call to prevent symlink attacks
+	try {
+		if (fs.lstatSync(baseDir).isSymbolicLink()) throw new Error(`Artifacts root is a symbolic link — not allowed: ${baseDir}`);
+	} catch (err) {
+		// If lstatSync fails because baseDir doesn't exist yet, that's fine —
+		// it will be created by writeArtifact. Any other error should propagate.
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+	}
+
 	const normalizedRelativePath = relativePath.replaceAll("\\", "/").replace(/^\.\/+/, "");
 	if (!normalizedRelativePath || normalizedRelativePath.split("/").some((segment) => segment === "..") || path.isAbsolute(normalizedRelativePath)) {
 		throw new Error(`Invalid artifact path: ${relativePath}`);
 	}
-	const base = path.resolve(baseDir);
-	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}`);
-	// 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;
+	// Use resolveRealContainedPath to resolve symlinks before checking containment,
+	// preventing TOCTOU attacks where intermediate directories are replaced with symlinks.
+	return resolveRealContainedPath(baseDir, normalizedRelativePath);
 }
 
 export function writeArtifact(artifactsRoot: string, options: ArtifactWriteOptions): ArtifactDescriptor {
-	const filePath = resolveInside(artifactsRoot, options.relativePath);
+	// FIX: Create the artifactsRoot BEFORE calling resolveInside/resolveRealContainedPath,
+	// which open() the path to validate symlinks (fails with ENOENT if not yet created).
+	// Also reject symlinks in baseDir at this point (catches both pre-existing symlinks
+	// and the case where baseDir was created by mkdirSync as a regular dir).
 	fs.mkdirSync(artifactsRoot, { recursive: true });
-	if (fs.lstatSync(artifactsRoot).isSymbolicLink()) throw new Error(`Artifacts root is a symbolic link — not allowed: ${artifactsRoot}`);
-	resolveRealContainedPath(path.dirname(artifactsRoot), path.basename(artifactsRoot));
+	if (fs.lstatSync(artifactsRoot).isSymbolicLink()) {
+		throw new Error(`Artifacts root is a symbolic link — not allowed: ${artifactsRoot}`);
+	}
+	const filePath = resolveInside(artifactsRoot, options.relativePath);
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	resolveRealContainedPath(artifactsRoot, path.dirname(filePath));
 	const content = redactSecretString(options.content);
 	atomicWriteFile(filePath, content);
 	// Compute hash on written bytes for integrity verification.
-	const contentHash = hashContent(content);
+	// Read back the actual file content to handle atomicWrite fallback path
+	// where the written content might differ from the input (e.g., concurrent writes).
+	const writtenContent = fs.readFileSync(filePath, "utf-8");
+	const contentHash = hashContent(writtenContent);
 	const stats = fs.statSync(filePath);
 	return {
 		kind: options.kind,

package/src/state/atomic-write-v2.ts

@@ -0,0 +1,86 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Fallow-inspired atomic writer: write-to-.tmp → fsync → rename.
+ *
+ * Key differences from atomic-write.ts:
+ * - Uses rename() (POSIX-atomic) instead of link()+unlink()
+ * - Calls fsyncSync() on the temp file before rename
+ * - Best-effort fsync (failure does not abort)
+ * - Writes .gitignore to directory on first use
+ * - UUID-based tmp file to prevent collisions under concurrent writes
+ */
+export class AtomicWriter {
+  private initializedDirs = new Set<string>();
+  private baseDir: string;
+
+  constructor(baseDir: string) {
+    this.baseDir = baseDir;
+  }
+
+  writeSync(targetPath: string, content: string): void {
+    this.ensureParentDir(targetPath);
+    const tmpPath = this.tmpPath(targetPath);
+    const fd = fs.openSync(tmpPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    try {
+      fs.writeSync(fd, content, undefined, "utf8");
+      try { fs.fsyncSync(fd); } catch { /* best-effort */ }
+    } finally {
+      fs.closeSync(fd);
+    }
+    try {
+      fs.renameSync(tmpPath, targetPath);
+    } catch (err) {
+      try { fs.unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
+      throw err;
+    }
+  }
+
+  async writeAsync(targetPath: string, content: string): Promise<void> {
+    await fs.promises.mkdir(path.dirname(targetPath), { recursive: true });
+    const tmpPath = this.tmpPath(targetPath);
+    const fd = await fs.promises.open(tmpPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    try {
+      await fd.writeFile(content, "utf8");
+      try { await fd.sync(); } catch { /* best-effort */ }
+    } finally {
+      await fd.close();
+    }
+    try {
+      await fs.promises.rename(tmpPath, targetPath);
+    } catch (err) {
+      try { await fs.promises.unlink(tmpPath); } catch { /* best-effort cleanup */ }
+      throw err;
+    }
+  }
+
+  writeJsonSync<T>(targetPath: string, value: T): void {
+    this.writeSync(targetPath, JSON.stringify(value, null, 2) + "\n");
+  }
+
+  async writeJsonAsync<T>(targetPath: string, value: T): Promise<void> {
+    await this.writeAsync(targetPath, JSON.stringify(value, null, 2) + "\n");
+  }
+
+  private tmpPath(targetPath: string): string {
+    const uuid = crypto.randomUUID();
+    return `${targetPath}.${uuid}.tmp`;
+  }
+
+  private ensureParentDir(targetPath: string): void {
+    const dir = path.dirname(targetPath);
+    fs.mkdirSync(dir, { recursive: true });
+    this.ensureGitignore(dir);
+  }
+
+  private ensureGitignore(dir: string): void {
+    if (this.initializedDirs.has(dir)) return;
+    this.initializedDirs.add(dir);
+    const gitignorePath = path.join(dir, ".gitignore");
+    try { fs.accessSync(gitignorePath); } catch {
+      try { fs.writeFileSync(gitignorePath, "*\n", "utf8"); } catch { /* best-effort */ }
+    }
+  }
+}