@north-light/crouter 0.3.282 → 0.3.284

package/dist/core/canvas/node-outcome-deliveries.d.ts

@@ -0,0 +1,80 @@
+import { type NodeOutcomeKind, type TerminalReason } from './types.js';
+export type OutcomeDeliveryState = 'armed' | 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface OutcomeDeliveryFailure {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exitCode?: number;
+    signal?: string;
+    message?: string;
+    stderr?: string;
+}
+/** Durable exponential retry delay for the attempt that just failed. */
+export declare function outcomeDeliveryBackoffMs(attempt: number): number;
+export interface OutcomeDeliveryRecord {
+    nodeId: string;
+    state: OutcomeDeliveryState;
+    attempt: number;
+    actionName: string;
+    argv: string[];
+    cwd: string;
+    configOrigin: string;
+    payload: unknown | null;
+    document: unknown | null;
+    nextAttemptAt: number;
+    claimedAt: number | null;
+    claimOwner: string | null;
+    acceptedAt: number | null;
+    permanentFailedAt: number | null;
+    lastFailure: OutcomeDeliveryFailure | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface OutcomeDocumentSnapshot {
+    kind: NodeOutcomeKind;
+    reason: TerminalReason;
+    at: string;
+    revision: number;
+    detailJson: string | null;
+}
+/** Compose every delivery document from the hydrated identity and the immutable outcome latch. */
+export declare function composeOutcomeDeliveryDocument(args: {
+    nodeId: string;
+    outcome: OutcomeDocumentSnapshot;
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    finalReport?: string | null;
+    structuredResult?: unknown;
+}): string;
+/** Register a target atomically against the outcome latch. A still-armed target
+ * is replaceable; a settled registration is not. When the outcome already
+ * exists, the row is born pending with its complete immutable document. */
+export declare function armOutcomeDelivery(row: {
+    nodeId: string;
+    actionName: string;
+    argv: string[];
+    cwd: string;
+    configOrigin: string;
+    payload?: unknown;
+    now?: number;
+}): OutcomeDeliveryRecord | null;
+export declare function readOutcomeDelivery(nodeId: string): OutcomeDeliveryRecord | null;
+export declare function dueOutcomeDeliveries(now: number): OutcomeDeliveryRecord[];
+export declare function claimOutcomeDelivery(nodeId: string, now: number, claimOwner: string): OutcomeDeliveryRecord | null;
+export type OutcomeDeliverySettlement = {
+    state: 'accepted';
+} | {
+    state: 'permanent_failed';
+    failure: OutcomeDeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: OutcomeDeliveryFailure;
+};
+/** Settle only the still-owned running attempt, fencing stale delivery processes. */
+export declare function settleOutcomeDelivery(nodeId: string, attempt: number, claimOwner: string, settlement: OutcomeDeliverySettlement, now: number): boolean;
+export declare function recoverRunningOutcomeDeliveries(now: number): number;
+/** Disarming is deliberately limited to registrations that have not started delivery. */
+export declare function disarmOutcomeDelivery(nodeId: string): boolean;
+/** A canonical final is the one allowed outcome supersede: discard any old claim and retry state. */
+export declare function resetOutcomeDeliveryForSupersede(nodeId: string, documentJson: string | null, now: number): boolean;

package/dist/core/canvas/node-outcome-deliveries.js

@@ -0,0 +1,163 @@
+// Durable delivery registration and attempt state for a node's terminal outcome.
+import { openDb, withCanvasWrite } from './db.js';
+import { getNode } from './canvas.js';
+import { OUTCOME_PAYLOAD_MAX_BYTES } from './types.js';
+import { composeNodeOutcomeDocument } from '../runtime/outcome-document.js';
+/** Durable exponential retry delay for the attempt that just failed. */
+export function outcomeDeliveryBackoffMs(attempt) {
+    return Math.min(5_000 * 2 ** (attempt - 1), 3_600_000);
+}
+function serializedPayload(payload) {
+    if (payload === undefined)
+        return null;
+    const json = JSON.stringify(payload);
+    if (json === undefined)
+        throw new TypeError('outcome delivery payload must be JSON-serializable');
+    if (Buffer.byteLength(json, 'utf8') > OUTCOME_PAYLOAD_MAX_BYTES) {
+        throw new RangeError(`outcome delivery payload exceeds ${OUTCOME_PAYLOAD_MAX_BYTES} bytes`);
+    }
+    return json;
+}
+function outcomeDeliveryFrom(row) {
+    return {
+        nodeId: row.node_id,
+        state: row.state,
+        attempt: row.attempt,
+        actionName: row.action_name,
+        argv: JSON.parse(row.argv_json),
+        cwd: row.cwd,
+        configOrigin: row.config_origin,
+        payload: row.payload_json === null ? null : JSON.parse(row.payload_json),
+        document: row.document_json === null ? null : JSON.parse(row.document_json),
+        nextAttemptAt: row.next_attempt_at,
+        claimedAt: row.claimed_at,
+        claimOwner: row.claim_owner,
+        acceptedAt: row.accepted_at,
+        permanentFailedAt: row.permanent_failed_at,
+        lastFailure: row.last_failure_json === null ? null : JSON.parse(row.last_failure_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/** The latch, rather than a later mutable row, defines the terminal view in a delivery document. */
+function nodeAtOutcome(node, outcome) {
+    let status;
+    let intent;
+    if (outcome.kind === 'result' || outcome.reason === 'finished' || outcome.reason === 'declined') {
+        status = 'done';
+        intent = 'done';
+    }
+    else if (outcome.reason === 'parked') {
+        status = 'done';
+        intent = 'parked';
+    }
+    else if (outcome.reason === 'closed' || outcome.reason === 'retired' || outcome.reason === 'stranded' || outcome.reason === 'deadline_exceeded') {
+        status = 'canceled';
+        intent = null;
+    }
+    else {
+        status = 'dead';
+        intent = null;
+    }
+    return { ...node, status, intent, terminal_reason: outcome.reason };
+}
+/** Compose every delivery document from the hydrated identity and the immutable outcome latch. */
+export function composeOutcomeDeliveryDocument(args) {
+    const node = getNode(args.nodeId);
+    if (node === null)
+        throw new Error(`unknown node ${args.nodeId}`);
+    return JSON.stringify(composeNodeOutcomeDocument({
+        node: nodeAtOutcome(node, args.outcome),
+        outcome: args.outcome,
+        action: args.action,
+        ...(args.finalReport === undefined ? {} : { finalReport: args.finalReport }),
+        ...(args.structuredResult === undefined ? {} : { structuredResult: args.structuredResult }),
+    }));
+}
+/** Register a target atomically against the outcome latch. A still-armed target
+ * is replaceable; a settled registration is not. When the outcome already
+ * exists, the row is born pending with its complete immutable document. */
+export function armOutcomeDelivery(row) {
+    const now = row.now ?? Date.now();
+    const payloadJson = serializedPayload(row.payload);
+    return withCanvasWrite((db) => {
+        const node = db.prepare('SELECT * FROM nodes WHERE node_id = ?').get(row.nodeId);
+        if (node === undefined)
+            throw new Error(`unknown node ${row.nodeId}`);
+        const settled = node.outcome_at !== null;
+        if (settled && (node.outcome_kind === null || node.outcome_reason === null)) {
+            throw new Error(`outcome latch is incomplete for node ${row.nodeId}`);
+        }
+        const documentJson = !settled
+            ? null
+            : composeOutcomeDeliveryDocument({
+                nodeId: row.nodeId,
+                outcome: {
+                    kind: node.outcome_kind,
+                    reason: node.outcome_reason,
+                    at: node.outcome_at,
+                    revision: node.outcome_revision,
+                    detailJson: node.outcome_detail_json,
+                },
+                action: { name: row.actionName, payload: row.payload ?? null },
+                finalReport: node.final_report,
+            });
+        const state = settled ? 'pending' : 'armed';
+        const inserted = db.prepare(`INSERT INTO node_outcome_deliveries
+        (node_id, state, action_name, argv_json, cwd, config_origin, payload_json, document_json, next_attempt_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         state = excluded.state, action_name = excluded.action_name, argv_json = excluded.argv_json,
+         cwd = excluded.cwd, config_origin = excluded.config_origin, payload_json = excluded.payload_json,
+         document_json = excluded.document_json, next_attempt_at = excluded.next_attempt_at,
+         updated_at = excluded.updated_at
+       WHERE node_outcome_deliveries.state = 'armed'`).run(row.nodeId, state, row.actionName, JSON.stringify(row.argv), row.cwd, row.configOrigin, payloadJson, documentJson, settled ? now : 0, now, now);
+        if (Number(inserted.changes) === 0)
+            return null;
+        return outcomeDeliveryFrom(db.prepare('SELECT * FROM node_outcome_deliveries WHERE node_id = ?').get(row.nodeId));
+    });
+}
+export function readOutcomeDelivery(nodeId) {
+    const row = openDb().prepare('SELECT * FROM node_outcome_deliveries WHERE node_id = ?').get(nodeId);
+    return row === undefined ? null : outcomeDeliveryFrom(row);
+}
+export function dueOutcomeDeliveries(now) {
+    return openDb().prepare(`SELECT * FROM node_outcome_deliveries
+     WHERE state = 'pending' AND next_attempt_at <= ?
+     ORDER BY next_attempt_at, created_at, node_id`).all(now).map(outcomeDeliveryFrom);
+}
+export function claimOutcomeDelivery(nodeId, now, claimOwner) {
+    return withCanvasWrite((db) => {
+        const claimed = db.prepare(`UPDATE node_outcome_deliveries
+       SET state = 'running', attempt = attempt + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+       WHERE node_id = ? AND state = 'pending' AND next_attempt_at <= ?`).run(now, claimOwner, now, nodeId, now);
+        if (Number(claimed.changes) === 0)
+            return null;
+        return outcomeDeliveryFrom(db.prepare('SELECT * FROM node_outcome_deliveries WHERE node_id = ?').get(nodeId));
+    });
+}
+/** Settle only the still-owned running attempt, fencing stale delivery processes. */
+export function settleOutcomeDelivery(nodeId, attempt, claimOwner, settlement, now) {
+    const failure = settlement.state === 'accepted' ? null : JSON.stringify(settlement.failure);
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE node_outcome_deliveries
+     SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+         accepted_at = ?, permanent_failed_at = ?, last_failure_json = ?, updated_at = ?
+     WHERE node_id = ? AND state = 'running' AND attempt = ? AND claim_owner = ?`).run(settlement.state, settlement.state === 'pending' ? settlement.nextAttemptAt : now, settlement.state === 'accepted' ? now : null, settlement.state === 'permanent_failed' ? now : null, failure, now, nodeId, attempt, claimOwner).changes) === 1);
+}
+export function recoverRunningOutcomeDeliveries(now) {
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE node_outcome_deliveries
+     SET state = 'pending', next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL, updated_at = ?
+     WHERE state = 'running'`).run(now, now).changes));
+}
+/** Disarming is deliberately limited to registrations that have not started delivery. */
+export function disarmOutcomeDelivery(nodeId) {
+    return withCanvasWrite((db) => Number(db.prepare("DELETE FROM node_outcome_deliveries WHERE node_id = ? AND state = 'armed'").run(nodeId).changes) === 1);
+}
+/** A canonical final is the one allowed outcome supersede: discard any old claim and retry state. */
+export function resetOutcomeDeliveryForSupersede(nodeId, documentJson, now) {
+    return withCanvasWrite((db) => Number(db.prepare(`UPDATE node_outcome_deliveries
+     SET state = 'pending', attempt = 0, document_json = ?, next_attempt_at = ?,
+         claimed_at = NULL, claim_owner = NULL, accepted_at = NULL, permanent_failed_at = NULL,
+         last_failure_json = NULL, updated_at = ?
+     WHERE node_id = ?`).run(documentJson, now, now, nodeId).changes) === 1);
+}

package/dist/core/canvas/pid.d.ts

@@ -4,6 +4,13 @@
  *  zombies and processes reaped between the two probes. Only an unavailable
  *  `ps` probe fails open to alive. A null/undefined pid reads dead. */
 export declare function isPidAlive(pid: number | null | undefined): boolean;
+/** Existence-only liveness for READ-ONLY display projections: the signal-0
+ *  probe alone, no `ps`. A zombie reads alive here, which a dashboard column
+ *  tolerates and which no lifecycle decision may rely on — revive, teardown,
+ *  and every other authority stays on `isPidAlive`. Exists because the
+ *  dashboard snapshot runs this per live row per request; a `ps` spawn each
+ *  time was a third of daemon CPU on a large canvas. */
+export declare function isPidPresent(pid: number | null | undefined): boolean;
 /** THE single precision-aware identity compare, used EVERYWHERE two
  *  `composeIdentity` fingerprints are compared (this module's own
  *  `recordedPidLiveness`, `captureTeardownSnapshot`'s reuse check, and

package/dist/core/canvas/pid.js

@@ -46,6 +46,23 @@ export function isPidAlive(pid) {
     const state = psProcessState(pid);
     return state !== 'zombie' && state !== 'gone';
 }
+/** Existence-only liveness for READ-ONLY display projections: the signal-0
+ *  probe alone, no `ps`. A zombie reads alive here, which a dashboard column
+ *  tolerates and which no lifecycle decision may rely on — revive, teardown,
+ *  and every other authority stays on `isPidAlive`. Exists because the
+ *  dashboard snapshot runs this per live row per request; a `ps` spawn each
+ *  time was a third of daemon CPU on a large canvas. */
+export function isPidPresent(pid) {
+    if (pid == null)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
 /** Matches the kernel `boot_id` UUID shape (`/proc/sys/kernel/random/boot_id`),
  *  used to tell a NEW-format identity base (a per-boot UUID) apart from a
  *  LEGACY one (a `ps lstart` wall-clock timestamp). A boot_id is a lowercase

package/dist/core/canvas/render-source.js

@@ -19,7 +19,7 @@ import { fullName } from './labels.js';
 import { jobDir, contextDir, reportsDir } from './paths.js';
 import { readNodeRecap } from './node-recap.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { isPidAlive } from './pid.js';
+import { isPidAlive, isPidPresent } from './pid.js';
 import { isFrozenRow, resolveNodeVisual, faultSummary } from './status-glyph.js';
 import { readFault } from '../runtime/fault.js';
 import { parseCard } from '../../shared/generated-context.js';
@@ -434,7 +434,7 @@ function assistantContentIsSubstantive(content) {
  *  (an active node is usually dormant between turns). Read directly off disk
  *  (mirrors telemetry) to avoid inverting the canvas→runtime dependency. */
 export function isStreaming(nodeId, piPid) {
-    if (!isPidAlive(piPid))
+    if (!isPidPresent(piPid))
         return false;
     try {
         return existsSync(join(jobDir(nodeId), 'busy'));

package/dist/core/canvas/types.d.ts

@@ -18,7 +18,34 @@ export type Lifecycle = 'terminal' | 'resident';
 export type Mode = 'base' | 'orchestrator';
 /** Why a node last stopped — drives the daemon's reap-vs-revive decision. */
 export type ExitIntent = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
-export type TerminalReason = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded';
+export type TerminalReason = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined';
+export type NodeOutcomeKind = 'result' | 'failure';
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export declare const OUTCOME_PAYLOAD_MAX_BYTES: number;
+export interface NodeOutcomeDetailV1 {
+    schema: 'crtr.node-outcome-detail/v1';
+    message?: string;
+    fault_kind?: import('../fault-classifier.js').FaultKind;
+    error_class?: import('../events/types.js').ErrorClassCode;
+    retry?: {
+        attempt: number;
+        max: number;
+    };
+    respawn_failures?: number;
+    deadline?: {
+        deadline_at: string;
+        elapsed_ms: number;
+    };
+    /** Present only for reason `declined`: what the node gave `crtr push result --decline`. */
+    declined?: DeclinedResult;
+    truncated?: true;
+}
+/** A declined structured result. `code` is opaque here — the requester validates it. */
+export interface DeclinedResult {
+    reason: string;
+    code: string;
+    retryable: boolean;
+}
 /** The two structural edges. `subscribes_to` is the load-bearing spine (flow,
  *  org chart, views, completion routing). `spawned_by` is audit only. */
 export type EdgeType = 'subscribes_to' | 'spawned_by';
@@ -266,6 +293,14 @@ export interface NodeRuntime {
     final_report?: string | null;
     /** ISO timestamp carried by the committed canonical final report, or null. */
     finalized_at?: string | null;
+    /** Durable terminal outcome. `outcome_at` is its write-once latch. */
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    /** Absolute wall-clock spawn deadline, or null when unbounded. */
+    deadline_at?: string | null;
     /** OS pid of the live broker process, recorded on boot (stophook session_start).
      *  The daemon's authoritative liveness signal — every node is a detached broker,
      *  so `isPidAlive(pi_pid)` is the sole liveness check. Cleared to null by
@@ -342,6 +377,12 @@ export interface NodeRow {
     terminal_reason?: TerminalReason | null;
     final_report?: string | null;
     finalized_at?: string | null;
+    outcome_kind?: NodeOutcomeKind | null;
+    outcome_reason?: TerminalReason | null;
+    outcome_at?: string | null;
+    outcome_revision?: number;
+    outcome_detail_json?: string | null;
+    deadline_at?: string | null;
     pi_pid: number | null;
     /** See `NodeRuntime.pi_pid_identity`. */
     pi_pid_identity: string | null;

package/dist/core/canvas/types.js

@@ -5,4 +5,5 @@
 // `meta.json` is the source of truth for its own row; the db is a queryable
 // index over those metas, plus the authoritative store for the mutable
 // `subscribes_to` edges (which no single meta owns).
-export {};
+/** Maximum serialized opaque action payload; enforced at registration in Phase 5. */
+export const OUTCOME_PAYLOAD_MAX_BYTES = 64 * 1024;

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
+import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig, ProviderOptionsConfig } from '../types.js';
 import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
@@ -111,6 +111,9 @@ export declare function readRawScopeConfig(scope: Scope): Partial<ScopeConfig> |
 export interface MergedLaunchConfig {
     kinds: Record<string, KindConfig>;
     modelLadders: ModelLaddersConfig;
+    /** Per-provider behavior options keyed by runtime provider id, merged
+     *  per provider across scopes (project stack > profile > user). */
+    providerOptions: Record<string, ProviderOptionsConfig>;
     /** Complete declared routes. Every route here has all four strengths. */
     modelRoutes?: Record<string, ModelRouteConfig>;
     /** Read-only compatibility view for sparse routes written before complete

package/dist/core/config.js

@@ -343,6 +343,25 @@ function mergeSpawnEnv(raw, base = []) {
     }
     return { allow: [...new Set([...base, ...extra])] };
 }
+/** Per-provider options, merged SHALLOWLY per provider id so a nearer scope
+ *  that sets one option does not erase a sibling option from a farther scope. */
+function mergeProviderOptions(raw, base = {}) {
+    const merged = {};
+    for (const [providerId, options] of Object.entries(base))
+        merged[providerId] = { ...options };
+    if (raw !== null && typeof raw === 'object') {
+        for (const [providerId, options] of Object.entries(raw)) {
+            if (options === null || typeof options !== 'object')
+                continue;
+            const next = { ...merged[providerId] };
+            const fastMode = options.fastMode;
+            if (typeof fastMode === 'boolean')
+                next.fastMode = fastMode;
+            merged[providerId] = next;
+        }
+    }
+    return merged;
+}
 /** The one bare-command-name rule, shared by the read path (`normalizeBin`)
  *  and the strict install gate (`invalidPluginBinReasons`): a name a shell can
  *  invoke verbatim and a filesystem can hold as a single symlink entry — no
@@ -761,6 +780,7 @@ function mergeConfig(partial) {
     const keybindings = normalizeKeybindings(partial.keybindings);
     const tmux_passthrough = normalizeTmuxPassthrough(partial.tmux_passthrough);
     const modelLadders = mergeModelLadders(partial.modelLadders);
+    const providerOptions = mergeProviderOptions(partial.providerOptions, defaults.providerOptions);
     const routes = resolveModelRoutes(mergeModelRoutePatches(partial.modelRoutes));
     const modelRoutes = routes.complete;
     const modelRouting = mergeModelRouting(partial.modelRouting, undefined);
@@ -769,7 +789,7 @@ function mergeConfig(partial) {
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
     const bin = normalizeBin(partial.bin);
     const humanActions = normalizeHumanActions(partial.humanActions);
-    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, providerOptions, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer
@@ -858,12 +878,14 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
     // (ladders/routes/spawnEnv) have no plugin channel.
     let kinds = mergeKinds(userRaw?.kinds, layerPluginKinds('user', scopeRoot('user'), defaults.kinds));
     let modelLadders = mergeModelLadders(userRaw?.modelLadders, defaults.modelLadders);
+    let providerOptions = mergeProviderOptions(userRaw?.providerOptions, defaults.providerOptions);
     let modelRoutePatches = mergeModelRoutePatches(userRaw?.modelRoutes);
     let modelRouting = mergeModelRouting(userRaw?.modelRouting, undefined);
     let spawnEnv = mergeSpawnEnv(userRaw?.spawnEnv, defaults.spawnEnv?.allow);
     if (profileRaw !== null) {
         kinds = mergeKinds(profileRaw.kinds, kinds);
         modelLadders = mergeModelLadders(profileRaw.modelLadders, modelLadders);
+        providerOptions = mergeProviderOptions(profileRaw.providerOptions, providerOptions);
         modelRoutePatches = mergeModelRoutePatches(profileRaw.modelRoutes, modelRoutePatches);
         modelRouting = mergeModelRouting(profileRaw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(profileRaw.spawnEnv, spawnEnv.allow);
@@ -873,6 +895,7 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
         if (raw === null)
             continue;
         modelLadders = mergeModelLadders(raw.modelLadders, modelLadders);
+        providerOptions = mergeProviderOptions(raw.providerOptions, providerOptions);
         modelRoutePatches = mergeModelRoutePatches(raw.modelRoutes, modelRoutePatches);
         modelRouting = mergeModelRouting(raw.modelRouting, modelRouting);
         spawnEnv = mergeSpawnEnv(raw.spawnEnv, spawnEnv.allow);
@@ -881,6 +904,7 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
     return {
         kinds,
         modelLadders,
+        providerOptions,
         ...(Object.keys(routes.complete).length > 0 ? { modelRoutes: routes.complete } : {}),
         ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}),
         ...(modelRouting !== undefined ? { modelRouting } : {}),

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

@@ -9,6 +9,14 @@ export interface PushOpts {
     from?: string;
     /** Attribution snapshotted by the human-ticket settlement paths; absent means an ordinary report. */
     disposition?: InboxDisposition;
+    /** Final only. The outcome the canonical final records; absent means `result`/`finalized`. */
+    outcome?: FinalOutcome;
+}
+/** A declined structured result: the node finishes, but its latch records a failure. */
+export interface FinalOutcome {
+    kind: 'failure';
+    reason: 'declined';
+    detailJson: string | null;
 }
 export interface PushResult {
     reportPath: string;

package/dist/core/feed/feed.js

@@ -2,7 +2,7 @@
 import { existsSync, linkSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { openDb, reportsDir, subscribersOf, cancelCronsOnWake, getNode } from '../canvas/index.js';
+import { openDb, reportsDir, subscribersOf, cancelCronsOnWake, composeOutcomeDeliveryDocument, getNode, readOutcomeDelivery, resetOutcomeDeliveryForSupersede } from '../canvas/index.js';
 import { appendInbox } from './inbox.js';
 import { appendPassive } from './passive.js';
 import { operationIdContext } from '../events/operation-id.js';
@@ -77,7 +77,7 @@ function deliver(subscribers, from, fromName, kind, requestedTier, reportRef, bo
     return { deliveredTo, failedTo };
 }
 /** Claim the one canonical final while holding SQLite's write lock. */
-function commitCanonicalFinal(nodeId, staged) {
+function commitCanonicalFinal(nodeId, staged, outcome) {
     const db = openDb();
     let installed = false;
     db.exec('BEGIN IMMEDIATE');
@@ -92,9 +92,28 @@ function commitCanonicalFinal(nodeId, staged) {
         if (row.status !== 'active' && row.status !== 'idle' && row.status !== 'done')
             throw new FinalizationError('finalization_forbidden');
         const subscribers = db.prepare(`SELECT from_id AS node_id, active, created FROM edges WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`).all(nodeId).map((row) => ({ node_id: row['node_id'], active: row['active'] === 1, created: row['created'] }));
+        const delivery = readOutcomeDelivery(nodeId);
+        const node = getNode(nodeId);
+        const recordsOutcome = node?.kind !== 'human';
+        const revision = (node?.outcome_revision ?? 0) + 1;
+        const outcomeKind = outcome?.kind ?? 'result';
+        const outcomeReason = outcome?.reason ?? 'finalized';
+        const outcomeDetailJson = outcome?.detailJson ?? null;
+        const documentJson = !recordsOutcome || delivery === null || node === null ? null : composeOutcomeDeliveryDocument({
+            nodeId,
+            outcome: { kind: outcomeKind, reason: outcomeReason, at: staged.ts, revision, detailJson: outcomeDetailJson },
+            action: { name: delivery.actionName, payload: delivery.payload },
+            finalReport: staged.basename,
+        });
         install(staged);
         installed = true;
-        db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = 'finalized', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(staged.basename, staged.ts, nodeId);
+        if (recordsOutcome) {
+            db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = ?, final_report = ?, finalized_at = ?, outcome_kind = ?, outcome_reason = ?, outcome_at = ?, outcome_revision = outcome_revision + 1, outcome_detail_json = ? WHERE node_id = ? AND final_report IS NULL").run(outcomeReason, staged.basename, staged.ts, outcomeKind, outcomeReason, staged.ts, outcomeDetailJson, nodeId);
+            resetOutcomeDeliveryForSupersede(nodeId, documentJson, Date.now());
+        }
+        else {
+            db.prepare("UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = 'finalized', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(staged.basename, staged.ts, nodeId);
+        }
         db.exec('COMMIT');
         return { subscribers };
     }
@@ -113,11 +132,13 @@ async function pushWithContext(nodeId, opts) {
         throw new Error(`push: empty nodeId (kind=${opts.kind}) — a report must belong to a node`);
     if (opts.kind === 'final' && opts.deliveryTier !== undefined)
         throw new Error('push final does not accept a delivery tier');
+    if (opts.kind !== 'final' && opts.outcome !== undefined)
+        throw new Error('push outcome is final-only');
     const staged = stageReport(nodeId, opts.kind, opts.body);
     const from = opts.from ?? nodeId;
     const fromName = getNode(from)?.name;
     if (opts.kind === 'final') {
-        const { subscribers } = commitCanonicalFinal(nodeId, staged);
+        const { subscribers } = commitCanonicalFinal(nodeId, staged, opts.outcome);
         // The finalization latch ends every wait this node was holding. It flips the
         // row to done DIRECTLY (not through lifecycle's `finish` event), so the
         // deadline cleanup must ride here too: an armed deadline outliving the final

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

@@ -87,6 +87,11 @@ export declare function writeCursor(nodeId: string, entryId: string): void;
  *  (do not park, do not shut down, do not resume quietly), so report it and
  *  return that. */
 export declare function hasUnseenWakeMail(nodeId: string): boolean;
+/** Whether wake-capable mail arrived at or after a parking turn began. Unlike
+ * `hasUnseenWakeMail`, this deliberately includes mail the main engine already
+ * consumed: a shadow completion must not undo activity that occurred while it
+ * ran. A failed scan conservatively keeps the node live. */
+export declare function hasWakeMailSince(nodeId: string, sinceMs: number): boolean;
 /** Clip a body to a bounded preview, reporting whether anything was dropped. */
 export declare function clipBody(body: string): {
     text: string;

package/dist/core/feed/inbox.js

@@ -315,6 +315,19 @@ export function hasUnseenWakeMail(nodeId) {
         return true;
     }
 }
+/** Whether wake-capable mail arrived at or after a parking turn began. Unlike
+ * `hasUnseenWakeMail`, this deliberately includes mail the main engine already
+ * consumed: a shadow completion must not undo activity that occurred while it
+ * ran. A failed scan conservatively keeps the node live. */
+export function hasWakeMailSince(nodeId, sinceMs) {
+    try {
+        return readPhysicalInbox(nodeId).some((entry) => entry.tier !== 'deferred' && Date.parse(entry.ts) >= sinceMs);
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'inbox.wake_scan.failed', node_id: nodeId, error });
+        return true;
+    }
+}
 // Coalesce
 /** Bounds for inlining a message body's preview in the digest. */
 const BODY_MAX_LINES = 12;

package/dist/core/keybindings/catalog.d.ts

@@ -1,6 +1,6 @@
 import type { BindingDefinition, SafetyRequirement } from './types.js';
 import type { AttachBindingId, AttachMenuBindingId } from './attach-control.js';
-type TmuxMenuAction = 'open' | 'attach' | 'show' | 'view-settings' | 'fold-tools' | 'metadata' | 'promote' | 'demote-mode' | 'resume' | 'fork' | 'demote' | 'make-resident' | 'detach' | 'close-subtree' | 'background-bash' | 'file-review' | 'pin' | 'reload-viewer' | 'recap' | 'context' | 'context-admin' | 'providers' | 'plugins' | 'graph' | 'focus-manager' | 'copy-id' | 'issues';
+type TmuxMenuAction = 'open' | 'attach' | 'show' | 'view-settings' | 'provider-options' | 'fold-tools' | 'metadata' | 'promote' | 'demote-mode' | 'resume' | 'fork' | 'demote' | 'make-resident' | 'detach' | 'close-subtree' | 'background-bash' | 'file-review' | 'pin' | 'reload-viewer' | 'recap' | 'context' | 'context-admin' | 'providers' | 'plugins' | 'graph' | 'focus-manager' | 'copy-id' | 'issues';
 type TmuxMenuEntryAction = Exclude<TmuxMenuAction, 'open' | 'attach'> | `issue.${'idea' | 'bug'}`;
 type GraphAction = 'down' | 'up' | 'first' | 'last' | 'collapse-or-manager' | 'expand-or-child' | 'focus' | 'revive' | 'focus-manager' | 'close-subtree' | 'dismiss';
 type BrowseAction = 'quit' | 'down' | 'up' | 'first' | 'last' | 'expand-or-child' | 'collapse-or-parent' | 'toggle-fold' | 'tab-next' | 'tab-previous' | `tab.${1 | 2 | 3 | 4 | 5}` | 'close-subtree' | 'confirm-close' | 'sort' | 'scope' | 'profile' | 'residents' | 'preview' | 'report' | 'pin' | 'search' | 'revive-now' | 'focus' | 'focus-background' | 'yank-id';

package/dist/core/keybindings/catalog.js

@@ -55,6 +55,9 @@ export const BINDING_CATALOG = Object.freeze([
     ...menuEntry('metadata', 'Show metadata', 'Show the focused node’s metadata dossier.', ['m'], ['tmux.menu.show']),
     ...menuEntry('context', 'Browse context', 'Browse the focused node context.', ['c'], ['tmux.menu.show']),
     ...menuEntry('providers', 'Open settings', 'Open the crouter settings panel.', [','], ['tmux.menu']),
+    // Next to the settings comma: the same page, opened on its provider-options
+    // destination.
+    ...menuEntry('provider-options', 'Provider options', 'Open provider options — how an authenticated provider serves your turns, including Codex fast mode.', ['.'], ['tmux.menu']),
     // j and k steer the menu cursor, so no selector may claim either.
     ...menuEntry('plugins', 'Browse plugins', 'Open the crouter plugin browser.', ['l'], ['tmux.menu']),
     // Lowercase c opens the create submenu, so the context surface takes the

package/dist/core/profiles/manifest.d.ts

@@ -114,7 +114,9 @@ export declare function isProfilePaused(profileId: string | null | undefined): b
 export declare function assertProfileEntryActive(entry: ProfileEntry): void;
 export declare function assertProfileActive(profileId: string | null | undefined): ProfileEntry | null;
 export declare function pauseProfile(profileId: string): ProfileEntry;
-export declare function resumeProfile(profileId: string): ProfileEntry;
+export declare function resumeProfile(profileId: string): ProfileEntry & {
+    pausedAt: string | null;
+};
 export declare function setProfileDefaultKind(profileId: string, defaultKind: string): ProfileEntry;
 /** Merge `set` entries over the stored map and drop `unset` keys; the
  *  `metadata` field is omitted entirely when the result is empty. */

package/dist/core/profiles/manifest.js

@@ -592,7 +592,12 @@ export function pauseProfile(profileId) {
     return mutateManifest(profileId, (m) => ({ ...m, paused_at: m.paused_at ?? nowIso() }));
 }
 export function resumeProfile(profileId) {
-    return mutateManifest(profileId, (m) => ({ ...m, paused_at: null }));
+    let pausedAt = null;
+    const entry = mutateManifest(profileId, (m) => {
+        pausedAt = m.paused_at;
+        return { ...m, paused_at: null };
+    });
+    return { ...entry, pausedAt };
 }
 export function setProfileDefaultKind(profileId, defaultKind) {
     return mutateManifest(profileId, (m) => ({ ...m, default_kind: defaultKind }));

package/dist/core/runtime/broker/daemon-ops.d.ts

@@ -1,8 +1,10 @@
-import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from '../../../api/dto/broker-ops.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerParkActivityResultDTO, BrokerParkCompleteRequest, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from '../../../api/dto/broker-ops.js';
 import type { RelaunchRootResultDTO } from '../../../api/dto/lifecycle.js';
 import type { PushReportRequest } from '../../../api/dto/reports.js';
 export declare function bindBrokerSession(nodeId: string, request: BrokerSessionBoundRequest): Promise<BrokerSessionBoundResultDTO>;
 export declare function settleBroker(nodeId: string, request: BrokerSettleRequest): Promise<BrokerSettleDirective>;
+export declare function completeBrokerPark(nodeId: string, request: BrokerParkCompleteRequest): Promise<BrokerSettleDirective>;
+export declare function recordBrokerParkActivity(nodeId: string): Promise<BrokerParkActivityResultDTO>;
 export declare function advanceBrokerInboxCursor(nodeId: string, request: BrokerInboxCursorRequest): Promise<BrokerInboxCursorDirective>;
 /** Fixed canvas projection for broker extension rendering. It deliberately
  * exposes no generic node/database facade. */