@crouton-kit/humanloop 0.3.34 → 0.3.36

package/dist/cli.js

@@ -8,7 +8,7 @@ import { managedInboxRoot, registerInboxRoot, registeredInboxRoot, unregisterInb
 import { submitDeck, submitReview } from './inbox/tickets.js';
 import { scanInbox } from './inbox/scan.js';
 import { openInboxPopup } from './surfaces/inbox-popup.js';
-import { installInboxBinding, inspectInboxBinding, toggleInboxPopup, unbindInboxBinding } from './tui/tmux.js';
+import { toggleInboxPopup } from './tui/tmux.js';
 import { ask } from './api.js';
 import { launchReview } from './editor/review.js';
 import { writeFeedbackResult } from './editor/feedback.js';
@@ -34,7 +34,8 @@ function fail(error) {
     emit({ error: 'bad_input', message, next: `Run ${help} for usage.` });
     process.exit(1);
 }
-function roots(values) { return values?.map((root) => resolve(root)); }
+/** Explicit --root values filter the scan; no --root (an empty array from commander) falls through to the registered-roots fallback in scanInbox/the controller, so it must be undefined, not []. */
+function roots(values) { return values && values.length > 0 ? values.map((root) => resolve(root)) : undefined; }
 /** Resolve an explicit --root to its existing registration; an unregistered root is an error, never a silent humanloop-owned registration. */
 function requireRegisteredRoot(root) {
     const abs = resolve(root);
@@ -49,11 +50,26 @@ const inbox = program.command('inbox').description('Open, inspect, and configure
 inbox.command('open').description('Open the inbox controller in this human TTY.').option('--root <path>', 'filter to a registered root', (value, prior) => [...prior, value], []).option('--control-socket <path>', 'popup control socket').action(async (options) => {
     if (!process.stdin.isTTY || !process.stdout.isTTY)
         fail('hl inbox open requires an interactive TTY; use hl inbox list for read-only output');
-    await openInboxPopup(options.controlSocket, roots(options.root));
+    try {
+        await openInboxPopup(options.controlSocket, roots(options.root));
+    }
+    catch (error) {
+        fail(error);
+    }
+    // This process IS the popup: `tmux display-popup -E` keeps the popup on screen
+    // until it exits. Once the controller has closed, exit hard — a stray live
+    // handle (e.g. an in-flight completion-handler child that hangs) must never
+    // keep a dismissed inbox occupying the terminal. Delivery is receipt-based
+    // and crash-safe, so cutting an unfinished handler here is always safe.
+    process.exit(0);
 });
-inbox.command('toggle').description('Toggle the inbox popup for one tmux client.').option('--tmux-socket <path>').option('--tmux-client <name>').option('--target-pane <pane>').action(async (options) => {
+inbox.command('toggle').description('Toggle the inbox popup for one tmux client.').option('--tmux-socket <path>').option('--tmux-client <name>').option('--target-pane <pane>').option('--quiet', 'suppress result JSON on success (the tmux binding uses this so run-shell -b output never overlays the pane)').action(async (options) => {
     const result = await toggleInboxPopup({ socket: options.tmuxSocket, client: options.tmuxClient, targetPane: options.targetPane });
-    emit({ result, next: result === 'not_in_tmux' ? 'Run hl inbox open in a human terminal.' : undefined });
+    // Under the `run-shell -b` binding, any stdout becomes a tmux view-mode overlay on the active
+    // pane. The opened/closed popup is its own feedback, so stay silent on every non-failure result;
+    // a genuine `failed` still prints so a broken binding is not invisible.
+    if (!options.quiet || result === 'failed')
+        emit({ result, next: result === 'not_in_tmux' ? 'Run hl inbox open in a human terminal.' : undefined });
     process.exit(result === 'failed' || result === 'ambiguous_client' ? 1 : 0);
 });
 inbox.command('list').description('Print pending tickets newest first as JSON.').option('--root <path>', 'filter to a root', (value, prior) => [...prior, value], []).action((options) => emit(scanInbox(roots(options.root))));
@@ -65,9 +81,6 @@ root.command('register').description('Register a root owned by a host.').require
 });
 root.command('unregister').description('Remove a matching root registration without deleting tickets.').requiredOption('--root <path>').requiredOption('--owner <owner>').action((options) => emit({ removed: unregisterInboxRoot(resolve(options.root), options.owner) }));
 root.command('list').description('List registered roots and availability.').action(() => emit(listInboxRoots()));
-inbox.command('bind').description('Install a collision-safe tmux inbox toggle binding.').option('--key <tmux-key>').action((options) => emit(installInboxBinding({ key: options.key })));
-inbox.command('unbind').description('Remove the configured inbox binding only when it is humanloop-owned.').action(() => emit(unbindInboxBinding()));
-inbox.command('binding').description('Inspect the configured inbox binding.').action(() => emit(inspectInboxBinding()));
 program.command('deck').command('ask').description('Submit a durable deck ticket; it never changes tmux. --inline blocks in this terminal instead.').option('--root <path>').option('--inline', 'present the deck in this terminal and block until it is answered').action(async (options) => {
     try {
         const body = objectInput();

package/dist/editor/review.d.ts

@@ -6,6 +6,10 @@ export interface ReviewOptions {
     editor?: string;
     /** Called exactly once when the human explicitly submits a final proposal. */
     onPropose?: (result: FeedbackResult) => Promise<void> | void;
+    /** Fired when the human presses Option/Alt+I inside the editor: a request to
+     *  gracefully close the WHOLE inbox (not submit, not return-to-list). The
+     *  draft is saved and the ticket stays pending. */
+    onClose?: () => Promise<void> | void;
     /** Controller cancellation closes the editor/browser handoff without proposing a result. */
     signal?: AbortSignal;
     /** Reuse this controller-owned directory for `review.vim`; an existing script is left untouched. */

package/dist/editor/review.js

@@ -309,6 +309,17 @@ export function reviewVimscript() {
         `  qa!`,
         `endfunction`,
         ``,
+        `" Option/Alt+I: request graceful close of the whole inbox. Saves the draft`,
+        `" (ticket stays PENDING — this is close, never submit) and quits nvim; the`,
+        `" controller reads the close flag on editor exit and dismisses the popup.`,
+        `function! s:Close() abort`,
+        `  call s:Save()`,
+        `  if $HL_CLOSE_FLAG !=# ''`,
+        `    call writefile([''], $HL_CLOSE_FLAG)`,
+        `  endif`,
+        `  qa!`,
+        `endfunction`,
+        ``,
         `function! s:HandOff() abort`,
         `  call s:Save()`,
         `  if g:hl_handoff_flag ==# ''`,
@@ -324,7 +335,13 @@ export function reviewVimscript() {
         `command! HLUndo call <SID>Undo()`,
         `command! HLSubmit call <SID>Submit()`,
         `command! HLBrowser call <SID>HandOff()`,
-        `command! HLHelp echo 'REVIEW  <Space>c comment   <Space>l list   <Space>u undo-last   <Space>s submit & quit   <Space>w browser handoff   |  in list: e/<CR> edit · dd delete · q close'`,
+        `command! HLClose call <SID>Close()`,
+        `" M-i (Option/Alt+I) closes the whole inbox from any mode, mirroring the`,
+        `" controller's list/deck close chord. Global (not buffer-local) so it fires`,
+        `" from the source buffer, the comment scratch buffer, and the list.`,
+        `nnoremap <silent> <M-i> :call <SID>Close()<CR>`,
+        `inoremap <silent> <M-i> <C-\\><C-o>:call <SID>Close()<CR>`,
+        `command! HLHelp echo 'REVIEW  <Space>c comment   <Space>l list   <Space>u undo-last   <Space>s submit & quit   <Space>w browser handoff   M-i close inbox   |  in list: e/<CR> edit · dd delete · q close'`,
         ``,
         `" Highlights are (re)applied after any colorscheme so the user's theme`,
         `" (e.g. gloam) loads first, then our anchor highlight sits on top.`,
@@ -601,6 +618,7 @@ export async function launchReview(file, opts) {
         writeFileSync(initPath, reviewVimscript());
     const handoffFlagPath = join(dir, 'browser-handoff.flag');
     const submitFlagPath = join(dir, 'review-submit.flag');
+    const closeFlagPath = join(dir, 'review-close.flag');
     // `-u NONE`: do NOT load the user's init.lua / LazyVim / plugins / keymaps.
     // Default runtimepath still includes the config dir (for the gloam
     // colorscheme) and the site dir (for the treesitter markdown parser), so the
@@ -614,6 +632,7 @@ export async function launchReview(file, opts) {
             HL_REVIEW_URL: reviewUrl,
             HL_HANDOFF_FLAG: handoffFlagPath,
             HL_SUBMIT_FLAG: submitFlagPath,
+            HL_CLOSE_FLAG: closeFlagPath,
         };
         process.stderr.write(`\nhumanloop: opening "${absFile}" for review in ${bin}.\n` +
             `  Draft   : ${outPath}\n` +
@@ -625,6 +644,7 @@ export async function launchReview(file, opts) {
     while (true) {
         clearFlag(handoffFlagPath);
         clearFlag(submitFlagPath);
+        clearFlag(closeFlagPath);
         let resolveSubmitted;
         const submitted = new Promise((resolveSubmittedPromise) => {
             resolveSubmitted = resolveSubmittedPromise;
@@ -644,6 +664,15 @@ export async function launchReview(file, opts) {
         }
         try {
             await runEditor(server.url);
+            // Option/Alt+I close request wins over every other exit outcome: save the
+            // draft, leave the ticket pending, and tell the controller to dismiss the
+            // whole inbox. Checked before handoff/submit so it is never misread.
+            if (existsSync(closeFlagPath)) {
+                await stopReviewServer(server);
+                clearFlag(closeFlagPath);
+                await opts.onClose?.();
+                return draftFeedback(outPath, absFile);
+            }
             if (existsSync(handoffFlagPath)) {
                 server.activate();
                 process.stderr.write(`humanloop: browser review handoff active — ${server.url}\n`);

package/dist/inbox/completion.js

@@ -14,18 +14,25 @@ function eventFor(root, dir, result) {
 }
 async function runHandler(command, args, event) {
     await new Promise((resolvePromise, rejectPromise) => {
-        const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+        // 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'));
+                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'})`));
+                rejectPromise(new Error(`completion handler failed (${signal ?? code ?? 'unknown'})${detail}`));
         });
         child.stdin.end(`${JSON.stringify(event)}\n`);
     });

package/dist/inbox/controller.d.ts

@@ -18,7 +18,12 @@ export declare class InboxController {
     private selectedIndex;
     private screen;
     private adapter;
+    private reviewAdapter;
     private claim;
+    private reconciling;
+    private suspended;
+    private submittingDir;
+    private stdinListener;
     private cols;
     private rows;
     private frame;
@@ -41,10 +46,22 @@ export declare class InboxController {
     render(): string[];
     handleKey(input: string, key: Key): void;
     activate(): void;
+    /** Claim the review, hand the whole popup TTY to the native editor, then
+     *  converge to the on-disk outcome when it exits. Draft/final ownership stays
+     *  in ReviewAdapter; the controller only owns the terminal handoff. */
+    private activateReview;
     reloadSelectedDeck(): void;
     close(): void;
     run(): Promise<void>;
     private complete;
+    /** Give the raw TTY to a child process (native review editor). */
+    private suspendForChild;
+    /** Retake the TTY after the child exits and force a full repaint. */
+    private resumeAfterChild;
+    private resolvedRoots;
+    /** Owner-boundary reconciliation for resolved results still lacking an ack.
+     *  Guarded so overlapping fs events cannot stack concurrent scans. */
+    private reconcileRoots;
     private leaveDetail;
     private select;
     private detailSize;

package/dist/inbox/controller.js

@@ -1,15 +1,18 @@
-import { watch } from 'node:fs';
+import { readFileSync, watch } from 'node:fs';
 import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
 import { diffFrame } from '../tui/render.js';
-import { BOLD, CYAN, DIM, RESET, YELLOW } from '../tui/ansi.js';
+import { renderMarkdown } from '../render/termrender.js';
+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 { claimTicket, heartbeatClaim, releaseClaim } from './claim.js';
 import { completeDeck, readTicketResult } from './tickets.js';
-import { clearProgress, deckPath, progressPath, readJson } from './convention.js';
+import { reconcileCompletions } from './completion.js';
+import { clearProgress, deckPath, progressPath, readJson, reviewPath } from './convention.js';
 import { DeckAdapter } from './deck-adapter.js';
+import { ReviewAdapter } from './review-adapter.js';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
 export class InboxController {
     options;
@@ -20,7 +23,12 @@ export class InboxController {
     selectedIndex = 0;
     screen = 'list';
     adapter;
+    reviewAdapter;
     claim;
+    reconciling = false;
+    suspended = false;
+    submittingDir;
+    stdinListener;
     cols;
     rows;
     frame = [];
@@ -56,7 +64,11 @@ export class InboxController {
             const canceled = readTicketResult(priorDir)?.kind === 'canceled';
             if (canceled)
                 clearProgress(priorDir);
-            this.status = canceled ? 'canceled by requester' : 'ticket resolved elsewhere';
+            // Suppress the "resolved elsewhere" banner when WE are the ones resolving
+            // this ticket: the response.json we just published trips the root watch
+            // mid-submit, and that is our own completion, not an external event.
+            if (priorDir !== this.submittingDir)
+                this.status = canceled ? 'canceled by requester' : 'ticket resolved elsewhere';
             this.leaveDetail();
         }
         if (this.items.length === 0) {
@@ -86,15 +98,26 @@ export class InboxController {
         if (geometry.mode === 'detail')
             return this.withStatus(detail);
         const lines = [];
+        // Dim box-drawing rule in the single-column gutter the layout reserves
+        // (detailWidth = cols - listWidth - 1) so the list and detail read as two
+        // distinct panels rather than one run-together block.
+        const divider = `${GRAY}│${RESET}`;
         for (let i = 0; i < geometry.height; i++) {
-            const left = list[i] ?? '';
+            // Hard-clip the list line to its column: an overflowing row would eat
+            // the pad and push the divider out of alignment for that row alone.
+            const left = clipLine(list[i] ?? '', geometry.listWidth);
             const right = detail[i] ?? '';
-            lines.push(`${left}${' '.repeat(Math.max(1, geometry.listWidth - visibleWidth(left)))} ${right}`);
+            const pad = ' '.repeat(Math.max(0, geometry.listWidth - visibleWidth(left)));
+            lines.push(`${left}${pad}${divider}${right}`);
         }
         return this.withStatus(lines);
     }
     handleKey(input, key) {
-        if (key.ctrl && input === 'c') {
+        // Option/Alt+I (M-i) and Ctrl-C request graceful close from ANY controller
+        // mode. A root-table binding cannot fire while the popup grabs client input,
+        // so the close-from-open path must live here — checked before adapter
+        // forwarding so it works in active deck freetext as well as the list.
+        if ((key.ctrl && input === 'c') || isToggleCloseChord(input)) {
             this.close();
             return;
         }
@@ -117,7 +140,13 @@ export class InboxController {
     }
     activate() {
         const item = this.items[this.selectedIndex];
-        if (item === undefined || item.kind !== 'deck')
+        if (item === undefined)
+            return;
+        if (item.kind === 'review') {
+            void this.activateReview(item);
+            return;
+        }
+        if (item.kind !== 'deck')
             return;
         const claim = claimTicket(item.dir);
         if (claim === null) {
@@ -148,11 +177,55 @@ export class InboxController {
         });
         this.watchSelected(item.dir);
     }
+    /** Claim the review, hand the whole popup TTY to the native editor, then
+     *  converge to the on-disk outcome when it exits. Draft/final ownership stays
+     *  in ReviewAdapter; the controller only owns the terminal handoff. */
+    async activateReview(item) {
+        const claim = claimTicket(item.dir);
+        if (claim === null) {
+            this.status = 'ticket is being edited by another inbox';
+            this.repaint();
+            return;
+        }
+        const descriptor = readJson(reviewPath(item.dir));
+        if (descriptor === null) {
+            releaseClaim(item.dir, claim.token);
+            this.invalidate();
+            return;
+        }
+        let closeRequested = false;
+        this.reviewAdapter = new ReviewAdapter({ dir: item.dir, descriptor, claim, onClose: () => { closeRequested = true; } });
+        this.suspendForChild();
+        try {
+            await this.reviewAdapter.start();
+        }
+        catch (error) {
+            this.status = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.reviewAdapter = undefined;
+            // M-i inside native review is a graceful close of the WHOLE inbox: the
+            // adapter already saved the draft and released the claim, so just tear the
+            // controller down instead of returning to the list. The ticket stays
+            // pending because no submit flag was written.
+            if (closeRequested) {
+                this.suspended = false;
+                this.close();
+            }
+            else {
+                this.resumeAfterChild();
+                this.rescan();
+                this.reconcileRoots();
+                this.repaint(true);
+            }
+        }
+    }
     reloadSelectedDeck() { this.adapter?.reload(); this.repaint(); }
     close() {
         if (this.closed)
             return;
         this.closed = true;
+        void this.reviewAdapter?.stop();
         this.leaveDetail();
         for (const watcher of this.watchers)
             watcher.close();
@@ -165,6 +238,9 @@ export class InboxController {
         setupTerminal();
         this.running = true;
         this.watchRoots();
+        // Close the crash window between an earlier result publication and its
+        // handler launch: dispatch every resolved-but-undelivered ticket now.
+        this.reconcileRoots();
         this.repaint(true);
         const heartbeat = setInterval(() => {
             if (this.claim !== undefined)
@@ -177,6 +253,7 @@ export class InboxController {
                 if (this.closed)
                     finish();
             };
+            this.stdinListener = onData;
             const onResize = () => this.resize();
             let done = false;
             this.finishRun = () => {
@@ -184,6 +261,7 @@ export class InboxController {
                     return;
                 done = true;
                 process.stdin.removeListener('data', onData);
+                this.stdinListener = undefined;
                 process.stdout.removeListener('resize', onResize);
                 clearInterval(heartbeat);
                 this.running = false;
@@ -200,17 +278,62 @@ export class InboxController {
         const claim = this.claim;
         if (claim === undefined)
             return;
+        this.submittingDir = claim.dir;
         try {
             await this.finishDeck(claim.dir, responses, claim.token);
         }
         catch (error) {
+            this.submittingDir = undefined;
             this.status = error instanceof Error ? error.message : String(error);
             return;
         }
+        this.submittingDir = undefined;
         this.leaveDetail(false);
         this.rescan();
+        this.reconcileRoots();
         this.repaint();
     }
+    /** Give the raw TTY to a child process (native review editor). */
+    suspendForChild() {
+        this.suspended = true;
+        if (this.stdinListener !== undefined)
+            process.stdin.removeListener('data', this.stdinListener);
+        restoreTerminal();
+    }
+    /** Retake the TTY after the child exits and force a full repaint. */
+    resumeAfterChild() {
+        this.suspended = false;
+        if (this.closed)
+            return;
+        setupTerminal();
+        if (this.stdinListener !== undefined)
+            process.stdin.on('data', this.stdinListener);
+        this.frame = [];
+    }
+    resolvedRoots() {
+        return this.options.roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
+    }
+    /** Owner-boundary reconciliation for resolved results still lacking an ack.
+     *  Guarded so overlapping fs events cannot stack concurrent scans. */
+    reconcileRoots() {
+        if (this.reconciling)
+            return;
+        this.reconciling = true;
+        const roots = this.resolvedRoots();
+        void (async () => {
+            try {
+                for (const root of roots) {
+                    try {
+                        await reconcileCompletions(root);
+                    }
+                    catch { /* undelivered stays for the next pass */ }
+                }
+            }
+            finally {
+                this.reconciling = false;
+            }
+        })();
+    }
     leaveDetail(release = true) {
         this.adapter?.close();
         this.adapter = undefined;
@@ -237,7 +360,31 @@ export class InboxController {
         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} · ${selected.source.sessionName ?? selected.source.askedBy ?? 'unknown source'}${RESET}`];
+        const lines = [`  ${BOLD}${CYAN}${selected.title}${RESET}`, '', `  ${DIM}${selected.kind} · ${sourceLabel(selected.source)}${RESET}`];
+        if (selected.kind === 'review') {
+            lines.push('', `  ${DIM}${selected.file}${RESET}`);
+            const draft = readJson(progressPath(selected.dir))?.comments;
+            const draftCount = Array.isArray(draft) ? draft.length : 0;
+            lines.push(`  ${DIM}${draftCount} draft comment${draftCount === 1 ? '' : 's'}${RESET}`, '');
+            let md = '';
+            try {
+                md = readFileSync(selected.file, 'utf8');
+            }
+            catch {
+                md = '';
+            }
+            if (md === '')
+                lines.push(`  ${DIM}(source file unavailable)${RESET}`);
+            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') {
             const deck = readJson(deckPath(selected.dir));
             if (deck !== null) {
@@ -267,7 +414,9 @@ export class InboxController {
         return next;
     }
     repaint(clear = false) {
-        if (this.closed || !this.running)
+        // While a child owns the TTY (native review), fs-watch invalidations must
+        // not scribble the inbox frame over the editor's screen.
+        if (this.closed || !this.running || this.suspended)
             return;
         if (clear)
             process.stdout.write('\x1b[2J\x1b[H');
@@ -279,10 +428,9 @@ export class InboxController {
         this.frame = diff.nextPrevFrame;
     }
     watchRoots() {
-        const roots = this.options.roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
-        for (const root of roots) {
+        for (const root of this.resolvedRoots()) {
             try {
-                this.watchers.push(watch(root, () => this.invalidate()));
+                this.watchers.push(watch(root, () => { this.invalidate(); this.reconcileRoots(); }));
             }
             catch { /* unavailable roots remain discoverable through later rescans */ }
         }
@@ -309,3 +457,8 @@ 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'; }
+/** 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/review-adapter.d.ts

@@ -7,6 +7,8 @@ export interface ReviewAdapterOptions {
     claim: TicketClaim;
     editor?: ReviewOptions['editor'];
     onSubmitted?: (result: TicketResult) => Promise<void> | void;
+    /** Human pressed Option/Alt+I inside the editor: close the whole inbox. */
+    onClose?: () => Promise<void> | void;
 }
 /** Controller-owned native review child. It persists drafts but delegates the sole final write to tickets.ts. */
 export declare class ReviewAdapter {

package/dist/inbox/review-adapter.js

@@ -25,6 +25,7 @@ export class ReviewAdapter {
             jobDir: this.opts.dir,
             editor: this.opts.editor,
             signal: this.abortController.signal,
+            onClose: this.opts.onClose,
             onPropose: async (proposal) => {
                 if (this.stopped || this.abortController.signal.aborted)
                     return;

package/dist/inbox/tui.js

@@ -28,8 +28,13 @@ export function buildInboxLines(items, width, selectedIndex) {
         const item = items[index];
         const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
         const icon = KIND_ICON[kind] ?? '·';
-        const source = item.source.sessionName ?? item.source.askedBy ?? '';
+        // Source and title share the row budget: an unbounded source (a long node
+        // or session name) would floor the title at its minimum and overflow the
+        // column, bending the panel divider. Shrink the source only when the row
+        // cannot hold it alongside the title's 10-col minimum.
+        const rawSource = item.source.sessionName ?? item.source.askedBy ?? item.source.nodeId ?? '';
         const age = formatTimeAgo(item.blockedSince);
+        const source = truncateRow(rawSource, Math.max(8, contentWidth - age.length - 8 - 10));
         const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
         const titleWidth = Math.max(10, contentWidth - source.length - age.length - 8);
         let row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} `;
@@ -38,7 +43,7 @@ export function buildInboxLines(items, width, selectedIndex) {
         row += `${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
         lines.push(row);
         if (item.claim)
-            lines.push(`      ${DIM}claimed by ${item.claim.owner}${RESET}`);
+            lines.push(`      ${DIM}${truncateRow(`claimed by ${item.claim.owner}`, contentWidth - 6)}${RESET}`);
         else if (item.subtitle)
             lines.push(`      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`);
     }

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { launchReview as review } from './editor/review.js';
 export type { ReviewOptions } from './editor/review.js';
 export { ask, notify, openInbox } from './api.js';
 export { openInboxPopup } from './surfaces/inbox-popup.js';
-export { toggleInboxPopup, installInboxBinding, inspectInboxBinding, unbindInboxBinding, inboxPopupStyle } from './tui/tmux.js';
+export { toggleInboxPopup, inboxToggleTmuxCommand, inboxPopupStyle } from './tui/tmux.js';
 export { display } from './surfaces/display.js';
 export { scanInbox } from './inbox/scan.js';
 export { registerInboxRoot, unregisterInboxRoot, listInboxRoots, managedInboxRoot } from './inbox/registry.js';
@@ -21,6 +21,6 @@ export { notifyDeck } from './inbox/deck-factories.js';
 export type { NotifyDeckOpts } from './inbox/deck-factories.js';
 export { deckPath, reviewPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';
 export type { InteractionState } from './inbox/convention.js';
-export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, InboxBindingState, CompletionEvent, } from './types.js';
+export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, CompletionEvent, } from './types.js';
 export type { Key } from './tui/terminal.js';
 export type { ConversationMessage } from './conversation/reader.js';

package/dist/index.js

@@ -5,7 +5,7 @@ export { launchReview as review } from './editor/review.js';
 // Interaction-layer surface (SDK).
 export { ask, notify, openInbox } from './api.js';
 export { openInboxPopup } from './surfaces/inbox-popup.js';
-export { toggleInboxPopup, installInboxBinding, inspectInboxBinding, unbindInboxBinding, inboxPopupStyle } from './tui/tmux.js';
+export { toggleInboxPopup, inboxToggleTmuxCommand, inboxPopupStyle } from './tui/tmux.js';
 export { display } from './surfaces/display.js';
 export { scanInbox } from './inbox/scan.js';
 export { registerInboxRoot, unregisterInboxRoot, listInboxRoots, managedInboxRoot } from './inbox/registry.js';

package/dist/render/termrender.d.ts

@@ -1,15 +1,19 @@
 /**
- * Memoized, self-healing. Ensures the pinned termrender binary exists inside
- * the humanloop-managed venv; (re)provisions it via `uv` when missing or the
- * version drifts from the pin. Runs at most once per process. Single
- * degradation path: `uv` absent → one stderr remediation line + plaintext
- * fallback. win32 → plaintext (no renderer).
+ * Memoized, self-healing. Guarantees at most one authoritative renderer
+ * lifecycle per process: trust a valid stamp outright (zero subprocess spawns),
+ * else run ONE provision/verify/publish transition under the exclusive lock.
+ * There is no permanent legacy-verifier fallback — the spawn-based verify
+ * (`binaryOk` + `installedVersion`) is a step INSIDE that single transition,
+ * always followed by publishing the stamp, never a lasting alternate path.
+ *
+ * Single degradation path: `uv` absent → one stderr remediation line + plaintext.
+ * win32 → plaintext (no renderer).
  *
  * Invoked at postinstall AND lazily on the first render/check/display call,
  * so `npm ci --ignore-scripts` consumers still self-heal on first use.
  */
 export declare function ensureRenderer(): void;
-/** Cheap predicate — true when the pinned managed binary is present and correct. Does not install. */
+/** Cheap predicate — true when the pinned managed binary is verified ready. Does not install or spawn. */
 export declare function isRendererReady(): boolean;
 /** Render markdown to terminal lines via the pinned binary; plaintext fallback. */
 export declare function renderMarkdown(md: string, width: number): string[];

package/dist/render/termrender.js

@@ -1,5 +1,5 @@
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, statSync, openSync, closeSync, unlinkSync, renameSync, accessSync, realpathSync, constants, } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import stringWidth from 'string-width';
@@ -27,7 +27,246 @@ const PKG_ROOT = findPkgRoot();
 const VENV_DIR = resolve(PKG_ROOT, '.venv');
 const VENV_BIN = resolve(PKG_ROOT, '.venv/bin/termrender');
 const VENV_PYTHON = resolve(PKG_ROOT, '.venv/bin/python');
+// Readiness marker written by the single authoritative provisioning transition
+// after a verified install. It fingerprints the ACTUAL verified environment —
+// launcher + interpreter (mtime, size, mode) and the interpreter's realpath —
+// so steady-state validation is a handful of cheap fs stats (no subprocess),
+// yet a stripped exec bit, a swapped venv Python, or a rewritten launcher all
+// invalidate it. Deeper corruption an fs stat can't see (e.g. mangled
+// site-packages under an unchanged launcher) is caught by the other half of
+// the contract: any `ready` invocation that fails to RUN invalidates this
+// marker (see invalidateRenderer), so the next process repairs. Together these
+// remove the ~149ms `termrender -h` + `importlib.metadata` spawn tax from the
+// steady path without letting a stale marker trust a broken renderer forever.
+const VENV_STAMP = resolve(PKG_ROOT, '.venv/.hl-termrender-stamp.json');
+// Provisioning lock — lives OUTSIDE .venv (which `uv venv --clear` wipes) so it
+// survives a reinstall. Serializes venv mutation + stamp publication across
+// processes: a stamp can never certify a concurrently-changing venv.
+const VENV_LOCK = resolve(PKG_ROOT, '.hl-termrender.lock');
+// A lock older than this is from a crashed process and may be stolen. Set
+// comfortably above the worst-case held path (uv probe 5s + venv 60s + install
+// 120s + re-verify ~10s ≈ 195s) so a slow-but-alive holder is never judged
+// stale while it still holds.
+const LOCK_STALE_MS = 300_000;
+// Absolute cap on how long a waiter spins before giving up to plaintext for
+// this session (the next launch retries) — a safety valve so a wedged holder
+// can never hang a process, WITHOUT ever stealing a lock we can't prove stale.
+const LOCK_GIVE_UP_MS = LOCK_STALE_MS + 60_000;
 let rendererState = 'unchecked';
+function isFp(x) {
+    const e = x;
+    return !!e && typeof e.mtimeMs === 'number' && typeof e.size === 'number' && typeof e.mode === 'number';
+}
+function fingerprint(path) {
+    try {
+        const s = statSync(path);
+        return { mtimeMs: s.mtimeMs, size: s.size, mode: s.mode };
+    }
+    catch {
+        return null;
+    }
+}
+function fpMatch(a, b) {
+    return !!a && a.mtimeMs === b.mtimeMs && a.size === b.size && a.mode === b.mode;
+}
+function readStamp() {
+    try {
+        const p = JSON.parse(readFileSync(VENV_STAMP, 'utf8'));
+        if (p && typeof p.version === 'string' && isFp(p.bin) && isFp(p.python) && typeof p.pythonRealpath === 'string') {
+            return p;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// Publish the readiness marker for the state we just verified. Failure to
+// persist is surfaced explicitly (not swallowed): the renderer works for THIS
+// process, but every future launch re-verifies the slow way until the marker
+// can be written — the operator should know why launches stay slow.
+function publishStamp() {
+    const bin = fingerprint(VENV_BIN);
+    const python = fingerprint(VENV_PYTHON);
+    if (!bin || !python) {
+        process.stderr.write('[hl] termrender stamp skipped: venv files vanished immediately after verify\n');
+        return;
+    }
+    let pythonRealpath;
+    try {
+        pythonRealpath = realpathSync(VENV_PYTHON);
+    }
+    catch {
+        pythonRealpath = VENV_PYTHON;
+    }
+    const stamp = { version: TERMRENDER_VERSION, bin, python, pythonRealpath };
+    // Atomic publish: write a temp then rename, so a crash mid-write can't leave
+    // a half-written stamp and a concurrent reader never observes a torn file.
+    const tmp = `${VENV_STAMP}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(stamp));
+        renameSync(tmp, VENV_STAMP);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* nothing to clean up */ }
+        process.stderr.write(`[hl] termrender ready but stamp not persisted (${err instanceof Error ? err.message : String(err)}); ` +
+            'future launches will re-verify the slow way\n');
+    }
+}
+// Invalidate the readiness marker when a supposedly-ready renderer misbehaves
+// in a way that implicates the environment (spawn fault, or a `doc render`
+// failure — render is best-effort by contract, so ANY failure means the tool,
+// not the input, is broken; this catches site-packages corruption an fs stat
+// can't see). Removes the on-disk marker so the next process repairs, and
+// downgrades THIS process to plaintext to avoid retry thrash within the session.
+function invalidateRenderer(reason) {
+    let removed = true;
+    try {
+        unlinkSync(VENV_STAMP);
+    }
+    catch (err) {
+        // ENOENT means it's already gone (still invalidated); any other error means
+        // the marker SURVIVES and will keep certifying — say so honestly rather
+        // than promising a repair that can't happen until the file is removable.
+        if (err.code !== 'ENOENT')
+            removed = false;
+    }
+    rendererState = 'unavailable';
+    if (removed) {
+        process.stderr.write(`[hl] termrender invocation failed (${reason}); invalidated readiness, future launches will repair\n`);
+    }
+    else {
+        process.stderr.write(`[hl] termrender invocation failed (${reason}) but its readiness marker could not be removed; ` +
+            `future launches may keep trusting a broken renderer until ${VENV_STAMP} is deleted\n`);
+    }
+}
+// True when a spawn was killed by its own timeout rather than failing to run —
+// usually a slow/large document, not a broken environment. Excluded from
+// invalidation so a reliably-slow render can't oscillate a healthy renderer
+// (invalidate → slow re-verify → re-stamp) every session.
+function isTimeout(err) {
+    const e = err;
+    return e?.code === 'ETIMEDOUT' || (!!e?.killed && !!e?.signal);
+}
+// Cheap steady-state trust — all fs stats, no subprocess. The pinned launcher
+// is present, executable, and byte-for-byte the one the stamp verified; the
+// interpreter it targets is the same file at the same realpath. Any of these
+// drifting (version bump, stripped exec bit, rewritten launcher, swapped venv
+// Python) forces the authoritative re-provision transition.
+function stampValid() {
+    const stamp = readStamp();
+    if (!stamp || stamp.version !== TERMRENDER_VERSION)
+        return false;
+    try {
+        accessSync(VENV_BIN, constants.X_OK);
+    }
+    catch {
+        return false;
+    }
+    if (!fpMatch(fingerprint(VENV_BIN), stamp.bin))
+        return false;
+    if (!fpMatch(fingerprint(VENV_PYTHON), stamp.python))
+        return false;
+    try {
+        if (realpathSync(VENV_PYTHON) !== stamp.pythonRealpath)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function lockIsStale() {
+    try {
+        const at = JSON.parse(readFileSync(VENV_LOCK, 'utf8')).at;
+        if (typeof at === 'number')
+            return Date.now() - at > LOCK_STALE_MS;
+    }
+    catch {
+        // Unreadable/malformed lock — fall through to mtime.
+    }
+    try {
+        return Date.now() - statSync(VENV_LOCK).mtimeMs > LOCK_STALE_MS;
+    }
+    catch {
+        return true; // vanished — the retry loop re-acquires
+    }
+}
+// Run `provision` while holding the exclusive provisioning lock. If another
+// live process holds it, wait for that process to publish (re-checking the
+// stamp) rather than mutating the venv concurrently. Stale locks are stolen.
+// Steal a lock judged stale by renaming it to a unique name first: rename is
+// atomic, so if two waiters race only the one whose rename succeeds owns (and
+// deletes) it — the loser gets ENOENT and re-loops. This can never delete a
+// lock a peer has freshly re-acquired (that peer holds a DIFFERENT inode at the
+// same path; our rename of the old name either already happened or fails).
+function stealStaleLock() {
+    const tmp = `${VENV_LOCK}.steal.${process.pid}.${Date.now()}`;
+    try {
+        renameSync(VENV_LOCK, tmp);
+    }
+    catch {
+        return; // lost the steal race or already gone — caller re-loops
+    }
+    try {
+        unlinkSync(tmp);
+    }
+    catch { /* best effort */ }
+}
+function withProvisionLock(provision) {
+    const giveUpAt = Date.now() + LOCK_GIVE_UP_MS;
+    for (;;) {
+        let fd;
+        try {
+            fd = openSync(VENV_LOCK, 'wx'); // O_CREAT | O_EXCL — atomic acquire
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (lockIsStale()) {
+                stealStaleLock();
+                continue;
+            }
+            // A live process is provisioning — give it a chance, then adopt its result.
+            // Never steal a lock we can't prove stale; if we wait too long, give up to
+            // plaintext this session rather than break mutual exclusion.
+            if (Date.now() > giveUpAt) {
+                rendererState = 'unavailable';
+                return;
+            }
+            sleepSync(200);
+            if (stampValid()) {
+                rendererState = 'ready';
+                return;
+            }
+            continue;
+        }
+        try {
+            writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+        }
+        catch { /* lock held regardless of whether the marker body wrote */ }
+        try {
+            provision();
+        }
+        finally {
+            try {
+                closeSync(fd);
+            }
+            catch { /* already closed */ }
+            try {
+                unlinkSync(VENV_LOCK);
+            }
+            catch { /* stolen as stale by another process */ }
+        }
+        return;
+    }
+}
 function binaryOk() {
     if (!existsSync(VENV_BIN))
         return false;
@@ -70,11 +309,15 @@ function uvAvailable() {
     }
 }
 /**
- * Memoized, self-healing. Ensures the pinned termrender binary exists inside
- * the humanloop-managed venv; (re)provisions it via `uv` when missing or the
- * version drifts from the pin. Runs at most once per process. Single
- * degradation path: `uv` absent → one stderr remediation line + plaintext
- * fallback. win32 → plaintext (no renderer).
+ * Memoized, self-healing. Guarantees at most one authoritative renderer
+ * lifecycle per process: trust a valid stamp outright (zero subprocess spawns),
+ * else run ONE provision/verify/publish transition under the exclusive lock.
+ * There is no permanent legacy-verifier fallback — the spawn-based verify
+ * (`binaryOk` + `installedVersion`) is a step INSIDE that single transition,
+ * always followed by publishing the stamp, never a lasting alternate path.
+ *
+ * Single degradation path: `uv` absent → one stderr remediation line + plaintext.
+ * win32 → plaintext (no renderer).
  *
  * Invoked at postinstall AND lazily on the first render/check/display call,
  * so `npm ci --ignore-scripts` consumers still self-heal on first use.
@@ -86,45 +329,75 @@ export function ensureRenderer() {
         rendererState = 'unavailable';
         return;
     }
-    if (binaryOk() && installedVersion() === TERMRENDER_VERSION) {
+    // Steady state: trust the stamp — zero subprocess spawns.
+    if (stampValid()) {
         rendererState = 'ready';
         return;
     }
-    if (!uvAvailable()) {
-        process.stderr.write('[hl] termrender unavailable — install uv to enable rich rendering:\n' +
-            '  curl -LsSf https://astral.sh/uv/install.sh | sh\n');
-        rendererState = 'unavailable';
-        return;
-    }
-    try {
-        // (Re)create the venv whenever the interpreter is missing — covers both
-        // "directory absent" and "directory present but bin/python stripped"
-        // (seen in the wild when pnpm rebuilds/dedupes node_modules or uv rotates
-        // its managed Python store). `--clear` makes uv wipe any partial state
-        // rather than refusing on the existing dir. If the interpreter is intact,
-        // skip straight to `uv pip install` so version drift reuses the venv.
-        if (!existsSync(VENV_PYTHON)) {
-            execFileSync('uv', ['venv', '--clear', VENV_DIR], { stdio: 'pipe', timeout: 60000 });
+    // No/invalid stamp → the single authoritative transition, serialized so no
+    // two processes mutate the venv (or certify it) concurrently.
+    provisionAndPublish();
+}
+// The one invalid-stamp transition. Under the exclusive lock: adopt a stamp a
+// racing process just published; else verify the current venv (a healthy venv
+// with no/stale stamp — pre-stamp humanloop, interrupted publish, or a peer
+// that finished the venv but not the stamp — needs only re-verification, not a
+// reinstall); reinstall via `uv` only when genuinely missing/drifted; then
+// verify and publish. Every success path ends by publishing the stamp.
+function provisionAndPublish() {
+    withProvisionLock(() => {
+        // A peer may have published between our unlocked stampValid() in
+        // ensureRenderer and our acquiring the lock here — adopt it, don't reinstall.
+        if (stampValid()) {
+            rendererState = 'ready';
+            return;
         }
-        execFileSync('uv', ['pip', 'install', '--python', VENV_PYTHON, `termrender==${TERMRENDER_VERSION}`], { stdio: 'pipe', timeout: 120000 });
-    }
-    catch (err) {
-        process.stderr.write(`[hl] termrender install failed (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
-        rendererState = 'unavailable';
-        return;
-    }
-    rendererState = (binaryOk() && installedVersion() === TERMRENDER_VERSION) ? 'ready' : 'unavailable';
-    if (rendererState === 'unavailable') {
-        process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
-    }
+        let verified = binaryOk() && installedVersion() === TERMRENDER_VERSION;
+        if (!verified) {
+            if (!uvAvailable()) {
+                process.stderr.write('[hl] termrender unavailable — install uv to enable rich rendering:\n' +
+                    '  curl -LsSf https://astral.sh/uv/install.sh | sh\n');
+                rendererState = 'unavailable';
+                return;
+            }
+            try {
+                // (Re)create the venv whenever the interpreter is missing — covers both
+                // "directory absent" and "directory present but bin/python stripped"
+                // (seen when pnpm rebuilds/dedupes node_modules or uv rotates its
+                // managed Python store). `--clear` wipes any partial state rather than
+                // refusing on the existing dir. Intact interpreter → reuse the venv.
+                if (!existsSync(VENV_PYTHON)) {
+                    execFileSync('uv', ['venv', '--clear', VENV_DIR], { stdio: 'pipe', timeout: 60000 });
+                }
+                // `--reinstall` forces uv to rebuild the package and rewrite its entry
+                // point even when the pinned version already appears satisfied — so this
+                // path actually REPAIRS a corrupt-but-present install (the case that
+                // drove us here via invalidation), not just a clean version drift.
+                execFileSync('uv', ['pip', 'install', '--reinstall', '--python', VENV_PYTHON, `termrender==${TERMRENDER_VERSION}`], { stdio: 'pipe', timeout: 120000 });
+            }
+            catch (err) {
+                process.stderr.write(`[hl] termrender install failed (${err instanceof Error ? err.message : String(err)}); using plaintext fallback\n`);
+                rendererState = 'unavailable';
+                return;
+            }
+            verified = binaryOk() && installedVersion() === TERMRENDER_VERSION;
+        }
+        if (!verified) {
+            rendererState = 'unavailable';
+            process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
+            return;
+        }
+        publishStamp();
+        rendererState = 'ready';
+    });
 }
-/** Cheap predicate — true when the pinned managed binary is present and correct. Does not install. */
+/** Cheap predicate — true when the pinned managed binary is verified ready. Does not install or spawn. */
 export function isRendererReady() {
     if (rendererState === 'ready')
         return true;
     if (rendererState === 'unavailable')
         return false;
-    return process.platform !== 'win32' && binaryOk();
+    return process.platform !== 'win32' && stampValid();
 }
 // ── Plaintext fallback helpers (kept here so this is the only termrender site) ─
 const CONTROL_CHARS_RE = /\x1b\[[0-9;?]*[a-zA-Z]|\x1b[@-_]|[\x00-\x08\x0B\x0E-\x1F\x7F-\x9F]/g;
@@ -208,8 +481,12 @@ export function renderMarkdown(md, width) {
             _bodyCache.set(key, lines);
             return lines;
         }
-        catch {
-            /* fall through to plaintext */
+        catch (err) {
+            // `doc render` is best-effort, so a non-timeout failure implicates the
+            // tool, not the markdown: invalidate so the next process repairs. A
+            // timeout is a slow/large doc, not corruption — just fall to plaintext.
+            if (!isTimeout(err))
+                invalidateRenderer('doc render');
         }
     }
     const fallback = wrap(sanitize(md), width);
@@ -229,6 +506,11 @@ export function checkMarkdown(md) {
         timeout: 5000,
     });
     if (result.error) {
+        // A timeout (slow doc) is not an environment fault; anything else is a
+        // spawn fault → invalidate so the next process repairs.
+        const timedOut = result.error.code === 'ETIMEDOUT' || result.signal === 'SIGTERM';
+        if (!timedOut)
+            invalidateRenderer('doc check');
         return { ok: false, error: `termrender: invocation failed: ${result.error.message}` };
     }
     let parsed = null;
@@ -270,7 +552,13 @@ export function displayInPane(path, opts = {}) {
         encoding: 'utf-8',
         stdio: ['pipe', 'pipe', 'pipe'],
     });
-    if (result.error || result.status !== 0)
+    // A spawn fault (binary broke) invalidates readiness; a non-zero exit (e.g.
+    // tmux refused, bad path) is not an environment fault and must not.
+    if (result.error) {
+        invalidateRenderer('pane open');
+        return {};
+    }
+    if (result.status !== 0)
         return {};
     // `encoding: 'utf-8'` makes spawnSync return stdout as a string.
     const rawStdout = result.stdout;

package/dist/tui/tmux.d.ts

@@ -1,4 +1,3 @@
-import type { InboxBindingState } from '../types.js';
 export interface TmuxPopupTarget {
     socket: string;
     client: string;
@@ -9,12 +8,11 @@ export declare function popupPaths(target: TmuxPopupTarget): {
     controlSocket: string;
     startupLock: string;
 };
-export declare function inspectInboxBinding(socket?: string | undefined): InboxBindingState;
-export declare function installInboxBinding(opts?: {
-    socket?: string;
-    key?: string;
-}): InboxBindingState;
-export declare function unbindInboxBinding(socket?: string | undefined): InboxBindingState;
+/** The argv crouter's tmux-binding installer binds on the root table to toggle the inbox popup.
+ *  Humanloop owns the command text; crouter owns which key(s) run it (via its keybindings catalog
+ *  and the single `installTmuxBindings()` manifest sweep). Humanloop no longer persists or
+ *  reconciles any key itself. */
+export declare function inboxToggleTmuxCommand(): string[];
 export declare function tmuxSocketFromEnvironment(): string | undefined;
 export declare function inferTmuxClient(socket: string, pane?: string | undefined): string | undefined | 'ambiguous';
 export declare function toggleInboxPopup(target?: Partial<TmuxPopupTarget>): Promise<ToggleInboxPopupResult>;

package/dist/tui/tmux.js

@@ -1,10 +1,9 @@
 import { createHash } from 'node:crypto';
 import { execFileSync, spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-const DEFAULT_KEY = 'M-i';
 const POPUP_TITLE = 'humanloop · inbox';
 const POPUP_STYLE = 'bg=#20242d';
 const POPUP_BORDER_STYLE = 'fg=#5c6370';
@@ -22,70 +21,17 @@ function tmux(socket, args) {
 }
 function quote(value) { return `'${value.replace(/'/g, `'\\''`)}'`; }
 function bindingCommand() {
-    return 'hl inbox toggle --tmux-socket "#{socket_path}" --tmux-client "#{client_name}" --target-pane "#{pane_id}"';
-}
-function configuredKeyPath() {
-    const state = process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
-    return join(state, 'humanloop', 'inbox-key');
-}
-function configuredKey() {
-    try {
-        return readFileSync(configuredKeyPath(), 'utf8').trim() || DEFAULT_KEY;
-    }
-    catch {
-        return DEFAULT_KEY;
-    }
-}
-function writeConfiguredKey(key) {
-    mkdirSync(join(configuredKeyPath(), '..'), { recursive: true, mode: 0o700 });
-    writeFileSync(configuredKeyPath(), `${key}\n`, { mode: 0o600 });
-}
-function rootBinding(socket, key) {
-    try {
-        const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        const match = tmux(socket, ['list-keys', '-T', 'root']).split('\n').map((row) => new RegExp(`^bind-key\\s+-T root\\s+${escaped}\\s+(.*)$`).exec(row)).find((entry) => entry !== null);
-        return match?.[1];
-    }
-    catch {
-        return undefined;
-    }
-}
-function isCanonical(command) {
-    const normalized = command?.replace(/\\"/g, '"');
-    return normalized !== undefined && normalized.includes('hl inbox toggle') && normalized.includes('--tmux-socket "#{socket_path}"') && normalized.includes('--tmux-client "#{client_name}"') && normalized.includes('--target-pane "#{pane_id}"');
-}
-export function inspectInboxBinding(socket = tmuxSocketFromEnvironment()) {
-    const key = configuredKey();
-    if (socket === undefined)
-        return { state: 'unbound', key, isDefault: key === DEFAULT_KEY };
-    const command = rootBinding(socket, key);
-    return { state: command === undefined ? 'unbound' : isCanonical(command) ? 'installed' : 'collision', key, isDefault: key === DEFAULT_KEY };
-}
-export function installInboxBinding(opts = {}) {
-    const socket = opts.socket ?? tmuxSocketFromEnvironment();
-    const key = opts.key ?? configuredKey();
-    if (socket === undefined)
-        return { state: 'unbound', key, isDefault: key === DEFAULT_KEY };
-    const existing = rootBinding(socket, key);
-    if (existing !== undefined && !isCanonical(existing))
-        return { state: 'collision', key, isDefault: key === DEFAULT_KEY };
-    if (existing === undefined)
-        tmux(socket, ['bind-key', '-T', 'root', key, 'run-shell', '-b', bindingCommand()]);
-    if (opts.key !== undefined) {
-        // Switching to a new key: drop the previous configured key iff it still holds the
-        // canonical toggle, so bindings don't accrete and inspect/unbind track a single live key.
-        const previous = configuredKey();
-        if (previous !== key && isCanonical(rootBinding(socket, previous)))
-            tmux(socket, ['unbind-key', '-T', 'root', previous]);
-        writeConfiguredKey(key);
-    }
-    return { state: 'installed', key, isDefault: key === DEFAULT_KEY };
-}
-export function unbindInboxBinding(socket = tmuxSocketFromEnvironment()) {
-    const key = configuredKey();
-    if (socket !== undefined && isCanonical(rootBinding(socket, key)))
-        tmux(socket, ['unbind-key', '-T', 'root', key]);
-    return inspectInboxBinding(socket);
+    // --quiet keeps the background `run-shell -b` binding from printing its result JSON, which
+    // tmux would otherwise surface as a view-mode overlay on the active pane. The popup opening
+    // is the feedback; a genuine failure still prints (see the CLI toggle action).
+    return 'hl inbox toggle --quiet --tmux-socket "#{socket_path}" --tmux-client "#{client_name}" --target-pane "#{pane_id}"';
+}
+/** The argv crouter's tmux-binding installer binds on the root table to toggle the inbox popup.
+ *  Humanloop owns the command text; crouter owns which key(s) run it (via its keybindings catalog
+ *  and the single `installTmuxBindings()` manifest sweep). Humanloop no longer persists or
+ *  reconciles any key itself. */
+export function inboxToggleTmuxCommand() {
+    return ['run-shell', '-b', bindingCommand()];
 }
 export function tmuxSocketFromEnvironment() {
     const value = process.env['TMUX'];
@@ -121,8 +67,11 @@ export async function toggleInboxPopup(target) {
     mkdirSync(join(paths.controlSocket, '..'), { recursive: true, mode: 0o700 });
     if (await requestPopupClose(paths.controlSocket))
         return 'closed';
+    // A concurrent toggle for this same client won the startup lock and is opening the popup.
+    // This gesture must not launch a second one; report a benign no-op close rather than a
+    // generic failure, so exactly one popup exists and the loser never exits with an error.
     if (!acquireStartupLock(paths.startupLock))
-        return 'failed';
+        return 'closed';
     try {
         // Re-probe under the lock: between the first probe and acquiring the lock a concurrent
         // toggle may have brought a live popup up. Deleting its control socket now would orphan
@@ -156,7 +105,12 @@ async function launchPopup(socket, target, controlSocket, command) {
     let stderr = '';
     child.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
     const exited = new Promise((resolve) => {
-        child.once('exit', (code) => resolve(code === 0 ? 'closed' : /popup/i.test(stderr) ? 'other_popup' : 'failed'));
+        // `display-popup -E` blocks until our popup closes, so a successful open keeps the child
+        // alive while the control socket comes up (detected below). An early exit before that means
+        // the popup command never ran: tmux 3.x silently declines to stack a popup on a client that
+        // already shows one (exit 0, command dropped), which is exactly the foreign-popup case the
+        // design must report as `other_popup` without disturbing the existing popup or its process.
+        child.once('exit', (code) => resolve(code === 0 || /popup/i.test(stderr) ? 'other_popup' : 'failed'));
         child.once('error', () => resolve('failed'));
     });
     const { Socket } = await import('node:net');
@@ -176,7 +130,7 @@ async function launchPopup(socket, target, controlSocket, command) {
             return 'opened';
         }
         if (outcome !== 'pending')
-            return outcome === 'closed' ? 'failed' : outcome;
+            return outcome;
     }
     return 'failed';
 }

package/dist/types.d.ts

@@ -211,11 +211,6 @@ export interface CanceledTicketResult {
 }
 /** The sole canonical response.json union. */
 export type TicketResult = DeckTicketResult | ReviewTicketResult | CanceledTicketResult;
-export interface InboxBindingState {
-    state: 'installed' | 'collision' | 'unbound';
-    key: string;
-    isDefault: boolean;
-}
 export interface CompletionEvent {
     schema: 'humanloop.completion/v1';
     root: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.34",
+  "version": "0.3.36",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "dev": "tsx src/cli.ts",
     "link": "npm link",
     "postinstall": "node dist/scripts/install-renderer.js || true",
-    "test": "tsx src/__tests__/inbox-core.test.ts && tsx src/__tests__/mount-panel.test.ts && tsx src/__tests__/feedback.test.ts && tsx src/__tests__/browser-server.test.ts && tsx web/src/__tests__/review-sourcemap.test.ts && tsx web/src/__tests__/review-reducer.test.ts && tsx web/src/__tests__/review-keymap.test.ts && tsx web/src/__tests__/review-markdown-instrumentation.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-deck-regression.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-conflict.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-ws-close.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-takeback.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-submit-race.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-stale-submit-failure.test.ts && tsx src/__tests__/inbox-popup.test.ts"
+    "test": "tsx src/__tests__/inbox-core.test.ts && tsx src/__tests__/inbox-controller.test.ts && tsx src/__tests__/review-adapter.test.ts && tsx src/__tests__/mount-panel.test.ts && tsx src/__tests__/feedback.test.ts && tsx src/__tests__/browser-server.test.ts && tsx web/src/__tests__/review-sourcemap.test.ts && tsx web/src/__tests__/review-reducer.test.ts && tsx web/src/__tests__/review-keymap.test.ts && tsx web/src/__tests__/review-markdown-instrumentation.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-deck-regression.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-conflict.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/app-ws-close.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-takeback.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-submit-race.test.ts && tsx --tsconfig web/tsconfig.json web/src/__tests__/review-surface-stale-submit-failure.test.ts && tsx src/__tests__/inbox-popup.test.ts"
   },
   "dependencies": {
     "@r-cli/sdk": "^1.3.0",