@gajae-code/coding-agent 0.11.7 → 0.11.9

package/src/sdk/bus/telegram-daemon.ts

@@ -37,7 +37,7 @@ import {
 	type TelegramDaemonControlDeps,
 	TelegramDaemonController,
 } from "./telegram-daemon-control";
-import { withTelegramSetupLease } from "./telegram-setup";
+import { type TelegramSetupPreflight, withTelegramSetupLease } from "./telegram-setup";
 
 export { DAEMON_GENERATION, NOTIFICATION_PROTOCOL_VERSION } from "./telegram-daemon-contract";
 
@@ -143,7 +143,7 @@ export interface TelegramDaemonFs {
 	open(path: string, flags: string, mode?: number): Promise<{ close(): Promise<void> }>;
 	readdir(path: string): Promise<string[]>;
 	chmod(path: string, mode: number): Promise<void>;
-	stat?(path: string): Promise<{ mtimeMs: number }>;
+	stat?(path: string): Promise<{ mtimeMs: number; size?: number; dev?: number; ino?: number; ctimeMs?: number }>;
 	readEndpointFile?(path: string): Promise<NotificationEndpointFile>;
 	exactUnlink?(path: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
 }
@@ -231,6 +231,37 @@ const BOT_API_RETRY_ATTEMPTS = 3;
 // Backoff after a failed getUpdates long-poll so a persistent outage does not
 // busy-loop the daemon.
 const POLL_BACKOFF_MS = 1_000;
+const AUTOMATIC_RELOAD_COOLDOWN_MS = 10 * 60 * 1_000;
+// Default freshness-poll window a cooldown contender waits for a sibling's
+// replacement daemon to publish a fresh ready owner before reloading itself.
+const RELOAD_FRESHNESS_WAIT_MS = 15_000;
+// Cooperative-then-forced termination + replacement-readiness bounds the reload
+// controller can spend while holding the reservation lock (mirrors the control
+// plane's graceful/kill defaults plus a readiness wait).
+const RELOAD_CONTROLLER_GRACEFUL_MS = 8_000;
+const RELOAD_CONTROLLER_KILL_MS = 3_000;
+const RELOAD_RESERVATION_HEADROOM_MS = 10_000;
+
+/**
+ * File-lock options whose acquisition budget covers the full reload-reservation
+ * critical section: the in-lock freshness poll plus the controller's
+ * graceful+kill+readiness sequence, with headroom. A contender must be able to
+ * wait out a legitimate slow reload and then attach, never fail startup.
+ */
+export function reloadReservationLockOptions(input: {
+	freshnessWaitMs: number;
+	readinessTimeoutMs: number;
+	retryDelayMs?: number;
+}): { staleMs: number; retries: number; retryDelayMs: number } {
+	const retryDelayMs = Math.max(input.retryDelayMs ?? 100, 1);
+	const criticalMs =
+		Math.max(input.freshnessWaitMs, 0) +
+		RELOAD_CONTROLLER_GRACEFUL_MS +
+		RELOAD_CONTROLLER_KILL_MS +
+		Math.max(input.readinessTimeoutMs, 0) +
+		RELOAD_RESERVATION_HEADROOM_MS;
+	return { staleMs: 10_000, retries: Math.max(1, Math.ceil(criticalMs / retryDelayMs)), retryDelayMs };
+}
 // Telegram clears a chat action after ~5s; refresh slightly sooner to keep the
 // typing indicator alive while the agent is busy.
 const TYPING_REFRESH_INTERVAL_MS = 4_000;
@@ -507,9 +538,17 @@ type LegacyOwnershipLockMetadata = {
 	incarnation?: string;
 	startedAt: number;
 };
+type V010OwnershipLockMetadata = {
+	size: 0;
+	mtimeMs?: number;
+	dev?: number;
+	ino?: number;
+	ctimeMs?: number;
+};
 type OwnershipLockRead =
 	| { kind: "missing" }
 	| { kind: "malformed"; raw: string; mtimeMs?: number }
+	| { kind: "v010"; metadata: V010OwnershipLockMetadata }
 	| { kind: "legacy"; metadata: LegacyOwnershipLockMetadata }
 	| { kind: "valid"; metadata: OwnershipLockMetadata };
 
@@ -522,6 +561,20 @@ export async function readOwnershipLock(fsImpl: TelegramDaemonFs, file: string):
 		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { kind: "missing" };
 		throw error;
 	}
+	if (raw.length === 0) {
+		const stat = await fsImpl.stat?.(file).catch(() => undefined);
+		if (stat?.size !== 0) return { kind: "malformed", raw, mtimeMs: stat?.mtimeMs };
+		return {
+			kind: "v010",
+			metadata: {
+				size: 0,
+				...(stat?.mtimeMs === undefined ? {} : { mtimeMs: stat.mtimeMs }),
+				...(stat?.dev === undefined ? {} : { dev: stat.dev }),
+				...(stat?.ino === undefined ? {} : { ino: stat.ino }),
+				...(stat?.ctimeMs === undefined ? {} : { ctimeMs: stat.ctimeMs }),
+			},
+		};
+	}
 	try {
 		const value = JSON.parse(raw) as Partial<OwnershipLockMetadata>;
 		const pid = value.pid;
@@ -564,6 +617,7 @@ export function liveOwnershipLockDecision(input: {
 	| { acquired: false; attached: false; blocked: true }
 	| { acquired: false; attached: false; provisional: true }
 	| undefined {
+	if (input.lock.kind === "v010") return { acquired: false, attached: false, blocked: true };
 	if (input.lock.kind !== "valid" && input.lock.kind !== "legacy") return undefined;
 	if (!input.pidAlive(input.lock.metadata.pid)) return undefined;
 	if (input.lock.kind === "legacy") {
@@ -585,8 +639,9 @@ function ownershipLockMatches(left: OwnershipLockRead, right: OwnershipLockRead)
 	if (left.kind === "missing") return true;
 	if (left.kind === "malformed" && right.kind === "malformed")
 		return left.raw === right.raw && left.mtimeMs !== undefined && left.mtimeMs === right.mtimeMs;
-	if ((left.kind !== "valid" && left.kind !== "legacy") || (right.kind !== "valid" && right.kind !== "legacy"))
-		return false;
+	if ((left.kind === "legacy" && right.kind === "legacy") || (left.kind === "v010" && right.kind === "v010"))
+		return JSON.stringify(left.metadata) === JSON.stringify(right.metadata);
+	if (left.kind !== "valid" || right.kind !== "valid") return false;
 	return JSON.stringify(left.metadata) === JSON.stringify(right.metadata);
 }
 
@@ -601,10 +656,22 @@ function ownershipLockMatchesState(lock: OwnershipLockRead, state: DaemonState |
 	);
 }
 
-function ownershipLockMatchesStoppedState(lock: OwnershipLockRead, state: unknown): boolean {
+function ownershipLockMatchesStoppedState(
+	lock: OwnershipLockRead,
+	state: unknown,
+	pidAlive: (pid: number) => boolean,
+): boolean {
 	if (isExplicitlyStoppedDaemonState(state)) return ownershipLockMatchesState(lock, state);
-	if (!isLegacyStoppedDaemonState(state) || lock.kind !== "legacy") return false;
-	const legacyState = state as Pick<DaemonState, "pid" | "startedAt"> & { stoppedAt: number };
+	if (!isLegacyStoppedDaemonState(state)) return false;
+	const legacyState = state as Pick<DaemonState, "pid" | "startedAt" | "generation"> & { stoppedAt: number };
+	if (lock.kind === "v010")
+		return (
+			legacyState.generation === 3 &&
+			!pidAlive(legacyState.pid) &&
+			lock.metadata.mtimeMs !== undefined &&
+			lock.metadata.mtimeMs <= legacyState.stoppedAt
+		);
+	if (lock.kind !== "legacy") return false;
 	return (
 		lock.metadata.pid === legacyState.pid &&
 		lock.metadata.startedAt <= legacyState.startedAt &&
@@ -624,6 +691,37 @@ function ownershipLockMatchesMetadata(lock: OwnershipLockRead, metadata: Ownersh
 	return lock.kind === "valid" && JSON.stringify(lock.metadata) === JSON.stringify(metadata);
 }
 
+/**
+ * Accept an exact unlink only when it either completed or returned typed
+ * retained authority — a concrete detached quarantine plus a proven-absent
+ * canonical pathname. Anything else stays fail-closed.
+ */
+async function exactUnlinkAcceptedWithRetainedEvidence(
+	fsImpl: TelegramDaemonFs,
+	file: string,
+	identity: NotificationEndpointFileIdentity,
+): Promise<boolean> {
+	const removed = await fsImpl.exactUnlink!(file, identity);
+	if (removed.ok) return true;
+	return (
+		removed.code === "cleanup_pending" &&
+		typeof removed.detachedPath === "string" &&
+		removed.detachedPath.length > 0 &&
+		(await fsImpl.readEndpointFile!(file).catch(() => undefined)) === undefined
+	);
+}
+
+async function unlinkOwnershipLockExactly(
+	fsImpl: TelegramDaemonFs,
+	file: string,
+	expected: OwnershipLockRead,
+): Promise<boolean> {
+	if (expected.kind === "missing" || !fsImpl.readEndpointFile || !fsImpl.exactUnlink) return false;
+	const endpoint = await fsImpl.readEndpointFile(file).catch(() => undefined);
+	if (!endpoint || !ownershipLockMatches(expected, await readOwnershipLock(fsImpl, file))) return false;
+	return await exactUnlinkAcceptedWithRetainedEvidence(fsImpl, file, endpoint.identity);
+}
+
 /**
  * Replace an acquisition's lease only after proving the old lease is unchanged.
  * The transition fence serializes lifecycle writers; the exact read-back prevents
@@ -687,6 +785,7 @@ async function ownershipLockIsReclaimable(input: {
 	pidIncarnation: (pid: number) => string | undefined;
 }): Promise<boolean> {
 	if (input.lock.kind === "missing") return true;
+	if (input.lock.kind === "v010") return false;
 	if (input.lock.kind === "malformed") {
 		if (!input.fs.stat) return false;
 		const stat = await input.fs.stat(input.path).catch(() => undefined);
@@ -870,6 +969,172 @@ function notificationRootForCwd(cwd: string): string {
 	return path.join(cwd, ".gjc", "state");
 }
 
+/**
+ * Leak artifact prefixes left when native exact-unlink cleanup is retained
+ * (#2956). Nothing previously reaped these; they accumulate in the notifications
+ * directory across ownership transitions.
+ */
+export const NOTIFICATION_LEAK_ARTIFACT_PREFIXES = [
+	".gjc-delete-daemon-transition-",
+	".gjc-exact-unlink-placeholder-",
+	".gjc-delete-notification-endpoint-",
+] as const;
+
+/** Grace window before a leak artifact is reaped (covers in-flight unlinks). */
+export const NOTIFICATION_LEAK_ARTIFACT_GRACE_MS = 5 * 60_000;
+
+/** True when a path is permanently gone (not a transient I/O blip). */
+export function isPermanentMissingPathError(error: unknown): boolean {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+}
+
+export function isNotificationLeakArtifactName(name: string): boolean {
+	return NOTIFICATION_LEAK_ARTIFACT_PREFIXES.some(prefix => name.startsWith(prefix));
+}
+
+type NotificationRootsRegistry = {
+	version?: number;
+	roots?: string[];
+	managedRoots?: string[];
+	sessions?: Record<string, string>;
+};
+
+/**
+ * Drop permanently missing scan roots from the durable registry under the roots
+ * lock. Session map entries that pointed only at those roots are removed too.
+ */
+export async function pruneMissingNotificationRoots(input: {
+	settings: Settings;
+	fs?: TelegramDaemonFs;
+	/** When set, only these roots are considered; otherwise every registered root is probed. */
+	candidates?: readonly string[];
+}): Promise<{ pruned: string[]; remaining: number }> {
+	const fsImpl = input.fs ?? nodeFs;
+	const paths = daemonPaths(input.settings.getAgentDir());
+	await ensureDir(fsImpl, paths.dir);
+	const pruned: string[] = [];
+	let remaining = 0;
+	await withFileLock(
+		paths.roots,
+		async () => {
+			const current = (await readJson<NotificationRootsRegistry>(fsImpl, paths.roots)) ?? {};
+			const roots = [...(current.roots ?? [])];
+			const managedRoots = new Set(current.managedRoots ?? []);
+			const sessions = { ...(current.sessions ?? {}) };
+			const candidateSet = input.candidates ? new Set(input.candidates) : undefined;
+			const survivors: string[] = [];
+			for (const root of roots) {
+				if (candidateSet && !candidateSet.has(root)) {
+					survivors.push(root);
+					continue;
+				}
+				const sdkDir = path.join(root, "sdk");
+				try {
+					await fsImpl.readdir(sdkDir);
+					survivors.push(root);
+				} catch (error) {
+					if (!isPermanentMissingPathError(error)) {
+						// Transient unreadable: keep for the next pass.
+						survivors.push(root);
+						continue;
+					}
+					// Also accept a missing sdk dir when the root itself is still a directory
+					// (empty registration) — still permanently useless for scans.
+					try {
+						await fsImpl.readdir(root);
+					} catch (rootError) {
+						if (!isPermanentMissingPathError(rootError)) {
+							survivors.push(root);
+							continue;
+						}
+					}
+					pruned.push(root);
+					managedRoots.delete(root);
+					for (const [sessionId, mapped] of Object.entries(sessions)) {
+						if (mapped === root) delete sessions[sessionId];
+					}
+				}
+			}
+			remaining = survivors.length;
+			if (pruned.length === 0) return;
+			await writeJsonAtomic(fsImpl, paths.roots, {
+				version: 1,
+				roots: Array.from(new Set(survivors)).sort(),
+				managedRoots: Array.from(managedRoots).sort(),
+				sessions,
+			});
+		},
+		{ staleMs: 10_000 },
+	);
+	return { pruned, remaining };
+}
+
+/**
+ * Reap retained exact-unlink / ownership-transition quarantine files older than
+ * the grace window from the notifications directory.
+ */
+export async function reapStaleNotificationArtifacts(input: {
+	settings: Settings;
+	fs?: TelegramDaemonFs;
+	now?: () => number;
+	graceMs?: number;
+}): Promise<{ removed: string[]; skipped: number }> {
+	const fsImpl = input.fs ?? nodeFs;
+	const paths = daemonPaths(input.settings.getAgentDir());
+	await ensureDir(fsImpl, paths.dir);
+	const now = input.now?.() ?? Date.now();
+	const graceMs = input.graceMs ?? NOTIFICATION_LEAK_ARTIFACT_GRACE_MS;
+	const removed: string[] = [];
+	let skipped = 0;
+	let names: string[];
+	try {
+		names = await fsImpl.readdir(paths.dir);
+	} catch (error) {
+		if (isPermanentMissingPathError(error)) return { removed, skipped };
+		throw error;
+	}
+	for (const name of names) {
+		if (!isNotificationLeakArtifactName(name)) continue;
+		const file = path.join(paths.dir, name);
+		try {
+			const stat = fsImpl.stat ? await fsImpl.stat(file) : undefined;
+			const age = stat ? now - stat.mtimeMs : Number.POSITIVE_INFINITY;
+			if (Number.isFinite(age) && age < graceMs) {
+				skipped += 1;
+				continue;
+			}
+			await fsImpl.unlink(file);
+			removed.push(file);
+		} catch (error) {
+			if (isPermanentMissingPathError(error)) continue;
+			// Best-effort: a busy file must not fail daemon ownership.
+			skipped += 1;
+		}
+	}
+	return { removed, skipped };
+}
+
+/**
+ * Startup / ownership self-heal: prune dead roots and reap leak artifacts so
+ * `gjc daemon reload` recovers a degraded install without manual surgery (#2956).
+ */
+export async function healTelegramDaemonNotificationState(input: {
+	settings: Settings;
+	fs?: TelegramDaemonFs;
+	now?: () => number;
+	graceMs?: number;
+}): Promise<{ prunedRoots: string[]; removedArtifacts: string[] }> {
+	const prune = await pruneMissingNotificationRoots(input);
+	const reap = await reapStaleNotificationArtifacts(input);
+	if (prune.pruned.length > 0 || reap.removed.length > 0) {
+		logger.warn(
+			`notifications: self-heal pruned ${prune.pruned.length} dead root(s), reaped ${reap.removed.length} leak artifact(s)`,
+		);
+	}
+	return { prunedRoots: prune.pruned, removedArtifacts: reap.removed };
+}
+
 function validBotToken(token: unknown): token is string {
 	return typeof token === "string" && token.trim().length > 0;
 }
@@ -959,24 +1224,98 @@ export function hasSafeDaemonStateShape(state: unknown): state is DaemonState {
 	);
 }
 
-type LegacyParentDaemonState = Omit<DaemonState, "incarnation" | "acquisitionId" | "ownershipPhase" | "generation"> & {
+const V010_PARENT_STATE_KEYS = [
+	"pid",
+	"ownerId",
+	"tokenFingerprint",
+	"chatId",
+	"startedAt",
+	"heartbeatAt",
+	"roots",
+	"version",
+] as const;
+const V010_GENERATION_3_PARENT_STATE_KEYS = [...V010_PARENT_STATE_KEYS, "generation"] as const;
+
+type ParentDaemonStateBase = Omit<
+	DaemonState,
+	"incarnation" | "acquisitionId" | "ownershipPhase" | "generation" | "launcherPid"
+> & {
 	incarnation?: undefined;
 	acquisitionId?: undefined;
 	ownershipPhase?: undefined;
+	generation?: unknown;
+	launcherPid?: undefined;
+};
+type GenerationAbsentParentDaemonState = Omit<ParentDaemonStateBase, "generation"> & {
 	generation?: undefined;
 };
+type Generation3ReleaseDaemonState = Omit<ParentDaemonStateBase, "generation"> & {
+	generation: 3;
+};
+export type LegacyParentDaemonState = GenerationAbsentParentDaemonState | Generation3ReleaseDaemonState;
 
 interface LegacyMigrationAttestation {
+	stateDigest: string;
+	confirmed?: true;
+	lock?: V010OwnershipLockMetadata;
 	pid: number;
 	incarnation: string;
 	heartbeatAt: number;
 	observedAt: number;
+	tokenFingerprint: string;
+	chatId: string;
+}
+
+function historicalStateSerializer(state: LegacyParentDaemonState): string {
+	const historicalState = {
+		pid: state.pid,
+		ownerId: state.ownerId,
+		tokenFingerprint: state.tokenFingerprint,
+		chatId: state.chatId,
+		startedAt: state.startedAt,
+		heartbeatAt: state.heartbeatAt,
+		roots: state.roots,
+		version: state.version,
+		...(state.generation === undefined ? {} : { generation: 3 }),
+	};
+	return `${JSON.stringify(historicalState, null, 2)}\n`;
+}
+
+function legacyParentStateDigest(state: LegacyParentDaemonState): string {
+	const { heartbeatAt: _heartbeatAt, ...immutableState } = state;
+	return crypto
+		.createHash("sha256")
+		.update(historicalStateSerializer({ ...immutableState, heartbeatAt: 0 }))
+		.digest("hex");
+}
+
+function hasExactParentStateKeys(state: object, keys: readonly string[]): boolean {
+	const actual = Object.keys(state);
+	return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+
+function isGenerationAbsentParentDaemonState(state: unknown): state is GenerationAbsentParentDaemonState {
+	return hasParentDaemonStateShape(state) && hasExactParentStateKeys(state, V010_PARENT_STATE_KEYS);
+}
+
+function isGeneration3ReleaseDaemonState(state: unknown): state is Generation3ReleaseDaemonState {
+	return (
+		hasParentDaemonStateShape(state) &&
+		state.generation === 3 &&
+		hasExactParentStateKeys(state, V010_GENERATION_3_PARENT_STATE_KEYS)
+	);
 }
 
-function isLegacyParentDaemonState(state: unknown): state is LegacyParentDaemonState {
-	const candidate = state as Partial<LegacyParentDaemonState> | undefined;
+function isParentDaemonState(state: unknown): state is LegacyParentDaemonState {
+	return isGenerationAbsentParentDaemonState(state) || isGeneration3ReleaseDaemonState(state);
+}
+
+function hasParentDaemonStateShape(state: unknown): state is ParentDaemonStateBase {
+	const candidate = state as Partial<ParentDaemonStateBase> | undefined;
 	return Boolean(
 		candidate &&
+			typeof candidate === "object" &&
+			!Array.isArray(candidate) &&
 			Number.isSafeInteger(candidate.pid) &&
 			(candidate.pid ?? 0) > 0 &&
 			typeof candidate.ownerId === "string" &&
@@ -991,11 +1330,70 @@ function isLegacyParentDaemonState(state: unknown): state is LegacyParentDaemonS
 			candidate.incarnation === undefined &&
 			candidate.acquisitionId === undefined &&
 			candidate.ownershipPhase === undefined &&
-			candidate.generation === undefined &&
-			candidate.stoppedAt === undefined,
+			candidate.launcherPid === undefined &&
+			candidate.stoppedAt === undefined &&
+			(candidate.generation === undefined || candidate.generation === 3),
 	);
 }
 
+const isLegacyParentDaemonState = isParentDaemonState;
+
+/**
+ * A live v0.10-shaped record is authority only in its exact historical form.
+ * Parsed JSON alone cannot establish that form: field order and serialization
+ * bytes are part of the migration attestation.
+ */
+async function isLiveNoncanonicalParentState(input: {
+	fs: TelegramDaemonFs;
+	statePath: string;
+	state: unknown;
+	pidAlive: (pid: number) => boolean;
+	pidIncarnation: (pid: number) => string | undefined;
+	tokenFingerprint: string;
+	chatId: string;
+}): Promise<boolean> {
+	const candidate = input.state as Partial<ParentDaemonStateBase> | undefined;
+	if (
+		!candidate ||
+		typeof candidate !== "object" ||
+		Array.isArray(candidate) ||
+		!validDaemonPid(candidate.pid) ||
+		typeof candidate.ownerId !== "string" ||
+		candidate.ownerId.length === 0 ||
+		typeof candidate.tokenFingerprint !== "string" ||
+		typeof candidate.chatId !== "string" ||
+		!Number.isSafeInteger(candidate.startedAt) ||
+		!Number.isSafeInteger(candidate.heartbeatAt) ||
+		!Array.isArray(candidate.roots) ||
+		!candidate.roots.every(root => typeof root === "string") ||
+		candidate.version !== DAEMON_VERSION ||
+		!input.pidAlive(candidate.pid)
+	)
+		return false;
+	if (
+		isStoppedDaemonState(candidate) ||
+		(candidate.incarnation !== undefined &&
+			(candidate.acquisitionId !== undefined || candidate.ownershipPhase !== undefined))
+	)
+		return false;
+	if (
+		candidate.incarnation !== undefined &&
+		isProcessIncarnation(input.pidIncarnation(candidate.pid)) &&
+		input.pidIncarnation(candidate.pid) !== candidate.incarnation &&
+		!(candidate.tokenFingerprint === input.tokenFingerprint && candidate.chatId === input.chatId)
+	)
+		return false;
+	if (!isParentDaemonState(candidate)) return true;
+	try {
+		return (await input.fs.readFile(input.statePath, "utf8")) !== historicalStateSerializer(candidate);
+	} catch {
+		return false;
+	}
+}
+function legacyOwnershipLockMatchesHandoffState(lock: OwnershipLockRead, state: unknown): boolean {
+	return lock.kind === "v010" && isGeneration3ReleaseDaemonState(state);
+}
+
 function legacyMigrationAttestationPath(statePath: string): string {
 	return `${statePath}.legacy-migration.json`;
 }
@@ -1003,6 +1401,7 @@ function legacyMigrationAttestationPath(statePath: string): string {
 async function legacyParentHandoffDecision(input: {
 	fs: TelegramDaemonFs;
 	statePath: string;
+	lockPath: string;
 	state: LegacyParentDaemonState;
 	now: number;
 	pidAlive: (pid: number) => boolean;
@@ -1010,7 +1409,15 @@ async function legacyParentHandoffDecision(input: {
 	tokenFingerprint: string;
 	chatId: string;
 }): Promise<
-	{ acquired: false; attached: false; provisional?: boolean; reloadRequired?: boolean; blocked?: boolean } | undefined
+	| {
+			acquired: false;
+			attached: false;
+			provisional?: boolean;
+			reloadRequired?: boolean;
+			legacyReloadRequired?: boolean;
+			blocked?: boolean;
+	  }
+	| undefined
 > {
 	const { state } = input;
 	if (!input.pidAlive(state.pid)) return undefined;
@@ -1018,33 +1425,133 @@ async function legacyParentHandoffDecision(input: {
 		return { acquired: false, attached: false, blocked: true };
 	const incarnation = input.pidIncarnation(state.pid);
 	if (!isProcessIncarnation(incarnation)) return { acquired: false, attached: false, blocked: true };
-	const attestationPath = legacyMigrationAttestationPath(input.statePath);
-	const previous = await readJson<LegacyMigrationAttestation>(input.fs, attestationPath);
+	let stateBytes: string;
+	try {
+		stateBytes = await input.fs.readFile(input.statePath, "utf8");
+	} catch {
+		return { acquired: false, attached: false, provisional: true };
+	}
+	if (stateBytes !== historicalStateSerializer(state)) return { acquired: false, attached: false, blocked: true };
+	const lock = await readOwnershipLock(input.fs, input.lockPath);
+	const attestationLock =
+		state.generation === undefined && lock.kind === "missing"
+			? undefined
+			: lock.kind === "v010" && legacyOwnershipLockMatchesHandoffState(lock, state)
+				? lock.metadata
+				: null;
+	if (attestationLock === null) return { acquired: false, attached: false, blocked: true };
+	const previous = await readJson<LegacyMigrationAttestation>(
+		input.fs,
+		legacyMigrationAttestationPath(input.statePath),
+	);
+	const stateDigest = legacyParentStateDigest(state);
 	const attested = Boolean(
 		previous &&
-			Number.isSafeInteger(previous.pid) &&
-			isProcessIncarnation(previous.incarnation) &&
-			Number.isSafeInteger(previous.heartbeatAt) &&
-			Number.isSafeInteger(previous.observedAt) &&
+			previous.stateDigest === stateDigest &&
+			JSON.stringify(previous.lock) === JSON.stringify(attestationLock) &&
 			previous.pid === state.pid &&
 			previous.incarnation === incarnation &&
+			previous.tokenFingerprint === input.tokenFingerprint &&
+			previous.chatId === input.chatId &&
 			state.heartbeatAt > previous.heartbeatAt &&
 			input.now - previous.observedAt <= HEARTBEAT_TTL_MS,
 	);
-	await writeJsonAtomic(input.fs, attestationPath, {
+	await writeJsonAtomic(input.fs, legacyMigrationAttestationPath(input.statePath), {
+		stateDigest,
+		...(attested ? { confirmed: true as const } : {}),
+		...(attestationLock === undefined ? {} : { lock: attestationLock }),
 		pid: state.pid,
 		incarnation,
 		heartbeatAt: state.heartbeatAt,
 		observedAt: input.now,
+		tokenFingerprint: input.tokenFingerprint,
+		chatId: input.chatId,
 	} satisfies LegacyMigrationAttestation);
-	return attested
-		? { acquired: false, attached: false, reloadRequired: true }
-		: { acquired: false, attached: false, provisional: true };
+	if (!attested) return { acquired: false, attached: false, provisional: true };
+	return { acquired: false, attached: false, reloadRequired: true, legacyReloadRequired: true };
+}
+
+export interface AttestedLegacyDaemonOwner {
+	state: LegacyParentDaemonState;
+	incarnation: string;
+}
+
+/** Revalidate the exact two-observation legacy proof immediately before signaling. */
+export async function readAttestedLegacyDaemonOwner(input: {
+	settings: Settings;
+	fs?: TelegramDaemonFs;
+	now?: () => number;
+	pidIncarnation?: (pid: number) => string | undefined;
+	tokenFingerprint: string;
+	chatId: string;
+}): Promise<AttestedLegacyDaemonOwner | undefined> {
+	const fsImpl = input.fs ?? nodeFs;
+	const paths = daemonPaths(input.settings.getAgentDir());
+	const state = await readJson<unknown>(fsImpl, paths.state);
+	if (!isGeneration3ReleaseDaemonState(state)) return undefined;
+	let stateBytes: string;
+	try {
+		stateBytes = await fsImpl.readFile(paths.state, "utf8");
+	} catch {
+		return undefined;
+	}
+	if (stateBytes !== historicalStateSerializer(state)) return undefined;
+	const lock = await readOwnershipLock(fsImpl, paths.lock);
+	if (lock.kind !== "v010") return undefined;
+	const attestation = await readJson<LegacyMigrationAttestation>(fsImpl, legacyMigrationAttestationPath(paths.state));
+	const incarnation = (input.pidIncarnation ?? defaultPidIncarnation)(state.pid);
+	const now = (input.now ?? Date.now)();
+	if (
+		attestation?.confirmed !== true ||
+		!isProcessIncarnation(incarnation) ||
+		attestation.stateDigest !== legacyParentStateDigest(state) ||
+		JSON.stringify(attestation.lock) !== JSON.stringify(lock.metadata) ||
+		attestation.pid !== state.pid ||
+		attestation.incarnation !== incarnation ||
+		attestation.tokenFingerprint !== input.tokenFingerprint ||
+		attestation.chatId !== input.chatId ||
+		attestation.heartbeatAt > state.heartbeatAt ||
+		now < attestation.observedAt ||
+		now - attestation.observedAt > HEARTBEAT_TTL_MS
+	)
+		return undefined;
+	return { state, incarnation };
 }
 
 function isRecognizedLegacyGeneration(generation: number | undefined): boolean {
-	return (
-		generation === undefined || (Number.isSafeInteger(generation) && generation > 0 && generation < DAEMON_GENERATION)
+	return generation === undefined || generation === 3;
+}
+
+/**
+ * A predecessor is reloadable only when it has the complete modern ownership
+ * proof. Generation is absent from the first fully-provenanced modern records,
+ * so it is an incompatible predecessor too; parent-format records remain
+ * excluded because they lack this ownership proof.
+ */
+function hasFullModernOwnerProvenance(
+	state: DaemonState | undefined,
+	pidIncarnation?: (pid: number) => string | undefined,
+): boolean {
+	return Boolean(
+		hasSafeDaemonStateShape(state) &&
+			state.generation !== 3 &&
+			state.ownershipPhase === "ready" &&
+			typeof state.acquisitionId === "string" &&
+			state.acquisitionId.length > 0 &&
+			ownerProvenanceMatches(state, pidIncarnation),
+	);
+}
+
+function isFullModernPredecessor(
+	state: DaemonState | undefined,
+	pidIncarnation?: (pid: number) => string | undefined,
+): boolean {
+	return Boolean(
+		hasFullModernOwnerProvenance(state, pidIncarnation) &&
+			(state?.generation === undefined ||
+				(Number.isSafeInteger(state?.generation) &&
+					(state?.generation as number) > 0 &&
+					(state?.generation as number) < DAEMON_GENERATION)),
 	);
 }
 
@@ -1086,18 +1593,23 @@ export function isPhysicalMatchingOwner(input: {
 	pidAlive: (pid: number) => boolean;
 	pidIncarnation?: (pid: number) => string | undefined;
 }): boolean {
-	const { state } = input;
-	return Boolean(
-		state &&
-			hasSafeDaemonStateShape(state) &&
-			state.stoppedAt === undefined &&
-			ownerIdentityMatches(state, input.tokenFingerprint, input.chatId) &&
-			input.pidAlive(state.pid) &&
-			ownerProvenanceMatches(state, input.pidIncarnation),
-	);
+	const persistedState: unknown = input.state;
+	const legacyParentState = isLegacyParentDaemonState(persistedState) ? persistedState : undefined;
+	const modernState = hasSafeDaemonStateShape(persistedState) ? persistedState : undefined;
+	const state = modernState ?? legacyParentState;
+	if (
+		!state ||
+		state.stoppedAt !== undefined ||
+		!ownerIdentityMatches(state, input.tokenFingerprint, input.chatId) ||
+		!input.pidAlive(state.pid)
+	)
+		return false;
+	return legacyParentState
+		? isProcessIncarnation((input.pidIncarnation ?? defaultPidIncarnation)(legacyParentState.pid))
+		: modernState !== undefined && ownerProvenanceMatches(modernState, input.pidIncarnation);
 }
 
-/** True only for a signalable legacy owner or this generation's ready bound child. */
+/** True only for a fully-provenanced modern owner outside the generation-3 parent schema. */
 export function isSignalableMatchingOwner(input: {
 	state: DaemonState | undefined;
 	tokenFingerprint: string;
@@ -1106,14 +1618,7 @@ export function isSignalableMatchingOwner(input: {
 	pidIncarnation?: (pid: number) => string | undefined;
 }): boolean {
 	const { state } = input;
-	return Boolean(
-		isPhysicalMatchingOwner(input) &&
-			(isRecognizedLegacyGeneration(state?.generation) ||
-				(state?.generation === DAEMON_GENERATION &&
-					state.ownershipPhase === "ready" &&
-					typeof state.acquisitionId === "string" &&
-					state.acquisitionId.length > 0)),
-	);
+	return Boolean(isPhysicalMatchingOwner(input) && hasFullModernOwnerProvenance(state, input.pidIncarnation));
 }
 
 export function isFreshLiveOwner(input: {
@@ -1180,6 +1685,7 @@ export async function acquireDaemonOwnership(input: {
 	provisional?: boolean;
 	reason?: "identity_mismatch";
 	reloadRequired?: boolean;
+	legacyReloadRequired?: boolean;
 }> {
 	const fsImpl = input.fs ?? nodeFs;
 	const now = input.now ?? Date.now;
@@ -1216,6 +1722,7 @@ export async function acquireDaemonOwnership(input: {
 		}
 		if (!state || state.stoppedAt !== undefined || !ownerIdentityMatches(state, input.tokenFingerprint, input.chatId))
 			return undefined;
+		if (state.generation === 3) return { acquired: false, attached: false, blocked: true };
 		// Unavailable provenance is ambiguous and must remain fail-closed. A
 		// different authoritative incarnation proves PID reuse, so allow only the
 		// transition-locked path below to reclaim the stale owner artifacts.
@@ -1238,19 +1745,18 @@ export async function acquireDaemonOwnership(input: {
 		)
 			return { acquired: false, attached: true };
 		// A physical owner that cannot prove current compatibility is never safe to
-		// attach. Legacy, stale, and malformed generations require a handoff;
-		// otherwise retain the explicit provisional classification.
+		// attach. A reload handoff additionally requires a fresh heartbeat: a stale
+		// record must remain blocked rather than authorizing a signal to its PID.
 		if (
-			state.version !== DAEMON_VERSION ||
-			!isFreshLiveOwner({
+			isFreshLiveOwner({
 				state,
 				now: now(),
 				tokenFingerprint: input.tokenFingerprint,
 				chatId: input.chatId,
 				pidAlive,
 				pidIncarnation,
-			}) ||
-			isRecognizedLegacyGeneration(state.generation)
+			}) &&
+			(state.version !== DAEMON_VERSION || isFullModernPredecessor(state, pidIncarnation))
 		)
 			return { acquired: false, attached: false, reloadRequired: true };
 		return { acquired: false, attached: false, provisional: true };
@@ -1278,12 +1784,48 @@ export async function acquireDaemonOwnership(input: {
 			? { acquired: false, attached: false, blocked: true, reason: "identity_mismatch" }
 			: { acquired: false, attached: false, blocked: true };
 	}
+	if (
+		await isLiveNoncanonicalParentState({
+			fs: fsImpl,
+			statePath: paths.state,
+			state: existing,
+			pidAlive,
+			pidIncarnation,
+			tokenFingerprint: input.tokenFingerprint,
+			chatId: input.chatId,
+		})
+	)
+		return { acquired: false, attached: false, blocked: true };
 
 	const transition = await acquireTransitionLock({ fs: fsImpl, path: paths.steal, pidAlive, pidIncarnation });
 	if (!transition) return { acquired: false, attached: false, provisional: true };
 	try {
 		const rechecked = await readJson<DaemonState>(fsImpl, paths.state);
 		const recheckedLock = await readOwnershipLock(fsImpl, paths.lock);
+		const recheckedForeignOwner = classifyForeignLiveOwner({
+			state: rechecked,
+			tokenFingerprint: input.tokenFingerprint,
+			chatId: input.chatId,
+			pidAlive,
+			pidIncarnation,
+		});
+		if (recheckedForeignOwner) {
+			return recheckedForeignOwner === "identity_mismatch"
+				? { acquired: false, attached: false, blocked: true, reason: "identity_mismatch" }
+				: { acquired: false, attached: false, blocked: true };
+		}
+		if (
+			await isLiveNoncanonicalParentState({
+				fs: fsImpl,
+				statePath: paths.state,
+				state: rechecked,
+				pidAlive,
+				pidIncarnation,
+				tokenFingerprint: input.tokenFingerprint,
+				chatId: input.chatId,
+			})
+		)
+			return { acquired: false, attached: false, blocked: true };
 		const recheckedDecision = isLegacyParentDaemonState(rechecked) ? undefined : attachDecision(rechecked);
 		if (
 			recheckedDecision &&
@@ -1297,13 +1839,19 @@ export async function acquireDaemonOwnership(input: {
 		// A newer initializer may have replaced the pathname while that tombstone
 		// remained, and must receive the same liveness/freshness protection as any
 		// other live reservation.
-		const stoppedLockMatches = ownershipLockMatchesStoppedState(recheckedLock, rechecked);
-		const lockDecision = stoppedLockMatches
-			? undefined
-			: liveOwnershipLockDecision({ lock: recheckedLock, pidAlive, pidIncarnation });
+		const stoppedLockMatches = ownershipLockMatchesStoppedState(recheckedLock, rechecked, pidAlive);
+		// A v0.10 parent owns a legacy { pid, startedAt } lock. An exact
+		// state/lock pair is authority only to attest or retry handoff of that
+		// owner; it is never attached or unlinked here.
+		const legacyHandoffLockMatches = legacyOwnershipLockMatchesHandoffState(recheckedLock, rechecked);
+		const lockDecision =
+			stoppedLockMatches || legacyHandoffLockMatches
+				? undefined
+				: liveOwnershipLockDecision({ lock: recheckedLock, pidAlive, pidIncarnation });
 		if (lockDecision) return lockDecision;
 		if (
 			!stoppedLockMatches &&
+			!legacyHandoffLockMatches &&
 			!(await ownershipLockIsReclaimable({
 				fs: fsImpl,
 				path: paths.lock,
@@ -1318,6 +1866,7 @@ export async function acquireDaemonOwnership(input: {
 			const legacyDecision = await legacyParentHandoffDecision({
 				fs: fsImpl,
 				statePath: paths.state,
+				lockPath: paths.lock,
 				state: rechecked,
 				now: now(),
 				pidAlive,
@@ -1329,18 +1878,6 @@ export async function acquireDaemonOwnership(input: {
 		} else if (recheckedDecision) {
 			return recheckedDecision;
 		}
-		const recheckedForeignOwner = classifyForeignLiveOwner({
-			state: rechecked,
-			tokenFingerprint: input.tokenFingerprint,
-			chatId: input.chatId,
-			pidAlive,
-			pidIncarnation,
-		});
-		if (recheckedForeignOwner) {
-			return recheckedForeignOwner === "identity_mismatch"
-				? { acquired: false, attached: false, blocked: true, reason: "identity_mismatch" }
-				: { acquired: false, attached: false, blocked: true };
-		}
 		if (
 			hasSafeDaemonStateShape(rechecked) &&
 			rechecked.stoppedAt === undefined &&
@@ -1354,7 +1891,8 @@ export async function acquireDaemonOwnership(input: {
 		if (currentLock.kind !== "missing") {
 			if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition })))
 				return { acquired: false, attached: false, provisional: true };
-			await fsImpl.unlink(paths.lock);
+			if (!(await unlinkOwnershipLockExactly(fsImpl, paths.lock, currentLock)))
+				return { acquired: false, attached: false, provisional: true };
 		}
 		const ownershipLock: OwnershipLockMetadata = {
 			pid,
@@ -1590,14 +2128,15 @@ export async function retireProvisionalDaemonOwnership(input: {
 		)
 			return false;
 		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))) return false;
+		const lock = await readOwnershipLock(fsImpl, paths.lock);
+		if (!ownershipLockMatchesState(lock, state)) return false;
 		await writeJsonAtomic(fsImpl, paths.state, {
 			...state,
 			ownershipPhase: "retired",
 			stoppedAt: (input.now ?? Date.now)(),
 		});
-		if (await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))
-			await fsImpl.unlink(paths.lock).catch(() => undefined);
-		return true;
+		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))) return false;
+		return await unlinkOwnershipLockExactly(fsImpl, paths.lock, lock);
 	} finally {
 		await releaseDaemonTransitionLock({ fs: fsImpl, path: paths.steal, lock: transition });
 	}
@@ -1754,6 +2293,8 @@ export async function confirmTelegramDaemonSpawn(input: {
 	sleep?: (ms: number) => Promise<void>;
 	waitStepMs?: number;
 	timeoutMs?: number;
+	/** Retain an unproven no-PID child lease during a successor handoff. */
+	preserveOnUnprovenChildExit?: boolean;
 }): Promise<boolean> {
 	if (input.spawned.result !== "owner_spawned") return true;
 	const childPid = input.spawned.acquisition.pid;
@@ -1775,6 +2316,14 @@ export async function confirmTelegramDaemonSpawn(input: {
 		timeoutMs: input.timeoutMs,
 	});
 	if (ready) return true;
+	// An identified live child remains fenced. A no-PID launch retains its lease
+	// only when a successor handoff explicitly requests that protection; ordinary
+	// confirmation keeps the historical cleanup behavior.
+	if (
+		(hasExactChildPid && (input.pidAlive ?? defaultPidAlive)(childPid as number)) ||
+		(!hasExactChildPid && input.preserveOnUnprovenChildExit)
+	)
+		return false;
 	const launcherPid = input.spawned.acquisition.launcherPid ?? input.pid;
 	const retired = await retireProvisionalDaemonOwnership({
 		settings: input.settings,
@@ -1856,9 +2405,11 @@ export async function releaseDaemonOwnership(input: {
 		)
 			return;
 		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))) return;
+		const lock = await readOwnershipLock(fsImpl, paths.lock);
+		if (!ownershipLockMatchesState(lock, state)) return;
 		await writeJsonAtomic(fsImpl, paths.state, { ...state, stoppedAt: (input.now ?? Date.now)() });
 		if (await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))
-			await fsImpl.unlink(paths.lock).catch(() => undefined);
+			await unlinkOwnershipLockExactly(fsImpl, paths.lock, lock);
 	} finally {
 		await releaseDaemonTransitionLock({ fs: fsImpl, path: paths.steal, lock: transition });
 	}
@@ -1881,6 +2432,57 @@ export async function readDaemonRoots(
 	return roots?.roots ?? [];
 }
 
+/** Injectable readers for {@link resolveTelegramSetupPreflight}, defaulting to the real OS/state probes. */
+export interface ResolveTelegramSetupPreflightDeps {
+	readDaemonState?: (settings: Settings) => Promise<DaemonState | undefined>;
+	pidAlive?: (pid: number) => boolean;
+	pidIncarnation?: (pid: number) => string | undefined;
+}
+
+/**
+ * Build the Telegram setup preflight from persisted daemon state. The daemon is
+ * reported live ONLY when its PID is alive AND its current process incarnation
+ * still matches the persisted incarnation. Skipping the incarnation check makes
+ * a stale state file whose PID has been recycled by an unrelated process
+ * masquerade as a live owner, which wrongly blocks discovery pairing. Both the
+ * `notify setup` CLI and the /settings Notifications tab share this resolver so
+ * pairing behaves identically on both surfaces.
+ */
+export async function resolveTelegramSetupPreflight(
+	settings: Settings,
+	deps: ResolveTelegramSetupPreflightDeps = {},
+): Promise<TelegramSetupPreflight> {
+	const storedChatId = getNotificationConfig(settings).chatId;
+	const pidAlive = deps.pidAlive ?? defaultPidAlive;
+	const pidIncarnation = deps.pidIncarnation ?? defaultPidIncarnation;
+	try {
+		const state = await (deps.readDaemonState ?? readDaemonState)(settings);
+		if (!state) return { storedChatId };
+		const validPid = Number.isSafeInteger(state.pid) && state.pid > 0;
+		if (!validPid || !pidAlive(state.pid)) return { storedChatId };
+		const persistedIncarnation = state.incarnation;
+		const currentIncarnation = pidIncarnation(state.pid);
+		if (
+			!isProcessIncarnation(persistedIncarnation) ||
+			!isProcessIncarnation(currentIncarnation) ||
+			persistedIncarnation !== currentIncarnation
+		)
+			return { storedChatId };
+		return {
+			storedChatId,
+			daemon: {
+				live: true,
+				tokenFingerprint: typeof state.tokenFingerprint === "string" ? state.tokenFingerprint : undefined,
+				chatId: typeof state.chatId === "string" ? state.chatId : undefined,
+			},
+		};
+	} catch {
+		// A state read failure is not proof of a live daemon; proceed normally. The
+		// daemon's own 409 handling remains the backstop against poller contention.
+		return { storedChatId };
+	}
+}
+
 function defaultPidAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -1945,7 +2547,13 @@ export interface TelegramSpawnAcquisition {
 
 export type TelegramSpawnOwnerResult =
 	| { result: "owner_spawned"; acquisition: TelegramSpawnAcquisition; runtime: DaemonRuntimeInfo; warnings: string[] }
-	| { result: "attached"; runtime: DaemonRuntimeInfo; warnings: string[]; reloadRequired?: boolean }
+	| {
+			result: "attached";
+			runtime: DaemonRuntimeInfo;
+			warnings: string[];
+			reloadRequired?: boolean;
+			legacyReloadRequired?: boolean;
+	  }
 	| { result: "blocked"; runtime: DaemonRuntimeInfo; warnings: string[]; reloadRequired?: boolean };
 
 /**
@@ -2028,6 +2636,7 @@ export async function spawnTelegramDaemonOwner(
 			runtime: buildTelegramDaemonSpawnArgs({ execPath, ownerId: "", agentDir }).runtime,
 			warnings: [],
 			reloadRequired: ownership.reloadRequired,
+			legacyReloadRequired: ownership.legacyReloadRequired,
 		};
 	}
 	const launcherPid = deps.pid ?? process.pid;
@@ -2180,7 +2789,7 @@ export async function reclaimDeadDaemonOwner(input: {
 		if (!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition })))
 			return { recovered: false, reason: "transition-contended" };
 		for (const endpoint of endpoints)
-			if (!(await fsImpl.exactUnlink(endpoint.file, endpoint.identity)).ok)
+			if (!(await exactUnlinkAcceptedWithRetainedEvidence(fsImpl, endpoint.file, endpoint.identity)))
 				return { recovered: false, reason: "endpoint-changed" };
 		if (currentLock.kind === "missing") return { recovered: true, reason: "cleared" };
 		const exactLock = await fsImpl.readEndpointFile!(paths.lock).catch(() => undefined);
@@ -2191,7 +2800,7 @@ export async function reclaimDeadDaemonOwner(input: {
 			!(await transitionLockIsHeldByCaller({ fs: fsImpl, path: paths.steal, lock: transition }))
 		)
 			return { recovered: false, reason: "lock-changed" };
-		return (await fsImpl.exactUnlink(paths.lock, exactLock.identity)).ok
+		return (await exactUnlinkAcceptedWithRetainedEvidence(fsImpl, paths.lock, exactLock.identity))
 			? { recovered: true, reason: "cleared" }
 			: { recovered: false, reason: "lock-changed" };
 	} finally {
@@ -2211,6 +2820,13 @@ export async function ensureTelegramDaemonRunningDetailed(
 	if (!isTelegramConfigured(cfg)) return "disabled";
 	const root = notificationRootForCwd(input.cwd);
 	const fp = tokenFingerprint(cfg.botToken);
+	// A live v0.10 parent has no stable process authority on Windows. Never turn an
+	// unproven cooperative handoff into destructive cleanup or a replacement spawn.
+	if ((deps.platform ?? process.platform) === "win32") {
+		const parentState: unknown = await readDaemonState(input.settings, deps.fs);
+		if (isParentDaemonState(parentState) && (deps.pidAlive ?? defaultPidAlive)(parentState.pid))
+			return "blocked_identity";
+	}
 	// Windows can retain dead launcher metadata without an ownership lock; reclaim
 	// its dead discovery records before the replacement can publish a new owner.
 	if ((deps.platform ?? process.platform) === "win32" && !deps.fs) {
@@ -2259,7 +2875,11 @@ export async function ensureTelegramDaemonRunningDetailed(
 			waitStepMs: deps.waitStepMs,
 			timeoutMs: deps.readinessTimeoutMs,
 		});
-		if (ready) {
+		// A legacy parent cannot satisfy the current ready-state shape, but the
+		// bounded wait gives its heartbeat a second observation window. Retry the
+		// acquisition once so legacyParentHandoffDecision can consume that
+		// attestation before startup treats the owner as blocked.
+		if (ready || isLegacyParentDaemonState(provisional)) {
 			spawned = await withTelegramSetupLease(
 				cfg.botToken,
 				async () =>
@@ -2300,9 +2920,78 @@ export async function ensureTelegramDaemonRunningDetailed(
 	if (spawned.result === "attached" && spawned.reloadRequired) {
 		const previous = await readNotificationRootRegistration({ ...input, fs: deps.fs });
 		await registerNotificationRoot({ ...input, fs: deps.fs });
-		const controller = new TelegramDaemonController(input.settings, telegramControllerDeps(deps));
-		const upgrade = await controller.reloadForGenerationUpgrade();
-		if (upgrade.outcome !== "ready") {
+		const fsImpl = deps.fs ?? nodeFs;
+		const now = deps.now ?? Date.now;
+		const pidAlive = deps.pidAlive ?? defaultPidAlive;
+		const pidIncarnation = deps.pidIncarnation ?? defaultPidIncarnation;
+		const reloadAttemptPath = path.join(
+			daemonPaths(input.settings.getAgentDir()).dir,
+			"telegram-daemon.reload-attempt.json",
+		);
+		await ensureDir(fsImpl, daemonPaths(input.settings.getAgentDir()).dir);
+		const reloadWaitStepMs = Math.max(deps.waitStepMs ?? 100, 1);
+		const reloadFreshnessWaitMs = Math.max(deps.readinessTimeoutMs ?? RELOAD_FRESHNESS_WAIT_MS, reloadWaitStepMs);
+		const reloadReadinessTimeoutMs = deps.readinessTimeoutMs ?? RELOAD_FRESHNESS_WAIT_MS;
+		const reloadResult = await withFileLock(
+			reloadAttemptPath,
+			async () => {
+				const currentState = await readDaemonState(input.settings, fsImpl);
+				const previousAttempt = await readJson<{
+					lastReloadAt?: number;
+					ownerId?: string;
+					targetGeneration?: number;
+				}>(fsImpl, reloadAttemptPath).catch(() => undefined);
+				const reloadNow = now();
+				const cooldownApplies =
+					previousAttempt?.targetGeneration === DAEMON_GENERATION &&
+					typeof previousAttempt.lastReloadAt === "number" &&
+					Number.isFinite(previousAttempt.lastReloadAt) &&
+					reloadNow - previousAttempt.lastReloadAt < AUTOMATIC_RELOAD_COOLDOWN_MS;
+				if (cooldownApplies) {
+					// A sibling ensure may have just finished its reload. Its replacement
+					// daemon heartbeats only after startup, so wait briefly for the fresh
+					// ready owner instead of issuing a duplicate reload in the gap.
+					const sleep = deps.sleep ?? Bun.sleep;
+					const waitStepMs = reloadWaitStepMs;
+					const waitBudgetMs = reloadFreshnessWaitMs;
+					const deadline = reloadNow + waitBudgetMs;
+					// Iteration-capped so a frozen `now` cannot spin forever.
+					const maxWaits = Math.ceil(waitBudgetMs / waitStepMs);
+					for (let waits = 0; waits <= maxWaits; waits++) {
+						const state = await readDaemonState(input.settings, fsImpl);
+						const t = now();
+						if (
+							isFreshLiveOwner({
+								state,
+								now: t,
+								tokenFingerprint: fp,
+								chatId: cfg.chatId,
+								pidAlive,
+								pidIncarnation,
+							})
+						)
+							return "attached" as const;
+						if (t >= deadline) break;
+						await sleep(waitStepMs);
+					}
+				}
+				await writeJsonAtomic(fsImpl, reloadAttemptPath, {
+					lastReloadAt: reloadNow,
+					ownerId: currentState?.ownerId ?? "",
+					targetGeneration: DAEMON_GENERATION,
+				});
+				const controller = new TelegramDaemonController(input.settings, telegramControllerDeps(deps));
+				const upgrade = await controller.reloadForGenerationUpgrade({}, spawned.legacyReloadRequired === true);
+				return upgrade.outcome === "ready" ? ("reloaded" as const) : upgrade;
+			},
+			reloadReservationLockOptions({
+				freshnessWaitMs: reloadFreshnessWaitMs,
+				readinessTimeoutMs: reloadReadinessTimeoutMs,
+				retryDelayMs: reloadWaitStepMs,
+			}),
+		);
+		if (reloadResult === "attached") return "attached";
+		if (reloadResult !== "reloaded") {
 			await restoreNotificationRootRegistration({
 				settings: input.settings,
 				sessionId: input.sessionId,
@@ -2310,7 +2999,7 @@ export async function ensureTelegramDaemonRunningDetailed(
 				previous,
 				fs: deps.fs,
 			});
-			throw new Error(`Unable to replace stale Telegram daemon: ${upgrade.operation.message}`);
+			throw new Error(`Unable to replace stale Telegram daemon: ${reloadResult.operation.message}`);
 		}
 		return "reloaded";
 	}
@@ -2363,12 +3052,28 @@ export async function ensureTelegramDaemonRunning(
 }
 
 function telegramControllerDeps(deps: TelegramDaemonDeps): TelegramDaemonControlDeps {
+	// The legacy signal seam has no authority metadata of its own. Pair it with
+	// the captured process incarnation so the controller retains its identity
+	// fence; Windows continues through its hard-authority refusal path.
+	const cooperativeSignalReference =
+		deps.sendSignal && (deps.platform ?? process.platform) !== "win32"
+			? (pid: number): DaemonProcessReference | undefined => {
+					const incarnation = deps.pidIncarnation?.(pid);
+					if (!isProcessIncarnation(incarnation)) return undefined;
+					return {
+						incarnation,
+						termination: "cooperative",
+						signalRoot: signal => deps.sendSignal!(pid, signal),
+					};
+				}
+			: undefined;
 	return {
 		fs: deps.fs,
 		now: deps.now,
 		pidAlive: deps.pidAlive,
-		processReference: deps.processReference,
+		processReference: cooperativeSignalReference ?? deps.processReference,
 		pidIncarnation: deps.pidIncarnation,
+		platform: deps.platform,
 		spawn: deps.spawn,
 		execPath: deps.execPath,
 		ownerPid: deps.pid,
@@ -2963,6 +3668,12 @@ export class TelegramNotificationDaemon {
 	private readonly botApi: BotApi;
 	private readonly effects = new TelegramEffectSupervisor();
 	private readonly topics = new TopicRegistry();
+	/**
+	 * Telegram may accept createForumTopic while returning an unusable success
+	 * payload. Remember that ambiguity per endpoint so later frames cannot repeat
+	 * the external side effect. Explicit API failures remain retryable.
+	 */
+	readonly #malformedTopicCreateEndpoints = new Map<string, string>();
 	/** Serializes registry snapshots so an older atomic write cannot overwrite newer rename state. */
 	/** Legacy sockets have no durable token, so explicit teardown is their revocation fence. */
 	private readonly droppedSessions = new WeakSet<SessionSocket>();
@@ -3830,13 +4541,20 @@ export class TelegramNotificationDaemon {
 		const paths = daemonPaths(this.opts.settings.getAgentDir());
 		const rootState = await readJson<{ roots?: string[] }>(this.fsImpl, paths.roots);
 		const endpointSessionIds = new Set<string>();
+		// Permanent absences prune; only transient I/O keeps orphan reconciliation
+		// gated (so one deleted worktree cannot disable cleanup forever) (#2956).
 		let allRootsReadable = true;
+		const permanentlyMissingRoots: string[] = [];
 		for (const root of rootState?.roots ?? []) {
 			const dir = path.join(root, "sdk");
 			let files: string[];
 			try {
 				files = await this.fsImpl.readdir(dir);
-			} catch {
+			} catch (error) {
+				if (isPermanentMissingPathError(error)) {
+					permanentlyMissingRoots.push(root);
+					continue;
+				}
 				allRootsReadable = false;
 				continue;
 			}
@@ -3885,6 +4603,27 @@ export class TelegramNotificationDaemon {
 				} catch {}
 			}
 		}
+		if (permanentlyMissingRoots.length > 0) {
+			try {
+				await pruneMissingNotificationRoots({
+					settings: this.opts.settings,
+					fs: this.fsImpl,
+					candidates: permanentlyMissingRoots,
+				});
+			} catch (error) {
+				logger.warn(`notifications: dead-root prune failed: ${sanitizeDiagnostic(String(error))}`);
+			}
+		}
+		// Best-effort periodic reap of retained exact-unlink quarantines (#2956).
+		try {
+			await reapStaleNotificationArtifacts({
+				settings: this.opts.settings,
+				fs: this.fsImpl,
+				now: this.opts.now,
+			});
+		} catch (error) {
+			logger.warn(`notifications: leak-artifact reap failed: ${sanitizeDiagnostic(String(error))}`);
+		}
 		if (allRootsReadable) {
 			for (const sessionId of this.topics.sessionIds()) {
 				const owner = this.logicalSessionOwners.get(sessionId);
@@ -3978,18 +4717,15 @@ export class TelegramNotificationDaemon {
 					);
 				} catch {}
 			}
-			// Preserve the transport-session contract: ordinary endpoints own a topic
-			// as soon as they connect. A later authenticated logical rekey is the only
-			// path that may recover a different logical session's durable topic.
 			void (async () => {
 				if (this.#logicalSessionId(session) !== sessionId) return;
-				const topicId = await this.ensureTopic(sessionId, this.topicNameFor(sessionId, {}), session);
+				const topic = this.topics.get(sessionId);
+				if (!topic || topic.authorityState === "delete_pending" || topic.bindingMalformed) return;
 				const topicLease = this.topicAuthorityLeaseFromRegistry(sessionId);
-				if (topicId && topicLease?.topicId === topicId)
-					await this.flushPendingThreadedFrames(sessionId, topicLease);
+				if (topicLease?.topicId === topic.topicId) await this.flushPendingThreadedFrames(sessionId, topicLease);
 			})().catch(err =>
 				logger.warn(
-					`notifications: Telegram initial topic creation failed: ${sanitizeDiagnostic(String(err), this.opts.botToken)}`,
+					`notifications: Telegram topic reattach flush failed: ${sanitizeDiagnostic(String(err), this.opts.botToken)}`,
 				),
 			);
 		});
@@ -4870,19 +5606,16 @@ export class TelegramNotificationDaemon {
 			this.legacyTopicOwners.set(previousSessionId, session);
 			this.preservedInitiatorTopics.add(previousSessionId);
 		}
-		if (candidateSessionId === session.sessionId && !this.topics.get(candidateSessionId))
+		if (candidateSessionId === session.sessionId)
 			void (async () => {
-				const topicId = await this.ensureTopic(
-					candidateSessionId,
-					this.topicNameFor(candidateSessionId, {}),
-					session,
-				);
+				const topic = this.topics.get(candidateSessionId);
+				if (!topic || topic.authorityState === "delete_pending" || topic.bindingMalformed) return;
 				const topicLease = this.topicAuthorityLeaseFromRegistry(candidateSessionId);
-				if (topicId && topicLease?.topicId === topicId)
+				if (topicLease?.topicId === topic.topicId)
 					await this.flushPendingThreadedFrames(candidateSessionId, topicLease);
 			})().catch(err =>
 				logger.warn(
-					`notifications: Telegram recovered topic creation failed: ${sanitizeDiagnostic(String(err), this.opts.botToken)}`,
+					`notifications: Telegram recovered topic reattach flush failed: ${sanitizeDiagnostic(String(err), this.opts.botToken)}`,
 				),
 			);
 		return true;
@@ -5117,6 +5850,9 @@ export class TelegramNotificationDaemon {
 		if (session && sessionId === session.sessionId && this.#logicalSessionId(session) !== sessionId) return undefined;
 		const capturedCreationLease = creationLease ?? (session ? this.#socketLease(session, sessionId) : undefined);
 		if (session?.logicalSessionIdTrusted && !capturedCreationLease) return undefined;
+		const creationEndpointKey = session?.endpointDigest ?? session?.endpointKey ?? "unbound";
+		if (this.#malformedTopicCreateEndpoints.get(sessionId) === creationEndpointKey)
+			throw new Error("createForumTopic: invalid message_thread_id");
 		const existing = this.topics.get(sessionId);
 		if (existing?.authorityState === "delete_pending" || existing?.bindingMalformed) return undefined;
 		if (existing) return existing.topicId;
@@ -5140,10 +5876,17 @@ export class TelegramNotificationDaemon {
 						throw new Error("topic authority was revoked during creation");
 					const res = await this.botApi.call("createForumTopic", { chat_id: this.opts.chatId, name });
 					if (isThreadedModeCapabilityRefusal(res)) throw new ThreadedModeCapabilityRefusal();
-					const tid = (res as { result?: { message_thread_id?: unknown } }).result?.message_thread_id;
-					if (typeof tid !== "number" || !Number.isSafeInteger(tid) || tid <= 0)
+					const response = res as {
+						ok?: unknown;
+						result?: { message_thread_id?: unknown };
+					};
+					const tid = response.result?.message_thread_id;
+					if (typeof tid !== "number" || !Number.isSafeInteger(tid) || tid <= 0) {
+						if (response.ok === true) this.#malformedTopicCreateEndpoints.set(sessionId, creationEndpointKey);
 						throw new Error("createForumTopic: invalid message_thread_id");
+					}
 					acceptedTopicId = String(tid);
+					this.#malformedTopicCreateEndpoints.delete(sessionId);
 					if (capturedCreationLease && !(await this.#awaitCreationLeaseAuthority(capturedCreationLease))) {
 						if (
 							!this.topics.fenceAcceptedCreateForLease(
@@ -6476,21 +7219,6 @@ export class TelegramNotificationDaemon {
 			const latestIdentity = identityIndex < 0 ? undefined : replayed[identityIndex];
 			const replayIdentitySessionId = latestIdentity?.sessionId as string | undefined;
 			const endpointBinding = this.#endpointBinding(session);
-			// An open transport owns an eager topic-create claim. An identity-less replay
-			// that races that claim must await its own public creation before classifying
-			// endpoint authority; otherwise the registry correctly sees an in-flight
-			// claim as ambiguous and rejects a valid bootstrap.
-			if (!this.topics.get(session.sessionId) && this.#ownsLiveOpenEndpoint(session, endpointBinding)) {
-				try {
-					await this.ensureTopic(session.sessionId, this.topicNameFor(session.sessionId, {}), session);
-				} catch (error) {
-					logger.warn(
-						`notifications: Telegram replay topic creation failed: ${sanitizeDiagnostic(String(error), this.opts.botToken)}`,
-					);
-					this.dropSession(session, "replay_topic_creation_failed");
-					return;
-				}
-			}
 			// Identity-less replay may resume only the exact transport owner. A
 			// rekeyed A→B transport remains denied unless replay proves B.
 			const endpointAuthority = this.#endpointAuthority(endpointBinding, session);
@@ -6974,6 +7702,7 @@ export class TelegramNotificationDaemon {
 				id: msg.id,
 				question: msg.question,
 				options: msg.options,
+				recommendedIndex: msg.recommendedIndex,
 				controls,
 				summary: msg.summary,
 			});
@@ -7025,6 +7754,7 @@ export class TelegramNotificationDaemon {
 							kind,
 							question: msg.question,
 							options: msg.options,
+							recommendedIndex: msg.recommendedIndex,
 							summary: msg.summary,
 						}),
 						replyMarkup: kind === "ask" && inline_keyboard.length ? { inline_keyboard } : undefined,
@@ -7818,6 +8548,17 @@ export class TelegramNotificationDaemon {
 			ownershipProved = true;
 			this.running = !this.stopRequested;
 			if (!this.running) return;
+			// Self-heal durable notification state before any scan/poll work so
+			// `daemon reload` recovers dead roots + leak artifacts (#2956).
+			try {
+				await healTelegramDaemonNotificationState({
+					settings: this.opts.settings,
+					fs: this.fsImpl,
+					now: this.opts.now,
+				});
+			} catch (error) {
+				logger.warn(`notifications: startup self-heal failed: ${sanitizeDiagnostic(String(error))}`);
+			}
 			// Owner-only: start lifecycle control immediately after ownership proof,
 			// before timers or pre-poll startup work can invalidate this run.
 			// Best-effort; notification delivery remains available on failure.