@north-light/crouter 0.3.170 → 0.3.172

package/dist/daemon/crtrd.js

@@ -50,20 +50,22 @@ import { execFile } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { promisify } from 'node:util';
 import { crtrHome, nodeDir, jobDir, isSafeNodeId } from '../core/canvas/paths.js';
-import { listNodes, getRow, getNode, migrateLegacyPidIdentities, listFocuses, closeFocusRow, pruneToLimit, subscribersOf, reconcileFollowUpWork, reconcileVisualWork, } from '../core/canvas/index.js';
+import { listNodes, getRow, getNode, migrateLegacyPidIdentities, listFocuses, closeFocusRow, pruneToLimit, subscribersOf, } from '../core/canvas/index.js';
 import { fullName } from '../core/canvas/labels.js';
 import { transition } from '../core/runtime/lifecycle.js';
 import { isBusy, busySince } from '../core/runtime/busy.js';
 import { FAULT_QUIET_MS, readFault, recordFault } from '../core/runtime/fault.js';
 import { fanDoctrineWake } from '../core/runtime/close.js';
 import { createApiServer } from './api/server.js';
+import { reconcileUndeliveredTickets } from './human/sweep.js';
+import { sweepReviews } from './review/sweep.js';
 // Lean pidfile/liveness helpers now live in `pidfile.ts` (db-free, so the CLI
 // daemon front door can import them without reaching openDb). Imported here for
 // internal use and re-exported below to preserve the historical crtrd.ts
 // surface (tests, `commands/sys/daemon.ts`).
 import { pidfilePath } from './pidfile.js';
 export { readPidfile, isDaemonRunning } from './pidfile.js';
-import { globalHumanloopWarning } from '../core/runtime/package-health.js';
+import { rendererWarning } from '../core/runtime/package-health.js';
 import { DEFAULT_INTERVAL_MS } from './supervise-cadence.js';
 import { readConfig } from '../core/config.js';
 export { FAULT_QUIET_MS };
@@ -80,7 +82,7 @@ import { reviveNode } from '../core/runtime/revive.js';
 import { prewarmRecentRecipes, reapStaleSpares } from '../core/runtime/warm-pool.js';
 import { headlessBrokerHost } from '../core/runtime/host.js';
 import { reloadAuthLive } from '../core/runtime/auth-reload.js';
-import { DaemonFleet, reconcileFollowUpWorkOnCrash, retryResumeMode } from './fleet.js';
+import { DaemonFleet, retryResumeMode } from './fleet.js';
 export { retryResumeMode };
 import { appendControllerDeathNotice, readInboxSince, readCursor, } from '../core/feed/inbox.js';
 import { migrateLegacyInboxIdentities } from '../core/feed/inbox-migrate.js';
@@ -99,9 +101,6 @@ import { recoverStaleCronLeases, runDueCrons } from './cron-run.js';
 // `encoding`/`timeout`, same decisions made from stdout) — only the blocking
 // behavior changes.
 const execFileAsync = promisify(execFile);
-// surfaceBootFailure + reconcileFollowUpWorkOnCrash moved to ./fleet.js — the
-// fleet's exit-policy paths are their primary consumers; the surviving crtrd
-// passes import them back from there.
 // Count-based auto-prune of the canvas (pruneToLimit). The canvas grows
 // unbounded — the TTL `crtr canvas prune` is manual, so without this a long-lived
 // daemon's canvas accumulates thousands of terminal nodes, making every scan +
@@ -359,7 +358,7 @@ export async function runStartupRecoverySweep(fleet) {
     const thresholds = brokerThresholdsForDaemon();
     for (const row of rows) {
         if (row.kind === 'human')
-            continue; // humanloop bridge rows — never broker-hosted
+            continue; // human bridge rows — never broker-hosted
         if (fleet.size() >= thresholds.automaticReviveCap) {
             emitEvent({
                 level: 'warn',
@@ -915,7 +914,6 @@ function handleFatalFault(id, now) {
     if (terminalOverflow) {
         try {
             transition(id, 'crash');
-            reconcileFollowUpWorkOnCrash(id);
             headlessBrokerHost.teardown(id);
         }
         catch {
@@ -1275,10 +1273,9 @@ export async function superviseTick(now = Date.now(), lifecycle = directTickLife
         return;
     }
     // kind:'human' rows are NOT broker-hosted agent nodes — they are bookkeeping
-    // rows for the `crtr human` bridge. Their lifecycle is driven entirely by
-    // humanloop's registered `_deliver` handler — which pushFinals the answer when
-    // the human responds from the humanloop inbox — or by `human cancel`. They
-    // never launch a broker or record a `pi_session_id`, so the dead-node policy
+    // rows for the `crtr human` bridge. crtrd delivers their terminal ticket result
+    // with pushFinal when the person responds from crouter's inbox, or when `human cancel`
+    // publishes a cancellation. They never launch a broker or record a `pi_session_id`, so the dead-node policy
     // table would read every one as a never-booted broker (row 8) and crash it
     // with surfaceBootFailure — exactly the regression where a headless
     // orchestrator's `human ask` nodes all died at boot. The daemon must never
@@ -1433,7 +1430,6 @@ export async function superviseTick(now = Date.now(), lifecycle = directTickLife
                         },
                     });
                     transition(id, 'crash');
-                    reconcileFollowUpWorkOnCrash(id);
                     if (meta !== null) {
                         try {
                             fanDoctrineWake(id, subscribersOf(id), `Child crashed — ${fullName(meta)} (${id}) failed to relaunch after ${attempts} attempts while trying to ` +
@@ -1845,13 +1841,12 @@ export async function runDaemon(opts = {}) {
         operationIdContext.fresh(() => {
             emitEvent({ level: 'info', event: 'daemon.install_id.resolved', fields: { install_id: installId } });
         });
-        // The tmux inbox binding resolves a PATH-global `hl`, while crouter imports
-        // its bundled humanloop library. The health probe is advisory; setup repairs
-        // a stale executable without blocking supervision.
+        // The pinned termrender renderer is an advisory dependency; setup repairs
+        // an unprovisioned venv without blocking supervision.
         operationIdContext.fresh(() => {
             let warning;
             try {
-                warning = globalHumanloopWarning();
+                warning = rendererWarning();
             }
             catch {
                 return;
@@ -1860,25 +1855,14 @@ export async function runDaemon(opts = {}) {
                 emitEvent({
                     level: 'warn',
                     event: 'daemon.startup.warning',
-                    fields: { stage: 'global_humanloop', warning: warning.slice(0, 2_048) },
+                    fields: { stage: 'termrender', warning: warning.slice(0, 2_048) },
                 });
             }
         });
-        // Consult-outbox reconciliation is the startup crash-safety pass for
-        // pending delivery and armed forks that terminated before reporting.
-        operationIdContext.fresh(() => {
-            try {
-                reconcileFollowUpWork();
-                reconcileVisualWork();
-            }
-            catch (error) {
-                emitEvent({
-                    level: 'error',
-                    event: 'consult.outbox.reconcile_failed',
-                    error,
-                    fields: { phase: 'startup' },
-                });
-            }
+        // Complete ticket delivery before API traffic can observe terminal answers.
+        await operationIdContext.fresh(async () => {
+            await sweepReviews();
+            await reconcileUndeliveredTickets();
         });
         // Boot reconciliation clears stale process identities before any tick can
         // inspect them, then migrates legacy identities only with proven same-boot

package/dist/daemon/fleet.d.ts

@@ -9,13 +9,6 @@ import type { HostHandle } from '../core/runtime/host.js';
  *  urgent push so the parent learns the child failed to launch instead of just
  *  seeing a silent `dead`. */
 export declare function surfaceBootFailure(meta: NodeMeta): Promise<void>;
-/** Event-driven follow-up human-work settlement at daemon-detected node death
- *  (design-followup-consult-v2.md §B.4 step 4). Re-runs the consult-outbox
- *  reconcile scan right where the daemon first observes a death, so an `armed`
- *  row whose fork just died with no final report becomes the ticket's error
- *  result immediately. A no-op for every crash that isn't a consult/visual
- *  fork. Best-effort, mirrors the startup call's error handling. */
-export declare function reconcileFollowUpWorkOnCrash(id: string): void;
 /** Whether a dead relaunch should resume the saved session strictly, or retry
  *  as a fresh cycle instead. A cycling attempt (cycle_pending) that dies
  *  before session_start must retry AS a cycle — a strict reopen only restores
@@ -26,7 +19,7 @@ export declare function retryResumeMode(meta: Pick<NodeMeta, 'cycle_pending'> |
 export type DeadNodeAction = 'forget' | 'respawn-fresh' | 'dormant' | 'respawn-cycle' | 'respawn-resume' | 'boot-failure';
 /** The narrow durable state the policy table reads. Structural (a Pick, not
  *  NodeMeta itself) so tests fabricate table rows directly. */
-export type DeadNodeRow = Pick<NodeMeta, 'status' | 'intent' | 'pi_session_id' | 'cycle_pending' | 'private_fork_phase'>;
+export type DeadNodeRow = Pick<NodeMeta, 'status' | 'intent' | 'pi_session_id' | 'cycle_pending' | 'fork_from'>;
 /** One pure function producing the action for a node known-dead. Used at
  *  exactly two call sites — an exit-policy job and the startup recovery sweep
  *  (design D-12) — so exit recovery and startup recovery can never diverge.

package/dist/daemon/fleet.js

@@ -13,7 +13,7 @@
 // before every deliberate exit, and that durable state is robust to every kill
 // path. Codes/signals are logged for diagnostics only. The single timing
 // input is uptime, used only by the throttle.
-import { getNode, subscribersOf, reconcileFollowUpWork, reconcileVisualWork } from '../core/canvas/index.js';
+import { getNode, subscribersOf } from '../core/canvas/index.js';
 import { fullName } from '../core/canvas/labels.js';
 import { isSafeNodeId } from '../core/canvas/paths.js';
 import { transition } from '../core/runtime/lifecycle.js';
@@ -50,30 +50,6 @@ async function surfaceRecoveryFailure(meta, error) {
         `The node is now dead. Fix the recorded launch configuration, then revive it if the work still needs doing.`;
     await pushUrgent(meta.node_id, body, { from: meta.node_id });
 }
-/** Event-driven follow-up human-work settlement at daemon-detected node death
- *  (design-followup-consult-v2.md §B.4 step 4). Re-runs the consult-outbox
- *  reconcile scan right where the daemon first observes a death, so an `armed`
- *  row whose fork just died with no final report becomes the ticket's error
- *  result immediately. A no-op for every crash that isn't a consult/visual
- *  fork. Best-effort, mirrors the startup call's error handling. */
-export function reconcileFollowUpWorkOnCrash(id) {
-    try {
-        reconcileFollowUpWork();
-        reconcileVisualWork();
-    }
-    catch (err) {
-        emitEvent({
-            level: 'error',
-            event: 'consult.outbox.reconcile_failed',
-            ...(isSafeNodeId(id) ? { node_id: id } : {}),
-            error: err,
-            fields: {
-                phase: 'crash',
-                ...(isSafeNodeId(id) ? {} : { affected_node_id: id }),
-            },
-        });
-    }
-}
 /** Whether a dead relaunch should resume the saved session strictly, or retry
  *  as a fresh cycle instead. A cycling attempt (cycle_pending) that dies
  *  before session_start must retry AS a cycle — a strict reopen only restores
@@ -104,8 +80,8 @@ export function classifyDeadNode(row, busy, cleanAbort = false) {
         return 'respawn-cycle'; // row 6: dirty interrupted turn
     if (row.pi_session_id != null)
         return retryResumeMode(row, false) ? 'respawn-resume' : 'respawn-cycle'; // row 7
-    if (row.private_fork_phase === 'fork_pending')
-        return 'respawn-fresh'; // row 8: bounded fork-birth retry
+    if (row.fork_from != null && row.pi_session_id == null)
+        return 'respawn-fresh'; // row 8: bounded ordinary fork-birth retry
     return 'boot-failure'; // row 9
 }
 // ---------------------------------------------------------------------------
@@ -377,8 +353,7 @@ export class DaemonFleet {
         }
     }
     /** Terminal outcome shared by table row 8 and throttle exhaustion:
-     *  transition('crash') + consult-outbox reconcile + surfaceBootFailure +
-     *  doctrine wake, counter cleared. */
+     *  transition('crash') + surfaceBootFailure + doctrine wake, counter cleared. */
     async #terminalize(nodeId, meta, opts) {
         this.#clearThrottle(nodeId);
         emitEvent({
@@ -387,7 +362,6 @@ export class DaemonFleet {
             ...(isSafeNodeId(nodeId) ? { node_id: nodeId } : { fields: { affected_node_id: nodeId } }),
         });
         transition(nodeId, 'crash');
-        reconcileFollowUpWorkOnCrash(nodeId);
         try {
             await (opts.surface ?? (() => surfaceBootFailure(meta)))();
         }

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

@@ -0,0 +1,14 @@
+import type { InteractionResponse, TicketResult } from '../../core/human/types.js';
+/** Resolve a deck ticket under the store-owned claim-takeover lock boundary. */
+export declare function resolveDeckTicket(nodeId: string, responses: InteractionResponse[]): Promise<TicketResult>;
+/** Cancel a ticket with the store's first-writer-wins publication. */
+export declare function cancelHumanTicket(nodeId: string, opts: {
+    reason?: string;
+    actor?: string;
+}): Promise<TicketResult>;
+/**
+ * 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
+ * by a later resolve/cancel attempt or the daemon-start sweep.
+ */
+export declare function deliverTerminalResult(nodeId: string): Promise<boolean>;

package/dist/daemon/human/finish.js

@@ -0,0 +1,115 @@
+import { join } from 'node:path';
+import { ApiError } from '../../api/index.js';
+import { getNode, subscribersOf } from '../../core/canvas/canvas.js';
+import { ticketDir } from '../../core/human/root.js';
+import { cancelTicket, projectReviewOutput, readTicketResult, takeoverAndCompleteDeck, } from '../../core/human/tickets.js';
+import { readJson, responsePath } from '../../core/human/convention.js';
+import { appendInbox } from '../../core/feed/inbox.js';
+import { FinalDeliveryError, pushFinal } from '../../core/feed/feed.js';
+import { transition } from '../../core/runtime/lifecycle.js';
+function envelopeFromDeckResult(responses, summary, completedAt, resultPath) {
+    return { summary, responsePath: resultPath, schema: 'humanloop.response/v2', responses, completedAt };
+}
+function renderDeckAnswer(env) {
+    const summary = env.summary.trim();
+    const body = summary === '' ? '(the human submitted no answer text)' : summary;
+    return `${body}\n\nResponse metadata (question ids, selected options, timestamp): ${env.responsePath}`;
+}
+function deliveryFailed(error) {
+    // A canonical final is committed inside its own write boundary and can never
+    // be replayed (`already_finalized`), so a subscriber that missed the fanout
+    // stays missed. Say that rather than promising a retry that cannot happen.
+    if (error instanceof FinalDeliveryError) {
+        return new ApiError(500, 'delivery_failed', `The answer is recorded and the bridge node is finalized; its report is at ${error.reportPath}. Notifying ${error.failedTo.join(', ')} failed and will not be retried.`);
+    }
+    const detail = error instanceof Error ? error.message : String(error);
+    return new ApiError(500, 'delivery_failed', `The answer is recorded and delivery will be retried: ${detail}`);
+}
+async function deliverOrConflict(nodeId) {
+    try {
+        await deliverTerminalResult(nodeId);
+    }
+    catch (error) {
+        throw deliveryFailed(error);
+    }
+    throw new ApiError(409, 'ticket_already_resolved', 'ticket already resolved');
+}
+/** Resolve a deck ticket under the store-owned claim-takeover lock boundary. */
+export async function resolveDeckTicket(nodeId, responses) {
+    const completed = takeoverAndCompleteDeck(ticketDir(nodeId), responses, { host: 'crtrd', pid: process.pid });
+    if (!completed.won)
+        return deliverOrConflict(nodeId);
+    try {
+        await deliverTerminalResult(nodeId);
+    }
+    catch (error) {
+        throw deliveryFailed(error);
+    }
+    return completed.result;
+}
+/** Cancel a ticket with the store's first-writer-wins publication. */
+export async function cancelHumanTicket(nodeId, opts) {
+    const canceled = cancelTicket(ticketDir(nodeId), opts);
+    if (canceled.status === 'already_resolved')
+        return deliverOrConflict(nodeId);
+    try {
+        await deliverTerminalResult(nodeId);
+    }
+    catch (error) {
+        throw deliveryFailed(error);
+    }
+    return canceled.result;
+}
+/**
+ * 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
+ * by a later resolve/cancel attempt or the daemon-start sweep.
+ */
+export async function deliverTerminalResult(nodeId) {
+    const dir = ticketDir(nodeId);
+    const run = readJson(join(dir, 'run.json'));
+    if (run?.mode === 'notify')
+        return false;
+    const result = readTicketResult(dir);
+    if (result === null)
+        return false;
+    projectReviewOutput(dir);
+    const node = getNode(nodeId);
+    if (node === null || node.status === 'dead' || node.status === 'canceled' || (node.status === 'done' && node.final_report !== null)) {
+        return true;
+    }
+    if (result.kind === 'canceled') {
+        const note = result.reason !== undefined && result.reason !== '' ? ` — ${result.reason}` : '';
+        // One failing subscriber must not silence the rest, and the bridge stays
+        // live until every notice lands: a partial fanout leaves the ticket for the
+        // next resolve/cancel attempt or the daemon-start sweep to replay. A
+        // subscriber notified twice reads the same idempotent "no answer is coming";
+        // a subscriber never notified waits forever.
+        const failedTo = [];
+        for (const subscriber of subscribersOf(nodeId)) {
+            if (result.actor !== undefined && subscriber.node_id === result.actor)
+                continue;
+            try {
+                appendInbox(subscriber.node_id, {
+                    from: nodeId,
+                    tier: 'deferred',
+                    kind: 'message',
+                    label: `human interaction ${nodeId} canceled — no answer is coming${note}`,
+                    data: { body: `The human interaction ${nodeId} was canceled${note}. No response will arrive.` },
+                });
+            }
+            catch {
+                failedTo.push(subscriber.node_id);
+            }
+        }
+        if (failedTo.length > 0)
+            throw new Error(`cancellation notice failed for ${failedTo.join(', ')}`);
+        transition(nodeId, 'finish');
+        return true;
+    }
+    if (result.kind !== 'deck')
+        return true;
+    const envelope = envelopeFromDeckResult(result.responses, result.summary, result.completedAt, responsePath(dir));
+    await pushFinal(nodeId, renderDeckAnswer(envelope));
+    return true;
+}

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

@@ -0,0 +1,6 @@
+/** Deliver terminal ticket results left behind before their bridge could finish. */
+export declare function reconcileUndeliveredTickets(): Promise<{
+    scanned: number;
+    delivered: number;
+    failed: number;
+}>;

package/dist/daemon/human/sweep.js

@@ -0,0 +1,49 @@
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getNode } from '../../core/canvas/canvas.js';
+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 } from './finish.js';
+function isTerminalBridge(status) {
+    return status === 'done' || status === 'dead' || status === 'canceled';
+}
+/** Deliver terminal ticket results left behind before their bridge could finish. */
+export async function reconcileUndeliveredTickets() {
+    let scanned = 0;
+    let delivered = 0;
+    let failed = 0;
+    const root = ticketsRoot();
+    for (const entry of readdirSync(root)) {
+        try {
+            const dir = join(root, entry);
+            if (!statSync(dir).isDirectory())
+                continue;
+            scanned += 1;
+            if (readTicketResult(dir) === null)
+                continue;
+            // Canonical reviews own terminal delivery and bridge retirement. Their
+            // finisher retries only when its winning operation is explicitly repeated.
+            if (getReviewByBridge(entry) !== null)
+                continue;
+            const bridge = getNode(entry);
+            if (bridge === null || isTerminalBridge(bridge.status))
+                continue;
+            if (await deliverTerminalResult(entry))
+                delivered += 1;
+        }
+        catch (error) {
+            failed += 1;
+            emitEvent({
+                level: 'error',
+                event: 'human.delivery.reconcile_failed',
+                node_id: entry,
+                error,
+            });
+        }
+    }
+    const result = { scanned, delivered, failed };
+    emitEvent({ level: 'info', event: 'human.delivery.reconciled', fields: result });
+    return result;
+}

package/dist/daemon/messaging/node-message.d.ts

@@ -0,0 +1,18 @@
+export type NodeMessageMode = 'interactive' | 'wake' | 'quiet';
+export interface NodeMessageDelivery {
+    entry_id: string | null;
+    via: 'engine' | 'inbox';
+    revived: boolean;
+}
+/**
+ * Deliver one daemon-originated node message. Interactive messages use the live
+ * broker when available; every other successful path is a durable inbox entry.
+ */
+export declare function deliverNodeMessage(args: {
+    node_id: string;
+    body: string;
+    label: string;
+    from?: string | null;
+    mode: NodeMessageMode;
+    data?: Record<string, unknown>;
+}): Promise<NodeMessageDelivery>;

package/dist/daemon/messaging/node-message.js

@@ -0,0 +1,70 @@
+import { getNode } from '../../core/canvas/canvas.js';
+import { withFreshTerminalGuard } from '../../core/canvas/canvas.js';
+import { appendInbox } from '../../core/feed/inbox.js';
+import { BrokerUnreachableError } from '../../core/runtime/broker-request.js';
+import { deliverLive } from '../../core/runtime/interactive-deliver.js';
+import { isBrokerLive } from '../../core/runtime/model-swap.js';
+import { reviveNode } from '../../core/runtime/revive.js';
+import { hasNoNaturalCycle } from '../../core/runtime/revive-all.js';
+import { ReviewOperationError } from '../../core/review/types.js';
+function deliveryUnroutable(nodeId, reason) {
+    throw new ReviewOperationError('delivery_unroutable', reason === 'origin_missing' ? 'message target was not found' : 'message target has no natural delivery cycle', { node_id: nodeId, reason });
+}
+/** Run a fresh terminal guard before any delivery path, including live engine sends. */
+function guardRoutable(nodeId, body) {
+    const outcome = withFreshTerminalGuard(nodeId, hasNoNaturalCycle, body);
+    if (outcome.kind === 'missing')
+        deliveryUnroutable(nodeId, 'origin_missing');
+    if (outcome.kind === 'terminal')
+        deliveryUnroutable(nodeId, 'no_natural_cycle');
+    return outcome.result;
+}
+/**
+ * Deliver one daemon-originated node message. Interactive messages use the live
+ * broker when available; every other successful path is a durable inbox entry.
+ */
+export async function deliverNodeMessage(args) {
+    // A live interactive delivery has no durable append to guard, so establish
+    // routability first. The durable fallback below takes the guard again to
+    // close the race before its append.
+    guardRoutable(args.node_id, () => undefined);
+    let target = getNode(args.node_id);
+    if (target === null)
+        deliveryUnroutable(args.node_id, 'origin_missing');
+    if (args.mode === 'interactive' && isBrokerLive(target)) {
+        try {
+            await deliverLive(args.node_id, args.body);
+            // The broker acknowledgement is asynchronous to the SQLite guard. Recheck
+            // before reporting an engine receipt so a final that committed during the
+            // request is not represented as a routable delivery.
+            guardRoutable(args.node_id, () => undefined);
+            return { entry_id: null, via: 'engine', revived: false };
+        }
+        catch (error) {
+            if (!(error instanceof BrokerUnreachableError))
+                throw error;
+        }
+    }
+    const entry = guardRoutable(args.node_id, () => appendInbox(args.node_id, {
+        from: args.from ?? null,
+        tier: args.mode === 'quiet' ? 'deferred' : 'normal',
+        kind: 'message',
+        label: args.label,
+        data: { ...args.data, body: args.body },
+    }));
+    let revived = false;
+    if (args.mode !== 'quiet') {
+        target = getNode(args.node_id);
+        if (target === null)
+            deliveryUnroutable(args.node_id, 'origin_missing');
+        if (!isBrokerLive(target)) {
+            try {
+                revived = reviveNode(args.node_id, { resume: true }).launch !== undefined;
+            }
+            catch {
+                // The durable entry remains authoritative; one wake attempt is enough.
+            }
+        }
+    }
+    return { entry_id: entry.entry_id, via: 'inbox', revived };
+}

package/dist/daemon/review/comment-notify.d.ts

@@ -0,0 +1,26 @@
+import type { ReviewComment, ReviewRecord } from '../../core/review/types.js';
+export type DeliverMode = 'wake' | 'quiet';
+type CommentVerb = 'create' | 'edit' | 'resolve' | 'reopen' | 'delete';
+export interface CommentDelivery {
+    attempted: boolean;
+    target_node_id?: string;
+    status: 'delivered' | 'skipped' | 'failed';
+    via?: 'engine' | 'inbox';
+    woke: boolean;
+    error?: string;
+}
+/** Render the one bounded, durable comment notice delivered to a review companion. */
+export declare function renderCommentNotice(review: ReviewRecord, comment: ReviewComment, verb: CommentVerb): string;
+/**
+ * Best-effort post-commit notice for one review-comment mutation. Delivery and
+ * its audit are deliberately outside the comment's state transaction.
+ */
+export declare function notifyComment(args: {
+    review: ReviewRecord;
+    comment: ReviewComment;
+    verb: CommentVerb;
+    actor_node_id: string | null;
+    deliver: DeliverMode | undefined;
+    operation_id: string;
+}): Promise<CommentDelivery>;
+export {};

package/dist/daemon/review/comment-notify.js

@@ -0,0 +1,107 @@
+import { appendDeliveryEvent } from '../../core/review/comments.js';
+import { deliverNodeMessage } from '../messaging/node-message.js';
+function defaultDeliverMode(verb) {
+    switch (verb) {
+        case 'create':
+        case 'edit':
+        case 'reopen':
+            return 'wake';
+        case 'resolve':
+        case 'delete':
+            return 'quiet';
+    }
+}
+function range(comment) {
+    return comment.anchor.end_line > comment.anchor.line
+        ? `L${comment.anchor.line}-${comment.anchor.end_line}`
+        : `L${comment.anchor.line}`;
+}
+function quotedSource(comment) {
+    const quote = comment.anchor.quote;
+    return quote === undefined || quote === '' ? comment.anchor_line_text : quote;
+}
+function verbPastTense(verb) {
+    switch (verb) {
+        case 'create': return 'created';
+        case 'edit': return 'edited';
+        case 'resolve': return 'resolved';
+        case 'reopen': return 'reopened';
+        case 'delete': return 'deleted';
+    }
+}
+/** Render the one bounded, durable comment notice delivered to a review companion. */
+export function renderCommentNotice(review, comment, verb) {
+    return [
+        `Review comment ${comment.comment_id} was ${verbPastTense(verb)} in review ${review.review_id}.`,
+        '',
+        `File: ${review.file}`,
+        `Range: ${range(comment)}`,
+        'Quoted source:',
+        quotedSource(comment),
+        '',
+        'Comment:',
+        comment.text,
+    ].join('\n');
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Best-effort post-commit notice for one review-comment mutation. Delivery and
+ * its audit are deliberately outside the comment's state transaction.
+ */
+export async function notifyComment(args) {
+    if (args.actor_node_id === args.review.companion_node_id && args.deliver === undefined) {
+        return { attempted: false, status: 'skipped', woke: false };
+    }
+    const target_node_id = args.review.companion_node_id;
+    const mode = args.deliver ?? defaultDeliverMode(args.verb);
+    const body = renderCommentNotice(args.review, args.comment, args.verb);
+    let delivery;
+    try {
+        delivery = await deliverNodeMessage({
+            node_id: target_node_id,
+            body,
+            label: 'review comment',
+            from: 'crtrd',
+            mode: mode === 'wake' ? 'interactive' : 'quiet',
+            data: {
+                review_id: args.review.review_id,
+                comment_id: args.comment.comment_id,
+                verb: args.verb,
+            },
+        });
+    }
+    catch (error) {
+        const projection = {
+            attempted: true,
+            target_node_id,
+            status: 'failed',
+            woke: false,
+            error: errorMessage(error),
+        };
+        appendDeliveryEvent({
+            review_id: args.review.review_id,
+            comment_id: args.comment.comment_id,
+            kind: 'notify_failed',
+            payload: projection,
+            operation_id: args.operation_id,
+        });
+        return projection;
+    }
+    const projection = {
+        attempted: true,
+        target_node_id,
+        status: 'delivered',
+        via: delivery.via,
+        woke: delivery.revived,
+    };
+    appendDeliveryEvent({
+        review_id: args.review.review_id,
+        comment_id: args.comment.comment_id,
+        kind: 'notified',
+        payload: projection,
+        operation_id: args.operation_id,
+    });
+    return projection;
+}

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

@@ -0,0 +1,7 @@
+import type { ReviewRecord } from '../../core/review/types.js';
+/** Render the immutable approval fact without replaying comment text. */
+export declare function renderApprovalMessage(review: ReviewRecord, resultPath: string): string;
+/** Deliver an approval through its origin-specific canonical route. */
+export declare function deliverApproval(review: ReviewRecord, resultPath: string): Promise<{
+    receipt: string | null;
+}>;