@crouton-kit/humanloop 0.3.33 → 0.3.35

package/dist/inbox/convention.js

@@ -1,76 +1,36 @@
-import { existsSync, statSync, writeFileSync, renameSync, readFileSync, unlinkSync, mkdirSync } from 'fs';
-import { dirname } from 'path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { buildSummary } from '../summary.js';
-// ── Path helpers ──────────────────────────────────────────────────────────────
-export function deckPath(dir) {
-    return `${dir}/deck.json`;
-}
-export function responsePath(dir) {
-    return `${dir}/response.json`;
-}
-export function progressPath(dir) {
-    return `${dir}/progress.json`;
-}
-export function visualsDir(dir) {
-    return `${dir}/visuals`;
-}
-export function visualMdPath(dir, id) {
-    return `${dir}/visuals/${id}.md`;
-}
-export function visualAnsiPath(dir, id) {
-    return `${dir}/visuals/${id}.ansi`;
-}
+export function deckPath(dir) { return `${dir}/deck.json`; }
+export function reviewPath(dir) { return `${dir}/review.json`; }
+export function responsePath(dir) { return `${dir}/response.json`; }
+export function progressPath(dir) { return `${dir}/progress.json`; }
+export function claimPath(dir) { return `${dir}/claim.json`; }
+export function deliveryPath(dir) { return `${dir}/delivery.json`; }
+export function deliveryErrorPath(dir) { return `${dir}/delivery-error.json`; }
+export function visualsDir(dir) { return `${dir}/visuals`; }
+export function visualMdPath(dir, id) { return `${dir}/visuals/${id}.md`; }
+export function visualAnsiPath(dir, id) { return `${dir}/visuals/${id}.ansi`; }
 export function interactionState(dir) {
-    const hasDeck = existsSync(deckPath(dir));
-    const hasResponse = existsSync(responsePath(dir));
-    const hasProgress = existsSync(progressPath(dir));
-    if (!hasDeck)
+    if (!existsSync(deckPath(dir)) && !existsSync(reviewPath(dir)))
         return 'missing';
-    if (hasResponse)
+    if (existsSync(responsePath(dir)))
         return 'resolved';
-    if (hasProgress)
-        return 'in-progress';
-    return 'pending';
-}
-export function isResolved(dir) {
-    return existsSync(responsePath(dir));
-}
-/** Returns true if a live resolver owns this dir (progress.json mtime < 300s). */
-export function isClaimed(dir) {
-    const p = progressPath(dir);
-    if (!existsSync(p))
-        return false;
-    try {
-        const { mtimeMs } = statSync(p);
-        return Date.now() - mtimeMs < 300_000;
-    }
-    catch {
-        return false;
-    }
+    return existsSync(claimPath(dir)) ? 'claimed' : 'pending';
 }
-// ── Canvas-node attribution ─────────────────────────────────────────
-/**
- * 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 function isResolved(dir) { return existsSync(responsePath(dir)); }
+export function isClaimed(dir) { return existsSync(claimPath(dir)); }
 export function stampCanvasNode(deck) {
     const id = process.env['CRTR_NODE_ID'];
-    if (id === undefined || id.trim() === '')
-        return;
-    if (deck.source?.nodeId != null && deck.source.nodeId !== '')
+    if (id === undefined || id.trim() === '' || deck.source?.nodeId)
         return;
     deck.source = { ...(deck.source ?? {}), nodeId: id };
 }
-// ── Atomic I/O ────────────────────────────────────────────────────────────────
 export function atomicWriteJson(path, value) {
-    const payload = JSON.stringify(value, null, 2);
-    const tmp = `${path}.tmp`;
+    const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(tmp, payload);
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
     renameSync(tmp, path);
 }
 export function readJson(path) {
@@ -81,31 +41,141 @@ export function readJson(path) {
         return null;
     }
 }
-// ── High-level write helpers ──────────────────────────────────────────────────
+function pause(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+// The holder's identity lives in the NAME of its single marker file. The marker's
+// mtime is the heartbeat and its presence is ownership, so the observed token, the
+// staleness clock, and the reclaim gate are one atomic fact.
+const MARKER_PREFIX = 'owner.';
+function markerPath(path, token) { return `${path}/${MARKER_PREFIX}${token}`; }
+function observedMarkerToken(path) {
+    try {
+        return readdirSync(path).find((entry) => entry.startsWith(MARKER_PREFIX))?.slice(MARKER_PREFIX.length) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function ownsLock(lock) { return existsSync(markerPath(lock.path, lock.token)); }
+function releaseDirectoryLock(lock) { if (ownsLock(lock))
+    rmSync(lock.path, { recursive: true, force: true }); }
+function lockAge(path, token) {
+    const target = token !== null ? markerPath(path, token) : path;
+    try {
+        return Date.now() - statSync(existsSync(target) ? target : path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+// Reclamation is bound to the exact instance it observed: it unlinks ONLY that
+// token's marker, then removes the now-empty directory with an empty-guarded
+// rmdir. A successor lock holds a different random token (a different marker
+// name), so a lagging reclaimer that saw the old stale lock can never strip a
+// live successor — its unlink targets a name that no longer exists.
+function reclaimIfStale(path, staleMs) {
+    const token = observedMarkerToken(path);
+    if (lockAge(path, token) <= staleMs)
+        return;
+    if (token !== null) {
+        try {
+            unlinkSync(markerPath(path, token));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    try {
+        rmdirSync(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTEMPTY' && code !== 'EEXIST')
+            throw error;
+    }
+}
+function tryAcquireDirectoryLock(path, staleMs) {
+    const token = randomUUID();
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        writeFileSync(markerPath(path, token), '', { flag: 'wx', mode: 0o600 });
+        return { path, token };
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        reclaimIfStale(path, staleMs);
+        return null;
+    }
+}
+function acquireDirectoryLock(path, staleMs, timeoutMs) {
+    const startedAt = Date.now();
+    while (true) {
+        const lock = tryAcquireDirectoryLock(path, staleMs);
+        if (lock !== null)
+            return lock;
+        if (Date.now() - startedAt >= timeoutMs)
+            throw new Error('exclusive operation lock acquisition timed out');
+        pause(5);
+    }
+}
+async function acquireDirectoryLockAsync(path, staleMs, timeoutMs) {
+    const startedAt = Date.now();
+    while (true) {
+        const lock = tryAcquireDirectoryLock(path, staleMs);
+        if (lock !== null)
+            return lock;
+        if (Date.now() - startedAt >= timeoutMs)
+            throw new Error('exclusive operation lock acquisition timed out');
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 10));
+    }
+}
+/** Runs a short filesystem transition under a token-checked, crash-reclaimable directory lock. */
+export function withExclusiveDirectoryLock(path, operation, options = {}) {
+    const lock = acquireDirectoryLock(path, options.staleMs ?? 30_000, options.timeoutMs ?? 5_000);
+    try {
+        return operation();
+    }
+    finally {
+        releaseDirectoryLock(lock);
+    }
+}
+/** Async counterpart heartbeats while its operation runs, so a valid long handler is never stolen. */
+export async function withExclusiveDirectoryLockAsync(path, operation, options = {}) {
+    const staleMs = options.staleMs ?? 35_000;
+    const lock = await acquireDirectoryLockAsync(path, staleMs, options.timeoutMs ?? staleMs + 5_000);
+    const heartbeat = setInterval(() => {
+        if (ownsLock(lock)) {
+            try {
+                utimesSync(markerPath(lock.path, lock.token), new Date(), new Date());
+            }
+            catch { /* a reclaimed lock is no longer ours */ }
+        }
+    }, 1_000);
+    try {
+        return await operation();
+    }
+    finally {
+        clearInterval(heartbeat);
+        releaseDirectoryLock(lock);
+    }
+}
+// Kept for the existing panel until H2 routes all finalization through tickets.ts.
 export function writeResponse(dir, responses, completedAt, deck) {
-    const p = responsePath(dir);
-    // Persist the deterministic summary alongside the raw responses so
-    // `hl job result` can return a populated summary without re-deriving it (or
-    // silently emitting ''). When the deck is known at write time we compute it
-    // here; the deck is deterministic input so this never diverges from ask()'s
-    // envelope summary.
-    const summary = deck !== undefined ? buildSummary(deck, responses) : '';
-    atomicWriteJson(p, { responses, completedAt, summary });
-    return p;
+    const summary = deck === undefined ? '' : buildSummary(deck, responses);
+    atomicWriteJson(responsePath(dir), { schema: 'humanloop.response/v2', kind: 'deck', responses, summary, completedAt });
+    return responsePath(dir);
 }
 export function writeProgress(dir, responses) {
-    atomicWriteJson(progressPath(dir), {
-        partial: true,
-        responses,
-        savedAt: new Date().toISOString(),
-    });
+    atomicWriteJson(progressPath(dir), { kind: 'deck', responses, savedAt: new Date().toISOString() });
 }
 export function clearProgress(dir) {
     try {
         unlinkSync(progressPath(dir));
     }
-    catch (err) {
-        if (err.code !== 'ENOENT')
-            throw err;
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
     }
 }

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;