@gajae-code/coding-agent 0.2.5 → 0.3.0

package/src/modes/controllers/input-controller.ts

@@ -31,7 +31,7 @@ export class InputController {
 	constructor(private ctx: InteractiveModeContext) {}
 
 	#abortInteractive(): Promise<void> {
-		return this.ctx.session.abort({ timeoutMs: INTERACTIVE_ABORT_CLEANUP_TIMEOUT_MS });
+		return this.ctx.session.abort({ timeoutMs: INTERACTIVE_ABORT_CLEANUP_TIMEOUT_MS, cause: "user_interrupt" });
 	}
 
 	setupKeyHandlers(): void {
@@ -568,6 +568,14 @@ export class InputController {
 			this.ctx.retryLoader.stop();
 			this.ctx.retryLoader = undefined;
 		}
+		if (this.ctx.retryCountdownTimer) {
+			clearInterval(this.ctx.retryCountdownTimer);
+			this.ctx.retryCountdownTimer = undefined;
+		}
+		if (this.ctx.retryEscapeHandler) {
+			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
+			this.ctx.retryEscapeHandler = undefined;
+		}
 		this.ctx.statusContainer.clear();
 		this.ctx.statusLine.dispose();
 

package/src/modes/controllers/selector-controller.ts

@@ -57,12 +57,13 @@ import { TreeSelectorComponent } from "../components/tree-selector";
 import { UserMessageSelectorComponent } from "../components/user-message-selector";
 import type { SessionObserverRegistry } from "../session-observer-registry";
 
-const CALLBACK_SERVER_PROVIDERS = new Set<OAuthProvider>([
+const CALLBACK_SERVER_PROVIDERS = new Set<string>([
 	"anthropic",
 	"openai-codex",
 	"gitlab-duo",
 	"google-gemini-cli",
 	"google-antigravity",
+	"xai",
 ]);
 
 const MANUAL_LOGIN_TIP = "Tip: You can complete pairing with /login <redirect URL>.";

package/src/modes/interactive-mode.ts

@@ -276,6 +276,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	}
 	autoCompactionEscapeHandler?: () => void;
 	retryEscapeHandler?: () => void;
+	retryCountdownTimer?: ReturnType<typeof setInterval>;
 	unsubscribe?: () => void;
 	onInputCallback?: (input: SubmittedUserInput) => void;
 	optimisticUserMessageSignature: string | undefined = undefined;

package/src/modes/types.ts

@@ -109,6 +109,7 @@ export interface InteractiveModeContext {
 	retryLoader: Loader | undefined;
 	autoCompactionEscapeHandler?: () => void;
 	retryEscapeHandler?: () => void;
+	retryCountdownTimer?: ReturnType<typeof setInterval>;
 	unsubscribe?: () => void;
 	onInputCallback?: (input: SubmittedUserInput) => void;
 	optimisticUserMessageSignature: string | undefined;

package/src/prompts/agents/executor.md

@@ -31,6 +31,19 @@ Explore just enough context, implement the smallest correct change, and leave co
 5. Remove debug leftovers and report changed files plus evidence.
 </execution_loop>
 
+<ultragoal_red_team_mode>
+This mode activates only when the assignment explicitly labels Executor as Ultragoal completion QA/red-team or asks for `executorQa` red-team evidence. Otherwise, preserve ordinary Executor behavior.
+
+When active:
+- Start from the approved plan/spec/acceptance criteria, then user-facing contracts, then implementation code only as supporting evidence. Treat plan/code mismatches as blockers.
+- Exercise the real user-facing invocation rather than inspecting internals alone: GUI/web uses browser automation plus screenshot or image verdict; CLI uses logs or terminal transcripts; API/package uses external consumer or black-box tests through the public interface; algorithm/math uses boundary, property, adversarial, and failure-mode cases.
+- Try to break the work with adversarial cases, not just happy-path confirmations.
+- Report the QA matrix with the final field names `executorQa.contractCoverage`, `executorQa.surfaceEvidence`, `executorQa.adversarialCases`, and `executorQa.artifactRefs`.
+- Include artifact refs for every executed surface and adversarial case: transcript ids, log paths, screenshots, image verdicts, test outputs, or other durable evidence.
+- Use `status: "not_applicable"` only for rows in `executorQa.contractCoverage` and `executorQa.surfaceEvidence`; each not-applicable row requires `contractRef` plus `reason`. `executorQa.adversarialCases` rows cannot be not-applicable.
+- Report blockers for any missing plan/spec/acceptance source, contract ambiguity, plan/code mismatch, untestable surface, failed adversarial case, shallow evidence, or missing artifact ref.
+</ultragoal_red_team_mode>
+
 <success_criteria>
 - Requested behavior is implemented in the assigned scope.
 - Modified files match existing style and contracts.

package/src/prompts/tools/subagent.md

@@ -1,11 +1,11 @@
-Lists, inspects, awaits, or cancels detached task subagents.
+Lists, inspects, awaits, pauses, resumes, steers, or cancels detached task subagents.
 
 Task launches return immediately. Use this tool when you need direct control over those running subagents. Prefer `subagent` for task subagents; generic `job` remains available for non-subagent jobs and compatibility fallback access.
 
 # Operations
 
 ## `action: "list"`
-Snapshot your visible detached subagents.
+Snapshot your visible detached subagents, including `running`, `paused`, `queued`, and terminal subagents when retained.
 
 ## `action: "inspect"`
 Inspect selected subagents by `ids`; omit `ids` to inspect current running subagents. Terminal subagents include final output when retained.
@@ -16,6 +16,36 @@ Wait for selected subagents by `ids`; omit `ids` to wait for current running sub
 - Await timeout only bounds this tool call's wait; it does not stop the subagent and is not a failure reason.
 - On timeout, inspect progress and keep doing independent work. Never cancel just because an await timed out; cancel only if the subagent has actually failed, gone off-track, or become unrecoverably wrong.
 
+## `action: "pause"`
+Request a graceful safe-boundary pause for selected subagents by `ids`.
+- Non-running subagents are a no-op and return their current status snapshot.
+- A paused subagent keeps its session context and can be resumed later.
+
+## `action: "resume"`
+Resume selected non-running subagents by `ids`.
+- Optional `message` is delivered into the resumed run.
+- Running subagents are a no-op and return their current status snapshot.
+- Terminal subagents require `message` to start a follow-up resume run; without `message`, the tool returns the current snapshot with guidance.
+- `paused` subagents resume from saved context; `queued` subagents are already waiting for capacity.
+
+## `action: "steer"`
+Send a non-empty `message` to selected subagents by `ids`.
+- Running subagents receive the message through their live handle.
+- Optional `pause: true` requests a safe-boundary pause after steering a running subagent.
+- `pause` only matters while the target is running.
+- Non-active subagents (`paused`, `queued`, or terminal) automatically resume with the message; `pause` is ignored for these targets.
+
 ## `action: "cancel"`
-Stop selected running subagents by `ids`.
+Stop selected subagents by `ids`, including running, paused, or queued subagents.
 - Use only when the subagent has actually failed, gone off-track, or become unrecoverably wrong; an await timeout alone is never a cancellation reason.
+- Cancellation keeps the subagent session file for possible later context recovery.
+
+# Statuses
+
+- `running` — currently executing.
+- `paused` — stopped at a safe boundary with resumable context.
+- `queued` — resume requested and waiting for execution capacity.
+- `completed` — finished successfully.
+- `failed` — finished with an error.
+- `cancelled` — stopped by cancellation.
+- `not_found` — no visible subagent matches the requested id.

package/src/sdk.ts

@@ -327,6 +327,8 @@ export interface CreateAgentSessionOptions {
 	forkContextSeed?: ForkContextSeed;
 	/** Optional provider state override. Fork-context children should omit this by default. */
 	providerSessionState?: Map<string, ProviderSessionState>;
+	/** Cooperative pause checkpoint passed through to Agent. */
+	shouldPause?: () => boolean;
 }
 
 /** Result from createAgentSession */
@@ -657,6 +659,7 @@ function createCustomToolsExtension(tools: CustomTool[]): ExtensionFactory {
 					reason: "auto_retry_start",
 					attempt: event.attempt,
 					maxAttempts: event.maxAttempts,
+					unbounded: event.unbounded,
 					delayMs: event.delayMs,
 					errorMessage: event.errorMessage,
 				},
@@ -1797,6 +1800,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			requestMaxRetries: retrySettings.requestMaxRetries,
 			streamMaxRetries: retrySettings.streamMaxRetries,
 			kimiApiFormat: settings.get("providers.kimiApiFormat") ?? "anthropic",
+			shouldPause: options.shouldPause,
 			preferWebsockets: preferOpenAICodexWebsockets,
 			getToolContext: tc => toolContextStore.getContext(tc),
 			getApiKey: async provider => {

package/src/session/agent-session.ts

@@ -167,6 +167,7 @@ import type { HookCommandContext } from "../extensibility/hooks/types";
 import type { Skill, SkillWarning } from "../extensibility/skills";
 import { expandSlashCommand, type FileSlashCommand } from "../extensibility/slash-commands";
 import { buildGjcRuntimeSessionEnv, consumePendingGoalModeRequest } from "../gjc-runtime/goal-mode-request";
+import { writeArtifact } from "../gjc-runtime/state-writer";
 import { requestGjcWorkerIntegrationAttempt } from "../gjc-runtime/team-runtime";
 import { GoalRuntime } from "../goals/runtime";
 import type { Goal, GoalModeState } from "../goals/state";
@@ -263,7 +264,14 @@ export type AgentSessionEvent =
 			/** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
 			skipped?: boolean;
 	  }
-	| { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
+	| {
+			type: "auto_retry_start";
+			attempt: number;
+			maxAttempts: number;
+			delayMs: number;
+			errorMessage: string;
+			unbounded?: boolean;
+	  }
 	| { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string }
 	| { type: "retry_fallback_applied"; from: string; to: string; role: string }
 	| { type: "retry_fallback_succeeded"; model: string; role: string }
@@ -282,6 +290,11 @@ export type AgentSessionEvent =
  */
 const SAFE_PATH_COMPONENT = /^[A-Za-z0-9_-][A-Za-z0-9._-]{0,63}$/;
 
+function isUnderProjectGjc(cwd: string, targetPath: string): boolean {
+	const relative = path.relative(path.join(path.resolve(cwd), ".gjc"), path.resolve(targetPath));
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
@@ -852,6 +865,7 @@ export class AgentSession {
 
 	// Retry state
 	#retryAbortController: AbortController | undefined = undefined;
+	#retryNowRequested = false;
 	#retryAttempt = 0;
 	#retryPromise: Promise<void> | undefined = undefined;
 	#retryResolve: (() => void) | undefined = undefined;
@@ -1887,6 +1901,15 @@ export class AgentSession {
 						attempt: this.#retryAttempt,
 					});
 					this.#retryAttempt = 0;
+					// Settle the retry gate here, colocated with the success event, rather
+					// than relying on the generic #resolveRetry() at the end of the
+					// agent_end branch. That tail resolver is bypassed by every early
+					// return in agent_end (successful `yield`, handoff-abort skip-maintenance,
+					// missing assistant message), so a retry that recovers on a yield turn
+					// would otherwise leave #retryPromise unresolved — wedging
+					// #waitForPostPromptRecovery and the session as permanently busy.
+					// #resolveRetry() is idempotent, so the later tail call is a no-op.
+					this.#resolveRetry();
 				}
 			}
 
@@ -2001,6 +2024,18 @@ export class AgentSession {
 				const didRetry = await this.#handleRetryableError(msg);
 				if (didRetry) return; // Retry was initiated, don't proceed to compaction
 			}
+			if (this.#retryAttempt > 0) {
+				// A prior retry ended on a non-retryable (terminal) message: emit
+				// the terminal retry-end and reset so observers clear retry state.
+				const attempt = this.#retryAttempt;
+				this.#retryAttempt = 0;
+				await this.#emitSessionEvent({
+					type: "auto_retry_end",
+					success: false,
+					attempt,
+					finalError: msg.errorMessage,
+				});
+			}
 			this.#resolveRetry();
 
 			const compactionTask = this.#checkCompaction(msg);
@@ -2871,6 +2906,7 @@ export class AgentSession {
 				maxAttempts: event.maxAttempts,
 				delayMs: event.delayMs,
 				errorMessage: event.errorMessage,
+				unbounded: event.unbounded,
 			});
 		} else if (event.type === "auto_retry_end") {
 			await this.#extensionRunner.emit({
@@ -3485,7 +3521,7 @@ export class AgentSession {
 	 * prompts or tool execution can run.
 	 */
 	#wrapToolForDeepInterviewMutationGuard<T extends AgentTool>(tool: T): T {
-		if (!["edit", "write", "ast_edit"].includes(tool.name)) return tool;
+		if (!["edit", "write", "ast_edit", "bash"].includes(tool.name)) return tool;
 		return new Proxy(tool, {
 			get: (target, prop) => {
 				if (prop !== "execute") return Reflect.get(target, prop, target);
@@ -5027,7 +5063,18 @@ export class AgentSession {
 	/**
 	 * Abort current operation and wait for agent to become idle.
 	 */
-	async abort(options?: { goalReason?: "interrupted" | "internal"; timeoutMs?: number }): Promise<void> {
+	async abort(options?: {
+		goalReason?: "interrupted" | "internal";
+		timeoutMs?: number;
+		cause?:
+			| "user_interrupt"
+			| "new_session"
+			| "session_switch"
+			| "compaction"
+			| "handoff"
+			| "tool_abort"
+			| "internal";
+	}): Promise<void> {
 		this.abortRetry();
 		this.#promptGeneration++;
 		this.#scheduledHiddenNextTurnGeneration = undefined;
@@ -5074,6 +5121,18 @@ export class AgentSession {
 		if (this.#toolChoiceQueue.hasInFlight) {
 			this.#toolChoiceQueue.reject("aborted");
 		}
+
+		// Steer-on-interrupt: after a genuine user interrupt, resume with any
+		// queued steering instead of going idle. Lifecycle/teardown causes
+		// (default "internal") suppress this; new-session/handoff additionally
+		// clear the steering queue, and compaction resumes via its own path.
+		if ((options?.cause ?? "internal") === "user_interrupt" && this.agent.hasQueuedSteering()) {
+			this.#scheduleAgentContinue({
+				delayMs: 1,
+				generation: this.#promptGeneration,
+				shouldContinue: () => this.agent.hasQueuedSteering(),
+			});
+		}
 	}
 
 	/**
@@ -5931,7 +5990,14 @@ export class AgentSession {
 				if (artifactsDir) {
 					const handoffFilePath = path.join(artifactsDir, createHandoffFileName());
 					try {
-						await Bun.write(handoffFilePath, `${handoffText}\n`);
+						if (isUnderProjectGjc(this.sessionManager.getCwd(), handoffFilePath)) {
+							await writeArtifact(handoffFilePath, `${handoffText}\n`, {
+								cwd: this.sessionManager.getCwd(),
+								audit: { category: "artifact", verb: "write", owner: "gjc-runtime" },
+							});
+						} else {
+							await Bun.write(handoffFilePath, `${handoffText}\n`);
+						}
 						savedPath = handoffFilePath;
 					} catch (error) {
 						logger.warn("Failed to save handoff document to disk", {
@@ -7121,19 +7187,14 @@ export class AgentSession {
 	// =========================================================================
 
 	/**
-	 * Check if an error is retryable (transient errors or usage limits).
-	 * Context overflow errors are NOT retryable (handled by compaction instead).
-	 * Usage-limit errors are retryable because the retry handler performs credential switching.
+	 * Whether an error should be retried. Uses the ordered classifier:
+	 * context-overflow routes to compaction; clearly-terminal coded errors
+	 * (auth/400/not-found) surface immediately; usage-limit, transient, and
+	 * unknown/no-code errors are retryable.
 	 */
 	#isRetryableError(message: AssistantMessage): boolean {
-		if (message.stopReason !== "error" || !message.errorMessage) return false;
-
-		// Context overflow is handled by compaction, not retry
-		const contextWindow = this.model?.contextWindow ?? 0;
-		if (isContextOverflow(message, contextWindow)) return false;
-
-		const err = message.errorMessage;
-		return this.#isTransientErrorMessage(err) || isUsageLimitError(err);
+		const classification = this.#classifyErrorForRetry(message);
+		return classification === "usage_limit" || classification === "transient" || classification === "unknown";
 	}
 
 	#isTransientErrorMessage(errorMessage: string): boolean {
@@ -7159,6 +7220,63 @@ export class AgentSession {
 		);
 	}
 
+	#isTerminalErrorMessage(errorMessage: string): boolean {
+		// Errors that will never succeed on retry (auth/permission, malformed
+		// request, unknown/unsupported model). These surface immediately rather
+		// than retry forever.
+		return /unauthorized|forbidden|authentication_error|permission_error|permission denied|invalid api key|invalid_request_error|invalid request|bad request|bad_request|validation_error|unprocessable|payload too large|payment required|insufficient_quota|insufficient credits|missing required (parameter|field)|invalid schema|invalid tool_choice|unsupported (parameter|value|model)|model_not_found|no such model|unknown model|does not (exist|support)|request was aborted|request aborted|the user aborted/i.test(
+			errorMessage,
+		);
+	}
+
+	#extractExplicitHttpStatusFromErrorMessage(errorMessage: string): number | undefined {
+		// Parse only explicit HTTP/status wording. Do not treat generic
+		// `error: 400` as an HTTP status because rate-limit copy can say
+		// "rate limit error: 400 requests per minute".
+		const match = /\b(?:http(?:\s+status)?|status(?:[\s_-]+code)?)(?:\s+|[:=]\s*)(\d{3})\b/i.exec(errorMessage);
+		if (!match) return undefined;
+		const status = Number(match[1]);
+		return Number.isFinite(status) && status >= 100 && status <= 599 ? status : undefined;
+	}
+
+	/**
+	 * Ordered retry classification: overflow (compaction) -> terminal (surface)
+	 * -> usage_limit (rotation) -> transient (retry) -> unknown (retry).
+	 */
+	#classifyErrorForRetry(
+		message: AssistantMessage,
+	): "none" | "overflow" | "terminal" | "usage_limit" | "transient" | "unknown" {
+		if (message.stopReason !== "error" || !message.errorMessage) return "none";
+		const contextWindow = this.model?.contextWindow ?? 0;
+		if (isContextOverflow(message, contextWindow)) return "overflow";
+		const err = message.errorMessage;
+		// Stream-envelope errors are only transient in the pre-message_start
+		// variant; any other envelope failure is structural and must surface.
+		if (/anthropic stream envelope error:/i.test(err)) {
+			return this.#isTransientEnvelopeErrorMessage(err) ? "transient" : "terminal";
+		}
+		const explicitStatus = this.#extractExplicitHttpStatusFromErrorMessage(err);
+		const structuredStatus = message.errorStatus;
+		const terminalStatus = explicitStatus ?? structuredStatus;
+		const isTerminalHttp4xx =
+			terminalStatus !== undefined &&
+			terminalStatus >= 400 &&
+			terminalStatus < 500 &&
+			terminalStatus !== 408 &&
+			terminalStatus !== 425 &&
+			terminalStatus !== 429;
+		if (this.#isTerminalErrorMessage(err)) return "terminal";
+		if (isUsageLimitError(err)) return "usage_limit";
+		// Explicit HTTP/status wording is authoritative. Structured provider status
+		// is also authoritative except for rate-limit copy where providers may have
+		// parsed an incidental quota number such as "400 requests per minute".
+		if (isTerminalHttp4xx && (explicitStatus !== undefined || !/rate.?limit|too many requests/i.test(err))) {
+			return "terminal";
+		}
+		if (this.#isTransientErrorMessage(err)) return "transient";
+		return "unknown";
+	}
+
 	#getRetryFallbackChains(): RetryFallbackChains {
 		const configuredChains = this.settings.get("retry.fallbackChains");
 		if (!configuredChains || typeof configuredChains !== "object") return {};
@@ -7428,6 +7546,8 @@ export class AgentSession {
 	async #handleRetryableError(message: AssistantMessage): Promise<boolean> {
 		const retrySettings = this.settings.getGroup("retry");
 		if (!retrySettings.enabled) return false;
+		const retryClassification = this.#classifyErrorForRetry(message);
+		const unboundedClass = retryClassification === "transient" || retryClassification === "unknown";
 
 		const generation = this.#promptGeneration;
 		this.#retryAttempt++;
@@ -7440,7 +7560,7 @@ export class AgentSession {
 			this.#retryResolve = resolve;
 		}
 
-		if (this.#retryAttempt > retrySettings.maxRetries) {
+		if (!unboundedClass && this.#retryAttempt > retrySettings.maxRetries) {
 			// Max retries exceeded, emit final failure and reset
 			await this.#emitSessionEvent({
 				type: "auto_retry_end",
@@ -7497,7 +7617,16 @@ export class AgentSession {
 		// assistant error message is preserved in agent state so the caller
 		// can act on it.
 		const maxDelayMs = retrySettings.maxDelayMs;
-		if (maxDelayMs > 0 && delayMs > maxDelayMs && !switchedCredential && !switchedModel) {
+		if (unboundedClass && !switchedCredential && !switchedModel) {
+			// Retry forever: honor a provider-supplied wait, otherwise cap the
+			// exponential backoff at the ceiling instead of giving up.
+			if (parsedRetryAfterMs !== undefined) {
+				delayMs = Math.max(delayMs, parsedRetryAfterMs);
+			} else if (maxDelayMs > 0) {
+				delayMs = Math.min(delayMs, maxDelayMs);
+			}
+		}
+		if (!unboundedClass && maxDelayMs > 0 && delayMs > maxDelayMs && !switchedCredential && !switchedModel) {
 			const attempt = this.#retryAttempt;
 			this.#retryAttempt = 0;
 			await this.#emitSessionEvent({
@@ -7510,12 +7639,22 @@ export class AgentSession {
 			return false;
 		}
 
+		// Create and install the backoff abort controller BEFORE emitting
+		// auto_retry_start, so a synchronous retryNow()/abortRetry() invoked from
+		// an event subscriber (e.g. the TUI Esc handler) is not lost in the gap
+		// between the event and the controller assignment.
+		const retryAbortController = new AbortController();
+		this.#retryAbortController?.abort();
+		this.#retryAbortController = retryAbortController;
+		this.#retryNowRequested = false;
+
 		await this.#emitSessionEvent({
 			type: "auto_retry_start",
 			attempt: this.#retryAttempt,
 			maxAttempts: retrySettings.maxRetries,
 			delayMs,
 			errorMessage,
+			unbounded: unboundedClass,
 		});
 
 		// Remove error message from agent state (keep in session for history)
@@ -7525,34 +7664,49 @@ export class AgentSession {
 		}
 
 		// Wait with exponential backoff (abortable).
-		const retryAbortController = new AbortController();
-		this.#retryAbortController?.abort();
-		this.#retryAbortController = retryAbortController;
 		try {
 			await scheduler.wait(delayMs, { signal: retryAbortController.signal });
 		} catch {
 			if (this.#retryAbortController !== retryAbortController) {
 				return false;
 			}
-			// Aborted during sleep - emit end event so UI can clean up
-			const attempt = this.#retryAttempt;
-			this.#retryAttempt = 0;
 			this.#retryAbortController = undefined;
-			await this.#emitSessionEvent({
-				type: "auto_retry_end",
-				success: false,
-				attempt,
-				finalError: "Retry cancelled",
-			});
-			this.#resolveRetry();
-			return false;
+			if (this.#retryNowRequested) {
+				// Retry-now: skip the remaining backoff and fall through to
+				// re-attempt immediately (keeps the retry session alive).
+				this.#retryNowRequested = false;
+			} else {
+				// Aborted during sleep (cancel) - emit end event so UI can clean up
+				const attempt = this.#retryAttempt;
+				this.#retryAttempt = 0;
+				await this.#emitSessionEvent({
+					type: "auto_retry_end",
+					success: false,
+					attempt,
+					finalError: "Retry cancelled",
+				});
+				this.#resolveRetry();
+				return false;
+			}
 		}
 		if (this.#retryAbortController === retryAbortController) {
 			this.#retryAbortController = undefined;
 		}
 
 		// Retry via continue() outside the agent_end event callback chain.
-		this.#scheduleAgentContinue({ delayMs: 1, generation });
+		// If the scheduled continue cannot run — it throws (e.g. AgentBusyError from a
+		// concurrent turn, or "Cannot continue ...") or is skipped because a newer
+		// generation took over — the agent_end that normally resolves #retryPromise
+		// never arrives. Finalize the retry in that case so #waitForPostPromptRecovery
+		// (and the in-flight prompt holding it open) cannot wedge the session as
+		// permanently busy, which would turn every later prompt() into a
+		// non-recoverable AgentBusyError loop.
+		this.#scheduleAgentContinue({
+			delayMs: 1,
+			generation,
+			onError: () => this.#failRetryRecovery("Retry continuation failed to start"),
+			onSkip: () => this.#failRetryRecovery("Retry continuation was superseded"),
+		});
 
 		return true;
 	}
@@ -7561,8 +7715,41 @@ export class AgentSession {
 	 * Cancel in-progress retry.
 	 */
 	abortRetry(): void {
+		this.#retryNowRequested = false;
 		this.#retryAbortController?.abort();
-		// Note: _retryAttempt is reset in the catch block of _autoRetry
+		// Note: #retryAttempt is reset in the catch block of #handleRetryableError
+		this.#resolveRetry();
+	}
+
+	/**
+	 * Skip the current retry backoff and re-attempt immediately. Distinct from
+	 * abortRetry(), which cancels the retry and returns to idle. No-op when no
+	 * retry backoff is active.
+	 */
+	retryNow(): void {
+		if (!this.#retryAbortController) return;
+		this.#retryNowRequested = true;
+		this.#retryAbortController.abort();
+	}
+
+	/**
+	 * Finalize a pending auto-retry that can no longer reach a resolving agent_end
+	 * (the scheduled continue threw or was superseded). Without this, #retryPromise
+	 * stays unresolved, #waitForPostPromptRecovery never returns, the owning
+	 * prompt's in-flight count is never released, and the session reports
+	 * `isStreaming === true` forever — turning every later prompt() into a
+	 * non-recoverable AgentBusyError. No-op once the retry has already settled.
+	 */
+	#failRetryRecovery(reason: string): void {
+		if (!this.#retryPromise) return;
+		const attempt = this.#retryAttempt;
+		this.#retryAttempt = 0;
+		void this.#emitSessionEvent({
+			type: "auto_retry_end",
+			success: false,
+			attempt,
+			finalError: reason,
+		});
 		this.#resolveRetry();
 	}
 
@@ -8279,6 +8466,8 @@ export class AgentSession {
 		const previousFallbackSelectedMCPToolNames = previousSessionFile
 			? this.#getSessionDefaultSelectedMCPToolNames(previousSessionFile)
 			: undefined;
+		const previousAgentSteeringQueue = this.agent.snapshotSteering();
+		const previousAgentFollowUpQueue = this.agent.snapshotFollowUp();
 
 		this.#steeringMessages = [];
 		this.#followUpMessages = [];
@@ -8297,6 +8486,12 @@ export class AgentSession {
 			const fallbackSelectedMCPToolNames = this.#getSessionDefaultSelectedMCPToolNames(sessionPath);
 			await this.#restoreMCPSelectionsForSessionContext(sessionContext, { fallbackSelectedMCPToolNames });
 
+			// The target session is loaded and MCP selections are restored: the
+			// switch is committed far enough to discard pre-switch delivery queues.
+			// Clear before session_switch hooks, so messages enqueued by hooks belong
+			// to the new session and remain deliverable.
+			this.agent.clearAllQueues();
+
 			// Emit session_switch event to hooks
 			if (this.#extensionRunner) {
 				await this.#extensionRunner.emit({
@@ -8391,6 +8586,9 @@ export class AgentSession {
 			this.#followUpMessages = previousFollowUpMessages;
 			this.#pendingNextTurnMessages = previousPendingNextTurnMessages;
 			this.#scheduledHiddenNextTurnGeneration = previousScheduledHiddenNextTurnGeneration;
+			this.agent.clearAllQueues();
+			this.agent.restoreSteering(previousAgentSteeringQueue);
+			this.agent.restoreFollowUp(previousAgentFollowUpQueue);
 			if (previousModel) {
 				this.agent.setModel(previousModel);
 			}

package/src/session/session-manager.ts

@@ -27,6 +27,7 @@ import {
 	Snowflake,
 	toError,
 } from "@gajae-code/utils";
+import { writeTextAtomic } from "../gjc-runtime/state-writer";
 import { ArtifactManager } from "./artifacts";
 import {
 	type BlobPutResult,
@@ -56,6 +57,10 @@ import type { SessionStorage, SessionStorageWriter } from "./session-storage";
 import { FileSessionStorage, MemorySessionStorage } from "./session-storage";
 
 export const CURRENT_SESSION_VERSION = 3;
+function isUnderProjectGjc(cwd: string, targetPath: string): boolean {
+	const relative = path.relative(path.join(path.resolve(cwd), ".gjc"), path.resolve(targetPath));
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
 
 export interface SessionHeader {
 	type: "session";
@@ -384,6 +389,7 @@ const migratedSessionRoots = new Set<string>();
  * Best effort: callers decide whether migration failures should surface.
  */
 function migrateSessionDirPath(oldPath: string, newPath: string): void {
+	// Session-dir lifecycle migration: moves/removes whole directories, not file content writes.
 	const existing = fs.statSync(newPath, { throwIfNoEntry: false });
 	if (existing?.isDirectory()) {
 		for (const file of fs.readdirSync(oldPath)) {
@@ -752,7 +758,13 @@ function writeTerminalBreadcrumb(cwd: string, sessionFile: string): void {
 	const breadcrumbFile = path.join(breadcrumbDir, terminalId);
 	const content = `${cwd}\n${sessionFile}\n`;
 	// Best-effort — don't break session creation if breadcrumb fails
-	Bun.write(breadcrumbFile, content).catch(() => {});
+	const write = isUnderProjectGjc(cwd, breadcrumbFile)
+		? writeTextAtomic(breadcrumbFile, content, {
+				cwd,
+				audit: { category: "artifact", verb: "write", owner: "gjc-runtime" },
+			})
+		: Bun.write(breadcrumbFile, content);
+	write.catch(() => {});
 }
 
 /**