@crouton-kit/humanloop 0.3.33 → 0.3.35

package/dist/inbox/completion.js

@@ -0,0 +1,107 @@
+import { readdirSync, statSync, unlinkSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { basename, resolve } from 'node:path';
+import { atomicWriteJson, deliveryErrorPath, deliveryPath, responsePath, readJson, reviewPath, withExclusiveDirectoryLockAsync } from './convention.js';
+import { registeredInboxRoot } from './registry.js';
+import { readTicketResult, ticketRoot } from './tickets.js';
+import { validateReviewProjection } from './deck-schema.js';
+function receiptMatches(dir) {
+    const receipt = readJson(deliveryPath(dir));
+    return receipt?.schema === 'humanloop.delivery/v1' && receipt.responsePath === responsePath(dir);
+}
+function eventFor(root, dir, result) {
+    return { schema: 'humanloop.completion/v1', root, dir, ticketId: basename(dir), kind: result.kind, outcome: result.kind === 'canceled' ? 'canceled' : 'resolved', responsePath: responsePath(dir) };
+}
+async function runHandler(command, args, event) {
+    await new Promise((resolvePromise, rejectPromise) => {
+        // stdout stays ignored (a handler acknowledges by exit code, never stdout),
+        // but stderr is captured so a nonzero exit surfaces the handler's own
+        // diagnostics in the delivery-error record instead of a bare exit code.
+        const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'pipe'] });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { stderr += chunk; if (stderr.length > 8192)
+            stderr = stderr.slice(-8192); });
+        let timedOut = false;
+        const timeout = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, 30_000);
+        child.once('error', (error) => { clearTimeout(timeout); rejectPromise(error); });
+        child.once('exit', (code, signal) => {
+            clearTimeout(timeout);
+            const detail = stderr.trim() === '' ? '' : `: ${stderr.trim()}`;
+            if (timedOut)
+                rejectPromise(new Error(`completion handler timed out after 30 seconds${detail}`));
+            else if (code === 0)
+                resolvePromise();
+            else
+                rejectPromise(new Error(`completion handler failed (${signal ?? code ?? 'unknown'})${detail}`));
+        });
+        child.stdin.end(`${JSON.stringify(event)}\n`);
+    });
+}
+function projectReview(dir, result) {
+    if (result.kind !== 'review')
+        return;
+    const descriptor = validateReviewProjection(dir, readJson(reviewPath(dir)));
+    atomicWriteJson(descriptor.output, result.result);
+}
+/** Deliver one canonical result. It is safe to call repeatedly after crashes. */
+export async function dispatchCompletion(root, dir) {
+    const registration = registeredInboxRoot(root);
+    const canonicalRoot = ticketRoot(dir);
+    if (registration === null || canonicalRoot !== registration.root)
+        throw new Error('ticket is not a canonical direct child of a registered root');
+    return withExclusiveDirectoryLockAsync(`${resolve(dir)}/.delivery-lock`, async () => {
+        const result = readTicketResult(dir);
+        if (result === null)
+            return 'none';
+        try {
+            projectReview(dir, result);
+        }
+        catch (error) {
+            atomicWriteJson(deliveryErrorPath(dir), { schema: 'humanloop.delivery-error/v1', responsePath: responsePath(dir), failedAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) });
+            return 'pending';
+        }
+        if (registration.handler === undefined)
+            return 'none';
+        if (receiptMatches(dir))
+            return 'delivered';
+        const event = eventFor(registration.root, resolve(dir), result);
+        try {
+            await runHandler(registration.handler.command, registration.handler.args, event);
+            atomicWriteJson(deliveryPath(dir), { schema: 'humanloop.delivery/v1', responsePath: event.responsePath, deliveredAt: new Date().toISOString() });
+            try {
+                unlinkSync(deliveryErrorPath(dir));
+            }
+            catch { /* no prior error */ }
+            return 'delivered';
+        }
+        catch (error) {
+            atomicWriteJson(deliveryErrorPath(dir), { schema: 'humanloop.delivery-error/v1', responsePath: event.responsePath, failedAt: new Date().toISOString(), error: error instanceof Error ? error.message : String(error) });
+            return 'pending';
+        }
+    });
+}
+/** Event-driven startup/root-change reconciliation for results lacking an ack. */
+export async function reconcileCompletions(root) {
+    const registration = registeredInboxRoot(root);
+    if (registration === null)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(registration.root);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const dir = resolve(registration.root, entry);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (ticketRoot(dir) === registration.root && readTicketResult(dir) !== null && !receiptMatches(dir))
+            await dispatchCompletion(registration.root, dir);
+    }
+}

package/dist/inbox/controller.d.ts

@@ -0,0 +1,74 @@
+import type { InteractionResponse, TicketSummary } from '../types.js';
+import type { Key } from '../tui/terminal.js';
+export interface InboxControllerOptions {
+    roots?: string[];
+    cols?: number;
+    rows?: number;
+    scan?: (roots?: string[]) => TicketSummary[];
+    completeDeck?: (dir: string, responses: InteractionResponse[], token: string) => Promise<unknown>;
+}
+type Screen = 'list' | 'detail';
+/** One terminal owner for scanning, stable selection, claims, and frame diffs. */
+export declare class InboxController {
+    private readonly options;
+    private readonly scan;
+    private readonly finishDeck;
+    private items;
+    private selectedDir;
+    private selectedIndex;
+    private screen;
+    private adapter;
+    private reviewAdapter;
+    private claim;
+    private reconciling;
+    private suspended;
+    private submittingDir;
+    private stdinListener;
+    private cols;
+    private rows;
+    private frame;
+    private status;
+    private watchers;
+    private selectedWatcher;
+    private closed;
+    private running;
+    private finishRun;
+    constructor(options?: InboxControllerOptions);
+    snapshot(): {
+        items: TicketSummary[];
+        selectedDir?: string;
+        screen: Screen;
+        inputBuffer?: string;
+    };
+    rescan(): void;
+    invalidate(): void;
+    resize(cols?: number, rows?: number): void;
+    render(): string[];
+    handleKey(input: string, key: Key): void;
+    activate(): void;
+    /** Claim the review, hand the whole popup TTY to the native editor, then
+     *  converge to the on-disk outcome when it exits. Draft/final ownership stays
+     *  in ReviewAdapter; the controller only owns the terminal handoff. */
+    private activateReview;
+    reloadSelectedDeck(): void;
+    close(): void;
+    run(): Promise<void>;
+    private complete;
+    /** Give the raw TTY to a child process (native review editor). */
+    private suspendForChild;
+    /** Retake the TTY after the child exits and force a full repaint. */
+    private resumeAfterChild;
+    private resolvedRoots;
+    /** Owner-boundary reconciliation for resolved results still lacking an ack.
+     *  Guarded so overlapping fs events cannot stack concurrent scans. */
+    private reconcileRoots;
+    private leaveDetail;
+    private select;
+    private detailSize;
+    private detailLines;
+    private withStatus;
+    private repaint;
+    private watchRoots;
+    private watchSelected;
+}
+export {};

package/dist/inbox/controller.js

@@ -0,0 +1,457 @@
+import { readFileSync, watch } from 'node:fs';
+import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
+import { diffFrame } from '../tui/render.js';
+import { renderMarkdown } from '../render/termrender.js';
+import { BOLD, CYAN, DIM, RESET, YELLOW } from '../tui/ansi.js';
+import { buildInboxLines } from './tui.js';
+import { inboxLayout } from './layout.js';
+import { scanInbox } from './scan.js';
+import { inboxRootsDirectory, listInboxRoots } from './registry.js';
+import { claimTicket, heartbeatClaim, releaseClaim } from './claim.js';
+import { completeDeck, readTicketResult } from './tickets.js';
+import { reconcileCompletions } from './completion.js';
+import { clearProgress, deckPath, progressPath, readJson, reviewPath } from './convention.js';
+import { DeckAdapter } from './deck-adapter.js';
+import { ReviewAdapter } from './review-adapter.js';
+/** One terminal owner for scanning, stable selection, claims, and frame diffs. */
+export class InboxController {
+    options;
+    scan;
+    finishDeck;
+    items = [];
+    selectedDir;
+    selectedIndex = 0;
+    screen = 'list';
+    adapter;
+    reviewAdapter;
+    claim;
+    reconciling = false;
+    suspended = false;
+    submittingDir;
+    stdinListener;
+    cols;
+    rows;
+    frame = [];
+    status;
+    watchers = [];
+    selectedWatcher;
+    closed = false;
+    running = false;
+    finishRun;
+    constructor(options = {}) {
+        this.options = options;
+        this.scan = options.scan ?? scanInbox;
+        this.finishDeck = options.completeDeck ?? completeDeck;
+        const size = getTerminalSize();
+        this.cols = options.cols ?? size.cols;
+        this.rows = options.rows ?? size.rows;
+        this.rescan();
+    }
+    snapshot() {
+        return { items: [...this.items], selectedDir: this.selectedDir, screen: this.screen, inputBuffer: this.adapter?.inputBuffer() };
+    }
+    rescan() {
+        const priorDir = this.selectedDir;
+        const priorIndex = this.selectedIndex;
+        this.items = this.scan(this.options.roots);
+        const found = priorDir === undefined ? -1 : this.items.findIndex((item) => item.dir === priorDir);
+        if (found >= 0) {
+            this.selectedIndex = found;
+            this.selectedDir = priorDir;
+            return;
+        }
+        if (this.adapter !== undefined && priorDir !== undefined) {
+            const canceled = readTicketResult(priorDir)?.kind === 'canceled';
+            if (canceled)
+                clearProgress(priorDir);
+            // Suppress the "resolved elsewhere" banner when WE are the ones resolving
+            // this ticket: the response.json we just published trips the root watch
+            // 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();
+        }
+        if (this.items.length === 0) {
+            this.selectedIndex = 0;
+            this.selectedDir = undefined;
+            return;
+        }
+        this.selectedIndex = Math.min(priorIndex, this.items.length - 1);
+        this.selectedDir = this.items[this.selectedIndex].dir;
+    }
+    invalidate() { this.rescan(); this.repaint(); }
+    resize(cols = getTerminalSize().cols, rows = getTerminalSize().rows) {
+        this.cols = cols;
+        this.rows = rows;
+        this.frame = [];
+        this.adapter?.resize(this.detailSize().cols, this.detailSize().rows);
+        this.repaint(true);
+    }
+    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.items, geometry.listWidth, this.selectedIndex);
+        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 = [];
+        for (let i = 0; i < geometry.height; i++) {
+            const left = list[i] ?? '';
+            const right = detail[i] ?? '';
+            lines.push(`${left}${' '.repeat(Math.max(1, geometry.listWidth - visibleWidth(left)))} ${right}`);
+        }
+        return this.withStatus(lines);
+    }
+    handleKey(input, key) {
+        // Option/Alt+I (M-i) and Ctrl-C request graceful close from ANY controller
+        // mode. A root-table binding cannot fire while the popup grabs client input,
+        // so the close-from-open path must live here — checked before adapter
+        // forwarding so it works in active deck freetext as well as the list.
+        if ((key.ctrl && input === 'c') || isToggleCloseChord(input)) {
+            this.close();
+            return;
+        }
+        if (this.screen === 'detail' && this.adapter !== undefined) {
+            this.adapter.handleKey(input, key);
+            this.repaint();
+            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 (key.return || input === 'a')
+            this.activate();
+        this.repaint();
+    }
+    activate() {
+        const item = this.items[this.selectedIndex];
+        if (item === undefined)
+            return;
+        if (item.kind === 'review') {
+            void this.activateReview(item);
+            return;
+        }
+        if (item.kind !== 'deck')
+            return;
+        const claim = claimTicket(item.dir);
+        if (claim === null) {
+            this.status = 'ticket is being edited by another inbox';
+            return;
+        }
+        this.claim = { dir: item.dir, token: claim.token };
+        const deck = readJson(deckPath(item.dir));
+        if (deck === null) {
+            releaseClaim(item.dir, claim.token);
+            this.claim = undefined;
+            this.invalidate();
+            return;
+        }
+        if (item.interactionKind === 'notify') {
+            void this.complete([{ id: deck.interactions[0]?.id ?? 'notify', selectedOptionId: deck.interactions[0]?.options[0]?.id }]);
+            return;
+        }
+        this.screen = 'detail';
+        this.adapter = new DeckAdapter({
+            dir: item.dir,
+            deck,
+            cols: this.detailSize().cols,
+            rows: this.detailSize().rows,
+            onDirty: () => this.repaint(),
+            onBack: () => { this.leaveDetail(); this.repaint(); },
+            onComplete: (responses) => { void this.complete(responses); },
+        });
+        this.watchSelected(item.dir);
+    }
+    /** Claim the review, hand the whole popup TTY to the native editor, then
+     *  converge to the on-disk outcome when it exits. Draft/final ownership stays
+     *  in ReviewAdapter; the controller only owns the terminal handoff. */
+    async activateReview(item) {
+        const claim = claimTicket(item.dir);
+        if (claim === null) {
+            this.status = 'ticket is being edited by another inbox';
+            this.repaint();
+            return;
+        }
+        const descriptor = readJson(reviewPath(item.dir));
+        if (descriptor === null) {
+            releaseClaim(item.dir, claim.token);
+            this.invalidate();
+            return;
+        }
+        let closeRequested = false;
+        this.reviewAdapter = new ReviewAdapter({ dir: item.dir, descriptor, claim, onClose: () => { closeRequested = true; } });
+        this.suspendForChild();
+        try {
+            await this.reviewAdapter.start();
+        }
+        catch (error) {
+            this.status = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            this.reviewAdapter = undefined;
+            // M-i inside native review is a graceful close of the WHOLE inbox: the
+            // adapter already saved the draft and released the claim, so just tear the
+            // controller down instead of returning to the list. The ticket stays
+            // pending because no submit flag was written.
+            if (closeRequested) {
+                this.suspended = false;
+                this.close();
+            }
+            else {
+                this.resumeAfterChild();
+                this.rescan();
+                this.reconcileRoots();
+                this.repaint(true);
+            }
+        }
+    }
+    reloadSelectedDeck() { this.adapter?.reload(); this.repaint(); }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        void this.reviewAdapter?.stop();
+        this.leaveDetail();
+        for (const watcher of this.watchers)
+            watcher.close();
+        this.watchers = [];
+        this.selectedWatcher?.close();
+        this.selectedWatcher = undefined;
+        this.finishRun?.();
+    }
+    async run() {
+        setupTerminal();
+        this.running = true;
+        this.watchRoots();
+        // Close the crash window between an earlier result publication and its
+        // handler launch: dispatch every resolved-but-undelivered ticket now.
+        this.reconcileRoots();
+        this.repaint(true);
+        const heartbeat = setInterval(() => {
+            if (this.claim !== undefined)
+                heartbeatClaim(this.claim.dir, this.claim.token);
+        }, 10_000);
+        await new Promise((resolve) => {
+            const onData = (data) => {
+                const { input, key } = parseKeypress(data);
+                this.handleKey(input, key);
+                if (this.closed)
+                    finish();
+            };
+            this.stdinListener = onData;
+            const onResize = () => this.resize();
+            let done = false;
+            this.finishRun = () => {
+                if (done)
+                    return;
+                done = true;
+                process.stdin.removeListener('data', onData);
+                this.stdinListener = undefined;
+                process.stdout.removeListener('resize', onResize);
+                clearInterval(heartbeat);
+                this.running = false;
+                this.finishRun = undefined;
+                restoreTerminal();
+                resolve();
+            };
+            const finish = this.finishRun;
+            process.stdin.on('data', onData);
+            process.stdout.on('resize', onResize);
+        });
+    }
+    async complete(responses) {
+        const claim = this.claim;
+        if (claim === undefined)
+            return;
+        this.submittingDir = claim.dir;
+        try {
+            await this.finishDeck(claim.dir, responses, claim.token);
+        }
+        catch (error) {
+            this.submittingDir = undefined;
+            this.status = error instanceof Error ? error.message : String(error);
+            return;
+        }
+        this.submittingDir = undefined;
+        this.leaveDetail(false);
+        this.rescan();
+        this.reconcileRoots();
+        this.repaint();
+    }
+    /** Give the raw TTY to a child process (native review editor). */
+    suspendForChild() {
+        this.suspended = true;
+        if (this.stdinListener !== undefined)
+            process.stdin.removeListener('data', this.stdinListener);
+        restoreTerminal();
+    }
+    /** Retake the TTY after the child exits and force a full repaint. */
+    resumeAfterChild() {
+        this.suspended = false;
+        if (this.closed)
+            return;
+        setupTerminal();
+        if (this.stdinListener !== undefined)
+            process.stdin.on('data', this.stdinListener);
+        this.frame = [];
+    }
+    resolvedRoots() {
+        return this.options.roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
+    }
+    /** Owner-boundary reconciliation for resolved results still lacking an ack.
+     *  Guarded so overlapping fs events cannot stack concurrent scans. */
+    reconcileRoots() {
+        if (this.reconciling)
+            return;
+        this.reconciling = true;
+        const roots = this.resolvedRoots();
+        void (async () => {
+            try {
+                for (const root of roots) {
+                    try {
+                        await reconcileCompletions(root);
+                    }
+                    catch { /* undelivered stays for the next pass */ }
+                }
+            }
+            finally {
+                this.reconciling = false;
+            }
+        })();
+    }
+    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.screen = 'list';
+    }
+    select(index) {
+        if (this.items.length === 0)
+            return;
+        this.selectedIndex = Math.max(0, Math.min(index, this.items.length - 1));
+        this.selectedDir = this.items[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.items[this.selectedIndex];
+        if (selected === undefined)
+            return [`  ${DIM}Select a pending interaction.${RESET}`];
+        const lines = [`  ${BOLD}${CYAN}${selected.title}${RESET}`, '', `  ${DIM}${selected.kind} · ${sourceLabel(selected.source)}${RESET}`];
+        if (selected.kind === 'review') {
+            lines.push('', `  ${DIM}${selected.file}${RESET}`);
+            const draft = readJson(progressPath(selected.dir))?.comments;
+            const draftCount = Array.isArray(draft) ? draft.length : 0;
+            lines.push(`  ${DIM}${draftCount} draft comment${draftCount === 1 ? '' : 's'}${RESET}`, '');
+            let md = '';
+            try {
+                md = readFileSync(selected.file, 'utf8');
+            }
+            catch {
+                md = '';
+            }
+            if (md === '')
+                lines.push(`  ${DIM}(source file unavailable)${RESET}`);
+            else
+                for (const rendered of renderMarkdown(md, Math.max(1, width - 2)))
+                    lines.push(`  ${rendered}`);
+            lines.push('', `  ${DIM}Enter${RESET} start review  ${DIM}j/k${RESET} select  ${DIM}q${RESET} close`);
+            while (lines.length < rows)
+                lines.push('');
+            // Rendered markdown carries ANSI; slicing by column count would sever
+            // escape sequences, so review preview lines are returned unsliced.
+            return lines;
+        }
+        if (selected.kind === 'deck') {
+            const deck = readJson(deckPath(selected.dir));
+            if (deck !== null) {
+                for (const interaction of deck.interactions) {
+                    lines.push('', `  ${BOLD}${interaction.title}${RESET}`);
+                    for (const option of interaction.options)
+                        lines.push(`    ${DIM}• ${option.label}${RESET}`);
+                }
+                const saved = readJson(progressPath(selected.dir))?.responses;
+                lines.push('', `  ${DIM}${Array.isArray(saved) ? saved.length : 0} saved responses${RESET}`);
+            }
+        }
+        if (selected.subtitle)
+            lines.push('', `  ${selected.subtitle}`);
+        lines.push('', `  ${DIM}Enter${RESET} open  ${DIM}j/k${RESET} select  ${DIM}q${RESET} close`);
+        while (lines.length < rows)
+            lines.push('');
+        return lines.map((line) => line.slice(0, width));
+    }
+    withStatus(lines) {
+        if (this.status === undefined || this.rows < 1)
+            return lines;
+        const next = [...lines];
+        while (next.length < this.rows)
+            next.push('');
+        next[this.rows - 1] = `${YELLOW}${this.status}${RESET}`;
+        return next;
+    }
+    repaint(clear = false) {
+        // While a child owns the TTY (native review), fs-watch invalidations must
+        // not scribble the inbox frame over the editor's screen.
+        if (this.closed || !this.running || this.suspended)
+            return;
+        if (clear)
+            process.stdout.write('\x1b[2J\x1b[H');
+        const diff = diffFrame(this.frame, this.render(), this.rows, this.cols);
+        process.stdout.write('\x1b[?2026h');
+        for (const write of diff.writes)
+            process.stdout.write(write);
+        process.stdout.write('\x1b[?2026l');
+        this.frame = diff.nextPrevFrame;
+    }
+    watchRoots() {
+        for (const root of this.resolvedRoots()) {
+            try {
+                this.watchers.push(watch(root, () => { this.invalidate(); this.reconcileRoots(); }));
+            }
+            catch { /* unavailable roots remain discoverable through later rescans */ }
+        }
+        if (this.options.roots === undefined) {
+            try {
+                this.watchers.push(watch(inboxRootsDirectory(), () => this.invalidate()));
+            }
+            catch { /* registry appears after the next explicit open */ }
+        }
+    }
+    watchSelected(dir) {
+        this.selectedWatcher?.close();
+        try {
+            this.selectedWatcher = watch(dir, (_event, file) => {
+                if (file === 'deck.json')
+                    this.reloadSelectedDeck();
+                else
+                    this.invalidate();
+            });
+        }
+        catch {
+            this.selectedWatcher = undefined;
+        }
+    }
+}
+function visibleWidth(line) { return line.replace(/\x1b\[[0-9;]*m/g, '').length; }
+/** M-i (Option/Alt+I) reaches the controller as the two-byte ESC-i sequence. */
+function isToggleCloseChord(input) { return input === '\x1bi' || input === '\x1bI'; }
+/** Prefer a human-meaningful source label, falling back to the raw node id
+ *  before an opaque "unknown source" — a crouter ticket always carries nodeId. */
+function sourceLabel(source) { return source.sessionName ?? source.askedBy ?? source.nodeId ?? 'unknown source'; }

package/dist/inbox/convention.d.ts

@@ -1,26 +1,31 @@
 import type { Deck, InteractionResponse } from '../types.js';
 export declare function deckPath(dir: string): string;
+export declare function reviewPath(dir: string): string;
 export declare function responsePath(dir: string): string;
 export declare function progressPath(dir: string): string;
+export declare function claimPath(dir: string): string;
+export declare function deliveryPath(dir: string): string;
+export declare function deliveryErrorPath(dir: string): string;
 export declare function visualsDir(dir: string): string;
 export declare function visualMdPath(dir: string, id: string): string;
 export declare function visualAnsiPath(dir: string, id: string): string;
-export type InteractionState = 'pending' | 'in-progress' | 'resolved' | 'missing';
+export type InteractionState = 'pending' | 'claimed' | 'resolved' | 'missing';
 export declare function interactionState(dir: string): InteractionState;
 export declare function isResolved(dir: string): boolean;
-/** Returns true if a live resolver owns this dir (progress.json mtime < 300s). */
 export declare function isClaimed(dir: string): boolean;
-/**
- * Stamp the originating canvas node id onto a deck's `source` so per-node
- * attention scoping (crouter's nav chrome) can attribute the ask to the node
- * that raised it rather than every sibling node sharing the same cwd.
- *
- * No-op when not inside a canvas node (CRTR_NODE_ID unset) or when the deck
- * already carries a nodeId. Mutates `deck` in place.
- */
 export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 export declare function readJson<T>(path: string): T | null;
+/** Runs a short filesystem transition under a token-checked, crash-reclaimable directory lock. */
+export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: {
+    staleMs?: number;
+    timeoutMs?: number;
+}): T;
+/** Async counterpart heartbeats while its operation runs, so a valid long handler is never stolen. */
+export declare function withExclusiveDirectoryLockAsync<T>(path: string, operation: () => Promise<T>, options?: {
+    staleMs?: number;
+    timeoutMs?: number;
+}): Promise<T>;
 export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string, deck?: Deck): string;
 export declare function writeProgress(dir: string, responses: InteractionResponse[]): void;
 export declare function clearProgress(dir: string): void;