@crouton-kit/humanloop 0.3.33 → 0.3.34

package/dist/inbox/scan.js

@@ -1,62 +1,90 @@
-import { readdirSync, statSync } from 'fs';
-import { resolve, basename } from 'path';
-import { deckPath, isResolved, isClaimed, readJson } from './convention.js';
-// ── scanInbox ─────────────────────────────────────────────────────────────────
+import { readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { claimPath, deckPath, isResolved, readJson, reviewPath } from './convention.js';
+import { validateDeck, validateReviewDescriptor } from './deck-schema.js';
+import { listInboxRoots } from './registry.js';
+function claimSummary(dir) {
+    const claim = readJson(claimPath(dir));
+    if (claim === null || typeof claim.host !== 'string' || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
+        return undefined;
+    return { owner: claim.host, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt };
+}
+function deckSummary(dir, id) {
+    const raw = readJson(deckPath(dir));
+    if (raw === null)
+        return null;
+    let deck;
+    try {
+        deck = validateDeck(raw);
+    }
+    catch {
+        return null;
+    }
+    const first = deck.interactions[0];
+    if (first === undefined)
+        return null;
+    let blockedSince = deck.source?.blockedSince;
+    if (blockedSince === undefined) {
+        try {
+            blockedSince = statSync(deckPath(dir)).mtime.toISOString();
+        }
+        catch {
+            return null;
+        }
+    }
+    return { dir, id, kind: 'deck', title: deck.title ?? first.title, subtitle: first.subtitle, interactionKind: first.kind, source: deck.source ?? {}, blockedSince, claim: claimSummary(dir) };
+}
+function reviewSummary(dir, id) {
+    const raw = readJson(reviewPath(dir));
+    if (raw === null)
+        return null;
+    let review;
+    try {
+        review = validateReviewDescriptor(raw);
+    }
+    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) };
+}
+/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
 export function scanInbox(roots) {
+    const selectedRoots = roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
+    const seen = new Set();
     const items = [];
-    for (const root of roots) {
+    for (const root of selectedRoots) {
+        let canonicalRoot;
+        try {
+            canonicalRoot = realpathSync(root);
+        }
+        catch {
+            continue;
+        }
         let entries;
         try {
-            entries = readdirSync(root);
+            entries = readdirSync(canonicalRoot);
         }
         catch {
-            // root doesn't exist or isn't readable — skip silently
             continue;
         }
         for (const entry of entries) {
-            const dir = resolve(root, entry);
+            const dir = resolve(canonicalRoot, entry);
+            let canonicalDir;
             try {
-                const stat = statSync(dir);
-                if (!stat.isDirectory())
+                if (!statSync(dir).isDirectory())
                     continue;
+                canonicalDir = realpathSync(dir);
             }
             catch {
                 continue;
             }
-            // Skip resolved or actively claimed dirs
-            if (isResolved(dir) || isClaimed(dir))
-                continue;
-            const dp = deckPath(dir);
-            const deck = readJson(dp);
-            if (deck === null)
+            if (resolve(canonicalDir, '..') !== canonicalRoot || seen.has(canonicalDir) || isResolved(canonicalDir))
                 continue;
-            // Derive blockedSince: prefer deck.source.blockedSince, fall back to mtime
-            let blockedSince;
-            if (deck.source?.blockedSince !== undefined) {
-                blockedSince = deck.source.blockedSince;
-            }
-            else {
-                try {
-                    blockedSince = new Date(statSync(dp).mtime).toISOString();
-                }
-                catch {
-                    blockedSince = new Date().toISOString();
-                }
-            }
-            const firstInteraction = deck.interactions[0];
-            const item = {
-                dir,
-                id: firstInteraction?.id ?? basename(dir),
-                title: deck.title ?? firstInteraction?.title,
-                subtitle: firstInteraction?.subtitle,
-                kind: firstInteraction?.kind,
-                source: deck.source,
-                blockedSince,
-            };
-            items.push(item);
+            seen.add(canonicalDir);
+            const item = deckSummary(canonicalDir, basename(canonicalDir)) ?? reviewSummary(canonicalDir, basename(canonicalDir));
+            if (item !== null)
+                items.push(item);
         }
     }
-    // Sort ascending by blockedSince (ISO string compare is monotonic)
-    items.sort((a, b) => (a.blockedSince < b.blockedSince ? -1 : a.blockedSince > b.blockedSince ? 1 : 0));
-    return items;
+    return items.sort((a, b) => b.blockedSince.localeCompare(a.blockedSince) || a.id.localeCompare(b.id));
 }

package/dist/inbox/tickets.d.ts

@@ -0,0 +1,63 @@
+import type { Deck, DeckTicketResult, FeedbackResult, ReviewDescriptor, TicketResult } from '../types.js';
+/** Strict decoder for the only canonical final marker. */
+export declare function readTicketResult(dirOrResponsePath: string): TicketResult | null;
+export interface SubmitDeckOptions {
+    root: string;
+    id: string;
+    deck: Deck;
+}
+export declare function submitDeck(opts: SubmitDeckOptions): {
+    id: string;
+    dir: string;
+    kind: 'deck';
+};
+export interface SubmitReviewOptions {
+    root: string;
+    id: string;
+    review: Omit<ReviewDescriptor, 'schema' | 'file' | 'output' | 'blockedSince'> & {
+        file: string;
+        output?: string;
+        blockedSince?: string;
+    };
+}
+export declare function submitReview(opts: SubmitReviewOptions): {
+    id: string;
+    dir: string;
+    kind: 'review';
+};
+export declare function finalizeDeck(dir: string, responses: DeckTicketResult['responses'], claimToken: string, completedAt?: string): {
+    won: boolean;
+    result: TicketResult;
+};
+export declare function finalizeReview(dir: string, feedback: FeedbackResult, claimToken: string, completedAt?: string): {
+    won: boolean;
+    result: TicketResult;
+    descriptor: ReviewDescriptor;
+};
+export declare function cancelTicketResult(dir: string, opts?: {
+    reason?: string;
+    actor?: string;
+}): {
+    status: 'canceled' | 'already_resolved';
+    result: TicketResult;
+};
+export declare function ticketRoot(dir: string): string | null;
+/** Finalize and immediately cross the trusted root completion boundary. */
+export declare function completeDeck(dir: string, responses: DeckTicketResult['responses'], claimToken: string): Promise<{
+    won: boolean;
+    result: TicketResult;
+}>;
+/** Finalize a review, then let completion own its projection and notification boundary. */
+export declare function completeReview(dir: string, feedback: FeedbackResult, claimToken: string): Promise<{
+    won: boolean;
+    result: TicketResult;
+    descriptor: ReviewDescriptor;
+}>;
+/** Cancellation races finalization but never requires or removes another claim. */
+export declare function cancelTicket(dir: string, opts?: {
+    reason?: string;
+    actor?: string;
+}): Promise<{
+    status: 'canceled' | 'already_resolved';
+    result: TicketResult;
+}>;

package/dist/inbox/tickets.js

@@ -0,0 +1,247 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import { z } from 'zod';
+import { buildSummary } from '../summary.js';
+import { clearProgress, claimPath, deckPath, deliveryErrorPath, deliveryPath, progressPath, responsePath, reviewPath } from './convention.js';
+import { validateDeck, validateReviewDescriptor, validateReviewProjection, resolveDeckBodyPaths } from './deck-schema.js';
+import { registeredInboxRoot } from './registry.js';
+import { readTicketClaim, releaseClaimLocked, withTicketLock } from './claim.js';
+import { dispatchCompletion } from './completion.js';
+const ticketId = z.string().regex(/^[A-Za-z0-9_-]+$/).min(1).max(128);
+const responseSchema = z.object({ id: z.string().min(1), selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), optionComments: z.record(z.string(), z.string()).optional() }).strict();
+const feedbackCommentSchema = z.object({ id: z.string().min(1), line: z.number().int().positive(), endLine: z.number().int().positive(), quote: z.string().optional(), colStart: z.number().int().nonnegative().optional(), colEnd: z.number().int().nonnegative().optional(), lineText: z.string(), comment: z.string().min(1), createdAt: z.string().min(1) }).strict();
+const iso = z.string().datetime({ offset: true });
+const feedbackSchema = z.object({ file: z.string().min(1).refine(isAbsolute, 'file must be absolute').refine((file) => resolve(file) === file, 'file must be canonical'), submitted: z.literal(true), approved: z.boolean(), comments: z.array(feedbackCommentSchema), submittedAt: iso, savedAt: iso }).strict().superRefine((result, ctx) => {
+    if (result.approved !== (result.comments.length === 0))
+        ctx.addIssue({ code: 'custom', message: 'approved must match empty comments' });
+    result.comments.forEach((comment, index) => {
+        if (comment.endLine < comment.line)
+            ctx.addIssue({ code: 'custom', message: 'endLine must be >= line', path: ['comments', index, 'endLine'] });
+        if ((comment.colStart === undefined) !== (comment.colEnd === undefined))
+            ctx.addIssue({ code: 'custom', message: 'columns must be supplied together', path: ['comments', index] });
+        if (comment.line === comment.endLine && comment.colStart !== undefined && comment.colEnd !== undefined && comment.colEnd <= comment.colStart)
+            ctx.addIssue({ code: 'custom', message: 'colEnd must exceed colStart', path: ['comments', index, 'colEnd'] });
+    });
+});
+const deckResultSchema = z.object({ schema: z.literal('humanloop.response/v2'), kind: z.literal('deck'), responses: z.array(responseSchema), summary: z.string(), completedAt: iso }).strict();
+const reviewResultSchema = z.object({ schema: z.literal('humanloop.review-response/v1'), kind: z.literal('review'), result: feedbackSchema, completedAt: iso }).strict();
+const canceledResultSchema = z.object({ schema: z.literal('humanloop.cancel/v1'), kind: z.literal('canceled'), canceledAt: iso, reason: z.string().optional(), actor: z.string().optional() }).strict();
+/** Strict decoder for the only canonical final marker. */
+export function readTicketResult(dirOrResponsePath) {
+    const path = basename(dirOrResponsePath) === 'response.json' ? dirOrResponsePath : responsePath(dirOrResponsePath);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    const parsed = deckResultSchema.safeParse(raw);
+    if (parsed.success)
+        return parsed.data;
+    const review = reviewResultSchema.safeParse(raw);
+    if (review.success)
+        return review.data;
+    const canceled = canceledResultSchema.safeParse(raw);
+    return canceled.success ? canceled.data : null;
+}
+function rootAndDir(root, id) {
+    const registration = registeredInboxRoot(root);
+    if (registration === null)
+        throw new Error('interaction root is not registered');
+    const parsedId = ticketId.parse(id);
+    const dir = resolve(registration.root, parsedId);
+    if (dirname(dir) !== registration.root)
+        throw new Error('ticket directory must be a direct child of its registered root');
+    return { root: registration.root, dir };
+}
+function ticketDir(root, id) {
+    const candidate = rootAndDir(root, id);
+    let created = false;
+    if (!existsSync(candidate.dir)) {
+        mkdirSync(candidate.dir, { mode: 0o700 });
+        created = true;
+    }
+    const dir = realpathSync(candidate.dir);
+    if (dirname(dir) !== candidate.root)
+        throw new Error('ticket directory must canonically be a direct child of its registered root');
+    return { dir, created };
+}
+function discardCreatedTicket(dir, created) { if (created)
+    rmSync(dir, { recursive: true, force: true }); }
+function hasTicketProtocolState(dir) {
+    return [deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir)].some(existsSync);
+}
+function requireRegisteredTicket(dir) {
+    const canonical = realpathSync(dir);
+    const root = dirname(canonical);
+    const registration = registeredInboxRoot(root);
+    if (registration === null || registration.root !== root || basename(canonical) === '')
+        throw new Error('ticket must be a canonical direct child of a registered root');
+    if (!existsSync(deckPath(canonical)) && !existsSync(reviewPath(canonical)))
+        throw new Error('ticket has no request descriptor');
+    return { root, dir: canonical };
+}
+function publishRequest(path, value) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    try {
+        linkSync(temp, path);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error(`ticket request already exists: ${path}`);
+        throw error;
+    }
+    finally {
+        unlinkSync(temp);
+    }
+}
+export function submitDeck(opts) {
+    // Validate shape before mutating caller-owned interaction directories.
+    validateDeck(opts.deck);
+    const { dir, created } = ticketDir(opts.root, opts.id);
+    try {
+        if (hasTicketProtocolState(dir))
+            throw new Error(`ticket protocol state already exists: ${dir}`);
+        const deck = validateDeck(resolveDeckBodyPaths(opts.deck, dir));
+        const stamped = { ...deck, source: { ...(deck.source ?? {}), blockedSince: deck.source?.blockedSince ?? new Date().toISOString() } };
+        publishRequest(deckPath(dir), stamped);
+        return { id: opts.id, dir, kind: 'deck' };
+    }
+    catch (error) {
+        discardCreatedTicket(dir, created);
+        throw error;
+    }
+}
+export function submitReview(opts) {
+    if (!isAbsolute(opts.review.file) || !existsSync(opts.review.file))
+        throw new Error('review file must be an existing absolute markdown file');
+    if (!/\.md(?:own)?$/i.test(opts.review.file))
+        throw new Error('review file must be markdown');
+    const source = realpathSync(opts.review.file);
+    const { dir, created } = ticketDir(opts.root, opts.id);
+    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() });
+        publishRequest(reviewPath(dir), descriptor);
+        return { id: opts.id, dir, kind: 'review' };
+    }
+    catch (error) {
+        discardCreatedTicket(dir, created);
+        throw error;
+    }
+}
+function exclusiveResult(dir, result) {
+    const path = responsePath(dir);
+    const temp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
+    try {
+        linkSync(temp, path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        unlinkSync(temp);
+    }
+}
+function requireDeck(dir) { return validateDeck(JSON.parse(readFileSync(deckPath(dir), 'utf8'))); }
+function requireReview(dir) { return validateReviewDescriptor(JSON.parse(readFileSync(reviewPath(dir), 'utf8'))); }
+function validateDeckResponses(deck, raw) {
+    const responses = z.array(responseSchema).parse(raw);
+    const interactions = new Map(deck.interactions.map((interaction) => [interaction.id, interaction]));
+    const seen = new Set();
+    for (const response of responses) {
+        const interaction = interactions.get(response.id);
+        if (interaction === undefined || seen.has(response.id))
+            throw new Error(`response does not match a unique deck interaction: ${response.id}`);
+        seen.add(response.id);
+        const optionIds = new Set(interaction.options.map((option) => option.id));
+        if (response.selectedOptionId !== undefined && (!optionIds.has(response.selectedOptionId) || interaction.multiSelect === true))
+            throw new Error(`invalid single-select response for ${response.id}`);
+        if (response.selectedOptionIds !== undefined && (interaction.multiSelect !== true || response.selectedOptionIds.some((id) => !optionIds.has(id)) || new Set(response.selectedOptionIds).size !== response.selectedOptionIds.length))
+            throw new Error(`invalid multi-select response for ${response.id}`);
+        if (response.freetext !== undefined && interaction.allowFreetext !== true)
+            throw new Error(`freetext is not allowed for ${response.id}`);
+        if (response.optionComments !== undefined && (interaction.multiSelect !== true || Object.keys(response.optionComments).some((id) => !optionIds.has(id))))
+            throw new Error(`invalid option comments for ${response.id}`);
+    }
+    return responses;
+}
+function requireClaimOwnership(dir, token) {
+    if (readTicketClaim(dir)?.token !== token)
+        throw new Error('only the current claim holder may submit a result');
+}
+function clearOwnedWork(dir, claimToken) { clearProgress(dir); releaseClaimLocked(dir, claimToken); }
+export function finalizeDeck(dir, responses, claimToken, completedAt = new Date().toISOString()) {
+    const ticket = requireRegisteredTicket(dir);
+    return withTicketLock(ticket.dir, () => {
+        requireClaimOwnership(ticket.dir, claimToken);
+        const deck = requireDeck(ticket.dir);
+        const parsedResponses = validateDeckResponses(deck, responses);
+        const result = { schema: 'humanloop.response/v2', kind: 'deck', responses: parsedResponses, summary: buildSummary(deck, parsedResponses), completedAt };
+        const won = exclusiveResult(ticket.dir, result);
+        clearOwnedWork(ticket.dir, claimToken);
+        return { won, result: won ? result : readTicketResult(ticket.dir) ?? result };
+    });
+}
+export function finalizeReview(dir, feedback, claimToken, completedAt = new Date().toISOString()) {
+    const ticket = requireRegisteredTicket(dir);
+    return withTicketLock(ticket.dir, () => {
+        requireClaimOwnership(ticket.dir, claimToken);
+        const descriptor = requireReview(ticket.dir);
+        const parsed = feedbackSchema.parse(feedback);
+        if (realpathSync(parsed.file) !== descriptor.file)
+            throw new Error('review result file does not match descriptor');
+        const result = { schema: 'humanloop.review-response/v1', kind: 'review', result: parsed, completedAt };
+        const won = exclusiveResult(ticket.dir, result);
+        clearOwnedWork(ticket.dir, claimToken);
+        return { won, result: won ? result : readTicketResult(ticket.dir) ?? result, descriptor };
+    });
+}
+export function cancelTicketResult(dir, opts = {}) {
+    const ticket = requireRegisteredTicket(dir);
+    return withTicketLock(ticket.dir, () => {
+        const result = { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: new Date().toISOString(), ...(opts.reason === undefined ? {} : { reason: opts.reason }), ...(opts.actor === undefined ? {} : { actor: opts.actor }) };
+        const won = exclusiveResult(ticket.dir, result);
+        return { status: won ? 'canceled' : 'already_resolved', result: won ? result : readTicketResult(ticket.dir) ?? result };
+    });
+}
+export function ticketRoot(dir) {
+    try {
+        return requireRegisteredTicket(dir).root;
+    }
+    catch {
+        return null;
+    }
+}
+/** Finalize and immediately cross the trusted root completion boundary. */
+export async function completeDeck(dir, responses, claimToken) {
+    const completed = finalizeDeck(dir, responses, claimToken);
+    const root = ticketRoot(dir);
+    if (completed.won && root !== null)
+        await dispatchCompletion(root, dir);
+    return completed;
+}
+/** Finalize a review, then let completion own its projection and notification boundary. */
+export async function completeReview(dir, feedback, claimToken) {
+    const completed = finalizeReview(dir, feedback, claimToken);
+    const root = ticketRoot(dir);
+    if (completed.won && root !== null)
+        await dispatchCompletion(root, dir);
+    return completed;
+}
+/** Cancellation races finalization but never requires or removes another claim. */
+export async function cancelTicket(dir, opts = {}) {
+    const canceled = cancelTicketResult(dir, opts);
+    const root = ticketRoot(dir);
+    if (canceled.status === 'canceled' && root !== null)
+        await dispatchCompletion(root, dir);
+    return canceled;
+}

package/dist/inbox/tui.d.ts

@@ -1,9 +1,6 @@
-import type { InboxItem } from '../types.js';
+import type { TicketSummary } from '../types.js';
 export declare const KIND_ICON: Record<string, string>;
 export declare const KIND_COLOR: Record<string, string>;
 export declare function formatTimeAgo(iso: string): string;
-export declare function buildInboxLines(items: InboxItem[], width: number, selectedIndex: number): string[];
-export declare function pickFromInbox(items: InboxItem[], opts: {
-    cols: number;
-    rows: number;
-}): Promise<InboxItem | null>;
+/** Pure inbox rows; selection and terminal ownership belong to InboxController. */
+export declare function buildInboxLines(items: TicketSummary[], width: number, selectedIndex: number): string[];

package/dist/inbox/tui.js

@@ -1,7 +1,4 @@
-import { setupTerminal, restoreTerminal, parseKeypress, getTerminalSize, } from '../tui/terminal.js';
-import { diffFrame } from '../tui/render.js';
 import { RESET, BOLD, DIM, ITALIC, CYAN, RED, GRAY, YELLOW, truncateRow } from '../tui/ansi.js';
-// ── ANSI helpers (local to this module) ──────────────────────────────────────
 function ansiColor(text, color) {
     switch (color) {
         case 'gray': return `${GRAY}${text}${RESET}`;
@@ -11,124 +8,39 @@ function ansiColor(text, color) {
         default: return text;
     }
 }
-// ── Row model (ported verbatim from sisyphus cross-session-inbox.ts:8-21) ────
-export const KIND_ICON = {
-    notify: '✉',
-    decision: '◆',
-    context: '✎',
-    error: '⚠',
-};
-export const KIND_COLOR = {
-    notify: 'gray',
-    decision: 'cyan',
-    context: 'cyan',
-    error: 'red',
-};
-// ── formatTimeAgo (ported from sisyphus src/tui/lib/format.ts:5-12) ──────────
+export const KIND_ICON = { notify: '✉', decision: '◆', context: '✎', error: '⚠', review: '▤' };
+export const KIND_COLOR = { notify: 'gray', decision: 'cyan', context: 'cyan', error: 'red', review: 'yellow' };
 export function formatTimeAgo(iso) {
-    const diff = Date.now() - new Date(iso).getTime();
-    const minutes = Math.floor(diff / 60000);
-    const hours = Math.floor(minutes / 60);
-    if (hours > 0)
-        return `${hours}h ago`;
+    const minutes = Math.floor((Date.now() - new Date(iso).getTime()) / 60000);
+    if (minutes >= 60)
+        return `${Math.floor(minutes / 60)}h ago`;
     if (minutes > 0)
         return `${minutes}m ago`;
     return 'just now';
 }
-// ── buildInboxLines ───────────────────────────────────────────────────────────
+/** Pure inbox rows; selection and terminal ownership belong to InboxController. */
 export function buildInboxLines(items, width, selectedIndex) {
-    const lines = [];
-    if (items.length === 0) {
-        lines.push(`  ${DIM}${ITALIC}No pending interactions${RESET}`);
-        return lines;
-    }
-    lines.push(`  ${BOLD}${items.length} pending${RESET}`);
-    lines.push('');
+    if (items.length === 0)
+        return [`  ${DIM}${ITALIC}No pending interactions${RESET}`];
+    const lines = [`  ${BOLD}${items.length} pending${RESET}`, ''];
     const contentWidth = width - 4;
-    for (let i = 0; i < items.length; i++) {
-        const item = items[i];
-        const kindKey = item.kind ?? '';
-        const icon = kindKey in KIND_ICON ? KIND_ICON[kindKey] : '·';
-        const iconColor = kindKey in KIND_COLOR ? KIND_COLOR[kindKey] : 'cyan';
-        const sourceLabel = item.source?.sessionName ?? item.source?.askedBy ?? '';
-        const titleText = item.title ?? `(${item.id.slice(0, 8)})`;
-        const blocked = formatTimeAgo(item.blockedSince);
-        const cursor = i === selectedIndex ? `${CYAN}▸${RESET} ` : '  ';
-        const maxTitle = Math.max(10, contentWidth - sourceLabel.length - blocked.length - 8);
-        let row = cursor;
-        row += ansiColor(icon, iconColor);
-        if (sourceLabel) {
-            row += ` ${ansiColor(sourceLabel, 'yellow')}`;
-            row += ` ${DIM}·${RESET} `;
-        }
-        else {
-            row += ' ';
-        }
-        row += `${BOLD}${truncateRow(titleText, maxTitle)}${RESET}`;
-        row += `  ${DIM}${blocked}${RESET}`;
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        const kind = item.kind === 'deck' ? item.interactionKind ?? 'decision' : 'review';
+        const icon = KIND_ICON[kind] ?? '·';
+        const source = item.source.sessionName ?? item.source.askedBy ?? '';
+        const age = formatTimeAgo(item.blockedSince);
+        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}`;
         lines.push(row);
-        if (item.subtitle) {
+        if (item.claim)
+            lines.push(`      ${DIM}claimed by ${item.claim.owner}${RESET}`);
+        else if (item.subtitle)
             lines.push(`      ${DIM}${truncateRow(item.subtitle, contentWidth - 6)}${RESET}`);
-        }
     }
     return lines;
 }
-// ── pickFromInbox ─────────────────────────────────────────────────────────────
-export function pickFromInbox(items, opts) {
-    if (items.length === 0)
-        return Promise.resolve(null);
-    return new Promise((resolve) => {
-        let selectedIndex = 0;
-        let prevFrame = [];
-        let onData;
-        const flush = () => {
-            const { cols: currentCols, rows: currentRows } = getTerminalSize();
-            const lines = buildInboxLines(items, currentCols, selectedIndex);
-            const { writes, nextPrevFrame } = diffFrame(prevFrame, lines, currentRows, currentCols);
-            process.stdout.write('\x1b[?2026h');
-            for (const w of writes)
-                process.stdout.write(w);
-            process.stdout.write('\x1b[?2026l');
-            prevFrame = nextPrevFrame;
-        };
-        // Resize reflows/scrolls what's already on screen, invalidating the diff
-        // model — clear and redraw from scratch at the new size.
-        const onResize = () => {
-            prevFrame = [];
-            process.stdout.write('\x1b[2J\x1b[H');
-            flush();
-        };
-        const done = (result) => {
-            restoreTerminal();
-            process.stdin.removeListener('data', onData);
-            process.stdout.removeListener('resize', onResize);
-            resolve(result);
-        };
-        setupTerminal();
-        flush();
-        onData = (data) => {
-            const { input, key } = parseKeypress(data);
-            if (key.downArrow || input === 'j') {
-                selectedIndex = Math.min(selectedIndex + 1, items.length - 1);
-                flush();
-                return;
-            }
-            if (key.upArrow || input === 'k') {
-                selectedIndex = Math.max(selectedIndex - 1, 0);
-                flush();
-                return;
-            }
-            if (key.return) {
-                const selected = items[selectedIndex];
-                done(selected ?? null);
-                return;
-            }
-            if (key.escape || (key.ctrl && input === 'c') || input === 'q') {
-                done(null);
-                return;
-            }
-        };
-        process.stdin.on('data', onData);
-        process.stdout.on('resize', onResize);
-    });
-}

package/dist/index.d.ts

@@ -3,15 +3,24 @@ export { defaultGenerateVisual } from './visuals/generate.js';
 export { launchReview } from './editor/review.js';
 export { launchReview as review } from './editor/review.js';
 export type { ReviewOptions } from './editor/review.js';
-export { ask, notify, inbox } from './api.js';
+export { ask, notify, openInbox } from './api.js';
+export { openInboxPopup } from './surfaces/inbox-popup.js';
+export { toggleInboxPopup, installInboxBinding, inspectInboxBinding, unbindInboxBinding, inboxPopupStyle } from './tui/tmux.js';
 export { display } from './surfaces/display.js';
 export { scanInbox } from './inbox/scan.js';
+export { registerInboxRoot, unregisterInboxRoot, listInboxRoots, managedInboxRoot } from './inbox/registry.js';
+export type { CompletionHandler, InboxRootRegistration, InboxRootStatus, RegisterInboxRootOptions } from './inbox/registry.js';
+export { submitDeck, submitReview, readTicketResult, finalizeDeck, finalizeReview, completeDeck, completeReview, cancelTicket, cancelTicketResult, } from './inbox/tickets.js';
+export type { SubmitDeckOptions, SubmitReviewOptions } from './inbox/tickets.js';
+export { dispatchCompletion, reconcileCompletions } from './inbox/completion.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';
 export { parseDeck, validateDeck, deckSchema, resolveDeckBodyPaths } from './inbox/deck-schema.js';
 export { notifyDeck } from './inbox/deck-factories.js';
 export type { NotifyDeckOpts } from './inbox/deck-factories.js';
-export { deckPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';
+export { deckPath, reviewPath, responsePath, progressPath, visualsDir, interactionState, isResolved, isClaimed, atomicWriteJson, readJson, writeResponse, writeProgress, clearProgress, } from './inbox/convention.js';
 export type { InteractionState } from './inbox/convention.js';
-export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, } from './types.js';
+export type { Interaction, InteractionOption, InteractionResponse, InteractionKind, Deck, DeckSource, MountedPanel, MountedPanelOpts, GenerateVisual, VisualBlock, FeedbackComment, FeedbackResult, ResolutionEnvelope, InboxItem, DisplayOpts, ClaimSummary, TicketSummary, DeckTicketSummary, ReviewTicketSummary, ReviewDescriptor, DeckTicketResult, ReviewTicketResult, CanceledTicketResult, TicketResult, InboxBindingState, CompletionEvent, } from './types.js';
 export type { Key } from './tui/terminal.js';
 export type { ConversationMessage } from './conversation/reader.js';