@crouton-kit/humanloop 0.3.33 → 0.3.34

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

@@ -0,0 +1,27 @@
+import type { Deck, InteractionResponse } from '../types.js';
+import type { Key } from '../tui/terminal.js';
+export interface DeckAdapterOptions {
+    dir: string;
+    deck: Deck;
+    cols: number;
+    rows: number;
+    onProgress?: (responses: InteractionResponse[]) => void;
+    onComplete: (responses: InteractionResponse[]) => void;
+    onBack: () => void;
+    onDirty: () => void;
+}
+/** Embeds the single deck renderer in a controller-owned rectangle. */
+export declare class DeckAdapter {
+    private readonly opts;
+    private panel;
+    private responses;
+    constructor(opts: DeckAdapterOptions);
+    render(): string[];
+    resize(cols: number, rows: number): string[];
+    inputBuffer(): string | undefined;
+    canAcceptHostKeys(): boolean;
+    handleKey(input: string, key: Key): void;
+    /** Fresh descriptor reads preserve mounted answers for interaction ids still present. */
+    reload(): void;
+    close(): void;
+}

package/dist/inbox/deck-adapter.js

@@ -0,0 +1,57 @@
+import { readFileSync } from 'node:fs';
+import { deckPath, progressPath, readJson } from './convention.js';
+import { validateDeck } from './deck-schema.js';
+import { mountPanel } from '../tui/app.js';
+/** Embeds the single deck renderer in a controller-owned rectangle. */
+export class DeckAdapter {
+    opts;
+    panel;
+    responses = [];
+    constructor(opts) {
+        this.opts = opts;
+        this.responses = initialResponses(opts.deck, opts.dir);
+        this.panel = mountPanel({
+            deck: opts.deck,
+            progressPath: progressPath(opts.dir),
+            cols: opts.cols,
+            rows: opts.rows,
+            onProgress: (responses) => { this.responses = responses; opts.onProgress?.(responses); },
+            onComplete: opts.onComplete,
+            onExit: () => opts.onComplete(this.responses),
+            onDirty: opts.onDirty,
+        });
+    }
+    render() { return this.panel.render(); }
+    resize(cols, rows) { return this.panel.handleResize(cols, rows); }
+    inputBuffer() { return this.panel.getInputBuffer(); }
+    canAcceptHostKeys() { return this.panel.canAcceptHostKeys(); }
+    handleKey(input, key) {
+        if (key.escape && this.panel.atDeckTop()) {
+            this.opts.onBack();
+            return;
+        }
+        this.panel.handleKey(input, key);
+    }
+    /** Fresh descriptor reads preserve mounted answers for interaction ids still present. */
+    reload() {
+        try {
+            this.panel.loadDeck(validateDeck(JSON.parse(readFileSync(deckPath(this.opts.dir), 'utf8'))), { progressPath: progressPath(this.opts.dir) });
+            this.opts.onDirty();
+        }
+        catch {
+            // An incomplete external rewrite is not a new deck; retain the current editor.
+        }
+    }
+    close() { this.panel.unmount(); }
+}
+function initialResponses(deck, dir) {
+    const saved = readJson(progressPath(dir))?.responses;
+    if (Array.isArray(saved))
+        return saved;
+    return deck.interactions.flatMap((interaction) => {
+        const answer = interaction.preAnswered;
+        if (answer === undefined)
+            return [];
+        return [{ id: interaction.id, ...(answer.selectedOptionId === undefined ? {} : { selectedOptionId: answer.selectedOptionId }), ...(answer.selectedOptionIds === undefined ? {} : { selectedOptionIds: [...answer.selectedOptionIds] }), ...(answer.freetext === undefined ? {} : { freetext: answer.freetext }) }];
+    });
+}

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { Deck } from '../types.js';
+import type { Deck, ReviewDescriptor } from '../types.js';
 export declare const interactionOptionSchema: z.ZodObject<{
     id: z.ZodString;
     label: z.ZodString;
@@ -48,18 +48,22 @@ export declare const deckSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-/**
- * The ONE canonical `bodyPath` → `body` normalization boundary. Resolves every
- * interaction's `bodyPath` (relative to `dir`, the interaction directory) into
- * `body` and strips `bodyPath` from the result.
- *
- * Call this once, right before a deck is (re)written to `<dir>/deck.json` —
- * `hl deck ask`, `hl deck update`, and the public `ask()` API all do — so
- * every reader downstream (the terminal TUI's render + its live-reload
- * poller, the browser server's `/api/interaction`) only ever sees a plain
- * `body` and never has to special-case `bodyPath` itself. `parseDeck` (below)
- * reuses this same function when reading a deck straight off disk.
- */
+export declare const reviewDescriptorSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"humanloop.review/v1">;
+    file: z.ZodString;
+    output: z.ZodString;
+    title: z.ZodString;
+    source: z.ZodObject<{
+        sessionName: z.ZodOptional<z.ZodString>;
+        askedBy: z.ZodOptional<z.ZodString>;
+        blockedSince: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    blockedSince: z.ZodString;
+}, z.core.$strict>;
 export declare function resolveDeckBodyPaths(deck: Deck, dir: string): Deck;
-export declare function parseDeck(deckPath: string): Deck;
+export declare function parseDeck(path: string): Deck;
 export declare function validateDeck(parsed: unknown): Deck;
+export declare function validateReviewDescriptor(parsed: unknown): ReviewDescriptor;
+/** Canonicalize and authorize the one review projection boundary before every write. */
+export declare function validateReviewProjection(dir: string, parsed: unknown): ReviewDescriptor;

package/dist/inbox/deck-schema.js

@@ -1,143 +1,85 @@
 import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
-import { dirname, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, resolve, sep } from 'node:path';
+import { claimPath, deckPath, deliveryErrorPath, deliveryPath, progressPath, responsePath, reviewPath } from './convention.js';
 import { z } from 'zod';
 import { INTERACTION_KINDS } from '../types.js';
 import { checkMarkdown } from '../render/termrender.js';
-// ── zod v4 building blocks ────────────────────────────────────────────────────
-// v4 notes: .nonempty() → .min(1); error messages use {error: 'string'} per check.
-export const interactionOptionSchema = z.object({
-    id: z.string().min(1),
-    label: z.string().min(1),
-    description: z.string().optional(),
-    // No author-settable `shortcut`: option shortcuts are auto-assigned by the
-    // TUI (assignShortcuts). zod strips unknown keys, so any author-supplied
-    // `shortcut` is silently dropped here — this is the enforcement boundary that
-    // stops a deck from shadowing a reserved key (e.g. `c` = comment).
-});
-export const preAnswerSchema = z.object({
-    selectedOptionId: z.string().optional(),
-    selectedOptionIds: z.array(z.string()).optional(),
-    freetext: z.string().optional(),
-    label: z.string().optional(),
-});
+export const interactionOptionSchema = z.object({ id: z.string().min(1), label: z.string().min(1), description: z.string().optional() });
+export const preAnswerSchema = z.object({ selectedOptionId: z.string().optional(), selectedOptionIds: z.array(z.string()).optional(), freetext: z.string().optional(), label: z.string().optional() });
 const interactionSchema = z.object({
     id: z.string().regex(/^[A-Za-z0-9_-]+$/, { error: 'interaction id must match /^[A-Za-z0-9_-]+$/' }).min(1).max(64),
-    title: z.string().min(1, { error: 'title must be non-empty' }),
-    subtitle: z.string().min(1, { error: 'subtitle must be non-empty when present' }).optional(),
-    body: z.string().optional(),
-    bodyPath: z.string().optional(),
-    options: z.array(interactionOptionSchema),
-    multiSelect: z.boolean().optional(),
-    allowFreetext: z.boolean().optional(),
-    freetextLabel: z.string().optional(),
-    kind: z.enum(INTERACTION_KINDS).optional(),
-    preAnswered: preAnswerSchema.optional(),
-});
-const deckSourceSchema = z.object({
-    sessionName: z.string().optional(),
-    askedBy: z.string().optional(),
-    blockedSince: z.string().optional(),
-    nodeId: z.string().optional(),
+    title: z.string().min(1), subtitle: z.string().min(1).optional(), body: z.string().optional(), bodyPath: z.string().optional(),
+    options: z.array(interactionOptionSchema), multiSelect: z.boolean().optional(), allowFreetext: z.boolean().optional(), freetextLabel: z.string().optional(), kind: z.enum(INTERACTION_KINDS).optional(), preAnswered: preAnswerSchema.optional(),
 });
-export const deckSchema = z.object({
-    title: z.string().optional(),
-    source: deckSourceSchema.optional(),
-    interactions: z.array(interactionSchema).min(1, { error: 'interactions[] must be non-empty' }),
-}).superRefine((input, ctx) => {
-    const seen = new Map();
-    for (let i = 0; i < input.interactions.length; i++) {
-        const interaction = input.interactions[i];
-        if (interaction.body !== undefined && interaction.bodyPath !== undefined) {
-            ctx.addIssue({
-                code: 'custom',
-                message: 'body and bodyPath are mutually exclusive',
-                path: ['interactions', i],
-            });
-        }
-        const prev = seen.get(interaction.id);
-        if (prev !== undefined) {
-            ctx.addIssue({
-                code: 'custom',
-                message: `duplicate interaction id "${interaction.id}" at indices ${prev} and ${i}`,
-                path: ['interactions', i, 'id'],
-            });
-        }
-        seen.set(interaction.id, i);
-    }
+const deckSourceSchema = z.object({ sessionName: z.string().optional(), askedBy: z.string().optional(), blockedSince: z.string().optional(), nodeId: z.string().optional() });
+export const deckSchema = z.object({ title: z.string().optional(), source: deckSourceSchema.optional(), interactions: z.array(interactionSchema).min(1) }).superRefine((input, ctx) => {
+    const seen = new Set();
+    input.interactions.forEach((interaction, index) => {
+        if (interaction.body !== undefined && interaction.bodyPath !== undefined)
+            ctx.addIssue({ code: 'custom', message: 'body and bodyPath are mutually exclusive', path: ['interactions', index] });
+        if (seen.has(interaction.id))
+            ctx.addIssue({ code: 'custom', message: `duplicate interaction id "${interaction.id}"`, path: ['interactions', index, 'id'] });
+        seen.add(interaction.id);
+    });
 });
-// ── C2 bodyPath defense + inlining ────────────────────────────────────────────
-/**
- * Read `bodyPath` (relative to `dir`, the interaction directory a deck.json
- * lives/will live in) with the traversal/symlink defenses a file read off an
- * agent-supplied relative path needs.
- */
+const reviewSourceSchema = deckSourceSchema;
+export const reviewDescriptorSchema = z.object({
+    schema: z.literal('humanloop.review/v1'),
+    file: z.string().min(1).refine(isAbsolute, 'file must be absolute'),
+    output: z.string().min(1).refine(isAbsolute, 'output must be absolute'),
+    title: z.string().min(1),
+    source: reviewSourceSchema,
+    blockedSince: z.string().datetime({ offset: true }),
+}).strict();
 function readBodyPathFile(dir, bodyPath) {
     const joined = resolve(dir, bodyPath);
-    // STEP 1: existence + lstat BEFORE realpath to catch symlinks and directories.
-    if (!existsSync(joined)) {
-        throw new Error(`bodyPath does not exist: '${bodyPath}' (resolved against deck dir '${dir}'). bodyPath is interpreted relative to the deck JSON's directory; place the body file there and use a relative path (e.g. "completion-summary.md").`);
-    }
-    const stat = lstatSync(joined);
-    if (!stat.isFile()) {
-        // Catches symlinks, directories, FIFOs — lstat does not follow symlinks.
-        throw new Error(`bodyPath must be a regular file (not a symlink, directory, or special file): ${bodyPath}`);
-    }
-    // STEP 2: realpath both sides, prefix-check (defense-in-depth for .. traversal).
-    // realpathSync is safe here: lstat already confirmed the path exists.
+    if (!existsSync(joined))
+        throw new Error(`bodyPath does not exist: '${bodyPath}'`);
+    if (!lstatSync(joined).isFile())
+        throw new Error(`bodyPath must be a regular file: ${bodyPath}`);
     const realResolved = realpathSync(joined);
     const realDeckDir = realpathSync(dir);
-    const prefix = realDeckDir + sep;
-    if (realResolved !== realDeckDir && !realResolved.startsWith(prefix)) {
-        throw new Error(`bodyPath '${bodyPath}' escapes the deck's directory ('${realDeckDir}'). bodyPath is resolved relative to the deck JSON file and must stay inside its directory (no '..', absolute paths pointing elsewhere, or symlinks out). Fix: write the deck JSON next to the body file (e.g. both inside $SISYPHUS_SESSION_DIR/context/) and use a relative path like "completion-summary.md".`);
-    }
-    // STEP 3: read. lstat confirmed regular file; realpath confirmed in-tree.
-    return readFileSync(joined, 'utf-8');
+    if (!realResolved.startsWith(realDeckDir + sep))
+        throw new Error(`bodyPath '${bodyPath}' escapes the deck directory`);
+    return readFileSync(joined, 'utf8');
 }
-/**
- * The ONE canonical `bodyPath` → `body` normalization boundary. Resolves every
- * interaction's `bodyPath` (relative to `dir`, the interaction directory) into
- * `body` and strips `bodyPath` from the result.
- *
- * Call this once, right before a deck is (re)written to `<dir>/deck.json` —
- * `hl deck ask`, `hl deck update`, and the public `ask()` API all do — so
- * every reader downstream (the terminal TUI's render + its live-reload
- * poller, the browser server's `/api/interaction`) only ever sees a plain
- * `body` and never has to special-case `bodyPath` itself. `parseDeck` (below)
- * reuses this same function when reading a deck straight off disk.
- */
 export function resolveDeckBodyPaths(deck, dir) {
-    const interactions = deck.interactions.map((interaction) => {
-        if (interaction.bodyPath === undefined)
-            return interaction;
-        const body = readBodyPathFile(dir, interaction.bodyPath);
-        // Drop bodyPath from persisted deck.json/decisions.json (recipe §1.8).
-        const { bodyPath: _drop, ...rest } = interaction;
-        return { ...rest, body };
-    });
-    return { ...deck, interactions };
+    return { ...deck, interactions: deck.interactions.map((interaction) => {
+            if (interaction.bodyPath === undefined)
+                return interaction;
+            const { bodyPath: _bodyPath, ...rest } = interaction;
+            return { ...rest, body: readBodyPathFile(dir, interaction.bodyPath) };
+        }) };
 }
-// ── public entry points ───────────────────────────────────────────────────────
-export function parseDeck(deckPath) {
-    const raw = readFileSync(deckPath, 'utf-8');
-    let json;
+export function parseDeck(path) {
+    let raw;
     try {
-        json = JSON.parse(raw);
+        raw = JSON.parse(readFileSync(path, 'utf8'));
     }
     catch {
         throw new Error('deck is not valid JSON');
     }
-    const parsed = deckSchema.parse(json);
-    const resolved = resolveDeckBodyPaths(parsed, dirname(deckPath));
-    for (const interaction of resolved.interactions) {
+    const deck = resolveDeckBodyPaths(deckSchema.parse(raw), dirname(path));
+    for (const interaction of deck.interactions)
         if (interaction.body !== undefined) {
             const check = checkMarkdown(interaction.body);
-            if (!check.ok) {
+            if (!check.ok)
                 throw new Error(check.error);
-            }
         }
-    }
-    return resolved;
+    return deck;
 }
-export function validateDeck(parsed) {
-    return deckSchema.parse(parsed);
+export function validateDeck(parsed) { return deckSchema.parse(parsed); }
+export function validateReviewDescriptor(parsed) { return reviewDescriptorSchema.parse(parsed); }
+/** Canonicalize and authorize the one review projection boundary before every write. */
+export function validateReviewProjection(dir, parsed) {
+    const descriptor = validateReviewDescriptor(parsed);
+    if (!/\.md(?:own)?$/i.test(descriptor.file) || !existsSync(descriptor.file))
+        throw new Error('review file must be an existing absolute markdown file');
+    const file = realpathSync(descriptor.file);
+    const output = resolve(realpathSync(dirname(descriptor.output)), basename(descriptor.output));
+    const reserved = new Set(['deck.json', 'review.json', 'response.json', 'progress.json', 'claim.json', 'delivery.json', 'delivery-error.json']);
+    const ownProtocolPaths = new Set([deckPath(dir), reviewPath(dir), responsePath(dir), progressPath(dir), claimPath(dir), deliveryPath(dir), deliveryErrorPath(dir)]);
+    if (output === file || reserved.has(basename(output)) || ownProtocolPaths.has(output))
+        throw new Error('review output must not alias the source or ticket protocol files');
+    return { ...descriptor, file, output };
 }

package/dist/inbox/layout.d.ts

@@ -0,0 +1,8 @@
+export interface InboxLayout {
+    mode: 'two-column' | 'list' | 'detail' | 'minimum';
+    listWidth: number;
+    detailWidth: number;
+    height: number;
+}
+/** Pure geometry for the centralized inbox surface. */
+export declare function inboxLayout(cols: number, rows: number, screen?: 'list' | 'detail'): InboxLayout;

package/dist/inbox/layout.js

@@ -0,0 +1,9 @@
+/** Pure geometry for the centralized inbox surface. */
+export function inboxLayout(cols, rows, screen = 'list') {
+    if (cols < 60 || rows < 18)
+        return { mode: 'minimum', listWidth: cols, detailWidth: 0, height: rows };
+    if (cols < 96)
+        return { mode: screen, listWidth: cols, detailWidth: cols, height: rows };
+    const listWidth = Math.max(30, Math.min(44, Math.floor(cols / 3)));
+    return { mode: 'two-column', listWidth, detailWidth: cols - listWidth - 1, height: rows };
+}

package/dist/inbox/registry.d.ts

@@ -0,0 +1,29 @@
+import type { CompletionEvent } from '../types.js';
+export interface CompletionHandler {
+    command: string;
+    args: string[];
+}
+export interface InboxRootRegistration {
+    schema: 'humanloop.inbox-root/v1';
+    root: string;
+    owner: string;
+    handler?: CompletionHandler;
+}
+export interface InboxRootStatus extends InboxRootRegistration {
+    available: boolean;
+}
+export interface RegisterInboxRootOptions {
+    root: string;
+    owner: string;
+    handler?: CompletionHandler;
+}
+export declare function inboxRootsDirectory(): string;
+/** Create/canonicalize a root and claim its user-scoped registration. */
+export declare function registerInboxRoot(opts: RegisterInboxRootOptions): InboxRootRegistration;
+/** Removes a matching available root through its real path, or an unavailable record by its stored canonical path. */
+export declare function unregisterInboxRoot(root: string, owner: string): boolean;
+export declare function listInboxRoots(): InboxRootStatus[];
+export declare function registeredInboxRoot(root: string): InboxRootRegistration | null;
+/** The managed SDK root is durable, user-scoped, and owned by humanloop. */
+export declare function managedInboxRoot(): InboxRootRegistration;
+export type CompletionHandlerEvent = CompletionEvent;

package/dist/inbox/registry.js

@@ -0,0 +1,97 @@
+import { chmodSync, existsSync, mkdirSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { atomicWriteJson, readJson, withExclusiveDirectoryLock } from './convention.js';
+function stateHome() { return process.env['XDG_STATE_HOME'] || join(homedir(), '.local', 'state'); }
+export function inboxRootsDirectory() { return join(stateHome(), 'humanloop', 'inbox-roots'); }
+function recordPath(root) { return join(inboxRootsDirectory(), createHash('sha256').update(root).digest('hex')); }
+function canonicalRoot(root) { try {
+    return realpathSync(root);
+}
+catch {
+    return resolve(root);
+} }
+function validateHandler(handler) {
+    if (handler === undefined)
+        return undefined;
+    if (!handler.command || !Array.isArray(handler.args) || !handler.args.every((arg) => typeof arg === 'string'))
+        throw new Error('completion handler requires a command and string args');
+    return { command: handler.command, args: [...handler.args] };
+}
+function validateRegistration(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const value = raw;
+    if (value.schema !== 'humanloop.inbox-root/v1' || typeof value.root !== 'string' || !value.root || typeof value.owner !== 'string' || !value.owner.trim())
+        return null;
+    try {
+        return { schema: 'humanloop.inbox-root/v1', root: value.root, owner: value.owner, handler: value.handler === undefined ? undefined : validateHandler(value.handler) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Create/canonicalize a root and claim its user-scoped registration. */
+export function registerInboxRoot(opts) {
+    if (!opts.owner.trim())
+        throw new Error('inbox root owner must be non-empty');
+    mkdirSync(resolve(opts.root), { recursive: true, mode: 0o700 });
+    const root = realpathSync(opts.root);
+    const path = recordPath(root);
+    mkdirSync(inboxRootsDirectory(), { recursive: true, mode: 0o700 });
+    return withExclusiveDirectoryLock(`${path}.lock`, () => {
+        const existing = validateRegistration(readJson(path));
+        if (existing !== null && existing.root === root && existing.owner !== opts.owner)
+            throw new Error(`inbox root is already owned by ${existing.owner}`);
+        if (existing !== null && existing.root !== root)
+            throw new Error('inbox root registry hash collision');
+        const registration = { schema: 'humanloop.inbox-root/v1', root, owner: opts.owner, handler: validateHandler(opts.handler) };
+        atomicWriteJson(path, registration);
+        chmodSync(path, 0o600);
+        return registration;
+    });
+}
+/** Removes a matching available root through its real path, or an unavailable record by its stored canonical path. */
+export function unregisterInboxRoot(root, owner) {
+    const canonical = canonicalRoot(root);
+    const path = recordPath(canonical);
+    return withExclusiveDirectoryLock(`${path}.lock`, () => {
+        const existing = validateRegistration(readJson(path));
+        if (existing === null || existing.root !== canonical || existing.owner !== owner)
+            return false;
+        unlinkSync(path);
+        return true;
+    });
+}
+export function listInboxRoots() {
+    let files;
+    try {
+        files = readdirSync(inboxRootsDirectory());
+    }
+    catch {
+        return [];
+    }
+    const roots = [];
+    for (const file of files) {
+        const record = validateRegistration(readJson(join(inboxRootsDirectory(), file)));
+        if (record !== null)
+            roots.push({ ...record, available: existsSync(record.root) });
+    }
+    return roots.sort((a, b) => a.root.localeCompare(b.root));
+}
+export function registeredInboxRoot(root) {
+    let canonical;
+    try {
+        canonical = realpathSync(root);
+    }
+    catch {
+        return null;
+    }
+    const record = validateRegistration(readJson(recordPath(canonical)));
+    return record?.root === canonical ? record : null;
+}
+/** The managed SDK root is durable, user-scoped, and owned by humanloop. */
+export function managedInboxRoot() {
+    return registerInboxRoot({ root: join(stateHome(), 'humanloop', 'inbox'), owner: 'humanloop' });
+}

package/dist/inbox/review-adapter.d.ts

@@ -0,0 +1,22 @@
+import { type TicketClaim } from './claim.js';
+import { type ReviewOptions } from '../editor/review.js';
+import type { ReviewDescriptor, TicketResult } from '../types.js';
+export interface ReviewAdapterOptions {
+    dir: string;
+    descriptor: ReviewDescriptor;
+    claim: TicketClaim;
+    editor?: ReviewOptions['editor'];
+    onSubmitted?: (result: TicketResult) => Promise<void> | void;
+}
+/** Controller-owned native review child. It persists drafts but delegates the sole final write to tickets.ts. */
+export declare class ReviewAdapter {
+    private readonly opts;
+    private readonly abortController;
+    private readonly heartbeat;
+    private running;
+    private stopped;
+    constructor(opts: ReviewAdapterOptions);
+    start(): Promise<TicketResult | null>;
+    /** Toggle, cancellation, and controller teardown all take this same path. */
+    stop(): Promise<void>;
+}

package/dist/inbox/review-adapter.js

@@ -0,0 +1,56 @@
+import { completeReview } from './tickets.js';
+import { heartbeatClaim, releaseClaim } from './claim.js';
+import { progressPath } from './convention.js';
+import { launchReview } from '../editor/review.js';
+/** Controller-owned native review child. It persists drafts but delegates the sole final write to tickets.ts. */
+export class ReviewAdapter {
+    opts;
+    abortController = new AbortController();
+    heartbeat;
+    running = null;
+    stopped = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.heartbeat = setInterval(() => {
+            if (!this.stopped)
+                heartbeatClaim(this.opts.dir, this.opts.claim.token);
+        }, 10_000);
+    }
+    start() {
+        if (this.running !== null)
+            return this.running;
+        let canonical = null;
+        this.running = launchReview(this.opts.descriptor.file, {
+            output: progressPath(this.opts.dir),
+            jobDir: this.opts.dir,
+            editor: this.opts.editor,
+            signal: this.abortController.signal,
+            onPropose: async (proposal) => {
+                if (this.stopped || this.abortController.signal.aborted)
+                    return;
+                const completed = await completeReview(this.opts.dir, proposal, this.opts.claim.token);
+                canonical = completed.result;
+                await this.opts.onSubmitted?.(canonical);
+            },
+        }).then(() => canonical).finally(() => {
+            clearInterval(this.heartbeat);
+            releaseClaim(this.opts.dir, this.opts.claim.token);
+            this.stopped = true;
+        });
+        return this.running;
+    }
+    /** Toggle, cancellation, and controller teardown all take this same path. */
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.abortController.abort();
+        try {
+            await this.running;
+        }
+        finally {
+            clearInterval(this.heartbeat);
+            releaseClaim(this.opts.dir, this.opts.claim.token);
+        }
+    }
+}

package/dist/inbox/scan.d.ts

@@ -1,2 +1,3 @@
-import type { InboxItem } from '../types.js';
-export declare function scanInbox(roots: string[]): InboxItem[];
+import type { TicketSummary } from '../types.js';
+/** Read all unresolved deck/review tickets, newest first. Progress never affects visibility. */
+export declare function scanInbox(roots?: string[]): TicketSummary[];