@crouton-kit/humanloop 0.3.38 → 0.3.39

package/dist/inbox/completion.js

@@ -1,7 +1,6 @@
 import { readdirSync, statSync, unlinkSync } from 'node:fs';
-import { spawn } from 'node:child_process';
 import { basename, resolve } from 'node:path';
-import { atomicWriteJson, deliveryErrorPath, deliveryPath, responsePath, readJson, reviewPath, withExclusiveDirectoryLockAsync } from './convention.js';
+import { atomicWriteJson, deliveryErrorPath, deliveryPath, responsePath, readJson, reviewPath, runHandler, withExclusiveDirectoryLockAsync } from './convention.js';
 import { registeredInboxRoot } from './registry.js';
 import { readTicketResult, ticketRoot } from './tickets.js';
 import { validateReviewProjection } from './deck-schema.js';
@@ -12,31 +11,6 @@ function receiptMatches(dir) {
 function eventFor(root, dir, result) {
     return { schema: 'humanloop.completion/v1', root, dir, ticketId: basename(dir), kind: result.kind, outcome: result.kind === 'canceled' ? 'canceled' : 'resolved', responsePath: responsePath(dir) };
 }
-async function runHandler(command, args, event) {
-    await new Promise((resolvePromise, rejectPromise) => {
-        // stdout stays ignored (a handler acknowledges by exit code, never stdout),
-        // but stderr is captured so a nonzero exit surfaces the handler's own
-        // diagnostics in the delivery-error record instead of a bare exit code.
-        const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'pipe'] });
-        let stderr = '';
-        child.stderr?.on('data', (chunk) => { stderr += chunk; if (stderr.length > 8192)
-            stderr = stderr.slice(-8192); });
-        let timedOut = false;
-        const timeout = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 30_000);
-        child.once('error', (error) => { clearTimeout(timeout); rejectPromise(error); });
-        child.once('exit', (code, signal) => {
-            clearTimeout(timeout);
-            const detail = stderr.trim() === '' ? '' : `: ${stderr.trim()}`;
-            if (timedOut)
-                rejectPromise(new Error(`completion handler timed out after 30 seconds${detail}`));
-            else if (code === 0)
-                resolvePromise();
-            else
-                rejectPromise(new Error(`completion handler failed (${signal ?? code ?? 'unknown'})${detail}`));
-        });
-        child.stdin.end(`${JSON.stringify(event)}\n`);
-    });
-}
 function projectReview(dir, result) {
     if (result.kind !== 'review')
         return;

package/dist/inbox/controller.d.ts

@@ -1,6 +1,7 @@
 import type { InteractionResponse, TicketSummary } from '../types.js';
 import type { Key } from '../tui/terminal.js';
 import { startWebServer } from '../browser/server.js';
+import { visualGeneratorForConversationSession } from '../visuals/conversation.js';
 export interface InboxControllerOptions {
     roots?: string[];
     cols?: number;
@@ -9,6 +10,8 @@ export interface InboxControllerOptions {
     completeDeck?: (dir: string, responses: InteractionResponse[], token: string) => Promise<unknown>;
     startDeckBrowser?: typeof startWebServer;
     openBrowser?: (url: string) => void;
+    /** Test seam; production uses the standard conversation-backed visual generator. */
+    visualGeneratorForSession?: typeof visualGeneratorForConversationSession;
 }
 type Screen = 'list' | 'detail';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
@@ -19,11 +22,21 @@ export declare class InboxController {
     private items;
     private selectedDir;
     private selectedIndex;
+    /** Scroll state belongs to the passive preview, never to an editable deck. */
+    private previewScrollOffset;
     private screen;
     private adapter;
+    private activeDeck;
     private reviewAdapter;
     private deckBrowser;
+    /** Blocks terminal input until browser finalization/shutdown is quiescent. */
+    private deckBrowserTakingBack;
+    /** The single accepted submit that crossed the browser boundary. */
+    private deckBrowserFinalizing;
     private deckBrowserStarting;
+    private deckBrowserStartingGeneration;
+    /** Invalidates an in-flight asynchronous browser start when ownership ends. */
+    private deckBrowserGeneration;
     private claim;
     private reconciling;
     private suspended;
@@ -56,16 +69,24 @@ export declare class InboxController {
      *  in ReviewAdapter; the controller only owns the terminal handoff. */
     private activateReview;
     reloadSelectedDeck(): void;
+    private followUpHandlers;
+    private readDeck;
+    private followUpViewState;
+    private refreshFollowUp;
     /** Hand the selected deck to its browser surface while retaining this ticket's claim. */
     private openDeckBrowser;
-    /** The browser has atomically published the response; reconcile its owner delivery. */
+    /** Finalize through this controller's claim-safe lifecycle before HTTP acks. */
+    private finalizeDeckBrowser;
+    /** The browser has finalized through the controller; reconcile its owner delivery. */
     private finishDeckBrowser;
     /** Return browser authority to the terminal deck without changing its draft. */
     private takeBackDeckBrowser;
     close(): void;
     run(): Promise<void>;
     private complete;
-    /** Give the raw TTY to a child process (native review editor). */
+    /** The controller owns the terminal handoff and repaint around $EDITOR. */
+    private editActiveDeckInput;
+    /** Give the raw TTY to a child process (native review editor or $EDITOR). */
     private suspendForChild;
     /** Retake the TTY after the child exits and force a full repaint. */
     private resumeAfterChild;
@@ -75,8 +96,11 @@ export declare class InboxController {
     private reconcileRoots;
     private leaveDetail;
     private select;
+    private scrollPreview;
     private detailSize;
     private detailLines;
+    private passiveDetailLines;
+    private previewViewport;
     private withStatus;
     private repaint;
     private watchRoots;

package/dist/inbox/controller.js

@@ -9,13 +9,17 @@ 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 } from './convention.js';
 import { DeckAdapter } from './deck-adapter.js';
+import { validateDeck } from './deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
+import { visualGeneratorForConversationSession } from '../visuals/conversation.js';
+import { editBufferInEditor } from '../editor/roundtrip.js';
+import { cancelFollowUp, readFollowUp, requestFollowUp } from './followup.js';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
 export class InboxController {
     options;
@@ -24,11 +28,21 @@ 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;
     suspended = false;
@@ -79,10 +93,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 +112,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 +142,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 +165,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);
@@ -175,10 +203,10 @@ export class InboxController {
             this.invalidate();
             return;
         }
-        if (item.interactionKind === 'notify') {
-            void this.complete([{ id: deck.interactions[0]?.id ?? 'notify', selectedOptionId: deck.interactions[0]?.options[0]?.id }]);
-            return;
-        }
+        // 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 +214,16 @@ export class InboxController {
             cols: this.detailSize().cols,
             rows: this.detailSize().rows,
             onDirty: () => this.repaint(),
+            generateVisual: deck.source?.originatingConversationSessionId === undefined ? undefined : (this.options.visualGeneratorForSession ?? visualGeneratorForConversationSession)(deck.source.originatingConversationSessionId),
+            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 +269,72 @@ 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);
+        this.adapter.reload(deck);
+        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 +346,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 +424,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,6 +454,9 @@ 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;
@@ -365,7 +528,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)
@@ -407,8 +589,13 @@ export class InboxController {
         })();
     }
     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.activeDeck = undefined;
         this.selectedWatcher?.close();
         this.selectedWatcher = undefined;
         if (release && this.claim !== undefined)
@@ -419,9 +606,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 +627,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 +656,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 +675,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 +744,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 +763,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'; }

package/dist/inbox/convention.d.ts

@@ -6,9 +6,16 @@ export declare function progressPath(dir: string): string;
 export declare function claimPath(dir: string): string;
 export declare function deliveryPath(dir: string): string;
 export declare function deliveryErrorPath(dir: string): string;
+export declare function followupRequestPath(dir: string): string;
+export declare function followupResultPath(dir: string): string;
 export declare function visualsDir(dir: string): string;
 export declare function visualMdPath(dir: string, id: string): string;
 export declare function visualAnsiPath(dir: string, id: string): string;
+/** Spawns a handler `{command,args}` with `event` as JSON on stdin. Exit 0
+ *  acknowledges; a nonzero exit, spawn error, or 30s timeout rejects with an
+ *  Error carrying the handler's captured stderr. Shared by completion delivery
+ *  and follow-up dispatch — both invoke a registered handler the same way. */
+export declare function runHandler(command: string, args: string[], event: unknown): Promise<void>;
 export type InteractionState = 'pending' | 'claimed' | 'resolved' | 'missing';
 export declare function interactionState(dir: string): InteractionState;
 export declare function isResolved(dir: string): boolean;

package/dist/inbox/convention.js

@@ -1,4 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
 import { dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { buildSummary } from '../summary.js';
@@ -9,9 +10,40 @@ export function progressPath(dir) { return `${dir}/progress.json`; }
 export function claimPath(dir) { return `${dir}/claim.json`; }
 export function deliveryPath(dir) { return `${dir}/delivery.json`; }
 export function deliveryErrorPath(dir) { return `${dir}/delivery-error.json`; }
+export function followupRequestPath(dir) { return `${dir}/followup-request.json`; }
+export function followupResultPath(dir) { return `${dir}/followup-result.json`; }
 export function visualsDir(dir) { return `${dir}/visuals`; }
 export function visualMdPath(dir, id) { return `${dir}/visuals/${id}.md`; }
 export function visualAnsiPath(dir, id) { return `${dir}/visuals/${id}.ansi`; }
+/** Spawns a handler `{command,args}` with `event` as JSON on stdin. Exit 0
+ *  acknowledges; a nonzero exit, spawn error, or 30s timeout rejects with an
+ *  Error carrying the handler's captured stderr. Shared by completion delivery
+ *  and follow-up dispatch — both invoke a registered handler the same way. */
+export async function runHandler(command, args, event) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        // stdout stays ignored (a handler acknowledges by exit code, never stdout),
+        // but stderr is captured so a nonzero exit surfaces the handler's own
+        // diagnostics in the delivery-error record instead of a bare exit code.
+        const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { stderr += chunk; if (stderr.length > 8192)
+            stderr = stderr.slice(-8192); });
+        let timedOut = false;
+        const timeout = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 30_000);
+        child.once('error', (error) => { clearTimeout(timeout); rejectPromise(error); });
+        child.once('exit', (code, signal) => {
+            clearTimeout(timeout);
+            const detail = stderr.trim() === '' ? '' : `: ${stderr.trim()}`;
+            if (timedOut)
+                rejectPromise(new Error(`handler timed out after 30 seconds${detail}`));
+            else if (code === 0)
+                resolvePromise();
+            else
+                rejectPromise(new Error(`handler failed (${signal ?? code ?? 'unknown'})${detail}`));
+        });
+        child.stdin.end(`${JSON.stringify(event)}\n`);
+    });
+}
 export function interactionState(dir) {
     if (!existsSync(deckPath(dir)) && !existsSync(reviewPath(dir)))
         return 'missing';