@north-light/crouter 0.3.198 → 0.3.200

package/dist/commands/dashboard.js

@@ -15,7 +15,7 @@ import { renderTreeFromSource, renderForestFromSource, dashboardRowsFromSource,
 export const dashboardLeaf = defineLeaf({
     name: 'dashboard',
     description: 'render the canvas as a subscription tree',
-    whenToUse: 'you want the whole graph at a glance as a rendered tree — the subscription forest drawn in ASCII so you can read its SHAPE: who reports to whom, how deep each branch runs, plus each node\'s status and context size. Scope to one root or show the full forest. Use `node inspect list` instead for a flat roster without the tree, `node inspect show` to drill into one node\'s neighbors, and `canvas attention` to find which nodes are blocked on a human',
+    whenToUse: 'you want the whole graph at a glance as a rendered tree — the subscription forest drawn in ASCII so you can read its SHAPE: who reports to whom, how deep each branch runs, plus each node\'s status and context size. Scope to one root or show the full forest. Use `node inspect list` instead for a flat roster without the tree, `node inspect show` to drill into one node\'s neighbors, and `canvas attention` to find which nodes are blocked on the user',
     help: {
         name: 'canvas dashboard',
         summary: 'render the canvas as an ASCII subscription tree — scoped to a root or the full forest',

package/dist/commands/human/{html.d.ts → components.d.ts}

@@ -1,2 +1,2 @@
 import { type BranchDef } from '../../core/command.js';
-export declare const humanHtml: BranchDef;
+export declare const humanComponents: BranchDef;

package/dist/commands/human/components.js

@@ -0,0 +1,77 @@
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { stateBlock } from '../../core/help.js';
+import { InputError } from '../../core/io.js';
+import { resolvePageComponents } from '../../core/config.js';
+import { componentNames, renderComponentCatalog, renderComponentContract } from '../../core/human/component-docs.js';
+function productComponents() {
+    return resolvePageComponents();
+}
+function componentNameState() {
+    const names = componentNames(productComponents());
+    return stateBlock('components', { count: names.length }, names.join(', '));
+}
+const humanComponentsList = defineLeaf({
+    name: 'list',
+    description: 'list page components for selection',
+    whenToUse: 'choosing which components to put in an authored page module.',
+    help: {
+        name: 'human components list',
+        summary: 'list page components for selection',
+        inputNote: 'No input parameters.',
+        output: [
+            { name: 'catalog', type: 'markdown', required: true, constraint: 'One concise selection entry per registry and product-registered component, grouped structural/response/display; no props or response schemas. A product component is written with the PascalCase tag derived from its registered kind.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Points to `crtr human components show <component>` for one selected component contract.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => ({
+        catalog: renderComponentCatalog(productComponents()),
+        follow_up: 'Use `crtr human components show <component>` for one component contract.',
+    }),
+    render: (result) => `${String(result['catalog'])}\n\n${String(result['follow_up'])}`,
+});
+const humanComponentsShow = defineLeaf({
+    name: 'show',
+    description: 'show one page component contract',
+    whenToUse: 'authoring one selected page component and needing its exact props, response contract, and shape in a page module.',
+    help: {
+        name: 'human components show',
+        summary: 'show one page component contract',
+        params: [
+            { kind: 'positional', name: 'component', type: 'string', required: true, constraint: 'Component name from the live <components> catalog below. Case-sensitive: registry components are PascalCase.' },
+        ],
+        output: [
+            { name: 'component', type: 'string', required: true, constraint: 'The selected component name.' },
+            { name: 'contract', type: 'markdown', required: true, constraint: 'Hand-written props, response contract, and authoring example for that component. A shadcn family (Card, CardHeader, …) shares one contract covering every member.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+        dynamicState: componentNameState,
+    },
+    run: async (input) => {
+        const component = input['component'];
+        const contract = renderComponentContract(component, productComponents());
+        if (contract === undefined) {
+            throw new InputError({
+                error: 'unknown_component',
+                message: `unknown page component "${component}"`,
+                field: 'component',
+                next: 'Run `crtr human components show -h` and choose a component from its live catalog.',
+            });
+        }
+        return { component, contract };
+    },
+    render: (result) => String(result['contract']),
+});
+export const humanComponents = defineBranch({
+    name: 'components',
+    description: 'discover page components and their contracts',
+    whenToUse: 'authoring a page module and choosing components, or needing one component’s exact props and response contract.',
+    help: {
+        name: 'human components',
+        summary: 'discover page components and their contracts',
+        model: 'These are the components already in scope in a page module — no import, ever. List is the selection catalog; show owns the full props, response contract, and authoring shape for one selected component.',
+    },
+    children: [humanComponentsList, humanComponentsShow],
+});

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

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const humanFeedbackBranch: BranchDef;

package/dist/commands/human/feedback.js

@@ -0,0 +1,108 @@
+// `crtr human feedback` — the feedback companion's surface for a page ticket's
+// feedback comments. list shows every item with its id and status; resolve is
+// the companion's terminal report that an open item has been dealt with.
+// Creating comments is the person's channel (the page surface); no agent
+// authors, edits, or deletes them.
+import { existsSync } from 'node:fs';
+import { ApiError } from '../../api/index.js';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { pageManifestPath } from '../../core/human/convention.js';
+import { opaqueInboxTicketId, ticketDir } from '../../core/human/root.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+/** Feedback tickets are addressed by the same raw ids as `human resolve`:
+ * the page_id from human send, which is also the ticket's directory name. */
+function requirePageTicketId(raw) {
+    const ticketId = raw;
+    if (!existsSync(pageManifestPath(ticketDir(ticketId)))) {
+        throw new InputError({ error: 'not_found', message: `no page ticket: ${ticketId}`, field: 'ticket_id', next: 'Pass the ticket id from your bearings, or a page ticket_id from `crtr human list`.' });
+    }
+    return ticketId;
+}
+const humanFeedbackList = defineLeaf({
+    name: 'list',
+    description: "list a page ticket's feedback comments",
+    whenToUse: 'you are the feedback companion for a page ticket and need each comment\'s id and open/resolved status.',
+    help: {
+        name: 'human feedback list',
+        summary: "every feedback comment on one page ticket, with ids and open/resolved status",
+        params: [
+            { kind: 'positional', name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id from your bearings (also the page_id from human send).' },
+        ],
+        output: [
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id.' },
+            { name: 'open_count', type: 'integer', required: true, constraint: 'How many comments remain open. Zero once feedback exists means all of it has been dealt with.' },
+            { name: 'comments', type: 'object[]', required: true, constraint: 'Each: {id, quote, context?, note, status, created_at, resolved_at?}; status is open or resolved. Oldest first.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const ticketId = requirePageTicketId(input['ticket_id']);
+        try {
+            const page = await cliClient().getHumanInboxPage(opaqueInboxTicketId(ticketId));
+            return { ticket_id: ticketId, open_count: page.feedback.open_count, comments: page.feedback.comments };
+        }
+        catch (e) {
+            rethrowAsCliError(e);
+        }
+    },
+});
+const humanFeedbackResolve = defineLeaf({
+    name: 'resolve',
+    description: 'mark one dealt-with feedback comment resolved',
+    whenToUse: 'you are the feedback companion and have dealt with an open comment — by revising the page or answering it in conversation.',
+    help: {
+        name: 'human feedback resolve',
+        summary: 'mark one open feedback comment resolved — terminal, and only after the feedback has actually been dealt with',
+        guide: 'Resolution is your report that the work is done, not a triage state: revise the page or answer the comment in conversation first, then resolve. It appends no chat turn — briefly report the result in the conversation yourself. A resolved comment never reopens; a renewed concern arrives as a new comment.',
+        params: [
+            { kind: 'positional', name: 'comment_id', type: 'string', required: true, constraint: 'A comment id from `crtr human feedback list`. The ticket is your own: it comes from the companion binding of the calling node.' },
+        ],
+        output: [
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call resolved the comment; false when it was already resolved.' },
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The page ticket id.' },
+            { name: 'comment_id', type: 'string', required: true, constraint: 'The comment id.' },
+            { name: 'open_count', type: 'integer', required: false, constraint: 'Comments still open after this resolution. Present when resolved is true.' },
+            { name: 'reason', type: 'string', required: false, constraint: 'comment_already_resolved when resolved is false.' },
+        ],
+        outputKind: 'object',
+        effects: ["Marks the comment resolved in your own ticket's feedback record — the ticket comes from the calling companion's binding. Only the ticket's bound companion may resolve — any other node refuses with not_companion. A terminal ticket refuses with ticket_terminal — settlement already closed this collaboration."],
+    },
+    run: async (input) => {
+        const commentId = input['comment_id'];
+        const callerNodeId = process.env['CRTR_NODE_ID'];
+        if (callerNodeId === undefined || callerNodeId === '') {
+            throw new InputError({ error: 'no_node', message: 'resolve runs inside the ticket\u2019s feedback companion (CRTR_NODE_ID unset)', next: 'Run this from the companion conversation bound to the ticket.' });
+        }
+        const binding = (await cliClient().getNode(callerNodeId)).review_binding;
+        if (binding === undefined || binding === null || binding.kind !== 'page_feedback') {
+            throw new InputError({ error: 'not_companion', message: 'this node is not a page-feedback companion — only the ticket\u2019s bound companion resolves its comments', next: 'Resolve from the companion conversation bound to the ticket.' });
+        }
+        const ticketId = requirePageTicketId(binding.review_id);
+        try {
+            const result = await cliClient().resolvePageFeedbackComment(opaqueInboxTicketId(ticketId), commentId, callerNodeId);
+            return { resolved: true, ticket_id: ticketId, comment_id: commentId, open_count: result.feedback.open_count };
+        }
+        catch (e) {
+            if (e instanceof ApiError && e.status === 409 && e.code === 'comment_already_resolved') {
+                return { resolved: false, ticket_id: ticketId, comment_id: commentId, reason: 'comment_already_resolved' };
+            }
+            rethrowAsCliError(e);
+        }
+    },
+    render: (r) => r['resolved'] === true
+        ? `Resolved feedback comment ${r['comment_id']} — ${r['open_count']} still open on ${r['ticket_id']}.`
+        : `Nothing to resolve for ${r['comment_id']} — ${r['reason']}.`,
+});
+export const humanFeedbackBranch = defineBranch({
+    name: 'feedback',
+    description: "operate on a page ticket's feedback comments",
+    whenToUse: "you are a feedback companion working a page ticket's feedback comments.",
+    help: {
+        name: 'human feedback',
+        summary: "a page ticket's feedback comments — the person creates them on the page; the bound companion lists and resolves them",
+        model: 'Each comment is immutable once sent and open until resolved. resolve is terminal and companion-only, taken after the feedback has been dealt with by revising the page or answering in conversation.',
+    },
+    children: [humanFeedbackList, humanFeedbackResolve],
+});

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

@@ -1,4 +1,4 @@
-import type { PageSource } from '../../core/human/page-schema.js';
+import { type PageSource } from '../../core/human/page-schema.js';
 /** Provenance for crouter tickets. Ticket *identity* comes from the bridge node
  * directory, never ticket data; `nodeId` carries the originating node so a
  * consumer can relate a ticket back to whatever that node belongs to, and
@@ -6,8 +6,16 @@ import type { PageSource } from '../../core/human/page-schema.js';
  * consumers resolve the applet or worker identity behind the ticket. Review
  * tickets stamp the same provenance (`core/review/realize.ts`), so pages match
  * them. `nodeId` is stamped even when the daemon is unreachable — losing the
- * labels is survivable, losing machine attribution is not. */
-export declare function sourceStamp(): Promise<PageSource>;
-export declare const humanAsk: import("../../core/command.js").LeafDef;
-export declare const humanNotify: import("../../core/command.js").LeafDef;
+ * labels is survivable, losing machine attribution is not.
+ *
+ * The same read answers who is sending: `lifecycle` decides whether the sender
+ * has a transcript a human is plausibly reading, which is what makes skipping
+ * the inbox safe. It is null for a bare shell (no node at all) and when the
+ * daemon cannot answer — neither is a terminal sender, so neither restricts
+ * delivery. */
+export declare function sender(): Promise<{
+    source: PageSource;
+    lifecycle: 'terminal' | 'resident' | null;
+}>;
+export declare const humanSend: import("../../core/command.js").LeafDef;
 export declare const humanShow: import("../../core/command.js").LeafDef;

package/dist/commands/human/prompts.js

@@ -1,16 +1,18 @@
 import { defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { cliClient } from '../api-client.js';
-import { extname, join } from 'node:path';
+import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { readConfig } from '../../core/config.js';
+import { resolvePageComponents } from '../../core/config.js';
 import { markStopSignal } from '../../core/runtime/stop-signals.js';
-import { atomicWriteJson } from '../../core/human/convention.js';
+import { bindTicketReplyRoute } from '../../core/human/convention.js';
 import { ticketDir } from '../../core/human/root.js';
-import { preparePage, publishPage } from '../../core/human/tickets.js';
-import { PageAuthoringError } from '../../core/human/page.js';
+import { preparePage, publishPage, readTicketResult } from '../../core/human/tickets.js';
+import { PageAuthoringError, parsePage } from '../../core/human/page.js';
+import { pageManifestPath } from '../../core/human/convention.js';
+import { isResponseBearingSlot, validateAuthoredPageManifest } from '../../core/human/page-schema.js';
 import { display } from '../../core/termrender/display.js';
 import { pageHelpText, resolveMaxPanes } from './shared.js';
 const PAGE_HELP = pageHelpText();
@@ -25,11 +27,17 @@ function askingNode() {
  * consumers resolve the applet or worker identity behind the ticket. Review
  * tickets stamp the same provenance (`core/review/realize.ts`), so pages match
  * them. `nodeId` is stamped even when the daemon is unreachable — losing the
- * labels is survivable, losing machine attribution is not. */
-export async function sourceStamp() {
+ * labels is survivable, losing machine attribution is not.
+ *
+ * The same read answers who is sending: `lifecycle` decides whether the sender
+ * has a transcript a human is plausibly reading, which is what makes skipping
+ * the inbox safe. It is null for a bare shell (no node at all) and when the
+ * daemon cannot answer — neither is a terminal sender, so neither restricts
+ * delivery. */
+export async function sender() {
     const nodeId = askingNode();
     if (nodeId === null || nodeId === '')
-        return {};
+        return { source: {}, lifecycle: null };
     try {
         const client = cliClient();
         const node = await client.getNode(nodeId);
@@ -38,28 +46,40 @@ export async function sourceStamp() {
             ? undefined
             : (await client.getProfile(node.profile_id)).name;
         return {
-            nodeId,
-            ...(sessionName === '' ? {} : { sessionName }),
-            ...(profileName === undefined ? {} : { profileName }),
+            source: {
+                nodeId,
+                ...(sessionName === '' ? {} : { sessionName }),
+                ...(profileName === undefined ? {} : { profileName }),
+            },
+            lifecycle: node.lifecycle,
         };
     }
     catch {
-        return { nodeId };
+        return { source: { nodeId }, lifecycle: null };
     }
 }
-function pageDialect(sourceFile) {
-    const extension = extname(sourceFile).toLowerCase();
-    if (extension === '.html' || extension === '.htm')
-        return 'html';
-    throw new InputError({
-        error: 'invalid_page_dialect',
-        message: `--page must name an HTML page; received "${sourceFile}"`,
-        field: 'page',
-        next: 'Write the page at `$CRTR_CONTEXT_DIR/pages/<name>.html`, then retry with --page PATH.',
-    });
-}
 function pageProductKinds() {
-    return readConfig('user').page_components;
+    return resolvePageComponents();
+}
+/** Delivery is two authored choices and one derived fact. Placement and inbox
+ * are the sender's to pick; `reply` is not a flag, because a page routes
+ * completion back exactly when it carries response-bearing components — the
+ * page's own shape decides it, and a sender who disagreed could only be wrong
+ * (inputs with no way to submit, or a bridge no response can settle).
+ *
+ * Skipping the inbox leaves the sender's own transcript as the page's only
+ * route to a human, so a terminal sender — a node that finishes, whose
+ * transcript nobody is watching — always projects to the inbox. */
+function deliveryFrom(input, responseBearing, senderLifecycle) {
+    const inbox = senderLifecycle === 'terminal'
+        ? true
+        : input['inbox'] === true
+            ? true
+            : input['noInbox'] === true
+                ? false
+                : responseBearing;
+    const placement = input['placement'] ?? 'inline';
+    return { placement, inbox, reply: responseBearing };
 }
 function submitAuthoredPage(submit) {
     try {
@@ -72,13 +92,26 @@ function submitAuthoredPage(submit) {
             error: 'invalid_page',
             message: error.message,
             field: 'page',
-            next: 'Fix the authored page, then pre-check it with `crtr human doc check <path>` before submitting again.',
+            next: 'Fix the authored page and submit again; the reported location is in the authored `.tsx` source.',
+        });
+    }
+}
+/** The page a `--replace` names, read for the one thing a revision inherits. */
+function replacedPage(ticketId) {
+    const dir = ticketDir(ticketId);
+    if (!existsSync(pageManifestPath(dir))) {
+        throw new InputError({
+            error: 'unknown_page',
+            message: `no page ${ticketId} on this canvas`,
+            field: 'replace',
+            next: 'Pass the page_id a previous send returned, or omit --replace to raise a new page.',
         });
     }
+    return parsePage(dir);
 }
 function writePipedPage(document) {
     const dir = mkdtempSync(join(tmpdir(), 'crtr-human-page-'));
-    const path = join(dir, 'page.html');
+    const path = join(dir, 'page.tsx');
     writeFileSync(path, document, { encoding: 'utf8', mode: 0o600 });
     return { dir, path };
 }
@@ -121,90 +154,120 @@ function pageInput(input) {
  * agents to repeat a screen-specific gesture back to a reader who may be on a
  * different surface entirely. */
 function queuedFollowUp() {
-    return 'Queued for the human. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block.';
+    return 'Queued for the user. Their answer is pushed to your inbox and wakes you when they respond — never poll, verify it opened, or block.';
 }
 // ---------------------------------------------------------------------------
-// ask
+// send
 // ---------------------------------------------------------------------------
-export const humanAsk = defineLeaf({
-    name: 'ask',
-    description: 'put a structured choice or open question to a person',
-    whenToUse: 'you would otherwise lay a decision, a set of options, or a question out for the user as prose — reach for this instead, for anything from a quick yes/no to a judgment-heavy call: gating a handoff, merge, deploy, destructive/irreversible operation, or real budget on an explicit human sign-off (offer Yes/No options), reviewing all the requirements before building, choosing among implementation patterns, walking a list of risks and deciding what to do about each, settling a naming or scope question, picking which of several findings to act on. Works for open-ended asks too (set `allowFreetext`, offer a few `options` as starting points).',
+export const humanSend = defineLeaf({
+    name: 'send',
+    description: 'send a durable page with explicit delivery',
+    whenToUse: 'you need to put structured TSX or HTML content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.',
     help: {
-        name: 'human ask',
-        summary: "submit a decision ticket to crouter's inbox; returns a job handle immediately",
+        name: 'human send',
+        summary: 'send a durable TSX or HTML page',
         guide: 'Page authoring: `crtr human -h`.',
         params: [
-            { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: 'Page bytes from stdin. Provide exactly one of stdin or --page PATH.' },
-            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} Provide exactly one of --page or stdin.` },
+            { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH. HTML is file-authored.' },
+            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} A .tsx file is JSX; .html/.htm is complete HTML. Provide exactly one of --page or stdin.` },
+            { kind: 'flag', name: 'placement', type: 'enum', choices: ['inline', 'panel'], required: false, default: 'inline', constraint: "Where the page is delivered. inline renders in this conversation's transcript; panel opens from the inbox beside it." },
+            { kind: 'flag', name: 'inbox', type: 'bool', required: false, constraint: 'Project this page into the inbox. Mutually exclusive with --no-inbox.' },
+            { kind: 'flag', name: 'no-inbox', type: 'bool', required: false, constraint: "Do not project this page into the inbox, leaving this conversation's transcript as its only route to the user. Mutually exclusive with --inbox, and refused from a terminal node, whose transcript nobody reads once it finishes." },
+            { kind: 'flag', name: 'replace', type: 'string', required: false, constraint: 'Page id returned by an earlier send. Rewrites source in place while retaining its delivery and transcript anchor. Refused once the page is settled or canceled. Not combinable with delivery flags.' },
         ],
         output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this human interaction. Its answer is pushed to your inbox when the human responds.' },
-            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding page.html, page.json, run.json, and response.json.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek; the answer arrives via your inbox.' },
+            { name: 'page_id', type: 'string', required: true, constraint: 'Identifier for the page; pass it as --replace to revise source in place.' },
+            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding page.tsx or page.html, optional page.js, page.json, and response lifecycle files when delivery needs them.' },
+            { name: 'placement', type: 'inline | panel', required: true, constraint: 'Resolved page placement.' },
+            { name: 'inbox', type: 'boolean', required: true, constraint: 'Whether the page is projected into the inbox.' },
+            { name: 'reply', type: 'boolean', required: true, constraint: 'Whether completion is routed back through a human bridge. Not a flag: true exactly when the page has response-bearing components.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'What happens next; never instructs the caller to poll.' },
         ],
         outputKind: 'object',
         effects: [
-            'Creates a kind:"human" node under you and enqueues a page in the human inbox.',
-            'Returns immediately; nothing opens on screen. The human answers from their inbox on their own time.',
+            'Writes one durable page record. Inbox projection follows the delivery flags, except from a terminal node, which always projects; reply routing follows the page\'s own components.',
+            "A display-only page's inbox entry is a notice, not a task: it clears itself once the person has actually seen the page, wherever they see it.",
+            'A reply-bearing page creates a kind:"human" bridge under the caller and routes completion back.',
+            '--replace rewrites source in place while retaining delivery and emitted time; open surfaces reload it without creating another page.',
         ],
     },
-    run: async (input) => {
+    run: async (input, context) => {
         const { sourceFile, tempDir } = pageInput(input);
-        try {
-            const source = await sourceStamp();
-            const prepared = submitAuthoredPage(() => preparePage({ sourceFile, dialect: pageDialect(sourceFile), source, productKinds: pageProductKinds() }));
-            const cwd = process.cwd();
-            const jobId = (await cliClient().createHumanBridge({ kind: 'human', parent: askingNode(), cwd, name: 'human-ask' })).node_id;
-            const idir = ticketDir(jobId);
-            const rc = { mode: 'ask', job_id: jobId };
-            atomicWriteJson(join(idir, 'run.json'), rc);
-            const { dir } = publishPage(ticketDir(jobId), prepared);
-            const originNodeId = askingNode();
-            if (originNodeId !== null && originNodeId !== '')
-                markStopSignal(originNodeId, 'askedHuman');
-            return { job_id: jobId, dir, follow_up: queuedFollowUp() };
+        const replacePage = input['replace'];
+        const deliveryFlags = ['placement', 'inbox', 'noInbox'];
+        if (input['inbox'] === true && input['noInbox'] === true) {
+            throw new InputError({ error: 'bad_invocation', message: 'received conflicting delivery flags', field: 'inbox', next: 'Pass at most one of --inbox and --no-inbox.' });
         }
-        finally {
-            if (tempDir !== undefined)
-                rmSync(tempDir, { recursive: true, force: true });
+        if (replacePage !== undefined && deliveryFlags.some((flag) => context?.providedParams.has(flag) === true)) {
+            throw new InputError({ error: 'bad_invocation', message: '--replace cannot change delivery', field: 'replace', next: 'Remove delivery flags: replacement retains the page placement, inbox, reply, and emitted time.' });
         }
-    },
-});
-// ---------------------------------------------------------------------------
-// notify (no job)
-// ---------------------------------------------------------------------------
-export const humanNotify = defineLeaf({
-    name: 'notify',
-    description: 'fire-and-forget acknowledgement, no reply expected',
-    whenToUse: 'informing a person without blocking or expecting an answer',
-    help: {
-        name: 'human notify',
-        summary: 'enqueue a fire-and-forget acknowledgement in the human inbox; creates no job',
-        guide: 'Page authoring: `crtr human -h`.',
-        params: [
-            { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: 'Page bytes from stdin. Provide exactly one of stdin or --page PATH.' },
-            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} Provide exactly one of --page or stdin.` },
-        ],
-        output: [
-            { name: 'queued', type: 'boolean', required: true, constraint: 'Always true — the notify page is durable inbox state the human acknowledges from the inbox.' },
-            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding page.html, page.json, and run.json.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Enqueues a durable display page in the human inbox. Creates no node; nothing opens on screen.',
-        ],
-    },
-    run: async (input) => {
-        const { sourceFile, tempDir } = pageInput(input);
         try {
-            const source = await sourceStamp();
-            const prepared = submitAuthoredPage(() => preparePage({ sourceFile, dialect: pageDialect(sourceFile), source, productKinds: pageProductKinds() }));
-            const id = `nfy-${randomBytes(4).toString('hex')}`;
-            const rc = { mode: 'notify' };
-            atomicWriteJson(join(ticketDir(id), 'run.json'), rc);
-            const { dir } = publishPage(ticketDir(id), prepared);
-            return { queued: true, dir };
+            if (replacePage !== undefined) {
+                const prior = replacedPage(replacePage);
+                // The human's submit wins the race with a revision: once the ticket has
+                // any terminal outcome, replacement is refused, and that refusal is the
+                // reviser's signal that the ticket is closed.
+                if (readTicketResult(ticketDir(replacePage)) !== null) {
+                    throw new InputError({
+                        error: 'page_settled',
+                        message: `page ${replacePage} already has a terminal outcome`,
+                        field: 'replace',
+                        next: 'The page was answered or canceled; nothing on it can change now. Raise a new page if more is needed.',
+                    });
+                }
+                // A revision changes only the content. Identity, routing, and emitted
+                // time stay the original sender's, so the prior source is inherited
+                // verbatim — a fork revising the page must not repoint its provenance.
+                const revised = submitAuthoredPage(() => preparePage({ sourceFile, source: prior.source, productKinds: pageProductKinds(), delivery: prior.delivery }));
+                const { dir } = publishPage(ticketDir(replacePage), revised);
+                return { page_id: replacePage, dir, ...prior.delivery, follow_up: 'Replaced in place. Every open surface reloads it; delivery and emitted time are unchanged.' };
+            }
+            const { source, lifecycle } = await sender();
+            // A terminal node finishes and its transcript stops being read, so the
+            // inbox is the only surface its page can still reach a human on. Refuse
+            // rather than quietly overriding the flag: the caller asked for a page
+            // nobody would ever see, and that is worth knowing.
+            if (lifecycle === 'terminal' && input['noInbox'] === true) {
+                throw new InputError({
+                    error: 'invalid_page_delivery',
+                    message: 'a terminal node cannot send a page --no-inbox',
+                    field: 'inbox',
+                    next: 'Drop --no-inbox. This node finishes, and nobody reads a finished node\'s transcript, so a page kept out of the inbox reaches no one.',
+                });
+            }
+            // Static extraction is an evaluation. Derive and validate delivery from this
+            // exact manifest so authored code runs once and cannot change between passes.
+            const productKinds = pageProductKinds();
+            const prepared = submitAuthoredPage(() => preparePage({ sourceFile, source, productKinds }));
+            const responseBearing = prepared.manifest.slots.some(isResponseBearingSlot);
+            const delivery = deliveryFrom(input, responseBearing, lifecycle);
+            prepared.manifest = submitAuthoredPage(() => validateAuthoredPageManifest({ ...prepared.manifest, delivery }, productKinds));
+            if (!delivery.reply) {
+                const pageId = `page-${randomBytes(4).toString('hex')}`;
+                const { dir } = publishPage(ticketDir(pageId), prepared);
+                // A page with no reply route carries no response-bearing components, so what the
+                // follow-up must get right is where the person will meet it and how it
+                // settles: an inline page is already in this conversation, and its
+                // inbox entry is a notice that clears itself the moment the page has
+                // actually been seen — an agent that points the person at their inbox
+                // for a page on their screen sends them to an empty list.
+                const followUp = delivery.placement === 'inline' && delivery.inbox
+                    ? 'Shown in this conversation and queued in the user\'s inbox. The inbox entry clears itself the user has seen the page — someone viewing this conversation acknowledges it on sight, so do not send them to their inbox for it. They already know this, do not inform them.'
+                    : delivery.placement === 'inline'
+                        ? 'Shown in this conversation as passive page content with no inbox entry.'
+                        : delivery.inbox
+                            ? 'Queued in the inbox; it opens in the panel and waits until dismissed.'
+                            : 'Published as passive page content with no inbox or response lifecycle.';
+                return { page_id: pageId, dir, ...delivery, follow_up: followUp };
+            }
+            const originNodeId = askingNode();
+            const bridgeNodeId = (await cliClient().createHumanBridge({ kind: 'human', parent: originNodeId, cwd: process.cwd(), name: 'human-page' })).node_id;
+            const idir = ticketDir(bridgeNodeId);
+            bindTicketReplyRoute(idir, bridgeNodeId);
+            const { dir } = publishPage(idir, prepared);
+            if (originNodeId !== null && originNodeId !== '')
+                markStopSignal(originNodeId, 'requestedHumanReply');
+            return { page_id: bridgeNodeId, dir, ...delivery, follow_up: queuedFollowUp() };
         }
         finally {
             if (tempDir !== undefined)
@@ -219,12 +282,12 @@ export const humanNotify = defineLeaf({
 // ---------------------------------------------------------------------------
 export const humanShow = defineLeaf({
     name: 'show',
-    description: "put a file live on the human's screen",
-    whenToUse: 'displaying a doc on screen while a human comments',
+    description: "put a file live on the user's screen",
+    whenToUse: 'displaying a doc on screen while the user comments',
     help: {
         name: 'human show',
         summary: "put a file live on screen in a tmux pane with crouter's renderer",
-        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid). To put a rich document in front of the human as a durable inbox page, use `crtr human notify --page PATH`.',
+        guide: 'The pane always watches the file and live-updates on every save — a displayed doc is a live view by definition, so point it at a file something keeps rewriting (a status board, a running summary) and it stays current. The file is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid). To put a rich document in front of the user as a durable inbox page, use `crtr human send --page PATH`; a page with no response-bearing components is a standalone announcement.',
         params: [
             { kind: 'positional', name: 'path', type: 'path', required: true, constraint: 'Path to the file to render.' },
             { kind: 'flag', name: 'window', type: 'enum', choices: ['auto', 'split', 'new'], required: false, default: 'auto', constraint: 'Placement. Default auto.' },