@gajae-code/coding-agent 0.17.1 → 0.17.4

package/src/sdk/broker/runtime.ts

@@ -6,7 +6,7 @@ import { currentExecutablePath } from "@gajae-code/natives";
 
 import internalSourceMarker from "./internal-source-marker-2178.txt" with { type: "file" };
 
-export type SdkInternalAction = "broker-internal" | "session-host-internal";
+export type SdkInternalAction = "broker-internal" | "session-host-internal" | "stderr-drain-internal";
 
 export type SdkInternalSpawnCommand =
 	| {

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

@@ -5,6 +5,7 @@ import { logger, resolveEquivalentPath } from "@gajae-code/utils";
 import { nativeProcessBindings } from "@gajae-code/utils/native-process";
 import { withFileLock } from "../../config/file-lock";
 import { repo } from "../../utils/git";
+import { endpointIncarnation } from "./endpoint-authority";
 import { processIncarnation } from "./process-incarnation";
 import {
 	assertSupportedSessionIndexEventVersion,
@@ -26,7 +27,7 @@ export type SessionIndexEventType =
 	| "record_reconciled";
 
 export type SessionActivityState = "active" | "idle";
-/** Coalesced broker-owned heartbeat checkpoint (C2): state plus the observation time. */
+/** Host-reported or broker-coalesced heartbeat: state plus the observation time. */
 export interface SessionActivity {
 	state: SessionActivityState;
 	at: number;
@@ -34,6 +35,8 @@ export interface SessionActivity {
 /** Events persisted without an OS process incarnation (v1/v2 era) are legacy provenance. */
 export type SessionIdentityProvenance = "composite" | "legacy";
 export type SessionTombstoneRule = "retain" | "expire";
+/** Durable provenance for a retired host registration. */
+export type HostUnregisteredReason = "process_exited" | "detached_idle";
 /**
  * Injected retention policy (C3). The broker schedules compaction independently of
  * rotation; settings apply at the next scheduled compaction. `clock` drives both
@@ -141,6 +144,7 @@ export interface SessionIndexEvent {
 	/** Immutable endpoint file identity captured by the broker at registration. */
 	endpointFileId?: string;
 	lifecycleRequestId?: string;
+	hostUnregisteredReason?: HostUnregisteredReason;
 	terminalUncertain?: boolean;
 	/**
 	 * Distinguishes the terminal-uncertain claim written by a forced stop of a
@@ -170,6 +174,7 @@ export interface IndexedSession {
 	live: boolean;
 	indexSeq: number;
 	lifecycleRequestId?: string;
+	hostUnregisteredReason?: HostUnregisteredReason;
 	terminalUncertain?: boolean;
 	/** True only for a terminal-uncertain claim written by a forced stale-worktree release. */
 	forcedStaleRelease?: boolean;
@@ -345,6 +350,8 @@ function sameIndexChangeStamp(a: SessionIndexChangeStamp, b: SessionIndexChangeS
 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;
+/** A stale-host retirement requires silence well beyond the broker freshness window. */
+export const DEAD_HOST_HEARTBEAT_SILENCE_MS = 10 * SESSION_HEARTBEAT_INTERVAL_MS;
 export const DEFAULT_SESSION_RETENTION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 export const DEFAULT_SESSION_RETENTION_MAX_ROWS = 25_000;
 
@@ -571,6 +578,10 @@ function projectIdentity(
 	const { latest, heartbeat } = state;
 	const terminal = isTerminalEvent(latest);
 	const terminalUncertain = latest.type === "lifecycle_terminal" || latest.terminalUncertain === true;
+	const hostUnregisteredReason =
+		latest.hostUnregisteredReason === "process_exited" || latest.hostUnregisteredReason === "detached_idle"
+			? latest.hostUnregisteredReason
+			: undefined;
 	const pidAlive = alive(latest.pid);
 	// Liveness evidence is host-written: a checkpointed heartbeat, or the
 	// `host_registered` event the host appended itself. Counting registration
@@ -606,6 +617,7 @@ function projectIdentity(
 		endpointMtimeMs: latest.endpointMtimeMs,
 		endpointFileId: latest.endpointFileId,
 		lifecycleRequestId: latest.lifecycleRequestId,
+		...(hostUnregisteredReason === undefined ? {} : { hostUnregisteredReason }),
 		terminalUncertain,
 		...(latest.forcedStaleRelease === true ? { forcedStaleRelease: true } : {}),
 		indexSeq: latest.indexSeq,
@@ -1687,6 +1699,82 @@ export class SessionIndex {
 			});
 		});
 	}
+
+	/**
+	 * Atomically fence an exact, long-silent dead-host authority before a caller
+	 * removes state outside the broker index. The comparison and terminal event
+	 * append share the machine-global index lock, so a heartbeat, successor
+	 * registration, or unresolved-authority update that wins the lock prevents
+	 * destructive coordinator cleanup.
+	 */
+	async retireStaleIfCurrent(expected: {
+		sessionId: string;
+		workspace: string;
+		endpointGeneration: number;
+		endpointIncarnation: string;
+	}): Promise<"retired" | "already_retired" | "not_found" | "stale"> {
+		const indexPath = path.resolve(logFor(this.#agentDir));
+		// Process-incarnation observations are gathered before the lock. The locked
+		// projection then uses this fixed batch, avoiding an unbounded OS probe while
+		// holding the machine-global index lock.
+		const probed = new Map<string, string | undefined>();
+		for (const row of reduceEvents(this.#events, this.#policy.clock(), this.#agentDir).identities) {
+			const recordedIncarnation = row.hostIncarnation ?? row.processIncarnation;
+			if (recordedIncarnation === undefined || !alive(row.pid)) continue;
+			probed.set(`${row.sessionId}\u0000${row.endpointGeneration}\u0000${row.pid}`, processIncarnation(row.pid));
+		}
+		return await SessionIndex.#enqueue(indexPath, async () => {
+			try {
+				await fs.stat(dirFor(this.#agentDir));
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return "not_found";
+				throw error;
+			}
+			return await withSessionIndexLock("stale session retirement", this.#agentDir, async () => {
+				await this.#replayUnderLock();
+				if (this.#corruptSuffix) throw new Error("Cannot retire a session from a corrupt session index");
+				const current = this.listSessions(probed).sessions.find(
+					session => session.sessionId === expected.sessionId,
+				);
+				if (!current) return "not_found";
+				if (
+					resolveEquivalentPath(current.locator.cwd) !== resolveEquivalentPath(expected.workspace) ||
+					current.endpointGeneration !== expected.endpointGeneration ||
+					endpointIncarnation(current, expected.sessionId) !== expected.endpointIncarnation
+				)
+					return "stale";
+				if (current.ambiguous || current.terminalUncertain) return "stale";
+				if (current.terminal) return "already_retired";
+				if (
+					current.live !== false ||
+					current.lastHeartbeatAt === undefined ||
+					this.#policy.clock() - current.lastHeartbeatAt < DEAD_HOST_HEARTBEAT_SILENCE_MS
+				)
+					return "stale";
+				const unsigned: Omit<SessionIndexEvent, "checksum"> = {
+					version: SESSION_INDEX_EVENT_VERSION,
+					indexSeq: this.indexSeq + 1,
+					ts: Date.now(),
+					type: "session_closed",
+					sessionId: current.sessionId,
+					locator: current.locator,
+					endpointGeneration: current.endpointGeneration,
+					pid: current.pid,
+					...(current.processIncarnation === undefined ? {} : { processIncarnation: current.processIncarnation }),
+					...(current.hostIncarnation === undefined ? {} : { hostIncarnation: current.hostIncarnation }),
+					...(current.endpointMtimeMs === undefined ? {} : { endpointMtimeMs: current.endpointMtimeMs }),
+					...(current.endpointFileId === undefined ? {} : { endpointFileId: current.endpointFileId }),
+					...(current.lifecycleRequestId === undefined ? {} : { lifecycleRequestId: current.lifecycleRequestId }),
+				};
+				const event: SessionIndexEvent = { ...unsigned, checksum: sessionIndexChecksum(unsigned) };
+				await appendSync(logFor(this.#agentDir), JSON.stringify(event));
+				await this.#refreshUnderLock();
+				if ((await fs.stat(logFor(this.#agentDir))).size >= ROTATE_BYTES) await this.#rotate();
+				return "retired";
+			});
+		});
+	}
+
 	async unregisterIfCurrent(
 		expected: Pick<
 			SessionIndexEvent,
@@ -1701,6 +1789,7 @@ export class SessionIndex {
 			| "processIncarnation"
 			| "hostIncarnation"
 		>,
+		reason?: HostUnregisteredReason,
 	): Promise<boolean> {
 		const indexPath = path.resolve(logFor(this.#agentDir));
 		return await SessionIndex.#enqueue(indexPath, async () => {
@@ -1781,6 +1870,7 @@ export class SessionIndex {
 					...(expected.lifecycleRequestId === undefined
 						? {}
 						: { lifecycleRequestId: expected.lifecycleRequestId }),
+					...(reason === undefined ? {} : { hostUnregisteredReason: reason }),
 				};
 				const event: SessionIndexEvent = { ...unsigned, checksum: sessionIndexChecksum(unsigned) };
 				await appendSync(logFor(this.#agentDir), JSON.stringify(event));
@@ -1866,10 +1956,10 @@ export class SessionIndex {
 		this.#changeStamp = await readIndexChangeStamp(this.#agentDir);
 	}
 
-	listSessions(): SessionList {
+	listSessions(probedIncarnations?: ReadonlyMap<string, string | undefined>): SessionList {
 		return {
 			indexSeq: this.indexSeq,
-			sessions: reduceEvents(this.#events, this.#policy.clock(), this.#agentDir).sessions,
+			sessions: reduceEvents(this.#events, this.#policy.clock(), this.#agentDir, probedIncarnations).sessions,
 			warnings: this.#warnings,
 		};
 	}
@@ -2323,7 +2413,10 @@ export class SessionIndex {
 						...(row.processIncarnation === undefined ? {} : { processIncarnation: row.processIncarnation }),
 						...(row.hostIncarnation === undefined ? {} : { hostIncarnation: row.hostIncarnation }),
 						...(row.masterRole === undefined ? {} : { masterRole: row.masterRole }),
-						activity: { state: "active", at: now },
+						// Preserve the host's last observed activity state while this
+						// broker-owned heartbeat only renews liveness. A live idle host
+						// must not be rewritten as active merely because its pid is alive.
+						activity: row.activity ?? { state: "active", at: now },
 						ts: now,
 					};
 					events.push({ ...unsigned, checksum: sessionIndexChecksum(unsigned) });

package/src/sdk/broker/spawn-authority.ts

@@ -23,6 +23,8 @@ export type SpawnClaimV2 = {
 	failure?: SpawnSubstrateFailure;
 	preSendLease?: { epoch: string; status: "owned" | "consumed" };
 	childId?: string;
+	/** Launch proof retained while registration is still unbound so a later retry can re-prove or close it. */
+	substrateProof?: SpawnSubstrateProof;
 	seed?: SeedDeliveryV2;
 	authorityRef?: string;
 	createdAt: number;
@@ -139,6 +141,8 @@ export type SpawnClaimTransition = {
 	leaseEpoch?: string;
 	/** The fresh child ID is committed before substrate launch. */
 	childId?: string;
+	/** Launch proof may be appended to the pre-registration state for later reconciliation. */
+	substrateProof?: SpawnSubstrateProof;
 	/** Required for seed and terminal state transitions that carry Q26 facts. */
 	seed?: SeedDeliveryV2;
 	failure?: SpawnSubstrateFailure;
@@ -225,6 +229,7 @@ const CLAIM_KEYS = new Set([
 	"failure",
 	"preSendLease",
 	"childId",
+	"substrateProof",
 	"seed",
 	"authorityRef",
 	"createdAt",
@@ -272,13 +277,13 @@ const FORBIDDEN_FIELD =
 	/(?:task|prompt|capability|idempotency|fingerprint|requesthash|digest|credential|token|secret|password|stderr)/i;
 const TRANSITION_EDGES: Readonly<Record<SpawnClaimV2["state"], readonly SpawnClaimV2["state"][]>> = {
 	prepared: ["substrate_starting", "pre_send_rejected", "uncertain", "closed"],
-	substrate_starting: ["authority_active", "pre_send_rejected", "uncertain", "closed"],
+	substrate_starting: ["substrate_starting", "authority_active", "pre_send_rejected", "uncertain", "closed"],
 	authority_active: ["seed_prepared", "pre_send_rejected", "uncertain", "closed"],
 	seed_prepared: ["dispatching", "pre_send_rejected", "uncertain", "closed"],
 	dispatching: ["accepted", "pre_send_rejected", "uncertain", "closed"],
 	accepted: ["uncertain", "closed"],
 	pre_send_rejected: ["uncertain", "closed"],
-	uncertain: ["closed"],
+	uncertain: ["pre_send_rejected", "closed"],
 	closed: [],
 };
 
@@ -476,6 +481,7 @@ export function isSpawnClaimV2(value: unknown): value is SpawnClaimV2 {
 				((lease as { status?: unknown }).status === "owned" ||
 					(lease as { status?: unknown }).status === "consumed"))) &&
 		(claim.childId === undefined || isOpaque(claim.childId)) &&
+		(claim.substrateProof === undefined || isSpawnSubstrateProof(claim.substrateProof)) &&
 		(claim.seed === undefined || isSeed(claim.seed)) &&
 		(claim.authorityRef === undefined || isOpaque(claim.authorityRef)) &&
 		(claim.failure === undefined || isSpawnSubstrateFailure(claim.failure)) &&
@@ -698,10 +704,19 @@ export class SpawnAuthorityStore {
 						!isOpaque(transition.childId) ||
 						transition.seed !== undefined ||
 						transition.authority !== undefined ||
-						transition.failure !== undefined
+						transition.failure !== undefined ||
+						(transition.substrateProof !== undefined && !isSpawnSubstrateProof(transition.substrateProof)) ||
+						(current.state === "prepared" && transition.substrateProof !== undefined) ||
+						(current.state === "substrate_starting" && transition.substrateProof === undefined) ||
+						(current.state === "substrate_starting" && transition.childId !== current.childId)
 					)
 						throw new SpawnAuthorityTransitionError("invalid_transition");
-					next = { ...current, state: "substrate_starting", childId: transition.childId };
+					next = {
+						...current,
+						state: "substrate_starting",
+						childId: transition.childId,
+						...(transition.substrateProof === undefined ? {} : { substrateProof: transition.substrateProof }),
+					};
 					break;
 				}
 				case "authority_active": {
@@ -804,7 +819,11 @@ export class SpawnAuthorityStore {
 					break;
 				}
 				case "uncertain": {
-					if (transition.childId !== undefined || transition.authority !== undefined)
+					if (
+						transition.childId !== undefined ||
+						transition.authority !== undefined ||
+						(transition.failure !== undefined && !isSpawnSubstrateFailure(transition.failure))
+					)
 						throw new SpawnAuthorityTransitionError("invalid_transition");
 					if (current.seed) {
 						if (
@@ -813,10 +832,19 @@ export class SpawnAuthorityStore {
 							!sameSeedIdentity(current.seed, transition.seed)
 						)
 							throw new SpawnAuthorityTransitionError("invalid_transition");
-						next = { ...current, state: "uncertain", seed: transition.seed };
+						next = {
+							...current,
+							state: "uncertain",
+							seed: transition.seed,
+							...(transition.failure === undefined ? {} : { failure: transition.failure }),
+						};
 					} else {
 						if (transition.seed !== undefined) throw new SpawnAuthorityTransitionError("invalid_transition");
-						next = { ...current, state: "uncertain" };
+						next = {
+							...current,
+							state: "uncertain",
+							...(transition.failure === undefined ? {} : { failure: transition.failure }),
+						};
 					}
 					break;
 				}

package/src/sdk/broker/stderr-drainer.ts

@@ -0,0 +1,59 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const MAX_DRAIN_BYTES = 64 * 1024;
+
+function parseMaxBytes(value: string): number {
+	if (!/^[0-9]+$/u.test(value)) throw new Error("Invalid lifecycle stderr drainer byte limit.");
+	const maxBytes = Number(value);
+	if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > MAX_DRAIN_BYTES)
+		throw new Error("Invalid lifecycle stderr drainer byte limit.");
+	return maxBytes;
+}
+
+/** Parse and run the private source/compiled CLI drainer route. */
+export async function runSdkStderrDrainerFromArgv(argv: readonly string[]): Promise<void> {
+	if (argv.length !== 4 || argv[0] !== "--path" || argv[1] === undefined || argv[2] !== "--max-bytes")
+		throw new Error("Invalid lifecycle stderr drainer invocation.");
+	if (!path.isAbsolute(argv[1])) throw new Error("Invalid lifecycle stderr drainer path.");
+	await runSdkStderrDrainer(argv[1], parseMaxBytes(argv[3] ?? ""));
+}
+
+/**
+ * Drain a detached lifecycle host's stderr without letting a noisy child grow
+ * its diagnostic artifact. The drainer owns the read side of the pipe, so the
+ * host remains attached to a process that outlives the broker itself.
+ *
+ * The artifact is written through one descriptor opened up front: once the
+ * broker has finished reading the startup diagnostic it unlinks the path, and
+ * the remaining output lands on an unlinked inode that disappears with this
+ * process instead of accumulating under the agent directory.
+ */
+export async function runSdkStderrDrainer(logPath: string, maxBytes: number): Promise<void> {
+	let handle: fs.FileHandle | undefined;
+	try {
+		handle = await fs.open(logPath, "w", 0o600);
+	} catch {
+		// Diagnostics are best effort; keep draining so the host never blocks.
+	}
+	let tail = Buffer.alloc(0);
+	try {
+		for await (const chunk of process.stdin) {
+			const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array);
+			if (bytes.length >= maxBytes) tail = Buffer.from(bytes.subarray(bytes.length - maxBytes));
+			else {
+				const combined = Buffer.concat([tail, bytes]);
+				tail = combined.length > maxBytes ? Buffer.from(combined.subarray(combined.length - maxBytes)) : combined;
+			}
+			if (!handle) continue;
+			try {
+				await handle.truncate(0);
+				await handle.write(tail, 0, tail.length, 0);
+			} catch {
+				// Diagnostics are best effort; continue draining so the host never blocks.
+			}
+		}
+	} finally {
+		await handle?.close().catch(() => undefined);
+	}
+}

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

@@ -141,8 +141,8 @@ export type ChatDaemonAction = "stop" | "reload";
  * crashes, recovery, and attachment retirement cannot replay ambiguous work.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 76,
-	slack: 83,
+	discord: 79,
+	slack: 86,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

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

@@ -317,6 +317,7 @@ export class ChatDaemonRuntime {
 	) {
 		this.#router = new SessionRouter({
 			agentDir: input.agentDir,
+			observer: true,
 			correlateFrame,
 			deps: {
 				...deps.routerDeps,