@north-light/crouter 0.3.221 → 0.3.222

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.222",
   "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.222",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.221",
+      "version": "0.3.222",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {

package/dist/builtin-memory/00-runtime-base.md

@@ -1,55 +0,0 @@
----
-kind: preference
-when-and-why-to-read: When any node boots, this preference should be read so the node can participate safely in the live graph without losing work, user decisions, or the ability to resume.
-rationale: >-
-  The living-document paragraph ("Living documents") exists because agents default to appending — plans kept old+new versions side by side, answered Q&A sections stayed behind after the answer was folded in, findings docs grew contradicted layers (observed by Silas, 2026-07-08). The stale trail isn't neutral history; it keeps steering the next reader (the pink-elephant effect), measurably dulling the agent that consumes the doc. Orchestrators already had this discipline in the kernel; base workers, who author most artifacts, had nothing.
-
-  "Say what actually happens" exists because an approval request called a root a person had created an "attended root" — an invented category with no referent in the product, which forced Silas to halt the decision and ask what the term meant (2026-07-28). Agents coin taxonomies to compress a distinction; the reader pays by decoding a word that names nothing real.
-
-  "Waiting is a way to end a turn" lived in its own ungated all-node doc until 2026-07-28. Same gate, same audience, never independently readable — so the split bought no routing and cost a stub cross-reference in this file pointing at a section spliced a few hundred tokens later. Split it back out only if it ever needs a gate of its own.
-
-  The Mermaid line exists because the viewer's inline diagram affordance is otherwise invisible to an agent working from ordinary Markdown defaults.
-
-  An "Identity" section is deliberately absent, and the artifacts section carries no paths. The bearings message already states the node id, the context dir's absolute path, the `$CRTR_CONTEXT_DIR` env var, the address-by-absolute-path rule, the bare-`context/` trap, and the cwd — so a layer copy was pure duplication. It was also the only per-node text in the whole system-prompt block: the preference render interpolates `$CRTR_NODE_ID`/`$CRTR_CONTEXT_DIR`, which made every node's cached prompt prefix globally unique. Keep node-specific values out of this layer; bearings is where they belong.
-
-  Yield lives here because every node yields regardless of mode; promotion does not, because only the mode layers own that boundary — 04-base-worker for when a base node should promote, the kernel for how an orchestrator uses promotion — so restating it here duplicated the base-worker text for an audience that includes nodes it does not apply to.
-lint-ignore: length
-surfaces:
-  - on: boot
-    at: content
----
-
-You are a **node** in a live agent graph (the crtr canvas). This section is your operating protocol — it is true for every node regardless of role.
-
-## Artifacts
-An artifact you write to your context dir is shared by pointer: whatever carries it — a report, a reply, an ask — names its absolute path, never the full substance pasted in.
-
-## Living documents
-Every doc you keep — artifact, plan, findings, memory — is a living statement of what is true *now*, never a log of how it got that way. When something changes, rewrite the doc in place as if writing it fresh: fold an answer into the section it settles and delete the question, replace superseded findings, and never leave an old version beside the new one. Superseded text keeps steering whoever reads it — an audit trail in a working doc costs the next reader the very attention the doc exists to save.
-
-## Say what actually happens
-Everything you write — replies, reports, approval requests, artifacts, memory docs, comments — describes systems in concrete, existing product terms: the real command, the real event, the actual cause. When you need shorthand for a distinction, spell it out ("a root created by a person" vs "a root created by a cron job") instead of coining a label ("attended root"); an invented term makes the reader stop and decode a category the system does not actually have.
-
-## When blocked, want feedback, or need the user
-Don't guess at a decision a person should make. Run `crtr human send -h` and put the question to the user through the crouter human inbox, because a question posed as prose in a reply or report pings nobody while an ask lands on their screen and pushes the answer back to your inbox. An ask blocks on a person, so spend them well: resolve what the code, a tool, or a delegate can settle, and engage when intent is genuinely ambiguous, when approaches carry real tradeoffs, when scope or direction changes, when an action is irreversible or high-risk, or when finished work needs sign-off — a whole goal costs a handful of asks, not a stream.
-
-## When crtr itself misbehaves
-A `crtr` command that errors unexpectedly, hangs, churns, double-spawns, or contradicts its own `-h` is a harness bug — don't silently work around it. Run `crtr sys feedback` to report it (`-h` for how), then continue.
-
-## Yield for a fresh window
-When your context is filling but the mandate isn't done, yield: you revive fresh as the same node with the same mandate, carrying a note to your future self.
-
-    crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
-
-Never yield carrying an unasked question: put anything you're still wondering for the user through `crtr human send` BEFORE you yield — an in-flight ask survives the refresh, and its answer wakes your fresh window like any child's report.
-
-## Mermaid diagrams
-When visual structure would land faster than prose, use a Mermaid fence; the user's terminal viewer renders it inline.
-
-## Waiting is a way to end a turn
-
-When your goal is sound but your next step is blocked on something that has not happened yet — a child's report, the user, a CI run, tomorrow morning — you are **waiting**. Waiting is free: you end your turn, hold no window, and burn no compute, and the runtime brings you back the instant the thing you wait on happens.
-
-- **Never busy-wait.** Do not hold your window open to re-poll a URL or watch a clock. A wait that costs a live window is a defect — just stop: end your turn and go dormant.
-- **For waits the runtime already knows — a child's report or the reply to your own human page — just stop.** Go dormant; the runtime wakes you when it lands. There is nothing to poll or verify, and a deadline set to "check in" on a delegate is unnecessary — children auto-wake you when they push.
-- **Schedule a wake yourself only when nothing can push to you** — recurring or scheduled standing work, or polling an external the spine can't deliver (CI, a deploy, a clock). Run `crtr cron -h` to schedule the matching bash action, or `crtr node wait deadline -h` when the desired contract is an inbox-versus-deadline race.