@north-light/crouter 0.3.179 → 0.3.181

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

@@ -1,12 +1,86 @@
-// Ticket-inbox listing for the attached terminal viewer.
+// Ticket inbox handlers — crtrd `/v1/human/inbox` (Northlight crouter-inbox
+// v1, inbox-contract.md §A). This public ticket-serving resource enumerates,
+// reads, responds to, and cancels tickets while preserving its product DTOs.
+//
+// Every ticket is addressed on the wire by an opaque, stable id: lowercase
+// SHA-256 hex of `canonicalRoot + "\0" + ticketBasename`. The wire never exposes
+// a ticket directory, review file/output, claim owner/heartbeat, or other host
+// path or process metadata. The daemon's shared ticket finish path owns claims,
+// terminal publication, and bridge delivery.
 import { createHash } from 'node:crypto';
-import { realpathSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { ApiError } from '../../../api/index.js';
+import { readJsonOrNull } from '../../../core/fs-utils.js';
+import { deckPath, reviewPath } from '../../../core/human/convention.js';
+import { parseDeck } from '../../../core/human/deck-schema.js';
 import { ticketsRoot } from '../../../core/human/root.js';
 import { scanInbox } from '../../../core/human/scan.js';
+import { readTicketResult } from '../../../core/human/tickets.js';
+import { getReviewByBridge } from '../../../core/review/store.js';
+import { ReviewOperationError } from '../../../core/review/types.js';
+import { cancelHumanTicket, resolveDeckTicket } from '../../human/finish.js';
+import { cancelReview } from '../../review/finish.js';
 import { filterTerminalReviewTickets } from '../../../core/review/ticket-filter.js';
+const DEFAULT_CANCEL_REASON = 'Canceled from the inbox.';
+const CANCEL_REASON_MAX = 1000;
+const TICKET_ID_PATTERN = /^[a-f0-9]{64}$/;
+// ===========================================================================
+// Opaque ticket id resolution
+// ===========================================================================
+/** Opaque ids hash the canonical derived tickets root and ticket basename. */
 function ticketHash(canonicalRoot, ticketBasename) {
     return createHash('sha256').update(`${canonicalRoot}\0${ticketBasename}`, 'utf8').digest('hex');
 }
+/** Resolve an opaque id against the single tickets root. Includes terminal
+ * tickets so a stale client receives the stable already-resolved response. */
+function resolveTicket(ticketId) {
+    let canonicalRoot;
+    try {
+        canonicalRoot = realpathSync(ticketsRoot());
+    }
+    catch {
+        return null;
+    }
+    let entries;
+    try {
+        entries = readdirSync(canonicalRoot);
+    }
+    catch {
+        return null;
+    }
+    for (const entry of entries) {
+        if (ticketHash(canonicalRoot, entry) !== ticketId)
+            continue;
+        const candidate = resolve(canonicalRoot, entry);
+        let canonicalDir;
+        try {
+            if (!statSync(candidate).isDirectory())
+                continue;
+            canonicalDir = realpathSync(candidate);
+        }
+        catch {
+            continue;
+        }
+        if (resolve(canonicalDir, '..') !== canonicalRoot || basename(canonicalDir) !== entry)
+            continue;
+        if (existsSync(deckPath(canonicalDir)))
+            return { nodeId: entry, dir: canonicalDir, kind: 'deck' };
+        if (existsSync(reviewPath(canonicalDir)))
+            return { nodeId: entry, dir: canonicalDir, kind: 'review' };
+    }
+    return null;
+}
+function requireTicketId(params) {
+    const ticketId = params['ticket_id'];
+    if (ticketId === undefined || !TICKET_ID_PATTERN.test(ticketId)) {
+        throw new ApiError(400, 'invalid_request', 'invalid ticket id');
+    }
+    return ticketId;
+}
+// ===========================================================================
+// Projections — humanloop canonical shapes → wire DTOs
+// ===========================================================================
 function toDeckSourceDTO(source) {
     const dto = {};
     if (source.sessionName !== undefined)
@@ -15,6 +89,44 @@ function toDeckSourceDTO(source) {
         dto.askedBy = source.askedBy;
     if (source.blockedSince !== undefined)
         dto.blockedSince = source.blockedSince;
+    // The originating canvas node id — machine attribution a consumer uses to
+    // relate a ticket to the node that raised it. A node id is opaque canvas
+    // identity, not a host path, so it is safe on this wire.
+    if (source.nodeId !== undefined)
+        dto.nodeId = source.nodeId;
+    return dto;
+}
+function toOptionDTO(option) {
+    const dto = { id: option.id, label: option.label };
+    if (option.description !== undefined)
+        dto.description = option.description;
+    return dto;
+}
+function toInteractionDTO(interaction) {
+    const dto = {
+        id: interaction.id,
+        title: interaction.title,
+        subtitle: interaction.subtitle,
+        options: interaction.options.map(toOptionDTO),
+    };
+    if (interaction.body !== undefined)
+        dto.body = interaction.body;
+    if (interaction.multiSelect !== undefined)
+        dto.multiSelect = interaction.multiSelect;
+    if (interaction.allowFreetext !== undefined)
+        dto.allowFreetext = interaction.allowFreetext;
+    if (interaction.freetextLabel !== undefined)
+        dto.freetextLabel = interaction.freetextLabel;
+    if (interaction.kind !== undefined)
+        dto.kind = interaction.kind;
+    if (interaction.preAnswered !== undefined)
+        dto.preAnswered = interaction.preAnswered;
+    return dto;
+}
+function toDeckDTO(deck) {
+    const dto = { title: deck.title, interactions: deck.interactions.map(toInteractionDTO) };
+    if (deck.source !== undefined)
+        dto.source = toDeckSourceDTO(deck.source);
     return dto;
 }
 function toTicketSummaryDTO(item) {
@@ -43,14 +155,246 @@ function toTicketSummaryDTO(item) {
         dto.interaction_kind = item.interactionKind;
     return dto;
 }
+// ===========================================================================
+// Request-body validation — structural only. Semantic response↔deck
+// validation (option ids, single/multi-select shape, freetext permission,
+// option comments, required notify acknowledgement) belongs to the ticket
+// store via the daemon finish path; a structural violation here is
+// `invalid_request`, a semantic rejection there is `invalid_ticket_response`.
+// ===========================================================================
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNoExtraKeys(obj, allowed) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key))
+            throw new ApiError(400, 'invalid_request', `unexpected field: ${key}`);
+    }
+}
+const RESPONSE_FIELDS = ['id', 'selectedOptionId', 'selectedOptionIds', 'freetext', 'optionComments'];
+function validateInteractionResponse(raw) {
+    if (!isPlainObject(raw))
+        throw new ApiError(400, 'invalid_request', 'each response must be an object');
+    requireNoExtraKeys(raw, RESPONSE_FIELDS);
+    const { id, selectedOptionId, selectedOptionIds, freetext, optionComments } = raw;
+    if (typeof id !== 'string' || id === '') {
+        throw new ApiError(400, 'invalid_request', 'response.id must be a nonempty string');
+    }
+    const response = { id };
+    if (selectedOptionId !== undefined) {
+        if (typeof selectedOptionId !== 'string') {
+            throw new ApiError(400, 'invalid_request', 'response.selectedOptionId must be a string');
+        }
+        response.selectedOptionId = selectedOptionId;
+    }
+    if (selectedOptionIds !== undefined) {
+        if (!Array.isArray(selectedOptionIds) || !selectedOptionIds.every((v) => typeof v === 'string')) {
+            throw new ApiError(400, 'invalid_request', 'response.selectedOptionIds must be a string array');
+        }
+        response.selectedOptionIds = selectedOptionIds;
+    }
+    if (freetext !== undefined) {
+        if (typeof freetext !== 'string')
+            throw new ApiError(400, 'invalid_request', 'response.freetext must be a string');
+        response.freetext = freetext;
+    }
+    if (optionComments !== undefined) {
+        if (!isPlainObject(optionComments) || !Object.values(optionComments).every((v) => typeof v === 'string')) {
+            throw new ApiError(400, 'invalid_request', 'response.optionComments must be a string map');
+        }
+        response.optionComments = optionComments;
+    }
+    return response;
+}
+function validateRespondRequest(raw) {
+    if (!isPlainObject(raw))
+        throw new ApiError(400, 'invalid_request', 'respond body is required');
+    requireNoExtraKeys(raw, ['responses']);
+    if (!Array.isArray(raw['responses']))
+        throw new ApiError(400, 'invalid_request', '`responses` must be an array');
+    return { responses: raw['responses'].map(validateInteractionResponse) };
+}
+function validateCancelRequest(raw) {
+    if (raw === undefined)
+        return {};
+    if (!isPlainObject(raw))
+        throw new ApiError(400, 'invalid_request', 'cancel body must be an object');
+    requireNoExtraKeys(raw, ['reason']);
+    if (raw['reason'] === undefined)
+        return {};
+    const reason = raw['reason'];
+    if (typeof reason !== 'string')
+        throw new ApiError(400, 'invalid_request', '`reason` must be a string');
+    if (reason.trim() === '' || reason.length > CANCEL_REASON_MAX) {
+        throw new ApiError(400, 'invalid_request', '`reason` must be nonempty after trim and at most 1000 characters');
+    }
+    return { reason };
+}
+// ===========================================================================
+// GET /v1/human/inbox — enumerate
+// ===========================================================================
 function handleList() {
     const items = filterTerminalReviewTickets(scanInbox());
+    // `blocked_since` is an RFC 3339 timestamp that may carry a non-`Z` offset;
+    // two offsets are not lexically comparable (`+14:00` can sort after `Z`
+    // while naming an earlier instant), so sort by parsed instant and use the
+    // ticket id only to break an exact tie.
     const tickets = items.map(toTicketSummaryDTO).sort((a, b) => {
         const byTime = Date.parse(b.blocked_since) - Date.parse(a.blocked_since);
         return byTime !== 0 ? byTime : a.ticket_id.localeCompare(b.ticket_id);
     });
     return { status: 200, body: { tickets } };
 }
+// ===========================================================================
+// GET /v1/human/inbox/:ticket_id — read a pending deck
+// ===========================================================================
+function handleGetDeck(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    if (resolved.kind === 'review') {
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets have no v1 read operation');
+    }
+    if (readTicketResult(resolved.dir) !== null) {
+        throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+    }
+    // A malformed stored ticket is omitted from enumeration by `scanInbox`; if
+    // independently reached during a race (or a ticket is mutated on disk after
+    // enumeration), `parseDeck` throws a plain Error whose message can carry a
+    // `bodyPath` value or another host filesystem path (e.g. "bodyPath '/etc/
+    // passwd' escapes the deck directory"). That message must never reach the
+    // wire, so it is never allowed to fall through to the router's generic
+    // mapper unsanitized — humanloop validation itself is never weakened to
+    // serve unvalidated content, only its failure message is sanitized.
+    let deck;
+    try {
+        deck = parseDeck(deckPath(resolved.dir));
+    }
+    catch {
+        throw new ApiError(500, 'internal', 'the ticket could not be read');
+    }
+    return { status: 200, body: { ticket_id: ticketId, kind: 'deck', deck: toDeckDTO(deck) } };
+}
+// ===========================================================================
+// POST /v1/human/inbox/:ticket_id/respond — submit
+// ===========================================================================
+// The exhaustive set of messages the ticket store's response validator throws
+// for a genuine response-shape
+// rejection — duplicate/unknown interaction id, invalid single/multi-select
+// shape, disallowed freetext, invalid option comments, or a missing required
+// notify acknowledgement. None of these ever carry a filesystem path (only
+// client-supplied interaction ids), so their message is safe to forward
+// verbatim as `invalid_ticket_response`. Any other failure — a malformed
+// stored deck, a lock/dispatch/filesystem error — is not a response-shape
+// problem and must not be mislabeled or leak its cause; it is sanitized to
+// `500 internal`.
+const RESPONSE_VALIDATION_MESSAGE_PATTERNS = [
+    /^response does not match a unique deck interaction: /,
+    /^invalid single-select response for /,
+    /^invalid multi-select response for /,
+    /^freetext is not allowed for /,
+    /^invalid option comments for /,
+    /^notification requires an explicit acknowledgement: /,
+];
+function isResponseValidationError(err) {
+    return err instanceof Error && RESPONSE_VALIDATION_MESSAGE_PATTERNS.some((pattern) => pattern.test(err.message));
+}
+function coerceSingleSelect(responses, dir) {
+    const deck = readJsonOrNull(deckPath(dir));
+    if (deck === null)
+        return responses;
+    const multiSelect = new Map(deck.interactions.map((interaction) => [interaction.id, interaction.multiSelect === true]));
+    return responses.map((response) => {
+        if (multiSelect.get(response.id) === true || response.selectedOptionId !== undefined || response.selectedOptionIds?.length !== 1)
+            return response;
+        const { selectedOptionIds: _selectedOptionIds, ...rest } = response;
+        return { ...rest, selectedOptionId: response.selectedOptionIds[0] };
+    });
+}
+async function handleRespond(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const request = validateRespondRequest(ctx.body);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    if (resolved.kind === 'review') {
+        throw new ApiError(409, 'ticket_kind_unsupported', 'review tickets submit through POST /v1/human/reviews/:id/submit');
+    }
+    if (readTicketResult(resolved.dir) !== null) {
+        throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+    }
+    try {
+        const result = await resolveDeckTicket(resolved.nodeId, coerceSingleSelect(request.responses, resolved.dir));
+        if (result.kind !== 'deck')
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        // The daemon's terminal errors are public protocol outcomes: preserve both
+        // their code and message so Northlight can distinguish conflict from a
+        // recorded-but-undelivered answer.
+        if (error instanceof ApiError)
+            throw error;
+        if (isResponseValidationError(error)) {
+            throw new ApiError(400, 'invalid_ticket_response', error.message);
+        }
+        throw new ApiError(500, 'internal', 'the ticket could not be finalized');
+    }
+}
+// ===========================================================================
+// POST /v1/human/inbox/:ticket_id/cancel — cancel
+// ===========================================================================
+async function handleCancel(ctx) {
+    const ticketId = requireTicketId(ctx.params);
+    const request = validateCancelRequest(ctx.body);
+    const resolved = resolveTicket(ticketId);
+    if (resolved === null)
+        throw new ApiError(404, 'ticket_not_found', 'no matching ticket');
+    try {
+        if (resolved.kind === 'review') {
+            const review = getReviewByBridge(resolved.nodeId);
+            if (review !== null) {
+                if (review.state === 'approved') {
+                    throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+                }
+                const finished = await cancelReview(review.review_id, {
+                    reason: request.reason ?? DEFAULT_CANCEL_REASON,
+                    actor: 'human',
+                });
+                if (finished.outcome === 'already_settled') {
+                    throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+                }
+                if (finished.ticket_result?.kind !== 'canceled') {
+                    throw new Error('canonical review cancellation did not produce a ticket result');
+                }
+                return { status: 200, body: finished.ticket_result };
+            }
+        }
+        const result = await cancelHumanTicket(resolved.nodeId, {
+            reason: request.reason ?? DEFAULT_CANCEL_REASON,
+            actor: 'human',
+        });
+        if (result.kind !== 'canceled')
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        return { status: 200, body: result };
+    }
+    catch (error) {
+        if (error instanceof ApiError)
+            throw error;
+        // Review errors are canonical lifecycle vocabulary, not ticket protocol.
+        // A concurrent terminal winner is the same public ticket conflict.
+        if (error instanceof ReviewOperationError) {
+            throw new ApiError(409, 'ticket_already_resolved', 'ticket was already resolved');
+        }
+        // A lock/filesystem/delivery failure is not a request-shape problem; do
+        // not leak its cause through the generic router mapper.
+        throw new ApiError(500, 'internal', 'the ticket could not be canceled');
+    }
+}
 export const inboxRoutes = [
     { method: 'GET', pattern: '/v1/human/inbox', handler: handleList },
+    { method: 'GET', pattern: '/v1/human/inbox/:ticket_id', handler: handleGetDeck },
+    { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/respond', handler: handleRespond },
+    { method: 'POST', pattern: '/v1/human/inbox/:ticket_id/cancel', handler: handleCancel },
 ];

package/dist/daemon/api/handlers/memory.d.ts

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

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

@@ -0,0 +1,48 @@
+// Memory-document resolution handler — `GET /v1/memory/resolve?name=&node=`.
+// Turns a `[[canonical/name]]` link written in a node's transcript into the
+// absolute path of the document THAT node would read, so a client can peek it
+// (`GET /v1/files/peek`) and render it.
+//
+// The node is required, not optional: crtrd serves every node from one process,
+// so its own cwd and env name no node, and the same name legitimately resolves
+// to different documents for two nodes (each has its own context store, project
+// stack, and profile). Resolution therefore runs target-addressed —
+// `resolveMemoryDocForTarget` with the node's cwd/profile/id off canvas.
+import { getNode } from '../../../index.js';
+import { notFound, usage } from '../../../core/errors.js';
+import { resolveMemoryDocForTarget } from '../../../core/memory-resolver.js';
+import { isDocLinkName } from '../../../core/memory/doc-link-grammar.js';
+function handleResolve(ctx) {
+    const name = ctx.query.get('name');
+    if (name === null || name === '') {
+        throw usage('a memory resolve requires a `name` query param');
+    }
+    // The link grammar is the same one that produced the link (browser-safe, one
+    // source of truth): anything outside it is not a document name, and rejecting
+    // it here keeps a stray `[[…]]` from reaching the resolver's scope parsing.
+    if (!isDocLinkName(name)) {
+        throw usage('memory document name must be `/`-joined [A-Za-z0-9_-] segments', { received: name });
+    }
+    const nodeId = ctx.query.get('node');
+    if (nodeId === null || nodeId === '') {
+        throw usage('a memory resolve requires a `node` query param — resolution is per-node');
+    }
+    const meta = getNode(nodeId);
+    if (meta === null)
+        throw notFound(`unknown node: ${nodeId}`, { received: nodeId });
+    const doc = resolveMemoryDocForTarget(name, {
+        cwd: meta.cwd,
+        profileId: meta.profile_id ?? null,
+        nodeId: meta.node_id,
+    });
+    const body = {
+        name: doc.name,
+        scope: doc.scope,
+        path: doc.path,
+        ...(doc.plugin === undefined ? {} : { plugin: doc.plugin }),
+    };
+    return { status: 200, body };
+}
+export const memoryRoutes = [
+    { method: 'GET', pattern: '/v1/memory/resolve', handler: handleResolve },
+];

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

@@ -59,6 +59,12 @@ function parseSendBody(body) {
     if (delivery !== undefined && delivery !== 'interactive') {
         throw usage(`invalid delivery: ${String(delivery)} (expected interactive)`);
     }
+    const messageId = b['message_id'];
+    if (messageId !== undefined && typeof messageId !== 'string') {
+        throw usage('message_id must be a string');
+    }
+    if (typeof messageId === 'string' && messageId.trim() !== '')
+        out.message_id = messageId;
     if (delivery === 'interactive') {
         // Interactive delivery is a live-conversation send: a plain immediate body,
         // nothing that only makes sense on the durable path.
@@ -158,7 +164,7 @@ async function handleMessage(ctx) {
     //     straight there (append + revive, watcher delivers post-boot). ---
     if (req.delivery === 'interactive' && isBrokerLive(meta)) {
         try {
-            await deliverLive(id, req.body);
+            await deliverLive(id, req.body, req.message_id);
             const body = {
                 node_id: id,
                 delivered: true,

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

@@ -172,11 +172,13 @@ async function handleSubmit(ctx) {
     if (violations.length > 0 || reviewId === undefined)
         invalidRequest(violations);
     const finished = await submitReviewApproval(reviewId);
-    const body = {
-        review: toReviewResponseDTO(finished.record),
-        result: toFeedbackResultDTO(finished.result),
-        outcome: finished.outcome,
-    };
+    const body = finished.outcome === 'awaiting_companion'
+        ? { review: toReviewResponseDTO(finished.record), outcome: finished.outcome }
+        : {
+            review: toReviewResponseDTO(finished.record),
+            result: toFeedbackResultDTO(finished.result),
+            outcome: finished.outcome,
+        };
     return { status: 200, body };
 }
 async function handleCancel(ctx) {

package/dist/daemon/api/map.js

@@ -228,6 +228,7 @@ export function toCronDTO(c, lastRun) {
         sink: sinkDisplay(c.sink),
         tier: c.tier,
         state: c.state,
+        held: c.held,
         run_state: c.run_state,
         last_run: lastRun === undefined || lastRun === null
             ? null
@@ -279,6 +280,8 @@ export function toReviewDTO(row, extras = {}) {
     };
     if (row.opened_at !== null)
         dto.opened_at = row.opened_at;
+    if (row.submit_requested_at !== null)
+        dto.submit_requested_at = row.submit_requested_at;
     if (row.approved_at !== null)
         dto.approved_at = row.approved_at;
     if (row.changed !== null)

package/dist/daemon/api/server.js

@@ -27,6 +27,7 @@ import { focusRoutes } from './handlers/focus.js';
 import { healthRoutes } from './handlers/health.js';
 import { humanRoutes } from './handlers/human.js';
 import { inboxRoutes } from './handlers/inbox.js';
+import { memoryRoutes } from './handlers/memory.js';
 import { messageRoutes } from './handlers/messages.js';
 import { modelAuthRoutes } from './handlers/modelauth.js';
 import { nodeRoutes } from './handlers/nodes.js';
@@ -52,6 +53,7 @@ function buildRouter() {
         .registerAll(attachRoutes)
         .registerAll(canvasRoutes)
         .registerAll(fileRoutes)
+        .registerAll(memoryRoutes)
         .registerAll(focusRoutes)
         .registerAll(subscriptionRoutes)
         .registerAll(cronRoutes)

package/dist/daemon/cron-run.js

@@ -95,6 +95,21 @@ const EMPTY_STDOUT_SHA256 = createHash('sha256').update('').digest('hex');
 /** Lead of a `cron_runs.delivered` string written by the overlap=skip pass.
  *  Matched (not just written) — see `latestRunIsSkip`. */
 const SKIP_MARKER = 'skipped (overlap=skip)';
+/** EX_TEMPFAIL — the owed-gate disposition. A scheduled run exiting 75
+ *  declares "this occurrence is owed but not currently eligible": the row is
+ *  PARKED (held=1, occurrence not spent) instead of disposed — no failure, no
+ *  escalation, no delivery, no on-change hash, no one-shot consumption. A poke
+ *  (`POST /v1/crons/poke`) re-dues it now; otherwise a recurring row re-checks
+ *  at its already-advanced natural slot and a held one-shot waits at its
+ *  backstop (`expires_at`, else far future — poke-only). The gate itself stays
+ *  in bash; the daemon only honors the exit code. */
+const EXIT_HELD = 75;
+/** `cron_runs.delivered` string for a held (exit-75) settlement. */
+const HELD_DELIVERED = 'deferred (exit 75) — held for poke';
+/** Backstop `fire_at` for a held one-shot without `--expires`: never due on
+ *  the clock — the row fires only on a poke. Without this, a past-due parked
+ *  one-shot would re-fire every tick forever. */
+const HELD_ONE_SHOT_FAR_FUTURE = '9999-12-31T23:59:59.999Z';
 /** One id per daemon process instance — distinguishes THIS process's own
  *  in-flight run leases from a stale 'running' row a prior (crashed/restarted)
  *  daemon left behind. */
@@ -451,7 +466,9 @@ export function recoverStaleCronLeases(now, options = {}) {
                 stderr_head: ctx.stderrHead,
                 delivered: disposition.delivered,
             });
-            releaseCronRunLease(c.cron_id);
+            // A recovered-timeout settlement took the ordinary disposition path
+            // (pause + escalation unless silent) — the gate is resolved, clear held.
+            releaseCronRunLease(c.cron_id, { kind: 'clear' });
             if (c.recur == null && !disposition.paused)
                 consumeCron(c.cron_id);
         })();
@@ -720,6 +737,16 @@ export function executeCron(c, opts) {
                     return;
                 }
                 const finishedAtMs = Date.now();
+                // The owed-gate branch (exit 75): a peer of the wasReplaced
+                // short-circuit — skip disposition entirely (no delivery, no
+                // escalation, no pause, no on-change hash, no one-shot consumption)
+                // and settle the row's held state with the lease release instead. The
+                // exclusions are deliberate: a manual `cron run` must not change
+                // scheduling state; a timeout-killed or launch-failed run is a real
+                // failure even if a stray 75 surfaces; a replaced or self-canceled
+                // run's existing short-circuits win.
+                const heldDeferred = !outOfBand && !timedOut && processError == null && code === EXIT_HELD && !wasReplaced && !wasSelfCanceled;
+                let heldSettle;
                 let delivered;
                 let paused = false;
                 if (wasReplaced) {
@@ -727,6 +754,38 @@ export function executeCron(c, opts) {
                     // fresh: record it, no disposition, no escalation.
                     delivered = 'replaced (overlap=replace)';
                 }
+                else if (heldDeferred) {
+                    delivered = HELD_DELIVERED;
+                    // Re-read the row: `last_poke_at` must be CURRENT — a poke landing
+                    // while this gate check was in flight is exactly the race this
+                    // check closes. (A row canceled mid-run is gone; recordCronRun and
+                    // the lease release below both no-op.)
+                    const fresh = getCron(c.cron_id);
+                    if (fresh !== null) {
+                        if (fresh.state === 'active' && fresh.last_poke_at !== null && startedAtIso < fresh.last_poke_at) {
+                            // A poke arrived mid-run — its unpark statement deliberately
+                            // skips leased rows — so re-due instead of park: the gate
+                            // re-checks next tick instead of stalling until the backstop
+                            // while the very eligibility it waits for is present. Only for
+                            // a row still ACTIVE: a row paused mid-run parks below instead —
+                            // the poke skips paused rows on purpose while its stamp lands on
+                            // every row, and a re-due would leave a past-due UNHELD row that
+                            // `cron resume` fires blind even though its gate never passed.
+                            heldSettle = { kind: 'redue', nowIso: new Date(finishedAtMs).toISOString() };
+                        }
+                        else if (c.recur != null) {
+                            // Recurring: the pre-run advance already wrote the natural next
+                            // slot, which IS the backstop — park and touch nothing else.
+                            heldSettle = { kind: 'park' };
+                        }
+                        else {
+                            // One-shot: park at its backstop. With --expires, expiry deletes
+                            // the row unfired at that instant (bounded wait); without, the
+                            // far-future fire_at means poke-only.
+                            heldSettle = { kind: 'park', fireAt: fresh.expires_at ?? HELD_ONE_SHOT_FAR_FUTURE };
+                        }
+                    }
+                }
                 else {
                     const disposition = await disposeSettledRun(c, {
                         runId,
@@ -758,7 +817,13 @@ export function executeCron(c, opts) {
                     delivered,
                 };
                 recordCronRun(record);
-                if (!outOfBand && c.recur == null && !paused) {
+                if (heldDeferred) {
+                    // Held: the occurrence is NOT spent — even a one-shot is retained
+                    // (like a paused escalated one-shot is). Park/re-due and the lease
+                    // release are one write.
+                    releaseCronRunLease(c.cron_id, heldSettle);
+                }
+                else if (!outOfBand && c.recur == null && !paused) {
                     // One-shot: the run is done, delete the row (its history cascades
                     // with it — matching one-shot consumption). A failing
                     // one-shot that PAUSED for escalation is kept, so `cron resume` can
@@ -767,7 +832,10 @@ export function executeCron(c, opts) {
                     consumeCron(c.cron_id);
                 }
                 else {
-                    releaseCronRunLease(c.cron_id);
+                    // An ordinary scheduled disposition settlement resolves the gate,
+                    // so it unparks a held row; a replaced or out-of-band run leaves
+                    // `held` untouched (the gate is still unresolved).
+                    releaseCronRunLease(c.cron_id, wasReplaced || outOfBand ? undefined : { kind: 'clear' });
                 }
                 resolve(record);
             })().catch(reject);

package/dist/daemon/crtrd.js

@@ -57,6 +57,7 @@ import { DEFAULT_INTERVAL_MS } from './supervise-cadence.js';
 import { BrokerSupervisionReconciler } from './reconcilers/broker-supervision.js';
 import { ControllerDeathReconciler, DormantInboxReconciler } from './reconcilers/dormant-inbox.js';
 import { CronLaneReconciler } from './reconcilers/cron-lane.js';
+import { PendingReviewSubmitReconciler } from './reconcilers/pending-review-submit.js';
 import { StorageMaintenanceReconciler } from './reconcilers/storage-maintenance.js';
 import { captureLivenessSnapshot, capturePidCommand, captureTeardownSnapshot, isPidAlive, killProcessTreePids, } from '../core/canvas/pid.js';
 import { bindFleet, boundFleet } from '../core/runtime/fleet.js';
@@ -311,6 +312,7 @@ const brokerSupervision = new BrokerSupervisionReconciler();
 const controllerDeath = new ControllerDeathReconciler();
 const dormantInbox = new DormantInboxReconciler();
 const cronLane = new CronLaneReconciler();
+const pendingReviewSubmit = new PendingReviewSubmitReconciler();
 const storageMaintenance = new StorageMaintenanceReconciler();
 /** Supervision tick over the daemon's current live set. */
 export async function superviseTick(now = Date.now(), lifecycle = directTickLifecycle) {
@@ -334,6 +336,7 @@ export async function superviseTick(now = Date.now(), lifecycle = directTickLife
     controllerDeath.run(now, { rows });
     dormantInbox.run(now, { rows, fleet, hasBrokerCapacity });
     cronLane.run(now, { lifecycle, hasBrokerCapacity });
+    pendingReviewSubmit.run({ lifecycle });
     storageMaintenance.run(now);
 }
 /** Start the supervisor loop after winning the authoritative canvas claim.

package/dist/daemon/reconcilers/pending-review-submit.d.ts

@@ -0,0 +1,7 @@
+import type { DetachedWorkLifecycle } from './broker-supervision.js';
+export interface PendingReviewSubmitContext {
+    lifecycle: DetachedWorkLifecycle;
+}
+export declare class PendingReviewSubmitReconciler {
+    run(ctx: PendingReviewSubmitContext): void;
+}