@north-light/crouter 0.3.233 → 0.3.235

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

@@ -94,6 +94,8 @@ export declare const REVIEW_ERROR_MAP: Readonly<Record<ReviewErrorCode, {
  *     `finalization_forbidden`, or 404 `node_not_found`;
  *   - a `NodeIdConflictError` (a `--node-id`/`node_id` spawn at an id that
  *     already exists) → 409 `node_id_exists`;
+ *   - a `WorktreeError` → its own code at 400 (404 for `unknown_node`), with
+ *     `next` + git `detail` preserved as CrtrError details;
  *   - `reviveNode`'s finalization-latch throw → 409 `already_finalized`;
  *   - an "unknown node" throw (reviveNode / transition / getNode-null handler) →
  *     404 `node_not_found`;
@@ -104,7 +106,7 @@ export declare const REVIEW_ERROR_MAP: Readonly<Record<ReviewErrorCode, {
  *  The recognized plain-`Error` cases match on the throw sites' messages (the
  *  only signal those sites carry); the source sites are named above so a message
  *  change there is caught by the A-11 tests. */
-export declare function errorToStatus(err: unknown): {
+export declare function errorToStatus(thrown: unknown): {
     status: number;
     code: string;
 };
@@ -115,7 +117,7 @@ export declare function errorToStatus(err: unknown): {
  *  `internal error`: it surfaces the bounded cause (`boundedCause`) so a caller
  *  is never left with a causeless internal, while the router logs the full
  *  error (with stack) server-side. */
-export declare function toErrorBody(err: unknown): {
+export declare function toErrorBody(thrown: unknown): {
     status: number;
     body: ErrorBody;
 };

package/dist/daemon/api/map.js

@@ -16,13 +16,12 @@ import { FinalizationError } from '../../core/feed/feed.js';
 import { NodeIdConflictError } from '../../core/runtime/nodes.js';
 import { readContextTokens } from '../../core/canvas/telemetry.js';
 import { CrtrError } from '../../core/errors.js';
+import { WorktreeError } from '../../core/worktree.js';
 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 +143,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 +395,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. */
@@ -436,6 +431,8 @@ export const REVIEW_ERROR_MAP = Object.freeze({
  *     `finalization_forbidden`, or 404 `node_not_found`;
  *   - a `NodeIdConflictError` (a `--node-id`/`node_id` spawn at an id that
  *     already exists) → 409 `node_id_exists`;
+ *   - a `WorktreeError` → its own code at 400 (404 for `unknown_node`), with
+ *     `next` + git `detail` preserved as CrtrError details;
  *   - `reviveNode`'s finalization-latch throw → 409 `already_finalized`;
  *   - an "unknown node" throw (reviveNode / transition / getNode-null handler) →
  *     404 `node_not_found`;
@@ -446,7 +443,8 @@ export const REVIEW_ERROR_MAP = Object.freeze({
  *  The recognized plain-`Error` cases match on the throw sites' messages (the
  *  only signal those sites carry); the source sites are named above so a message
  *  change there is caught by the A-11 tests. */
-export function errorToStatus(err) {
+export function errorToStatus(thrown) {
+    const err = normalizeThrow(thrown);
     // An already-shaped API-style throw (e.g. a re-thrown ApiError) — trust it.
     if (typeof err === 'object' &&
         err !== null &&
@@ -485,6 +483,21 @@ export function errorToStatus(err) {
     }
     return { status: 500, code: 'internal' };
 }
+/** A `WorktreeError` is bad input or a repository-state conflict, never a daemon
+ *  fault, so it is projected onto the `CrtrError` contract: its specific code,
+ *  its `next` remediation, and its git `detail` all survive to the caller
+ *  instead of collapsing into an opaque 500. The details carry the FULL
+ *  `{error, message, next}` payload so `apiErrorToCliError` reconstructs the
+ *  worktree contract verbatim rather than degrading to `invalid_request`. */
+function normalizeThrow(err) {
+    if (!(err instanceof WorktreeError))
+        return err;
+    const exitCode = err.code === 'unknown_node' ? ExitCode.NOT_FOUND : ExitCode.GENERAL;
+    const details = { error: err.code, message: err.message, next: err.next };
+    if (err.detail !== undefined)
+        details['received'] = err.detail;
+    return new CrtrError(err.code, err.message, exitCode, details);
+}
 /** Remove the store row from a terminal-conflict detail before it reaches the wire.
  * Only the approved `ReviewDTO` fields cross this boundary; all other review
  * errors retain their explicitly specified internal detail object. */
@@ -545,7 +558,8 @@ function boundedCause(err) {
  *  `internal error`: it surfaces the bounded cause (`boundedCause`) so a caller
  *  is never left with a causeless internal, while the router logs the full
  *  error (with stack) server-side. */
-export function toErrorBody(err) {
+export function toErrorBody(thrown) {
+    const err = normalizeThrow(thrown);
     const { status, code } = errorToStatus(err);
     if (status >= 500) {
         return { status, body: { error: { code, message: boundedCause(err) } } };

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;

package/dist/daemon/cron/escalation.js

@@ -0,0 +1,124 @@
+// src/daemon/cron/escalation.ts — the cron failure path: pause the row and
+// spawn a terminal node holding everything it needs to deal with the failure.
+// Pausing IS the dedup — a paused row is never due, so nothing refires while
+// the escalation node works.
+import { getNode } from '../../core/canvas/canvas.js';
+import { fullName } from '../../core/canvas/labels.js';
+import { listCronRuns, setCronState } from '../../core/canvas/crons.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { spawnChild } from '../../core/runtime/spawn.js';
+import { cronWakeOrigin } from '../../core/runtime/bearings.js';
+import { cadenceDisplay } from '../../core/wake.js';
+import { resolveLiveProfileOrRoot } from './armed-context.js';
+export function failureSummary(ctx, deliveryFailure) {
+    if (deliveryFailure !== null)
+        return deliveryFailure;
+    if (ctx.timedOut)
+        return `run timed out after ${ctx.runTimeoutS}s (killed; recorded exit -1)`;
+    if (ctx.processErrorMessage !== null)
+        return `run process error: ${ctx.processErrorMessage}`;
+    return `command exited ${ctx.exitCode ?? '(no exit observed)'}`;
+}
+/** The escalation node's kickoff: the cron's identity/config, this failure,
+ *  the run-log ring, the creating-node reference, and a mandate that names its
+ *  actual options (resume after verifying / cancel / ask the human). */
+function buildEscalationKickoff(c, ctx, deliveryFailure) {
+    const creator = c.created_by != null ? getNode(c.created_by) : null;
+    const creatorLine = c.created_by == null
+        ? 'created by: (no creating node recorded)'
+        : creator !== null
+            ? `created by: node ${c.created_by} ("${fullName(creator)}") — still on the canvas; consider telling it what happened`
+            : `created by: node ${c.created_by} (now gone)`;
+    const schedule = c.recur != null ? `every ${cadenceDisplay(c.recur)}` : `one-shot at ${c.fire_at}`;
+    const priorRuns = listCronRuns(c.cron_id)
+        .slice(0, 10)
+        .map((r) => {
+        const exit = r.exit_code === null ? 'no exit' : `exit ${r.exit_code}`;
+        const head = (r.stderr_head ?? r.stdout_head ?? '').split('\n')[0]?.slice(0, 120) ?? '';
+        return `- ${r.started} — ${exit}, ${r.duration_ms}ms — ${r.delivered ?? ''}${head !== '' ? ` — ${head}` : ''}`;
+    });
+    return [
+        `A scheduled cron FAILED and has paused itself. You were spawned to deal with it.`,
+        '',
+        `- cron: "${c.name}" (${c.cron_id})`,
+        `- schedule: ${schedule}${c.tz != null ? ` (tz ${c.tz})` : ''}`,
+        `- context: cwd ${c.cwd}${c.profile != null ? `, profile ${c.profile}` : ''}`,
+        `- ${creatorLine}`,
+        `- this failure: ${failureSummary(ctx, deliveryFailure)}`,
+        '',
+        '## The command',
+        '',
+        '```bash',
+        c.command,
+        '```',
+        '',
+        '## This run',
+        '',
+        `- exit: ${ctx.timedOut ? '-1 (timeout)' : String(ctx.exitCode)}`,
+        `- stdout (head): ${ctx.stdoutHead === '' ? '(empty)' : ''}`,
+        ...(ctx.stdoutHead !== '' ? ['```', ctx.stdoutHead, '```'] : []),
+        `- stderr (head): ${ctx.stderrHead === '' ? '(empty)' : ''}`,
+        ...(ctx.stderrHead !== '' ? ['```', ctx.stderrHead, '```'] : []),
+        '',
+        '## Recent runs (most recent first, this failure not yet recorded)',
+        '',
+        ...(priorRuns.length > 0 ? priorRuns : ['(no prior runs recorded)']),
+        '',
+        '## Your mandate',
+        '',
+        `Diagnose why it failed and decide what to do:`,
+        `- Transient or fixable: fix the environment/command context, verify with \`crtr cron run ${c.cron_id}\` (fires now, out of band, shows you the result), then \`crtr cron resume ${c.cron_id}\` to re-arm it.`,
+        `- Obsolete: \`crtr cron cancel ${c.cron_id}\`.`,
+        `- The user's call (or the fix needs a change you cannot make): \`crtr human send\`.`,
+        '',
+        'The cron stays paused until someone resumes it — nothing refires while you work.',
+    ].join('\n');
+}
+/** 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 async function escalateFailure(c, ctx, deliveryFailure) {
+    setCronState(c.cron_id, 'paused');
+    const creatorAlive = c.created_by != null && getNode(c.created_by) !== null;
+    try {
+        const res = await spawnChild({
+            kind: 'general',
+            cwd: c.cwd,
+            prompt: buildEscalationKickoff(c, ctx, deliveryFailure),
+            // The spec's word is TERMINAL: a node that deals with this failure and
+            // reaps. With the creator gone there is nobody to parent it, but
+            // parentless must not mean resident-and-forefront — see deliverSpawnSink.
+            ...(creatorAlive ? { parent: c.created_by } : { root: true, rootLifecycle: 'terminal' }),
+            readiness: 'launch',
+            profile: resolveLiveProfileOrRoot(c),
+            wakeOrigin: cronWakeOrigin(c, 'node_birth'),
+        });
+        emitEvent({
+            level: 'info',
+            event: 'cron.failure.escalated',
+            fields: { cron_id: c.cron_id, name: c.name, escalation_node: res.node.node_id },
+        });
+        return `failure: cron paused, escalation node ${res.node.node_id} spawned`;
+    }
+    catch (err) {
+        emitEvent({
+            level: 'error',
+            event: 'cron.escalation.spawn_failed',
+            error: err,
+            fields: { cron_id: c.cron_id, name: c.name },
+        });
+        return `failure: cron paused; escalation spawn failed: ${err.message}`;
+    }
+}
+/** 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 function crashedOneShotSummary(why) {
+    return [
+        `${why}.`,
+        'This is a ONE-SHOT, so it has been PAUSED rather than released: its side effects may have completed in full,',
+        'and re-firing would enact them a second time. Determine whether the work actually landed, then either',
+        '`crtr cron run` it to redo it deliberately, or `crtr cron cancel` it.',
+    ].join(' ');
+}

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

@@ -0,0 +1,4 @@
+import { type Cron, type HeldSettle } from '../../core/canvas/crons.js';
+export declare const EXIT_HELD = 75;
+export declare const HELD_DELIVERED = "deferred (exit 75) \u2014 held for poke";
+export declare function decideHeldSettle(c: Cron, startedAtIso: string, finishedAtMs: number): HeldSettle | undefined;

package/dist/daemon/cron/held.js

@@ -0,0 +1,20 @@
+import { getCron } from '../../core/canvas/crons.js';
+// Exit 75 parks an owed occurrence; the daemon honors the gate but does not implement it.
+export const EXIT_HELD = 75;
+export const HELD_DELIVERED = 'deferred (exit 75) — held for poke';
+// A held one-shot without expiry is poke-only; leaving it past due would re-fire every tick.
+const HELD_ONE_SHOT_FAR_FUTURE = '9999-12-31T23:59:59.999Z';
+// Re-read `last_poke_at`: a poke can land while the gate check runs.
+export function decideHeldSettle(c, startedAtIso, finishedAtMs) {
+    const fresh = getCron(c.cron_id);
+    if (fresh === null)
+        return undefined;
+    if (fresh.state === 'active' && fresh.last_poke_at !== null && startedAtIso < fresh.last_poke_at) {
+        // A mid-run poke cannot unpark a lease, so re-due an active row; paused rows must remain parked.
+        return { kind: 'redue', nowIso: new Date(finishedAtMs).toISOString() };
+    }
+    if (c.recur != null) {
+        return { kind: 'park' };
+    }
+    return { kind: 'park', fireAt: fresh.expires_at ?? HELD_ONE_SHOT_FAR_FUTURE };
+}

package/dist/daemon/cron/lease-recovery.d.ts

@@ -0,0 +1,3 @@
+import type { RunDueCronOptions } from './passes.js';
+/** Recover leases from prior daemon instances. Verify launch identity, not pid liveness: a reboot can recycle the pid, and killing its new owner would signal a stranger. */
+export declare function recoverStaleCronLeases(now: number, options?: RunDueCronOptions): void;