@gajae-code/coding-agent 0.6.1 → 0.6.4

package/src/lsp/startup-events.ts

@@ -11,3 +11,27 @@ export type LspStartupEvent =
 			type: "failed";
 			error: string;
 	  };
+const OPTIONAL_STARTUP_FAILURE_SERVERS = new Set(["rust-analyzer"]);
+
+function isOptionalStartupFailure(server: LspStartupServerInfo): boolean {
+	return server.status === "error" && OPTIONAL_STARTUP_FAILURE_SERVERS.has(server.name);
+}
+
+export function getLspStartupWarningMessage(event: LspStartupEvent): string | null {
+	if (event.type === "failed") {
+		return "LSP startup failed. It will retry lazily on write.";
+	}
+
+	const failedServers = event.servers.filter(server => server.status === "error" && !isOptionalStartupFailure(server));
+
+	if (failedServers.length === 1) {
+		return `LSP startup failed for ${failedServers[0].name}. It will retry lazily on write.`;
+	}
+
+	if (failedServers.length > 1) {
+		const failedNames = failedServers.map(server => server.name).join(", ");
+		return `LSP startup failed for ${failedNames}. It will retry lazily on write.`;
+	}
+
+	return null;
+}

package/src/modes/components/welcome.ts

@@ -13,6 +13,8 @@ export interface LspServerInfo {
 	fileTypes: string[];
 }
 
+export type WelcomeLogoMode = "unicode" | "square" | "ascii";
+
 /**
  * GJC-native launch surface with compact command affordances, project
  * signals, and a claw/talon mark without copying another agent shell.
@@ -27,6 +29,7 @@ export class WelcomeComponent implements Component {
 		private providerName: string,
 		private recentSessions: RecentSession[] = [],
 		private lspServers: LspServerInfo[] = [],
+		private readonly logoMode: WelcomeLogoMode = "unicode",
 	) {}
 
 	invalidate(): void {}
@@ -83,7 +86,8 @@ export class WelcomeComponent implements Component {
 		const minRightCol = 20;
 		const modelPill = this.#pill(theme.icon.model || "model", this.modelName, "statusLineModel");
 		const providerPill = this.#pill(theme.icon.package || "provider", this.providerName, "statusLinePath");
-		const logoMinWidth = Math.max(...RED_CLAW_LOGO.map(line => visibleWidth(line)));
+		const logoLines = this.#logoLines();
+		const logoMinWidth = Math.max(...logoLines.map(line => visibleWidth(line)));
 		const leftMinContentWidth = Math.max(
 			minLeftCol,
 			logoMinWidth,
@@ -102,8 +106,7 @@ export class WelcomeComponent implements Component {
 		const leftCol = showRightColumn ? dualLeftCol : boxWidth - 2;
 		const rightCol = showRightColumn ? dualRightCol : 0;
 
-		// Logo: pick a frame from the intro animation if active, else the resting frame.
-		const logoColored = this.#currentLogoFrame();
+		const logoColored = this.#currentLogoFrame(logoLines);
 
 		// Left column - centered content
 		const leftLines = [
@@ -258,10 +261,10 @@ export class WelcomeComponent implements Component {
 	}
 
 	/** Pick the logo frame for the current intro phase, or the resting frame. */
-	#currentLogoFrame(): readonly string[] {
-		if (this.#animStart == null) return REST_FRAME;
+	#currentLogoFrame(logoLines: readonly string[]): readonly string[] {
+		if (this.#animStart == null) return REST_FRAMES[this.logoMode];
 		const elapsed = performance.now() - this.#animStart;
-		if (elapsed >= INTRO_MS) return REST_FRAME;
+		if (elapsed >= INTRO_MS) return REST_FRAMES[this.logoMode];
 		// Ease-out cubic so the spin decelerates into the resting state.
 		const progress = elapsed / INTRO_MS;
 		const eased = 1 - (1 - progress) ** 3;
@@ -273,7 +276,13 @@ export class WelcomeComponent implements Component {
 		// the same ease-out curve so the highlight is gone by the resting frame.
 		const shinePos = (((progress * INTRO_SHINE_TRAVERSALS) % 1) + 1) % 1;
 		const shineStrength = (1 - eased) ** 1.5;
-		return gradientLogo(RED_CLAW_LOGO, phase, { strength: shineStrength, pos: shinePos });
+		return gradientLogo(logoLines, phase, { strength: shineStrength, pos: shinePos });
+	}
+
+	#logoLines(): readonly string[] {
+		if (this.logoMode === "ascii") return ASCII_CLAW_LOGO;
+		if (this.logoMode === "square") return SQUARE_CLAW_LOGO;
+		return RED_CLAW_LOGO;
 	}
 }
 
@@ -287,6 +296,26 @@ const RED_CLAW_LOGO = [
 	"╰────────────────╯        ╰────────╯",
 ];
 
+// biome-ignore format: preserve ASCII art layout
+const SQUARE_CLAW_LOGO = [
+	"┌────────────────┐        ┌────────┐",
+	"└──────┐      ┌──┘     ┌──┘  ┌─────┘",
+	"       └──────┘    ┌───┘  ┌──┘      ",
+	"       ┌──────┐    └───┐  └──┐      ",
+	"┌──────┘      └──┐     └──┐  └─────┐",
+	"└────────────────┘        └────────┘",
+];
+
+// biome-ignore format: preserve ASCII art layout
+const ASCII_CLAW_LOGO = [
+	"+----------------+        +--------+",
+	"+------+      +--+     +--+  +-----+",
+	"       +------+    +---+  +--+      ",
+	"       +------+    +---+  +--+      ",
+	"+------+      +--+     +--+  +-----+",
+	"+----------------+        +--------+",
+];
+
 /** Multi-stop palette for the red-claw diagonal gradient. */
 const GRADIENT_STOPS: ReadonlyArray<readonly [number, number, number]> = [
 	[127, 29, 29], // deep shell red
@@ -385,5 +414,9 @@ const INTRO_SWEEPS = 2.5;
 /** Number of times the shine highlight crosses the diagonal across the intro. */
 const INTRO_SHINE_TRAVERSALS = 3;
 
-/** Resting gradient frame, cached for re-renders outside of the intro. */
-const REST_FRAME = gradientLogo(RED_CLAW_LOGO, 0);
+/** Resting gradient frames, cached for re-renders outside of the intro. */
+const REST_FRAMES: Record<WelcomeLogoMode, readonly string[]> = {
+	unicode: gradientLogo(RED_CLAW_LOGO, 0),
+	square: gradientLogo(SQUARE_CLAW_LOGO, 0),
+	ascii: gradientLogo(ASCII_CLAW_LOGO, 0),
+};

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

@@ -199,6 +199,9 @@ export class InputController {
 		this.ctx.editor.onDequeue = () => this.handleDequeue();
 		this.ctx.editor.setActionKeys("app.message.queue", this.ctx.keybindings.getKeys("app.message.queue"));
 		this.ctx.editor.onQueue = () => void this.handleQueueSubmit();
+		this.ctx.editor.onTabDeclined = () => {
+			if (this.ctx.session.isStreaming) void this.handleQueueSubmit();
+		};
 
 		this.ctx.editor.clearCustomKeyHandlers();
 		// Wire up extension shortcuts
@@ -228,7 +231,11 @@ export class InputController {
 			});
 		}
 		for (const key of this.ctx.keybindings.getKeys("app.message.followUp")) {
-			this.ctx.editor.setCustomKeyHandler(key, () => void this.handleFollowUp());
+			this.ctx.editor.setCustomKeyHandler(key, () => {
+				if (!this.#isFollowUpShortcutActive()) return false;
+				void this.handleFollowUp();
+				return true;
+			});
 		}
 		for (const key of this.ctx.keybindings.getKeys("app.stt.toggle")) {
 			this.ctx.editor.setCustomKeyHandler(key, () => void this.ctx.handleSTTToggle());
@@ -503,6 +510,15 @@ export class InputController {
 		return this.ctx.settings.get("busyPromptMode") === "steer" ? "steer" : "followUp";
 	}
 
+	#isFollowUpShortcutActive(): boolean {
+		return (
+			this.ctx.session.isStreaming ||
+			this.ctx.session.isCompacting ||
+			this.ctx.session.isBashRunning ||
+			this.ctx.session.isEvalRunning
+		);
+	}
+
 	/**
 	 * Dispatch skill slash invocation(s) (`/skill:<name>`) through custom messages
 	 * using the supplied `streamingBehavior`. Returns true if the text was a
@@ -824,8 +840,9 @@ export class InputController {
 				this.ctx.ui.requestRender();
 				return true;
 			}
-			// No image in clipboard - show hint
-			this.ctx.showStatus("No image in clipboard (use terminal paste for text)");
+			this.ctx.showStatus(
+				"No image in clipboard. Use #paste-image, paste a copied image, or attach an image file with @path/to/image.png.",
+			);
 			return false;
 		} catch {
 			this.ctx.showStatus("Failed to read clipboard");
@@ -840,6 +857,7 @@ export class InputController {
 			keybindings: this.ctx.keybindings,
 			copyCurrentLine: () => this.handleCopyCurrentLine(),
 			copyPrompt: () => this.handleCopyPrompt(),
+			pasteImage: () => void this.handleImagePaste(),
 			undo: prefix => this.ctx.editor.undoPastTransientText(prefix),
 			moveCursorToMessageEnd: () => this.ctx.editor.moveToMessageEnd(),
 			moveCursorToMessageStart: () => this.ctx.editor.moveToMessageStart(),

package/src/modes/interactive-mode.ts

@@ -44,7 +44,7 @@ import { BUILTIN_SLASH_COMMANDS, loadSlashCommands } from "../extensibility/slas
 import { consumePendingGoalModeRequest } from "../gjc-runtime/goal-mode-request";
 import { type Goal, type GoalModeState, normalizeGoal } from "../goals/state";
 import { resolveLocalUrlToPath } from "../internal-urls";
-import { LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
+import { getLspStartupWarningMessage, LSP_STARTUP_EVENT_CHANNEL, type LspStartupEvent } from "../lsp/startup-events";
 import {
 	humanizePlanTitle,
 	type PlanApprovalDetails,
@@ -71,6 +71,7 @@ import { normalizeLocalScheme } from "../tools/path-utils";
 import { type ResolveToolDetails, runResolveInvocation } from "../tools/resolve";
 import { formatPhaseDisplayName } from "../tools/todo-write";
 import { ToolError } from "../tools/tool-errors";
+
 import type { EventBus } from "../utils/event-bus";
 import { getEditorCommand, openInEditor } from "../utils/external-editor";
 import { getSessionAccentAnsi, getSessionAccentHex } from "../utils/session-color";
@@ -85,7 +86,11 @@ import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent } from "./components/hook-selector";
 import { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
-import { WelcomeComponent, type LspServerInfo as WelcomeLspServerInfo } from "./components/welcome";
+import {
+	WelcomeComponent,
+	type WelcomeLogoMode,
+	type LspServerInfo as WelcomeLspServerInfo,
+} from "./components/welcome";
 import { BtwController } from "./controllers/btw-controller";
 import { CommandController } from "./controllers/command-controller";
 import { EventController } from "./controllers/event-controller";
@@ -217,6 +222,21 @@ function parseGoalSubcommand(args: string): { sub: GoalSubcommand | undefined; r
 	return { sub: undefined, rest: trimmed };
 }
 
+export type WelcomeBannerSettingMode = "auto" | "unicode" | "square" | "ascii";
+
+export function resolveWelcomeLogoMode(
+	mode: WelcomeBannerSettingMode,
+	env: Record<string, string | undefined> = Bun.env,
+	platform: NodeJS.Platform = process.platform,
+): WelcomeLogoMode {
+	void env;
+	void platform;
+	if (mode === "unicode") return "unicode";
+	if (mode === "square") return "square";
+	if (mode === "ascii") return "ascii";
+	return "unicode";
+}
+
 /** Options for creating an InteractiveMode instance (for future API use) */
 export interface InteractiveModeOptions {
 	/** Providers that were migrated during startup */
@@ -478,6 +498,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		);
 
 		const startupQuiet = settings.get("startup.quiet");
+		const welcomeLogoMode = resolveWelcomeLogoMode(settings.get("startup.welcomeBannerMode"));
 		this.#welcomeComponent = undefined;
 
 		for (const warning of this.session.configWarnings) {
@@ -493,6 +514,7 @@ export class InteractiveMode implements InteractiveModeContext {
 				providerName,
 				recentSessions,
 				this.#getWelcomeLspServers(),
+				welcomeLogoMode,
 			);
 
 			// Setup UI layout
@@ -2061,23 +2083,9 @@ export class InteractiveMode implements InteractiveModeContext {
 	#handleLspStartupEvent(event: LspStartupEvent): void {
 		this.#updateWelcomeLspServers();
 
-		if (event.type === "failed") {
-			this.showWarning(`LSP startup failed: ${event.error}. It will retry lazily on write.`);
-			return;
-		}
-
-		const failedServers = event.servers.filter(server => server.status === "error");
-
-		if (failedServers.length === 1) {
-			const failedServer = failedServers[0];
-			const detail = failedServer.error ? `: ${failedServer.error}` : "";
-			this.showWarning(`LSP startup failed for ${failedServer.name}${detail}. It will retry lazily on write.`);
-			return;
-		}
-
-		if (failedServers.length > 1) {
-			const failedNames = failedServers.map(server => server.name).join(", ");
-			this.showWarning(`LSP startup failed for ${failedNames}. It will retry lazily on write.`);
+		const warningMessage = getLspStartupWarningMessage(event);
+		if (warningMessage) {
+			this.showWarning(warningMessage);
 		}
 	}
 

package/src/modes/prompt-action-autocomplete.ts

@@ -28,6 +28,7 @@ interface PromptActionAutocompleteOptions {
 	keybindings: KeybindingsManager;
 	copyCurrentLine: () => void;
 	copyPrompt: () => void;
+	pasteImage: () => void;
 	undo: (prefix: string) => void;
 	moveCursorToMessageEnd: () => void;
 	moveCursorToMessageStart: () => void;
@@ -190,7 +191,9 @@ export class PromptActionAutocompleteProvider implements AutocompleteProvider {
 			const query = promptActionPrefix.slice(1).toLowerCase();
 			const items = this.#actions
 				.map(action => {
-					const searchable = [action.label, action.description, ...action.keywords].join(" ").toLowerCase();
+					const searchable = [action.id, action.label, action.description, ...action.keywords]
+						.join(" ")
+						.toLowerCase();
 					if (!fuzzyMatch(query, searchable)) return null;
 					return {
 						value: action.label,
@@ -368,6 +371,13 @@ export function createPromptActionAutocompleteProvider(
 			keywords: ["copy", "prompt", "clipboard", "message"],
 			execute: options.copyPrompt,
 		},
+		{
+			id: "paste-image",
+			label: "Paste image from clipboard",
+			description: formatKeyHints(options.keybindings.getKeys("app.clipboard.pasteImage")),
+			keywords: ["paste", "image", "clipboard", "screenshot", "attach", "vision"],
+			execute: options.pasteImage,
+		},
 		{
 			id: "undo",
 			label: "Undo",

package/src/session/agent-session.ts

@@ -44,7 +44,6 @@ import {
 	type EmergencyCompactionSample,
 	emergencyCompactionReason,
 	estimateMessageTokensHeuristic,
-	estimateTokens,
 	generateBranchSummary,
 	generateHandoff,
 	prepareCompaction,
@@ -225,7 +224,7 @@ import {
 	readVisibleSkillActiveState,
 	syncSkillActiveState,
 } from "../skill-state/active-state";
-import { assertDeepInterviewMutationAllowed } from "../skill-state/deep-interview-mutation-guard";
+import { assertWorkflowMutationAllowed } from "../skill-state/deep-interview-mutation-guard";
 import { invalidateHostMetadata } from "../ssh/connection-manager";
 import { resolveThinkingLevelForModel, toReasoningEffort } from "../thinking";
 import {
@@ -1475,7 +1474,7 @@ export class AgentSession {
 			}
 			const sanitized = sanitizeMessage(providerMessages[i]!);
 			if (!sanitized) continue;
-			const messageTokens = estimateTokens(sanitized);
+			const messageTokens = estimateMessageTokensHeuristic(sanitized);
 			if (maxTokens > 0 && approximateTokens + messageTokens > maxTokens) {
 				recordSkip("token-limit");
 				continue;
@@ -3775,7 +3774,7 @@ export class AgentSession {
 					onUpdate: never,
 					ctx: never,
 				) => {
-					await assertDeepInterviewMutationAllowed({
+					await assertWorkflowMutationAllowed({
 						cwd: this.sessionManager.getCwd(),
 						sessionId: this.sessionManager.getSessionId(),
 						tool: target,
@@ -9901,9 +9900,9 @@ export class AgentSession {
 	#estimateContextTokensForCompaction(pendingMessages: readonly AgentMessage[]): {
 		tokens: number;
 	} {
-		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageNativeContextTokens(message));
+		const estimate = this.#estimateContextTokensWith(message => this.#estimateMessageCompactionDeltaTokens(message));
 		return {
-			tokens: estimate.tokens + this.#estimateMessagesNativeContextTokens(pendingMessages),
+			tokens: estimate.tokens + this.#estimateMessagesCompactionDeltaTokens(pendingMessages),
 		};
 	}
 
@@ -9949,10 +9948,10 @@ export class AgentSession {
 		};
 	}
 
-	#estimateMessagesNativeContextTokens(messages: readonly AgentMessage[]): number {
+	#estimateMessagesCompactionDeltaTokens(messages: readonly AgentMessage[]): number {
 		let tokens = 0;
 		for (const message of messages) {
-			tokens += this.#estimateMessageNativeContextTokens(message);
+			tokens += this.#estimateMessageCompactionDeltaTokens(message);
 		}
 		return tokens;
 	}
@@ -9965,11 +9964,17 @@ export class AgentSession {
 		return tokens;
 	}
 
-	#nativeTokenCache = new WeakMap<AgentMessage, { len: number; tokens: number }>();
+	/**
+	 * Conservative inflation applied to the native-free chars/4 estimate of the
+	 * UNSENT context delta. chars/4 undercounts dense code/CJK, so we bias high
+	 * to compact slightly early rather than overflow the model window before the
+	 * next provider response re-anchors the exact count.
+	 */
+	#compactionDeltaInflation = 1.2;
+	#compactionDeltaTokenCache = new WeakMap<AgentMessage, { len: number; tokens: number }>();
 
-	/** Cheap content-size signal to invalidate the native token cache on mutation (growth). */
 	/**
-	 * Cheap content-size signal to invalidate the native token cache on mutation. Recursively
+	 * Cheap content-size signal to invalidate the compaction-delta token cache on mutation. Recursively
 	 * sums string lengths across the whole message (depth-bounded), so it covers every
 	 * provider-visible shape (text/thinking/tool args, toolResult output, tool names, etc.)
 	 * without allocating a serialized copy. A size-preserving in-place edit yields only a
@@ -9992,19 +9997,22 @@ export class AgentSession {
 		return 0;
 	}
 
-	#estimateMessageNativeContextTokens(message: AgentMessage): number {
-		// F10/F22: cache the expensive native token count per message object, invalidated by a
-		// cheap content-size signal, so unchanged (stable-size) messages are not re-tokenized on
-		// every pre-prompt estimate. A rare size-preserving in-place edit yields only a benign
-		// token-estimate drift, never wrong output.
+	#estimateMessageCompactionDeltaTokens(message: AgentMessage): number {
+		// Provider usage anchors the already-sent context (see calculatePromptTokens); this
+		// estimates only the UNSENT delta with the native-free chars/4 heuristic, inflated by
+		// #compactionDeltaInflation so dense input cannot undercount us past the compaction
+		// threshold before the next provider response re-anchors the exact count. Cached per
+		// message object, invalidated by a cheap content-size signal; a rare size-preserving
+		// in-place edit yields only a benign estimate drift, never wrong output.
 		const len = this.#messageTokenSize(message);
-		const cached = this.#nativeTokenCache.get(message);
+		const cached = this.#compactionDeltaTokenCache.get(message);
 		if (cached && cached.len === len) return cached.tokens;
-		let tokens = 0;
+		let heuristic = 0;
 		for (const llmMessage of convertToLlm([message])) {
-			tokens += estimateTokens(llmMessage);
+			heuristic += estimateMessageTokensHeuristic(llmMessage);
 		}
-		this.#nativeTokenCache.set(message, { len, tokens });
+		const tokens = Math.ceil(heuristic * this.#compactionDeltaInflation);
+		this.#compactionDeltaTokenCache.set(message, { len, tokens });
 		return tokens;
 	}
 

package/src/session/session-manager.ts

@@ -1129,6 +1129,23 @@ function formatTimeAgo(date: Date): string {
 	return date.toLocaleDateString();
 }
 
+async function movePathAcrossDevicesSafe(source: string, destination: string): Promise<void> {
+	try {
+		await fs.promises.rename(source, destination);
+		return;
+	} catch (error) {
+		if (!hasFsCode(error, "EXDEV")) throw error;
+	}
+	const stat = await fs.promises.stat(source);
+	if (stat.isDirectory()) {
+		await fs.promises.cp(source, destination, { recursive: true, force: false, errorOnExist: true });
+		await fs.promises.rm(source, { recursive: true, force: false });
+		return;
+	}
+	await fs.promises.copyFile(source, destination, fs.constants.COPYFILE_EXCL);
+	await fs.promises.unlink(source);
+}
+
 const MAX_PERSIST_CHARS = 500_000;
 const TRUNCATION_NOTICE = "\n\n[Session persistence truncated large content]";
 /** Minimum base64 length to externalize to blob store (skip tiny inline images) */
@@ -2498,14 +2515,14 @@ export class SessionManager {
 			try {
 				// Guard: session file may not exist yet (no assistant messages persisted)
 				if (hadSessionFile) {
-					await fs.promises.rename(oldSessionFile, newSessionFile);
+					await movePathAcrossDevicesSafe(oldSessionFile, newSessionFile);
 					movedSessionFile = true;
 				}
 
 				try {
 					const stat = await fs.promises.stat(oldArtifactDir);
 					if (stat.isDirectory()) {
-						await fs.promises.rename(oldArtifactDir, newArtifactDir);
+						await movePathAcrossDevicesSafe(oldArtifactDir, newArtifactDir);
 						movedArtifactDir = true;
 					}
 				} catch (err) {

package/src/setup/hermes/templates/operator-instructions.v1.md

@@ -29,6 +29,14 @@ The Hermes bridge does not choose a model/provider. Generated setup configures `
 
 Provider-specific commands are examples only, never product defaults.
 
+## Visible routed-session fallback
+
+If a Hermes/OpenClaw/Clawhip-style operator needs a human-visible, channel-routed GJC pane instead of a pure Coordinator MCP session, use the visible session pattern in [`docs/gjc-session-clawhip-routing.md`](../../../../../../docs/gjc-session-clawhip-routing.md).
+
+Use that pattern only when the router must watch tmux output, send stale-session alerts, or inject follow-up prompts into the same visible pane. The short version is: prepare a dedicated worktree, register a stable tmux session through the host router, start interactive `gjc`, wait for TUI readiness, inject the task prompt separately, and verify actual tool/work activity before reporting acceptance.
+
+Do not put private channel ids, mention targets, socket names, tokens, or local routing policy into portable setup output. Keep those in the host/operator deployment.
+
 ## Safety
 
 - Mutating tools require bridge startup mutation classes and per-call consent.

package/src/skill-state/active-state.ts

@@ -559,39 +559,44 @@ function dedupeVisibleBySkill(entries: SkillActiveEntry[], sessionId?: string):
 
 /**
  * The planning pipeline advances one stage at a time: `deep-interview →
- * ralplan → ultragoal`. Each stage is activated through its own command path
- * (`gjc deep-interview`, `gjc ralplan`, `gjc ultragoal`), and those activations
- * do not demote the previous stage's row — only the explicit `handoff` verb
- * does. Without this collapse, activating ultragoal while ralplan is still
- * `active:true` would render both stages and keep showing a workflow that has
- * already handed control forward. Keep only the most recently updated pipeline
- * stage so the HUD reflects the single current workflow. `team` is intentionally
- * excluded — it runs alongside ultragoal — and every non-pipeline skill is left
- * untouched.
- *
- * This is a HUD-display policy only. It is applied by the skill HUD renderer and
- * deliberately NOT folded into `readVisibleSkillActiveState`, whose callers (the
- * deep-interview mutation guard and handoff caller inference) must keep seeing
- * every genuinely-active skill rather than the single most-recent pipeline stage.
+ * ralplan → ultragoal`. Activating a downstream stage supersedes upstream
+ * stages so stale rows cannot keep owning the HUD, gate, or primary active
+ * snapshot. `team` is intentionally excluded — it runs alongside ultragoal —
+ * and every non-pipeline skill is left untouched.
  */
 const PLANNING_PIPELINE_SKILLS = new Set<string>(["deep-interview", "ralplan", "ultragoal"]);
+const PLANNING_PIPELINE_RANK = new Map<string, number>([
+	["deep-interview", 0],
+	["ralplan", 1],
+	["ultragoal", 2],
+]);
+
+function planningPipelineRank(skill: string): number | undefined {
+	return PLANNING_PIPELINE_RANK.get(skill);
+}
+
+function comparePipelineEntry(a: SkillActiveEntry, b: SkillActiveEntry): number {
+	const aRank = planningPipelineRank(a.skill);
+	const bRank = planningPipelineRank(b.skill);
+	if (aRank !== undefined || bRank !== undefined) return (bRank ?? -1) - (aRank ?? -1);
+	const aRecency = entryRecency(a);
+	const bRecency = entryRecency(b);
+	if (Number.isFinite(aRecency) || Number.isFinite(bRecency)) return (bRecency || 0) - (aRecency || 0);
+	return 0;
+}
+
+function upstreamPlanningPipelineSkills(skill: string): string[] {
+	const rank = planningPipelineRank(skill);
+	if (rank === undefined) return [];
+	return [...PLANNING_PIPELINE_RANK.entries()]
+		.filter(([, candidateRank]) => candidateRank < rank)
+		.map(([candidate]) => candidate);
+}
 
 export function collapsePlanningPipeline(entries: readonly SkillActiveEntry[]): SkillActiveEntry[] {
 	const pipeline = entries.filter(entry => PLANNING_PIPELINE_SKILLS.has(entry.skill));
 	if (pipeline.length <= 1) return [...entries];
-	let current = pipeline[0];
-	let currentRecency = entryRecency(current);
-	for (const entry of pipeline) {
-		const recency = entryRecency(entry);
-		// Prefer a strictly-newer valid timestamp; a valid timestamp also beats a
-		// missing/unparseable one. Ties (or all-invalid) keep the first stage
-		// deterministically rather than letting an unknown-recency row win.
-		const better = Number.isFinite(recency) && (!Number.isFinite(currentRecency) || recency > currentRecency);
-		if (better) {
-			current = entry;
-			currentRecency = recency;
-		}
-	}
+	const current = pipeline.toSorted(comparePipelineEntry)[0];
 	return entries.filter(entry => !PLANNING_PIPELINE_SKILLS.has(entry.skill) || entry === current);
 }
 
@@ -618,9 +623,11 @@ async function mergeVisibleEntries(
 		merged.set(entryKey(entry), entry);
 	}
 	const canonicalRalplanPhase = await readModeStatePhase(cwd, sessionId, "ralplan");
-	return dedupeVisibleBySkill([...merged.values()], sessionId)
-		.filter(entry => entry.active !== false)
-		.map(entry => withCanonicalRalplanPhase(entry, canonicalRalplanPhase));
+	return collapsePlanningPipeline(
+		dedupeVisibleBySkill([...merged.values()], sessionId)
+			.filter(entry => entry.active !== false)
+			.map(entry => withCanonicalRalplanPhase(entry, canonicalRalplanPhase)),
+	);
 }
 
 export async function readVisibleSkillActiveState(cwd: string, sessionId?: string): Promise<SkillActiveState | null> {
@@ -682,6 +689,20 @@ async function rebuildActiveState(cwd: string, sessionScope?: ActiveSessionScope
 	await rebuildActiveSnapshot(cwd, sessionScope, { cwd, audit: activeStateWriterAudit("rebuild-active-snapshot") });
 }
 
+async function removeSupersededPlanningPipelineEntries(
+	cwd: string,
+	sessionScope: ActiveSessionScope | undefined,
+	entry: SkillActiveEntry,
+): Promise<void> {
+	if (entry.active === false) return;
+	for (const skill of upstreamPlanningPipelineSkills(entry.skill)) {
+		await removeActiveEntry(cwd, sessionScope, skill, {
+			cwd,
+			audit: activeStateWriterAudit("remove-superseded-pipeline-entry"),
+		});
+	}
+}
+
 async function activeSubskillsForExistingEntry(
 	cwd: string,
 	sessionId: string | undefined,
@@ -725,11 +746,13 @@ export async function syncSkillActiveState(options: SyncSkillActiveStateOptions)
 				? { active_subskills: preservedActiveSubskills }
 				: {}),
 	};
+	await removeSupersededPlanningPipelineEntries(options.cwd, undefined, entry);
 	await persistActiveEntry(options.cwd, undefined, entry);
 	await rebuildActiveState(options.cwd);
 
 	if (!options.sessionId) return;
 	const sessionScope = { sessionId: options.sessionId };
+	await removeSupersededPlanningPipelineEntries(options.cwd, sessionScope, entry);
 	await persistActiveEntry(options.cwd, sessionScope, entry);
 	await rebuildActiveState(options.cwd, sessionScope);
 }