@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/sdk/broker/state-version.ts

@@ -1,11 +1,14 @@
 export const SDK_STATE_VERSION = 1;
 
 // The session-index snapshot carries its own format version, independent of the shared
-// SDK_STATE_VERSION used by discovery, the lifecycle ledger, and per-event records. Version 2
-// snapshots relax the on-disk schema to allow gaps in indexSeq (compaction drops terminal+dead
-// sessions and superseded heartbeats), so an older broker must hard-fail rather than silently
-// fall back to a truncated log. Bumping only this constant keeps the broker protocol untouched.
-export const SESSION_INDEX_SNAPSHOT_VERSION = 2;
+// SDK_STATE_VERSION used by discovery, the lifecycle ledger, and per-event records.
+// Version 2 snapshots relax the on-disk schema to allow gaps in indexSeq (compaction
+// drops terminal+dead sessions and superseded heartbeats), so an older broker must
+// hard-fail rather than silently fall back to a truncated log. Version 3 snapshots may
+// additionally carry composite-identity events (hostIncarnation, activity checkpoints,
+// session_deleted tombstones) and retention-compacted sessions; v2 (and v1) snapshots
+// remain readable. Bumping only this constant keeps the broker protocol untouched.
+export const SESSION_INDEX_SNAPSHOT_VERSION = 3;
 
 export class UnsupportedStateVersionError extends Error {
 	readonly code = "unsupported_state_version";
@@ -32,10 +35,11 @@ export function assertSupportedStateVersion(file: string, value: unknown): void
 	}
 }
 
-// Fences the session-index snapshot format independently of SDK_STATE_VERSION. An older broker
-// (whose SESSION_INDEX_SNAPSHOT_VERSION is 1) trips assertSupportedStateVersion on a version-2
-// snapshot and refuses to start; a current broker accepts both the legacy contiguous format
-// (version 1 or absent) and the gapped version-2 format.
+// Fences the session-index snapshot format independently of SDK_STATE_VERSION. An older
+// broker (whose SESSION_INDEX_SNAPSHOT_VERSION is below 3) trips assertSupportedStateVersion
+// on a version-3 snapshot and refuses to start; a current broker accepts the legacy
+// contiguous format (version 1), the gapped version-2 format, and the version-3 format
+// with composite-identity events.
 export function assertSupportedSnapshotVersion(file: string, value: unknown): void {
 	if (!value || typeof value !== "object") return;
 	const record = value as { version?: unknown; stateVersion?: unknown };

package/src/sdk/broker/transport.ts

@@ -15,6 +15,9 @@ const BROKER_OPERATIONS = new Set([
 	"session.close",
 	"session.delete",
 	"broker.shutdown",
+	"elevation.issue",
+	"elevation.status",
+	"session.control",
 ]);
 type RequestInput = Record<string, unknown>;
 type BrokerRequest = {
@@ -23,6 +26,7 @@ type BrokerRequest = {
 	operation?: string;
 	input?: RequestInput;
 	idempotencyKey?: string;
+	elevationRequestId?: string;
 };
 function digest(value: string): Buffer {
 	return createHash("sha256").update(value).digest();
@@ -134,6 +138,10 @@ export class BrokerTransport {
 			sendError(socket, frame.id, "invalid_input", "idempotencyKey must be a string");
 			return;
 		}
+		if (frame.elevationRequestId !== undefined && typeof frame.elevationRequestId !== "string") {
+			sendError(socket, frame.id, "invalid_input", "elevationRequestId must be a string");
+			return;
+		}
 		if (frame.operation === "broker.shutdown") {
 			const action = brokerShutdownSendAction(
 				send(socket, { type: "broker_response", id: frame.id, ok: true, result: { accepted: true } }),
@@ -145,7 +153,12 @@ export class BrokerTransport {
 			return;
 		}
 		try {
-			const result = await this.#broker.handleRequest(frame.operation, frame.input, frame.idempotencyKey);
+			const result = await this.#broker.handleRequest(
+				frame.operation,
+				frame.input,
+				frame.idempotencyKey,
+				frame.elevationRequestId,
+			);
 			send(socket, { type: "broker_response", id: frame.id, ...result });
 		} catch {
 			sendError(socket, frame.id, "unavailable", "broker request failed");

package/src/sdk/bus/index.ts

@@ -24,6 +24,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { execFile } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { promisify } from "node:util";
@@ -81,9 +82,11 @@ import {
 import { acpFinalTextFromMessage } from "../acp/final-text";
 import { ensureBroker } from "../broker/ensure";
 import { publishSessionHostRuntimeEvidence, type SessionHostRuntimePublication } from "../broker/lifecycle";
+import { processIncarnation } from "../broker/process-incarnation";
 import { SessionIndex } from "../broker/session-index";
+import { elevationAuthorityPath, verifyElevationCapability } from "../elevation/capability";
 import { createSdkSurfaceFactory, type SessionSdkHost, SessionSdkSessionRuntime, shouldHostSdk } from "../host";
-import { type ControlSurface, dispatchControl } from "../host/control";
+import { type ControlSurface, controlRequestFromFrame, dispatchControl } from "../host/control";
 import { CursorRegistry, QueryHandlers, RevisionStore, type SessionSurface } from "../host/query";
 import type { SdkFrame } from "../host/types";
 import {
@@ -2384,6 +2387,7 @@ function sdkControlSurface(
 	settings?: Settings,
 	configOverrides: Map<string, unknown> = new Map(),
 	configRevision: { current: number } = { current: 0 },
+	elevationAuthorityToken?: string,
 	abortOwnedPrompt: (
 		connectionId: string | undefined,
 	) => Promise<{ aborted: true; disposition: "cancelled" | "already_terminal" | "idle" }> = async () => ({
@@ -2683,6 +2687,9 @@ function sdkControlSurface(
 		cancelPendingPreflights(): void;
 		cancelPendingPreflightsForConnection(connectionId: string): void;
 	} = {
+		authorizeElevationClaim: (sdkId, input, capability) =>
+			elevationAuthorityToken !== undefined &&
+			verifyElevationCapability(elevationAuthorityToken, capability, sdkId, input),
 		prompt: (text, images, clientRef) =>
 			submitPrompt(text, images, false, undefined, true, controlRequesterContext.getStore(), clientRef, true),
 		steer: text => sendSteer(text),
@@ -2717,7 +2724,7 @@ function sdkControlSurface(
 			pending.completeDirect();
 			return { resolved: true };
 		},
-		answerGate: async (id, response, expectedSessionId, idempotencyKey) => {
+		answerGate: async (id, response, expectedSessionId, idempotencyKey, _elevationRequestId) => {
 			if (!acceptGateResolution())
 				throw Object.assign(new Error("Workflow gate is no longer answerable."), { code: "resource_gone" });
 			if (expectedSessionId === undefined) auditMissingExpectedSessionId("workflow.gate_answer");
@@ -2792,7 +2799,7 @@ function sdkControlSurface(
 				code: "terminal_uncertain",
 			});
 		},
-		approvePlan: async (id, choice, expectedSessionId) => {
+		approvePlan: async (id, choice, expectedSessionId, _elevationRequestId) => {
 			if (!acceptGateResolution())
 				throw Object.assign(new Error("Workflow plan is no longer answerable."), { code: "resource_gone" });
 			if (expectedSessionId === undefined) auditMissingExpectedSessionId("workflow.plan_approve");
@@ -3917,6 +3924,11 @@ export function createNotificationsExtension(
 		// build information and required capability while lifecycle startup can settle
 		// a structured failure instead of leaving the lifecycle caller pending.
 		const token = resolveToken();
+		const elevationAuthorityToken = crypto.randomBytes(32).toString("base64url");
+		const elevationAuthorityFile = elevationAuthorityPath(endpointStateRoot, id);
+		await fsPromises.mkdir(path.dirname(elevationAuthorityFile), { recursive: true, mode: 0o700 });
+		await Bun.write(elevationAuthorityFile, `${JSON.stringify({ version: 1, token: elevationAuthorityToken })}\n`);
+		await fsPromises.chmod(elevationAuthorityFile, 0o600);
 		let server: NotificationServer;
 		try {
 			const { NotificationServer, nativeBuildInfo } = sdkBusNatives();
@@ -4599,6 +4611,7 @@ export function createNotificationsExtension(
 			settings,
 			configOverrides,
 			configRevision,
+			elevationAuthorityToken,
 			async connectionId => {
 				const active = [...promptSubmissions.entries()].find(
 					([, submission]) => submission.connectionId === connectionId && !submission.terminal,
@@ -4882,15 +4895,7 @@ export function createNotificationsExtension(
 					dispatchControl(
 						controlSurface,
 						OPERATIONS.find(row => row.kind === "control" && row.sdkId === operation),
-						{
-							id: requestId,
-							operation,
-							input: request.input,
-							expectedRevision:
-								typeof request.expectedRevision === "string" ? request.expectedRevision : undefined,
-							idempotencyKey: typeof request.idempotencyKey === "string" ? request.idempotencyKey : undefined,
-							confirm: request.confirm === true,
-						},
+						controlRequestFromFrame(request as Record<string, unknown>),
 					),
 				);
 
@@ -4902,6 +4907,16 @@ export function createNotificationsExtension(
 			},
 			query: async (connectionId, frame) => {
 				const request = frame as { id?: unknown; query?: unknown; input?: unknown; cursor?: unknown };
+				// D1: a non-string top-level cursor is rejected, never silently
+				// dropped into a fresh-snapshot query (parity with the loopback
+				// session-runtime adapter).
+				if (request.cursor !== undefined && typeof request.cursor !== "string")
+					return {
+						type: "query_response",
+						id: typeof request.id === "string" ? request.id : undefined,
+						ok: false,
+						error: { code: "invalid_input", message: "cursor must be a non-empty string" },
+					};
 				const response = await queryHandlers.dispatch({
 					id: typeof request.id === "string" ? request.id : undefined,
 					query: typeof request.query === "string" ? request.query : "",
@@ -5608,6 +5623,7 @@ export function createNotificationsExtension(
 					throwIfLifecycleStopped();
 					const locator = { repo: path.resolve(ctx.cwd), stateRoot: endpointStateRoot };
 					const endpointMtimeMs = fs.statSync(path.join(endpointStateRoot, "sdk", `${id}.json`)).mtimeMs;
+					const hostProcessIncarnation = processIncarnation(process.pid);
 					await host.registerWithBroker({
 						// The endpoint is written before registration. Its exact mtime
 						// binds this index generation to that discovery record.
@@ -5617,6 +5633,11 @@ export function createNotificationsExtension(
 								...input,
 								locator,
 								pid: process.pid,
+								// A pid alone cannot survive its own reuse, and the marker that
+								// binds it lives in the workspace state root this host can outlive.
+								// Publishing the incarnation into broker-owned storage is what keeps
+								// teardown identity provable after that workspace is gone.
+								...(hostProcessIncarnation ? { processIncarnation: hostProcessIncarnation } : {}),
 								endpointMtimeMs,
 								...(lifecycleRequestId ? { lifecycleRequestId } : {}),
 							});
@@ -5810,7 +5831,7 @@ export function createNotificationsExtension(
 			logger.warn(`notifications: failed to start server: ${String(e)}`);
 			const result = failLifecycleStartup("failed", e);
 			finishStartup(result);
-			let suppressExtensionError = false;
+			let suppressExtensionError = result.failure?.message === "Lifecycle SDK startup was cancelled.";
 			let stopped = false;
 			try {
 				stopped = await stopSession(id, "session", runtime);

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

@@ -195,7 +195,21 @@ export function createKindAwareReconciliation(
 		if (!correlation) return;
 		await queueMutation(candidate => {
 			const record = candidate.get(keyOf(kind, correlation));
-			if (!record || record.terminalAt !== undefined) return { value: undefined, changed: false };
+			if (!record) return { value: undefined, changed: false };
+			if (record.terminalAt !== undefined) {
+				// The terminal is claimed by one delivery path while the reason arrives on
+				// another, so ordering is not the caller's to control. A late agent_failed
+				// enriches the settled record instead of being dropped; it must not resurrect
+				// it, so status, terminalAt, retention order, and the clientRef index stay
+				// as-is (cleanupRecords is intentionally not re-run). First reason wins: a
+				// late generic frame never overwrites a specific one. Persisted so the reason
+				// survives reconnect/restart reconciliation.
+				if (frame.type === "agent_failed" && record.error === undefined) {
+					record.error = sanitizePromptFailure(frame.error);
+					return { value: undefined, changed: true };
+				}
+				return { value: undefined, changed: false };
+			}
 			if (frame.type === "agent_start") {
 				if (record.status !== "accepted") return { value: undefined, changed: false };
 				record.status = "in_flight";
@@ -278,7 +292,12 @@ export function createKindAwareReconciliation(
 			terminalAt: record.terminalAt as number,
 			...(record.outcome !== undefined ? { outcome: record.outcome } : {}),
 		};
-		if (record.status === "terminal_ok") return { status: "terminal_ok", ...terminal };
+		if (record.status === "terminal_ok")
+			return {
+				status: "terminal_ok",
+				...terminal,
+				...(record.error !== undefined ? { error: record.error } : {}),
+			};
 		return { status: "failed", ...terminal, error: record.error ?? sanitizePromptFailure(undefined) };
 	};
 

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

@@ -602,6 +602,13 @@ export interface DaemonHealth {
 	stopped: boolean;
 	heartbeatAt: number | undefined;
 	heartbeatAgeMs: number | undefined;
+
+	/**
+	 * Session endpoints the live owner reported an OPEN socket to in its latest
+	 * matching heartbeat sidecar. `undefined` means the owner never published the
+	 * field (older daemon, no stable owner tag, no matching sidecar): unknown, not zero.
+	 */
+	attachedEndpoints: number | undefined;
 	generation: number | undefined;
 	currentGeneration: number;
 	generationRelation: DaemonGenerationRelation;
@@ -822,7 +829,13 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		});
 	} catch {
 		daemonStateUnreadable = true;
-		snapshot = { ownerTag: null, effectiveHeartbeatAt: undefined, legacyEmbedded: false, state: undefined };
+		snapshot = {
+			ownerTag: null,
+			effectiveHeartbeatAt: undefined,
+			legacyEmbedded: false,
+			attachedEndpoints: undefined,
+			state: undefined,
+		};
 	}
 	const state = snapshot.state ? parseDaemonState(JSON.stringify(snapshot.state)) : undefined;
 	const heartbeatAt = finiteNonNegativeNumber(snapshot.effectiveHeartbeatAt);
@@ -840,6 +853,7 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 		stopped: state?.stoppedAt !== undefined,
 		heartbeatAt,
 		heartbeatAgeMs: heartbeatAt === undefined ? undefined : displayHeartbeatAgeMs(now, heartbeatAt),
+		attachedEndpoints: snapshot.attachedEndpoints,
 		generation: state?.generation,
 		currentGeneration: DAEMON_GENERATION,
 		generationRelation: daemonGenerationRelation(state),
@@ -863,6 +877,19 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 				level: "warn",
 				detail: "a live daemon owns a different bot token or chat id",
 			});
+		} else if (telegramConfigured && !daemon.stopped && daemon.generationRelation !== "current") {
+			// Liveness is not serviceability. `isCurrentCompatibleOwner` refuses to attach
+			// a session to an owner whose generation is not this build's, and
+			// `acquireDaemonOwnership` then answers `provisional`, which `ensureTelegramDaemonRunning`
+			// reports as `blocked_identity`: no transport is ever attached and no
+			// notification is ever published, while the owner keeps heartbeating. Reporting
+			// that as OK is what makes the outage invisible; the generation is inventory
+			// metadata that never forces a reload on its own, so the operator has to.
+			checks.push({
+				name: "daemon",
+				level: "warn",
+				detail: `daemon pid ${daemon.pid} serves generation ${daemon.generation ?? "unknown"} but this build attaches only to generation ${daemon.currentGeneration}; it cannot attach a session transport — run \`gjc daemon reload\``,
+			});
 		} else {
 			checks.push({ name: "daemon", level: "ok", detail: `daemon pid ${daemon.pid} alive with a fresh heartbeat` });
 		}
@@ -931,6 +958,25 @@ export async function checkNotificationHealth(opts: HealthOptions): Promise<Noti
 					"No local notification endpoint for this working directory. In this GJC terminal run /notify on; if it does not report notifications enabled, start a new local GJC session. Do not re-pair Telegram.",
 			});
 		}
+		// Endpoint files are registrations, not deliveries: a live owner that
+		// reports zero OPEN sockets cannot deliver to any of them. An owner that
+		// never published a count is unknown, and unknown is never treated as zero.
+		if (
+			telegramConfigured &&
+			daemon.present &&
+			daemon.alive &&
+			daemon.heartbeatFresh &&
+			daemon.identityMatches &&
+			!daemon.stopped &&
+			endpoints.total > 0 &&
+			daemon.attachedEndpoints === 0
+		) {
+			checks.push({
+				name: "endpoint_attachment",
+				level: "warn",
+				detail: `${endpoints.total} endpoint file(s) registered but daemon pid ${daemon.pid} reports 0 attached session(s); the daemon cannot deliver to any registered endpoint`,
+			});
+		}
 	}
 
 	// Optional selected REST-only reachability probe.

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

@@ -16,7 +16,9 @@
  *   Session-scoped durable retention (kind-aware store) is provided by reconciliation-store.ts (#3032).
  * - The clientRef index is session-runtime scoped; a ref conflicts only while
  *   retained and must never be reused as a retry mechanism.
- * - Terminal transitions settle once: the first terminal outcome wins.
+ * - Terminal transitions settle once: first terminal outcome wins. A late
+ *   `agent_failed` may still attach its sanitized reason to an already-terminal
+ *   record that has none, but never changes status, terminalAt, or retention.
  */
 
 import { PROMPT_FAILURE_CODE_MAX, sanitizePromptFailure } from "../prompt-failure";
@@ -67,6 +69,8 @@ export type TurnPromptReconciliation =
 			acceptedAt: number;
 			startedAt?: number;
 			terminalAt: number;
+			/** Present when a late `agent_failed` supplied the only failure reason. */
+			error?: { code: string; message: string };
 	  }
 	| {
 			status: "failed";
@@ -184,7 +188,17 @@ export function createPromptReconciliation(options: { now?: () => number } = {})
 	) => {
 		if (!correlation) return;
 		const record = records.get(keyOf(correlation));
-		if (!record || record.terminalAt !== undefined) return;
+		if (!record) return;
+		if (record.terminalAt !== undefined) {
+			// The terminal is claimed by one path while the reason arrives on another,
+			// so ordering is not the caller's to control. A late agent_failed enriches
+			// the settled record instead of being dropped; it must not resurrect it,
+			// so status, terminalAt, retention order, and clientRefIndex stay as-is.
+			// First reason wins: a late generic frame never overwrites a specific one.
+			if (frame.type === "agent_failed" && record.error === undefined)
+				record.error = sanitizePromptFailure(frame.error);
+			return;
+		}
 		if (frame.type === "agent_start") {
 			if (record.status === "accepted") {
 				record.status = "in_flight";
@@ -227,7 +241,12 @@ export function createPromptReconciliation(options: { now?: () => number } = {})
 			...(record.startedAt !== undefined ? { startedAt: record.startedAt } : {}),
 			terminalAt: record.terminalAt as number,
 		};
-		if (record.status === "terminal_ok") return { status: "terminal_ok", ...terminal };
+		if (record.status === "terminal_ok")
+			return {
+				status: "terminal_ok",
+				...terminal,
+				...(record.error !== undefined ? { error: record.error } : {}),
+			};
 		return { status: "failed", ...terminal, error: record.error ?? sanitizePromptFailure(undefined) };
 	};
 

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

@@ -93,8 +93,11 @@ export const NOTIFICATION_PROTOCOL_VERSION = 3;
  * later session from creating a topic or replaying notifications. Generation
  * 58 preserves that invariant during durable-fence load promotion and restores
  * the exact grace deadline when a failed archive publication rolls back.
+ * Generation 59 publishes the owner's attached OPEN-socket count in the
+ * heartbeat sidecar so `gjc notify health` can report a live daemon that is
+ * attached to no registered endpoint (#4128).
  */
-export const DAEMON_GENERATION = 58;
+export const DAEMON_GENERATION = 59;
 
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 5

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

@@ -1217,8 +1217,19 @@ type OwnerHeartbeatSidecar = {
 	ownerId: string;
 	acquisitionId: string;
 	heartbeatAt: number;
+	/**
+	 * Session endpoints this owner had an OPEN WebSocket to when the heartbeat was
+	 * published. Optional: a sidecar written by an older daemon omits it and must
+	 * read back as unknown, never as zero.
+	 */
+	attachedEndpoints?: number;
 };
 
+/** Attachment counts are advisory observations, so only safe non-negative integers are published or trusted. */
+function validAttachedEndpointCount(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
 function ownerTagFromState(
 	state: DaemonState | undefined,
 ): Pick<OwnerHeartbeatSidecar, "pid" | "incarnation" | "ownerId" | "acquisitionId"> | undefined {
@@ -1250,6 +1261,7 @@ function sidecarMatchesOwnerTag(
 			typeof sidecar.ownerId === "string" &&
 			typeof sidecar.acquisitionId === "string" &&
 			Number.isSafeInteger(sidecar.heartbeatAt) &&
+			(sidecar.attachedEndpoints === undefined || validAttachedEndpointCount(sidecar.attachedEndpoints)) &&
 			sidecar.pid === tag.pid &&
 			sidecar.incarnation === tag.incarnation &&
 			sidecar.ownerId === tag.ownerId &&
@@ -1277,6 +1289,12 @@ export interface OwnerFreshnessSnapshot {
 	ownerTag: Pick<OwnerHeartbeatSidecar, "pid" | "incarnation" | "ownerId" | "acquisitionId"> | null;
 	effectiveHeartbeatAt: number | undefined;
 	legacyEmbedded: boolean;
+	/**
+	 * Session endpoints the current owner reported as attached in its latest matching
+	 * heartbeat sidecar. `undefined` means the owner never published the field (older
+	 * daemon, no stable owner tag, or no matching sidecar) — that is unknown, not zero.
+	 */
+	attachedEndpoints: number | undefined;
 	state: DaemonState | undefined;
 }
 
@@ -1293,7 +1311,14 @@ export async function readOwnerFreshnessSnapshot(input: {
 	const tag = ownerTagFromState(state);
 	const lock = await readOwnershipLock(fsImpl, paths.lock);
 	const ownerTag = tag && ownershipLockMatchesState(lock, state) ? tag : null;
-	if (legacyEmbedded) return { ownerTag, effectiveHeartbeatAt: state?.heartbeatAt, legacyEmbedded, state };
+	if (legacyEmbedded)
+		return {
+			ownerTag,
+			effectiveHeartbeatAt: state?.heartbeatAt,
+			legacyEmbedded,
+			attachedEndpoints: undefined,
+			state,
+		};
 	const sidecar = await readSidecarLenient(fsImpl, paths.heartbeat);
 	const rereadState = await readJson<DaemonState>(fsImpl, paths.state);
 	const rereadLock = await readOwnershipLock(fsImpl, paths.lock);
@@ -1301,15 +1326,20 @@ export async function readOwnerFreshnessSnapshot(input: {
 	const stableTag = rereadTag && ownershipLockMatchesState(rereadLock, rereadState) ? rereadTag : null;
 	const stable =
 		ownerTag && stableTag && sidecarMatchesOwnerTag({ ...ownerTag, heartbeatAt: 0 }, stableTag) ? stableTag : null;
+	const matchingSidecar = stable && sidecarMatchesOwnerTag(sidecar, stable) ? sidecar : undefined;
 	const effectiveHeartbeatAt = stable
-		? sidecarMatchesOwnerTag(sidecar, stable)
-			? Math.max(rereadState?.heartbeatAt ?? 0, sidecar.heartbeatAt)
+		? matchingSidecar
+			? Math.max(rereadState?.heartbeatAt ?? 0, matchingSidecar.heartbeatAt)
 			: rereadState?.heartbeatAt
 		: undefined;
+	const attachedEndpoints = validAttachedEndpointCount(matchingSidecar?.attachedEndpoints)
+		? matchingSidecar.attachedEndpoints
+		: undefined;
 	return {
 		ownerTag: stable,
 		effectiveHeartbeatAt,
 		legacyEmbedded: false,
+		attachedEndpoints,
 		state: rereadState,
 	};
 }
@@ -1323,6 +1353,12 @@ export async function renewOwnerHeartbeatSidecar(input: {
 	now?: () => number;
 	pid?: number;
 	pidIncarnation?: (pid: number) => string | undefined;
+	/**
+	 * Session endpoints the caller currently holds an OPEN WebSocket to. Omitted by
+	 * non-daemon callers (bootstrap/proof paths) so their sidecar reports unknown
+	 * rather than falsely claiming zero attachments.
+	 */
+	attachedEndpoints?: number;
 }): Promise<boolean> {
 	const fsImpl = input.fs ?? nodeFs;
 	const paths = daemonPaths(input.settings.getAgentDir());
@@ -1347,6 +1383,7 @@ export async function renewOwnerHeartbeatSidecar(input: {
 		ownerId: input.ownerId,
 		acquisitionId,
 		heartbeatAt: (input.now ?? Date.now)(),
+		...(validAttachedEndpointCount(input.attachedEndpoints) ? { attachedEndpoints: input.attachedEndpoints } : {}),
 	};
 	const tmp = `${paths.heartbeat}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
 	await fsImpl.writeFile(tmp, `${JSON.stringify(sidecar, null, 2)}\n`, { mode: 0o600 });
@@ -9665,6 +9702,18 @@ export class TelegramNotificationDaemon {
 	private stopFlushTimer(): void {
 		this.runtime.stopInterval("telegram-flush");
 	}
+	/**
+	 * Sessions this owner can actually deliver to right now. Only `WebSocket.OPEN`
+	 * counts: a CONNECTING socket is constructed but cannot carry a frame, and
+	 * CLOSING/CLOSED ones are gone. Every delivery path in this daemon refuses to
+	 * send unless `readyState === WebSocket.OPEN`, so OPEN is exactly the state
+	 * that means a notification can leave this process for that session.
+	 */
+	private attachedEndpointCount(): number {
+		let attached = 0;
+		for (const session of this.sessions.values()) if (session.ws.readyState === WebSocket.OPEN) attached += 1;
+		return attached;
+	}
 	private async renewOwnershipHeartbeat(): Promise<boolean> {
 		return renewOwnerHeartbeatSidecar({
 			settings: this.opts.settings,
@@ -9674,6 +9723,7 @@ export class TelegramNotificationDaemon {
 			now: this.opts.now,
 			pid: this.opts.pid ?? process.pid,
 			pidIncarnation: this.opts.pidIncarnation,
+			attachedEndpoints: this.attachedEndpointCount(),
 		});
 	}
 
@@ -12347,6 +12397,7 @@ export class TelegramNotificationDaemon {
 						now: this.opts.now,
 						pid: this.opts.pid ?? process.pid,
 						pidIncarnation: this.opts.pidIncarnation,
+						attachedEndpoints: this.attachedEndpointCount(),
 					}))
 				)
 					break;