@north-light/crouter 0.3.281 → 0.3.283

package/dist/daemon/api/__tests__/submit-result.test.js

@@ -0,0 +1,214 @@
+// Run with: node --import tsx/esm --test src/daemon/api/__tests__/submit-result.test.ts
+//
+// `POST /v1/nodes/{id}/result` — the server side of `crtr push result` — and
+// the `structured_result_pending` gate on the plain push route. In-process
+// handler calls against a throwaway CRTR_HOME (reopen-delivery.test.ts pattern).
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createNode, getNode, openDb } from '../../../core/canvas/index.js';
+import { closeDb } from '../../../core/canvas/db.js';
+import { InputError } from '../../../core/io.js';
+import { outputResultPath, outputSchemaPath, writeOutputSchema, } from '../../../core/runtime/structured-output.js';
+import { reportRoutes } from '../handlers/reports.js';
+import { toNodeOutcomeDTO } from '../map.js';
+let home;
+const priorHome = process.env['CRTR_HOME'];
+before(() => {
+    // macOS limits Unix-socket paths to 104 bytes; keep the home short.
+    home = mkdtempSync('/tmp/crtr-result-');
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    if (priorHome === undefined)
+        delete process.env['CRTR_HOME'];
+    else
+        process.env['CRTR_HOME'] = priorHome;
+});
+function node(id, lifecycle = 'terminal') {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp',
+        kind: 'general',
+        mode: 'base',
+        lifecycle,
+        status: 'active',
+    };
+}
+function finalize(id) {
+    openDb()
+        .prepare('UPDATE nodes SET final_report = ?, finalized_at = ? WHERE node_id = ?')
+        .run('final.md', new Date().toISOString(), id);
+}
+function route(method, pattern) {
+    const def = reportRoutes.find((r) => r.method === method && r.pattern === pattern);
+    assert.ok(def, `route ${method} ${pattern} registered`);
+    return (id, body) => Promise.resolve(def.handler({
+        method,
+        path: pattern.replace(':id', id),
+        params: { id },
+        query: new URLSearchParams(),
+        body,
+    }));
+}
+const submit = route('POST', '/v1/nodes/:id/result');
+const pushReport = route('POST', '/v1/nodes/:id/reports');
+const SCHEMA = {
+    type: 'object',
+    properties: { status: { type: 'string' }, count: { type: 'number' } },
+    required: ['status'],
+};
+async function rejection(promise) {
+    let caught;
+    await promise.then(() => assert.fail('expected a rejection'), (err) => { caught = err; });
+    assert.ok(caught instanceof InputError, `expected InputError, got ${String(caught)}`);
+    return caught;
+}
+test('terminal happy path: result written, schema cleared, node finished', async () => {
+    createNode(node('t1'));
+    writeOutputSchema('t1', 'terminal', SCHEMA);
+    const res = await submit('t1', { value: { status: 'ok' } });
+    assert.equal(res.status, 200);
+    const dto = res.body;
+    assert.equal(dto.mode, 'terminal');
+    assert.equal(dto.result_path, outputResultPath('t1'));
+    assert.ok(dto.report_path.endsWith('.md'));
+    assert.deepEqual(dto.notified, []);
+    assert.deepEqual(dto.transitioned, { from: 'active', to: 'done' });
+    assert.deepEqual(JSON.parse(readFileSync(outputResultPath('t1'), 'utf8')), { status: 'ok' });
+    assert.equal(existsSync(outputSchemaPath('t1')), false);
+    const meta = getNode('t1');
+    assert.equal(meta?.status, 'done');
+    assert.notEqual(meta?.final_report, null);
+    assert.match(readFileSync(dto.report_path, 'utf8'), /Structured output submitted/);
+});
+test('one-off happy path: update pushed, node keeps working', async () => {
+    createNode(node('o1', 'resident'));
+    writeOutputSchema('o1', 'oneoff', SCHEMA);
+    const res = await submit('o1', { value: { status: 'ok' } });
+    const dto = res.body;
+    assert.equal(dto.mode, 'oneoff');
+    assert.equal(dto.transitioned, undefined);
+    assert.equal(existsSync(outputSchemaPath('o1')), false);
+    const meta = getNode('o1');
+    assert.equal(meta?.status, 'active');
+    assert.equal(meta?.final_report, null);
+});
+test('schema mismatch: field errors, nothing recorded, request retained for retry', async () => {
+    createNode(node('m1'));
+    writeOutputSchema('m1', 'terminal', SCHEMA);
+    const err = await rejection(submit('m1', { value: { count: 3 } }));
+    assert.equal(err.payload.error, 'result_schema_mismatch');
+    assert.match(err.payload.message, /status/);
+    assert.equal(existsSync(outputResultPath('m1')), false);
+    assert.equal(existsSync(outputSchemaPath('m1')), true);
+    assert.equal(getNode('m1')?.status, 'active');
+});
+test('coercion parity with the retired submit tool: "5" persists as 5', async () => {
+    createNode(node('c1'));
+    writeOutputSchema('c1', 'terminal', SCHEMA);
+    await submit('c1', { value: { status: 'ok', count: '5' } });
+    assert.deepEqual(JSON.parse(readFileSync(outputResultPath('c1'), 'utf8')), { status: 'ok', count: 5 });
+});
+test('no pending request → no_output_request', async () => {
+    createNode(node('n1'));
+    const err = await rejection(submit('n1', { value: {} }));
+    assert.equal(err.payload.error, 'no_output_request');
+});
+test('corrupt request file → invalid_output_request naming the parse failure', async () => {
+    createNode(node('i1'));
+    const path = outputSchemaPath('i1');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, '{not json', 'utf8');
+    const err = await rejection(submit('i1', { value: {} }));
+    assert.equal(err.payload.error, 'invalid_output_request');
+    assert.match(err.payload.message, /not valid JSON/);
+});
+test('unknown node → 404', async () => {
+    await assert.rejects(submit('ghost', { value: {} }), (err) => err.code === 'not_found');
+});
+test('already-finalized node, terminal submit → already_finalized; schema retained', async () => {
+    createNode(node('f1'));
+    finalize('f1');
+    writeOutputSchema('f1', 'terminal', SCHEMA);
+    const err = await rejection(submit('f1', { value: { status: 'ok' } }));
+    assert.equal(err.payload.error, 'already_finalized');
+    assert.equal(existsSync(outputSchemaPath('f1')), true);
+});
+test('missing value key → usage error (distinct from a legal null value)', async () => {
+    createNode(node('u1'));
+    writeOutputSchema('u1', 'terminal', SCHEMA);
+    await assert.rejects(submit('u1', {}), (err) => err.code === 'usage');
+    // A PRESENT null value is legal input to validation (here: a mismatch, not usage).
+    const err = await rejection(submit('u1', { value: null }));
+    assert.equal(err.payload.error, 'result_schema_mismatch');
+});
+test('non-object value against an object schema → mismatch, not a crash', async () => {
+    createNode(node('s1'));
+    writeOutputSchema('s1', 'terminal', SCHEMA);
+    const err = await rejection(submit('s1', { value: 42 }));
+    assert.equal(err.payload.error, 'result_schema_mismatch');
+    assert.equal(existsSync(outputSchemaPath('s1')), true);
+});
+test('push final while a valid schema is pending → structured_result_pending', async () => {
+    createNode(node('g1'));
+    writeOutputSchema('g1', 'terminal', SCHEMA);
+    const err = await rejection(pushReport('g1', { tier: 'final', body: 'done' }));
+    assert.equal(err.payload.error, 'structured_result_pending');
+    assert.match(err.payload.next ?? '', /crtr push result/);
+    assert.equal(getNode('g1')?.status, 'active');
+});
+test('push update while a schema is pending is still allowed', async () => {
+    createNode(node('g2'));
+    writeOutputSchema('g2', 'oneoff', SCHEMA);
+    const res = await pushReport('g2', { tier: 'update', body: 'progress' });
+    assert.equal(res.status, 200);
+});
+test('push final with a corrupt schema file stays allowed (manual-cleanup escape)', async () => {
+    createNode(node('g3'));
+    const path = outputSchemaPath('g3');
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, '{not json', 'utf8');
+    const res = await pushReport('g3', { tier: 'final', body: 'done' });
+    assert.equal(res.status, 200);
+    assert.equal(getNode('g3')?.status, 'done');
+});
+test('terminal decline: declined.json + failure/declined outcome carrying reason, code, retryable', async () => {
+    createNode(node('d1'));
+    writeOutputSchema('d1', 'terminal', SCHEMA);
+    const res = await submit('d1', { decline: 'The route is blocked. ', code: 'blocked-device-route', retryable: true });
+    const dto = res.body;
+    assert.equal(dto.mode, 'terminal');
+    assert.deepEqual(dto.declined, { reason: 'The route is blocked.', code: 'blocked-device-route', retryable: true });
+    assert.deepEqual(dto.transitioned, { from: 'active', to: 'done' });
+    assert.equal(existsSync(outputResultPath('d1')), false);
+    assert.equal(existsSync(outputSchemaPath('d1')), false);
+    const marker = JSON.parse(readFileSync(dto.result_path, 'utf8'));
+    assert.equal(marker['code'], 'blocked-device-route');
+    assert.equal(marker['retryable'], true);
+    const outcome = toNodeOutcomeDTO(getNode('d1'));
+    assert.ok(outcome !== null && outcome.kind === 'failure' && outcome.reason === 'declined');
+    assert.deepEqual(outcome.declined, { reason: 'The route is blocked.', code: 'blocked-device-route', retryable: true });
+    assert.equal(outcome.detail?.message, 'The route is blocked.');
+    assert.match(readFileSync(dto.report_path, 'utf8'), /Code: blocked-device-route/);
+});
+test('decline without a code, or with a non-boolean retryable, records nothing', async () => {
+    createNode(node('d2'));
+    writeOutputSchema('d2', 'terminal', SCHEMA);
+    const noCode = await rejection(submit('d2', { decline: 'blocked', retryable: false }));
+    assert.equal(noCode.payload.error, 'invalid_decline_code');
+    const spaced = await rejection(submit('d2', { decline: 'blocked', code: 'has space', retryable: false }));
+    assert.equal(spaced.payload.error, 'invalid_decline_code');
+    await assert.rejects(submit('d2', { decline: 'blocked', code: 'x' }), (err) => err.code === 'usage');
+    assert.equal(existsSync(outputSchemaPath('d2')), true);
+    assert.equal(getNode('d2')?.status, 'active');
+});

package/dist/daemon/api/handlers/broker-ops.js

@@ -1,7 +1,8 @@
 // Broker-originated canvas operations. The broker sends Pi lifecycle facts;
 // crtrd validates and commits their durable effects while the handler stays
 // strictly canvas-write-only — no broker launch, kill, or view.sock round trip.
-import { canonicalSessionFile, findNodeBySessionFile, getNode, isWarmSpare, listNodes, recordPid, recordSettledTurn, setPresence, subscriptionsOf, updateNode } from '../../../core/canvas/canvas.js';
+import { canonicalSessionFile, findNodeBySessionFile, getNode, isWarmSpare, listNodeIdentities, recordPid, recordSettledTurn, setPresence, subscriptionsOf, updateNode } from '../../../core/canvas/canvas.js';
+import { isSafeNodeId } from '../../../core/canvas/paths.js';
 import { isPidAlive } from '../../../core/canvas/pid.js';
 import { editorLabel } from '../../../core/canvas/labels.js';
 import { assembleNodeSubject } from '../../../core/substrate/subject.js';
@@ -17,8 +18,9 @@ import { evaluateStop } from '../../../core/runtime/stop-guard.js';
 import { clearFault, recordFault } from '../../../core/runtime/fault.js';
 import { updateModelRecipe } from '../../../core/runtime/model-swap.js';
 import { completeCompanionRequestedSubmit } from '../../review/finish.js';
-import { consumePendingPark } from '../../park-pending.js';
-import { parkEvent } from '../../reconcilers/live-obligation.js';
+import { emitEvent } from '../../../core/events/emit.js';
+import { consumePendingPark, recordPendingParkActivity } from '../../park-pending.js';
+import { shouldParkAfterSummary } from '../../park-activity.js';
 function objectBody(body, operation) {
     if (typeof body !== 'object' || body === null || Array.isArray(body)) {
         throw usage(`${operation} requires a JSON body`);
@@ -55,6 +57,13 @@ function parseSettleBody(body) {
     }
     return value;
 }
+function parseParkCompleteBody(body) {
+    const value = objectBody(body, 'broker park-complete');
+    if (value['outcome'] !== 'completed' && value['outcome'] !== 'failed') {
+        throw usage('outcome must be completed or failed');
+    }
+    return value;
+}
 function parseInboxCursorBody(body) {
     const value = objectBody(body, 'broker inbox-cursor');
     const throughEntryId = value['throughEntryId'];
@@ -137,7 +146,6 @@ function extensionState(nodeId) {
     const subject = assembleNodeSubject(nodeId);
     if (subject === null)
         throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
-    const report_nodes = listNodes().map((row) => ({ node_id: row.node_id, name: row.name, created: row.created }));
     return {
         node: extensionNode(node),
         warm_spare: isWarmSpare(nodeId),
@@ -145,7 +153,7 @@ function extensionState(nodeId) {
         children,
         fork_source: source === null ? null : extensionNode(source),
         subject,
-        report_nodes,
+        report_nodes: listNodeIdentities(),
     };
 }
 function samePersona(a, b) {
@@ -250,11 +258,6 @@ function handleSessionBound(ctx) {
  * boundary. This handler intentionally never invokes the broker that called it:
  * the returned directive is the only Pi-side consequence. */
 function settleBroker(nodeId, request) {
-    // A parking turn in flight ends HERE, whatever it ended as. Consuming
-    // unconditionally is the abort rule expressed once: every early return below
-    // — clean quit, pushed final, human ask, interrupted turn, refresh — discards
-    // the park and leaves the node live under a restarted clock.
-    const parkPending = consumePendingPark(nodeId);
     const node = getNode(nodeId);
     if (node === null) {
         // A command may have recorded its Pi-local completion marker just as an
@@ -301,20 +304,6 @@ function settleBroker(nodeId, request) {
         clearFault(nodeId);
         return { action: 'shutdown' };
     }
-    // The parking turn just ended. Re-evaluate the verdict the clock reached
-    // before this turn ran: a `crtr human send`, new wake-worthy mail, a fresh
-    // subscription to a child it spawned, or a pending structured-output request
-    // all make the node live work again, and the ordinary stop policy applies
-    // instead. `pushedFinal` was checked above, so a node that finished during
-    // its parking turn ends latched rather than parked.
-    if (parkPending && parkEvent(nodeId, node.lifecycle) === 'park') {
-        clearFault(nodeId);
-        transition(nodeId, 'park');
-        if (focusOf(nodeId) !== null)
-            tearDownNode(nodeId);
-        setPresence(nodeId, { pane: null, tmux_session: null, window: null });
-        return { action: 'shutdown' };
-    }
     const decision = evaluateStop(nodeId, signals, request.backgroundJobsRunning);
     clearFault(nodeId);
     if (decision.action === 'reprompt')
@@ -345,6 +334,44 @@ function handleSettle(ctx) {
         void completeCompanionRequestedSubmit(nodeId);
     return { status: 200, body: directive };
 }
+/** The shadow parking turn is the sole good-path enactor for its pending marker.
+ * The ordinary main-session settle path remains independent so user activity
+ * cannot erase the marker before this completion re-evaluates the obligation. */
+function handleParkComplete(ctx) {
+    const nodeId = ctx.params['id'];
+    const request = parseParkCompleteBody(ctx.body);
+    const directive = withCanvasWrite(() => {
+        const pending = consumePendingPark(nodeId);
+        if (pending === undefined)
+            return { action: 'stay_dormant' };
+        const node = requireNode(nodeId);
+        if (!shouldParkAfterSummary(nodeId, node, pending))
+            return { action: 'stay_dormant' };
+        clearFault(nodeId);
+        transition(nodeId, 'park');
+        if (focusOf(nodeId) !== null)
+            tearDownNode(nodeId);
+        setPresence(nodeId, { pane: null, tmux_session: null, window: null });
+        emitEvent({
+            level: request.outcome === 'completed' ? 'info' : 'warn',
+            event: 'broker.park.complete',
+            ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : {}),
+            outcome: request.outcome === 'completed' ? 'succeeded' : 'failed',
+        });
+        return { action: 'shutdown' };
+    });
+    return { status: 200, body: directive };
+}
+/** Record an accepted main-engine input before Pi begins driving it. This shares
+ * the canvas-write boundary with park completion, so a pending shadow turn can
+ * never terminalize a viewer or live-delivery input that won admission. */
+function handleParkActivity(ctx) {
+    const nodeId = ctx.params['id'];
+    const result = withCanvasWrite(() => ({
+        activity: recordPendingParkActivity(nodeId) ? 'recorded' : 'none',
+    }));
+    return { status: 200, body: result };
+}
 /** Commit a watcher cursor only while this broker generation remains current.
  * A refresh or a replacement binding must leave the cursor untouched so the
  * replacement replays every handoff that may have reached the discarded Pi
@@ -447,6 +474,8 @@ function handlePersonaAck(ctx) {
 export const brokerOperationRoutes = [
     { method: 'POST', pattern: '/v1/nodes/:id/broker/session-bound', handler: handleSessionBound },
     { method: 'POST', pattern: '/v1/nodes/:id/broker/settle', handler: handleSettle },
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/park-complete', handler: handleParkComplete },
+    { method: 'POST', pattern: '/v1/nodes/:id/broker/park-activity', handler: handleParkActivity },
     { method: 'POST', pattern: '/v1/nodes/:id/broker/inbox-cursor', handler: handleInboxCursor },
     { method: 'POST', pattern: '/v1/nodes/:id/broker/model', handler: handleModelCommit },
     { method: 'GET', pattern: '/v1/nodes/:id/broker/extension-state', handler: handleExtensionState },

package/dist/daemon/api/handlers/canvas.js

@@ -15,7 +15,7 @@ import { listNodes, pruneNodes, pruneToLimit, rebuildIndex, rosterEdges, rosterN
 import { activeBackgroundBashJobs } from '../../../core/bash-jobs.js';
 import { contextDir } from '../../../core/canvas/paths.js';
 import { nowIso } from '../../../core/fs-utils.js';
-import { isBrokerLive } from '../../../core/runtime/model-swap.js';
+import { isPidPresent } from '../../../core/canvas/pid.js';
 import { dashboardRowsAllFromSource, enrichRowsFromSource } from '../../../core/canvas/render-source.js';
 import { localCanvasSource } from '../../../core/canvas/source.js';
 import { listFocuses } from '../../../core/canvas/focuses.js';
@@ -343,7 +343,7 @@ async function handleSnapshot(ctx) {
             ...(row.mtimeMs !== undefined ? { last_activity: new Date(row.mtimeMs).toISOString() } : {}),
             ctx_tokens: row.ctx_tokens,
             streaming: row.streaming ?? false,
-            jobs_active: src !== undefined && isBrokerLive(src)
+            jobs_active: src !== undefined && isPidPresent(src.pi_pid)
                 ? activeBackgroundBashJobs(contextDir(row.node_id)).length
                 : 0,
             waiting_for: src?.waiting_for ?? null,

package/dist/daemon/api/handlers/messages.js

@@ -8,12 +8,14 @@ import { isBrokerLive } from '../../../core/runtime/model-swap.js';
 import { deliverLive, interruptLive } from '../../../core/runtime/interactive-deliver.js';
 import { isProfilePaused } from '../../../core/profiles/manifest.js';
 import { getNode, withFreshTerminalGuard } from '../../../core/canvas/canvas.js';
+import { withCanvasWrite } from '../../../core/canvas/db.js';
 import { cancelCronsOnWake } from '../../../core/canvas/crons.js';
 import { assertNotFinalized, assertFinalizedForReopen, commitReopen, commitReopenResident, } from '../../../core/runtime/reopen.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { appendSituationalContext, formatSituationalProse } from '../../../core/runtime/situational-context.js';
 import { formatDataCard } from '../../../shared/generated-context.js';
 import { hasNoNaturalCycle } from '../../../core/runtime/revive-all.js';
+import { recordPendingParkActivity } from '../../park-pending.js';
 import { hasFreshGroundState } from '../../../core/runtime/revive.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { InputError } from '../../../core/io.js';
@@ -298,7 +300,7 @@ async function handleMessage(ctx) {
         if (hasBody || schema !== null) {
             const messageBody = hasBody
                 ? req.body
-                : 'A one-off structured-output request has been granted. Call the `submit` tool with a result matching the requested schema before you stop; after submit succeeds, continue normally.';
+                : 'A one-off structured-output request has been granted. Submit a result matching the requested schema with `crtr push result` before you stop; after it is accepted, continue normally.';
             return appendInbox(id, {
                 from,
                 tier,
@@ -341,6 +343,14 @@ async function handleMessage(ctx) {
         return deliverImmediate();
     };
     const entry = deliver();
+    // Wake-capable durable mail wins the same park-completion boundary as a live
+    // broker input. A completion that won before this append is handled by the
+    // fresh row read below, which revives the now-parked node.
+    if (entry.tier !== 'deferred')
+        withCanvasWrite(() => recordPendingParkActivity(id));
+    const current = getNode(id);
+    if (current === null)
+        throw notFound(`unknown node: ${id}`, { received: id });
     // Deferred mail normally waits for a natural cycle, but a frozen row already
     // owes a thaw; consume its deadline when that durable future wake arrives.
     if (entry.tier !== 'deferred' || meta.frozen_at !== null)
@@ -351,7 +361,7 @@ async function handleMessage(ctx) {
     // already raised to a wake-capable tier by the append.
     let revived = false;
     let frozen = false;
-    if (entry.tier !== 'deferred' && !paused && !isBrokerLive(meta)) {
+    if (entry.tier !== 'deferred' && !paused && !isBrokerLive(current)) {
         try {
             // The entry is already durable, so a wake denied for capacity is only
             // delayed: the row freezes and the tick relaunches it — at which point

package/dist/daemon/api/handlers/node-outcomes.d.ts

@@ -0,0 +1,2 @@
+import type { RouteTable } from '../router.js';
+export declare const nodeOutcomeRoutes: RouteTable;

package/dist/daemon/api/handlers/node-outcomes.js

@@ -0,0 +1,136 @@
+// Durable node-outcome reads and outcome-delivery registration.
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ApiError } from '../../../api/errors.js';
+import { getNode } from '../../../core/canvas/canvas.js';
+import { armOutcomeDelivery, disarmOutcomeDelivery, readOutcomeDelivery, } from '../../../core/canvas/node-outcome-deliveries.js';
+import { OUTCOME_PAYLOAD_MAX_BYTES } from '../../../core/canvas/types.js';
+import { HUMAN_ACTION_NAME_PATTERN } from '../../../core/human/action-binding.js';
+import { resolveHumanAction } from '../../../core/human-actions.js';
+import { toNodeOutcomeDTO, toOutcomeDeliveryDTO } from '../map.js';
+const POLL_INTERVAL_MS = 250;
+const MAX_WAIT_SECONDS = 25;
+function requireNode(id) {
+    const node = getNode(id);
+    if (node === null)
+        throw new ApiError(404, 'node_not_found', `no node ${id}`);
+    return node;
+}
+function parseWait(ctx) {
+    const raw = ctx.query.get('wait');
+    if (raw === null || raw === '')
+        return 0;
+    if (!/^(?:0|[1-9]\d*)$/.test(raw)) {
+        throw new ApiError(400, 'invalid_request', '`wait` must be an integer between 0 and 25');
+    }
+    const seconds = Number(raw);
+    if (seconds < 0 || seconds > MAX_WAIT_SECONDS) {
+        throw new ApiError(400, 'invalid_request', '`wait` must be an integer between 0 and 25');
+    }
+    return seconds;
+}
+function responseFor(node) {
+    const outcome = toNodeOutcomeDTO(node);
+    return {
+        node_id: node.node_id,
+        state: outcome === null ? 'pending' : 'settled',
+        outcome,
+        node_status: node.status,
+        deadline_at: node.deadline_at ?? null,
+    };
+}
+/** GET /v1/nodes/:id/outcome — poll now, or poll the durable row for up to 25 seconds. */
+async function handleGetOutcome(ctx) {
+    const id = ctx.params['id'] ?? '';
+    const waitSeconds = parseWait(ctx);
+    const deadline = Date.now() + waitSeconds * 1_000;
+    let node = requireNode(id);
+    while (toNodeOutcomeDTO(node) === null && Date.now() < deadline) {
+        await sleep(Math.min(POLL_INTERVAL_MS, deadline - Date.now()));
+        node = requireNode(id);
+    }
+    return { status: 200, body: responseFor(node) };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function payloadBytes(payload) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(payload);
+    }
+    catch {
+        throw new ApiError(400, 'invalid_request', '`payload` must be JSON-serializable');
+    }
+    if (serialized === undefined)
+        throw new ApiError(400, 'invalid_request', '`payload` must be JSON-serializable');
+    return Buffer.byteLength(serialized, 'utf8');
+}
+function parseRegistration(body) {
+    if (!isPlainObject(body))
+        throw new ApiError(400, 'invalid_request', 'request body must be an object');
+    for (const key of Object.keys(body)) {
+        if (key !== 'action' && key !== 'payload') {
+            throw new ApiError(400, 'invalid_request', `unexpected field in request body: ${key}`);
+        }
+    }
+    const action = body['action'];
+    if (typeof action !== 'string' || !HUMAN_ACTION_NAME_PATTERN.test(action)) {
+        throw new ApiError(400, 'invalid_request', '`action` must be a declared action name');
+    }
+    if (body['payload'] !== undefined && payloadBytes(body['payload']) > OUTCOME_PAYLOAD_MAX_BYTES) {
+        throw new ApiError(413, 'payload_too_large', `serialized payload exceeds ${OUTCOME_PAYLOAD_MAX_BYTES} bytes`);
+    }
+    return body['payload'] === undefined ? { action } : { action, payload: body['payload'] };
+}
+function resolveAction(action, cwd) {
+    const resolution = resolveHumanAction(action, cwd);
+    if (!('kind' in resolution))
+        return resolution;
+    if (resolution.kind === 'unknown_action') {
+        throw new ApiError(422, 'unknown_action', `no action named ${action} is declared from ${cwd}`);
+    }
+    throw new ApiError(422, 'invalid_action', `${action} is declared in ${resolution.configOrigin} but unusable: ${resolution.reason}`, { reason: resolution.reason, configOrigin: resolution.configOrigin });
+}
+/** PUT /v1/nodes/:id/outcome-delivery — arm/re-arm an unsettled target. */
+function handlePutDelivery(ctx) {
+    const id = ctx.params['id'] ?? '';
+    const node = requireNode(id);
+    const request = parseRegistration(ctx.body);
+    const target = resolveAction(request.action, node.cwd);
+    const delivery = armOutcomeDelivery({
+        nodeId: node.node_id,
+        actionName: request.action,
+        argv: target.argv,
+        cwd: target.cwd,
+        configOrigin: target.configOrigin,
+        ...(request.payload === undefined ? {} : { payload: request.payload }),
+    });
+    if (delivery === null) {
+        throw new ApiError(409, 'outcome_delivery_settled', 'outcome delivery has already started or settled');
+    }
+    return { status: 200, body: toOutcomeDeliveryDTO(delivery) };
+}
+/** GET /v1/nodes/:id/outcome-delivery — inspect the one durable registration. */
+function handleGetDelivery(ctx) {
+    const id = ctx.params['id'] ?? '';
+    const delivery = readOutcomeDelivery(id);
+    if (delivery === null)
+        throw new ApiError(404, 'outcome_delivery_not_found', `no outcome delivery for node ${id}`);
+    return { status: 200, body: toOutcomeDeliveryDTO(delivery) };
+}
+/** DELETE /v1/nodes/:id/outcome-delivery — disarm only before delivery begins. */
+function handleDeleteDelivery(ctx) {
+    const id = ctx.params['id'] ?? '';
+    const current = readOutcomeDelivery(id);
+    if (current !== null && current.state !== 'armed') {
+        throw new ApiError(409, 'outcome_delivery_settled', 'outcome delivery has already started or settled');
+    }
+    disarmOutcomeDelivery(id);
+    return { status: 204 };
+}
+export const nodeOutcomeRoutes = [
+    { method: 'GET', pattern: '/v1/nodes/:id/outcome', handler: handleGetOutcome },
+    { method: 'PUT', pattern: '/v1/nodes/:id/outcome-delivery', handler: handlePutDelivery },
+    { method: 'GET', pattern: '/v1/nodes/:id/outcome-delivery', handler: handleGetDelivery },
+    { method: 'DELETE', pattern: '/v1/nodes/:id/outcome-delivery', handler: handleDeleteDelivery },
+];