@north-light/crouter 0.3.170 → 0.3.172

package/dist/core/document-lines.d.ts

@@ -0,0 +1,4 @@
+/** The document's logical lines: a single terminating newline closes the last
+ *  line rather than opening an empty one. Never empty — an empty document is
+ *  one empty line. */
+export declare function documentLines(text: string): string[];

package/dist/core/document-lines.js

@@ -0,0 +1,6 @@
+/** The document's logical lines: a single terminating newline closes the last
+ *  line rather than opening an empty one. Never empty — an empty document is
+ *  one empty line. */
+export function documentLines(text) {
+    return (text.endsWith('\n') ? text.slice(0, -1) : text).split('\n');
+}

package/dist/core/feed/feed.d.ts

@@ -29,3 +29,5 @@ export declare function pushUrgent(nodeId: string, body: string, opts?: {
 export declare function pushFinal(nodeId: string, body: string, opts?: {
     from?: string;
 }): Promise<PushResult>;
+/** Re-fan a previously committed final to its ticket origin without finalizing again. */
+export declare function redeliverFinalReport(nodeId: string, originNodeId: string, reportBasename: string, body: string): PushResult;

package/dist/core/feed/feed.js

@@ -92,13 +92,6 @@ function commitCanonicalFinal(nodeId, staged) {
         install(staged);
         installed = true;
         db.prepare("UPDATE nodes SET status = 'done', intent = 'done', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(staged.basename, staged.ts, nodeId);
-        // Follow-up human-work promotion remains inside this canonical-final
-        // transaction: a crash after finalization leaves a durable `pending`
-        // receipt for follow-up reconciliation. Visual work deliberately has no
-        // final dispatch path in this slice, and its namespaced statuses make this
-        // legacy promotion blind to Visual rows.
-        db.prepare("UPDATE consult_outbox SET status = 'pending', final_report = ?, updated_at = ? WHERE node_id = ? AND work_kind = 'follow_up' AND status = 'armed'").run(staged.basename, staged.ts, nodeId);
-        db.prepare("UPDATE consult_outbox SET status = 'visual_pending', final_report = ?, updated_at = ? WHERE node_id = ? AND work_kind = 'visual' AND status = 'visual_armed'").run(staged.basename, staged.ts, nodeId);
         db.exec('COMMIT');
         return { subscribers };
     }
@@ -157,3 +150,14 @@ export async function pushUrgent(nodeId, body, opts) {
 export async function pushFinal(nodeId, body, opts) {
     return push(nodeId, { kind: 'final', body, ...opts });
 }
+/** Re-fan a previously committed final to its ticket origin without finalizing again. */
+export function redeliverFinalReport(nodeId, originNodeId, reportBasename, body) {
+    if (reportBasename === '' || reportBasename.includes('/') || reportBasename.includes('\\')) {
+        throw new Error(`invalid canonical final report basename: ${reportBasename}`);
+    }
+    const { deliveredTo, failedTo } = deliver([{ node_id: originNodeId, active: true, created: '' }], nodeId, 'final', `${nodeId}:reports/${reportBasename}`, body);
+    const reportPath = join(reportsDir(nodeId), reportBasename);
+    if (failedTo.length > 0)
+        throw new FinalDeliveryError(reportPath, deliveredTo, failedTo);
+    return { reportPath, deliveredTo };
+}

package/dist/core/human/__tests__/inbox-cancel-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/human/__tests__/inbox-cancel-worker.js

@@ -0,0 +1,7 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { cancelTicket } from '../tickets.js';
+const [dir, barrier, ready] = process.argv.slice(2);
+writeFileSync(ready, 'ready');
+while (!existsSync(barrier))
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1);
+process.stdout.write(JSON.stringify(cancelTicket(dir)));

package/dist/core/human/__tests__/inbox-claim-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/human/__tests__/inbox-claim-worker.js

@@ -0,0 +1,17 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { claimTicket } from '../claim.js';
+const [dir, barrier, ready, result, release] = process.argv.slice(2);
+const spin = (path) => { while (!existsSync(path))
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1); };
+writeFileSync(ready, 'ready');
+spin(barrier);
+const claim = claimTicket(dir);
+writeFileSync(result, JSON.stringify(claim));
+process.stdout.write(JSON.stringify(claim));
+// Stay alive until the parent has read BOTH results and releases us. A same-host
+// claim is reclaimable the instant its holder's pid dies, so a winner that exited
+// early would legitimately free its claim for the peer — that is designed
+// stale-recovery, not a double-claim. Blocking here keeps both pids live across
+// the peer's attempt, so the assertion tests exclusion, not exit timing.
+if (release !== undefined)
+    spin(release);

package/dist/core/human/__tests__/inbox-core.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/human/__tests__/inbox-core.test.js

@@ -0,0 +1,144 @@
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { submitDeck, submitReview, completeDeck, cancelTicket, readTicketResult } from '../tickets.js';
+import { claimTicket } from '../claim.js';
+import { scanInbox } from '../scan.js';
+import { atomicWriteJson, progressPath, responsePath } from '../convention.js';
+import { validateDeck } from '../deck-schema.js';
+import { ticketDir } from '../root.js';
+const temp = mkdtempSync(join(tmpdir(), 'crtr-inbox-core-'));
+process.env['CRTR_HOME'] = temp;
+const source = join(temp, 'source.md');
+writeFileSync(source, '# Source\n');
+const deck = (blockedSince) => ({ title: 'A deck', source: { blockedSince, nodeId: 'node-1' }, interactions: [{ id: 'go', title: 'Go?', subtitle: 'Go? requires your attention.', options: [{ id: 'yes', label: 'Yes' }] }] });
+assert.throws(() => validateDeck({ interactions: [{ id: 'go', title: 'Go?', subtitle: 'Go? requires your attention.', options: [] }] }), /title/, 'a deck must carry its own explicit inbox title');
+assert.throws(() => validateDeck({ title: 'Missing subtitle', interactions: [{ id: 'go', title: 'Go?', options: [] }] }), /subtitle/, 'a deck interaction without an authored subtitle is invalid');
+async function waitFor(paths) {
+    for (let attempts = 0; !paths.every(existsSync); attempts++) {
+        if (attempts > 1_000)
+            throw new Error(`workers did not reach barrier: ${paths.join(', ')}`);
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 1));
+    }
+}
+const oldDeck = submitDeck({ dir: ticketDir('z-last'), deck: deck('2025-01-01T00:00:00.000Z') });
+const newDeck = submitDeck({ dir: ticketDir('a-first'), deck: deck('2025-01-02T00:00:00.000Z') });
+const review = submitReview({ dir: ticketDir('review'), review: { file: source, title: 'Review source', subtitle: 'Review findings require your decision.', source: { nodeId: 'node-1' }, blockedSince: '2025-01-02T00:00:00.000Z' } });
+assert.throws(() => submitReview({ dir: ticketDir('missing-review-subtitle'), review: { file: source, title: 'Missing subtitle', source: {} } }), /subtitle/, 'a review without an authored subtitle is invalid');
+assert.throws(() => submitReview({ dir: ticketDir('bad-review'), review: { file: join(temp, 'missing.md'), title: 'Bad', subtitle: 'This invalid review must be rejected.', source: {} } }), /existing absolute path/);
+assert.equal(existsSync(ticketDir('bad-review')), false, 'invalid submission does not strand an id');
+const prepared = ticketDir('prepared');
+mkdirSync(prepared);
+writeFileSync(join(prepared, 'body.md'), 'prepared body');
+const preparedTicket = submitDeck({ dir: prepared, deck: { ...deck('2025-01-02T00:00:00.000Z'), interactions: [{ id: 'go', title: 'Go?', subtitle: 'Go? requires your attention.', bodyPath: 'body.md', options: [{ id: 'yes', label: 'Yes' }] }] } });
+assert.equal(preparedTicket.dir, realpathSync(prepared), 'submission accepts a crouter-precreated direct child and colocated assets');
+// Same timestamp is stable by id; progress is resumable work, never a hidden lease.
+atomicWriteJson(progressPath(newDeck.dir), { kind: 'deck', responses: [], savedAt: new Date().toISOString() });
+const scanned = scanInbox();
+assert.deepEqual(scanned.map((item) => item.id), ['a-first', 'prepared', 'review', 'z-last']);
+assert.equal(scanned.find((item) => item.id === 'a-first')?.claim, undefined);
+assert.equal(scanned.find((item) => item.id === 'review')?.kind, 'review');
+assert.equal(scanned.find((item) => item.id === 'review')?.subtitle, 'Review findings require your decision.', 'review scanning exposes its required subtitle');
+const firstClaim = claimTicket(newDeck.dir);
+assert.notEqual(firstClaim, null);
+assert.equal(claimTicket(newDeck.dir), null, 'a second controller cannot claim a live ticket');
+// A separate process writes a genuine remote claim whose heartbeat is already
+// stale, then exits; this process recovers it — cross-process stale recovery.
+const staleDir = submitDeck({ dir: ticketDir('stale'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+const staleClaimReady = join(temp, 'stale-claim-ready');
+await new Promise((resolveWorker, rejectWorker) => spawn(process.execPath, ['--conditions=crtr-src', '--import', 'tsx', 'src/core/human/__tests__/inbox-stale-claim-worker.ts', staleDir, staleClaimReady], { cwd: process.cwd(), stdio: ['ignore', 'ignore', 'inherit'] }).once('exit', (code) => code === 0 ? resolveWorker() : rejectWorker(new Error('stale-claim worker failed'))));
+assert.notEqual(JSON.parse(readFileSync(staleClaimReady, 'utf8')), null, 'a separate process wrote a stale remote claim on disk');
+assert.notEqual(claimTicket(staleDir), null, 'a remote claim written by another process recovers once its heartbeat has expired');
+const malformedDir = submitDeck({ dir: ticketDir('malformed-claim'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+writeFileSync(join(malformedDir, 'claim.json'), '{');
+assert.notEqual(claimTicket(malformedDir), null, 'partial claim crash artifact recovers');
+const final = completeDeck(newDeck.dir, [{ id: 'go', selectedOptionId: 'yes' }], firstClaim.token);
+assert.equal(final.won, true);
+assert.equal(readTicketResult(newDeck.dir)?.kind, 'deck');
+assert.equal(claimTicket(newDeck.dir), null, 'terminal tickets cannot be claimed');
+const exactResults = [
+    { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '', completedAt: '2025-01-04T00:00:00.000Z' },
+    { schema: 'humanloop.review-response/v1', kind: 'review', result: { file: source, submitted: true, approved: true, comments: [], submittedAt: '2025-01-04T00:00:00.000Z', savedAt: '2025-01-04T00:00:00.000Z', reviewId: 'review-1', changed: false, baselineSha256: 'baseline', approvedSha256: 'approved', companionNodeId: 'companion-1', commentsTotal: 0, commentsUnresolved: 0 }, completedAt: '2025-01-04T00:00:00.000Z' },
+    { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: '2025-01-04T00:00:00.000Z', reason: 'stop', actor: 'test' },
+];
+for (const [index, result] of exactResults.entries()) {
+    const dir = submitDeck({ dir: ticketDir(`strict-${index}`), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+    writeFileSync(responsePath(dir), JSON.stringify(result));
+    assert.equal(readTicketResult(dir)?.kind, result.kind, `strict decoder accepts exact ${result.kind} result`);
+}
+const validFeedback = exactResults[1].result;
+const iso = '2025-01-04T00:00:00.000Z';
+const rejectFixtures = [
+    { why: 'a wrong kind for a known schema', result: { schema: 'humanloop.response/v2', kind: 'review', responses: [], summary: '', completedAt: iso } },
+    { why: 'an unknown schema id', result: { schema: 'humanloop.response/v9', kind: 'deck', responses: [], summary: '', completedAt: iso } },
+    { why: 'a deck missing its required completedAt', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '' } },
+    { why: 'a deck with a non-ISO completedAt', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '', completedAt: 'now' } },
+    { why: 'a deck with an unrecognized nested response field', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [{ id: 'go', bogus: true }], summary: '', completedAt: iso } },
+    { why: 'a deck with an extra top-level field', result: { schema: 'humanloop.response/v2', kind: 'deck', responses: [], summary: '', completedAt: iso, extra: true } },
+    { why: 'a review missing its required result', result: { schema: 'humanloop.review-response/v1', kind: 'review', completedAt: iso } },
+    { why: 'a review whose nested result is not submitted', result: { schema: 'humanloop.review-response/v1', kind: 'review', result: { ...validFeedback, submitted: false }, completedAt: iso } },
+    { why: 'a review with incomplete comment columns', result: { schema: 'humanloop.review-response/v1', kind: 'review', result: { ...validFeedback, approved: true, comments: [{ id: 'c1', line: 1, endLine: 1, colStart: 1, lineText: '# Source', comment: 'x', createdAt: iso }] }, completedAt: iso } },
+    { why: 'a review nested comment whose endLine precedes its line', result: { schema: 'humanloop.review-response/v1', kind: 'review', result: { ...validFeedback, approved: false, comments: [{ id: 'c1', line: 5, endLine: 2, lineText: '# Source', comment: 'x', createdAt: iso }] }, completedAt: iso } },
+    { why: 'a review with an extra top-level field', result: { schema: 'humanloop.review-response/v1', kind: 'review', result: validFeedback, completedAt: iso, extra: true } },
+    { why: 'a canceled result missing its required canceledAt', result: { schema: 'humanloop.cancel/v1', kind: 'canceled', reason: 'stop' } },
+    { why: 'a canceled result with a non-ISO canceledAt', result: { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: 'now' } },
+    { why: 'a canceled result with an extra top-level field', result: { schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: iso, extra: true } },
+];
+for (const [index, fixture] of rejectFixtures.entries()) {
+    const dir = submitDeck({ dir: ticketDir(`strict-reject-${index}`), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+    writeFileSync(responsePath(dir), JSON.stringify(fixture.result));
+    assert.equal(readTicketResult(dir), null, `strict decoder rejects ${fixture.why}`);
+}
+const protocolDir = ticketDir('stale-protocol');
+mkdirSync(protocolDir);
+writeFileSync(responsePath(protocolDir), '{}');
+assert.throws(() => submitDeck({ dir: protocolDir, deck: deck('2025-01-03T00:00:00.000Z') }), /protocol state/, 'precreated assets may not include humanloop lifecycle state');
+const cancelDir = submitDeck({ dir: ticketDir('cancel-race'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+const canceled = cancelTicket(cancelDir, { reason: 'stop' });
+assert.equal(canceled.status, 'canceled');
+assert.equal(cancelTicket(cancelDir).status, 'already_resolved', 'first final writer wins');
+const finalRaceDir = submitDeck({ dir: ticketDir('final-race'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+const finalRaceClaim = claimTicket(finalRaceDir);
+const finalBarrier = join(temp, 'final-race-barrier');
+const finalReady = join(temp, 'final-race-ready');
+const cancelWorker = spawn(process.execPath, ['--conditions=crtr-src', '--import', 'tsx', 'src/core/human/__tests__/inbox-cancel-worker.ts', finalRaceDir, finalBarrier, finalReady], { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'pipe'] });
+await waitFor([finalReady]);
+writeFileSync(finalBarrier, 'go');
+const finalRace = completeDeck(finalRaceDir, [{ id: 'go', selectedOptionId: 'yes' }], finalRaceClaim.token);
+await new Promise((resolveWorker, rejectWorker) => cancelWorker.once('exit', (code) => code === 0 ? resolveWorker() : rejectWorker(new Error('cancel worker failed'))));
+assert.equal(readTicketResult(finalRaceDir)?.kind, finalRace.won ? 'deck' : 'canceled', 'submit and cancellation race has one canonical winner');
+const concurrentDir = submitDeck({ dir: ticketDir('concurrent-claim'), deck: deck('2025-01-03T00:00:00.000Z') }).dir;
+const claimBarrier = join(temp, 'claim-race-barrier');
+// Both workers block on this release until the parent has read both results, so
+// neither winner's pid dies during the peer's attempt (a dead same-host pid is
+// legitimately reclaimable — that stale-recovery race, not a double claim, is
+// what previously flaked this assertion).
+const claimRelease = join(temp, 'claim-race-release');
+let claimWorkerNumber = 0;
+const claimReadyPaths = [];
+const claimResultPaths = [];
+const runClaimWorker = () => new Promise((resolveWorker, rejectWorker) => {
+    const n = claimWorkerNumber++;
+    const ready = join(temp, `claim-race-ready-${n}`);
+    const result = join(temp, `claim-race-result-${n}`);
+    claimReadyPaths.push(ready);
+    claimResultPaths.push(result);
+    const child = spawn(process.execPath, ['--conditions=crtr-src', '--import', 'tsx', 'src/core/human/__tests__/inbox-claim-worker.ts', concurrentDir, claimBarrier, ready, result, claimRelease], { cwd: process.cwd(), stdio: ['ignore', 'ignore', 'pipe'] });
+    let errors = '';
+    child.stderr.on('data', (chunk) => { errors += chunk; });
+    child.once('exit', (code) => code === 0 ? resolveWorker() : rejectWorker(new Error(errors)));
+});
+const concurrentClaimRuns = [runClaimWorker(), runClaimWorker()];
+await waitFor(claimReadyPaths);
+writeFileSync(claimBarrier, 'go');
+await waitFor(claimResultPaths);
+const concurrentClaims = claimResultPaths.map((path) => JSON.parse(readFileSync(path, 'utf8')));
+assert.equal(concurrentClaims.filter((claim) => claim !== null).length, 1, 'separate processes exclusively claim one ticket');
+writeFileSync(claimRelease, 'go');
+await Promise.all(concurrentClaimRuns);
+assert.throws(() => submitReview({ dir: ticketDir('bad-output'), review: { file: source, output: responsePath(review.dir), title: 'Bad output', subtitle: 'This invalid output path must be rejected.', source: {} } }), /must not alias/, 'review output cannot replace a ticket response');
+assert.throws(() => submitReview({ dir: ticketDir('source-output'), review: { file: source, output: source, title: 'Bad output', subtitle: 'This invalid output path must be rejected.', source: {} } }), /must not alias/, 'review output cannot overwrite its source');
+rmSync(temp, { recursive: true, force: true });
+console.log('inbox core tests passed');

package/dist/core/human/__tests__/inbox-stale-claim-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/human/__tests__/inbox-stale-claim-worker.js

@@ -0,0 +1,8 @@
+import { writeFileSync } from 'node:fs';
+import { claimTicket } from '../claim.js';
+// Writes a genuine claim from a SEPARATE process, as a remote host whose
+// heartbeat is already older than the remote-stale window, then exits. The
+// parent process then recovers the ticket, proving cross-process stale recovery.
+const [dir, ready] = process.argv.slice(2);
+const claim = claimTicket(dir, { host: 'other-host', pid: 1, now: new Date(Date.now() - 31_000) });
+writeFileSync(ready, JSON.stringify(claim));

package/dist/core/human/__tests__/visible-paths.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/{clients/attach → core/human}/__tests__/visible-paths.test.js

@@ -17,3 +17,12 @@ test('checkReviewableFile rejects non-files and binary text', () => {
     assert.deepEqual(checkReviewableFile(root), { ok: false, reason: 'not a file' });
     assert.deepEqual(checkReviewableFile(binary), { ok: false, reason: 'file is not UTF-8 text' });
 });
+test('checkReviewableFile admits a newline-terminated document at the 5,000-line limit and rejects 5,001', () => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-reviewable-limit-'));
+    const atLimit = join(root, 'at-limit.md');
+    const overLimit = join(root, 'over-limit.md');
+    writeFileSync(atLimit, 'line\n'.repeat(5000));
+    writeFileSync(overLimit, 'line\n'.repeat(5001));
+    assert.deepEqual(checkReviewableFile(atLimit), { ok: true });
+    assert.deepEqual(checkReviewableFile(overLimit), { ok: false, reason: 'file is too long to review (5,000 line limit)' });
+});

package/dist/core/human/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/core/human/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/core/human/convention.d.ts

@@ -0,0 +1,30 @@
+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 type InteractionState = 'pending' | 'claimed' | 'resolved' | 'missing';
+export declare function interactionState(dir: string): InteractionState;
+export declare function isResolved(dir: string): boolean;
+export declare function isClaimed(dir: string): boolean;
+/** Resolve and verify a ticket directory without a registry. */
+export declare function requireTicket(dir: string): string;
+export declare function stampCanvasNode(deck: Deck): void;
+export declare function atomicWriteJson(path: string, value: unknown): void;
+/** Publish one immutable JSON record without replacing an existing winner. */
+export declare function publishJsonExclusive(path: string, value: unknown): boolean;
+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/core/human/convention.js

@@ -0,0 +1,202 @@
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, 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';
+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 interactionState(dir) {
+    if (!existsSync(deckPath(dir)) && !existsSync(reviewPath(dir)))
+        return 'missing';
+    if (existsSync(responsePath(dir)))
+        return 'resolved';
+    return existsSync(claimPath(dir)) ? 'claimed' : 'pending';
+}
+export function isResolved(dir) { return existsSync(responsePath(dir)); }
+export function isClaimed(dir) { return existsSync(claimPath(dir)); }
+/** Resolve and verify a ticket directory without a registry. */
+export function requireTicket(dir) {
+    const canonicalDir = realpathSync(dir);
+    if (!existsSync(deckPath(canonicalDir)) && !existsSync(reviewPath(canonicalDir))) {
+        throw new Error('ticket directory has no deck or review');
+    }
+    return canonicalDir;
+}
+export function stampCanvasNode(deck) {
+    const id = process.env['CRTR_NODE_ID'];
+    if (id === undefined || id.trim() === '' || deck.source?.nodeId)
+        return;
+    deck.source = { ...(deck.source ?? {}), nodeId: id };
+}
+export function atomicWriteJson(path, value) {
+    const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/** Publish one immutable JSON record without replacing an existing winner. */
+export function publishJsonExclusive(path, value) {
+    const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    try {
+        linkSync(tmp, path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+    finally {
+        unlinkSync(tmp);
+    }
+}
+export function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+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 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), { kind: 'deck', responses, savedAt: new Date().toISOString() });
+}
+export function clearProgress(dir) {
+    try {
+        unlinkSync(progressPath(dir));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}

package/dist/core/human/deck-factories.d.ts

@@ -0,0 +1,8 @@
+import type { Deck } from './types.js';
+export interface NotifyDeckOpts {
+    /** One plain-English sentence stating the notification's status and stakes. */
+    subtitle: string;
+    body?: string;
+}
+/** Build a validated single-option notify deck. id: 'notify', kind: 'notify'. */
+export declare function notifyDeck(title: string, opts: NotifyDeckOpts): Deck;

package/dist/core/human/deck-factories.js

@@ -0,0 +1,15 @@
+import { validateDeck } from './deck-schema.js';
+/** Build a validated single-option notify deck. id: 'notify', kind: 'notify'. */
+export function notifyDeck(title, opts) {
+    return validateDeck({
+        title,
+        interactions: [{
+                id: 'notify',
+                title,
+                subtitle: opts.subtitle,
+                ...(opts.body !== undefined ? { body: opts.body } : {}),
+                kind: 'notify',
+                options: [{ id: 'ok', label: 'OK' }],
+            }],
+    });
+}