@north-light/crouter 0.3.281 → 0.3.283

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

@@ -37,6 +37,10 @@ import { activeFaultForDisplay } from '../../../core/canvas/render-source.js';
 import { isBrokerLive, persistDormantModel, setModelLive } from '../../../core/runtime/model-swap.js';
 import { boundFleet } from '../../../core/runtime/fleet.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.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 { parseDurationMs } from '../../../core/wake.js';
 import { claimWarmNode, refillWarmPool, warmPoolEnabled } from '../../../core/runtime/warm-pool.js';
 import { resolveLaunchTarget } from '../../../core/runtime/launch-target.js';
 import { fullName } from '../../../core/canvas/labels.js';
@@ -115,6 +119,58 @@ function parseCreateBody(body) {
     }
     return b;
 }
+function parseDeadline(raw) {
+    if (raw === undefined)
+        return undefined;
+    const durationMs = parseDurationMs(raw);
+    const deadlineAt = durationMs === null ? null : new Date(Date.now() + durationMs);
+    if (durationMs === null || !Number.isFinite(durationMs) || durationMs <= 0 || deadlineAt === null || !Number.isFinite(deadlineAt.getTime())) {
+        throw new ApiError(422, 'invalid_deadline', '`deadline` must be a positive representable duration');
+    }
+    return deadlineAt.toISOString();
+}
+function parseOutcomeDelivery(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new ApiError(400, 'invalid_request', '`outcome_delivery` must be an object');
+    }
+    if (typeof raw.action !== 'string' || !HUMAN_ACTION_NAME_PATTERN.test(raw.action)) {
+        throw new ApiError(400, 'invalid_request', '`outcome_delivery.action` must be a declared action name');
+    }
+    if (raw.payload !== undefined) {
+        let serialized;
+        try {
+            serialized = JSON.stringify(raw.payload);
+        }
+        catch {
+            throw new ApiError(400, 'invalid_request', '`outcome_delivery.payload` must be JSON-serializable');
+        }
+        if (serialized === undefined) {
+            throw new ApiError(400, 'invalid_request', '`outcome_delivery.payload` must be JSON-serializable');
+        }
+        if (Buffer.byteLength(serialized, 'utf8') > OUTCOME_PAYLOAD_MAX_BYTES) {
+            throw new ApiError(413, 'payload_too_large', `serialized payload exceeds ${OUTCOME_PAYLOAD_MAX_BYTES} bytes`);
+        }
+    }
+    return raw;
+}
+function resolveOutcomeDelivery(request, cwd) {
+    const resolution = resolveHumanAction(request.action, cwd);
+    if (!('kind' in resolution)) {
+        return {
+            actionName: request.action,
+            argv: resolution.argv,
+            cwd: resolution.cwd,
+            configOrigin: resolution.configOrigin,
+            ...(request.payload === undefined ? {} : { payload: request.payload }),
+        };
+    }
+    if (resolution.kind === 'unknown_action') {
+        throw new ApiError(422, 'unknown_action', `no action named ${request.action} is declared from ${cwd}`);
+    }
+    throw new ApiError(422, 'invalid_action', `${request.action} is declared in ${resolution.configOrigin} but unusable: ${resolution.reason}`, { reason: resolution.reason, configOrigin: resolution.configOrigin });
+}
 /** Build the immediate spawn recipe. */
 function buildRecipe(req, parent, cwd) {
     const recipe = {
@@ -212,6 +268,8 @@ async function assertNodeModelChangeRegistered(meta, target, registry) {
 }
 export async function handleCreate(ctx, deps = {}) {
     const req = parseCreateBody(ctx.body);
+    const deadline = parseDeadline(req.deadline);
+    const outcomeDelivery = parseOutcomeDelivery(req.outcome_delivery);
     // `no_kickoff` needs no dedicated recipe field: an empty prompt IS the
     // no-kickoff mechanism (spawnChild runs no launch turn on prompt===''), and
     // buildRecipe already defaults `prompt` to ''. The CLI keeps every no_kickoff
@@ -237,13 +295,17 @@ export async function handleCreate(ctx, deps = {}) {
     // to this daemon, never to the possibly-remote CLI caller.
     const { profileId, kind, cwd, launch } = await resolveLaunchTarget(req, { validateKind: assertKindServer });
     const resolvedReq = { ...req, kind };
+    const resolvedOutcomeDelivery = outcomeDelivery === undefined ? undefined : resolveOutcomeDelivery(outcomeDelivery, cwd);
     await assertLaunchModelRegistered(requestFromLaunch(launch), { cwd, profileId }, deps.modelRegistry);
     // --- Warm path: hand out an already-booted spare instead of paying a full
     //     engine boot. A miss is not a failure — it falls through to the cold
     //     spawn below and mints the spare that serves the NEXT create. ---
     const warm = warmRequestFor(resolvedReq, cwd, profileId);
     if (warm !== null) {
-        const claimed = await claimWarmNode(warm);
+        const claimed = await claimWarmNode(warm, {
+            ...(deadline === undefined ? {} : { deadlineAt: deadline }),
+            ...(resolvedOutcomeDelivery === undefined ? {} : { outcomeDelivery: resolvedOutcomeDelivery }),
+        });
         refillWarmPool(warm);
         if (claimed !== null) {
             if (schema !== null)
@@ -252,6 +314,10 @@ export async function handleCreate(ctx, deps = {}) {
         }
     }
     const recipe = buildRecipe(resolvedReq, parent, cwd);
+    if (deadline !== undefined)
+        recipe.deadlineAt = deadline;
+    if (resolvedOutcomeDelivery !== undefined)
+        recipe.outcomeDelivery = resolvedOutcomeDelivery;
     recipe.readiness = req.root === true ? 'await' : 'launch';
     const result = await spawnChild(recipe);
     if (schema !== null)

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

@@ -7,8 +7,13 @@
 //   GET    /v1/profiles/:name    resolve one profile by name or id
 //   DELETE /v1/profiles/:name    required-force cascade or detach
 import { assertInstalledKind } from '../../../core/config.js';
+import { listNodesByProfile, shiftProfileNodeDeadlines } from '../../../core/canvas/canvas.js';
+import { shiftAutoBackgroundBashDeadlines } from '../../../core/bash-jobs.js';
+import { contextDir } from '../../../core/canvas/paths.js';
+import { boundFleet } from '../../../core/runtime/fleet.js';
+import { recordedPidLiveness } from '../../../core/canvas/pid.js';
 import { usage } from '../../../core/errors.js';
-import { assertProfileProjects, createProfile, ensureRootProfile, listProfiles, loadProfileManifest, updateProfileMetadata, } from '../../../core/profiles/manifest.js';
+import { assertProfileProjects, createProfile, ensureRootProfile, listProfiles, loadProfileManifest, pauseProfile, resumeProfile, updateProfileMetadata, } from '../../../core/profiles/manifest.js';
 import { requestProfileDeletion } from '../../profile-delete.js';
 import { toProfileDTO } from '../map.js';
 const ROOT_PROFILE_NAME = 'root';
@@ -62,6 +67,51 @@ function handleSetMetadata(ctx) {
     const updated = updateProfileMetadata(profile.profileId, set, unset);
     return { status: 200, body: toProfileDTO(updated) };
 }
+/** `POST /v1/profiles/:name/pause` — make the profile inert, then directly
+ * SIGTERM its live brokers. This deliberately avoids host teardown: the
+ * broker's SIGTERM path hands foreground bash jobs to their detached
+ * supervisors, while shutdown would abort and remove them. */
+function handlePause(ctx) {
+    const profile = loadProfileManifest(ctx.params['name']);
+    const paused = pauseProfile(profile.profileId);
+    const nodes = listNodesByProfile(profile.profileId).filter((node) => node.status === 'active' || node.status === 'idle');
+    if (nodes.length === 0)
+        return { status: 200, body: { profile_id: profile.profileId, paused_at: paused.manifest.paused_at } };
+    const fleet = boundFleet();
+    for (const node of nodes) {
+        const live = fleet.get(node.node_id);
+        if (live !== undefined) {
+            fleet.interruptForProfilePause(node.node_id, live.pid);
+            continue;
+        }
+        if (node.pi_pid != null && recordedPidLiveness(node.pi_pid, node.pi_pid_identity) === 'alive') {
+            fleet.interruptForProfilePause(node.node_id, node.pi_pid);
+        }
+    }
+    return { status: 200, body: { profile_id: profile.profileId, paused_at: paused.manifest.paused_at } };
+}
+/** `POST /v1/profiles/:name/resume` — restore admission and credit active
+ * profile deadlines for the interval during which the profile was inert. The
+ * lifecycle tick owns broker recovery after the pause interruption settles. */
+function handleResume(ctx) {
+    const profile = loadProfileManifest(ctx.params['name']);
+    const resumed = resumeProfile(profile.profileId);
+    if (resumed.pausedAt !== null) {
+        const pausedAt = Date.parse(resumed.pausedAt);
+        if (!Number.isNaN(pausedAt)) {
+            const pausedMs = Math.max(0, Date.now() - pausedAt);
+            shiftProfileNodeDeadlines(profile.profileId, pausedMs);
+            // Background bash claim windows are the same kind of budget as a node
+            // deadline: time the node was allowed to act, not wall-clock time.
+            for (const node of listNodesByProfile(profile.profileId)) {
+                if (node.status === 'dead')
+                    continue;
+                shiftAutoBackgroundBashDeadlines(contextDir(node.node_id), pausedMs);
+            }
+        }
+    }
+    return { status: 200, body: { profile_id: profile.profileId, paused_at: resumed.manifest.paused_at } };
+}
 /** `GET /v1/profiles` — every profile with a readable manifest. */
 function handleList() {
     return { status: 200, body: listProfiles().map(toProfileDTO) };
@@ -81,6 +131,8 @@ async function handleDelete(ctx) {
 }
 export const profileRoutes = [
     { method: 'PUT', pattern: '/v1/profiles/:name', handler: handleEnsure },
+    { method: 'POST', pattern: '/v1/profiles/:name/pause', handler: handlePause },
+    { method: 'POST', pattern: '/v1/profiles/:name/resume', handler: handleResume },
     { method: 'PATCH', pattern: '/v1/profiles/:name/metadata', handler: handleSetMetadata },
     { method: 'DELETE', pattern: '/v1/profiles/:name', handler: handleDelete },
     { method: 'GET', pattern: '/v1/profiles', handler: handleList },

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

@@ -2,7 +2,13 @@
 // push route — `tier` is the report kind and update-only `delivery_tier` sets
 // subscriber delivery urgency; `final` drives the server-side lifecycle
 // transition inside feed `push()` (the sanctioned path). `GET
-// /nodes/{id}/reports` lists the node's stored report files.
+// /nodes/{id}/reports` lists the node's stored report files. `POST
+// /nodes/{id}/result` submits a structured result against the node's pending
+// output schema (`crtr push result`): validate → write context/result.json →
+// push the mode-matched report → clear the schema — or declines it
+// (`--decline --code [--retryable]`): write context/declined.json → push the
+// same report shape carrying a `failure`/`declined` outcome whose detail holds
+// the reason, code, and retryable flag → clear the schema.
 //
 // `{id}` is the REPORTING node (client-side = CRTR_NODE_ID).
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
@@ -15,6 +21,7 @@ import { notFound, usage } from '../../../core/errors.js';
 import { InputError } from '../../../core/io.js';
 import { parseFrontmatterGeneric } from '../../../core/frontmatter.js';
 import { toReportResultDTO } from '../map.js';
+import { outputSchemaPath, readOutputRequest, removeOutputSchema, validateStructuredResult, writeOutputDeclined, writeOutputResult, } from '../../../core/runtime/structured-output.js';
 function requireNode(id) {
     if (getNode(id) === null)
         throw notFound(`unknown node: ${id}`, { received: id });
@@ -45,46 +52,202 @@ async function handlePush(ctx) {
     const id = ctx.params['id'];
     requireNode(id);
     const req = parsePushBody(ctx.body);
+    // A valid pending structured-output request means this node owes a
+    // schema-checked result — a plain `push final` would finish it with
+    // context/result.json never written (the stop guard honors `pushedFinal`
+    // before its structured-output check, so it cannot catch this). An INVALID
+    // request file deliberately does NOT block: the stop guard's prescribed
+    // manual-cleanup escape (`push final` after removing the corrupt file, or
+    // despite it) must stay reachable.
+    if (req.tier === 'final' && readOutputRequest(id).state === 'valid') {
+        throw new InputError({
+            error: 'structured_result_pending',
+            message: 'This node owes a structured result — a plain `push final` would finish it without recording one.',
+            next: 'Submit the result with `crtr push result` instead; it validates against the pending schema, records it, and pushes the final report for you. If the schema cannot be honestly satisfied, `crtr push result --decline "<reason>" --code <token>` records the decline and finishes the node.',
+        });
+    }
     // `final` flips the node to done inside push() (commitCanonicalFinal). Capture
     // the pre-push status so the DTO can report the transition (spec §7.4).
     const before = req.tier === 'final' ? getNode(id)?.status : undefined;
-    // `final` with an OPEN managed worktree, BEFORE the push/transition (spec
-    // §6.2 — worktree fs ops are server-side). A provably-clean, zero-commit
-    // worktree is auto-dropped so a read-only or already-landed node
-    // can finish without an explicit `node worktree close`; a clean worktree
-    // whose exact tip is already on origin can also finish while retaining its
-    // branch and checkout. Any work that is neither locally landed nor remotely
-    // retained instead blocks with the parity `open_managed_worktree` error,
-    // round-tripped via CrtrError.details so the CLI renders the same InputError
-    // (next-hint included) it surfaced before B-5 re-homed this to the server.
-    let autoDroppedPath;
-    if (req.tier === 'final' && hasOpenManagedWorktree(getNode(id))) {
-        const dropped = autoDropCleanManagedWorktree(id);
-        if (dropped !== null) {
-            autoDroppedPath = dropped.worktree_path;
+    const autoDroppedPath = req.tier === 'final' ? await guardFinalWorktree(id) : undefined;
+    const result = await pushOrRethrow(id, req);
+    const transitioned = req.tier === 'final' && before !== undefined
+        ? { from: before, to: getNode(id)?.status ?? 'done' }
+        : undefined;
+    return { status: 200, body: toReportResultDTO(result, transitioned, autoDroppedPath) };
+}
+/** The `final`-path managed-worktree guard, BEFORE the push/transition (spec
+ *  §6.2 — worktree fs ops are server-side). A provably-clean, zero-commit
+ *  worktree is auto-dropped so a read-only or already-landed node
+ *  can finish without an explicit `node worktree close`; a clean worktree
+ *  whose exact tip is already on origin can also finish while retaining its
+ *  branch and checkout. Any work that is neither locally landed nor remotely
+ *  retained instead blocks with the parity `open_managed_worktree` error,
+ *  round-tripped via CrtrError.details so the CLI renders the same InputError
+ *  (next-hint included) it surfaced before B-5 re-homed this to the server.
+ *  Returns the auto-dropped checkout path, or undefined when nothing dropped. */
+async function guardFinalWorktree(id) {
+    if (!hasOpenManagedWorktree(getNode(id)))
+        return undefined;
+    const dropped = autoDropCleanManagedWorktree(id);
+    if (dropped !== null)
+        return dropped.worktree_path;
+    if (await branchIsPushedAtCurrentTip(getNode(id).managed_worktree))
+        return undefined;
+    // Thrown as InputError so `toErrorBody` round-trips the FULL structured
+    // payload (code + message + next) into `ApiError.details`, and the CLI's
+    // shared `apiErrorToCliError` reconstructs it byte-for-byte — no
+    // command-local mapper needed (plan C-5).
+    throw new InputError({
+        error: 'open_managed_worktree',
+        message: 'This node still owns an open managed worktree — `push final` is blocked until it is closed.',
+        next: (() => {
+            const wt = getNode(id)?.managed_worktree;
+            return wt !== null && wt !== undefined && wt.state === 'open' && !existsSync(wt.path)
+                ? missingWorktreeRecoveryHint(wt)
+                : 'Commit the remaining work in the worktree, push its branch to origin at its current tip, then rerun `crtr push final`; or run `crtr node worktree close` to land it locally.';
+        })(),
+    });
+}
+/** Cap on the fenced-JSON echo inside the submit report body. The full result
+ *  is always on disk at result_path; the report only needs enough to orient. */
+const REPORT_JSON_ECHO_LIMIT = 2000;
+function submitReportBody(resultPath, value) {
+    const json = JSON.stringify(value, null, 2);
+    const fenced = json.length > REPORT_JSON_ECHO_LIMIT
+        ? `${json.slice(0, REPORT_JSON_ECHO_LIMIT)}\n… (truncated — the full result is at the result path above)`
+        : json;
+    return `Structured output submitted.\n\nResult path: ${resultPath}\n\n\`\`\`json\n${fenced}\n\`\`\`\n`;
+}
+function declineReportBody(declinedPath, declined) {
+    return `Structured result declined.\n\nReason: ${declined.reason}\nCode: ${declined.code}\nRetryable: ${declined.retryable ? 'yes' : 'no'}\n\nDeclined marker: ${declinedPath}\n`;
+}
+/** A decline reason is one sentence for a human or a consumer to read, not a payload. */
+const DECLINE_REASON_MAX_CHARS = 1024;
+/** A decline code is one token the requester classifies on, not a message. */
+const DECLINE_CODE_MAX_CHARS = 64;
+/** Narrow the submit body to exactly one of `{ value }` or `{ decline, code, retryable }`. */
+function parseSubmitBody(body) {
+    if (typeof body !== 'object' || body === null) {
+        throw usage('a result submission requires a JSON body { value } or { decline, code, retryable }');
+    }
+    const hasValue = Object.hasOwn(body, 'value');
+    const hasDecline = Object.hasOwn(body, 'decline');
+    if (hasValue && hasDecline)
+        throw usage('a result submission carries either { value } or { decline, code, retryable }, not both');
+    if (hasDecline) {
+        const { decline, code, retryable } = body;
+        if (typeof decline !== 'string' || decline.trim() === '') {
+            throw new InputError({
+                error: 'missing_decline_reason',
+                message: 'A decline needs a reason.',
+                next: 'Rerun with `--decline "<one sentence on why the schema cannot be honestly satisfied>" --code <token>`.',
+            });
         }
-        else if (!(await branchIsPushedAtCurrentTip(getNode(id).managed_worktree))) {
-            // Thrown as InputError so `toErrorBody` round-trips the FULL structured
-            // payload (code + message + next) into `ApiError.details`, and the CLI's
-            // shared `apiErrorToCliError` reconstructs it byte-for-byte — no
-            // command-local mapper needed (plan C-5).
+        if (decline.length > DECLINE_REASON_MAX_CHARS) {
             throw new InputError({
-                error: 'open_managed_worktree',
-                message: 'This node still owns an open managed worktree — `push final` is blocked until it is closed.',
-                next: (() => {
-                    const wt = getNode(id)?.managed_worktree;
-                    return wt !== null && wt !== undefined && wt.state === 'open' && !existsSync(wt.path)
-                        ? missingWorktreeRecoveryHint(wt)
-                        : 'Commit the remaining work in the worktree, push its branch to origin at its current tip, then rerun `crtr push final`; or run `crtr node worktree close` to land it locally.';
-                })(),
+                error: 'decline_reason_too_long',
+                message: `A decline reason is at most ${DECLINE_REASON_MAX_CHARS} characters (got ${decline.length}).`,
+                next: 'Keep the reason to one plain sentence; put any detail in an artifact and name its path.',
             });
         }
+        if (typeof code !== 'string' || code.trim() === '' || /\s/.test(code.trim()) || code.trim().length > DECLINE_CODE_MAX_CHARS) {
+            throw new InputError({
+                error: 'invalid_decline_code',
+                message: `A decline needs a code: one whitespace-free token of at most ${DECLINE_CODE_MAX_CHARS} characters naming the decline class.`,
+                next: 'Rerun with `--code <token>` — the token your requester documented for this case.',
+            });
+        }
+        if (typeof retryable !== 'boolean') {
+            throw usage('a decline carries `retryable` as a boolean');
+        }
+        return { declined: { reason: decline.trim(), code: code.trim(), retryable } };
     }
-    const result = await pushOrRethrow(id, req);
-    const transitioned = req.tier === 'final' && before !== undefined
+    if (!hasValue) {
+        // `value` must be PRESENT — but any JSON value, including null, is a legal
+        // result to validate, so presence is checked rather than truthiness.
+        throw usage('a result submission requires a JSON body { value } or { decline, code, retryable }');
+    }
+    return { value: body.value };
+}
+/** `POST /v1/nodes/{id}/result` — submit a structured result (`crtr push
+ *  result`). Validate against the pending schema, write context/result.json
+ *  atomically, push the mode-matched report (final for terminal, update for
+ *  oneoff), then clear the schema. Any failure before the schema removal leaves
+ *  the request in place, so the submit stays retryable. */
+async function handleSubmitResult(ctx) {
+    const id = ctx.params['id'];
+    requireNode(id);
+    const submitted = parseSubmitBody(ctx.body);
+    const state = readOutputRequest(id);
+    if (state.state === 'absent') {
+        throw new InputError({
+            error: 'no_output_request',
+            message: 'No structured output is currently requested of this node.',
+            next: 'Nothing to submit here — continue working, or finish with `crtr push final`.',
+        });
+    }
+    if (state.state === 'invalid') {
+        throw new InputError({
+            error: 'invalid_output_request',
+            message: `The structured-output request file is invalid: ${state.error}`,
+            next: `Have the requester re-issue the request, or remove ${outputSchemaPath(id)} and finish with \`crtr push final\`.`,
+        });
+    }
+    const { mode, schema } = state.request;
+    let validated;
+    if ('value' in submitted) {
+        try {
+            validated = await validateStructuredResult(schema, submitted.value);
+        }
+        catch (err) {
+            // Schema retained — the node fixes the listed fields and resubmits.
+            throw new InputError({
+                error: 'result_schema_mismatch',
+                message: `the submitted result does not match the requested schema: ${err.message}`,
+                next: 'Fix the listed fields and rerun `crtr push result`; if the schema cannot be honestly satisfied, rerun with `--decline "<reason>" --code <token>`.',
+            });
+        }
+    }
+    const before = mode === 'terminal' ? getNode(id)?.status : undefined;
+    const autoDroppedPath = mode === 'terminal' ? await guardFinalWorktree(id) : undefined;
+    let resultPath;
+    let reportBody;
+    let outcome;
+    if ('declined' in submitted) {
+        const { declined } = submitted;
+        resultPath = writeOutputDeclined(id, { mode, ...declined, at: new Date().toISOString() });
+        reportBody = declineReportBody(resultPath, declined);
+        // A one-off decline is an update report, not the canonical final: no outcome to record.
+        if (mode === 'terminal') {
+            const detail = { schema: 'crtr.node-outcome-detail/v1', message: declined.reason, declined };
+            outcome = { kind: 'failure', reason: 'declined', detailJson: JSON.stringify(detail) };
+        }
+    }
+    else {
+        resultPath = writeOutputResult(id, validated);
+        reportBody = submitReportBody(resultPath, validated);
+    }
+    const pushed = await pushOrRethrow(id, {
+        tier: mode === 'terminal' ? 'final' : 'update',
+        body: reportBody,
+    }, outcome);
+    removeOutputSchema(id);
+    const transitioned = mode === 'terminal' && before !== undefined
         ? { from: before, to: getNode(id)?.status ?? 'done' }
         : undefined;
-    return { status: 200, body: toReportResultDTO(result, transitioned, autoDroppedPath) };
+    const body = {
+        mode,
+        result_path: resultPath,
+        report_path: pushed.reportPath,
+        notified: [...pushed.deliveredTo],
+        ...('declined' in submitted ? { declined: submitted.declined } : {}),
+        ...(transitioned === undefined ? {} : { transitioned }),
+        ...(autoDroppedPath === undefined
+            ? {}
+            : { worktree_auto_dropped: true, worktree_auto_dropped_path: autoDroppedPath }),
+    };
+    return { status: 200, body };
 }
 /** `push()` but with the finalization guards translated to the same structured
  *  `InputError` the pre-API `crtr push` verb surfaced. Feed throws a bare
@@ -95,9 +258,9 @@ async function handlePush(ctx) {
  *  survives (a bare 409 would otherwise collapse to the generic `conflict`
  *  code). `unknown_node` is unreachable here (`requireNode` guards above), so
  *  it falls through as the generic 404. */
-async function pushOrRethrow(id, req) {
+async function pushOrRethrow(id, req, outcome) {
     try {
-        return await push(id, { kind: req.tier, body: req.body, ...(req.delivery_tier === undefined ? {} : { deliveryTier: req.delivery_tier }) });
+        return await push(id, { kind: req.tier, body: req.body, ...(req.delivery_tier === undefined ? {} : { deliveryTier: req.delivery_tier }), ...(outcome === undefined ? {} : { outcome }) });
     }
     catch (err) {
         if (err instanceof FinalizationError && err.code === 'already_finalized') {
@@ -164,4 +327,5 @@ function handleList(ctx) {
 export const reportRoutes = [
     { method: 'POST', pattern: '/v1/nodes/:id/reports', handler: handlePush },
     { method: 'GET', pattern: '/v1/nodes/:id/reports', handler: handleList },
+    { method: 'POST', pattern: '/v1/nodes/:id/result', handler: handleSubmitResult },
 ];

package/dist/daemon/api/map.d.ts

@@ -1,4 +1,5 @@
-import type { ManagedWorktree, NodeMeta, NodeRow, SubscriptionRef } from '../../core/canvas/types.js';
+import type { ManagedWorktree, NodeMeta, NodeRow, NodeRuntime, SubscriptionRef } from '../../core/canvas/types.js';
+import type { OutcomeDeliveryRecord } from '../../core/canvas/node-outcome-deliveries.js';
 import type { ReviewComment, ReviewCommentEvent, ReviewErrorCode, ReviewRecord, ReviewResult } from '../../core/review/types.js';
 import type { Cron, CronRunRecord } from '../../core/canvas/crons.js';
 import type { ProfileEntry } from '../../core/profiles/manifest.js';
@@ -6,7 +7,11 @@ import type { ReviveResult } from '../../core/runtime/revive.js';
 import type { CloseNodeResult } from '../../core/runtime/close.js';
 import { type PushResult } from '../../core/feed/feed.js';
 import type { PageFeedback, PageFeedbackComment } from '../../core/human/feedback.js';
-import type { CloseResultDTO, CronDTO, CronRunDTO, ErrorBody, NodeEdgesDTO, NodePathsDTO, NodeStatusDTO, NodeSummaryDTO, NodeDetailDTO, NodeWorktreeDTO, ProfileDTO, ReviewCommentDTO, ReviewCommentEventDTO, ReviewDTO, FeedbackResultDTO, PageFeedbackCommentDTO, PageFeedbackDTO, PushReportResultDTO, ReviveResultDTO, SubscriptionDTO } from '../../api/index.js';
+import type { CloseResultDTO, CronDTO, CronRunDTO, ErrorBody, NodeEdgesDTO, NodeOutcomeDTO, NodePathsDTO, NodeStatusDTO, OutcomeDeliveryDTO, NodeSummaryDTO, NodeDetailDTO, NodeWorktreeDTO, ProfileDTO, ReviewCommentDTO, ReviewCommentEventDTO, ReviewDTO, FeedbackResultDTO, PageFeedbackCommentDTO, PageFeedbackDTO, PushReportResultDTO, ReviveResultDTO, SubscriptionDTO } from '../../api/index.js';
+/** Project a latched outcome, or null while this node remains unsettled. */
+export declare function toNodeOutcomeDTO(node: Pick<NodeMeta, 'node_id' | 'final_report'> & NodeRuntime): NodeOutcomeDTO | null;
+/** Project a durable delivery row without exposing its execution coordinates or stderr tail. */
+export declare function toOutcomeDeliveryDTO(row: OutcomeDeliveryRecord): OutcomeDeliveryDTO;
 /** Project the queryable row (what `listNodes` yields) into a summary DTO. */
 export declare function toNodeSummaryDTO(row: NodeRow): NodeSummaryDTO;
 /** The subscription/child edges a detail projection needs. The handler gathers

package/dist/daemon/api/map.js

@@ -4,13 +4,15 @@
 // dependency-light wire contract. `src/api/*` stays pure (Node built-ins only);
 // all projection lives here, server-side.
 //
-// Every function here is a pure projection (no I/O, no db reach) except the
-// path builders, which call `core/canvas/paths.ts` — themselves pure string
-// constructors. The DTO field sets these project into were pinned by A-1 as
+// Every function here is a pure projection (no db reach) except the path
+// builders and the optional structured-result sidecar read needed by a settled
+// outcome. The DTO field sets these project into were pinned by A-1 as
 // reasonable projections; this module is what makes them concrete, so any DTO
 // field that projection proves wrong is corrected here at the source.
+import { existsSync, readFileSync } from 'node:fs';
+import { outputResultPath } from '../../core/runtime/structured-output.js';
 import { ReviewOperationError as ReviewOperationErrorClass } from '../../core/review/types.js';
-import { sanitizeProfileMetadata } from '../../core/profiles/manifest.js';
+import { isProfilePaused, sanitizeProfileMetadata } from '../../core/profiles/manifest.js';
 import { contextDir, inboxPath, nodeDir, nodeMetaPath, reportsDir, reviewResultPath, transcriptPath, viewSocketPath, } from '../../core/canvas/paths.js';
 import { FinalizationError } from '../../core/feed/feed.js';
 import { NodeIdConflictError } from '../../core/runtime/nodes.js';
@@ -23,6 +25,72 @@ import { sinkDisplay } from '../cron-sink.js';
 import { responsePath } from '../../core/human/convention.js';
 import { ticketDir } from '../../core/human/root.js';
 // Node projections
+/** Read the optional machine result without letting a missing or malformed sidecar obscure the durable outcome row. */
+function readStructuredResult(nodeId) {
+    const path = outputResultPath(nodeId);
+    try {
+        return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Project a latched outcome, or null while this node remains unsettled. */
+export function toNodeOutcomeDTO(node) {
+    if (node.outcome_at === null || node.outcome_at === undefined || node.outcome_kind === null || node.outcome_kind === undefined || node.outcome_reason === null || node.outcome_reason === undefined) {
+        return null;
+    }
+    let detail = null;
+    if (node.outcome_detail_json !== null && node.outcome_detail_json !== undefined) {
+        try {
+            detail = JSON.parse(node.outcome_detail_json);
+        }
+        catch {
+            detail = null;
+        }
+    }
+    // A declined structured result is a `failure` that still carries a canonical final report.
+    const finalReport = node.final_report ?? null;
+    const base = {
+        node_id: node.node_id,
+        revision: node.outcome_revision ?? 1,
+        settled_at: node.outcome_at,
+        final_report: finalReport,
+        final_report_path: finalReport === null ? null : `${reportsDir(node.node_id)}/${finalReport}`,
+        structured_result: node.outcome_kind === 'result' ? readStructuredResult(node.node_id) : null,
+        detail,
+    };
+    if (node.outcome_kind === 'result')
+        return { ...base, kind: 'result', reason: node.outcome_reason, declined: null };
+    if (node.outcome_reason === 'declined') {
+        // The decline lane always records its detail; a declined row without one is corrupt, not a legacy shape.
+        if (detail?.declined === undefined)
+            throw new Error(`node ${node.node_id}: outcome reason 'declined' without a declined detail`);
+        return { ...base, kind: 'failure', reason: 'declined', declined: detail.declined };
+    }
+    return { ...base, kind: 'failure', reason: node.outcome_reason, declined: null };
+}
+/** Project a durable delivery row without exposing its execution coordinates or stderr tail. */
+export function toOutcomeDeliveryDTO(row) {
+    const failure = row.lastFailure;
+    return {
+        node_id: row.nodeId,
+        state: row.state,
+        action: row.actionName,
+        attempt: row.attempt,
+        next_attempt_at: row.nextAttemptAt === 0 ? null : new Date(row.nextAttemptAt).toISOString(),
+        accepted_at: row.acceptedAt === null ? null : new Date(row.acceptedAt).toISOString(),
+        permanent_failed_at: row.permanentFailedAt === null ? null : new Date(row.permanentFailedAt).toISOString(),
+        last_failure: failure === null ? null : {
+            kind: failure.kind,
+            ...(failure.exitCode === undefined ? {} : { exit_code: failure.exitCode }),
+            ...(failure.signal === undefined ? {} : { signal: failure.signal }),
+            ...(failure.message === undefined ? {} : { message: failure.message }),
+        },
+        created_at: new Date(row.createdAt).toISOString(),
+        updated_at: new Date(row.updatedAt).toISOString(),
+    };
+}
 /** Project the queryable row (what `listNodes` yields) into a summary DTO. */
 export function toNodeSummaryDTO(row) {
     return {
@@ -37,6 +105,7 @@ export function toNodeSummaryDTO(row) {
         cwd: row.cwd,
         host_kind: row.host_kind,
         profile_id: row.profile_id,
+        profile_paused: isProfilePaused(row.profile_id),
         parent: row.parent,
         created: row.created,
         intent: row.intent,
@@ -50,6 +119,8 @@ export function toNodeSummaryDTO(row) {
         pane: row.pane,
         final_report: row.final_report ?? null,
         finalized_at: row.finalized_at ?? null,
+        deadline_at: row.deadline_at ?? null,
+        outcome: toNodeOutcomeDTO(row),
     };
 }
 /** Project a node's spine + subscription edges (absorbs `managers`/`paths`). */
@@ -109,6 +180,7 @@ export function toNodeDetailDTO(meta, edges) {
         cwd: meta.cwd,
         host_kind: meta.host_kind ?? null,
         profile_id: meta.profile_id ?? null,
+        profile_paused: isProfilePaused(meta.profile_id),
         parent: meta.parent ?? null,
         created: meta.created,
         intent: (meta.intent ?? null),
@@ -122,6 +194,8 @@ export function toNodeDetailDTO(meta, edges) {
         pane: meta.pane ?? null,
         final_report: meta.final_report ?? null,
         finalized_at: meta.finalized_at ?? null,
+        deadline_at: meta.deadline_at ?? null,
+        outcome: toNodeOutcomeDTO(meta),
         creator: meta.creator ?? null,
         edges: toNodeEdgesDTO(meta, edges),
         paths: toNodePathsDTO(meta.node_id),

package/dist/daemon/api/server.js

@@ -38,6 +38,7 @@ import { messageRoutes } from './handlers/messages.js';
 import { modelAuthRoutes } from './handlers/modelauth.js';
 import { modelConfigRoutes } from './handlers/model-config.js';
 import { nodeRoutes } from './handlers/nodes.js';
+import { nodeOutcomeRoutes } from './handlers/node-outcomes.js';
 import { profileRoutes } from './handlers/profiles.js';
 import { prospectiveChatInventoryRoutes } from './handlers/prospective-chat-inventory.js';
 import { reportRoutes } from './handlers/reports.js';
@@ -54,6 +55,7 @@ function buildRouter() {
         .registerAll(healthRoutes)
         .registerAll(daemonRoutes)
         .registerAll(nodeRoutes)
+        .registerAll(nodeOutcomeRoutes)
         .registerAll(bashJobRoutes)
         .registerAll(brokerOperationRoutes)
         .registerAll(worktreeRoutes)