@gajae-code/coding-agent 0.16.7 → 0.17.1

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

@@ -5,7 +5,13 @@ import { createHash, randomUUID } from "node:crypto";
  * Preserves Q26 admit/first-terminal/capacity semantics; indexes and caps are per-kind.
  */
 
-import { sanitizePromptFailure } from "../prompt-failure";
+import {
+	failedPromptOutcome,
+	failureEvidence,
+	type PromptFailureEvidence,
+	rephaseFailedOutcome,
+	sanitizePromptFailure,
+} from "../prompt-failure";
 import type {
 	PromptReconciliationStatus,
 	SdkPromptFailureCode,
@@ -55,7 +61,10 @@ const STOP_REASONS: readonly SdkPromptStopReason[] = [
 ];
 const FAILURE_CODES: readonly SdkPromptFailureCode[] = ["prompt_failed", "prompt_deadline_exceeded"];
 
-const normalizeTerminalOutcome = (outcome: unknown): SdkPromptTerminalOutcome | undefined => {
+const normalizeTerminalOutcome = (
+	outcome: unknown,
+	evidence: PromptFailureEvidence = {},
+): SdkPromptTerminalOutcome | undefined => {
 	if (outcome === null || typeof outcome !== "object") return undefined;
 	const candidate = outcome as Record<string, unknown>;
 	if (
@@ -73,23 +82,32 @@ const normalizeTerminalOutcome = (outcome: unknown): SdkPromptTerminalOutcome |
 		FAILURE_CODES.includes(candidate.code as SdkPromptFailureCode) &&
 		typeof candidate.message === "string" &&
 		["agent_failed", "deadline"].includes(candidate.provenance as string)
-	)
-		return {
-			kind: "failed",
+	) {
+		return failedPromptOutcome({
 			code: candidate.code as SdkPromptFailureCode,
-			message:
-				candidate.code === "prompt_deadline_exceeded" ? "Prompt deadline exceeded." : "Prompt submission failed.",
 			provenance: candidate.provenance as "agent_failed" | "deadline",
-		};
+			...(typeof candidate.providerCode === "string" ? { providerCode: candidate.providerCode } : {}),
+			evidence,
+		});
+	}
 	return undefined;
 };
 
-const failedOutcomeForError = (error: { code: string; message: string }): SdkPromptTerminalOutcome => ({
-	kind: "failed",
-	code: "prompt_failed",
-	message: error.message,
-	provenance: "agent_failed",
-});
+const failedOutcomeForError = (
+	error: { code: string; message: string },
+	evidence: PromptFailureEvidence = {},
+	providerCodeOverride?: string,
+): SdkPromptTerminalOutcome =>
+	failedPromptOutcome({
+		code: "prompt_failed",
+		provenance: "agent_failed",
+		...(providerCodeOverride !== undefined
+			? { providerCode: providerCodeOverride }
+			: error.code !== "prompt_failed"
+				? { providerCode: error.code }
+				: {}),
+		evidence,
+	});
 
 const isDeadlineOutcome = (outcome: SdkPromptTerminalOutcome | undefined): boolean =>
 	outcome?.kind === "failed" && outcome.provenance === "deadline";
@@ -440,7 +458,10 @@ export function createKindAwareReconciliation(
 						record.receiptState,
 						reportableTurnResultContent(content) ? "present" : undefined,
 					);
-					const incomingOutcome = normalizeTerminalOutcome(frame.outcome);
+					const incomingOutcome = normalizeTerminalOutcome(
+						frame.outcome,
+						failureEvidence(record, frame.hasActivity),
+					);
 					const providerErrorRecord = record.error;
 					const providerError =
 						providerErrorRecord !== undefined && providerErrorRecord.code !== "prompt_deadline_exceeded";
@@ -460,7 +481,7 @@ export function createKindAwareReconciliation(
 								? providerErrorRecord
 								: { code: providerOutcome.code, message: providerOutcome.message };
 						} else if (providerError) {
-							outcome = failedOutcomeForError(providerErrorRecord);
+							outcome = failedOutcomeForError(providerErrorRecord, failureEvidence(record, frame.hasActivity));
 							error = providerErrorRecord;
 						} else if (
 							incomingOutcome?.kind === "stopped" ||
@@ -479,7 +500,7 @@ export function createKindAwareReconciliation(
 								? providerErrorRecord
 								: { code: providerOutcome.code, message: providerOutcome.message };
 						} else if (record.status === "failed" && providerError) {
-							outcome = failedOutcomeForError(providerErrorRecord);
+							outcome = failedOutcomeForError(providerErrorRecord, failureEvidence(record, frame.hasActivity));
 							error = providerErrorRecord;
 						} else if (
 							record.status === "terminal_ok" &&
@@ -523,7 +544,7 @@ export function createKindAwareReconciliation(
 					const failure = sanitizePromptFailure(frame.error);
 					if (record.error?.code === "prompt_deadline_exceeded") {
 						record.error = failure;
-						record.outcome = failedOutcomeForError(failure);
+						record.outcome = failedOutcomeForError(failure, failureEvidence(record, frame.hasActivity));
 						record.status = "failed";
 						return { value: undefined, changed: true };
 					}
@@ -557,7 +578,10 @@ export function createKindAwareReconciliation(
 				return { value: undefined, changed: true };
 			}
 			const pendingOutcome = record.pendingOutcome;
-			const frameOutcome = normalizeTerminalOutcome(frame.type === "agent_end" ? frame.outcome : undefined);
+			const frameOutcome = normalizeTerminalOutcome(
+				frame.type === "agent_end" ? frame.outcome : undefined,
+				failureEvidence(record, frame.hasActivity),
+			);
 			delete record.deadlineRecoveryPending;
 			delete record.deadlineMaxAt;
 			record.terminalAt = now();
@@ -572,7 +596,7 @@ export function createKindAwareReconciliation(
 				if (frameOutcome?.kind === "failed" && frameOutcome.provenance === "agent_failed")
 					terminalOutcome = frameOutcome;
 				else if (providerError && (pendingOutcome.kind !== "failed" || isDeadlineOutcome(pendingOutcome)))
-					terminalOutcome = failedOutcomeForError(providerErrorRecord);
+					terminalOutcome = failedOutcomeForError(providerErrorRecord, failureEvidence(record, frame.hasActivity));
 				else if (isDeadlineOutcome(pendingOutcome) && frameOutcome?.kind === "stopped")
 					terminalOutcome = frameOutcome;
 				record.outcome = terminalOutcome;
@@ -598,7 +622,7 @@ export function createKindAwareReconciliation(
 					? frameOutcome
 					: providerError &&
 							(frameOutcome === undefined || isDeadlineOutcome(frameOutcome) || frameOutcome.kind === "stopped")
-						? failedOutcomeForError(providerErrorRecord)
+						? failedOutcomeForError(providerErrorRecord, failureEvidence(record, frame.hasActivity))
 						: frameOutcome;
 				if (terminalOutcome !== undefined) {
 					record.outcome = terminalOutcome;
@@ -618,10 +642,10 @@ export function createKindAwareReconciliation(
 				) {
 					record.status = "failed";
 					record.error = EMPTY_PROMPT_FAILURE;
-					record.outcome = failedOutcomeForError(EMPTY_PROMPT_FAILURE);
+					record.outcome = failedOutcomeForError(EMPTY_PROMPT_FAILURE, failureEvidence(record, frame.hasActivity));
 				} else if (record.error !== undefined) {
 					record.status = "failed";
-					record.outcome = failedOutcomeForError(record.error);
+					record.outcome = failedOutcomeForError(record.error, failureEvidence(record, frame.hasActivity));
 				} else record.status = "terminal_ok";
 				record.receiptState = reduceReceiptState(
 					record.receiptState,
@@ -645,9 +669,10 @@ export function createKindAwareReconciliation(
 			if (!record || record.terminalAt !== undefined || record.kind !== kind)
 				return { value: normalized, changed: false };
 			if (record.pendingOutcome !== undefined) return { value: record.pendingOutcome, changed: false };
-			record.pendingOutcome = normalized;
+			const decorated = rephaseFailedOutcome(normalized, failureEvidence(record));
+			record.pendingOutcome = decorated;
 			record.pendingReceiptState = receiptState;
-			return { value: normalized, changed: true };
+			return { value: decorated, changed: true };
 		});
 
 	const finalizeOutcome = async (
@@ -673,25 +698,28 @@ export function createKindAwareReconciliation(
 			const record = candidate.get(keyOf(kind, correlation));
 			if (!record || record.terminalAt !== undefined || record.kind !== kind)
 				return { value: undefined, changed: false };
-			const requestedOutcome = normalizeTerminalOutcome(outcome) ?? record.pendingOutcome;
+			const requestedOutcome = normalizeTerminalOutcome(outcome, failureEvidence(record)) ?? record.pendingOutcome;
 			const providerErrorRecord = record.error;
 			const providerError =
 				providerErrorRecord !== undefined && providerErrorRecord.code !== "prompt_deadline_exceeded";
+			const requestedProviderCode = requestedOutcome?.kind === "failed" ? requestedOutcome.providerCode : undefined;
 			const finalOutcome = providerError
-				? failedOutcomeForError(providerErrorRecord)
+				? failedOutcomeForError(providerErrorRecord, failureEvidence(record), requestedProviderCode)
 				: requestedOutcome?.kind === "stopped"
 					? requestedOutcome
 					: providerError &&
 							(requestedOutcome === undefined ||
 								(requestedOutcome.kind === "failed" && isDeadlineOutcome(requestedOutcome)))
-						? failedOutcomeForError(providerErrorRecord)
+						? failedOutcomeForError(providerErrorRecord, failureEvidence(record), requestedProviderCode)
 						: requestedOutcome;
 			record.terminalAt = now();
 			if (finalOutcome?.kind === "failed") {
 				record.status = "failed";
 				if (recordError !== undefined && !(providerError && recordError.code === "prompt_deadline_exceeded"))
-					record.error = recordError;
-				else if (!providerError) record.error = { code: finalOutcome.code, message: finalOutcome.message };
+					record.error = { code: recordError.code, message: finalOutcome.message };
+				else if (providerError && providerErrorRecord !== undefined)
+					record.error = { code: providerErrorRecord.code, message: finalOutcome.message };
+				else record.error = { code: finalOutcome.code, message: finalOutcome.message };
 			} else if (
 				kind === "prompt" &&
 				((finalOutcome === undefined && !sanitizedContent?.text.trim()) ||
@@ -699,7 +727,7 @@ export function createKindAwareReconciliation(
 			) {
 				record.status = "failed";
 				record.error = EMPTY_PROMPT_FAILURE;
-				record.outcome = failedOutcomeForError(EMPTY_PROMPT_FAILURE);
+				record.outcome = failedOutcomeForError(EMPTY_PROMPT_FAILURE, failureEvidence(record));
 			} else if (finalOutcome?.kind === "stopped") {
 				// A stopped terminal is authoritative only when no provider failure
 				// was recorded before finalization.
@@ -837,16 +865,23 @@ export function createKindAwareReconciliation(
 				loaded.map(record => {
 					const safeOutcome = (
 						outcome: SdkPromptTerminalOutcome | undefined,
-					): SdkPromptTerminalOutcome | undefined =>
-						outcome?.kind === "failed"
-							? {
-									...outcome,
-									message:
-										outcome.code === "prompt_deadline_exceeded"
-											? "Prompt deadline exceeded."
-											: "Prompt submission failed.",
-								}
-							: outcome;
+					): SdkPromptTerminalOutcome | undefined => {
+						if (outcome?.kind !== "failed") return outcome;
+						const rephased = rephaseFailedOutcome(
+							outcome,
+							record.startedAt !== undefined ? { startedAt: record.startedAt } : {},
+						);
+						// Legacy durable rows carry a generic message and no phase/category;
+						// rewriting them to the current contract is a durable-state sanitization.
+						if (
+							rephased.kind === "failed" &&
+							(outcome.phase !== rephased.phase ||
+								outcome.category !== rephased.category ||
+								outcome.message !== rephased.message)
+						)
+							sanitizedDurableRecord = true;
+						return rephased;
+					};
 					let hydrated: DurableReconciliationRecord;
 					if (record.kind === "steer") {
 						const safeError = record.error === undefined ? undefined : sanitizePromptFailure(record.error);

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

@@ -52,7 +52,13 @@ import { DiscordLiveProvider } from "./discord-live-provider";
 import type { DiscordDiagnosticProvider } from "./discord-provider";
 import { SlackLiveProvider } from "./slack-live-provider";
 import type { SlackDiagnosticProvider } from "./slack-provider";
-import { type OwnerFreshnessSnapshot, readOwnerFreshnessSnapshot, type TelegramDaemonFs } from "./telegram-daemon";
+import {
+	isTelegramDaemonStopCause,
+	type OwnerFreshnessSnapshot,
+	readOwnerFreshnessSnapshot,
+	type TelegramDaemonFs,
+	type TelegramDaemonStopCause,
+} from "./telegram-daemon";
 import { DAEMON_GENERATION } from "./telegram-daemon-contract";
 
 const DEFAULT_API_BASE = "https://api.telegram.org";
@@ -547,6 +553,7 @@ interface NormalizedDaemonState {
 	startedAt: number | undefined;
 	heartbeatAt: number | undefined;
 	stoppedAt: number | undefined;
+	stopCause: TelegramDaemonStopCause | undefined;
 	roots: string[] | undefined;
 	generation: number | undefined;
 	generationStatus: "missing" | "valid" | "invalid";
@@ -594,6 +601,7 @@ function parseDaemonState(raw: string): NormalizedDaemonState | undefined {
 		startedAt: finiteNonNegativeNumber(rec.startedAt),
 		heartbeatAt: finiteNonNegativeNumber(rec.heartbeatAt),
 		stoppedAt: finiteNonNegativeNumber(rec.stoppedAt),
+		stopCause: isTelegramDaemonStopCause(rec.stopCause) ? rec.stopCause : undefined,
 		roots: stringArray(rec.roots),
 		generation,
 		generationStatus,
@@ -677,6 +685,8 @@ export interface DaemonHealth {
 	stopped: boolean;
 	heartbeatAt: number | undefined;
 	heartbeatAgeMs: number | undefined;
+	/** Bounded persisted stop cause; absent means this record predates diagnostics or is unknown. */
+	stopCause?: TelegramDaemonStopCause;
 
 	/**
 	 * Session endpoints the live owner reported an OPEN socket to in its latest
@@ -928,6 +938,7 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		stopped: state?.stoppedAt !== undefined,
 		heartbeatAt,
 		heartbeatAgeMs: heartbeatAt === undefined ? undefined : displayHeartbeatAgeMs(now, heartbeatAt),
+		...(state?.stopCause === undefined ? {} : { stopCause: state.stopCause }),
 		attachedEndpoints: snapshot.attachedEndpoints,
 		generation: state?.generation,
 		currentGeneration: DAEMON_GENERATION,
@@ -948,19 +959,26 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 			} catch {
 				lockPresent = false;
 			}
+			const stopCause = daemon.stopCause ?? "unknown";
 			if (lockPresent) {
 				checks.push({
 					name: "daemon",
 					level: "warn",
-					detail: `daemon owner pid ${daemon.pid} is not alive; run recovery to clear the stale lock`,
+					detail: `daemon owner pid ${daemon.pid} is not alive; run recovery to clear the stale lock (stop cause: ${stopCause})`,
 				});
 			} else {
 				checks.push({
 					name: "daemon",
 					level: "warn",
-					detail: `daemon owner pid ${daemon.pid} is not alive; no lock present (daemon exited cleanly)`,
+					detail: `daemon owner pid ${daemon.pid} is not alive; no lock present (stop cause: ${stopCause})`,
 				});
 			}
+		} else if (daemon.stopped) {
+			checks.push({
+				name: "daemon",
+				level: "warn",
+				detail: `daemon is stopped (stop cause: ${daemon.stopCause ?? "unknown"})`,
+			});
 		} else if (!daemon.heartbeatFresh) {
 			checks.push({ name: "daemon", level: "warn", detail: `daemon pid ${daemon.pid} heartbeat is stale` });
 		} else if (telegramConfigured && !daemon.identityMatches) {

package/src/sdk/bus/reconciliation-store.ts

@@ -12,6 +12,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { failedPromptOutcome } from "../prompt-failure";
 import type { PromptReconciliationStatus, SdkPromptTerminalOutcome } from "../prompt-status";
 import type { ReceiptState } from "../receipt-state";
 import { reportableTurnResultContent, TURN_RESULT_CONTENT_MAX_BYTES, type TurnResultContent } from "../turn-result";
@@ -559,12 +560,16 @@ export function settleProcessRestart(
 ): DurableReconciliationRecord[] {
 	const isDeadlineOutcome = (outcome: SdkPromptTerminalOutcome | undefined): boolean =>
 		outcome?.kind === "failed" && outcome.provenance === "deadline";
-	const providerFailureOutcome = (error: { code: string; message: string }): SdkPromptTerminalOutcome => ({
-		kind: "failed",
-		code: "prompt_failed",
-		message: error.message,
-		provenance: "agent_failed",
-	});
+	const providerFailureOutcome = (
+		error: { code: string; message: string },
+		record: { startedAt?: number },
+	): SdkPromptTerminalOutcome =>
+		failedPromptOutcome({
+			code: "prompt_failed",
+			provenance: "agent_failed",
+			...(error.code !== "prompt_failed" ? { providerCode: error.code } : {}),
+			evidence: record.startedAt !== undefined ? { startedAt: record.startedAt } : {},
+		});
 	return records.map(record => {
 		if (record.kind === "steer") {
 			if (record.status !== "dispatching") return record;
@@ -592,13 +597,14 @@ export function settleProcessRestart(
 			const outcome: SdkPromptTerminalOutcome =
 				providerError &&
 				(pendingOutcome === undefined || isDeadlineOutcome(pendingOutcome) || pendingOutcome.kind === "stopped")
-					? providerFailureOutcome(providerErrorRecord)
-					: (pendingOutcome ?? {
-							kind: "failed",
+					? providerFailureOutcome(providerErrorRecord, record)
+					: (pendingOutcome ??
+						failedPromptOutcome({
 							code: "prompt_failed",
-							message: "Prompt did not complete before process restart.",
 							provenance: "agent_failed",
-						});
+							providerCode: "process_restart_uncertain",
+							evidence: record.startedAt !== undefined ? { startedAt: record.startedAt } : {},
+						}));
 			const preservedError =
 				providerError && preserveProviderError
 					? providerErrorRecord

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

@@ -13,6 +13,7 @@ import {
 	parseNotificationSettingsSnapshot,
 } from "./config";
 import { daemonPaths, HEARTBEAT_TTL_MS } from "./daemon-paths";
+import { doctorDaemonIdentityMatches, doctorDaemonOccupancySettled } from "./doctor-daemon-restart";
 import { type NotificationDebrisSweepReport, sweepNotificationDebris } from "./notification-service";
 import {
 	type DaemonState,
@@ -26,11 +27,26 @@ import {
 	type TelegramDaemonOptions,
 	TelegramNotificationDaemon,
 } from "./telegram-daemon";
-import { clearTelegramControlRequest, readTelegramControlRequest } from "./telegram-daemon-control";
+import {
+	clearTelegramControlRequest,
+	clearTelegramDoctorControlRequest,
+	readTelegramControlRequest,
+	readTelegramDoctorControlRequest,
+} from "./telegram-daemon-control";
 
 type TelegramDaemonRunner = {
 	run(): Promise<void>;
 	requestStop(reason?: "reload" | "signal" | "stop"): void;
+	prepareDoctorRestart?(): void;
+	cancelDoctorRestart?(): void;
+	doctorOccupancy?(): {
+		attached: number;
+		inflight: number;
+		inbound: number;
+		outbound: number;
+		cleanup: number;
+	};
+	doctorRestartReady?(): boolean;
 };
 
 type TelegramDaemonConstructor = new (opts: TelegramDaemonOptions) => TelegramDaemonRunner;
@@ -254,16 +270,23 @@ function ownerProcessIsAlive(ownerId: string, deps: RunDaemonInternalDeps): bool
 
 /** Creates owner-fenced daemon control hooks for the CLI lifecycle boundary. */
 export function createDaemonControlHooks(settings: Settings) {
+	const readOwnedRequest = async (owner: string) => {
+		const req = await readTelegramControlRequest(settings);
+		return req && (!req.ownerId || req.ownerId === owner) ? req : undefined;
+	};
 	return {
 		shouldStop: async (owner: string) => {
-			const req = await readTelegramControlRequest(settings);
-			return Boolean(req && (!req.ownerId || req.ownerId === owner));
+			return (await readOwnedRequest(owner)) !== undefined;
+		},
+		requestedAction: async (owner: string): Promise<"reload" | "stop" | undefined> => {
+			const action = (await readOwnedRequest(owner))?.action;
+			return action === "reload" || action === "stop" ? action : undefined;
 		},
 		clear: async (owner: string) => {
-			const req = await readTelegramControlRequest(settings);
+			const req = await readOwnedRequest(owner);
 			// Only clear a request that targets this daemon owner, so an exiting
 			// daemon never erases a newer request meant for a different owner.
-			if (req && (!req.ownerId || req.ownerId === owner)) await clearTelegramControlRequest(settings, req.requestId);
+			if (req) await clearTelegramControlRequest(settings, req.requestId);
 		},
 	};
 }
@@ -409,6 +432,22 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 		requireTelegramTopicEligibility: true,
 		orphanReap,
 	});
+	const doctorOwnerIdentity = async (): Promise<
+		| {
+				owner: "telegram";
+				ownerId: string;
+				generation: number;
+				incarnation: string;
+		  }
+		| undefined
+	> => {
+		const current = await readState(settings as Settings);
+		if (!current || !hasSafeDaemonStateShape(current) || current.ownerId !== ownerId) return undefined;
+		const expectedIncarnation = (deps.pidIncarnation ?? processIncarnation)(deps.processPid ?? process.pid);
+		if (!expectedIncarnation || current.incarnation !== expectedIncarnation || current.generation === undefined)
+			return undefined;
+		return { owner: "telegram", ownerId, generation: current.generation, incarnation: current.incarnation };
+	};
 	// Signals are a process concern: install them at the daemon-internal boundary,
 	// not inside the embeddable daemon class. SIGTERM is the reload wakeup path.
 	const onSignal = (): void => daemon.requestStop("signal");
@@ -418,6 +457,8 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 	let watchdogActive = true;
 	let watchdogTickInFlight = false;
 	let stopRequested = false;
+	let doctorPreparedRequestId: string | undefined;
+	let doctorPoll: Timer | undefined;
 	let lastHeartbeatAt: number | undefined;
 	let stalledSince: number | undefined;
 	const watchdogTick = async (): Promise<void> => {
@@ -526,8 +567,53 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 		await recordOwnerStopped();
 	});
 	try {
+		const doctorTick = async (): Promise<void> => {
+			const request = await readTelegramDoctorControlRequest(settings as Settings);
+			if (!request) return;
+			const identity = await doctorOwnerIdentity();
+			// The shared predicate is the single definition of "this request addresses
+			// exactly me"; spelling the four fields out here would let this owner and the
+			// doctor client drift apart silently.
+			if (
+				!identity ||
+				!doctorDaemonIdentityMatches(request, identity) ||
+				(request.action !== "prepare" &&
+					request.action !== "commit" &&
+					request.action !== "cancel" &&
+					request.action !== "status")
+			)
+				return;
+			if (request.leaseExpiresAt !== undefined && request.leaseExpiresAt <= (deps.now ?? Date.now)()) {
+				// Expiry never reopens admission implicitly; an authorized
+				// coordinator must issue cancel after recovering the lease.
+				return;
+			}
+			if (request.action === "prepare") {
+				daemon.prepareDoctorRestart?.();
+				doctorPreparedRequestId = request.requestId;
+				return;
+			}
+			if (request.action === "cancel") {
+				if (doctorPreparedRequestId === request.requestId) daemon.cancelDoctorRestart?.();
+				await clearTelegramDoctorControlRequest(settings as Settings, request.requestId);
+				doctorPreparedRequestId = undefined;
+				return;
+			}
+			if (request.action === "commit" && doctorPreparedRequestId === request.requestId) {
+				const occupancy = daemon.doctorOccupancy?.();
+				if (!occupancy || !doctorDaemonOccupancySettled(occupancy)) return;
+				if (!daemon.doctorRestartReady?.()) return;
+				// A committed intent is durable across this owner's exit. The
+				// successor/doctor clears it only after proving old death, cleanup,
+				// and successor publication.
+				daemon.requestStop("reload");
+				doctorPreparedRequestId = undefined;
+			}
+		};
+		doctorPoll = schedule(() => void doctorTick(), 50);
 		await daemon.run();
 	} finally {
+		if (doctorPoll !== undefined) unschedule(doctorPoll);
 		watchdogActive = false;
 		unschedule(watchdog);
 		process.off("SIGTERM", onSignal);

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

@@ -291,7 +291,7 @@ export const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * killing a session's mirroring after one transient rejection and must be
  * replaced across this upgrade.
  */
-export const DAEMON_GENERATION = 181;
+export const DAEMON_GENERATION = 187;
 
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7

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

@@ -27,6 +27,7 @@ import { resolveGjcRuntimeSpawnInfo } from "../../daemon/runtime";
 import { isProcessIncarnation } from "../broker/process-incarnation";
 
 import { getNotificationConfig, isTelegramComplete, tokenFingerprint } from "./config";
+import { type DoctorDaemonControlRequest, isDoctorDaemonControlRequest } from "./doctor-daemon-restart";
 import {
 	type AttestedLegacyDaemonOwner,
 	confirmTelegramDaemonSpawn,
@@ -36,6 +37,7 @@ import {
 	isCurrentCompatibleOwner,
 	isFreshLiveOwner,
 	isSignalableMatchingOwner,
+	isTelegramDaemonStopCause,
 	readAttestedLegacyDaemonOwner,
 	readDaemonState,
 	readOwnerFreshnessSnapshot,
@@ -65,6 +67,48 @@ export function telegramControlRequestPath(agentDir: string): string {
 	return path.join(daemonPaths(agentDir).dir, "telegram-daemon.control.json");
 }
 
+export function telegramDoctorControlRequestPath(agentDir: string): string {
+	return path.join(daemonPaths(agentDir).dir, "doctor-restart.control.json");
+}
+
+export async function readTelegramDoctorControlRequest(
+	settings: Settings,
+	fsImpl: TelegramDaemonFs = nodeFs,
+): Promise<DoctorDaemonControlRequest | undefined> {
+	try {
+		const parsed = JSON.parse(
+			await fsImpl.readFile(telegramDoctorControlRequestPath(settings.getAgentDir()), "utf8"),
+		) as unknown;
+		return isDoctorDaemonControlRequest(parsed) && parsed.owner === "telegram" ? parsed : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function writeTelegramDoctorControlRequest(
+	settings: Settings,
+	request: DoctorDaemonControlRequest,
+	fsImpl: TelegramDaemonFs = nodeFs,
+): Promise<void> {
+	if (request.owner !== "telegram") throw new Error("telegram doctor request owner mismatch");
+	const dir = daemonPaths(settings.getAgentDir()).dir;
+	await fsImpl.mkdir(dir, { recursive: true, mode: 0o700 });
+	const file = telegramDoctorControlRequestPath(settings.getAgentDir());
+	const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+	await fsImpl.writeFile(tmp, `${JSON.stringify(request)}\n`, { mode: 0o600 });
+	await fsImpl.rename(tmp, file);
+}
+
+export async function clearTelegramDoctorControlRequest(
+	settings: Settings,
+	requestId?: string,
+	fsImpl: TelegramDaemonFs = nodeFs,
+): Promise<void> {
+	const file = telegramDoctorControlRequestPath(settings.getAgentDir());
+	if (requestId && (await readTelegramDoctorControlRequest(settings, fsImpl))?.requestId !== requestId) return;
+	await fsImpl.unlink(file).catch(() => undefined);
+}
+
 export async function readTelegramControlRequest(
 	settings: Settings,
 	fsImpl: TelegramDaemonFs = nodeFs,
@@ -236,6 +280,8 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 						})
 					? "running"
 					: "stale";
+		const stopCause = isTelegramDaemonStopCause(state?.stopCause) ? state.stopCause : undefined;
+		const detail = health === "stopped" && state ? `stop cause: ${stopCause ?? "unknown"}` : undefined;
 		return {
 			kind: this.kind,
 			configured: true,
@@ -244,6 +290,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 			ownerId: state?.ownerId,
 			startedAt: state?.startedAt,
 			heartbeatAt: snapshot.effectiveHeartbeatAt,
+			...(detail === undefined ? {} : { detail }),
 			runtime,
 		};
 	}

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

@@ -15,7 +15,7 @@ export interface TelegramOwnerMarker {
 	startedAt: number;
 }
 
-function validMarker(value: unknown): value is TelegramOwnerMarker {
+export function validMarker(value: unknown): value is TelegramOwnerMarker {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 	const v = value as Record<string, unknown>;
 	return (