@gajae-code/coding-agent 0.10.1 → 0.11.0

package/src/sdk/broker/discovery.ts

@@ -0,0 +1,94 @@
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { processIncarnation } from "./process-incarnation";
+import { assertSupportedStateVersion, SDK_STATE_VERSION } from "./state-version";
+
+export const BROKER_HEARTBEAT_TTL_MS = 15_000;
+export interface BrokerDiscovery {
+	version: typeof SDK_STATE_VERSION;
+	protocolVersion: 3;
+	packageGeneration: string;
+	ownerId: string;
+	pid: number;
+	incarnation: string;
+	host: "127.0.0.1";
+	port: number;
+	url: string;
+	token: string;
+	startedAt: number;
+	heartbeatAt: number;
+}
+export type RedactedBrokerDiscovery = Omit<BrokerDiscovery, "token"> & { token: "[redacted]" };
+export type BrokerDiscoveryWrite = Omit<BrokerDiscovery, "incarnation"> & { incarnation?: string };
+export const brokerDiscoveryPath = (agentDir: string) => path.join(agentDir, "sdk", "broker.json");
+export const newBrokerToken = () => randomBytes(32).toString("hex");
+export const brokerProcessIncarnation = processIncarnation;
+export function isPidAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (e) {
+		return (e as NodeJS.ErrnoException).code === "EPERM";
+	}
+}
+async function syncFile(file: string): Promise<void> {
+	const handle = await fs.open(file, "r");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+export async function writeBrokerDiscovery(agentDir: string, discovery: BrokerDiscoveryWrite): Promise<void> {
+	const incarnation = discovery.incarnation ?? brokerProcessIncarnation(discovery.pid);
+	if (!incarnation) throw new Error(`Broker process incarnation is unavailable for pid ${discovery.pid}.`);
+	const record: BrokerDiscovery = { ...discovery, incarnation };
+	const file = brokerDiscoveryPath(agentDir);
+	const dir = path.dirname(file);
+	await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+	await fs.chmod(dir, 0o700);
+	const temp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		await fs.writeFile(temp, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+		await fs.chmod(temp, 0o600);
+		await syncFile(temp);
+		await fs.rename(temp, file);
+		await syncFile(dir);
+	} finally {
+		await fs.rm(temp, { force: true });
+	}
+}
+export async function readBrokerDiscovery(
+	agentDir: string,
+	ttlMs = BROKER_HEARTBEAT_TTL_MS,
+): Promise<BrokerDiscovery | null> {
+	try {
+		const raw: unknown = JSON.parse(await fs.readFile(brokerDiscoveryPath(agentDir), "utf8"));
+		if (!raw || typeof raw !== "object") return null;
+		assertSupportedStateVersion(brokerDiscoveryPath(agentDir), raw);
+		const d = raw as BrokerDiscovery;
+		if (
+			d.version !== SDK_STATE_VERSION ||
+			d.protocolVersion !== 3 ||
+			d.host !== "127.0.0.1" ||
+			!d.token ||
+			!Number.isSafeInteger(d.pid) ||
+			d.pid <= 0 ||
+			typeof d.incarnation !== "string" ||
+			d.incarnation.length === 0 ||
+			!Number.isFinite(d.heartbeatAt)
+		)
+			return null;
+		if (!isPidAlive(d.pid)) return null;
+		const incarnation = brokerProcessIncarnation(d.pid);
+		if (!incarnation || incarnation !== d.incarnation || Date.now() - d.heartbeatAt > ttlMs) return null;
+		return d;
+	} catch (e) {
+		if ((e as NodeJS.ErrnoException).code === "ENOENT" || e instanceof SyntaxError) return null;
+		throw e;
+	}
+}
+export function redactBrokerDiscovery(discovery: BrokerDiscovery): RedactedBrokerDiscovery {
+	return { ...discovery, token: "[redacted]" };
+}

package/src/sdk/broker/ensure.ts

@@ -0,0 +1,249 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { type BrokerDiscovery, brokerProcessIncarnation, readBrokerDiscovery } from "./discovery";
+import { resolveSdkInternalSpawnCommand, type SdkInternalSpawnCommand } from "./runtime";
+export interface EnsureBrokerSettings {
+	agentDir: string;
+	heartbeatTtlMs?: number;
+	/**
+	 * Environment for the spawned detached broker. Defaults to `process.env`; tests
+	 * that pre-start an isolated broker pass the same sanitized child env so the
+	 * broker and the child that attaches to it share one owned root.
+	 */
+	env?: NodeJS.ProcessEnv;
+}
+
+const DISCOVERY_TIMEOUT_MS = 10_000;
+// Bounded grace windows for reaping a spawned broker on failure, mirroring the
+// owned-process teardown convention (SIGTERM -> grace -> SIGKILL -> hard cap).
+const REAP_GRACEFUL_MS = 2_000;
+const REAP_SIGKILL_CAP_MS = 2_000;
+interface BrokerOwner {
+	stop(): Promise<void>;
+	canReuse(discovery: BrokerDiscovery | null): boolean;
+	markReady(discovery: BrokerDiscovery): boolean;
+}
+const owners = new Map<string, BrokerOwner>();
+const ensureInFlight = new Map<string, Promise<BrokerDiscovery>>();
+const reapErrorGuards = new WeakSet<ChildProcess>();
+interface ReapTiming {
+	gracefulMs: number;
+	killVerifyMs: number;
+}
+const DEFAULT_REAP_TIMING: ReapTiming = {
+	gracefulMs: REAP_GRACEFUL_MS,
+	killVerifyMs: REAP_SIGKILL_CAP_MS,
+};
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Terminate and reap a detached broker this process spawned, targeting the exact
+ * owned {@link ChildProcess} (never by name). SIGTERM escalates to SIGKILL after
+ * a bounded grace window; a child still alive after SIGKILL is surfaced rather
+ * than silently orphaned. Reaping is idempotent once the child has exited.
+ *
+ * Termination is proven only by an observed exit — an `exit`/`close` event or a
+ * non-null `exitCode`/`signalCode`. A still-live child can emit `error` during
+ * teardown (e.g. a transient signal-delivery failure); that is diagnostic only
+ * and never counts as exit, so the escalation cannot be skipped mid-shutdown.
+ */
+async function reapSpawnedBroker(child: ChildProcess, timing: ReapTiming = DEFAULT_REAP_TIMING): Promise<void> {
+	// A spawn failure (e.g. ENOENT) never created a kernel process: pid is
+	// undefined and there is nothing to signal or await. The `error` event is the
+	// only signal and is diagnostic here — termination trivially holds, so do not
+	// run out the TERM/KILL windows or report a stuck child that never existed.
+	if (child.pid === undefined) return;
+	// Reaping owns repeated teardown diagnostics too. Keep exactly one error
+	// listener for the retained child so a later signal-delivery error cannot
+	// become an unhandled EventEmitter error after the spawn listener is consumed.
+	if (!reapErrorGuards.has(child)) {
+		child.on("error", () => {});
+		reapErrorGuards.add(child);
+	}
+
+	// Awaits an authoritative exit signal, never a transient `error`. Resolves on
+	// an `exit`/`close` event or when the codes are already set; the caller
+	// re-checks the codes after the race, so resolution alone is never proof.
+	const awaitVerifiedExit = (): Promise<void> => {
+		const { promise, resolve } = Promise.withResolvers<void>();
+		if (child.exitCode !== null || child.signalCode !== null) resolve();
+		else {
+			child.once("exit", () => resolve());
+			child.once("close", () => resolve());
+		}
+		return promise;
+	};
+	// Observed exit is authoritative: only non-null exit/signal codes prove the
+	// child is gone, regardless of which event (if any) resolved the wait.
+	const hasExited = (): boolean => child.exitCode !== null || child.signalCode !== null;
+	const signal = (sig: NodeJS.Signals): void => {
+		if (hasExited()) return;
+		try {
+			child.kill(sig);
+		} catch {
+			// already exited between the liveness check and the kill
+		}
+	};
+	if (hasExited()) return;
+	signal("SIGTERM");
+	await Promise.race([awaitVerifiedExit(), sleep(timing.gracefulMs)]);
+	if (hasExited()) return;
+	signal("SIGKILL");
+	await Promise.race([awaitVerifiedExit(), sleep(timing.killVerifyMs)]);
+	if (hasExited()) return;
+	// SIGKILL is uninterruptible; a child still alive past this bounded wait is a
+	// kernel-level stuck state. Surface it rather than silently orphaning the spawn.
+	throw new Error(`Detached SDK broker (pid ${child.pid}) did not exit after SIGKILL during reap.`);
+}
+
+function registerBrokerOwner(
+	agentDir: string,
+	child: ChildProcess,
+	timing: ReapTiming = DEFAULT_REAP_TIMING,
+): BrokerOwner {
+	const incarnation = child.pid === undefined ? undefined : brokerProcessIncarnation(child.pid);
+	let state: "starting" | "ready" | "cleanup-unverified" = "starting";
+	const matches = (discovery: BrokerDiscovery | null): boolean =>
+		Boolean(
+			discovery &&
+				child.pid !== undefined &&
+				incarnation &&
+				discovery.pid === child.pid &&
+				discovery.incarnation === incarnation,
+		);
+	const owner: BrokerOwner = {
+		async stop(): Promise<void> {
+			try {
+				await reapSpawnedBroker(child, timing);
+			} catch (error) {
+				state = "cleanup-unverified";
+				throw error;
+			}
+			if (owners.get(agentDir) === owner) owners.delete(agentDir);
+		},
+		canReuse(discovery): boolean {
+			return state === "ready" && matches(discovery);
+		},
+		markReady(discovery): boolean {
+			if (!matches(discovery)) return false;
+			state = "ready";
+			return true;
+		},
+	};
+	owners.set(agentDir, owner);
+	return owner;
+}
+function brokerSpawnEnvironment(command: SdkInternalSpawnCommand, override?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const environment = { ...(override ?? command.env) };
+	delete environment.BUN_OPTIONS;
+	if (command.kind === "bun-source") {
+		delete environment.PI_COMPILED;
+		delete environment.GJC_COMPILED;
+	}
+	return environment;
+}
+
+async function ensureBrokerOnce(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
+	const priorOwner = owners.get(settings.agentDir);
+	const existing = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+	if (priorOwner) {
+		// A retained cleanup failure fences every discovery record. Only a ready
+		// record bound to this exact child incarnation may be reused.
+		if (priorOwner.canReuse(existing)) return existing!;
+		await priorOwner.stop();
+		const discoveredAfterCleanup = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+		if (discoveredAfterCleanup) return discoveredAfterCleanup;
+	} else if (existing) {
+		return existing;
+	}
+
+	const command = resolveSdkInternalSpawnCommand("broker-internal");
+	const child = spawn(command.file, [...command.args, "--agent-dir", settings.agentDir], {
+		detached: true,
+		stdio: "ignore",
+		env: brokerSpawnEnvironment(command, settings.env),
+		...(command.kind === "bun-source" ? { cwd: command.cwd } : {}),
+	});
+	child.unref();
+	let spawnError: Error | undefined;
+	child.once("error", error => {
+		spawnError = error;
+	});
+	const owner = registerBrokerOwner(settings.agentDir, child);
+	const deadline = Date.now() + DISCOVERY_TIMEOUT_MS;
+	let discoveryError: unknown;
+	while (Date.now() < deadline) {
+		// Fail fast: if the spawn failed or the child already exited, discovery can
+		// never succeed — stop (a no-op once dead) and surface the failure instead
+		// of running out the discovery timeout with an orphaned child.
+		if (spawnError || child.exitCode !== null || child.signalCode !== null) break;
+		try {
+			const discovered = await readBrokerDiscovery(settings.agentDir, settings.heartbeatTtlMs);
+			if (discovered) {
+				if (owner.markReady(discovered)) return discovered;
+				await owner.stop();
+				return discovered;
+			}
+		} catch (error) {
+			// A transient read failure (e.g. a half-written record) must not orphan the
+			// child; remember it and keep polling. It is surfaced if discovery fails.
+			discoveryError = error;
+		}
+		await sleep(50);
+	}
+	// Discovery failed (timeout, early child exit, spawn error, or unreadable
+	// discovery): the spawned broker never became reachable. Terminate and reap it
+	// so the failure cannot leave a detached orphan behind, then surface why.
+	const exitedBeforeDiscovery = child.exitCode !== null || child.signalCode !== null;
+	const failure = spawnError
+		? new Error(`Failed to spawn detached SDK broker: ${spawnError.message}`)
+		: exitedBeforeDiscovery
+			? new Error(
+					`Detached SDK broker exited before discovery (code=${child.exitCode}, signal=${child.signalCode}).`,
+				)
+			: discoveryError
+				? discoveryError
+				: new Error("Timed out waiting for detached SDK broker discovery.");
+	try {
+		await owner.stop();
+	} catch (cleanupError) {
+		throw new AggregateError([failure, cleanupError], "SDK broker discovery and spawned broker cleanup both failed.");
+	}
+	throw failure;
+}
+
+/** Starts the detached broker entrypoint when discovery has no live owner. */
+export function ensureBroker(settings: EnsureBrokerSettings): Promise<BrokerDiscovery> {
+	const existing = ensureInFlight.get(settings.agentDir);
+	if (existing) return existing;
+	const pending = ensureBrokerOnce(settings);
+	ensureInFlight.set(settings.agentDir, pending);
+	const clear = (): void => {
+		if (ensureInFlight.get(settings.agentDir) === pending) ensureInFlight.delete(settings.agentDir);
+	};
+	void pending.then(clear, clear);
+	return pending;
+}
+
+/** Test hook: returns a stop handle for the detached broker this process spawned. */
+export function brokerOwnerForTest(agentDir: string): BrokerOwner | undefined {
+	return owners.get(agentDir);
+}
+/** Test hook: drives the detached-broker reap on a controllable child surface. */
+export function reapSpawnedBrokerForTest(child: ChildProcess, timing: ReapTiming = DEFAULT_REAP_TIMING): Promise<void> {
+	return reapSpawnedBroker(child, timing);
+}
+/** Test hook: resolves the complete broker environment without spawning. */
+export function brokerSpawnEnvironmentForTest(
+	command: SdkInternalSpawnCommand,
+	override?: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv {
+	return brokerSpawnEnvironment(command, override);
+}
+/** Test hook: installs an exact controllable owner to exercise replacement fencing. */
+export function registerBrokerOwnerForTest(
+	agentDir: string,
+	child: ChildProcess,
+	timing: ReapTiming = DEFAULT_REAP_TIMING,
+): BrokerOwner {
+	return registerBrokerOwner(agentDir, child, timing);
+}

package/src/sdk/broker/identity.ts

@@ -0,0 +1,42 @@
+import { createHmac, randomBytes } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+
+const MODE = 0o600;
+
+export function brokerIdentityPath(agentDir: string): string {
+	return path.join(agentDir, "sdk", "broker.identity");
+}
+
+export async function getBrokerIdentityKey(agentDir: string): Promise<string> {
+	const file = brokerIdentityPath(agentDir);
+	await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+	try {
+		const key = (await fs.readFile(file, "utf8")).trim();
+		if (/^[0-9a-f]{64}$/i.test(key)) return key;
+		throw new Error(`Invalid broker identity key at ${file}`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		const key = randomBytes(32).toString("hex");
+		try {
+			await fs.writeFile(file, `${key}\n`, { encoding: "utf8", mode: MODE, flag: "wx" });
+			await fs.chmod(file, MODE);
+			return key;
+		} catch (writeError) {
+			if ((writeError as NodeJS.ErrnoException).code !== "EEXIST") throw writeError;
+			return getBrokerIdentityKey(agentDir);
+		}
+	}
+}
+
+export async function deriveIdempotencyIdentity(
+	agentDir: string,
+	operation: string,
+	callerKey: string,
+	canonicalTargetHash: string,
+): Promise<string> {
+	const key = await getBrokerIdentityKey(agentDir);
+	return createHmac("sha256", Buffer.from(key, "hex"))
+		.update(`3|${operation}|${callerKey}|${canonicalTargetHash}`)
+		.digest("hex");
+}

package/src/sdk/broker/index.ts

@@ -0,0 +1,8 @@
+export * from "./broker";
+export * from "./discovery";
+export * from "./ensure";
+export * from "./identity";
+export * from "./lifecycle";
+export * from "./lifecycle-ledger";
+export * from "./session-index";
+export * from "./transport";

package/src/sdk/broker/internal-source-marker-2178.txt

@@ -0,0 +1 @@
+gjc-sdk-broker-internal-source-marker-2178

package/src/sdk/broker/internal-source.bunfig.toml

@@ -0,0 +1 @@
+# Product-owned empty Bun configuration for isolated SDK-internal source children.

package/src/sdk/broker/lifecycle-ledger.ts

@@ -0,0 +1,286 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import type { SdkStartupFailure, SdkStartupRollbackResult } from "../startup-capability";
+import { assertSupportedStateVersion, SDK_STATE_VERSION } from "./state-version";
+
+export type LifecycleState =
+	| "accepted"
+	| "effect_started"
+	| "awaiting_ready"
+	| "terminal_ok"
+	| "terminal_error"
+	| "terminal_uncertain";
+export interface LifecycleWorktreeIntent {
+	repoRoot: string;
+	worktreePath: string;
+	detached: boolean;
+	baseRef: string;
+	branchName?: string;
+}
+
+export interface LifecycleEffectIntent {
+	sessionId: string;
+	stateRoot: string;
+	childOwnershipEstablished?: boolean;
+	worktree?: LifecycleWorktreeIntent;
+}
+
+/** Durable lifecycle effects retained for exact replay; never implies rollback authority. */
+export interface LifecycleCleanupProof {
+	processExited: true;
+	endpointRemoved: true;
+	hostUnregistered:
+		| { state: "unregistered"; indexSeq: number; lifecycleRequestId?: string }
+		| { state: "not_registered" };
+	rollback: {
+		endpointGeneration: number | null;
+		fenced: true;
+		runtimeRemoved: true;
+		hostStopped: true;
+		brokerRegistrationReleased: true;
+	};
+}
+
+export interface LifecycleStartupFailureReceipt extends SdkStartupFailure {
+	artifactDigest: string;
+	rollback: SdkStartupRollbackResult;
+	cleanupProof?: LifecycleCleanupProof;
+}
+
+export interface LifecycleDurableEffectsReceipt {
+	worktree?: {
+		cwdDigest: string;
+		created: boolean;
+		reused: boolean;
+		branchDigest?: string;
+	};
+	transcript?: {
+		identityDigest: string;
+		contentDigest: string;
+	};
+	startup?: LifecycleStartupFailureReceipt;
+	digest?: string;
+}
+
+export interface LifecycleLedgerEntry {
+	version: typeof SDK_STATE_VERSION;
+	identity: string;
+	requestHash: string;
+	state: LifecycleState;
+	intendedSessionId?: string;
+	resultSessionId?: string;
+	effectMarker?: string;
+	effectIntent?: LifecycleEffectIntent;
+	durableEffects?: LifecycleDurableEffectsReceipt;
+	startupFailure?: LifecycleStartupFailureReceipt;
+
+	endpointGeneration?: number;
+	responseDigest?: string;
+	response?: unknown;
+	ts: number;
+}
+export type BeginResult =
+	| { kind: "new"; entry: LifecycleLedgerEntry }
+	| { kind: "replay"; entry: LifecycleLedgerEntry }
+	| { kind: "idempotency_conflict" }
+	| { kind: "terminal_uncertain"; entry: LifecycleLedgerEntry }
+	| { kind: "in_progress"; entry: LifecycleLedgerEntry };
+const terminal = (s: LifecycleState) => s === "terminal_ok" || s === "terminal_error";
+function canonicalJson(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	const record = value as Record<string, unknown>;
+	return `{${Object.keys(record)
+		.sort()
+		.map(key => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+		.join(",")}}`;
+}
+
+function hasValidTerminalDigests(entry: LifecycleLedgerEntry): boolean {
+	if (!terminal(entry.state) && entry.state !== "terminal_uncertain") return true;
+	if (
+		(entry.state !== "terminal_uncertain" || entry.response !== undefined) &&
+		(entry.response === undefined ||
+			typeof entry.responseDigest !== "string" ||
+			entry.responseDigest !== createHash("sha256").update(canonicalJson(entry.response)).digest("hex"))
+	)
+		return false;
+	if (!entry.durableEffects) return true;
+	const { digest, ...body } = entry.durableEffects;
+	return typeof digest === "string" && digest === createHash("sha256").update(canonicalJson(body)).digest("hex");
+}
+export class LifecycleLedger {
+	#file: string;
+	#corruptFile: string;
+	#entries: LifecycleLedgerEntry[] = [];
+	#byIdentity = new Map<string, LifecycleLedgerEntry>();
+	#warnings: string[] = [];
+	constructor(agentDir: string) {
+		this.#file = path.join(agentDir, "sdk", "lifecycle-ledger.jsonl");
+		this.#corruptFile = `${this.#file}.corrupt`;
+	}
+	async open(): Promise<this> {
+		await this.assertSupportedStateVersions();
+		await fs.mkdir(path.dirname(this.#file), { recursive: true, mode: 0o700 });
+		this.#entries = [];
+		const quarantinedTerminal = new Set<string>();
+		this.#byIdentity.clear();
+		this.#warnings = [];
+		const uncertainAfterCorruption = new Set<string>();
+		let tornTail = false;
+		try {
+			const source = await fs.readFile(this.#file, "utf8");
+			tornTail = source.length > 0 && !source.endsWith("\n");
+			const lines = source.split("\n");
+			for (const line of lines) {
+				if (!line) continue;
+				try {
+					const e = JSON.parse(line) as LifecycleLedgerEntry;
+					assertSupportedStateVersion(this.#file, e);
+					if (!e.identity || !e.requestHash || !e.state) throw new Error("invalid ledger entry");
+					if (!hasValidTerminalDigests(e)) {
+						await this.#quarantine(line);
+						const {
+							response: _response,
+							responseDigest: _responseDigest,
+							durableEffects: _durableEffects,
+							...uncertain
+						} = e;
+						const quarantined = { ...uncertain, state: "terminal_uncertain" as const, ts: Date.now() };
+						this.#entries.push(quarantined);
+						this.#byIdentity.set(quarantined.identity, quarantined);
+						quarantinedTerminal.add(quarantined.identity);
+						continue;
+					}
+					this.#entries.push(e);
+					this.#byIdentity.set(e.identity, e);
+					uncertainAfterCorruption.delete(e.identity);
+				} catch {
+					for (const [identity, latest] of this.#byIdentity) {
+						if (!terminal(latest.state) && latest.state !== "terminal_uncertain")
+							uncertainAfterCorruption.add(identity);
+					}
+					await this.#quarantine(line);
+				}
+			}
+		} catch (e) {
+			if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+		}
+		if (tornTail) await this.#sealTornTail();
+		for (const identity of quarantinedTerminal) {
+			const entry = this.#byIdentity.get(identity);
+			if (entry) await this.#append(entry);
+		}
+		for (const identity of uncertainAfterCorruption) {
+			const entry = this.#byIdentity.get(identity);
+			if (entry && !terminal(entry.state) && entry.state !== "terminal_uncertain") {
+				await this.#append({ ...entry, state: "terminal_uncertain", ts: Date.now() });
+			}
+		}
+		// Effects may have completed after the last durable marker; do not retry them after a restart.
+		for (const entry of [...this.#byIdentity.values()]) {
+			if (entry.state === "effect_started" || entry.state === "awaiting_ready")
+				await this.#append({ ...entry, state: "terminal_uncertain", ts: Date.now() });
+		}
+		return this;
+	}
+	async #sealTornTail(): Promise<void> {
+		const h = await fs.open(this.#file, "a", 0o600);
+		try {
+			await h.writeFile("\n");
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+	}
+	async #quarantine(line: string): Promise<void> {
+		const h = await fs.open(this.#corruptFile, "a", 0o600);
+		try {
+			await h.writeFile(`${line}\n`);
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+		this.#warnings.push("Malformed lifecycle ledger entry quarantined");
+	}
+	get warnings(): readonly string[] {
+		return this.#warnings;
+	}
+	async #append(entry: LifecycleLedgerEntry): Promise<LifecycleLedgerEntry> {
+		const h = await fs.open(this.#file, "a", 0o600);
+		try {
+			await h.writeFile(`${JSON.stringify(entry)}\n`);
+			await h.sync();
+		} finally {
+			await h.close();
+		}
+		this.#entries.push(entry);
+		this.#byIdentity.set(entry.identity, entry);
+		return entry;
+	}
+	async begin(identity: string, requestHash: string): Promise<BeginResult> {
+		const prior = this.#byIdentity.get(identity);
+		if (!prior)
+			return {
+				kind: "new",
+				entry: await this.#append({
+					version: SDK_STATE_VERSION,
+					identity,
+					requestHash,
+					state: "accepted",
+					ts: Date.now(),
+				}),
+			};
+		if (prior.requestHash !== requestHash) return { kind: "idempotency_conflict" };
+		if (terminal(prior.state)) return { kind: "replay", entry: prior };
+		if (prior.state === "terminal_uncertain") return { kind: "terminal_uncertain", entry: prior };
+		// An accepted row has no durable side effect. Target serialization makes retrying it safe.
+		if (prior.state === "accepted") return { kind: "new", entry: prior };
+		return { kind: "in_progress", entry: prior };
+	}
+	async transition(
+		identity: string,
+		state: LifecycleState,
+		fields: Omit<Partial<LifecycleLedgerEntry>, "identity" | "requestHash" | "state" | "ts"> = {},
+	): Promise<LifecycleLedgerEntry> {
+		const previous = this.#byIdentity.get(identity);
+		if (!previous) throw new Error("Unknown lifecycle identity");
+		const next = { ...previous, ...fields, state, ts: Date.now() };
+		if (
+			(terminal(state) || state === "terminal_uncertain") &&
+			next.response !== undefined &&
+			next.responseDigest === undefined
+		)
+			next.responseDigest = createHash("sha256").update(canonicalJson(next.response)).digest("hex");
+		if (next.durableEffects && next.durableEffects.digest === undefined) {
+			const { digest: _digest, ...body } = next.durableEffects;
+			next.durableEffects = {
+				...body,
+				digest: createHash("sha256").update(canonicalJson(body)).digest("hex"),
+			};
+		}
+		return this.#append(next);
+	}
+	async assertSupportedStateVersions(): Promise<void> {
+		let source: string;
+		try {
+			source = await fs.readFile(this.#file, "utf8");
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+		for (const line of source.split("\n")) {
+			if (!line) continue;
+			try {
+				assertSupportedStateVersion(this.#file, JSON.parse(line));
+			} catch (error) {
+				if (error instanceof Error && "code" in error && error.code === "unsupported_state_version") throw error;
+			}
+		}
+	}
+
+	get(identity: string): LifecycleLedgerEntry | undefined {
+		return this.#byIdentity.get(identity);
+	}
+}