@crouton-kit/humanloop 0.3.35 → 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';
@@ -50,7 +50,18 @@ 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>').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 });
@@ -70,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/inbox/controller.js

@@ -2,7 +2,7 @@ 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 { 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';
@@ -98,10 +98,17 @@ 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);
     }

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 ?? item.source.nodeId ?? '';
+        // 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,20 +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.
  *
- * 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.
+ * 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, readFileSync, writeFileSync, statSync } 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,47 +27,245 @@ 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.
+// 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 parsed = JSON.parse(readFileSync(VENV_STAMP, 'utf8'));
-        if (typeof parsed.version === 'string' && typeof parsed.mtimeMs === 'number')
-            return parsed;
+        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;
     }
 }
-function writeStamp() {
+// 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 {
-        writeFileSync(VENV_STAMP, JSON.stringify({ version: TERMRENDER_VERSION, mtimeMs: statSync(VENV_BIN).mtimeMs }));
+        pythonRealpath = realpathSync(VENV_PYTHON);
     }
     catch {
-        // Best-effort: an unwritable stamp just means the next process re-verifies
-        // the slow way once and re-stamps. Correctness is unaffected.
+        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`);
     }
 }
-// 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.
+// 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() {
-    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;
+        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))
@@ -111,16 +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.
  *
- * 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.
+ * 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.
@@ -137,53 +334,70 @@ export function ensureRenderer() {
         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;
-    }
-    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;
-    }
-    if (binaryOk() && installedVersion() === TERMRENDER_VERSION) {
-        writeStamp();
+        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';
-    }
-    else {
-        rendererState = 'unavailable';
-        process.stderr.write('[hl] termrender install completed but health check failed; using plaintext fallback\n');
-    }
+    });
 }
-/** 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' && (stampValid() || 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;
@@ -267,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);
@@ -288,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;
@@ -329,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';
@@ -27,68 +26,12 @@ function bindingCommand() {
     // 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');
-    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);
+/** 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'];

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.35",
+  "version": "0.3.36",
   "description": "Human-in-the-loop decision TUI — agents write questions, humans answer them",
   "type": "module",
   "main": "dist/index.js",