@crouton-kit/humanloop 0.3.33 → 0.3.34

package/dist/inbox/controller.d.ts

@@ -0,0 +1,57 @@
+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 claim;
+    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;
+    reloadSelectedDeck(): void;
+    close(): void;
+    run(): Promise<void>;
+    private complete;
+    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,311 @@
+import { watch } from 'node:fs';
+import { getTerminalSize, parseKeypress, restoreTerminal, setupTerminal } from '../tui/terminal.js';
+import { diffFrame } from '../tui/render.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 { clearProgress, deckPath, progressPath, readJson } from './convention.js';
+import { DeckAdapter } from './deck-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;
+    claim;
+    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);
+            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) {
+        if (key.ctrl && input === 'c') {
+            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 || 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);
+    }
+    reloadSelectedDeck() { this.adapter?.reload(); this.repaint(); }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        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();
+        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();
+            };
+            const onResize = () => this.resize();
+            let done = false;
+            this.finishRun = () => {
+                if (done)
+                    return;
+                done = true;
+                process.stdin.removeListener('data', onData);
+                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;
+        try {
+            await this.finishDeck(claim.dir, responses, claim.token);
+        }
+        catch (error) {
+            this.status = error instanceof Error ? error.message : String(error);
+            return;
+        }
+        this.leaveDetail(false);
+        this.rescan();
+        this.repaint();
+    }
+    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} · ${selected.source.sessionName ?? selected.source.askedBy ?? 'unknown source'}${RESET}`];
+        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) {
+        if (this.closed || !this.running)
+            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() {
+        const roots = this.options.roots ?? listInboxRoots().filter((root) => root.available).map((root) => root.root);
+        for (const root of roots) {
+            try {
+                this.watchers.push(watch(root, () => this.invalidate()));
+            }
+            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; }

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;

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;
     }
 }