@crouton-kit/humanloop 0.3.38 → 0.4.0

package/dist/inbox/controller.js

@@ -1,4 +1,5 @@
 import { readFileSync, watch } from 'node:fs';
+import { join } from 'node:path';
 import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
 import { diffFrame } from '../tui/render.js';
 import { renderMarkdown } from '../render/termrender.js';
@@ -9,13 +10,72 @@ import { BOLD, CYAN, DIM, GRAY, RESET, YELLOW, clipLine } from '../tui/ansi.js';
 import { buildInboxLines } from './tui.js';
 import { inboxLayout } from './layout.js';
 import { scanInbox } from './scan.js';
-import { inboxRootsDirectory, listInboxRoots } from './registry.js';
+import { inboxRootsDirectory, listInboxRoots, registeredInboxRoot } from './registry.js';
 import { claimTicket, heartbeatClaim, releaseClaim } from './claim.js';
-import { completeDeck, readTicketResult } from './tickets.js';
+import { completeDeck, readTicketResult, ticketRoot } from './tickets.js';
 import { reconcileCompletions } from './completion.js';
-import { clearProgress, deckPath, progressPath, readJson, reviewPath } from './convention.js';
+import { clearProgress, deckPath, progressPath, readJson, responsePath, reviewPath, visualsDir } from './convention.js';
 import { DeckAdapter } from './deck-adapter.js';
+import { validateDeck } from './deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
+import { editBufferInEditor } from '../editor/roundtrip.js';
+import { cancelFollowUp, readFollowUp, requestFollowUp } from './followup.js';
+import { cancelVisualRequest, dispatchVisualCleanup, listVisualCleanupObligationsForRoot, readVisualResult, reconcileStaleVisualRequestsForRoot, reconcileVisualRequestsForTicket, startVisualRequest, VISUAL_CAPABILITY, } from './visual.js';
+/** One controller-owned retry loop for durable cancellation only. */
+class VisualCleanupExecutor {
+    roots;
+    timer;
+    dispatching = new Set();
+    stopped = false;
+    constructor(roots) {
+        this.roots = roots;
+    }
+    reconcile() {
+        if (this.stopped)
+            return;
+        let tasks = [];
+        for (const root of this.roots()) {
+            try {
+                tasks.push(...listVisualCleanupObligationsForRoot(root));
+            }
+            catch { /* the next root reconciliation retries durable work */ }
+        }
+        tasks = tasks.filter((task) => !this.dispatching.has(this.key(task)));
+        const now = Date.now();
+        for (const task of tasks.filter((candidate) => Date.parse(candidate.nextAttemptAt) <= now))
+            this.dispatch(task);
+        this.arm(tasks.filter((task) => !this.dispatching.has(this.key(task))));
+    }
+    stop() {
+        this.stopped = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    dispatch(task) {
+        const key = this.key(task);
+        if (this.dispatching.has(key))
+            return;
+        this.dispatching.add(key);
+        void dispatchVisualCleanup(task.root, task.dir, task.requestId).catch(() => undefined).finally(() => {
+            this.dispatching.delete(key);
+            this.reconcile();
+        });
+    }
+    arm(tasks) {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        const earliest = tasks.reduce((next, task) => {
+            const due = Date.parse(task.nextAttemptAt);
+            return Number.isFinite(due) && (next === undefined || due < next) ? due : next;
+        }, undefined);
+        if (earliest === undefined)
+            return;
+        this.timer = setTimeout(() => { this.timer = undefined; this.reconcile(); }, Math.max(0, earliest - Date.now()));
+    }
+    key(task) { return `${task.root}\u0000${task.dir}\u0000${task.requestId}`; }
+}
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
 export class InboxController {
     options;
@@ -24,13 +84,25 @@ export class InboxController {
     items = [];
     selectedDir;
     selectedIndex = 0;
+    /** Scroll state belongs to the passive preview, never to an editable deck. */
+    previewScrollOffset = 0;
     screen = 'list';
     adapter;
+    activeDeck;
     reviewAdapter;
     deckBrowser;
+    /** Blocks terminal input until browser finalization/shutdown is quiescent. */
+    deckBrowserTakingBack = false;
+    /** The single accepted submit that crossed the browser boundary. */
+    deckBrowserFinalizing;
     deckBrowserStarting = false;
+    deckBrowserStartingGeneration;
+    /** Invalidates an in-flight asynchronous browser start when ownership ends. */
+    deckBrowserGeneration = 0;
     claim;
     reconciling = false;
+    visualReconciling = false;
+    visualCleanupExecutor;
     suspended = false;
     submittingDir;
     stdinListener;
@@ -50,7 +122,9 @@ export class InboxController {
         const size = getTerminalSize();
         this.cols = options.cols ?? size.cols;
         this.rows = options.rows ?? size.rows;
+        this.visualCleanupExecutor = new VisualCleanupExecutor(() => this.resolvedRoots());
         this.rescan();
+        this.reconcileVisualWork();
     }
     snapshot() {
         return { items: [...this.items], selectedDir: this.selectedDir, screen: this.screen, inputBuffer: this.adapter?.inputBuffer() };
@@ -79,10 +153,12 @@ export class InboxController {
         if (this.items.length === 0) {
             this.selectedIndex = 0;
             this.selectedDir = undefined;
+            this.previewScrollOffset = 0;
             return;
         }
         this.selectedIndex = Math.min(priorIndex, this.items.length - 1);
         this.selectedDir = this.items[this.selectedIndex].dir;
+        this.previewScrollOffset = 0;
     }
     invalidate() { this.rescan(); this.repaint(); }
     resize(cols = getTerminalSize().cols, rows = getTerminalSize().rows) {
@@ -96,7 +172,7 @@ export class InboxController {
         const geometry = inboxLayout(this.cols, this.rows, this.screen);
         if (geometry.mode === 'minimum')
             return [`${YELLOW}Resize terminal to at least 60×18 to use inbox.${RESET}`];
-        const list = buildInboxLines(this.items, geometry.listWidth, this.selectedIndex);
+        const list = buildInboxLines(this.items, geometry.listWidth, this.selectedIndex, geometry.height);
         const detail = this.detailLines(geometry.detailWidth, geometry.height);
         if (geometry.mode === 'list')
             return this.withStatus(list);
@@ -126,6 +202,11 @@ export class InboxController {
             this.close();
             return;
         }
+        // Take-back is an ownership boundary, not an instantaneous UI toggle:
+        // discard every key until a pre-existing browser finalizer and the listener
+        // have both settled, so terminal edits cannot race browser completion.
+        if (this.deckBrowserTakingBack)
+            return;
         if (this.deckBrowser !== undefined) {
             if (input === 'w' || input === 'W')
                 void this.takeBackDeckBrowser();
@@ -144,7 +225,14 @@ export class InboxController {
             this.close();
             return;
         }
-        if (input === 'j' || key.downArrow)
+        // Passive previews share the deck's documented scroll bindings without
+        // claiming or mounting an editable panel. Ctrl+E/Y are line-wise aliases;
+        // u/d and Ctrl+U/D/Page keys move a useful chunk.
+        if (input === 'd' || key.pageDown || (key.ctrl && (input === 'd' || input === 'e')))
+            this.scrollPreview(input === 'e' ? 1 : 10);
+        else if (input === 'u' || key.pageUp || (key.ctrl && (input === 'u' || input === 'y')))
+            this.scrollPreview(input === 'y' ? -1 : -10);
+        else if (input === 'j' || key.downArrow)
             this.select(this.selectedIndex + 1);
         else if (input === 'k' || key.upArrow)
             this.select(this.selectedIndex - 1);
@@ -168,17 +256,24 @@ export class InboxController {
             return;
         }
         this.claim = { dir: item.dir, token: claim.token };
-        const deck = readJson(deckPath(item.dir));
-        if (deck === null) {
+        const deck = this.readDeck(item.dir);
+        if (deck === undefined) {
             releaseClaim(item.dir, claim.token);
             this.claim = undefined;
             this.invalidate();
             return;
         }
-        if (item.interactionKind === 'notify') {
-            void this.complete([{ id: deck.interactions[0]?.id ?? 'notify', selectedOptionId: deck.interactions[0]?.options[0]?.id }]);
-            return;
+        const root = ticketRoot(item.dir);
+        if (root !== null) {
+            // A newly acquired claim makes every older running generation stale
+            // before the panel can mint its own work. This only dispatches cleanup.
+            const retirement = reconcileVisualRequestsForTicket(root, item.dir, claim.token);
+            void retirement.delivery.finally(() => this.visualCleanupExecutor.reconcile());
         }
+        // Notifications use the same canonical deck panel as every other deck:
+        // opening is not acknowledgement; panel completion is.
+        this.activeDeck = deck;
+        const followUp = this.followUpHandlers(item.dir, deck);
         this.screen = 'detail';
         this.adapter = new DeckAdapter({
             dir: item.dir,
@@ -186,9 +281,16 @@ export class InboxController {
             cols: this.detailSize().cols,
             rows: this.detailSize().rows,
             onDirty: () => this.repaint(),
+            visualProvider: this.visualProviderFor(item.dir, deck, claim.token),
+            onEditorRequest: () => this.editActiveDeckInput(),
+            followUpAvailable: followUp.available,
+            onFollowUpRequest: followUp.onRequest,
+            onFollowUpCancel: followUp.onCancel,
             onBack: () => { this.leaveDetail(); this.repaint(); },
             onComplete: (responses) => { void this.complete(responses); },
         });
+        if (followUp.available)
+            this.adapter.setFollowUpState(this.followUpViewState(item.dir));
         this.watchSelected(item.dir);
     }
     /** Claim the review, hand the whole popup TTY to the native editor, then
@@ -234,7 +336,73 @@ export class InboxController {
             }
         }
     }
-    reloadSelectedDeck() { this.adapter?.reload(); this.repaint(); }
+    reloadSelectedDeck() {
+        if (this.adapter === undefined || this.claim === undefined) {
+            this.repaint();
+            return;
+        }
+        const deck = this.readDeck(this.claim.dir);
+        if (deck === undefined) {
+            this.repaint();
+            return;
+        }
+        this.activeDeck = deck;
+        const followUp = this.followUpHandlers(this.claim.dir, deck);
+        this.adapter.setFollowUpHandlers(followUp.available, followUp.onRequest, followUp.onCancel);
+        // Reload replaces the capability before it mints the next panel generation.
+        this.adapter.reload(deck, this.visualProviderFor(this.claim.dir, deck, this.claim.token));
+        if (followUp.available)
+            this.adapter.setFollowUpState(this.followUpViewState(this.claim.dir));
+        this.repaint();
+    }
+    followUpHandlers(dir, deck) {
+        const root = ticketRoot(dir);
+        const available = root !== null && registeredInboxRoot(root)?.followUpHandler !== undefined && isAnswerBearingDeck(deck);
+        if (!available)
+            return { available: false };
+        return {
+            available: true,
+            onRequest: (question) => {
+                requestFollowUp(root, dir, { question });
+                this.refreshFollowUp(dir);
+            },
+            onCancel: () => {
+                cancelFollowUp(root, dir);
+                this.refreshFollowUp(dir);
+            },
+        };
+    }
+    readDeck(dir) {
+        const deck = readJson(deckPath(dir));
+        if (deck === null)
+            return undefined;
+        try {
+            return validateDeck(deck);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    followUpViewState(dir) {
+        const { request, result } = readFollowUp(dir);
+        if (request === null)
+            return { status: 'idle' };
+        if (result !== null && result.requestId === request.requestId) {
+            return result.status === 'ready'
+                ? { status: 'ready', markdown: result.markdown }
+                : { status: 'error', error: result.error };
+        }
+        return request.state === 'running' ? { status: 'running' } : { status: 'idle' };
+    }
+    refreshFollowUp(dir) {
+        if (this.adapter === undefined || this.claim?.dir !== dir || this.activeDeck === undefined)
+            return;
+        const followUp = this.followUpHandlers(dir, this.activeDeck);
+        this.adapter.setFollowUpHandlers(followUp.available, followUp.onRequest, followUp.onCancel);
+        if (followUp.available)
+            this.adapter.setFollowUpState(this.followUpViewState(dir));
+        this.repaint();
+    }
     /** Hand the selected deck to its browser surface while retaining this ticket's claim. */
     async openDeckBrowser() {
         if (this.deckBrowser !== undefined || this.deckBrowserStarting || this.adapter === undefined || this.claim === undefined)
@@ -246,26 +414,71 @@ export class InboxController {
         if (deck === null)
             return;
         this.deckBrowserStarting = true;
+        const generation = ++this.deckBrowserGeneration;
+        this.deckBrowserStartingGeneration = generation;
+        const claim = this.claim;
+        const adapter = this.adapter;
         try {
             const start = this.options.startDeckBrowser ?? startWebServer;
             let browser;
             browser = await start({
                 dir: item.dir,
                 deck,
-                onSubmit: () => { void this.finishDeckBrowser(item.dir, browser); },
+                finalize: async (responses) => this.finalizeDeckBrowser(item.dir, claim.token, generation, responses),
+                onSubmit: () => this.finishDeckBrowser(item.dir, browser),
             });
+            // Closing, taking back, or losing the claim while listen() was pending
+            // retires this start. Stop the fresh listener before it can open a tab.
+            if (this.closed || generation !== this.deckBrowserGeneration || this.claim?.token !== claim.token || this.adapter !== adapter) {
+                await browser.stop();
+                return;
+            }
             this.deckBrowser = browser;
             (this.options.openBrowser ?? openBrowser)(browser.url);
         }
         catch (error) {
-            this.status = error instanceof Error ? error.message : String(error);
+            if (!this.closed && generation === this.deckBrowserGeneration)
+                this.status = error instanceof Error ? error.message : String(error);
         }
         finally {
-            this.deckBrowserStarting = false;
+            if (this.deckBrowserStartingGeneration === generation) {
+                this.deckBrowserStarting = false;
+                this.deckBrowserStartingGeneration = undefined;
+            }
             this.repaint();
         }
     }
-    /** The browser has atomically published the response; reconcile its owner delivery. */
+    /** Finalize through this controller's claim-safe lifecycle before HTTP acks. */
+    async finalizeDeckBrowser(dir, token, generation, responses) {
+        // The generation advances synchronously at take-back's ownership boundary.
+        // A request that reaches the listener after that point must fail before it
+        // can write, even while stop() is still closing HTTP connections.
+        if (this.deckBrowserTakingBack || generation !== this.deckBrowserGeneration || this.claim?.dir !== dir || this.claim.token !== token) {
+            throw new Error('browser handoff no longer owns this ticket');
+        }
+        // The server's HTTP single-assignment marker is published after its
+        // finalizer resolves, so simultaneous tabs can both reach us first. Share
+        // the first finalizer rather than starting another write or replacing the
+        // promise take-back must wait on.
+        if (this.deckBrowserFinalizing !== undefined)
+            return this.deckBrowserFinalizing;
+        const finalizing = (async () => {
+            await this.finishDeck(dir, responses, token);
+            const result = readTicketResult(dir);
+            if (result?.kind !== 'deck')
+                throw new Error('ticket did not produce a deck result');
+            return { completedAt: result.completedAt, responsePath: responsePath(dir) };
+        })();
+        this.deckBrowserFinalizing = finalizing;
+        try {
+            return await finalizing;
+        }
+        finally {
+            if (this.deckBrowserFinalizing === finalizing)
+                this.deckBrowserFinalizing = undefined;
+        }
+    }
+    /** The browser has finalized through the controller; reconcile its owner delivery. */
     async finishDeckBrowser(dir, browser) {
         if (this.deckBrowser === browser)
             this.deckBrowser = undefined;
@@ -279,14 +492,29 @@ export class InboxController {
     /** Return browser authority to the terminal deck without changing its draft. */
     async takeBackDeckBrowser() {
         const browser = this.deckBrowser;
-        if (browser === undefined)
+        if (browser === undefined || this.deckBrowserTakingBack)
             return;
-        this.deckBrowser = undefined;
+        // Invalidate newly-arriving browser submits before awaiting anything. Keep
+        // the handoff mounted and terminal input blocked until its running submit
+        // (if any) has conclusively won or failed and the listener is gone.
+        this.deckBrowserTakingBack = true;
+        this.deckBrowserGeneration++;
         try {
+            // A request that crossed the server boundary before this ownership change
+            // must own its normal finish path: it includes the HTTP 200 flush and
+            // onSubmit convergence before it stops the listener. Do not force-close
+            // that response after merely observing controller persistence.
+            const lifecycle = browser.pendingSubmitLifecycle?.();
+            if (lifecycle !== undefined && await lifecycle.catch(() => false))
+                return;
             await browser.requestTakeBack();
             await browser.stop();
         }
         finally {
+            if (this.deckBrowser === browser)
+                this.deckBrowser = undefined;
+            this.deckBrowserTakingBack = false;
+            this.rescan();
             this.repaint(true);
         }
     }
@@ -294,11 +522,15 @@ export class InboxController {
         if (this.closed)
             return;
         this.closed = true;
+        this.deckBrowserGeneration++;
+        this.deckBrowserTakingBack = false;
+        this.deckBrowserStarting = false;
         void this.reviewAdapter?.stop();
         const browser = this.deckBrowser;
         this.deckBrowser = undefined;
         void browser?.stop();
         this.leaveDetail();
+        this.visualCleanupExecutor.stop();
         for (const watcher of this.watchers)
             watcher.close();
         this.watchers = [];
@@ -365,7 +597,26 @@ export class InboxController {
         this.reconcileRoots();
         this.repaint();
     }
-    /** Give the raw TTY to a child process (native review editor). */
+    /** The controller owns the terminal handoff and repaint around $EDITOR. */
+    editActiveDeckInput() {
+        const buffer = this.adapter?.inputBuffer();
+        if (buffer === undefined)
+            return;
+        this.suspendForChild();
+        let result = { text: buffer };
+        try {
+            result = editBufferInEditor(buffer);
+        }
+        finally {
+            this.resumeAfterChild();
+            this.adapter?.setInputBuffer(result.text);
+            this.resize();
+            if (result.error !== undefined)
+                this.status = result.error;
+            this.repaint(true);
+        }
+    }
+    /** Give the raw TTY to a child process (native review editor or $EDITOR). */
     suspendForChild() {
         this.suspended = true;
         if (this.stdinListener !== undefined)
@@ -405,10 +656,107 @@ export class InboxController {
                 this.reconciling = false;
             }
         })();
+        this.reconcileVisualWork();
+    }
+    /** Reconciliation owns stale-claim retirement and durable cleanup, never a Visual start. */
+    reconcileVisualWork() {
+        if (this.visualReconciling)
+            return;
+        this.visualReconciling = true;
+        const roots = this.resolvedRoots();
+        void (async () => {
+            try {
+                const deliveries = roots.flatMap((root) => {
+                    try {
+                        return reconcileStaleVisualRequestsForRoot(root).map((entry) => entry.delivery);
+                    }
+                    catch {
+                        return [];
+                    }
+                });
+                await Promise.all(deliveries);
+            }
+            finally {
+                this.visualReconciling = false;
+                this.visualCleanupExecutor.reconcile();
+            }
+        })();
+    }
+    /** Automatic ticket capability is deliberately marker + current-root-handler only. */
+    visualProviderFor(dir, deck, claimToken) {
+        // An inline provider is intentional host injection, independent of ticket capability.
+        if (this.options.visualProvider !== undefined)
+            return this.options.visualProvider;
+        const root = ticketRoot(dir);
+        if (root === null || deck.source?.visual !== VISUAL_CAPABILITY || registeredInboxRoot(root)?.visualHandler === undefined)
+            return undefined;
+        return (request) => this.startTicketVisual(root, dir, claimToken, request);
+    }
+    startTicketVisual(root, dir, claimToken, request) {
+        let watcher;
+        let settled = false;
+        let settle;
+        const result = new Promise((resolve) => { settle = resolve; });
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            watcher?.close();
+            watcher = undefined;
+            settle(outcome);
+        };
+        let started;
+        try {
+            started = startVisualRequest({ root, dir, claimToken, request });
+        }
+        catch (error) {
+            finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+            return { result, cancel: () => { } };
+        }
+        const reread = () => {
+            if (settled)
+                return;
+            try {
+                const outcome = readVisualResult(root, dir, request.requestId);
+                if (outcome === null)
+                    return;
+                finish(outcome.status === 'ready'
+                    ? { status: 'ready', markdown: outcome.markdown }
+                    : { status: 'error', error: outcome.error });
+            }
+            catch (error) {
+                finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+            }
+        };
+        try {
+            // Install the watch before the first durable reread so a publication in
+            // the narrow setup window is either observed or found by that reread.
+            watcher = watch(join(visualsDir(dir), request.requestId), () => reread());
+            watcher.once('error', (error) => finish({ status: 'error', error: error.message }));
+            reread();
+        }
+        catch (error) {
+            finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
+        }
+        void started.delivery.then(reread, (error) => finish({ status: 'error', error: error instanceof Error ? error.message : String(error) }));
+        return {
+            result,
+            cancel: () => {
+                watcher?.close();
+                watcher = undefined;
+                void cancelVisualRequest(root, dir, request.requestId).finally(() => this.visualCleanupExecutor.reconcile());
+            },
+        };
     }
     leaveDetail(release = true) {
+        this.deckBrowserGeneration++;
+        // A stale listener will stop itself after its await, but this controller
+        // may immediately claim another ticket and start a fresh browser handoff.
+        this.deckBrowserStarting = false;
         this.adapter?.close();
         this.adapter = undefined;
+        this.visualCleanupExecutor.reconcile();
+        this.activeDeck = undefined;
         this.selectedWatcher?.close();
         this.selectedWatcher = undefined;
         if (release && this.claim !== undefined)
@@ -419,9 +767,15 @@ export class InboxController {
     select(index) {
         if (this.items.length === 0)
             return;
-        this.selectedIndex = Math.max(0, Math.min(index, this.items.length - 1));
+        const next = Math.max(0, Math.min(index, this.items.length - 1));
+        if (next !== this.selectedIndex)
+            this.previewScrollOffset = 0;
+        this.selectedIndex = next;
         this.selectedDir = this.items[this.selectedIndex].dir;
     }
+    scrollPreview(delta) {
+        this.previewScrollOffset = Math.max(0, this.previewScrollOffset + delta);
+    }
     detailSize() {
         const layout = inboxLayout(this.cols, this.rows, this.screen);
         return { cols: Math.max(1, layout.detailWidth - 2), rows: layout.height };
@@ -434,6 +788,15 @@ export class InboxController {
         if (this.adapter !== undefined)
             return this.adapter.render();
         const selected = this.items[this.selectedIndex];
+        if (selected === undefined)
+            return this.previewViewport(this.passiveDetailLines(width), width, rows);
+        const footer = selected.kind === 'deck'
+            ? [`  ${DIM}Enter${RESET} opens the full ticket  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}Active ask:${RESET} c comment  u/d scroll  w browser  ${DIM}q${RESET} close`]
+            : [`  ${DIM}Enter${RESET} opens the full review  ${DIM}u/d${RESET} scroll  ${DIM}j/k${RESET} select`, `  ${DIM}q${RESET} close`];
+        return [...this.previewViewport(this.passiveDetailLines(width), width, Math.max(0, rows - footer.length)), ...footer.map((line) => clipLine(line, width))];
+    }
+    passiveDetailLines(width) {
+        const selected = this.items[this.selectedIndex];
         if (selected === undefined)
             return [`  ${DIM}Select a pending interaction.${RESET}`];
         const lines = [`  ${BOLD}${CYAN}${selected.title}${RESET}`, '', `  ${DIM}${selected.kind} · ${sourceLabel(selected.source)}${RESET}`];
@@ -454,18 +817,18 @@ export class InboxController {
             else
                 for (const rendered of renderMarkdown(md, Math.max(1, width - 2)))
                     lines.push(`  ${rendered}`);
-            lines.push('', `  ${DIM}Enter${RESET} start review  ${DIM}j/k${RESET} select  ${DIM}q${RESET} close`);
-            while (lines.length < rows)
-                lines.push('');
-            // Rendered markdown carries ANSI; slicing by column count would sever
-            // escape sequences, so review preview lines are returned unsliced.
-            return lines;
         }
-        if (selected.kind === 'deck') {
+        else {
             const deck = readJson(deckPath(selected.dir));
             if (deck !== null) {
                 for (const interaction of deck.interactions) {
                     lines.push('', `  ${BOLD}${interaction.title}${RESET}`);
+                    if (interaction.subtitle)
+                        for (const rendered of renderMarkdown(interaction.subtitle, Math.max(1, width - 2)))
+                            lines.push(`  ${rendered}`);
+                    if (interaction.body)
+                        for (const rendered of renderMarkdown(interaction.body, Math.max(1, width - 2)))
+                            lines.push(`  ${rendered}`);
                     for (const option of interaction.options)
                         lines.push(`    ${DIM}• ${option.label}${RESET}`);
                 }
@@ -473,12 +836,33 @@ export class InboxController {
                 lines.push('', `  ${DIM}${Array.isArray(saved) ? saved.length : 0} saved responses${RESET}`);
             }
         }
-        if (selected.subtitle)
-            lines.push('', `  ${selected.subtitle}`);
-        lines.push('', `  ${DIM}Enter${RESET} open  ${DIM}j/k${RESET} select  ${DIM}q${RESET} close`);
-        while (lines.length < rows)
-            lines.push('');
-        return lines.map((line) => line.slice(0, width));
+        return lines.map((line) => clipLine(line, width));
+    }
+    previewViewport(lines, width, rows) {
+        if (rows < 1)
+            return [];
+        const maxOffset = Math.max(0, lines.length - Math.max(1, rows - 1));
+        this.previewScrollOffset = Math.min(this.previewScrollOffset, maxOffset);
+        const start = this.previewScrollOffset;
+        const hasAbove = start > 0;
+        // Reserve an indicator row before selecting content so a remaining tail is
+        // always signalled instead of silently disappearing below the viewport.
+        let contentRows = rows - (hasAbove ? 1 : 0);
+        let end = Math.min(lines.length, start + contentRows);
+        const hasBelow = end < lines.length;
+        if (hasBelow) {
+            contentRows--;
+            end = Math.min(lines.length, start + Math.max(0, contentRows));
+        }
+        const out = [];
+        if (hasAbove)
+            out.push(`  ${DIM}↑ more above${RESET}`);
+        out.push(...lines.slice(start, end));
+        if (hasBelow)
+            out.push(`  ${DIM}↓ more below${RESET}`);
+        while (out.length < rows)
+            out.push('');
+        return out.map((line) => clipLine(line, width));
     }
     withStatus(lines) {
         if (this.status === undefined || this.rows < 1)
@@ -521,10 +905,15 @@ export class InboxController {
         this.selectedWatcher?.close();
         try {
             this.selectedWatcher = watch(dir, (_event, file) => {
-                if (file === 'deck.json')
+                if (file === 'deck.json') {
                     this.reloadSelectedDeck();
-                else
-                    this.invalidate();
+                    return;
+                }
+                if (file === 'followup-result.json' || file === 'followup-request.json') {
+                    this.refreshFollowUp(dir);
+                    return;
+                }
+                this.invalidate();
             });
         }
         catch {
@@ -535,6 +924,9 @@ export class InboxController {
 function visibleWidth(line) { return line.replace(/\x1b\[[0-9;]*m/g, '').length; }
 /** M-i (Option/Alt+I) reaches the controller as the two-byte ESC-i sequence. */
 function isToggleCloseChord(input) { return input === '\x1bi' || input === '\x1bI'; }
+function isAnswerBearingDeck(deck) {
+    return deck.interactions.some((interaction) => interaction.kind !== 'notify');
+}
 /** Prefer a human-meaningful source label, falling back to the raw node id
  *  before an opaque "unknown source" — a crouter ticket always carries nodeId. */
 function sourceLabel(source) { return source.sessionName ?? source.askedBy ?? source.nodeId ?? 'unknown source'; }