@sayknow-cli/coding-agent 0.5.0 → 0.5.2

package/src/sdk/bus/lifecycle-control-runtime.ts

@@ -40,21 +40,27 @@ import {
 	resolveSkcTmuxCommand,
 } from "../../skc-runtime/tmux-common";
 import {
+	abandonIdentityCreate,
+	advanceIdentityCreatePhase,
 	captureOwnerGenerationBaseline,
 	classifyCgroup,
 	isExactScopedBootstrapSuccessReceipt,
 	type OwnerGenerationBaseline,
 	type OwnerIsolationProbe,
 	planTmuxOwnerIsolation,
+	releaseIdentityCreate,
 	replaceOwnerGeneration,
+	reserveIdentityCreate,
 	resolveManagedOwnerPredecessorSync,
 	type TmuxServerProof,
 } from "../../skc-runtime/tmux-owner-isolation";
 import {
+	abandonedIdentityCensus,
 	findSkcTmuxSessionByName,
 	forceCloseSkcTmuxSession,
 	listSkcTmuxSessions,
 	type SkcTmuxSessionStatus,
+	settleAbandonedIdentity,
 } from "../../skc-runtime/tmux-sessions";
 import type {
 	LifecycleErrorReason,
@@ -873,66 +879,103 @@ export function daemonSpawnCreate(
 		const { cwd, args } = buildCreateArgv(frame, ids);
 		const sessionStateFile = lifecycleRuntimeStateFile(cwd, ids.intendedSessionId, name);
 		const stateDir = path.dirname(sessionStateFile);
-		const previousBaseline = await captureOwnerGenerationBaseline(stateDir, ids.intendedSessionId);
-		const predecessor = resolveManagedOwnerPredecessorSync(stateDir, ids.intendedSessionId, previousBaseline);
-		const generation = crypto.randomUUID();
-		const runId = crypto.randomUUID();
-		const incarnation = crypto.randomUUID();
-		// Detached: no interactive TTY needed (daemon-safe). These values contain
-		// only opaque ids and paths needed by the resident sidecar to publish its
-		// exact-owner terminal verdict.
-		const childEnv: Record<string, string> = {
-			SKC_TMUX_LAUNCHED: "1",
-			SKC_NOTIFICATIONS: "1",
-			SKC_SESSION_ID: ids.intendedSessionId,
-			SKC_LIFECYCLE_REQUEST_ID: ids.lifecycleRequestId,
-			[SKC_COORDINATOR_SESSION_ID_ENV]: ids.intendedSessionId,
-			[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]: sessionStateFile,
-			[SKC_TMUX_OWNER_GENERATION_ENV]: generation,
-			[SKC_TMUX_OWNER_STATE_DIR_ENV]: stateDir,
-			[SKC_TMUX_OWNER_SERVER_KEY_ENV]: "default",
-			SKC_MANAGED_OWNER_COMMAND_JSON: JSON.stringify(["skc", ...args]),
-			[MANAGED_OWNER_RUN_ID_ENV]: runId,
-			[MANAGED_OWNER_INCARNATION_ENV]: incarnation,
-			...(predecessor
-				? {
-						[MANAGED_OWNER_PREDECESSOR_TOKEN_ENV]: predecessor.predecessorToken,
-						[MANAGED_OWNER_PREDECESSOR_GENERATION_ENV]: predecessor.generation,
-						[MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV]: predecessor.runId,
-						[MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV]: predecessor.incarnation,
-						[MANAGED_OWNER_TRANSCRIPT_PATH_ENV]: env.SKC_SESSION_FILE ?? "",
-					}
-				: {}),
-		};
-		if (ids.startupPromptRef) childEnv.SKC_STARTUP_PROMPT_REF = ids.startupPromptRef;
-		const envPairs = Object.entries(childEnv)
-			.map(([key, value]) => `${key}=${shellQuote(value)}`)
-			.join(" ");
-		const command = `cd ${shellQuote(cwd)} && exec env ${envPairs} skc ${shellQuote(MANAGED_OWNER_SUPERVISOR_ARG)}`;
-		await completeLifecycleSpawnTransaction({
-			tmux,
-			env,
-			sessionId: ids.intendedSessionId,
-			generation,
-			stateDir,
-			cwd,
-			sessionName: name,
-			sessionStateFile,
-			argv: [tmux, "new-session", "-d", "-P", "-F", "#{session_id}", "-s", name, "sh", "-c", command],
-			ownerIsolationProbe: opts.ownerIsolationProbe,
-			prepareSpawn: () => {
-				if (frame.target.kind === "plain_dir") fs.mkdirSync(cwd, { recursive: true });
-			},
-			previousBaseline,
-		});
+		// Shared identity create fence, before the final baseline capture and any
+		// spawn preparation. The SDK-bus producer is a separate implementation
+		// from the notification one and must acquire it in its own right.
+		const identityKey = { stateDir, sessionId: ids.intendedSessionId, stateFile: sessionStateFile };
+		const reserved = reserveIdentityCreate(identityKey);
+		// A dead previous owner that reached the helper may have left an untagged
+		// child. Resolve it authority-first instead of treating the row as a
+		// permanent collision, which would brick this identity forever.
+		const settled = settleAbandonedIdentity(
+			reserved,
+			identityKey,
+			abandonedIdentityCensus(tmux, env, sessionStateFile),
+		);
+		// Fail closed: an unreachable fence cannot honor the one-create guarantee.
+		if (!settled.ok) throw new Error(`skc_lifecycle_identity_create_${settled.code}:${settled.diagnostic}`);
+		let reservation = settled.reservation;
+		let cleanupUncertain = false;
+		try {
+			const previousBaseline = await captureOwnerGenerationBaseline(stateDir, ids.intendedSessionId);
+			const predecessor = resolveManagedOwnerPredecessorSync(stateDir, ids.intendedSessionId, previousBaseline);
+			const generation = crypto.randomUUID();
+			const runId = crypto.randomUUID();
+			const incarnation = crypto.randomUUID();
+			// Detached: no interactive TTY needed (daemon-safe). These values contain
+			// only opaque ids and paths needed by the resident sidecar to publish its
+			// exact-owner terminal verdict.
+			const childEnv: Record<string, string> = {
+				SKC_TMUX_LAUNCHED: "1",
+				SKC_NOTIFICATIONS: "1",
+				SKC_SESSION_ID: ids.intendedSessionId,
+				SKC_LIFECYCLE_REQUEST_ID: ids.lifecycleRequestId,
+				[SKC_COORDINATOR_SESSION_ID_ENV]: ids.intendedSessionId,
+				[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]: sessionStateFile,
+				[SKC_TMUX_OWNER_GENERATION_ENV]: generation,
+				[SKC_TMUX_OWNER_STATE_DIR_ENV]: stateDir,
+				[SKC_TMUX_OWNER_SERVER_KEY_ENV]: "default",
+				SKC_MANAGED_OWNER_COMMAND_JSON: JSON.stringify(["skc", ...args]),
+				[MANAGED_OWNER_RUN_ID_ENV]: runId,
+				[MANAGED_OWNER_INCARNATION_ENV]: incarnation,
+				...(predecessor
+					? {
+							[MANAGED_OWNER_PREDECESSOR_TOKEN_ENV]: predecessor.predecessorToken,
+							[MANAGED_OWNER_PREDECESSOR_GENERATION_ENV]: predecessor.generation,
+							[MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV]: predecessor.runId,
+							[MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV]: predecessor.incarnation,
+							[MANAGED_OWNER_TRANSCRIPT_PATH_ENV]: env.SKC_SESSION_FILE ?? "",
+						}
+					: {}),
+			};
+			if (ids.startupPromptRef) childEnv.SKC_STARTUP_PROMPT_REF = ids.startupPromptRef;
+			const envPairs = Object.entries(childEnv)
+				.map(([key, value]) => `${key}=${shellQuote(value)}`)
+				.join(" ");
+			const command = `cd ${shellQuote(cwd)} && exec env ${envPairs} skc ${shellQuote(MANAGED_OWNER_SUPERVISOR_ARG)}`;
+			// Record the attempt name BEFORE anything can spawn. Without this the
+			// reservation stays at `reserved`, and a successor would read a crash
+			// here as "no child can exist" and reclaim an identity that already
+			// has an untagged child.
+			reservation =
+				advanceIdentityCreatePhase(reservation, "helper_invoked", { attemptSessionName: name }) ??
+				(() => {
+					throw new Error("skc_lifecycle_identity_create_fence_lost");
+				})();
+			await completeLifecycleSpawnTransaction({
+				tmux,
+				env,
+				sessionId: ids.intendedSessionId,
+				generation,
+				stateDir,
+				cwd,
+				sessionName: name,
+				sessionStateFile,
+				argv: [tmux, "new-session", "-d", "-P", "-F", "#{session_id}", "-s", name, "sh", "-c", command],
+				ownerIsolationProbe: opts.ownerIsolationProbe,
+				prepareSpawn: () => {
+					if (frame.target.kind === "plain_dir") fs.mkdirSync(cwd, { recursive: true });
+				},
+				previousBaseline,
+			});
 
-		return {
-			sessionId: ids.intendedSessionId,
-			tmuxSession: name,
-			sessionStateFile,
-			endpointUrl: "",
-			topicThreadId: "",
-		};
+			return {
+				sessionId: ids.intendedSessionId,
+				tmuxSession: name,
+				sessionStateFile,
+				endpointUrl: "",
+				topicThreadId: "",
+			};
+		} catch (error) {
+			// `skc_lifecycle_cleanup_uncertain` means a child may survive that we
+			// could not remove. Keep the reservation so its evidence outlives us.
+			if (error instanceof AggregateError && /cleanup_uncertain/.test(String(error.message)))
+				cleanupUncertain = true;
+			throw error;
+		} finally {
+			if (cleanupUncertain) abandonIdentityCreate(reservation);
+			else releaseIdentityCreate(reservation);
+		}
 	};
 }
 
@@ -1086,58 +1129,94 @@ export function daemonResumeSession(
 		const name = tmuxSessionNameFor(resumeId);
 		const sessionStateFile = lifecycleRuntimeStateFile(resolvedResumeCwd, resumeId, name);
 		const stateDir = path.dirname(sessionStateFile);
-		const previousBaseline = await captureOwnerGenerationBaseline(stateDir, resumeId);
-		const predecessor = resolveManagedOwnerPredecessorSync(stateDir, resumeId, previousBaseline);
-		const generation = crypto.randomUUID();
-		const runId = crypto.randomUUID();
-		const incarnation = crypto.randomUUID();
-		const childEnv: Record<string, string> = {
-			SKC_TMUX_LAUNCHED: "1",
-			SKC_NOTIFICATIONS: "1",
-			[SKC_COORDINATOR_SESSION_ID_ENV]: resumeId,
-			[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]: sessionStateFile,
-			[SKC_TMUX_OWNER_GENERATION_ENV]: generation,
-			[SKC_TMUX_OWNER_STATE_DIR_ENV]: stateDir,
-			[SKC_TMUX_OWNER_SERVER_KEY_ENV]: "default",
-			SKC_MANAGED_OWNER_COMMAND_JSON: JSON.stringify(["skc", "--resume", resumeId]),
-			[MANAGED_OWNER_RUN_ID_ENV]: runId,
-			[MANAGED_OWNER_INCARNATION_ENV]: incarnation,
-			...(predecessor
-				? {
-						[MANAGED_OWNER_PREDECESSOR_TOKEN_ENV]: predecessor.predecessorToken,
-						[MANAGED_OWNER_PREDECESSOR_GENERATION_ENV]: predecessor.generation,
-						[MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV]: predecessor.runId,
-						[MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV]: predecessor.incarnation,
-						[MANAGED_OWNER_TRANSCRIPT_PATH_ENV]: env.SKC_SESSION_FILE ?? "",
-					}
-				: {}),
-		};
-		const envPairs = Object.entries(childEnv)
-			.map(([key, value]) => `${key}=${shellQuote(value)}`)
-			.join(" ");
-		const command = `cd ${shellQuote(resolvedResumeCwd)} && exec env ${envPairs} skc ${shellQuote(MANAGED_OWNER_SUPERVISOR_ARG)}`;
-		await completeLifecycleSpawnTransaction({
-			tmux,
-			env,
-			sessionId: resumeId,
-			generation,
-			stateDir,
-			cwd: resolvedResumeCwd,
-			sessionName: name,
-			sessionStateFile,
-			argv: [tmux, "new-session", "-d", "-P", "-F", "#{session_id}", "-s", name, "sh", "-c", command],
-			ownerIsolationProbe: opts.ownerIsolationProbe,
-			previousBaseline,
-		});
+		// Same shared fence: the cold restart reuses the historical id, so it can
+		// collide with a restore of that exact identity.
+		const identityKey = { stateDir, sessionId: resumeId, stateFile: sessionStateFile };
+		const reserved = reserveIdentityCreate(identityKey);
+		// A dead previous owner that reached the helper may have left an untagged
+		// child. Resolve it authority-first instead of treating the row as a
+		// permanent collision, which would brick this identity forever.
+		const settled = settleAbandonedIdentity(
+			reserved,
+			identityKey,
+			abandonedIdentityCensus(tmux, env, sessionStateFile),
+		);
+		// Fail closed: an unreachable fence cannot honor the one-create guarantee.
+		if (!settled.ok) throw new Error(`skc_lifecycle_identity_create_${settled.code}:${settled.diagnostic}`);
+		let reservation = settled.reservation;
+		let cleanupUncertain = false;
+		try {
+			const previousBaseline = await captureOwnerGenerationBaseline(stateDir, resumeId);
+			const predecessor = resolveManagedOwnerPredecessorSync(stateDir, resumeId, previousBaseline);
+			const generation = crypto.randomUUID();
+			const runId = crypto.randomUUID();
+			const incarnation = crypto.randomUUID();
+			const childEnv: Record<string, string> = {
+				SKC_TMUX_LAUNCHED: "1",
+				SKC_NOTIFICATIONS: "1",
+				[SKC_COORDINATOR_SESSION_ID_ENV]: resumeId,
+				[SKC_COORDINATOR_SESSION_STATE_FILE_ENV]: sessionStateFile,
+				[SKC_TMUX_OWNER_GENERATION_ENV]: generation,
+				[SKC_TMUX_OWNER_STATE_DIR_ENV]: stateDir,
+				[SKC_TMUX_OWNER_SERVER_KEY_ENV]: "default",
+				SKC_MANAGED_OWNER_COMMAND_JSON: JSON.stringify(["skc", "--resume", resumeId]),
+				[MANAGED_OWNER_RUN_ID_ENV]: runId,
+				[MANAGED_OWNER_INCARNATION_ENV]: incarnation,
+				...(predecessor
+					? {
+							[MANAGED_OWNER_PREDECESSOR_TOKEN_ENV]: predecessor.predecessorToken,
+							[MANAGED_OWNER_PREDECESSOR_GENERATION_ENV]: predecessor.generation,
+							[MANAGED_OWNER_PREDECESSOR_RUN_ID_ENV]: predecessor.runId,
+							[MANAGED_OWNER_PREDECESSOR_INCARNATION_ENV]: predecessor.incarnation,
+							[MANAGED_OWNER_TRANSCRIPT_PATH_ENV]: env.SKC_SESSION_FILE ?? "",
+						}
+					: {}),
+			};
+			const envPairs = Object.entries(childEnv)
+				.map(([key, value]) => `${key}=${shellQuote(value)}`)
+				.join(" ");
+			const command = `cd ${shellQuote(resolvedResumeCwd)} && exec env ${envPairs} skc ${shellQuote(MANAGED_OWNER_SUPERVISOR_ARG)}`;
+			// Record the attempt name BEFORE anything can spawn. Without this the
+			// reservation stays at `reserved`, and a successor would read a crash
+			// here as "no child can exist" and reclaim an identity that already
+			// has an untagged child.
+			reservation =
+				advanceIdentityCreatePhase(reservation, "helper_invoked", { attemptSessionName: name }) ??
+				(() => {
+					throw new Error("skc_lifecycle_identity_create_fence_lost");
+				})();
+			await completeLifecycleSpawnTransaction({
+				tmux,
+				env,
+				sessionId: resumeId,
+				generation,
+				stateDir,
+				cwd: resolvedResumeCwd,
+				sessionName: name,
+				sessionStateFile,
+				argv: [tmux, "new-session", "-d", "-P", "-F", "#{session_id}", "-s", name, "sh", "-c", command],
+				ownerIsolationProbe: opts.ownerIsolationProbe,
+				previousBaseline,
+			});
 
-		return {
-			sessionId: resumeId,
-			tmuxSession: name,
-			sessionStateFile,
-			endpointUrl: "",
-			topicThreadId: "",
-			mode: "cold_restarted",
-		};
+			return {
+				sessionId: resumeId,
+				tmuxSession: name,
+				sessionStateFile,
+				endpointUrl: "",
+				topicThreadId: "",
+				mode: "cold_restarted",
+			};
+		} catch (error) {
+			// `skc_lifecycle_cleanup_uncertain` means a child may survive that we
+			// could not remove. Keep the reservation so its evidence outlives us.
+			if (error instanceof AggregateError && /cleanup_uncertain/.test(String(error.message)))
+				cleanupUncertain = true;
+			throw error;
+		} finally {
+			if (cleanupUncertain) abandonIdentityCreate(reservation);
+			else releaseIdentityCreate(reservation);
+		}
 	};
 }
 

package/src/session/agent-session.ts

@@ -1547,6 +1547,27 @@ type SessionAdmissionLease = {
 	release(): void;
 };
 
+const TODO_WRITE_INFRASTRUCTURE_ERROR =
+	/(?:HTTP2StreamReset|ECONNRESET|ECONNREFUSED|ETIMEDOUT|network error|transport error|connection reset|stream reset|timed out|timeout|fetching https?:)/iu;
+const TODO_WRITE_ERROR_CONTEXT_LIMIT = 1_000;
+
+export function buildTodoWriteFailureReminder(errorText: string | undefined, failureCount: number): string {
+	const normalizedError = errorText?.trim().slice(0, TODO_WRITE_ERROR_CONTEXT_LIMIT);
+	const shouldRetry =
+		failureCount === 1 && (!normalizedError || !TODO_WRITE_INFRASTRUCTURE_ERROR.test(normalizedError));
+	const directive = shouldRetry
+		? "Correct the todo_write payload and retry once with a minimal argument object. If that retry fails, do not call todo_write again in this user turn; continue the requested work using a checklist in reasoning."
+		: "Do not call todo_write again in this user turn. Continue the requested work now, track the remaining steps in reasoning, and report progress directly.";
+
+	return [
+		"<system-reminder>",
+		"todo_write failed, so todo progress is not visible to the user.",
+		normalizedError ? `Failure: ${normalizedError}` : "Failure: todo_write returned an error.",
+		directive,
+		"</system-reminder>",
+	].join("\n");
+}
+
 export class AgentSession {
 	readonly agent: Agent;
 	readonly sessionManager: SessionManager;
@@ -1740,6 +1761,7 @@ export class AgentSession {
 	#fallbackInvocationId = 0;
 	// Todo completion reminder state
 	#todoReminderCount = 0;
+	#todoWriteFailureCount = 0;
 	#deepInterviewUserIntentEpoch = 0;
 	#deepInterviewTurnOwnerEpoch = 0;
 	#deepInterviewGenuineUserMessageEpochs = new WeakMap<object, number>();
@@ -3794,24 +3816,21 @@ export class AgentSession {
 				if (toolName === "edit" && details?.path) {
 					this.#invalidateFileCacheForPath(details.path);
 				}
-				if (toolName === "todo_write" && !isError && Array.isArray(details?.phases)) {
-					this.setTodoPhases(details.phases);
+				if (toolName === "todo_write" && !isError) {
+					this.#todoWriteFailureCount = 0;
+					if (Array.isArray(details?.phases)) {
+						this.setTodoPhases(details.phases);
+					}
 				}
 				if (toolName === "todo_write" && isError) {
+					this.#todoWriteFailureCount++;
 					const errorText = content?.find(part => part.type === "text")?.text;
-					const reminderText = [
-						"<system-reminder>",
-						"todo_write failed, so todo progress is not visible to the user.",
-						errorText ? `Failure: ${errorText}` : "Failure: todo_write returned an error.",
-						"Fix the todo payload and call todo_write again before continuing.",
-						"</system-reminder>",
-					].join("\n");
 					await this.sendCustomMessage(
 						{
 							customType: "todo-write-error-reminder",
-							content: reminderText,
+							content: buildTodoWriteFailureReminder(errorText, this.#todoWriteFailureCount),
 							display: false,
-							details: { toolName, errorText },
+							details: { toolName, errorText, failureCount: this.#todoWriteFailureCount },
 						},
 						{ deliverAs: "nextTurn" },
 					);
@@ -7793,6 +7812,7 @@ export class AgentSession {
 				this.#defaultFallbackChain().resetAttemptBudget();
 				this.#overflowMaintenanceAttempts = 0;
 				this.#throwIfPromptPreflightCancelled(generation, preflightSignal);
+				this.#todoWriteFailureCount = 0;
 			}
 			// Flush any pending bash messages before the new prompt
 			this.#flushPendingBashMessages();

package/src/skc-runtime/boot-generation.ts

@@ -0,0 +1,172 @@
+/**
+ * Boot-generation evidence for reboot-only session restore.
+ *
+ * Restore exists to survive a reboot, and only a reboot. The eligibility rule is
+ * therefore narrow on purpose: a session may be restored only when the recorded
+ * and current boot values come from the SAME source and differ. Anything else —
+ * equal values, a missing or malformed record, an unreadable probe, or two
+ * different sources — is inconclusive and must never spawn.
+ *
+ * The same-source requirement is not pedantry. Linux can report `boot-id` at
+ * record time and fall back to `proc-btime` later; those two values are always
+ * unequal even on one boot, so comparing across sources would read every launch
+ * as a reboot and duplicate live sessions.
+ */
+
+import * as fsSync from "node:fs";
+
+/** Where a boot value came from. Values are only ever compared within one source. */
+export type BootGenerationSource = "darwin-kern-boottime" | "linux-boot-id" | "linux-proc-btime" | "unavailable";
+
+export interface BootGeneration {
+	source: BootGenerationSource;
+	/** Opaque; only equality within the same source is meaningful. */
+	value: string | null;
+}
+
+export type BootComparison = "changed" | "same_boot" | "boot_unknown";
+
+const BOOT_GENERATION_SCHEMA_VERSION = 1;
+
+export interface RecordedBootGeneration {
+	schema_version: number;
+	source: string;
+	value: string;
+}
+
+export interface BootGenerationProbeDeps {
+	platform?: NodeJS.Platform;
+	readFile?: (file: string) => string;
+	runCommand?: (command: string, args: string[]) => { exitCode: number | null; stdout: string };
+}
+
+function defaultReadFile(file: string): string {
+	return fsSync.readFileSync(file, "utf8");
+}
+
+function defaultRunCommand(command: string, args: string[]): { exitCode: number | null; stdout: string } {
+	const result = Bun.spawnSync({ cmd: [command, ...args], stdout: "pipe", stderr: "ignore" });
+	return { exitCode: result.exitCode, stdout: result.stdout.toString() };
+}
+
+/** `{ sec = 1785305532, usec = 377197 } Wed Jul 29 ...` -> `1785305532.377197`. */
+export function parseDarwinBootTime(raw: string): string | null {
+	const match = /sec\s*=\s*(\d+)\s*,\s*usec\s*=\s*(\d+)/u.exec(raw);
+	if (!match) return null;
+	const sec = match[1];
+	const usec = match[2];
+	if (!sec || !usec) return null;
+	// A microsecond field at or above 1e6 is not a time this kernel produced;
+	// accepting it would let a malformed reading masquerade as a distinct boot.
+	if (Number.parseInt(usec, 10) >= 1_000_000) return null;
+	return `${sec}.${usec.padStart(6, "0")}`;
+}
+
+/** A boot id is a UUID that changes on every boot; anything else is not usable. */
+export function parseLinuxBootId(raw: string): string | null {
+	const value = raw.trim();
+	return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(value) ? value : null;
+}
+
+/** `/proc/stat` carries `btime <seconds>` once, as the kernel boot wall-clock. */
+export function parseLinuxProcBtime(raw: string): string | null {
+	const values: string[] = [];
+	for (const line of raw.split("\n")) {
+		const match = /^btime\s+(\d+)\s*$/u.exec(line);
+		if (match?.[1]) values.push(match[1]);
+	}
+	// The kernel reports btime exactly once. More than one means the input is not
+	// a `/proc/stat` we can reason about, so refuse rather than pick one.
+	return values.length === 1 ? (values[0] ?? null) : null;
+}
+
+/**
+ * Reads the strongest boot evidence this platform offers.
+ *
+ * Windows returns `unavailable`: restore is unsupported there (no immutable
+ * native tmux session identity), so there is nothing to gate.
+ */
+export function readBootGeneration(deps: BootGenerationProbeDeps = {}): BootGeneration {
+	const platform = deps.platform ?? process.platform;
+	const readFile = deps.readFile ?? defaultReadFile;
+	const runCommand = deps.runCommand ?? defaultRunCommand;
+
+	if (platform === "darwin") {
+		try {
+			const probed = runCommand("sysctl", ["-n", "kern.boottime"]);
+			if (probed.exitCode !== 0) return { source: "unavailable", value: null };
+			const value = parseDarwinBootTime(probed.stdout);
+			return value ? { source: "darwin-kern-boottime", value } : { source: "unavailable", value: null };
+		} catch {
+			return { source: "unavailable", value: null };
+		}
+	}
+
+	if (platform === "linux") {
+		try {
+			const value = parseLinuxBootId(readFile("/proc/sys/kernel/random/boot_id"));
+			if (value) return { source: "linux-boot-id", value };
+		} catch {
+			// Fall through: some hardened kernels hide boot_id.
+		}
+		try {
+			const value = parseLinuxProcBtime(readFile("/proc/stat"));
+			if (value) return { source: "linux-proc-btime", value };
+		} catch {
+			// Fall through to unavailable.
+		}
+		return { source: "unavailable", value: null };
+	}
+
+	return { source: "unavailable", value: null };
+}
+
+/**
+ * Each source produces one exact shape. Validating it is what stops a value that
+ * merely differs textually — trailing space, a zero-width character — from being
+ * read as a different boot.
+ */
+const BOOT_VALUE_SHAPE: Record<string, RegExp> = {
+	"darwin-kern-boottime": /^\d+\.\d{6}$/u,
+	"linux-boot-id": /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u,
+	"linux-proc-btime": /^\d+$/u,
+};
+
+export function isBootValueWellFormed(source: string, value: string): boolean {
+	return BOOT_VALUE_SHAPE[source]?.test(value) ?? false;
+}
+
+export function isRecordedBootGeneration(value: unknown): value is RecordedBootGeneration {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		record.schema_version === BOOT_GENERATION_SCHEMA_VERSION &&
+		typeof record.source === "string" &&
+		record.source.length > 0 &&
+		record.source !== "unavailable" &&
+		typeof record.value === "string" &&
+		record.value.length > 0 &&
+		isBootValueWellFormed(record.source, record.value)
+	);
+}
+
+export function recordBootGeneration(current: BootGeneration): RecordedBootGeneration | null {
+	if (current.source === "unavailable" || !current.value) return null;
+	if (!isBootValueWellFormed(current.source, current.value)) return null;
+	return { schema_version: BOOT_GENERATION_SCHEMA_VERSION, source: current.source, value: current.value };
+}
+
+/**
+ * Decides whether the machine rebooted since the session was recorded.
+ *
+ * `changed` is the ONLY executable answer. It requires a well-formed record, a
+ * readable current probe, an identical source, and different values. Source
+ * mismatch is deliberately `boot_unknown` rather than `changed`.
+ */
+export function compareBootGeneration(recorded: unknown, current: BootGeneration): BootComparison {
+	if (!isRecordedBootGeneration(recorded)) return "boot_unknown";
+	if (current.source === "unavailable" || !current.value) return "boot_unknown";
+	if (!isBootValueWellFormed(current.source, current.value)) return "boot_unknown";
+	if (recorded.source !== current.source) return "boot_unknown";
+	return recorded.value === current.value ? "same_boot" : "changed";
+}