@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/sdk/bus/chat-daemon-runtime.ts

@@ -21,6 +21,12 @@ import { DiscordNotificationDaemon } from "./discord-daemon";
 
 import { DiscordLiveProvider } from "./discord-live-provider";
 import type { DiscordProvider } from "./discord-provider";
+import {
+	type DoctorDaemonIdentity,
+	type DoctorDaemonOccupancy,
+	type DoctorDaemonStatus,
+	doctorDaemonOccupancySettled,
+} from "./doctor-daemon-restart";
 import { type NotificationEvent, NotificationPresentationEngine } from "./engine";
 import { SlackNotificationDaemon } from "./slack-daemon";
 import { SlackLiveProvider } from "./slack-live-provider";
@@ -299,6 +305,11 @@ export class ChatDaemonRuntime {
 	#slack: SlackNotificationDaemon | undefined;
 	#presentation: NotificationPresentationEngine | undefined;
 	#transportHealthy: (() => boolean) | undefined;
+	#doctorPrepared = false;
+	/** Real inbound `/sdk` command dispatches currently admitted and running. */
+	readonly #inboundInFlight = new Set<Promise<unknown>>();
+	/** Real outbound provider notify/resume deliveries currently in flight. */
+	readonly #outboundInFlight = new Set<Promise<unknown>>();
 
 	constructor(
 		private readonly input: { kind: ChatDaemonKind; agentDir: string; config: ChatDaemonRuntimeConfig },
@@ -317,6 +328,24 @@ export class ChatDaemonRuntime {
 		});
 	}
 
+	#trackInbound<T>(work: Promise<T>): Promise<T> {
+		this.#inboundInFlight.add(work);
+		void work.then(
+			() => this.#inboundInFlight.delete(work),
+			() => this.#inboundInFlight.delete(work),
+		);
+		return work;
+	}
+
+	#trackOutbound<T>(work: Promise<T>): Promise<T> {
+		this.#outboundInFlight.add(work);
+		void work.then(
+			() => this.#outboundInFlight.delete(work),
+			() => this.#outboundInFlight.delete(work),
+		);
+		return work;
+	}
+
 	async start(): Promise<void> {
 		const replayReady = Promise.withResolvers<void>();
 		this.#replayReady = replayReady.promise;
@@ -443,6 +472,51 @@ export class ChatDaemonRuntime {
 		return this.#transportHealthy?.() ?? false;
 	}
 
+	/** Doctor reservation hook: stop admitting new `/sdk` command dispatch. Synchronous fence. */
+	prepareDoctorRestart(): boolean {
+		this.#doctorPrepared = true;
+		return true;
+	}
+
+	cancelDoctorRestart(): void {
+		if (!this.#stopping) this.#doctorPrepared = false;
+	}
+
+	/**
+	 * Real runtime occupancy, not synthetic placeholders. `attached` is live
+	 * session attachments; `inflight` is attachment (re)publication barriers
+	 * currently resolving; `inbound` is admitted `/sdk` command dispatches
+	 * (including operator `bindExistingRoot` binds) actually executing;
+	 * `outbound` is real Discord/Slack notify/resume provider deliveries in
+	 * flight; `cleanup` is provider close/retire work that has not yet
+	 * settled.
+	 */
+	doctorOccupancy(): DoctorDaemonOccupancy {
+		return {
+			attached: this.#attachments.size,
+			inflight: this.#attachmentBarriers.size,
+			inbound: this.#inboundInFlight.size,
+			outbound: this.#outboundInFlight.size,
+			cleanup: this.#cleanupWork.size + this.#retirementWork.size,
+		};
+	}
+
+	doctorRestartStatus(identity: DoctorDaemonIdentity, requestId: string, leaseExpiresAt: number): DoctorDaemonStatus {
+		const occupancy = this.doctorOccupancy();
+		return {
+			...identity,
+			requestId,
+			phase: this.#doctorPrepared ? "prepared" : "idle",
+			admitting: !this.#doctorPrepared && !this.#stopping,
+			occupancy,
+			leaseExpiresAt,
+		};
+	}
+
+	doctorRestartReady(): boolean {
+		return doctorDaemonOccupancySettled(this.doctorOccupancy());
+	}
+
 	/** Reconcile indexed attachments and optionally wait for their replay tails. */
 	async reconcile(options: { waitForReplay?: boolean } = {}): Promise<void> {
 		await this.#router.reconcile(options);
@@ -487,8 +561,19 @@ export class ChatDaemonRuntime {
 
 	/** Adopt an operator-supplied Slack root through the provider's presentation store. */
 	async bindExistingRoot(request: ChatDaemonCommandBindInput): Promise<ChatDaemonCommandOutcome> {
+		// Operator binds admit new provider-facing work exactly like /sdk command
+		// dispatch: they must be refused under the same doctor admission fence, not
+		// only the slash-command path.
+		if (this.#doctorPrepared) return { ok: false, certainty: "rejected", code: "target_not_configured" };
 		const slack = this.#slack;
 		if (!slack) return { ok: false, certainty: "rejected", code: "target_not_configured" };
+		return await this.#trackInbound(this.#bindExistingRoot(slack, request));
+	}
+
+	async #bindExistingRoot(
+		slack: SlackNotificationDaemon,
+		request: ChatDaemonCommandBindInput,
+	): Promise<ChatDaemonCommandOutcome> {
 		try {
 			const bound = await slack.bindExistingRoot(request.sessionId, request.rootTs, request.commitAuthority);
 			if (!bound.rootTs || bound.endpointGeneration === undefined)
@@ -662,23 +747,27 @@ export class ChatDaemonRuntime {
 				: undefined;
 		if (typeof content !== "string") return;
 		if (this.#discord)
-			await this.#discord.notify({
-				sessionId,
-				endpointGeneration: attachment.generation,
-				attachmentAuthorityId: attachment.authorityId,
-				content,
-				...(publicationId === undefined ? {} : { publicationId }),
-				...(notification.type === "action_needed"
-					? { actionId: notification.id, options: notification.options }
-					: {}),
-			});
+			await this.#trackOutbound(
+				this.#discord.notify({
+					sessionId,
+					endpointGeneration: attachment.generation,
+					attachmentAuthorityId: attachment.authorityId,
+					content,
+					...(publicationId === undefined ? {} : { publicationId }),
+					...(notification.type === "action_needed"
+						? { actionId: notification.id, options: notification.options }
+						: {}),
+				}),
+			);
 		if (this.#slack)
-			await this.#slack.notify(
-				sessionId,
-				content,
-				notification.type === "action_needed" && notification.kind === "ask" ? notification.id : undefined,
-				attachment.generation,
-				publicationId,
+			await this.#trackOutbound(
+				this.#slack.notify(
+					sessionId,
+					content,
+					notification.type === "action_needed" && notification.kind === "ask" ? notification.id : undefined,
+					attachment.generation,
+					publicationId,
+				),
 			);
 	}
 
@@ -721,16 +810,18 @@ export class ChatDaemonRuntime {
 		publicationId?: string,
 	): Promise<void> {
 		if (this.#discord) {
-			await this.#discord.resume(sessionId, generation, attachmentAuthorityId);
-			await this.#discord.notify({
-				sessionId,
-				endpointGeneration: generation,
-				attachmentAuthorityId,
-				content,
-				...(publicationId === undefined ? {} : { publicationId }),
-			});
+			await this.#trackOutbound(this.#discord.resume(sessionId, generation, attachmentAuthorityId));
+			await this.#trackOutbound(
+				this.#discord.notify({
+					sessionId,
+					endpointGeneration: generation,
+					attachmentAuthorityId,
+					content,
+					...(publicationId === undefined ? {} : { publicationId }),
+				}),
+			);
 		}
-		if (this.#slack) await this.#slack.resume(sessionId, content, generation, publicationId);
+		if (this.#slack) await this.#trackOutbound(this.#slack.resume(sessionId, content, generation, publicationId));
 	}
 
 	async #runChatCommand(
@@ -741,6 +832,31 @@ export class ChatDaemonRuntime {
 		idempotencyKey: string = randomUUID(),
 		beforeDispatch?: () => void,
 		dispatchFence?: <T>(dispatch: () => Promise<T>) => Promise<T>,
+	): Promise<boolean> {
+		// Fence BEFORE any admitted async work: a prepared doctor restart must
+		// refuse this dispatch synchronously, never merely self-report admitting.
+		if (this.#doctorPrepared) throw new ChatDeliveryError("pre_send");
+		return await this.#trackInbound(
+			this.#runChatCommandBody(
+				transport,
+				sessionId,
+				content,
+				expectedAttachment,
+				idempotencyKey,
+				beforeDispatch,
+				dispatchFence,
+			),
+		);
+	}
+
+	async #runChatCommandBody(
+		transport: ChatTransport,
+		sessionId: string,
+		content: string,
+		expectedAttachment: SessionAttachment,
+		idempotencyKey: string,
+		beforeDispatch: (() => void) | undefined,
+		dispatchFence: (<T>(dispatch: () => Promise<T>) => Promise<T>) | undefined,
 	): Promise<boolean> {
 		const match = /^\/sdk\s+(control|query|global)\s+([^\s]+)(?:\s+(.+))?\s*$/.exec(content);
 		if (!match) return false;

package/src/sdk/bus/daemon-startup-exclusion.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared, hold-only cross-process startup/maintenance exclusion for the D8/D9
+ * doctor daemon-service flows.
+ *
+ * This guard NEVER publishes ownership or service state and NEVER starts,
+ * signals, or claims a daemon owner. It is purely a mutual-exclusion fence,
+ * built on the same authoritative file-lock machinery every other durable
+ * daemon lock in this codebase uses ({@link withFileLock}): bounded retry with
+ * backoff, honoring an optional `AbortSignal`, and exact-lease release on the
+ * way out (never a blind recursive `rm`, and never a PID kill).
+ *
+ * Why a separate guard file: `withFileLock` serializes on `<path>.lock`, a
+ * name distinct from every existing canonical artifact for a service
+ * (`telegram-daemon.lock`/`.state.json`/`.steal`, or `owner.lock`/`state.json`
+ * for Discord/Slack). Acquiring this guard therefore can never collide with,
+ * be satisfied by, or be mistaken for an ordinary ownership/publication lock,
+ * and ordinary publication code paths are free to acquire their own locks
+ * independently — this primitive only fences bulk-maintenance and startup
+ * repair work (e.g. detaching a stale Telegram `.steal` transition marker)
+ * against a concurrent ordinary `ensure`, and vice versa.
+ *
+ * If a caller already holds this guard, it must route any further
+ * `withDaemonStartupExclusion` acquisition for the SAME `(agentDir, owner)`
+ * pair through nested async work that never itself re-enters this function —
+ * `withFileLock`'s underlying acquisition has no reentrant/owner-token
+ * concept visible to callers, so a second acquisition attempt from the same
+ * async context is indistinguishable from unrelated contention and will
+ * deadlock against itself. Nothing in this module grants, threads, or
+ * consults any bypass flag or ambient/AsyncLocalStorage authority to avoid
+ * that; the caller is responsible for not awaiting a child operation that
+ * itself needs this same guard while still holding it.
+ */
+import * as path from "node:path";
+import { acquireFileLock, type FileLockOptions, withFileLock } from "../../config/file-lock";
+import { CHAT_DAEMON_DIRECTORY } from "../service-artifact-paths";
+import { daemonPaths } from "./daemon-paths";
+
+export type DaemonStartupExclusionOwner = "telegram" | "discord" | "slack";
+
+export interface DaemonStartupExclusionOptions {
+	/** Abort acquisition early; never releases a lease this call did not itself acquire. */
+	signal?: AbortSignal;
+	/** Upper bound on total wait while contended. Defaults to {@link DAEMON_STARTUP_EXCLUSION_DEFAULT_TIMEOUT_MS}. */
+	timeoutMs?: number;
+}
+
+/** Matches the production wall-time bound already established for other durable daemon locks. */
+export const DAEMON_STARTUP_EXCLUSION_DEFAULT_TIMEOUT_MS = 5_000;
+const RETRY_DELAY_MS = 100;
+
+/**
+ * The canonical per-service guard path. Lives inside the SAME per-service
+ * directory as the service's ordinary owner/state artifacts (so it inherits
+ * that directory's existing parent-permission posture) but under a filename
+ * reserved exclusively for this guard — never a name any ownership,
+ * publication, or transition-marker code path reads or writes.
+ *
+ * This function only computes a path; it performs no filesystem I/O and
+ * creates nothing. (`withFileLock` itself creates the missing parent
+ * directory chain, mode 0o700, purely as lock-acquisition scaffolding — an
+ * empty directory carries no service state.)
+ */
+export function daemonStartupExclusionPath(agentDir: string, owner: DaemonStartupExclusionOwner): string {
+	const root = path.resolve(agentDir);
+	const dir = owner === "telegram" ? daemonPaths(root).dir : path.join(root, CHAT_DAEMON_DIRECTORY, owner);
+	return path.join(dir, ".startup-exclusion");
+}
+
+/**
+ * Run `operation` while holding the cross-process startup/maintenance
+ * exclusion for `(agentDir, owner)`. Bounded: acquisition retries back off
+ * for at most `timeoutMs` (default {@link DAEMON_STARTUP_EXCLUSION_DEFAULT_TIMEOUT_MS})
+ * and additionally honors `signal` if supplied — whichever bound is hit first
+ * rejects the acquisition. A rejected/timed-out/aborted acquisition never held
+ * a lease and therefore never releases one; it cannot touch a foreign owner's
+ * lock. On success, the lease this call acquired is released exactly once,
+ * through the same identity-bound release primitive `withFileLock` uses for
+ * every other durable lock in this codebase — never a recursive directory
+ * removal, and never a process signal.
+ *
+ * This primitive itself never reads, writes, or removes any owner/state/lock
+ * file belonging to the service; it only fences concurrent callers of this
+ * same function (and, by construction, is never consulted by ordinary
+ * ownership-acquisition or publication code, which uses its own distinct
+ * lock file).
+ */
+export async function withDaemonStartupExclusion<T>(
+	agentDir: string,
+	owner: DaemonStartupExclusionOwner,
+	operation: () => Promise<T>,
+	options: DaemonStartupExclusionOptions = {},
+): Promise<T> {
+	return await withFileLock(daemonStartupExclusionPath(agentDir, owner), operation, exclusionOptions(options));
+}
+
+function exclusionOptions(options: DaemonStartupExclusionOptions): FileLockOptions {
+	const requested = options.timeoutMs ?? DAEMON_STARTUP_EXCLUSION_DEFAULT_TIMEOUT_MS;
+	if (!Number.isFinite(requested) || requested <= 0 || requested > 120_000)
+		throw new RangeError("invalid startup exclusion timeout");
+	const timeoutMs = Math.ceil(requested);
+	const retries = Math.max(Math.ceil(timeoutMs / RETRY_DELAY_MS), 1);
+	const deadline = AbortSignal.timeout(timeoutMs);
+	const signal = options.signal ? AbortSignal.any([options.signal, deadline]) : deadline;
+	const lockOptions: FileLockOptions = {
+		signal,
+		retries,
+		retryDelayMs: RETRY_DELAY_MS,
+	};
+	return lockOptions;
+}
+
+/** Retain the same exclusion across an existing acquire/release lifecycle. */
+export async function acquireDaemonStartupExclusion(
+	agentDir: string,
+	owner: DaemonStartupExclusionOwner,
+	options: DaemonStartupExclusionOptions = {},
+): Promise<() => Promise<void>> {
+	return await acquireFileLock(daemonStartupExclusionPath(agentDir, owner), exclusionOptions(options));
+}

package/src/sdk/bus/doctor-daemon-restart-client.ts

@@ -0,0 +1,291 @@
+/**
+ * Doctor-side caller for the owner-driven daemon restart protocol (D8).
+ *
+ * The owner already implements prepare/commit/cancel against its own admission
+ * fence and occupancy (`chat-daemon-cli.ts`, `telegram-daemon-cli.ts`); this
+ * module is the counterpart that a `gjc doctor --fix --repair
+ * service.restart-owned` invocation drives. It never signals, kills, or reloads
+ * anything: the only lever is the durable control request the owner polls, and
+ * the only proof of the owner's exit is a positive kernel observation of its
+ * exact incarnation.
+ *
+ * The successor is started through the product's own sanctioned start path,
+ * never a doctor-private spawn, so the existing startup exclusion stays the
+ * single authority for who may own the slot.
+ */
+import { randomUUID } from "node:crypto";
+import type { Settings } from "../../config/settings";
+import { observeProcessIncarnation } from "../broker/process-incarnation";
+import {
+	type ChatDaemonKind,
+	type ChatDaemonState,
+	chatDaemonGeneration,
+	clearChatDoctorControlRequest,
+	ensureDiscordDaemon,
+	ensureSlackDaemon,
+	readChatDaemonState,
+	readChatDoctorControlRequest,
+	writeChatDoctorControlRequest,
+} from "./chat-daemon-control";
+import type { DoctorDaemonControlRequest, DoctorDaemonIdentity, DoctorDaemonOwner } from "./doctor-daemon-restart";
+import { ensureTelegramDaemonRunning, readDaemonState } from "./telegram-daemon";
+import { DAEMON_GENERATION } from "./telegram-daemon-contract";
+import {
+	clearTelegramDoctorControlRequest,
+	readTelegramDoctorControlRequest,
+	writeTelegramDoctorControlRequest,
+} from "./telegram-daemon-control";
+
+/**
+ * Per-owner adapter over the two control-file surfaces. Both owners implement
+ * the same prepare/commit/cancel protocol; only the accessor signatures and the
+ * sanctioned start path differ, so this is a shape adapter, never a second
+ * protocol.
+ */
+/**
+ * A published owner this doctor can drive, an owner that predates the current
+ * restart protocol (which requires the disclosed one-time manual transition and
+ * must never be signalled), or no record at all. The three are distinct: a
+ * pre-protocol incumbent is present and must not be reported as absent.
+ */
+type OwnerObservation =
+	| { readonly kind: "current"; readonly pid: number; readonly identity: DoctorDaemonIdentity }
+	| { readonly kind: "pre_protocol" }
+	| { readonly kind: "absent" };
+
+interface OwnerAdapter {
+	readonly owner: DoctorDaemonOwner;
+	observe(): Promise<OwnerObservation>;
+	read(): Promise<DoctorDaemonControlRequest | undefined>;
+	write(request: DoctorDaemonControlRequest): Promise<void>;
+	clear(requestId: string): Promise<void>;
+	/** The product's own sanctioned start path; never a doctor-private spawn. */
+	start(): Promise<boolean>;
+}
+
+const POLL_MS = 100;
+const DEFAULT_DEADLINE_MS = 30_000;
+
+export interface DoctorDaemonRestartOptions {
+	readonly agentDir: string;
+	readonly owner: DoctorDaemonOwner;
+	readonly settings: Settings;
+	readonly requestId?: string;
+	readonly deadlineMs?: number;
+	/** Bounded natural-completion wait; idle attached sessions still count as workload. */
+	readonly drainSeconds?: number;
+}
+
+/**
+ * Typed before/after-effect outcome. Every refusal names the exact stage it
+ * stopped at, so a caller never has to infer whether an effect began.
+ */
+export type DoctorDaemonRestartOutcome =
+	| {
+			kind: "restarted";
+			requestId: string;
+			oldOwner: DoctorDaemonIdentity;
+			successor: DoctorDaemonIdentity;
+			adopted: boolean;
+	  }
+	| { kind: "owner_unavailable"; reason: "no_state" | "owner_not_confirmed_live" | "unsupported_incumbent_protocol" }
+	| { kind: "prepare_refused"; reason: "control_write_failed" | "not_acknowledged" }
+	// The owner enforces occupancy itself and simply does not exit while work
+	// remains, which this client observes as `old_owner_exit_timeout`. A failed
+	// commit here therefore means only that the durable request could not be
+	// written, and must not claim to describe occupancy.
+	| { kind: "commit_refused"; reason: "control_write_failed" }
+	| { kind: "old_owner_exit_timeout"; requestId: string; oldOwner: DoctorDaemonIdentity }
+	| {
+			kind: "successor_refused";
+			requestId: string;
+			oldOwner: DoctorDaemonIdentity;
+			reason: "start_refused" | "publication_timeout";
+	  };
+
+function identityOf(owner: DoctorDaemonOwner, state: ChatDaemonState): DoctorDaemonIdentity {
+	return { owner, ownerId: state.ownerId, generation: state.generation, incarnation: state.incarnation };
+}
+
+function chatAdapter(options: DoctorDaemonRestartOptions, kind: ChatDaemonKind): OwnerAdapter {
+	return {
+		owner: kind,
+		async observe(): Promise<OwnerObservation> {
+			const state = await readChatDaemonState(options.agentDir, kind);
+			if (!state || state.stoppedAt !== undefined) return { kind: "absent" };
+			// Present but older than the current restart protocol: the operator must
+			// perform the disclosed one-time manual transition; doctor never signals it.
+			if (state.generation !== chatDaemonGeneration(kind)) return { kind: "pre_protocol" };
+			return { kind: "current", pid: state.pid, identity: identityOf(kind, state) };
+		},
+		read: () => readChatDoctorControlRequest(options.agentDir, kind),
+		write: request => writeChatDoctorControlRequest(options.agentDir, kind, request),
+		clear: requestId => clearChatDoctorControlRequest(options.agentDir, kind, requestId),
+		async start() {
+			const ensured =
+				kind === "discord"
+					? await ensureDiscordDaemon(options.settings)
+					: await ensureSlackDaemon(options.settings);
+			return ensured !== "disabled";
+		},
+	};
+}
+
+function telegramAdapter(options: DoctorDaemonRestartOptions): OwnerAdapter {
+	const settings = options.settings;
+	return {
+		owner: "telegram",
+		async observe(): Promise<OwnerObservation> {
+			const state = await readDaemonState(settings);
+			if (!state || state.stoppedAt !== undefined) return { kind: "absent" };
+			if (state.generation !== DAEMON_GENERATION) return { kind: "pre_protocol" };
+			// A provisional owner is physically live but not attachable as ready, so it
+			// is not a restartable incumbent.
+			if (state.ownershipPhase !== undefined && state.ownershipPhase !== "ready") return { kind: "absent" };
+			return {
+				kind: "current",
+				pid: state.pid,
+				identity: {
+					owner: "telegram",
+					ownerId: state.ownerId,
+					generation: state.generation,
+					incarnation: state.incarnation,
+				},
+			};
+		},
+		read: () => readTelegramDoctorControlRequest(settings),
+		write: request => writeTelegramDoctorControlRequest(settings, request),
+		clear: requestId => clearTelegramDoctorControlRequest(settings, requestId),
+		async start() {
+			// The product's own ensure path resolves the configured destination and
+			// holds the existing setup lease; doctor never supplies a token or chat and
+			// never refreshes a credential.
+			const ensured = await ensureTelegramDaemonRunning({ settings });
+			return ensured === "owner_spawned" || ensured === "attached";
+		},
+	};
+}
+
+/** Positive kernel absence only: a changed or missing record is never death proof. */
+function confirmedExited(pid: number, incarnation: string): boolean {
+	const observation = observeProcessIncarnation(pid);
+	if (observation.status === "absent") return true;
+	// A live pid whose incarnation differs is a reused pid, so the original
+	// incarnation is genuinely gone; `unknown` stays inconclusive.
+	return observation.status === "present" && observation.incarnation !== incarnation;
+}
+
+async function request(
+	adapter: OwnerAdapter,
+	identity: DoctorDaemonIdentity,
+	requestId: string,
+	action: DoctorDaemonControlRequest["action"],
+	leaseExpiresAt: number,
+): Promise<boolean> {
+	try {
+		await adapter.write({ version: 1, requestId, action, leaseExpiresAt, createdAt: Date.now(), ...identity });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Owner-side prepare/commit, positive-exit-confirmed cleanup, then exactly one
+ * successor started through the product's own ensure path.
+ *
+ * Ordering is fixed: prepare (owner closes admission) → occupancy settles →
+ * commit → owner exits under its own gate → positive absence proof → successor
+ * start or adoption. A commit is never issued before the owner acknowledged the
+ * prepare, and a successor is never started before the predecessor is proven
+ * gone.
+ */
+export async function restartDaemonForDoctor(options: DoctorDaemonRestartOptions): Promise<DoctorDaemonRestartOutcome> {
+	const adapter = options.owner === "telegram" ? telegramAdapter(options) : chatAdapter(options, options.owner);
+	const deadlineAt = Date.now() + (options.deadlineMs ?? DEFAULT_DEADLINE_MS);
+	const before = await adapter.observe();
+	if (before.kind === "pre_protocol") return { kind: "owner_unavailable", reason: "unsupported_incumbent_protocol" };
+	if (before.kind === "absent") return { kind: "owner_unavailable", reason: "no_state" };
+	if (confirmedExited(before.pid, before.identity.incarnation))
+		return { kind: "owner_unavailable", reason: "owner_not_confirmed_live" };
+	const identity = before.identity;
+	const requestId = options.requestId ?? randomUUID();
+	if (!(await request(adapter, identity, requestId, "prepare", deadlineAt)))
+		return { kind: "prepare_refused", reason: "control_write_failed" };
+
+	// The owner consumes a prepare without rewriting it, so the request simply
+	// staying present proves nothing: this process wrote it. What IS observable to
+	// a non-parent caller is that the owner remains the same live incarnation that
+	// can still act on it. A request that outlives its own owner, or that a third
+	// party removed, is never treated as accepted.
+	const drainUntil = Date.now() + (options.drainSeconds ?? 0) * 1_000;
+	let acknowledged = false;
+	while (Date.now() < deadlineAt) {
+		const current = await adapter.read();
+		if (current?.requestId !== requestId) break;
+		const owner = await adapter.observe();
+		if (owner.kind !== "current" || owner.identity.incarnation !== identity.incarnation) break;
+		if (!confirmedExited(before.pid, identity.incarnation)) {
+			acknowledged = true;
+			break;
+		}
+		await Bun.sleep(POLL_MS);
+	}
+	if (!acknowledged) {
+		// An owner that already consumed the prepare has closed admission, and only a
+		// `cancel` under the same request id reopens it — deleting the control file
+		// reopens nothing and would strand a healthy daemon refusing all work. Cancel
+		// when the addressed owner is still there (it unlinks the file itself);
+		// otherwise there is nobody to reopen and the stale file is just removed.
+		const owner = await adapter.observe();
+		if (owner.kind === "current" && owner.identity.incarnation === identity.incarnation)
+			await request(adapter, identity, requestId, "cancel", deadlineAt);
+		else await adapter.clear(requestId);
+		return { kind: "prepare_refused", reason: "not_acknowledged" };
+	}
+
+	// `--drain` is bounded natural completion only. The owner itself refuses the
+	// commit while any workload remains (an idle attached session counts), so this
+	// wait never detaches or retires anything on its behalf.
+	if (Date.now() < drainUntil)
+		await Bun.sleep(Math.min(drainUntil - Date.now(), Math.max(0, deadlineAt - Date.now())));
+
+	if (!(await request(adapter, identity, requestId, "commit", deadlineAt))) {
+		await adapter.clear(requestId);
+		return { kind: "commit_refused", reason: "control_write_failed" };
+	}
+
+	while (Date.now() < deadlineAt) {
+		if (confirmedExited(before.pid, identity.incarnation)) break;
+		await Bun.sleep(POLL_MS);
+	}
+	if (!confirmedExited(before.pid, identity.incarnation))
+		// The commit is durable and the owner may still retire under its own gate;
+		// never cancel it here and never force the exit.
+		return { kind: "old_owner_exit_timeout", requestId, oldOwner: identity };
+
+	// An already-published successor of the same generation is adopted rather than
+	// starting a second one.
+	const published = await adapter.observe();
+	if (published.kind === "current" && published.identity.incarnation !== identity.incarnation) {
+		await adapter.clear(requestId);
+		return { kind: "restarted", requestId, oldOwner: identity, successor: published.identity, adopted: true };
+	}
+
+	try {
+		if (!(await adapter.start()))
+			return { kind: "successor_refused", requestId, oldOwner: identity, reason: "start_refused" };
+	} catch {
+		return { kind: "successor_refused", requestId, oldOwner: identity, reason: "start_refused" };
+	}
+
+	while (Date.now() < deadlineAt) {
+		const successor = await adapter.observe();
+		if (successor.kind === "current" && successor.identity.incarnation !== identity.incarnation) {
+			await adapter.clear(requestId);
+			return { kind: "restarted", requestId, oldOwner: identity, successor: successor.identity, adopted: false };
+		}
+		await Bun.sleep(POLL_MS);
+	}
+	return { kind: "successor_refused", requestId, oldOwner: identity, reason: "publication_timeout" };
+}