@llblab/pi-kit 0.10.7 → 0.11.0

package/node_modules/@llblab/pi-state-flow/lib/git.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, relative, resolve, sep } from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import {
 	assertOwnedFileUpdates,
 	captureOwnedFileBases,
@@ -52,12 +52,13 @@ export interface GitPushResult {
 function git(
 	repositoryRoot: string,
 	args: readonly string[],
-	options: { allowFailure?: boolean; env?: NodeJS.ProcessEnv; input?: string } = {},
+	options: { allowFailure?: boolean; env?: NodeJS.ProcessEnv; input?: string; maxBuffer?: number } = {},
 ): GitResult {
 	const result = spawnSync("git", ["-C", repositoryRoot, ...args], {
 		encoding: "utf8",
 		timeout: GIT_TIMEOUT_MS,
 		input: options.input,
+		...(options.maxBuffer === undefined ? {} : { maxBuffer: options.maxBuffer }),
 		env: {
 			...process.env,
 			GIT_TERMINAL_PROMPT: "0",
@@ -142,26 +143,51 @@ function currentBranchRef(repositoryRoot: string): string {
 	return result.stdout.trim();
 }
 
-function revisionFile(
-	repositoryRoot: string,
-	revision: string,
-	path: string,
-): DurableFileBase {
-	const relativePath = relativeOwnedPath(path, repositoryRoot);
-	const object = `${revision}:${relativePath}`;
-	const entry = git(repositoryRoot, ["ls-tree", "-z", revision, "--", relativePath]).stdout;
-	if (entry.length === 0) return { path, identity: "missing" };
-	if (!/^100(?:644|755) blob [0-9a-f]+\t/.test(entry)) {
-		throw new Error(`Historical State Flow file is not a regular blob: ${path}`);
+/** One exact-path tree query per immutable revision; inspect only blobs the caller actually selects. */
+function revisionFileReader(repositoryRoot: string, revision: string, paths: readonly string[]): (path: string) => DurableFileBase {
+	const relativePaths = new Map(paths.map((path) => [path, relativeOwnedPath(path, repositoryRoot)]));
+	if (relativePaths.size === 0) throw new Error("Git revision reader requires owned paths");
+	const selected = new Set(relativePaths.values());
+	const listing = git(repositoryRoot, ["ls-tree", "-z", revision, "--", ...selected], { env: {
+		GIT_LITERAL_PATHSPECS: "1", GIT_GLOB_PATHSPECS: "0", GIT_NOGLOB_PATHSPECS: "0", GIT_ICASE_PATHSPECS: "0",
+	} }).stdout;
+	if (listing.length > 0 && !listing.endsWith("\0")) throw new Error("Historical Git tree listing is incomplete");
+	const entries = new Map<string, string | null>();
+	for (const entry of listing.split("\0").filter(Boolean)) {
+		const separator = entry.indexOf("\t");
+		if (separator < 0) throw new Error("Historical Git tree listing is malformed");
+		const path = entry.slice(separator + 1);
+		if (!selected.has(path)) continue;
+		entries.set(path, entries.has(path) ? null : entry.slice(0, separator));
 	}
-	const content = git(repositoryRoot, ["show", object]).stdout;
-	return {
-		path,
-		identity: `sha256:${createHash("sha256").update(content).digest("hex")}`,
-		content,
+	const files = new Map<string, DurableFileBase>();
+	return (path) => {
+		const relativePath = relativePaths.get(path);
+		if (relativePath === undefined) throw new Error(`Git revision reader did not select path: ${path}`);
+		const cached = files.get(path);
+		if (cached) return cached;
+		const entry = entries.get(relativePath);
+		if (entry === null) throw new Error(`Historical Git tree has duplicate path: ${relativePath}`);
+		if (entry === undefined) {
+			const missing: DurableFileBase = { path, identity: "missing" };
+			files.set(path, missing);
+			return missing;
+		}
+		if (!/^100(?:644|755) blob [0-9a-f]+$/.test(entry)) {
+			throw new Error(`Historical State Flow file is not a regular blob: ${path}`);
+		}
+		// Selected state/runtime blobs have no semantic byte cap; Node's default pipe budget is only 1 MiB.
+		const content = git(repositoryRoot, ["show", `${revision}:${relativePath}`], { maxBuffer: Infinity }).stdout;
+		const file: DurableFileBase = { path, identity: `sha256:${createHash("sha256").update(content).digest("hex")}`, content };
+		files.set(path, file);
+		return file;
 	};
 }
 
+function revisionFile(repositoryRoot: string, revision: string, path: string): DurableFileBase {
+	return revisionFileReader(repositoryRoot, revision, [path])(path);
+}
+
 function assertReadableRevision(root: string, revision: string): void {
 	if (!/^[0-9a-f]{40,64}$/.test(revision)
 		|| git(root, ["cat-file", "-e", `${revision}^{commit}`], { allowFailure: true }).status !== 0) {
@@ -192,29 +218,41 @@ function captureTemporalBaseUnderLock(cwd: string, sessionId: string, root: stri
 	return { head: currentHead(root), files: captureTemporalFileBases(cwd, sessionId, root, sessionKey) };
 }
 
-function revisionScopeFiles(root: string, revision: string, cwd: string, sessionId: string, sessionKey: string, scope: StateScope) {
-	const read = (paths: ReturnType<typeof temporalScopePaths>) => ({
+function revisionScopeFiles(read: (path: string) => DurableFileBase, paths: ReturnType<typeof temporalScopePaths>) {
+	return {
 		paths,
-		checkpoint: revisionFile(root, revision, paths.checkpoint),
-		patches: revisionFile(root, revision, paths.patches),
-		legacy: revisionFile(root, revision, resolve(paths.directory, "state.json")),
-		meta: revisionFile(root, revision, paths.meta),
-	});
-	const canonical = read(temporalScopePaths(cwd, sessionId, scope, root, sessionKey));
-	if (scope === "global" || [canonical.checkpoint, canonical.patches, canonical.legacy].some(({ identity }) => identity !== "missing")) return { ...canonical, legacyLayout: false };
-	return { ...read(legacyTemporalScopePaths(cwd, sessionId, scope, root)), legacyLayout: true };
+		checkpoint: read(paths.checkpoint),
+		patches: read(paths.patches),
+		legacy: read(resolve(paths.directory, "state.json")),
+		meta: read(paths.meta),
+	};
 }
 
 /** Cold scope-stream reconstruction; pre-0.4 hashed paths remain read-only revision input. */
 export function loadTemporalRevision(cwd: string, sessionId: string, repositoryRoot: string, revision: string, sessionKey = sessionId): TemporalRevisionLoad {
 	const root = assertRepositoryRoot(repositoryRoot);
 	assertReadableRevision(root, revision);
+	const scopePaths = (["global", "cwd", "session"] as const).map((scope) => ({
+		scope,
+		canonical: temporalScopePaths(cwd, sessionId, scope, root, sessionKey),
+		legacy: scope === "global" ? undefined : legacyTemporalScopePaths(cwd, sessionId, scope, root),
+	}));
+	const canonicalRuntime = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
+	const legacyRuntime = legacySessionRuntimePaths(cwd, sessionId, root);
+	const readFile = revisionFileReader(root, revision, [
+		...scopePaths.flatMap(({ canonical, legacy }) => legacy ? [canonical, legacy] : [canonical])
+			.flatMap((paths) => [paths.checkpoint, paths.patches, resolve(paths.directory, "state.json"), paths.meta]),
+		canonicalRuntime.config, canonicalRuntime.meta, legacyRuntime.config, legacyRuntime.meta,
+	]);
 	const files: DurableFileBase[] = [];
 	const scopes = {} as Record<StateScope, ScopeStream | undefined>;
 	const provenance: Record<StateScope, ArtifactProvenanceRegistry> = { global: {}, cwd: {}, session: {} };
 	let legacyLayout = false;
-	for (const scope of ["global", "cwd", "session"] as const) {
-		const selected = revisionScopeFiles(root, revision, cwd, sessionId, sessionKey, scope);
+	for (const { scope, canonical, legacy } of scopePaths) {
+		let selected = { ...revisionScopeFiles(readFile, canonical), legacyLayout: false };
+		if (legacy && [selected.checkpoint, selected.patches, selected.legacy].every(({ identity }) => identity === "missing")) {
+			selected = { ...revisionScopeFiles(readFile, legacy), legacyLayout: true };
+		}
 		if (selected.legacy.identity !== "missing") throw new Error("Historical legacy storage requires explicit migration interpretation");
 		legacyLayout ||= selected.legacyLayout;
 		files.push(selected.checkpoint, selected.patches, selected.legacy, ...(scope === "session" ? [] : [selected.meta]));
@@ -223,11 +261,11 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 			scope === "cwd" && !selected.legacyLayout ? cwd : undefined);
 	}
 	const readRuntime = (paths: ReturnType<typeof sessionRuntimePaths>) => ({
-		paths, config: revisionFile(root, revision, paths.config), meta: revisionFile(root, revision, paths.meta),
+		paths, config: readFile(paths.config), meta: readFile(paths.meta),
 	});
-	let selectedRuntime = { ...readRuntime(sessionRuntimePaths(cwd, sessionId, root, sessionKey)), legacyLayout: false };
+	let selectedRuntime = { ...readRuntime(canonicalRuntime), legacyLayout: false };
 	if (selectedRuntime.config.identity === "missing" && selectedRuntime.meta.identity === "missing") {
-		selectedRuntime = { ...readRuntime(legacySessionRuntimePaths(cwd, sessionId, root)), legacyLayout: true };
+		selectedRuntime = { ...readRuntime(legacyRuntime), legacyLayout: true };
 	}
 	legacyLayout ||= selectedRuntime.legacyLayout;
 	const { paths: runtimePaths, config, meta } = selectedRuntime;
@@ -247,6 +285,7 @@ export function loadTemporalRevision(cwd: string, sessionId: string, repositoryR
 		}
 		const selected = loadTemporalRevision(cwd, sessionId, root, temporalRevision, sessionKey);
 		Object.assign(scopes, selected.scopes);
+		Object.assign(provenance, selected.provenance);
 	}
 	if (scopes.global === undefined || scopes.cwd === undefined || scopes.session === undefined) {
 		throw new Error("Session runtime has incomplete temporal scope storage");
@@ -430,6 +469,7 @@ function commitOwnedFiles(
 		// and manual deletions, while `.gitignore` stays authoritative for untracked files. The
 		// transient publication lock is ours, not repository content.
 		git(repositoryRoot, ["add", "-A", "--", ".", ":(exclude).state-flow-publication.lock"], { env });
+		const entries: string[] = [];
 		for (const update of updates) {
 			const relativePath = relativeOwnedPath(update.path, repositoryRoot);
 			if (update.content === undefined) {
@@ -437,8 +477,10 @@ function commitOwnedFiles(
 				continue;
 			}
 			const blob = git(repositoryRoot, ["hash-object", "-w", "--stdin"], { input: update.content }).stdout.trim();
-			git(repositoryRoot, ["update-index", "--add", "--cacheinfo", `100644,${blob},${relativePath}`], { env });
+			entries.push(`100644 ${blob}\t${relativePath}\0`);
 		}
+		// NUL framing preserves literal path characters while the blobs retain exact prepared bytes.
+		if (entries.length > 0) git(repositoryRoot, ["update-index", "-z", "--index-info"], { env, input: entries.join("") });
 		const tree = git(repositoryRoot, ["write-tree"], { env }).stdout.trim();
 		if (expectedHead !== undefined) {
 			const previousTree = git(repositoryRoot, ["rev-parse", `${expectedHead}^{tree}`]).stdout.trim();
@@ -559,20 +601,22 @@ function includeUncommittedCohort(cwd: string, sessionId: string, root: string,
 	updates: OwnedFileUpdate[], changedScopes: StateScope[], scopes: readonly StateScope[], runtime: boolean, sessionKey = sessionId): void {
 	const targets = new Map(updates.map((update) => [update.path, update]));
 	const desired = (paths: string[]) => paths.map((path) => targets.get(path) ?? { path, content: current.files.find((file) => file.path === path)!.content });
-	const absentFromHead = (files: OwnedFileUpdate[]) => files.some(({ path, content }) => current.head === undefined || revisionFile(root, current.head, path).content !== content);
-	for (const scope of ["global", "cwd", "session"] as const) {
+	const pairs = (["global", "cwd", "session"] as const).map((scope) => {
 		const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
-		const pair = desired([paths.checkpoint, paths.patches]);
+		return { scope, pair: desired([paths.checkpoint, paths.patches]) };
+	});
+	const runtimePaths = runtime ? sessionRuntimePaths(cwd, sessionId, root, sessionKey) : undefined;
+	const runtimePair = runtimePaths ? desired([runtimePaths.config, runtimePaths.meta]) : [];
+	const readFile = current.head === undefined ? undefined : revisionFileReader(root, current.head,
+		[...pairs.flatMap(({ pair }) => pair), ...runtimePair].map(({ path }) => path));
+	const absentFromHead = (files: OwnedFileUpdate[]) => files.some(({ path, content }) => readFile === undefined || readFile(path).content !== content);
+	for (const { scope, pair } of pairs) {
 		if (!absentFromHead(pair)) continue;
 		if (!scopes.includes(scope)) throw new Error(`Temporal scope update omitted an uncommitted stream: ${scope}`);
 		for (const update of pair) targets.set(update.path, update);
 		if (!changedScopes.includes(scope)) changedScopes.push(scope);
 	}
-	if (runtime) {
-		const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-		const pair = desired([paths.config, paths.meta]);
-		if (absentFromHead(pair)) for (const update of pair) targets.set(update.path, update);
-	}
+	if (absentFromHead(runtimePair)) for (const update of runtimePair) targets.set(update.path, update);
 	updates.splice(0, updates.length, ...targets.values());
 }
 
@@ -657,6 +701,62 @@ export function isGitCommitAncestor(repositoryRoot: string, ancestor: string, de
 	throw new Error(`Cannot inspect Git commit ancestry: ${result.stderr || `exit ${result.status}`}`);
 }
 
+/** Own one non-interactive exact-target push; cancellation is not confirmation of child exit. */
+export function pushGitTarget(
+	repositoryRoot: string,
+	destination: { remote: string; ref: string },
+	commit: string,
+	signal?: AbortSignal,
+): Promise<void> {
+	if (typeof commit !== "string" || !/^[0-9a-f]{40,64}$/.test(commit)) return Promise.reject(new Error("Git push target must be an exact commit"));
+	if (signal?.aborted) return Promise.reject(new Error("Git push aborted"));
+	return new Promise<void>((resolve, reject) => {
+		const child = spawn("git", ["-C", repositoryRoot, "push", "--", destination.remote, `${commit}:${destination.ref}`], {
+			detached: process.platform !== "win32", // Own the POSIX group, not a detached daemon; retain the child handle.
+			stdio: ["ignore", "ignore", "pipe"],
+			windowsHide: true,
+			env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" },
+		});
+		let stderr = "";
+		let failure: Error | undefined;
+		let settled = false;
+		function terminate(error: Error): void {
+			failure ??= error;
+			if (child.exitCode !== null || child.signalCode !== null) {
+				child.stderr?.destroy(); // Do not wait indefinitely for an outliving helper's inherited pipe.
+				return;
+			}
+			if (!child.pid) return;
+			try {
+				if (process.platform === "win32") child.kill("SIGKILL");
+				else process.kill(-child.pid, "SIGKILL");
+			} catch {
+				// No exit proof: keep the promise and caller's lease outstanding, even if signalling fails.
+			}
+		}
+		const abort = () => terminate(new Error("Git push aborted"));
+		const timeout = setTimeout(() => terminate(new Error(`Git push timed out after ${GIT_TIMEOUT_MS}ms`)), GIT_TIMEOUT_MS);
+		function finish(error?: Error): void {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timeout);
+			signal?.removeEventListener("abort", abort);
+			if (error) reject(error);
+			else resolve();
+		}
+		child.stderr?.on("data", (chunk: Buffer) => { stderr = (stderr + chunk.toString("utf8")).slice(-1000); });
+		child.on("error", (error) => {
+			failure ??= error;
+			if (!child.pid) finish(error); // Spawn failure owns no live process; kill errors do not prove exit.
+		});
+		child.once("exit", () => { if (failure) child.stderr?.destroy(); });
+		child.once("close", (code, endedBy) => finish(failure ?? (code === 0 ? undefined
+			: new Error(`Git push failed (${endedBy ?? code}): ${stderr.trim() || "no diagnostic output"}`))));
+		signal?.addEventListener("abort", abort, { once: true });
+		if (signal?.aborted) abort();
+	});
+}
+
 export function pushGitCommit(repositoryRoot: string, commit: string): GitPushResult {
 	try {
 		const root = assertRepositoryRoot(repositoryRoot);

package/node_modules/@llblab/pi-state-flow/lib/publication.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, parse, resolve, sep } from "node:path";
 
 
@@ -62,7 +62,9 @@ export function remotePublicationDestinationKey(destination: RemotePublicationDe
 	return JSON.stringify([resolve(destination.gitCommonDir), destination.remote, destination.ref]);
 }
 
-const COMMIT = /^[0-9a-f]{40,64}$/;
+function isCommit(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{40,64}$/.test(value);
+}
 export type PublicationQueueStatus = "pending" | "pushing" | "failed";
 export interface PublicationQueueState {
 	version: 1;
@@ -76,7 +78,7 @@ export interface PublicationQueueState {
 export type CommitAncestor = (ancestor: string, descendant: string) => boolean;
 
 export function createPublicationQueue(destination: RemotePublicationDestination, target: string): PublicationQueueState {
-	if (!COMMIT.test(target)) throw new Error("Publication queue target must be an exact commit");
+	if (!isCommit(target)) throw new Error("Publication queue target must be an exact commit");
 	remotePublicationDestinationKey(destination);
 	return { version: 1, destination: structuredClone(destination), target, status: "pending", attempt: 0 };
 }
@@ -88,7 +90,7 @@ export interface PublicationCoalesceObserver {
 
 export function coalescePublicationTarget(state: PublicationQueueState, destination: RemotePublicationDestination, target: string, isAncestor: CommitAncestor, observer?: PublicationCoalesceObserver): PublicationQueueState {
 	validatePublicationQueue(state);
-	if (!COMMIT.test(target)) throw new Error("Publication queue target must be an exact commit");
+	if (!isCommit(target)) throw new Error("Publication queue target must be an exact commit");
 	if (remotePublicationDestinationKey(state.destination) !== remotePublicationDestinationKey(destination)) throw new Error("Publication queue destination changed");
 	if (target === state.target || isAncestor(target, state.target)) return structuredClone(state);
 	const previous = structuredClone(state);
@@ -129,7 +131,7 @@ export function failPublicationAttempt(state: PublicationQueueState, error: stri
 
 export function confirmPublicationTarget(state: PublicationQueueState, pushed: string, isAncestor: CommitAncestor): PublicationQueueState | undefined {
 	validatePublicationQueue(state);
-	if (!COMMIT.test(pushed)) throw new Error("Confirmed publication target must be an exact commit");
+	if (!isCommit(pushed)) throw new Error("Confirmed publication target must be an exact commit");
 	if (pushed === state.target) return undefined;
 	if (!isAncestor(pushed, state.target)) throw new Error("Publication confirmation does not cover the queued lineage");
 	return { ...structuredClone(state), confirmed: pushed, status: "pending", error: undefined };
@@ -146,11 +148,11 @@ export function recoverPublicationQueue(state: PublicationQueueState): Publicati
 export function validatePublicationQueue(value: unknown): asserts value is PublicationQueueState {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Invalid publication queue document");
 	const v = value as Record<string, unknown>;
-	if (v.version !== 1 || !COMMIT.test(String(v.target)) || !Number.isSafeInteger(v.attempt) || (v.attempt as number) < 0
+	if (v.version !== 1 || !isCommit(v.target) || !Number.isSafeInteger(v.attempt) || (v.attempt as number) < 0
 		|| (v.status !== "pending" && v.status !== "pushing" && v.status !== "failed")
 		|| typeof v.destination !== "object" || v.destination === null) throw new Error("Invalid publication queue document");
 	remotePublicationDestinationKey(v.destination as unknown as RemotePublicationDestination);
-	if (v.confirmed !== undefined && !COMMIT.test(String(v.confirmed))) throw new Error("Invalid publication queue document");
+	if (v.confirmed !== undefined && !isCommit(v.confirmed)) throw new Error("Invalid publication queue document");
 	if (v.error !== undefined && (typeof v.error !== "string" || !v.error.trim())) throw new Error("Invalid publication queue document");
 	const allowed = new Set(["version", "destination", "target", "confirmed", "status", "attempt", "error"]);
 	if (Object.keys(v).some((key) => !allowed.has(key))) throw new Error("Invalid publication queue document");
@@ -181,6 +183,43 @@ export interface PublicationWorkerLease {
 	release(): void;
 }
 
+interface WorkerLeaseDocument {
+	version: 1;
+	pid: number;
+	token: string;
+	startedAt: string;
+}
+
+function readWorkerLease(path: string): WorkerLeaseDocument | undefined {
+	assertNoSymlinkAncestors(dirname(path));
+	const stat = lstatSync(path, { throwIfNoEntry: false });
+	if (!stat) return undefined;
+	if (!stat.isFile()) throw new Error("Publication worker lease path must be a regular file");
+	let descriptor: number;
+	try { descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; // A live owner may have released it.
+		throw error;
+	}
+	try {
+		if (!fstatSync(descriptor).isFile()) throw new Error("Publication worker lease path must be a regular file");
+		const source = readFileSync(descriptor, "utf8");
+		let value: unknown;
+		try { value = JSON.parse(source); } catch { throw new Error("Publication worker lease is malformed"); }
+		if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("Publication worker lease is malformed");
+		const record = value as Record<string, unknown>;
+		if (Object.keys(record).sort().join(",") !== "pid,startedAt,token,version" || record.version !== 1
+			|| !Number.isSafeInteger(record.pid) || (record.pid as number) <= 0 || (record.pid as number) > 2147483647
+			|| typeof record.token !== "string" || !record.token.trim() || record.token !== record.token.trim()
+			|| typeof record.startedAt !== "string" || !Number.isFinite(Date.parse(record.startedAt))) {
+			throw new Error("Publication worker lease is malformed");
+		}
+		return record as unknown as WorkerLeaseDocument;
+	} finally {
+		closeSync(descriptor);
+	}
+}
+
 function processAlive(pid: number): boolean {
 	try { process.kill(pid, 0); return true; }
 	catch (error) { return (error as NodeJS.ErrnoException).code !== "ESRCH"; }
@@ -191,28 +230,42 @@ export function acquirePublicationWorkerLease(queuePath: string): PublicationWor
 	assertNoSymlinkAncestors(dirname(path));
 	const token = randomUUID();
 	const document = `${JSON.stringify({ version: 1, pid: process.pid, token, startedAt: new Date().toISOString() })}\n`;
-	for (let attempt = 0; attempt < 2; attempt++) {
-		try {
-			writeFileSync(path, document, { flag: "wx", mode: 0o600 });
-			return {
-				path, token,
-				release() {
-					let current: unknown;
-					try { current = JSON.parse(readFileSync(path, "utf8")); } catch { return; }
-					if (typeof current === "object" && current !== null && (current as { token?: unknown }).token === token) rmSync(path, { force: true });
-				},
-			};
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-			let current: unknown;
-			try { current = JSON.parse(readFileSync(path, "utf8")); } catch { throw new Error("Publication worker lease is malformed"); }
-			const pid = typeof current === "object" && current !== null ? (current as { pid?: unknown }).pid : undefined;
-			if (!Number.isSafeInteger(pid) || (pid as number) <= 0) throw new Error("Publication worker lease is malformed");
-			if (processAlive(pid as number)) return undefined;
-			rmSync(path, { force: true });
+	const create = (): PublicationWorkerLease | undefined => {
+		try { writeFileSync(path, document, { flag: "wx", mode: 0o600 }); }
+		catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "EEXIST") return undefined;
+			throw error;
 		}
+		return { path, token, release() {
+			let current: WorkerLeaseDocument | undefined;
+			try { current = readWorkerLease(path); } catch { return; }
+			// A live owner cannot be reclaimed, so release need not wait for queue writers.
+			if (current?.pid === process.pid && current.token === token) rmSync(path, { force: true });
+		} };
+	};
+	const lease = create();
+	if (lease) return lease;
+	const current = readWorkerLease(path);
+	if (!current) return create();
+	if (processAlive(current.pid)) return undefined;
+	// Only reclamation needs the existing queue writer gate; exclusive creation protects fresh claims.
+	const gate = `${resolve(queuePath)}.lock`;
+	assertNoSymlinkAncestors(dirname(gate));
+	let descriptor: number;
+	try { descriptor = openSync(gate, "wx", 0o600); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") return undefined;
+		throw error;
+	}
+	try {
+		const owner = readWorkerLease(path);
+		if (owner && processAlive(owner.pid)) return undefined;
+		if (owner) rmSync(path, { force: true });
+		return create(); // A fresh claimant may win the gap; never remove its replacement.
+	} finally {
+		closeSync(descriptor);
+		rmSync(gate, { force: true });
 	}
-	return undefined;
 }
 
 export function loadPublicationQueue(path: string): PublicationQueueState | undefined {

package/node_modules/@llblab/pi-state-flow/lib/runtime.ts

@@ -16,6 +16,12 @@ const SCOPES = ["global", "cwd", "session"] as const;
 const SHARED_SCOPES = ["global", "cwd"] as const;
 export type RuntimePublication = ReturnType<typeof publishTemporalStateToGit> & { revision?: string };
 
+interface SessionCopy {
+	stream: ScopeStream;
+	provenance: ArtifactProvenanceRegistry;
+	backend: "git" | "files";
+}
+
 function emptyProvenance(): Record<StateScope, ArtifactProvenanceRegistry> {
 	return { global: {}, cwd: {}, session: {} };
 }
@@ -33,10 +39,14 @@ function targetScopeConflict(scopes: readonly StateScope[]): Error {
 	return new Error(`State Flow cannot publish the ${labels.join(" and ")} patches because the live ${labels.join(" and ")} states advanced after this transition's selected basis. Refresh or reconcile the target scopes before retrying.`);
 }
 
+export class MissingSessionRuntimeError extends Error {
+	constructor() { super("Linked State Flow revision has no session runtime"); }
+}
+
 /** Immutable target validation is independent of acquiring the live publication basis. */
 export function inspectRuntimeRevision(cwd: string, sessionId: string, root: string, revision: string, sessionKey = sessionId) {
 	const loaded = loadTemporalRevision(cwd, sessionId, root, revision, sessionKey);
-	if (!loaded.runtime) throw new Error("Linked State Flow revision has no session runtime");
+	if (!loaded.runtime) throw new MissingSessionRuntimeError();
 	const resolved = resolveSessionRuntime(loaded.runtime.document, loaded.runtime.revision);
 	if (!loaded.scopes.global || !loaded.scopes.cwd || !loaded.scopes.session) throw new Error("Incomplete temporal scope cohort");
 	const view = { lineage: resolved.lineage, scopes: { global: loaded.scopes.global, cwd: loaded.scopes.cwd, session: loaded.scopes.session } };
@@ -138,8 +148,66 @@ export class TemporalRuntime {
 		return result;
 	}
 
-	restore(revision: string, legacySnapshot?: Snapshot): Snapshot {
+	/** Validate selection without installing state; only a matching immutable Git inspection is reusable. */
+	prepareRestore(revision: string, legacySnapshot?: Snapshot): { snapshot: Snapshot; restore: () => Snapshot } {
 		const inspected = inspectSnapshotRevision(this.cwd, this.sessionId, this.root, revision, legacySnapshot, this.sessionKey);
+		const selected = inspected.snapshot.meta.durableBase ?? revision;
+		let consumed = false;
+		return {
+			snapshot: structuredClone(inspected.snapshot),
+			restore: () => {
+				if (consumed) throw new Error("Prepared State Flow restore was already consumed");
+				consumed = true;
+				// File cohorts can expire; legacy migration and owner redirection keep their fresh-read path.
+				return inspected.temporal && selected === revision
+					? this.restoreInspected(revision, inspected)
+					: this.restore(selected, inspected.snapshot);
+			},
+		};
+	}
+
+	/** Copy only a proven source session stream; shared streams come from the child's fresh live basis. */
+	prepareFork(source: SessionAddress, revision: string): { snapshot: Snapshot; fork: () => { snapshot: Snapshot; publication: RuntimePublication } } {
+		const parent = Object.freeze({ ...source });
+		if (parent.id === this.sessionId || parent.key === this.sessionKey) throw new Error("State Flow fork requires a distinct session identity and key");
+		const inspect = () => inspectSnapshotRevision(this.cwd, parent.id, this.root, revision, undefined, parent.key);
+		const inspected = inspect();
+		const snapshot: Snapshot = {
+			config: structuredClone(inspected.snapshot.config),
+			meta: {
+				step: 0,
+				...(inspected.snapshot.meta.bootstrap === undefined ? {} : { bootstrap: inspected.snapshot.meta.bootstrap }),
+				...(inspected.snapshot.meta.remotePublication === undefined ? {} : { remotePublication: structuredClone(inspected.snapshot.meta.remotePublication) }),
+			},
+		};
+		let consumed = false;
+		return {
+			snapshot: { ...structuredClone(snapshot), meta: { ...structuredClone(snapshot.meta), durableBase: revision } },
+			fork: () => {
+				if (consumed) throw new Error("Prepared State Flow fork was already consumed");
+				consumed = true;
+				if (this.view) throw new Error("State Flow fork target already has session storage");
+				// Unlike immutable Git input, a file-only source must still match its complete cohort.
+				const current = inspected.file ? inspect() : inspected;
+				const selected = current.temporal ?? current.file;
+				if (!selected) throw new Error("State Flow fork requires a temporal session stream");
+				const publication = this.initializeOrigin(snapshot, { allowCreateCwd: false, copy: {
+					stream: selected.view.scopes.session,
+					provenance: selected.provenance.session,
+					backend: current.file ? "files" : "git",
+				} });
+				const ownedRevision = publication?.revision ?? publication?.commit;
+				if (!publication || !ownedRevision) throw new Error("State Flow fork requires existing shared scope storage");
+				return { snapshot: { ...structuredClone(snapshot), meta: { ...structuredClone(snapshot.meta), durableBase: ownedRevision } }, publication };
+			},
+		};
+	}
+
+	restore(revision: string, legacySnapshot?: Snapshot): Snapshot {
+		return this.restoreInspected(revision, inspectSnapshotRevision(this.cwd, this.sessionId, this.root, revision, legacySnapshot, this.sessionKey));
+	}
+
+	private restoreInspected(revision: string, inspected: ReturnType<typeof inspectSnapshotRevision>): Snapshot {
 		if (inspected.file) {
 			const savedRuntime = hashJson(createSessionRuntime(inspected.snapshot, this.cwd, this.sessionId, inspected.file.view.lineage, "files", inspected.file.provenance.session));
 			this.view = inspected.file.view;
@@ -205,16 +273,26 @@ export class TemporalRuntime {
 	}
 
 	initialize(snapshot: Snapshot, allowCreateCwd: boolean, expectedShared?: Pick<ScopedStates, "global" | "cwd">, newSessionOrigin = false): RuntimePublication | undefined {
+		return this.initializeOrigin(snapshot, { allowCreateCwd, expectedShared, newSessionOrigin });
+	}
+
+	private initializeOrigin(snapshot: Snapshot, options: {
+		allowCreateCwd: boolean;
+		expectedShared?: Pick<ScopedStates, "global" | "cwd">;
+		newSessionOrigin?: boolean;
+		copy?: SessionCopy;
+	}): RuntimePublication | undefined {
+		const { allowCreateCwd, expectedShared, newSessionOrigin = false, copy } = options;
 		const hasCwd = hasCwdMaterialization(this.cwd, this.root);
 		if (!allowCreateCwd && !hasCwd) return undefined;
-		const backend = this.backend ?? (detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files");
-		if (backend === "git") {
+		const backend = copy?.backend ?? this.backend ?? (detectGitCapability() === "git" && lstatSync(join(this.root, ".git"), { throwIfNoEntry: false }) ? "git" : "files");
+		if (!copy && backend === "git") {
 			if (!hasCwd) migrateHashedCwdAtHead(this.cwd, this.root);
 			if (hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) {
 				migrateLegacyStorageToGit(this.cwd, this.sessionId, this.root, this.sessionKey);
 			}
 		}
-		else {
+		else if (!copy) {
 			if (allowCreateCwd) initializeFileStore(this.root);
 			if (hasLegacyStateSources(this.cwd, this.sessionId, this.root, this.sessionKey)) {
 				migrateLegacyStorageToFiles(this.cwd, this.sessionId, this.root, this.sessionKey);
@@ -222,6 +300,15 @@ export class TemporalRuntime {
 		}
 		const base: TemporalGitBase = backend === "git" ? captureTemporalGitBase(this.cwd, this.sessionId, this.root, this.sessionKey) : captureTemporalFileBase(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const files = new Map(base.files.map((file) => [file.path, file.content]));
+		if (copy) {
+			const session = temporalScopePaths(this.cwd, this.sessionId, "session", this.root, this.sessionKey);
+			const owned = [session.checkpoint, session.patches, session.meta, join(session.directory, "config.json"), join(session.directory, "state.json")];
+			const occupied = owned.some((path) => files.get(path) !== undefined);
+			const historical = !occupied && backend === "git" && base.head ? loadTemporalRevision(this.cwd, this.sessionId, this.root, base.head, this.sessionKey) : undefined;
+			if (occupied || historical?.runtime || historical?.scopes.session) {
+				throw new Error("State Flow fork target already has session storage");
+			}
+		}
 		if (SCOPES.some((scope) => {
 			const paths = temporalScopePaths(this.cwd, this.sessionId, scope, this.root, this.sessionKey);
 			return files.get(join(paths.directory, "state.json")) !== undefined;
@@ -231,11 +318,13 @@ export class TemporalRuntime {
 			return [scope, parseScopeStream(files.get(paths.checkpoint), files.get(paths.patches), scope, scope === "cwd" ? this.cwd : undefined)];
 		})) as Record<StateScope, TemporalState["scopes"][StateScope] | undefined>;
 		if (!streams.cwd && !allowCreateCwd) return undefined;
+		if (copy && !streams.global) throw new Error("State Flow fork requires existing shared scope storage");
 		const paths = sessionRuntimePaths(this.cwd, this.sessionId, this.root, this.sessionKey);
 		const existingRuntime = parseSessionRuntime(files.get(paths.config), files.get(paths.meta), this.cwd, this.sessionId);
 		if (existingRuntime && !snapshot.legacySession && !newSessionOrigin) throw new Error("Existing session runtime requires a branch revision pointer");
 		// Explicit start before any branch runtime is a new origin, never inheritance of a later session layer.
 		if (snapshot.legacySession || newSessionOrigin) streams.session = undefined;
+		if (copy) streams.session = copy.stream;
 		const fresh = createTemporalState({ global: emptyState(), cwd: emptyState(), session: snapshot.legacySession?.state ?? emptyState() }, randomUUID());
 		const candidate = new TemporalRuntime(this.cwd, this.session, this.root);
 		candidate.backend = backend;
@@ -246,12 +335,12 @@ export class TemporalRuntime {
 		candidate.provenanceByScope = {
 			global: parseScopeProvenance(files.get(globalMeta), globalMeta),
 			cwd: parseScopeProvenance(files.get(cwdMeta), cwdMeta),
-			session: streams.session === undefined ? {} : parseArtifactProvenanceRegistry(existingRuntime?.meta.artifacts, "State Flow session artifact provenance"),
+			session: copy ? structuredClone(copy.provenance) : streams.session === undefined ? {} : parseArtifactProvenanceRegistry(existingRuntime?.meta.artifacts, "State Flow session artifact provenance"),
 		};
 		if (expectedShared && (["global", "cwd"] as const).some((scope) => !sameJson(candidate.read(0, scope), expectedShared[scope]))) {
 			throw new Error("Legacy branch shared scopes diverged from the selected revision; migration cannot overwrite them");
 		}
-		const publication = candidate.publish(snapshot, true);
+		const publication = copy ? candidate.publishForkOrigin(snapshot) : candidate.publish(snapshot, true);
 		this.view = candidate.view;
 		this.base = candidate.base;
 		this.backend = backend;
@@ -261,6 +350,19 @@ export class TemporalRuntime {
 		return publication;
 	}
 
+	/** Initial copy owns only the new session files, without pruning or rewriting shared provenance. */
+	private publishForkOrigin(snapshot: Snapshot): RuntimePublication {
+		const runtime = createSessionRuntime(snapshot, this.cwd, this.sessionId, this.view!.lineage, this.backend === "files" ? "files" : "unconfirmed", this.provenanceByScope.session);
+		const result = this.backend === "files"
+			? publishTemporalStateToFiles(this.cwd, this.sessionId, this.view!, ["session"], this.base!, this.root, runtime, this.sessionKey, this.provenanceByScope)
+			: publishTemporalStateToGit(this.cwd, this.sessionId, this.view!, ["session"], this.base!, this.root, runtime, this.sessionKey, (snapshot.meta.remotePublication?.mode ?? "transition") === "transition", this.provenanceByScope);
+		const publication: RuntimePublication = result;
+		this.base = publication.base;
+		this.semanticRevision = publication.revision ?? publication.commit;
+		this.savedRuntime = hashJson(runtime);
+		return publication;
+	}
+
 	/**
 	 * Reconcile untouched shared-scope drift against the current proven live basis.
 	 *