@north-light/api 0.3.580 → 0.3.588

package/dist/clients/inbox/controller.js

@@ -0,0 +1,816 @@
+import { existsSync, watch } from 'node:fs';
+import { visibleWidth } from '@earendil-works/pi-tui';
+import { renderMarkdown } from '../../core/termrender/termrender.js';
+import { BOLD, CYAN, DIM, GRAY, RESET, YELLOW, clipLine, singleLine, wrap } from './tui/ansi.js';
+import { buildInboxLines, recommendedLabel } from './tui.js';
+import { inboxLayout } from './layout.js';
+import { resolvePageComponents } from '../../core/config.js';
+import { watchInboxActivity } from '../../core/human/root.js';
+import { claimTicket, heartbeatClaim, releaseClaim } from '../../core/human/claim.js';
+import { claimPath, clearProgress } from '../../core/human/convention.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { cliClient } from '../../commands/api-client.js';
+import { projectPageDisplayMarkdown } from '../../core/human/page-markdown.js';
+import { projectHtmlDocumentMarkdown } from '../../core/human/page-html-markdown.js';
+import { pageBodyLines } from './tui/page-body.js';
+import { docLinksRevision } from '../attach/render/doc-links.js';
+import { byNewestFirst, inboxRowFromDTO, pageViewFromDTO, settledStatusOf } from './dto-adapt.js';
+import { PageAdapter } from './page-adapter.js';
+import { ReviewAdapter } from './review-adapter.js';
+import { createReviewClient } from './review/review-client.js';
+import { editBufferInEditor } from './review/roundtrip.js';
+import { daemonErrorMessage, dismissTicketViaDaemon, resolveFailureKind, resolveTicketPage, } from './resolve.js';
+/** Host-agnostic model for scanning, stable selection, claims, and rendering. */
+export class InboxController {
+    options;
+    host;
+    scan;
+    /** Every row the daemon's inbox leaves eligible. This, never the
+     *  profile-filtered list, decides whether a ticket has settled. */
+    items = [];
+    /** The eligible rows the current filter shows. */
+    visible = [];
+    profile;
+    filter;
+    /** Ticket dir the caller asked to open on, until the first scan can seat it. */
+    pendingSeat;
+    selectedDir;
+    /** Position hint into `visible`; the highlight itself is derived from
+     *  `selectedDir`, which an open detail may hold on a filtered-out ticket. */
+    selectedIndex = 0;
+    screen = 'list';
+    adapter;
+    reviewAdapter;
+    focusingSource = false;
+    claim;
+    submittingDir;
+    cancelConfirmation;
+    cols;
+    rows;
+    status;
+    /** Set while the latest refresh failed, so the list is known incomplete. */
+    refreshError;
+    watchers = [];
+    selectedWatcher;
+    heartbeat;
+    started = false;
+    closed = false;
+    /** The selected page's projection, kept across frames because fetching it is
+     *  a round trip. `view` is held so a width change re-wraps without one. */
+    preview;
+    /** A preview read that failed, so the panel says so instead of staying blank. */
+    previewFailed;
+    /** In-flight preview fetch, keyed by dir: one request per selection at a time. */
+    previewFetching;
+    /** Set by `invalidate`: the held preview may no longer be the current revision. */
+    previewStale = false;
+    /** The revision the open detail was loaded from, so a replacement published
+     *  while the reader has the page open reloads it. */
+    openRevision;
+    constructor(options) {
+        this.options = options;
+        this.host = options.host;
+        this.scan = options.scan ?? defaultScan;
+        this.cols = options.cols ?? 80;
+        this.rows = options.rows ?? 24;
+        this.profile = options.profile;
+        this.filter = options.profile === undefined ? 'all' : 'profile';
+        // Seeded before the first rescan, which preserves a selected dir it finds.
+        this.selectedDir = options.initialSelection;
+        this.pendingSeat = options.initialSelection;
+        void this.rescan();
+    }
+    snapshot() {
+        return { items: [...this.items], selectedDir: this.selectedDir, screen: this.screen, inputBuffer: this.adapter?.inputBuffer() };
+    }
+    async rescan() {
+        const priorDir = this.selectedDir;
+        const claim = this.claim;
+        // The row list is a round trip, and most rescans are fired from inbox
+        // activity with nobody awaiting them. A failed read keeps the rows already
+        // on screen and says so in the status line, rather than rejecting into a
+        // caller that cannot handle it.
+        try {
+            this.items = await this.scan();
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            this.status = daemonErrorMessage(error);
+            this.markDirty();
+            return;
+        }
+        if (this.closed)
+            return;
+        this.recomputeVisible();
+        if (this.pendingSeat !== undefined) {
+            const wanted = this.pendingSeat;
+            this.pendingSeat = undefined;
+            this.seatOn(wanted);
+        }
+        // Eligibility, never profile visibility, says whether the open ticket
+        // settled: a requester that left this profile still has a live ticket.
+        const eligible = priorDir !== undefined && this.items.some((item) => item.dir === priorDir);
+        if (!eligible && this.adapter !== undefined && priorDir !== undefined && claim !== undefined) {
+            const canceled = (await this.requestOrNull(claim.id))?.state === 'canceled';
+            if (this.closed)
+                return;
+            if (canceled)
+                clearProgress(priorDir);
+            // Suppress the "resolved elsewhere" banner when WE are the ones resolving
+            // this ticket: the settlement we just submitted drops the row from the
+            // scan mid-submit, and that is our own completion, not an external event.
+            if (priorDir !== this.submittingDir)
+                this.status = canceled ? 'canceled by requester' : 'ticket resolved elsewhere';
+            this.leaveDetail(priorDir !== this.submittingDir);
+        }
+        this.reseatSelection();
+    }
+    /** Apply the active filter to the eligible list. A ticket belongs to the
+     *  profile exactly when its requesting node is one of that profile's nodes;
+     *  an absent or unknown requester is reachable under all profiles only. */
+    recomputeVisible() {
+        if (this.filter === 'all' || this.profile === undefined) {
+            this.visible = this.items;
+            return;
+        }
+        const members = this.profile.members();
+        this.visible = this.items.filter((item) => {
+            const nodeId = item.source.nodeId;
+            return nodeId !== undefined && members.has(nodeId);
+        });
+    }
+    /** Put the highlight back on a visible row after the list or the filter
+     *  changed under it, keeping the same list position when the selected ticket
+     *  is gone. An open detail holds its own ticket instead, filtered out or not. */
+    reseatSelection() {
+        const found = this.selectedDir === undefined ? -1 : this.visible.findIndex((item) => item.dir === this.selectedDir);
+        if (found >= 0) {
+            this.selectedIndex = found;
+            return;
+        }
+        if (this.adapter !== undefined && this.selectedDir !== undefined
+            && this.items.some((item) => item.dir === this.selectedDir))
+            return;
+        if (this.visible.length === 0) {
+            this.selectedIndex = 0;
+            this.selectedDir = undefined;
+            return;
+        }
+        this.selectedIndex = Math.min(Math.max(0, this.selectedIndex), this.visible.length - 1);
+        this.selectedDir = this.visible[this.selectedIndex].dir;
+    }
+    /** Index of the highlighted row, or -1 while an open detail holds a ticket
+     *  the filter hides — no other row stands in for it. */
+    highlightIndex() {
+        if (this.selectedDir === undefined)
+            return -1;
+        return this.visible.findIndex((item) => item.dir === this.selectedDir);
+    }
+    /** The highlighted ticket, absent when no visible row is highlighted. */
+    currentRow() {
+        const index = this.highlightIndex();
+        return index >= 0 ? this.visible[index] : undefined;
+    }
+    scopeHeading() {
+        if (this.profile === undefined)
+            return { label: 'all profiles' };
+        return this.filter === 'profile'
+            ? { label: this.profile.label, hint: 'P all profiles' }
+            : { label: 'all profiles', hint: `P ${this.profile.label} only` };
+    }
+    /** Record how a surface refresh ended. A failure names itself while the last
+     *  complete list stays on screen — never an empty profile or a silent
+     *  widening — and the next successful refresh takes that notice away. */
+    refreshOutcome(error) {
+        this.refreshError = error;
+        if (error === undefined) {
+            void this.invalidate();
+            return;
+        }
+        this.markDirty();
+    }
+    start() {
+        if (this.started || this.closed)
+            return;
+        this.started = true;
+        this.watchRoots();
+        this.heartbeat = setInterval(() => {
+            if (this.claim !== undefined)
+                heartbeatClaim(this.claim.dir, this.claim.token);
+        }, 10_000);
+    }
+    /** Inbox activity is the one signal a replacement always emits, and it is
+     *  emitted after the new revision is selected — so an open page reloads here
+     *  rather than from a file watch that cannot see a directory swap. */
+    async invalidate() {
+        // Activity is the one signal a replacement always emits, and it fires after
+        // the new revision is selected — so the held preview and any open page are
+        // re-read from the daemon here rather than from a file watch, which cannot
+        // see a directory swap at all.
+        this.previewStale = true;
+        await this.rescan();
+        if (this.closed)
+            return;
+        if (this.adapter !== undefined && this.claim !== undefined) {
+            await this.reloadSelectedPage();
+            return;
+        }
+        this.markDirty();
+    }
+    resize(cols, rows) {
+        this.cols = cols;
+        this.rows = rows;
+        this.adapter?.resize(this.detailSize().cols, this.detailSize().rows);
+        this.markDirty();
+    }
+    render() {
+        const geometry = inboxLayout(this.cols, this.rows, this.screen);
+        if (geometry.mode === 'minimum')
+            return [`${YELLOW}Resize terminal to at least 60×18 to use inbox.${RESET}`];
+        const list = buildInboxLines(this.visible, geometry.listWidth, this.highlightIndex(), this.scopeHeading(), geometry.height);
+        const detail = this.detailLines(geometry.detailWidth, geometry.height);
+        if (geometry.mode === 'list')
+            return this.withStatus(list);
+        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++) {
+            // 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);
+            // Clip the detail column too: a 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}`);
+        }
+        return this.withStatus(lines);
+    }
+    handleKey(input, key) {
+        // Ctrl-C closes from every controller mode before adapter forwarding.
+        // The inbox toggle is a host action, never a surface key chord.
+        if (key.ctrl && input === 'c') {
+            this.close();
+            return;
+        }
+        if (this.screen === 'detail' && this.adapter !== undefined) {
+            if ((input === 'g' || input === 'G') && this.adapter.canAcceptHostKeys()) {
+                void this.focusSelectedSource();
+                return;
+            }
+            this.adapter.handleKey(input, key);
+            this.markDirty();
+            return;
+        }
+        if (this.cancelConfirmation !== undefined) {
+            if (input === 'y' || input === 'Y') {
+                const item = this.cancelConfirmation.item;
+                this.cancelConfirmation = undefined;
+                this.status = 'canceling…';
+                void this.cancelFromInbox(item);
+            }
+            else if (input === 'n' || input === 'N' || key.escape) {
+                this.cancelConfirmation = undefined;
+                this.status = undefined;
+            }
+            this.markDirty();
+            return;
+        }
+        if (input === 'P' && this.profile !== undefined) {
+            this.toggleProfileFilter();
+            this.markDirty();
+            return;
+        }
+        if (input === 'x' || input === 'X') {
+            const selected = this.currentRow();
+            if (selected !== undefined) {
+                this.cancelConfirmation = { item: selected };
+                this.status = undefined;
+            }
+            this.markDirty();
+            return;
+        }
+        if (input === 's' || input === 'S') {
+            void this.sendFastAction();
+            this.markDirty();
+            return;
+        }
+        if (key.escape || input === 'q') {
+            this.close();
+            return;
+        }
+        if (input === 'j' || key.downArrow)
+            this.select(this.selectedIndex + 1);
+        else if (input === 'k' || key.upArrow)
+            this.select(this.selectedIndex - 1);
+        else if (input === 'g' || input === 'G')
+            void this.focusSelectedSource();
+        else if (key.return || input === 'a')
+            void this.activate();
+        this.markDirty();
+    }
+    /** Swap between this profile's tickets and every eligible ticket. The mode
+     *  lives only until this inbox closes; the next open starts filtered again. */
+    toggleProfileFilter() {
+        this.filter = this.filter === 'profile' ? 'all' : 'profile';
+        this.recomputeVisible();
+        this.reseatSelection();
+    }
+    /** Settle the selected ticket from the list with what crouter already put on
+     *  its summary — the agent's recommended option, or a notice's empty map. A
+     *  row without a fast action says so rather than opening the page: the key
+     *  means one thing, and the page is what Enter is for. */
+    async sendFastAction() {
+        const item = this.currentRow();
+        if (item === undefined)
+            return;
+        if (item.kind !== 'page' || item.fastAction === undefined) {
+            this.status = 'no recommended answer on this ticket — Enter opens it';
+            return;
+        }
+        // Settlement is a daemon-owned state, so a claim still succeeds on a
+        // settled request's directory. The record decides whether this row is
+        // stale; only then does a refused claim mean another inbox holds it.
+        const request = await this.requestOrNull(item.id);
+        if (isSettled(request)) {
+            this.status = settledStatus(request);
+            await this.rescan();
+            return;
+        }
+        const claim = claimTicket(item.dir);
+        if (claim === null) {
+            this.status = 'ticket is being edited by another inbox';
+            return;
+        }
+        const settled = item.fastAction.kind === 'acknowledge'
+            ? 'acknowledged'
+            : `sent: ${recommendedLabel(item) ?? 'recommended answer'}`;
+        this.submittingDir = item.dir;
+        try {
+            await resolveTicketPage(item.id, item.fastAction.responses);
+            this.status = settled;
+        }
+        catch (error) {
+            this.status = resolveFailureKind(error) === 'already_settled'
+                ? settledStatus(await this.requestOrNull(item.id))
+                : daemonErrorMessage(error);
+        }
+        finally {
+            releaseClaim(item.dir, claim.token);
+            this.submittingDir = undefined;
+            await this.rescan();
+            this.markDirty();
+        }
+    }
+    /** A review and a page are two different durable records; the inbox dismisses
+     *  whichever one the selected row actually is. */
+    async cancelFromInbox(item) {
+        this.submittingDir = item.dir;
+        try {
+            if (item.kind === 'review')
+                await createReviewClient().cancel(item.id, 'Canceled from the inbox.');
+            else
+                await dismissTicketViaDaemon(item.id, { reason: 'Canceled from the inbox.', actor: 'human' });
+            this.status = 'canceled';
+        }
+        catch (error) {
+            this.status = daemonErrorMessage(error);
+        }
+        finally {
+            this.submittingDir = undefined;
+            await this.rescan();
+            this.markDirty();
+        }
+    }
+    async activate() {
+        const item = this.currentRow();
+        if (item === undefined)
+            return;
+        if (item.kind === 'review') {
+            await this.activateReview(item);
+            return;
+        }
+        const request = await this.requestOrNull(item.id);
+        if (this.closed)
+            return;
+        if (isSettled(request)) {
+            this.status = settledStatus(request);
+            await this.rescan();
+            return;
+        }
+        const claim = claimTicket(item.dir);
+        if (claim === null) {
+            this.status = 'ticket is being edited by another inbox';
+            return;
+        }
+        // One projection carries the revision AND the content it belongs to, so
+        // there is no window between reading the two in which a replacement lands.
+        let view;
+        let revision;
+        try {
+            const page = await cliClient().getHumanInboxPage(item.inboxTicketId);
+            // The claim is a presenter lock, not settlement authority, so a request
+            // that settled between the pre-claim check and this read would still
+            // claim. This projection already carries the state that decides it.
+            if (page.state === 'resolved' || page.state === 'canceled') {
+                releaseClaim(item.dir, claim.token);
+                this.status = settledStatusOf(page);
+                await this.rescan();
+                return;
+            }
+            view = pageViewFromDTO(page);
+            revision = page.revision;
+        }
+        catch {
+            releaseClaim(item.dir, claim.token);
+            this.status = 'page could not be read';
+            await this.invalidate();
+            return;
+        }
+        // Another activation (or a close) may have landed while this read was in
+        // flight; that one owns the detail screen, so this claim is released.
+        if (this.closed || this.claim !== undefined || this.adapter !== undefined) {
+            releaseClaim(item.dir, claim.token);
+            return;
+        }
+        this.claim = { dir: item.dir, id: item.id, ticketId: item.inboxTicketId, token: claim.token };
+        this.screen = 'detail';
+        this.adapter = new PageAdapter({
+            ticketId: item.inboxTicketId,
+            page: view,
+            productKinds: resolvePageComponents(),
+            cols: this.detailSize().cols,
+            rows: this.detailSize().rows,
+            onDirty: () => this.markDirty(),
+            onEditorRequest: () => this.editActivePageInput(),
+            onBack: () => { this.leaveDetail(); this.markDirty(); },
+            onComplete: (responses) => { void this.complete(responses); },
+        });
+        this.openRevision = revision;
+        this.watchSelected(item.dir);
+        this.markDirty();
+    }
+    /** A review opens in its own tmux window, which tmux selects at once, so
+     *  the inbox left behind in this pane has nothing more to do: it closes,
+     *  and returning to this window lands on the conversation beneath it. The
+     *  inbox stays up only when the window could not be opened, so its notice
+     *  is read where the person is looking. */
+    async activateReview(item) {
+        this.reviewAdapter = new ReviewAdapter({
+            reviewId: item.id,
+            host: this.host,
+        });
+        let opened = false;
+        try {
+            opened = await this.reviewAdapter.start();
+        }
+        catch (error) {
+            this.status = daemonErrorMessage(error);
+        }
+        finally {
+            this.reviewAdapter = undefined;
+        }
+        if (opened) {
+            this.close();
+            return;
+        }
+        await this.rescan();
+        this.markDirty();
+    }
+    /** Seat the selection on a ticket dir, when present in the current list. */
+    selectDir(dir) {
+        if (this.seatOn(dir))
+            this.markDirty();
+    }
+    /** Seat the selection on an eligible ticket, widening to all profiles when
+     *  the profile filter alone is what hides it — a caller that names a ticket
+     *  is promised that ticket, never a neighbouring one. */
+    seatOn(dir) {
+        let index = this.visible.findIndex((item) => item.dir === dir);
+        if (index < 0 && this.items.some((item) => item.dir === dir)) {
+            this.filter = 'all';
+            this.recomputeVisible();
+            index = this.visible.findIndex((item) => item.dir === dir);
+        }
+        if (index < 0)
+            return false;
+        this.select(index);
+        return true;
+    }
+    /** Re-read the open page and reload it only when its revision actually moved. */
+    async reloadSelectedPage() {
+        const claim = this.claim;
+        if (this.adapter === undefined || claim === undefined) {
+            this.markDirty();
+            return;
+        }
+        try {
+            const page = await cliClient().getHumanInboxPage(claim.ticketId);
+            if (this.closed || this.claim !== claim || this.adapter === undefined)
+                return;
+            if (page.revision !== this.openRevision) {
+                this.openRevision = page.revision;
+                this.adapter.reload(pageViewFromDTO(page));
+            }
+        }
+        catch {
+            this.status = 'page could not be read';
+        }
+        this.markDirty();
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.started = false;
+        if (this.heartbeat !== undefined)
+            clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+        void this.reviewAdapter?.stop();
+        this.leaveDetail(this.claim?.dir !== this.submittingDir);
+        for (const watcher of this.watchers)
+            watcher.close();
+        this.watchers = [];
+        this.selectedWatcher?.close();
+        this.selectedWatcher = undefined;
+        this.options.onClosed();
+    }
+    async complete(responses) {
+        const claim = this.claim;
+        if (claim === undefined)
+            return;
+        this.submittingDir = claim.dir;
+        try {
+            await resolveTicketPage(claim.id, responses);
+        }
+        catch (error) {
+            this.submittingDir = undefined;
+            this.status = daemonErrorMessage(error);
+            const failure = resolveFailureKind(error);
+            if (failure === 'unreachable' || failure === 'other') {
+                this.markDirty();
+                return;
+            }
+            if (failure === 'already_settled')
+                this.status = settledStatus(await this.requestOrNull(claim.id));
+            this.leaveDetail(false);
+            await this.rescan();
+            this.markDirty();
+            return;
+        }
+        this.submittingDir = undefined;
+        this.leaveDetail(false);
+        await this.rescan();
+        // A settled page whose row survives its own post-resolve rescan is the
+        // "row won't leave" defect. This records the truth at the exact moment the
+        // row should have dropped, so a live recurrence is diagnosable without a
+        // reproduction: did the request reach a terminal state, does the scan still
+        // list it, and was the claim left behind.
+        const stillListed = this.items.some((item) => item.dir === claim.dir);
+        emitEvent({
+            level: stillListed ? 'warn' : 'info',
+            event: 'inbox.page.resolved',
+            fields: {
+                ticket_id: claim.id,
+                request_settled: isSettled(await this.requestOrNull(claim.id)),
+                still_listed: stillListed,
+                claim_left_behind: existsSync(claimPath(claim.dir)),
+            },
+        });
+        this.markDirty();
+    }
+    /** Edit the active buffer while the host releases the terminal to $EDITOR. */
+    editActivePageInput() {
+        const buffer = this.adapter?.inputBuffer();
+        if (buffer === undefined)
+            return;
+        const resume = this.host.suspendForChild();
+        let result = { text: buffer };
+        try {
+            result = editBufferInEditor(buffer);
+        }
+        finally {
+            resume();
+            this.adapter?.setInputBuffer(result.text);
+            if (result.error !== undefined)
+                this.status = result.error;
+            this.markDirty();
+        }
+    }
+    leaveDetail(release = true) {
+        this.adapter?.close();
+        this.adapter = undefined;
+        this.selectedWatcher?.close();
+        this.selectedWatcher = undefined;
+        if (release && this.claim !== undefined)
+            releaseClaim(this.claim.dir, this.claim.token);
+        this.claim = undefined;
+        this.openRevision = undefined;
+        this.screen = 'list';
+        this.reseatSelection();
+    }
+    select(index) {
+        if (this.visible.length === 0)
+            return;
+        this.selectedIndex = Math.max(0, Math.min(index, this.visible.length - 1));
+        this.selectedDir = this.visible[this.selectedIndex].dir;
+    }
+    detailSize() {
+        const layout = inboxLayout(this.cols, this.rows, this.screen);
+        return { cols: Math.max(1, layout.detailWidth - 2), rows: layout.height };
+    }
+    detailLines(width, rows) {
+        if (this.adapter !== undefined)
+            return this.adapter.render();
+        const selected = this.currentRow();
+        if (selected === undefined)
+            return this.passiveDetailLines(width, rows);
+        const focusHint = this.focusAvailable(selected.dir) ? `  ${DIM}g${RESET} chat` : '';
+        const sendHint = selected.kind === 'page' && selected.fastAction !== undefined
+            ? `  ${DIM}s${RESET} ${selected.fastAction.kind === 'acknowledge' ? 'acknowledge' : 'send recommended'}`
+            : '';
+        const footer = selected.kind === 'page'
+            ? [`  ${DIM}Enter${RESET} opens the full page  ${DIM}↑↓/jk${RESET} select${sendHint}  ${DIM}x${RESET} cancel`, `  ${DIM}Page:${RESET} c comment  u/d scroll${focusHint}  ${DIM}q${RESET} close`]
+            : [`  ${DIM}Enter${RESET} opens the full review  ${DIM}↑↓/jk${RESET} select  ${DIM}x${RESET} cancel`, ` ${focusHint}  ${DIM}q${RESET} close`];
+        // The hints hold the bottom of the pane rather than trailing the preview,
+        // so they stay in one place as the preview grows and shrinks.
+        const room = Math.max(0, rows - footer.length);
+        const preview = this.passiveDetailLines(width, room);
+        while (preview.length < room)
+            preview.push('');
+        return [...preview, ...footer.map((line) => clipLine(line, width))];
+    }
+    focusAvailable(_dir) {
+        return this.host.capabilities.canFocusNode;
+    }
+    /** Ask the host to bring the requesting node's viewer into view — the
+     *  conversation that raised this ask. */
+    async focusSelectedSource() {
+        // In detail the open ticket is the source, even when the filter hides it.
+        const dir = this.screen === 'detail' ? this.claim?.dir : this.currentRow()?.dir;
+        const item = dir === undefined ? undefined : this.items.find((row) => row.dir === dir);
+        if (item === undefined || this.focusingSource)
+            return;
+        const requesterNodeId = item.source.nodeId;
+        if (requesterNodeId === undefined) {
+            this.status = 'This request was not raised by a canvas node';
+            this.markDirty();
+            return;
+        }
+        this.focusingSource = true;
+        try {
+            const focused = await this.host.focusNode(requesterNodeId);
+            if (focused)
+                this.close();
+            else {
+                this.status = 'Could not open that node’s viewer';
+                this.markDirty();
+            }
+        }
+        finally {
+            this.focusingSource = false;
+        }
+    }
+    /** What the selected page actually says. Rendering is synchronous and the
+     *  page is a round trip, so the projection is held and a miss schedules the
+     *  fetch, marking the frame dirty when it lands. A width change re-wraps the
+     *  held projection without another read. */
+    pagePreviewBody(item, width) {
+        const cached = this.preview;
+        if (cached !== undefined && cached.dir === item.dir) {
+            if (this.previewStale)
+                this.schedulePreview(item);
+            if (cached.width === width && cached.links === docLinksRevision())
+                return cached.lines;
+            const lines = previewLines(cached.view, width);
+            this.preview = { ...cached, width, links: docLinksRevision(), lines };
+            return lines;
+        }
+        this.schedulePreview(item);
+        // A failed read says so; an unfetched one is simply not there yet.
+        return this.previewFailed === item.dir ? [`${DIM}page could not be read${RESET}`] : [];
+    }
+    /** One in-flight preview read at a time. A revision that did not move keeps
+     *  the held projection, so activity on an unrelated ticket costs no re-wrap. */
+    schedulePreview(item) {
+        if (this.previewFetching === item.dir)
+            return;
+        this.previewFetching = item.dir;
+        this.previewStale = false;
+        void cliClient().getHumanInboxPage(item.inboxTicketId).then((page) => {
+            if (this.closed || this.previewFetching !== item.dir)
+                return;
+            this.previewFetching = undefined;
+            this.previewFailed = undefined;
+            if (this.preview?.dir === item.dir && this.preview.revision === page.revision)
+                return;
+            const view = pageViewFromDTO(page);
+            const width = this.preview?.width ?? inboxLayout(this.cols, this.rows, this.screen).detailWidth;
+            this.preview = { dir: item.dir, revision: page.revision, view, width, links: docLinksRevision(), lines: previewLines(view, width) };
+            this.markDirty();
+        }, () => {
+            if (this.closed || this.previewFetching !== item.dir)
+                return;
+            this.previewFetching = undefined;
+            this.previewFailed = item.dir;
+            // Never leave the prior page's body standing under this row's title.
+            if (this.preview?.dir === item.dir)
+                this.preview = undefined;
+            this.markDirty();
+        });
+    }
+    /** The request record is the settlement authority: a settled page publishes
+     *  no file, so a claim would still succeed on its directory. An unreachable
+     *  daemon reads as "not known to be settled" — the settle attempt that
+     *  follows is the one that fails loudly. */
+    async requestOrNull(id) {
+        try {
+            return await cliClient().getHumanRequest(id);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** The read-only preview beside the list. It shows the page's own content,
+     *  because `s` settles the selected ticket from here without ever opening
+     *  it — a reader must not answer something they were never shown. */
+    passiveDetailLines(width, rows) {
+        const selected = this.currentRow();
+        if (selected === undefined)
+            return [`  ${DIM}Select a pending interaction.${RESET}`];
+        const lines = [...wrap(singleLine(selected.title), Math.max(10, width - 2)).map((line) => `  ${BOLD}${CYAN}${line}${RESET}`), ''];
+        for (const rendered of renderMarkdown(selected.subtitle, Math.max(1, width - 2)))
+            lines.push(`  ${rendered}`);
+        const body = selected.kind === 'page' ? this.pagePreviewBody(selected, width) : [`${DIM}1 file to review${RESET}`];
+        if (body.length > 0) {
+            lines.push('');
+            const room = Math.max(0, rows - lines.length);
+            const shown = body.length <= room ? body : body.slice(0, Math.max(0, room - 1));
+            for (const line of shown)
+                lines.push(`  ${line}`);
+            if (shown.length < body.length)
+                lines.push(`  ${DIM}… +${body.length - shown.length} more lines${RESET}`);
+        }
+        return lines.map((line) => clipLine(line, width)).slice(0, Math.max(1, rows));
+    }
+    withStatus(lines) {
+        // A live prompt first, then a known-stale list, then the last action's
+        // result: an action message is history once a refresh has failed under it.
+        const status = this.cancelConfirmation === undefined
+            ? this.refreshError ?? this.status
+            : `cancel “${this.cancelConfirmation.item.title}”?  y yes · n/Esc no`;
+        if (status === undefined || this.rows < 1)
+            return lines;
+        const next = [...lines];
+        while (next.length < this.rows)
+            next.push('');
+        next[this.rows - 1] = `${YELLOW}${status}${RESET}`;
+        return next;
+    }
+    markDirty() {
+        this.options.onDirty();
+    }
+    watchRoots() {
+        const unsubscribe = watchInboxActivity(this.options.onInboxActivity ?? (() => { void this.invalidate(); }));
+        this.watchers.push({ close: unsubscribe });
+    }
+    /** The request directory still carries the claim and progress files other
+     *  inboxes write. Its page content lives in the daemon-selected revision,
+     *  which `invalidate` re-reads over the API. */
+    watchSelected(dir) {
+        this.selectedWatcher?.close();
+        try {
+            this.selectedWatcher = watch(dir, () => { void this.invalidate(); });
+        }
+        catch {
+            this.selectedWatcher = undefined;
+        }
+    }
+}
+/** The inbox the daemon lists IS the inbox: visibility, ordering and row
+ *  content all come from the one projection. */
+async function defaultScan() {
+    const { tickets } = await cliClient().listHumanInbox();
+    return tickets.map(inboxRowFromDTO).sort(byNewestFirst);
+}
+function previewLines(view, width) {
+    const display = view.manifest.dialect === 'html'
+        ? projectHtmlDocumentMarkdown(view.document)
+        : projectPageDisplayMarkdown(view.document, view.manifest);
+    return pageBodyLines(view.manifest, display, Math.min(Math.max(20, width - 4), 100), Math.max(20, width - 4));
+}
+/** A request the daemon no longer reports on is not known to be settled. */
+function isSettled(request) {
+    return request !== undefined && request.state !== 'pending';
+}
+/** Why a second settlement was refused, in the status line's own wording. */
+function settledStatus(request) {
+    if (request?.page === undefined)
+        return 'ticket was already resolved';
+    return settledStatusOf(request.page);
+}