@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/tools/plan-tools.js

@@ -0,0 +1,198 @@
+/**
+ * `ask_user` and `submit_plan` — the two tools that only exist because a human
+ * is attached (plan-mode §4.1 / §4.2 / §5.3).
+ *
+ * ASCII ONLY: `tools/` is inside the glyph scanner's scope.
+ *
+ * THE SCHEMAS DECLARE SHAPE, NOT POLICY (P0-4). `type`, `required` and `default`
+ * stay, because a `questions` value that is not an array has nothing for a
+ * normalizer to repair and both validator strategies agree on that check.
+ * Everything else — how many questions, how many options, how long a header may
+ * be — lives in the `description`, which is what the model actually reads, and
+ * is enforced by `normalizeQuestions` / `normalizePlan`. Putting `maxItems: 5`
+ * in the schema instead had two failure modes at once: with `ajv` present
+ * `ToolExecutor` rejected a six-question call outright and the repair rules were
+ * dead code; without it (ajv is an OPTIONAL dependency of core) the same call
+ * sailed straight through to the repair path. One design, two behaviours,
+ * selected by whether an optional install step succeeded.
+ */
+import { errorResult, textResult } from '@aragon-agent/core';
+import { formatAnswersResult, normalizePlan, normalizeQuestions, } from './human-input.js';
+// ---------------------------------------------------------------------------
+// Shared refusal text
+// ---------------------------------------------------------------------------
+const NO_INTERACTIVE_USER = 'No interactive user is attached (-p/--print mode). Do not ask questions: ' +
+    'state your assumptions explicitly and continue.';
+const NO_INTERACTIVE_REVIEWER = 'No interactive reviewer is attached. Emit the full plan as your final answer ' +
+    'in markdown instead.';
+function roundCapRefusal(used) {
+    return (`You have already asked ${used} rounds of questions (the configured maximum). ` +
+        'Proceed with your best assumptions and state them in the plan.');
+}
+// ---------------------------------------------------------------------------
+// ask_user
+// ---------------------------------------------------------------------------
+const ASK_USER_DESCRIPTION = 'Ask the user 1-5 multiple-choice questions when a decision would change the work. ' +
+    'Give each question a stable id, a header of at most 12 characters, and 2-4 options; ' +
+    'exactly one option must set recommended:true, with the reason in its description. ' +
+    'Extra questions or options beyond these limits are dropped, so keep within them. ' +
+    'Do not ask anything you could answer by reading the workspace.';
+function makeAskUser(opts) {
+    return {
+        name: 'ask_user',
+        label: 'Ask the user',
+        description: ASK_USER_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                questions: {
+                    type: 'array',
+                    description: '1-5 questions, asked in one round.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string', description: 'Stable key echoed back in the answer.' },
+                            header: {
+                                type: 'string',
+                                description: 'Very short chip label (<= 12 chars), e.g. "Datastore".',
+                            },
+                            question: { type: 'string', description: '<= 300 chars.' },
+                            allowMultiple: { type: 'boolean', default: false },
+                            options: {
+                                type: 'array',
+                                description: '2-4 options. Exactly one must be recommended.',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        label: { type: 'string', description: '<= 60 chars.' },
+                                        description: {
+                                            type: 'string',
+                                            description: '<= 120 chars. Why this option.',
+                                        },
+                                        recommended: { type: 'boolean', default: false },
+                                    },
+                                    required: ['label'],
+                                },
+                            },
+                        },
+                        required: ['id', 'header', 'question', 'options'],
+                    },
+                },
+            },
+            required: ['questions'],
+        },
+        async execute(_id, params, ctx) {
+            // Probed BEFORE the work, never discovered afterwards: a missing human
+            // channel must mean "refuse with an actionable message", not "wait
+            // forever" and not "assume yes".
+            if (!opts.gate.canPrompt())
+                return errorResult(NO_INTERACTIVE_USER);
+            const questions = normalizeQuestions(params.questions);
+            if (questions.length === 0) {
+                return errorResult('No usable questions: each needs 2-4 distinct options.');
+            }
+            const ticket = opts.takeAskRound();
+            if (!ticket.ok)
+                return errorResult(roundCapRefusal(ticket.used));
+            const response = await opts.withHumanWait(() => opts.gate.request({ kind: 'questions', questions }, ctx.signal));
+            // `null` covers cancel, unmount, abort AND timeout. From the model's point
+            // of view an unanswered question and an abandoned one are the same
+            // situation and want the same guidance, so they share a shape — and it is
+            // a NON-error result on purpose: a cancellation rendered as a tool failure
+            // invites a retry loop.
+            const cancelled = response === null || response.kind !== 'answers' || response.cancelled;
+            const answers = response !== null && response.kind === 'answers' ? response.answers : [];
+            return textResult(formatAnswersResult({
+                answers,
+                cancelled,
+                roundsUsed: ticket.used,
+                roundsRemaining: ticket.remaining,
+            }, questions.length));
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// submit_plan
+// ---------------------------------------------------------------------------
+const SUBMIT_PLAN_DESCRIPTION = 'Present the implementation plan for approval. Call this exactly once, after you ' +
+    'have read enough of the workspace to be specific. Steps must be ordered and ' +
+    'independently verifiable. Limits, enforced by truncation rather than rejection: ' +
+    'title <= 80 chars, summary <= 600, at most 20 steps (title <= 100, detail <= 400), ' +
+    'at most 30 filesTouched, 10 risks, 10 openQuestions.';
+const APPROVED_RESULT = 'Plan approved. You are now in Build mode - implement the plan step by step, in order.';
+const DISMISSED_RESULT = 'The user dismissed the plan review without a verdict. Ask a clarifying question ' +
+    'or refine the plan, then call submit_plan again.';
+function makeSubmitPlan(opts) {
+    return {
+        name: 'submit_plan',
+        label: 'Submit plan',
+        description: SUBMIT_PLAN_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                title: { type: 'string' },
+                summary: { type: 'string' },
+                steps: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            title: { type: 'string' },
+                            detail: { type: 'string' },
+                        },
+                        required: ['title'],
+                    },
+                },
+                filesTouched: { type: 'array', items: { type: 'string' } },
+                risks: { type: 'array', items: { type: 'string' } },
+                openQuestions: { type: 'array', items: { type: 'string' } },
+            },
+            required: ['title', 'summary', 'steps'],
+        },
+        async execute(_id, params, ctx) {
+            // Non-error: under `-p` the read-only gate still applies, so "plan this
+            // and do not touch my repository" is a legitimate combination and must not
+            // read as a malfunction.
+            if (!opts.gate.canPrompt())
+                return textResult(NO_INTERACTIVE_REVIEWER);
+            const plan = normalizePlan(params);
+            if (!plan)
+                return errorResult('A plan needs at least one step with a title.');
+            const response = await opts.withHumanWait(() => opts.gate.request({ kind: 'plan', plan }, ctx.signal));
+            if (response === null || response.kind !== 'planDecision') {
+                return textResult(DISMISSED_RESULT);
+            }
+            if (response.decision === 'approved') {
+                opts.onPlanApproved();
+                return textResult(APPROVED_RESULT);
+            }
+            if (response.decision === 'revise') {
+                return textResult(`Plan rejected. The user's feedback: "${response.feedback}". ` +
+                    'Revise and call submit_plan again.');
+            }
+            return textResult(DISMISSED_RESULT);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+/**
+ * Build the plan tools, or `[]` for a channel that can never reach a human.
+ *
+ * KEYED ON `neverPrompts`, NOT `canPrompt()` (P0-3). This function runs inside
+ * `makeController()`, and in the interactive path the bridge handler is still
+ * null there — the App attaches it later, in an effect. So `canPrompt()` is
+ * false for EVERY session at this moment, and gating registration on it would
+ * ship plan mode with no `ask_user` and no `submit_plan`, in every interactive
+ * session, with nothing anywhere reporting it.
+ *
+ * Registration is a one-time structural question ("can this channel ever reach a
+ * human?"). `canPrompt()` answers a live one ("is one attached right now?") and
+ * is checked again inside each tool, where it belongs.
+ */
+export function createPlanTools(opts) {
+    if (opts.gate.neverPrompts)
+        return [];
+    return [makeAskUser(opts), makeSubmitPlan(opts)];
+}

package/dist/ui/App.d.ts

@@ -9,6 +9,9 @@ import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
 import { type Overlay } from '../agent/reducer.js';
 import { type RenderMode } from './layout/frame.js';
+import { type FrameGeometry } from './layout/regions.js';
+import type { MouseSource } from '../input/stdin-mouse-filter.js';
+import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
     handler: ((req: ConfirmRequest) => Promise<boolean>) | null;
 }
@@ -20,5 +23,13 @@ export interface AppProps {
     initialOverlay?: Overlay;
     initialPrompt?: string;
     confirmBridge?: ConfirmBridge;
+    /** The plan-mode human channel; absent in tests that do not exercise it. */
+    humanInputBridge?: HumanInputBridge;
+    /** Wheel events, already stripped out of stdin. Absent whenever mouse support
+     *  is off: inline mode, `--no-mouse`, a non-TTY, or a filter that failed to
+     *  build (mouse-wheel-region-routing §4.2). */
+    mouseSource?: MouseSource;
+    /** Test-only seam (§8.2): frame geometry, bypassing `measureElement`. */
+    geometryOverride?: FrameGeometry;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, geometryOverride, }: AppProps): React.ReactElement;

package/dist/ui/App.js

@@ -12,7 +12,10 @@ import { initialViewState, reduceEvent, viewReducer, } from '../agent/reducer.js
 import { mergeDeltas } from '../agent/coalesce.js';
 import { coerceMaxTokens, DEFAULT_TRANSCRIPT_WINDOW, PROMPT_HISTORY_CAP, } from '../config/schema.js';
 import { updatePersistedConfig } from '../config/store.js';
+import { getLogger } from '../logging/logger.js';
+import { registerSecret } from '../logging/secret-registry.js';
 import { detectCapabilities } from './capabilities.js';
+import { useStartupNotices } from './use-startup-notices.js';
 import { getTheme } from './theme.js';
 import { pickGlyphs } from './glyphs.js';
 import { Header } from './Header.js';
@@ -28,6 +31,8 @@ import { ScrollViewport } from './layout/ScrollViewport.js';
 import { useTerminalSize } from './layout/useTerminalSize.js';
 import { frameHeight, MIN_FULLSCREEN_ROWS } from './layout/frame.js';
 import { HINT_MIN_ROWS, viewportRows as computeViewportRows } from './layout/budget.js';
+import { UNMEASURED_GEOMETRY } from './layout/regions.js';
+import { OVERLAY_PAGE, useWheelRouting } from './use-wheel-routing.js';
 import { installConsoleBridge } from './console-bridge.js';
 import { publishExitSnapshot } from './exit-snapshot.js';
 import { OverlayFrame } from './layout/OverlayFrame.js';
@@ -35,14 +40,15 @@ import { helpRows } from './overlays/HelpOverlay.js';
 import { ModelPicker } from './overlays/ModelPicker.js';
 import { SettingsScreen } from './overlays/SettingsScreen.js';
 import { ConfirmDialog } from './overlays/ConfirmDialog.js';
+import { QuestionOverlay } from './overlays/QuestionOverlay.js';
+import { PlanReviewOverlay } from './overlays/PlanReviewOverlay.js';
 import { CommandRegistry, runSlashInput } from '../commands/registry.js';
 import { registerBuiltinCommands } from '../commands/builtins.js';
 import { makeSkillsCommand, registerSkillCommands } from '../commands/skills.js';
+import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 /** Merge pending delta actions ~33 ms and flush the coalescer buffer. */
 const COALESCE_MS = 33;
-/** Rows a PgUp/PgDn moves inside a controlled overlay. */
-const OVERLAY_PAGE = 8;
-export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, }) {
+export function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, geometryOverride, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const fullscreen = mode === 'fullscreen';
@@ -50,9 +56,13 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const [state, dispatch] = useReducer(viewReducer, undefined, initialViewState);
     const [elapsedMs, setElapsedMs] = useState(0);
     const [confirmState, setConfirmState] = useState(null);
+    /** The request the question / plan overlay is currently rendering. */
+    const [humanRequest, setHumanRequest] = useState(null);
     const [promptHistory, setPromptHistory] = useState(() => controller.getConfig().promptHistory ?? []);
     // Scroll plumbing: intent goes down, one derived display number comes back.
     const [scrollIntent, setScrollIntent] = useState();
+    /** One prompt-history step per wheel notch over the composer band (§4.7). */
+    const [historyIntent, setHistoryIntent] = useState();
     const [pinToBottomNonce, setPinToBottomNonce] = useState(0);
     const [scrolledLines, setScrolledLines] = useState(0);
     // I-5 (§4.13): Ctrl+L cannot repaint by writing escapes — Ink dedupes
@@ -87,6 +97,34 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const ctrlCTimer = useRef(null);
     const runBaselineOut = useRef(0);
     const toastTimers = useRef(new Map());
+    /** Every outstanding `gate.request()`. Held in a ref, never in state: it is
+     *  bookkeeping for promises, and re-rendering on it would be noise. */
+    const pendingHuman = useRef(new Set());
+    /** Written by `AppShell`'s layout effect, read at wheel-event time (§4.5). */
+    const geometryRef = useRef(UNMEASURED_GEOMETRY);
+    /**
+     * THE SINGLE SETTLE PATH for a human request. Idempotent per entry, and it
+     * clears the overlay as its last act.
+     *
+     * Exactly four callers, and there must be no fifth: the overlay's own submit,
+     * `Esc` in `App`, the `ctx.signal` abort listener, and `cancelPending()`.
+     * Every one of them can race the others, which is what `done` is for.
+     */
+    const settleHuman = useCallback((entry, value) => {
+        if (entry.done)
+            return;
+        entry.done = true;
+        pendingHuman.current.delete(entry);
+        entry.resolve(value);
+        if (pendingHuman.current.size === 0) {
+            setHumanRequest(null);
+            dispatch({ type: 'setOverlay', overlay: null });
+        }
+    }, []);
+    const cancelPendingHuman = useCallback(() => {
+        for (const entry of [...pendingHuman.current])
+            settleHuman(entry, null);
+    }, [settleHuman]);
     const registry = useMemo(() => {
         const r = new CommandRegistry();
         // Order matters: built-ins first, so `registerSkillCommands` sees them when
@@ -131,12 +169,31 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
                     dispatch(action);
                 }
             }
+            if (event.type !== 'agent_end')
+                return;
+            // NO OVERLAY OUTLIVES ITS RUN (P1-4). `ctx.signal` already covers the
+            // abort path, so this is DELIBERATE REDUNDANCY: it makes "the card cannot
+            // survive the run that opened it" a property of the App's lifecycle
+            // rather than a consequence of signal plumbing three modules away.
+            // Without it, an aborted run leaves a plan card on screen whose `a` key
+            // silently flips the session to build, with no visible cause.
+            cancelPendingHuman();
+            // A deferred `plan -> build` becomes real here and nowhere else (§3.2).
+            const applied = controller.applyPendingMode();
+            if (applied) {
+                dispatch({ type: 'setAgentMode', mode: applied.effective, pending: null });
+                dispatch({
+                    type: 'pushToast',
+                    level: 'info',
+                    text: `${MODE_LABEL[applied.effective]} mode.`,
+                });
+            }
         });
         return () => {
             flushPending();
             unsubscribe();
         };
-    }, [controller, flushPending]);
+    }, [controller, flushPending, cancelPendingHuman]);
     // --- Elapsed timer + tokens/sec baseline while running. ----------------
     useEffect(() => {
         if (state.status !== 'running') {
@@ -180,6 +237,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             return undefined;
         return installConsoleBridge((level, text) => dispatch({ type: 'notice', level, text }));
     }, [fullscreen]);
+    // `enabled` is `mouseSource`, not `cfg.mouse`: a user whose terminal drops
+    // the events must never be shown advice about a mode not in effect (§6.1).
+    useStartupNotices(dispatch, {
+        enabled: !!mouseSource,
+        onSeen: () => persistConfig({ mouseNoticeSeen: true }),
+    });
     // --- Exit snapshot: the only way state reaches cli.tsx (§4.4). ----------
     useEffect(() => {
         publishExitSnapshot({
@@ -205,6 +268,42 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             confirmBridge.handler = null;
         };
     }, [confirmBridge]);
+    // --- Human-input bridge (ask_user / submit_plan). ----------------------
+    useEffect(() => {
+        if (!humanInputBridge)
+            return undefined;
+        const bridge = humanInputBridge;
+        bridge.handler = (req, signal) => new Promise((resolve) => {
+            const entry = { resolve, done: false };
+            pendingHuman.current.add(entry);
+            // THE ONLY CEILING THIS WAIT HAS. `ToolExecutor`'s timeout is
+            // cooperative — it aborts the context signal and keeps awaiting the
+            // tool — and the idle watchdog is deliberately paused for the duration.
+            // Without this listener both ceilings are gone at once and the process
+            // wedges behind an overlay nobody is going to answer (P0-2).
+            signal?.addEventListener('abort', () => settleHuman(entry, null), { once: true });
+            setHumanRequest(req);
+            dispatch({
+                type: 'setOverlay',
+                overlay: req.kind === 'plan' ? 'plan' : 'question',
+            });
+        });
+        bridge.cancelPending = cancelPendingHuman;
+        return () => {
+            // BEFORE nulling the handler, not after: `ConfirmBridge` nulls its handler
+            // and leaves in-flight promises dangling forever, which with a wizard the
+            // user abandons would hang the tool until its ceiling (R-P4).
+            cancelPendingHuman();
+            bridge.handler = null;
+        };
+    }, [humanInputBridge, settleHuman, cancelPendingHuman]);
+    // --- Seed the mode mirror from its owner, once, on mount. --------------
+    // `--plan` / `planModeDefault` are resolved before the App exists, so the
+    // reducer's `'build'` seed would render one wrong frame without this.
+    useEffect(() => {
+        const current = controller.getAgentMode();
+        dispatch({ type: 'setAgentMode', mode: current, pending: null });
+    }, [controller]);
     // --- Let the controller drive command-list rebuilds. -------------------
     useEffect(() => {
         controller.setOnSkillsChanged(() => setSkillsNonce((n) => n + 1));
@@ -248,15 +347,44 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     const persistConfig = (patch) => {
         try {
             updatePersistedConfig(patch);
+            getLogger().info('config', 'config_write', { keys: Object.keys(patch) });
         }
-        catch {
-            // Best-effort: a failed persist should not break the live session.
+        catch (err) {
+            // Still best-effort — a failed persist must not break the live session —
+            // but no longer SILENT. Swallowing this is the root of "I changed the
+            // model in the TUI and it was back to the old one after a restart", a
+            // report with nothing anywhere to investigate.
+            const reason = err instanceof Error ? err.message : String(err);
+            getLogger().error('config', 'config_write_failed', { reason });
+            toast('warn', `Could not save settings: ${reason}`);
         }
     };
     const doExit = () => {
         controller.abort();
         exit();
     };
+    /**
+     * THE SINGLE MODE WRITE PATH (§3.1 / R-P7).
+     *
+     * `Shift+Tab` and `/plan` both come through here, which is what makes them
+     * the same code path rather than two that can drift. Note that the value
+     * dispatched into the view is what the controller reports it ADOPTED, never
+     * what was requested: dispatching the request is the one way to make the badge
+     * claim a permission the gate will not honour.
+     */
+    const applyMode = (next, opts = {}) => {
+        const applied = controller.setAgentMode(next, opts.force ? { force: true } : {});
+        dispatch({ type: 'setAgentMode', mode: applied.effective, pending: applied.pending });
+        if (opts.silent)
+            return applied;
+        if (applied.pending) {
+            toast('info', `${MODE_LABEL[applied.pending]} mode applies after this run.`);
+        }
+        else {
+            toast('info', `${MODE_LABEL[applied.effective]} mode.`);
+        }
+        return applied;
+    };
     const makeCtx = (args) => ({
         args,
         controller,
@@ -269,6 +397,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         exit: doExit,
         submit: (text) => submitMessage(text),
         refreshSkills: () => setSkillsNonce((n) => n + 1),
+        applyAgentMode: applyMode,
     });
     const recordPrompt = (text) => {
         const next = [...promptHistory.filter((p) => p !== text), text].slice(-PROMPT_HISTORY_CAP);
@@ -280,8 +409,9 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         controller.setSubmitCount(nextCount);
         persistConfig({ promptHistory: next, submitCount: nextCount });
     };
-    const scrollBy = useCallback((kind) => {
-        setScrollIntent((prev) => ({ kind, nonce: (prev?.nonce ?? 0) + 1 }));
+    /** `repeat` folds a coalesced wheel burst; the keyboard always sends one. */
+    const scrollBy = useCallback((kind, repeat = 1) => {
+        setScrollIntent((prev) => ({ kind, nonce: (prev?.nonce ?? 0) + 1, repeat }));
     }, []);
     /**
      * Send a message to the agent, bypassing slash parsing.
@@ -322,8 +452,14 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         controller.setThinkingLevel(values.thinkingLevel);
         controller.setMaxTokens(maxTokens);
         const key = values.apiKey.trim();
-        if (key.length > 0)
+        if (key.length > 0) {
+            // Registration site 4 (§4.4.3), and the one that matters most: this is how
+            // a key most often enters the process, and it happens long after
+            // `installLogging()` ran. A startup snapshot would miss it entirely, and
+            // the vendor regexes only cover keys that look like a vendor's.
+            registerSecret(key);
             controller.setApiKey(values.provider, key);
+        }
         const patch = {
             provider: values.provider,
             model: values.model,
@@ -333,7 +469,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         };
         if (key.length > 0)
             patch.apiKeys = { [values.provider]: key };
+        // A PARTIAL `log` section, safe only because `updatePersistedConfig` deep-
+        // merges it — a shallow merge here would reset `redactSecrets` every time
+        // someone touched the level.
+        patch.log = { level: values.logLevel };
         persistConfig(patch);
+        getLogger().reconfigure({ ...controller.getConfig().log, level: values.logLevel });
         dispatch({ type: 'setOverlay', overlay: null });
         toast('success', 'Settings saved.');
     };
@@ -347,11 +488,52 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
         setConfirmState(null);
         dispatch({ type: 'setOverlay', overlay: null });
     };
+    /** Answer every outstanding request with the same response and close up. */
+    const resolveHuman = (response) => {
+        for (const entry of [...pendingHuman.current])
+            settleHuman(entry, response);
+    };
+    const handlePlanVerdict = (verdict) => {
+        if (verdict.decision === 'approved') {
+            // BEFORE resolving, not after. `submit_plan` also calls
+            // `setAgentMode('build', { force: true })` when its wait returns — that is
+            // the authoritative act, and it stays because it must work even if the App
+            // is gone by then. But it runs a microtask later, so reading the mode back
+            // here would read `'plan'` and the badge would lag by a frame. Writing it
+            // first through the same single path makes the tool's call an idempotent
+            // no-op and keeps the mirror exact (§3.1 / R-P7).
+            applyMode('build', { force: true, silent: true });
+            toast('success', 'Plan approved. Implementing.');
+        }
+        else {
+            toast('info', 'Revision requested.');
+        }
+        resolveHuman({ kind: 'planDecision', decision: verdict.decision, feedback: verdict.feedback });
+    };
+    // --- Mouse wheel region routing (§4.6). Table and coalescer live in the
+    // hook (D-13); only the wiring it cannot own stays here. Inline arrows are
+    // fine — the hook re-reads its options through a ref every render. The
+    // `Math.max(0, …)` mirrors the keyboard branch below, and for the same
+    // reason: `OverlayFrame` only ever reports a clamp DOWNWARD.
+    const { clearCoalescer } = useWheelRouting({
+        mouseSource,
+        geometryRef,
+        geometryOverride,
+        getOverlay: () => stateRef.current.overlay,
+        onScroll: scrollBy,
+        onOverlayScroll: (delta) => setOverlayScroll((n) => Math.max(0, n + delta)),
+        onHistoryStep: (dir) => setHistoryIntent((prev) => ({ dir, nonce: (prev?.nonce ?? 0) + 1 })),
+    });
     // A fresh overlay always opens at the top; carrying the previous overlay's
     // offset over would open Help mid-list for no reason the user can see.
+    //
+    // `clearCoalescer()` rides along here rather than adding a second subscriber
+    // to the same transition (§4.7 rule 2): an accumulated-but-unflushed
+    // transcript scroll must not survive an overlay opening.
     useEffect(() => {
         setOverlayScroll(0);
-    }, [state.overlay]);
+        clearCoalescer();
+    }, [state.overlay, clearCoalescer]);
     // --- Initial overlay / prompt (after handlers are defined). ------------
     useEffect(() => {
         if (initialOverlay)
@@ -390,7 +572,7 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             const overlay = stateRef.current.overlay;
             // Modes A only. `model` / `confirm` manage their own keys; registering an
             // arrow handler for them would double every keypress (R-12).
-            const controlled = overlay === 'help' || overlay === 'settings';
+            const controlled = overlay === 'help' || overlay === 'settings' || overlay === 'plan';
             if (key.pageUp) {
                 if (controlled)
                     setOverlayScroll((n) => Math.max(0, n - OVERLAY_PAGE));
@@ -402,12 +584,23 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
                 return;
             }
             // `settings` keeps Up/Down for field movement — a high-frequency action
-            // worth more than scrolling six fields (§4.9).
-            if (overlay === 'help' && (key.upArrow || key.downArrow)) {
+            // worth more than scrolling six fields (§4.9). `question` keeps them for
+            // its option cursor, for the same reason; `plan` has no cursor of its own
+            // and scrolls a line at a time.
+            if ((overlay === 'help' || overlay === 'plan') && (key.upArrow || key.downArrow)) {
                 setOverlayScroll((n) => Math.max(0, n + (key.upArrow ? -1 : 1)));
                 return;
             }
         }
+        // AFTER the overlay block, and with an EXPLICIT guard rather than relying on
+        // ordering: that block only `return`s for the keys it recognizes, and
+        // everything else falls through (AC-P2).
+        if (key.tab && key.shift) {
+            if (stateRef.current.overlay)
+                return;
+            applyMode(nextMode(controller.getAgentMode()));
+            return;
+        }
         if (key.ctrl && (input === 'l' || input === 'L')) {
             if (fullscreen) {
                 // Writing \x1B[2J here would erase the screen and then leave it blank:
@@ -462,6 +655,12 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
                     confirmRef.current.resolve(false);
                     setConfirmState(null);
                 }
+                // `App` owns Esc for both plan-mode overlays and they register no
+                // handler of their own, so this is the only place a cancellation
+                // reaches the waiting tool.
+                if (overlay === 'question' || overlay === 'plan')
+                    cancelPendingHuman();
+                setHumanRequest(null);
                 dispatch({ type: 'setOverlay', overlay: null });
                 return;
             }
@@ -494,7 +693,14 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
             thinkingLevel: cfg.thinkingLevel,
             maxTokens: cfg.maxTokens ? String(cfg.maxTokens) : '',
             apiKey: '',
-        }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onSave: handleSettingsSave })) : overlay === 'confirm' && confirmState ? (_jsx(ConfirmDialog, { state: confirmState, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onClose: closeConfirm })) : null;
+            logLevel: cfg.log.level,
+        }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onSave: handleSettingsSave })) : overlay === 'confirm' && confirmState ? (_jsx(ConfirmDialog, { state: confirmState, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onClose: closeConfirm })) : overlay === 'question' && humanRequest?.kind === 'questions' ? (_jsx(QuestionOverlay, { questions: humanRequest.questions, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onSubmit: (answers) => resolveHuman({ kind: 'answers', answers, cancelled: false }) })) : overlay === 'plan' && humanRequest?.kind === 'plan' ? (_jsx(PlanReviewOverlay, { plan: humanRequest.plan, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onVerdict: handlePlanVerdict })) : null;
+    // A MEASUREMENT MUST NEVER OUTLIVE THE FRAME IT DESCRIBED (P1-5): neither
+    // path below renders the full-screen `AppShell`, so nothing else would
+    // overwrite a stale `bottom`. See `UNMEASURED_GEOMETRY` for why there is no
+    // arithmetic fallback.
+    if (!fullscreen || rows < MIN_FULLSCREEN_ROWS)
+        geometryRef.current = UNMEASURED_GEOMETRY;
     // A resize can drop below the usable floor. Do NOT leave the alt-screen —
     // entering and leaving it on every drag is worse than a placeholder — and take
     // the height from `frameHeight()` like everything else, because this is the
@@ -512,11 +718,11 @@ export function App({ controller, version, mode, initialOverlay, initialPrompt,
     // the header the moment the first message lands.
     const opener = empty ? (_jsx(SessionOpener, { variant: fullscreen ? pickOpenerVariant(viewportBudget, cols, caps) : 'none', version: version, cwd: controller.getCwd(), hasKey: hasKey, viewportRows: fullscreen ? viewportBudget : Number.POSITIVE_INFINITY, theme: theme, caps: caps })) : null;
     const density = cfg.density;
-    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps, windowSize: cfg.transcriptWindow ?? DEFAULT_TRANSCRIPT_WINDOW })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps }), overlayNode] }));
+    const viewport = fullscreen ? (overlayNode ? (_jsx(Box, { flexDirection: "column", flexGrow: 1, overflow: "hidden", children: overlayNode })) : (_jsxs(ScrollViewport, { intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, showScrollIndicator: true, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps, windowSize: cfg.transcriptWindow ?? DEFAULT_TRANSCRIPT_WINDOW })] }))) : (_jsxs(_Fragment, { children: [opener, _jsx(Transcript, { entries: state.entries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: reducedMotion, density: density, theme: theme, caps: caps }), overlayNode] }));
     // The completion popup lives inside the bottom chrome and can add up to 9
     // rows; unbounded, it pushes the status bar past the frame height where
     // `overflow: hidden` clips it away (R-14 / M-14). Cap it against the viewport.
     const popupMaxRows = fullscreen ? Math.max(1, viewportBudget - 4) : undefined;
-    const composer = fullscreen ? (_jsx(Composer, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), showHint: rows >= HINT_MIN_ROWS, submitCount: cfg.submitCount, hintsEnabled: cfg.hints, popupMaxRows: popupMaxRows, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) })) : (_jsx(Box, { marginTop: 1, children: _jsx(PromptInput, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) }) }));
-    return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, header: header, viewport: viewport, toast: _jsx(ToastStack, { toasts: state.toasts, theme: theme, mode: mode }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce }) }));
+    const composer = fullscreen ? (_jsx(Composer, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), showHint: rows >= HINT_MIN_ROWS, submitCount: cfg.submitCount, hintsEnabled: cfg.hints, agentMode: state.agentMode, popupMaxRows: popupMaxRows, historyIntent: historyIntent, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) })) : (_jsx(Box, { marginTop: 1, children: _jsx(PromptInput, { isActive: overlay === null, running: state.status === 'running', history: promptHistory, commands: commandOptions, cwd: controller.getCwd(), agentMode: state.agentMode, theme: theme, caps: caps, onSubmit: (text) => void handleSubmit(text), onHelp: () => dispatch({ type: 'setOverlay', overlay: 'help' }) }) }));
+    return (_jsx(AppShell, { mode: mode, rows: rows, cols: cols, geometryRef: geometryRef, header: header, viewport: viewport, toast: _jsx(ToastStack, { toasts: state.toasts, theme: theme, mode: mode }), composer: composer, status: _jsx(StatusBar, { model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, contextTokens: state.contextTokens, contextWindow: modelInfo.contextWindow, contextWindowKnown: modelKnown, status: state.status, elapsedMs: elapsedMs, thinkingLevel: cfg.thinkingLevel, tokPerSec: tokPerSec, theme: theme, caps: caps, scrolledLines: scrolledLines, redrawNonce: redrawNonce, agentMode: state.agentMode, pendingAgentMode: state.pendingAgentMode }) }));
 }