@north-light/api 0.3.580 → 0.3.588

package/dist/daemon/cron/run-socket.js

@@ -0,0 +1,170 @@
+// src/daemon/cron/run-socket.ts — the per-execution socket: a cron command's only path to the daemon.
+//
+// Every cron execution gets `nodeRunDir('cron-<execution_id>')` (on Linux `/run/crtr/nodes/cron-<id>/`) holding
+// `cli.sock` and `cron-launch.json`. The launcher bind-mounts that folder (and nothing else of `/run/crtr/nodes`)
+// into the execution's sandbox, so the folder IS the identity: a request on this socket is the execution
+// registered under the folder's id, answered as the `cron` principal class. No bearer, no creator broker relay.
+import { createServer } from 'node:http';
+import { chmodSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { peerUid } from '../../native/linux.js';
+import { nodeRunDir } from '../../core/canvas/paths.js';
+import { readConfig, readMergedLaunchConfig } from '../../core/config.js';
+import { loadRotationConfig } from '../../core/subscription-state.js';
+import { runningCrons } from '../../core/canvas/crons.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { cronLaunchId } from '../../core/spaces/process.js';
+import { ensureAppSpace } from '../../core/spaces/space.js';
+import { launcherPresent, listSandboxes } from '../../core/grants/sandboxes.js';
+import { uidForApp } from '../../core/spaces/users.js';
+import { setModeBeneath, writeFileBeneath } from '../../core/spaces/open-beneath.js';
+import { cronExecutionFor, cronExecutions, dropCronExecution, registerCronExecution } from './live-runs.js';
+let requestHandler = null;
+export function setCronRequestHandler(handler) { requestHandler = handler; }
+const linuxPeerUid = (req) => process.platform === 'linux' ? peerUid(req.socket) : null;
+let peerOf = linuxPeerUid;
+/** Test seam: the peer uid of a request (null = unchecked). */
+export function __setCronPeerUidForTest(fn) { peerOf = fn ?? linuxPeerUid; }
+const listeners = new Map();
+export function cronSocketPath(executionId) { return join(nodeRunDir(cronLaunchId(executionId)), 'cli.sock'); }
+export function cronPrincipalClassOf(e) {
+    const common = { class: 'cron', app: e.grantee, sub: e.sub, grant: e.grantId, scopes: e.scopes, execution: e.executionId, from_exec: e.fromExec,
+        origin_run: e.originRunId, isolated: e.isolated, anchor: e.anchor, uid: e.uid };
+    return e.kind === 'cron' ? { ...common, kind: 'cron', cron: e.cronId } : { ...common, kind: 'exec', cron: null };
+}
+function refuse(res, status, code, message) {
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ error: { code, message, type: 'invalid_request_error', origin: 'runtime', retryable: false } }));
+}
+function onCronRequest(executionId) {
+    return (req, res) => {
+        try {
+            // Absent means settled: the execution finished (or was never registered), so its socket answers nothing.
+            const execution = cronExecutionFor(executionId);
+            if (execution === undefined) {
+                refuse(res, 401, 'unauthorized', 'this cron execution has ended');
+                return;
+            }
+            const uid = peerOf(req);
+            if (uid !== null && uid !== execution.uid) {
+                emitEvent({ event: 'api.principal.denied', level: 'warn', fields: { method: req.method, execution: executionId } });
+                refuse(res, 401, 'unauthorized', 'missing or invalid bearer token');
+                return;
+            }
+            if (requestHandler === null) {
+                refuse(res, 503, 'daemon_unavailable', 'the API server is not running');
+                return;
+            }
+            requestHandler(req, res, cronPrincipalClassOf(execution));
+        }
+        catch (error) {
+            emitEvent({ event: 'api.principal.failed', level: 'error', error: error instanceof Error ? error : new Error(String(error)) });
+            if (!res.headersSent)
+                refuse(res, 401, 'unauthorized', 'missing or invalid bearer token');
+        }
+    };
+}
+async function listen(executionId) {
+    const path = cronSocketPath(executionId);
+    if (existsSync(path))
+        unlinkSync(path);
+    const server = createServer(onCronRequest(executionId));
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(path, () => { server.off('error', reject); resolve(); });
+    });
+    // Reachable by the app uid only because the folder (0770, app-owned once launched) is the gate, as `api.sock` is.
+    chmodSync(path, 0o666);
+    listeners.set(executionId, server);
+}
+/** Register the execution and open its socket. The folder is created daemon-owned, group daemon, mode 0770 — the state
+ *  the root launcher's `SourceValidator.pin` accepts and re-owns to the app uid for a launch whose node id is
+ *  `cron-<execution_id>` (`launcher/validate.ts`); `cron-launch.json` carries the config snapshot a sandboxed
+ *  `crtr` installs (the shape of `broker-launch.json`'s). */
+export async function openCronExecution(execution, cwd, profileId) {
+    const dir = nodeRunDir(cronLaunchId(execution.executionId));
+    registerCronExecution(execution);
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o770 });
+        chmodSync(dir, 0o770);
+        const configSnapshot = { user: readConfig('user'), launch: readMergedLaunchConfig(cwd, profileId), rotation: await loadRotationConfig() };
+        const launchFile = join(dir, 'cron-launch.json');
+        writeFileBeneath(dir, launchFile, JSON.stringify({ configSnapshot }), { atomic: true, mode: 0o640 });
+        // The sandbox reads this file as the app uid in the app's group, not the daemon's: give the file the app space's group,
+        // as a node's `broker-launch.json` gets it (`host.ts`). A failure here fails the launch closed.
+        if (launcherPresent()) {
+            const space = await ensureAppSpace(execution.grantee);
+            setModeBeneath(dir, launchFile, 0o640, { uid: process.getuid(), gid: space.gid });
+        }
+        await listen(execution.executionId);
+    }
+    catch (error) {
+        closeCronExecution(execution.executionId);
+        throw error;
+    }
+}
+/** Close the listener, delete the execution folder, drop the registry entry. Idempotent. */
+export function closeCronExecution(executionId) {
+    dropCronExecution(executionId);
+    const server = listeners.get(executionId);
+    listeners.delete(executionId);
+    if (server !== undefined) {
+        server.closeAllConnections();
+        server.close();
+    }
+    try {
+        rmSync(nodeRunDir(cronLaunchId(executionId)), { recursive: true, force: true });
+    }
+    catch { /* best effort; the daemon-start cleanup retries */ }
+}
+let rebuilding = Promise.resolve();
+/** Resolves once a restart rebuild finished; the grant sweep waits on it so it never stops a live execution it has not yet re-registered. */
+export function cronExecutionsReady() { return rebuilding; }
+/** After a daemon restart the listener died with the daemon but the folder and the sandbox survived. Rebuild the registry from
+ *  `running` rows whose recorded execution id still has a live `cron-<id>` sandbox and re-listen on the same path; delete
+ *  `nodes/cron-*` folders with no live sandbox. A self-canceled execution (row deleted) cannot be rebuilt: it stays without
+ *  an API path and the grant sweep stops it. */
+export function rebuildCronExecutions(list = listSandboxes) {
+    const run = (async () => {
+        if (list === listSandboxes && !launcherPresent())
+            return;
+        const live = new Set((await list()).map((sandbox) => sandbox.nodeId));
+        for (const c of await runningCrons()) {
+            const id = c.run_execution_id;
+            if (id == null || !live.has(cronLaunchId(id)) || cronExecutionFor(id) !== undefined)
+                continue;
+            try {
+                registerCronExecution({ executionId: id, kind: 'cron', cronId: c.cron_id, fromExec: c.armed_from_exec, grantee: c.grantee, sub: c.sub, grantId: c.grant_id, scopes: c.scopes,
+                    originRunId: c.origin_run_id, isolated: c.isolated, anchor: c.anchor_node, uid: await uidForApp(c.grantee), rebuilt: true, refusal: null });
+                await listen(id);
+                emitEvent({ level: 'info', event: 'cron.execution.rebuilt', fields: { cron_id: c.cron_id, execution_id: id } });
+            }
+            catch (error) {
+                dropCronExecution(id);
+                emitEvent({ level: 'error', event: 'cron.execution.rebuild_failed', error, fields: { cron_id: c.cron_id, execution_id: id } });
+            }
+        }
+        if (process.platform !== 'linux')
+            return;
+        const root = dirname(nodeRunDir(cronLaunchId('x')));
+        if (!existsSync(root))
+            return;
+        for (const name of readdirSync(root)) {
+            if (!name.startsWith('cron-') || live.has(name))
+                continue;
+            try {
+                rmSync(join(root, name), { recursive: true, force: true });
+            }
+            catch { /* retried at the next start */ }
+        }
+    })();
+    rebuilding = run.catch((error) => { emitEvent({ level: 'error', event: 'cron.execution.rebuild_failed', error }); });
+    return rebuilding;
+}
+/** Close rebuilt executions whose row no longer records them (their lease settled elsewhere). Own executions close in the executor. */
+export async function reapRebuiltCronExecutions() {
+    const recorded = new Set((await runningCrons()).map((c) => c.run_execution_id));
+    for (const e of cronExecutions())
+        if (e.rebuilt && !recorded.has(e.executionId))
+            closeCronExecution(e.executionId);
+}

package/dist/daemon/drain.d.ts

@@ -0,0 +1,25 @@
+/** How long turns in flight get to settle before their broker is stopped. */
+export declare const DRAIN_SETTLE_LIMIT_MS: number;
+export interface DrainStateDTO {
+    drained: boolean;
+    /** When the drain began (ISO), null when not drained. */
+    since: string | null;
+    /** Nodes with a turn in flight and a live broker right now. */
+    busy_nodes: string[];
+    /** Brokers stopped as a dormant exit because their turn outlived the limit (set by the call that waited). */
+    stopped_nodes: string[];
+}
+export declare function drainedSince(): Promise<string | null>;
+export declare function isDrained(): Promise<boolean>;
+/** Nodes mid-turn with a live broker: an open turn and a recorded pid that answers (the roster's own definition of busy). */
+export declare function busyNodes(): Promise<string[]>;
+/** Begin the drain. Idempotent: a second call keeps the first call's start time. */
+export declare function startDrain(now?: Date): Promise<DrainStateDTO>;
+export declare function endDrain(): Promise<DrainStateDTO>;
+export declare function drainState(stopped?: string[]): Promise<DrainStateDTO>;
+/** Wait for turns in flight to settle; past `limitMs`, stop each remaining broker as a dormant exit (the node is released, so
+ *  the lifecycle lane does not respawn it as a crash, and its mail stays pending). */
+export declare function settleDrain(opts?: {
+    limitMs?: number;
+    pollMs?: number;
+}): Promise<DrainStateDTO>;

package/dist/daemon/drain.js

@@ -0,0 +1,76 @@
+// Drain: the source side of an import pauses its own daemon so the row dump sees a quiet install.
+// Design: design-import, Exporter row "drain" — no new wake, no cron fire, warm pool emptied, turns in flight settle
+// (limit 10 minutes, then the broker is stopped as a dormant exit); deliveries stay `pending`.
+//
+// The flag is one `runtime_state` row, so every lane and request handler in the process reads the same answer and a daemon
+// restart in the middle of an export stays drained. Whoever started the drain ends it (`crtr sys import start` on failure,
+// `crtr sys import resume` after a crash).
+import { openDb } from '../core/canvas/db.js';
+import { isPidPresent } from '../core/canvas/pid.js';
+import { emptyWarmPool } from '../core/runtime/warm-pool.js';
+import { requestBrokerTeardown } from '../core/runtime/host.js';
+import { transition } from '../core/runtime/lifecycle.js';
+import { emitEvent } from '../core/events/emit.js';
+const KEY = 'drain';
+/** How long turns in flight get to settle before their broker is stopped. */
+export const DRAIN_SETTLE_LIMIT_MS = 10 * 60_000;
+const POLL_MS = 1_000;
+export async function drainedSince() {
+    const row = await (await openDb()).prepare('SELECT value FROM runtime_state WHERE key = ?').get(KEY);
+    return row?.value ?? null;
+}
+export async function isDrained() {
+    return await drainedSince() !== null;
+}
+/** Nodes mid-turn with a live broker: an open turn and a recorded pid that answers (the roster's own definition of busy). */
+export async function busyNodes() {
+    const rows = await (await openDb()).prepare(`
+    SELECT node_id, pi_pid
+    FROM node_rows
+    WHERE node_id NOT IN (SELECT node_id FROM warm_pool)
+      AND kind != 'human'
+      AND pi_pid IS NOT NULL
+      AND turn_open_at IS NOT NULL
+      AND turn_closed_at IS NULL
+  `).all();
+    return rows.filter((row) => isPidPresent(row.pi_pid)).map((row) => row.node_id);
+}
+/** Begin the drain. Idempotent: a second call keeps the first call's start time. */
+export async function startDrain(now = new Date()) {
+    const db = await openDb();
+    await db.prepare('INSERT INTO runtime_state (key, value) VALUES (?, ?) ON CONFLICT(key) DO NOTHING').run(KEY, now.toISOString());
+    await emptyWarmPool();
+    emitEvent({ level: 'info', event: 'drain.started' });
+    return await drainState();
+}
+export async function endDrain() {
+    await (await openDb()).prepare('DELETE FROM runtime_state WHERE key = ?').run(KEY);
+    emitEvent({ level: 'info', event: 'drain.ended' });
+    return await drainState();
+}
+export async function drainState(stopped = []) {
+    const since = await drainedSince();
+    return { drained: since !== null, since, busy_nodes: await busyNodes(), stopped_nodes: stopped };
+}
+/** Wait for turns in flight to settle; past `limitMs`, stop each remaining broker as a dormant exit (the node is released, so
+ *  the lifecycle lane does not respawn it as a crash, and its mail stays pending). */
+export async function settleDrain(opts = {}) {
+    const limitMs = opts.limitMs ?? DRAIN_SETTLE_LIMIT_MS;
+    const pollMs = opts.pollMs ?? POLL_MS;
+    if (!await isDrained())
+        throw new Error('settleDrain: the daemon is not drained');
+    const deadline = Date.now() + limitMs;
+    let busy = await busyNodes();
+    while (busy.length > 0 && Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        busy = await busyNodes();
+    }
+    for (const id of busy) {
+        await transition(id, 'release');
+        const result = await requestBrokerTeardown(id, { reason: 'import-drain' });
+        if (!result.confirmed)
+            throw new Error(`drain: the broker of ${id} could not be confirmed stopped: ${result.error?.message ?? 'unknown'}`);
+        emitEvent({ level: 'warn', event: 'drain.broker_stopped', node_id: id });
+    }
+    return await drainState(busy);
+}

package/dist/daemon/human/finish.d.ts

@@ -0,0 +1,24 @@
+import type { TicketResult } from '../../core/human/types.js';
+export interface CompletePageOptions {
+    completedAt?: string;
+    actor?: string;
+}
+export interface CancelTicketOptions {
+    reason?: string;
+    actor?: string;
+    disposition?: 'canceled' | 'dismissed';
+}
+/** Settle a page request directly in human_requests; result files and bridge nodes are not part of this path. */
+export declare function resolvePageTicket(ticketId: string, responses: unknown, opts?: CompletePageOptions): Promise<TicketResult>;
+/** {@link resolvePageTicket}, also saying whether this answer won (`settled`) or the request was already settled. */
+export declare function answerPageTicket(ticketId: string, responses: unknown, opts?: CompletePageOptions): Promise<{
+    outcome: 'settled' | 'already_settled';
+    result: TicketResult;
+}>;
+export declare function cancelHumanTicket(ticketId: string, opts: CancelTicketOptions): Promise<{
+    outcome: 'settled' | 'already_settled';
+    result: TicketResult;
+}>;
+/** Legacy callers use this as a replay hook. Settlement effects are repaired by sweepHumanRequests. */
+export declare function deliverTerminalResult(ticketId: string): Promise<boolean>;
+export declare function settleFeedbackCompanion(ticketId: string, outcome: 'approved' | 'canceled'): Promise<void>;

package/dist/daemon/human/finish.js

@@ -0,0 +1,178 @@
+import { getRequest, getRequestByInboxTicket, presentationDir } from '../../core/human/requests.js';
+import { buildPageSummary } from '../../core/human/summary.js';
+import { validateFinalPageResponses } from '../../core/human/tickets.js';
+import { composeHumanCompletion } from '../../core/human/completion.js';
+import { describePageAnswer } from '../../core/human/answer.js';
+import { renderAnswerText } from '../../core/human/answer-text.js';
+import { readPageFeedback } from '../../core/human/feedback.js';
+import { pageDocumentSha256 } from '../../core/human/feedback-companion.js';
+import { pagePath } from '../../core/human/convention.js';
+import { retireCompanion } from '../companion-retire.js';
+import { settleHumanRequest } from './settle.js';
+async function requestForTicket(ticketId) {
+    const request = await getRequest(ticketId) ?? await getRequestByInboxTicket(ticketId);
+    if (request === null || request.kind !== 'page')
+        throw new Error(`unknown page request: ${ticketId}`);
+    return request;
+}
+function manifest(request) {
+    try {
+        const value = JSON.parse(request.specification_json);
+        if (typeof value !== 'object' || value === null)
+            throw new Error('not an object');
+        return value;
+    }
+    catch (error) {
+        throw new Error(`corrupt page specification: ${request.request_id}`, { cause: error });
+    }
+}
+function completionAction(request, result) {
+    if (request.action_json === null)
+        return undefined;
+    try {
+        const binding = JSON.parse(request.action_json);
+        if (binding.schema !== 'crtr.human-action-binding/v1' || !Array.isArray(binding.argv) || typeof binding.cwd !== 'string')
+            throw new Error('invalid binding');
+        return {
+            adapter: { adapter: 'subprocess', argv: binding.argv, cwd: binding.cwd, node_id: request.requester_node_id, ...(binding.app ? { app: binding.app } : {}) },
+            bodyJson: composeHumanCompletion({ requestId: request.request_id, result: result, binding, source: manifest(request).source ?? {} }),
+        };
+    }
+    catch (error) {
+        throw new Error(`corrupt frozen completion action: ${request.request_id}`, { cause: error });
+    }
+}
+function firstLine(text, maxLen = 80) {
+    const line = text.split('\n')[0] ?? '';
+    return line.length > maxLen ? `${line.slice(0, maxLen - 1)}…` : line;
+}
+function pageTitle(request) {
+    try {
+        return manifest(request).title;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The settle-time feedback addendum — answer and cancellation alike: a change
+ * notice when the final page differs from the version first commented on, and
+ * each still-open item's quote and note. Silent when the page is unchanged and
+ * nothing remains open; never a manufactured prose diff. */
+async function feedbackAddendum(request) {
+    let sections;
+    try {
+        const feedback = await readPageFeedback(request.request_dir);
+        if (feedback.companionNodeId === undefined)
+            return '';
+        sections = [];
+        if (feedback.firstCommentedSha256 !== undefined && await pageDocumentSha256(request.request_dir) !== feedback.firstCommentedSha256) {
+            sections.push(`The page changed during feedback: the person commented on it and its companion conversation (node ${feedback.companionNodeId}) revised it in place. ` +
+                `Reread the final page at ${pagePath(presentationDir(request), manifest(request).dialect)} before interpreting this outcome.`);
+        }
+        const open = feedback.comments.filter((comment) => comment.status === 'open');
+        if (open.length > 0) {
+            const items = open.map((comment) => [
+                ...comment.quote.split('\n').map((line) => `> ${line}`),
+                comment.note,
+            ].join('\n'));
+            sections.push([
+                `Feedback left unresolved at settlement — the companion conversation (node ${feedback.companionNodeId}) had not dealt with these items:`,
+                ...items,
+            ].join('\n\n'));
+        }
+    }
+    catch {
+        // The outcome itself is the deliverable; a broken feedback record adds nothing.
+        return '';
+    }
+    return sections.length === 0 ? '' : `\n\n${sections.join('\n\n')}`;
+}
+/** The person's answer as prose the asking agent reads directly. Short bodies
+ * ride inline; the mail layer spills a long one to a file and leaves a preview
+ * plus its path. */
+async function answerBody(request, result) {
+    const answer = describePageAnswer(manifest(request), result.responses, { completedAt: result.completedAt });
+    return renderAnswerText(answer) + await feedbackAddendum(request);
+}
+/** A dismissal is a rejection, not a routing event: say so plainly so the agent
+ * acts on the "no" instead of re-raising the same ask. */
+async function cancelBody(request, dismissed, reason) {
+    const title = pageTitle(request);
+    const named = title === undefined ? `the human interaction ${request.request_id}` : `“${title}”`;
+    const why = reason !== undefined && reason !== '' ? reason : 'no reason was given';
+    const body = dismissed
+        ? `The user dismissed ${named} without answering — a deliberate “no, I'm not answering this.” Treat it as a rejection: no response will arrive, no partial answer exists, and the same ask must not be raised again.`
+        : `${title === undefined ? `The human interaction ${request.request_id}` : `The page “${title}”`} was canceled — ${why}. No response will arrive, and any partial answers the user had entered were discarded unsent.`;
+    return body + await feedbackAddendum(request);
+}
+function notification(request, disposition, body, result) {
+    if (request.requester_node_id === null)
+        return undefined;
+    return { label: firstLine(body), disposition, body_json: { body, result } };
+}
+function retire(request) {
+    return request.companion_node_id === null ? undefined : { retire: async (nodeId, outcome) => { await retireCompanion(nodeId, outcome); } };
+}
+/** Settle a page request directly in human_requests; result files and bridge nodes are not part of this path. */
+export async function resolvePageTicket(ticketId, responses, opts = {}) {
+    return (await answerPageTicket(ticketId, responses, opts)).result;
+}
+/** {@link resolvePageTicket}, also saying whether this answer won (`settled`) or the request was already settled. */
+export async function answerPageTicket(ticketId, responses, opts = {}) {
+    const request = await requestForTicket(ticketId);
+    const page = manifest(request);
+    const parsedResponses = validateFinalPageResponses(page, responses);
+    const result = {
+        schema: 'crtr.page-response/v1', kind: 'page', responses: parsedResponses,
+        summary: buildPageSummary(page, parsedResponses), completedAt: opts.completedAt ?? new Date().toISOString(),
+        ...(opts.actor === undefined ? {} : { actor: opts.actor }),
+    };
+    const settled = await settleHumanRequest({
+        request_id: request.request_id,
+        outcome: 'answered',
+        result_json: JSON.stringify(result),
+        notification: async (settledRequest) => notification(settledRequest, 'human-answer', await answerBody(settledRequest, result), result),
+        ...(completionAction(request, result) === undefined ? {} : { completion_action: completionAction(request, result) }),
+        ...(retire(request) === undefined ? {} : { post_commit: retire(request) }),
+    });
+    if (settled.outcome === 'already_settled') {
+        if (settled.request.result_json === null)
+            throw new Error(`settled page request lacks a result: ${request.request_id}`);
+        return { outcome: 'already_settled', result: JSON.parse(settled.request.result_json) };
+    }
+    return { outcome: 'settled', result };
+}
+export async function cancelHumanTicket(ticketId, opts) {
+    const request = await requestForTicket(ticketId);
+    const at = new Date().toISOString();
+    const result = {
+        schema: 'humanloop.cancel/v1', kind: 'canceled', canceledAt: at,
+        ...(opts.reason === undefined ? {} : { reason: opts.reason }),
+        ...(opts.actor === undefined ? {} : { actor: opts.actor }),
+        ...(opts.disposition === undefined ? {} : { disposition: opts.disposition }),
+    };
+    const settled = await settleHumanRequest({
+        request_id: request.request_id,
+        outcome: opts.disposition === 'dismissed' ? 'dismissed' : 'canceled',
+        result_json: JSON.stringify(result),
+        notification: async (settledRequest) => notification(settledRequest, 'human-canceled', await cancelBody(settledRequest, opts.disposition === 'dismissed', opts.reason), result),
+        ...(completionAction(request, result) === undefined ? {} : { completion_action: completionAction(request, result) }),
+        ...(retire(request) === undefined ? {} : { post_commit: retire(request) }),
+    });
+    if (settled.outcome === 'already_settled') {
+        if (settled.request.result_json === null)
+            throw new Error(`settled page request lacks a result: ${request.request_id}`);
+        return { outcome: 'already_settled', result: JSON.parse(settled.request.result_json) };
+    }
+    return { outcome: 'settled', result };
+}
+/** Legacy callers use this as a replay hook. Settlement effects are repaired by sweepHumanRequests. */
+export async function deliverTerminalResult(ticketId) {
+    const request = await requestForTicket(ticketId);
+    return request.state === 'settled';
+}
+export async function settleFeedbackCompanion(ticketId, outcome) {
+    const request = await requestForTicket(ticketId);
+    if (request.companion_node_id !== null)
+        await retireCompanion(request.companion_node_id, outcome);
+}

package/dist/daemon/human/settle.d.ts

@@ -0,0 +1,44 @@
+import { type DaemonActionAdapter } from '../../core/canvas/daemon-actions.js';
+import { type InboxDisposition } from '../../core/feed/messages.js';
+import { type HumanRequestOutcome, type HumanRequestRecord } from '../../core/human/requests.js';
+interface SettlementNotification {
+    label: string;
+    /** `human-answer` marks the body as the person's own words (attached views
+     *  render it as their message); null is a runtime notice about the request. */
+    disposition: InboxDisposition | null;
+    body_ref?: string;
+    body_json?: unknown;
+}
+export interface SettleHumanRequestInput {
+    request_id: string;
+    outcome: HumanRequestOutcome;
+    result_json: string;
+    settled_at?: string;
+    notification?: SettlementNotification | ((request: HumanRequestRecord) => Promise<SettlementNotification | undefined> | SettlementNotification | undefined);
+    completion_action?: {
+        adapter: DaemonActionAdapter;
+        bodyJson: unknown;
+    };
+    post_commit?: {
+        project?: (request: HumanRequestRecord) => Promise<void> | void;
+        retire?: (companionNodeId: string, outcome: 'approved' | 'canceled') => Promise<void>;
+    };
+}
+export type SettleHumanRequestOutcome = {
+    outcome: 'settled';
+    request: HumanRequestRecord;
+} | {
+    outcome: 'already_settled';
+    request: HumanRequestRecord;
+};
+/**
+ * The only terminal transition. The conditional update is first-writer-wins;
+ * the winner's result and every obligation are committed in the same canvas write.
+ */
+export declare function settleHumanRequest(input: SettleHumanRequestInput): Promise<SettleHumanRequestOutcome>;
+/** Projection and companion retirement happen after settlement because filesystem and node lifecycle cannot join SQLite. */
+export declare function projectAndRetire(request: HumanRequestRecord, effects: {
+    project?: (request: HumanRequestRecord) => Promise<void> | void;
+    retire?: (companionNodeId: string, outcome: 'approved' | 'canceled') => Promise<void>;
+}): Promise<void>;
+export {};

package/dist/daemon/human/settle.js

@@ -0,0 +1,103 @@
+import { withCanvasWrite } from '../../core/canvas/db.js';
+import { enqueueDaemonAction } from '../../core/canvas/daemon-actions.js';
+import { cancelDelivery, enqueueNodeMail } from '../../core/feed/messages.js';
+import { getRequest, markCompanionRetired, markProjected, markProjectionError, setSettlementDeliveryMarksLocked, settleRequestLocked, } from '../../core/human/requests.js';
+import { appendQuestionAnswered } from '../../core/runs/questions.js';
+import { notifyProviderApproval } from '../../core/providers/approval.js';
+import { signalInboxActivity } from '../../core/human/root.js';
+/**
+ * The only terminal transition. The conditional update is first-writer-wins;
+ * the winner's result and every obligation are committed in the same canvas write.
+ */
+export async function settleHumanRequest(input) {
+    const committed = await withCanvasWrite(async (db) => {
+        const settledAt = input.settled_at ?? new Date().toISOString();
+        const won = await settleRequestLocked(db, {
+            request_id: input.request_id,
+            outcome: input.outcome,
+            result_json: input.result_json,
+            settled_at: settledAt,
+        });
+        if (won === null) {
+            const winner = await getRequest(input.request_id);
+            if (winner === null)
+                throw new Error(`human request disappeared while settling: ${input.request_id}`);
+            return { outcome: 'already_settled', request: winner };
+        }
+        const notification = typeof input.notification === 'function' ? await input.notification(won) : input.notification;
+        if (won.requester_node_id !== null && notification === undefined) {
+            throw new Error(`request ${won.request_id} needs a requester notification`);
+        }
+        if (won.action_json !== null && won.kind === 'page' && input.completion_action === undefined) {
+            throw new Error(`request ${won.request_id} needs its frozen completion action`);
+        }
+        if (won.kind === 'review' && won.projected_at === null && input.post_commit?.project === undefined) {
+            throw new Error(`review ${won.request_id} needs a projection effect`);
+        }
+        if (won.companion_node_id !== null && won.companion_retired_at === null && input.post_commit?.retire === undefined) {
+            throw new Error(`request ${won.request_id} needs a companion retirement effect`);
+        }
+        let settlementDeliveryId = null;
+        let actionDeliveryId = null;
+        if (won.requester_node_id !== null) {
+            if (notification === undefined)
+                throw new Error(`request ${won.request_id} needs a requester notification`);
+            settlementDeliveryId = (await enqueueNodeMail(won.requester_node_id, {
+                kind: 'completed', label: notification.label, senderName: 'crtrd',
+                ...(notification.body_ref === undefined ? {} : { bodyRef: notification.body_ref }),
+                ...(notification.body_json === undefined ? {} : { bodyJson: notification.body_json }),
+                disposition: notification.disposition, urgency: 'normal', wake: 1,
+            })).deliveryId;
+        }
+        if (won.action_json !== null && input.completion_action !== undefined && won.kind === 'page') {
+            actionDeliveryId = await enqueueDaemonAction({
+                adapter: input.completion_action.adapter,
+                bodyJson: input.completion_action.bodyJson,
+                idempotencyKey: `human-action:${won.inbox_ticket_id}`,
+            });
+        }
+        if (won.submit_note_delivery_id !== null)
+            await cancelDelivery(won.submit_note_delivery_id);
+        await setSettlementDeliveryMarksLocked(db, won.request_id, {
+            settlement_delivery_id: settlementDeliveryId,
+            action_delivery_id: actionDeliveryId,
+        });
+        const request = await getRequest(won.request_id);
+        if (request === null)
+            throw new Error(`settled human request disappeared: ${won.request_id}`);
+        await appendQuestionAnswered(db, request);
+        return { outcome: 'settled', request };
+    });
+    if (committed.outcome === 'settled') {
+        // Wake in-process provider callers only after the ticket and approval status
+        // are committed. Other questions have no registered waiter.
+        notifyProviderApproval(committed.request.request_id);
+        // Open viewers re-read their inline page blocks and inbox strip on this
+        // signal; without it an answered page stays on screen until a reload.
+        signalInboxActivity();
+        if (input.post_commit !== undefined)
+            await projectAndRetire(committed.request, input.post_commit);
+    }
+    return committed;
+}
+/** Projection and companion retirement happen after settlement because filesystem and node lifecycle cannot join SQLite. */
+export async function projectAndRetire(request, effects) {
+    if (request.kind === 'review' && request.projected_at === null && effects.project !== undefined) {
+        try {
+            await effects.project(request);
+            await markProjected(request.request_id, new Date().toISOString());
+        }
+        catch (error) {
+            await markProjectionError(request.request_id, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (request.companion_node_id !== null && request.companion_retired_at === null && effects.retire !== undefined) {
+        try {
+            await effects.retire(request.companion_node_id, request.outcome === 'canceled' || request.outcome === 'dismissed' ? 'canceled' : 'approved');
+            await markCompanionRetired(request.request_id, new Date().toISOString());
+        }
+        catch {
+            // The durable NULL mark is the authoritative retry obligation for the sweep.
+        }
+    }
+}