@north-light/crouter 0.3.202 → 0.3.204

package/dist/commands/human/shared.d.ts

@@ -1,4 +1,5 @@
 export interface PageHelpText {
+    brief: string;
     authoring: string;
     componentSelection: readonly string[];
     pageHint: string;

package/dist/commands/human/shared.js

@@ -1,10 +1,15 @@
 import { readConfig } from '../../core/config.js';
 import { CORE_COMPONENT_SELECTION_LINES } from '../../core/human/component-docs.js';
+// The reader's missing context is the gap syntax cannot close: an inbox page
+// is opened away from the conversation that produced it, by someone who never
+// followed the work.
+const PAGE_BRIEF = 'Write the page for where it is read. A page projected to the inbox is opened away from this conversation by someone who has not followed the work, so it stands alone; an inline page can lean on what the conversation already said. Title names the topic; subtitle states the decision, your recommendation, and the stakes. Content carries only what is needed to decide, with the evidence behind it below the ask rather than ahead of it. Ask only what changes your next step, and offer only options you would actually take. A page that asks nothing states what happened and what it changes.';
 const PAGE_AUTHORING = 'Write one `.tsx` module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx` that default-exports a component whose root element is `<Page title="…" subtitle="…">`; a multi-step page puts its content in `<Step>` children. Or send a complete `.html` file with a nonempty `<title>`; HTML is delivered verbatim and collects no response. Delivery is chosen by `human send` flags, never a Page prop. Registry components and React are already in scope, so the module contains no `import` and no `require`. Full JS is yours: state, expressions, `.map` over your data, event handlers, plain elements with Tailwind classes. `usePageHost` is a reserved hook whose product-supplied members are opaque here. Never render submit or dismiss chrome — the host owns it. Display-only pages are first-class: a page with no questions may be sent without inbox or reply delivery. The module is compiled when you submit it and a compile error rejects the submit; there is no pre-check.';
 const DISPLAY_SET_LINE = 'The shadcn display set — `Card`, `Badge`, `Button`, `Table`, `Tabs`, `Separator`, `Alert`, `Progress`, `Accordion` and their parts — is in scope too, for presentation only.';
 /** The one page authoring model for `human -h`. */
 export function pageHelpText(pageSurface = false) {
     return {
+        brief: PAGE_BRIEF,
         authoring: pageSurface
             ? `Use inline pages as the default way to put structured or interactive content in front of the user; the environment renders rich components, so a page is not a special occasion. ${PAGE_AUTHORING}`
             : PAGE_AUTHORING,

package/dist/commands/human.js

@@ -36,6 +36,7 @@ export function registerHuman() {
             summary: concept,
             model: [
                 ticketModel,
+                pageHelp.brief,
                 pageHelp.authoring,
                 pageHelp.componentSelection.join('\n'),
                 'Props, response contracts, and the full component catalog: `crtr human components`.',

package/dist/core/__tests__/human-deliver.test.js

@@ -7,11 +7,14 @@ import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'no
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createApiServer } from '../../daemon/api/server.js';
-import { cancelHumanTicket, deliverTerminalResult, resolvePageTicket } from '../../daemon/human/finish.js';
+import { cancelHumanTicket, deliverTerminalResult, resolvePageTicket, settleFeedbackCompanion } from '../../daemon/human/finish.js';
 import { humanSend } from '../../commands/human/prompts.js';
 import { getNode, listNodes, closeDb } from '../canvas/index.js';
 import { readInboxSince } from '../feed/inbox.js';
+import { createPageFeedbackComment } from '../human/feedback.js';
 import { resolveRef } from '../canvas/history.js';
+import { transition } from '../runtime/lifecycle.js';
+import { reviveNode } from '../runtime/revive.js';
 import { apiSocketPath } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { bindTicketReplyRoute } from '../human/convention.js';
@@ -142,6 +145,36 @@ describe('terminal ticket delivery', () => {
         const finals = readInboxSince(parent).filter((entry) => entry.from === bridge && entry.kind === 'final');
         assert.equal(finals.length, 1, 'replay after a terminal bridge pushes nothing further');
     });
+    test('approved companions receive one canonical final while dismissed companions remain canceled', async () => {
+        const { bridge } = bridgeUnder();
+        const dir = submitBridgePage(bridge);
+        const companion = spawnNode({ kind: 'general', parent: bridge, cwd: home, name: 'feedback companion', lifecycle: 'resident' }).node_id;
+        createPageFeedbackComment(dir, { quote: 'Ship it?', note: 'Confirm the release.', companionNodeId: companion });
+        transition(companion, 'finish');
+        await resolvePageTicket(bridge, { question: { text: 'yes', edited: true } });
+        const finalized = getNode(companion);
+        assert.equal(finalized.status, 'done');
+        assert.equal(finalized.intent, 'done');
+        assert.ok(finalized.final_report);
+        assert.ok(finalized.finalized_at);
+        const finalReport = finalized.final_report;
+        const finalizedAt = finalized.finalized_at;
+        await deliverTerminalResult(bridge);
+        assert.equal(getNode(companion)?.final_report, finalReport, 'terminal replay preserves the first canonical final');
+        assert.equal(getNode(companion)?.finalized_at, finalizedAt, 'terminal replay preserves the first finalization time');
+        assert.throws(() => reviveNode(companion, { resume: true }), /finalization latch/);
+        const { bridge: dismissedBridge } = bridgeUnder();
+        const dismissedDir = submitBridgePage(dismissedBridge);
+        const dismissedCompanion = spawnNode({ kind: 'general', parent: dismissedBridge, cwd: home, name: 'dismissed feedback companion', lifecycle: 'resident' }).node_id;
+        createPageFeedbackComment(dismissedDir, { quote: 'Ship it?', note: 'Do not ship.', companionNodeId: dismissedCompanion });
+        await cancelHumanTicket(dismissedBridge, { reason: 'dismissed', actor: 'human' });
+        assert.equal(getNode(dismissedCompanion)?.status, 'canceled');
+        assert.equal(getNode(dismissedCompanion)?.final_report, null);
+        const dismissedResult = readTicketResult(dismissedDir);
+        await settleFeedbackCompanion(dismissedBridge, dismissedResult.kind === 'canceled' ? 'canceled' : 'approved');
+        assert.equal(getNode(dismissedCompanion)?.status, 'canceled');
+        assert.equal(getNode(dismissedCompanion)?.final_report, null);
+    });
     test('cancelHumanTicket finishes the bridge and notifies non-actor subscribers', async () => {
         const actor = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' }).node_id;
         const bridge = spawnNode({ kind: 'human', parent: actor, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;

package/dist/daemon/companion-retire.d.ts

@@ -1,2 +1,2 @@
-/** 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';
+/** Retire a companion only through the terminal transition legal for its current status. */
+export declare function retireCompanion(nodeId: string, outcome: 'approved' | 'canceled'): Promise<'retired' | 'already' | 'missing'>;

package/dist/daemon/companion-retire.js

@@ -3,25 +3,32 @@
 // can retire a feedback companion without importing the review finisher (which
 // itself imports human/finish.ts).
 import { getNode } from '../core/canvas/canvas.js';
+import { FinalizationError, pushFinal } from '../core/feed/feed.js';
 import { transition } from '../core/runtime/lifecycle.js';
 import { headlessBrokerHost } from '../core/runtime/host.js';
-/** Retire a companion only through a lifecycle transition legal for its current status. */
-export function retireCompanion(nodeId, outcome) {
+/** Retire a companion only through the terminal transition legal for its current status. */
+export async function retireCompanion(nodeId, outcome) {
     const node = getNode(nodeId);
     if (node === null)
         return 'missing';
-    if (node.status === 'done' || node.status === 'canceled')
+    if (node.status === 'canceled' || (outcome === 'canceled' && node.status === 'done'))
         return 'already';
-    if (outcome === 'approved' && (node.status === 'active' || node.status === 'idle')) {
-        transition(nodeId, 'finish');
+    if (outcome === 'approved' && (node.status === 'active' || node.status === 'idle' || node.status === 'done')) {
+        let result = 'retired';
+        try {
+            await pushFinal(nodeId, 'The companion conversation is complete.');
+        }
+        catch (error) {
+            if (!(error instanceof FinalizationError) || error.code !== 'already_finalized')
+                throw error;
+            result = 'already';
+        }
         try {
             headlessBrokerHost.teardown(nodeId);
         }
-        catch { /* the terminal transition is authoritative */ }
-        return 'retired';
+        catch { /* the canonical final is authoritative */ }
+        return result;
     }
-    // Cancellation is legal from every status. An already-dead companion cannot
-    // be finished, so it is retired as canceled even when approval won.
     transition(nodeId, 'cancel');
     if (node.status === 'active' || node.status === 'idle') {
         try {

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

@@ -1,10 +1,10 @@
 import type { TicketResult } from '../../core/human/types.js';
 /** Every ticket-ending action retires the ticket's feedback companion — done
- * when active or idle, never left resident. Idempotent and replay-safe; a
+ * with a canonical final when approved, never left resident. Idempotent and replay-safe; a
  * corrupt feedback file must not block result publication. Exported for the
  * daemon-start sweep, which must settle terminal tickets whether or not a
  * reply bridge exists. */
-export declare function settleFeedbackCompanion(ticketId: string): void;
+export declare function settleFeedbackCompanion(ticketId: string, outcome: 'approved' | 'canceled'): Promise<void>;
 /**
  * The one completion path for a page ticket: claim takeover, exclusive result
  * publication, then optional reply delivery. Every addressing surface routes

package/dist/daemon/human/finish.js

@@ -14,15 +14,15 @@ import { transition } from '../../core/runtime/lifecycle.js';
 import { emitEvent } from '../../core/events/emit.js';
 import { retireCompanion } from '../companion-retire.js';
 /** Every ticket-ending action retires the ticket's feedback companion — done
- * when active or idle, never left resident. Idempotent and replay-safe; a
+ * with a canonical final when approved, never left resident. Idempotent and replay-safe; a
  * corrupt feedback file must not block result publication. Exported for the
  * daemon-start sweep, which must settle terminal tickets whether or not a
  * reply bridge exists. */
-export function settleFeedbackCompanion(ticketId) {
+export async function settleFeedbackCompanion(ticketId, outcome) {
     try {
         const companionNodeId = readPageFeedback(ticketDir(ticketId)).companionNodeId;
         if (companionNodeId !== undefined)
-            retireCompanion(companionNodeId, 'approved');
+            await retireCompanion(companionNodeId, outcome);
     }
     catch (error) {
         emitEvent({ level: 'warn', event: 'human.feedback_companion.retire_failed', error });
@@ -155,7 +155,7 @@ export async function deliverTerminalResult(ticketId) {
     // through here, and an inbox-only page with no reply bridge still settles
     // its companion. The daemon-start sweep settles the tickets that die before
     // reaching this call.
-    settleFeedbackCompanion(ticketId);
+    await settleFeedbackCompanion(ticketId, result.kind === 'canceled' ? 'canceled' : 'approved');
     const replyRoute = readTicketReplyRoute(dir);
     if (replyRoute === null)
         return false;

package/dist/daemon/human/sweep.js

@@ -21,7 +21,8 @@ export async function reconcileUndeliveredTickets() {
             if (!statSync(dir).isDirectory())
                 continue;
             scanned += 1;
-            if (readTicketResult(dir) === null)
+            const ticketResult = readTicketResult(dir);
+            if (ticketResult === null)
                 continue;
             // Canonical reviews own terminal delivery and bridge retirement. Their
             // finisher retries only when its winning operation is explicitly repeated.
@@ -30,7 +31,7 @@ export async function reconcileUndeliveredTickets() {
             // A terminal page ticket retires its feedback companion whether or not a
             // reply bridge exists: inbox-only pages have no bridge row, yet the
             // daemon can die between result publication and companion retirement.
-            settleFeedbackCompanion(entry);
+            await settleFeedbackCompanion(entry, ticketResult.kind === 'canceled' ? 'canceled' : 'approved');
             // 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/review/finish.js

@@ -89,7 +89,7 @@ async function finishApproved(review, result) {
         }
     }
     current = requireVisibleReview(review.review_id);
-    retireCompanion(current.companion_node_id, 'approved');
+    await retireCompanion(current.companion_node_id, 'approved');
     return requireVisibleReview(review.review_id);
 }
 async function finishCanceled(review, winningWrite, args) {
@@ -150,7 +150,7 @@ async function finishCanceled(review, winningWrite, args) {
     current = requireVisibleReview(review.review_id);
     if (canceledTicket === undefined)
         canceledTicket = ticketResult(current);
-    retireCompanion(current.companion_node_id, 'canceled');
+    await retireCompanion(current.companion_node_id, 'canceled');
     return { record: requireVisibleReview(review.review_id), ...(canceledTicket === undefined ? {} : { ticket_result: canceledTicket }) };
 }
 /** Tell the origin its review was submitted but is finishing behind the

package/package.json

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