@north-light/crouter 0.3.233 → 0.3.234

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

@@ -6,12 +6,15 @@
 // map.ts carries no projector — it is frozen under concurrency).
 //
 // `{id}` is the target node.
+import { envProfileId } from '../../../shared/env.js';
 import { readdirSync } from 'node:fs';
 import { basename } from 'node:path';
-import { appendSituationalContext, closeNode, getNode, listNodes, nowIso, reviveNode, } from '../../../index.js';
-import { formatSituationalProse } from '../../../core/runtime/situational-context.js';
+import { appendSituationalContext, formatSituationalProse } from '../../../core/runtime/situational-context.js';
+import { closeNode } from '../../../core/runtime/close.js';
+import { reviveNode } from '../../../core/runtime/revive.js';
+import { nowIso } from '../../../core/fs-utils.js';
 import { assertLaunchModelRegistered, forkNode, spawnChild } from '../../../core/runtime/spawn.js';
-import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
+import { childrenOf, getNode, listNodes, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
 import { subtreeIds } from '../../../core/canvas/nav-model.js';
 import { ticketCountsForNodes } from '../../../core/canvas/attention.js';
 import { contextDir, reportsDir } from '../../../core/canvas/paths.js';
@@ -40,9 +43,7 @@ import { cronWakeOrigin } from '../../../core/runtime/bearings.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { toCloseResultDTO, toNodeDetailDTO, toNodeSummaryDTO, toReviveResultDTO } from '../map.js';
 import { ApiError } from '../../../api/index.js';
-// ---------------------------------------------------------------------------
 // Shared helpers
-// ---------------------------------------------------------------------------
 function requireMeta(id) {
     const meta = getNode(id);
     if (meta === null)
@@ -76,9 +77,7 @@ function countFiles(id) {
     }
     return n;
 }
-// ---------------------------------------------------------------------------
 // POST /v1/nodes — create immediately (201)
-// ---------------------------------------------------------------------------
 /** Validate + narrow the create body (spec §6.2). */
 function parseCreateBody(body) {
     if (typeof body !== 'object' || body === null) {
@@ -192,7 +191,7 @@ export async function handleCreate(ctx, deps = {}) {
     // buildRecipe already defaults `prompt` to ''. The CLI keeps every no_kickoff
     // guards (root-only / no-prompt / no-orchestrator).
     const parent = req.parent ?? undefined;
-    // --- Immediate spawn (201). A managed child needs a parent; a root does not. ---
+    // Immediate spawn (201). A managed child needs a parent; a root does not.
     if (parent == null && req.root !== true) {
         throw usage('a node create requires a parent (or root: true for an independent root)');
     }
@@ -233,9 +232,7 @@ export async function handleCreate(ctx, deps = {}) {
         writeOutputSchema(result.node.node_id, 'terminal', schema);
     return { status: 201, body: detailOf(result.node.node_id) };
 }
-// ---------------------------------------------------------------------------
 // GET /v1/nodes — list (filters) ; GET /v1/nodes/{id} — detail
-// ---------------------------------------------------------------------------
 function singleQueryValue(ctx, name) {
     const values = ctx.query.getAll(name);
     if (values.length > 1)
@@ -343,9 +340,7 @@ function handleDetail(ctx) {
     requireMeta(id);
     return { status: 200, body: detailOf(id) };
 }
-// ---------------------------------------------------------------------------
 // Read endpoints (snapshot / transcript / context / artifacts)
-// ---------------------------------------------------------------------------
 async function handleSnapshot(ctx) {
     const id = ctx.params['id'];
     requireMeta(id);
@@ -458,9 +453,7 @@ function handleArtifacts(ctx) {
     const body = { node_id: id, artifacts };
     return { status: 200, body };
 }
-// ---------------------------------------------------------------------------
 // Lifecycle verbs
-// ---------------------------------------------------------------------------
 async function handleFork(ctx) {
     const id = ctx.params['id'];
     requireMeta(id);
@@ -601,9 +594,7 @@ function handleReviveAll() {
     const body = { revived: [...result.revived], failed: [...result.failed] };
     return { status: 200, body };
 }
-// ---------------------------------------------------------------------------
 // PATCH /v1/nodes/{id}/config — model / situational-context (spec §6.2)
-// ---------------------------------------------------------------------------
 export async function handleConfig(ctx, deps = {}) {
     const id = ctx.params['id'];
     let meta = requireMeta(id);
@@ -646,7 +637,7 @@ export async function handleConfig(ctx, deps = {}) {
         // Re-read so the launch-spec rebuild below sees the fresh model pin.
         meta = requireMeta(id);
     }
-    // --- kind / mode / lifecycle: reshape via canonical primitive (CLI parity). ---
+    // kind / mode / lifecycle: reshape via canonical primitive (CLI parity).
     if (patch.kind !== undefined || patch.mode !== undefined || patch.lifecycle !== undefined) {
         if (patch.kind !== undefined)
             await assertKindServer(patch.kind);
@@ -671,7 +662,7 @@ export async function handleConfig(ctx, deps = {}) {
             ...(patch.lifecycle !== undefined ? { lifecycle: newLifecycle } : {}),
         }, beforePersist);
     }
-    // --- name: rename the row and, when it has a live viewer window, that window. ---
+    // name: rename the row and, when it has a live viewer window, that window.
     if (patch.name !== undefined) {
         meta = updateNode(id, { name: patch.name });
         if (meta.window)
@@ -685,15 +676,13 @@ export async function handleConfig(ctx, deps = {}) {
  * ambient configuration; prospective reads validate their resolved target. The
  * read is subprocess-isolated — crtrd must never resolve config on its own loop. */
 async function assertKindServer(kind) {
-    const kinds = Object.keys((await readMergedLaunchConfigAsync(process.cwd(), process.env['CRTR_PROFILE_ID'] || null)).kinds);
+    const kinds = Object.keys((await readMergedLaunchConfigAsync(process.cwd(), envProfileId() || null)).kinds);
     if (!kinds.includes(kind)) {
         throw usage(`unknown kind: ${kind}`, { received: kind, next: `Valid kinds: ${kinds.sort().join(', ')}.` });
     }
 }
-// ---------------------------------------------------------------------------
 // Route table (revive-all registered before `:id` collisions are impossible —
 // different methods — but ordered defensively).
-// ---------------------------------------------------------------------------
 export const nodeRoutes = [
     { method: 'POST', pattern: '/v1/nodes', handler: handleCreate },
     { method: 'GET', pattern: '/v1/nodes', handler: handleList },

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

@@ -6,7 +6,7 @@
 // `{id}` is the REPORTING node (client-side = CRTR_NODE_ID).
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode } from '../../../index.js';
+import { getNode } from '../../../core/canvas/canvas.js';
 import { push, FinalizationError } from '../../../core/feed/feed.js';
 import { autoDropCleanManagedWorktree, hasOpenManagedWorktree, missingWorktreeRecoveryHint } from '../../../core/worktree.js';
 import { reportsDir } from '../../../core/canvas/paths.js';

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

@@ -1,10 +1,8 @@
 // Canonical daemon-owned review lifecycle routes. Handlers validate the full
 // wire request, delegate lifecycle work to review services, and project only
 // committed daemon state.
-import { existsSync } from 'node:fs';
-import { ApiError } from '../../../api/index.js';
 import { isSafeNodeId, reviewResultPath } from '../../../core/canvas/paths.js';
-import { responsePath, reviewPath } from '../../../core/human/convention.js';
+import { responsePath } from '../../../core/human/convention.js';
 import { ticketDir } from '../../../core/human/root.js';
 import { createReview } from '../../../core/review/birth.js';
 import { readAnchorBase, getReviewByBridge, listReviews, requireVisibleReview } from '../../../core/review/store.js';
@@ -168,9 +166,6 @@ function handleByBridge(ctx) {
     const review = getReviewByBridge(bridgeNodeId);
     if (review !== null)
         return { status: 200, body: toReviewResponseDTO(review) };
-    if (existsSync(reviewPath(ticketDir(bridgeNodeId)))) {
-        throw new ApiError(409, 'review_predates_system', 'this review predates canonical review records; cancel it and re-file the review', { bridge_node_id: bridgeNodeId });
-    }
     throw new ReviewOperationError('unknown_review', 'review was not found', { received: bridgeNodeId });
 }
 async function handleSubmit(ctx) {

package/dist/daemon/api/map.js

@@ -20,9 +20,7 @@ import { ExitCode } from '../../types.js';
 import { sinkDisplay } from '../cron-sink.js';
 import { responsePath } from '../../core/human/convention.js';
 import { ticketDir } from '../../core/human/root.js';
-// ---------------------------------------------------------------------------
 // Node projections
-// ---------------------------------------------------------------------------
 /** Project the queryable row (what `listNodes` yields) into a summary DTO. */
 export function toNodeSummaryDTO(row) {
     return {
@@ -144,9 +142,7 @@ export function toNodeDetailDTO(meta, edges) {
         dto.worktree = toNodeWorktreeDTO(meta.managed_worktree);
     return dto;
 }
-// ---------------------------------------------------------------------------
 // Action-result projections
-// ---------------------------------------------------------------------------
 /** Project a `reviveNode` result. `revived` is true only when a fresh launch
  *  actually happened — the double-revive no-op (already-alive) returns without a
  *  `launch` handle, so its absence is the "nothing relaunched" signal. `status`
@@ -398,9 +394,7 @@ export function toFeedbackResultDTO(result) {
 }
 const _exitIntentParity = true;
 void _exitIntentParity;
-// ---------------------------------------------------------------------------
 // Error → HTTP status mapping (spec §8)
-// ---------------------------------------------------------------------------
 /** The only internal review-error to public HTTP projection. Every internal
  * review failure is listed explicitly so handlers never need to invent a status
  * or public code. */

package/dist/daemon/api/router.js

@@ -102,9 +102,7 @@ export class Router {
         }
     }
 }
-// ---------------------------------------------------------------------------
 // Matching
-// ---------------------------------------------------------------------------
 /** Split a path/pattern into non-empty segments (leading/trailing '/' ignored). */
 function splitPath(p) {
     return p.split('/').filter((s) => s.length > 0);
@@ -127,9 +125,7 @@ function matchSegments(pattern, actual) {
     }
     return params;
 }
-// ---------------------------------------------------------------------------
 // Body + response I/O
-// ---------------------------------------------------------------------------
 class BodyTooLargeError extends Error {
 }
 /** Read and JSON-parse the request body. Returns `undefined` for an empty body.

package/dist/daemon/api/server.js

@@ -16,6 +16,7 @@ import { createServer } from 'node:http';
 import { chmodSync, existsSync, unlinkSync } from 'node:fs';
 import { apiSocketPath } from '../../core/canvas/paths.js';
 import { emitEvent } from '../../core/events/emit.js';
+import { envCrtrdTcp } from '../../shared/env.js';
 import { Router } from './router.js';
 import { handleAttachUpgrade } from './bridge.js';
 import { attachRoutes } from './handlers/attach.js';
@@ -204,10 +205,8 @@ export function createApiServer(opts = {}) {
             emitEvent({ event: 'api.server.failed', level: 'error', error: err });
         });
     };
-    // -------------------------------------------------------------------------
     // Unix socket — ALWAYS bound. Unlink any stale socket first (mirror
     // broker.ts's listener setup), listen, then chmod 0600 once the file exists.
-    // -------------------------------------------------------------------------
     const socketServer = createServer(onRequest);
     socketServer.on('upgrade', onUpgrade);
     bindErrorHandler(socketServer);
@@ -230,11 +229,9 @@ export function createApiServer(opts = {}) {
             });
         }
     });
-    // -------------------------------------------------------------------------
     // TCP — opt-in only. A SECOND http.Server sharing the same handlers.
-    // -------------------------------------------------------------------------
     let tcpServer;
-    const tcpSpec = opts.tcp ?? process.env['CRTRD_TCP'];
+    const tcpSpec = opts.tcp ?? envCrtrdTcp();
     if (tcpSpec !== undefined && tcpSpec !== '') {
         const parsed = parseTcp(tcpSpec);
         if (parsed === null) {

package/dist/daemon/boot-migrations.d.ts

@@ -0,0 +1,14 @@
+export interface BootMigrationResult {
+    changed: boolean;
+    summary: Record<string, unknown>;
+}
+export interface BootMigration {
+    readonly id: string;
+    readonly description: string;
+    /** Runs unconditionally at every daemon boot. Must be safe to re-run every
+     *  time (idempotent via its own convergence, not a version gate) and must
+     *  isolate its own per-item failures — a thrown error here is NOT caught by
+     *  the boot sequence and would abort daemon startup. */
+    apply(): BootMigrationResult;
+}
+export declare const BOOT_MIGRATIONS: readonly BootMigration[];

package/dist/daemon/boot-migrations.js

@@ -0,0 +1,31 @@
+// The ordered boot-migration list — the THIRD of this repo's three migration
+// homes, and the one for filesystem repairs that must run unconditionally at
+// every daemon boot, before supervision can revive anything. No version gate
+// (there is no single database to hold a `user_version`, and no `crtr sys
+// migrate` invocation to drive it): each entry converges on its own, the same
+// way `migrateLegacyInboxIdentities` already does — a re-run over
+// already-migrated state rewrites nothing.
+//
+// The other two homes:
+//   - `../core/canvas/migrations.ts` — canvas.db's versioned schema chain,
+//     gated by `PRAGMA user_version`, applied once per database inside
+//     `migrate()`.
+//   - `../migrations/registry.ts` — the `STATE_MIGRATIONS` registry for
+//     on-disk memory documents, profile manifests, and the corpus lane,
+//     driven by `crtr sys migrate`.
+//
+// Authoring contract: one entry per boot-time filesystem repair, appended
+// here in order. `crtrd.ts` iterates this list once at boot and emits one
+// `daemon.boot_migration.applied` event per entry that reports a change —
+// add a step here instead of a bespoke call in the boot sequence.
+import { migrateLegacyInboxIdentities } from '../core/feed/inbox-migrate.js';
+export const BOOT_MIGRATIONS = [
+    {
+        id: 'legacy-inbox-identities',
+        description: 'normalize pre-cutover inbox entry/operation ids (UUID-spelled or missing) and cursors (ISO-timestamp boundaries) into canonical 32-lowercase-hex identities the strict inbox reader requires.',
+        apply: () => {
+            const summary = migrateLegacyInboxIdentities();
+            return { changed: summary.nodes > 0 || summary.failures > 0, summary: { ...summary } };
+        },
+    },
+];

package/dist/daemon/cron/armed-context.d.ts

@@ -0,0 +1,21 @@
+import type { Cron } from '../../core/canvas/crons.js';
+/** The cron's profile, re-validated now and returned in canonical id form.
+ *
+ *  A DELETED profile is the spec's root fallback: null. An UNREADABLE one is
+ *  not — the profile is still there, so running as root would execute the
+ *  command under an identity nobody armed, with the profile's own env store and
+ *  purview silently replaced. That throws, and the run fails loudly once
+ *  instead of running wrong on every tick. */
+export declare function resolveLiveProfile(c: Cron): string | null;
+export declare function resolveLiveProfileOrRoot(c: Cron): string | null;
+export declare function resolveLiveProfileName(c: Cron): string | undefined;
+/** A stored context cannot be rebuilt; the run fails rather than running under a context nobody armed. */
+export declare class ArmedContextError extends Error {
+    constructor(message: string);
+}
+export interface ArmedRunContext {
+    profileId: string | null;
+    env: NodeJS.ProcessEnv;
+}
+/** Rebuild the armed context. Corrupt snapshots and unreadable profiles fail rather than silently changing its identity or environment. */
+export declare function buildArmedRunContext(c: Cron, runId: string): ArmedRunContext;

package/dist/daemon/cron/armed-context.js

@@ -0,0 +1,100 @@
+import { envHomeOverride } from '../../shared/env.js';
+import { loadProfileManifest, lookupProfile } from '../../core/profiles/manifest.js';
+import { readProfileEnvVars } from '../../core/profiles/env-store.js';
+import { ADMITTED_HOST_PATH_ENV, buildOperationalEnvBase } from '../../core/runtime/spawn-env.js';
+/** The cron's profile, re-validated now and returned in canonical id form.
+ *
+ *  A DELETED profile is the spec's root fallback: null. An UNREADABLE one is
+ *  not — the profile is still there, so running as root would execute the
+ *  command under an identity nobody armed, with the profile's own env store and
+ *  purview silently replaced. That throws, and the run fails loudly once
+ *  instead of running wrong on every tick. */
+export function resolveLiveProfile(c) {
+    if (c.profile == null)
+        return null;
+    let lookup;
+    try {
+        lookup = lookupProfile(c.profile);
+    }
+    catch {
+        return null; // an ambiguous NAME resolves no better than a deleted profile
+    }
+    if (lookup.kind === 'resolved')
+        return lookup.entry.profileId;
+    if (lookup.kind === 'absent')
+        return null;
+    throw new ArmedContextError(`the armed profile "${c.profile}" is still on this host but its manifest could not be read (${lookup.manifestPath}) — running as root would silently give this cron a different identity, env store, and purview. Repair the manifest, or re-arm the cron under a profile that resolves.`);
+}
+// The escalation node must still report an unreadable manifest, so its own spawn falls back to root.
+export function resolveLiveProfileOrRoot(c) {
+    try {
+        return resolveLiveProfile(c);
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveLiveProfileName(c) {
+    if (c.profile == null)
+        return undefined;
+    try {
+        return loadProfileManifest(c.profile).manifest.name;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A stored context cannot be rebuilt; the run fails rather than running under a context nobody armed. */
+export class ArmedContextError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ArmedContextError';
+    }
+}
+// Invalid snapshots are corruption: dropping `--env` would run under an environment nobody armed, so fail instead.
+function parseArmedEnv(envJson) {
+    if (envJson == null)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(envJson);
+    }
+    catch (err) {
+        throw new ArmedContextError(`the armed env snapshot is not valid JSON (${err.message}) — this cron's stored env_json is corrupt, so the run would silently drop every armed variable. Re-arm the cron with a valid --env.`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new ArmedContextError("the armed env snapshot is not a JSON object — this cron's stored env_json is corrupt. Re-arm the cron with a valid --env.");
+    }
+    const extraEnv = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (typeof v !== 'string') {
+            throw new ArmedContextError(`the armed env snapshot's value for "${k}" is not a string — this cron's stored env_json is corrupt, so the run would silently drop that variable. Re-arm the cron with a valid --env.`);
+        }
+        extraEnv[k] = v;
+    }
+    return extraEnv;
+}
+/** Rebuild the armed context. Corrupt snapshots and unreadable profiles fail rather than silently changing its identity or environment. */
+export function buildArmedRunContext(c, runId) {
+    const extraEnv = parseArmedEnv(c.env_json);
+    const profileId = resolveLiveProfile(c);
+    const operationalEnv = buildOperationalEnvBase({ targetCwd: c.cwd, targetProfileId: profileId });
+    const env = {
+        ...operationalEnv,
+        ...readProfileEnvVars(profileId),
+        ...extraEnv,
+        ...(profileId !== null ? { CRTR_PROFILE_ID: profileId } : {}),
+        CRTR_CRON_ID: c.cron_id,
+        CRTR_CRON_NAME: c.name,
+        CRTR_RUN_ID: runId,
+    };
+    // Preserve the daemon identity: otherwise child `crtr` resolves the default canvas.
+    const canvasHomeOverride = envHomeOverride();
+    if (canvasHomeOverride !== undefined && canvasHomeOverride !== '') {
+        env['CRTR_HOME'] = canvasHomeOverride;
+    }
+    if (c.anchor_node != null)
+        env['CRTR_ANCHOR'] = c.anchor_node;
+    env[ADMITTED_HOST_PATH_ENV] = operationalEnv[ADMITTED_HOST_PATH_ENV];
+    return { profileId, env };
+}

package/dist/daemon/cron/capture.d.ts

@@ -0,0 +1,20 @@
+/** Output head caps for the run log (spec: "capped, e.g. 4KB"). */
+export declare const CRON_OUTPUT_HEAD_BYTES: number;
+/** Bound between the run-timeout SIGTERM and a forced SIGKILL escalation, so
+ *  a signal-trapping command cannot stall teardown's detached drain. */
+export declare const CRON_KILL_GRACE_MS = 2000;
+/** Poll interval while waiting for a SIGTERMed stale-lease run to actually die
+ *  (each probe is a `ps` call, so this is deliberately coarse). */
+export declare const CRON_DEATH_POLL_MS = 250;
+/** sha256 of empty stdout — the change-detection hash a run that produced no
+ *  output carries (a failed spawn, a recovered stale lease). */
+export declare const EMPTY_STDOUT_SHA256: string;
+/** A byte-capped capture of one output stream's head. Bytes are buffered and
+ *  decoded exactly once, at the end — decoding per chunk both mis-measured the
+ *  cap (UTF-16 code units, not bytes) and corrupted any multi-byte sequence
+ *  that straddled a chunk boundary. Truncation is MARKED, never silent: a
+ *  clipped body reads as complete output to whoever receives the delivery. */
+export declare function newHeadCapture(): {
+    take(chunk: Buffer): void;
+    decode(): string;
+};

package/dist/daemon/cron/capture.js

@@ -0,0 +1,45 @@
+// src/daemon/cron/capture.ts — output capture for a cron run's child process,
+// plus the timing/hash constants the capture and kill mechanics share.
+import { createHash } from 'node:crypto';
+/** Output head caps for the run log (spec: "capped, e.g. 4KB"). */
+export const CRON_OUTPUT_HEAD_BYTES = 4 * 1024;
+/** Bound between the run-timeout SIGTERM and a forced SIGKILL escalation, so
+ *  a signal-trapping command cannot stall teardown's detached drain. */
+export const CRON_KILL_GRACE_MS = 2000;
+/** Poll interval while waiting for a SIGTERMed stale-lease run to actually die
+ *  (each probe is a `ps` call, so this is deliberately coarse). */
+export const CRON_DEATH_POLL_MS = 250;
+/** sha256 of empty stdout — the change-detection hash a run that produced no
+ *  output carries (a failed spawn, a recovered stale lease). */
+export const EMPTY_STDOUT_SHA256 = createHash('sha256').update('').digest('hex');
+/** A byte-capped capture of one output stream's head. Bytes are buffered and
+ *  decoded exactly once, at the end — decoding per chunk both mis-measured the
+ *  cap (UTF-16 code units, not bytes) and corrupted any multi-byte sequence
+ *  that straddled a chunk boundary. Truncation is MARKED, never silent: a
+ *  clipped body reads as complete output to whoever receives the delivery. */
+export function newHeadCapture() {
+    const chunks = [];
+    let bytes = 0;
+    let truncated = false;
+    return {
+        take(chunk) {
+            const room = CRON_OUTPUT_HEAD_BYTES - bytes;
+            if (room <= 0) {
+                truncated = true;
+                return;
+            }
+            if (chunk.length > room) {
+                chunks.push(chunk.subarray(0, room));
+                bytes = CRON_OUTPUT_HEAD_BYTES;
+                truncated = true;
+                return;
+            }
+            chunks.push(chunk);
+            bytes += chunk.length;
+        },
+        decode() {
+            const text = Buffer.concat(chunks).toString('utf8');
+            return truncated ? `${text}\n[… output truncated at ${CRON_OUTPUT_HEAD_BYTES} bytes]` : text;
+        },
+    };
+}

package/dist/daemon/cron/disposition.d.ts

@@ -0,0 +1,19 @@
+import { type Cron } from '../../core/canvas/crons.js';
+export interface RunSettleContext {
+    runId: string;
+    startedAtIso: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    runTimeoutS: number;
+    processErrorMessage: string | null;
+    stdoutHead: string;
+    /** Hash the full output: a capped head can hide a change. */
+    stdoutSha256: string;
+    stderrHead: string;
+}
+export interface Disposition {
+    delivered: string;
+    /** A paused row is retained so `cron resume` can re-arm it. */
+    paused: boolean;
+}
+export declare function disposeSettledRun(c: Cron, ctx: RunSettleContext, outOfBand: boolean, selfCanceled?: boolean): Promise<Disposition>;

package/dist/daemon/cron/disposition.js

@@ -0,0 +1,52 @@
+import { getCron, setCronLastOutputHash } from '../../core/canvas/crons.js';
+import { escalateFailure, failureSummary } from './escalation.js';
+import { deliverToSink } from './sinks.js';
+export async function disposeSettledRun(c, ctx, outOfBand, selfCanceled = false) {
+    const prefix = outOfBand ? 'out-of-band: ' : '';
+    // A self-cancel still delivers its already-produced output; an external cancellation does not.
+    const fresh = getCron(c.cron_id);
+    if (fresh === null && !selfCanceled)
+        return { delivered: `${prefix}cron canceled mid-run — nothing delivered`, paused: false };
+    const effective = fresh ?? c;
+    const failed = ctx.timedOut || ctx.processErrorMessage !== null || ctx.exitCode !== 0;
+    // `cron run` compares but never rewrites the scheduled baseline.
+    let changed = true;
+    if (effective.on_output === 'on-change') {
+        changed = effective.last_output_hash !== ctx.stdoutSha256;
+        if (!outOfBand && fresh !== null)
+            setCronLastOutputHash(c.cron_id, ctx.stdoutSha256);
+    }
+    if (failed) {
+        if (effective.on_output === 'silent')
+            return { delivered: `${prefix}silent`, paused: false };
+        if (outOfBand)
+            return { delivered: `out-of-band: ${failureSummary(ctx, null)} — not escalated`, paused: false };
+        return { delivered: await escalateFailure(effective, ctx, null), paused: true };
+    }
+    switch (effective.on_output) {
+        case 'silent':
+            return { delivered: `${prefix}silent`, paused: false };
+        case 'on-failure':
+            return { delivered: `${prefix}ok — nothing to deliver (on-failure)`, paused: false };
+        case 'on-change':
+            if (!changed)
+                return { delivered: `${prefix}unchanged — not delivered (on-change)`, paused: false };
+            return deliverOrEscalate(effective, ctx, outOfBand, prefix);
+        case 'always':
+            return deliverOrEscalate(effective, ctx, outOfBand, prefix);
+    }
+}
+async function deliverOrEscalate(c, ctx, outOfBand, prefix) {
+    if (ctx.stdoutHead.trim() === '') {
+        return { delivered: `${prefix}empty stdout — nothing delivered`, paused: false };
+    }
+    try {
+        return { delivered: `${prefix}${await deliverToSink(c, ctx.stdoutHead)}`, paused: false };
+    }
+    catch (err) {
+        const why = `delivery failed: ${err.message}`;
+        if (outOfBand)
+            return { delivered: `out-of-band: ${why} — not escalated`, paused: false };
+        return { delivered: await escalateFailure(c, ctx, why), paused: true };
+    }
+}

package/dist/daemon/cron/escalation.d.ts

@@ -0,0 +1,12 @@
+import { type Cron } from '../../core/canvas/crons.js';
+import type { RunSettleContext } from './disposition.js';
+export declare function failureSummary(ctx: RunSettleContext, deliveryFailure: string | null): string;
+/** Pause the cron and spawn the escalation node in the cron's originating
+ *  profile (root fallback). Returns the run-log `delivered` string. Never
+ *  throws: an escalation spawn failure is recorded and logged, the pause
+ *  stands (the row must not keep refiring a broken command). */
+export declare function escalateFailure(c: Cron, ctx: RunSettleContext, deliveryFailure: string | null): Promise<string>;
+/** The delivery-failure line an escalated crashed ONE-SHOT carries: its side
+ *  effects may already have landed in full, so a human/agent decides whether to
+ *  redo it rather than the daemon re-firing it. */
+export declare function crashedOneShotSummary(why: string): string;