@north-light/crouter 0.3.179 → 0.3.181

package/dist/daemon/reconcilers/pending-review-submit.js

@@ -0,0 +1,35 @@
+// The safety net under a deferred review submit.
+//
+// The companion's turn end is what normally completes a submit the human left
+// waiting (`daemon/api/handlers/broker-ops.ts`). A companion that crashed, was
+// torn down, or ended its turn while this daemon was starting never delivers
+// that settlement, so this pass completes any review whose companion is no
+// longer working. Without it a review could wait forever on a turn end that is
+// never coming.
+import { emitEvent } from '../../core/events/emit.js';
+import { operationIdContext } from '../../core/events/operation-id.js';
+import { listSubmitRequestedReviews } from '../../core/review/store.js';
+import { completeRequestedSubmit } from '../review/finish.js';
+export class PendingReviewSubmitReconciler {
+    run(ctx) {
+        if (!ctx.lifecycle.acceptsDetachedWork())
+            return;
+        let pending;
+        try {
+            pending = listSubmitRequestedReviews();
+        }
+        catch (error) {
+            operationIdContext.fresh(() => {
+                emitEvent({ level: 'error', event: 'review.deferred_submit.scan_failed', error });
+            });
+            return;
+        }
+        for (const review of pending) {
+            ctx.lifecycle.registerDetached(completeRequestedSubmit(review.review_id, { atCompanionTurnEnd: false }).then(() => { }, (error) => {
+                operationIdContext.fresh(() => {
+                    emitEvent({ level: 'error', event: 'review.deferred_submit.failed', error });
+                });
+            }));
+        }
+    }
+}

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

@@ -0,0 +1,8 @@
+/** Is the companion inside a turn right now? */
+export declare function companionMidTurn(nodeId: string): boolean;
+/** Does the companion hold work it has not yet consumed? A deferred entry is
+ *  excluded for the same reason the settlement policy excludes it: it never
+ *  starts a turn of its own. */
+export declare function companionHasQueuedWork(nodeId: string): boolean;
+/** Would submitting right now step on the companion's work? */
+export declare function companionStillWorking(nodeId: string): boolean;

package/dist/daemon/review/companion.js

@@ -0,0 +1,35 @@
+// Is a review companion still working? This is what a deferred submit waits on.
+//
+// Two facts, both already maintained by the runtime, and neither one enough
+// alone:
+//
+//  - MID-TURN — the `<jobDir>/busy` marker AND-ed with a live broker pid, the
+//    canonical "pi is inside a turn" signal (`core/runtime/busy.ts`). A stale
+//    marker from a crashed broker reads false through the AND.
+//  - QUEUED — an undelivered non-deferred inbox entry. Comments are pushed to
+//    the companion as inbox messages, so the ordinary rhythm is: the human
+//    comments, the entry lands, the companion's turn starts a moment later.
+//    Between those two moments the busy marker is cold while the companion is
+//    unmistakably about to work, and submitting into that gap kills the edit
+//    the wait exists to protect.
+import { getNode } from '../../core/canvas/canvas.js';
+import { isPidAlive } from '../../core/canvas/pid.js';
+import { readCursor, readInboxSince } from '../../core/feed/inbox.js';
+import { isBusy } from '../../core/runtime/busy.js';
+/** Is the companion inside a turn right now? */
+export function companionMidTurn(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null || !isPidAlive(node.pi_pid))
+        return false;
+    return isBusy(nodeId);
+}
+/** Does the companion hold work it has not yet consumed? A deferred entry is
+ *  excluded for the same reason the settlement policy excludes it: it never
+ *  starts a turn of its own. */
+export function companionHasQueuedWork(nodeId) {
+    return readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred');
+}
+/** Would submitting right now step on the companion's work? */
+export function companionStillWorking(nodeId) {
+    return companionMidTurn(nodeId) || companionHasQueuedWork(nodeId);
+}

package/dist/daemon/review/deliver.js

@@ -1,4 +1,5 @@
 import { FinalizationError, pushFinal, redeliverFinalReport } from '../../core/feed/feed.js';
+import { formatReviewApproval } from '../../shared/generated-context.js';
 import { deliverNodeMessage } from '../messaging/node-message.js';
 function approvalBody(review, resultPath) {
     const summary = review.changed
@@ -8,7 +9,7 @@ function approvalBody(review, resultPath) {
 }
 /** Render the immutable approval fact without replaying comment text. */
 export function renderApprovalMessage(review, resultPath) {
-    return approvalBody(review, resultPath);
+    return formatReviewApproval(approvalBody(review, resultPath));
 }
 function recordedFailedFanout(review, reportBasename) {
     const error = review.delivery_error;

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

@@ -5,6 +5,13 @@ export interface ReviewApprovalFinishOutcome {
     record: ReviewRecord;
     result: ReviewResult;
 }
+/** The human submitted while the companion was still working. The review stays
+ *  open and the daemon completes the approval once the companion goes quiet. */
+export interface ReviewSubmitDeferredOutcome {
+    outcome: 'awaiting_companion';
+    record: ReviewRecord;
+}
+export type ReviewSubmitOutcome = ReviewApprovalFinishOutcome | ReviewSubmitDeferredOutcome;
 export interface ReviewCancellationFinishOutcome {
     outcome: 'settled' | 'already_settled';
     record: ReviewRecord;
@@ -13,8 +20,28 @@ export interface ReviewCancellationFinishOutcome {
 export type ReviewFinishOutcome = ReviewApprovalFinishOutcome | ReviewCancellationFinishOutcome;
 /** Retire a companion only through a lifecycle transition legal for its current status. */
 export declare function retireCompanion(nodeId: string, outcome: 'approved' | 'canceled'): 'retired' | 'already' | 'missing';
-/** Commit approval once, then independently finish its projection, delivery, and companion retirement ledgers. */
-export declare function submitReviewApproval(reviewId: string): Promise<ReviewApprovalFinishOutcome>;
+/** Approve on the human's behalf, waiting first when the companion is still
+ *  working. Waiting is the only new outcome: an idle companion approves in the
+ *  same pass it always did, and the wait never freezes the review — comments
+ *  added during it are in the snapshot, because the snapshot happens at
+ *  completion and the review is still open. */
+export declare function submitReviewApproval(reviewId: string): Promise<ReviewSubmitOutcome>;
+/** Complete a submit the human already pressed, once its companion is quiet.
+ *  Returns null when there is nothing to complete — no pending intent, the
+ *  review moved on, or the companion is still working. Idempotent: concurrent
+ *  callers race on the same conditional `state = 'open'` approval write, so
+ *  only one can win and the loser reports what the winner committed.
+ *
+ *  `atCompanionTurnEnd` marks the one caller that IS the companion's turn end.
+ *  There the mid-turn marker may not be cleared yet, so it is not consulted;
+ *  queued work still defers, because an inbox entry means another turn is
+ *  coming and the wait should outlast it. */
+export declare function completeRequestedSubmit(reviewId: string, opts: {
+    atCompanionTurnEnd: boolean;
+}): Promise<ReviewApprovalFinishOutcome | null>;
+/** 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: {
     reason?: string;

package/dist/daemon/review/finish.js

@@ -8,11 +8,14 @@ import { reviewResultPath } from '../../core/canvas/paths.js';
 import { snapshotCommentsLocked } from '../../core/review/comments.js';
 import { readReviewSource } from '../../core/review/document.js';
 import { signalReviewActivity } from '../../core/review/signal.js';
-import { approveReviewLocked, cancelReviewRow, markDelivered, markDeliveryError, markProjected, markProjectionError, requireVisibleReview, } from '../../core/review/store.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 { transition } from '../../core/runtime/lifecycle.js';
 import { headlessBrokerHost } from '../../core/runtime/host.js';
+import { emitEvent } from '../../core/events/emit.js';
+import { deliverNodeMessage } from '../messaging/node-message.js';
 import { cancelHumanTicket, deliverTerminalResult } from '../human/finish.js';
+import { companionHasQueuedWork, companionMidTurn, companionStillWorking } from './companion.js';
 import { deliverApproval } from './deliver.js';
 /** One daemon serializes terminal side effects for each immutable review row. */
 const finishChains = new Map();
@@ -178,9 +181,46 @@ async function finishCanceled(review, winningWrite, args) {
     retireCompanion(current.companion_node_id, 'canceled');
     return { record: requireVisibleReview(review.review_id), ...(canceledTicket === undefined ? {} : { ticket_result: canceledTicket }) };
 }
-/** Commit approval once, then independently finish its projection, delivery, and companion retirement ledgers. */
+/** 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. */
+async function noteSubmitQueued(review) {
+    try {
+        await deliverNodeMessage({
+            node_id: review.origin_node_id,
+            from: 'crtrd',
+            mode: 'quiet',
+            label: 'human review submitted — result to follow',
+            data: { review_id: review.review_id },
+            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.",
+        });
+    }
+    catch (error) {
+        emitEvent({ level: 'warn', event: 'review.submit_queued_note.failed', error });
+    }
+}
+/** Approve on the human's behalf, waiting first when the companion is still
+ *  working. Waiting is the only new outcome: an idle companion approves in the
+ *  same pass it always did, and the wait never freezes the review — comments
+ *  added during it are in the snapshot, because the snapshot happens at
+ *  completion and the review is still open. */
 export async function submitReviewApproval(reviewId) {
     const initial = requireVisibleReview(reviewId);
+    if (initial.state === 'canceled')
+        return terminalConflict(initial, 'submit');
+    if (initial.state === 'open' && companionStillWorking(initial.companion_node_id)) {
+        if (requestReviewSubmit(reviewId, now())) {
+            signalReviewActivity();
+            await noteSubmitQueued(initial);
+        }
+        return { outcome: 'awaiting_companion', record: requireVisibleReview(reviewId) };
+    }
+    return await approveReview(initial);
+}
+/** Commit approval once, then independently finish its projection, delivery, and companion retirement ledgers. */
+async function approveReview(initial) {
+    const reviewId = initial.review_id;
     if (initial.state === 'canceled')
         return terminalConflict(initial, 'submit');
     if (initial.state === 'approved') {
@@ -219,6 +259,39 @@ export async function submitReviewApproval(reviewId) {
     const record = await serializedFinish(reviewId, () => finishApproved(committed.review, committed.result));
     return { outcome: committed.outcome, record, result: committed.result };
 }
+/** Complete a submit the human already pressed, once its companion is quiet.
+ *  Returns null when there is nothing to complete — no pending intent, the
+ *  review moved on, or the companion is still working. Idempotent: concurrent
+ *  callers race on the same conditional `state = 'open'` approval write, so
+ *  only one can win and the loser reports what the winner committed.
+ *
+ *  `atCompanionTurnEnd` marks the one caller that IS the companion's turn end.
+ *  There the mid-turn marker may not be cleared yet, so it is not consulted;
+ *  queued work still defers, because an inbox entry means another turn is
+ *  coming and the wait should outlast it. */
+export async function completeRequestedSubmit(reviewId, opts) {
+    const review = getReview(reviewId);
+    if (review === null || review.state !== 'open' || review.submit_requested_at === null)
+        return null;
+    if (companionHasQueuedWork(review.companion_node_id))
+        return null;
+    if (!opts.atCompanionTurnEnd && companionMidTurn(review.companion_node_id))
+        return null;
+    return await approveReview(review);
+}
+/** 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 async function completeCompanionRequestedSubmit(companionNodeId) {
+    try {
+        const review = getReviewByCompanion(companionNodeId);
+        if (review === null || review.state !== 'open' || review.submit_requested_at === null)
+            return;
+        await completeRequestedSubmit(review.review_id, { atCompanionTurnEnd: true });
+    }
+    catch (error) {
+        emitEvent({ level: 'error', event: 'review.deferred_submit.failed', error });
+    }
+}
 /** Cancel an open review once; ticket cancellation remains owned by the retained human-ticket finisher. */
 export async function cancelReview(reviewId, args) {
     const initial = requireVisibleReview(reviewId);

package/dist/shared/generated-context.d.ts

@@ -20,6 +20,8 @@ export declare const CONNECTION_FAULT_RECOVERY_BODY = "The network connection is
 export declare const PROVIDER_FAULT_RECOVERY_BODY = "Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.";
 /** Mark an active persona transition without changing the guidance inside it. */
 export declare function formatPersonaTransition(guidance: string): string;
+/** Mark a daemon-delivered review approval for compact viewer presentation. */
+export declare function formatReviewApproval(body: string): string;
 /** Format the stop guard's dynamic structured-output mandate. */
 export declare function formatStructuredOutputReprompt(schema: string): string;
 export type ModelFallbackRecoveryReason = 'credential' | 'not-found';
@@ -31,15 +33,12 @@ export interface GeneratedContextMessageLike {
     content?: unknown;
 }
 export interface GeneratedContextPresentation {
-    kind: 'bearings' | 'situational' | 'revive' | 'context-nudge' | 'inbox' | 'persona-transition' | 'stop-guard' | 'recovery';
+    kind: 'bearings' | 'situational' | 'revive' | 'context-nudge' | 'inbox' | 'review-approval' | 'persona-transition' | 'stop-guard' | 'recovery';
     label: string;
     summary: string;
     /** The unmodified, model-visible message content. */
     body: string;
 }
-/** The display-only disclosure body for a generated context card. The full
- * message remains in `body` for the model and transcript bookkeeping; the two
- * prompt-sized cards expose the one piece a person needs to inspect. */
 export declare function generatedContextExpandedBody(presentation: GeneratedContextPresentation): string;
 /** Plain text from a generated message's string or text-block content. */
 export declare function generatedContextText(message: GeneratedContextMessageLike): string;

package/dist/shared/generated-context.js

@@ -31,6 +31,8 @@ export const CONNECTION_FAULT_RECOVERY_BODY = 'The network connection is back on
 export const PROVIDER_FAULT_RECOVERY_BODY = 'Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.';
 const PERSONA_TRANSITION_OPEN = '<persona-transition>';
 const PERSONA_TRANSITION_CLOSE = '</persona-transition>';
+const REVIEW_APPROVAL_OPEN = '<crtr-review-approval>';
+const REVIEW_APPROVAL_CLOSE = '</crtr-review-approval>';
 const MODEL_FALLBACK_RECOVERY_OPEN = '<model-fallback-recovery>';
 const MODEL_FALLBACK_RECOVERY_CLOSE = '</model-fallback-recovery>';
 const STRUCTURED_OUTPUT_REPROMPT_PREFIX = 'You must call the `submit` tool with a result matching the required schema before you can stop. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n';
@@ -39,6 +41,10 @@ const STRUCTURED_OUTPUT_REPROMPT_SUFFIX = '\n```';
 export function formatPersonaTransition(guidance) {
     return `${PERSONA_TRANSITION_OPEN}\n${guidance}\n${PERSONA_TRANSITION_CLOSE}`;
 }
+/** Mark a daemon-delivered review approval for compact viewer presentation. */
+export function formatReviewApproval(body) {
+    return `${REVIEW_APPROVAL_OPEN}\n${body}\n${REVIEW_APPROVAL_CLOSE}`;
+}
 /** Format the stop guard's dynamic structured-output mandate. */
 export function formatStructuredOutputReprompt(schema) {
     return `${STRUCTURED_OUTPUT_REPROMPT_PREFIX}${schema}${STRUCTURED_OUTPUT_REPROMPT_SUFFIX}`;
@@ -55,14 +61,18 @@ const YIELD_MESSAGE_BLOCK = /<yield-message>([\s\S]*?)<\/yield-message>/;
 /** The display-only disclosure body for a generated context card. The full
  * message remains in `body` for the model and transcript bookkeeping; the two
  * prompt-sized cards expose the one piece a person needs to inspect. */
+function unmarkReviewApprovals(body) {
+    return body.replaceAll(`${REVIEW_APPROVAL_OPEN}\n`, '').replaceAll(`\n${REVIEW_APPROVAL_CLOSE}`, '');
+}
 export function generatedContextExpandedBody(presentation) {
+    let body = presentation.body;
     if (presentation.label === 'crtr context') {
-        return AUTO_LOADED_CONTEXT_BLOCK.exec(presentation.body)?.[1]?.trim() ?? '';
+        body = AUTO_LOADED_CONTEXT_BLOCK.exec(body)?.[1]?.trim() ?? '';
     }
-    if (presentation.kind === 'revive') {
-        return YIELD_MESSAGE_BLOCK.exec(presentation.body)?.[1]?.trim() ?? '';
+    else if (presentation.kind === 'revive') {
+        body = YIELD_MESSAGE_BLOCK.exec(body)?.[1]?.trim() ?? '';
     }
-    return presentation.body;
+    return unmarkReviewApprovals(body);
 }
 /** Plain text from a generated message's string or text-block content. */
 export function generatedContextText(message) {
@@ -88,7 +98,9 @@ function nudgeSummary(body) {
 }
 // Stable header emitted by core/feed/inbox.ts coalesce(). Human-authored inbox
 // messages are deliberately delivered verbatim and never carry this header.
-const INBOX_HEADER_RE = /^From ([a-z0-9]+(?:-[a-z0-9]+)+|system|human) — (\d+) update/m;
+// Senders are node ids, the two reserved words, or the daemon itself (crtrd —
+// review notes and other daemon-originated node messages).
+const INBOX_HEADER_RE = /^From ([a-z0-9]+(?:-[a-z0-9]+)+|system|human|crtrd) — (\d+) update/m;
 export function isInboxDigest(text) {
     return INBOX_HEADER_RE.test(text);
 }
@@ -96,7 +108,7 @@ export function extractInboxSender(text) {
     return INBOX_HEADER_RE.exec(text)?.[1] ?? null;
 }
 function inboxSummary(body) {
-    const headers = [...body.matchAll(/^From ([a-z0-9]+(?:-[a-z0-9]+)+|system|human) — (\d+) update/gm)];
+    const headers = [...body.matchAll(/^From ([a-z0-9]+(?:-[a-z0-9]+)+|system|human|crtrd) — (\d+) update/gm)];
     if (headers.length === 0)
         return 'node update';
     const updates = headers.reduce((total, match) => total + Number(match[2] ?? 0), 0);
@@ -109,6 +121,9 @@ function inboxSummary(body) {
 function isPersonaTransition(body) {
     return body.startsWith(`${PERSONA_TRANSITION_OPEN}\n`) && body.endsWith(`\n${PERSONA_TRANSITION_CLOSE}`);
 }
+function isReviewApproval(body) {
+    return body.startsWith(`${REVIEW_APPROVAL_OPEN}\n`) && body.endsWith(`\n${REVIEW_APPROVAL_CLOSE}`);
+}
 function isStructuredOutputReprompt(body) {
     if (!body.startsWith(STRUCTURED_OUTPUT_REPROMPT_PREFIX) || !body.endsWith(STRUCTURED_OUTPUT_REPROMPT_SUFFIX)) {
         return false;
@@ -189,6 +204,9 @@ export function generatedContextPresentation(message) {
     if (isInboxDigest(body)) {
         return { kind: 'inbox', label: 'crtr inbox', summary: inboxSummary(body), body };
     }
+    if (isReviewApproval(body)) {
+        return { kind: 'review-approval', label: 'crtr review', summary: 'human review approved', body };
+    }
     if (isPersonaTransition(body)) {
         return {
             kind: 'persona-transition',

package/dist/types.d.ts

@@ -263,7 +263,6 @@ export interface ScopeState {
         last_updated?: string;
     }>;
     last_self_check?: string;
-    bootstrap_done?: boolean;
     /** The name of the remote canvas target `crtr canvas use` last selected
      *  (see `RemoteCanvasConfig`), or `null`/omitted for local. Read by
      *  `resolveCanvasSource` (`core/canvas/source.ts`) as the durable fallback

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.179",
+  "version": "0.3.181",
   "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.179",
+  "version": "0.3.181",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.179",
+      "version": "0.3.181",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {