@north-light/crouter 0.3.221 → 0.3.223

package/dist/daemon/api/handlers/prospective-chat-inventory.js

@@ -0,0 +1,59 @@
+import { ApiError } from '../../../api/errors.js';
+import { usage } from '../../../core/errors.js';
+import { resolveLaunchTarget } from '../../../core/runtime/launch-target.js';
+import { runProspectiveInventory } from '../../../core/runtime/prospective-inventory.js';
+const inFlight = new Map();
+function singleQueryValue(ctx, name) {
+    const values = ctx.query.getAll(name);
+    if (values.length > 1)
+        throw usage(`${name} must appear at most once`);
+    return values[0];
+}
+async function handleGet(ctx) {
+    for (const [name] of ctx.query) {
+        if (name !== 'profile' && name !== 'cwd' && name !== 'kind')
+            throw usage(`unknown prospective inventory query parameter: ${name}`);
+    }
+    const profile = singleQueryValue(ctx, 'profile');
+    const cwd = singleQueryValue(ctx, 'cwd');
+    const kind = singleQueryValue(ctx, 'kind');
+    if (kind !== undefined && kind.trim() === '')
+        throw usage('kind must be a non-empty string when provided');
+    const target = await resolveLaunchTarget({
+        root: true,
+        ...(profile !== undefined ? { profile } : {}),
+        ...(cwd !== undefined ? { cwd } : {}),
+        ...(kind !== undefined ? { kind } : {}),
+    }, { readOnlyProfileSelection: true });
+    const key = JSON.stringify([target.profileId, target.cwd, target.kind]);
+    let pending = inFlight.get(key);
+    if (pending === undefined) {
+        pending = runProspectiveInventory({
+            cwd: target.cwd,
+            profileId: target.profileId,
+            extensions: target.launch.extensions,
+        });
+        inFlight.set(key, pending);
+        void pending.finally(() => {
+            if (inFlight.get(key) === pending)
+                inFlight.delete(key);
+        }).catch(() => { });
+    }
+    let rows;
+    try {
+        rows = await pending;
+    }
+    catch {
+        throw new ApiError(503, 'preflight_failed', 'prospective chat inventory preflight failed');
+    }
+    const body = {
+        profile_id: target.profileId,
+        cwd: target.cwd,
+        commands: rows.commands,
+        memory_refs: rows.memory_refs,
+    };
+    return { status: 200, body };
+}
+export const prospectiveChatInventoryRoutes = [
+    { method: 'GET', pattern: '/v1/prospective-chat-inventory', handler: handleGet },
+];

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

@@ -14,7 +14,7 @@ import { toFeedbackResultDTO, toReviewDTO } from '../map.js';
 import { invalidRequest as rejectRequest, objectBody, optionalString, requireParam, requiredString, } from './validate.js';
 const REVIEW_STATES = new Set(['open', 'approved', 'canceled']);
 const CREATE_FIELDS = ['origin_kind', 'origin_node_id', 'file', 'idempotency_key', 'subtitle', 'output_path'];
-const CANCEL_FIELDS = ['reason', 'actor'];
+const CANCEL_FIELDS = ['reason', 'actor', 'disposition'];
 function invalidRequest(violations) {
     rejectRequest('review request', violations);
 }
@@ -131,7 +131,15 @@ function parseCancel(ctx, violations) {
     const body = ctx.body === undefined ? {} : objectBody(ctx.body, CANCEL_FIELDS, violations);
     const reason = optionalString(body, 'reason', violations);
     const actor = optionalString(body, 'actor', violations);
-    return { ...(reason === undefined ? {} : { reason }), ...(actor === undefined ? {} : { actor }) };
+    const disposition = optionalString(body, 'disposition', violations);
+    if (disposition !== undefined && disposition !== 'canceled' && disposition !== 'dismissed') {
+        violations.push({ field: 'disposition', problem: 'must be "canceled" or "dismissed"', received: disposition });
+    }
+    return {
+        ...(reason === undefined ? {} : { reason }),
+        ...(actor === undefined ? {} : { actor }),
+        ...(disposition === 'canceled' || disposition === 'dismissed' ? { disposition } : {}),
+    };
 }
 function requireEmptyBody(ctx, violations) {
     objectBody(ctx.body, [], violations);

package/dist/daemon/api/server.js

@@ -28,6 +28,7 @@ import { fileRoutes } from './handlers/files.js';
 import { focusRoutes } from './handlers/focus.js';
 import { healthRoutes } from './handlers/health.js';
 import { humanRoutes } from './handlers/human.js';
+import { humanRequestRoutes } from './handlers/human-requests.js';
 import { inboxRoutes } from './handlers/inbox.js';
 import { feedbackCommentRoutes } from './handlers/feedback-comments.js';
 import { memoryRoutes } from './handlers/memory.js';
@@ -35,6 +36,7 @@ import { messageRoutes } from './handlers/messages.js';
 import { modelAuthRoutes } from './handlers/modelauth.js';
 import { nodeRoutes } from './handlers/nodes.js';
 import { profileRoutes } from './handlers/profiles.js';
+import { prospectiveChatInventoryRoutes } from './handlers/prospective-chat-inventory.js';
 import { reportRoutes } from './handlers/reports.js';
 import { reviewCommentRoutes } from './handlers/review-comments.js';
 import { reviewRoutes } from './handlers/reviews.js';
@@ -67,7 +69,9 @@ function buildRouter() {
         .registerAll(reviewRoutes)
         .registerAll(reviewCommentRoutes)
         .registerAll(inboxRoutes)
+        .registerAll(humanRequestRoutes)
         .registerAll(chatInventoryRoutes)
+        .registerAll(prospectiveChatInventoryRoutes)
         .registerAll(feedbackCommentRoutes);
 }
 /** Is this request an attach upgrade — `GET /v1/nodes/{id}/attach` — and if so,

package/dist/daemon/crtrd.js

@@ -50,6 +50,7 @@ import { crtrHome, isSafeNodeId } from '../core/canvas/paths.js';
 import { listNodes, migrateLegacyPidIdentities, } from '../core/canvas/index.js';
 import { createApiServer } from './api/server.js';
 import { reconcileUndeliveredTickets } from './human/sweep.js';
+import { recoverRunningActionDeliveries } from '../core/canvas/human-deliveries.js';
 import { sweepReviews } from './review/sweep.js';
 import { pidfilePath } from './pidfile.js';
 import { rendererWarning } from '../core/runtime/package-health.js';
@@ -57,6 +58,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 { HumanDeliveryLaneReconciler } from './reconcilers/human-delivery-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';
@@ -312,6 +314,7 @@ const brokerSupervision = new BrokerSupervisionReconciler();
 const controllerDeath = new ControllerDeathReconciler();
 const dormantInbox = new DormantInboxReconciler();
 const cronLane = new CronLaneReconciler();
+const humanDeliveryLane = new HumanDeliveryLaneReconciler();
 const pendingReviewSubmit = new PendingReviewSubmitReconciler();
 const storageMaintenance = new StorageMaintenanceReconciler();
 /** Supervision tick over the daemon's current live set. */
@@ -336,6 +339,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 });
+    humanDeliveryLane.run(now, { lifecycle });
     pendingReviewSubmit.run({ lifecycle });
     storageMaintenance.run(now);
 }
@@ -652,6 +656,8 @@ export async function runDaemon(opts = {}) {
         await operationIdContext.fresh(async () => {
             await sweepReviews();
             await reconcileUndeliveredTickets();
+            // Unlike a cron one-shot, a completion is at-least-once: destinations deduplicate request IDs, so a dead daemon's running delivery is re-queued immediately.
+            recoverRunningActionDeliveries(Date.now());
         });
         // Boot reconciliation clears stale process identities before any tick can
         // inspect them, then migrates legacy identities only with proven same-boot

package/dist/daemon/human/deliver-action.d.ts

@@ -0,0 +1,16 @@
+import { type ActionDeliveryRecord, type ActionDeliverySettlement } from '../../core/canvas/human-deliveries.js';
+export declare const ACTION_DELIVERY_TIMEOUT_MS = 120000;
+export declare const ACTION_DELIVERY_STDERR_TAIL_BYTES: number;
+/** Durable exponential retry delay for the attempt that just failed. */
+export declare function actionDeliveryBackoffMs(attempt: number): number;
+export interface ActionDeliveryProcessOutcome {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    spawnError?: Error;
+    stderr: string;
+}
+/** Process contract mapping. stdout deliberately does not participate. */
+export declare function actionDeliverySettlementForOutcome(outcome: ActionDeliveryProcessOutcome, attempt: number, now: number): ActionDeliverySettlement;
+/** Spawn and settle one already-claimed action delivery. */
+export declare function deliverAction(delivery: ActionDeliveryRecord, claimOwner: string): Promise<void>;

package/dist/daemon/human/deliver-action.js

@@ -0,0 +1,168 @@
+import { spawn } from 'node:child_process';
+import { settleActionDelivery, } from '../../core/canvas/human-deliveries.js';
+import { killProcessGroup } from '../../core/canvas/pid.js';
+import { buildOperationalEnvBase } from '../../core/runtime/spawn-env.js';
+export const ACTION_DELIVERY_TIMEOUT_MS = 120_000;
+const ACTION_DELIVERY_KILL_GRACE_MS = 2_000;
+export const ACTION_DELIVERY_STDERR_TAIL_BYTES = 4 * 1024;
+/** Durable exponential retry delay for the attempt that just failed. */
+export function actionDeliveryBackoffMs(attempt) {
+    return Math.min(5_000 * 2 ** (attempt - 1), 3_600_000);
+}
+/** Process contract mapping. stdout deliberately does not participate. */
+export function actionDeliverySettlementForOutcome(outcome, attempt, now) {
+    if (outcome.spawnError !== undefined) {
+        return {
+            state: 'pending',
+            nextAttemptAt: now + actionDeliveryBackoffMs(attempt),
+            failure: failure('spawn_error', { message: outcome.spawnError.message, stderr: outcome.stderr }),
+        };
+    }
+    if (outcome.timedOut) {
+        return {
+            state: 'pending',
+            nextAttemptAt: now + actionDeliveryBackoffMs(attempt),
+            // The kill escalation's own signal distinguishes the graceful term from the SIGKILL.
+            failure: failure('timeout', { ...(outcome.signal === null ? {} : { signal: outcome.signal }), stderr: outcome.stderr }),
+        };
+    }
+    if (outcome.signal !== null) {
+        return {
+            state: 'pending',
+            nextAttemptAt: now + actionDeliveryBackoffMs(attempt),
+            failure: failure('signal', { signal: outcome.signal, stderr: outcome.stderr }),
+        };
+    }
+    if (outcome.exitCode === 0)
+        return { state: 'accepted' };
+    if (outcome.exitCode === 78) {
+        return { state: 'permanent_failed', failure: failure('exit', { exitCode: 78, stderr: outcome.stderr }) };
+    }
+    return {
+        state: 'pending',
+        nextAttemptAt: now + actionDeliveryBackoffMs(attempt),
+        failure: failure('exit', { exitCode: outcome.exitCode ?? undefined, stderr: outcome.stderr }),
+    };
+}
+function failure(kind, fields) {
+    return { kind, ...fields };
+}
+function stderrTailCapture() {
+    let tail = Buffer.alloc(0);
+    return {
+        take(chunk) {
+            tail = chunk.length >= ACTION_DELIVERY_STDERR_TAIL_BYTES
+                ? chunk.subarray(chunk.length - ACTION_DELIVERY_STDERR_TAIL_BYTES)
+                : Buffer.concat([tail, chunk]).subarray(Math.max(0, tail.length + chunk.length - ACTION_DELIVERY_STDERR_TAIL_BYTES));
+        },
+        decode() {
+            return tail.toString('utf8');
+        },
+    };
+}
+function completionForAttempt(completion, attempt) {
+    const document = completion;
+    const delivery = document.delivery;
+    return JSON.stringify({ ...document, delivery: { ...delivery, attempt } });
+}
+/** Spawn and settle one already-claimed action delivery. */
+export async function deliverAction(delivery, claimOwner) {
+    const stderr = stderrTailCapture();
+    let completion;
+    try {
+        completion = completionForAttempt(delivery.completion, delivery.attempt);
+    }
+    catch (error) {
+        settle(delivery, claimOwner, actionDeliverySettlementForOutcome({
+            exitCode: null,
+            signal: null,
+            timedOut: false,
+            spawnError: error,
+            stderr: stderr.decode(),
+        }, delivery.attempt, Date.now()));
+        return;
+    }
+    let child;
+    try {
+        child = spawn(delivery.argv[0], delivery.argv.slice(1), {
+            cwd: delivery.cwd,
+            env: actionDeliveryEnv(delivery.cwd),
+            detached: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (error) {
+        settle(delivery, claimOwner, actionDeliverySettlementForOutcome({
+            exitCode: null,
+            signal: null,
+            timedOut: false,
+            spawnError: error,
+            stderr: stderr.decode(),
+        }, delivery.attempt, Date.now()));
+        return;
+    }
+    await new Promise((resolve) => {
+        let settled = false;
+        let timedOut = false;
+        let killTimer;
+        let timeout;
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            child.stdin?.destroy();
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            settle(delivery, claimOwner, actionDeliverySettlementForOutcome(outcome, delivery.attempt, Date.now()));
+            resolve();
+        };
+        child.stdout?.on('data', () => { }); // Drain diagnostics; stdout is never a control channel.
+        child.stderr?.on('data', (chunk) => stderr.take(chunk));
+        child.stdin?.on('error', () => { }); // A child may exit before draining a large completion; its exit code remains authoritative.
+        child.on('error', (error) => {
+            finish({ exitCode: null, signal: null, timedOut: false, spawnError: error, stderr: stderr.decode() });
+        });
+        child.on('exit', (exitCode, signal) => {
+            finish({
+                exitCode,
+                signal,
+                timedOut,
+                stderr: stderr.decode(),
+            });
+        });
+        const killWithEscalation = () => {
+            if (child.pid === undefined)
+                return;
+            killProcessGroup(child.pid);
+            killTimer = setTimeout(() => killProcessGroup(child.pid, 'SIGKILL'), ACTION_DELIVERY_KILL_GRACE_MS);
+            killTimer.unref?.();
+        };
+        // The deadline starts at spawn, not after stdin write or any output.
+        timeout = setTimeout(() => {
+            timedOut = true;
+            killWithEscalation();
+        }, ACTION_DELIVERY_TIMEOUT_MS);
+        timeout.unref?.();
+        child.stdin?.end(completion, 'utf8');
+    });
+}
+/** The delivery child crosses the same consent boundary as every other
+ *  crouter spawn: nothing of crtrd's own environment reaches it except what
+ *  `spawnEnv.allow` and the operational base admit for the action's own cwd.
+ *  No profile participates — an action is declared in scope config alone. */
+function actionDeliveryEnv(cwd) {
+    const env = buildOperationalEnvBase({ targetCwd: cwd, targetProfileId: null });
+    // Runtime identity, not host state: an action that calls `crtr` must reach
+    // the daemon that delivered to it, exactly as a cron body does.
+    const canvasHome = process.env['CRTR_HOME'];
+    if (canvasHome !== undefined && canvasHome !== '')
+        env['CRTR_HOME'] = canvasHome;
+    return env;
+}
+function settle(delivery, claimOwner, settlement) {
+    settleActionDelivery(delivery.requestId, delivery.attempt, claimOwner, settlement, Date.now());
+}

package/dist/daemon/human/finish.d.ts

@@ -1,3 +1,4 @@
+import { type CancelTicketOptions, type CompletePageOptions } from '../../core/human/tickets.js';
 import type { TicketResult } from '../../core/human/types.js';
 /** Every ticket-ending action retires the ticket's feedback companion — done
  * with a canonical final when approved, never left resident. Idempotent and replay-safe; a
@@ -11,12 +12,14 @@ export declare function settleFeedbackCompanion(ticketId: string, outcome: 'appr
  * through this function, so the reply-route descriptor is the sole authority
  * on whether completion reaches a bridge.
  */
-export declare function resolvePageTicket(ticketId: string, responses: unknown): Promise<TicketResult>;
+export declare function resolvePageTicket(ticketId: string, responses: unknown, opts?: CompletePageOptions): Promise<TicketResult>;
 /** Cancel a ticket with the store's first-writer-wins publication. */
-export declare function cancelHumanTicket(ticketId: string, opts: {
-    reason?: string;
-    actor?: string;
-}): Promise<TicketResult>;
+export declare function cancelHumanTicket(ticketId: string, opts: CancelTicketOptions): Promise<TicketResult>;
+/** Schedule the settled request's completion action, if it bound one. Only the
+ * settlement winner calls this; the daemon-start sweep replays it for a
+ * settlement that died before enqueueing, and the insert is idempotent on the
+ * request id so neither path can create a second delivery. */
+export declare function releaseActionDelivery(ticketId: string): void;
 /**
  * Deliver a terminal ticket result to its bridge. The canonical response is the
  * receipt: every action below is replay-safe, so lost delivery can be retried

package/dist/daemon/human/finish.js

@@ -1,6 +1,9 @@
 import { ApiError } from '../../api/index.js';
 import { getRow, subscribersOf } from '../../core/canvas/canvas.js';
-import { ticketDir } from '../../core/human/root.js';
+import { opaqueInboxTicketId, ticketDir } from '../../core/human/root.js';
+import { readTicketActionBinding } from '../../core/human/action-binding.js';
+import { completionEventFor, composeHumanCompletion } from '../../core/human/completion.js';
+import { enqueueActionDelivery } from '../../core/canvas/human-deliveries.js';
 import { parsePage } from '../../core/human/page.js';
 import { cancelTicket, projectReviewOutput, readTicketResult, takeoverAndCompletePage, } from '../../core/human/tickets.js';
 import { describePageAnswer } from '../../core/human/answer.js';
@@ -151,10 +154,11 @@ async function deliverOrConflict(ticketId) {
  * through this function, so the reply-route descriptor is the sole authority
  * on whether completion reaches a bridge.
  */
-export async function resolvePageTicket(ticketId, responses) {
-    const completed = takeoverAndCompletePage(ticketDir(ticketId), responses, { host: 'crtrd', pid: process.pid });
+export async function resolvePageTicket(ticketId, responses, opts = {}) {
+    const completed = takeoverAndCompletePage(ticketDir(ticketId), responses, { host: 'crtrd', pid: process.pid }, opts);
     if (!completed.won)
         return deliverOrConflict(ticketId);
+    releaseActionDelivery(ticketId);
     try {
         await deliverTerminalResult(ticketId);
     }
@@ -168,6 +172,7 @@ export async function cancelHumanTicket(ticketId, opts) {
     const canceled = cancelTicket(ticketDir(ticketId), opts);
     if (canceled.status === 'already_resolved')
         return deliverOrConflict(ticketId);
+    releaseActionDelivery(ticketId);
     try {
         await deliverTerminalResult(ticketId);
     }
@@ -176,6 +181,40 @@ export async function cancelHumanTicket(ticketId, opts) {
     }
     return canceled.result;
 }
+/** Schedule the settled request's completion action, if it bound one. Only the
+ * settlement winner calls this; the daemon-start sweep replays it for a
+ * settlement that died before enqueueing, and the insert is idempotent on the
+ * request id so neither path can create a second delivery. */
+export function releaseActionDelivery(ticketId) {
+    try {
+        const dir = ticketDir(ticketId);
+        const binding = readTicketActionBinding(dir);
+        if (binding === null)
+            return;
+        const result = readTicketResult(dir);
+        if (result === null || result.kind === 'review')
+            return;
+        const requestId = opaqueInboxTicketId(ticketId);
+        enqueueActionDelivery({
+            requestId,
+            argv: binding.argv,
+            cwd: binding.cwd,
+            completion: composeHumanCompletion({ requestId, result, binding, source: pageSource(dir) }),
+        });
+    }
+    catch (error) {
+        // The canonical outcome is already durable; the sweep replays this.
+        emitEvent({ level: 'error', event: 'human.action_delivery.enqueue_failed', node_id: ticketId, error });
+    }
+}
+function pageSource(dir) {
+    try {
+        return parsePage(dir).source ?? {};
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Deliver a terminal ticket result to its bridge. The canonical response is the
  * receipt: every action below is replay-safe, so lost delivery can be retried
@@ -207,9 +246,9 @@ export async function deliverTerminalResult(ticketId) {
     if (result.kind === 'canceled') {
         const title = pageTitle(dir);
         const reason = result.reason !== undefined && result.reason !== '' ? result.reason : 'no reason was given';
-        // A human dismissal is a rejection, not a routing event: say so plainly so
-        // the agent acts on the "no" instead of re-raising the same ask.
-        const dismissed = result.actor === 'human';
+        // A dismissal is a rejection, not a routing event: say so plainly so the
+        // agent acts on the "no" instead of re-raising the same ask.
+        const dismissed = completionEventFor(result) === 'dismissed';
         const subject = dismissed
             ? (title === undefined ? `human interaction ${ticketId} dismissed without answering` : `human interaction ${ticketId} — “${title}” dismissed without answering`)
             : (title === undefined ? `human interaction ${ticketId} canceled — no answer is coming` : `human interaction ${ticketId} — “${title}” canceled, no answer is coming`);

package/dist/daemon/human/sweep.js

@@ -5,7 +5,7 @@ import { getReviewByBridge } from '../../core/review/store.js';
 import { emitEvent } from '../../core/events/emit.js';
 import { ticketsRoot } from '../../core/human/root.js';
 import { readTicketResult } from '../../core/human/tickets.js';
-import { deliverTerminalResult, settleFeedbackCompanion } from './finish.js';
+import { deliverTerminalResult, releaseActionDelivery, settleFeedbackCompanion } from './finish.js';
 function isTerminalBridge(status) {
     return status === 'done' || status === 'dead' || status === 'canceled';
 }
@@ -32,6 +32,9 @@ export async function reconcileUndeliveredTickets() {
             // reply bridge exists: inbox-only pages have no bridge row, yet the
             // daemon can die between result publication and companion retirement.
             await settleFeedbackCompanion(entry, ticketResult.kind === 'canceled' ? 'canceled' : 'approved');
+            // A settlement that died before enqueueing its completion action still
+            // owes that delivery; the insert is idempotent on the request id.
+            releaseActionDelivery(entry);
             // The ROW is what carries status; `getNode` would answer from a pruned
             // bridge's surviving meta.json with no status at all.
             const bridge = getRow(entry);

package/dist/daemon/reconcilers/human-delivery-lane.d.ts

@@ -0,0 +1,10 @@
+import type { DetachedWorkLifecycle } from './broker-supervision.js';
+/** One daemon-life identity for guarded action-delivery claims. */
+export declare const humanDeliveryDaemonInstanceId: `${string}-${string}-${string}-${string}-${string}`;
+export interface HumanDeliveryLaneContext {
+    lifecycle: DetachedWorkLifecycle;
+}
+/** Admit due action deliveries without making the daemon's serial tick await subprocesses. */
+export declare class HumanDeliveryLaneReconciler {
+    run(now: number, ctx: HumanDeliveryLaneContext): void;
+}

package/dist/daemon/reconcilers/human-delivery-lane.js

@@ -0,0 +1,41 @@
+import { randomUUID } from 'node:crypto';
+import { claimActionDelivery, dueActionDeliveries } from '../../core/canvas/human-deliveries.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { operationIdContext } from '../../core/events/operation-id.js';
+import { deliverAction } from '../human/deliver-action.js';
+/** One daemon-life identity for guarded action-delivery claims. */
+export const humanDeliveryDaemonInstanceId = randomUUID();
+/** Admit due action deliveries without making the daemon's serial tick await subprocesses. */
+export class HumanDeliveryLaneReconciler {
+    run(now, ctx) {
+        if (!ctx.lifecycle.acceptsDetachedWork())
+            return;
+        let due;
+        try {
+            due = dueActionDeliveries(now);
+        }
+        catch (error) {
+            operationIdContext.fresh(() => {
+                emitEvent({ level: 'error', event: 'human.action_delivery.scan_failed', error });
+            });
+            return;
+        }
+        for (const candidate of due) {
+            try {
+                const claimed = claimActionDelivery(candidate.requestId, now, humanDeliveryDaemonInstanceId);
+                if (claimed === null)
+                    continue;
+                ctx.lifecycle.registerDetached(deliverAction(claimed, humanDeliveryDaemonInstanceId).catch((error) => {
+                    operationIdContext.fresh(() => {
+                        emitEvent({ level: 'error', event: 'human.action_delivery.failed', error, fields: { request_id: claimed.requestId } });
+                    });
+                }));
+            }
+            catch (error) {
+                operationIdContext.fresh(() => {
+                    emitEvent({ level: 'error', event: 'human.action_delivery.claim_failed', error, fields: { request_id: candidate.requestId } });
+                });
+            }
+        }
+    }
+}

package/dist/daemon/review/finish.d.ts

@@ -40,8 +40,13 @@ export declare function completeRequestedSubmit(reviewId: string, opts: {
 /** The companion's turn ended: complete any submit the human left waiting on
  *  it. Never throws — a settlement directive must not depend on delivery. */
 export declare function completeCompanionRequestedSubmit(companionNodeId: string): Promise<void>;
-/** Cancel an open review once; ticket cancellation remains owned by the retained human-ticket finisher. */
-export declare function cancelReview(reviewId: string, args: {
+/** `disposition` rides through to the ticket result: the recipient closing a
+ * review in their inbox is a dismissal, while the requester withdrawing it
+ * stays a cancellation. */
+export interface ReviewCancellationArgs {
     reason?: string;
     actor?: string;
-}): Promise<ReviewCancellationFinishOutcome>;
+    disposition?: 'canceled' | 'dismissed';
+}
+/** Cancel an open review once; ticket cancellation remains owned by the retained human-ticket finisher. */
+export declare function cancelReview(reviewId: string, args: ReviewCancellationArgs): Promise<ReviewCancellationFinishOutcome>;

package/dist/daemon/review/finish.js

@@ -9,6 +9,7 @@ import { readReviewSource } from '../../core/review/document.js';
 import { signalReviewActivity } from '../../core/review/signal.js';
 import { approveReviewLocked, cancelReviewRow, getReview, getReviewByCompanion, markDelivered, markDeliveryError, markProjected, markProjectionError, requestReviewSubmit, requireVisibleReview, } from '../../core/review/store.js';
 import { ReviewOperationError } from '../../core/review/types.js';
+import { cancelPendingEntries } from '../../core/feed/inbox.js';
 import { emitEvent } from '../../core/events/emit.js';
 import { retireCompanion } from '../companion-retire.js';
 import { deliverNodeMessage } from '../messaging/node-message.js';
@@ -68,6 +69,7 @@ async function serializedFinish(reviewId, work) {
     }
 }
 async function finishApproved(review, result) {
+    retractSubmitQueuedNote(review);
     let current = requireVisibleReview(review.review_id);
     if (current.projected_at === null) {
         try {
@@ -93,6 +95,7 @@ async function finishApproved(review, result) {
     return requireVisibleReview(review.review_id);
 }
 async function finishCanceled(review, winningWrite, args) {
+    retractSubmitQueuedNote(review);
     let current = requireVisibleReview(review.review_id);
     let canceledTicket;
     if (current.origin_kind === 'inline') {
@@ -153,6 +156,21 @@ async function finishCanceled(review, winningWrite, args) {
     await retireCompanion(current.companion_node_id, 'canceled');
     return { record: requireVisibleReview(review.review_id), ...(canceledTicket === undefined ? {} : { ticket_result: canceledTicket }) };
 }
+const SUBMIT_QUEUED_NOTE = 'review-submit-queued';
+/** Retract an undelivered queued-submit note once the review is settling. The
+ *  note rides the deferred tier and so does not wake the origin, while the
+ *  terminal result goes live — without this the origin reads "result to
+ *  follow" only after it already acted on that result. */
+function retractSubmitQueuedNote(review) {
+    try {
+        cancelPendingEntries(review.origin_node_id, (entry) => entry.kind === 'message'
+            && entry.data?.['note'] === SUBMIT_QUEUED_NOTE
+            && entry.data?.['review_id'] === review.review_id);
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'review.submit_queued_note.retract_failed', error });
+    }
+}
 /** Tell the origin its review was submitted but is finishing behind the
  *  companion. Deliberately deferred: the origin is told nothing is needed of
  *  it, so waking it to say so would be noise. The approval itself wakes it. */
@@ -163,7 +181,7 @@ async function noteSubmitQueued(review) {
             from: 'crtrd',
             mode: 'quiet',
             label: 'human review submitted — result to follow',
-            data: { review_id: review.review_id },
+            data: { review_id: review.review_id, note: SUBMIT_QUEUED_NOTE },
             runtime: { kind: 'review-queued', facts: {} },
             body: `The human submitted their review of \`${review.file}\`; the document is still being edited. `
                 + "You'll be notified with the result once the review completes. Nothing is needed from you now.",

package/dist/types.d.ts

@@ -231,6 +231,10 @@ export interface PageComponentRegistration {
     /** A display-only product slot contributes no page response. */
     display?: boolean;
 }
+export interface HumanActionConfig {
+    argv: string[];
+    cwd: string;
+}
 /** The normalized product component catalog used to validate page slots. */
 export type ProductPageComponents = readonly PageComponentRegistration[];
 export interface ScopeConfig {
@@ -344,6 +348,10 @@ export interface ScopeConfig {
      *  the trusted local binary is materialized into the PATH-prepended shim dir
      *  by `core/runtime/bin-contributions.ts`. */
     bin?: Record<string, string>;
+    /** Named completion commands. Project scopes nearest to a creator's cwd
+     *  outrank farther project scopes, then user scope; plugins and profiles do
+     *  not contribute. Paths resolve against the declaring scope's authoring root. */
+    humanActions: Record<string, HumanActionConfig>;
 }
 /** One remote canvas target: where to relay-attach and how to find its
  *  bearer token. The token itself is NEVER stored here — only a ref into the

package/dist/types.js

@@ -103,6 +103,7 @@ export function defaultScopeConfig() {
         remoteCanvas: defaultRemoteCanvasConfig(),
         spawnEnv: { allow: [] },
         bin: {},
+        humanActions: {},
     };
 }
 /** No remote canvas targets are configured out of the box — every one is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.221",
+  "version": "0.3.223",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.221",
+  "version": "0.3.223",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.221",
+      "version": "0.3.223",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {