stim 1.3.0 → 1.3.1

package/dist/{status-BxQNqu9t.mjs → status-CI9clRSb.mjs}

@@ -5,13 +5,13 @@ import { f as listWorktrees } from "./worktree-Eq6TLH8N.mjs";
 import { a as findProjectRoot, c as projectShortcut } from "./project-fKmuIaMI.mjs";
 import { a as isMetroRunning, i as resolveProjectMetro } from "./metro-CORqXyTL.mjs";
 import { a as formatElapsed, r as clockTime, u as plural } from "./command-output-8wHMEde0.mjs";
-import { N as resolveOwnedAvdSerial } from "./android-BqVIJoG7.mjs";
-import { a as POOL_SETTING_REMEDY, c as parkedMaxSetting, l as readParked } from "./teardown-ClFp1Aax.mjs";
+import { N as resolveOwnedAvdSerial } from "./android-hMj83VpN.mjs";
+import { a as POOL_SETTING_REMEDY, c as parkedMaxSetting, l as readParked } from "./teardown--gESs9ck.mjs";
 import { u as listAllIosSims } from "./ios-Deh5js5V.mjs";
-import { i as listLeaseFiles } from "./device-lease-BJYybF-2.mjs";
-import { s as queryLogs } from "./logs-query-R-Cqc6Qv.mjs";
-import { t as resolveSupervisorTarget } from "./ownership-BpCKiRlQ.mjs";
-import { i as readSupervisorState } from "./stop-DimGXEKY.mjs";
+import { i as listLeaseFiles } from "./device-lease-CJwK7OZr.mjs";
+import { c as queryLogs } from "./logs-query-Cdp5aaCH.mjs";
+import { t as resolveSupervisorTarget } from "./ownership-DXcol4oU.mjs";
+import { i as readSupervisorState } from "./stop-CjlgDk0a.mjs";
 import { existsSync } from "fs";
 import { totalmem } from "os";
 import chalk from "chalk";

package/dist/{stop-CrHGcjrV.mjs → stop-CQhffpmX.mjs}

@@ -1,3 +1,3 @@
-import { t as resolveSupervisorTarget } from "./ownership-BpCKiRlQ.mjs";
-import { a as resolveCollectorTargets, i as readSupervisorState, n as clearSupervisorState, o as runStop, r as readCollectorState, s as stopCommand, t as clearCollectorState } from "./stop-DimGXEKY.mjs";
+import { t as resolveSupervisorTarget } from "./ownership-DXcol4oU.mjs";
+import { a as resolveCollectorTargets, i as readSupervisorState, n as clearSupervisorState, o as runStop, r as readCollectorState, s as stopCommand, t as clearCollectorState } from "./stop-CjlgDk0a.mjs";
 export { clearCollectorState, clearSupervisorState, stopCommand as default, readCollectorState, readSupervisorState, resolveCollectorTargets, resolveSupervisorTarget, runStop };

package/dist/{stop-DimGXEKY.mjs → stop-CjlgDk0a.mjs}

@@ -4,11 +4,11 @@ import { a as findProjectRoot } from "./project-fKmuIaMI.mjs";
 import { i as resolveProjectMetro, n as killMetroTree, r as pidExists } from "./metro-CORqXyTL.mjs";
 import { n as verifyCollectorOwnership } from "./ownership-8O073GIC.mjs";
 import { f as releasedLeaseFact, l as phaseLine, u as plural } from "./command-output-8wHMEde0.mjs";
-import { n as teardownOwnedIosSim, t as teardownOwnedAvd, x as resolveEasCliBin } from "./teardown-ClFp1Aax.mjs";
-import { t as withWorkspaceProcessLock } from "./workspace-process-lock-3NcQnZ0X.mjs";
-import { l as releaseWorkspaceLeases } from "./device-lease-BJYybF-2.mjs";
-import { i as endRecordedSession } from "./device-remote-AkYCKS8U.mjs";
-import { r as stopTunnel, t as resolveSupervisorTarget } from "./ownership-BpCKiRlQ.mjs";
+import { n as teardownOwnedIosSim, t as teardownOwnedAvd, x as resolveEasCliBin } from "./teardown--gESs9ck.mjs";
+import { t as withWorkspaceProcessLock } from "./workspace-process-lock-IBj1Towr.mjs";
+import { l as releaseWorkspaceLeases } from "./device-lease-CJwK7OZr.mjs";
+import { i as endRecordedSession } from "./device-remote-DAA0Zm6Z.mjs";
+import { r as stopTunnel, t as resolveSupervisorTarget } from "./ownership-DXcol4oU.mjs";
 import chalk from "chalk";
 //#region src/commands/stop.ts
 const DEFAULT_WAIT_MS = 1e4;

package/dist/{teardown-ClFp1Aax.mjs → teardown--gESs9ck.mjs}

@@ -4,7 +4,8 @@ import { r as createNdjsonWriter } from "./ndjson-BZwI1NBv.mjs";
 import { D as workspaceLogsDir } from "./state-B3XA2wp2.mjs";
 import { l as resolvePackageJson } from "./project-fKmuIaMI.mjs";
 import { n as stripAnsi } from "./process-output-C7IlIzd7.mjs";
-import { E as ownedAvdMatchesConfiguration, F as shutdownAndroidEmulator, I as waitForAndroidEmulatorShutdown, N as resolveOwnedAvdSerial, O as ownedAvdSystemImage, S as listOrphanedAvdDirectories, T as ownedAvdDirectory, l as avdStorageRoots, o as assertOwnedAvdStopped, p as deleteAvd, s as avdPathExists } from "./android-BqVIJoG7.mjs";
+import { l as phaseLine } from "./command-output-8wHMEde0.mjs";
+import { E as ownedAvdMatchesConfiguration, F as shutdownAndroidEmulator, I as waitForAndroidEmulatorShutdown, N as resolveOwnedAvdSerial, O as ownedAvdSystemImage, S as listOrphanedAvdDirectories, T as ownedAvdDirectory, l as avdStorageRoots, o as assertOwnedAvdStopped, p as deleteAvd, s as avdPathExists } from "./android-hMj83VpN.mjs";
 import { n as expoBinFromPackage, r as expoBinPath, s as findBinUpward } from "./server-expo-DizT4OMk.mjs";
 import { C as shutdownIosSim, _ as renameIosSim, a as deleteIosSim, d as listIosDeviceTypes, g as parseRuntimeVersion, h as parkedSimName, o as deleteParkedIosSim, r as clearAppDataContainer, s as findAppDataContainer, x as resolveOwnedIosSim } from "./ios-Deh5js5V.mjs";
 import { createRequire } from "node:module";
@@ -720,6 +721,77 @@ function dropParked(platform, udid) {
 	return removeParkedAfter(platform, udid, () => {}) !== null;
 }
 //#endregion
+//#region src/agent-device-cleanup.ts
+function parseAgentDeviceSessions(output) {
+	const result = JSON.parse(output);
+	if (result?.success !== true || !Array.isArray(result.data?.sessions)) throw new Error("agent-device did not return a successful session list");
+	return result.data.sessions.flatMap((entry) => {
+		if (!entry || typeof entry !== "object") return [];
+		const row = entry;
+		const id = row.platform === "ios" ? row.device_udid : row.id;
+		if (row.platform !== "ios" && row.platform !== "android" || typeof row.name !== "string" || !row.name.trim() || typeof id !== "string" || !id || typeof row.createdAt !== "number" || !Number.isFinite(row.createdAt) || row.platform === "ios" && row.id !== void 0 && row.id !== id) return [];
+		return [{
+			name: row.name,
+			platform: row.platform,
+			id,
+			createdAt: row.createdAt
+		}];
+	});
+}
+function report(message) {
+	process.stderr.write(`${phaseLine("device", message)}\n`);
+}
+function closeOwnedDeviceSessions(device, stillOwned) {
+	const exec = getExecutor();
+	const deadline = Date.now() + 15e3;
+	const run = (args) => {
+		const remaining = deadline - Date.now();
+		if (remaining <= 0) throw new Error("agent-device cleanup timed out");
+		return exec.runFile("agent-device", [
+			...args,
+			"--json",
+			"--daemon-transport",
+			"socket"
+		], {
+			timeoutMs: Math.min(5e3, remaining),
+			killSignal: "SIGKILL"
+		});
+	};
+	const list = () => parseAgentDeviceSessions(run([
+		"session",
+		"list",
+		"--session",
+		"stim-teardown-inventory"
+	]));
+	try {
+		if (!exec.runQuiet("command -v agent-device", {
+			timeoutMs: 2e3,
+			killSignal: "SIGKILL"
+		})) return;
+		const sessions = list().filter((session) => session.platform === device.platform && session.id === device.id);
+		for (const session of sessions) try {
+			if (!list().some((current) => current.name === session.name && current.platform === session.platform && current.id === session.id && current.createdAt === session.createdAt)) continue;
+			if (!stillOwned()) return;
+			if (JSON.parse(run([
+				"close",
+				"--session",
+				session.name,
+				"--session-lock",
+				"reject",
+				"--platform",
+				device.platform,
+				device.platform === "ios" ? "--udid" : "--serial",
+				device.id
+			]))?.success !== true) throw new Error("agent-device did not confirm session close");
+			report(`closed agent-device session ${session.name} on ${device.id}`);
+		} catch (error) {
+			report(`could not close agent-device session ${session.name} on ${device.id}: ${error.message}`);
+		}
+	} catch (error) {
+		report(`could not list agent-device sessions for ${device.id}: ${error.message}`);
+	}
+}
+//#endregion
 //#region src/teardown.ts
 function teardownParkedAvd(avdName) {
 	try {
@@ -746,7 +818,13 @@ function teardownParkedAvd(avdName) {
 }
 function teardownParkedIosSim(udid, { label, deleteSim = deleteParkedIosSim } = {}) {
 	try {
-		const removed = removeParkedAfter("ios", udid, () => deleteSim(udid));
+		const removed = removeParkedAfter("ios", udid, () => {
+			closeOwnedDeviceSessions({
+				platform: "ios",
+				id: udid
+			}, () => Boolean(resolveOwnedIosSim(udid).sim));
+			deleteSim(udid);
+		});
 		if (!removed) return {
 			status: "skipped",
 			kind: "not-parked",
@@ -812,6 +890,17 @@ function teardownOwnedIosSim(udid, { del = false, label, park } = {}) {
 			reason: `sim is now named "${resolved.notOwned}", not Stim-owned by name`
 		};
 		if (resolved.missing) return { status: "missing" };
+		closeOwnedDeviceSessions({
+			platform: "ios",
+			id: udid
+		}, () => Boolean(resolveOwnedIosSim(udid).sim));
+		const current = resolveOwnedIosSim(udid);
+		if (current.missing) return { status: "missing" };
+		if (current.notOwned) return {
+			status: "skipped",
+			kind: "not-owned",
+			reason: "simulator ownership changed before shutdown"
+		};
 		shutdownIosSim(udid);
 		const sim = resolved.sim;
 		if (del && park && park.max > 0) try {
@@ -916,8 +1005,18 @@ function teardownOwnedAvd(avdName, { del = false, park, owner, orphanedDirectory
 			reason: "AVD registration appeared; its data was kept."
 		};
 		const serial = resolved.serial;
-		if (serial) waitForShutdown(avdName, (timeoutMs) => shutdownAndroidEmulator(serial, timeoutMs));
-		else assertStopped(avdName);
+		if (serial) {
+			const stillOwned = () => {
+				const current = resolveAvd(avdName);
+				return !current.notOwned && !current.missing && current.serial === serial;
+			};
+			closeOwnedDeviceSessions({
+				platform: "android",
+				id: serial
+			}, stillOwned);
+			if (!stillOwned()) throw new Error(`Owned AVD ${avdName} changed before shutdown; it was kept.`);
+			waitForShutdown(avdName, (timeoutMs) => shutdownAndroidEmulator(serial, timeoutMs));
+		} else assertStopped(avdName);
 		if (del) {
 			const current = resolveAvd(avdName);
 			if (current.notOwned) return {

package/dist/{workspace-process-lock-3NcQnZ0X.mjs → workspace-process-lock-IBj1Towr.mjs}

@@ -1,4 +1,4 @@
-import { f as releaseClaim, h as tryAcquireClaim } from "./ownership-claim-Bf2CAfw3.mjs";
+import { d as releaseClaim, m as tryAcquireClaim } from "./ownership-claim-BtPtJVmq.mjs";
 import { join } from "node:path";
 //#region src/engine/workspace-process-lock.ts
 const DEFAULT_WAIT_MS = 6e4;

package/dist/{worktree-DxTgN1CJ.mjs → worktree-DtQGO9-s.mjs}

@@ -4,14 +4,14 @@ import { c as readMetroTunnel, u as readRemoteSession } from "./state-B3XA2wp2.m
 import { _ as resolveFullRef, b as warmWorktreePaths, c as hasRemote, d as isPodInstallChurn, f as listWorktrees, h as removeWorktree, i as depsOutOfSync, l as hasUncommittedWork, m as readWorktreeExclude, n as cloneIgnoredEntries, o as dirtyPaths, p as podsOutOfSync, r as deleteBranch, s as gitCommonDir, t as branchExists, u as isMainWorkingTree, v as restoreFile, y as unpushedCommits } from "./worktree-Eq6TLH8N.mjs";
 import { a as findProjectRoot } from "./project-fKmuIaMI.mjs";
 import { a as formatElapsed, f as releasedLeaseFact, i as formatDuration, l as phaseLine, m as shortUdid, u as plural } from "./command-output-8wHMEde0.mjs";
-import { a as clearClaimChild, c as isClaimUnavailable, d as readClaimSet, f as releaseClaim, h as tryAcquireClaim, i as claimRemoveCommand, l as markClaimChildPending, m as settleClaim, p as setClaimChild, r as claimFailure, s as isClaimRefusal, u as processGroupAlive } from "./ownership-claim-Bf2CAfw3.mjs";
+import { a as clearClaimChild, c as markClaimChildPending, d as releaseClaim, f as setClaimChild, i as claimRemoveCommand, l as processGroupAlive, m as tryAcquireClaim, n as ClaimUnavailableError, p as settleClaim, r as claimFailure } from "./ownership-claim-BtPtJVmq.mjs";
 import { A as resolveSettings, I as unknownSettingKeys, N as settingShapeErrors, a as SETTING_SHAPE_REMEDY } from "./settings-DEJf6_kJ.mjs";
-import { a as POOL_SETTING_REMEDY, c as parkedMaxSetting } from "./teardown-ClFp1Aax.mjs";
-import { g as podInstallCommand, r as HEARTBEAT_INTERVAL_MS } from "./xcode-D7sAp-Zy.mjs";
-import { a as installedNpmTreeIsValid, i as hasInstalledDependencies, o as locallyKnownUpstream, t as dependencyState } from "./doctor-Bmv86UUW.mjs";
-import { c as withManagedTunnelRemovalLock, o as withManagedRemoteWorktreeRemovalLock } from "./ownership-BpCKiRlQ.mjs";
-import { n as reclaimProject } from "./reclaim-iW9Cad7k.mjs";
-import { a as runPodInstall, i as runCaptured, n as podsAreStale, r as readPodState, t as DEPS_ERROR } from "./deps-Spz8ozgo.mjs";
+import { a as POOL_SETTING_REMEDY, c as parkedMaxSetting } from "./teardown--gESs9ck.mjs";
+import { g as podInstallCommand, r as HEARTBEAT_INTERVAL_MS } from "./xcode-xnxyvJkD.mjs";
+import { a as installedNpmTreeIsValid, i as hasInstalledDependencies, o as locallyKnownUpstream, t as dependencyState } from "./doctor-B4EITgQB.mjs";
+import { c as withManagedTunnelRemovalLock, o as withManagedRemoteWorktreeRemovalLock } from "./ownership-DXcol4oU.mjs";
+import { n as reclaimProject } from "./reclaim-CUmwucWG.mjs";
+import { a as runPodInstall, i as runCaptured, n as podsAreStale, r as readPodState, t as DEPS_ERROR } from "./deps-0Yt0Inly.mjs";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { join, relative } from "node:path";
@@ -56,57 +56,10 @@ function asHolder(holder) {
 function waitingLine(holder, elapsedMs) {
 	return phaseLine("lock", `waiting ${formatElapsed(elapsedMs)} for ${warmCommand(holder.phase)} (pid ${holder.pid}) -- stim guide lifecycle options`);
 }
-function warmClaimAcquiredLine(wait) {
-	if (!wait.holder || wait.waitedMs <= 0) return phaseLine("lock", "acquired");
-	return phaseLine("lock", `acquired (waited ${formatElapsed(wait.waitedMs)} for ${warmCommand(wait.holder.phase)} pid ${wait.holder.pid}) -- stim guide lifecycle options`);
-}
-function warmClaimUnavailableLine(reason) {
-	return phaseLine("lock", `unavailable (${reason}); copying without it`);
-}
-/**
-* The reason a copy may proceed without the claim, or null when it must refuse. Plain `warm` worked on an
-* unwritable STIM_HOME before any claim existed and only reads, so the states in which no claim can be
-* recorded at all degrade to an unsynchronised copy: no process identity, a claim store the filesystem
-* rejects, and a claim store whose own path holds a file. A claim record Stim cannot resolve and a wait
-* that ran out are refusals: neither state can exist unless the claim does, so refusing them takes
-* nothing away.
-*/
-function warmClaimDegradation(error) {
-	if (isClaimUnavailable(error)) return error.message;
-	if (isClaimRefusal(error)) return error.reason === "the claim path is a file, not a claim directory" ? `${error.claimPath}: ${error.reason}` : null;
-	const code = error?.code;
-	if (typeof code === "string" && code.startsWith("STIM_")) return null;
-	return error?.message ?? String(error);
-}
-/**
-* What a copy that could not record a claim of its own would overlap if it went ahead anyway. Reading the
-* claim set classifies without writing anything and without refusing, so it works in exactly the states
-* that made the claim unrecordable -- a read-only STIM_HOME included. It is a read before a copy rather
-* than a held claim, so a refresh that starts after it is not covered; it closes the window in which one
-* is already installing, which is the window a refresh actually occupies.
-*/
-function warmClaimBlocker(repositoryRoot) {
-	const survey = readClaimSet(warmClaimPath(repositoryRoot));
-	const refresh = survey.live.find((holder) => holder.mode === "exclusive");
-	if (refresh) return {
-		kind: "refresh",
-		holder: asHolder(refresh)
-	};
-	const unresolved = survey.unresolved.find((problem) => problem.path.endsWith(".claim"));
-	if (unresolved) return {
-		kind: "unresolved",
-		path: unresolved.path,
-		reason: unresolved.reason
-	};
-	return null;
-}
-function warmClaimBlockedLine(reason, blocker) {
-	const what = blocker.kind === "refresh" ? `${warmCommand(blocker.holder.phase)} (pid ${blocker.holder.pid}) holds this repository` : `a claim at ${blocker.path} cannot be resolved: ${blocker.reason}`;
-	return phaseLine("lock", `unavailable (${reason}); ${what}`);
-}
-function warmClaimBlockedRefusal(blocker) {
-	if (blocker.kind === "refresh") return "Refusing to copy from a source checkout a refresh is rewriting, even without a claim of its own. Wait for that refresh to finish, then run warm again.";
-	return `Refusing to copy past a claim Stim cannot resolve. If nothing is warming, remove it and run warm again:\n  ${claimRemoveCommand(blocker.path)}`;
+function warmClaimAcquiredLine(wait, detail = "") {
+	const acquired = `acquired${detail ? ` ${detail}` : ""}`;
+	if (!wait.holder || wait.waitedMs < 1e3) return phaseLine("lock", acquired);
+	return phaseLine("lock", `${acquired} (waited ${formatElapsed(wait.waitedMs)} for ${warmCommand(wait.holder.phase)} pid ${wait.holder.pid}) -- stim guide lifecycle options`);
 }
 function installerWaitingLine(pid, elapsedMs) {
 	return phaseLine("lock", `waiting on the install this refresh spawned (pid ${pid}, ${formatElapsed(elapsedMs)} elapsed) -- stim guide lifecycle options`);
@@ -183,7 +136,7 @@ function timeoutError(holder, elapsedMs, root) {
 	error.code = "STIM_LOCK_TIMEOUT";
 	return error;
 }
-async function acquireWarmClaim({ repositoryRoot, phase, now = Date.now, sleep = defaultSleep, pollMs = WARM_CLAIM_POLL_MS, progressMs = WARM_CLAIM_PROGRESS_MS, ceilingMs = WARM_CLAIM_CEILING_MS, out = () => {} }) {
+async function acquireWarmClaim({ repositoryRoot, phase, mode = phase === "refresh" ? "exclusive" : "shared", now = Date.now, sleep = defaultSleep, pollMs = WARM_CLAIM_POLL_MS, progressMs = WARM_CLAIM_PROGRESS_MS, ceilingMs = WARM_CLAIM_CEILING_MS, out = () => {} }) {
 	const root = warmClaimPath(repositoryRoot);
 	const started = now();
 	let lastProgress = started;
@@ -193,7 +146,7 @@ async function acquireWarmClaim({ repositoryRoot, phase, now = Date.now, sleep =
 		for (;;) {
 			const attempt = pending ? settleClaim(pending) : tryAcquireClaim({
 				root,
-				mode: phase === "refresh" ? "exclusive" : "shared",
+				mode,
 				label: WARM_CLAIM_LABEL
 			});
 			const acquired = attempt.acquired;
@@ -228,6 +181,12 @@ async function acquireWarmClaim({ repositoryRoot, phase, now = Date.now, sleep =
 		}
 	} catch (error) {
 		releaseClaim(pending);
+		if ([
+			"EACCES",
+			"EPERM",
+			"EROFS",
+			"ENOENT"
+		].includes(error?.code ?? "")) throw new ClaimUnavailableError(error.message, { claimPath: root });
 		throw error;
 	}
 }
@@ -521,6 +480,38 @@ function branchRemote(root, branch) {
 		`branch.${branch}.remote`
 	])?.trim() || "origin";
 }
+function remoteUpstreamIsCurrent(root, branch) {
+	const exec = getExecutor();
+	const merge = exec.runFileQuiet("git", [
+		"-C",
+		root,
+		"config",
+		"--get-all",
+		`branch.${branch}.merge`
+	])?.trim();
+	if (!merge) return true;
+	if (!merge.startsWith("refs/") || merge.includes("\n")) return false;
+	const remote = branchRemote(root, branch);
+	if (remote === ".") return true;
+	const local = resolveFullRef(root, "@{upstream}");
+	if (!local) return false;
+	const advertised = exec.runFileQuiet("git", [
+		"-C",
+		root,
+		"ls-remote",
+		"--exit-code",
+		"--refs",
+		"--",
+		remote,
+		merge
+	], {
+		timeoutMs: FETCH_TIMEOUT_MS,
+		env: { GIT_TERMINAL_PROMPT: "0" }
+	});
+	if (advertised === null) return false;
+	const refs = advertised.trim().split("\n").map((line) => line.split(/\s+/));
+	return refs.length === 1 && refs[0]?.[0] === local && refs[0]?.[1] === merge;
+}
 function gitPath(...parts) {
 	return parts.filter((part) => part && part !== ".").join("/");
 }
@@ -603,7 +594,7 @@ function fastForward(root, upstream) {
 		};
 	}
 }
-async function refreshMainCheckout({ root, appDir, settings, emit, spawnFn = null, now = Date.now, heartbeatMs = HEARTBEAT_INTERVAL_MS, installer = NO_INSTALLER_CLAIM }) {
+async function refreshMainCheckout({ root, appDir, settings, emit, spawnFn = null, now = Date.now, heartbeatMs = HEARTBEAT_INTERVAL_MS, installer = NO_INSTALLER_CLAIM, inspectOnly = false }) {
 	const state = readMainCheckoutState(root);
 	const refusal = mainCheckoutRefusal(root, state);
 	if (refusal) return refusal;
@@ -640,7 +631,9 @@ async function refreshMainCheckout({ root, appDir, settings, emit, spawnFn = nul
 		};
 	};
 	const before = resolveFullRef(root, "HEAD") ?? "";
-	if (getExecutor().runFileQuiet("git", [
+	if (inspectOnly) {
+		if (!remoteUpstreamIsCurrent(root, branch)) return { mutation: "fetch upstream" };
+	} else if (getExecutor().runFileQuiet("git", [
 		"-C",
 		root,
 		"fetch",
@@ -652,6 +645,7 @@ async function refreshMainCheckout({ root, appDir, settings, emit, spawnFn = nul
 	}) === null) emit(phaseLine("checkout", "could not fetch; continuing with the local state"));
 	const plan = checkoutPlan(locallyKnownUpstream(root));
 	if (plan.kind === "diverged") return divergedRefusal(root, branch, plan);
+	if (inspectOnly && plan.kind === "fast-forward") return { mutation: `fast-forward ${plan.behind} commit${plan.behind === 1 ? "" : "s"}` };
 	const depsBefore = dependencyState(existsSync(appDir) ? appDir : root);
 	const priorInstall = depsBefore ? readInstallEvidence(depsBefore.root) : null;
 	const marked = plan.kind === "fast-forward" ? depsBefore : null;
@@ -683,6 +677,7 @@ async function refreshMainCheckout({ root, appDir, settings, emit, spawnFn = nul
 	});
 	const depsSubject = `source ${dependencies?.root ?? root}: ${deps.reason}`;
 	if (deps.run && dependencies) {
+		if (inspectOnly) return { mutation: deps.reason };
 		writeInstallEvidence(dependencies.root, dependencies.lock, consumed, false);
 		const install = await runInstallCommand({
 			command: dependencies.command,
@@ -719,6 +714,7 @@ async function refreshMainCheckout({ root, appDir, settings, emit, spawnFn = nul
 		emit(stepLine("pods", `${where}${pods.reason}`, "skipped"));
 		return null;
 	}
+	if (inspectOnly) return { mutation: pods.reason };
 	const result = await runPodInstall(appDir, null, {
 		spawnFn: spawn,
 		now,
@@ -793,31 +789,6 @@ function registerWarm(worktree) {
 				for (const key of unknownSettingKeys(settings)) console.error(chalk.yellow(`Warning: setting "${key}" is not read by Stim and will be ignored.`));
 				return settings;
 			};
-			if (opts.refresh) {
-				const settings = readSettings();
-				if (!settings) {
-					process.exitCode = 1;
-					return;
-				}
-				const failure = await withWarmClaim({
-					repositoryRoot: root,
-					phase: "refresh",
-					out: console.error
-				}, (hold) => {
-					console.error(warmClaimAcquiredLine(hold.wait));
-					return refreshMainCheckout({
-						root,
-						appDir: mainCheckoutAppDir(root, target),
-						settings,
-						emit: (line) => console.error(line),
-						installer: hold.installer
-					});
-				});
-				if (failure) {
-					reportRefreshFailure(failure);
-					return;
-				}
-			}
 			const copy = (wait) => {
 				if (wait?.holder) console.error(warmClaimAcquiredLine(wait));
 				const incomplete = incompleteInstallRefusal(root, mainCheckoutAppDir(root, target));
@@ -846,30 +817,69 @@ function registerWarm(worktree) {
 				console.error(phaseLine("carry", `${result.failed.length ? "incomplete" : "complete"}: ${result.copied.length} ignored entries copied, ${result.skipped.length} kept, ${result.failed.length} failed`));
 				if (result.failed.length) process.exitCode = 1;
 			};
-			let hold = null;
-			try {
-				hold = await acquireWarmClaim({
+			if (opts.refresh) {
+				const inspect = await acquireWarmClaim({
 					repositoryRoot: root,
-					phase: "copy",
+					phase: "refresh",
+					mode: "shared",
 					out: console.error
 				});
-			} catch (error) {
-				const degraded = opts.refresh ? null : warmClaimDegradation(error);
-				if (degraded === null) throw error;
-				const blocker = warmClaimBlocker(root);
-				if (blocker) {
-					console.error(chalk.dim(warmClaimBlockedLine(degraded, blocker)));
-					console.error(chalk.red(warmClaimBlockedRefusal(blocker)));
-					throw error;
+				let mutation;
+				try {
+					const settings = readSettings();
+					if (!settings) {
+						process.exitCode = 1;
+						return;
+					}
+					const lines = [];
+					const result = await refreshMainCheckout({
+						root,
+						appDir: mainCheckoutAppDir(root, target),
+						settings,
+						emit: (line) => lines.push(line),
+						inspectOnly: true
+					});
+					if (!result || !("mutation" in result)) {
+						console.error(warmClaimAcquiredLine(inspect.wait, result ? "shared" : "shared (seed current)"));
+						for (const line of lines) console.error(line);
+						if (result) reportRefreshFailure(result);
+						else copy(null);
+						return;
+					}
+					mutation = result.mutation;
+				} finally {
+					inspect.release();
 				}
-				console.error(chalk.dim(warmClaimUnavailableLine(degraded)));
-			}
-			if (!hold) copy(null);
-			else try {
-				copy(hold.wait);
-			} finally {
-				hold.release();
+				const failure = await withWarmClaim({
+					repositoryRoot: root,
+					phase: "refresh",
+					out: console.error
+				}, async (hold) => {
+					console.error(warmClaimAcquiredLine(hold.wait, `exclusive (${mutation})`));
+					const settings = readSettings();
+					if (!settings) {
+						process.exitCode = 1;
+						return null;
+					}
+					return refreshMainCheckout({
+						root,
+						appDir: mainCheckoutAppDir(root, target),
+						settings,
+						emit: (line) => console.error(line),
+						installer: hold.installer
+					});
+				});
+				if (failure) {
+					reportRefreshFailure(failure);
+					return;
+				}
+				if (process.exitCode) return;
 			}
+			await withWarmClaim({
+				repositoryRoot: root,
+				phase: "copy",
+				out: console.error
+			}, (hold) => copy(hold.wait));
 		} catch (error) {
 			const code = error?.code;
 			console.error(chalk.red(`Could not warm this worktree: ${error.message}`));