@gajae-code/coding-agent 0.11.9 → 0.11.10

package/src/modes/controllers/selector-controller.ts

@@ -64,8 +64,10 @@ import {
 import type { NotificationSessionStatus } from "../../sdk/bus/session-control";
 import {
 	ensureTelegramDaemonRunningDetailed,
+	readNotificationRootRegistration,
 	resolveTelegramSetupPreflight,
 	unregisterNotificationRoot,
+	withNotificationRootRegistryFence,
 } from "../../sdk/bus/telegram-daemon";
 import { TelegramDaemonController } from "../../sdk/bus/telegram-daemon-control";
 import { runTelegramSetup, type TelegramSetupPreflight } from "../../sdk/bus/telegram-setup";
@@ -216,6 +218,12 @@ export interface NotificationsEditorAdapterContext {
 	notifyConfigChanged?: () => Promise<void> | void;
 }
 
+type TelegramDaemonStopResult = {
+	ok: boolean;
+	message: string;
+	before?: { health?: string };
+};
+
 export interface NotificationsEditorOperationDependencies {
 	getNotificationConfig: typeof getNotificationConfig;
 	maskToken: typeof maskToken;
@@ -231,14 +239,17 @@ export interface NotificationsEditorOperationDependencies {
 	reconcileCommittedTelegramConfiguration: typeof reconcileCommittedTelegramConfiguration;
 	saveTelegramInactive: typeof saveTelegramInactive;
 	removeTelegramConfiguration: typeof removeTelegramConfiguration;
+	readNotificationRootRegistration: typeof readNotificationRootRegistration;
 	unregisterNotificationRoot: typeof unregisterNotificationRoot;
+	stopTelegramDaemonIfRootRegistryFenceMatches(input: {
+		settings: Settings;
+		registryFingerprint: string;
+		stop: () => Promise<TelegramDaemonStopResult>;
+	}): Promise<boolean>;
+
 	reloadTelegramDaemon(settings: Settings): Promise<{ ok: boolean; message: string }>;
 	restartTelegramDaemon(settings: Settings): Promise<{ ok: boolean; message: string }>;
-	stopTelegramDaemon(settings: Settings): Promise<{
-		ok: boolean;
-		message: string;
-		before?: { health?: string };
-	}>;
+	stopTelegramDaemon(settings: Settings): Promise<TelegramDaemonStopResult>;
 }
 
 const notificationEditorOperationDependencies: NotificationsEditorOperationDependencies = {
@@ -256,7 +267,18 @@ const notificationEditorOperationDependencies: NotificationsEditorOperationDepen
 	reconcileCommittedTelegramConfiguration,
 	saveTelegramInactive,
 	removeTelegramConfiguration,
+	readNotificationRootRegistration,
 	unregisterNotificationRoot,
+	stopTelegramDaemonIfRootRegistryFenceMatches: async input =>
+		await withNotificationRootRegistryFence({
+			settings: input.settings,
+			registryFingerprint: input.registryFingerprint,
+			action: async () => {
+				const stopped = await input.stop();
+				if (!stopped.ok) throw new Error(stopped.message);
+			},
+		}),
+
 	reloadTelegramDaemon: async settings =>
 		await new TelegramDaemonController(settings).reload({ spawnIfStopped: false }),
 	restartTelegramDaemon: async settings =>
@@ -625,14 +647,22 @@ export function createNotificationsEditorOperations(
 						stopAndUnregister: async () => {
 							if (controller) await controller.enterBlockedRuntime(sessionContext());
 							runtimePrepared = true;
+							const registration = await services.readNotificationRootRegistration({
+								settings: ctx.settings,
+								sessionId: ctx.sessionManager.getSessionId(),
+							});
 							const unregistered = await services.unregisterNotificationRoot({
 								settings: ctx.settings,
 								cwd: ctx.sessionManager.getCwd(),
 								sessionId: ctx.sessionManager.getSessionId(),
+								registrationToken: registration.token,
 							});
-							if (unregistered.remainingRoots === 0) {
-								const stopped = await new TelegramDaemonController(ctx.settings).stop();
-								if (!stopped.ok) throw new Error(stopped.message);
+							if (unregistered.registryFingerprint !== undefined) {
+								await services.stopTelegramDaemonIfRootRegistryFenceMatches({
+									settings: ctx.settings,
+									registryFingerprint: unregistered.registryFingerprint,
+									stop: () => services.stopTelegramDaemon(ctx.settings),
+								});
 							}
 						},
 					},

package/src/prompts/agent-fragments/restricted-bash.md

@@ -1 +1 @@
-- Exception: restricted `bash` is only for sanctioned GJC workflow persistence (`gjc ralplan --write ...`) and GJC workflow state commands (`gjc state ...`). Pass artifacts through `GJC_RALPLAN_ARTIFACT` with `--artifact-env GJC_RALPLAN_ARTIFACT`; never use bash for product-source writes or general shell work.
+- Exception: restricted `bash` is only for sanctioned GJC workflow persistence (`gjc ralplan --write ...`), GJC workflow state commands (`gjc state ...`), and read-only git inspection (`git status`, `git log`, `git show`, `git diff`, `git blame`, `git rev-parse`, `git ls-files`). Pass artifacts through `GJC_RALPLAN_ARTIFACT` with `--artifact-env GJC_RALPLAN_ARTIFACT`; never use bash for product-source writes, commits, pushes, or other mutating/general shell work.

package/src/prompts/agents/architect.md

@@ -1,13 +1,20 @@
 ---
 name: architect
 description: Read-only architecture and code-review agent with severity-rated findings and status verdicts
-tools: read, search, find, lsp, ast_grep, web_search, bash, report_finding
+tools: read, search, find, lsp, ast_grep, web_search, bash, report_finding, irc
 thinking-level: high
 blocking: true
 forkContext: allowed
 bashAllowedPrefixes:
   - gjc ralplan --write
   - gjc state
+  - git status
+  - git log
+  - git show
+  - git diff
+  - git blame
+  - git rev-parse
+  - git ls-files
 ---
 <identity>
 You are Architect. You combine system architecture review with code-review discipline. Diagnose, analyze, and recommend with file-backed evidence. You are read-only.

package/src/prompts/agents/critic.md

@@ -1,11 +1,18 @@
 ---
 name: critic
 description: Read-only plan critic that approves only actionable, verifiable execution plans
-tools: read, search, find, lsp, ast_grep, web_search, bash
+tools: read, search, find, lsp, ast_grep, web_search, bash, irc
 thinking-level: high
 bashAllowedPrefixes:
   - gjc ralplan --write
   - gjc state
+  - git status
+  - git log
+  - git show
+  - git diff
+  - git blame
+  - git rev-parse
+  - git ls-files
 ---
 <identity>
 You are Critic. Decide whether a work plan is actionable before execution begins.

package/src/prompts/agents/planner.md

@@ -1,11 +1,18 @@
 ---
 name: planner
 description: Read-only planning agent for sequencing, acceptance criteria, risks, and handoff shape
-tools: read, search, find, lsp, ast_grep, web_search, bash
+tools: read, search, find, lsp, ast_grep, web_search, bash, irc
 thinking-level: medium
 bashAllowedPrefixes:
   - gjc ralplan --write
   - gjc state
+  - git status
+  - git log
+  - git show
+  - git diff
+  - git blame
+  - git rev-parse
+  - git ls-files
 ---
 <identity>
 You are Planner. Turn requests into actionable work plans. You plan; you do not implement.

package/src/sdk/broker/identity.ts

@@ -11,20 +11,30 @@ export function brokerIdentityPath(agentDir: string): string {
 export async function getBrokerIdentityKey(agentDir: string): Promise<string> {
 	const file = brokerIdentityPath(agentDir);
 	await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
-	try {
-		const key = (await fs.readFile(file, "utf8")).trim();
-		if (/^[0-9a-f]{64}$/i.test(key)) return key;
-		throw new Error(`Invalid broker identity key at ${file}`);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	while (true) {
+		try {
+			const key = (await fs.readFile(file, "utf8")).trim();
+			if (/^[0-9a-f]{64}$/i.test(key)) return key;
+			throw new Error(`Invalid broker identity key at ${file}`);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+
 		const key = randomBytes(32).toString("hex");
+		const temporary = path.join(path.dirname(file), `.broker.identity-${randomBytes(16).toString("hex")}`);
 		try {
-			await fs.writeFile(file, `${key}\n`, { encoding: "utf8", mode: MODE, flag: "wx" });
-			await fs.chmod(file, MODE);
-			return key;
-		} catch (writeError) {
-			if ((writeError as NodeJS.ErrnoException).code !== "EEXIST") throw writeError;
-			return getBrokerIdentityKey(agentDir);
+			await fs.writeFile(temporary, `${key}\n`, { encoding: "utf8", mode: MODE, flag: "wx" });
+			await fs.chmod(temporary, MODE);
+			try {
+				// Link publishes a fully written key without exposing a partial target.
+				// Same-directory hard-link support is required (standard on Linux, macOS, and Windows NTFS).
+				await fs.link(temporary, file);
+				return key;
+			} catch (linkError) {
+				if ((linkError as NodeJS.ErrnoException).code !== "EEXIST") throw linkError;
+			}
+		} finally {
+			await fs.rm(temporary, { force: true });
 		}
 	}
 }

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

@@ -12,6 +12,7 @@ export interface DaemonPaths {
 	dir: string;
 	lock: string;
 	state: string;
+	heartbeat: string;
 	ownership: string;
 	roots: string;
 	steal: string;
@@ -26,6 +27,7 @@ export function daemonPaths(agentDir: string): DaemonPaths {
 		lock: path.join(dir, "telegram-daemon.lock"),
 		state: path.join(dir, "telegram-daemon.state.json"),
 		ownership: path.join(dir, "telegram-daemon.ownership"),
+		heartbeat: path.join(dir, "telegram-daemon.heartbeat.json"),
 		roots: path.join(dir, "telegram-daemon.roots.json"),
 		steal: path.join(dir, "telegram-daemon.steal"),
 		aliases: path.join(dir, "telegram-callback-aliases.json"),

package/src/sdk/bus/index.ts

@@ -89,6 +89,8 @@ import {
 	type EnsureDaemonResult,
 	endpointAuthorityDigest,
 	ensureTelegramDaemonRunningDetailed,
+	type RegisterNotificationRootResult,
+	unregisterNotificationRoot,
 } from "./telegram-daemon";
 
 // ===========================================================================
@@ -909,6 +911,8 @@ interface SessionRuntime {
 	hostStopped: boolean;
 	serverStopped: boolean;
 	brokerRegistrationReleased: boolean;
+	/** Managed Telegram root registration released during terminal teardown. */
+	notificationRootRegistration?: { settings: Settings; cwd: string; registrationToken?: string };
 	verbosity: "lean" | "verbose";
 	sessionTag: string;
 	/** Whether the agent loop is currently running (drives the typing indicator). */
@@ -2832,6 +2836,7 @@ export function createNotificationsExtension(
 			settings: Settings;
 			cwd: string;
 			sessionId: string;
+			onRegistered?: (registration: RegisterNotificationRootResult) => void;
 		}) => Promise<EnsureDaemonResult>;
 		ensureProviderDaemon?: (provider: "discord" | "slack", settings: Settings) => Promise<unknown>;
 		/** Suppress auto-delivery for a GJC-spawned child under `sessionScope=primary`. */
@@ -2873,13 +2878,24 @@ export function createNotificationsExtension(
 		settings: Settings,
 		cwd: string,
 		id: string,
+		onRegistered?: (registrationToken: string) => void,
 	): Promise<"ready" | "blocked_identity"> {
 		if (options.ensureTelegramDaemon) {
-			return (await options.ensureTelegramDaemon({ settings, cwd, sessionId: id })) === "blocked"
+			return (await options.ensureTelegramDaemon({
+				settings,
+				cwd,
+				sessionId: id,
+				onRegistered: registration => onRegistered?.(registration.token),
+			})) === "blocked"
 				? "blocked_identity"
 				: "ready";
 		}
-		return (await ensureTelegramDaemonRunningDetailed({ settings, cwd, sessionId: id })) === "blocked_identity"
+		return (await ensureTelegramDaemonRunningDetailed({
+			settings,
+			cwd,
+			sessionId: id,
+			onRegistered: registration => onRegistered?.(registration.token),
+		})) === "blocked_identity"
 			? "blocked_identity"
 			: "ready";
 	}
@@ -2888,9 +2904,10 @@ export function createNotificationsExtension(
 		cfg: NotificationConfig,
 		cwd: string,
 		id: string,
+		onRegistered?: (registrationToken: string) => void,
 	): Promise<boolean> {
 		if (isTelegramConfigured(cfg)) {
-			if ((await ensureTelegramOwner(settings, cwd, id)) === "blocked_identity") return false;
+			if ((await ensureTelegramOwner(settings, cwd, id, onRegistered)) === "blocked_identity") return false;
 		}
 		await ensureConfiguredProviderDaemons(settings, cfg, options.ensureProviderDaemon);
 		return true;
@@ -3040,6 +3057,20 @@ export function createNotificationsExtension(
 			hostStopped: rt.hostStopped && rt.serverStopped,
 			brokerRegistrationReleased: rt.brokerRegistrationReleased,
 		});
+		if (rt.notificationRootRegistration) {
+			try {
+				await unregisterNotificationRoot({
+					settings: rt.notificationRootRegistration.settings,
+					cwd: rt.notificationRootRegistration.cwd,
+					sessionId: id,
+					registrationToken: rt.notificationRootRegistration.registrationToken,
+				});
+				rt.notificationRootRegistration = undefined;
+			} catch (e) {
+				ownerReleaseFailures.push(e);
+				logger.warn(`notifications: Telegram root unregister failed: ${String(e)}`);
+			}
+		}
 		if (ownerReleaseFailures.length > 0) {
 			cleanupRetries.set(id, rt);
 			throw new AggregateError(ownerReleaseFailures, `SDK notification runtime ${id} owner release failed.`);
@@ -3641,6 +3672,7 @@ export function createNotificationsExtension(
 			inFlightTools: new Map<string, { toolName: string; args: unknown }>(),
 			deferredGatePresentations: [],
 			deferredInboundControls: [],
+			notificationRootRegistration: undefined,
 		};
 		const initializedRuntime = runtime;
 		runtimes.set(id, initializedRuntime);
@@ -4130,12 +4162,19 @@ export function createNotificationsExtension(
 			}
 			if (notificationsEnabledForSession && settingsAvailable && settings) {
 				try {
-					if (!(await ensureConfiguredDaemonOwners(settings, cfg, ctx.cwd, id))) {
+					let registrationToken: string | undefined;
+					if (
+						!(await ensureConfiguredDaemonOwners(settings, cfg, ctx.cwd, id, token => {
+							registrationToken = token;
+						}))
+					) {
 						const result = failLifecycleStartup("failed", "Telegram daemon ownership is blocked.");
 						finishStartup(result);
 						await cleanupAbandonedStartup();
 						return result;
 					}
+					if (isTelegramConfigured(cfg))
+						runtime.notificationRootRegistration = { settings, cwd: ctx.cwd, registrationToken };
 				} catch (error) {
 					const result = failLifecycleStartup("failed", error);
 					finishStartup(result);
@@ -4434,7 +4473,23 @@ export function createNotificationsExtension(
 			const { settings, settingsAvailable } = resolveSettings(options.settings);
 			if (!settingsAvailable || !settings) return "blocked_identity";
 			try {
-				return await ensureTelegramOwner(settings, binding.cwd, binding.sessionId);
+				let registrationToken: string | undefined;
+				const result = await ensureTelegramOwner(settings, binding.cwd, binding.sessionId, token => {
+					registrationToken = token;
+				});
+				const runtime = runtimes.get(binding.sessionId);
+				const configured = isTelegramConfigured(resolveSettings(options.settings).cfg);
+				if (result === "ready" && runtime && !runtime.stopping && configured) {
+					runtime.notificationRootRegistration = { settings, cwd: binding.cwd, registrationToken };
+				} else if (registrationToken !== undefined) {
+					await unregisterNotificationRoot({
+						settings,
+						cwd: binding.cwd,
+						sessionId: binding.sessionId,
+						registrationToken,
+					});
+				}
+				return result;
 			} catch {
 				return "failed";
 			}

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";
@@ -578,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,
@@ -600,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({

package/src/sdk/bus/operator-runtime.ts

@@ -74,7 +74,7 @@ export class NotificationOperatorRuntime {
 	#stopRequested = false;
 	#activeAbort: AbortController | undefined;
 	#intervals = new Map<string, OperatorIntervalHandle>();
-	#exclusive = new Set<string>();
+	#exclusive = new Map<string, Promise<void>>();
 
 	#deps: NotificationOperatorTimerDeps;
 
@@ -130,7 +130,7 @@ export class NotificationOperatorRuntime {
 
 	stopInterval(name: string): void {
 		const timer = this.#intervals.get(name);
-		if (!timer) return;
+		if (timer === undefined) return;
 		const clearIntervalImpl = this.#deps.clearIntervalImpl ?? clearInterval;
 		clearIntervalImpl(timer);
 		this.#intervals.delete(name);
@@ -142,14 +142,40 @@ export class NotificationOperatorRuntime {
 
 	async runExclusive(name: string, fn: () => Promise<void>): Promise<void> {
 		if (this.#exclusive.has(name)) return;
-		this.#exclusive.add(name);
+		const completion = Promise.withResolvers<void>();
+		this.#exclusive.set(name, completion.promise);
 		try {
-			await fn();
+			try {
+				void fn().then(completion.resolve, completion.reject);
+			} catch (error) {
+				completion.reject(error);
+			}
+			await completion.promise;
 		} finally {
-			this.#exclusive.delete(name);
+			if (this.#exclusive.get(name) === completion.promise) this.#exclusive.delete(name);
 		}
 	}
 
+	async joinExclusive(name: string, timeoutMs: number): Promise<boolean> {
+		const completion = this.#exclusive.get(name);
+		if (!completion) return true;
+		const setTimeoutImpl = this.#deps.setTimeoutImpl ?? setTimeout;
+		const clearTimeoutImpl = this.#deps.clearTimeoutImpl ?? clearTimeout;
+		const { promise, resolve } = Promise.withResolvers<boolean>();
+		const timer = setTimeoutImpl(() => resolve(false), timeoutMs);
+		void completion.then(
+			() => {
+				clearTimeoutImpl(timer);
+				resolve(true);
+			},
+			() => {
+				clearTimeoutImpl(timer);
+				resolve(true);
+			},
+		);
+		return await promise;
+	}
+
 	sleep(ms: number, signal?: AbortSignal): Promise<void> {
 		return new Promise<void>(resolve => {
 			if (signal?.aborted) return resolve();

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

@@ -21,7 +21,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { getAgentDir } from "@gajae-code/utils";
 import { tokenFingerprint } from "./config";
-import { type DaemonState, daemonPaths, isFreshLiveOwner } from "./telegram-daemon";
+import { isFreshLiveOwner, readOwnerFreshnessSnapshot } from "./telegram-daemon";
 import { runTelegramReferenceClient } from "./telegram-reference";
 
 interface CliArgs {
@@ -134,17 +134,9 @@ function pidAlive(pid: number): boolean {
 	}
 }
 
-function readDaemonState(): DaemonState | undefined {
-	try {
-		const raw = fs.readFileSync(daemonPaths(getAgentDir()).state, "utf8");
-		return JSON.parse(raw) as DaemonState;
-	} catch {
-		return undefined;
-	}
-}
-
-function activeDaemonOwnsToken(input: { botToken: string; chatId: string }): boolean {
-	const state = readDaemonState();
+async function activeDaemonOwnsToken(input: { botToken: string; chatId: string }): Promise<boolean> {
+	const snapshot = await readOwnerFreshnessSnapshot({ settings: { getAgentDir } as never });
+	const state = snapshot.state;
 	if (!state) return false;
 	return isFreshLiveOwner({
 		state,
@@ -152,6 +144,7 @@ function activeDaemonOwnsToken(input: { botToken: string; chatId: string }): boo
 		tokenFingerprint: tokenFingerprint(input.botToken),
 		chatId: input.chatId,
 		pidAlive,
+		effectiveHeartbeatAt: snapshot.effectiveHeartbeatAt,
 	});
 }
 
@@ -176,7 +169,7 @@ async function main(): Promise<void> {
 	}
 
 	const chatId = args.chatId ?? process.env.GJC_TG_CHAT_ID ?? (await resolveChatId(botToken, apiBase));
-	if (!args.force && activeDaemonOwnsToken({ botToken, chatId })) {
+	if (!args.force && (await activeDaemonOwnsToken({ botToken, chatId }))) {
 		process.stderr.write(
 			"an active gjc notifications daemon already owns this bot token; running a second poller will cause Telegram 409 conflicts. Re-run with --force to override.\n",
 		);

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

@@ -14,6 +14,7 @@ import { daemonPaths, HEARTBEAT_TTL_MS } from "./daemon-paths";
 import {
 	type DaemonState,
 	readDaemonState,
+	readOwnerFreshnessSnapshot,
 	type TelegramDaemonOptions,
 	TelegramNotificationDaemon,
 } from "./telegram-daemon";
@@ -254,15 +255,19 @@ export async function runDaemonInternal(argv: string[], deps: RunDaemonInternalD
 		if (!watchdogActive || watchdogTickInFlight || stopRequested) return;
 		watchdogTickInFlight = true;
 		try {
-			const state = await readState(settings as Settings);
+			const snapshot = deps.readDaemonState
+				? { state: await readState(settings as Settings), effectiveHeartbeatAt: undefined }
+				: await readOwnerFreshnessSnapshot({ settings: settings as Settings });
+			const state = snapshot.state;
+			const heartbeatAt = snapshot.effectiveHeartbeatAt ?? state?.heartbeatAt;
 			if (!watchdogActive || !state) return;
 			if (state.ownerId !== ownerId) {
 				stopRequested = true;
 				daemon.requestStop("stop");
 				return;
 			}
-			if (lastHeartbeatAt === undefined || state.heartbeatAt !== lastHeartbeatAt) {
-				lastHeartbeatAt = state.heartbeatAt;
+			if (lastHeartbeatAt === undefined || heartbeatAt !== lastHeartbeatAt) {
+				lastHeartbeatAt = heartbeatAt;
 				stalledSince = now();
 				return;
 			}

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

@@ -7,12 +7,9 @@
 export const NOTIFICATION_PROTOCOL_VERSION = 3;
 
 /**
- * Operational generation the current daemon build speaks. Decoupled from
- * {@link NOTIFICATION_PROTOCOL_VERSION} (#2304): additive `tool_activity` /
- * `reasoning_summary` frames do not bump the wire protocol version, but a
- * freshly-upgraded host must still recognize an older, still-live daemon that
- * predates capability-gated frame enforcement and trigger a reload. Bump this
- * on every daemon-behavior change independent of the wire version.
+ * Guarded behavior-inventory version for the current daemon build. Bump this
+ * on every guarded daemon-behavior change independent of the wire version; it
+ * does not force a live daemon reload by itself.
  * The current development baseline already includes #2299's generation 4,
  * incarnation fencing in generation 5, owner-lock authority in generation 6,
  * identity-atomic transition markers in generation 7, stable signaling plus
@@ -40,5 +37,14 @@ export const NOTIFICATION_PROTOCOL_VERSION = 3;
  * cooldown and lazy Telegram topic lifecycle safeguards (#2956, #2960, #2984).
  * Generation 27 refreshes retained native path and process authority semantics.
  * Generation 28 rejects special files before retained native authority opens.
+ * Generation 29 adds serving-epoch compatibility, sidecar heartbeat, root GC,
+ * and Bot API cooldown structural fixes (#2956, #2960, #3048).
  */
-export const DAEMON_GENERATION = 28;
+export const DAEMON_GENERATION = 29;
+
+/**
+ * Serving-compatibility boundary for daemon lifecycle requests. Epoch 1 covers
+ * all builds published before this field existed; bump this to force serving
+ * convergence and reload of compatible live predecessors.
+ */
+export const SERVING_EPOCH = 2;

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

@@ -40,6 +40,7 @@ import {
 	readAttestedLegacyDaemonOwner,
 	readDaemonRoots,
 	readDaemonState,
+	readOwnerFreshnessSnapshot,
 	spawnTelegramDaemonOwner,
 	type TelegramDaemonDeps,
 	type TelegramDaemonFs,
@@ -224,7 +225,8 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		if (!configured) {
 			return { kind: this.kind, configured: false, health: "not_configured", runtime };
 		}
-		const state = await readDaemonState(this.settings, this.fsImpl);
+		const snapshot = await readOwnerFreshnessSnapshot({ settings: this.settings, fs: this.fsImpl });
+		const state = snapshot.state;
 		const roots = await readDaemonRoots(this.settings, this.fsImpl);
 		const health: DaemonHealth =
 			!state || state.stoppedAt !== undefined || !this.pidAlive(state.pid)
@@ -236,6 +238,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 							chatId: cfg.chatId as string,
 							pidAlive: this.pidAlive,
 							pidIncarnation: this.deps.pidIncarnation,
+							effectiveHeartbeatAt: snapshot.effectiveHeartbeatAt,
 						})
 					? "running"
 					: "stale";
@@ -246,7 +249,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 			pid: state?.pid,
 			ownerId: state?.ownerId,
 			startedAt: state?.startedAt,
-			heartbeatAt: state?.heartbeatAt,
+			heartbeatAt: snapshot.effectiveHeartbeatAt,
 			roots,
 			rootCount: roots.length,
 			runtime,
@@ -480,7 +483,8 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		const gracefulTimeoutMs = opts.gracefulTimeoutMs ?? DEFAULT_GRACEFUL_TIMEOUT_MS;
 		const killTimeoutMs = opts.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS;
 
-		const state = await readDaemonState(this.settings, this.fsImpl);
+		const ownerSnapshot = await readOwnerFreshnessSnapshot({ settings: this.settings, fs: this.fsImpl });
+		const state = ownerSnapshot.state;
 		const attestedLegacyOwner = attestedLegacyUpgrade
 			? await readAttestedLegacyDaemonOwner({
 					settings: this.settings,
@@ -501,6 +505,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 					chatId,
 					pidAlive: this.pidAlive,
 					pidIncarnation: this.deps.pidIncarnation,
+					effectiveHeartbeatAt: ownerSnapshot.effectiveHeartbeatAt,
 				}) &&
 				isSignalableMatchingOwner({
 					state,
@@ -628,7 +633,8 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		let dead = await this.waitForPidDeath(oldPid, gracefulTimeoutMs);
 		if (!dead) {
 			// Old pid still alive after the cooperative SIGTERM. Inspect current ownership.
-			const current = await readDaemonState(this.settings, this.fsImpl);
+			const currentSnapshot = await readOwnerFreshnessSnapshot({ settings: this.settings, fs: this.fsImpl });
+			const current = currentSnapshot.state;
 			const changedToLiveOwner =
 				current !== undefined &&
 				current.ownerId !== oldOwnerId &&
@@ -639,6 +645,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 					chatId,
 					pidAlive: this.pidAlive,
 					pidIncarnation: this.deps.pidIncarnation,
+					effectiveHeartbeatAt: currentSnapshot.effectiveHeartbeatAt,
 				});
 			if (changedToLiveOwner) {
 				await this.clearOwnRequest(requestId);
@@ -701,7 +708,8 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		warnings.push(...spawned.warnings);
 		const after = await this.status();
 		if (spawned.result === "attached") {
-			const attachedState = await readDaemonState(this.settings, this.fsImpl);
+			const attachedSnapshot = await readOwnerFreshnessSnapshot({ settings: this.settings, fs: this.fsImpl });
+			const attachedState = attachedSnapshot.state;
 			if (
 				!isCurrentCompatibleOwner({
 					state: attachedState,
@@ -710,6 +718,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 					chatId,
 					pidAlive: this.pidAlive,
 					pidIncarnation: this.deps.pidIncarnation,
+					effectiveHeartbeatAt: attachedSnapshot.effectiveHeartbeatAt,
 				})
 			) {
 				return this.result(