@gajae-code/coding-agent 0.16.7 → 0.17.1

package/src/coordinator-mcp/session-reaper.ts

@@ -3,12 +3,13 @@ import { logger } from "@gajae-code/utils";
 /**
  * Idle reaper for coordinator-managed GJC worker sessions.
  *
- * Every `gjc_delegate_*` call that omits `session_id` starts a fresh tmux worker
- * session. Nothing in the coordinator ever tore those down, so completed/crashed
- * sessions accumulated (RAM + worktrees) until something killed them by hand.
+ * New coordinator-owned sessions created by `gjc_coordinator_start_session` or by a
+ * `gjc_delegate_*` call that omits `session_id` are ephemeral. Nothing in the
+ * coordinator ever tore those down, so completed/crashed sessions accumulated
+ * (RAM + worktrees) until something killed them by hand.
  *
  * This is the automatic backstop (defense-in-depth): a periodic sweep force-closes
- * sessions that are (a) ephemeral — coordinator delegate-created, never a user's
+ * sessions that are (a) ephemeral — coordinator-created, never a user's
  * registered resident session, (b) not mid-turn, and (c) idle past a TTL.
  *
  * The controller is pure + fully injectable (clock / list / reap side-effects) so
@@ -21,11 +22,13 @@ export const DEFAULT_SESSION_IDLE_TTL_MS = 30 * 60_000; // 30 min idle → reap
 export const DEFAULT_SESSION_SWEEP_INTERVAL_MS = 5 * 60_000; // sweep every 5 min
 export const MIN_SESSION_IDLE_TTL_MS = 60_000; // never reap a <1min-idle session
 export const MIN_SESSION_SWEEP_INTERVAL_MS = 30_000;
+/** After this many consecutive reap failures the session is force-evicted from the index. */
+export const MAX_REAP_FAILURES = 3;
 
 /** Minimal projection of a coordinator session the reaper needs to decide. */
 export interface ReapableSession {
 	sessionId: string;
-	/** True only for coordinator delegate-created sessions. User-registered resident sessions are false and never reaped. */
+	/** True for newly coordinator-created sessions. User-registered resident sessions are false and never reaped. */
 	ephemeral: boolean;
 	/** Epoch ms of last observed activity (turn update / session-state write / session creation). */
 	lastActivityMs: number;
@@ -51,10 +54,29 @@ export function selectReapableSessions(
 	return sessions.filter(s => s.ephemeral && !s.hasActiveTurn && now - s.lastActivityMs >= ttl);
 }
 
+/**
+ * Only a stale/absent endpoint makes a session permanently unreapable, so it is
+ * the sole failure that advances the force-eviction counter. Every other reap
+ * failure (close_failed, broker unavailability, filesystem errors) is transient
+ * and must keep retrying without ever escalating to force eviction. The server
+ * wires `reapSession` to throw `new Error(reason)`, so the reason code is the
+ * error message here.
+ */
+function isEndpointStaleReapError(err: unknown): boolean {
+	return (err instanceof Error ? err.message : String(err)) === "endpoint_stale";
+}
+
 /** Injectable side-effects so the controller runs in tests without tmux/fs/real time. */
 export interface SessionReaperDeps {
 	listSessions: () => Promise<ReapableSession[]>;
 	reapSession: (sessionId: string) => Promise<void>;
+	/**
+	 * Force-evict a session from the coordinator index when it has exceeded the
+	 * consecutive-failure limit and cannot be reaped normally (e.g. endpoint_stale).
+	 * Called exactly once per session-id at the eviction boundary; the session must
+	 * not appear in future listSessions() results after this resolves.
+	 */
+	markSessionDead: (sessionId: string) => Promise<void>;
 	now: () => number;
 }
 
@@ -72,6 +94,8 @@ export function createSessionReaper(deps: SessionReaperDeps, policy: SessionReap
 	let timer: ReturnType<typeof setTimeout> | null = null;
 	let generation = 0;
 	let inProgress = false;
+	/** Consecutive reap-failure count per session-id. Cleared on success or eviction. */
+	const failureCounts = new Map<string, number>();
 
 	async function sweepOnce(): Promise<number> {
 		if (inProgress) return 0; // never overlap sweeps
@@ -83,12 +107,44 @@ export function createSessionReaper(deps: SessionReaperDeps, policy: SessionReap
 			for (const session of targets) {
 				try {
 					await deps.reapSession(session.sessionId);
+					// Success — clear any accumulated failure count.
+					failureCounts.delete(session.sessionId);
 					reaped += 1;
 				} catch (err) {
 					// One wedged session must not abort the rest of the sweep.
-					logger.warn(
-						`session-reaper: failed to reap ${session.sessionId}: ${err instanceof Error ? err.message : String(err)}`,
-					);
+					const msg = err instanceof Error ? err.message : String(err);
+					if (!isEndpointStaleReapError(err)) {
+						// Transient failure (close_failed, broker/filesystem error): a non-stale
+						// outcome breaks the consecutive-stale streak, so clear the counter and
+						// retry on the next sweep. Only genuinely consecutive endpoint_stale
+						// failures may accumulate toward force eviction.
+						logger.warn(`session-reaper: failed to reap ${session.sessionId}: ${msg}`);
+						failureCounts.delete(session.sessionId);
+						continue;
+					}
+					const prev = failureCounts.get(session.sessionId) ?? 0;
+					const count = prev + 1;
+					if (count < MAX_REAP_FAILURES) {
+						// First failure(s): log at warn and keep retrying next sweep.
+						logger.warn(`session-reaper: failed to reap ${session.sessionId}: ${msg}`);
+						failureCounts.set(session.sessionId, count);
+					} else {
+						// Hit the limit — evict unconditionally and silence future attempts.
+						logger.warn(
+							`session-reaper: session ${session.sessionId} evicted after ${count} consecutive failures (${msg})`,
+						);
+						failureCounts.delete(session.sessionId);
+						try {
+							await deps.markSessionDead(session.sessionId);
+						} catch (evictErr) {
+							// Eviction failure is non-fatal; the session will be retried next
+							// sweep and the counter has been cleared, so it will get MAX_REAP_FAILURES
+							// fresh chances before the next eviction attempt.
+							logger.warn(
+								`session-reaper: markSessionDead failed for ${session.sessionId}: ${evictErr instanceof Error ? evictErr.message : String(evictErr)}`,
+							);
+						}
+					}
 				}
 			}
 			return reaped;

package/src/cursor.ts

@@ -71,19 +71,30 @@ function buildToolErrorResult(message: string): AgentToolResult<unknown> {
 	};
 }
 
+/** Admission markers are control flow, not user-facing tool failures. */
+function isCursorExecAdmissionClosedError(error: unknown): boolean {
+	return (
+		typeof error === "object" &&
+		error !== null &&
+		(error as { name?: unknown }).name === "CursorExecAdmissionClosedError"
+	);
+}
+
 async function executeTool(
 	options: CursorExecBridgeOptions,
 	toolName: string,
 	toolCallId: string,
 	args: Record<string, unknown>,
 	overrideTool?: AgentTool,
+	execSignal?: AbortSignal,
+	markNonAbortable?: () => void,
 ): Promise<ToolResultMessage> {
+	if (execSignal?.aborted) throw cursorAbortError(execSignal);
 	const tool = overrideTool ?? options.tools.get(toolName);
 	if (!tool) {
 		const result = buildToolErrorResult(`Tool "${toolName}" not available`);
 		return createToolResultMessage(toolCallId, toolName, result, true);
 	}
-
 	// `tool` is the object this call will run; pass it so the start event carries proven
 	// provenance instead of a name a consumer would have to re-resolve later.
 	options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args }, tool);
@@ -108,14 +119,23 @@ async function executeTool(
 		: undefined;
 
 	try {
+		if (execSignal?.aborted) throw cursorAbortError(execSignal);
+		const toolContext = options.getToolContext?.();
+		if (execSignal?.aborted) throw cursorAbortError(execSignal);
+		if (tool.nonAbortable) markNonAbortable?.();
 		result = await tool.execute(
 			toolCallId,
 			args as Record<string, unknown>,
-			undefined,
+			// Non-abortable tools receive NO signal, matching agent-loop.ts: their
+			// returned promise must represent actual mutation settlement, so an
+			// untilAborted(signal, ...) rejection cannot make the settlement fence
+			// publish the terminal while the mutation is still running.
+			tool.nonAbortable ? undefined : (execSignal ?? undefined),
 			onUpdate,
-			options.getToolContext?.(),
+			toolContext,
 		);
 	} catch (error) {
+		if (isCursorExecAdmissionClosedError(error)) throw error;
 		const message = error instanceof Error ? error.message : String(error);
 		result = buildToolErrorResult(message);
 		isError = true;
@@ -131,9 +151,23 @@ async function executeTool(
 	return createToolResultMessage(toolCallId, toolName, result, isError);
 }
 
-async function executeDelete(options: CursorExecBridgeOptions, pathArg: string, toolCallId: string) {
+async function executeDelete(
+	options: CursorExecBridgeOptions,
+	pathArg: string,
+	toolCallId: string,
+	execSignal?: AbortSignal,
+	markNonAbortable?: () => void,
+) {
 	const toolName = "delete";
+	if (execSignal?.aborted) throw cursorAbortError(execSignal);
+	// Register the non-abortable mutation before notifying observers: a synchronous
+	// tool_execution_start subscriber may abort the run.
+	markNonAbortable?.();
 	options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args: { path: pathArg } });
+	if (execSignal?.aborted) throw cursorAbortError(execSignal);
+	// Delete is a filesystem mutation with no cooperative cancellation point:
+	// mark it non-abortable so the settlement fence publishes the exec terminal
+	// only once the unlink is final, matching write/edit dispatch.
 
 	const absolutePath = resolveToCwd(pathArg, options.cwd);
 	let isError = false;
@@ -201,6 +235,11 @@ function shellTimeoutSeconds(timeout: number | undefined): number | undefined {
 	return Math.max(1, Math.ceil(timeout / 1000));
 }
 
+function cursorAbortError(signal: AbortSignal): Error {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason : new Error("Request was aborted");
+}
+
 export class CursorExecHandlers implements ICursorExecHandlers {
 	constructor(private options: CursorExecBridgeOptions) {
 		// Bind every native handler so methods stay instance-safe when invoked
@@ -242,20 +281,44 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 		};
 	}
 
-	async read(args: Parameters<NonNullable<ICursorExecHandlers["read"]>>[0]) {
+	async read(
+		args: Parameters<NonNullable<ICursorExecHandlers["read"]>>[0],
+		signal?: AbortSignal,
+		markNonAbortable?: () => void,
+	) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
-		const toolResultMessage = await executeTool(this.#optionsForCall(), "read", toolCallId, { path: args.path });
+		const toolResultMessage = await executeTool(
+			this.#optionsForCall(),
+			"read",
+			toolCallId,
+			{ path: args.path },
+			undefined,
+			signal,
+			markNonAbortable,
+		);
 		return toolResultMessage;
 	}
 
-	async ls(args: Parameters<NonNullable<ICursorExecHandlers["ls"]>>[0]) {
+	async ls(
+		args: Parameters<NonNullable<ICursorExecHandlers["ls"]>>[0],
+		signal?: AbortSignal,
+		markNonAbortable?: () => void,
+	) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
 		// Redirect ls to read tool, which handles directories
-		const toolResultMessage = await executeTool(this.#optionsForCall(), "read", toolCallId, { path: args.path });
+		const toolResultMessage = await executeTool(
+			this.#optionsForCall(),
+			"read",
+			toolCallId,
+			{ path: args.path },
+			undefined,
+			signal,
+			markNonAbortable,
+		);
 		return toolResultMessage;
 	}
 
-	async grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0]) {
+	async grep(args: Parameters<NonNullable<ICursorExecHandlers["grep"]>>[0], signal?: AbortSignal) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
 		// Cursor's native Glob tool arrives as a grep exec with a glob but no content
 		// pattern. The search tool requires a non-empty pattern, so an empty pattern
@@ -265,7 +328,7 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 		if (pattern.trim().length === 0) {
 			if (args.glob) {
 				const globPath = `${args.path || "."}/${args.glob}`;
-				return executeTool(this.#optionsForCall(), "find", toolCallId, { paths: [globPath] });
+				return executeTool(this.#optionsForCall(), "find", toolCallId, { paths: [globPath] }, undefined, signal);
 			}
 			const result = buildToolErrorResult(
 				"Cursor grep request rejected: pattern must not be empty. Provide a non-empty search pattern.",
@@ -273,45 +336,90 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 			return createToolResultMessage(toolCallId, "search", result, true);
 		}
 		const searchPath = args.glob ? `${args.path || "."}/${args.glob}` : args.path || ".";
-		const toolResultMessage = await executeTool(this.#optionsForCall(), "search", toolCallId, {
-			pattern,
-			paths: [searchPath],
-			i: args.caseInsensitive || undefined,
-		});
+		const toolResultMessage = await executeTool(
+			this.#optionsForCall(),
+			"search",
+			toolCallId,
+			{
+				pattern,
+				paths: [searchPath],
+				i: args.caseInsensitive || undefined,
+			},
+			undefined,
+			signal,
+		);
 		return toolResultMessage;
 	}
 
-	async write(args: Parameters<NonNullable<ICursorExecHandlers["write"]>>[0]) {
+	async write(
+		args: Parameters<NonNullable<ICursorExecHandlers["write"]>>[0],
+		signal?: AbortSignal,
+		markNonAbortable?: () => void,
+	) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
 		const content = args.fileText ?? new TextDecoder().decode(args.fileBytes ?? new Uint8Array());
-		const toolResultMessage = await executeTool(this.#optionsForCall(), "write", toolCallId, {
-			path: args.path,
-			content,
-		});
+		const toolResultMessage = await executeTool(
+			this.#optionsForCall(),
+			"write",
+			toolCallId,
+			{
+				path: args.path,
+				content,
+			},
+			undefined,
+			signal,
+			markNonAbortable,
+		);
 		return toolResultMessage;
 	}
 
-	async delete(args: Parameters<NonNullable<ICursorExecHandlers["delete"]>>[0]) {
+	async delete(
+		args: Parameters<NonNullable<ICursorExecHandlers["delete"]>>[0],
+		signal?: AbortSignal,
+		markNonAbortable?: () => void,
+	) {
+		if (signal?.aborted) throw cursorAbortError(signal);
 		const toolCallId = decodeToolCallId(args.toolCallId);
-		const toolResultMessage = await executeDelete(this.#optionsForCall(), args.path, toolCallId);
+		const toolResultMessage = await executeDelete(
+			this.#optionsForCall(),
+			args.path,
+			toolCallId,
+			signal,
+			markNonAbortable,
+		);
 		return toolResultMessage;
 	}
 
-	async shell(args: Parameters<NonNullable<ICursorExecHandlers["shell"]>>[0]) {
+	async shell(
+		args: Parameters<NonNullable<ICursorExecHandlers["shell"]>>[0],
+		signal?: AbortSignal,
+		markNonAbortable?: () => void,
+	) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
 		const timeoutSeconds = shellTimeoutSeconds(args.timeout);
-		const toolResultMessage = await executeTool(this.#optionsForCall(), "bash", toolCallId, {
-			command: args.command,
-			cwd: args.workingDirectory || undefined,
-			timeout: timeoutSeconds,
-		});
+		const toolResultMessage = await executeTool(
+			this.#optionsForCall(),
+			"bash",
+			toolCallId,
+			{
+				command: args.command,
+				cwd: args.workingDirectory || undefined,
+				timeout: timeoutSeconds,
+			},
+			undefined,
+			signal,
+			markNonAbortable,
+		);
 		return toolResultMessage;
 	}
 
 	async shellStream(
 		args: Parameters<NonNullable<ICursorExecHandlers["shellStream"]>>[0],
 		callbacks: CursorShellStreamCallbacks,
+		signal?: AbortSignal,
+		markNonAbortable?: () => void,
 	) {
+		if (signal?.aborted) throw cursorAbortError(signal);
 		const options = this.#optionsForCall();
 		const toolCallId = decodeToolCallId(args.toolCallId);
 		const toolName = "bash";
@@ -329,6 +437,7 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 		};
 
 		options.emitEvent?.({ type: "tool_execution_start", toolCallId, toolName, args: toolArgs }, tool);
+		if (signal?.aborted) throw cursorAbortError(signal);
 
 		let result: AgentToolResult<unknown>;
 		let isError = false;
@@ -373,8 +482,13 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 		};
 
 		try {
-			result = await tool.execute(toolCallId, toolArgs, undefined, onUpdate, options.getToolContext?.());
+			const nonAbortable = tool.nonAbortable === true;
+			const toolContext = options.getToolContext?.();
+			if (signal?.aborted) throw cursorAbortError(signal);
+			if (nonAbortable) markNonAbortable?.();
+			result = await tool.execute(toolCallId, toolArgs, nonAbortable ? undefined : signal, onUpdate, toolContext);
 		} catch (error) {
+			if (isCursorExecAdmissionClosedError(error)) throw error;
 			const message = error instanceof Error ? error.message : String(error);
 			result = buildToolErrorResult(message);
 			isError = true;
@@ -414,14 +528,30 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 		if (composed === null) {
 			return createToolResultMessage(call.toolCallId, "read", { content: [{ type: "text", text: "" }] }, false);
 		}
-		return executeTool(this.#optionsForCall(), "read", call.toolCallId, { path: composed });
+		return executeTool(
+			this.#optionsForCall(),
+			"read",
+			call.toolCallId,
+			{ path: composed },
+			undefined,
+			call.signal,
+			call.markNonAbortable,
+		);
 	}
 
 	async piBash(call: Parameters<NonNullable<ICursorExecHandlers["piBash"]>>[0]) {
-		return executeTool(this.#optionsForCall(), "bash", call.toolCallId, {
-			command: call.args.command,
-			timeout: piTimeout(call.args.timeout),
-		});
+		return executeTool(
+			this.#optionsForCall(),
+			"bash",
+			call.toolCallId,
+			{
+				command: call.args.command,
+				timeout: piTimeout(call.args.timeout),
+			},
+			undefined,
+			call.signal,
+			call.markNonAbortable,
+		);
 	}
 
 	async piEdit(call: Parameters<NonNullable<ICursorExecHandlers["piEdit"]>>[0]) {
@@ -435,14 +565,24 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 			call.toolCallId,
 			{ path: call.args.path, edits },
 			this.options.getEditReplaceTool?.(),
+			call.signal,
+			call.markNonAbortable,
 		);
 	}
 
 	async piWrite(call: Parameters<NonNullable<ICursorExecHandlers["piWrite"]>>[0]) {
-		return executeTool(this.#optionsForCall(), "write", call.toolCallId, {
-			path: call.args.path,
-			content: call.args.content,
-		});
+		return executeTool(
+			this.#optionsForCall(),
+			"write",
+			call.toolCallId,
+			{
+				path: call.args.path,
+				content: call.args.content,
+			},
+			undefined,
+			call.signal,
+			call.markNonAbortable,
+		);
 	}
 
 	async piGrep(call: Parameters<NonNullable<ICursorExecHandlers["piGrep"]>>[0]) {
@@ -456,33 +596,55 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 			paths: [glob ? piJoinPath(path, glob) : path || "."],
 		};
 		if (ignoreCase === true) args.i = true;
-		return executeTool(this.#optionsForCall(), "search", call.toolCallId, args, perCallSearch);
+		return executeTool(this.#optionsForCall(), "search", call.toolCallId, args, perCallSearch, call.signal);
 	}
 
 	async piFind(call: Parameters<NonNullable<ICursorExecHandlers["piFind"]>>[0]) {
 		const { pattern, path, limit } = call.args;
-		return executeTool(this.#optionsForCall(), "find", call.toolCallId, {
-			paths: [piJoinPath(path, pattern)],
-			limit: piLimit(limit),
-		});
+		return executeTool(
+			this.#optionsForCall(),
+			"find",
+			call.toolCallId,
+			{
+				paths: [piJoinPath(path, pattern)],
+				limit: piLimit(limit),
+			},
+			undefined,
+			call.signal,
+		);
 	}
 
 	async piLs(call: Parameters<NonNullable<ICursorExecHandlers["piLs"]>>[0]) {
-		return executeTool(this.#optionsForCall(), "read", call.toolCallId, {
-			path: piLsPath(call.args.path),
-		});
+		return executeTool(
+			this.#optionsForCall(),
+			"read",
+			call.toolCallId,
+			{
+				path: piLsPath(call.args.path),
+			},
+			undefined,
+			call.signal,
+			call.markNonAbortable,
+		);
 	}
 
-	async diagnostics(args: Parameters<NonNullable<ICursorExecHandlers["diagnostics"]>>[0]) {
+	async diagnostics(args: Parameters<NonNullable<ICursorExecHandlers["diagnostics"]>>[0], signal?: AbortSignal) {
 		const toolCallId = decodeToolCallId(args.toolCallId);
-		const toolResultMessage = await executeTool(this.#optionsForCall(), "lsp", toolCallId, {
-			action: "diagnostics",
-			file: args.path,
-		});
+		const toolResultMessage = await executeTool(
+			this.#optionsForCall(),
+			"lsp",
+			toolCallId,
+			{
+				action: "diagnostics",
+				file: args.path,
+			},
+			undefined,
+			signal,
+		);
 		return toolResultMessage;
 	}
 
-	async mcp(call: CursorMcpCall) {
+	async mcp(call: CursorMcpCall, signal?: AbortSignal, markNonAbortable?: () => void) {
 		const options = this.#optionsForCall();
 		const toolName = call.toolName || call.name;
 		const toolCallId = decodeToolCallId(call.toolCallId);
@@ -495,7 +657,15 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 		}
 
 		const args = Object.keys(call.args ?? {}).length > 0 ? call.args : decodeMcpArgs(call.rawArgs ?? {});
-		const toolResultMessage = await executeTool(options, toolName, toolCallId, args);
+		const toolResultMessage = await executeTool(
+			options,
+			toolName,
+			toolCallId,
+			args,
+			undefined,
+			signal,
+			markNonAbortable,
+		);
 		return toolResultMessage;
 	}
 }