@crouton-kit/humanloop 0.3.34 → 0.3.35

package/dist/cli.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);
@@ -51,9 +52,13 @@ inbox.command('open').description('Open the inbox controller in this human TTY.'
         fail('hl inbox open requires an interactive TTY; use hl inbox list for read-only output');
     await openInboxPopup(options.controlSocket, roots(options.root));
 });
-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))));

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,6 +1,7 @@
-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 { renderMarkdown } from '../render/termrender.js';
 import { BOLD, CYAN, DIM, RESET, YELLOW } from '../tui/ansi.js';
 import { buildInboxLines } from './tui.js';
 import { inboxLayout } from './layout.js';
@@ -8,8 +9,10 @@ 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) {
@@ -94,7 +106,11 @@ export class InboxController {
         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 +133,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 +170,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 +231,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 +246,7 @@ export class InboxController {
                 if (this.closed)
                     finish();
             };
+            this.stdinListener = onData;
             const onResize = () => this.resize();
             let done = false;
             this.finishRun = () => {
@@ -184,6 +254,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 +271,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 +353,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 +407,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 +421,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 +450,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,7 +28,7 @@ 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 ?? '';
+        const source = item.source.sessionName ?? item.source.askedBy ?? item.source.nodeId ?? '';
         const age = formatTimeAgo(item.blockedSince);
         const cursor = index === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
         const titleWidth = Math.max(10, contentWidth - source.length - age.length - 8);

package/dist/render/termrender.d.ts

@@ -5,6 +5,11 @@
  * degradation path: `uv` absent → one stderr remediation line + plaintext
  * fallback. win32 → plaintext (no renderer).
  *
+ * Steady state is subprocess-free: a valid stamp is trusted outright. The
+ * spawn-based verification (`binaryOk` + `installedVersion`) runs only when the
+ * stamp is absent or stale — once, after which the venv is re-stamped — and the
+ * full `uv` reinstall runs only when the binary is actually missing or drifted.
+ *
  * Invoked at postinstall AND lazily on the first render/check/display call,
  * so `npm ci --ignore-scripts` consumers still self-heal on first use.
  */

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 } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join, resolve } from 'node:path';
 import stringWidth from 'string-width';
@@ -27,7 +27,48 @@ 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');
+// Stamp written after a verified install: records the pin we provisioned and
+// the binary's mtime at that moment. Steady-state validation is a stat + a
+// tiny JSON read against this — no subprocess — so attach no longer pays the
+// ~149ms `termrender -h` + `importlib.metadata` spawn tax on every launch.
+const VENV_STAMP = resolve(PKG_ROOT, '.venv/.hl-termrender-stamp.json');
 let rendererState = 'unchecked';
+function readStamp() {
+    try {
+        const parsed = JSON.parse(readFileSync(VENV_STAMP, 'utf8'));
+        if (typeof parsed.version === 'string' && typeof parsed.mtimeMs === 'number')
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeStamp() {
+    try {
+        writeFileSync(VENV_STAMP, JSON.stringify({ version: TERMRENDER_VERSION, mtimeMs: statSync(VENV_BIN).mtimeMs }));
+    }
+    catch {
+        // Best-effort: an unwritable stamp just means the next process re-verifies
+        // the slow way once and re-stamps. Correctness is unaffected.
+    }
+}
+// Cheap steady-state trust: the pinned binary is present and unchanged since
+// the verified install that wrote the stamp. A version bump or an out-of-band
+// rewrite of the binary changes the pin or the mtime and forces re-provision.
+function stampValid() {
+    if (!existsSync(VENV_BIN))
+        return false;
+    const stamp = readStamp();
+    if (!stamp || stamp.version !== TERMRENDER_VERSION)
+        return false;
+    try {
+        return statSync(VENV_BIN).mtimeMs === stamp.mtimeMs;
+    }
+    catch {
+        return false;
+    }
+}
 function binaryOk() {
     if (!existsSync(VENV_BIN))
         return false;
@@ -76,6 +117,11 @@ function uvAvailable() {
  * degradation path: `uv` absent → one stderr remediation line + plaintext
  * fallback. win32 → plaintext (no renderer).
  *
+ * Steady state is subprocess-free: a valid stamp is trusted outright. The
+ * spawn-based verification (`binaryOk` + `installedVersion`) runs only when the
+ * stamp is absent or stale — once, after which the venv is re-stamped — and the
+ * full `uv` reinstall runs only when the binary is actually missing or drifted.
+ *
  * 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,7 +132,16 @@ export function ensureRenderer() {
         rendererState = 'unavailable';
         return;
     }
+    // Steady state: trust the stamp — zero subprocess spawns.
+    if (stampValid()) {
+        rendererState = 'ready';
+        return;
+    }
+    // No/stale stamp but the correct binary is already present (a venv from a
+    // pre-stamp humanloop, or an interrupted stamp write): verify once the slow
+    // way, stamp it, and skip the reinstall.
     if (binaryOk() && installedVersion() === TERMRENDER_VERSION) {
+        writeStamp();
         rendererState = 'ready';
         return;
     }
@@ -113,8 +168,12 @@ export function ensureRenderer() {
         rendererState = 'unavailable';
         return;
     }
-    rendererState = (binaryOk() && installedVersion() === TERMRENDER_VERSION) ? 'ready' : 'unavailable';
-    if (rendererState === 'unavailable') {
+    if (binaryOk() && installedVersion() === TERMRENDER_VERSION) {
+        writeStamp();
+        rendererState = 'ready';
+    }
+    else {
+        rendererState = 'unavailable';
         process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
     }
 }
@@ -124,7 +183,7 @@ export function isRendererReady() {
         return true;
     if (rendererState === 'unavailable')
         return false;
-    return process.platform !== 'win32' && binaryOk();
+    return process.platform !== 'win32' && (stampValid() || binaryOk());
 }
 // ── 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;

package/dist/tui/tmux.js

@@ -22,7 +22,10 @@ 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}"';
+    // --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}"';
 }
 function configuredKeyPath() {
     const state = process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state');
@@ -121,8 +124,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 +162,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 +187,7 @@ async function launchPopup(socket, target, controlSocket, command) {
             return 'opened';
         }
         if (outcome !== 'pending')
-            return outcome === 'closed' ? 'failed' : outcome;
+            return outcome;
     }
     return 'failed';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/humanloop",
-  "version": "0.3.34",
+  "version": "0.3.35",
   "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",