@oh-my-pi/pi-coding-agent 16.5.0 → 16.5.2

package/src/advisor/advise-tool.ts

@@ -75,6 +75,17 @@ export function isInterruptingSeverity(severity: AdvisorSeverity | undefined): b
 	return severity === "concern" || severity === "blocker";
 }
 
+/**
+ * Append a staleness caveat to an advisor note when newer primary turns arrived
+ * after the reviewed transcript window (i.e. `hasFreshBacklog` is true on the
+ * advisor runtime at delivery time). Pure function — no session coupling — so it
+ * can be unit-tested in isolation and called from `AgentSession#routeAdvice`.
+ */
+export function annotateForStaleness(note: string, hasFreshBacklog: boolean): string {
+	if (!hasFreshBacklog) return note;
+	return `${note}\n\n_(Note: newer primary turns arrived after this reviewed window — verify this still applies.)_`;
+}
+
 /** How an advisor note is routed to the primary. */
 export type AdvisorDeliveryChannel = "aside" | "steer" | "preserve";
 /** Half-open turn-count fence for the post-interrupt cooldown. */
@@ -94,6 +105,9 @@ export function isAdvisorInterruptImmuneTurnActive(opts: {
  * - An interrupting `concern`/`blocker` is normally steered into the agent: into
  *   the live turn while one is streaming, or (when idle) a triggered turn so the
  *   advice is acted on immediately.
+ * - If the primary tail is already a terminal text answer and there is no queued
+ *   work, late interrupting advice is preserved as a visible card instead of
+ *   waking the primary to restate completion.
  * - After a deliberate user interrupt (`autoResumeSuppressed`) the advisor must
  *   not auto-resume the stopped run. While the agent is idle — or still tearing
  *   the interrupted turn down (`aborting`) — the note is preserved as a visible
@@ -103,17 +117,19 @@ export function isAdvisorInterruptImmuneTurnActive(opts: {
  *   run instead strands it (it never reaches the running agent) and the withheld
  *   notes dump as one burst at the next user prompt — the bug this guards.
  * - During the post-interrupt immune-turn window, further `concern`/`blocker`
- *   notes are downgraded to asides; suppression preservation still wins.
+ *   notes are downgraded to asides; preservation still wins.
  */
 export function resolveAdvisorDeliveryChannel(opts: {
 	severity: AdvisorSeverity | undefined;
 	autoResumeSuppressed: boolean;
 	streaming: boolean;
 	aborting: boolean;
+	terminalAnswerNoQueuedWork?: boolean;
 	interruptImmuneTurnActive?: boolean;
 }): AdvisorDeliveryChannel {
 	if (!isInterruptingSeverity(opts.severity)) return "aside";
 	if (opts.autoResumeSuppressed && (opts.aborting || !opts.streaming)) return "preserve";
+	if (opts.terminalAnswerNoQueuedWork && !opts.streaming && !opts.aborting) return "preserve";
 	if (opts.interruptImmuneTurnActive) return "aside";
 	return "steer";
 }

package/src/advisor/runtime.ts

@@ -63,9 +63,126 @@ export interface AdvisorRuntimeHost {
 	notifyFailure?(error: unknown): void;
 }
 
+const ADVISOR_QUARANTINE_PREFIX = "Advisor response quarantined";
+
+/** Signals that an advisor response was discarded before it could become model-visible context. */
+export class AdvisorOutputQuarantinedError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "AdvisorOutputQuarantinedError";
+	}
+}
+
+interface AdvisorOutputHazard {
+	label: string;
+	pattern: RegExp;
+}
+
+const ADVISOR_OUTPUT_ONLY_HAZARDS: readonly AdvisorOutputHazard[] = [
+	{ label: "account-deletion claim", pattern: /\buser\b.{0,80}\b(?:deleted|erased)\b.{0,80}\baccount\b/i },
+	{
+		label: "instruction override",
+		pattern: /\bignore\s+(?:all\s+)?(?:prior|previous|earlier)\s+(?:user\s+)?instructions\b/i,
+	},
+	{
+		label: "destructive shell command",
+		pattern: /\brm\s+(?=(?:-[a-z]+\s*)*-[a-z]*r[a-z]*)(?=(?:-[a-z]+\s*)*-[a-z]*f[a-z]*)(?:-[a-z]+\s*)+/i,
+	},
+	{ label: "denial instruction", pattern: /\bdeny\s+(?:this|it|the\s+request)\s+if\s+(?:asked|questioned)\b/i },
+];
+
+/**
+ * Replaces an advisor assistant turn that requested unavailable tools or generated
+ * output-only destructive directives with a sanitized error before dispatch.
+ *
+ * The agent loop records assistant turns before dispatching tools. Without this
+ * pre-dispatch rewrite, an advisor hallucination can leave unrelated text in the
+ * advisor transcript even though the action itself never executes.
+ */
+export function quarantineAdvisorUnsafeOutput(
+	message: AssistantMessage,
+	availableToolNames: ReadonlySet<string>,
+	sourceText = "",
+): string | undefined {
+	const reasons: string[] = [];
+	const unavailableToolNames = new Set<string>();
+	const generatedParts: string[] = [];
+	for (const block of message.content) {
+		if (block.type === "toolCall" && !availableToolNames.has(block.name)) unavailableToolNames.add(block.name);
+		if (block.type === "toolCall" && block.name === "advise" && typeof block.arguments.note === "string") {
+			generatedParts.push(block.arguments.note);
+		}
+		if (block.type === "text") generatedParts.push(block.text);
+	}
+	if (unavailableToolNames.size > 0) {
+		const names = [...unavailableToolNames].sort();
+		const toolLabel = names.length === 1 ? "tool" : "tools";
+		reasons.push(`requested unavailable ${toolLabel} ${names.join(", ")}`);
+	}
+
+	const generatedText = generatedParts.join("\n");
+	if (generatedText) {
+		const labels: string[] = [];
+		const matchedLabels: string[] = [];
+		for (const hazard of ADVISOR_OUTPUT_ONLY_HAZARDS) {
+			if (!hazard.pattern.test(generatedText)) continue;
+			matchedLabels.push(hazard.label);
+			if (!hazard.pattern.test(sourceText)) labels.push(hazard.label);
+		}
+		// A transcript can quote a destructive command while the advisor turns it
+		// into a new instruction. The output-only override remains sufficient
+		// provenance to quarantine that combination.
+		if (
+			matchedLabels.includes("destructive shell command") &&
+			labels.includes("instruction override") &&
+			!labels.includes("destructive shell command")
+		) {
+			labels.push("destructive shell command");
+		}
+		if (labels.includes("destructive shell command") || labels.length >= 3) {
+			reasons.push(`generated output-only destructive directives: ${labels.join(", ")}`);
+		}
+	}
+
+	if (reasons.length === 0) return undefined;
+
+	const messageText = `${ADVISOR_QUARANTINE_PREFIX}: ${reasons.join("; ")}`;
+	message.content = [{ type: "text", text: messageText }];
+	message.stopReason = "error";
+	message.stopDetails = undefined;
+	message.toolCallAbortMessages = undefined;
+	message.providerPayload = undefined;
+	message.errorMessage = messageText;
+	return messageText;
+}
+
+/**
+ * Builds the provenance text used to decide whether hazardous advisor output was
+ * generated by the advisor or came from model-visible primary/tool context.
+ */
+export function buildAdvisorQuarantineSourceText(currentInput: string, messages: readonly AgentMessage[]): string {
+	const parts: string[] = [];
+	if (currentInput) parts.push(currentInput);
+	for (const message of messages) {
+		if (message.role !== "toolResult") continue;
+		for (const block of message.content) {
+			if (block.type === "text") parts.push(block.text);
+		}
+	}
+	return parts.join("\n");
+}
+/**
+ * Maximum number of late-arrival coalescing rounds in {@link AdvisorRuntime.#collectAndMaintainBatch}.
+ * After this many rounds any items still in `#pending` are left for the next drain iteration
+ * so a pathologically fast primary + slow `maintainContext` cannot stall dispatch indefinitely.
+ */
+const MAX_COALESCE_ROUNDS = 3;
+
 interface PendingDelta {
 	text: string;
 	turns: number;
+	/** Whether the primary was mid-turn (willContinue:true) when this delta was rendered. */
+	wip: boolean;
 }
 
 interface CatchupWaiter {
@@ -107,13 +224,36 @@ export class AdvisorRuntime {
 		return this.#backlog;
 	}
 
-	onTurnEnd(messages?: AgentMessage[]): void {
+	/**
+	 * True when `#pending` is non-empty while the drain loop is busy — i.e., newer
+	 * primary turns arrived after the current batch's transcript window was fixed
+	 * but before the advisor model finished processing it. The delivery path uses
+	 * this to annotate advice that was generated without seeing those newer turns.
+	 * Can be true during `agent.prompt()`, a `maintainContext` await, or a retry
+	 * sleep — any time `#drain` is busy and a concurrent `onTurnEnd` pushed.
+	 */
+	get hasFreshBacklog(): boolean {
+		return this.#pending.length > 0;
+	}
+
+	/**
+	 * Called after each primary turn ends. Renders the incremental delta and
+	 * queues it for the advisor model.
+	 *
+	 * @param messages - Live primary transcript snapshot (defaults to `snapshotMessages()`).
+	 * @param opts.willContinue - When `true` the primary is mid-turn (more tool-call
+	 *   steps will follow). The rendered heading is tagged `[in progress]` so the
+	 *   advisor knows to withhold critique on partial work. The flag is carried on
+	 *   the delta and forwarded to the reprime path so it is never silently dropped.
+	 */
+	onTurnEnd(messages?: AgentMessage[], opts?: { willContinue?: boolean }): void {
 		if (this.disposed) return;
 		const all = messages ?? this.host.snapshotMessages();
 		this.#latestMessages = all;
-		const render = this.#renderDelta(all);
+		const wip = opts?.willContinue ?? false;
+		const render = this.#renderDelta(all, wip);
 		if (render) {
-			this.#pending.push({ text: render, turns: 1 });
+			this.#pending.push({ text: render, turns: 1, wip });
 			this.#backlog++;
 			this.#notifyWaiters();
 			void this.#drain();
@@ -200,7 +340,7 @@ export class AdvisorRuntime {
 		this.#wakeAllWaiters();
 	}
 
-	#renderDelta(messages?: AgentMessage[]): string | null {
+	#renderDelta(messages?: AgentMessage[], wip = false): string | null {
 		const all = messages ?? this.#latestMessages ?? this.host.snapshotMessages();
 		if (all.length < this.#lastCount) {
 			this.#lastCount = all.length;
@@ -209,7 +349,7 @@ export class AdvisorRuntime {
 		}
 		const delta = all
 			.slice(this.#lastCount)
-			.filter(m => !(m.role === "custom" && (m as { customType?: string }).customType === "advisor"))
+			.filter(m => !(m.role === "custom" && m.customType === "advisor"))
 			.map(m => this.#dedupContextMessage(m));
 		this.#lastCount = all.length;
 		if (delta.length === 0) return null;
@@ -223,7 +363,8 @@ export class AdvisorRuntime {
 			expandEditDiffs: true,
 		});
 		if (!md.trim()) return null;
-		return `### Session update\n\n${md}`;
+		const heading = wip ? "### Session update [in progress — more steps follow]" : "### Session update";
+		return `${heading}\n\n${md}`;
 	}
 
 	/**
@@ -236,14 +377,13 @@ export class AdvisorRuntime {
 	 */
 	#dedupContextMessage(msg: AgentMessage): AgentMessage {
 		if (msg.role !== "custom") return msg;
-		const type = (msg as { customType?: string }).customType;
-		if (!type || !PRIMARY_CONTEXT_CUSTOM_TYPES.has(type)) return msg;
-		const content = (msg as { content?: unknown }).content;
-		if (typeof content !== "string") return msg;
-		if (this.#seenContext.get(type) === content) {
-			return { ...(msg as object), content: "(unchanged — still in effect)" } as AgentMessage;
+		// Narrowed to CustomMessage: customType and content are properly typed.
+		if (!PRIMARY_CONTEXT_CUSTOM_TYPES.has(msg.customType)) return msg;
+		if (typeof msg.content !== "string") return msg;
+		if (this.#seenContext.get(msg.customType) === msg.content) {
+			return { ...msg, content: "(unchanged — still in effect)" };
 		}
-		this.#seenContext.set(type, content);
+		this.#seenContext.set(msg.customType, msg.content);
 		return msg;
 	}
 
@@ -284,46 +424,90 @@ export class AdvisorRuntime {
 		}
 	}
 
+	/**
+	 * Collect all currently pending deltas into one batch, running
+	 * `maintainContext` for correct token budgeting. Loops until the pending
+	 * queue is stable (no new deltas arrived during a maintenance check) or a
+	 * reprime is triggered. Every `await` inside the loop has an epoch guard so
+	 * a reset/dispose mid-await cannot leak a stale batch into the post-reset
+	 * conversation.
+	 *
+	 * The coalescing loop is capped at {@link MAX_COALESCE_ROUNDS} iterations so
+	 * a pathologically fast primary combined with a slow `maintainContext` cannot
+	 * stall dispatch indefinitely — any items still in `#pending` after the cap
+	 * are left for the next drain iteration.
+	 *
+	 * Returns `null` when the epoch was invalidated — caller should `continue`.
+	 * Returns `{ batch: null, finalTurns }` when there is nothing to render but
+	 * backlog still needs to be decremented.
+	 */
+	async #collectAndMaintainBatch(
+		epoch: number,
+	): Promise<{ batch: string | null; finalTurns: number; wip: boolean } | null> {
+		const initial = this.#pending.splice(0);
+		let batchText = initial.map(b => b.text).join("\n\n");
+		let turns = initial.reduce((sum, b) => sum + b.turns, 0);
+		// Track WIP state of the most recent delta — forwarded to the reprime
+		// #renderDelta so a willContinue:true turn keeps its [in progress] heading
+		// even when the full transcript is replayed from scratch. Also returned to
+		// #drain so the retry-requeue path preserves it on failed turns.
+		let wip = initial.at(-1)?.wip ?? false;
+
+		for (let round = 0; round < MAX_COALESCE_ROUNDS; round++) {
+			if (this.host.maintainContext) {
+				const incomingTokens = estimateTokens({ role: "user", content: batchText, timestamp: Date.now() });
+				let shouldReprime = false;
+				try {
+					shouldReprime = await this.host.maintainContext(incomingTokens);
+				} catch (err) {
+					logger.debug("advisor context maintenance failed", { err: String(err) });
+				}
+				// Epoch guard — a reset/dispose during the maintainContext await
+				// invalidates this batch.
+				if (this.#epoch !== epoch) return null;
+
+				if (shouldReprime) {
+					// Tally deltas that arrived during this await before #resetAdvisorContext
+					// wipes #pending, so finalTurns stays accurate for backlog accounting.
+					// Also capture the latest WIP state before the queue is cleared.
+					const lateItems = this.#pending.splice(0);
+					turns += lateItems.reduce((sum, b) => sum + b.turns, 0);
+					if (lateItems.length > 0) wip = lateItems.at(-1)!.wip;
+					this.#resetAdvisorContext(false, false);
+					return { batch: this.#renderDelta(this.#latestMessages, wip), finalTurns: turns, wip };
+				}
+			}
+
+			// On the final round stop here — any late arrivals would ship without
+			// a subsequent maintainContext budget check. Leave them in #pending for
+			// the next drain iteration where they will be properly budgeted.
+			if (round === MAX_COALESCE_ROUNDS - 1) break;
+
+			// Coalesce any deltas that arrived while we were awaiting maintenance.
+			// If none arrived the batch is stable and we're done; otherwise merge,
+			// update WIP state, and re-check the maintenance budget.
+			const late = this.#pending.splice(0);
+			if (late.length === 0) break;
+			batchText = [batchText, ...late.map(b => b.text)].join("\n\n");
+			turns += late.reduce((sum, b) => sum + b.turns, 0);
+			wip = late.at(-1)!.wip;
+		}
+
+		return { batch: batchText || null, finalTurns: turns, wip };
+	}
+
 	async #drain(): Promise<void> {
 		if (this.#busy) return;
 		this.#busy = true;
 		try {
 			while (!this.disposed && this.#pending.length) {
-				const popped = this.#pending.splice(0);
 				const epoch = this.#epoch;
-				// Each delta already opens with a `### Session update` heading, so
-				// join with a blank line rather than a `---` rule.
-				const candidateBatch = popped.map(b => b.text).join("\n\n");
-				const turnsCovered = popped.reduce((sum, b) => sum + b.turns, 0);
-				const incomingTokens = estimateTokens({
-					role: "user",
-					content: candidateBatch,
-					timestamp: Date.now(),
-				});
+				const result = await this.#collectAndMaintainBatch(epoch);
 
-				let shouldReprime = false;
-				if (this.host.maintainContext) {
-					try {
-						shouldReprime = await this.host.maintainContext(incomingTokens);
-					} catch (err) {
-						logger.debug("advisor context maintenance failed", { err: String(err) });
-					}
-				}
-				// A reset/dispose during context maintenance invalidates this batch.
-				if (this.#epoch !== epoch) continue;
+				// Epoch was invalidated during batch collection; restart the loop.
+				if (result === null) continue;
 
-				let batch: string | null;
-				let finalTurns: number;
-				if (shouldReprime) {
-					// Promotion could not fit the advisor's context — re-prime.
-					const newTurns = this.#pending.reduce((sum, b) => sum + b.turns, 0);
-					this.#resetAdvisorContext(false, false);
-					batch = this.#renderDelta(this.#latestMessages);
-					finalTurns = turnsCovered + newTurns;
-				} else {
-					batch = candidateBatch;
-					finalTurns = turnsCovered;
-				}
+				const { batch, finalTurns, wip } = result;
 
 				if (this.disposed || batch === null) {
 					this.#backlog = Math.max(0, this.#backlog - finalTurns);
@@ -333,33 +517,34 @@ export class AdvisorRuntime {
 
 				let success = false;
 				// Capture the advisor's message count BEFORE the prompt so a failure can
-				// roll back the user batch + synthetic assistant-error turn `Agent.#runLoop`
-				// appends to internal state. Without this, a retry would replay the
-				// failed batch on top of the stale turns and the dropped-after-3 path
-				// would leak orphan failures into the next successful run's context.
+				// roll back the user batch + synthetic assistant-error turn Agent.#runLoop
+				// appends to internal state. Without this, a retry would replay the failed
+				// batch on top of stale turns and the dropped-after-3 path would leak
+				// orphan failures into the next successful run's context.
 				const messageSnapshot = this.agent.state.messages.length;
 				try {
 					// Reset the host's per-update advisor state (one-advise-per-update
-					// gate) before each model cycle, so the new batch starts with a
-					// fresh budget. Dedupe history persists across cycles.
+					// gate) before each model cycle so the new batch starts fresh.
 					this.host.beginAdvisorUpdate?.();
 					await this.agent.prompt(batch);
-					// `Agent.#runLoop` catches provider/stream failures internally and
-					// resolves `prompt()` cleanly with the assistant turn ending in
-					// `stopReason: "error"` and the message recorded on `state.error`.
-					// Treat that as a failed turn so OpenRouter ZDR-style endpoint
-					// rejections trip the retry/notify path instead of looking like a
-					// successful empty cycle.
+					// Agent.#runLoop catches provider/stream failures internally and
+					// resolves prompt() cleanly with stopReason: "error". Treat that
+					// as a failed turn so endpoint rejections trip the retry path.
 					const promptError = this.agent.state.error;
 					if (promptError) throw new Error(promptError);
+					// A content-less stop is a deliberate silent review — the documented
+					// verifier behavior ("prefer silence when the agent is on track") — and
+					// completes the turn. Sessions can legitimately have nothing to advise
+					// on for any number of consecutive turns, so silence is never warned
+					// about (#5216 did, spamming "Advisor unavailable" at quiet models).
+					const turnError = getAdvisorTurnError(this.agent.state.messages.slice(messageSnapshot));
+					if (turnError) throw turnError;
 					success = true;
 					this.#consecutiveFailures = 0;
 					this.#failureNotified = false;
 				} catch (err) {
-					// reset()/dispose() aborts the in-flight prompt; the rejection is the
-					// reset itself, not a transient advisor failure. Drop the stale batch
-					// (reset already cleared #pending and rewound the cursor) instead of
-					// requeuing it into the post-reset conversation.
+					// reset()/dispose() aborts the in-flight prompt; treat it as a
+					// reset, not a transient failure — drop the stale batch.
 					if (this.#epoch !== epoch) continue;
 					this.#rollbackFailedTurn(messageSnapshot);
 					logger.debug("advisor turn failed", { err: String(err) });
@@ -368,8 +553,15 @@ export class AdvisorRuntime {
 					} catch (hookErr) {
 						logger.debug("advisor onTurnError hook failed", { err: String(hookErr) });
 					}
-					// The hook awaits; a reset during it invalidates this batch like the
-					// prompt await above — drop it instead of requeueing stale content.
+					if (err instanceof AdvisorOutputQuarantinedError) {
+						const rePrime = this.#pending.length > 0 ? this.#latestMessages : undefined;
+						// Wake catchup waiters only when nothing is re-primed; otherwise the
+						// re-primed turn restores the backlog and waiters resolve on its completion.
+						this.#resetAdvisorContext(true, !rePrime);
+						if (rePrime) this.onTurnEnd(rePrime);
+						continue;
+					}
+					// Epoch guard after the async error hook.
 					if (this.#epoch !== epoch) continue;
 					this.#consecutiveFailures++;
 					if (this.#consecutiveFailures >= 3) {
@@ -383,13 +575,13 @@ export class AdvisorRuntime {
 							}
 						}
 						this.#consecutiveFailures = 0;
-						// The dropped batch may carry primary-context we never delivered; drop
-						// the seen-state too so the next turn re-expands it instead of marking
-						// it "unchanged" against content the advisor never received.
+						// Drop the seen-context so the next turn re-expands primary-context
+						// prompts instead of marking them "unchanged" against content the
+						// advisor never received.
 						this.#seenContext.clear();
 						success = true;
 					} else {
-						this.#pending.unshift({ text: batch, turns: finalTurns });
+						this.#pending.unshift({ text: batch, turns: finalTurns, wip });
 						await Bun.sleep(this.retryDelayMs);
 					}
 				}
@@ -405,6 +597,17 @@ export class AdvisorRuntime {
 	}
 }
 
+/**
+ * The only malformed advisor turn shape: the prompt resolved but produced no
+ * assistant response at all. Everything an assistant message carries — advice,
+ * reasoning, or deliberate silence (empty `stop`) — is a completed review.
+ */
+function getAdvisorTurnError(messages: readonly AgentMessage[]): Error | undefined {
+	if (messages.length === 0) return undefined;
+	if (messages.some(message => message.role === "assistant")) return undefined;
+	return new Error("Advisor turn ended without an assistant response");
+}
+
 type TextualContent = string | readonly (TextContent | ImageContent)[];
 
 function obfuscateTextualContent(obfuscator: SecretObfuscator, content: TextualContent): TextualContent {

package/src/autolearn/controller.ts

@@ -76,11 +76,11 @@ export class AutoLearnController {
 			return;
 		}
 		if (event.type === "agent_end") {
-			this.#onAgentEnd();
+			this.#onAgentEnd(event);
 		}
 	}
 
-	#onAgentEnd(): void {
+	#onAgentEnd(event: Extract<AgentSessionEvent, { type: "agent_end" }>): void {
 		// Snapshot and reset every turn: the counter describes only the
 		// just-finished turn, so below-threshold, disabled, and plan-mode stops
 		// must not let tool calls accumulate into a later turn.
@@ -95,6 +95,18 @@ export class AutoLearnController {
 			this.#suppressNext = false;
 			return;
 		}
+		// Never nudge a turn that ended in an abort (ESC, cancel, etc.). The
+		// abort flag on the session is unreliable by the time agent_end is
+		// deferred to subscribers; read stopReason from the event messages.
+		for (let i = event.messages.length - 1; i >= 0; i--) {
+			const message = event.messages[i];
+			if (message && typeof message === "object" && "role" in message && message.role === "assistant") {
+				if ("stopReason" in message && message.stopReason === "aborted") {
+					return;
+				}
+				break;
+			}
+		}
 		// Honor a live opt-out: the subscription outlives the setting, so re-check
 		// the current flag rather than trusting install-time state.
 		if (!this.#settings.get("autolearn.enabled")) return;
@@ -132,7 +144,7 @@ export class AutoLearnController {
 					display: false,
 					attribution: "user",
 				},
-				{ deliverAs: "nextTurn", triggerTurn: true },
+				{ deliverAs: "nextTurn", triggerTurn: true, acceptTerminalEmptyStop: true },
 			)
 			.then(started => {
 				if (!started) this.#suppressNext = false;

package/src/autoresearch/dashboard.ts

@@ -95,9 +95,9 @@ export function createDashboardController(): DashboardController {
 								done(undefined);
 								return;
 							}
-							if (matchesKey(data, "up") || data === "k") {
+							if (matchesKey(data, "up") || matchesKey(data, "k")) {
 								scrollOffset = Math.max(0, scrollOffset - 1);
-							} else if (matchesKey(data, "down") || data === "j") {
+							} else if (matchesKey(data, "down") || matchesKey(data, "j")) {
 								scrollOffset = Math.min(maxScroll, scrollOffset + 1);
 							} else if (matchesKey(data, "pageUp")) {
 								scrollOffset = Math.max(0, scrollOffset - viewportRows);

package/src/cli/args.ts

@@ -13,6 +13,7 @@ import {
 	STRING_SETTERS,
 	STRING_VALUE_FLAGS,
 } from "./flag-tables";
+import { CliUsageError } from "./usage-error";
 
 export type Mode = "text" | "json" | "rpc" | "acp" | "rpc-ui";
 
@@ -310,6 +311,17 @@ export function reportUnrecognizedFlags(
 	return true;
 }
 
+/** Emit a clean CLI usage error without an internal stack trace. */
+export function reportCliUsageError(
+	error: unknown,
+	write: (text: string) => void = text => process.stderr.write(text),
+): boolean {
+	if (!(error instanceof CliUsageError)) return false;
+	write(`${chalk.red(`Error: ${error.message}`)}\n`);
+	write(`Run \`${APP_NAME} --help\` for available flags.\n`);
+	return true;
+}
+
 export function getExtraHelpText(): string {
 	return `${chalk.bold("Environment Variables:")}
   ${chalk.dim("# Core Providers")}

package/src/cli/auth-broker-cli.ts

@@ -660,19 +660,25 @@ interface MigrateSkip {
 
 function credentialIdentity(provider: string, credential: AuthCredential): string {
 	if (credential.type === "api_key") return "(api key)";
-	return credential.email ?? credential.accountId ?? credential.projectId ?? `<${provider} oauth>`;
+	const base = credential.email ?? credential.accountId ?? credential.projectId ?? `<${provider} oauth>`;
+	return credential.orgId ? `${base} (${credential.orgName ?? credential.orgId})` : base;
 }
 
 /**
  * Build the set of "identities already on the broker" so re-runs are idempotent.
- * For OAuth, identity = email|accountId|projectId. For api_key, we collapse
- * to a single marker per provider (broker has no concept of "multiple api keys
- * per provider with different identities"; upsert would coalesce them).
+ * For OAuth, identity = email|accountId|projectId, each org-qualified when the
+ * row carries an organization (one Anthropic email can hold a Team seat AND a
+ * personal Max plan — those must migrate as two rows). A row with NO base
+ * identity but an orgId (login recovered neither email nor account) is marked
+ * by the org alone, so re-running migrate does not re-upload a stale refresh
+ * token over the broker's newer one. For api_key, we collapse to a single
+ * marker per provider (broker has no concept of "multiple api keys per
+ * provider with different identities"; upsert would coalesce them).
  */
 function indexBrokerSnapshot(snapshot: {
 	credentials: Array<{
 		provider: string;
-		credential: { type: string; email?: string; accountId?: string; projectId?: string };
+		credential: { type: string; email?: string; accountId?: string; projectId?: string; orgId?: string };
 	}>;
 }): Map<string, Set<string>> {
 	const out = new Map<string, Set<string>>();
@@ -681,9 +687,18 @@ function indexBrokerSnapshot(snapshot: {
 		if (entry.credential.type === "api_key") {
 			ids.add("@api_key");
 		} else {
-			if (entry.credential.email) ids.add(`email:${entry.credential.email}`);
-			if (entry.credential.accountId) ids.add(`accountId:${entry.credential.accountId}`);
-			if (entry.credential.projectId) ids.add(`projectId:${entry.credential.projectId}`);
+			const orgSuffix = entry.credential.orgId ? `|org:${entry.credential.orgId}` : "";
+			if (entry.credential.email) ids.add(`email:${entry.credential.email}${orgSuffix}`);
+			if (entry.credential.accountId) ids.add(`accountId:${entry.credential.accountId}${orgSuffix}`);
+			if (entry.credential.projectId) ids.add(`projectId:${entry.credential.projectId}${orgSuffix}`);
+			if (
+				!entry.credential.email &&
+				!entry.credential.accountId &&
+				!entry.credential.projectId &&
+				entry.credential.orgId
+			) {
+				ids.add(`org:${entry.credential.orgId}`);
+			}
 		}
 		out.set(entry.provider, ids);
 	}
@@ -694,9 +709,13 @@ function brokerAlreadyHas(existing: Map<string, Set<string>>, provider: string,
 	const ids = existing.get(provider);
 	if (!ids) return false;
 	if (credential.type === "api_key") return ids.has("@api_key");
-	if (credential.email && ids.has(`email:${credential.email}`)) return true;
-	if (credential.accountId && ids.has(`accountId:${credential.accountId}`)) return true;
-	if (credential.projectId && ids.has(`projectId:${credential.projectId}`)) return true;
+	const orgSuffix = credential.orgId ? `|org:${credential.orgId}` : "";
+	if (credential.email && ids.has(`email:${credential.email}${orgSuffix}`)) return true;
+	if (credential.accountId && ids.has(`accountId:${credential.accountId}${orgSuffix}`)) return true;
+	if (credential.projectId && ids.has(`projectId:${credential.projectId}${orgSuffix}`)) return true;
+	if (!credential.email && !credential.accountId && !credential.projectId && credential.orgId) {
+		return ids.has(`org:${credential.orgId}`);
+	}
 	return false;
 }
 

package/src/cli/auth-gateway-cli.ts

@@ -573,8 +573,12 @@ async function runCheck(flags: AuthGatewayCommandArgs["flags"]): Promise<void> {
 							: row.ok === false
 								? chalk.red("FAIL    ")
 								: chalk.yellow("unknown ");
-					const identity =
+					const base =
 						row.email ?? row.accountId ?? (row.type === "api_key" ? "(api key)" : "(no identity on credential)");
+					// Two subscriptions (orgs) can share one email — without the org a
+					// failed row can't say which subscription needs re-login.
+					const org = row.orgName ?? row.orgId;
+					const identity = org && org !== base ? `${base} (${org})` : base;
 					const remote = row.remoteRefresh ? chalk.dim(" [remote-refresh]") : "";
 					const reasonParts: string[] = [];
 					if (row.reason) reasonParts.push(row.reason);