@gajae-code/coding-agent 0.11.2 → 0.11.4

package/src/sdk/broker/session-index.ts

@@ -1,4 +1,4 @@
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import * as fs from "node:fs/promises";
 import path from "node:path";
 import { withFileLock } from "../../config/file-lock";
@@ -48,6 +48,27 @@ export interface SessionList {
 	sessions: IndexedSession[];
 	warnings: string[];
 }
+
+export interface SessionIndexDiagnosis {
+	status: "healthy" | "corrupt" | "unsupported";
+	validPrefixSeq: number;
+	snapshotSeq: number;
+	reason?: string;
+}
+
+export interface SessionIndexRepairResult extends SessionIndexDiagnosis {
+	repaired: boolean;
+	quarantinePath?: string;
+}
+
+interface SessionIndexScan {
+	diagnosis: SessionIndexDiagnosis;
+	snapshotEvents: SessionIndexEvent[];
+	validLogEvents: SessionIndexEvent[];
+	snapshotContents: Buffer | undefined;
+	logContents: Buffer | undefined;
+	unsupportedError?: UnsupportedStateVersionError;
+}
 const canonical = (event: Omit<SessionIndexEvent, "checksum">) => JSON.stringify(event);
 export const sessionIndexChecksum = (event: Omit<SessionIndexEvent, "checksum">) =>
 	createHash("sha256").update(canonical(event)).digest("hex");
@@ -142,6 +163,27 @@ async function syncDirectory(file: string): Promise<void> {
 	}
 }
 
+async function writeAndSync(file: string, contents: Buffer | string): Promise<void> {
+	const handle = await fs.open(file, "w", 0o600);
+	try {
+		await handle.writeFile(contents);
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
+
+async function replaceAtomically(file: string, contents: Buffer | string): Promise<void> {
+	const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+	try {
+		await writeAndSync(temporary, contents);
+		await fs.rename(temporary, file);
+		await syncDirectory(file);
+	} finally {
+		await fs.rm(temporary, { force: true });
+	}
+}
+
 function alive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -166,26 +208,194 @@ export class SessionIndex {
 		return this;
 	}
 	async replay(): Promise<void> {
-		this.#events = [];
+		const scan = await this.#scan();
+		if (scan.diagnosis.status === "unsupported") throw scan.unsupportedError!;
+		this.#events = [...scan.snapshotEvents, ...scan.validLogEvents];
 		this.#warnings = [];
-		this.#logOffset = 0;
-		this.#corruptSuffix = false;
+		this.#logOffset = scan.logContents?.length ?? 0;
+		this.#corruptSuffix = scan.diagnosis.status === "corrupt";
+		if (scan.diagnosis.reason === "invalid snapshot") this.#warnings.push("Invalid session index snapshot");
+		if (this.#corruptSuffix) this.#warnings.push("Corrupt session index entry; replay truncated");
+	}
+	async #scan(): Promise<SessionIndexScan> {
+		let snapshotContents: Buffer | undefined;
+		let logContents: Buffer | undefined;
+		let snapshotEvents: SessionIndexEvent[] = [];
 		let snapshotSeq = 0;
+		let trustedSnapshotSeq = 0;
+		let invalidSnapshot = false;
+		let unsupportedError: UnsupportedStateVersionError | undefined;
 		try {
-			const snapshot = JSON.parse(await fs.readFile(snapshotFor(this.#agentDir), "utf8")) as {
+			snapshotContents = await fs.readFile(snapshotFor(this.#agentDir));
+			const snapshot = JSON.parse(snapshotContents.toString("utf8")) as {
 				version?: number;
-				events?: SessionIndexEvent[];
-				indexSeq?: number;
+				indexSeq?: unknown;
+				events?: unknown;
 			};
+			if (typeof snapshot.indexSeq === "number" && Number.isSafeInteger(snapshot.indexSeq) && snapshot.indexSeq >= 0)
+				snapshotSeq = snapshot.indexSeq;
 			assertSupportedSnapshotVersion(snapshotFor(this.#agentDir), snapshot);
-			if (!isValidSnapshot(snapshot)) throw new Error("invalid snapshot");
-			this.#events = snapshot.events;
-			snapshotSeq = snapshot.indexSeq;
-		} catch (e) {
-			if (e instanceof UnsupportedStateVersionError) throw e;
-			if ((e as NodeJS.ErrnoException).code !== "ENOENT") this.#warnings.push("Invalid session index snapshot");
+			const supportedEvents: SessionIndexEvent[] = [];
+			if (Array.isArray(snapshot.events)) {
+				try {
+					for (const event of snapshot.events) {
+						assertSupportedStateVersion(snapshotFor(this.#agentDir), event);
+						supportedEvents.push(event as SessionIndexEvent);
+					}
+				} catch (error) {
+					if (!(error instanceof UnsupportedStateVersionError)) throw error;
+					unsupportedError = error;
+					snapshotEvents = supportedEvents;
+				}
+			}
+			if (!unsupportedError) {
+				if (!isValidSnapshot(snapshot)) invalidSnapshot = true;
+				else {
+					snapshotEvents = snapshot.events;
+					trustedSnapshotSeq = snapshot.indexSeq;
+				}
+			}
+		} catch (error) {
+			if (error instanceof UnsupportedStateVersionError) unsupportedError = error;
+			else if ((error as NodeJS.ErrnoException).code !== "ENOENT") invalidSnapshot = true;
+		}
+		try {
+			logContents = await fs.readFile(logFor(this.#agentDir));
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+		const validLogEvents: SessionIndexEvent[] = [];
+		let corrupt = invalidSnapshot;
+		let logCorrupt = false;
+		let tailStarted = false;
+		let historicalLast: number | undefined;
+		let expected = trustedSnapshotSeq + 1;
+		if (logContents) {
+			const text = logContents.toString("utf8");
+			const lines = text.split("\n");
+			const terminal = lines.pop();
+			for (const line of lines) {
+				if (!line) continue;
+				try {
+					const event = JSON.parse(line) as SessionIndexEvent;
+					assertSupportedStateVersion(logFor(this.#agentDir), event);
+					const { checksum, ...unsigned } = event;
+					if (checksum !== sessionIndexChecksum(unsigned)) {
+						corrupt = true;
+						logCorrupt = true;
+						continue;
+					}
+					if (!tailStarted && !invalidSnapshot && event.indexSeq <= trustedSnapshotSeq) {
+						if (
+							!Number.isSafeInteger(event.indexSeq) ||
+							event.indexSeq <= 0 ||
+							(historicalLast !== undefined && event.indexSeq !== historicalLast + 1)
+						) {
+							corrupt = true;
+							logCorrupt = true;
+						} else {
+							historicalLast = event.indexSeq;
+						}
+						continue;
+					}
+					tailStarted = true;
+					if (historicalLast !== undefined && historicalLast !== trustedSnapshotSeq) {
+						corrupt = true;
+						logCorrupt = true;
+					}
+					if (event.indexSeq !== expected) {
+						corrupt = true;
+						logCorrupt = true;
+					} else if (!logCorrupt) {
+						validLogEvents.push(event);
+						expected++;
+					}
+				} catch (error) {
+					if (error instanceof UnsupportedStateVersionError) {
+						const verifiedSnapshotPrefix = snapshotEvents.at(-1)?.indexSeq ?? trustedSnapshotSeq;
+						const validPrefixSeq = validLogEvents.at(-1)?.indexSeq ?? verifiedSnapshotPrefix;
+						return {
+							diagnosis: { status: "unsupported", validPrefixSeq, snapshotSeq, reason: error.message },
+							snapshotEvents,
+							validLogEvents,
+							snapshotContents,
+							logContents,
+							unsupportedError: error,
+						};
+					}
+					corrupt = true;
+					logCorrupt = true;
+				}
+			}
+			if (historicalLast !== undefined && !tailStarted && historicalLast !== trustedSnapshotSeq) {
+				corrupt = true;
+				logCorrupt = true;
+			}
+			if (terminal !== "") {
+				corrupt = true;
+				logCorrupt = true;
+			}
 		}
-		await this.#tail(snapshotSeq, false);
+		const verifiedSnapshotPrefix = snapshotEvents.at(-1)?.indexSeq ?? trustedSnapshotSeq;
+		const validPrefixSeq = validLogEvents.at(-1)?.indexSeq ?? verifiedSnapshotPrefix;
+		return {
+			diagnosis: {
+				status: unsupportedError ? "unsupported" : corrupt ? "corrupt" : "healthy",
+				validPrefixSeq,
+				snapshotSeq,
+				reason:
+					unsupportedError?.message ??
+					(invalidSnapshot ? "invalid snapshot" : corrupt ? "invalid log sequence" : undefined),
+			},
+			snapshotEvents,
+			validLogEvents,
+			snapshotContents,
+			logContents,
+			unsupportedError,
+		};
+	}
+	async diagnose(): Promise<SessionIndexDiagnosis> {
+		const exists = await Promise.all(
+			[snapshotFor(this.#agentDir), logFor(this.#agentDir)].map(async file => {
+				try {
+					await fs.stat(file);
+					return true;
+				} catch (error) {
+					if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+					throw error;
+				}
+			}),
+		);
+		if (!exists.some(Boolean)) return { status: "healthy", validPrefixSeq: 0, snapshotSeq: 0 };
+		return await withFileLock(logFor(this.#agentDir), async () => (await this.#scan()).diagnosis);
+	}
+	async repair(): Promise<SessionIndexRepairResult> {
+		await fs.mkdir(dirFor(this.#agentDir), { recursive: true, mode: 0o700 });
+		return await withFileLock(logFor(this.#agentDir), async () => {
+			const scan = await this.#scan();
+			if (scan.diagnosis.status === "unsupported") return { ...scan.diagnosis, repaired: false };
+			if (scan.diagnosis.status === "healthy") return { ...scan.diagnosis, repaired: false };
+			const quarantineBase = path.join(dirFor(this.#agentDir), "quarantine");
+			await fs.mkdir(quarantineBase, { recursive: true, mode: 0o700 });
+			await syncDirectory(quarantineBase);
+			const quarantinePath = path.join(quarantineBase, `repair-${Date.now()}-${process.pid}-${randomUUID()}`);
+			await fs.mkdir(quarantinePath, { mode: 0o700 });
+			await syncDirectory(quarantinePath);
+			if (scan.snapshotContents)
+				await writeAndSync(path.join(quarantinePath, "index.snapshot.json"), scan.snapshotContents);
+			if (scan.logContents) await writeAndSync(path.join(quarantinePath, "index.jsonl"), scan.logContents);
+			await syncDirectory(path.join(quarantinePath, "index.jsonl"));
+			const snapshot = JSON.stringify({
+				version: SESSION_INDEX_SNAPSHOT_VERSION,
+				indexSeq: scan.snapshotEvents.at(-1)?.indexSeq ?? 0,
+				events: scan.snapshotEvents,
+			});
+			const log = scan.validLogEvents.map(event => JSON.stringify(event)).join("\n");
+			await replaceAtomically(snapshotFor(this.#agentDir), snapshot);
+			await replaceAtomically(logFor(this.#agentDir), log ? `${log}\n` : "");
+			await this.replay();
+			return { ...scan.diagnosis, repaired: true, quarantinePath };
+		});
 	}
 	async #tail(snapshotSeq = this.indexSeq, allowResync = true): Promise<void> {
 		let data: Buffer;
@@ -252,7 +462,10 @@ export class SessionIndex {
 		await fs.mkdir(dirFor(this.#agentDir), { recursive: true, mode: 0o700 });
 		return withFileLock(logFor(this.#agentDir), async () => {
 			await this.replay();
-			if (this.#corruptSuffix) throw new Error("Cannot append to corrupt session index log");
+			if (this.#corruptSuffix)
+				throw new Error(
+					"Cannot append to corrupt session index log; run `gjc gc --repair-session-index` to quarantine evidence and retain the valid prefix",
+				);
 			const unsigned: Omit<SessionIndexEvent, "checksum"> = {
 				...input,
 				version: SDK_STATE_VERSION,

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

@@ -13,8 +13,11 @@ export class UnsupportedStateVersionError extends Error {
 	constructor(
 		readonly file: string,
 		readonly version: number,
+		readonly maximumSupportedVersion = SDK_STATE_VERSION,
 	) {
-		super(`Unsupported SDK state version ${version} in ${file}; maximum supported version is ${SDK_STATE_VERSION}.`);
+		super(
+			`Unsupported SDK state version ${version} in ${file}; maximum supported version is ${maximumSupportedVersion}.`,
+		);
 		this.name = "UnsupportedStateVersionError";
 	}
 }
@@ -38,7 +41,7 @@ export function assertSupportedSnapshotVersion(file: string, value: unknown): vo
 	const record = value as { version?: unknown; stateVersion?: unknown };
 	for (const version of [record.version, record.stateVersion]) {
 		if (typeof version === "number" && Number.isFinite(version) && version > SESSION_INDEX_SNAPSHOT_VERSION) {
-			throw new UnsupportedStateVersionError(file, version);
+			throw new UnsupportedStateVersionError(file, version, SESSION_INDEX_SNAPSHOT_VERSION);
 		}
 	}
 }

package/src/sdk/bus/index.ts

@@ -2741,6 +2741,8 @@ export function createNotificationsExtension(
 		/** Suppress auto-delivery for a GJC-spawned child under `sessionScope=primary`. */
 		spawnedByGjc?: boolean;
 		controller?: NotificationSessionController;
+		/** Whether this host mode can own the root SDK endpoint. Default: true. */
+		sdkHostModeSupported?: boolean;
 
 		onSdkRequest?: (kind: "control" | "query", connectionId: string, frame: Record<string, unknown>) => void;
 		runEphemeralTurn?: (promptText: string, signal: AbortSignal) => Promise<{ replyText: string }>;
@@ -2956,7 +2958,8 @@ export function createNotificationsExtension(
 		const lifecycleRequestId = safeLifecycleRequestId(process.env.GJC_LIFECYCLE_REQUEST_ID);
 		const { settings, cfg, settingsAvailable } = resolveSettings(options.settings);
 		const notificationsEnabledForSession = controller.query(ctx).effectiveEnabled;
-		const sdkEnabledForSession = shouldHostSdk(settings, isNotificationEligibleContext(ctx));
+		const sdkEnabledForSession =
+			(options.sdkHostModeSupported ?? true) && shouldHostSdk(settings, isNotificationEligibleContext(ctx));
 		const lifecycleRequired = lifecycleStartupCapability !== undefined;
 		const failLifecycleStartup = (
 			reason: "disabled" | "ineligible" | "failed",

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

@@ -1293,6 +1293,20 @@ export interface DaemonControlHooks {
 	clear?(ownerId: string): Promise<void>;
 }
 
+type BtwTerminalDeliveryOutcome = "accepted" | "not_delivered" | "uncertain" | "partial_accepted" | "stale";
+
+interface BtwTerminalDeliveryReceipt {
+	requestId: string;
+	logicalSessionId: string;
+	transportSessionId: string;
+	threadId: string;
+	updateId: number;
+	messageId: number;
+	outcome: BtwTerminalDeliveryOutcome;
+}
+
+const BTW_TERMINAL_DELIVERY_TEST_OBSERVER = Symbol.for("gjc.test.btw-terminal-delivery-observer");
+
 export interface TelegramDaemonOptions {
 	settings: Settings;
 	ownerId: string;
@@ -3958,6 +3972,7 @@ export class TelegramNotificationDaemon {
 			};
 			this.#btwTerminalDeliveries.set(requestId, terminalDelivery);
 			let deliveryOutcome: "accepted" | "not_delivered" | "uncertain" | "partial_accepted" = "not_delivered";
+			let observerOutcome: BtwTerminalDeliveryOutcome = deliveryOutcome;
 			try {
 				if (msg.status !== "ok") {
 					const text =
@@ -4023,7 +4038,7 @@ export class TelegramNotificationDaemon {
 					}
 				};
 				const html = markdownToTelegramHtml(markdown);
-				const fallback = async (): Promise<typeof deliveryOutcome> => {
+				const fallback = async (): Promise<BtwTerminalDeliveryOutcome> => {
 					let acceptedChunks = 0;
 					for (const [index, text] of splitTelegramHtml(html).entries()) {
 						const outcome = await this.#queueBtwFallbackChunk({
@@ -4045,6 +4060,7 @@ export class TelegramNotificationDaemon {
 							continue;
 						}
 						if (outcome === "partial_accepted" || acceptedChunks > 0) return "partial_accepted";
+						if (outcome === "stale") return "stale";
 						return outcome === "uncertain" ? "uncertain" : "not_delivered";
 					}
 					return "accepted";
@@ -4056,16 +4072,21 @@ export class TelegramNotificationDaemon {
 						reply_parameters: { message_id: pending.messageId },
 						rich_message: { markdown, skip_entity_detection: true },
 					});
-					deliveryOutcome =
-						outcome === "accepted"
-							? "accepted"
-							: outcome === "rejected"
-								? await fallback()
-								: outcome === "uncertain"
-									? "uncertain"
-									: "not_delivered";
+					if (outcome === "accepted") {
+						deliveryOutcome = "accepted";
+						observerOutcome = "accepted";
+					} else if (outcome === "rejected") {
+						const fallbackOutcome = await fallback();
+						observerOutcome = fallbackOutcome;
+						deliveryOutcome = fallbackOutcome === "stale" ? "not_delivered" : fallbackOutcome;
+					} else {
+						deliveryOutcome = outcome === "uncertain" ? "uncertain" : "not_delivered";
+						observerOutcome = outcome === "stale" ? "stale" : deliveryOutcome;
+					}
 				} else {
-					deliveryOutcome = await fallback();
+					const fallbackOutcome = await fallback();
+					observerOutcome = fallbackOutcome;
+					deliveryOutcome = fallbackOutcome === "stale" ? "not_delivered" : fallbackOutcome;
 				}
 			} finally {
 				if (this.#btwTerminalDeliveries.get(requestId) === terminalDelivery) {
@@ -4084,6 +4105,25 @@ export class TelegramNotificationDaemon {
 					}
 				} finally {
 					terminalDelivery.finish();
+					observerOutcome = observerOutcome === "stale" ? "stale" : deliveryOutcome;
+					if (this.#pendingBtwTurns.get(requestId) !== pending) {
+						try {
+							const observer = (
+								this as unknown as Record<symbol, ((receipt: BtwTerminalDeliveryReceipt) => void) | undefined>
+							)[BTW_TERMINAL_DELIVERY_TEST_OBSERVER];
+							observer?.({
+								requestId,
+								logicalSessionId: pending.logicalSessionId,
+								transportSessionId: pending.transportSessionId,
+								threadId: pending.threadId,
+								updateId: pending.updateId,
+								messageId: pending.messageId,
+								outcome: observerOutcome,
+							});
+						} catch {
+							logger.warn("notifications: /btw terminal delivery observer failed");
+						}
+					}
 				}
 			}
 			return;

package/src/sdk/host/host.ts

@@ -102,6 +102,7 @@ export class SessionSdkHost {
 	readonly reverse: ReverseLeaseRuntime;
 	readonly #options: SessionSdkHostOptions;
 	#started = false;
+	#stopPromise?: Promise<"stopped">;
 	#unsubscribe?: () => void;
 	#registration?: { writer: BrokerIndexWriter; generation: number };
 
@@ -154,16 +155,27 @@ export class SessionSdkHost {
 	}
 
 	async stop(): Promise<"stopped" | "already"> {
+		if (this.#stopPromise) return this.#stopPromise;
 		if (!this.#started) return "already";
+		const stopPromise = this.#stopStartedHost();
+		this.#stopPromise = stopPromise;
+		try {
+			return await stopPromise;
+		} finally {
+			if (this.#stopPromise === stopPromise) this.#stopPromise = undefined;
+		}
+	}
+
+	async #stopStartedHost(): Promise<"stopped"> {
 		this.#unsubscribe?.();
 		this.#unsubscribe = undefined;
-		this.#started = false;
 		if (this.#registration?.writer.unregister)
 			await this.#registration.writer.unregister({
 				sessionId: this.#options.sessionId,
 				stateRoot: this.#options.stateRoot,
 				endpointGeneration: this.events.generation,
 			});
+		this.#started = false;
 		return "stopped";
 	}
 

package/src/sdk/session.ts

@@ -390,6 +390,8 @@ export interface CreateAgentSessionOptions {
 	hasUI?: boolean;
 	/** Whether this host mode can own a notification session endpoint. Default: true. */
 	notificationHostModeSupported?: boolean;
+	/** Whether this host mode can own the root SDK endpoint. Default: true. */
+	sdkHostModeSupported?: boolean;
 
 	/**
 	 * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
@@ -1763,7 +1765,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 				currentAgentType: options.currentAgentType,
 				spawnedByGjc,
 			}) ||
-			shouldHostSdk(notificationCfg, isTopLevelSdkSession)
+			(shouldHostSdk(notificationCfg, isTopLevelSdkSession) && (options.sdkHostModeSupported ?? true))
 		) {
 			inlineExtensions.push(async api => {
 				try {
@@ -1774,6 +1776,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 						settings,
 						controller: notificationSessionController,
 						spawnedByGjc,
+						sdkHostModeSupported: options.sdkHostModeSupported,
 						runEphemeralTurn: async (promptText, signal) => {
 							if (!session) throw new Error("Ephemeral turns are unavailable.");
 							const { replyText } = await session.runEphemeralTurn({ promptText, signal });

package/src/session/internal/managed-session-scope.ts

@@ -99,6 +99,7 @@ export type ManagedDeleteCandidateResult =
 type NativeIdentity =
 	| { ok: true; platform: "posix" | "win32"; canonicalPath: string }
 	| { ok: false; code: NativeIdentityFailureCode };
+type CanonicalNativeIdentity = Extract<NativeIdentity, { ok: true }>;
 
 type NativeIdentityFailureCode =
 	| "not_found"
@@ -149,6 +150,18 @@ function identityFor(cwd: string): NativeIdentity {
 	return canonicalExistingDirectoryIdentity(cwd) as NativeIdentity;
 }
 
+function canonicalExistingPathForIo(base: string, identity: CanonicalNativeIdentity): string {
+	if (identity.platform !== "win32") return identity.canonicalPath;
+	try {
+		// Native identity uses a stable Volume GUID path on Windows. Bun 1.3.14
+		// cannot reliably create/read files through that path, so retain the
+		// symlink-resolved DOS path for JavaScript filesystem I/O.
+		return fs.realpathSync.native(base);
+	} catch {
+		return path.resolve(base);
+	}
+}
+
 /**
  * Resolve benign symlinks in the deepest existing ancestor of a trusted storage
  * root (e.g. macOS `/var -> /private/var`, or a symlinked `$HOME`) while keeping
@@ -164,7 +177,8 @@ export function canonicalizeTrustedPath(target: string): string {
 	for (;;) {
 		const identity = canonicalExistingDirectoryIdentity(base) as NativeIdentity;
 		if (identity.ok) {
-			return suffix.length === 0 ? identity.canonicalPath : path.join(identity.canonicalPath, ...suffix);
+			const canonicalBase = canonicalExistingPathForIo(base, identity);
+			return suffix.length === 0 ? canonicalBase : path.join(canonicalBase, ...suffix);
 		}
 		if (identity.code !== "not_found" && identity.code !== "not_directory") return path.resolve(target);
 		const parent = path.dirname(base);