@gajae-code/coding-agent 0.7.3 → 0.7.5

package/src/notifications/telegram-daemon.ts

@@ -10,9 +10,32 @@ import type { DaemonRuntimeInfo } from "../daemon/control-types";
 import { resolveGjcRuntimeSpawnInfo } from "../daemon/runtime";
 import { getNotificationConfig, isGloballyConfigured, tokenFingerprint } from "./config";
 import { parseInThreadConfigCommand } from "./config-commands";
-import { buildButtonGrid, TELEGRAM_PARSE_MODE } from "./html-format";
+import { buildCompactChoiceGrid, TELEGRAM_PARSE_MODE } from "./html-format";
+import type {
+	SessionCloseTarget,
+	SessionCreateTarget,
+	SessionLifecycleRequest,
+	SessionLifecycleResponse,
+	SessionResumeTarget,
+} from "./index";
+import {
+	formatLifecycleOutcome,
+	isLifecycleCommandText,
+	lifecycleUsage,
+	parseLifecycleCommand,
+	validateLifecycleTarget,
+} from "./lifecycle-commands";
+import {
+	attachLifecycleControl,
+	buildOrchestratorDeps,
+	type ControlServerLike,
+	createNativeControlServer,
+	type LifecycleControlServer,
+	type LifecycleControlServerFactory,
+} from "./lifecycle-control-runtime";
 import { NotificationOperatorRuntime, OperatorBackoffPolicy, OperatorEventRouter } from "./operator-runtime";
 import { RateLimitPool } from "./rate-limit-pool";
+import { listRecentSessions } from "./recent-activity";
 import {
 	type AliasTable,
 	buildActionMessage,
@@ -173,6 +196,31 @@ export function daemonPaths(agentDir: string): DaemonPaths {
 	};
 }
 
+/**
+ * Attach session-lifecycle control (create/close/resume) to the running daemon.
+ *
+ * Wires an already-started, authenticated control server to the lifecycle
+ * orchestrator with real daemon-side effects (tmux launcher / force-close /
+ * resume), a durable fsynced idempotency ledger + audit JSONL under the agent
+ * notifications dir, and strict paired-chat gating. The control server itself
+ * (NotificationControlServer) is owned/started by the daemon process; this
+ * function only connects it to policy. Returns the orchestrator deps for tests.
+ */
+export function startDaemonLifecycleControl(input: {
+	controlServer: ControlServerLike;
+	pairedChatId: string;
+	agentDir: string;
+	env?: NodeJS.ProcessEnv;
+}): void {
+	const deps = buildOrchestratorDeps({
+		pairedChatId: input.pairedChatId,
+		agentNotificationsDir: daemonPaths(input.agentDir).dir,
+		sessionsRoot: path.join(input.agentDir, "sessions"),
+		env: input.env,
+	});
+	attachLifecycleControl(input.controlServer, deps);
+}
+
 async function ensureDir(fsImpl: TelegramDaemonFs, dir: string): Promise<void> {
 	await fsImpl.mkdir(dir, { recursive: true, mode: 0o700 });
 	await fsImpl.chmod(dir, 0o700).catch(() => undefined);
@@ -706,8 +754,17 @@ export interface TelegramDaemonOptions {
 	idleTimeoutMs?: number;
 	scanIntervalMs?: number;
 	pid?: number;
+	/** Liveness probe for skipping dead-PID endpoint records in {@link TelegramNotificationDaemon.scanRoots}. */
+	pidAlive?: (pid: number) => boolean;
 	botApi?: BotApi;
 	control?: DaemonControlHooks;
+	/**
+	 * Factory for the session-lifecycle control server. Defaults to the real
+	 * native NotificationControlServer; tests inject a fake to verify the
+	 * owner-bound start/stop lifecycle without a socket. When `undefined` AND no
+	 * default applies (e.g. lifecycle control disabled), no control server starts.
+	 */
+	createLifecycleControlServer?: LifecycleControlServerFactory | null;
 }
 
 interface SessionSocket {
@@ -763,6 +820,25 @@ export class TelegramNotificationDaemon {
 	private get inboundReactions(): Map<number, { messageId: number }> {
 		return this.dispatchState.inboundReactions;
 	}
+	/**
+	 * The owner-bound session-lifecycle control server (create/close/resume).
+	 * Started in {@link run} after ownership is confirmed (so exactly one owner
+	 * ever runs one), stopped in run()'s finally on any exit path.
+	 */
+	private controlServer: LifecycleControlServer | undefined;
+	/** True while lifecycle control is active, so the loop keeps polling at idle. */
+	private lifecycleControlActive = false;
+	/** Control token (in-memory) the loopback client presents; never persisted/logged. */
+	private controlToken: string | undefined;
+	/** Loopback WS client to the daemon's own control endpoint (Option A real wire path). */
+	private controlClient: WebSocket | undefined;
+	/** Pending lifecycle responses awaiting a control-endpoint reply, by requestId. */
+	private readonly pendingLifecycle = new Map<
+		string,
+		{ resolve: (r: SessionLifecycleResponse) => void; timer: ReturnType<typeof setTimeout> }
+	>();
+	/** Monotonic counter for unique lifecycle request ids. */
+	private lifecycleSeq = 0;
 
 	/**
 	 * Cooperatively stop the daemon: set the stop flag and abort the in-flight
@@ -774,6 +850,282 @@ export class TelegramNotificationDaemon {
 		this.running = false;
 	}
 
+	/**
+	 * Start the owner-bound lifecycle control server and wire it to the
+	 * orchestrator. Called from {@link run} ONLY after ownership is confirmed, so
+	 * exactly one owner ever starts exactly one control server (no second poller
+	 * / 409). A control-server failure degrades gracefully: the daemon keeps
+	 * serving notifications without lifecycle control. Returns true when started.
+	 */
+	private async startLifecycleControl(): Promise<boolean> {
+		const factory =
+			this.opts.createLifecycleControlServer === null
+				? undefined
+				: (this.opts.createLifecycleControlServer ?? createNativeControlServer);
+		if (!factory) return false;
+		let server: LifecycleControlServer | undefined;
+		try {
+			// High-entropy, in-memory control token (never persisted raw / logged).
+			const token = crypto.randomBytes(32).toString("base64url");
+			const agentDir = this.opts.settings.getAgentDir();
+			server = factory({ token, ownerId: this.opts.ownerId, agentDir });
+			const deps = buildOrchestratorDeps({
+				pairedChatId: this.opts.chatId,
+				agentNotificationsDir: daemonPaths(agentDir).dir,
+				sessionsRoot: path.join(agentDir, "sessions"),
+			});
+			// Register the lifecycle-request handler BEFORE start(): the native
+			// control server captures the callback at start time, so wiring must
+			// precede start or forwarded requests never reach the orchestrator.
+			attachLifecycleControl(server, deps);
+			const endpoint = (await server.start()) as { url?: string } | undefined;
+			this.controlServer = server;
+			this.controlToken = token;
+			// Option A: connect a loopback WS client to our own control endpoint so
+			// parsed /session_* commands traverse the real authenticated wire path.
+			// Mark control active ONLY after the client is open, so a first-poll
+			// /session_create never races a still-CONNECTING socket.
+			const opened = endpoint?.url ? await this.connectControlClient(endpoint.url, token) : false;
+			this.lifecycleControlActive = opened;
+			if (!opened) {
+				logger.warn("notifications: lifecycle control client did not open; lifecycle commands disabled");
+			}
+			return opened;
+		} catch (e) {
+			// Never let lifecycle-control startup kill the notifications daemon.
+			// Stop any partially-started server so it cannot leak.
+			try {
+				server?.stop();
+			} catch {
+				// best-effort
+			}
+			logger.warn(`notifications: lifecycle control failed to start: ${String(e)}`);
+			this.controlServer = undefined;
+			this.lifecycleControlActive = false;
+			return false;
+		}
+	}
+
+	/** Stop the lifecycle control server (idempotent); called from run()'s finally. */
+	private stopLifecycleControl(): void {
+		this.lifecycleControlActive = false;
+		this.controlToken = undefined;
+		const client = this.controlClient;
+		this.controlClient = undefined;
+		try {
+			client?.close();
+		} catch {
+			// best-effort
+		}
+		// Reject any in-flight lifecycle requests so callers do not hang.
+		for (const [requestId, pending] of this.pendingLifecycle) {
+			clearTimeout(pending.timer);
+			pending.resolve({
+				type: "session_lifecycle_error",
+				requestId,
+				status: "error",
+				reason: "terminal_uncertain",
+				message: "control server stopped",
+			});
+		}
+		this.pendingLifecycle.clear();
+		const server = this.controlServer;
+		this.controlServer = undefined;
+		try {
+			server?.stop();
+		} catch (e) {
+			logger.warn(`notifications: lifecycle control failed to stop cleanly: ${String(e)}`);
+		}
+	}
+
+	/**
+	 * Connect the loopback control client and resolve responses by requestId.
+	 * Resolves true once the socket is OPEN (bounded), false on error/timeout, so
+	 * the caller only marks lifecycle control active when commands can be sent.
+	 */
+	private connectControlClient(url: string, token: string): Promise<boolean> {
+		return new Promise<boolean>(resolve => {
+			let settled = false;
+			const finish = (ok: boolean) => {
+				if (settled) return;
+				settled = true;
+				resolve(ok);
+			};
+			try {
+				const WsCtor = this.opts.WebSocketImpl ?? WebSocket;
+				const client = new WsCtor(`${url}/?token=${encodeURIComponent(token)}`);
+				this.controlClient = client;
+				const openTimer = (this.opts.setTimeoutImpl ?? setTimeout)(() => finish(false), 5_000);
+				client.addEventListener("open", () => {
+					clearTimeout(openTimer);
+					finish(true);
+				});
+				client.addEventListener("error", () => {
+					clearTimeout(openTimer);
+					finish(false);
+				});
+				client.addEventListener("message", (ev: MessageEvent) => {
+					let msg: SessionLifecycleResponse;
+					try {
+						msg = JSON.parse(String((ev as { data: unknown }).data)) as SessionLifecycleResponse;
+					} catch {
+						return;
+					}
+					const requestId = (msg as { requestId?: string }).requestId;
+					if (!requestId) return;
+					const pending = this.pendingLifecycle.get(requestId);
+					if (!pending) return;
+					clearTimeout(pending.timer);
+					this.pendingLifecycle.delete(requestId);
+					pending.resolve(msg);
+				});
+			} catch (e) {
+				logger.warn(`notifications: lifecycle control client failed to connect: ${String(e)}`);
+				finish(false);
+			}
+		});
+	}
+
+	/** Send a lifecycle frame over the loopback client and await the response. */
+	private submitLifecycleFrame(frame: SessionLifecycleRequest): Promise<SessionLifecycleResponse> {
+		return new Promise<SessionLifecycleResponse>(resolve => {
+			const client = this.controlClient;
+			if (!client || client.readyState !== WebSocket.OPEN) {
+				resolve({
+					type: "session_lifecycle_error",
+					requestId: frame.requestId,
+					status: "error",
+					reason: "terminal_uncertain",
+					message: "lifecycle control unavailable",
+				});
+				return;
+			}
+			const timer = (this.opts.setTimeoutImpl ?? setTimeout)(() => {
+				this.pendingLifecycle.delete(frame.requestId);
+				resolve({
+					type: "session_lifecycle_error",
+					requestId: frame.requestId,
+					status: "error",
+					reason: "readiness_timeout",
+					message: "lifecycle request timed out",
+				});
+			}, 120_000);
+			this.pendingLifecycle.set(frame.requestId, { resolve, timer });
+			try {
+				client.send(JSON.stringify(frame));
+			} catch (e) {
+				clearTimeout(timer);
+				this.pendingLifecycle.delete(frame.requestId);
+				resolve({
+					type: "session_lifecycle_error",
+					requestId: frame.requestId,
+					status: "error",
+					reason: "terminal_uncertain",
+					message: `lifecycle send failed: ${String(e)}`,
+				});
+			}
+		});
+	}
+
+	private nextLifecycleRequestId(): string {
+		this.lifecycleSeq += 1;
+		return `tg-${this.opts.ownerId}-${this.lifecycleSeq}-${crypto.randomBytes(4).toString("hex")}`;
+	}
+
+	/** Build an authenticated lifecycle frame from a parsed command + identity. */
+	private buildLifecycleFrame(
+		parsed:
+			| { kind: "create"; target: SessionCreateTarget }
+			| { kind: "close"; target: SessionCloseTarget }
+			| { kind: "resume"; target: SessionResumeTarget },
+		updateId: number,
+	): SessionLifecycleRequest {
+		const requestId = this.nextLifecycleRequestId();
+		const token = this.controlToken ?? "";
+		const chatId = this.opts.chatId;
+		if (parsed.kind === "create") {
+			return {
+				type: "session_create",
+				requestId,
+				lifecycleRequestId: requestId,
+				intendedSessionId: `s${crypto.randomBytes(6).toString("hex")}`,
+				updateId,
+				chatId,
+				token,
+				target: parsed.target,
+			};
+		}
+		if (parsed.kind === "close") {
+			return { type: "session_close", requestId, updateId, chatId, token, target: parsed.target, force: true };
+		}
+		return { type: "session_resume", requestId, updateId, chatId, token, target: parsed.target };
+	}
+
+	/**
+	 * Handle a paired-chat /session_* command: validate (shared validator),
+	 * route to the control endpoint, and reply with the outcome. Returns true
+	 * when the message was a lifecycle command (so the caller stops processing).
+	 */
+	private async handleLifecycleCommand(
+		text: string | undefined,
+		updateId: number | undefined,
+		threadId: number | undefined,
+	): Promise<boolean> {
+		if (!isLifecycleCommandText(text)) return false;
+		const reply = (body: string) =>
+			this.botApi
+				.call("sendMessage", {
+					chat_id: this.opts.chatId,
+					...(threadId !== undefined ? { message_thread_id: threadId } : {}),
+					text: body,
+				})
+				.catch(() => undefined);
+
+		if (!this.lifecycleControlActive) {
+			await reply("Session lifecycle control is not available right now.");
+			return true;
+		}
+		if (updateId !== undefined && this.dispatchState.seenUpdateIds.has(updateId)) return true;
+		if (updateId !== undefined) this.dispatchState.seenUpdateIds.add(updateId);
+
+		const parsed = parseLifecycleCommand(text);
+		if (parsed.kind === "none") return false;
+		if (parsed.kind === "usage" || parsed.kind === "reject") {
+			await reply(parsed.message);
+			return true;
+		}
+		if (parsed.kind === "recent") {
+			const recent = listRecentSessions({
+				sessionsRoot: path.join(this.opts.settings.getAgentDir(), "sessions"),
+				limit: 10,
+			});
+			const lines = recent.length
+				? recent.map(e => `\u2022 ${e.sessionId}${e.path ? ` (${e.path})` : ""}`).join("\n")
+				: "No recent sessions.";
+			await reply(lines);
+			return true;
+		}
+
+		// Defensive shared-validator pre-check before any effect.
+		const verb =
+			parsed.kind === "create" ? "session_create" : parsed.kind === "close" ? "session_close" : "session_resume";
+		const valid = validateLifecycleTarget(verb, parsed.target);
+		if (!valid.ok) {
+			await reply(`${valid.message}\n\n${lifecycleUsage()}`);
+			return true;
+		}
+
+		const frame = this.buildLifecycleFrame(parsed, updateId ?? Date.now());
+		const response = await this.submitLifecycleFrame(frame);
+		await reply(this.formatLifecycleResponse(response));
+		return true;
+	}
+
+	/** Map a lifecycle response/error to a user-facing message (G010 surfacing). */
+	private formatLifecycleResponse(r: SessionLifecycleResponse): string {
+		return formatLifecycleOutcome(r);
+	}
+
 	constructor(private readonly opts: TelegramDaemonOptions) {
 		this.fsImpl = opts.fs ?? nodeFs;
 		this.aliasTable = createAliasTable();
@@ -847,6 +1199,14 @@ export class TelegramNotificationDaemon {
 						await this.setReaction(target.messageId, CONSUMED_REACTION);
 					}
 				},
+			})
+			.add({
+				name: "session_closed",
+				matches: msg => msg.type === "session_closed",
+				handle: async session => {
+					this.busy.delete(session.sessionId);
+					await this.deleteTopic(session.sessionId);
+				},
 			});
 	}
 
@@ -877,6 +1237,11 @@ export class TelegramNotificationDaemon {
 				if (this.sessions.has(sessionId)) continue;
 				try {
 					const endpoint = readEndpoint(path.join(dir, file));
+					// Skip endpoint files whose owning process is gone or that are
+					// explicitly stale (e.g. a hard-closed session): reconnecting
+					// would chase a dead, token-bearing record forever.
+					const pidAlive = this.opts.pidAlive ?? defaultPidAlive;
+					if (endpoint.stale || (endpoint.pid !== undefined && !pidAlive(endpoint.pid))) continue;
 					this.connectSession(sessionId, endpoint.url, endpoint.token);
 				} catch {}
 			}
@@ -912,6 +1277,12 @@ export class TelegramNotificationDaemon {
 					);
 				} catch {}
 			}
+			// Eagerly create the session's Telegram topic as soon as it connects, so
+			// a thread exists the moment a notifications-enabled session is live —
+			// not lazily on the first delivered frame (which only arrives once the
+			// user sends a prompt). A provisional "GJC <id>" name is used; the
+			// identity_header frame renames it to "{repo}/{branch} - {title}" later.
+			void this.ensureTopic(sessionId, this.topicNameFor(sessionId, {})).catch(() => undefined);
 		});
 		ws.addEventListener("message", ev => {
 			// Identity guard: a delayed frame from a superseded socket must not act
@@ -1077,8 +1448,12 @@ export class TelegramNotificationDaemon {
 					return String(tid);
 				},
 				this.opts.now,
+				// The create winner records the name it actually used; callers that
+				// merely JOIN an in-flight create must not overwrite it locally, or a
+				// later identity rename would be wrongly skipped (topic stuck at the
+				// provisional name on Telegram).
+				name,
 			);
-			this.topics.applyName(sessionId, name);
 			await this.persistTopics();
 			return rec.topicId;
 		} catch {
@@ -1086,6 +1461,31 @@ export class TelegramNotificationDaemon {
 		}
 	}
 
+	/** Best-effort delete of a session topic once its local notification endpoint shuts down. */
+	private async deleteTopic(sessionId: string): Promise<void> {
+		const record = this.topics.get(sessionId);
+		if (!record) return;
+		try {
+			// Drop queued sends for this session before deleting the topic; otherwise
+			// rate-limited frames can flush later into a deleted topic or across resume.
+			this.pool.removeWhere(item => item.sessionId === sessionId);
+			await this.flushPool();
+			const res = (await this.botApi.call("deleteForumTopic", {
+				chat_id: this.opts.chatId,
+				message_thread_id: Number(record.topicId),
+			})) as { ok?: boolean };
+			if (res?.ok === false) return;
+			this.topics.delete(sessionId);
+			this.topicOwnerByIdentity.forEach((ownerSessionId, identityKey) => {
+				if (ownerSessionId === sessionId) this.topicOwnerByIdentity.delete(identityKey);
+			});
+			this.pendingThreadedFrames.delete(sessionId);
+			await this.persistTopics();
+		} catch {
+			// Best-effort: missing Telegram topic permissions must not stop teardown.
+		}
+	}
+
 	private async persistTopics(): Promise<void> {
 		const paths = daemonPaths(this.opts.settings.getAgentDir());
 		await ensureDir(this.fsImpl, paths.dir);
@@ -1434,9 +1834,9 @@ export class TelegramNotificationDaemon {
 				summary: msg.summary,
 			});
 			const options = Array.isArray(msg.options) ? msg.options : [];
-			// Daemon keyboards MUST use alias callback data (not reference encodeCallbackData).
-			// Labels show one-based numbers; the stored alias answer stays zero-based.
-			const inline_keyboard = buildButtonGrid(options, (i: number) =>
+			// Daemon keyboards use alias callback data with compact one-based tap targets;
+			// full option text is rendered in the message body by buildActionMessage.
+			const inline_keyboard = buildCompactChoiceGrid(options, (i: number) =>
 				this.aliasTable.put({ sessionId: session.sessionId, actionId: msg.id, answer: i }),
 			);
 			const result = (await this.botApi.call("sendMessage", {
@@ -1480,6 +1880,20 @@ export class TelegramNotificationDaemon {
 	}
 
 	async handleTelegramUpdate(update: unknown): Promise<void> {
+		// Session-lifecycle command (/session_*): handled ONLY from the paired chat,
+		// gated before any arg parsing or side effect, and routed through the control
+		// endpoint. Must run before threaded-injection so commands are not treated as
+		// session input.
+		{
+			const m = (update as { update_id?: number; message?: Record<string, unknown> }).message;
+			const chatId = (m?.chat as { id?: unknown } | undefined)?.id;
+			const cmdText = typeof m?.text === "string" ? m.text : undefined;
+			if (m !== undefined && String(chatId) === String(this.opts.chatId) && isLifecycleCommandText(cmdText)) {
+				const updateId = (update as { update_id?: number }).update_id;
+				const threadId = typeof m.message_thread_id === "number" ? (m.message_thread_id as number) : undefined;
+				if (await this.handleLifecycleCommand(cmdText, updateId, threadId)) return;
+			}
+		}
 		// Threaded injection: a free-text message in a known topic (not a button
 		// tap and not a reply to a specific ask message) injects a user turn or an
 		// in-thread config command. Fail-closed: paired chat + known topic +
@@ -1616,6 +2030,9 @@ export class TelegramNotificationDaemon {
 			await this.loadAliases();
 			await this.loadTopics();
 			await this.runScan();
+			// Owner-only: start the session-lifecycle control server now that
+			// ownership is confirmed (singleton-safe). Best-effort; degrades.
+			await this.startLifecycleControl();
 			let idleSince = this.runtime.now();
 			while (this.running) {
 				if (await this.controlStopRequested()) break;
@@ -1631,10 +2048,17 @@ export class TelegramNotificationDaemon {
 					break;
 				await this.runScan();
 				if (await this.controlStopRequested()) break;
-				if (this.sessions.size === 0) {
-					if (this.runtime.now() - idleSince >= (this.opts.idleTimeoutMs ?? 60_000)) break;
+				const idleElapsed = this.runtime.now() - idleSince >= (this.opts.idleTimeoutMs ?? 60_000);
+				if (this.sessions.size === 0 && !this.lifecycleControlActive) {
+					// No sessions and no lifecycle control: idle-exit on timeout.
+					if (idleElapsed) break;
 				} else {
-					idleSince = this.runtime.now();
+					// Poll getUpdates when sessions exist OR lifecycle control is active
+					// (so phone /session_* commands are received even with zero sessions).
+					// With zero sessions, still idle-exit after the timeout so the owner
+					// does not run forever; an active session resets the idle window.
+					if (this.sessions.size > 0) idleSince = this.runtime.now();
+					else if (idleElapsed) break;
 					const activePoll = this.runtime.createAbortController();
 					try {
 						await this.pollOnce(activePoll.signal);
@@ -1659,6 +2083,7 @@ export class TelegramNotificationDaemon {
 			this.stopFlushTimer();
 			this.stopScanTimer();
 			this.stopTypingTimer();
+			this.stopLifecycleControl();
 			await this.cleanupAllAttachmentDirs();
 			// Persist durable state before releasing ownership so a fresh daemon
 			// (e.g. after reload) reloads aliases/topics seamlessly.

package/src/notifications/telegram-reference.ts

@@ -15,7 +15,14 @@
  */
 
 import * as fs from "node:fs";
-import { bold, buildButtonGrid, escapeHtml, TELEGRAM_PARSE_MODE, truncateTelegramHtml } from "./html-format";
+import {
+	bold,
+	buildCompactChoiceGrid,
+	escapeHtml,
+	numberedOptionList,
+	TELEGRAM_PARSE_MODE,
+	truncateTelegramHtml,
+} from "./html-format";
 import { renderThreadedFrame } from "./threaded-render";
 
 /** One inline-keyboard button. */
@@ -129,8 +136,9 @@ export function buildActionMessage(action: {
 	const text = `❓ ${bold(action.question ?? "Question")}`;
 	const options = action.options ?? [];
 	if (options.length === 0) return { text: truncateTelegramHtml(`${text}\n\n(reply with text)`) };
-	const inline_keyboard = buildButtonGrid(options, i => encodeCallbackData(action.id, i));
-	return { text: truncateTelegramHtml(text), inline_keyboard };
+	const body = `${text}\n\n${numberedOptionList(options)}`;
+	const inline_keyboard = buildCompactChoiceGrid(options, i => encodeCallbackData(action.id, i));
+	return { text: truncateTelegramHtml(body), inline_keyboard };
 }
 
 /** A protocol `reply` frame the client should send to the server. */
@@ -235,13 +243,23 @@ export function routeInboundUpdate(update: unknown, ctx: RouteInboundContext): R
 	return { kind: "ignore" };
 }
 
-/** Read `{url, token}` from an endpoint discovery file. */
-export function readEndpoint(path: string): { url: string; token: string } {
-	const raw = JSON.parse(fs.readFileSync(path, "utf8")) as { url?: unknown; token?: unknown };
+/** Read `{url, token, pid?, stale?}` from an endpoint discovery file. */
+export function readEndpoint(path: string): { url: string; token: string; pid?: number; stale?: boolean } {
+	const raw = JSON.parse(fs.readFileSync(path, "utf8")) as {
+		url?: unknown;
+		token?: unknown;
+		pid?: unknown;
+		stale?: unknown;
+	};
 	if (typeof raw.url !== "string" || typeof raw.token !== "string") {
 		throw new Error(`invalid endpoint file: ${path}`);
 	}
-	return { url: raw.url, token: raw.token };
+	return {
+		url: raw.url,
+		token: raw.token,
+		pid: typeof raw.pid === "number" ? raw.pid : undefined,
+		stale: raw.stale === true,
+	};
 }
 
 /** Options for {@link runTelegramReferenceClient}. */

package/src/notifications/topic-registry.ts

@@ -1,11 +1,11 @@
 /**
  * Per-session forum-topic registry for the threaded session surface.
  *
- * Each GJC session owns exactly one Telegram forum topic in the paired private
- * DM. The topic is created once (via `createForumTopic`) and REUSED on resume,
- * keyed by session id, so a resumed session streams back into its existing
- * thread/history. The registry also tracks whether the one-time identity header
- * has already been pinned, so it is sent exactly once per topic even across
+ * Each GJC session owns one active Telegram forum topic in the paired private
+ * DM. The topic is created via `createForumTopic`, reused while the session
+ * remains active, and removed from the registry when the daemon deletes it on
+ * shutdown. The registry also tracks whether the one-time identity header has
+ * already been pinned, so it is sent exactly once per active topic, even across
  * reconnects.
  *
  * State is a plain serialisable map persisted beside the daemon state files;
@@ -76,14 +76,14 @@ export class TopicRegistry {
 	}
 
 	/**
-	 * Return the existing topic for `sessionId`, or create one via `create`
-	 * (called only on first use). Reuse-on-resume: an existing record is
-	 * returned without invoking `create`.
+	 * Return the existing active topic for `sessionId`, or create one via
+	 * `create` (called only on first use).
 	 */
 	async getOrCreateTopic(
 		sessionId: string,
 		create: () => Promise<string>,
 		now: () => number = Date.now,
+		name?: string,
 	): Promise<TopicRecord> {
 		const existing = this.topics.get(sessionId);
 		if (existing) return existing;
@@ -95,7 +95,7 @@ export class TopicRegistry {
 		if (pending) return pending;
 		const promise = (async () => {
 			const topicId = await create();
-			const record: TopicRecord = { topicId, identitySent: false, createdAt: now() };
+			const record: TopicRecord = { topicId, name, identitySent: false, createdAt: now() };
 			this.topics.set(sessionId, record);
 			this.byTopic.set(topicId, sessionId);
 			return record;
@@ -131,6 +131,15 @@ export class TopicRegistry {
 		return true;
 	}
 
+	/** Remove a session topic record after Telegram deletes the topic. */
+	delete(sessionId: string): boolean {
+		const record = this.topics.get(sessionId);
+		if (!record) return false;
+		this.topics.delete(sessionId);
+		this.byTopic.delete(record.topicId);
+		return true;
+	}
+
 	/** Serialise for atomic persistence beside the daemon state. */
 	serialize(): TopicRegistryState {
 		return { topics: Object.fromEntries(this.topics) };

package/src/prompts/agents/executor.md

@@ -36,8 +36,8 @@ This mode activates only when the assignment explicitly labels Executor as Ultra
 
 When active:
 - Start from the approved plan/spec/acceptance criteria, then user-facing contracts, then implementation code only as supporting evidence. Treat plan/code mismatches as blockers.
-- Exercise the real user-facing invocation rather than inspecting internals alone. Live artifacts must be runtime-valid: GUI/web needs a real automation transcript plus non-uniform screenshot; CLI needs executed argv-only replay; native/desktop/TUI needs a real screenshot, PTY capture with control codes, or app-automation transcript. `inlineEvidence` is supplemental only and is never sole proof for live surfaces.
-- For CLI evidence, emit argv-only replay JSON with `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, and `command` as a string array. Use only allowlisted deterministic executables/arguments, or mark unsafe/non-deterministic commands with audited `replayExempt` metadata plus a valid structural fallback artifact. `replayExempt` must use exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs`; allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
+- Exercise the real user-facing invocation rather than inspecting internals alone. Live artifacts must be runtime-valid: GUI/web needs a real automation transcript plus non-uniform screenshot; CLI needs executed argv-only replay; native/desktop/TUI needs a real screenshot, PTY capture with control codes, or app-automation transcript. API/package surfaces need a real artifact file or typed receipt whose artifact `kind` contains `api`, `package`, `consumer`, `black-box`, or `test-report`; good kinds include `api-package-test-report`, `package-consumer-report`, and `black-box-api-receipt`. Algorithm/math surfaces need a real artifact file or typed receipt whose artifact `kind` contains `property`, `boundary`, `edge`, `adversarial`, `failure`, `math`, `algorithm`, or `test-report`; good kinds include `property-test-report` and `algorithm-boundary-report`. `inlineEvidence` is supplemental only and is never sole proof for live surfaces.
+- For CLI evidence, emit argv-only replay JSON with `schemaVersion: 1`, `kind: "cli-replay"`, `replaySafe: true`, and `command` as a string array. Use only allowlisted deterministic executables/arguments: `bun --version`, `node --version`, deterministic `bun/node -e "console.log(...)"`, `npm|pnpm|yarn --version`, `npm|pnpm|yarn list`, read-only `git status|rev-parse|merge-base|diff|show|log` with safe args, and `gjc read|status`. Mark any other command with audited `replayExempt` metadata plus a valid structural fallback artifact. `replayExempt` must use exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs`; allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
 - Native/TUI evidence must be structural, not prose-only: screenshot, app transcript, or PTY artifact with terminal control codes.
 - Do not call the `ask` tool while an Ultragoal run is active; record unresolved decisions with `gjc ultragoal record-review-blockers`.
 - Try to break the work with adversarial cases, not just happy-path confirmations.