@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/interactive/interactive-application.ts

@@ -10,10 +10,12 @@ import type { DispatchContract } from "../domains/dispatch/contract.js";
 import type { ExtensionsContract } from "../domains/extensions/index.js";
 import type { InteropContract } from "../domains/interop/index.js";
 import type { TaskMemoryOperatorStatus } from "../domains/memory/index.js";
+import { openDetachedBatchViews } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/index.js";
 import type { ProvidersContract, ThinkingLevel } from "../domains/providers/index.js";
 import type { ResourcesContract } from "../domains/resources/index.js";
 import type { FleetNodeSnapshot } from "../domains/scheduling/cluster.js";
+import type { SchedulingContract } from "../domains/scheduling/contract.js";
 import type { DecisionLedgerEntry } from "../domains/session/entries.js";
 import type { SessionContract, SessionEntry, TaskBoardSnapshot } from "../domains/session/index.js";
 import type { ShareContract } from "../domains/share/index.js";
@@ -26,8 +28,10 @@ import { APPLICATION_DOUBLE_TAP_MS, type ApplicationController } from "./applica
 import type { ChatLoop, ChatLoopEvent } from "./chat-loop.js";
 import { emitCommandNotice } from "./command-fallbacks.js";
 import { appendNotice } from "./command-output.js";
+import { dispatchCouncilThroughRegistry } from "./council-dispatch.js";
 import { createDispatchSteering } from "./dispatch-steering.js";
 import { createEditorSubmitController } from "./editor-submit.js";
+import { createInteractiveDesktopNotifications } from "./footer/notifications.js";
 import { createInteractiveEventProjection } from "./interactive-event-projection.js";
 import { createInteractiveInputRuntime } from "./interactive-input-runtime.js";
 import { createInteractivePresentation } from "./interactive-presentation.js";
@@ -108,6 +112,8 @@ export interface InteractiveDeps {
 	providers: ProvidersContract;
 	dispatch: DispatchContract;
 	agents?: AgentsContract;
+	/** Session budget state `/fleet run` shows as the ceiling a plan is admitted under. */
+	scheduling?: SchedulingContract;
 	observability: ObservabilityContract;
 	chat: ChatLoop;
 	/** Fired once after the first real TUI render transaction issued all of its terminal writes. */
@@ -482,10 +488,16 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 	 * here for the same reason as the leader flag above.
 	 */
 	let shutdownArmed = false;
+	/**
+	 * Assigned after the presentation because it renders into it. The composer
+	 * rail reads it through the optional chain before then as "no prompt".
+	 */
+	let overlayLifecycle: OverlayLifecycleController;
 	const presentation = createInteractivePresentation({
 		bus: deps.bus,
 		getLeaderArmed: () => leaderArmed,
 		getShutdownArmed: () => shutdownArmed,
+		isAwaitingApproval: () => overlayLifecycle?.getState() === "permission-confirm",
 		resolveVisibleEventSequence: (event) => visibleEventIngress.get(event)?.traceSequence ?? null,
 		resolveStreamIngress: (event) => visibleEventIngress.get(event) ?? null,
 		commitFrame: (reason) => shell.commitCurrentFrame(reason === "teardown" ? 300 : 30_000),
@@ -535,6 +547,16 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 	} = presentation;
 	refreshPresentationFooter = () => footer.refresh();
 	const agentProgress = createAgentProgress(terminal);
+	// Desktop notifications are a protocol write on the terminal owner, issued
+	// outside any render transaction, so the sequence carries frameId null and
+	// never lands inside a frame. A non-TTY process never emits one even when
+	// `CLIO_CODER_INTERACTIVE=1` forced the interactive surface on.
+	const desktopNotifications = createInteractiveDesktopNotifications({
+		write: (data) => terminal.write(data),
+		enabled: () => deps.getSettings?.().terminal.notify ?? false,
+		interactiveTty: () => process.stdout.isTTY === true,
+		getOpenBatches: () => openDetachedBatchViews(deps.dispatch),
+	});
 	const busNoticeSink = {
 		appendReplayBlock: (renderBlock: Parameters<typeof chatPanel.appendReplayBlock>[0]) =>
 			chatRenderer.mutate(() => chatPanel.appendReplayBlock(renderBlock), "bus-notice"),
@@ -564,6 +586,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		setLastTurnSummary: (summary) => presentation.setLastTurnSummary(summary),
 		startTerminalProgress: () => agentProgress.start(),
 		stopTerminalProgress: () => agentProgress.stop(),
+		onTurnEnded: () => desktopNotifications.turnEnded(),
 		refreshLiveWorkspaceGit,
 		refreshFooter: () => footer.refresh(),
 		requestRender: () => tui.requestRender(),
@@ -581,6 +604,10 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 	// The overlay reads the report this process already produced at boot; it
 	// never probes on a keystroke.
 	const interop = deps.interop;
+	// `/council` reaches execution only through the tool registry, so the
+	// approval overlay this application already installs on it is the same one an
+	// operator-typed council parks.
+	const toolRegistry = deps.toolRegistry;
 	const interopSurface = interop ? interopOverlaySurface(interop, (level, text) => notify(level, text)) : null;
 	const slashRuntime = createInteractiveSlashRuntime({
 		io,
@@ -620,8 +647,12 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		readStructuredEntries,
 		expandSubmit: (text) => expandInteractiveSubmitAsync(text, deps.resources),
 		openAskUser: (questions, options) => openAskUserOverlayState(questions, options),
-		openSkillsHub: () => openSkillsHubState(),
+		openSkillsHub: (tab) => openSkillsHubState(tab),
 		openCost: () => openCostOverlayState(),
+		openSideQuestion: (question) => openSideQuestionOverlayState(question),
+		startHandoff: (goal) => startHandoffState(goal),
+		startFleetRun: (name, vars) => startFleetRunState(name, vars),
+		...(toolRegistry ? { runCouncilDispatch: (args) => dispatchCouncilThroughRegistry(toolRegistry, args) } : {}),
 		openContextView: () => openContextViewOverlayState(),
 		openTasks: () => openTasksOverlayState(),
 		openDecisions: () => openDecisionsOverlayState(),
@@ -668,7 +699,6 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 	});
 	editor.onSubmit = editorSubmit.submitEditorText;
 
-	let overlayLifecycle: OverlayLifecycleController;
 	const interactiveTickers = createInteractiveTickers({
 		tui,
 		dispatchBoardStore,
@@ -700,6 +730,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		notify,
 		terminal,
 		dispatchBoard,
+		setFleetRunPhase: (runId, phase) => dispatchBoardStore.setFleetPhase(runId, phase),
 		chatPanel,
 		resetTranscript,
 		io,
@@ -709,11 +740,26 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		keybindings,
 		editor,
 		getSlashContext: () => slashRuntime.context,
+		// One terminal owner, so the external editor a handoff review opens gets
+		// the screen the same way the composer's own `$EDITOR` opener does.
+		suspendTerminal: (run) => {
+			try {
+				tui.stop();
+				return run();
+			} finally {
+				tui.start();
+				tui.requestRender(true);
+			}
+		},
+		onOperatorParked: () => desktopNotifications.approvalParked(),
 	});
 	const {
 		closeOverlay,
 		openAskUserOverlayState,
 		openCostOverlayState,
+		openSideQuestionOverlayState,
+		startHandoffState,
+		startFleetRunState,
 		openContextViewOverlayState,
 		openContextResetOverlayState,
 		openTasksOverlayState,
@@ -805,6 +851,7 @@ export async function createInteractiveApplication(deps: InteractiveDeps): Promi
 		renderContextIsland: interactiveTickers.renderContextIsland,
 		requestRender: () => tui.requestRender(),
 		notify,
+		onDispatchSettled: () => desktopNotifications.dispatchSettled(),
 		// The reducer mutates one state object per assignment, so the panel is
 		// handed that object rather than a copy: a streamed delta reaches the
 		// screen by invalidating a cached render, not by rebuilding the entry.

package/src/interactive/interactive-event-projection.ts

@@ -77,6 +77,11 @@ export interface InteractiveEventProjectionDeps {
 	setLastTurnSummary: (summary: TurnSummary) => void;
 	startTerminalProgress: () => void;
 	stopTerminalProgress: () => void;
+	/**
+	 * One model turn reached its end. Wired to the desktop notification; absent
+	 * on hosts that do not own a terminal to notify through.
+	 */
+	onTurnEnded?: () => void;
 	refreshLiveWorkspaceGit: (force: boolean) => void;
 	refreshFooter: () => void;
 	requestRender: () => void;
@@ -214,7 +219,10 @@ export function createInteractiveEventProjection(deps: InteractiveEventProjectio
 		deps.chat.onEvent((event) => {
 			const showProgress = deps.getSettings?.().terminal.showTerminalProgress ?? false;
 			if (event.type === "agent_start" && showProgress) deps.startTerminalProgress();
-			else if (event.type === "agent_end") deps.stopTerminalProgress();
+			else if (event.type === "agent_end") {
+				deps.stopTerminalProgress();
+				deps.onTurnEnded?.();
+			}
 		}),
 		deps.bus.on(BusChannels.RunAborted, () => {
 			deps.stopTerminalProgress();

package/src/interactive/interactive-input-runtime.ts

@@ -76,13 +76,14 @@ export interface InteractiveInputRuntimeDeps {
 	dispatchBoard: {
 		selectPrevious(): void;
 		selectNext(): void;
+		toggleDetail(): void;
 	};
 	steerSelectedDispatch: () => void;
 	cancelSelectedDispatch: () => void;
 	cancelActiveEditorBash: () => boolean;
 	isStreaming: () => boolean;
 	cancelActiveRun: () => void;
-	editor: { getText(): string; setText(text: string): void };
+	editor: { getText(): string; setText(text: string): void; handleInput?(data: string): void };
 	editorSubmit: {
 		openExternalEditorForInput(): void;
 		queueFollowUpFromEditor(): void;
@@ -211,6 +212,11 @@ export function createInteractiveInputRuntime(deps: InteractiveInputRuntimeDeps)
 					cancelPermission: () => deps.overlay.closeOverlay(),
 					confirmPermission: () => deps.overlay.confirmPermission(),
 					stopTurnFromPermission: () => deps.overlay.stopTurnFromPermission(),
+					composerHasDraft: () => deps.editor.getText().length > 0,
+					editDraft: (data) => {
+						deps.editor.handleInput?.(data);
+						deps.requestRender();
+					},
 					closeOverlay: () => deps.overlay.closeOverlay(),
 					selectPreviousDispatch: () => {
 						deps.dispatchBoard.selectPrevious();
@@ -220,6 +226,10 @@ export function createInteractiveInputRuntime(deps: InteractiveInputRuntimeDeps)
 						deps.dispatchBoard.selectNext();
 						deps.requestRender();
 					},
+					toggleSelectedDispatchDetail: () => {
+						deps.dispatchBoard.toggleDetail();
+						deps.requestRender();
+					},
 					steerSelectedDispatch: deps.steerSelectedDispatch,
 					cancelSelectedDispatch: deps.cancelSelectedDispatch,
 					cancelAskUser: () => deps.overlay.cancelAskUser(),

package/src/interactive/interactive-presentation.ts

@@ -39,6 +39,7 @@ import type { SmoothStreamingMode } from "./stream-pacer.js";
 import { processAutoPacingAllowed, resolveSmoothStreamingMode } from "./stream-pacing-policy.js";
 import { formatTargetLabel } from "./theme/index.js";
 import { createWelcomeDashboard, type WelcomeDashboardComponent } from "./welcome-dashboard.js";
+import { readWorkerReceiptFacts } from "./worker-receipts.js";
 import type { WorkspaceFacts } from "./workspace-facts.js";
 
 export interface PresentationTickerHandle {
@@ -96,6 +97,8 @@ export interface InteractivePresentationDeps {
 	getLeaderArmed?: () => boolean;
 	/** Whether a Ctrl+C armed the double tap and its window is still open. */
 	getShutdownArmed?: () => boolean;
+	/** Whether a permission prompt owns the keyboard, for the composer's CONFIRM rail. */
+	isAwaitingApproval?: () => boolean;
 	getCwd?: () => string;
 	resolveVisibleEventSequence?: (event: ChatLoopEvent) => number | null;
 	resolveStreamIngress?: (
@@ -242,7 +245,13 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 		bus: deps.bus,
 		...(deps.getSettings ? { getSettings: deps.getSettings } : {}),
 	});
-	const dispatchBoardStore = factories.createDispatchBoardStore(deps.bus, () => deps.dispatch.snapshot());
+	// The board settles a finished run on the same sealed receipt the transcript
+	// block reads, so the two surfaces agree on a worker's terminal answer.
+	const dispatchBoardStore = factories.createDispatchBoardStore(
+		deps.bus,
+		() => deps.dispatch.snapshot(),
+		(runId) => readWorkerReceiptFacts(runId),
+	);
 	const contextActivityStore = factories.createContextActivityStore(deps.bus);
 
 	const footerToolCounts = new Map<string, number>();
@@ -408,6 +417,7 @@ export function createInteractivePresentation(deps: InteractivePresentationDeps)
 			);
 		},
 		isStreaming: () => deps.chat.isStreaming(),
+		...(deps.isAwaitingApproval ? { isAwaitingApproval: deps.isAwaitingApproval } : {}),
 		willEnterSteer: (text) => willEnterSteerActiveWork(deps, text),
 		getSubmitKeyLabel: () => formatKeyLabel(keybindings.getKeys("tui.input.submit")[0], "Enter"),
 		getNewlineKeyLabel: () => formatKeyLabel(keybindings.getKeys("tui.input.newLine")[0], "Shift+Enter"),

package/src/interactive/interactive-slash-runtime.ts

@@ -16,9 +16,12 @@ import {
 	type ThinkingLevel,
 	thinkingLevelChoiceLabel,
 } from "../domains/providers/index.js";
-import type { ResourcesContract } from "../domains/resources/index.js";
+import type { LibraryEntryKind, ResourcesContract } from "../domains/resources/index.js";
 import { installSkill } from "../domains/resources/skills/marketplace.js";
+import { foldDecisionBoard } from "../domains/session/decision-board.js";
 import type { SessionContract, SessionEntry } from "../domains/session/index.js";
+import { foldTaskBoard } from "../domains/session/task-board.js";
+import { filterEntriesToActivePath } from "../domains/session/tree/active-path.js";
 import type { ShareContract } from "../domains/share/index.js";
 import type { UserTasksStore } from "../domains/user-tasks/store.js";
 import { stripTerminalSequences } from "../engine/tui.js";
@@ -32,9 +35,11 @@ import { appendNotice, appendOperatorCommand } from "./command-output.js";
 import { runOperatorRecall } from "./context-recall-command.js";
 import { renderSessionHtml } from "./export-html/index.js";
 import { dateLocal } from "./format-time.js";
+import type { OracleDigestSources } from "./oracle.js";
 import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings.js";
 import {
 	type ContextClearCommandOptions,
+	type CouncilDispatchOutcome,
 	dispatchSlashCommand,
 	type InitCommandOptions,
 	parseSlashCommand,
@@ -108,8 +113,21 @@ export interface InteractiveSlashRuntimeDeps {
 	session?: Pick<SessionContract, "tree" | "current" | "appendEntry">;
 	expandSubmit: (text: string) => Promise<InteractiveSlashSubmitExpansion>;
 	openAskUser: AskUserHandler;
-	openSkillsHub: () => void;
+	openSkillsHub: (tab?: LibraryEntryKind) => void;
 	openCost: () => void;
+	/** Run one `/btw` side question in its own overlay. */
+	openSideQuestion: (question: string) => void;
+	/** Run one `/handoff <goal>`: extract, review, and seed a successor session. */
+	startHandoff: (goal: string) => void;
+	/** Run one `/fleet run <name>`: approval preview first, dispatch only on accept. */
+	startFleetRun?: (name: string, vars: Readonly<Record<string, string>>) => void;
+	/**
+	 * Run one `/council <task>`: the prepared dispatch-tool arguments go through
+	 * the ordinary tool-admission path, so supervised autonomy parks the call and
+	 * the approval overlay opens before any member runs. Absent on a host with no
+	 * tool registry, in which case `/council` says so.
+	 */
+	runCouncilDispatch?: (args: Readonly<Record<string, unknown>>) => Promise<CouncilDispatchOutcome>;
 	openContextView: () => void;
 	openTasks: () => void;
 	openDecisions: () => void;
@@ -186,6 +204,29 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 	const resources = deps.resources;
 	const userTasks = deps.userTasks;
 
+	/**
+	 * The record `/oracle` briefs its advisor on. Entries are filtered to the
+	 * active branch first, the same way the task board, compaction, and the
+	 * finish contract read them (issue #94): after a `/tree` switch the raw file
+	 * still holds the abandoned turns, and an unscoped fold would brief the
+	 * advisor on decisions the operator walked away from.
+	 */
+	const oracleBriefingSources = (): Omit<OracleDigestSources, "question"> => {
+		const sessionId = deps.chat.getSessionId();
+		if (sessionId === null) return { decisions: [], tasks: [], compactionSummary: null };
+		const leafTurnId = deps.session?.tree(sessionId).leafId ?? undefined;
+		const entries = filterEntriesToActivePath(deps.readStructuredEntries(sessionId), leafTurnId);
+		let compactionSummary: string | null = null;
+		for (const entry of entries) {
+			if (entry.kind === "compactionSummary") compactionSummary = entry.summary;
+		}
+		return {
+			decisions: foldDecisionBoard(entries),
+			tasks: foldTaskBoard(entries)?.tasks ?? [],
+			compactionSummary,
+		};
+	};
+
 	const appendCommandNotice: SlashCommandContext["notice"] = (level, text) => {
 		appendNotice(level, text, {
 			appendReplayBlock: (renderBlock) => deps.chatPanel.appendReplayBlock(renderBlock),
@@ -342,6 +383,15 @@ export function createInteractiveSlashRuntime(deps: InteractiveSlashRuntimeDeps)
 				: deps.share.importArchive(resolve(archivePath), importOptions);
 		},
 		openCost: deps.openCost,
+		openSideQuestion: deps.openSideQuestion,
+		// `/oracle` is refused, never queued, while a turn streams: the digest it
+		// packs describes the record as it stands.
+		isTurnInFlight: () => deps.chat.isStreaming(),
+		oracleBriefing: oracleBriefingSources,
+		startHandoff: deps.startHandoff,
+		...(deps.startFleetRun ? { startFleetRun: deps.startFleetRun } : {}),
+		...(deps.getSettings ? { getWorkerRosters: () => deps.getSettings?.().workers.rosters ?? {} } : {}),
+		...(deps.runCouncilDispatch ? { runCouncilDispatch: deps.runCouncilDispatch } : {}),
 		openContextView: deps.openContextView,
 		openTasks: deps.openTasks,
 		openDecisions: deps.openDecisions,

package/src/interactive/interactive-subscriptions.ts

@@ -37,6 +37,12 @@ export interface InteractiveSubscriptionsDeps {
 	recordWorkerRun?: (fields: WorkerRunEntryFields) => void;
 	/** Sealed-receipt reader, injected by tests. Defaults to `<state>/receipts/<runId>.json`. */
 	readWorkerReceipt?: WorkerReceiptReader;
+	/**
+	 * A dispatch run reached a terminal state. The desktop notification uses it
+	 * to look for a detached batch that settled with this run; nothing else
+	 * derives state from it.
+	 */
+	onDispatchSettled?: () => void;
 }
 
 export interface InteractiveSubscriptions {
@@ -89,8 +95,14 @@ export function createInteractiveSubscriptions(deps: InteractiveSubscriptionsDep
 			}),
 		),
 		deps.bus.on(BusChannels.RunAborted, folded(workers.aborted)),
-		deps.bus.on(BusChannels.DispatchCompleted, folded(workers.completed)),
-		deps.bus.on(BusChannels.DispatchFailed, folded(workers.failed)),
+		deps.bus.on(BusChannels.DispatchCompleted, (payload) => {
+			folded(workers.completed)(payload);
+			deps.onDispatchSettled?.();
+		}),
+		deps.bus.on(BusChannels.DispatchFailed, (payload) => {
+			folded(workers.failed)(payload);
+			deps.onDispatchSettled?.();
+		}),
 		deps.bus.on(BusChannels.ContextActivity, () => {
 			deps.refreshFooter();
 			deps.renderContextIsland();

package/src/interactive/memory-overlay.ts

@@ -1,5 +1,6 @@
 import {
 	describeTaskMemoryActivity,
+	type MemoryProposalResult,
 	type MemoryRecord,
 	type TaskMemoryActivityEvent,
 	type TaskMemoryEntry,
@@ -182,6 +183,7 @@ function memorySignature(status: TaskMemoryOperatorStatus, records: ReadonlyArra
 
 interface OpenMemoryOverlayOptions {
 	onClose?: () => void;
+	onPromote?: (entry: TaskMemoryEntry, scope: "repo" | "global") => Promise<MemoryProposalResult>;
 }
 
 /** Master-detail memory view: status header, grouped list, scrollable detail pane. */
@@ -189,12 +191,18 @@ export class MemoryOverlayView implements Component {
 	private readonly list: ListOverlayView;
 	private signature: string | null = null;
 	private renderMemo: { width: number; status: string; listLines: string[]; lines: string[] } | null = null;
+	private pendingGlobalEntryId: string | null = null;
+	private promotionMessage: { token: "muted" | "warning" | "success" | "error"; text: string } | null = null;
+	private promotionInFlight = false;
 
 	constructor(
 		private readonly getStatus: () => TaskMemoryOperatorStatus,
 		private readonly getRecords: () => ReadonlyArray<MemoryRecord>,
 		onClose: () => void,
 		onChange: () => void,
+		private readonly promotion?: {
+			onPromote: (entry: TaskMemoryEntry, scope: "repo" | "global") => Promise<MemoryProposalResult>;
+		},
 	) {
 		this.list = new ListOverlayView(
 			{
@@ -203,6 +211,18 @@ export class MemoryOverlayView implements Component {
 				filterable: true,
 				layout: "split",
 				emptyMessage: EMPTY_MESSAGE,
+				...(promotion
+					? {
+							hints: [
+								{ key: "p", verb: "propose repo" },
+								{ key: "g", verb: "propose global" },
+							],
+							actions: {
+								p: (item: ListOverlayItem) => this.promote(item, "repo", onChange),
+								g: (item: ListOverlayItem) => this.promote(item, "global", onChange),
+							},
+						}
+					: {}),
 				onClose,
 			},
 			onChange,
@@ -217,11 +237,21 @@ export class MemoryOverlayView implements Component {
 	render(width: number): string[] {
 		const status = this.sync();
 		const statusLine = formatMemoryStatusLine(status, width);
+		const promotionLine =
+			this.promotionMessage === null
+				? null
+				: fitUnits(clioTheme(), "", [clioTheme().fg(this.promotionMessage.token, this.promotionMessage.text)], width);
+		const statusKey = promotionLine === null ? statusLine : `${statusLine}\n${promotionLine}`;
 		const listLines = this.list.render(width);
 		const memo = this.renderMemo;
-		if (memo && memo.width === width && memo.status === statusLine && memo.listLines === listLines) return memo.lines;
-		const lines = [statusLine, rule(clioTheme(), width), ...listLines];
-		this.renderMemo = { width, status: statusLine, listLines, lines };
+		if (memo && memo.width === width && memo.status === statusKey && memo.listLines === listLines) return memo.lines;
+		const lines = [
+			statusLine,
+			...(promotionLine === null ? [] : [promotionLine]),
+			rule(clioTheme(), width),
+			...listLines,
+		];
+		this.renderMemo = { width, status: statusKey, listLines, lines };
 		return lines;
 	}
 
@@ -247,9 +277,63 @@ export class MemoryOverlayView implements Component {
 		}
 		return status;
 	}
+
+	private promote(item: ListOverlayItem, scope: "repo" | "global", onChange: () => void): void {
+		if (this.promotion === undefined || this.promotionInFlight) return;
+		const entry = this.selectedBankEntry(item);
+		if (entry === null) {
+			this.pendingGlobalEntryId = null;
+			this.promotionMessage = { token: "warning", text: "select a knowledge or procedural task-bank entry" };
+			this.invalidate();
+			onChange();
+			return;
+		}
+		if (scope === "global" && this.pendingGlobalEntryId !== entry.id) {
+			this.pendingGlobalEntryId = entry.id;
+			this.promotionMessage = {
+				token: "warning",
+				text: `global scope broadens applicability for ${entry.id}; press g again to acknowledge`,
+			};
+			this.invalidate();
+			onChange();
+			return;
+		}
+		this.pendingGlobalEntryId = null;
+		this.promotionInFlight = true;
+		this.promotionMessage = { token: "muted", text: `proposing ${entry.id} with ${scope} scope` };
+		this.invalidate();
+		onChange();
+		void this.promotion
+			.onPromote(entry, scope)
+			.then((result) => {
+				this.promotionMessage = {
+					token: "success",
+					text: `${result.created ? "proposed" : "found existing"} ${result.record.id}; review, then run clio-coder memory approve ${result.record.id}`,
+				};
+			})
+			.catch((error: unknown) => {
+				this.promotionMessage = {
+					token: "error",
+					text: `promotion failed: ${error instanceof Error ? error.message : String(error)}`,
+				};
+			})
+			.finally(() => {
+				this.promotionInFlight = false;
+				this.invalidate();
+				onChange();
+			});
+	}
+
+	private selectedBankEntry(item: ListOverlayItem): TaskMemoryEntry | null {
+		if (!item.id.startsWith("bank:")) return null;
+		const entryId = item.id.slice("bank:".length);
+		const entry = bankEntries(this.getStatus().bank).find((candidate) => candidate.id === entryId);
+		if (entry === undefined || entry.kind === "status") return null;
+		return entry;
+	}
 }
 
-/** Mount the read-only durable-lessons and live task-bank view. */
+/** Mount durable lessons and the live task bank with reviewed promotion actions. */
 export function openMemoryOverlay(
 	tui: TUI,
 	getStatus: () => TaskMemoryOperatorStatus,
@@ -261,6 +345,7 @@ export function openMemoryOverlay(
 		getRecords,
 		() => options.onClose?.(),
 		() => tui.requestRender(),
+		options.onPromote ? { onPromote: options.onPromote } : undefined,
 	);
 	const handle = showClioOverlayFrame(tui, view, {
 		anchor: "center",