@gajae-code/coding-agent 0.11.4 → 0.11.6

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

@@ -1,7 +1,10 @@
 import { spawn as childProcessSpawn } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
+import * as native from "@gajae-code/natives";
+import { Process } from "@gajae-code/natives";
 import type { Settings } from "../../config/settings";
 import type {
 	BuiltInDaemonController,
@@ -18,6 +21,23 @@ import { getNotificationConfig, isDiscordConfigured, isSlackConfigured } from ".
 export type ChatDaemonKind = "discord" | "slack";
 export type ChatDaemonAction = "stop" | "reload";
 
+/**
+ * Operational generations of the Discord/Slack daemon lifecycle contracts.
+ * These are intentionally separate from per-session endpoint generations.
+ * Generation 6 carries the retained managed filesystem authority boundary.
+ * Generation 7 restores macOS daemon signaling (kill(2) with a start-time
+ * incarnation recheck) so a live/hung owner can be replaced without an external
+ * `kill -9`.
+ */
+export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
+	discord: 7,
+	slack: 7,
+};
+
+export function chatDaemonGeneration(kind: ChatDaemonKind): number {
+	return CHAT_DAEMON_GENERATIONS[kind];
+}
+
 export interface ChatDaemonState {
 	version: 1;
 	kind: ChatDaemonKind;
@@ -28,9 +48,111 @@ export interface ChatDaemonState {
 	startedAt: number;
 	heartbeatAt: number;
 	transportHealthy: boolean;
+	generation: number;
 	stoppedAt?: number;
 }
 
+/**
+ * State files are untrusted persisted input. A record must be completely valid
+ * before its PID can be treated as an owner, stopped, or safe to replace.
+ */
+/** A legacy owner is recognized only when the sole missing field is generation. */
+export function isRecognizedLegacyGeneration(value: unknown): value is undefined {
+	return value === undefined;
+}
+
+function hasProcessIncarnationAuthority(incarnation: unknown): incarnation is string {
+	return typeof incarnation === "string" && isProcessIncarnation(incarnation);
+}
+
+function hasSafeChatDaemonOwnerShape(
+	value: unknown,
+): value is Omit<ChatDaemonState, "generation"> & { generation?: unknown } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const state = value as Record<string, unknown>;
+	return (
+		state.version === 1 &&
+		(state.kind === "discord" || state.kind === "slack") &&
+		typeof state.pid === "number" &&
+		Number.isSafeInteger(state.pid) &&
+		state.pid > 0 &&
+		typeof state.ownerId === "string" &&
+		state.ownerId.length > 0 &&
+		typeof state.identity === "string" &&
+		state.identity.length > 0 &&
+		hasProcessIncarnationAuthority(state.incarnation) &&
+		typeof state.startedAt === "number" &&
+		Number.isFinite(state.startedAt) &&
+		typeof state.heartbeatAt === "number" &&
+		Number.isFinite(state.heartbeatAt) &&
+		typeof state.transportHealthy === "boolean" &&
+		(state.stoppedAt === undefined || (typeof state.stoppedAt === "number" && Number.isFinite(state.stoppedAt)))
+	);
+}
+
+export function hasSafeChatDaemonStateShape(value: unknown): value is ChatDaemonState {
+	if (!hasSafeChatDaemonOwnerShape(value)) return false;
+	const state = value as Record<string, unknown>;
+	return typeof state.generation === "number" && Number.isSafeInteger(state.generation) && state.generation >= 0;
+}
+
+/**
+ * Versions before immutable process provenance persisted this single sentinel.
+ * Recover it only after proving its recorded PID is dead; every other malformed
+ * record remains fail-closed.
+ */
+function isExactPreUpgradeUnavailableChatDaemonState(
+	value: unknown,
+): value is Omit<ChatDaemonState, "generation" | "incarnation"> & { incarnation: "unavailable" } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const state = value as Record<string, unknown>;
+	const keys = Object.keys(state);
+	if (
+		keys.some(
+			key =>
+				key !== "version" &&
+				key !== "kind" &&
+				key !== "pid" &&
+				key !== "ownerId" &&
+				key !== "identity" &&
+				key !== "incarnation" &&
+				key !== "startedAt" &&
+				key !== "heartbeatAt" &&
+				key !== "transportHealthy" &&
+				key !== "stoppedAt",
+		)
+	)
+		return false;
+	return (
+		state.version === 1 &&
+		(state.kind === "discord" || state.kind === "slack") &&
+		typeof state.pid === "number" &&
+		Number.isSafeInteger(state.pid) &&
+		state.pid > 0 &&
+		typeof state.ownerId === "string" &&
+		state.ownerId.length > 0 &&
+		typeof state.identity === "string" &&
+		state.identity.length > 0 &&
+		state.incarnation === "unavailable" &&
+		typeof state.startedAt === "number" &&
+		Number.isFinite(state.startedAt) &&
+		typeof state.heartbeatAt === "number" &&
+		Number.isFinite(state.heartbeatAt) &&
+		typeof state.transportHealthy === "boolean" &&
+		(state.stoppedAt === undefined || (typeof state.stoppedAt === "number" && Number.isFinite(state.stoppedAt)))
+	);
+}
+
+function hasChatDaemonStatePid(value: unknown): value is { pid: number } {
+	return (
+		!!value &&
+		typeof value === "object" &&
+		typeof (value as { pid?: unknown }).pid === "number" &&
+		Number.isSafeInteger((value as { pid: number }).pid) &&
+		(value as { pid: number }).pid > 0
+	);
+}
+
 export interface ChatDaemonControlRequest {
 	version: 1;
 	requestId: string;
@@ -41,21 +163,61 @@ export interface ChatDaemonControlRequest {
 	incarnation: string;
 }
 
+export interface ChatDaemonProcessReference {
+	incarnation: string;
+	signalRoot(signal: NodeJS.Signals): void;
+}
+
+function defaultProcessReference(pid: number, platform = os.platform()): ChatDaemonProcessReference | undefined {
+	try {
+		const processRef = Process.fromPid(pid);
+		if (!processRef || !hasProcessIncarnationAuthority(processRef.incarnation)) return undefined;
+		const incarnation = processRef.incarnation;
+		return {
+			incarnation,
+			signalRoot: signal => {
+				const nativeSignal = os.constants.signals[signal];
+				if (nativeSignal === undefined) throw new Error(`Unsupported signal: ${signal}`);
+				// macOS exposes no pidfd and the native signal_root is a no-op there, so
+				// the daemon control plane previously had NO way to signal a live owner —
+				// every stop/reload of a live/hung daemon refused, and only an external
+				// `kill -9` could recover it. Signal by numeric PID via kill(2), but
+				// re-read the immutable start-time incarnation immediately beforehand so a
+				// PID that exited and was reused since capture is never signaled.
+				if (platform === "darwin") {
+					const current = Process.fromPid(pid) as { incarnation?: unknown } | null;
+					if (!current || current.incarnation !== incarnation) throw new Error("Pinned process is already gone");
+					process.kill(pid, signal);
+					return;
+				}
+				const rootProcess = processRef as typeof processRef & { signalRoot(signal: number): boolean };
+				if (!rootProcess.signalRoot(nativeSignal)) throw new Error("Pinned process is already gone");
+			},
+		};
+	} catch {
+		return undefined;
+	}
+}
+
 export interface ChatDaemonControlDeps {
 	pidAlive?: (pid: number) => boolean;
-	sendSignal?: (pid: number, signal: NodeJS.Signals) => void;
+	processReference?: (pid: number) => ChatDaemonProcessReference | undefined;
 	spawn?: (command: string, args: string[], opts: { detached: boolean; stdio: "ignore" }) => { unref?: () => void };
 	execPath?: string;
 	ownerPid?: number;
 	randomId?: () => string;
 	pidIncarnation?: (pid: number) => string | undefined;
+	/** Test seam for platform-specific default stable-process authority. */
+	platform?: NodeJS.Platform;
 	sleep?: (ms: number) => Promise<void>;
+	spawnReadyTimeoutMs?: number;
 }
 
 const HEARTBEAT_TTL_MS = 20_000;
 const DEFAULT_GRACEFUL_TIMEOUT_MS = 8_000;
 const DEFAULT_KILL_TIMEOUT_MS = 3_000;
-const UNPUBLISHED_OWNER_LOCK_STALE_MS = HEARTBEAT_TTL_MS;
+/** Covers Discord READY plus its first 5-second heartbeat; tests inject a smaller timeout. */
+const DEFAULT_SPAWN_READY_TIMEOUT_MS = 8_000;
 
 interface ChatDaemonOwnerLock {
 	pid: number;
@@ -63,6 +225,15 @@ interface ChatDaemonOwnerLock {
 	createdAt: number;
 }
 
+interface ChatDaemonOwnerLockLease {
+	content: string;
+	dev: bigint;
+	ino: bigint;
+	size: bigint;
+	mtimeNs: bigint;
+	sha256: string;
+}
+
 interface ChatDaemonOwnershipProbe {
 	pidAlive(pid: number): boolean;
 	pidIncarnation(pid: number): string | undefined;
@@ -117,12 +288,11 @@ function defaultPidAlive(pid: number): boolean {
 		return false;
 	}
 }
-function defaultSignal(pid: number, signal: NodeJS.Signals): void {
-	try {
-		process.kill(pid, signal);
-	} catch {}
+/** Windows process ownership uses immutable StartTime/FileTime provenance through
+ * the shared native/platform authority. Without authority, numeric PIDs are never trusted. */
+function defaultPidIncarnation(pid: number): string | undefined {
+	return processIncarnation(pid);
 }
-
 function runtimeInfo(execPath?: string): DaemonRuntimeInfo {
 	const rt = resolveGjcRuntimeSpawnInfo(execPath ?? process.execPath);
 	return {
@@ -219,6 +389,15 @@ export function buildChatDaemonSpawnArgs(input: {
 	};
 }
 
+type ChatDaemonStateClassification =
+	| "absent"
+	| "replaceable"
+	| "compatible"
+	| "newer"
+	| "malformed"
+	| "unauthorized"
+	| "stopped";
+
 export class ChatDaemonController implements BuiltInDaemonController {
 	readonly kind: ChatDaemonKind;
 	constructor(
@@ -237,20 +416,9 @@ export class ChatDaemonController implements BuiltInDaemonController {
 	async status(): Promise<DaemonStatus> {
 		const runtime = runtimeInfo(this.deps.execPath);
 		const identity = this.identity();
-		if (!identity) return { kind: this.kind, configured: false, health: "not_configured", runtime };
 		const state = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
-		const live = Boolean(
-			state &&
-				state.version === 1 &&
-				state.kind === this.kind &&
-				state.identity === identity &&
-				!state.stoppedAt &&
-				state.transportHealthy &&
-				Date.now() - state.heartbeatAt <= HEARTBEAT_TTL_MS &&
-				this.alive(state.pid) &&
-				this.incarnation(state.pid) === state.incarnation,
-		);
-		const health: DaemonHealth = live ? "running" : state && !state.stoppedAt ? "stale" : "stopped";
+		if (!identity) return { kind: this.kind, configured: false, health: "not_configured", runtime };
+		const health: DaemonHealth = this.stateHealth(state, identity);
 		return {
 			kind: this.kind,
 			configured: true,
@@ -272,14 +440,27 @@ export class ChatDaemonController implements BuiltInDaemonController {
 		const identity = this.identity();
 		if (!identity) return "disabled";
 		const existing = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
-		if (existing && this.isLiveState(existing)) {
-			if (existing.identity === identity) return "attached";
+		const classification = this.classify(existing, identity);
+		if (classification === "malformed" || classification === "unauthorized")
+			throw new Error(`Unable to replace unauthorized ${this.kind} daemon owner`);
+		if (existing && this.isSignalableMatchingOwner(existing)) {
+			if (classification === "compatible" || classification === "newer") {
+				// A compatible, physically-live owner may be mid-startup: a concurrent
+				// ensure can have just acquired ownership and published transportHealthy:false
+				// before its transport heartbeats healthy. Wait bounded for that owner to
+				// become attachable instead of failing a racing startup outright.
+				if (this.isHealthyFreshState(existing) || (await this.waitForOwnership(existing.ownerId, identity)))
+					return "attached";
+				if (classification === "newer")
+					throw new Error(`Unable to replace newer ${this.kind} daemon owner; upgrade this controller`);
+				throw new Error(`Unable to replace unhealthy ${this.kind} daemon owner`);
+			}
 			await this.stopForReplacement(existing);
 		}
 		const spawned = await this.spawn();
 		if (spawned) return "owner_spawned";
 		const replacement = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
-		if (replacement && replacement.identity === identity && this.isLiveState(replacement)) return "attached";
+		if (replacement && this.isCurrentCompatibleState(replacement, identity)) return "attached";
 		throw new Error(`Unable to attach or spawn ${this.kind} daemon owner`);
 	}
 
@@ -288,24 +469,54 @@ export class ChatDaemonController implements BuiltInDaemonController {
 		const warnings = before.runtime.warning ? [before.runtime.warning] : [];
 		if (!before.configured)
 			return this.result(action, false, `${this.kind} notifications are not configured`, before, before, warnings);
-		if (before.health !== "running") {
-			if (action === "stop")
+		const state = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
+		const classification = this.classify(state, this.identity());
+		if (classification === "newer")
+			return this.result(
+				action,
+				false,
+				`${this.kind} daemon is newer than this controller; upgrade this controller before ${action}`,
+				before,
+				before,
+				warnings,
+			);
+		if (classification === "malformed" || classification === "unauthorized")
+			return this.result(
+				action,
+				false,
+				`${this.kind} daemon ownership changed; refusing to signal`,
+				before,
+				await this.status(),
+				warnings,
+			);
+		if (!state || !this.isSignalableMatchingOwner(state)) {
+			if (action === "stop") {
+				if (state && this.isAmbiguouslyLiveState(state))
+					return this.result(
+						action,
+						false,
+						`${this.kind} daemon ownership changed; refusing to signal`,
+						before,
+						before,
+						warnings,
+					);
 				return this.result(action, true, `no running ${this.kind} daemon`, before, before, warnings);
+			}
 			if (opts.spawnIfStopped === false)
 				return this.result(action, true, `no running ${this.kind} daemon to reload`, before, before, warnings);
 			const spawned = await this.spawn();
-			const after = await this.status();
 			return this.result(
 				action,
 				spawned,
-				spawned ? `spawned fresh ${this.kind} daemon` : `a live ${this.kind} owner already exists`,
+				spawned
+					? `spawned fresh ${this.kind} daemon`
+					: `${this.kind} daemon did not publish ownership after spawning`,
 				before,
-				after,
+				await this.status(),
 				warnings,
 			);
 		}
-		const state = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
-		if (!state || !this.ownsCapturedState(state, before))
+		if (state.identity !== this.identity() || !this.ownsCapturedState(state, before))
 			return this.result(
 				action,
 				false,
@@ -359,20 +570,75 @@ export class ChatDaemonController implements BuiltInDaemonController {
 	private incarnation(pid: number): string | undefined {
 		return (this.deps.pidIncarnation ?? processIncarnation)(pid);
 	}
-	private isLiveState(state: ChatDaemonState): boolean {
+	private processReference(pid: number): ChatDaemonProcessReference | undefined {
+		return this.deps.processReference
+			? this.deps.processReference(pid)
+			: defaultProcessReference(pid, this.deps.platform);
+	}
+	private isDefinitelyStoppedState(state: ChatDaemonState | undefined): boolean {
+		if (isExactPreUpgradeUnavailableChatDaemonState(state)) return !this.alive(state.pid);
+		if (!state || !hasSafeChatDaemonOwnerShape(state)) return false;
+		if (!this.alive(state.pid)) return true;
+		// Proven PID reuse means this persisted owner is gone. The distinct live PID
+		// remains nonsignalable because isSignalableMatchingOwner requires equality.
+		const incarnation = this.incarnation(state.pid);
+		return hasProcessIncarnationAuthority(incarnation) && incarnation !== state.incarnation;
+	}
+	private stateHealth(state: ChatDaemonState | undefined, identity: string): DaemonHealth {
+		if (!state || this.isDefinitelyStoppedState(state)) return "stopped";
+		if (this.isCurrentCompatibleState(state, identity)) return "running";
+		// A PID that is live but cannot prove a matching current incarnation is
+		// ambiguous: do not report it ready or overwrite it.
+		return "stale";
+	}
+	private isSignalableMatchingOwner(state: ChatDaemonState): boolean {
+		const incarnation = this.incarnation(state.pid);
 		return (
-			state.version === 1 &&
+			hasSafeChatDaemonOwnerShape(state) &&
 			state.kind === this.kind &&
-			!state.stoppedAt &&
-			state.transportHealthy &&
-			Date.now() - state.heartbeatAt <= HEARTBEAT_TTL_MS &&
+			state.stoppedAt === undefined &&
 			this.alive(state.pid) &&
-			Boolean(state.incarnation) &&
-			this.incarnation(state.pid) === state.incarnation
+			hasProcessIncarnationAuthority(incarnation) &&
+			incarnation === state.incarnation
 		);
 	}
+	/** A live PID with an invalid ownership record is never safe to overwrite. */
+	private isAmbiguouslyLiveState(state: ChatDaemonState): boolean {
+		return !this.isDefinitelyStoppedState(state) && !this.isSignalableMatchingOwner(state);
+	}
+
+	private isHealthyFreshState(state: ChatDaemonState): boolean {
+		return (
+			hasSafeChatDaemonStateShape(state) &&
+			state.transportHealthy &&
+			Date.now() - state.heartbeatAt <= HEARTBEAT_TTL_MS
+		);
+	}
+	private classify(state: ChatDaemonState | undefined, identity: string | undefined): ChatDaemonStateClassification {
+		if (!state) return "absent";
+		if (isExactPreUpgradeUnavailableChatDaemonState(state)) return this.alive(state.pid) ? "malformed" : "stopped";
+		if (!hasSafeChatDaemonOwnerShape(state)) return "malformed";
+		if (this.isDefinitelyStoppedState(state)) return "stopped";
+		if (!identity || state.kind !== this.kind || state.identity !== identity) return "unauthorized";
+		if (hasSafeChatDaemonStateShape(state)) {
+			if (state.generation < chatDaemonGeneration(this.kind)) return "replaceable";
+			return state.generation > chatDaemonGeneration(this.kind) ? "newer" : "compatible";
+		}
+		const generation = (state as { generation?: unknown }).generation;
+		return isRecognizedLegacyGeneration(generation) ? "replaceable" : "malformed";
+	}
+	private isCurrentCompatibleState(state: ChatDaemonState, identity: string): boolean {
+		const classification = this.classify(state, identity);
+		return (
+			this.isSignalableMatchingOwner(state) &&
+			this.isHealthyFreshState(state) &&
+			(classification === "compatible" || classification === "newer")
+		);
+	}
+
 	private async stopForReplacement(state: ChatDaemonState): Promise<void> {
-		if (!this.isLiveState(state)) return;
+		if (!this.isSignalableMatchingOwner(state)) return;
+
 		const requestId = this.deps.randomId?.() ?? crypto.randomUUID();
 		await writeChatDaemonControlRequest(this.settings.getAgentDir(), this.kind, {
 			version: 1,
@@ -403,21 +669,35 @@ export class ChatDaemonController implements BuiltInDaemonController {
 			state.ownerId === before.ownerId &&
 			state.pid === before.pid &&
 			Boolean(state.incarnation) &&
-			this.incarnation(state.pid) === state.incarnation
+			this.isSignalableMatchingOwner(state)
 		);
 	}
 	private async signalIfOwner(state: ChatDaemonState, signal: NodeJS.Signals): Promise<boolean> {
 		const current = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
+		const identity = this.identity();
+		const classification = this.classify(current, identity);
 		if (
+			!identity ||
 			!current ||
 			current.ownerId !== state.ownerId ||
 			current.pid !== state.pid ||
+			current.identity !== state.identity ||
 			current.incarnation !== state.incarnation ||
-			this.incarnation(state.pid) !== state.incarnation
+			current.generation !== state.generation ||
+			(classification !== "compatible" && classification !== "replaceable") ||
+			!this.isSignalableMatchingOwner(current)
 		)
 			return false;
-		(this.deps.sendSignal ?? defaultSignal)(state.pid, signal);
-		return true;
+		const processRef = this.processReference(state.pid);
+		// Numeric PIDs can be reused after the ordinary provenance recheck. Only the
+		// native stable reference may perform this privileged signal operation.
+		if (!processRef || processRef.incarnation !== state.incarnation) return false;
+		try {
+			processRef.signalRoot(signal);
+			return true;
+		} catch {
+			return false;
+		}
 	}
 	private async ownerChanged(
 		action: ChatDaemonAction,
@@ -459,15 +739,10 @@ export class ChatDaemonController implements BuiltInDaemonController {
 		const paths = chatDaemonPaths(this.settings.getAgentDir(), this.kind);
 		await fs.promises.mkdir(paths.dir, { recursive: true, mode: 0o700 });
 		const existing = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
-		if (
-			existing &&
-			!existing.stoppedAt &&
-			existing.identity === identity &&
-			Date.now() - existing.heartbeatAt <= HEARTBEAT_TTL_MS &&
-			this.alive(existing.pid) &&
-			this.incarnation(existing.pid) === existing.incarnation
-		)
-			return false;
+		const classification = this.classify(existing, identity);
+		if (classification === "malformed" || classification === "unauthorized") return false;
+		if (existing && (this.isSignalableMatchingOwner(existing) || this.isAmbiguouslyLiveState(existing))) return false;
+
 		const ownerId = `${this.deps.ownerPid ?? process.ppid}-${this.deps.randomId?.() ?? crypto.randomUUID()}`;
 		const { command, args } = buildChatDaemonSpawnArgs({
 			kind: this.kind,
@@ -479,7 +754,26 @@ export class ChatDaemonController implements BuiltInDaemonController {
 			detached: true,
 			stdio: "ignore",
 		}).unref?.();
-		return true;
+		return await this.waitForOwnership(ownerId, identity);
+	}
+	private async waitForOwnership(ownerId: string, identity: string): Promise<boolean> {
+		const timeoutMs = Math.max(this.deps.spawnReadyTimeoutMs ?? DEFAULT_SPAWN_READY_TIMEOUT_MS, 0);
+		const until = Date.now() + timeoutMs;
+		const maxPolls = Math.ceil(timeoutMs / 25);
+		for (let poll = 0; poll <= maxPolls; poll++) {
+			const state = await readChatDaemonState(this.settings.getAgentDir(), this.kind);
+			const classification = state ? this.classify(state, identity) : undefined;
+			if (
+				state &&
+				state.ownerId === ownerId &&
+				(classification === "compatible" || classification === "newer") &&
+				this.isCurrentCompatibleState(state, identity)
+			)
+				return true;
+			if (Date.now() >= until || poll === maxPolls) return false;
+			await this.sleep(25);
+		}
+		return false;
 	}
 }
 
@@ -523,44 +817,132 @@ export async function acquireChatDaemonOwnership(input: {
 		pidAlive: input.pidAlive ?? defaultPidAlive,
 		pidIncarnation: input.pidIncarnation ?? processIncarnation,
 	};
-	const incarnation = input.incarnation ?? probe.pidIncarnation(pid) ?? "unavailable";
+	const incarnation = input.incarnation ?? probe.pidIncarnation(pid);
+	if (!hasProcessIncarnationAuthority(incarnation)) return false;
+
 	await fs.promises.mkdir(paths.dir, { recursive: true, mode: 0o700 });
-	if (!(await createChatDaemonOwnerLock(paths.lock, { pid, incarnation, createdAt: Date.now() }))) {
+	const existing = await readJson<unknown>(paths.state);
+	// A live record remains fenced unless authoritative provenance proves the PID
+	// was reused. This permits recovery without ever signaling that replacement.
+	if (hasChatDaemonStatePid(existing) && probe.pidAlive(existing.pid)) {
+		const current = probe.pidIncarnation(existing.pid);
+		if (
+			!hasSafeChatDaemonOwnerShape(existing) ||
+			!hasProcessIncarnationAuthority(current) ||
+			current === existing.incarnation
+		)
+			return false;
+	}
+	const owner = { pid, incarnation, createdAt: Date.now() };
+	let lock = await createChatDaemonOwnerLock(paths.lock, owner);
+	if (!lock) {
 		if (!(await reclaimChatDaemonOwnerLock(paths.lock, paths.state, probe))) return false;
-		if (!(await createChatDaemonOwnerLock(paths.lock, { pid, incarnation, createdAt: Date.now() }))) return false;
-	}
-
-	await withStateWriteLock(
-		paths.state,
-		async () =>
-			await writeJson(paths.state, {
-				version: 1,
-				kind: input.kind,
-				pid,
-				ownerId: input.ownerId,
-				identity: input.identity,
-				incarnation,
-				startedAt: Date.now(),
-				heartbeatAt: Date.now(),
-				transportHealthy: false,
-			} satisfies ChatDaemonState),
-	);
-	return true;
+		lock = await createChatDaemonOwnerLock(paths.lock, owner);
+		if (!lock) return false;
+	}
+	return await withStateWriteLock(paths.state, async () => {
+		if (!(await ownsChatDaemonOwnerLock(paths.lock, lock))) return false;
+		await writeJson(paths.state, {
+			version: 1,
+			kind: input.kind,
+			pid,
+			ownerId: input.ownerId,
+			identity: input.identity,
+			incarnation,
+			startedAt: Date.now(),
+			heartbeatAt: Date.now(),
+			transportHealthy: false,
+			generation: chatDaemonGeneration(input.kind),
+		} satisfies ChatDaemonState);
+		return true;
+	});
 }
 
-async function createChatDaemonOwnerLock(lock: string, owner: ChatDaemonOwnerLock): Promise<boolean> {
+async function createChatDaemonOwnerLock(
+	lock: string,
+	owner: ChatDaemonOwnerLock,
+): Promise<ChatDaemonOwnerLockLease | undefined> {
+	const content = `${JSON.stringify(owner)}\n`;
+	const temporary = `${lock}.${process.pid}.${crypto.randomUUID()}.tmp`;
 	try {
-		const handle = await fs.promises.open(lock, "wx", 0o600);
+		const handle = await fs.promises.open(temporary, "wx", 0o600);
 		try {
-			await handle.writeFile(`${JSON.stringify(owner)}\n`, "utf8");
+			await handle.writeFile(content, "utf8");
 			await handle.sync();
 		} finally {
 			await handle.close();
 		}
-		return true;
-	} catch (error) {
-		if (isAlreadyExists(error)) return false;
-		throw error;
+		try {
+			await fs.promises.link(temporary, lock);
+		} catch (error) {
+			if (isAlreadyExists(error)) return undefined;
+			throw error;
+		}
+		return await captureChatDaemonOwnerLockLease(lock);
+	} finally {
+		await fs.promises.unlink(temporary).catch(() => undefined);
+	}
+}
+
+async function captureChatDaemonOwnerLockLease(lock: string): Promise<ChatDaemonOwnerLockLease | undefined> {
+	try {
+		const handle = await fs.promises.open(lock, "r");
+		try {
+			const before = await handle.stat({ bigint: true });
+			if (!before.isFile()) return undefined;
+			const content = await handle.readFile({ encoding: "utf8" });
+			const after = await handle.stat({ bigint: true });
+			const pathname = await fs.promises.lstat(lock, { bigint: true });
+			if (
+				!after.isFile() ||
+				!pathname.isFile() ||
+				pathname.isSymbolicLink() ||
+				before.dev !== after.dev ||
+				before.ino !== after.ino ||
+				before.size !== after.size ||
+				before.mtimeNs !== after.mtimeNs ||
+				before.dev !== pathname.dev ||
+				before.ino !== pathname.ino ||
+				before.size !== pathname.size ||
+				before.mtimeNs !== pathname.mtimeNs
+			)
+				return undefined;
+			return {
+				content,
+				dev: before.dev,
+				ino: before.ino,
+				size: before.size,
+				mtimeNs: before.mtimeNs,
+				sha256: crypto.createHash("sha256").update(content).digest("hex"),
+			};
+		} finally {
+			await handle.close();
+		}
+	} catch {
+		return undefined;
+	}
+}
+
+async function ownsChatDaemonOwnerLock(lock: string, lease: ChatDaemonOwnerLockLease): Promise<boolean> {
+	const current = await captureChatDaemonOwnerLockLease(lock);
+	return (
+		current?.dev === lease.dev &&
+		current.ino === lease.ino &&
+		current.size === lease.size &&
+		current.mtimeNs === lease.mtimeNs &&
+		current.content === lease.content
+	);
+}
+
+/** Deletes only the exact lease observed by this contender; a successor is retained. */
+function unlinkExactChatDaemonOwnerLock(lock: string, lease: ChatDaemonOwnerLockLease): boolean {
+	try {
+		return native.exactUnlink(lock, {
+			...lease,
+			quarantineName: `.gjc-delete-chat-daemon-lock-${crypto.randomUUID()}`,
+		}).ok;
+	} catch {
+		return false;
 	}
 }
 
@@ -570,64 +952,68 @@ async function reclaimChatDaemonOwnerLock(
 	probe: ChatDaemonOwnershipProbe,
 ): Promise<boolean> {
 	if (!(await canReclaimChatDaemonOwnerLock(lock, stateFile, probe))) return false;
-
 	const reclaimFile = `${lock}.reclaim`;
 	const reclaimLock = await acquireChatDaemonReclaimLock(reclaimFile, probe);
-
 	if (!reclaimLock) return false;
 	try {
-		if (!(await canReclaimChatDaemonOwnerLock(lock, stateFile, probe))) return false;
-
-		await fs.promises.unlink(lock).catch(() => undefined);
-		return true;
+		const ownerLock = await canReclaimChatDaemonOwnerLock(lock, stateFile, probe);
+		return !!ownerLock && unlinkExactChatDaemonOwnerLock(lock, ownerLock);
 	} finally {
-		await reclaimLock.close().catch(() => undefined);
-		await fs.promises.unlink(reclaimFile).catch(() => undefined);
+		unlinkExactChatDaemonOwnerLock(reclaimFile, reclaimLock);
 	}
 }
 
 async function acquireChatDaemonReclaimLock(
 	reclaimFile: string,
 	probe: ChatDaemonOwnershipProbe,
-): Promise<{ close(): Promise<void> } | undefined> {
-	const owner: ChatDaemonOwnerLock = {
-		pid: process.pid,
-		incarnation: probe.pidIncarnation(process.pid) ?? "unavailable",
-		createdAt: Date.now(),
-	};
-	if (await createChatDaemonOwnerLock(reclaimFile, owner)) return await fs.promises.open(reclaimFile, "r+");
-	if (!(await isStaleChatDaemonLock(reclaimFile, probe))) return undefined;
-	await fs.promises.unlink(reclaimFile).catch(() => undefined);
-	if (!(await createChatDaemonOwnerLock(reclaimFile, owner))) return undefined;
-	return await fs.promises.open(reclaimFile, "r+");
+): Promise<ChatDaemonOwnerLockLease | undefined> {
+	const incarnation = probe.pidIncarnation(process.pid);
+	if (!hasProcessIncarnationAuthority(incarnation)) return undefined;
+	const owner: ChatDaemonOwnerLock = { pid: process.pid, incarnation, createdAt: Date.now() };
+	const created = await createChatDaemonOwnerLock(reclaimFile, owner);
+	if (created) return created;
+	const stale = await staleChatDaemonLockLease(reclaimFile, probe);
+	if (!stale || !unlinkExactChatDaemonOwnerLock(reclaimFile, stale)) return undefined;
+	return await createChatDaemonOwnerLock(reclaimFile, owner);
 }
 
-async function isStaleChatDaemonLock(lock: string, probe: ChatDaemonOwnershipProbe): Promise<boolean> {
+async function staleChatDaemonLockLease(
+	lock: string,
+	probe: ChatDaemonOwnershipProbe,
+): Promise<ChatDaemonOwnerLockLease | undefined> {
+	const lease = await captureChatDaemonOwnerLockLease(lock);
+	if (!lease) return undefined;
 	let owner: unknown;
 	try {
-		owner = JSON.parse(await fs.promises.readFile(lock, "utf8"));
-	} catch {}
-	if (isChatDaemonOwnerLock(owner)) {
-		const currentIncarnation = probe.pidIncarnation(owner.pid);
-		return (
-			!probe.pidAlive(owner.pid) ||
-			(owner.incarnation !== "unavailable" &&
-				(!isProcessIncarnation(owner.incarnation) ||
-					(currentIncarnation !== undefined && currentIncarnation !== owner.incarnation)))
-		);
+		owner = JSON.parse(lease.content);
+	} catch {
+		return undefined;
 	}
-	const stat = await fs.promises.stat(lock).catch(() => undefined);
-	return Boolean(stat && Date.now() - stat.mtimeMs >= UNPUBLISHED_OWNER_LOCK_STALE_MS);
+	if (!isChatDaemonOwnerLock(owner)) return undefined;
+	if (!probe.pidAlive(owner.pid)) return lease;
+	if (!hasProcessIncarnationAuthority(owner.incarnation)) return undefined;
+	const currentIncarnation = probe.pidIncarnation(owner.pid);
+	return hasProcessIncarnationAuthority(currentIncarnation) && currentIncarnation !== owner.incarnation
+		? lease
+		: undefined;
 }
 
 async function canReclaimChatDaemonOwnerLock(
 	lock: string,
 	stateFile: string,
 	probe: ChatDaemonOwnershipProbe,
-): Promise<boolean> {
-	const state = await readJson<ChatDaemonState>(stateFile);
-	if (state && probe.pidAlive(state.pid) && probe.pidIncarnation(state.pid) === state.incarnation) return false;
-	return await isStaleChatDaemonLock(lock, probe);
+): Promise<ChatDaemonOwnerLockLease | undefined> {
+	const state = await readJson<unknown>(stateFile);
+	if (hasChatDaemonStatePid(state) && probe.pidAlive(state.pid)) {
+		const current = probe.pidIncarnation(state.pid);
+		if (
+			!hasSafeChatDaemonOwnerShape(state) ||
+			!hasProcessIncarnationAuthority(current) ||
+			current === state.incarnation
+		)
+			return undefined;
+	}
+	return await staleChatDaemonLockLease(lock, probe);
 }
 
 function isChatDaemonOwnerLock(value: unknown): value is ChatDaemonOwnerLock {
@@ -652,17 +1038,25 @@ export async function renewChatDaemonHeartbeat(input: {
 	pid?: number;
 	incarnation?: string;
 	transportHealthy: boolean;
+	pidAlive?: (pid: number) => boolean;
+	pidIncarnation?: (pid: number) => string | undefined;
 }): Promise<boolean> {
 	const paths = chatDaemonPaths(input.agentDir, input.kind);
+	const pidAlive = input.pidAlive ?? defaultPidAlive;
+	const pidIncarnation = input.pidIncarnation ?? defaultPidIncarnation;
 	return await withStateWriteLock(paths.state, async () => {
-		const state = await readJson<ChatDaemonState>(paths.state);
-		const pid = input.pid ?? state?.pid;
+		const state = await readJson<unknown>(paths.state);
+		if (!hasSafeChatDaemonStateShape(state)) return false;
+		const pid = input.pid ?? state.pid;
+		const currentIncarnation = pidIncarnation(pid);
 		if (
-			!state ||
 			state.ownerId !== input.ownerId ||
 			pid !== state.pid ||
-			!input.incarnation ||
-			state.incarnation !== input.incarnation
+			!hasProcessIncarnationAuthority(input.incarnation) ||
+			state.incarnation !== input.incarnation ||
+			!pidAlive(pid) ||
+			!hasProcessIncarnationAuthority(currentIncarnation) ||
+			currentIncarnation !== input.incarnation
 		)
 			return false;
 		await writeJson(paths.state, { ...state, heartbeatAt: Date.now(), transportHealthy: input.transportHealthy });
@@ -673,21 +1067,35 @@ export async function releaseChatDaemonOwnership(input: {
 	agentDir: string;
 	kind: ChatDaemonKind;
 	ownerId: string;
-	pid?: number;
-	incarnation?: string;
+	pid: number;
+	incarnation: string;
+	pidAlive?: (pid: number) => boolean;
+	pidIncarnation?: (pid: number) => string | undefined;
 }): Promise<void> {
 	const paths = chatDaemonPaths(input.agentDir, input.kind);
+	const pidAlive = input.pidAlive ?? defaultPidAlive;
+	const pidIncarnation = input.pidIncarnation ?? defaultPidIncarnation;
 	await withStateWriteLock(paths.state, async () => {
-		const state = await readJson<ChatDaemonState>(paths.state);
+		const state = await readJson<unknown>(paths.state);
+		const currentIncarnation = pidIncarnation(input.pid);
 		if (
-			state?.ownerId !== input.ownerId ||
-			(input.pid !== undefined && state.pid !== input.pid) ||
-			(input.incarnation !== undefined && state.incarnation !== input.incarnation)
+			!hasSafeChatDaemonStateShape(state) ||
+			!hasProcessIncarnationAuthority(input.incarnation) ||
+			state.ownerId !== input.ownerId ||
+			state.pid !== input.pid ||
+			state.incarnation !== input.incarnation ||
+			!pidAlive(input.pid) ||
+			!hasProcessIncarnationAuthority(currentIncarnation) ||
+			currentIncarnation !== input.incarnation
 		)
 			return;
 		await writeJson(paths.state, { ...state, stoppedAt: Date.now(), transportHealthy: false });
-		const lock = await readJson<ChatDaemonOwnerLock>(paths.lock);
-		if (lock?.pid === state.pid && lock.incarnation === state.incarnation)
-			await fs.promises.unlink(paths.lock).catch(() => undefined);
+		const lock = await captureChatDaemonOwnerLockLease(paths.lock);
+		let owner: unknown;
+		try {
+			owner = lock && JSON.parse(lock.content);
+		} catch {}
+		if (lock && isChatDaemonOwnerLock(owner) && owner.pid === state.pid && owner.incarnation === state.incarnation)
+			unlinkExactChatDaemonOwnerLock(paths.lock, lock);
 	});
 }