@sayknow-cli/coding-agent 0.4.6 → 0.5.0

package/src/sdk/bus/kind-aware-reconciliation.ts

@@ -0,0 +1,242 @@
+/**
+ * Kind-aware invocation reconciliation (prompt | skill) with optional durable store.
+ * Preserves Q26 admit/first-terminal/capacity/TTL semantics; indexes and caps are per-kind.
+ */
+import {
+	PROMPT_RECONCILIATION_ACTIVE_CAPACITY,
+	PROMPT_RECONCILIATION_TERMINAL_CAPACITY,
+	PROMPT_RECONCILIATION_TERMINAL_TTL_MS,
+	type PromptCorrelation,
+	type PromptReconciliationStatus,
+	sanitizePromptFailure,
+	type TurnPromptReconciliation,
+} from "./prompt-reconciliation";
+import type { DurableReconciliationRecord, ReconciliationKind, ReconciliationStore } from "./reconciliation-store";
+
+export type { ReconciliationKind };
+
+export interface KindCorrelation extends PromptCorrelation {
+	kind: ReconciliationKind;
+}
+
+export interface KindAwareReconciliation {
+	admit(kind: ReconciliationKind, clientRef?: string): void;
+	releaseAdmission(kind: ReconciliationKind, clientRef?: string): void;
+	noteAccepted(
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation,
+		clientRef?: string,
+		extra?: { skillName?: string },
+	): Promise<void>;
+	noteTransition(
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	): Promise<void>;
+	lookup(
+		kind: ReconciliationKind,
+		selector: { commandId?: string; turnId?: string; clientRef?: string },
+	): TurnPromptReconciliation;
+	cleanup(): void;
+	activeCount(kind: ReconciliationKind): number;
+	/** Hydrate from durable store (call once at session host start). */
+	hydrateFromStore(): Promise<void>;
+}
+
+export function createKindAwareReconciliation(
+	options: { now?: () => number; store?: ReconciliationStore | null } = {},
+): KindAwareReconciliation {
+	const now = options.now ?? Date.now;
+	const store = options.store ?? null;
+	const records = new Map<string, DurableReconciliationRecord>();
+	const clientRefIndex = new Map<string, string>(); // `${kind}\0${clientRef}` -> key
+	const reservedClientRefs = new Map<ReconciliationKind, Set<string>>();
+	const reservations: Array<{ kind: ReconciliationKind; clientRef?: string }> = [];
+
+	const keyOf = (kind: ReconciliationKind, correlation: PromptCorrelation) =>
+		`${kind}:${correlation.commandId}:${correlation.turnId}`;
+	const refKey = (kind: ReconciliationKind, clientRef: string) => `${kind}\0${clientRef}`;
+
+	const reservedFor = (kind: ReconciliationKind) => {
+		let set = reservedClientRefs.get(kind);
+		if (!set) {
+			set = new Set();
+			reservedClientRefs.set(kind, set);
+		}
+		return set;
+	};
+
+	const remove = (key: string) => {
+		const record = records.get(key);
+		if (!record) return;
+		records.delete(key);
+		if (record.clientRef !== undefined) {
+			const rk = refKey(record.kind, record.clientRef);
+			if (clientRefIndex.get(rk) === key) clientRefIndex.delete(rk);
+		}
+	};
+
+	const cleanup = () => {
+		const at = now();
+		for (const [key, record] of records)
+			if (record.terminalAt !== undefined && record.terminalAt + PROMPT_RECONCILIATION_TERMINAL_TTL_MS <= at)
+				remove(key);
+		for (const kind of ["prompt", "skill"] as const) {
+			const terminalEntries = [...records.entries()].filter(
+				([, record]) => record.kind === kind && record.terminalAt !== undefined,
+			);
+			if (terminalEntries.length <= PROMPT_RECONCILIATION_TERMINAL_CAPACITY) continue;
+			terminalEntries.sort((a, b) => (a[1].terminalAt as number) - (b[1].terminalAt as number));
+			for (const [key] of terminalEntries.slice(0, terminalEntries.length - PROMPT_RECONCILIATION_TERMINAL_CAPACITY))
+				remove(key);
+		}
+	};
+
+	const activeCount = (kind: ReconciliationKind) => {
+		let count = 0;
+		for (const record of records.values()) if (record.kind === kind && record.terminalAt === undefined) count++;
+		return count;
+	};
+
+	const reservationCount = (kind: ReconciliationKind) => reservations.filter(r => r.kind === kind).length;
+
+	const consumeReservation = (kind: ReconciliationKind, clientRef?: string) => {
+		const index = reservations.findIndex(r => r.kind === kind && r.clientRef === clientRef);
+		if (index === -1) return;
+		reservations.splice(index, 1);
+		if (clientRef !== undefined && !reservations.some(r => r.kind === kind && r.clientRef === clientRef))
+			reservedFor(kind).delete(clientRef);
+	};
+
+	const persist = async () => {
+		if (!store) return;
+		await store.transact(() => [...records.values()].map(r => ({ ...r })));
+	};
+
+	const admit = (kind: ReconciliationKind, clientRef?: string) => {
+		cleanup();
+		const reserved = reservedFor(kind);
+		if (clientRef !== undefined && (clientRefIndex.has(refKey(kind, clientRef)) || reserved.has(clientRef)))
+			throw Object.assign(
+				new Error("A submission with this clientRef is already retained; never reuse a clientRef for retry."),
+				{ code: "client_ref_conflict" },
+			);
+		if (activeCount(kind) + reservationCount(kind) >= PROMPT_RECONCILIATION_ACTIVE_CAPACITY)
+			throw Object.assign(new Error("Too many active submissions; reconcile or await terminal state."), {
+				code: "reconciliation_capacity",
+			});
+		reservations.push({ kind, clientRef });
+		if (clientRef !== undefined) reserved.add(clientRef);
+	};
+
+	const releaseAdmission = (kind: ReconciliationKind, clientRef?: string) => {
+		consumeReservation(kind, clientRef);
+	};
+
+	const noteAccepted = async (
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation,
+		clientRef?: string,
+		extra?: { skillName?: string },
+	) => {
+		cleanup();
+		consumeReservation(kind, clientRef);
+		const at = now();
+		const key = keyOf(kind, correlation);
+		const record: DurableReconciliationRecord = {
+			kind,
+			commandId: correlation.commandId,
+			turnId: correlation.turnId,
+			...(clientRef !== undefined ? { clientRef } : {}),
+			status: "accepted",
+			acceptedAt: at,
+			...(extra?.skillName ? { skillName: extra.skillName } : {}),
+		};
+		records.set(key, record);
+		if (clientRef !== undefined) clientRefIndex.set(refKey(kind, clientRef), key);
+		await persist();
+	};
+
+	const noteTransition = async (
+		kind: ReconciliationKind,
+		correlation: PromptCorrelation | undefined,
+		frame: { type: "agent_start" | "agent_end" } | { type: "agent_failed"; error: unknown },
+	) => {
+		if (!correlation) return;
+		const record = records.get(keyOf(kind, correlation));
+		if (!record || record.terminalAt !== undefined) return;
+		if (frame.type === "agent_start") {
+			if (record.status === "accepted") {
+				record.status = "in_flight";
+				record.startedAt = now();
+				await persist();
+			}
+			return;
+		}
+		record.terminalAt = now();
+		if (frame.type === "agent_failed") {
+			record.status = "failed";
+			record.error = sanitizePromptFailure(frame.error);
+		} else {
+			record.status = "terminal_ok";
+		}
+		cleanup();
+		await persist();
+	};
+
+	const lookup = (
+		kind: ReconciliationKind,
+		selector: { commandId?: string; turnId?: string; clientRef?: string },
+	): TurnPromptReconciliation => {
+		cleanup();
+		const key =
+			selector.clientRef !== undefined
+				? clientRefIndex.get(refKey(kind, selector.clientRef))
+				: selector.commandId !== undefined && selector.turnId !== undefined
+					? keyOf(kind, { commandId: selector.commandId, turnId: selector.turnId })
+					: undefined;
+		const record = key === undefined ? undefined : records.get(key);
+		if (!record) return { status: "unknown" };
+		const identity = {
+			commandId: record.commandId,
+			turnId: record.turnId,
+			...(record.clientRef !== undefined ? { clientRef: record.clientRef } : {}),
+			acceptedAt: record.acceptedAt,
+		};
+		if (record.status === "accepted") return { status: "accepted", ...identity };
+		if (record.status === "in_flight")
+			return { status: "in_flight", ...identity, startedAt: record.startedAt as number };
+		const terminal = {
+			...identity,
+			...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
+			terminalAt: record.terminalAt as number,
+		};
+		if (record.status === "terminal_ok") return { status: "terminal_ok", ...terminal };
+		return { status: "failed", ...terminal, error: record.error ?? sanitizePromptFailure(undefined) };
+	};
+
+	const hydrateFromStore = async () => {
+		if (!store) return;
+		const loaded = await store.load();
+		records.clear();
+		clientRefIndex.clear();
+		for (const record of loaded) {
+			const key = keyOf(record.kind, record);
+			records.set(key, record);
+			if (record.clientRef !== undefined) clientRefIndex.set(refKey(record.kind, record.clientRef), key);
+		}
+	};
+
+	return {
+		admit,
+		releaseAdmission,
+		noteAccepted,
+		noteTransition,
+		lookup,
+		cleanup,
+		activeCount,
+		hydrateFromStore,
+	};
+}
+
+export type { PromptReconciliationStatus };

package/src/sdk/bus/lifecycle-commands.ts

@@ -49,6 +49,49 @@ const USAGE = [
 	"/session_recent [create|resume]",
 ].join("\n");
 
+function tokenizeLifecycleCommand(value: string): string[] | undefined {
+	const tokens: string[] = [];
+	let token = "";
+	let quote: '"' | "'" | undefined;
+	let started = false;
+	for (let index = 0; index < value.length; index++) {
+		const character = value[index]!;
+		if (character === "\\") {
+			const next = value[index + 1];
+			if (next !== undefined && (next === "\\" || next === '"' || next === "'" || /\s/u.test(next))) {
+				token += next;
+				index++;
+			} else token += character;
+			started = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			else token += character;
+			started = true;
+			continue;
+		}
+		if (character === '"' || character === "'") {
+			quote = character;
+			started = true;
+			continue;
+		}
+		if (/\s/u.test(character)) {
+			if (started) {
+				tokens.push(token);
+				token = "";
+				started = false;
+			}
+			continue;
+		}
+		token += character;
+		started = true;
+	}
+	if (quote) return undefined;
+	if (started) tokens.push(token);
+	return tokens;
+}
+
 /** True when the text begins with any /session_* token, regardless of addressability. */
 export function isLifecycleCommandLikeText(text: string | undefined): boolean {
 	if (!text) return false;
@@ -98,8 +141,10 @@ export function parseLifecycleCommand(
 	text: string | undefined,
 	ctx: { chatType?: string; botUsername?: string } = {},
 ): ParsedLifecycleCommand {
+	const tokens = tokenizeLifecycleCommand((text ?? "").trim());
+	if (!tokens) return { kind: "usage", message: USAGE };
+	const [rawCommand, ...args] = tokens;
 	const raw = (text ?? "").trim();
-	const [rawCommand, ...args] = raw.split(/\s+/);
 	const command = normalizeLifecycleCommandToken(rawCommand ?? "", ctx);
 	if (command === undefined) return { kind: "none" };
 
@@ -140,9 +185,8 @@ export function parseLifecycleCommand(
 
 	// /session_create <kind> ... [--mpreset <profile>]
 	const { positional, modelPreset } = extractModelPreset(args);
-	if (modelPreset !== undefined && !isSafeIdentifier(modelPreset)) {
+	if (modelPreset !== undefined && modelPreset.length === 0)
 		return { kind: "reject", reason: "invalid_target", message: `Invalid model preset name.\n\n${USAGE}` };
-	}
 	const kind = positional[0];
 	if (kind === "path") {
 		if (positional.length !== 2) return { kind: "usage", message: USAGE };
@@ -238,11 +282,12 @@ function isSafeBranch(value: string): boolean {
 /**
  * Map a lifecycle response/error to a user-facing Telegram message (G010).
  *
- * Only derives text from sessionId, mode, reason, a safe message, and candidate
- * {sessionId,path} — never a token or prompt. Each error reason gets tailored,
- * actionable copy; an "in progress" pending response is surfaced distinctly.
+ * Only derives text from sessionId, mode, reason, a safe message, the originating
+ * lifecycle verb, and candidate {sessionId,path} — never a token or prompt. Each
+ * error reason gets tailored, actionable copy; an "in progress" pending response
+ * is surfaced distinctly.
  */
-export function formatLifecycleOutcome(r: SessionLifecycleResponse): string {
+export function formatLifecycleOutcome(r: SessionLifecycleResponse, verb?: LifecycleCommandVerb): string {
 	switch (r.type) {
 		case "session_create_response":
 			return `\u{1f680} Launching session ${r.sessionId} in tmux. It will appear once ready \u2014 check /session_recent.`;
@@ -282,9 +327,17 @@ export function formatLifecycleOutcome(r: SessionLifecycleResponse): string {
 		case "unsupported_platform":
 			return "Remote session lifecycle is unavailable on this psmux host because SKC cannot prove immutable session identity. No lifecycle action was performed. Use a local SKC terminal with a supported tmux provider.";
 		case "terminal_uncertain":
-			return /in progress/i.test(r.message)
-				? "\u23f3 That request is already in progress \u2014 hold on."
-				: "\u26a0\ufe0f Outcome uncertain. Check /session_recent before retrying so you don't double-spawn.";
+			if (/in progress/i.test(r.message)) return "\u23f3 That request is already in progress \u2014 hold on.";
+			switch (verb) {
+				case "session_create":
+					return "\u26a0\ufe0f Create outcome uncertain. The session may already be starting \u2014 check /session_recent before retrying to avoid starting it twice.";
+				case "session_close":
+					return "\u26a0\ufe0f Close outcome uncertain. The session may already be closed \u2014 check /session_recent before retrying.";
+				case "session_resume":
+					return "\u26a0\ufe0f Resume outcome uncertain. The session may already be reattached or restarting \u2014 check /session_recent before retrying.";
+				default:
+					return "\u26a0\ufe0f Outcome uncertain. Check /session_recent before retrying.";
+			}
 		default:
 			return `\u26a0\ufe0f ${r.reason}: ${r.message}`;
 	}

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

@@ -1178,16 +1178,25 @@ export function outcomeToResponse(frame: SessionLifecycleRequest, outcome: Lifec
 	if (frame.type === "session_close") {
 		if (typeof e.sessionId !== "string" || typeof e.processGone !== "boolean")
 			throw new Error("invalid close success ledger entry");
+		if (!e.processGone) {
+			return {
+				type: "session_lifecycle_error",
+				requestId: frame.requestId,
+				status: "error",
+				reason: "terminal_uncertain",
+				message: "close did not confirm process termination",
+			};
+		}
 		return {
 			type: "session_close_response",
 			requestId: frame.requestId,
 			status: "ok",
 			sessionId: e.sessionId,
-			processGone: e.processGone,
+			processGone: true,
 			historyPreserved: true,
 			// The killed session's per-session endpoint record is reaped by the
 			// daemon's dead-PID scan (scanRoots), so it is effectively stale.
-			endpointStale: e.processGone,
+			endpointStale: true,
 		};
 	}
 	if (

package/src/sdk/bus/lifecycle-orchestrator.ts

@@ -309,6 +309,21 @@ export async function handleLifecycleRequest(
 
 	// 4. Durable idempotency.
 	const doc = await deps.store.read();
+	const existing = doc.entries[key];
+	if (
+		frame.type === "session_close" &&
+		existing?.verb === "session_close" &&
+		existing.requestHash === hash &&
+		existing.state === "success" &&
+		typeof existing.sessionId === "string" &&
+		existing.processGone === false
+	) {
+		existing.state = "terminal_uncertain";
+		existing.reason = "terminal_uncertain";
+		existing.updatedAt = deps.now();
+		delete existing.processGone;
+		await deps.store.write(doc);
+	}
 	const dup = classifyDuplicate(doc.entries[key], hash);
 	switch (dup.kind) {
 		case "conflict":
@@ -394,12 +409,28 @@ export async function handleLifecycleRequest(
 
 		if (frame.type === "session_close") {
 			const closed = await deps.closeSession(frame.target);
+			if (!closed.processGone) {
+				Object.assign(entry, {
+					state: "terminal_uncertain",
+					updatedAt: deps.now(),
+					reason: "terminal_uncertain",
+					sessionId: frame.target.sessionId,
+					tmuxSession: frame.target.tmuxSession,
+				});
+				await deps.store.write(doc);
+				await deps.audit({ ...baseAudit, event: "terminal_uncertain", reason: "terminal_uncertain" });
+				return {
+					status: "error",
+					reason: "terminal_uncertain",
+					message: "session_close could not confirm process disappearance; manual check",
+				};
+			}
 			Object.assign(entry, {
 				state: "success",
 				updatedAt: deps.now(),
 				sessionId: frame.target.sessionId,
 				tmuxSession: frame.target.tmuxSession,
-				processGone: closed.processGone,
+				processGone: true,
 			});
 			await deps.store.write(doc);
 			await deps.audit({ ...baseAudit, event: "success" });

package/src/sdk/bus/notification-orchestration.ts

@@ -1,5 +1,6 @@
 import type { CasRestoreResult } from "../../config/atomic-yaml-patch";
 import type { RawSettings, SettingsAtomicPatch, SettingsAtomicReceipt } from "../../config/settings";
+import { isProcessIncarnation, processIncarnation } from "../broker/process-incarnation";
 import {
 	getNotificationConfig,
 	hasNonBlankValue,
@@ -53,6 +54,7 @@ export interface ProposedTelegramIdentityPreflightInput {
 	deps?: {
 		fs?: TelegramDaemonFs;
 		pidAlive?: (pid: number) => boolean;
+		pidIncarnation?: (pid: number) => string | undefined;
 	};
 }
 
@@ -109,6 +111,16 @@ export async function proposedTelegramIdentity(
 
 		const pidAlive = input.deps?.pidAlive ?? defaultPidAlive;
 		if (!pidAlive(metadata.pid)) return { status: "absent" };
+		const pidIncarnation = input.deps?.pidIncarnation ?? processIncarnation;
+		const persistedIncarnation = state.incarnation;
+		const currentIncarnation = pidIncarnation(metadata.pid);
+		if (
+			!isProcessIncarnation(persistedIncarnation) ||
+			!isProcessIncarnation(currentIncarnation) ||
+			persistedIncarnation !== currentIncarnation
+		) {
+			return { status: "absent" };
+		}
 
 		if (state.tokenFingerprint === tokenFingerprint(input.botToken) && state.chatId === input.chatId) {
 			return {

package/src/sdk/bus/notification-service.ts

@@ -28,6 +28,7 @@ import {
 	tokenFingerprint,
 } from "./config";
 import { type DaemonPaths, daemonPaths, HEARTBEAT_TTL_MS } from "./daemon-paths";
+import { type OwnerFreshnessSnapshot, readOwnerFreshnessSnapshot, type TelegramDaemonFs } from "./telegram-daemon";
 import { DAEMON_GENERATION } from "./telegram-daemon-contract";
 
 const DEFAULT_API_BASE = "https://api.telegram.org";
@@ -251,19 +252,29 @@ export function formatNotificationStatusReport(report: NotificationStatusReport)
 
 // --- endpoint / daemon file readers -------------------------------------
 
-interface EndpointView {
+export interface NotificationEndpointView {
 	sessionId: string;
 	pid: number | undefined;
 	stale: boolean;
 }
 
-type EndpointFileRead =
-	| { kind: "endpoint"; view: EndpointView; identity: NotificationEndpointFileIdentity }
+export type NotificationEndpointLiveness = "live" | "dead" | "unknown";
+
+/**
+ * Classification used by recovery and startup takeover. A file is an endpoint
+ * only when it has endpoint authority fields; lifecycle/audit records are never
+ * candidates for endpoint cleanup.
+ */
+export type NotificationEndpointClassification =
+	| {
+			kind: "endpoint";
+			view: NotificationEndpointView;
+			liveness: NotificationEndpointLiveness;
+			identity: NotificationEndpointFileIdentity;
+	  }
 	| { kind: "non-endpoint" }
 	| { kind: "unreadable" };
 
-type EndpointLiveness = "live" | "dead" | "unknown";
-
 /**
  * Classify an endpoint using owner-proof semantics. An endpoint is only `dead`
  * with positive proof: an explicit `stale` tombstone, or a recorded pid that is
@@ -271,7 +282,10 @@ type EndpointLiveness = "live" | "dead" | "unknown";
  * must never be treated as dead — removing it could delete a live session's
  * discovery file that simply omitted a pid.
  */
-function endpointLiveness(view: EndpointView, pidAlive: (pid: number) => boolean): EndpointLiveness {
+export function notificationEndpointLiveness(
+	view: NotificationEndpointView,
+	pidAlive: (pid: number) => boolean,
+): NotificationEndpointLiveness {
 	if (view.stale) return "dead";
 	if (view.pid === undefined) return "unknown";
 	return pidAlive(view.pid) ? "live" : "dead";
@@ -314,11 +328,19 @@ function isCanonicalLifecycleArtifactName(name: string): boolean {
 	);
 }
 
-function unreadableEndpointResult(file: string): EndpointFileRead {
+function unreadableEndpointResult(file: string): NotificationEndpointClassification {
 	return isCanonicalLifecycleArtifactName(path.basename(file)) ? { kind: "non-endpoint" } : { kind: "unreadable" };
 }
 
-async function readEndpointView(fs: NotificationServiceFs, file: string): Promise<EndpointFileRead> {
+/**
+ * Read and classify one endpoint candidate. The returned identity belongs to
+ * exactly the bytes inspected and is required for any later deletion.
+ */
+export async function classifyNotificationEndpoint(
+	fs: Pick<NotificationServiceFs, "readEndpointFile">,
+	file: string,
+	pidAlive: (pid: number) => boolean,
+): Promise<NotificationEndpointClassification> {
 	let endpoint: NotificationEndpointFile;
 	let raw: string;
 	try {
@@ -334,16 +356,19 @@ async function readEndpointView(fs: NotificationServiceFs, file: string): Promis
 		return unreadableEndpointResult(file);
 	}
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { kind: "non-endpoint" };
+	if (path.basename(file) === "broker.json") return { kind: "non-endpoint" };
 	const rec = parsed as Record<string, unknown>;
 	if (isLifecycleArtifact(rec) || typeof rec.url !== "string" || typeof rec.token !== "string")
 		return { kind: "non-endpoint" };
+	const view: NotificationEndpointView = {
+		sessionId: typeof rec.sessionId === "string" ? rec.sessionId : path.basename(file, ".json"),
+		pid: safePositiveInteger(rec.pid),
+		stale: rec.stale === true,
+	};
 	return {
 		kind: "endpoint",
-		view: {
-			sessionId: typeof rec.sessionId === "string" ? rec.sessionId : path.basename(file, ".json"),
-			pid: safePositiveInteger(rec.pid),
-			stale: rec.stale === true,
-		},
+		view,
+		liveness: notificationEndpointLiveness(view, pidAlive),
 		identity: endpoint.identity,
 	};
 }
@@ -554,10 +579,21 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		checks.push({ name: "config", level: "ok", detail: "enabled with at least one configured adapter" });
 	}
 
-	// Daemon ownership state (offline; read the persisted state file directly).
-	const paths = daemonPaths(opts.settings.getAgentDir());
-	const state = await readDaemonStateFile(fs, paths.state);
-	const heartbeatAt = state?.heartbeatAt;
+	// Daemon ownership state (offline; corrupt or unreadable state degrades to a
+	// warning instead of making the health command itself fail).
+	let daemonStateUnreadable = false;
+	let snapshot: OwnerFreshnessSnapshot;
+	try {
+		snapshot = await readOwnerFreshnessSnapshot({
+			settings: opts.settings,
+			fs: fs as unknown as TelegramDaemonFs,
+		});
+	} catch {
+		daemonStateUnreadable = true;
+		snapshot = { ownerTag: null, effectiveHeartbeatAt: undefined, legacyEmbedded: false, state: undefined };
+	}
+	const state = snapshot.state ? parseDaemonState(JSON.stringify(snapshot.state)) : undefined;
+	const heartbeatAt = finiteNonNegativeNumber(snapshot.effectiveHeartbeatAt);
 	const daemon: DaemonHealth = {
 		present: Boolean(state),
 		ownerId: state?.ownerId,
@@ -576,7 +612,9 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		currentGeneration: DAEMON_GENERATION,
 		generationRelation: daemonGenerationRelation(state),
 	};
-	if (!state) {
+	if (daemonStateUnreadable) {
+		checks.push({ name: "daemon", level: "warn", detail: "daemon ownership record is corrupt or unreadable" });
+	} else if (!state) {
 		checks.push({ name: "daemon", level: "ok", detail: "no daemon ownership record (none running)" });
 	} else if (!daemon.alive) {
 		checks.push({
@@ -604,14 +642,13 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 	let unknownEndpoints = 0;
 	let unreadable = 0;
 	for (const name of files) {
-		const record = await readEndpointView(fs, path.join(dir, name));
+		const record = await classifyNotificationEndpoint(fs, path.join(dir, name), pidAlive);
 		if (record.kind === "non-endpoint") continue;
 		if (record.kind === "unreadable") {
 			unreadable += 1;
 			continue;
 		}
-		const view = record.view;
-		switch (endpointLiveness(view, pidAlive)) {
+		switch (record.liveness) {
 			case "live":
 				live += 1;
 				break;
@@ -877,7 +914,16 @@ async function detachTransitionMarker(
 ): Promise<boolean> {
 	if (!snapshot.identity || !fs.exactUnlink) return false;
 	try {
-		return (await fs.exactUnlink(path, snapshot.identity)).ok;
+		const removed = await fs.exactUnlink(path, snapshot.identity);
+		if (removed.ok) return true;
+		// Accept only typed retained authority: a concrete detached quarantine plus
+		// a proven-absent canonical marker pathname. Anything else stays fail-closed.
+		return (
+			removed.code === "cleanup_pending" &&
+			typeof removed.detachedPath === "string" &&
+			removed.detachedPath.length > 0 &&
+			(await fs.readFile(path, "utf8").catch(() => undefined)) === undefined
+		);
 	} catch {
 		return false;
 	}
@@ -1040,7 +1086,7 @@ export async function recoverNotifications(opts: RecoveryOptions): Promise<Notif
 	let unreadable = 0;
 	for (const name of files) {
 		const file = path.join(dir, name);
-		const record = await readEndpointView(fs, file);
+		const record = await classifyNotificationEndpoint(fs, file, pidAlive);
 		if (record.kind === "non-endpoint") continue;
 		if (record.kind === "unreadable") {
 			// Leave unparseable files untouched: they may be mid-write by a live server.
@@ -1048,7 +1094,7 @@ export async function recoverNotifications(opts: RecoveryOptions): Promise<Notif
 			continue;
 		}
 		const view = record.view;
-		if (endpointLiveness(view, pidAlive) !== "dead") {
+		if (record.liveness !== "dead") {
 			// Keep live AND unknown (PID-less) endpoints: only positive proof of
 			// death (a stale tombstone or a dead pid) authorizes removal.
 			kept += 1;
@@ -1057,11 +1103,27 @@ export async function recoverNotifications(opts: RecoveryOptions): Promise<Notif
 		try {
 			const result = await fs.exactUnlink(file, record.identity);
 			if (!result.ok) {
-				recoveryFailures += 1;
 				if (result.detachedPath) detached.push(result.detachedPath);
 				if (result.retainedSuccessorPath) retainedSuccessors.push(result.retainedSuccessorPath);
 				if (result.retainedPlaceholderPath) retainedPlaceholders.push(result.retainedPlaceholderPath);
 				if (result.retainedUnknownPath) retainedUnknown.push(result.retainedUnknownPath);
+				// Typed retained authority with a concrete quarantine and a proven-absent
+				// canonical endpoint counts as removed; the detached path above is the
+				// durable evidence. Anything else is a genuine recovery failure.
+				const retainedRemoved =
+					result.code === "cleanup_pending" &&
+					typeof result.detachedPath === "string" &&
+					result.detachedPath.length > 0 &&
+					(await fs.readFile(file, "utf8").catch(() => undefined)) === undefined;
+				if (retainedRemoved) {
+					removed.push({
+						sessionId: view.sessionId,
+						pid: view.pid,
+						reason: view.stale ? "stale-flag" : "dead-pid",
+					});
+					continue;
+				}
+				recoveryFailures += 1;
 				if (
 					!result.detachedPath &&
 					!result.retainedSuccessorPath &&