@crouton-kit/humanloop 0.4.9 → 0.4.10

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);
             },
         };
     }

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/tui.js

@@ -37,19 +37,12 @@ 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}`;
+    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}`;
     if (item.claim)
         return [row, `      ${DIM}${truncateRow(`claimed by ${item.claim.owner}`, contentWidth - 6)}${RESET}`];
     if (item.subtitle)

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 {};

package/dist/inbox/visual.js

@@ -5,7 +5,7 @@ import { INTERACTION_KINDS } from '../types.js';
 import { checkMarkdown } from '../render/termrender.js';
 import { atomicWriteJson, deckPath, publishJsonExclusive, readJson, runHandler, visualsDir, withExclusiveDirectoryLock, withExclusiveDirectoryLockAsync, } from './convention.js';
 import { parseDeck } from './deck-schema.js';
-import { isStaleClaim, readTicketClaim, withTicketLock } from './claim.js';
+import { readTicketClaim, withTicketLock } from './claim.js';
 import { registeredInboxRoot } from './registry.js';
 import { requireCanonicalTicket } from './tickets.js';
 export const VISUAL_CAPABILITY = 'humanloop.visual/v1';
@@ -643,6 +643,17 @@ function requestIdsForTicket(root, dir) {
         return [];
     return readdirSync(parent).filter((entry) => uuid.safeParse(entry).success).sort();
 }
+/** Return the latest generation for one unchanged interaction. A canceled latest
+ * generation is authoritative and cannot resurrect an older completed result. */
+export function latestVisualRequestForInteraction(root, dir, interaction) {
+    const canonical = canonicalInteractionJson(interaction);
+    const requests = requestIdsForTicket(root, dir)
+        .map((requestId) => readVisualRequest(root, dir, requestId))
+        .filter((request) => request !== null && request.interactionId === interaction.id && canonicalInteractionJson(request.interaction) === canonical)
+        .sort((left, right) => left.requestedAt.localeCompare(right.requestedAt) || left.requestId.localeCompare(right.requestId));
+    const latest = requests.at(-1);
+    return latest !== undefined && latest.state !== 'canceled' ? latest : null;
+}
 /** State-first cancel every running request, then dispatch every owed cleanup (including start failures). */
 export function cancelVisualRequestsForTicket(root, dir) {
     const requests = requestIdsForTicket(root, dir).map((requestId) => ({ requestId, canceled: stateFirstCancel(root, dir, requestId) }));
@@ -664,35 +675,6 @@ export function listVisualCleanupObligations(root, dir) {
     }
     return tasks.sort((left, right) => left.nextAttemptAt.localeCompare(right.nextAttemptAt) || left.requestId.localeCompare(right.requestId));
 }
-/** Retire abandoned generations under the ticket claim boundary. A live claim is
- * authoritative; a newly acquired claim retires every older generation first. */
-export function reconcileVisualRequestsForTicket(root, dir, currentClaimToken) {
-    const ticket = requireCanonicalTicket(root, dir);
-    const reconciled = withTicketLock(ticket.dir, () => {
-        const claim = readTicketClaim(ticket.dir);
-        if (currentClaimToken !== undefined) {
-            uuid.parse(currentClaimToken);
-            if (claim?.token !== currentClaimToken)
-                return { retired: 0, owed: [] };
-        }
-        else if (claim !== null && !isStaleClaim(claim)) {
-            return { retired: 0, owed: [] };
-        }
-        const entries = requestIdsForTicket(ticket.root, ticket.dir).map((requestId) => {
-            const request = readVisualRequest(ticket.root, ticket.dir, requestId);
-            if (request === null || (currentClaimToken !== undefined && request.claim.token === currentClaimToken))
-                return { requestId, canceled: null };
-            return { requestId, canceled: stateFirstCancel(ticket.root, ticket.dir, requestId) };
-        });
-        const owed = entries.filter((entry) => entry.canceled?.owed === true).map((entry) => entry.requestId);
-        return { retired: entries.filter((entry) => entry.canceled?.changed === true).length, owed };
-    });
-    return {
-        retired: reconciled.retired,
-        cleanupOwed: reconciled.owed.length,
-        delivery: Promise.all(reconciled.owed.map((requestId) => dispatchVisualCleanup(ticket.root, ticket.dir, requestId))),
-    };
-}
 /** Enumerate direct ticket children only, including resolved tickets whose cleanup is still owed. */
 export function listVisualCleanupObligationsForRoot(root) {
     const registration = registeredInboxRoot(root);
@@ -719,29 +701,3 @@ export function listVisualCleanupObligationsForRoot(root) {
     }
     return tasks.sort((left, right) => left.nextAttemptAt.localeCompare(right.nextAttemptAt) || left.dir.localeCompare(right.dir) || left.requestId.localeCompare(right.requestId));
 }
-/** Startup reconciliation only retires stale/missing-claim work; live owners stay untouched. */
-export function reconcileStaleVisualRequestsForRoot(root) {
-    const registration = registeredInboxRoot(root);
-    if (registration === null)
-        return [];
-    const reconciled = [];
-    for (const entry of readdirSync(registration.root)) {
-        const candidate = resolve(registration.root, entry);
-        let dir;
-        try {
-            if (!statSync(candidate).isDirectory())
-                continue;
-            dir = realpathSync(candidate);
-        }
-        catch {
-            continue;
-        }
-        if (dirname(dir) !== registration.root)
-            continue;
-        try {
-            reconciled.push(reconcileVisualRequestsForTicket(registration.root, dir));
-        }
-        catch { /* unrelated or malformed children have no protocol obligation */ }
-    }
-    return reconciled;
-}

package/dist/index.d.ts

@@ -14,8 +14,8 @@ export type { SubmitDeckOptions, SubmitReviewOptions } from './inbox/tickets.js'
 export { dispatchCompletion, reconcileCompletions } from './inbox/completion.js';
 export { requestFollowUp, cancelFollowUp, submitFollowUpResult, readFollowUp } from './inbox/followup.js';
 export type { FollowUpRequestEvent, FollowUpRequest, FollowUpResult } from './inbox/followup.js';
-export { VISUAL_CAPABILITY, canonicalizeInteraction, canonicalInteractionJson, parseVisualRequestEvent, readVisualRequest, readVisualResult, readVisualRequestForEvent, startVisualRequest, submitVisualResult, cancelVisualRequest, cancelVisualRequestsForTicket, dispatchVisualCleanup, listVisualCleanupObligations, listVisualCleanupObligationsForRoot, reconcileVisualRequestsForTicket, reconcileStaleVisualRequestsForRoot, } from './inbox/visual.js';
-export type { VisualClaimIdentity, VisualCleanupObligation, VisualProtocolRequest, VisualRequestEvent, VisualProtocolResult, VisualResultSubmission, StartVisualRequestOptions, StartedVisualRequest, VisualStartDeliveryResult, VisualCleanupDeliveryResult, VisualCleanupTask, VisualRequestReconciliation, } from './inbox/visual.js';
+export { VISUAL_CAPABILITY, canonicalizeInteraction, canonicalInteractionJson, parseVisualRequestEvent, readVisualRequest, readVisualResult, readVisualRequestForEvent, startVisualRequest, submitVisualResult, cancelVisualRequest, cancelVisualRequestsForTicket, dispatchVisualCleanup, listVisualCleanupObligations, listVisualCleanupObligationsForRoot, latestVisualRequestForInteraction, } from './inbox/visual.js';
+export type { VisualClaimIdentity, VisualCleanupObligation, VisualProtocolRequest, VisualRequestEvent, VisualProtocolResult, VisualResultSubmission, StartVisualRequestOptions, StartedVisualRequest, VisualStartDeliveryResult, VisualCleanupDeliveryResult, VisualCleanupTask, } from './inbox/visual.js';
 export { claimTicket, heartbeatClaim, releaseClaim, readTicketClaim } from './inbox/claim.js';
 export type { TicketClaim, ClaimOptions } from './inbox/claim.js';
 export { renderMarkdown, checkMarkdown, ensureRenderer, isRendererReady, } from './render/termrender.js';

package/dist/index.js

@@ -11,7 +11,7 @@ export { registerInboxRoot, unregisterInboxRoot, listInboxRoots, managedInboxRoo
 export { submitDeck, submitReview, readTicketResult, finalizeDeck, finalizeReview, completeDeck, completeReview, cancelTicket, cancelTicketResult, } from './inbox/tickets.js';
 export { dispatchCompletion, reconcileCompletions } from './inbox/completion.js';
 export { requestFollowUp, cancelFollowUp, submitFollowUpResult, readFollowUp } from './inbox/followup.js';
-export { VISUAL_CAPABILITY, canonicalizeInteraction, canonicalInteractionJson, parseVisualRequestEvent, readVisualRequest, readVisualResult, readVisualRequestForEvent, startVisualRequest, submitVisualResult, cancelVisualRequest, cancelVisualRequestsForTicket, dispatchVisualCleanup, listVisualCleanupObligations, listVisualCleanupObligationsForRoot, reconcileVisualRequestsForTicket, reconcileStaleVisualRequestsForRoot, } from './inbox/visual.js';
+export { VISUAL_CAPABILITY, canonicalizeInteraction, canonicalInteractionJson, parseVisualRequestEvent, readVisualRequest, readVisualResult, readVisualRequestForEvent, startVisualRequest, submitVisualResult, cancelVisualRequest, cancelVisualRequestsForTicket, dispatchVisualCleanup, listVisualCleanupObligations, listVisualCleanupObligationsForRoot, latestVisualRequestForInteraction, } from './inbox/visual.js';
 export { claimTicket, heartbeatClaim, releaseClaim, readTicketClaim } from './inbox/claim.js';
 // Renderer binding — the sole org-wide termrender caller. Consumers
 // (sisyphus md-render / ask-schema) route markdown through these.

package/dist/render/termrender.d.ts

@@ -26,8 +26,10 @@ export interface RenderedDoc {
      *  (a bullet, a table row, a code line…); null for separator rows and rows
      *  of unmapped blocks. Same length as `lines`. */
     spans: ([number, number] | null)[];
-    /** Per top-level block: 1-indexed inclusive source-line bounds. Never empty. */
+    /** Per top-level block: its termrender block type plus 1-indexed inclusive
+     *  source-line bounds. Never empty. */
     blocks: {
+        type: string;
         start: number;
         end: number;
     }[];
@@ -35,6 +37,21 @@ export interface RenderedDoc {
 /** Render markdown with a row→source-line map via the pinned binary
  *  (`doc render --line-map`); plaintext paragraph-block fallback. */
 export declare function renderMarkdownWithMap(md: string, width: number): RenderedDoc;
+/**
+ * The shared block-aware mapped render: prose blocks keep the readability cap
+ * (`proseWidth`), while diagram blocks are re-rendered at the pane's full
+ * `paneWidth` and spliced back in by block index. Both surfaces (terminal
+ * review and the ask deck) go through this, so "which blocks may be wide" is
+ * decided once, from the renderer's own block types, never by heuristics on
+ * the emitted rows.
+ *
+ * Row order, block list and source spans are the narrow render's; only the
+ * rows OF a wide block are replaced, so anchoring stays source-based and
+ * unchanged.
+ */
+export declare function renderMarkdownBlockAware(md: string, proseWidth: number, paneWidth: number): RenderedDoc;
+/** Block-aware render as plain rows, for surfaces that do not anchor. */
+export declare function renderMarkdownBlockAwareLines(md: string, proseWidth: number, paneWidth: number): string[];
 /** Validate markdown via `termrender doc check`. */
 export declare function checkMarkdown(md: string): {
     ok: true;