@crouton-kit/humanloop 0.4.9 → 0.4.11

package/dist/api.d.ts

@@ -13,7 +13,7 @@ export interface AskOpts {
  */
 export declare function ask(deck: Deck, opts?: AskOpts): Promise<ResolutionEnvelope>;
 /** Sugar: a single `kind:'notify'` acknowledgement. */
-export declare function notify(title: string, body?: string): Promise<void>;
+export declare function notify(title: string, subtitle: string, body?: string): Promise<void>;
 export interface InboxOpts {
     cols?: number;
     rows?: number;

package/dist/api.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { resolveInteractionDir } from './tui/app.js';
 import { InboxController } from './inbox/controller.js';
 import { deckPath, atomicWriteJson, stampCanvasNode } from './inbox/convention.js';
-import { resolveDeckBodyPaths } from './inbox/deck-schema.js';
+import { resolveDeckBodyPaths, validateDeck } from './inbox/deck-schema.js';
 import { notifyDeck } from './inbox/deck-factories.js';
 import { buildSummary } from './summary.js';
 const RESPONSE_SCHEMA_ID = 'humanloop.response/v2';
@@ -23,7 +23,7 @@ export async function ask(deck, opts = {}) {
     // resolved BEFORE the deck is ever written to disk, so every reader
     // downstream (terminal render, the live-reload poller, the browser server)
     // only ever sees a plain `body`.
-    deck = resolveDeckBodyPaths(deck, dir);
+    deck = validateDeck(resolveDeckBodyPaths(deck, dir));
     stampCanvasNode(deck);
     atomicWriteJson(deckPath(dir), deck);
     const { responses, completedAt, responsePath, deck: answeredDeck } = await resolveInteractionDir(dir, deck, {
@@ -42,8 +42,8 @@ export async function ask(deck, opts = {}) {
     };
 }
 /** Sugar: a single `kind:'notify'` acknowledgement. */
-export async function notify(title, body) {
-    const deck = notifyDeck(title, body !== undefined ? { body } : {});
+export async function notify(title, subtitle, body) {
+    const deck = notifyDeck(title, { subtitle, ...(body !== undefined ? { body } : {}) });
     await ask(deck, {});
 }
 /** Open the centralized inbox controller in the current human terminal. */

package/dist/cli.js

@@ -85,7 +85,7 @@ 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()));
-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) => {
+program.command('deck').command('ask').description('Submit a durable deck ticket; every interaction needs a one-sentence subtitle stating the decision, recommendation/status, and stakes. --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();
         const deck = validateDeck(body.deck);
@@ -102,11 +102,13 @@ program.command('deck').command('ask').description('Submit a durable deck ticket
         fail(error);
     }
 });
-program.command('review').command('open').description('Submit a durable anchored review; it never changes tmux. --inline blocks in this terminal instead.').option('--root <path>').option('--inline', 'run the review in this terminal and block until submitted').action(async (options) => {
+program.command('review').command('open').description('Submit a durable anchored review; subtitle is a required one-sentence recommendation/status and stakes. --inline blocks in this terminal instead.').option('--root <path>').option('--inline', 'run the review in this terminal and block until submitted').action(async (options) => {
     try {
         const body = objectInput();
         if (typeof body.file !== 'string' || !existsSync(resolve(body.file)))
             throw new Error('file must be an existing markdown path');
+        if (typeof body.subtitle !== 'string' || body.subtitle.trim() === '')
+            throw new Error('subtitle is required and must be a non-empty plain-English sentence stating the recommendation/status and stakes');
         const absFile = resolve(body.file);
         const output = typeof body.output === 'string' ? resolve(body.output) : `${absFile}.feedback.json`;
         if (options.inline) {
@@ -118,7 +120,7 @@ program.command('review').command('open').description('Submit a durable anchored
         if (typeof body.title !== 'string' || !body.title)
             throw new Error('title is required');
         const registration = options.root === undefined ? managedInboxRoot() : requireRegisteredRoot(options.root);
-        emit({ ...submitReview({ root: registration.root, id: typeof body.id === 'string' ? body.id : randomUUID(), review: { file: absFile, output, title: body.title, source: typeof body.source === 'object' && body.source !== null ? body.source : {} } }), queued: true });
+        emit({ ...submitReview({ root: registration.root, id: typeof body.id === 'string' ? body.id : randomUUID(), review: { file: absFile, output, title: body.title, subtitle: body.subtitle, source: typeof body.source === 'object' && body.source !== null ? body.source : {} } }), queued: true });
     }
     catch (error) {
         fail(error);

package/dist/editor/terminal-review.d.ts

@@ -50,6 +50,9 @@ export interface ReviewState {
     selectionAnchor: number | null;
     /** Scroll offset into the rendered (termrender) lines. */
     scroll: number;
+    /** Horizontal pan offset, in display cells, for rows wider than the body
+     *  rectangle (diagrams). Rows that fit never move. */
+    hscroll: number;
     mode: 'view' | 'list' | 'compose' | 'help';
     compose: ComposeState | null;
     listIndex: number;
@@ -130,9 +133,26 @@ export declare function textDelete(buffer: string, cursor: number): {
 export declare function textHome(buffer: string, cursor: number): number;
 export declare function textEnd(buffer: string, cursor: number): number;
 export declare function textVertical(buffer: string, cursor: number, delta: number): number;
-/** Width the document is rendered at for a given terminal width: 2-col left
+/** Width prose is rendered at for a given terminal width: 2-col left
  *  margin + 2-col gutter before the content, capped for readability. */
 export declare function renderWidthForCols(cols: number): number;
+/** The body rectangle a rendered row is painted into: the terminal minus the
+ *  4-col gutter prefix. Diagram blocks render at this width (no prose cap),
+ *  and every emitted body row is contained within it. */
+export declare function contentWidthForCols(cols: number): number;
+/** The mapped render this surface paints: prose at the readability cap,
+ *  diagrams at the full body width. */
+export declare function renderReviewDoc(content: string, cols: number): RenderedDoc;
+/** Widest painted row, in display cells, for a body window. */
+export declare function widestVisibleRow(doc: RenderedDoc, scroll: number, bodyHeight: number): number;
+/** How far the body can pan right, given what is currently on screen. Zero
+ *  when nothing visible overflows — which is also what makes h/l contextual:
+ *  the keys only pan while an overflowing row is in view. */
+export declare function maxHScroll(state: ReviewState, doc: RenderedDoc, cols: number, rows: number): number;
+/** Pan the body horizontally, clamped to what is currently reachable. The
+ *  stored offset is only ever clamped against the live window, so vertical
+ *  scrolling and resize can never leave it pointing past the content. */
+export declare function panBy(state: ReviewState, delta: number, doc: RenderedDoc, cols: number, rows: number): ReviewState;
 /** Reserved (non-body) rows for each mode's fixed header/footer chrome. Kept in
  *  sync with renderReviewFrame so scroll math can clamp before a repaint — the
  *  compose case counts the same hard-wrapped input lines the frame renders. */

package/dist/editor/terminal-review.js

@@ -7,10 +7,10 @@ import { waitForParkedReviewSubmit } from './parked.js';
 import { openBrowser } from '../browser/open.js';
 import { startReviewWebServer } from '../browser/server.js';
 import { buildDraftFeedbackResult, buildFinalFeedbackResult, readReviewDraft, writeReviewDraft } from './feedback.js';
-import { renderMarkdownWithMap } from '../render/termrender.js';
+import { renderMarkdownBlockAware } from '../render/termrender.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress } from '../tui/terminal.js';
 import { diffFrame, renderInputBuffer } from '../tui/render.js';
-import { BOLD, CYAN, DIM, ESC, RESET, YELLOW, hline, sanitize, truncate } from '../tui/ansi.js';
+import { BOLD, CYAN, DIM, ESC, RESET, YELLOW, clipLine, hline, panLine, sanitize, truncate, visibleWidth } from '../tui/ansi.js';
 /** Derive leaf anchor units from a mapped render: dedupe runs of consecutive
  *  rows carrying the identical source span. A mapped row without a leaf span
  *  (an unmapped block) anchors at its whole block's range, so every content
@@ -113,6 +113,7 @@ export function initReviewState(sourceLines, anchor, comments, version) {
         activeUnit: comments.length > 0 ? unitIndexForLine(safe.units, comments[0].line) : 0,
         selectionAnchor: null,
         scroll: 0,
+        hscroll: 0,
         mode: 'view',
         compose: null,
         listIndex: 0,
@@ -342,11 +343,64 @@ export function textVertical(buffer, cursor, delta) {
     return Math.min(nextEnd, nextStart + col);
 }
 // ── Rendering (pure) ─────────────────────────────────────────────────────────
-/** Width the document is rendered at for a given terminal width: 2-col left
+/** Width prose is rendered at for a given terminal width: 2-col left
  *  margin + 2-col gutter before the content, capped for readability. */
 export function renderWidthForCols(cols) {
     return Math.min(Math.max(20, cols - 6), 120);
 }
+/** The body rectangle a rendered row is painted into: the terminal minus the
+ *  4-col gutter prefix. Diagram blocks render at this width (no prose cap),
+ *  and every emitted body row is contained within it. */
+export function contentWidthForCols(cols) {
+    return Math.max(20, cols - 4);
+}
+/** The mapped render this surface paints: prose at the readability cap,
+ *  diagrams at the full body width. */
+export function renderReviewDoc(content, cols) {
+    return renderMarkdownBlockAware(content, renderWidthForCols(cols), contentWidthForCols(cols));
+}
+/** Body rows as they are actually painted. Vertical-scroll indicators replace
+ * their endpoint rows, so content behind one cannot advertise or claim h/l. */
+function paintedBodyRows(doc, scroll, bodyHeight) {
+    const rows = [];
+    for (let i = 0; i < bodyHeight; i++) {
+        const abs = scroll + i;
+        rows.push(abs < doc.lines.length ? { abs, line: doc.lines[abs] } : { abs: null, line: '' });
+    }
+    if (scroll > 0 && rows.length > 0)
+        rows[0] = { abs: null, line: `  ${DIM}↑ ${scroll} more above${RESET}` };
+    const remaining = doc.lines.length - (scroll + bodyHeight);
+    if (remaining > 0 && rows.length > 0)
+        rows[rows.length - 1] = { abs: null, line: `  ${DIM}↓ ${remaining} more below${RESET}` };
+    return rows;
+}
+/** Widest painted row, in display cells, for a body window. */
+export function widestVisibleRow(doc, scroll, bodyHeight) {
+    let widest = 0;
+    for (const row of paintedBodyRows(doc, scroll, bodyHeight))
+        widest = Math.max(widest, visibleWidth(row.line));
+    return widest;
+}
+/** How far the body can pan right, given what is currently on screen. Zero
+ *  when nothing visible overflows — which is also what makes h/l contextual:
+ *  the keys only pan while an overflowing row is in view. */
+export function maxHScroll(state, doc, cols, rows) {
+    const bodyHeight = Math.max(1, rows - reservedRows(state, cols));
+    const maxScroll = Math.max(0, doc.lines.length - bodyHeight);
+    const scroll = Math.max(0, Math.min(state.scroll, maxScroll));
+    return Math.max(0, widestVisibleRow(doc, scroll, bodyHeight) - contentWidthForCols(cols));
+}
+/** Pan the body horizontally, clamped to what is currently reachable. The
+ *  stored offset is only ever clamped against the live window, so vertical
+ *  scrolling and resize can never leave it pointing past the content. */
+export function panBy(state, delta, doc, cols, rows) {
+    const max = maxHScroll(state, doc, cols, rows);
+    const next = Math.max(0, Math.min(state.hscroll + delta, max));
+    return next === state.hscroll ? state : { ...state, hscroll: next };
+}
+/** Cells one h/l press pans by — a chunk large enough to cross a diagram in a
+ *  few presses, small enough to keep orientation. */
+const PAN_STEP = 8;
 // Single-hue anchor tint (a dark neutral step below the CYAN gutter bar).
 // termrender's only reset is `\x1b[0m`, so re-arming the background after each
 // reset keeps the tint alive across inner styling. Heading rows carry their
@@ -409,7 +463,7 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
     else if (state.mode === 'help') {
         footer.push('  Keys:');
         footer.push(`  ${DIM}j/k${RESET}         move anchor            ${DIM}shift+j/k${RESET}   extend selection`);
-        footer.push(`  ${DIM}u/d, pgup/pgdn${RESET}  scroll document`);
+        footer.push(`  ${DIM}u/d, pgup/pgdn${RESET}  scroll document       ${DIM}h/l${RESET}         pan visible wide diagrams`);
         footer.push(`  ${DIM}space c${RESET}     compose comment        ${DIM}space l${RESET}     list comments`);
         footer.push(`  ${DIM}space u${RESET}     undo last comment      ${DIM}space s${RESET}     submit review`);
         footer.push(`  ${DIM}space w${RESET}     hand off to browser`);
@@ -425,35 +479,46 @@ export function renderReviewFrame(state, fileLabel, doc, cols, rows) {
     const bodyHeight = Math.max(1, rows - reserved);
     const maxScroll = Math.max(0, doc.lines.length - bodyHeight);
     const scroll = Math.max(0, Math.min(state.scroll, maxScroll));
+    const contentW = contentWidthForCols(cols);
+    // Effective pan: the stored offset, clamped to what this window can reach.
+    // Scrolling into narrow content parks the diagram offset rather than losing
+    // it, so scrolling back restores the same horizontal position.
+    const overflow = Math.max(0, widestVisibleRow(doc, scroll, bodyHeight) - contentW);
+    const hscroll = Math.max(0, Math.min(state.hscroll, overflow));
     const { lo, hi } = selectedUnitBounds(state);
     const commented = commentedUnitSet(state);
     const body = [];
-    for (let i = 0; i < bodyHeight; i++) {
-        const abs = scroll + i;
-        if (abs >= doc.lines.length) {
-            body.push('');
+    for (const source of paintedBodyRows(doc, scroll, bodyHeight)) {
+        if (source.abs === null) {
+            body.push(source.line);
             continue;
         }
-        const row = doc.lines[abs];
-        const u = state.rowUnits[abs] ?? null;
+        // Every body row is windowed into the body rectangle: a diagram wider than
+        // the pane pans instead of spilling past the right edge.
+        const row = panLine(source.line, hscroll, contentW);
+        const u = state.rowUnits[source.abs] ?? null;
+        // Tint the prose column at minimum, and a wide row across what it occupies.
+        const tintW = Math.min(contentW, Math.max(docW, visibleWidth(row)));
         if (u !== null && u >= lo && u <= hi)
-            body.push(`  ${CYAN}▌${RESET} ${tintRow(row, docW)}`);
+            body.push(`  ${CYAN}▌${RESET} ${tintRow(row, tintW)}`);
         else if (u !== null && commented.has(u))
             body.push(`  ${YELLOW}▎${RESET} ${row}`);
         else
             body.push(`    ${row}`);
     }
-    if (scroll > 0 && body.length > 0)
-        body[0] = `  ${DIM}↑ ${scroll} more above${RESET}`;
-    const remaining = doc.lines.length - (scroll + bodyHeight);
-    if (remaining > 0 && body.length > 0)
-        body[body.length - 1] = `  ${DIM}↓ ${remaining} more below${RESET}`;
+    // Contextual pan hint: only while something on screen actually overflows.
+    // Appends to the existing footer line, so the reserved row count is unchanged.
+    if (overflow > 0 && state.mode === 'view' && footer.length > 0) {
+        footer[0] = `${footer[0]}  ${DIM}h/l${RESET} pan`;
+    }
     while (body.length < bodyHeight)
         body.push('');
     const lines = [...header, ...body, ...footer];
     while (lines.length < rows)
         lines.push('');
-    return lines.slice(0, rows);
+    // The frame is contained by construction: no row may exceed the terminal, or
+    // it wraps and breaks the differ's one-line-per-row model.
+    return lines.slice(0, rows).map((line) => clipLine(line, cols));
 }
 function diskDraftResult(absFile, outPath) {
     const draft = readReviewDraft(outPath);
@@ -537,7 +602,7 @@ function runTerminalReviewSession(absFile, content, outPath, fileLabel, opts) {
     const draft = readReviewDraft(outPath);
     setupTerminal();
     let { cols, rows } = getTerminalSize();
-    let doc = renderMarkdownWithMap(content, renderWidthForCols(cols));
+    let doc = renderReviewDoc(content, cols);
     let state = initReviewState(sourceLines, deriveAnchorUnits(doc), draft?.comments ?? [], draft?.version ?? 0);
     let prevFrame = [];
     let spaceArmed = false;
@@ -575,7 +640,7 @@ function runTerminalReviewSession(absFile, content, outPath, fileLabel, opts) {
         const finish = (result) => finishWith({ type: 'done', result });
         const onResize = () => {
             ({ cols, rows } = getTerminalSize());
-            doc = renderMarkdownWithMap(content, renderWidthForCols(cols));
+            doc = renderReviewDoc(content, cols);
             // Unit SOURCE ranges are width-independent under the same renderer (only
             // their rendered-row bounds move), but a mid-session renderer→fallback
             // transition can reshape the list — so remap the anchor by its source
@@ -775,6 +840,10 @@ function runTerminalReviewSession(absFile, content, outPath, fileLabel, opts) {
                 state = scrollBy(state, -bodyH(), bodyH(), doc.lines.length);
             else if (input === 'd' || key.pageDown)
                 state = scrollBy(state, bodyH(), bodyH(), doc.lines.length);
+            else if ((input === 'h' || key.leftArrow) && maxHScroll(state, doc, cols, rows) > 0)
+                state = panBy(state, -PAN_STEP, doc, cols, rows);
+            else if ((input === 'l' || key.rightArrow) && maxHScroll(state, doc, cols, rows) > 0)
+                state = panBy(state, PAN_STEP, doc, cols, rows);
             else if (input === '?')
                 state = openHelp(state);
             else if (key.escape) {

package/dist/inbox/controller.js

@@ -19,7 +19,7 @@ import { validateDeck } from './deck-schema.js';
 import { ReviewAdapter } from './review-adapter.js';
 import { editBufferInEditor } from '../editor/roundtrip.js';
 import { cancelFollowUp, readFollowUp, requestFollowUp } from './followup.js';
-import { cancelVisualRequest, readVisualResult, reconcileVisualRequestsForTicket, startVisualRequest, VISUAL_CAPABILITY, } from './visual.js';
+import { cancelVisualRequest, latestVisualRequestForInteraction, readVisualResult, startVisualRequest, VISUAL_CAPABILITY, } from './visual.js';
 import { kickInboxMaintenance } from './maintenance.js';
 /** One terminal owner for scanning, stable selection, claims, and frame diffs. */
 export class InboxController {
@@ -129,7 +129,9 @@ export class InboxController {
             // 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] ?? '';
+            // Clip the detail column too: a deck/preview row is only ever entitled to
+            // its own panel, so an over-wide row cannot run past the pane's edge.
+            const right = clipLine(detail[i] ?? '', geometry.detailWidth);
             const pad = ' '.repeat(Math.max(0, geometry.listWidth - visibleWidth(left)));
             lines.push(`${left}${pad}${divider}${right}`);
         }
@@ -249,13 +251,6 @@ export class InboxController {
             this.invalidate();
             return;
         }
-        const root = ticketRoot(item.dir);
-        if (root !== null) {
-            // A newly acquired claim makes every older running generation stale
-            // before the panel can mint its own work. This only dispatches cleanup.
-            const retirement = reconcileVisualRequestsForTicket(root, item.dir, claim.token);
-            void retirement.delivery.finally(kickInboxMaintenance);
-        }
         // Notifications use the same canonical deck panel as every other deck:
         // opening is not acknowledgement; panel completion is.
         this.activeDeck = deck;
@@ -640,19 +635,28 @@ export class InboxController {
             watcher = undefined;
             settle(outcome);
         };
-        let started;
+        let durableRequestId;
+        let delivery;
         try {
-            started = startVisualRequest({ root, dir, claimToken, request });
+            const adopted = latestVisualRequestForInteraction(root, dir, request.interaction);
+            if (adopted !== null) {
+                durableRequestId = adopted.requestId;
+            }
+            else {
+                const started = startVisualRequest({ root, dir, claimToken, request });
+                durableRequestId = started.request.requestId;
+                delivery = started.delivery;
+            }
         }
         catch (error) {
             finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
-            return { result, cancel: () => { } };
+            return { result, detach: () => { }, cancel: () => { } };
         }
         const reread = () => {
             if (settled)
                 return;
             try {
-                const outcome = readVisualResult(root, dir, request.requestId);
+                const outcome = readVisualResult(root, dir, durableRequestId);
                 if (outcome === null)
                     return;
                 finish(outcome.status === 'ready'
@@ -666,20 +670,26 @@ export class InboxController {
         try {
             // Install the watch before the first durable reread so a publication in
             // the narrow setup window is either observed or found by that reread.
-            watcher = watch(join(visualsDir(dir), request.requestId), () => reread());
+            watcher = watch(join(visualsDir(dir), durableRequestId), (_event, file) => {
+                // Rereading takes a short directory lock, which itself emits watch events on Linux.
+                // Only the immutable result can settle this handle; ignoring lock/request churn avoids a self-triggered event loop.
+                if (file !== null && file !== 'result.json')
+                    return;
+                reread();
+            });
             watcher.once('error', (error) => finish({ status: 'error', error: error.message }));
             reread();
         }
         catch (error) {
             finish({ status: 'error', error: error instanceof Error ? error.message : String(error) });
         }
-        void started.delivery.then(reread, (error) => finish({ status: 'error', error: error instanceof Error ? error.message : String(error) }));
+        void delivery?.then(reread, (error) => finish({ status: 'error', error: error instanceof Error ? error.message : String(error) }));
         return {
             result,
+            detach: () => finish({ status: 'error', error: 'Visual view detached' }),
             cancel: () => {
-                watcher?.close();
-                watcher = undefined;
-                void cancelVisualRequest(root, dir, request.requestId).finally(kickInboxMaintenance);
+                finish({ status: 'error', error: 'Visual request canceled' });
+                void cancelVisualRequest(root, dir, durableRequestId).finally(kickInboxMaintenance);
             },
         };
     }
@@ -764,7 +774,8 @@ 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} · ${sourceLabel(selected.source)}${RESET}`];
+        const source = sourceLabel(selected.source);
+        const lines = [`  ${BOLD}${CYAN}${selected.title}${RESET}`, '', `  ${DIM}${selected.kind}${source === undefined ? '' : ` · ${source}`}${RESET}`];
         if (selected.kind === 'review') {
             lines.push('', `  ${DIM}${selected.file}${RESET}`);
             const draft = readJson(progressPath(selected.dir))?.comments;
@@ -788,9 +799,8 @@ export class InboxController {
             if (deck !== null) {
                 for (const interaction of deck.interactions) {
                     lines.push('', `  ${BOLD}${interaction.title}${RESET}`);
-                    if (interaction.subtitle)
-                        for (const rendered of renderMarkdown(interaction.subtitle, Math.max(1, width - 2)))
-                            lines.push(`  ${rendered}`);
+                    for (const rendered of renderMarkdown(interaction.subtitle, Math.max(1, width - 2)))
+                        lines.push(`  ${rendered}`);
                     if (interaction.body)
                         for (const rendered of renderMarkdown(interaction.body, Math.max(1, width - 2)))
                             lines.push(`  ${rendered}`);
@@ -901,6 +911,5 @@ function isToggleCloseChord(input) { return input === '\x1bi' || input === '\x1b
 function isAnswerBearingDeck(deck) {
     return deck.interactions.some((interaction) => interaction.kind !== 'notify');
 }
-/** Prefer a human-meaningful source label, falling back to the raw node id
- *  before an opaque "unknown source" — a crouter ticket always carries nodeId. */
-function sourceLabel(source) { return source.sessionName ?? source.askedBy ?? source.nodeId ?? 'unknown source'; }
+/** Machine node IDs remain stored for routing, but passive detail shows only authored labels. */
+function sourceLabel(source) { return source.sessionName?.trim() || source.askedBy?.trim() || undefined; }

package/dist/inbox/deck-factories.d.ts

@@ -1,6 +1,8 @@
 import type { Deck } from '../types.js';
 export interface NotifyDeckOpts {
+    /** One plain-English sentence stating the notification's status and stakes. */
+    subtitle: string;
     body?: string;
 }
 /** Build a validated single-option notify deck. id: 'notify', kind: 'notify'. */
-export declare function notifyDeck(title: string, opts?: NotifyDeckOpts): Deck;
+export declare function notifyDeck(title: string, opts: NotifyDeckOpts): Deck;

package/dist/inbox/deck-factories.js

@@ -1,11 +1,12 @@
 import { validateDeck } from './deck-schema.js';
 /** Build a validated single-option notify deck. id: 'notify', kind: 'notify'. */
-export function notifyDeck(title, opts = {}) {
+export function notifyDeck(title, opts) {
     return validateDeck({
         title,
         interactions: [{
                 id: 'notify',
                 title,
+                subtitle: opts.subtitle,
                 ...(opts.body !== undefined ? { body: opts.body } : {}),
                 kind: 'notify',
                 options: [{ id: 'ok', label: 'OK' }],

package/dist/inbox/deck-schema.d.ts

@@ -23,7 +23,7 @@ export declare const deckSchema: z.ZodObject<{
     interactions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         title: z.ZodString;
-        subtitle: z.ZodOptional<z.ZodString>;
+        subtitle: z.ZodString;
         body: z.ZodOptional<z.ZodString>;
         bodyPath: z.ZodOptional<z.ZodString>;
         options: z.ZodArray<z.ZodObject<{
@@ -54,6 +54,7 @@ export declare const reviewDescriptorSchema: z.ZodObject<{
     file: z.ZodString;
     output: z.ZodString;
     title: z.ZodString;
+    subtitle: z.ZodString;
     source: z.ZodObject<{
         sessionName: z.ZodOptional<z.ZodString>;
         askedBy: z.ZodOptional<z.ZodString>;

package/dist/inbox/deck-schema.js

@@ -8,7 +8,7 @@ export const interactionOptionSchema = z.object({ id: z.string().min(1), label:
 export const preAnswerSchema = z.object({ selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), label: z.string().optional() });
 const interactionSchema = z.object({
     id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
-    title: z.string().trim().min(1), subtitle: z.string().min(1).optional(), body: z.string().optional(), bodyPath: z.string().optional(),
+    title: z.string().trim().min(1), subtitle: z.string().trim().min(1), body: z.string().optional(), bodyPath: z.string().optional(),
     options: z.array(interactionOptionSchema), multiSelect: z.boolean().optional(), allowFreetext: z.boolean().optional(), freetextLabel: z.string().optional(), kind: z.enum(INTERACTION_KINDS).optional(), preAnswered: preAnswerSchema.optional(),
 });
 const deckSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional(), visual: z.literal('humanloop.visual/v1').optional() });
@@ -27,7 +27,8 @@ export const reviewDescriptorSchema = z.object({
     schema: z.literal('humanloop.review/v1'),
     file: z.string().min(1).refine(isAbsolute, 'file must be absolute'),
     output: z.string().min(1).refine(isAbsolute, 'output must be absolute'),
-    title: z.string().min(1),
+    title: z.string().trim().min(1),
+    subtitle: z.string().trim().min(1),
     source: reviewSourceSchema,
     blockedSince: z.string().datetime({ offset: true }),
 }).strict();

package/dist/inbox/maintenance.js

@@ -4,7 +4,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { inboxRootsDirectory, listInboxRoots } from './registry.js';
 import { reconcileCompletions } from './completion.js';
-import { dispatchVisualCleanup, listVisualCleanupObligationsForRoot, reconcileStaleVisualRequestsForRoot } from './visual.js';
+import { dispatchVisualCleanup, listVisualCleanupObligationsForRoot } from './visual.js';
 const LEASE_STALE_MS = 300_000;
 function leasePath() { return join(dirname(inboxRootsDirectory()), 'maintenance.lock'); }
 function roots() { return listInboxRoots().filter((root) => root.available).map((root) => root.root); }
@@ -107,15 +107,6 @@ async function repairOnce() {
         }
         catch { /* receipt remains durable for the next pass */ }
     }
-    const retirements = allRoots.flatMap((root) => {
-        try {
-            return reconcileStaleVisualRequestsForRoot(root).map((entry) => entry.delivery);
-        }
-        catch {
-            return [];
-        }
-    });
-    await Promise.all(retirements);
     const tasks = dueTasks(allRoots);
     await Promise.all(tasks.filter((task) => Date.parse(task.nextAttemptAt) <= Date.now()).map((task) => dispatchVisualCleanup(task.root, task.dir, task.requestId)));
     return dueTasks(roots());

package/dist/inbox/scan.js

@@ -45,7 +45,7 @@ function reviewSummary(dir, id) {
     catch {
         return null;
     }
-    return { dir, id, kind: 'review', title: review.title, file: review.file, output: review.output, source: review.source, blockedSince: review.blockedSince, claim: claimSummary(dir) };
+    return { dir, id, kind: 'review', title: review.title, subtitle: review.subtitle, file: review.file, output: review.output, source: review.source, blockedSince: review.blockedSince, claim: claimSummary(dir) };
 }
 /** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
 export function scanInbox(roots) {

package/dist/inbox/tickets.js

@@ -124,7 +124,7 @@ export function submitReview(opts) {
     try {
         if (hasTicketProtocolState(dir))
             throw new Error(`ticket protocol state already exists: ${dir}`);
-        const descriptor = validateReviewProjection(dir, { schema: 'humanloop.review/v1', file: source, output: resolve(opts.review.output ?? `${dir}/feedback.json`), title: opts.review.title, source: opts.review.source, blockedSince: opts.review.blockedSince ?? new Date().toISOString() });
+        const descriptor = validateReviewProjection(dir, { schema: 'humanloop.review/v1', file: source, output: resolve(opts.review.output ?? `${dir}/feedback.json`), title: opts.review.title, subtitle: opts.review.subtitle, source: opts.review.source, blockedSince: opts.review.blockedSince ?? new Date().toISOString() });
         publishRequest(reviewPath(dir), descriptor);
         signalInboxActivity();
         return { id: opts.id, dir, kind: 'review' };

package/dist/inbox/tui.js

@@ -37,24 +37,14 @@ export function buildInboxLines(items, width, selectedIndex, height = Number.MAX
 function buildItemLines(item, index, selectedIndex, contentWidth) {
     const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
     const icon = KIND_ICON[kind] ?? '·';
-    // 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 ?? '';
+    // The inbox is a title-first triage surface. Origin details remain available
+    // after opening a ticket, rather than consuming the list's scarce row width.
     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')} `;
-    if (source)
-        row += `${ansiColor(source, 'yellow')} ${DIM}·${RESET} `;
-    row += `${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
-    if (item.claim)
-        return [row, `      ${DIM}${truncateRow(`claimed by ${item.claim.owner}`, contentWidth - 6)}${RESET}`];
-    if (item.subtitle)
-        return [row, `      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`];
-    return [row];
+    const titleWidth = Math.max(1, contentWidth - age.length - 6);
+    const row = `${cursor}${ansiColor(icon, KIND_COLOR[kind] ?? 'cyan')} ${BOLD}${truncateRow(item.title || `(${item.id.slice(0, 8)})`, titleWidth)}${RESET}  ${DIM}${age}${RESET}`;
+    const subtitle = item.claim ? `claimed by ${item.claim.owner} · ${item.subtitle}` : item.subtitle;
+    return [row, `      ${DIM}${truncateRow(subtitle, contentWidth - 6)}${RESET}`];
 }
 /** Select a contiguous row window that always contains the selected ticket. */
 function visibleWindow(rows, selectedIndex, capacity) {

package/dist/inbox/visual.d.ts

@@ -107,6 +107,9 @@ export declare function submitVisualResult(root: string, dir: string, raw: Visua
 export declare function dispatchVisualCleanup(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
 /** State-first cancellation for one handle; the returned promise is cleanup delivery only. */
 export declare function cancelVisualRequest(root: string, dir: string, requestId: string): Promise<VisualCleanupDeliveryResult>;
+/** Return the latest generation for one unchanged interaction. A canceled latest
+ * generation is authoritative and cannot resurrect an older completed result. */
+export declare function latestVisualRequestForInteraction(root: string, dir: string, interaction: Interaction | CanonicalInteraction): VisualProtocolRequest | null;
 /** State-first cancel every running request, then dispatch every owed cleanup (including start failures). */
 export declare function cancelVisualRequestsForTicket(root: string, dir: string): Promise<{
     canceled: number;
@@ -114,17 +117,6 @@ export declare function cancelVisualRequestsForTicket(root: string, dir: string)
 }>;
 /** Durable tasks the next controller-owned retry executor should schedule. */
 export declare function listVisualCleanupObligations(root: string, dir: string): VisualCleanupTask[];
-export interface VisualRequestReconciliation {
-    retired: number;
-    cleanupOwed: number;
-    /** Cleanup delivery only; reconciliation never redelivers a start. */
-    delivery: Promise<VisualCleanupDeliveryResult[]>;
-}
-/** Retire abandoned generations under the ticket claim boundary. A live claim is
- * authoritative; a newly acquired claim retires every older generation first. */
-export declare function reconcileVisualRequestsForTicket(root: string, dir: string, currentClaimToken?: string): VisualRequestReconciliation;
 /** Enumerate direct ticket children only, including resolved tickets whose cleanup is still owed. */
 export declare function listVisualCleanupObligationsForRoot(root: string): VisualCleanupTask[];
-/** Startup reconciliation only retires stale/missing-claim work; live owners stay untouched. */
-export declare function reconcileStaleVisualRequestsForRoot(root: string): VisualRequestReconciliation[];
 export {};