@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/interactive/overlay-lifecycle.ts

@@ -1,3 +1,4 @@
+import type { LibraryEntryKind } from "../domains/resources/index.js";
 import { appendNotice } from "./command-output.js";
 import { createOverlayAskUserLifecycle, type OverlayAskUserLifecycle } from "./overlay-ask-user-lifecycle.js";
 import { createOverlayAuthLifecycle } from "./overlay-auth-lifecycle.js";
@@ -12,7 +13,9 @@ import {
 	createPermissionOverlayBody,
 	PERMISSION_OVERLAY_WIDTH,
 	permissionOverlayHint,
+	permissionOverlayPlacement,
 	permissionOverlayTitle,
+	permissionOverlayTone,
 } from "./permission-overlay.js";
 
 export * from "./overlay-key-routing.js";
@@ -24,6 +27,7 @@ import type { SettingsCenterRowId, SettingsSectionId } from "./overlays/settings
 // application composition root no longer owns the mutable overlay state.
 export type OverlayLifecycleApplicationDeps = Pick<
 	import("./interactive-application.js").InteractiveDeps,
+	| "agents"
 	| "bus"
 	| "chat"
 	| "commitSetting"
@@ -40,12 +44,14 @@ export type OverlayLifecycleApplicationDeps = Pick<
 	| "observability"
 	| "onContextClear"
 	| "onForkSession"
+	| "onNewSession"
 	| "onResumeSession"
 	| "onSelectModel"
 	| "providers"
 	| "readSessionEntries"
 	| "registerAskUserHandler"
 	| "resources"
+	| "scheduling"
 	| "session"
 	| "stateDir"
 	| "supersedeDecision"
@@ -73,17 +79,30 @@ export interface OverlayLifecycleRuntimeDeps {
 	notify: (level: import("./interactive-subscriptions.js").InteractiveNoticeLevel, text: string, key?: string) => void;
 	terminal: Pick<import("../engine/tui.js").ProcessTerminal, "columns">;
 	dispatchBoard: ReturnType<typeof import("./dispatch-board.js").createDispatchBoardView>;
+	/** Record a dispatched fleet step's plan position for the board's phase column. */
+	setFleetRunPhase?: (runId: string, phase: { wave: number; stepId: string }) => void;
 	chatPanel: import("./chat-panel.js").ChatPanel;
 	/** Clears the transcript and every view folded alongside it; the session overlays call it before a replay. */
 	resetTranscript: () => void;
+	/**
+	 * Stop and restart the terminal around a child process that owns the screen.
+	 * `/handoff` uses it for the external editor, the same way the composer's
+	 * own `$EDITOR` opener does.
+	 */
+	suspendTerminal: <T>(run: () => T) => T;
 	io: import("./slash-commands.js").RunIo;
 	readStructuredEntries: (sessionId: string) => import("../domains/session/index.js").SessionEntry[];
 	announceTaskMemorySeedOffer: () => void;
 	/** Rescopes the footer's last-turn line when a session overlay changes the branch. */
 	setLastTurnSummary?: (summary: import("./status/index.js").TurnSummary | null) => void;
 	keybindings: ReturnType<typeof import("./keybinding-manager.js").createKeybindingManager>;
-	editor: Pick<import("./clio-editor.js").ClioEditor, "getText" | "setText">;
+	editor: Pick<import("./clio-editor.js").ClioEditor, "getText" | "render" | "setText">;
 	getSlashContext: () => import("./slash-commands.js").SlashCommandContext;
+	/**
+	 * A worker permission or ask_user request parked waiting for the operator.
+	 * Wired to the desktop notification; absent hosts simply do not notify.
+	 */
+	onOperatorParked?: () => void;
 	showOverlayFrame?: typeof showClioOverlayFrame;
 	openAuthDialog?: typeof import("./overlays/auth-dialog.js").openAuthDialog;
 	openAskUserOverlay?: typeof import("./overlays/ask-user.js").openAskUserOverlay;
@@ -125,6 +144,11 @@ export interface OverlayLifecycleController {
 	openDecisionsOverlayState(): void;
 	openMemoryOverlayState(): void;
 	openViewOverlayState(initialFilter?: string): void;
+	/** `/btw <question>`: one side-question round rendered in its own overlay. */
+	openSideQuestionOverlayState(question: string): void;
+	/** `/handoff <goal>`: extract, review, and seed a successor session. */
+	startHandoffState(goal: string): void;
+	startFleetRunState(name: string, vars: Readonly<Record<string, string>>): void;
 	openModelOverlayState(): void;
 	openSettingsOverlayState(section?: SettingsSectionId, rowId?: SettingsCenterRowId): void;
 	openResumeOverlayState(): void;
@@ -132,7 +156,7 @@ export interface OverlayLifecycleController {
 	openMessagePickerOverlayState(): void;
 	openHelpOverlayState(query?: string): void;
 	openAgentsOverlayState(): void;
-	openSkillsHubState(): void;
+	openSkillsHubState(tab?: LibraryEntryKind): void;
 	openPromptsOverlayState(): void;
 	openExtensionsOverlayState(): void;
 	openInteropOverlayState(): void;
@@ -194,6 +218,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		cancelPendingAskUser: () => overlayAskUser?.cancelPending() ?? false,
 		finishAuth: (dismiss) => overlayAuth.finish(dismiss),
 		onPermissionOverlayClosed: () => overlayPermission?.onPermissionOverlayClosed(),
+		onOverlayClosed: () => overlayPermission?.retryPending(),
 	});
 	const closeOverlay = overlayTransitions.close;
 
@@ -227,10 +252,13 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 			if (overlayTransitions.state !== "closed") return false;
 			overlayTransitions.state = "permission-confirm";
 			overlayTransitions.handle = showOverlayFrame(tui, createPermissionOverlayBody(view), {
-				anchor: "center",
+				...permissionOverlayPlacement(tui, editor, footer.view),
 				width: PERMISSION_OVERLAY_WIDTH,
-				title: permissionOverlayTitle(),
-				footerHint: (innerWidth) => permissionOverlayHint(innerWidth),
+				title: permissionOverlayTitle(view),
+				tone: permissionOverlayTone(view),
+				// Read per frame: the footer names what Enter does right now, and
+				// that depends on whether the composer holds a draft.
+				footerHint: (innerWidth) => permissionOverlayHint(innerWidth, editor.getText().length > 0),
 			});
 			tui.requestRender();
 			return true;
@@ -247,6 +275,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 				source: "stream_cancel",
 				auditReason: "operator stopped the turn at a permission prompt",
 			}),
+		...(deps.onOperatorParked ? { onOperatorParked: deps.onOperatorParked } : {}),
 	});
 
 	overlayAskUser = createOverlayAskUserLifecycle({
@@ -264,6 +293,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		requestRender: () => tui.requestRender(),
 		...(deps.app.registerAskUserHandler ? { registerHandler: deps.app.registerAskUserHandler } : {}),
 		...(openAskUserOverlayFactory ? { openAskUserOverlay: openAskUserOverlayFactory } : {}),
+		...(deps.onOperatorParked ? { onOperatorParked: deps.onOperatorParked } : {}),
 	});
 
 	const overlayModelSelectors = createOverlayModelSelectors({
@@ -312,6 +342,10 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		getSlashNotice: () => deps.getSlashContext().notice,
 		...(deps.app.onResumeSession ? { onResumeSession: deps.app.onResumeSession } : {}),
 		...(deps.app.onForkSession ? { onForkSession: deps.app.onForkSession } : {}),
+		...(deps.app.onNewSession ? { onNewSession: deps.app.onNewSession } : {}),
+		...(deps.app.getDecisionBoard ? { getDecisionBoard: deps.app.getDecisionBoard } : {}),
+		terminal: deps.terminal,
+		suspendTerminal: deps.suspendTerminal,
 		announceTaskMemorySeedOffer,
 		sessionUsage: deps.app.observability,
 		...(setLastTurnSummary ? { setLastTurnSummary } : {}),
@@ -325,6 +359,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		...(openCwdFallbackOverlayFactory ? { openCwdFallbackOverlay: openCwdFallbackOverlayFactory } : {}),
 	});
 
+	const scheduling = deps.app.scheduling;
 	const overlayGeneralOpeners = createOverlayGeneralOpeners({
 		tui,
 		transitions: overlayTransitions,
@@ -351,6 +386,7 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		stateDir: deps.app.stateDir,
 		getSessionMeta: () => deps.app.session?.current() ?? null,
 		...(deps.app.readSessionEntries ? { readSessionEntries: deps.app.readSessionEntries } : {}),
+		...(deps.app.getSettings ? { getSettings: deps.app.getSettings } : {}),
 		terminal,
 		dispatchBoard,
 		startDispatchBoardTicker: () => interactiveTickers.startDispatchBoardTicker(),
@@ -363,6 +399,11 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		...(openDecisionsOverlayFactory ? { openDecisionsOverlay: openDecisionsOverlayFactory } : {}),
 		...(openMemoryOverlayFactory ? { openMemoryOverlay: openMemoryOverlayFactory } : {}),
 		...(openViewOverlayFactory ? { openViewOverlay: openViewOverlayFactory } : {}),
+		askSideQuestion: (question, options) => deps.app.chat.askSideQuestion(question, options),
+		...(deps.app.agents ? { agents: deps.app.agents } : {}),
+		...(scheduling ? { getBudgetPreflight: () => scheduling.preflight() } : {}),
+		isTurnInFlight: () => deps.app.chat.isStreaming(),
+		...(deps.setFleetRunPhase ? { setFleetRunPhase: deps.setFleetRunPhase } : {}),
 	});
 
 	const openResumeOverlayState = overlaySessions.openResume;
@@ -376,6 +417,9 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 	const openDecisionsOverlayState = overlayGeneralOpeners.openDecisions;
 	const openMemoryOverlayState = overlayGeneralOpeners.openMemory;
 	const openViewOverlayState = overlayGeneralOpeners.openView;
+	const openSideQuestionOverlayState = overlayGeneralOpeners.openSideQuestion;
+	const startFleetRunState = overlayGeneralOpeners.startFleetRun;
+	const startHandoffState = overlaySessions.startHandoff;
 	const toggleDispatchBoardOverlay = overlayGeneralOpeners.toggleDispatchBoard;
 
 	return {
@@ -395,6 +439,9 @@ export function createOverlayLifecycle(deps: OverlayLifecycleRuntimeDeps): Overl
 		openDecisionsOverlayState,
 		openMemoryOverlayState,
 		openViewOverlayState,
+		openSideQuestionOverlayState,
+		startFleetRunState,
+		startHandoffState,
 		openModelOverlayState: overlayModelSelectors.openModelOverlayState,
 		openSettingsOverlayState: overlayModelSelectors.openSettingsOverlayState,
 		openResumeOverlayState,

package/src/interactive/overlay-permission-lifecycle.ts

@@ -2,9 +2,11 @@ import { BusChannels, type PermissionRequestedPayload } from "../core/bus-events
 import type { SafeEventBus } from "../core/event-bus.js";
 import { ToolNames } from "../core/tool-names.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
-import type { ClassifierCall } from "../domains/safety/action-classifier.js";
+import type { ActionClass, ClassifierCall } from "../domains/safety/action-classifier.js";
 import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
 import type { SafetyDecision } from "../domains/safety/contract.js";
+import { decisionActionClass } from "../domains/safety/decision-presentation.js";
+import { askUserExposure } from "../tools/ask-user.js";
 import type { PermissionRequiredMeta, ToolRegistry } from "../tools/registry.js";
 import { approvalParkedNotice, autonomyDeniedNotice, workerEscalationNotice } from "./bus-notices.js";
 import type { ToolApprovalStateEvent } from "./chat-loop.js";
@@ -29,7 +31,7 @@ interface WorkerEscalationEntry {
 	requestId: string;
 	agentId: string;
 	tool: string;
-	actionClass: string;
+	actionClass: ActionClass;
 	axis: ApprovalRequestView["axis"];
 	reason: string;
 	target?: string;
@@ -48,6 +50,12 @@ export interface OverlayPermissionLifecycleDeps {
 	requestRender(): void;
 	/** End the in-flight run, carrying the text the operator will see. */
 	stopActiveTurn(reason: string): void;
+	/**
+	 * A worker permission request parked waiting for the operator. Fired once per
+	 * request, on the same dedup the operator-facing surfaces use, so a
+	 * re-presented dialog does not notify twice.
+	 */
+	onOperatorParked?(): void;
 }
 
 export interface OverlayPermissionLifecycle {
@@ -60,6 +68,14 @@ export interface OverlayPermissionLifecycle {
 	 */
 	stopTurn(): void;
 	onPermissionOverlayClosed(): void;
+	/**
+	 * Re-present whatever is still parked once no overlay holds the screen. A
+	 * request that arrived while `/context` or a picker was open could only be
+	 * announced, and nothing re-attempted the dialog when that overlay closed:
+	 * the transcript said awaiting approval, the footer said confirm, and the
+	 * operator had no key to press (issue #186).
+	 */
+	retryPending(): void;
 	dispose(): void;
 }
 
@@ -114,7 +130,7 @@ function mainApprovalRequestView(
 		(axisFromDecision.kind === "net"
 			? { kind: "net" as const, ruleId: axisFromDecision.ruleId }
 			: { kind: "autonomy" as const, level: autonomy });
-	const target = describeCallTarget(call.args);
+	const target = describeCallTarget(call.tool, call.args);
 	return {
 		requestId: meta?.requestId ?? "permission-pending",
 		tool: call.tool,
@@ -126,6 +142,7 @@ function mainApprovalRequestView(
 		...(call.tool === ToolNames.Dispatch && decision.kind === "ask"
 			? { artifact: { kind: "dispatch-plan" as const, text: decision.rejection.detail } }
 			: {}),
+		...(call.tool === ToolNames.AskUser ? { exposure: askUserExposure(call.args) } : {}),
 		...(target.length > 0 ? { target } : {}),
 		...(queueDepth !== undefined && queueDepth > 1 ? { queueDepth } : {}),
 	};
@@ -141,7 +158,7 @@ function workerEscalationEntry(payload: PermissionRequestedPayload, autonomy: st
 		requestId: payload.requestId,
 		agentId: typeof payload.agentId === "string" ? payload.agentId : "worker",
 		tool: typeof payload.tool === "string" ? payload.tool : "unknown",
-		actionClass: typeof payload.actionClass === "string" ? payload.actionClass : "unknown",
+		actionClass: decisionActionClass(payload.actionClass),
 		axis:
 			axisViewFromId(typeof payload.axis === "string" ? payload.axis : undefined, autonomy) ??
 			(typeof payload.ruleId === "string"
@@ -173,6 +190,8 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 	let pendingWorker: Pick<WorkerEscalationEntry, "agentId" | "requestId" | "runId"> | null = null;
 	const workerQueue: WorkerEscalationEntry[] = [];
 	const announcedRequestIds = new Set<string>();
+	/** Worker escalations already surfaced, so one request parks the operator once. */
+	const announcedWorkerRequestIds = new Set<string>();
 	let confirmed = false;
 	let stopping = false;
 
@@ -188,6 +207,12 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 		const next = workerQueue.shift();
 		if (next) openWorker(next);
 	};
+	const retryPending = (): void => {
+		maybeOpenWorker();
+		if (deps.getOverlayState() === "closed" && deps.toolRegistry?.hasParkedCalls()) {
+			deps.toolRegistry.renotifyHead();
+		}
+	};
 
 	const unsubscribePermission =
 		deps.toolRegistry?.onPermissionRequired((call, decision, meta) => {
@@ -228,8 +253,10 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 	const unsubscribeWorker = deps.bus.on(BusChannels.PermissionRequested, (payload) => {
 		const entry = workerEscalationEntry(payload, deps.getAutonomy());
 		if (!entry) return;
+		if (!markPermissionRequestSurfaced(announcedWorkerRequestIds, entry.requestId)) return;
 		const notice = workerEscalationNotice(payload);
 		if (notice !== null) deps.appendNotice(notice.level, notice.text);
+		deps.onOperatorParked?.();
 		workerQueue.push(entry);
 		maybeOpenWorker();
 	});
@@ -310,10 +337,7 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 			workerQueue.length = 0;
 			return;
 		}
-		maybeOpenWorker();
-		if (deps.getOverlayState() === "closed" && deps.toolRegistry?.hasParkedCalls()) {
-			deps.toolRegistry.renotifyHead();
-		}
+		retryPending();
 	};
 
 	return {
@@ -336,6 +360,7 @@ export function createOverlayPermissionLifecycle(deps: OverlayPermissionLifecycl
 			);
 		},
 		onPermissionOverlayClosed,
+		retryPending,
 		dispose: () => {
 			unsubscribePermission();
 			unsubscribeWorker();

package/src/interactive/overlay-resource-openers.ts

@@ -1,4 +1,4 @@
-import type { ResourcesContract } from "../domains/resources/index.js";
+import type { LibraryEntryKind, ResourcesContract } from "../domains/resources/index.js";
 import { installSkill as installMarketplaceSkill } from "../domains/resources/skills/marketplace.js";
 import type { TUI } from "../engine/tui.js";
 import type { ClioEditor } from "./clio-editor.js";
@@ -32,7 +32,7 @@ export interface OverlayResourceOpenersDeps {
 export interface OverlayResourceOpeners {
 	openHelpOverlayState(query?: string): void;
 	openAgentsOverlayState(): void;
-	openSkillsHubState(): void;
+	openSkillsHubState(tab?: LibraryEntryKind): void;
 	openPromptsOverlayState(): void;
 	openExtensionsOverlayState(): void;
 	openInteropOverlayState(): void;
@@ -61,10 +61,18 @@ export function createOverlayResourceOpeners(deps: OverlayResourceOpenersDeps):
 		deps.tui.requestRender();
 	};
 
-	const openSkillsHubState = (): void => {
+	const openSkillsHubState = (tab?: LibraryEntryKind): void => {
 		if (deps.transitions.state !== "closed") return;
 		deps.transitions.state = "skills-hub";
 		deps.transitions.handle = openSkills(deps.tui, {
+			...(tab ? { initialTab: tab } : {}),
+			// A fleet's `use` is its approval preview, which is a surface of its own.
+			// The hub closes first so the preview owns the overlay slot, exactly as
+			// `/fleet run <name>` typed into the composer would.
+			openFleetRun: (name) => {
+				deps.closeOverlay();
+				deps.getSlashContext().startFleetRun?.(name, {});
+			},
 			listSkills: () => deps.resources?.skills(process.cwd()) ?? { items: [], diagnostics: [] },
 			setEditorText: (text) => {
 				deps.editor.setText(text);

package/src/interactive/overlay-session-lifecycle.ts

@@ -1,14 +1,29 @@
 import { resolveSessionCwd } from "../domains/session/cwd-fallback.js";
+import type { DecisionLedgerEntry } from "../domains/session/entries.js";
+import {
+	buildHandoffReadLedger,
+	HANDOFF_NOTE_CUSTOM_TYPE,
+	HANDOFF_SEED_CUSTOM_TYPE,
+	type HandoffNoteData,
+	type HandoffSeedData,
+	mergeHandoffDecisions,
+	parseHandoffExtraction,
+	renderHandoffDocument,
+	validateHandoffFiles,
+	validateHandoffGoal,
+} from "../domains/session/handoff.js";
 import type { SessionContract, SessionEntry } from "../domains/session/index.js";
 import type { TUI } from "../engine/tui.js";
 import type { ChatLoop } from "./chat-loop.js";
 import type { ChatPanel } from "./chat-panel.js";
 import { rehydrateChatPanelFromTurns } from "./chat-renderer.js";
 import { emitCommandNotice } from "./command-fallbacks.js";
+import { editTextExternally, resolveExternalEditor } from "./external-editor.js";
 import type { InteractiveNoticeLevel } from "./interactive-subscriptions.js";
 import { buildModelReplayAgentMessagesFromTurns } from "./model-session-replay.js";
 import type { OverlayTransitions } from "./overlay-transitions.js";
 import { openCwdFallbackOverlay } from "./overlays/cwd-fallback.js";
+import { openHandoffReviewOverlay } from "./overlays/handoff-review.js";
 import { openMessagePickerOverlay } from "./overlays/message-picker.js";
 import { openSessionOverlay } from "./overlays/session-selector.js";
 import { openTreeOverlay } from "./overlays/tree-selector.js";
@@ -22,7 +37,7 @@ export interface OverlaySessionLifecycleDeps {
 	tui: TUI;
 	transitions: OverlayTransitions;
 	session?: SessionContract;
-	chat: Pick<ChatLoop, "cancel" | "isStreaming" | "resetForSession" | "whenSettled">;
+	chat: Pick<ChatLoop, "cancel" | "isStreaming" | "resetForSession" | "whenSettled" | "extractHandoff">;
 	chatPanel: ChatPanel;
 	/** The one transcript reset: the panel plus every view folded alongside it. */
 	resetTranscript(): void;
@@ -30,6 +45,18 @@ export interface OverlaySessionLifecycleDeps {
 	getSlashNotice(): SlashCommandContext["notice"];
 	onResumeSession?(sessionId: string): void;
 	onForkSession?(parentTurnId: string): void;
+	/**
+	 * Mint a fresh session, the same hook `/new` uses. `/handoff` needs the one
+	 * session-creation path the orchestrator owns rather than a second one.
+	 */
+	onNewSession?(): void;
+	/** The session's settled decision board, which wins over extracted decisions. */
+	getDecisionBoard?(): ReadonlyArray<DecisionLedgerEntry>;
+	/** Stop and restart the terminal around an external editor child process. */
+	suspendTerminal?<T>(run: () => T): T;
+	resolveEditor?: typeof resolveExternalEditor;
+	editExternally?: typeof editTextExternally;
+	openHandoffReviewOverlay?: typeof openHandoffReviewOverlay;
 	announceTaskMemorySeedOffer(): void;
 	/**
 	 * Running usage totals, reseeded whenever the session under them changes.
@@ -45,6 +72,8 @@ export interface OverlaySessionLifecycleDeps {
 	setLastTurnSummary?(summary: TurnSummary | null): void;
 	refreshFooter(): void;
 	requestRender(): void;
+	/** Live terminal width, so the handoff review box tracks the window. */
+	terminal?: { columns: number };
 	stderr(text: string): void;
 	notify(level: InteractiveNoticeLevel, text: string, key?: string): void;
 	openSessionOverlay?: typeof openSessionOverlay;
@@ -57,6 +86,8 @@ export interface OverlaySessionLifecycle {
 	openResume(): void;
 	openTree(): void;
 	openMessagePicker(): void;
+	/** `/handoff <goal>`: extract, review, and seed a successor session. */
+	startHandoff(goal: string): void;
 }
 
 /**
@@ -327,5 +358,206 @@ export function createOverlaySessionLifecycle(deps: OverlaySessionLifecycleDeps)
 		deps.requestRender();
 	}
 
-	return { openResume, openTree, openMessagePicker: openMessagePickerState };
+	/**
+	 * `/handoff <goal>`: carry this session's working state into a fresh one.
+	 *
+	 * A handoff is a session operation. It writes no memory promotion candidate,
+	 * touches no memory record, and never calls the task-memory bank; the only
+	 * things it writes are one seed entry plus replayed skill activations in the
+	 * new session and one terminal note in the old one, and it writes none of
+	 * them until the operator has accepted the document.
+	 */
+	function startHandoff(goal: string): void {
+		if (deps.transitions.state !== "closed") return;
+		const notice = deps.getSlashNotice();
+		const verdict = validateHandoffGoal(goal);
+		if (!verdict.ok) {
+			emitCommandNotice(notice, "warn", "handoff", verdict.reason);
+			return;
+		}
+		if (!deps.session) {
+			emitCommandNotice(notice, "error", "handoff", "session contract unavailable");
+			return;
+		}
+		if (!deps.onNewSession) {
+			emitCommandNotice(notice, "error", "handoff", "no session-creation path is wired in this session");
+			return;
+		}
+		// Refused, never queued. The document describes a session that has
+		// stopped; a turn still in flight is about to change what it would say.
+		if (deps.chat.isStreaming()) {
+			emitCommandNotice(
+				notice,
+				"warn",
+				"handoff",
+				"a turn is in flight; /handoff cannot summarize a session that is still moving",
+			);
+			return;
+		}
+		const session = deps.session;
+		const fromSessionId = session.current()?.id ?? null;
+		if (fromSessionId === null) {
+			emitCommandNotice(notice, "warn", "handoff", "no current session to hand off; start one with /new or /resume");
+			return;
+		}
+		void runHandoffExtraction(session, fromSessionId, verdict.goal);
+	}
+
+	async function runHandoffExtraction(session: SessionContract, fromSessionId: string, goal: string): Promise<void> {
+		const notice = deps.getSlashNotice();
+		const outcome = await deps.chat.extractHandoff(goal);
+		if (outcome.status !== "answered") {
+			const reason = outcome.status === "aborted" ? "the extraction round was cancelled" : outcome.reason;
+			emitCommandNotice(notice, outcome.status === "failed" ? "error" : "warn", "handoff", reason);
+			return;
+		}
+		const parsed = parseHandoffExtraction(outcome.text);
+		if (!parsed.ok) {
+			emitCommandNotice(notice, "error", "handoff", parsed.reason);
+			return;
+		}
+		const meta = session.current();
+		const cwd = typeof meta?.cwd === "string" && meta.cwd.length > 0 ? meta.cwd : null;
+		const entries = deps.readStructuredEntries(fromSessionId);
+		// The ledger is what this session's own tool calls touched, folded through
+		// the active path so an abandoned `/tree` branch is not evidence.
+		const ledger = buildHandoffReadLedger(entries, { cwd, leafTurnId: meta?.pinnedLeafTurnId ?? null });
+		const files = validateHandoffFiles(parsed.result.extraction.files, ledger, cwd);
+		const decisions = mergeHandoffDecisions(parsed.result.extraction.decisions, deps.getDecisionBoard?.() ?? []);
+		const document = renderHandoffDocument({
+			goal,
+			fromSessionId,
+			decisions,
+			facts: parsed.result.extraction.facts,
+			files: files.kept,
+			droppedFiles: files.dropped,
+			commands: parsed.result.extraction.commands,
+			openQuestions: parsed.result.extraction.openQuestions,
+			truncations: parsed.result.truncations,
+		});
+		openHandoffReview(session, fromSessionId, goal, document);
+	}
+
+	/** Hand the document to `$EDITOR`, or say why it could not go. */
+	function editHandoffDocument(current: string): string | null {
+		const resolve = deps.resolveEditor ?? resolveExternalEditor;
+		const edit = deps.editExternally ?? editTextExternally;
+		const command = resolve();
+		if (!command) {
+			deps.notify("warning", "handoff: no external editor configured; set VISUAL or EDITOR", "handoff:no-editor");
+			return null;
+		}
+		const suspend = deps.suspendTerminal ?? (<T>(run: () => T): T => run());
+		const result = suspend(() => edit(current, command));
+		if (result.ok) return result.text ?? current;
+		if (result.error) deps.notify("warning", `handoff: ${result.error}`, "handoff:editor-failed");
+		return null;
+	}
+
+	function openHandoffReview(session: SessionContract, fromSessionId: string, goal: string, document: string): void {
+		if (deps.transitions.state !== "closed") return;
+		const openReview = deps.openHandoffReviewOverlay ?? openHandoffReviewOverlay;
+		deps.transitions.state = "handoff-review";
+		deps.transitions.handle = openReview(deps.tui, {
+			document,
+			goal,
+			columns: deps.terminal?.columns ?? 80,
+			onEdit: editHandoffDocument,
+			onAccept: (reviewed) => {
+				deps.transitions.close();
+				const text = reviewed.trim();
+				if (text.length === 0) {
+					deps.notify("warning", "handoff: the reviewed document was empty; nothing was written", "handoff:empty");
+					return;
+				}
+				seedHandoffSession(session, fromSessionId, goal, text);
+			},
+			// Esc. Nothing has been written yet, so cancel really is free. The
+			// overlay settles itself on cancel and answers no further key, so the
+			// transition has to close here or the review stays on screen inert.
+			onCancel: () => {
+				deps.transitions.close();
+				deps.notify("info", "handoff cancelled; nothing was written", "handoff:cancelled");
+			},
+		});
+		deps.requestRender();
+	}
+
+	/**
+	 * Mint the successor session and open it on the reviewed document.
+	 *
+	 * Order matters. The old session's terminal note is appended while it is
+	 * still current, because an append always lands in the current session. Then
+	 * the new session is minted through the one creation path the orchestrator
+	 * owns, the document goes in as bounded data labelled by its origin, and the
+	 * old session's skill activations are replayed so loaded skills carry
+	 * forward. The old session is otherwise untouched.
+	 */
+	function seedHandoffSession(session: SessionContract, fromSessionId: string, goal: string, document: string): void {
+		const notice = deps.getSlashNotice();
+		const activations = session.current()?.skillActivations ?? [];
+		let toSessionId: string;
+		try {
+			deps.onNewSession?.();
+			const minted = session.current()?.id ?? null;
+			if (minted === null || minted === fromSessionId) throw new Error("the new session was not created");
+			toSessionId = minted;
+			session.appendEntry({
+				kind: "custom",
+				parentTurnId: null,
+				customType: HANDOFF_SEED_CUSTOM_TYPE,
+				display: true,
+				data: { fromSessionId, goal, document } satisfies HandoffSeedData,
+			});
+			for (const activation of activations) session.recordSkillActivation(activation);
+		} catch (error) {
+			emitCommandNotice(
+				notice,
+				"error",
+				"handoff",
+				`could not seed the new session: ${error instanceof Error ? error.message : String(error)}`,
+			);
+			return;
+		}
+		// The note names the target, so it can only be written once the target
+		// exists. Appends land in the current session, so the old session is made
+		// current for exactly one append and then handed back. A failure here
+		// costs the note and nothing else: the successor session is already
+		// seeded and is where the operator continues.
+		try {
+			session.switchBranch(fromSessionId);
+			session.appendEntry({
+				kind: "custom",
+				parentTurnId: null,
+				customType: HANDOFF_NOTE_CUSTOM_TYPE,
+				display: true,
+				data: { toSessionId, goal } satisfies HandoffNoteData,
+			});
+		} catch (error) {
+			deps.stderr(`[/handoff] handoff note failed: ${error instanceof Error ? error.message : String(error)}\n`);
+		} finally {
+			try {
+				session.switchBranch(toSessionId);
+			} catch (error) {
+				deps.stderr(
+					`[/handoff] could not return to the new session: ${error instanceof Error ? error.message : String(error)}\n`,
+				);
+			}
+		}
+		try {
+			const turns = deps.readStructuredEntries(toSessionId);
+			deps.resetTranscript();
+			rehydrateChatPanelFromTurns(deps.chatPanel, turns);
+			deps.chat.resetForSession(null, buildModelReplayAgentMessagesFromTurns(turns));
+			rescopeToBranch(session, turns, null);
+		} catch (error) {
+			deps.stderr(`[/handoff] seeding replay failed: ${error instanceof Error ? error.message : String(error)}\n`);
+			deps.chat.resetForSession(null);
+		}
+		emitCommandNotice(notice, "info", "handoff", `handed off to session ${toSessionId}`);
+		deps.refreshFooter();
+		deps.requestRender();
+	}
+
+	return { openResume, openTree, openMessagePicker: openMessagePickerState, startHandoff };
 }

package/src/interactive/overlay-transitions.ts

@@ -9,6 +9,12 @@ export interface OverlayTransitionsDeps {
 	cancelPendingAskUser: () => boolean;
 	finishAuth: (dismiss: boolean) => void;
 	onPermissionOverlayClosed: () => void;
+	/**
+	 * Runs after any overlay has closed and the state is back to `closed`. The
+	 * permission lifecycle uses it to re-present a call that parked while this
+	 * overlay held the screen; nothing else re-attempts that dialog.
+	 */
+	onOverlayClosed?: () => void;
 }
 
 export interface OverlayTransitions {
@@ -26,7 +32,11 @@ export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayT
 			return state;
 		},
 		set state(next) {
+			const closing = state !== "closed" && next === "closed";
 			state = next;
+			// The ask-user and auth lifecycles leave by assigning the state rather
+			// than through `close`, so the hook fires here for them.
+			if (closing) deps.onOverlayClosed?.();
 		},
 		get handle() {
 			return handle;
@@ -50,6 +60,7 @@ export function createOverlayTransitions(deps: OverlayTransitionsDeps): OverlayT
 		handle?.hide();
 		handle = null;
 		if (leaving === "permission-confirm") deps.onPermissionOverlayClosed();
+		else deps.onOverlayClosed?.();
 		deps.renderContextIsland();
 		deps.renderTaskIsland();
 		deps.requestRender();