@crouton-kit/humanloop 0.3.33 → 0.3.34

package/dist/editor/feedback.d.ts

@@ -15,4 +15,13 @@ export declare function serializeFeedbackResult(result: FeedbackResult): string;
 export declare function writeFeedbackResult(path: string, result: FeedbackResult): string;
 export declare function writeDraftFeedbackResult(path: string, file: string, comments: FeedbackComment[], savedAt?: string): FeedbackResult;
 export declare function writeFinalFeedbackResult(path: string, file: string, comments: FeedbackComment[], timestamp?: string): FeedbackResult;
+export interface ReviewDraft {
+    kind: 'review';
+    comments: FeedbackComment[];
+    savedAt: string;
+    version: number;
+}
+/** Durable, resumable review work. Canonical feedback is produced only by the ticket finalizer. */
+export declare function readReviewDraft(path: string): ReviewDraft | null;
+export declare function writeReviewDraft(path: string, comments: FeedbackComment[], version: number, savedAt?: string): ReviewDraft;
 export declare function writeSubmitFlag(path: string): void;

package/dist/editor/feedback.js

@@ -198,6 +198,29 @@ export function writeFinalFeedbackResult(path, file, comments, timestamp = nowIs
     writeFeedbackResult(path, result);
     return result;
 }
+/** Durable, resumable review work. Canonical feedback is produced only by the ticket finalizer. */
+export function readReviewDraft(path) {
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(raw) || raw.kind !== 'review' || !Number.isInteger(raw.version) || raw.version < 0 || typeof raw.savedAt !== 'string')
+        return null;
+    return { kind: 'review', comments: sanitizeFeedbackComments(raw.comments), savedAt: raw.savedAt, version: raw.version };
+}
+export function writeReviewDraft(path, comments, version, savedAt = nowIso()) {
+    const draft = { kind: 'review', comments: sanitizeFeedbackComments(comments), savedAt, version };
+    const tmp = `${path}.tmp`;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(tmp, `${JSON.stringify(draft, null, 2)}\n`);
+    renameSync(tmp, path);
+    return draft;
+}
 export function writeSubmitFlag(path) {
     mkdirSync(dirname(path), { recursive: true });
     writeFileSync(path, '');

package/dist/editor/review.d.ts

@@ -1,35 +1,14 @@
 import type { FeedbackResult } from '../types.js';
 export interface ReviewOptions {
-    /** Where the answers JSON is written (live autosave + finalized on exit). */
+    /** Where the resumable review draft is written. */
     output: string;
     /** Editor binary override. Default: first of nvim, vim on PATH. */
     editor?: string;
-    /** Force running in the current terminal even when $TMUX is set. */
-    noTmux?: boolean;
-    /**
-     * When set, an explicit `<Space>s` / `:HLSubmit` invocation writes a sentinel
-     * file at this path. Node-side uses the file's existence to gate `submitted: true`.
-     * When omitted, any editor exit finalizes `submitted: true` (legacy behavior).
-     */
-    submitFlagPath?: string;
-    /**
-     * When true and $TMUX is set and !opts.noTmux, launch via
-     * `tmux display-popup -E` instead of `tmux split-window`.
-     * display-popup -E is synchronous so no poll loop is needed.
-     */
-    tmuxPopup?: boolean;
-    /** Override the default 90%/90% popup size. Only used when tmuxPopup is true. */
-    popupSize?: {
-        w: string;
-        h: string;
-    };
-    /**
-     * Reuse this directory for `review.vim` instead of minting a fresh temp dir.
-     * The async `review open` kickoff passes its job dir so the detached child
-     * sources the same vimscript the parent already wrote there (which also lets
-     * the job be recognized as a review while it's still live). When the file
-     * already exists it is left untouched.
-     */
+    /** Called exactly once when the human explicitly submits a final proposal. */
+    onPropose?: (result: FeedbackResult) => Promise<void> | void;
+    /** Controller cancellation closes the editor/browser handoff without proposing a result. */
+    signal?: AbortSignal;
+    /** Reuse this controller-owned directory for `review.vim`; an existing script is left untouched. */
     jobDir?: string;
 }
 export declare function reviewVimscript(): string;
@@ -43,8 +22,7 @@ export declare function formatFeedbackSummary(result: FeedbackResult, feedbackJs
 /**
  * Open a markdown file in a clean, read-only Neovim/Vim review session. The
  * human anchors comments to source lines/selections with native vim motions
- * and quits to submit. Blocks until the editor exits, then finalizes and
- * returns the feedback. Autosaved continuously so a kill is recoverable and
- * the next run resumes.
+ * and explicitly submits a proposal. Blocks until the editor exits. Autosaved
+ * drafts survive exit; canonical ticket finalization belongs to the controller.
  */
 export declare function launchReview(file: string, opts: ReviewOptions): Promise<FeedbackResult>;

package/dist/editor/review.js

@@ -1,15 +1,10 @@
-import { spawn, spawnSync, execFileSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { existsSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
 import { tmpdir } from 'os';
 import { resolve, join } from 'path';
 import { openBrowser } from '../browser/open.js';
 import { startReviewWebServer } from '../browser/server.js';
-import { readStoredFeedbackResult, writeDraftFeedbackResult, writeFinalFeedbackResult, } from './feedback.js';
-function shellQuote(s) {
-    if (s.length > 0 && /^[a-zA-Z0-9_\-./:@%+=]+$/.test(s))
-        return s;
-    return `'${s.replace(/'/g, `'\\''`)}'`;
-}
+import { buildFinalFeedbackResult, readReviewDraft, } from './feedback.js';
 function resolveEditor(override) {
     const candidates = override ? [override] : ['nvim', 'vim'];
     for (const bin of candidates) {
@@ -41,6 +36,7 @@ export function reviewVimscript() {
         `let g:hl_review_url = $HL_REVIEW_URL`,
         `let g:hl_handoff_flag = $HL_HANDOFF_FLAG`,
         `let s:comments = []`,
+        `let s:version = 0`,
         `let s:idseq = 0`,
         `let s:ns = exists('*nvim_create_namespace') ? nvim_create_namespace('hl_review') : -1`,
         ``,
@@ -50,15 +46,17 @@ export function reviewVimscript() {
         `  endif`,
         `  try`,
         `    let l:obj = json_decode(join(readfile(g:hl_out), "\\n"))`,
-        `    if type(l:obj) == type({}) && get(l:obj,'file','') ==# g:hl_src && !get(l:obj,'submitted',0)`,
+        `    if type(l:obj) == type({}) && get(l:obj,'kind','') ==# 'review'`,
         `      let s:comments = get(l:obj,'comments',[])`,
+        `      let s:version = get(l:obj,'version',0)`,
         `    endif`,
         `  catch`,
         `  endtry`,
         `endfunction`,
         ``,
         `function! s:Save() abort`,
-        `  let l:obj = {'file': g:hl_src, 'submitted': v:false, 'approved': v:false, 'comments': s:comments, 'savedAt': strftime('%Y-%m-%dT%H:%M:%S')}`,
+        `  let s:version += 1`,
+        `  let l:obj = {'kind': 'review', 'comments': s:comments, 'savedAt': strftime('%Y-%m-%dT%H:%M:%S'), 'version': s:version}`,
         `  let l:tmp = g:hl_out . '.tmp'`,
         `  call writefile([json_encode(l:obj)], l:tmp)`,
         `  call rename(l:tmp, g:hl_out)`,
@@ -428,7 +426,7 @@ export function reviewVimscript() {
         ``,
         `" Watchmode: the source is opened read-only here but may be rewritten on`,
         `" disk by the agent while the human reviews. autoread + a periodic checktime`,
-        `" (timers fire even when the tmux pane is unfocused) reload the buffer`,
+        `" (timers fire even when the terminal is unfocused) reload the buffer`,
         `" silently — it is never locally modified, so there is nothing to clobber.`,
         `" On reload, re-run Setup (read-only guard, treesitter, maps) and redraw the`,
         `" comment anchors, which the reload cleared. Comments live in s:comments /`,
@@ -496,78 +494,58 @@ export function formatFeedbackSummary(result, feedbackJsonPath) {
     out.push(`  schema: ${FEEDBACK_SCHEMA}  · cols are 0-based byte offsets, colEnd exclusive`);
     return out.join('\n');
 }
-async function runInTmuxPane(paneCmd) {
-    // `paneCmd` MUST be an `exec`-prefixed command so the editor replaces the
-    // shell and becomes the pane's process. tmux's `#{pane_current_command}`
-    // then reports `nvim` — many users gate "let Ctrl-D/Ctrl-U/etc. through to
-    // the app vs. take over with tmux copy-mode" on exactly that. If the pane
-    // command were `nvim …; tmux wait-for` the pane process stays the shell,
-    // pane_current_command is `zsh`/`sh`, and those bindings hijack native vim
-    // keys. Because the editor is exec'd there is no "after" to signal from, so
-    // completion is detected purely by the pane disappearing on exit.
-    const paneId = execFileSync('tmux', ['split-window', '-h', '-d', '-P', '-F', '#{pane_id}', paneCmd], { encoding: 'utf8' }).trim();
-    // Ensure the pane closes when the editor exits (some configs set
-    // remain-on-exit globally, which would hang the poll below).
-    try {
-        execFileSync('tmux', ['set-option', '-p', '-t', paneId, 'remain-on-exit', 'off'], { stdio: 'ignore' });
-    }
-    catch {
-        // older tmux without -p pane scope — default is already 'off'
-    }
-    await new Promise((resolvePromise, rejectPromise) => {
-        let settled = false;
-        const finish = (fn) => { if (!settled) {
-            settled = true;
-            clearInterval(poll);
-            fn();
-        } };
-        // The editor IS the pane process; when it exits the pane is destroyed.
-        const poll = setInterval(() => {
-            try {
-                const panes = execFileSync('tmux', ['list-panes', '-a', '-F', '#{pane_id}'], { encoding: 'utf8' });
-                if (!panes.split('\n').map((s) => s.trim()).includes(paneId)) {
-                    finish(resolvePromise);
-                }
-            }
-            catch (e) {
-                finish(() => rejectPromise(new Error(`tmux list-panes failed: ${e instanceof Error ? e.message : String(e)}`)));
-            }
-        }, 200);
-    });
-}
-function runInCurrentTerminal(bin, args, env) {
+function runInCurrentTerminal(bin, args, env, signal) {
     return new Promise((resolvePromise, rejectPromise) => {
         const child = spawn(bin, args, { stdio: 'inherit', env });
-        child.on('error', rejectPromise);
-        child.on('exit', () => resolvePromise());
+        let settled = false;
+        const cleanup = () => signal?.removeEventListener('abort', abort);
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error === undefined)
+                resolvePromise();
+            else
+                rejectPromise(error);
+        };
+        const abort = () => child.kill('SIGTERM');
+        child.once('error', finish);
+        child.once('exit', () => finish());
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted)
+            abort();
     });
 }
 function clearFlag(path) {
     rmSync(path, { force: true });
 }
-function readDraftComments(path, absFile) {
-    const stored = readStoredFeedbackResult(path, absFile);
-    return stored?.comments ?? [];
+function proposedFeedback(path, absFile) {
+    return buildFinalFeedbackResult(absFile, readReviewDraft(path)?.comments ?? []);
 }
-function finalizeReviewOutput(outPath, absFile, didSubmit) {
-    const comments = readDraftComments(outPath, absFile);
-    return didSubmit
-        ? writeFinalFeedbackResult(outPath, absFile, comments)
-        : writeDraftFeedbackResult(outPath, absFile, comments);
+function draftFeedback(path, absFile) {
+    const draft = readReviewDraft(path);
+    return {
+        file: absFile,
+        submitted: false,
+        approved: false,
+        comments: draft?.comments ?? [],
+        savedAt: draft?.savedAt ?? new Date().toISOString(),
+    };
 }
-async function waitForParkedReviewSubmit(submitted) {
+async function waitForParkedReviewSubmit(submitted, signal) {
     process.stderr.write('\nhumanloop: browser review handoff is active.\n' +
         '  The terminal editor is parked; the browser is the editing authority.\n' +
         '  Press w to take back into nvim, or Ctrl+C to exit with an unsubmitted draft.\n\n');
-    if (!process.stdin.isTTY) {
-        const result = await submitted;
-        return { type: 'submitted', result };
-    }
     return new Promise((resolveAction) => {
         const stdin = process.stdin;
+        const interactive = stdin.isTTY;
         const wasRaw = stdin.isRaw;
         let settled = false;
         const cleanup = () => {
+            signal?.removeEventListener('abort', onAbort);
+            if (!interactive)
+                return;
             stdin.off('data', onData);
             if (stdin.setRawMode)
                 stdin.setRawMode(wasRaw);
@@ -580,6 +558,7 @@ async function waitForParkedReviewSubmit(submitted) {
             cleanup();
             resolveAction(action);
         };
+        const onAbort = () => finish({ type: 'cancel' });
         const onData = (chunk) => {
             const text = chunk.toString('utf8');
             if (text === 'w' || text === 'W')
@@ -587,9 +566,14 @@ async function waitForParkedReviewSubmit(submitted) {
             if (text === '\u0003')
                 finish({ type: 'cancel' });
         };
-        stdin.setRawMode(true);
-        stdin.resume();
-        stdin.on('data', onData);
+        if (interactive) {
+            stdin.setRawMode(true);
+            stdin.resume();
+            stdin.on('data', onData);
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (signal?.aborted)
+            onAbort();
         submitted.then((result) => finish({ type: 'submitted', result }), () => finish({ type: 'cancel' }));
     });
 }
@@ -600,9 +584,8 @@ async function stopReviewServer(handle) {
 /**
  * Open a markdown file in a clean, read-only Neovim/Vim review session. The
  * human anchors comments to source lines/selections with native vim motions
- * and quits to submit. Blocks until the editor exits, then finalizes and
- * returns the feedback. Autosaved continuously so a kill is recoverable and
- * the next run resumes.
+ * and explicitly submits a proposal. Blocks until the editor exits. Autosaved
+ * drafts survive exit; canonical ticket finalization belongs to the controller.
  */
 export async function launchReview(file, opts) {
     const absFile = resolve(file);
@@ -611,19 +594,18 @@ export async function launchReview(file, opts) {
     }
     const outPath = resolve(opts.output);
     const bin = resolveEditor(opts.editor);
-    // When the async kickoff passes its job dir, source the review.vim the parent
-    // already wrote there; otherwise mint a private temp dir as before.
+    // Reuse the controller-owned job directory when supplied; otherwise create a private directory.
     const dir = opts.jobDir ?? mkdtempSync(join(tmpdir(), 'hl-review-'));
     const initPath = join(dir, 'review.vim');
     if (!existsSync(initPath))
         writeFileSync(initPath, reviewVimscript());
     const handoffFlagPath = join(dir, 'browser-handoff.flag');
+    const submitFlagPath = join(dir, 'review-submit.flag');
     // `-u NONE`: do NOT load the user's init.lua / LazyVim / plugins / keymaps.
     // Default runtimepath still includes the config dir (for the gloam
     // colorscheme) and the site dir (for the treesitter markdown parser), so the
     // review layer pulls in ONLY the colorscheme + treesitter styling itself.
     const editorArgs = ['-u', 'NONE', '-n', '-i', 'NONE', absFile, '-c', `source ${initPath}`];
-    const inTmux = !!process.env.TMUX && !opts.noTmux;
     async function runEditor(reviewUrl) {
         const env = {
             ...process.env,
@@ -631,73 +613,47 @@ export async function launchReview(file, opts) {
             HL_SOURCE: absFile,
             HL_REVIEW_URL: reviewUrl,
             HL_HANDOFF_FLAG: handoffFlagPath,
-            ...(opts.submitFlagPath ? { HL_SUBMIT_FLAG: opts.submitFlagPath } : {}),
+            HL_SUBMIT_FLAG: submitFlagPath,
         };
-        process.stderr.write(`\nhumanloop: opening "${absFile}" for review in ${bin}` +
-            (inTmux ? ' (tmux pane).\n' : '.\n') +
-            `  Answers : ${outPath}\n` +
+        process.stderr.write(`\nhumanloop: opening "${absFile}" for review in ${bin}.\n` +
+            `  Draft   : ${outPath}\n` +
             `  Browser : available after <Space>w hands off (or :HLBrowser)\n` +
             `  Keys    : <Space>c comment · <Space>l list · <Space>u undo · <Space>s submit & quit · <Space>w browser  (or :HLComment/:HLSubmit/:HLBrowser)\n` +
             `  Status  : BLOCKING — waiting for you to finish the review.\n\n`);
-        if (inTmux) {
-            // `exec env …` so the editor replaces the shell and becomes the pane's
-            // process (so tmux `#{pane_current_command}` is `nvim`, not the shell).
-            const envPairs = [
-                `HL_OUTPUT=${shellQuote(outPath)}`,
-                `HL_SOURCE=${shellQuote(absFile)}`,
-                `HL_REVIEW_URL=${shellQuote(reviewUrl)}`,
-                `HL_HANDOFF_FLAG=${shellQuote(handoffFlagPath)}`,
-                ...(opts.submitFlagPath ? [`HL_SUBMIT_FLAG=${shellQuote(opts.submitFlagPath)}`] : []),
-            ];
-            const paneCmd = [
-                'exec',
-                'env',
-                ...envPairs,
-                shellQuote(bin),
-                ...editorArgs.map(shellQuote),
-            ].join(' ');
-            try {
-                if (opts.tmuxPopup) {
-                    const w = opts.popupSize ? opts.popupSize.w : '90%';
-                    const h = opts.popupSize ? opts.popupSize.h : '90%';
-                    execFileSync('tmux', ['display-popup', '-E', '-w', w, '-h', h, paneCmd], { stdio: 'inherit' });
-                }
-                else {
-                    await runInTmuxPane(paneCmd);
-                }
-            }
-            catch (err) {
-                process.stderr.write(`tmux dispatch failed, running in current terminal: ${err instanceof Error ? err.message : String(err)}\n`);
-                await runInCurrentTerminal(bin, editorArgs, env);
-            }
-        }
-        else {
-            await runInCurrentTerminal(bin, editorArgs, env);
-        }
+        await runInCurrentTerminal(bin, editorArgs, env, opts.signal);
     }
     while (true) {
         clearFlag(handoffFlagPath);
+        clearFlag(submitFlagPath);
         let resolveSubmitted;
         const submitted = new Promise((resolveSubmittedPromise) => {
             resolveSubmitted = resolveSubmittedPromise;
         });
+        if (opts.signal?.aborted)
+            return draftFeedback(outPath, absFile);
         const server = await startReviewWebServer({
             jobDir: dir,
             file: absFile,
             output: outPath,
-            submitFlagPath: opts.submitFlagPath,
+            submitFlagPath,
             onSubmit: (result) => resolveSubmitted(result),
         });
+        if (opts.signal?.aborted) {
+            await stopReviewServer(server);
+            return draftFeedback(outPath, absFile);
+        }
         try {
             await runEditor(server.url);
             if (existsSync(handoffFlagPath)) {
                 server.activate();
                 process.stderr.write(`humanloop: browser review handoff active — ${server.url}\n`);
                 openBrowser(server.url);
-                const action = await waitForParkedReviewSubmit(submitted);
+                const action = await waitForParkedReviewSubmit(submitted, opts.signal);
                 if (action.type === 'submitted') {
                     await stopReviewServer(server);
                     clearFlag(handoffFlagPath);
+                    if (!opts.signal?.aborted)
+                        await opts.onPropose?.(action.result);
                     return action.result;
                 }
                 if (action.type === 'take-back') {
@@ -709,11 +665,16 @@ export async function launchReview(file, opts) {
                 }
                 await stopReviewServer(server);
                 clearFlag(handoffFlagPath);
-                return finalizeReviewOutput(outPath, absFile, false);
+                return draftFeedback(outPath, absFile);
             }
             await stopReviewServer(server);
-            const didSubmit = opts.submitFlagPath ? existsSync(opts.submitFlagPath) : true;
-            return finalizeReviewOutput(outPath, absFile, didSubmit);
+            if (existsSync(submitFlagPath)) {
+                const proposal = proposedFeedback(outPath, absFile);
+                if (!opts.signal?.aborted)
+                    await opts.onPropose?.(proposal);
+                return proposal;
+            }
+            return draftFeedback(outPath, absFile);
         }
         catch (err) {
             await stopReviewServer(server);

package/dist/inbox/claim.d.ts

@@ -0,0 +1,23 @@
+export interface TicketClaim {
+    token: string;
+    host: string;
+    pid: number;
+    claimedAt: string;
+    heartbeatAt: string;
+    tmuxClient?: string;
+}
+export interface ClaimOptions {
+    host?: string;
+    pid?: number;
+    tmuxClient?: string;
+    now?: Date;
+}
+export declare function readTicketClaim(dir: string): TicketClaim | null;
+export declare function isStaleClaim(claim: TicketClaim, now?: number, localHost?: string): boolean;
+/** Acquire a visible claim only for a still-pending ticket. Malformed crash artifacts are stale claims. */
+export declare function claimTicket(dir: string, opts?: ClaimOptions): TicketClaim | null;
+export declare function heartbeatClaim(dir: string, token: string, now?: Date): boolean;
+export declare function releaseClaimLocked(dir: string, token: string): boolean;
+export declare function releaseClaim(dir: string, token: string): boolean;
+export declare function claimExists(dir: string): boolean;
+export declare function withTicketLock<T>(dir: string, operation: () => T): T;

package/dist/inbox/claim.js

@@ -0,0 +1,67 @@
+import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { claimPath, deckPath, readJson, responsePath, reviewPath, withExclusiveDirectoryLock } from './convention.js';
+const REMOTE_STALE_MS = 30_000;
+function parseClaim(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return null;
+    const claim = raw;
+    if (typeof claim.token !== 'string' || typeof claim.host !== 'string' || !Number.isInteger(claim.pid) || typeof claim.claimedAt !== 'string' || typeof claim.heartbeatAt !== 'string')
+        return null;
+    return { token: claim.token, host: claim.host, pid: claim.pid, claimedAt: claim.claimedAt, heartbeatAt: claim.heartbeatAt, ...(typeof claim.tmuxClient === 'string' ? { tmuxClient: claim.tmuxClient } : {}) };
+}
+export function readTicketClaim(dir) { return parseClaim(readJson(claimPath(dir))); }
+function isLiveLocalPid(pid) { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch {
+    return false;
+} }
+export function isStaleClaim(claim, now = Date.now(), localHost = hostname()) {
+    if (claim.host === localHost)
+        return !isLiveLocalPid(claim.pid);
+    const heartbeat = Date.parse(claim.heartbeatAt);
+    return !Number.isFinite(heartbeat) || now - heartbeat > REMOTE_STALE_MS;
+}
+/** Acquire a visible claim only for a still-pending ticket. Malformed crash artifacts are stale claims. */
+export function claimTicket(dir, opts = {}) {
+    return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => {
+        if (existsSync(responsePath(dir)) || (!existsSync(deckPath(dir)) && !existsSync(reviewPath(dir))))
+            return null;
+        const path = claimPath(dir);
+        const existing = readTicketClaim(dir);
+        if (existing !== null && !isStaleClaim(existing, Date.now(), opts.host ?? hostname()))
+            return null;
+        if (existsSync(path))
+            unlinkSync(path);
+        const host = opts.host ?? hostname();
+        const pid = opts.pid ?? process.pid;
+        const now = (opts.now ?? new Date()).toISOString();
+        const claim = { token: randomUUID(), host, pid, claimedAt: now, heartbeatAt: now, ...(opts.tmuxClient ? { tmuxClient: opts.tmuxClient } : {}) };
+        writeFileSync(path, `${JSON.stringify(claim)}\n`, { flag: 'wx', mode: 0o600 });
+        return claim;
+    });
+}
+export function heartbeatClaim(dir, token, now = new Date()) {
+    return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => {
+        const claim = readTicketClaim(dir);
+        if (claim === null || claim.token !== token)
+            return false;
+        const temp = `${claimPath(dir)}.${token}.heartbeat`;
+        writeFileSync(temp, `${JSON.stringify({ ...claim, heartbeatAt: now.toISOString() })}\n`, { flag: 'wx', mode: 0o600 });
+        renameSync(temp, claimPath(dir));
+        return true;
+    });
+}
+export function releaseClaimLocked(dir, token) {
+    const claim = readTicketClaim(dir);
+    if (claim === null || claim.token !== token)
+        return false;
+    unlinkSync(claimPath(dir));
+    return true;
+}
+export function releaseClaim(dir, token) { return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, () => releaseClaimLocked(dir, token)); }
+export function claimExists(dir) { return existsSync(claimPath(dir)); }
+export function withTicketLock(dir, operation) { return withExclusiveDirectoryLock(`${dir}/.ticket-lock`, operation); }

package/dist/inbox/completion.d.ts

@@ -0,0 +1,4 @@
+/** Deliver one canonical result. It is safe to call repeatedly after crashes. */
+export declare function dispatchCompletion(root: string, dir: string): Promise<'delivered' | 'pending' | 'none'>;
+/** Event-driven startup/root-change reconciliation for results lacking an ack. */
+export declare function reconcileCompletions(root: string): Promise<void>;

package/dist/inbox/completion.js

@@ -0,0 +1,100 @@
+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) => {
+        const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+        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);
+            if (timedOut)
+                rejectPromise(new Error('completion handler timed out after 30 seconds'));
+            else if (code === 0)
+                resolvePromise();
+            else
+                rejectPromise(new Error(`completion handler failed (${signal ?? code ?? 'unknown'})`));
+        });
+        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);
+    }
+}