@stim-cli/core 1.3.1 → 1.4.0

package/README.md

@@ -3,6 +3,30 @@
 Shared internal contracts for Stim and its cache packages.
 
 The package contains runtime-path resolution, cache-key generation, cache
-registration, and directory locking. It is not a user-facing API.
+registration, filesystem artifact storage, and identity-aware ownership claims. It is not a user-facing API.
+
+`withDirLock` runs short synchronous, reentrant transactions with a bounded wait
+for a live holder. It shares the claim protocol in `@stim-cli/core/ownership-claim`
+and the identity checks in `@stim-cli/core/process-identity`; the CLI re-exports
+those modules. Core depends on `unique-pid`, so standalone Metro and Expo cache
+consumers receive the same process identity implementation without installing Stim.
+
+The shared claim lives beside the visible lock directory at `<lock>.claims`.
+While holding its exclusive claim, the short-lock adapter takes the visible
+directory and adds a `.stim-claim-<claimId>` compatibility marker. Older callers
+still see an occupied directory. Publication staging stays in the claim store,
+so a losing publisher cannot prevent the visible directory's release. Only the
+holder of the exclusive claim can recover a recognized compatibility marker;
+release removes its own marker before removing the empty visible directory.
+This preserves ordinary legacy mkdir contention; an older caller that deletes
+occupied locks based on their age can still violate mutual exclusion.
+
+A complete claim left by a proven-dead owner can be recovered immediately.
+Age never expires a live claim. Unknown owner or child identities refuse;
+legacy directories and visible directories left empty before marker publication
+or after marker removal remain blocked because there is no record proving that
+they are free. Verify the holder before manually
+removing the named claim or legacy directory. Long operations that spawn native
+children use an explicit claim and record the child's identity.
 
 The npm scope remains `@stim-cli` until the `@stim` scope is available.

package/dist/index.d.mts

@@ -1,11 +1,29 @@
-//#region index.d.ts
+//#region dir-lock.d.ts
 interface DirLockOptions {
+  /** @deprecated Occupied locks are never expired. */
   staleMs?: number;
   waitMs?: number;
   pollMs?: number;
   ensureParent?: () => void;
 }
-declare function withDirLock<T>(lockPath: string, fn: () => T, { staleMs, waitMs, pollMs, ensureParent }?: DirLockOptions): T;
+declare function withDirLock<T>(lockPath: string, fn: () => T, { waitMs, pollMs, ensureParent }?: DirLockOptions): T;
+//#endregion
+//#region quoted-path.d.ts
+/** Quote a path for a shell command Stim prints for a human to copy and run. */
+declare function quotedPath(path: string): string;
+//#endregion
+//#region artifact-store.d.ts
+declare function artifactIn(dir: string): string | null;
+declare function resolveArtifact(dir: string): string | null;
+interface StoreArtifactOptions {
+  runFile: (file: string, args: string[]) => unknown;
+  overwrite?: boolean;
+  writeMetadata?: (stagingDir: string) => void;
+  onRenameError?: (stagingDir: string) => void;
+}
+declare function storeArtifact(dest: string, buildPath: string, { runFile, overwrite, writeMetadata, onRenameError }: StoreArtifactOptions): string | null;
+//#endregion
+//#region index.d.ts
 declare function configDir(): string;
 declare function workspaceSlug(projectRoot: string): string;
 declare function workspaceId(projectRoot: string): string;
@@ -57,4 +75,4 @@ declare function readCacheManifest(file: string): CacheManifest;
 declare function updateCacheManifest(file: string, mutate: (caches: Array<Record<string, unknown>>) => Array<Record<string, unknown>>): CacheManifest;
 declare function registerCache({ dir, name, prune, note, entriesDepth, layout, replaces }: RegisterOptions): void;
 //#endregion
-export { BuildRunOptions, CacheManifest, CacheRegistrationMatch, DirLockOptions, METRO_NAMED_CACHE_LAYOUT, RegisterOptions, STORE_ROOT_TAG, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, readCacheManifest, registerCache, sharedStoreRoot, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };
+export { BuildRunOptions, CacheManifest, CacheRegistrationMatch, type DirLockOptions, METRO_NAMED_CACHE_LAYOUT, RegisterOptions, STORE_ROOT_TAG, type StoreArtifactOptions, artifactIn, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, quotedPath, readCacheManifest, registerCache, resolveArtifact, sharedStoreRoot, storeArtifact, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };

package/dist/index.mjs

@@ -1,58 +1,112 @@
-import fs from "node:fs";
+import { S as quotedPath, _ as releaseClaim, r as ClaimRefusedError, x as tryAcquireClaim } from "./ownership-claim-DGxNcAcy.mjs";
+import fs, { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
 import os from "node:os";
-import path from "node:path";
+import path, { basename, dirname, join } from "node:path";
 import { createHash } from "node:crypto";
-//#region index.ts
-const DEFAULT_LOCK_STALE_MS = 1e4;
+//#region dir-lock.ts
 const DEFAULT_LOCK_WAIT_MS = 12e3;
 const DEFAULT_LOCK_POLL_MS = 25;
 const lockDepths = /* @__PURE__ */ new Map();
+const OWNER_MARKER = /^\.stim-claim-[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/;
 function sleepSync(ms) {
 	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
-function acquireDirLock(lockPath, { staleMs, waitMs, pollMs, ensureParent }) {
-	ensureParent?.();
-	const deadline = Date.now() + waitMs;
-	for (;;) {
+function createLockDirectory(lockPath) {
+	try {
+		mkdirSync(lockPath);
+		return true;
+	} catch (error) {
+		if (error?.code === "EEXIST") return false;
+		throw error;
+	}
+}
+function removeLockDirectory(lockPath, marker) {
+	try {
+		unlinkSync(marker);
+	} catch (error) {
+		if (error?.code === "ENOENT") return false;
+		throw error;
+	}
+	try {
+		rmdirSync(lockPath);
+		return true;
+	} catch (error) {
+		if ([
+			"ENOENT",
+			"ENOTEMPTY",
+			"EEXIST"
+		].includes(error?.code ?? "")) return false;
+		throw error;
+	}
+}
+function takeLockDirectory(lockPath, claim) {
+	if (!createLockDirectory(lockPath)) {
+		let entries;
 		try {
-			fs.mkdirSync(lockPath);
-			return;
+			entries = readdirSync(lockPath);
 		} catch (error) {
-			if (error?.code !== "EEXIST") throw error;
+			if (error?.code === "ENOENT") return null;
+			throw error;
 		}
-		let ageMs = null;
+		const name = entries.length === 1 ? entries[0] : void 0;
+		if (!name || !OWNER_MARKER.test(name)) return null;
+		const marker = join(lockPath, name);
+		let entry;
 		try {
-			ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
-		} catch {
-			continue;
-		}
-		if (ageMs > staleMs) {
-			try {
-				fs.rmSync(lockPath, {
-					recursive: true,
-					force: true
-				});
-			} catch {}
-			continue;
-		}
-		if (Date.now() >= deadline) {
-			const error = /* @__PURE__ */ new Error(`Timed out waiting for the lock at ${lockPath}. Another Stim process is holding it; if none is running, remove that directory.`);
-			error.code = "STIM_LOCK_TIMEOUT";
-			error.lockPath = lockPath;
+			entry = lstatSync(marker);
+		} catch (error) {
+			if (error?.code === "ENOENT") return null;
 			throw error;
 		}
-		sleepSync(pollMs);
+		if (!entry.isFile() || entry.size !== 0) throw new ClaimRefusedError({
+			root: lockPath,
+			claimPath: lockPath,
+			label: "directory lock",
+			reason: `its compatibility marker ${name} is not an empty file`
+		});
+		if (!removeLockDirectory(lockPath, marker) || !createLockDirectory(lockPath)) return null;
 	}
+	const marker = join(lockPath, `.stim-claim-${claim.claimId}`);
+	writeFileSync(marker, "", { flag: "wx" });
+	return marker;
 }
-function releaseDirLock(lockPath) {
+function acquireDirLock(lockPath, { waitMs, pollMs, ensureParent }) {
+	ensureParent?.();
+	statSync(dirname(lockPath));
+	const deadline = Date.now() + waitMs;
+	let claim;
 	try {
-		fs.rmSync(lockPath, {
-			recursive: true,
-			force: true
-		});
-	} catch {}
+		for (;;) {
+			if (!claim) {
+				const attempt = tryAcquireClaim({
+					root: `${lockPath}.claims`,
+					mode: "exclusive",
+					label: "directory lock"
+				});
+				claim = attempt.acquired;
+				if (attempt.pending) releaseClaim(attempt.pending);
+			}
+			if (claim) {
+				const marker = takeLockDirectory(lockPath, claim);
+				if (marker) return {
+					claim,
+					marker
+				};
+			}
+			if (Date.now() >= deadline) {
+				const error = /* @__PURE__ */ new Error(`Timed out waiting for the lock at ${lockPath}. Another Stim process may be holding it; if none is running, remove that directory.`);
+				error.code = "STIM_LOCK_TIMEOUT";
+				error.lockPath = lockPath;
+				throw error;
+			}
+			sleepSync(pollMs);
+		}
+	} catch (error) {
+		releaseClaim(claim);
+		throw error;
+	}
 }
-function withDirLock(lockPath, fn, { staleMs = DEFAULT_LOCK_STALE_MS, waitMs = DEFAULT_LOCK_WAIT_MS, pollMs = DEFAULT_LOCK_POLL_MS, ensureParent } = {}) {
+function withDirLock(lockPath, fn, { waitMs = DEFAULT_LOCK_WAIT_MS, pollMs = DEFAULT_LOCK_POLL_MS, ensureParent } = {}) {
 	const depth = lockDepths.get(lockPath) || 0;
 	if (depth > 0) {
 		lockDepths.set(lockPath, depth + 1);
@@ -62,8 +116,7 @@ function withDirLock(lockPath, fn, { staleMs = DEFAULT_LOCK_STALE_MS, waitMs = D
 			lockDepths.set(lockPath, (lockDepths.get(lockPath) ?? 1) - 1);
 		}
 	}
-	acquireDirLock(lockPath, {
-		staleMs,
+	const { claim, marker } = acquireDirLock(lockPath, {
 		waitMs,
 		pollMs,
 		ensureParent
@@ -73,9 +126,71 @@ function withDirLock(lockPath, fn, { staleMs = DEFAULT_LOCK_STALE_MS, waitMs = D
 		return fn();
 	} finally {
 		lockDepths.set(lockPath, 0);
-		releaseDirLock(lockPath);
+		try {
+			removeLockDirectory(lockPath, marker);
+		} catch {}
+		releaseClaim(claim);
+	}
+}
+//#endregion
+//#region artifact-store.ts
+function artifactIn(dir) {
+	if (!existsSync(dir)) return null;
+	let found;
+	try {
+		found = readdirSync(dir).find((f) => f.endsWith(".app") || f.endsWith(".apk"));
+	} catch {
+		return null;
+	}
+	return found ? join(dir, found) : null;
+}
+function resolveArtifact(dir) {
+	const hit = artifactIn(dir);
+	if (!hit) return null;
+	try {
+		utimesSync(dir, /* @__PURE__ */ new Date(), /* @__PURE__ */ new Date());
+	} catch {}
+	return hit;
+}
+function storeArtifact(dest, buildPath, { runFile, overwrite = false, writeMetadata, onRenameError }) {
+	const existing = artifactIn(dest);
+	if (existing && !overwrite) return existing;
+	const staging = `${dest}.staging-${process.pid}`;
+	rmSync(staging, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(staging, { recursive: true });
+	try {
+		runFile("cp", [
+			"-c",
+			"-R",
+			buildPath,
+			join(staging, basename(buildPath))
+		]);
+	} catch {
+		runFile("cp", [
+			"-R",
+			buildPath,
+			join(staging, basename(buildPath))
+		]);
 	}
+	writeMetadata?.(staging);
+	mkdirSync(dirname(dest), { recursive: true });
+	rmSync(dest, {
+		recursive: true,
+		force: true
+	});
+	try {
+		renameSync(staging, dest);
+	} catch (error) {
+		if (!onRenameError) throw error;
+		onRenameError(staging);
+	}
+	return artifactIn(dest);
 }
+//#endregion
+//#region index.ts
 function configDir() {
 	return process.env.STIM_HOME || path.join(os.homedir(), ".stim");
 }
@@ -220,4 +335,4 @@ function matchesCache(cache, match) {
 	return match.layout === void 0 || cache.layout === match.layout;
 }
 //#endregion
-export { METRO_NAMED_CACHE_LAYOUT, STORE_ROOT_TAG, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, readCacheManifest, registerCache, sharedStoreRoot, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };
+export { METRO_NAMED_CACHE_LAYOUT, STORE_ROOT_TAG, artifactIn, buildCacheKey, buildCacheRoot, cacheManifestLockPath, cacheNameSegment, cachePathSetting, configDir, metroCacheRoot, quotedPath, readCacheManifest, registerCache, resolveArtifact, sharedStoreRoot, storeArtifact, tagSharedStore, updateCacheManifest, withDirLock, workspaceId, workspaceLogDir, workspaceName, workspaceSlug, workspaceStateDir };

package/dist/ownership-claim-DGxNcAcy.mjs

@@ -0,0 +1,589 @@
+import { captureProcessIdentity, inspectProcessIdentity } from "./process-identity.mjs";
+import { lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+//#region quoted-path.ts
+/** Quote a path for a shell command Stim prints for a human to copy and run. */
+function quotedPath(path) {
+	return `'${path.replaceAll("'", "'\\''")}'`;
+}
+//#endregion
+//#region ownership-claim.ts
+const CLAIM_REFUSED = "STIM_CLAIM_REFUSED";
+const CLAIM_UNAVAILABLE = "STIM_CLAIM_UNAVAILABLE";
+const EXCLUSIVE_DIR = "exclusive";
+const SHARED_DIR = "shared";
+const CLAIM_SUFFIX = ".claim";
+const CHILD_SUFFIX = ".child";
+const STAGING_PREFIX = ".staging-";
+const PUBLISH_ATTEMPTS = 64;
+var ClaimRefusedError = class extends Error {
+	code = CLAIM_REFUSED;
+	claimPath;
+	reason;
+	removeCommand;
+	constructor({ claimPath, root, reason, label, blockingFile = false }) {
+		const removeCommand = blockingFile ? `mv -i ${quotedPath(claimPath)} ${quotedPath(`${claimPath}.stim-backup`)}` : claimRemoveCommand(claimPath.startsWith(root) ? claimPath : root);
+		super(blockingFile ? `The ${label} claim store is blocked by a non-directory path at ${claimPath}. Inspect it before moving it aside; its contents may be unrelated to Stim. Preserve it with the command below (an existing backup prompts before overwriting), then run the command again:\n  ${removeCommand}` : `Stim cannot tell whether the ${label} claim at ${claimPath} is still held: ${reason}. It will not remove a claim it cannot prove is dead, and it will not wait on one either. If nothing is using it, remove the claim and run the command again:\n  ${removeCommand}`);
+		this.claimPath = claimPath;
+		this.reason = reason;
+		this.removeCommand = removeCommand;
+	}
+};
+var ClaimUnavailableError = class extends Error {
+	code = CLAIM_UNAVAILABLE;
+	reason;
+	remedy;
+	constructor(reason, { claimPath } = {}) {
+		super(claimPath ? `Stim could not write the ownership claim at ${claimPath}: ${reason}.` : `Stim could not record a process identity, so it cannot take an ownership claim: ${reason}.`);
+		this.reason = reason;
+		this.remedy = claimPath ? `Restore write access to the existing claim store at ${quotedPath(claimPath)} (check parent permissions, symlink targets, mount access and sandbox rules)` : "Reinstall Stim so the unique-pid native module for this platform is present";
+	}
+};
+/**
+* The command that clears one surveyed claim: targeted at the claim's own file when the path names one,
+* and quoted, because this text is printed for a human to copy into a shell and a path with a space in
+* it would otherwise name several targets.
+*/
+function claimRemoveCommand(path) {
+	return `rm ${path.endsWith(CLAIM_SUFFIX) || path.endsWith(CHILD_SUFFIX) ? "-f" : "-rf"} ${quotedPath(path)}`;
+}
+function isClaimRefusal(err) {
+	return err?.code === CLAIM_REFUSED;
+}
+function isClaimUnavailable(err) {
+	return err?.code === CLAIM_UNAVAILABLE;
+}
+/** Convert an unresolved claim, unavailable identity or inaccessible warm claim store into command recovery guidance. */
+function claimFailure(err, retryCommand) {
+	const retry = retryCommand === null ? "retry the same Stim command" : `run \`${retryCommand}\` again`;
+	if (isClaimRefusal(err)) return {
+		code: CLAIM_REFUSED,
+		message: err.message,
+		remedy: `Run \`${err.removeCommand}\`, then ${retry}.`
+	};
+	if (isClaimUnavailable(err)) return {
+		code: CLAIM_UNAVAILABLE,
+		message: err.message,
+		remedy: `${err.remedy}, then ${retry}.`
+	};
+	return null;
+}
+function exclusiveClaimDir(root) {
+	return join(root, EXCLUSIVE_DIR);
+}
+function sharedClaimDir(root) {
+	return join(root, SHARED_DIR);
+}
+function childPath(claimPath) {
+	return `${claimPath.slice(0, -6)}${CHILD_SUFFIX}`;
+}
+function asOwner(record) {
+	const candidate = record;
+	if (!candidate || typeof candidate !== "object") return null;
+	if (typeof candidate.pid !== "number" || !Number.isSafeInteger(candidate.pid) || candidate.pid <= 0) return null;
+	if (typeof candidate.processToken !== "string" || !candidate.processToken) return null;
+	return {
+		pid: candidate.pid,
+		processToken: candidate.processToken
+	};
+}
+function readChild(claimPath) {
+	let text;
+	try {
+		text = readFileSync(childPath(claimPath), "utf-8");
+	} catch (err) {
+		if (err?.code === "ENOENT") return null;
+		return "unreadable";
+	}
+	try {
+		return { record: asOwner(JSON.parse(text)?.record) };
+	} catch {
+		return "unreadable";
+	}
+}
+function readClaim(path, mode) {
+	let text;
+	try {
+		text = readFileSync(path, "utf-8");
+	} catch (err) {
+		if (err?.code === "ENOENT") return null;
+		return "unreadable";
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return "unreadable";
+	}
+	const owner = asOwner(parsed?.owner);
+	if (!owner || typeof parsed.claimId !== "string" || !parsed.claimId) return "unreadable";
+	const child = readChild(path);
+	if (child === "unreadable") return "unreadable";
+	return {
+		path,
+		claimId: parsed.claimId,
+		mode,
+		owner,
+		startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : "",
+		details: parsed.details && typeof parsed.details === "object" ? parsed.details : {},
+		child: child?.record ?? null,
+		childDeclared: child !== null
+	};
+}
+/**
+* Whether any member of the process group `pid` leads is alive. A recorded child is resolved through
+* its group rather than through the one process, so a package manager's postinstall descendant keeps
+* the claim after the manager exits. A pgid, unlike a ProcessRecord, carries no identity: a recycled
+* one reads as alive, which holds a claim longer than it needs to be held and never frees a live one.
+*/
+function processGroupAlive(pid) {
+	if (!Number.isSafeInteger(pid) || pid <= 1) return false;
+	try {
+		process.kill(-pid, 0);
+		return true;
+	} catch (err) {
+		return err?.code === "EPERM";
+	}
+}
+function childLiveness(claimPath) {
+	const child = readChild(claimPath);
+	if (child === null) return "none";
+	if (child === "unreadable" || !child.record) return "unknown";
+	const status = inspectProcessIdentity(child.record);
+	if (status === "same") return "live";
+	if (status === "gone") return processGroupAlive(child.record.pid) ? "live" : "dead";
+	return "unknown";
+}
+function claimLiveness(holder) {
+	const status = inspectProcessIdentity(holder.owner);
+	if (status === "same") return "live";
+	if (status === "unknown") return "unknown";
+	const child = childLiveness(holder.path);
+	return child === "none" ? "dead" : child;
+}
+function refuse(root, claimPath, label, reason) {
+	throw new ClaimRefusedError({
+		claimPath,
+		root,
+		label,
+		reason
+	});
+}
+function refuseNonDirectory(root, path, label) {
+	let blocking = null;
+	for (let level = path;; level = dirname(level)) {
+		try {
+			if (!statSync(level).isDirectory()) {
+				blocking = level;
+				break;
+			}
+		} catch (error) {
+			const code = error?.code;
+			if (code !== "ENOENT" && code !== "ENOTDIR") break;
+		}
+		if (dirname(level) === level) break;
+	}
+	if (blocking === null) throw new ClaimUnavailableError("the non-directory path could not be identified; the claim store may have changed", { claimPath: root });
+	throw new ClaimRefusedError({
+		root,
+		claimPath: blocking,
+		label,
+		reason: "the claim path is a file, not a claim directory",
+		blockingFile: true
+	});
+}
+function names(dir) {
+	try {
+		return readdirSync(dir).toSorted();
+	} catch (err) {
+		if (err?.code === "ENOENT") return [];
+		return "unreadable";
+	}
+}
+function survey(dir, mode, into) {
+	const listed = names(dir);
+	if (listed === "unreadable") {
+		into.unresolved.push({
+			path: dir,
+			reason: "its directory could not be read"
+		});
+		return;
+	}
+	const claims = new Set(listed.filter((name) => name.endsWith(CLAIM_SUFFIX)));
+	const orphans = listed.filter((name) => name.endsWith(CHILD_SUFFIX) && !claims.has(`${name.slice(0, -6)}${CLAIM_SUFFIX}`));
+	for (const name of orphans) into.orphans.push(join(dir, name));
+	for (const name of listed) {
+		if (!name.endsWith(CLAIM_SUFFIX)) continue;
+		const path = join(dir, name);
+		const holder = readClaim(path, mode);
+		if (holder === null) continue;
+		if (holder === "unreadable") {
+			into.unresolved.push({
+				path,
+				reason: "its record is missing, truncated or not valid JSON"
+			});
+			continue;
+		}
+		const liveness = claimLiveness(holder);
+		if (liveness === "live") into.live.push(holder);
+		else if (liveness === "dead") into.dead.push(holder);
+		else into.unresolved.push({
+			path,
+			reason: holder.childDeclared && !holder.child ? "it spawned the process that holds it and was killed before recording which one" : "its process identity token does not decode, so the holder cannot be identified"
+		});
+	}
+	if (listed.filter((name) => !orphans.includes(name)).length > 0 && claims.size === 0) into.unresolved.push({
+		path: dir,
+		reason: "it holds files Stim did not write"
+	});
+}
+/** Classify every claim in a claim set without removing anything and without refusing. */
+function readClaimSet(root) {
+	const state = {
+		live: [],
+		dead: [],
+		unresolved: [],
+		orphans: []
+	};
+	survey(exclusiveClaimDir(root), "exclusive", state);
+	survey(sharedClaimDir(root), "shared", state);
+	return state;
+}
+function removeOrRefuse(path, root, claimPath, label) {
+	try {
+		unlinkSync(path);
+	} catch (err) {
+		const code = err?.code;
+		if (code === "ENOENT") return;
+		refuse(root, claimPath, label, `the claim left behind could not be removed (${code || err?.message})`);
+	}
+}
+function reap(holder, root, label) {
+	const again = readClaim(holder.path, holder.mode);
+	if (again === null) return true;
+	if (again === "unreadable" || again.claimId !== holder.claimId) return false;
+	removeOrRefuse(childPath(holder.path), root, holder.path, label);
+	removeOrRefuse(holder.path, root, holder.path, label);
+	return true;
+}
+function tidy(dir) {
+	try {
+		rmdirSync(dir);
+	} catch {}
+}
+function inspectClaimSet(root, { label = "ownership" } = {}) {
+	const state = readClaimSet(root);
+	const unresolved = state.unresolved[0];
+	if (unresolved) refuse(root, unresolved.path, label, unresolved.reason);
+	const reaped = [];
+	for (const orphan of state.orphans) removeOrRefuse(orphan, root, orphan, label);
+	for (const holder of state.dead) if (reap(holder, root, label)) reaped.push(holder);
+	if (!state.live.some((holder) => holder.mode === "exclusive")) tidy(exclusiveClaimDir(root));
+	if (!state.live.some((holder) => holder.mode === "shared")) tidy(sharedClaimDir(root));
+	return {
+		exclusive: state.live.find((holder) => holder.mode === "exclusive") ?? null,
+		shared: state.live.filter((holder) => holder.mode === "shared"),
+		reaped
+	};
+}
+function tidySet(root) {
+	tidy(exclusiveClaimDir(root));
+	tidy(sharedClaimDir(root));
+	tidy(root);
+}
+function removeAbandonedStaging(root) {
+	const listed = names(root);
+	if (listed === "unreadable") return;
+	for (const name of listed) if (name.startsWith(STAGING_PREFIX)) rmSync(join(root, name), {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Remove a claim set that holds nothing. Takes the set's own exclusive claim first and removes the set
+* only through the token-verified unlink and empty-directory removals that releasing a claim performs,
+* so a claim published between the survey that reported the set stale and this call is kept, not
+* deleted; a set whose state cannot be established is refused rather than removed.
+*/
+function clearFreeClaimSet({ root, label = "ownership" }) {
+	let attempt;
+	try {
+		attempt = tryAcquireClaim({
+			root,
+			mode: "exclusive",
+			label
+		});
+	} catch (err) {
+		if (isClaimRefusal(err) || isClaimUnavailable(err)) return {
+			status: "refused",
+			reason: err.reason
+		};
+		return {
+			status: "failed",
+			reason: err?.message ?? String(err)
+		};
+	}
+	if (!attempt.acquired) {
+		if (attempt.pending) releaseClaim(attempt.pending);
+		return {
+			status: "held",
+			holder: attempt.held ?? attempt.waitingFor?.[0] ?? null
+		};
+	}
+	try {
+		removeAbandonedStaging(root);
+	} catch (err) {
+		return {
+			status: "failed",
+			reason: err?.message ?? String(err)
+		};
+	} finally {
+		releaseClaim(attempt.acquired);
+	}
+	tidySet(root);
+	const remaining = names(root);
+	if (remaining === "unreadable") return {
+		status: "failed",
+		reason: "its directory could not be read"
+	};
+	const after = readClaimSet(root);
+	if (after.live.length > 0) return {
+		status: "held",
+		holder: after.live[0]
+	};
+	if (after.unresolved.length > 0) return {
+		status: "refused",
+		reason: after.unresolved[0].reason
+	};
+	if (remaining.length > 0) return {
+		status: "failed",
+		reason: `it still holds ${remaining.join(", ")}`
+	};
+	return { status: "cleared" };
+}
+function selfOwner() {
+	const captured = captureProcessIdentity(process.pid);
+	if (!captured.ok) throw new ClaimUnavailableError(captured.reason);
+	return {
+		pid: process.pid,
+		processToken: captured.token
+	};
+}
+function contended(error) {
+	if (error instanceof MissingClaimStoreError) return false;
+	const code = error?.code;
+	return code === "EEXIST" || code === "ENOTEMPTY" || code === "ENOENT" || code === "EINVAL";
+}
+var MissingClaimStoreError = class extends Error {
+	code = "ENOENT";
+};
+function createClaimDir(path) {
+	try {
+		mkdirSync(path, { recursive: true });
+		return;
+	} catch (error) {
+		if (error?.code !== "ENOENT") throw error;
+	}
+	const missing = [];
+	for (let level = path;; level = dirname(level)) {
+		let entry;
+		try {
+			entry = lstatSync(level);
+		} catch (error) {
+			if (error?.code !== "ENOENT") throw error;
+			missing.push(level);
+			continue;
+		}
+		if (entry.isSymbolicLink()) try {
+			statSync(level);
+		} catch (error) {
+			if (error?.code === "ENOENT") throw new MissingClaimStoreError(error.message, { cause: error });
+			throw error;
+		}
+		break;
+	}
+	for (const level of missing.toReversed()) try {
+		mkdirSync(level);
+	} catch (error) {
+		if (error?.code !== "EEXIST") throw error;
+	}
+}
+function publishExclusive(root, payload, claimId, label) {
+	const staging = join(root, `${STAGING_PREFIX}${claimId}`);
+	const target = exclusiveClaimDir(root);
+	try {
+		createClaimDir(staging);
+		writeFileSync(join(staging, `${claimId}${CLAIM_SUFFIX}`), payload);
+		renameSync(staging, target);
+		return join(target, `${claimId}${CLAIM_SUFFIX}`);
+	} catch (err) {
+		rmSync(staging, {
+			recursive: true,
+			force: true
+		});
+		const code = err?.code;
+		if (contended(err)) return null;
+		if (code === "ENOTDIR") refuseNonDirectory(root, target, label);
+		throw err;
+	}
+}
+function publishShared(root, payload, claimId) {
+	const staging = join(root, `${STAGING_PREFIX}${claimId}`);
+	const target = join(sharedClaimDir(root), `${claimId}${CLAIM_SUFFIX}`);
+	try {
+		createClaimDir(sharedClaimDir(root));
+		writeFileSync(staging, payload);
+		renameSync(staging, target);
+		return target;
+	} catch (err) {
+		rmSync(staging, { force: true });
+		if (contended(err)) return null;
+		throw err;
+	}
+}
+function settleOrRelease(claim) {
+	try {
+		return inspectClaimSet(claim.root, { label: claim.label });
+	} catch (err) {
+		releaseClaim(claim);
+		throw err;
+	}
+}
+function tryAcquireClaim({ root, mode, details = {}, label = "ownership" }) {
+	const owner = selfOwner();
+	const reaped = [];
+	for (let attempt = 0; attempt < PUBLISH_ATTEMPTS; attempt++) {
+		try {
+			createClaimDir(root);
+		} catch (err) {
+			const code = err?.code;
+			if (code === "EEXIST" || code === "ENOTDIR") refuseNonDirectory(root, root, label);
+			if (contended(err)) continue;
+			throw err;
+		}
+		const state = inspectClaimSet(root, { label });
+		reaped.push(...state.reaped);
+		if (state.exclusive) return {
+			held: state.exclusive,
+			reaped
+		};
+		const claimId = randomUUID();
+		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const payload = JSON.stringify({
+			claimId,
+			mode,
+			owner,
+			startedAt,
+			details
+		});
+		const handle = (path) => ({
+			root,
+			path,
+			claimId,
+			mode,
+			owner,
+			startedAt,
+			details,
+			label
+		});
+		if (mode === "shared") {
+			const published = publishShared(root, payload, claimId);
+			if (!published) continue;
+			const claim = handle(published);
+			const settled = settleOrRelease(claim);
+			reaped.push(...settled.reaped);
+			if (!settled.exclusive) return {
+				acquired: claim,
+				reaped
+			};
+			releaseClaim(claim);
+			return {
+				held: settled.exclusive,
+				reaped
+			};
+		}
+		const path = publishExclusive(root, payload, claimId, label);
+		if (!path) continue;
+		const claim = handle(path);
+		const settled = settleOrRelease(claim);
+		reaped.push(...settled.reaped);
+		if (settled.shared.length === 0) return {
+			acquired: claim,
+			reaped
+		};
+		return {
+			waitingFor: settled.shared,
+			pending: claim,
+			reaped
+		};
+	}
+	const contender = inspectClaimSet(root, { label });
+	reaped.push(...contender.reaped);
+	const holder = contender.exclusive ?? (mode === "exclusive" ? contender.shared[0] : void 0);
+	if (holder) return {
+		held: holder,
+		reaped
+	};
+	refuse(root, root, label, `another process took and gave up the claim on every one of ${PUBLISH_ATTEMPTS} attempts to take it`);
+}
+function settleClaim(pending) {
+	const state = inspectClaimSet(pending.root, { label: pending.label });
+	if (state.shared.length === 0) return {
+		acquired: pending,
+		reaped: state.reaped
+	};
+	return {
+		waitingFor: state.shared,
+		pending,
+		reaped: state.reaped
+	};
+}
+function releaseClaim(handle) {
+	if (!handle) return false;
+	const current = readClaim(handle.path, handle.mode);
+	if (current === null) return true;
+	if (current === "unreadable" || current.claimId !== handle.claimId) return false;
+	try {
+		rmSync(childPath(handle.path), { force: true });
+		rmSync(handle.path, { force: true });
+	} catch {
+		return false;
+	}
+	tidy(handle.mode === "exclusive" ? exclusiveClaimDir(handle.root) : sharedClaimDir(handle.root));
+	tidy(handle.root);
+	return true;
+}
+/**
+* Declare that this claim is about to spawn the process that does the real work, before the spawn.
+* A claim marked this way and left without a child record reads as unresolvable rather than as free,
+* so a parent killed between the spawn and the record cannot release a claim its child still needs.
+*/
+function markClaimChildPending(handle) {
+	writeChild(handle, { record: null });
+}
+/**
+* Record the spawned process that holds this claim. Spawn it with `detached: true` so it leads its own
+* process group: the claim then reads as held while any member of that group is alive, which is what
+* keeps a package manager's postinstall child covered after the manager itself exits.
+*/
+function setClaimChild(handle, record) {
+	const child = asOwner(record);
+	if (!child) throw new ClaimUnavailableError("the child process identity was not a pid and token pair");
+	writeChild(handle, { record: child });
+}
+function clearClaimChild(handle) {
+	rmSync(childPath(handle.path), { force: true });
+}
+function writeChild(handle, body) {
+	const staging = join(handle.root, `${STAGING_PREFIX}child-${handle.claimId}`);
+	try {
+		writeFileSync(staging, JSON.stringify(body));
+		renameSync(staging, childPath(handle.path));
+	} catch (err) {
+		rmSync(staging, { force: true });
+		throw err;
+	}
+}
+//#endregion
+export { quotedPath as S, releaseClaim as _, claimFailure as a, sharedClaimDir as b, clearClaimChild as c, inspectClaimSet as d, isClaimRefusal as f, readClaimSet as g, processGroupAlive as h, ClaimUnavailableError as i, clearFreeClaimSet as l, markClaimChildPending as m, CLAIM_UNAVAILABLE as n, claimLiveness as o, isClaimUnavailable as p, ClaimRefusedError as r, claimRemoveCommand as s, CLAIM_REFUSED as t, exclusiveClaimDir as u, setClaimChild as v, tryAcquireClaim as x, settleClaim as y };

package/dist/ownership-claim.d.mts

@@ -0,0 +1,152 @@
+import { ProcessRecord } from "./process-identity.mjs";
+//#region ownership-claim.d.ts
+type ClaimMode = "exclusive" | "shared";
+interface ClaimDetails {
+  readonly [key: string]: unknown;
+}
+interface ClaimOwner {
+  pid: number;
+  processToken: string;
+}
+interface ClaimHolder {
+  path: string;
+  claimId: string;
+  mode: ClaimMode;
+  owner: ClaimOwner;
+  startedAt: string;
+  details: ClaimDetails;
+  child: ClaimOwner | null;
+  childDeclared: boolean;
+}
+interface ClaimHandle {
+  root: string;
+  path: string;
+  claimId: string;
+  mode: ClaimMode;
+  owner: ClaimOwner;
+  startedAt: string;
+  details: ClaimDetails;
+  label: string;
+}
+interface ClaimAttempt {
+  acquired?: ClaimHandle;
+  held?: ClaimHolder;
+  waitingFor?: ClaimHolder[];
+  pending?: ClaimHandle;
+  reaped: ClaimHolder[];
+}
+interface ClaimSetState {
+  exclusive: ClaimHolder | null;
+  shared: ClaimHolder[];
+  reaped: ClaimHolder[];
+}
+interface ClaimProblem {
+  path: string;
+  reason: string;
+}
+interface ClaimSurvey {
+  live: ClaimHolder[];
+  dead: ClaimHolder[];
+  unresolved: ClaimProblem[];
+  orphans: string[];
+}
+interface ClaimOptions {
+  root: string;
+  mode: ClaimMode;
+  details?: ClaimDetails;
+  label?: string;
+}
+declare const CLAIM_REFUSED = "STIM_CLAIM_REFUSED";
+declare const CLAIM_UNAVAILABLE = "STIM_CLAIM_UNAVAILABLE";
+declare class ClaimRefusedError extends Error {
+  readonly code: string;
+  readonly claimPath: string;
+  readonly reason: string;
+  readonly removeCommand: string;
+  constructor({ claimPath, root, reason, label, blockingFile }: {
+    claimPath: string;
+    root: string;
+    reason: string;
+    label: string;
+    blockingFile?: boolean;
+  });
+}
+declare class ClaimUnavailableError extends Error {
+  readonly code: string;
+  readonly reason: string;
+  readonly remedy: string;
+  constructor(reason: string, { claimPath }?: {
+    claimPath?: string;
+  });
+}
+/**
+ * The command that clears one surveyed claim: targeted at the claim's own file when the path names one,
+ * and quoted, because this text is printed for a human to copy into a shell and a path with a space in
+ * it would otherwise name several targets.
+ */
+declare function claimRemoveCommand(path: string): string;
+declare function isClaimRefusal(err: unknown): err is ClaimRefusedError;
+declare function isClaimUnavailable(err: unknown): err is ClaimUnavailableError;
+interface ClaimFailure {
+  code: string;
+  message: string;
+  remedy: string;
+}
+/** Convert an unresolved claim, unavailable identity or inaccessible warm claim store into command recovery guidance. */
+declare function claimFailure(err: unknown, retryCommand: string | null): ClaimFailure | null;
+declare function exclusiveClaimDir(root: string): string;
+declare function sharedClaimDir(root: string): string;
+/**
+ * Whether any member of the process group `pid` leads is alive. A recorded child is resolved through
+ * its group rather than through the one process, so a package manager's postinstall descendant keeps
+ * the claim after the manager exits. A pgid, unlike a ProcessRecord, carries no identity: a recycled
+ * one reads as alive, which holds a claim longer than it needs to be held and never frees a live one.
+ */
+declare function processGroupAlive(pid: number): boolean;
+type Liveness = "live" | "dead" | "unknown";
+declare function claimLiveness(holder: ClaimHolder): Liveness;
+/** Classify every claim in a claim set without removing anything and without refusing. */
+declare function readClaimSet(root: string): ClaimSurvey;
+declare function inspectClaimSet(root: string, { label }?: {
+  label?: string;
+}): ClaimSetState;
+type ClaimSetClearance = {
+  status: "cleared";
+} | {
+  status: "held";
+  holder: ClaimHolder | null;
+} | {
+  status: "refused";
+  reason: string;
+} | {
+  status: "failed";
+  reason: string;
+};
+/**
+ * Remove a claim set that holds nothing. Takes the set's own exclusive claim first and removes the set
+ * only through the token-verified unlink and empty-directory removals that releasing a claim performs,
+ * so a claim published between the survey that reported the set stale and this call is kept, not
+ * deleted; a set whose state cannot be established is refused rather than removed.
+ */
+declare function clearFreeClaimSet({ root, label }: {
+  root: string;
+  label?: string;
+}): ClaimSetClearance;
+declare function tryAcquireClaim({ root, mode, details, label }: ClaimOptions): ClaimAttempt;
+declare function settleClaim(pending: ClaimHandle): ClaimAttempt;
+declare function releaseClaim(handle: ClaimHandle | null | undefined): boolean;
+/**
+ * Declare that this claim is about to spawn the process that does the real work, before the spawn.
+ * A claim marked this way and left without a child record reads as unresolvable rather than as free,
+ * so a parent killed between the spawn and the record cannot release a claim its child still needs.
+ */
+declare function markClaimChildPending(handle: ClaimHandle): void;
+/**
+ * Record the spawned process that holds this claim. Spawn it with `detached: true` so it leads its own
+ * process group: the claim then reads as held while any member of that group is alive, which is what
+ * keeps a package manager's postinstall child covered after the manager itself exits.
+ */
+declare function setClaimChild(handle: ClaimHandle, record: ProcessRecord): void;
+declare function clearClaimChild(handle: ClaimHandle): void;
+//#endregion
+export { CLAIM_REFUSED, CLAIM_UNAVAILABLE, ClaimAttempt, ClaimDetails, ClaimFailure, ClaimHandle, ClaimHolder, ClaimMode, ClaimOptions, ClaimOwner, ClaimProblem, ClaimRefusedError, ClaimSetClearance, ClaimSetState, ClaimSurvey, ClaimUnavailableError, claimFailure, claimLiveness, claimRemoveCommand, clearClaimChild, clearFreeClaimSet, exclusiveClaimDir, inspectClaimSet, isClaimRefusal, isClaimUnavailable, markClaimChildPending, processGroupAlive, readClaimSet, releaseClaim, setClaimChild, settleClaim, sharedClaimDir, tryAcquireClaim };

package/dist/ownership-claim.mjs

@@ -0,0 +1,2 @@
+import { _ as releaseClaim, a as claimFailure, b as sharedClaimDir, c as clearClaimChild, d as inspectClaimSet, f as isClaimRefusal, g as readClaimSet, h as processGroupAlive, i as ClaimUnavailableError, l as clearFreeClaimSet, m as markClaimChildPending, n as CLAIM_UNAVAILABLE, o as claimLiveness, p as isClaimUnavailable, r as ClaimRefusedError, s as claimRemoveCommand, t as CLAIM_REFUSED, u as exclusiveClaimDir, v as setClaimChild, x as tryAcquireClaim, y as settleClaim } from "./ownership-claim-DGxNcAcy.mjs";
+export { CLAIM_REFUSED, CLAIM_UNAVAILABLE, ClaimRefusedError, ClaimUnavailableError, claimFailure, claimLiveness, claimRemoveCommand, clearClaimChild, clearFreeClaimSet, exclusiveClaimDir, inspectClaimSet, isClaimRefusal, isClaimUnavailable, markClaimChildPending, processGroupAlive, readClaimSet, releaseClaim, setClaimChild, settleClaim, sharedClaimDir, tryAcquireClaim };

package/dist/process-identity.d.mts

@@ -0,0 +1,20 @@
+//#region process-identity.d.ts
+interface ProcessRecord {
+  pid?: unknown;
+  processToken?: unknown;
+}
+declare function sameProcessRecord(a: ProcessRecord | null | undefined, b: ProcessRecord | null | undefined): boolean;
+type CapturedIdentity = {
+  ok: true;
+  token: string;
+} | {
+  ok: false;
+  reason: string;
+};
+declare function captureProcessIdentity(pid: number): CapturedIdentity;
+declare function captureProcessToken(pid: number): string | null;
+type ProcessIdentityStatus = "same" | "different" | "gone" | "unknown";
+declare function inspectProcessIdentity(record: ProcessRecord | null | undefined): ProcessIdentityStatus;
+declare function waitForProcessExit(record: ProcessRecord, timeoutMs: number): Promise<boolean>;
+//#endregion
+export { CapturedIdentity, ProcessIdentityStatus, ProcessRecord, captureProcessIdentity, captureProcessToken, inspectProcessIdentity, sameProcessRecord, waitForProcessExit };

package/dist/process-identity.mjs

@@ -0,0 +1,40 @@
+import { capture, check, decode } from "unique-pid";
+//#region process-identity.ts
+function sameProcessRecord(a, b) {
+	if (!a || !b) return !a && !b;
+	return a.pid === b.pid && a.processToken === b.processToken;
+}
+function captureProcessIdentity(pid) {
+	const result = capture(pid);
+	if (result.ok) return {
+		ok: true,
+		token: result.value
+	};
+	return {
+		ok: false,
+		reason: `${result.error.code} (${result.error.message})`
+	};
+}
+function captureProcessToken(pid) {
+	const captured = captureProcessIdentity(pid);
+	return captured.ok ? captured.token : null;
+}
+function inspectProcessIdentity(record) {
+	if (!record || typeof record.processToken !== "string") return "unknown";
+	const decoded = decode(record.processToken);
+	if (!decoded.ok || decoded.value.pid !== record.pid) return "unknown";
+	const result = check(record.processToken);
+	return result.ok ? result.value : "unknown";
+}
+async function waitForProcessExit(record, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() <= deadline) {
+		const identity = inspectProcessIdentity(record);
+		if (identity === "different" || identity === "gone") return true;
+		if (Date.now() >= deadline) return false;
+		await new Promise((resolve) => setTimeout(resolve, 100));
+	}
+	return false;
+}
+//#endregion
+export { captureProcessIdentity, captureProcessToken, inspectProcessIdentity, sameProcessRecord, waitForProcessExit };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/core",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Shared internal cache and runtime primitives for Stim packages.",
   "license": "MIT",
   "repository": {
@@ -21,8 +21,21 @@
       "types": "./dist/index.d.mts",
       "module-sync": "./dist/index.mjs",
       "default": "./dist/index.mjs"
+    },
+    "./ownership-claim": {
+      "types": "./dist/ownership-claim.d.mts",
+      "module-sync": "./dist/ownership-claim.mjs",
+      "default": "./dist/ownership-claim.mjs"
+    },
+    "./process-identity": {
+      "types": "./dist/process-identity.d.mts",
+      "module-sync": "./dist/process-identity.mjs",
+      "default": "./dist/process-identity.mjs"
     }
   },
+  "dependencies": {
+    "unique-pid": "0.1.1"
+  },
   "engines": {
     "node": "^20.19.4 || >=22.12.0"
   },