@gajae-code/coding-agent 0.11.6 → 0.11.8

package/src/sdk/bus/recent-activity.ts

@@ -11,7 +11,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { verifyOwnerOnlyPathSecurity } from "@gajae-code/natives";
 import { getAgentDir, getSessionsDir } from "@gajae-code/utils";
-import { FileSessionStorage } from "../../session/session-storage";
+import { FileSessionStorage, type SessionStorageSnapshot } from "../../session/session-storage";
 import {
 	type LogicalSessionCandidate,
 	listManagedSessionCandidates,
@@ -58,25 +58,52 @@ export interface RecentActivityDeps {
 	readInitialLines?: (file: string, maxLines: number) => string[];
 }
 
+class ManagedCandidateChangedError extends Error {}
+class ManagedCandidateUnavailableError extends Error {}
+
+const CHANGED_CANDIDATE_WARNING = "Ignored managed session candidate that changed during inspection.";
+
+function isAppendExtension(bytes: Uint8Array, candidate: LogicalSessionCandidate): boolean {
+	return (
+		bytes.byteLength >= candidate.identity.size &&
+		createHash("sha256").update(bytes.subarray(0, candidate.identity.size)).digest("hex") ===
+			candidate.identity.sha256
+	);
+}
+
 function readCandidateInitialLines(
 	candidate: LogicalSessionCandidate,
 	readInitialLines: ((file: string, maxLines: number) => string[]) | undefined,
+	appendBase?: LogicalSessionCandidate,
 ): string[] {
 	if (readInitialLines) return readInitialLines(candidate.path, 8);
 	if (candidate.provenance !== "legacy") {
 		const security = verifyOwnerOnlyPathSecurity(candidate.path, "file");
-		if (!security.ok) throw new Error(`Managed session metadata path is unsafe: ${security.code}`);
+		if (!security.ok) throw new ManagedCandidateUnavailableError("Managed session metadata path is unsafe.");
 	}
-	const snapshot = new FileSessionStorage().readSnapshotSync(candidate.path);
+	let snapshot: SessionStorageSnapshot;
+	try {
+		snapshot = new FileSessionStorage().readSnapshotSync(candidate.path);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR")
+			throw new ManagedCandidateUnavailableError("Managed session metadata is unavailable.");
+		throw error;
+	}
+	const sameFile = snapshot.stat.dev === candidate.identity.dev && snapshot.stat.ino === candidate.identity.ino;
 	const digest = createHash("sha256").update(snapshot.bytes).digest("hex");
-	if (
-		snapshot.stat.dev !== candidate.identity.dev ||
-		snapshot.stat.ino !== candidate.identity.ino ||
-		snapshot.stat.size !== candidate.identity.size ||
-		snapshot.stat.mtimeNs !== candidate.identity.mtimeNs ||
-		digest !== candidate.identity.sha256
-	)
-		throw new Error("Managed session changed after ownership was verified.");
+	const exactIdentity =
+		sameFile &&
+		snapshot.stat.size === candidate.identity.size &&
+		snapshot.stat.mtimeNs === candidate.identity.mtimeNs &&
+		digest === candidate.identity.sha256;
+	if (appendBase && (!sameFile || !isAppendExtension(snapshot.bytes, appendBase)))
+		throw new ManagedCandidateUnavailableError("Managed session no longer extends the verified transcript.");
+	if (!exactIdentity) {
+		if (sameFile && isAppendExtension(snapshot.bytes, candidate))
+			throw new ManagedCandidateChangedError("Managed session was appended after ownership was verified.");
+		throw new ManagedCandidateUnavailableError("Managed session changed without an append-only extension.");
+	}
 	return Buffer.from(snapshot.bytes).toString("utf8").split("\n").slice(0, 8);
 }
 
@@ -227,13 +254,13 @@ export async function listRecentSessions(deps: RecentActivityDeps): Promise<List
 	const resolved = await resolveRecentScopes(deps);
 	if (resolved.kind === "error") return resolved;
 	const warnings = [...resolved.warnings];
-	const candidates: LogicalSessionCandidate[] = [];
+	const candidates: Array<{ scope: ManagedSessionScope; candidate: LogicalSessionCandidate }> = [];
 	for (const scope of resolved.scopes) {
 		const listed = await listManagedSessionCandidates({ scope });
 		if (listed.kind !== "complete") {
 			return { kind: "error", code: "managed_scan_failed", message: listed.message };
 		}
-		candidates.push(...listed.owned);
+		candidates.push(...listed.owned.map(candidate => ({ scope, candidate })));
 		warnings.push(
 			...listed.invalid
 				.filter(
@@ -245,28 +272,65 @@ export async function listRecentSessions(deps: RecentActivityDeps): Promise<List
 	}
 
 	const entries: RecentSessionEntry[] = [];
-	for (const candidate of candidates) {
-		let initialLines: string[];
+	for (const { scope, candidate } of candidates) {
+		let selected = candidate;
+		let initialLines: string[] | undefined;
 		try {
-			initialLines = readCandidateInitialLines(candidate, readInitialLines);
+			initialLines = readCandidateInitialLines(selected, readInitialLines);
 		} catch (error) {
-			return {
-				kind: "error",
-				code: "managed_scan_failed",
-				message: `Could not read managed session metadata: ${error instanceof Error ? error.message : String(error)}`,
-			};
+			if (error instanceof ManagedCandidateChangedError) {
+				const refreshed = await listManagedSessionCandidates({ scope });
+				if (refreshed.kind !== "complete")
+					return { kind: "error", code: "managed_scan_failed", message: refreshed.message };
+				const sameFile = refreshed.owned.find(
+					current =>
+						path.resolve(current.path) === path.resolve(candidate.path) &&
+						current.identity.dev === candidate.identity.dev &&
+						current.identity.ino === candidate.identity.ino,
+				);
+				if (sameFile) {
+					try {
+						initialLines = readCandidateInitialLines(sameFile, readInitialLines, candidate);
+						selected = sameFile;
+					} catch (retryError) {
+						if (
+							!(retryError instanceof ManagedCandidateChangedError) &&
+							!(retryError instanceof ManagedCandidateUnavailableError)
+						)
+							return {
+								kind: "error",
+								code: "managed_scan_failed",
+								message: `Could not read managed session metadata: ${
+									retryError instanceof Error ? retryError.message : String(retryError)
+								}`,
+							};
+					}
+				}
+			} else if (!(error instanceof ManagedCandidateUnavailableError)) {
+				return {
+					kind: "error",
+					code: "managed_scan_failed",
+					message: `Could not read managed session metadata: ${
+						error instanceof Error ? error.message : String(error)
+					}`,
+				};
+			}
+			if (!initialLines) {
+				warnings.push(CHANGED_CANDIDATE_WARNING);
+				continue;
+			}
 		}
 		const meta = headerMeta(initialLines[0]);
 		const internal = isInternalSession(initialLines);
 		if (internal && !includeInternal) continue;
 		entries.push({
-			sessionId: candidate.sessionId,
-			path: candidate.cwd,
+			sessionId: selected.sessionId,
+			path: selected.cwd,
 			branch: meta.branch,
 			title: meta.title,
-			sessionStateFile: candidate.path,
-			mtimeMs: candidate.identity.mtimeMs,
-			currentTerminal: breadcrumbs.has(path.resolve(candidate.path)) || undefined,
+			sessionStateFile: selected.path,
+			mtimeMs: selected.identity.mtimeMs,
+			currentTerminal: breadcrumbs.has(path.resolve(selected.path)) || undefined,
 			internal: internal || undefined,
 		});
 	}

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

@@ -21,7 +21,22 @@ export const NOTIFICATION_PROTOCOL_VERSION = 3;
  * confirmed-dead owner's lock in generation 10, legacy stopped-tombstone
  * reclamation in generation 11, force-escalated SIGKILL of an unresponsive
  * older-generation owner during automatic generation-upgrade reload in
- * generation 12, and restored macOS daemon signaling (kill(2) with a start-time
- * incarnation recheck, replacing the darwin no-op) in generation 13.
+ * generation 12, restored macOS daemon signaling (kill(2) with a start-time
+ * incarnation recheck, replacing the darwin no-op) in generation 13, retained
+ * legacy stopped-lock reclamation in generation 14, Windows expected-identity
+ * ACL verification and repair in generation 15, identity-fenced stale endpoint
+ * startup recovery in generation 16, Telegram topic recovery authority fencing
+ * in generation 17, fail-closed blank-token validation plus lifecycle-startup
+ * stop fencing in generation 18, recommended ask metadata rendering in
+ * generation 19, authoritative terminal session-close delivery and cleanup
+ * fencing, attested generation-bearing pre-incarnation owner handoff in
+ * generation 20, guarded modern generation-absent predecessor signaling in
+ * generation 21, dead Windows v0.10 owner replacement in generation 22, and
+ * retained native cleanup authority revalidation in generation 23, and typed
+ * retained exact-unlink cleanup authority acceptance (concrete detached
+ * quarantine plus proven canonical absence) in generation 24.
+ * Generation 25 adds startup dead-root prune + leak-artifact self-heal
+ * on TelegramNotificationDaemon.run (#2958). Generation 26 adds bounded reload
+ * cooldown and lazy Telegram topic lifecycle safeguards (#2956, #2960, #2984).
  */
-export const DAEMON_GENERATION = 13;
+export const DAEMON_GENERATION = 26;

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

@@ -25,9 +25,11 @@ import type {
 import { OWNERSHIP_MISMATCH_MESSAGE, ownershipMismatchRecovery } from "../../daemon/operator-contract";
 import { resolveGjcRuntimeSpawnInfo } from "../../daemon/runtime";
 import { isProcessIncarnation } from "../broker/process-incarnation";
+
 import { getNotificationConfig, isTelegramConfigured, tokenFingerprint } from "./config";
 import { exactUnlinkNotificationFile, readNotificationEndpointFile } from "./notification-service";
 import {
+	type AttestedLegacyDaemonOwner,
 	confirmTelegramDaemonSpawn,
 	type DaemonState,
 	daemonPaths,
@@ -35,6 +37,7 @@ import {
 	isCurrentCompatibleOwner,
 	isFreshLiveOwner,
 	isSignalableMatchingOwner,
+	readAttestedLegacyDaemonOwner,
 	readDaemonRoots,
 	readDaemonState,
 	spawnTelegramDaemonOwner,
@@ -109,16 +112,19 @@ export async function clearTelegramControlRequest(
 
 export interface DaemonProcessReference {
 	incarnation: string;
+	/** Whether the platform delivers the requested signal cooperatively or as a hard termination. */
+	termination: "cooperative" | "hard";
 	signalRoot(signal: NodeJS.Signals): void;
 }
 
-function defaultProcessReference(pid: number, platform = os.platform()): DaemonProcessReference | undefined {
+export function defaultProcessReference(pid: number, platform = os.platform()): DaemonProcessReference | undefined {
 	try {
 		const processRef = Process.fromPid(pid);
 		if (!processRef || !isProcessIncarnation(processRef.incarnation)) return undefined;
 		const incarnation = processRef.incarnation;
 		return {
 			incarnation,
+			termination: platform === "win32" ? "hard" : "cooperative",
 			signalRoot: signal => {
 				const nativeSignal = os.constants.signals[signal];
 				if (nativeSignal === undefined) throw new Error(`Unsupported signal: ${signal}`);
@@ -178,8 +184,8 @@ function defaultPidAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
 		return true;
-	} catch {
-		return false;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
 	}
 }
 
@@ -190,7 +196,6 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 	private readonly now: () => number;
 	private readonly processReference: (pid: number) => DaemonProcessReference | undefined;
 	private readonly waitStepMs: number;
-
 	constructor(
 		private readonly settings: Settings,
 		private readonly deps: TelegramDaemonControlDeps = {},
@@ -315,31 +320,28 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		tokenFingerprint: string,
 		chatId: string,
 		signal: NodeJS.Signals,
-	): Promise<"signaled" | "already_gone" | "ownership_changed"> {
+	): Promise<"signaled" | "already_gone" | "ownership_changed" | "hard_termination"> {
 		const current = await readDaemonState(this.settings, this.fsImpl);
-		// The signal is a privileged action: immediately before sending it, prove the
-		// complete state record is still the exact captured owner. A malformed record,
-		// configuration mutation, or successor using a reused PID is never signalable.
-		if (
-			!hasSafeDaemonStateShape(current) ||
-			current.ownerId !== captured.ownerId ||
-			current.acquisitionId !== captured.acquisitionId ||
-			current.pid !== captured.pid ||
-			current.generation !== captured.generation ||
-			current.incarnation !== captured.incarnation ||
-			current.tokenFingerprint !== captured.tokenFingerprint ||
-			current.chatId !== captured.chatId ||
-			current.tokenFingerprint !== tokenFingerprint ||
-			current.chatId !== chatId
-		)
-			return "ownership_changed";
-		// A matching captured owner that exited between the request and recheck has
-		// completed the handoff. A live owner with changed or unavailable provenance
-		// remains ambiguous and must not be treated as stopped.
+
+		const modernCurrentMatches =
+			hasSafeDaemonStateShape(current) &&
+			current.ownerId === captured.ownerId &&
+			current.acquisitionId === captured.acquisitionId &&
+			current.pid === captured.pid &&
+			current.generation === captured.generation &&
+			current.incarnation === captured.incarnation &&
+			current.tokenFingerprint === captured.tokenFingerprint &&
+			current.chatId === captured.chatId &&
+			current.tokenFingerprint === tokenFingerprint &&
+			current.chatId === chatId;
+		// The signal is privileged: the persisted record must still be the exact
+		// modern owner. Legacy generation-3 records remain migration evidence only;
+		// this controller never upgrades or signals them.
+		if (!modernCurrentMatches) return "ownership_changed";
 		if (!this.pidAlive(captured.pid)) return "already_gone";
 		if (
 			!isSignalableMatchingOwner({
-				state: current,
+				state: modernCurrentMatches ? current : captured,
 				tokenFingerprint,
 				chatId,
 				pidAlive: this.pidAlive,
@@ -352,6 +354,69 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		// the exit-and-reuse window between ordinary provenance checks and signaling.
 		// Its identity must still be the exact persisted incarnation before use.
 		if (!processRef || processRef.incarnation !== captured.incarnation) return "ownership_changed";
+		if (signal === "SIGTERM" && processRef.termination === "hard") return "hard_termination";
+		try {
+			processRef.signalRoot(signal);
+		} catch {
+			return "already_gone";
+		}
+		return "signaled";
+	}
+
+	#currentConfigurationMatches(tokenFingerprintValue: string, chatId: string): boolean {
+		const current = getNotificationConfig(this.settings);
+		return (
+			isTelegramConfigured(current) &&
+			tokenFingerprint(current.botToken) === tokenFingerprintValue &&
+			current.chatId === chatId
+		);
+	}
+
+	async #signalAttestedLegacyOwner(
+		captured: AttestedLegacyDaemonOwner,
+		tokenFingerprint: string,
+		chatId: string,
+		signal: NodeJS.Signals,
+	): Promise<"signaled" | "already_gone" | "ownership_changed" | "hard_termination"> {
+		if (!this.#currentConfigurationMatches(tokenFingerprint, chatId)) return "ownership_changed";
+		const current = await readAttestedLegacyDaemonOwner({
+			settings: this.settings,
+			fs: this.fsImpl,
+			now: this.now,
+			pidIncarnation: this.deps.pidIncarnation,
+			tokenFingerprint,
+			chatId,
+		});
+		if (
+			!current ||
+			current.state.pid !== captured.state.pid ||
+			current.state.ownerId !== captured.state.ownerId ||
+			current.state.startedAt !== captured.state.startedAt ||
+			current.incarnation !== captured.incarnation
+		)
+			return "ownership_changed";
+		if (!this.pidAlive(captured.state.pid)) return "already_gone";
+		const processRef = this.processReference(captured.state.pid);
+		if (!processRef || processRef.incarnation !== captured.incarnation) return "ownership_changed";
+		const rechecked = await readAttestedLegacyDaemonOwner({
+			settings: this.settings,
+			fs: this.fsImpl,
+			now: this.now,
+			pidIncarnation: this.deps.pidIncarnation,
+			tokenFingerprint,
+			chatId,
+		});
+		if (
+			!rechecked ||
+			rechecked.state.pid !== current.state.pid ||
+			rechecked.state.ownerId !== current.state.ownerId ||
+			rechecked.state.startedAt !== current.state.startedAt ||
+			rechecked.incarnation !== current.incarnation ||
+			!this.#currentConfigurationMatches(tokenFingerprint, chatId) ||
+			!this.pidAlive(captured.state.pid)
+		)
+			return "ownership_changed";
+		if (signal === "SIGTERM" && processRef.termination === "hard") return "hard_termination";
 		try {
 			processRef.signalRoot(signal);
 		} catch {
@@ -376,7 +441,10 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		return this.stopOrReload("reload", opts);
 	}
 
-	async reloadForGenerationUpgrade(opts: DaemonOperationOptions = {}): Promise<TelegramGenerationReloadResult> {
+	async reloadForGenerationUpgrade(
+		opts: DaemonOperationOptions = {},
+		attestedLegacyUpgrade = false,
+	): Promise<TelegramGenerationReloadResult> {
 		// A generation upgrade MUST replace an incompatible older-generation owner to
 		// avoid a permanent single-poller deadlock. Unlike a manual `gjc daemon
 		// reload`, this automatic path force-escalates to SIGKILL when the old owner
@@ -384,7 +452,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		// self-recovers instead of failing closed and asking the operator to rerun
 		// with --force. The SIGKILL remains fenced to the still-live, still-matching
 		// captured owner (same ownerId + pid), so a fresh replacement is never killed.
-		const operation = await this.stopOrReload("reload", { ...opts, force: true });
+		const operation = await this.stopOrReload("reload", { ...opts, force: true }, attestedLegacyUpgrade);
 		if (!operation.ok) return { outcome: "failed", operation };
 		const after = await this.status();
 		return after.health === "running" ? { outcome: "ready", operation } : { outcome: "failed", operation };
@@ -394,7 +462,11 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		return this.stopOrReload("stop", opts);
 	}
 
-	private async stopOrReload(action: "stop" | "reload", opts: DaemonOperationOptions): Promise<DaemonOperationResult> {
+	private async stopOrReload(
+		action: "stop" | "reload",
+		opts: DaemonOperationOptions,
+		attestedLegacyUpgrade = false,
+	): Promise<DaemonOperationResult> {
 		const before = await this.status();
 		const warnings: string[] = [];
 		if (before.runtime.warning) warnings.push(before.runtime.warning);
@@ -409,6 +481,16 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		const killTimeoutMs = opts.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS;
 
 		const state = await readDaemonState(this.settings, this.fsImpl);
+		const attestedLegacyOwner = attestedLegacyUpgrade
+			? await readAttestedLegacyDaemonOwner({
+					settings: this.settings,
+					fs: this.fsImpl,
+					now: this.now,
+					pidIncarnation: this.deps.pidIncarnation,
+					tokenFingerprint: fp,
+					chatId,
+				})
+			: undefined;
 		const replaceableLiveOwner =
 			(action === "reload" &&
 				state !== undefined &&
@@ -427,6 +509,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 					pidAlive: this.pidAlive,
 					pidIncarnation: this.deps.pidIncarnation,
 				})) ||
+			(action === "reload" && attestedLegacyOwner !== undefined && this.pidAlive(attestedLegacyOwner.state.pid)) ||
 			// A physically-live matching owner whose heartbeat is stale (hung) may be
 			// past-TTL yet still holding the poller. Autostart/generation-upgrade reloads
 			// stay conservative and refuse it, but an explicit `reload --force` must be
@@ -483,16 +566,18 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 		}
 
 		// Running owner: capture identity, request cooperative stop, signal, wait.
-		if (
-			!hasSafeDaemonStateShape(state) ||
-			!isSignalableMatchingOwner({
+		const modernCapturedOwner =
+			hasSafeDaemonStateShape(state) &&
+			isSignalableMatchingOwner({
 				state,
 				tokenFingerprint: fp,
 				chatId,
 				pidAlive: this.pidAlive,
 				pidIncarnation: this.deps.pidIncarnation,
 			})
-		) {
+				? state
+				: undefined;
+		if (!modernCapturedOwner && !attestedLegacyOwner) {
 			return this.result(
 				action,
 				false,
@@ -502,7 +587,7 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 				warnings,
 			);
 		}
-		const capturedOwner = state;
+		const capturedOwner = modernCapturedOwner ?? attestedLegacyOwner!.state;
 		const oldOwnerId = capturedOwner.ownerId;
 		const oldPid = capturedOwner.pid;
 		const requestId = this.deps.randomId?.() ?? `${this.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
@@ -511,7 +596,21 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 			{ version: 1, requestId, action, ownerId: oldOwnerId, pid: oldPid, createdAt: this.now() },
 			this.fsImpl,
 		);
-		if ((await this.signalCapturedOwner(capturedOwner, fp, chatId, "SIGTERM")) === "ownership_changed") {
+		const signalResult = attestedLegacyOwner
+			? await this.#signalAttestedLegacyOwner(attestedLegacyOwner, fp, chatId, "SIGTERM")
+			: await this.signalCapturedOwner(modernCapturedOwner!, fp, chatId, "SIGTERM");
+		if (signalResult === "hard_termination") {
+			await this.clearOwnRequest(requestId);
+			return this.result(
+				action,
+				false,
+				"telegram daemon has hard process authority; refusing cooperative SIGTERM",
+				before,
+				await this.status(),
+				warnings,
+			);
+		}
+		if (signalResult === "ownership_changed") {
 			await this.clearOwnRequest(requestId);
 			return this.result(
 				action,
@@ -559,7 +658,9 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 			// the captured owner/pid still matches, so we never kill a different owner.
 			const stillSameOwner = current !== undefined && current.ownerId === oldOwnerId && current.pid === oldPid;
 			if (opts.force && stillSameOwner) {
-				const killResult = await this.signalCapturedOwner(capturedOwner, fp, chatId, "SIGKILL");
+				const killResult = attestedLegacyOwner
+					? await this.#signalAttestedLegacyOwner(attestedLegacyOwner, fp, chatId, "SIGKILL")
+					: await this.signalCapturedOwner(modernCapturedOwner!, fp, chatId, "SIGKILL");
 				// Kill only a still-live matching owner; an owner that exited between the
 				// graceful timeout and this recheck ("already_gone") is confirmed dead by
 				// waitForPidDeath, while a real ownership change stays fenced.
@@ -585,6 +686,17 @@ export class TelegramDaemonController implements BuiltInDaemonController {
 			return this.result(action, true, "stopped telegram daemon", before, after, warnings);
 		}
 
+		if (!this.#currentConfigurationMatches(fp, chatId)) {
+			const after = await this.status();
+			return this.result(
+				action,
+				false,
+				"telegram notification configuration changed during reload; refusing to spawn",
+				before,
+				after,
+				warnings,
+			);
+		}
 		const { spawned, ready } = await this.spawnAndWait(roots, fp, chatId);
 		warnings.push(...spawned.warnings);
 		const after = await this.status();