@gajae-code/coding-agent 0.16.3 → 0.16.6

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

@@ -1,8 +1,9 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { processIncarnation } from "./process-incarnation";
 
 export interface BrokerStartupFailureMarker {
-	version: 1;
+	version: 2;
 	reason: string;
 	exitCode: number | null;
 	signal: string | null;
@@ -16,6 +17,8 @@ export interface BrokerStartupFailureMarker {
 	 * failure.
 	 */
 	pid: number;
+	/** Kernel-derived identity for the exact process incarnation that wrote the marker. */
+	incarnation: string;
 }
 
 const BROKER_STARTUP_FAILURE_FILE = "broker.startup-failure.json";
@@ -30,14 +33,16 @@ function boundedMarker(
 	exitCode: number | null,
 	signal: string | null,
 	pid: number,
+	incarnation: string,
 ): BrokerStartupFailureMarker {
 	return {
-		version: 1,
+		version: 2,
 		reason: reason.slice(0, MAX_BROKER_STARTUP_FAILURE_REASON),
 		exitCode,
 		signal,
 		writtenAt: Date.now(),
 		pid,
+		incarnation,
 	};
 }
 
@@ -49,13 +54,15 @@ function boundedMarker(
  */
 export async function writeBrokerStartupFailureMarker(
 	agentDir: string,
-	failure: { reason: string; exitCode: number | null; signal: string | null; pid: number },
+	failure: { reason: string; exitCode: number | null; signal: string | null; pid: number; incarnation?: string },
 ): Promise<void> {
 	try {
+		const incarnation = failure.incarnation ?? processIncarnation(failure.pid);
+		if (!incarnation) return;
 		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, failure.pid)),
+			JSON.stringify(boundedMarker(failure.reason, failure.exitCode, failure.signal, failure.pid, incarnation)),
 		);
 	} catch {
 		// Best-effort only.
@@ -74,7 +81,7 @@ export async function readBrokerStartupFailureMarker(
 		if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
 		const marker = value as Partial<BrokerStartupFailureMarker>;
 		if (
-			marker.version !== 1 ||
+			marker.version !== 2 ||
 			typeof marker.reason !== "string" ||
 			marker.reason.length === 0 ||
 			(marker.exitCode !== null && typeof marker.exitCode !== "number") ||
@@ -82,7 +89,9 @@ export async function readBrokerStartupFailureMarker(
 			typeof marker.writtenAt !== "number" ||
 			typeof marker.pid !== "number" ||
 			!Number.isInteger(marker.pid) ||
-			marker.pid <= 0
+			marker.pid <= 0 ||
+			typeof marker.incarnation !== "string" ||
+			marker.incarnation.length === 0
 		)
 			return undefined;
 		return marker as BrokerStartupFailureMarker;

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

@@ -133,10 +133,12 @@ export type ChatDaemonAction = "stop" | "reload";
  * Discord generation 72 / Slack generation 75 serialize same-generation
  * successor attachment admission behind predecessor provider retirement, so a
  * pre-upgrade owner cannot retain the queue race fixed by #5120.
+ * Slack generation 80 persists and fences the inbound SDK dispatch boundary so
+ * crashes, recovery, and attachment retirement cannot replay ambiguous work.
  */
 export const CHAT_DAEMON_GENERATIONS: Readonly<Record<ChatDaemonKind, number>> = {
 	discord: 73,
-	slack: 77,
+	slack: 80,
 };
 
 export function chatDaemonGeneration(kind: ChatDaemonKind): number {

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

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { logger } from "@gajae-code/utils";
-import { SdkClientError } from "../client/client";
+import { SdkClientError, SdkPreparedDispatchError } from "../client/client";
 import { SESSION_PREPARED_EVENT } from "../host/host";
 
 import type { SessionRouterDeps } from "../router";
@@ -50,6 +50,7 @@ function chatDeliveryPhase(error: unknown): ChatDeliveryPhase | undefined {
 	if (error instanceof SessionRouterError) return error.phase;
 
 	if (error instanceof ChatDeliveryError) return error.phase;
+	if (error instanceof SdkPreparedDispatchError) return "pre_send";
 	if (!(error instanceof SdkClientError)) return undefined;
 	// `uncertain_after_send` is the one code that states outright that the frame
 	// reached the host: reporting it as a definite failure would tell the operator a
@@ -92,6 +93,36 @@ function isReservedIdentity(name: string | undefined): boolean {
 	return isLifecycleEvent(name) || isControlPlaneFrameType(name);
 }
 
+/**
+ * Chat notifications in lean mode are an answer surface, not a mirror of the
+ * session protocol. Lifecycle, identity, and activity frames remain available
+ * to verbose consumers, while finalized answers and action-needed events are
+ * delivered in lean mode.
+ */
+export function shouldPublishChatFrame(
+	frame: Record<string, unknown>,
+	verbosity: "lean" | "verbose" | undefined,
+): boolean {
+	if (verbosity !== "lean") return frame.type !== "turn_stream" || frame.phase !== "live";
+	return frame.type === "turn_stream" && frame.phase === "finalized" && frame.finalAnswer === true;
+}
+
+/**
+ * A final answer's message ref identifies its one rendered message even when
+ * the SDK transport delivers an unpositioned duplicate frame.
+ */
+export function publicationIdForFinalChatAnswer(sessionId: string, frame: Record<string, unknown>): string | undefined {
+	if (
+		frame.type !== "turn_stream" ||
+		frame.phase !== "finalized" ||
+		frame.finalAnswer !== true ||
+		typeof frame.messageRef !== "string" ||
+		frame.messageRef.length === 0
+	)
+		return undefined;
+	return `turn:${sessionId}:${frame.messageRef}`;
+}
+
 /** One delivered frame reduced to a single event identity. */
 type CorrelatedFrame = SessionRouterFrame;
 
@@ -384,8 +415,16 @@ export class ChatDaemonRuntime {
 				authorizeActor: async actorId => config.authorizedUserId === actorId,
 				resolveAttachment: async sessionId => this.#router.attachment(sessionId),
 				resolveBindingAuthority: async sessionId => await this.#router.bindingAuthority(sessionId),
-				onCommand: async (sessionId, content, attachment, idempotencyKey) =>
-					await this.#runChatCommand("slack", sessionId, content, attachment, idempotencyKey),
+				onCommand: async (sessionId, content, attachment, idempotencyKey, beforeDispatch, dispatchFence) =>
+					await this.#runChatCommand(
+						"slack",
+						sessionId,
+						content,
+						attachment,
+						idempotencyKey,
+						beforeDispatch,
+						dispatchFence,
+					),
 			});
 		}
 		try {
@@ -571,8 +610,9 @@ export class ChatDaemonRuntime {
 		if (this.#attachments.get(attachment.sessionId) !== attachment) return;
 		await this.#attachmentBarriers.get(attachment.sessionId);
 		if (this.#attachments.get(attachment.sessionId) !== attachment) return;
-		const publicationId = correlated.publicationId;
 		const normalizedFrame = correlated.body;
+		const publicationId =
+			publicationIdForFinalChatAnswer(attachment.sessionId, normalizedFrame) ?? correlated.publicationId;
 		const bodyType = typeof normalizedFrame.type === "string" ? normalizedFrame.type : undefined;
 		if (isControlPlaneFrameType(correlated.name) || isControlPlaneFrameType(bodyType)) return;
 		if (normalizedFrame.type === "turn_stream" && normalizedFrame.phase === "live") return;
@@ -607,6 +647,11 @@ export class ChatDaemonRuntime {
 			return;
 		}
 		if (!notification) return;
+		if (
+			notification.type === "frame" &&
+			!shouldPublishChatFrame(normalizedFrame, this.input.config.presentation?.verbosity)
+		)
+			return;
 		const payload = this.#presentation?.fanout(notification)[0];
 		const body = payload?.body;
 		const content =
@@ -694,6 +739,8 @@ export class ChatDaemonRuntime {
 		content: string,
 		expectedAttachment: SessionAttachment,
 		idempotencyKey: string = randomUUID(),
+		beforeDispatch?: () => void,
+		dispatchFence?: <T>(dispatch: () => Promise<T>) => Promise<T>,
 	): Promise<boolean> {
 		const match = /^\/sdk\s+(control|query|global)\s+([^\s]+)(?:\s+(.+))?\s*$/.exec(content);
 		if (!match) return false;
@@ -712,7 +759,13 @@ export class ChatDaemonRuntime {
 		try {
 			outcome = await sendAuthorizedChatOperation(transport, { kind, operation, input }, async () => {
 				if (kind === "global")
-					return await this.#runGlobalCommand(operation, input as Record<string, unknown>, idempotencyKey);
+					return await this.#runGlobalCommand(
+						operation,
+						input as Record<string, unknown>,
+						idempotencyKey,
+						beforeDispatch,
+						dispatchFence,
+					);
 				if (!expectedAttachment.isCurrent()) throw new ChatDeliveryError("pre_send");
 				return await this.#router.request(
 					sessionId,
@@ -721,6 +774,12 @@ export class ChatDaemonRuntime {
 						: { type: "query_request", query: operation, input, idempotencyKey },
 					expectedAttachment.generation,
 					expectedAttachment,
+					beforeDispatch || dispatchFence
+						? {
+								beforeDispatch,
+								dispatchFence: dispatchFence ? dispatch => dispatchFence(dispatch) : undefined,
+							}
+						: undefined,
 				);
 			});
 		} catch (error) {
@@ -740,10 +799,17 @@ export class ChatDaemonRuntime {
 		operation: string,
 		input: Record<string, unknown>,
 		idempotencyKey: string,
+		beforeDispatch?: () => void,
+		dispatchFence?: <T>(dispatch: () => Promise<T>) => Promise<T>,
 	): Promise<Record<string, unknown>> {
 		if (operation !== "session.list") throw new ChatDeliveryError("pre_send");
 		try {
-			return await this.#router.listBrokerSessions(input, idempotencyKey);
+			return await this.#router.listBrokerSessions(
+				input,
+				idempotencyKey,
+				{ beforeDispatch },
+				dispatchFence ? dispatch => dispatchFence(dispatch) : undefined,
+			);
 		} catch (error) {
 			if (error instanceof SessionRouterError) throw new ChatDeliveryError(error.phase);
 			throw error;

package/src/sdk/bus/chat-effect-journal.ts

@@ -14,7 +14,7 @@ export function chatEffectJournalPath(agentDir: string, transport: "discord" | "
 	return conversationStorePath(agentDir, transport, "effects.json");
 }
 
-export type ChatEffectState = "pending" | "leased" | "accepted" | "uncertain" | "terminal";
+export type ChatEffectState = "pending" | "leased" | "dispatching" | "accepted" | "uncertain" | "terminal";
 
 /** Provider receipts are identifiers/status only. Never put request or response bodies here. */
 export interface ChatEffectReceipt {
@@ -262,7 +262,11 @@ export class ChatEffectJournal {
 		let renewed: ChatEffect<TPayload> | undefined;
 		const now = this.#now();
 		await this.#store.transact(id, current => {
-			if (current?.state !== "leased" || current.owner !== lease.owner || current.epoch !== lease.epoch)
+			if (
+				(current?.state !== "leased" && current?.state !== "dispatching") ||
+				current.owner !== lease.owner ||
+				current.epoch !== lease.epoch
+			)
 				return current;
 			renewed = {
 				...current,
@@ -275,6 +279,78 @@ export class ChatEffectJournal {
 		return renewed;
 	}
 
+	async markDispatching<TPayload = unknown>(
+		id: string,
+		lease: ChatEffectLease,
+	): Promise<ChatEffect<TPayload> | undefined> {
+		let marked: ChatEffect<TPayload> | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (current?.state !== "leased" || current.owner !== lease.owner || current.epoch !== lease.epoch)
+				return current;
+			marked = {
+				...current,
+				generation: current.generation + 1,
+				state: "dispatching",
+				updatedAt: now,
+			} as ChatEffect<TPayload>;
+			return marked;
+		});
+		return marked;
+	}
+
+	async ownsDispatching(id: string, lease: ChatEffectLease): Promise<boolean> {
+		const current = await this.#store.read(id);
+		return (
+			current?.state === "dispatching" &&
+			current.owner === lease.owner &&
+			current.epoch === lease.epoch &&
+			(current.leaseExpiresAt ?? 0) > this.#now()
+		);
+	}
+
+	/** Hold the durable dispatching lease until the synchronous SDK prewire boundary. */
+	async dispatchWithLeaseFence<R>(
+		id: string,
+		lease: ChatEffectLease,
+		dispatch: () => Promise<R>,
+		dispatched: Promise<void>,
+	): Promise<{ value: R } | undefined> {
+		return await this.#store.dispatchWithSnapshotFence(id, current => {
+			if (
+				current?.state !== "dispatching" ||
+				current.owner !== lease.owner ||
+				current.epoch !== lease.epoch ||
+				(current.leaseExpiresAt ?? 0) <= this.#now()
+			)
+				return undefined;
+			return { result: dispatch(), dispatched };
+		});
+	}
+
+	async recoverDispatchingAsUncertain<TPayload = unknown>(
+		id: string,
+		options: { onlyIfExpired?: boolean } = {},
+	): Promise<ChatEffect<TPayload> | undefined> {
+		let recovered: ChatEffect<TPayload> | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (current?.state !== "dispatching") return current;
+			if (options.onlyIfExpired && (current.leaseExpiresAt ?? 0) > now) return current;
+			recovered = {
+				...current,
+				generation: current.generation + 1,
+				state: "uncertain",
+				owner: undefined,
+				leaseExpiresAt: undefined,
+				receipt: { status: "uncertain" },
+				updatedAt: now,
+			} as ChatEffect<TPayload>;
+			return recovered;
+		});
+		return recovered;
+	}
+
 	/** Persists provider progress without releasing the owner/epoch fence. */
 	async recordReceipt<TPayload = unknown>(
 		id: string,
@@ -284,7 +360,11 @@ export class ChatEffectJournal {
 		let recorded: ChatEffect<TPayload> | undefined;
 		const now = this.#now();
 		await this.#store.transact(id, current => {
-			if (current?.state !== "leased" || current.owner !== lease.owner || current.epoch !== lease.epoch)
+			if (
+				(current?.state !== "leased" && current?.state !== "dispatching") ||
+				current.owner !== lease.owner ||
+				current.epoch !== lease.epoch
+			)
 				return current;
 			recorded = {
 				...current,
@@ -300,13 +380,17 @@ export class ChatEffectJournal {
 	async record<TPayload = unknown>(
 		id: string,
 		lease: ChatEffectLease,
-		state: Exclude<ChatEffectState, "pending" | "leased">,
-		receipt?: ChatEffectReceipt,
+		state: "accepted" | "uncertain" | "terminal",
+		receipt: ChatEffectReceipt = {},
 	): Promise<ChatEffect<TPayload> | undefined> {
 		let recorded: ChatEffect<TPayload> | undefined;
 		const now = this.#now();
 		await this.#store.transact(id, current => {
-			if (current?.state !== "leased" || current.owner !== lease.owner || current.epoch !== lease.epoch)
+			if (
+				(current?.state !== "leased" && current?.state !== "dispatching") ||
+				current.owner !== lease.owner ||
+				current.epoch !== lease.epoch
+			)
 				return current;
 			recorded = {
 				...current,
@@ -329,7 +413,10 @@ export class ChatEffectJournal {
 		const now = this.#now();
 		await this.#store.transact(id, current => {
 			if (!current || current.state === "terminal") return current;
-			if (current.state === "leased" && (!lease || current.owner !== lease.owner || current.epoch !== lease.epoch))
+			if (
+				(current.state === "leased" || current.state === "dispatching") &&
+				(!lease || current.owner !== lease.owner || current.epoch !== lease.epoch)
+			)
 				return current;
 
 			terminalized = {
@@ -347,6 +434,44 @@ export class ChatEffectJournal {
 		return terminalized;
 	}
 
+	/**
+	 * Terminalize only a decided effect. The uncertainty check and state change
+	 * share one store transaction so a concurrent sender cannot publish an
+	 * ambiguity tombstone between a caller's read and stale cleanup.
+	 */
+	async terminalizeDecided(
+		id: string,
+		receipt: ChatEffectReceipt,
+		lease?: ChatEffectLease,
+	): Promise<ChatEffect | undefined> {
+		let terminalized: ChatEffect | undefined;
+		const now = this.#now();
+		await this.#store.transact(id, current => {
+			if (!current || current.state === "uncertain") return current;
+			if (current.state === "terminal") {
+				terminalized = current;
+				return current;
+			}
+			if (
+				(current.state === "leased" || current.state === "dispatching") &&
+				(!lease || current.owner !== lease.owner || current.epoch !== lease.epoch)
+			)
+				return current;
+			terminalized = {
+				...current,
+				generation: current.generation + 1,
+				state: "terminal",
+				owner: undefined,
+				leaseExpiresAt: undefined,
+				receipt,
+				updatedAt: now,
+			};
+			return terminalized;
+		});
+		if (terminalized?.state === "terminal") await this.#pruneTerminal();
+		return terminalized;
+	}
+
 	async #pruneTerminal(): Promise<void> {
 		const terminal = (await this.list())
 			.filter(effect => effect.state === "terminal")

package/src/sdk/bus/conversation-store.ts

@@ -208,6 +208,35 @@ export class ConversationStore<T extends ConversationRecord> {
 		});
 	}
 
+	/**
+	 * Hold the cross-process mapping lock until a prepared dispatch either reaches
+	 * its synchronous wire boundary or fails before sending. The result may remain
+	 * pending after the lock is released while the remote response is awaited.
+	 */
+	async dispatchWithSnapshotFence<R>(
+		key: string,
+		prepare: (
+			current: T | undefined,
+			conversations: Readonly<Record<string, T>>,
+		) => { result: Promise<R>; dispatched: Promise<void> } | undefined,
+	): Promise<{ value: R } | undefined> {
+		let result: Promise<R> | undefined;
+		await this.#withLock(async () => {
+			const document = await this.#readDocument();
+			const prepared = prepare(document.conversations[key], Object.freeze({ ...document.conversations }));
+			if (!prepared) return;
+			result = prepared.result;
+			await Promise.race([
+				prepared.dispatched,
+				prepared.result.then(
+					() => undefined,
+					() => undefined,
+				),
+			]);
+		});
+		return result ? { value: await result } : undefined;
+	}
+
 	async #withLock<R>(operation: () => Promise<R>): Promise<R> {
 		const previous = this.#locks.get(this.#file) ?? Promise.resolve();
 		const gate = Promise.withResolvers<void>();

package/src/sdk/bus/lifecycle-commands.ts

@@ -15,10 +15,15 @@ import * as os from "node:os";
 import type { SessionCloseTarget, SessionCreateTarget, SessionLifecycleResponse, SessionResumeTarget } from "./index";
 
 export type LifecycleCommandVerb = "session_create" | "session_close" | "session_resume";
-function normalizeLifecycleCommandToken(
-	token: string,
-	ctx: { chatType?: string; botUsername?: string } = {},
-): string | undefined {
+
+export interface LifecycleCommandContext {
+	chatType?: string;
+	botUsername?: string;
+	/** Session durably associated with the Telegram topic containing the command. */
+	threadSessionId?: string;
+}
+
+function normalizeLifecycleCommandToken(token: string, ctx: LifecycleCommandContext = {}): string | undefined {
 	const at = token.indexOf("@");
 	const command = at === -1 ? token : token.slice(0, at);
 	if (!/^\/session_(create|close|resume|recent)\b/.test(command)) return undefined;
@@ -44,8 +49,8 @@ const USAGE = [
 	"/session_create path <dir> [--mpreset <profile>]",
 	"/session_create worktree <repo> <branch> [--mpreset <profile>]",
 	"/session_create dir <newdir> [--mpreset <profile>]",
-	"/session_close <sessionId>",
-	"/session_resume <sessionId|prefix>",
+	"/session_close <sessionId> (ID optional inside its session thread)",
+	"/session_resume <sessionId|prefix> (ID optional inside its session thread)",
 	"/session_recent [create|resume]",
 ].join("\n");
 
@@ -103,10 +108,7 @@ export function isLifecycleCommandLikeText(text: string | undefined): boolean {
 }
 
 /** True when the text begins an addressable /session_* command (cheap pre-gate). */
-export function isLifecycleCommandText(
-	text: string | undefined,
-	ctx: { chatType?: string; botUsername?: string } = {},
-): boolean {
+export function isLifecycleCommandText(text: string | undefined, ctx: LifecycleCommandContext = {}): boolean {
 	if (!text) return false;
 	const [rawCommand] = text.trim().split(/\s+/, 1);
 	return normalizeLifecycleCommandToken(rawCommand ?? "", ctx) !== undefined;
@@ -139,7 +141,7 @@ function extractModelPreset(args: string[]): { positional: string[]; modelPreset
  */
 export function parseLifecycleCommand(
 	text: string | undefined,
-	ctx: { chatType?: string; botUsername?: string } = {},
+	ctx: LifecycleCommandContext = {},
 ): ParsedLifecycleCommand {
 	const tokens = tokenizeLifecycleCommand((text ?? "").trim());
 	if (!tokens) return { kind: "usage", message: USAGE };
@@ -166,6 +168,8 @@ export function parseLifecycleCommand(
 	}
 
 	if (command === "/session_close") {
+		if (args.length === 0 && ctx.threadSessionId)
+			return { kind: "close", target: { sessionId: ctx.threadSessionId } };
 		if (args.length !== 1) return { kind: "usage", message: USAGE };
 		const sessionId = args[0]!;
 		if (!isSafeIdentifier(sessionId)) {
@@ -175,6 +179,8 @@ export function parseLifecycleCommand(
 	}
 
 	if (command === "/session_resume") {
+		if (args.length === 0 && ctx.threadSessionId)
+			return { kind: "resume", target: { sessionIdOrPrefix: ctx.threadSessionId } };
 		if (args.length !== 1) return { kind: "usage", message: USAGE };
 		const idOrPrefix = args[0]!;
 		if (!isSafeIdentifier(idOrPrefix)) {

package/src/sdk/bus/slack-conversation.ts

@@ -76,6 +76,7 @@ export function normalizeSlackConversation(record: SlackConversation): SlackConv
 export function acceptsSlackInbound(record: SlackConversation, rootTs: string, endpointGeneration: number): boolean {
 	return (
 		(record.state === "active" || record.state === "resumed_root") &&
+		record.cleanupEffectId === undefined &&
 		record.rootTs === rootTs &&
 		record.endpointGeneration === endpointGeneration
 	);