@gajae-code/coding-agent 0.13.0 → 0.13.2

package/src/sdk/broker/lifecycle-ledger.ts

@@ -66,6 +66,8 @@ export interface LifecycleDurableEffectsReceipt {
 }
 
 export interface LifecycleLedgerEntry {
+	operationKey?: string;
+	fingerprint?: string;
 	version: typeof SDK_STATE_VERSION;
 	identity: string;
 	requestHash: string;
@@ -153,7 +155,9 @@ function isLifecycleLedgerEntry(value: unknown): value is LifecycleLedgerEntry {
 			entry.state === "terminal_error" ||
 			entry.state === "terminal_uncertain") &&
 		typeof entry.ts === "number" &&
-		Number.isSafeInteger(entry.ts)
+		Number.isSafeInteger(entry.ts) &&
+		(entry.operationKey === undefined || typeof entry.operationKey === "string") &&
+		(entry.fingerprint === undefined || typeof entry.fingerprint === "string")
 	);
 }
 function canonicalJson(value: unknown): string {
@@ -661,6 +665,35 @@ export class LifecycleLedger {
 		}
 		return replacement !== undefined;
 	}
+	findByOperationKey(operationKey: string): LifecycleLedgerEntry | undefined {
+		return [...this.#byIdentity.values()].find(entry => entry.operationKey === operationKey);
+	}
+	/**
+	 * Legacy target-inclusive rows predate the operation/key index. Their opaque
+	 * identities cannot establish that a different target is safe, so callers
+	 * must reject rather than create a second admission.
+	 */
+	hasLegacyIdentity(): boolean {
+		return [...this.#byIdentity.values()].some(entry => entry.operationKey === undefined);
+	}
+	async migrateIdentity(
+		from: string,
+		to: string,
+		metadata: { operationKey: string; fingerprint: string },
+	): Promise<LifecycleLedgerEntry | undefined> {
+		return this.#mutate(async () => {
+			if (this.#byIdentity.has(to)) return this.#byIdentity.get(to);
+			const entry = this.#byIdentity.get(from);
+			if (!entry) return undefined;
+			const migrated = await this.#append({ ...entry, identity: to, ...metadata, ts: Date.now() });
+			// Retire the legacy row so hasLegacyIdentity() returns false and future
+			// unrelated lifecycle requests are not globally blocked. The legacy
+			// identity gets a metadata-bearing replacement row in the append-only
+			// log, superseding the original metadata-free entry in #byIdentity.
+			if (entry.operationKey === undefined) await this.#append({ ...entry, ...metadata, ts: Date.now() });
+			return migrated;
+		});
+	}
 	get warnings(): readonly string[] {
 		return this.#warnings;
 	}
@@ -687,11 +720,19 @@ export class LifecycleLedger {
 		this.#byteCount += line.length;
 		return entry;
 	}
-	async begin(identity: string, requestHash: string): Promise<BeginResult> {
-		return this.#mutate(async () => this.#begin(identity, requestHash));
+	async begin(
+		identity: string,
+		requestHash: string,
+		metadata: { operationKey?: string; fingerprint?: string } = {},
+	): Promise<BeginResult> {
+		return this.#mutate(async () => this.#begin(identity, requestHash, metadata));
 	}
 
-	async #begin(identity: string, requestHash: string): Promise<BeginResult> {
+	async #begin(
+		identity: string,
+		requestHash: string,
+		metadata: { operationKey?: string; fingerprint?: string },
+	): Promise<BeginResult> {
 		const prior = this.#byIdentity.get(identity);
 		if (!prior)
 			return {
@@ -700,15 +741,24 @@ export class LifecycleLedger {
 					version: SDK_STATE_VERSION,
 					identity,
 					requestHash,
+					operationKey: metadata.operationKey,
+					fingerprint: metadata.fingerprint,
 					state: "accepted",
 					ts: Date.now(),
 				}),
 			};
-		if (prior.requestHash !== requestHash) return { kind: "idempotency_conflict" };
+		if (
+			prior.requestHash !== requestHash ||
+			(prior.operationKey !== undefined &&
+				metadata.operationKey !== undefined &&
+				prior.operationKey !== metadata.operationKey)
+		)
+			return { kind: "idempotency_conflict" };
 		if (terminal(prior.state) || (prior.state === "effect_started" && this.#isCleanupPending(prior)))
 			return { kind: "replay", entry: prior };
 		if (prior.state === "terminal_uncertain") return { kind: "terminal_uncertain", entry: prior };
-		// An accepted row has no durable side effect. Target serialization makes retrying it safe.
+		// Accepted proves admission only. The effect_started marker is the boundary
+		// after which retrying the operation is unsafe.
 		if (prior.state === "accepted") return { kind: "new", entry: prior };
 		return { kind: "in_progress", entry: prior };
 	}

package/src/sdk/broker/lifecycle.ts

@@ -89,6 +89,8 @@ export {
 
 const POLL_MS = 50;
 const CLOSE_TIMEOUT_MS = 2_000;
+const STARTUP_CLEANUP_PROOF_GRACE_MS = 500;
+
 const MAX_RECEIVED_AT_SKEW_MS = 5_000;
 const MAX_LIFECYCLE_METADATA_BYTES = 4096;
 const MAX_EFFECT_MARKER_LENGTH = 128;
@@ -1957,6 +1959,7 @@ type SignalTarget = {
 	pid: number;
 	lifecycleRequestId?: string;
 	processIncarnation?: string;
+	hostIncarnation?: string;
 };
 
 /**
@@ -1979,7 +1982,11 @@ async function hasDurableProcessIdentity(target: SignalTarget, id: string, expec
 			marker.incarnation === processIncarnation(target.pid)
 		);
 	if (expected && (expected.pid !== target.pid || target.lifecycleRequestId !== expected.effectMarker)) return false;
-	return target.processIncarnation !== undefined && target.processIncarnation === processIncarnation(target.pid);
+	// Hosts that pass an explicit incarnation record it as `processIncarnation`;
+	// the index's append path auto-stamps `hostIncarnation` for everything else.
+	// Either binding is the same pid-to-incarnation proof.
+	const recorded = target.hostIncarnation ?? target.processIncarnation;
+	return recorded !== undefined && recorded === processIncarnation(target.pid);
 }
 
 async function hasOwnedReadinessEvidence(
@@ -3062,7 +3069,9 @@ async function revalidateCloseGeneration(
 function isTransportFailure(error: unknown): error is SdkClientError {
 	return (
 		error instanceof SdkClientError &&
-		["unavailable", "timeout", "connection_closed", "reconnect_exhausted"].includes(error.code)
+		["unavailable", "timeout", "connection_closed", "uncertain_after_send", "reconnect_exhausted"].includes(
+			error.code,
+		)
 	);
 }
 
@@ -3438,6 +3447,11 @@ async function executeLifecycleResponse(
 	let record = broker.index.listSessions().sessions.find(session => session.sessionId === id);
 	if (operation === "session.close") {
 		if (!record) return fail("not_found", "session is not indexed");
+		// DR-1 retains closed/unregistered rows for inspect and offline tail.
+		// Pre-DR-1 they vanished from the listing and close answered not_found;
+		// a terminal row is the same already-gone outcome, never an escalation
+		// target — signalling its recorded pid could hit a reused process.
+		if (record.terminal) return fail("resource_gone", "Session is already closed and unregistered.");
 		if (record.terminalUncertain)
 			return fail("terminal_uncertain", "Session ownership is uncertain and cannot be closed safely.");
 		const requestedAuthority = requestedCloseAuthority(input);
@@ -4248,6 +4262,23 @@ async function exactCleanupProof(
 		: undefined;
 }
 
+async function waitForExactCleanupProof(
+	broker: Broker,
+	root: string | undefined,
+	id: string | undefined,
+	expected: EffectMarker | undefined,
+	evidence: { artifact: LifecycleFailureArtifact } | undefined,
+): Promise<LifecycleCleanupProof | undefined> {
+	const timing = lifecycleTiming(broker);
+	const deadline = timing.now() + STARTUP_CLEANUP_PROOF_GRACE_MS;
+	for (;;) {
+		const proof = await exactCleanupProof(broker, root, id, expected, evidence);
+		if (proof) return proof;
+		const remaining = deadline - timing.now();
+		if (remaining <= 0) return undefined;
+		await timing.sleep(Math.min(POLL_MS, remaining));
+	}
+}
 function validateLifecycleDeleteMetadataBinding(
 	broker: Broker,
 	operation: string,
@@ -4361,7 +4392,7 @@ export async function executeLifecycle(
 					expected,
 				)
 			: undefined;
-	const cleanupProof = await exactCleanupProof(broker, root, entry?.intendedSessionId, expected, evidence);
+	const cleanupProof = await waitForExactCleanupProof(broker, root, entry?.intendedSessionId, expected, evidence);
 	const startupFailure: LifecycleStartupFailureReceipt | undefined = evidence
 		? {
 				artifactDigest: evidence.digest,
@@ -4580,18 +4611,30 @@ export interface ReapedSessionRegistration {
 /**
  * Drops every indexed session registration whose host process is provably gone.
  *
- * Liveness is the session index's own `alive(pid)` probe (`listSessions().live`),
- * which reports live for both a running pid and an EPERM pid, so an alien or
- * unreadable process is never mistaken for a dead one. Registrations already
- * marked `terminalUncertain` are left alone: their disposition belongs to the
- * terminal-uncertainty reconciliation path, and silently dropping them would
- * turn a fail-closed `session.close`/`session.delete` refusal into `not_found`.
+ * Proof of death is positive, never inferred from a missing liveness proof:
+ * `observeProcess` reports "exited" only on ESRCH or on a readable OS process
+ * incarnation that differs from the recorded one (a reused pid). A stale or
+ * missing heartbeat merely makes a session read as not-live — the host may
+ * still be running ahead of the next heartbeat checkpoint pass, so it is never
+ * grounds for a reap. EPERM and unreadable incarnations stay "uncertain", so an
+ * alien or unreadable process is never mistaken for a dead one. Registrations
+ * already terminal or marked `terminalUncertain` are left alone: their
+ * disposition belongs to the terminal-uncertainty reconciliation path, and
+ * silently dropping them would turn a fail-closed `session.close`/
+ * `session.delete` refusal into `not_found`.
  */
 export async function reapDeadSessionRegistrations(
 	broker: Pick<Broker, "index">,
 ): Promise<ReapedSessionRegistration[]> {
 	await broker.index.refresh();
-	const dead = broker.index.listSessions().sessions.filter(session => !session.live && !session.terminalUncertain);
+	const dead = broker.index
+		.listSessions()
+		.sessions.filter(
+			session =>
+				!session.terminal &&
+				!session.terminalUncertain &&
+				observeProcess(session.pid, session.hostIncarnation ?? session.processIncarnation) === "exited",
+		);
 	const reaped: ReapedSessionRegistration[] = [];
 	for (const session of dead) {
 		await broker.index.append({

package/src/sdk/broker/process-incarnation.ts

@@ -40,7 +40,12 @@ export interface ProcessIncarnationOptions {
 
 function runProcessIncarnationCommand(command: string, args: readonly string[]): ProcessIncarnationCommandResult {
 	try {
-		const result = Bun.spawnSync([command, ...args], { stdin: "ignore", stdout: "pipe", stderr: "ignore" });
+		const result = Bun.spawnSync([command, ...args], {
+			stdin: "ignore",
+			stdout: "pipe",
+			stderr: "ignore",
+			windowsHide: true,
+		});
 		return { exitCode: result.exitCode, stdout: Buffer.from(result.stdout).toString("utf8") };
 	} catch {
 		return undefined;

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

@@ -278,8 +278,10 @@ function auditRecords(events: SessionIndexEvent[], ts: number): SessionIndexAudi
  * highest (generation, indexSeq); only `session_deleted` hides a row (DR-1 retains
  * stopped/terminal credential-free rows so inspect/offline tail can work). Heartbeats
  * inherit locator/endpoint metadata from their identity's prior event. Liveness (C2)
- * requires a heartbeat observed within 2x the checkpoint interval AND a live host:
- * a missing heartbeat (e.g. after a broker restart) is unknown, never fresh forever.
+ * requires host-written evidence — a heartbeat, or the host's own `host_registered`
+ * append — observed within 2x the checkpoint interval AND a live host whose OS
+ * incarnation still matches: a missing or stale evidence trail (e.g. after a broker
+ * restart) is unknown, never fresh forever.
  */
 function reduceEvents(events: SessionIndexEvent[], now: number): IndexedSession[] {
 	const { admitted } = admitEvents(events);
@@ -325,7 +327,15 @@ function reduceEvents(events: SessionIndexEvent[], now: number): IndexedSession[
 		if (latest.type === "session_deleted") continue;
 		const heartbeat = latestHeartbeatByIdentity.get(chosen.identity);
 		const pidAlive = alive(latest.pid);
-		const heartbeatFresh = heartbeat !== undefined && now - heartbeat.ts < 2 * SESSION_HEARTBEAT_INTERVAL_MS;
+		// Liveness evidence is host-written: a checkpointed heartbeat, or the
+		// `host_registered` event the host appended itself. Counting registration
+		// closes the up-to-one-interval window where a just-registered session
+		// would read not-live before the first C2 pass — without weakening the
+		// pid-reuse fence, because the incarnation match below is still required.
+		// Broker-written events (reconciliation, terminal records) are not host
+		// evidence and never refresh liveness.
+		const evidenceTs = Math.max(heartbeat?.ts ?? 0, latest.type === "host_registered" ? latest.ts : 0);
+		const heartbeatFresh = evidenceTs > 0 && now - evidenceTs < 2 * SESSION_HEARTBEAT_INTERVAL_MS;
 		const recordedIncarnation = effectiveIncarnation(latest);
 		const currentIncarnation = recordedIncarnation === undefined ? undefined : processIncarnation(latest.pid);
 		const incarnationMatches = currentIncarnation !== undefined && currentIncarnation === recordedIncarnation;
@@ -351,6 +361,13 @@ function reduceEvents(events: SessionIndexEvent[], now: number): IndexedSession[
 	return sessions;
 }
 
+// Global launch bursts may queue behind legitimate long index transactions. Keep
+// this bounded at one minute while the shared lock's exact dead-owner recovery runs.
+const SESSION_INDEX_LOCK_OPTIONS = { retries: 600, retryDelayMs: 100 } as const;
+
+function withSessionIndexLock<T>(agentDir: string, callback: () => Promise<T>): Promise<T> {
+	return withFileLock(logFor(agentDir), callback, SESSION_INDEX_LOCK_OPTIONS);
+}
 function isValidSnapshot(snapshot: unknown): snapshot is { indexSeq: number; events: SessionIndexEvent[] } {
 	if (!snapshot || typeof snapshot !== "object") return false;
 	const { indexSeq, events } = snapshot as { indexSeq?: unknown; events?: unknown };
@@ -557,7 +574,7 @@ export class SessionIndex {
 			group.promise = SessionIndex.#enqueue(indexPath, () => this.#prepareOpenGroup(indexPath, group!));
 		}
 		await group.promise;
-		await SessionIndex.#enqueue(indexPath, () => withFileLock(logFor(this.#agentDir), () => this.#replayUnderLock()));
+		await SessionIndex.#enqueue(indexPath, () => withSessionIndexLock(this.#agentDir, () => this.#replayUnderLock()));
 		return this;
 	}
 	async #prepareOpenGroup(indexPath: string, group: SessionIndexOpenGroup): Promise<void> {
@@ -571,7 +588,7 @@ export class SessionIndex {
 	}
 	async replay(): Promise<void> {
 		const indexPath = path.resolve(logFor(this.#agentDir));
-		await SessionIndex.#enqueue(indexPath, () => withFileLock(logFor(this.#agentDir), () => this.#replayUnderLock()));
+		await SessionIndex.#enqueue(indexPath, () => withSessionIndexLock(this.#agentDir, () => this.#replayUnderLock()));
 	}
 	async #replayUnderLock(): Promise<void> {
 		const scan = await this.#scan();
@@ -762,14 +779,14 @@ export class SessionIndex {
 				}),
 			);
 			if (!exists.some(Boolean)) return { status: "healthy", validPrefixSeq: 0, snapshotSeq: 0 };
-			return await withFileLock(logFor(this.#agentDir), async () => (await this.#scan()).diagnosis);
+			return await withSessionIndexLock(this.#agentDir, async () => (await this.#scan()).diagnosis);
 		});
 	}
 	async repair(): Promise<SessionIndexRepairResult> {
 		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 withFileLock(logFor(this.#agentDir), async () => {
+			return await withSessionIndexLock(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 };
@@ -852,7 +869,7 @@ export class SessionIndex {
 	async refresh(): Promise<void> {
 		const indexPath = path.resolve(logFor(this.#agentDir));
 		await SessionIndex.#enqueue(indexPath, () =>
-			withFileLock(logFor(this.#agentDir), () => this.#refreshUnderLock()),
+			withSessionIndexLock(this.#agentDir, () => this.#refreshUnderLock()),
 		);
 	}
 	async #refreshUnderLock(): Promise<void> {
@@ -869,7 +886,7 @@ 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 withFileLock(logFor(this.#agentDir), async () => {
+			return await withSessionIndexLock(this.#agentDir, async () => {
 				await this.#replayUnderLock();
 				if (this.#corruptSuffix)
 					throw new Error(
@@ -905,7 +922,7 @@ export class SessionIndex {
 				if ((error as NodeJS.ErrnoException).code === "ENOENT") return await callback();
 				throw error;
 			}
-			return await withFileLock(logFor(this.#agentDir), async () => {
+			return await withSessionIndexLock(this.#agentDir, async () => {
 				await this.#replayUnderLock();
 				if (this.#corruptSuffix) throw new Error("Cannot use corrupt session index for artifact reclamation");
 				return await callback();
@@ -915,7 +932,7 @@ export class SessionIndex {
 	async snapshot(): Promise<void> {
 		const indexPath = path.resolve(logFor(this.#agentDir));
 		await SessionIndex.#enqueue(indexPath, () =>
-			withFileLock(logFor(this.#agentDir), () => this.#snapshotUnderLock()),
+			withSessionIndexLock(this.#agentDir, () => this.#snapshotUnderLock()),
 		);
 	}
 	async #snapshotUnderLock(): Promise<void> {

package/src/sdk/broker/startup-failure.ts

@@ -0,0 +1,101 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+export interface BrokerStartupFailureMarker {
+	version: 1;
+	reason: string;
+	exitCode: number | null;
+	signal: string | null;
+	writtenAt: number;
+}
+
+const BROKER_STARTUP_FAILURE_FILE = "broker.startup-failure.json";
+const MAX_BROKER_STARTUP_FAILURE_REASON = 512;
+
+export function brokerStartupFailurePath(agentDir: string): string {
+	return path.join(agentDir, "sdk", BROKER_STARTUP_FAILURE_FILE);
+}
+
+function boundedMarker(reason: string, exitCode: number | null, signal: string | null): BrokerStartupFailureMarker {
+	return {
+		version: 1,
+		reason: reason.slice(0, MAX_BROKER_STARTUP_FAILURE_REASON),
+		exitCode,
+		signal,
+		writtenAt: Date.now(),
+	};
+}
+
+/** Best-effort durable marker write; never throws (diagnostics must not mask the exit itself). */
+export async function writeBrokerStartupFailureMarker(
+	agentDir: string,
+	failure: { reason: string; exitCode: number | null; signal: string | null },
+): Promise<void> {
+	try {
+		await fs.mkdir(path.dirname(brokerStartupFailurePath(agentDir)), { recursive: true, mode: 0o700 });
+		await Bun.write(
+			brokerStartupFailurePath(agentDir),
+			JSON.stringify(boundedMarker(failure.reason, failure.exitCode, failure.signal)),
+		);
+	} catch {
+		// Best-effort only.
+	}
+}
+
+/** Reads a bounded startup-failure marker; `undefined` when absent or malformed. */
+export async function readBrokerStartupFailureMarker(
+	agentDir: string,
+): Promise<BrokerStartupFailureMarker | undefined> {
+	try {
+		const file = Bun.file(brokerStartupFailurePath(agentDir));
+		if (!(await file.exists())) return undefined;
+		const raw = await file.text();
+		const value: unknown = JSON.parse(raw);
+		if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+		const marker = value as Partial<BrokerStartupFailureMarker>;
+		if (
+			marker.version !== 1 ||
+			typeof marker.reason !== "string" ||
+			marker.reason.length === 0 ||
+			(marker.exitCode !== null && typeof marker.exitCode !== "number") ||
+			(marker.signal !== null && typeof marker.signal !== "string") ||
+			typeof marker.writtenAt !== "number"
+		)
+			return undefined;
+		return marker as BrokerStartupFailureMarker;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Best-effort marker removal; used at spawn so a stale marker never misattributes an older failure. */
+export async function clearBrokerStartupFailureMarker(agentDir: string): Promise<void> {
+	try {
+		const file = Bun.file(brokerStartupFailurePath(agentDir));
+		if (await file.exists()) await file.unlink();
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			// Best-effort only.
+		}
+	}
+}
+
+/** Typed error returned when a detached broker exits before discovery. */
+export class BrokerStartupError extends Error {
+	readonly code = "broker_startup_failed";
+	readonly exitCode: number | null;
+	readonly signal: string | null;
+	readonly reason: string;
+	readonly stderrExcerpt?: string;
+
+	constructor(fields: { exitCode: number | null; signal: string | null; reason: string; stderrExcerpt?: string }) {
+		super(
+			`Detached SDK broker exited before discovery (code=${fields.exitCode}, signal=${fields.signal}): ${fields.reason}${fields.stderrExcerpt ? ` Broker stderr: ${fields.stderrExcerpt}` : ""}`,
+		);
+		this.name = "BrokerStartupError";
+		this.exitCode = fields.exitCode;
+		this.signal = fields.signal;
+		this.reason = fields.reason;
+		this.stderrExcerpt = fields.stderrExcerpt;
+	}
+}

package/src/sdk/broker/transport.ts

@@ -18,6 +18,7 @@ const BROKER_OPERATIONS = new Set([
 	"elevation.issue",
 	"elevation.status",
 	"session.control",
+	"broker.lookup_lifecycle",
 ]);
 type RequestInput = Record<string, unknown>;
 type BrokerRequest = {

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

@@ -72,11 +72,12 @@ export type ChatDaemonAction = "stop" | "reload";
  * before the host heartbeat TTL expires and permanently loses its attachment. Discord
  * generation 29 / slack generation 28 advance the replay cursor only after a frame is
  * published, so an owner at an earlier generation acknowledges an event before delivering
- * it and loses that event for good the first time a surface refuses it.
+ * it and loses that event for good the first time a surface refuses it. Discord generation 30 /
+ * slack generation 29 invalidate existing owners after SDK discovery validation changes.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
-	discord: 29,
-	slack: 28,
+	discord: 30,
+	slack: 29,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

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

@@ -67,7 +67,14 @@ function chatDeliveryPhase(error: unknown): ChatDeliveryPhase | undefined {
 	if (!(error instanceof SdkClientError)) return undefined;
 	// `connection_closed` conveys no send-progress guarantee: SdkClient also emits it
 	// when a pending, already-sent request loses its response.
-	return ["connection_closed", "unavailable", "timeout", "reconnect_exhausted", "protocol_error"].includes(error.code)
+	return [
+		"connection_closed",
+		"unavailable",
+		"timeout",
+		"uncertain_after_send",
+		"reconnect_exhausted",
+		"protocol_error",
+	].includes(error.code)
 		? "ambiguous"
 		: undefined;
 }