@gajae-code/coding-agent 0.14.2 → 0.15.0

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

@@ -146,6 +146,74 @@ const dirFor = (agentDir: string) => path.join(agentDir, "sdk", "sessions");
 const logFor = (agentDir: string) => path.join(dirFor(agentDir), "index.jsonl");
 const snapshotFor = (agentDir: string) => path.join(dirFor(agentDir), "index.snapshot.json");
 const auditFor = (agentDir: string) => path.join(dirFor(agentDir), "index-audit.jsonl");
+/**
+ * Idle-poll change stamp over the two index files (#4689). A polling reader
+ * that has already replayed the index must be able to prove "nothing changed"
+ * with two stats instead of re-acquiring the machine-global lock and
+ * re-parsing the whole log every cycle.
+ *
+ * Timestamps alone are NOT a durable-equality proof: on a coarse-resolution
+ * filesystem a same-size write inside one tick reports identical `mtimeMs` and
+ * `ctimeMs` (measured: ~98% of back-to-back same-size rewrites collide on
+ * both). The stamp is therefore anchored on the two fields the cooperative
+ * writer protocol cannot leave untouched:
+ *   - append (`appendSync`) always grows `size`;
+ *   - rename-replace (`replaceAtomically`, used for snapshots and rotation)
+ *     always installs a new inode, so `ino` changes even when the replacement
+ *     has an identical byte length (measured: 0/3000 inode collisions).
+ * `mtimeMs`/`ctimeMs` are retained as an extra signal for foreign in-place
+ * edits that keep both size and inode, which the writer protocol never does.
+ */
+interface SessionIndexFileStamp {
+	readonly exists: boolean;
+	readonly size: number;
+	/**
+	 * Kept as `bigint` so a 64-bit inode / Windows file id above
+	 * `Number.MAX_SAFE_INTEGER` cannot collapse onto another id and make a real
+	 * replacement read as unchanged (#4730 review).
+	 */
+	readonly ino: bigint;
+	readonly mtimeMs: number;
+	readonly ctimeMs: number;
+}
+interface SessionIndexChangeStamp {
+	readonly log: SessionIndexFileStamp;
+	readonly snapshot: SessionIndexFileStamp;
+}
+async function statIndexFile(file: string): Promise<SessionIndexFileStamp> {
+	try {
+		const stat = await fs.stat(file, { bigint: true });
+		return {
+			exists: true,
+			size: Number(stat.size),
+			ino: stat.ino,
+			mtimeMs: Number(stat.mtimeMs),
+			ctimeMs: Number(stat.ctimeMs),
+		};
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT")
+			return { exists: false, size: 0, ino: 0n, mtimeMs: 0, ctimeMs: 0 };
+		throw error;
+	}
+}
+async function readIndexChangeStamp(agentDir: string): Promise<SessionIndexChangeStamp> {
+	const [log, snapshot] = await Promise.all([statIndexFile(logFor(agentDir)), statIndexFile(snapshotFor(agentDir))]);
+	return { log, snapshot };
+}
+function sameIndexChangeStamp(a: SessionIndexChangeStamp, b: SessionIndexChangeStamp): boolean {
+	return (
+		a.log.exists === b.log.exists &&
+		a.log.size === b.log.size &&
+		a.log.ino === b.log.ino &&
+		a.log.mtimeMs === b.log.mtimeMs &&
+		a.log.ctimeMs === b.log.ctimeMs &&
+		a.snapshot.exists === b.snapshot.exists &&
+		a.snapshot.size === b.snapshot.size &&
+		a.snapshot.ino === b.snapshot.ino &&
+		a.snapshot.mtimeMs === b.snapshot.mtimeMs &&
+		a.snapshot.ctimeMs === b.snapshot.ctimeMs
+	);
+}
 const ROTATE_BYTES = 4 * 1024 * 1024;
 /** Coalesced heartbeat checkpoint rate cap (C2): at most one per session per minute. */
 export const SESSION_HEARTBEAT_INTERVAL_MS = 60_000;
@@ -723,35 +791,60 @@ async function syncDirectory(file: string): Promise<void> {
 		if (process.platform === "win32" && (code === "EPERM" || code === "EACCES")) return;
 		throw error;
 	}
+	let syncError: unknown;
 	try {
 		await handle.sync();
 	} catch (error) {
 		const code = (error as NodeJS.ErrnoException).code;
-		if (process.platform !== "win32" || (code !== "EPERM" && code !== "EACCES")) throw error;
-	} finally {
+		if (process.platform !== "win32" || (code !== "EPERM" && code !== "EACCES")) syncError = error;
+	}
+	try {
 		await handle.close();
+	} catch (closeError) {
+		if (syncError) throw new AggregateError([syncError, closeError], "session-index directory sync and close failed");
+		throw closeError;
 	}
+	if (syncError) throw syncError;
 }
 
 async function writeAndSync(file: string, contents: Buffer | string): Promise<void> {
 	const handle = await fs.open(file, "w", 0o600);
+	let writeError: unknown;
 	try {
 		await handle.writeFile(contents);
 		await handle.sync();
-	} finally {
+	} catch (error) {
+		writeError = error;
+	}
+	try {
 		await handle.close();
+	} catch (closeError) {
+		if (writeError) throw new AggregateError([writeError, closeError], "session-index write and close failed");
+		throw closeError;
 	}
+	if (writeError) throw writeError;
 }
 
 async function replaceAtomically(file: string, contents: Buffer | string): Promise<void> {
 	const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+	let primaryError: unknown;
 	try {
 		await writeAndSync(temporary, contents);
 		await fs.rename(temporary, file);
 		await syncDirectory(file);
-	} finally {
+	} catch (error) {
+		primaryError = error;
+	}
+	let cleanupError: unknown;
+	try {
 		await fs.rm(temporary, { force: true });
+	} catch (error) {
+		cleanupError = error;
 	}
+	if (primaryError && cleanupError)
+		throw new AggregateError([primaryError, cleanupError], "session-index replace and cleanup failed");
+	if (primaryError) throw primaryError;
+	if (cleanupError) throw cleanupError;
 }
 
 function alive(pid: number): boolean {
@@ -788,6 +881,11 @@ export class SessionIndex {
 	#warnings: string[] = [];
 	#logOffset = 0;
 	#corruptSuffix = false;
+	/**
+	 * Last change stamp observed by a completed locked pass (#4689); lets the
+	 * polling refresh path prove "index unchanged" with two stats.
+	 */
+	#changeStamp: SessionIndexChangeStamp | undefined;
 	/** indexSeqs already recorded in the durable audit; null until lazily seeded. */
 	#auditedSeq: Set<number> | null = null;
 	constructor(agentDir: string, policy: RetentionPolicy = {}) {
@@ -836,6 +934,77 @@ export class SessionIndex {
 			withSessionIndexLock("replay", this.#agentDir, () => this.#replayUnderLock()),
 		);
 	}
+	/**
+	 * Polling-path refresh (#4689): when both index files carry the exact change
+	 * stamp of the last completed locked pass, the in-memory projection is
+	 * already current and the locked rescan is skipped entirely — this is what
+	 * keeps an idle SessionRouter reconcile (2s cadence) from re-parsing and
+	 * re-checksumming the whole index forever. An append committed before the
+	 * stat always changes the stamp, so a miss is impossible; a change landing
+	 * after the stat is seen on the next poll, the same TOCTOU envelope a
+	 * locked read has. A corrupt suffix never takes the fast path: re-scanning
+	 * preserves the existing re-diagnosis behavior. Returns true when state was
+	 * reloaded. Authority revalidation that needs the strongest available
+	 * snapshot inside an already-locked write (append, unregister) keeps using
+	 * the exact locked paths.
+	 */
+	async refreshIfChanged(): Promise<boolean> {
+		if (this.#changeStamp !== undefined && !this.#corruptSuffix) {
+			const stamp = await readIndexChangeStamp(this.#agentDir);
+			if (sameIndexChangeStamp(this.#changeStamp, stamp)) return false;
+			// A possible change is re-classified UNDER the lock (#4689 review):
+			// writers mutate these files only while holding it, so the locked
+			// observation is atomic with the tail/replay it selects. The
+			// unlocked stamp above is only the cheap "definitely unchanged" cut.
+			const indexPath = path.resolve(logFor(this.#agentDir));
+			await SessionIndex.#enqueue(indexPath, () =>
+				withSessionIndexLock("poll-refresh", this.#agentDir, () => this.#refreshOrReplayUnderLock()),
+			);
+			return true;
+		}
+		await this.open();
+		await this.refresh();
+		return true;
+	}
+	/**
+	 * Locked change classification (#4689). Append-only log growth with an
+	 * untouched snapshot tails from the last offset; anything else — in-place
+	 * rewrite, truncation, rotation, snapshot replacement, existence
+	 * transitions, or an append/compact interleaving that outran the unlocked
+	 * pre-check — takes the full replay. Metadata cannot prove prefix identity
+	 * against a writer that rewrites history in place while growing the file;
+	 * that boundary is the cooperative locked-writer protocol, which never
+	 * does that (appendSync, or rename-replace with a fresh snapshot).
+	 */
+	async #refreshOrReplayUnderLock(): Promise<void> {
+		const stamp = await readIndexChangeStamp(this.#agentDir);
+		const prior = this.#changeStamp;
+		// Append-only growth with an untouched snapshot tails from the last
+		// offset; anything else replays in full.
+		// The inode is load-bearing on BOTH files here (#4730 review): tailing is
+		// only sound if this is the SAME log file grown in place and the SAME
+		// snapshot file. A rename-over installs a new inode while size and
+		// timestamps can all still match, so without these two comparisons a log
+		// that grew while the snapshot was replaced by a same-size, same-timestamp
+		// file would be misclassified as append-only, and the reader would tail
+		// from its last offset while caching a stale compacted projection.
+		if (
+			prior?.log.exists &&
+			stamp.log.exists &&
+			stamp.log.ino === prior.log.ino &&
+			stamp.log.size > prior.log.size &&
+			stamp.snapshot.exists === prior.snapshot.exists &&
+			stamp.snapshot.ino === prior.snapshot.ino &&
+			stamp.snapshot.size === prior.snapshot.size &&
+			stamp.snapshot.mtimeMs === prior.snapshot.mtimeMs &&
+			stamp.snapshot.ctimeMs === prior.snapshot.ctimeMs
+		)
+			await this.#tailUnderLock();
+		else await this.#replayUnderLock();
+		// #replayUnderLock recaptures the stamp itself; the tail path needs it
+		// captured here (refresh() does this via #refreshUnderLock).
+		this.#changeStamp = await readIndexChangeStamp(this.#agentDir);
+	}
 	async #replayUnderLock(): Promise<void> {
 		const scan = await this.#scan();
 		if (scan.diagnosis.status === "unsupported") throw scan.unsupportedError!;
@@ -846,6 +1015,7 @@ export class SessionIndex {
 		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");
 		await this.#writeAuditUnderLock();
+		this.#changeStamp = await readIndexChangeStamp(this.#agentDir);
 	}
 	/** Seed the audit dedupe set once, then append records for newly-rejected events. */
 	async #writeAuditUnderLock(): Promise<void> {
@@ -1032,43 +1202,44 @@ export class SessionIndex {
 		const indexPath = path.resolve(logFor(this.#agentDir));
 		return await SessionIndex.#enqueue(indexPath, async () => {
 			await fs.mkdir(dirFor(this.#agentDir), { recursive: true, mode: 0o700 });
-			return await withSessionIndexLock("repair", 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"));
-				// Repair republishes the surviving history as the new snapshot, so it must
-				// apply the same retention the ordinary snapshot path applies. Writing the
-				// raw survivor set instead let one repair of a long-lived index restore an
-				// unbounded snapshot, and every later locked transaction then re-parsed that
-				// whole history while holding the index lock — the broker burns CPU and
-				// unrelated launches time out waiting for the lock.
-				const events = compactEvents([...scan.snapshotEvents, ...scan.validLogEvents], this.#policy);
-				const snapshot = JSON.stringify({
-					version: SESSION_INDEX_SNAPSHOT_VERSION,
-					indexSeq: scan.diagnosis.validPrefixSeq,
-					events,
-				});
-				await replaceAtomically(snapshotFor(this.#agentDir), snapshot);
-				// The republished snapshot already carries the full surviving history (after
-				// compaction), so the log must be truncated to match: leaving the original
-				// events in place keeps every subsequent #scan() parsing them under the lock
-				// — the same starvation the compaction above is meant to end. This mirrors
-				// #rotate(), which writes an empty log after snapshotting.
-				await replaceAtomically(logFor(this.#agentDir), "");
-				await this.#replayUnderLock();
-				return { ...scan.diagnosis, repaired: true, quarantinePath };
-			});
+			return await withSessionIndexLock("repair", this.#agentDir, async () => await this.#repairUnderLock());
+		});
+	}
+	async #repairUnderLock(): Promise<SessionIndexRepairResult> {
+		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"));
+		// Repair republishes the surviving history as the new snapshot, so it must
+		// apply the same retention the ordinary snapshot path applies. Writing the
+		// raw survivor set instead let one repair of a long-lived index restore an
+		// unbounded snapshot, and every later locked transaction then re-parsed that
+		// whole history while holding the index lock — the broker burns CPU and
+		// unrelated launches time out waiting for the lock.
+		const events = compactEvents([...scan.snapshotEvents, ...scan.validLogEvents], this.#policy);
+		const snapshot = JSON.stringify({
+			version: SESSION_INDEX_SNAPSHOT_VERSION,
+			indexSeq: scan.diagnosis.validPrefixSeq,
+			events,
 		});
+		await replaceAtomically(snapshotFor(this.#agentDir), snapshot);
+		// The republished snapshot already carries the full surviving history (after
+		// compaction), so the log must be truncated to match: leaving the original
+		// events in place keeps every subsequent #scan() parsing them under the lock
+		// — the same starvation the compaction above is meant to end. This mirrors
+		// #rotate(), which writes an empty log after snapshotting.
+		await replaceAtomically(logFor(this.#agentDir), "");
+		await this.#replayUnderLock();
+		return { ...scan.diagnosis, repaired: true, quarantinePath };
 	}
 	async #tailUnderLock(snapshotSeq = this.indexSeq, allowResync = true): Promise<void> {
 		let data: Buffer;
@@ -1129,8 +1300,15 @@ export class SessionIndex {
 		);
 	}
 	async #refreshUnderLock(): Promise<void> {
-		await this.#tailUnderLock();
+		// A newly constructed reader has no replay cursor. Refresh must still load
+		// snapshot-carried authority before tailing the empty log; otherwise a cold
+		// router starting after compaction projects no sessions until a later append.
+		if (this.#events.length === 0 && this.#logOffset === 0) await this.#replayUnderLock();
+		else await this.#tailUnderLock();
 		await this.#writeAuditUnderLock();
+		// #tailUnderLock may delegate to #replayUnderLock (which re-captures);
+		// capturing here covers the tail-only and missing-log paths.
+		this.#changeStamp = await readIndexChangeStamp(this.#agentDir);
 	}
 	get indexSeq(): number {
 		return this.#events.at(-1)?.indexSeq ?? 0;
@@ -1156,10 +1334,25 @@ export class SessionIndex {
 				ownIncarnation = input.processIncarnation ?? processIncarnation(input.pid);
 			return await withSessionIndexLock("append", this.#agentDir, async () => {
 				await this.#replayUnderLock();
-				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",
+				if (this.#corruptSuffix) {
+					// A corrupt suffix used to hard-fail every append until a human ran
+					// `gjc gc --repair-session-index` — but the writers that corrupt the
+					// log (typically a stale long-lived broker signing events against an
+					// outdated in-memory indexSeq) keep appending, so the operator-run
+					// repair was re-corrupted within minutes and delegated session
+					// launches stayed dead indefinitely. Run the same quarantine-backed
+					// repair inline instead: evidence is preserved under
+					// sessions/quarantine, the valid prefix is republished, and this
+					// append proceeds against the repaired index.
+					const repair = await this.#repairUnderLock();
+					if (this.#corruptSuffix)
+						throw new Error(
+							"Cannot append to corrupt session index log; automatic repair did not converge — run `gjc gc --repair-session-index` to quarantine evidence and retain the valid prefix",
+						);
+					logger.warn(
+						`sdk broker: session index self-repaired before append (${repair.reason ?? "corrupt suffix"}); evidence quarantined at ${repair.quarantinePath ?? "unknown"}`,
 					);
+				}
 				const unsigned: Omit<SessionIndexEvent, "checksum"> = {
 					...input,
 					version: SDK_STATE_VERSION,
@@ -1325,11 +1518,13 @@ export class SessionIndex {
 	async #rotate(): Promise<void> {
 		await this.#snapshotUnderLock();
 		const file = logFor(this.#agentDir);
-		const temporary = `${file}.${process.pid}.tmp`;
-		await fs.writeFile(temporary, "", { mode: 0o600 });
-		await fs.rename(temporary, file);
-		await syncDirectory(file);
+		await replaceAtomically(file, "");
 		this.#logOffset = 0;
+		// Sync in-memory state with the compacted snapshot while the lock is
+		// held: without this the instance keeps pre-compaction events and a
+		// fresh change stamp, so later refreshIfChanged() polls would never
+		// observe the compaction (#4689 review).
+		await this.#replayUnderLock();
 	}
 
 	listSessions(): SessionList {

package/src/sdk/broker/transport.ts

@@ -17,6 +17,7 @@ const BROKER_OPERATIONS = new Set([
 	"broker.shutdown",
 	"session.control",
 	"broker.lookup_lifecycle",
+	"model.resolve",
 ]);
 type RequestInput = Record<string, unknown>;
 type BrokerRequest = {

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

@@ -124,10 +124,16 @@ export type ChatDaemonAction = "stop" | "reload";
  * Discord generation 65 / Slack generation 68 fence the off-reconcile-tail
  * initial attachment replay introduced by #4542 so pre-upgrade daemon owners
  * cannot retain the earlier SessionRouter attachment contract.
+ * The Discord 67 / Slack 70 fence covers the SessionRouter idle-poll/change-stamp
+ * rollout (#4689). Both daemons construct a
+ * SessionRouter whose idle tick no longer re-acquires the machine-global
+ * session-index lock every 2s; staleness retirement moved to a 30s sweep and
+ * lease heartbeats no longer force an authority reconcile. A pre-upgrade owner
+ * would retain the old hot polling loop, so replacement is required.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 66,
-	slack: 69,
+	discord: 67,
+	slack: 70,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

package/src/sdk/bus/chat-daemon-runtime.ts

@@ -365,6 +365,11 @@ export class ChatDaemonRuntime {
 		return this.#transportHealthy?.() ?? false;
 	}
 
+	/** Reconcile indexed attachments and optionally wait for their replay tails. */
+	async reconcile(options: { waitForReplay?: boolean } = {}): Promise<void> {
+		await this.#router.reconcile(options);
+	}
+
 	async stop(): Promise<void> {
 		const providerResults = await Promise.allSettled([this.#discord?.stop(), this.#slack?.stop()]);
 		const discordRestartBlocked = this.#discord?.restartBlocked() ?? false;