@gajae-code/coding-agent 0.12.0 → 0.12.2

package/src/cli/plugin-cli.ts

@@ -7,7 +7,19 @@
 import { APP_NAME, getProjectDir } from "@gajae-code/utils";
 import chalk from "chalk";
 import { resolveOrDefaultProjectRegistryPath } from "../discovery/helpers";
-import { installGjcPluginBundle, isGjcPluginBundleSource, readRegistry } from "../extensibility/gjc-plugins";
+import {
+	applyGjcBundleUpdate,
+	bundleIdentity,
+	type GjcBundleIdentity,
+	type GjcBundleSummary,
+	GjcPluginLoadError,
+	getGjcBundle,
+	installGjcBundle,
+	isGjcPluginBundleSource,
+	isGjcPluginSourceShape,
+	listGjcBundles,
+	previewGjcBundleUpdate,
+} from "../extensibility/gjc-plugins";
 import { PluginManager, parseSettingValue, validateSetting } from "../extensibility/plugins";
 import {
 	getInstalledPluginsRegistryPath,
@@ -312,9 +324,118 @@ async function handleDiscover(args: string[], _flags: PluginCommandArgs["flags"]
 	}
 }
 
+/**
+ * Scope-qualified GJC bundle upgrade: re-resolve the stored source, review the
+ * candidate, then apply it as a compare-and-swap. `--dry-run` stops after the
+ * preview. Requires exactly one of `--user` / `--project` because (scope, name)
+ * is the canonical target.
+ */
+async function handleGjcUpgrade(name: string, flags: PluginCommandArgs["flags"]): Promise<void> {
+	if (flags.user === flags.project) {
+		console.error(chalk.red(`GJC bundle upgrade requires exactly one of --user or --project for "${name}".`));
+		process.exit(1);
+	}
+	const scope: "user" | "project" = flags.user ? "user" : "project";
+	const ctx = { cwd: getProjectDir() };
+	const identity = bundleIdentity(scope, name);
+
+	const emitError = (error: { code: string; message: string; recovery?: string }): never => {
+		if (flags.json) console.log(JSON.stringify({ error }, null, 2));
+		else {
+			console.error(chalk.red(`${theme.status.error} ${error.message}`));
+			if (error.recovery) console.error(chalk.dim(`  Try: ${error.recovery}`));
+		}
+		process.exit(3);
+	};
+
+	// Source re-resolution can throw with a cause carrying the raw locator, so
+	// the whole flow reports a stable code instead of the underlying error.
+	try {
+		await runGjcUpgrade(ctx, identity, name, scope, flags, emitError);
+	} catch (err) {
+		const reason = err instanceof GjcPluginLoadError ? err.code : "upgrade_failed";
+		console.error(chalk.red(`${theme.status.error} Failed to upgrade GJC bundle ${name} (${reason})`));
+		process.exit(1);
+	}
+}
+
+async function runGjcUpgrade(
+	ctx: { cwd: string },
+	identity: GjcBundleIdentity,
+	name: string,
+	scope: "user" | "project",
+	flags: PluginCommandArgs["flags"],
+	emitError: (error: { code: string; message: string; recovery?: string }) => never,
+): Promise<void> {
+	const preview = await previewGjcBundleUpdate(ctx, identity);
+	if (!preview.ok) emitError(preview.error);
+	else if (flags.dryRun || !preview.value.changed) {
+		const { changed, candidateVersion, addedSurfaceIds, removedSurfaceIds } = preview.value;
+		if (flags.json) {
+			console.log(
+				JSON.stringify(
+					{
+						status: changed ? "update-available" : "up-to-date",
+						identity,
+						currentVersion: preview.value.current.version,
+						candidateVersion,
+						addedSurfaceIds,
+						removedSurfaceIds,
+					},
+					null,
+					2,
+				),
+			);
+		} else if (!changed) {
+			console.log(chalk.dim(`GJC bundle ${name} (${scope}) is up to date at ${preview.value.current.version}`));
+		} else {
+			console.log(
+				chalk.cyan(`[dry-run] ${name} (${scope}): ${preview.value.current.version} -> ${candidateVersion}`),
+			);
+			if (addedSurfaceIds.length > 0) console.log(chalk.dim(`  + ${addedSurfaceIds.join(", ")}`));
+			if (removedSurfaceIds.length > 0) console.log(chalk.dim(`  - ${removedSurfaceIds.join(", ")}`));
+		}
+	} else {
+		const applied = await applyGjcBundleUpdate(ctx, preview.value.token);
+		if (!applied.ok) emitError(applied.error);
+		else if (flags.json) {
+			console.log(
+				JSON.stringify(
+					{
+						status: applied.value.status,
+						bundle: applied.value.summary,
+						remnantCount: applied.value.remnantCount,
+					},
+					null,
+					2,
+				),
+			);
+		} else {
+			console.log(
+				chalk.green(
+					`${theme.status.success} ${applied.value.status} GJC bundle ${name}@${applied.value.summary.version} (${scope})`,
+				),
+			);
+			if (applied.value.remnantCount > 0) {
+				console.error(chalk.yellow(`  ${applied.value.remnantCount} leftover directory could not be removed`));
+			}
+		}
+	}
+}
+
 async function handleUpgrade(args: string[], flags: PluginCommandArgs["flags"]): Promise<void> {
-	const manager = await makeMarketplaceManager();
 	const pluginId = args[0];
+	// Scope-qualified GJC bundles upgrade through the lifecycle service, never
+	// through the marketplace manager.
+	if (pluginId && (flags.user || flags.project)) {
+		const scope: "user" | "project" = flags.user ? "user" : "project";
+		const existing = await getGjcBundle({ cwd: getProjectDir() }, bundleIdentity(scope, pluginId));
+		if (existing.ok) {
+			await handleGjcUpgrade(pluginId, flags);
+			return;
+		}
+	}
+	const manager = await makeMarketplaceManager();
 	try {
 		if (pluginId) {
 			if (flags.scope) {
@@ -349,6 +470,15 @@ async function handleUpgrade(args: string[], flags: PluginCommandArgs["flags"]):
 	}
 }
 
+/**
+ * Stable, non-identifying reason for an install failure. The raw spec and the
+ * underlying cause can both carry credentials, a query string, or an absolute
+ * home path, so neither is ever printed.
+ */
+function describeInstallFailure(error: unknown): string {
+	return error instanceof GjcPluginLoadError ? error.code : "install_failed";
+}
+
 async function handleInstall(
 	manager: PluginManager,
 	packages: string[],
@@ -374,27 +504,52 @@ async function handleInstall(
 	const knownMarketplaces = new Set((await mktMgr.listMarketplaces()).map(m => m.name));
 
 	for (const spec of packages) {
-		// GJC plugin bundle classifier: a source containing gajae-plugin.json (or a
-		// git/tarball source) routes to the bundle installer BEFORE marketplace/npm.
-		if (await isGjcPluginBundleSource(spec)) {
+		// A GJC bundle is identified by the SHAPE of its source: a filesystem path,
+		// a git locator, or a tarball. npm and marketplace specs are never any of
+		// those, so shape alone separates the two worlds without resolving.
+		//
+		// Shape is checked BEFORE `isGjcPluginBundleSource`, which resolves the
+		// source: a deleted or unreachable GJC source fails that probe and would
+		// otherwise fall through to npm, losing the create-only refusal the
+		// lifecycle owes for an already-installed target.
+		if (isGjcPluginSourceShape(spec) || (await isGjcPluginBundleSource(spec))) {
 			if (flags.user === flags.project) {
 				console.error(
-					chalk.red(`GJC plugin bundle install requires exactly one of --user or --project for "${spec}".`),
+					// The spec can carry credentials or an absolute home path, so name
+					// the missing flag instead of echoing it back.
+					chalk.red("GJC plugin bundle install requires exactly one of --user or --project."),
 				);
 				process.exit(1);
 			}
 			const scope: "user" | "project" = flags.user ? "user" : "project";
 			try {
-				const res = await installGjcPluginBundle(spec, { scope, cwd: process.cwd(), force: flags.force });
+				const res = await installGjcBundle({ cwd: getProjectDir() }, scope, spec);
+				if (!res.ok) {
+					const doc = {
+						error: { code: res.error.code, message: res.error.message, recovery: res.error.recovery },
+					};
+					if (flags.json) console.log(JSON.stringify(doc, null, 2));
+					else {
+						console.error(chalk.red(`${theme.status.error} ${res.error.message}`));
+						if (res.error.recovery) console.error(chalk.dim(`  Try: ${res.error.recovery}`));
+					}
+					process.exit(3);
+				}
+				const { summary } = res.value;
 				if (flags.json) {
-					console.log(JSON.stringify({ name: res.entry.name, status: res.status, scope }, null, 2));
+					console.log(JSON.stringify({ status: res.value.status, bundle: summary }, null, 2));
 				} else {
 					console.log(
-						chalk.green(`${theme.status.success} ${res.status} GJC plugin ${res.entry.name} (${scope})`),
+						chalk.green(
+							`${theme.status.success} installed GJC plugin ${summary.identity.name}@${summary.version} (${scope})`,
+						),
 					);
 				}
 			} catch (err) {
-				console.error(chalk.red(`${theme.status.error} Failed to install GJC plugin ${spec}: ${err}`));
+				// Never echo the raw spec or the underlying cause: either can carry
+				// credentials, a query string, or an absolute home path.
+				const reason = err instanceof GjcPluginLoadError ? err.code : "install_failed";
+				console.error(chalk.red(`${theme.status.error} Failed to install GJC bundle (${reason})`));
 				process.exit(1);
 			}
 			continue;
@@ -414,7 +569,9 @@ async function handleInstall(
 					),
 				);
 			} catch (err) {
-				console.error(chalk.red(`${theme.status.error} Failed to install ${spec}: ${err}`));
+				// The spec can carry credentials, a query string, or an absolute home
+				// path, so report the failure without echoing it or the raw cause.
+				console.error(chalk.red(`${theme.status.error} Failed to install plugin (${describeInstallFailure(err)})`));
 				process.exit(1);
 			}
 			continue;
@@ -449,7 +606,9 @@ async function handleInstall(
 				}
 			}
 		} catch (err) {
-			console.error(chalk.red(`${theme.status.error} Failed to install ${spec}: ${err}`));
+			// The spec can carry credentials, a query string, or an absolute home
+			// path, so report the failure without echoing it or the raw cause.
+			console.error(chalk.red(`${theme.status.error} Failed to install plugin (${describeInstallFailure(err)})`));
 			process.exit(1);
 		}
 	}
@@ -503,8 +662,7 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 	const mktMgr = await makeMarketplaceManager();
 	const mktPlugins = await mktMgr.listInstalledPlugins();
 	const cwd = getProjectDir();
-	const [gjcUser, gjcProject] = await Promise.all([readRegistry("user", cwd), readRegistry("project", cwd)]);
-	const gjcBundles = [...gjcUser.plugins, ...gjcProject.plugins];
+	const gjcBundles: GjcBundleSummary[] = await listGjcBundles({ cwd });
 
 	if (flags.json) {
 		console.log(JSON.stringify({ npm: npmPlugins, marketplace: mktPlugins, gjc: gjcBundles }, null, 2));
@@ -559,9 +717,9 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 		console.log(chalk.bold("GJC Plugin Bundles:\n"));
 		for (const plugin of gjcBundles) {
 			const status = plugin.enabled ? chalk.green(theme.status.enabled) : chalk.dim(theme.status.disabled);
-			const scopeLabel = chalk.dim(` (${plugin.scope})`);
-			const disabledCount = plugin.disabledSurfaceIds.length;
-			const quarantineCount = plugin.quarantine?.length ?? 0;
+			const scopeLabel = chalk.dim(` (${plugin.identity.scope})`);
+			const disabledCount = plugin.surfaces.filter(s => !s.enabled).length;
+			const quarantineCount = plugin.surfaces.filter(s => s.quarantined).length;
 			const detail = [
 				disabledCount > 0 ? `${disabledCount} disabled` : null,
 				quarantineCount > 0 ? `${quarantineCount} quarantined` : null,
@@ -569,7 +727,7 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 				.filter((v): v is string => Boolean(v))
 				.join(", ");
 			console.log(
-				`${status} ${plugin.name}@${plugin.version}${scopeLabel}${detail ? chalk.dim(` — ${detail}`) : ""}`,
+				`${status} ${plugin.identity.name}@${plugin.version}${scopeLabel}${detail ? chalk.dim(` — ${detail}`) : ""}`,
 			);
 		}
 	}

package/src/commands/team.ts

@@ -13,6 +13,7 @@ import {
 	readGjcTeamSnapshot,
 	shutdownGjcTeam,
 	startGjcTeam,
+	UnknownGjcTeamApiOperationError,
 } from "../gjc-runtime/team-runtime";
 import { syncSkillActiveState } from "../skill-state/active-state";
 
@@ -183,7 +184,24 @@ export default class Team extends Command {
 				return;
 			}
 			const input = parseInputFlag(rest);
-			const result = await executeGjcTeamApiOperation(operation, input);
+			let result: unknown;
+			try {
+				result = await executeGjcTeamApiOperation(operation, input);
+			} catch (error) {
+				if (!(error instanceof UnknownGjcTeamApiOperationError)) throw error;
+				process.exitCode = 1;
+				if (json) {
+					writeReceipt({
+						ok: false,
+						error: error.code,
+						operation: error.operation,
+						suggestions: error.suggestions,
+					});
+				} else {
+					process.stderr.write(`${error.message}\n`);
+				}
+				return;
+			}
 			const teamName = String(input.team_name ?? input.teamName ?? "").trim();
 			if (teamName) {
 				try {

package/src/config/file-lock.ts

@@ -1,7 +1,7 @@
 import type { Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { isEnoent } from "@gajae-code/utils/fs-error";
+import { hasFsCode, isEnoent } from "@gajae-code/utils/fs-error";
 
 export interface FileLockOptions {
 	staleMs?: number;
@@ -185,7 +185,16 @@ async function staleLockSnapshot(
 	staleMs: number,
 	startTimeCache?: Map<string, string | null>,
 ): Promise<LockStaleSnapshot> {
-	const info = await readLockInfo(lockPath);
+	let info: LockInfo | null;
+	try {
+		info = await readLockInfo(lockPath);
+	} catch (error) {
+		// Windows can transiently deny reads of a just-created lock metadata file
+		// while another contender is publishing it. Treat that as active
+		// contention and retry rather than failing the caller or reaping by path.
+		if (hasFsCode(error, "EPERM")) return { stale: false };
+		throw error;
+	}
 	if (!info) {
 		try {
 			const stats = await fs.stat(lockPath);

package/src/config/settings-schema.ts

@@ -275,6 +275,13 @@ export const SETTINGS_SCHEMA = {
 		values: ["copy-retain", "disabled"] as const,
 		default: "copy-retain",
 	},
+	// SDK-owned prompt deadline. Hidden from the UI; ACP has no separate timeout.
+	"sdk.promptDeadlineMs": {
+		type: "number",
+		default: 1_800_000,
+		description: "SDK-owned prompt deadline; ACP has no separate timeout.",
+		validate: (value: number) => Number.isSafeInteger(value) && value >= 60_000 && value <= 86_400_000,
+	},
 
 	// Notifications (shared daemon with Telegram/Discord/Slack presentation adapters)
 	"notifications.enabled": { type: "boolean", default: false },
@@ -287,6 +294,17 @@ export const SETTINGS_SCHEMA = {
 	"notifications.telegram.activation": { type: "record", default: {} as Record<string, unknown> },
 	"notifications.telegram.btw.enabled": { type: "boolean", default: true },
 	"notifications.telegram.streaming.enabled": { type: "boolean", default: true },
+	"notifications.telegram.sound": {
+		type: "enum",
+		values: ["all", "important", "none"] as const,
+		default: "all",
+		ui: {
+			tab: "notifications",
+			label: "Telegram Notification Sounds",
+			description: "Choose which Telegram notifications play a sound.",
+			editing: "notification-atomic",
+		},
+	},
 	"notifications.telegram.rich.enabled": {
 		type: "boolean",
 		default: true,
@@ -489,6 +507,22 @@ export const SETTINGS_SCHEMA = {
 			options: "runtime",
 		},
 	},
+	"session.resumeModelBehavior": {
+		type: "enum",
+		values: ["keepSessionModel", "useCurrentDefault", "ask"] as const,
+		default: "keepSessionModel",
+		ui: {
+			tab: "model",
+			label: "Resume Model Behavior",
+			description:
+				"When resuming a session: keep the model that session last used, switch to the currently configured default model, or ask (TUI only; falls back to keeping the session's model in headless/CLI resume).",
+			options: [
+				{ value: "keepSessionModel", label: "Keep session's saved model" },
+				{ value: "useCurrentDefault", label: "Use current default model" },
+				{ value: "ask", label: "Ask on resume (TUI only)" },
+			],
+		},
+	},
 
 	modelTags: { type: "record", default: EMPTY_MODEL_TAGS_RECORD },
 
@@ -501,6 +535,11 @@ export const SETTINGS_SCHEMA = {
 		default: 0.05,
 		validate: (value: number) => Number.isFinite(value) && value > 0 && value <= 1,
 	},
+	"gjc.ralplan.autoHandoff": {
+		type: "enum",
+		values: ["off", "ultragoal", "team"],
+		default: "off",
+	},
 	"gjc.ralplan.maxIterations": {
 		type: "number",
 		default: 5,
@@ -834,8 +873,8 @@ export const SETTINGS_SCHEMA = {
 		default: true,
 		ui: {
 			tab: "appearance",
-			label: "Status Line Action Hints",
-			description: "Show contextual keyboard shortcuts in the status line",
+			label: "Composer Shortcut Hints",
+			description: "Show contextual keyboard shortcuts in the composer placeholder",
 		},
 	},
 
@@ -1224,6 +1263,16 @@ export const SETTINGS_SCHEMA = {
 				"Maximum provider stream replay retries for replay-safe transient stream failures. Counts retries, not the first attempt. Set to 0 to disable provider stream retries.",
 		},
 	},
+	"retry.streamFirstEventTimeoutMs": {
+		type: "number",
+		default: 100_000,
+		validate: (value: number) => Number.isFinite(value) && value >= 0,
+		ui: {
+			tab: "model",
+			label: "First Event Timeout",
+			description: "Maximum wait for the first provider stream event, in ms. Set to 0 to disable the watchdog.",
+		},
+	},
 	"retry.fallbackChains": { type: "record", default: {} as Record<string, string[]> },
 	"retry.fallbackRevertPolicy": {
 		type: "enum",
@@ -3810,6 +3859,7 @@ export interface RetrySettings {
 	maxDelayMs: number;
 	requestMaxRetries: number;
 	streamMaxRetries: number;
+	streamFirstEventTimeoutMs: number;
 }
 
 export interface MemoriesSettings {
@@ -3929,6 +3979,7 @@ export interface NotificationsSettings {
 	telegram: {
 		botToken: string | undefined;
 		chatId: string | undefined;
+		sound: "all" | "important" | "none";
 		btw: {
 			enabled: boolean;
 		};

package/src/coordinator-mcp/question-gate-codec.ts

@@ -147,7 +147,7 @@ function askSchema(labels: string[], multi: boolean, allowEmpty: boolean): JsonS
 }
 export function decodeAskGateV1(gate: WorkflowGate): PrivateAskGateCodecV1 | null {
 	if (
-		gate.stage !== "deep-interview" ||
+		(gate.stage !== "deep-interview" && gate.stage !== "ralplan" && gate.stage !== "ultragoal") ||
 		gate.kind !== "question" ||
 		!isRecord(gate.context) ||
 		!boundedText(gate.context.prompt, MAX_TEXT) ||

package/src/coordinator-mcp/server.ts

@@ -859,7 +859,7 @@ interface RuntimePromptAcknowledgement {
 	turn_id: string;
 }
 
-function acknowledgementPayload(result: unknown): Record<string, unknown> | null {
+function sdkResultPayload(result: unknown): Record<string, unknown> | null {
 	const response = asRecord(result);
 	if (!response) return null;
 	const envelope = ["ok", "result", "error"].some(key => Object.hasOwn(response, key));
@@ -887,7 +887,7 @@ function runtimeAcknowledgementIdentity(
 }
 
 function normalizeRuntimePromptAcknowledgement(result: unknown): RuntimePromptAcknowledgement {
-	const acknowledgement = acknowledgementPayload(result);
+	const acknowledgement = sdkResultPayload(result);
 	if (acknowledgement?.accepted !== true)
 		throw new SdkClientError("unavailable", "SDK did not acknowledge prompt delivery.");
 	return {
@@ -2458,15 +2458,8 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 				items.push(...pageItems);
 				if (complete) {
 					const valid = items.every(item => {
-						if (!item || typeof item !== "object" || Buffer.byteLength(JSON.stringify(item)) > 16 * 1024)
-							return false;
-						const gate = item as WorkflowGateQueryRecord & WorkflowGate;
-						return (
-							gate.tag === "pending" &&
-							typeof gate.gate_id === "string" &&
-							gate.gate_id.length > 0 &&
-							!!decodeAskGateV1(gate)
-						);
+						const encoded = JSON.stringify(item);
+						return typeof encoded === "string" && Buffer.byteLength(encoded) <= 16 * 1024;
 					});
 					return valid
 						? { items, revision, complete: true, reason: null }
@@ -4492,7 +4485,7 @@ export function createCoordinatorMcpServer(options: CoordinatorMcpServerOptions
 								{ id: gateId, response: translated, expectedSessionId: sessionId },
 								(claimed as { requestId: string }).requestId,
 							);
-							const resolution = asRecord(result);
+							const resolution = sdkResultPayload(result);
 							const status = resolution?.status;
 							if (status === "rejected") {
 								await withAdmittedSessionTransaction(questionPaths, sessionId, async transaction => {

package/src/debug/index.ts

@@ -11,6 +11,7 @@ import { getSessionsDir } from "@gajae-code/utils";
 import { DynamicBorder } from "../modes/components/dynamic-border";
 import { getSelectListTheme, getSymbolTheme, theme } from "../modes/theme/theme";
 import type { InteractiveModeContext } from "../modes/types";
+import { suspendInteractiveActivityIndicator } from "../modes/types";
 import { formatBytes } from "../tools/render-utils";
 import { openPath } from "../utils/open";
 import { DebugLogViewerComponent } from "./log-viewer";
@@ -77,10 +78,12 @@ export class DebugSelectorComponent extends Container {
 	}
 
 	handleInput(keyData: string): void {
+		if (this.ctx.isStopped?.()) return;
 		this.#selectList.handleInput(keyData);
 	}
 
 	async #handleSelection(value: string): Promise<void> {
+		if (this.ctx.isStopped?.()) return;
 		switch (value) {
 			case "open-artifacts":
 				await this.#handleOpenArtifacts();
@@ -115,12 +118,23 @@ export class DebugSelectorComponent extends Container {
 		}
 	}
 
+	#finishStatusLoader(loader: Loader, releaseActivityIndicator: () => void): void {
+		loader.stop();
+		if (!this.ctx.isStopped?.()) this.ctx.statusContainer.clear();
+		releaseActivityIndicator();
+	}
+
 	async #handlePerformanceReport(): Promise<void> {
 		// Start profiling
 		let session: ProfilerSession;
 		try {
 			session = await startCpuProfile();
+			if (this.ctx.isStopped?.()) {
+				await session.stop().catch(() => {});
+				return;
+			}
 		} catch (err) {
+			if (this.ctx.isStopped?.()) return;
 			this.ctx.showError(`Failed to start profiler: ${err instanceof Error ? err.message : String(err)}`);
 			return;
 		}
@@ -151,9 +165,17 @@ export class DebugSelectorComponent extends Container {
 			resolve();
 		};
 
-		await promise;
+		const stopped = Promise.withResolvers<void>();
+		const unsubscribeStop = this.ctx.onStop?.(() => stopped.resolve());
+		const stopWon = await Promise.race([promise.then(() => false), stopped.promise.then(() => true)]);
+		unsubscribeStop?.();
+		if (stopWon || this.ctx.isStopped?.()) {
+			await session.stop().catch(() => {});
+			return;
+		}
 
 		// Stop profiling and create report
+		const releaseActivityIndicator = suspendInteractiveActivityIndicator(this.ctx);
 		const loader = new Loader(
 			this.ctx.ui,
 			spinner => theme.fg("accent", spinner),
@@ -174,8 +196,8 @@ export class DebugSelectorComponent extends Container {
 				workProfile,
 			});
 
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 
 			this.ctx.chatContainer.addChild(new Spacer(1));
 			this.ctx.chatContainer.addChild(
@@ -184,8 +206,8 @@ export class DebugSelectorComponent extends Container {
 			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
 		} catch (err) {
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 			this.ctx.showError(`Failed to create report: ${err instanceof Error ? err.message : String(err)}`);
 		}
 
@@ -219,6 +241,7 @@ export class DebugSelectorComponent extends Container {
 	}
 
 	async #handleDumpReport(): Promise<void> {
+		const releaseActivityIndicator = suspendInteractiveActivityIndicator(this.ctx);
 		const loader = new Loader(
 			this.ctx.ui,
 			spinner => theme.fg("accent", spinner),
@@ -235,8 +258,8 @@ export class DebugSelectorComponent extends Container {
 				settings: this.#getResolvedSettings(),
 			});
 
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 
 			this.ctx.chatContainer.addChild(new Spacer(1));
 			this.ctx.chatContainer.addChild(
@@ -245,8 +268,8 @@ export class DebugSelectorComponent extends Container {
 			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
 		} catch (err) {
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 			this.ctx.showError(`Failed to create report: ${err instanceof Error ? err.message : String(err)}`);
 		}
 
@@ -254,6 +277,7 @@ export class DebugSelectorComponent extends Container {
 	}
 
 	async #handleMemoryReport(): Promise<void> {
+		const releaseActivityIndicator = suspendInteractiveActivityIndicator(this.ctx);
 		const loader = new Loader(
 			this.ctx.ui,
 			spinner => theme.fg("accent", spinner),
@@ -274,8 +298,8 @@ export class DebugSelectorComponent extends Container {
 				heapSnapshot,
 			});
 
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 
 			this.ctx.chatContainer.addChild(new Spacer(1));
 			this.ctx.chatContainer.addChild(
@@ -284,8 +308,8 @@ export class DebugSelectorComponent extends Container {
 			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", formatFileHyperlink(result.path)), 1, 0));
 			this.ctx.chatContainer.addChild(new Text(theme.fg("dim", `Files: ${result.files.length}`), 1, 0));
 		} catch (err) {
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 			this.ctx.showError(`Failed to create report: ${err instanceof Error ? err.message : String(err)}`);
 		}
 
@@ -405,6 +429,7 @@ export class DebugSelectorComponent extends Container {
 		}
 
 		// Clear cache
+		const releaseActivityIndicator = suspendInteractiveActivityIndicator(this.ctx);
 		const loader = new Loader(
 			this.ctx.ui,
 			spinner => theme.fg("accent", spinner),
@@ -418,8 +443,8 @@ export class DebugSelectorComponent extends Container {
 		try {
 			const result = await clearArtifactCache(sessionsDir, 30);
 
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 
 			this.ctx.chatContainer.addChild(new Spacer(1));
 			this.ctx.chatContainer.addChild(
@@ -430,8 +455,8 @@ export class DebugSelectorComponent extends Container {
 				),
 			);
 		} catch (err) {
-			loader.stop();
-			this.ctx.statusContainer.clear();
+			this.#finishStatusLoader(loader, releaseActivityIndicator);
+			if (this.ctx.isStopped?.()) return;
 			this.ctx.showError(`Failed to clear cache: ${err instanceof Error ? err.message : String(err)}`);
 		}
 

package/src/defaults/gjc/skills/deep-interview/SKILL.md

@@ -180,6 +180,7 @@ Run this phase only when the active deep-interview state or invocation indicates
    - Direct `.gjc/` file edits are forbidden unless an explicit force override is active; do not use `write`, `edit`, or `ast_edit` against `.gjc/_session-{sessionid}/specs`, `.gjc/_session-{sessionid}/plans`, `.gjc/_session-{sessionid}/state`, or other `.gjc/` paths during normal workflow operation.
    - Preferred: pass the spec markdown **inline** to the native deep-interview write command (`--write … --spec "<markdown>"`) — no scratch file is needed. The CLI is the only sanctioned writer for `.gjc/_session-{sessionid}/specs`.
    - Only if a spec is too large to pass inline, stage it with the `write` tool to a system temp directory (`os.tmpdir()`/`$TMPDIR`, `/tmp`, `/var/tmp`) outside the project tree, then pass that path to `--spec`. The planning phase-boundary block tolerates these neutral temp writes; never stage interview artifacts inside the repo or under `.gjc/`, and do not improvise repo-relative scratch files.
+   - When staging via bash instead of the `write` tool, a heredoc into a neutral temp path (`cat > /tmp/spec.md <<'EOF' … EOF`) is also tolerated; quote the heredoc delimiter (`<<'EOF'`) so the document body stays inert. Never stage into the repo or `.gjc/`, and prefer the `write` tool over bash for large bodies.
 
 4. **Initialize state** via `gjc deep-interview write --input '<json>'`: