@north-light/crouter 0.3.198 → 0.3.200

package/dist/commands/human/queue.js

@@ -1,15 +1,13 @@
 import { existsSync } from 'node:fs';
-import { basename, join } from 'node:path';
 import { ApiError } from '../../api/index.js';
 import { defineLeaf } from '../../core/command.js';
 import { ticketDir } from '../../core/human/root.js';
 import { scanInbox } from '../../core/human/scan.js';
-import { pageManifestPath, isResolved, reviewPath } from '../../core/human/convention.js';
+import { pageManifestPath, isResolved, readTicketReplyRoute, reviewPath } from '../../core/human/convention.js';
 import { InputError } from '../../core/io.js';
 import { paginate } from '../../core/pagination.js';
 import { cliClient, rethrowAsCliError } from '../api-client.js';
 import { filterVisibleReviewTickets } from '../../clients/inbox/review-visibility.js';
-import { readJsonOrNull } from '../../core/fs-utils.js';
 function toRef(n) {
     return { node_id: n.node_id, name: n.name, cwd: n.cwd, parent: n.parent, status: n.status };
 }
@@ -20,17 +18,6 @@ function toRef(n) {
 async function fetchNodeRefs() {
     return (await cliClient().listNodes()).map(toRef);
 }
-/** Look up one node by id, mapping the API's 404 to `null`. */
-async function getNodeOrNull(id) {
-    try {
-        return await cliClient().getNode(id);
-    }
-    catch (err) {
-        if (err instanceof ApiError && err.status === 404)
-            return null;
-        rethrowAsCliError(err);
-    }
-}
 function resolveConversation(asking, nodes) {
     if (asking === undefined)
         return undefined;
@@ -59,43 +46,41 @@ function askingNodeFor(jobId, byId) {
         return byId.get(bridge.parent) ?? bridge;
     return bridge;
 }
-/** `notify` enqueues a durable page with no bridge node at all — its run.json
- *  is the manifest-based truth that distinguishes that intentional, workerless
- *  ticket from an `ask`/`review` ticket whose bridge node was reaped. */
-function isWorkerlessTicket(dir) {
-    return readJsonOrNull(join(dir, 'run.json'))?.mode === 'notify';
+/** A missing reply route is the complete representation of a standalone page;
+ * a route whose bridge disappeared is an orphaned reply-bearing ticket. */
+function replyBridgeId(dir) {
+    return readTicketReplyRoute(dir)?.bridge_node_id ?? null;
 }
 function summarizeTicket(summary, nodes, byId) {
-    const jobId = basename(summary.dir);
-    const workerless = isWorkerlessTicket(summary.dir);
-    // A ticket that expects a bridge node but has none is a stale ticket whose
-    // node was reaped, intentionally absent from the canvas view. A workerless
-    // notify ticket never had one, so it renders with its node-derived fields
-    // omitted rather than being dropped as an orphan.
-    if (!workerless && !byId.has(jobId))
+    const bridgeNodeId = replyBridgeId(summary.dir);
+    // A reply-bearing ticket whose bridge was reaped is stale and absent from the
+    // canvas view. A standalone page has no bridge by construction.
+    if (bridgeNodeId !== null && !byId.has(bridgeNodeId))
         return null;
-    const asking = workerless ? undefined : askingNodeFor(jobId, byId);
+    const asking = bridgeNodeId === null ? undefined : askingNodeFor(bridgeNodeId, byId);
     const conversation = resolveConversation(asking, nodes);
     const sourceLabel = readableSourceLabel(summary.source);
     return {
-        id: summary.id,
-        ...(workerless ? {} : { job_id: jobId }),
+        ticket_id: summary.id,
+        ...(bridgeNodeId === null ? {} : { bridge_node_id: bridgeNodeId }),
         dir: summary.dir,
         title: summary.title,
         subtitle: summary.subtitle,
         kind: summary.kind,
-        blocked_since: summary.blockedSince,
+        ...(summary.kind === 'page' ? { emitted_at: summary.emittedAt } : { blocked_since: summary.blockedSince }),
         ...(summary.claim !== undefined ? { claim_owner: summary.claim.owner } : {}),
         ...(sourceLabel !== undefined ? { source_label: sourceLabel } : {}),
         ...(asking !== undefined ? { asking_node_id: asking.node_id, asking_node_name: asking.name, cwd: asking.cwd } : {}),
         ...(conversation !== undefined ? { conversation_id: conversation.node_id, conversation_title: conversation.name } : {}),
     };
 }
-function interactionDirForJob(jobId, byId) {
-    const node = byId.get(jobId);
-    if (node !== undefined)
-        return { dir: ticketDir(jobId), node };
-    throw new InputError({ error: 'not_found', message: `no interaction node: ${jobId}`, field: 'job_id', next: 'Pass a job_id from `crtr human list`.' });
+function interactionDirForTicket(ticketId, byId) {
+    const dir = ticketDir(ticketId);
+    if (!existsSync(pageManifestPath(dir)) && !existsSync(reviewPath(dir))) {
+        throw new InputError({ error: 'not_found', message: `no interaction ticket: ${ticketId}`, field: 'ticket_id', next: 'Pass a ticket_id from `crtr human list`.' });
+    }
+    const bridgeNodeId = replyBridgeId(dir);
+    return { dir, bridge: bridgeNodeId === null ? null : byId.get(bridgeNodeId) ?? null };
 }
 function isTerminalBridge(status) {
     return status === 'done' || status === 'dead' || status === 'canceled';
@@ -109,7 +94,7 @@ function isAlreadyResolvedConflict(error) {
 export const humanList = defineLeaf({
     name: 'list',
     description: 'enumerate pending interactions',
-    whenToUse: 'discovering what is blocked on a human',
+    whenToUse: 'discovering what is blocked on the user',
     help: {
         name: 'human list',
         summary: 'paginated list of pending interactions, oldest first',
@@ -118,7 +103,7 @@ export const humanList = defineLeaf({
             { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: "Opaque token from a previous response's next_cursor. Omit on first call." },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {id, dir, title, subtitle, kind, blocked_since}; subtitle is the required authored one-sentence summary. Enriched when derivable with claim_owner, source_label, asking_node_id/name, conversation_id/title. Oldest first.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {ticket_id, dir, title, subtitle, kind, emitted_at? | blocked_since?}; pages use emitted_at, reviews use blocked_since. Enriched when derivable with bridge_node_id, claim_owner, source_label, asking_node_id/name, conversation_id/title. Oldest first.' },
             { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Pass on the next call to continue. null means no more items.' },
             { name: 'total', type: 'integer | null', required: true, constraint: 'Total pending interactions.' },
         ],
@@ -139,14 +124,14 @@ export const humanList = defineLeaf({
             return item === null ? [] : [item];
         })
             .sort((a, b) => {
-            const ka = `${a.blocked_since}|${a.id}`;
-            const kb = `${b.blocked_since}|${b.id}`;
+            const ka = `${a.emitted_at ?? a.blocked_since}|${a.ticket_id}`;
+            const kb = `${b.emitted_at ?? b.blocked_since}|${b.ticket_id}`;
             return ka < kb ? -1 : ka > kb ? 1 : 0;
         });
         const page = paginate(items, { limit, cursor }, {
             defaultLimit: 20,
             maxLimit: 100,
-            keyOf: (i) => `${i.blocked_since}|${i.id}`,
+            keyOf: (i) => `${i.emitted_at ?? i.blocked_since}|${i.ticket_id}`,
             total: 'count',
         });
         return { items: page.items, next_cursor: page.next_cursor, total: page.total };
@@ -162,11 +147,11 @@ function parseResolveBody(raw) {
         parsed = JSON.parse(raw);
     }
     catch (e) {
-        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(e)}`, field: 'stdin', next: 'Pass {"responses":{"<slot_id>":{...}}} on stdin.' });
+        throw new InputError({ error: 'invalid_json', message: `stdin is not valid JSON: ${String(e)}`, field: 'stdin', next: 'Pass {"responses":{"<component_id>":{...}}} on stdin.' });
     }
     const responses = parsed.responses;
     if (typeof responses !== 'object' || responses === null || Array.isArray(responses)) {
-        throw new InputError({ error: 'invalid_field', message: 'responses must be an object keyed by slot id', field: 'responses', next: 'Pass {"responses":{"<slot_id>":{...}}}, or {"responses":{}} to acknowledge a page with no response slots.' });
+        throw new InputError({ error: 'invalid_field', message: 'responses must be an object keyed by the id of a response-bearing component', field: 'responses', next: 'Pass {"responses":{"<component_id>":{...}}}, or {"responses":{}} to acknowledge a page with no response-bearing components.' });
     }
     return responses;
 }
@@ -177,101 +162,85 @@ export const humanResolve = defineLeaf({
     tier: 'hidden',
     help: {
         name: 'human resolve',
-        summary: 'resolve a pending page with the given answers and deliver them to the asking node',
+        summary: 'resolve a pending page with the given answers',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'job_id from human ask/review/list.' },
-            { kind: 'stdin', name: 'body', required: true, constraint: 'JSON {responses:{<slot_id>:{...}}} — one typed response object per response-bearing slot of the page.' },
+            { kind: 'positional', name: 'ticket_id', type: 'string', required: true, constraint: 'page_id from human send, or a page ticket_id from human list.' },
+            { kind: 'stdin', name: 'body', required: true, constraint: 'JSON {responses:{<component_id>:{...}}} — one typed response object per response-bearing component of the page.' },
         ],
         output: [
-            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call answered and delivered the page to the asking node.' },
-            { name: 'job_id', type: 'string', required: true, constraint: 'Interaction job id.' },
+            { name: 'resolved', type: 'boolean', required: true, constraint: 'True when this call completed the page.' },
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'Interaction ticket id.' },
             { name: 'reason', type: 'string', required: false, constraint: 'already_resolved or claimed when resolved is false.' },
         ],
         outputKind: 'object',
-        effects: ['The daemon publishes the answer, delivers it to the asking node, and retires the bridge before this call returns.'],
+        effects: ['The daemon publishes the answer and, when the ticket has a reply route, retires its bridge and returns the completion to subscribers.'],
     },
     run: async (input) => {
-        const jobId = input['job_id'];
+        const ticketId = input['ticket_id'];
         const nodes = await fetchNodeRefs();
         const byId = new Map(nodes.map((n) => [n.node_id, n]));
-        const { dir, node } = interactionDirForJob(jobId, byId);
+        const { dir, bridge } = interactionDirForTicket(ticketId, byId);
         if (!existsSync(pageManifestPath(dir))) {
-            throw new InputError({ error: 'not_found', message: `no page for interaction: ${jobId}`, field: 'job_id', next: 'Pass a pending job_id from `crtr human list`.' });
+            throw new InputError({ error: 'not_found', message: `no page for interaction: ${ticketId}`, field: 'ticket_id', next: 'Pass a pending ticket_id from `crtr human list`.' });
         }
         const responses = parseResolveBody(input['body']);
         // A published result on a live bridge may be an interrupted delivery. The
-        // daemon re-drives that delivery before it returns its 409, so only bypass
-        // it when the bridge is already terminal.
-        if (isResolved(dir) && isTerminalBridge(node.status)) {
-            return { resolved: false, job_id: jobId, reason: 'already_resolved' };
+        // daemon re-drives that delivery before it returns its 409. A standalone
+        // ticket or terminal bridge has nothing left to deliver.
+        if (isResolved(dir) && (bridge === null || isTerminalBridge(bridge.status))) {
+            return { resolved: false, ticket_id: ticketId, reason: 'already_resolved' };
         }
         try {
-            await cliClient().resolveHumanTicket(jobId, { responses });
+            await cliClient().resolveHumanTicket(ticketId, { responses });
         }
         catch (e) {
             if (isAlreadyResolvedConflict(e))
-                return { resolved: false, job_id: jobId, reason: 'already_resolved' };
+                return { resolved: false, ticket_id: ticketId, reason: 'already_resolved' };
             rethrowAsCliError(e);
         }
-        return { resolved: true, job_id: jobId };
+        return { resolved: true, ticket_id: ticketId };
     },
 });
 // ---------------------------------------------------------------------------
-// cancel — retract a pending ask/review
+// cancel — retract a pending page/review
 // ---------------------------------------------------------------------------
 export const humanCancel = defineLeaf({
     name: 'cancel',
-    description: 'retract a pending ask/review',
-    whenToUse: 'a question went stale before the human answered',
+    description: 'retract a pending page/review',
+    whenToUse: 'a page or review went stale before the user completed it',
     help: {
         name: 'human cancel',
-        summary: 'retract a pending ask/review you posed — drops it from the human inbox and retires the bridge node. Reach for this the moment a question goes stale (you answered it yourself, the situation changed) so a human is not left resolving a prompt whose answer no longer matters',
-        guide: 'Pass the job_id returned by `human ask`/`review`. Best-effort and idempotent: if the human already answered, or it was already canceled, it reports canceled:false with reason "already_resolved" and changes nothing. Cancellation races the human\'s submit; whichever wins is authoritative. The agent that posed the question is almost always the one canceling it, so the caller is never messaged — only OTHER subscribers get a quiet deferred note that no answer is coming.',
+        summary: 'retract a pending page/review — drops it from the human inbox and retires its reply bridge when one exists. Reach for this the moment an interaction goes stale so the user is not left completing something that no longer matters',
+        guide: 'Pass the page_id returned by `human send`, or a ticket_id from `human list`. Best-effort and idempotent: if the user already completed or canceled it, canceled:false with reason "already_resolved" changes nothing. Cancellation races the user\'s submit; whichever wins is authoritative. For a reply-bearing ticket, only subscribers other than the caller receive the cancellation notice.',
         params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Node id of the interaction to cancel — the job_id returned by ask/review.' },
+            { kind: 'positional', name: 'ticket_id', type: 'string', required: true, constraint: 'page_id returned by human send, or ticket_id returned by human list.' },
             { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Optional short note delivered to subscribers explaining why it was retracted.' },
         ],
         output: [
             { name: 'canceled', type: 'boolean', required: true, constraint: 'True when the interaction was retracted; false when there was nothing live to cancel (already answered/canceled).' },
-            { name: 'job_id', type: 'string', required: true, constraint: 'The interaction node id.' },
+            { name: 'ticket_id', type: 'string', required: true, constraint: 'The interaction ticket id.' },
             { name: 'reason', type: 'string', required: false, constraint: 'Why nothing was canceled (e.g. "already_resolved"), present when canceled is false.' },
         ],
         outputKind: 'object',
         effects: [
-            'The daemon retires the bridge and notifies subscribers other than the caller that no answer is coming.',
+            'The daemon removes the ticket from the inbox; when it has a reply bridge, the bridge retires and subscribers other than the caller are notified that no answer is coming.',
         ],
     },
     run: async (input) => {
-        const jobId = input['job_id'];
+        const ticketId = input['ticket_id'];
         const reason = input['reason'];
-        const node = await getNodeOrNull(jobId);
-        if (node === null) {
-            throw new InputError({
-                error: 'not_found',
-                message: `no interaction node: ${jobId}`,
-                field: 'job_id',
-                next: 'Pass the job_id from human ask/review, or list pending with `crtr human list`.',
-            });
-        }
-        const idir = ticketDir(jobId);
-        // Nothing live to cancel: the bridge is already terminal, or the ticket
-        // never carried a request descriptor.
-        const hasDescriptor = existsSync(pageManifestPath(idir)) || existsSync(reviewPath(idir));
-        if (isTerminalBridge(node.status) || !hasDescriptor) {
-            return { canceled: false, job_id: jobId, reason: 'already_resolved' };
-        }
         const actor = process.env['CRTR_NODE_ID'] ?? 'human';
         try {
-            await cliClient().cancelHumanTicket(jobId, { ...(reason !== undefined && reason !== '' ? { reason } : {}), actor });
+            await cliClient().cancelHumanTicket(ticketId, { ...(reason !== undefined && reason !== '' ? { reason } : {}), actor });
         }
         catch (e) {
             if (isAlreadyResolvedConflict(e))
-                return { canceled: false, job_id: jobId, reason: 'already_resolved' };
+                return { canceled: false, ticket_id: ticketId, reason: 'already_resolved' };
             rethrowAsCliError(e);
         }
-        return { canceled: true, job_id: jobId };
+        return { canceled: true, ticket_id: ticketId };
     },
     render: (r) => r['canceled'] === true
-        ? `Canceled human interaction ${r['job_id']} — it left the human inbox and subscribers were notified no answer is coming.`
-        : `Nothing to cancel for ${r['job_id']} — ${r['reason'] ?? 'nothing to cancel'}.`,
+        ? `Canceled human interaction ${r['ticket_id']} — it left the human inbox.`
+        : `Nothing to cancel for ${r['ticket_id']} — ${r['reason'] ?? 'nothing to cancel'}.`,
 });

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

@@ -4,16 +4,6 @@ export interface PageHelpText {
     pageHint: string;
     rootUseWhen: string;
 }
-/** The one HTML authoring model for `human -h`. */
-export declare function pageHelpText(htmlSurface?: boolean): PageHelpText;
-/**
- * Crouter's private per-interaction record. Reduced to the delivery essentials:
- * the mode that identifies the ticket and the bridge node id it delivers back to.
- * The ticket store owns every public request/result/output path (page.html,
- * page.json, response.json, review.json); crouter never records pane ids or output paths.
- */
-export interface RunRecord {
-    mode: 'ask' | 'notify' | 'review';
-    job_id?: string;
-}
+/** The one page authoring model for `human -h`. */
+export declare function pageHelpText(pageSurface?: boolean): PageHelpText;
 export declare function resolveMaxPanes(): number;

package/dist/commands/human/shared.js

@@ -1,16 +1,22 @@
 import { readConfig } from '../../core/config.js';
-import { BUILTIN_COMPONENT_SELECTION_LINES } from '../../core/human/component-docs.js';
-/** The one HTML authoring model for `human -h`. */
-export function pageHelpText(htmlSurface = false) {
+import { CORE_COMPONENT_SELECTION_LINES } from '../../core/human/component-docs.js';
+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 {
-        authoring: htmlSurface
-            ? 'Use inline HTML pages as the default way to put structured or interactive content in front of the human; the environment renders web content, so a page is not a special occasion. Write one complete HTML document to `$CRTR_CONTEXT_DIR/pages/<name>.html`. Its `<head>` has required `<meta name="crtr-page-title" content="…">`, optional `<meta name="crtr-page-subtitle" content="…">`, and optional `<meta name="crtr-page-placement" content="inline|panel">` (default `panel`); interactive or multi-step pages need one `<crtr-pages>` wrapper with `<crtr-page>` steps, and each component config is its first `<script type="application/json">` child. Display-only pages are first-class: a page with no questions is a legitimate, encouraged way to show structured UI with `notify --page`.'
-            : 'Write one complete HTML document to `$CRTR_CONTEXT_DIR/pages/<name>.html`. Its `<head>` has required `<meta name="crtr-page-title" content="…">`, optional `<meta name="crtr-page-subtitle" content="…">`, and optional `<meta name="crtr-page-placement" content="inline|panel">` (default `panel`); interactive or multi-step pages need one `<crtr-pages>` wrapper with `<crtr-page>` steps, and each component config is its first `<script type="application/json">` child. Display-only pages are first-class: a page with no questions is a legitimate, encouraged way to show structured UI with `notify --page`.',
-        componentSelection: BUILTIN_COMPONENT_SELECTION_LINES,
-        pageHint: 'Write the page to `$CRTR_CONTEXT_DIR/pages/<name>.html`; pass that path.',
-        rootUseWhen: htmlSurface
-            ? 'when a person must decide, review a document with you, or receive a live display; use inline HTML pages by default for structured or interactive content because the environment renders web content.'
-            : 'when a person must decide, review a document with you, or receive a live display.',
+        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,
+        componentSelection: [...CORE_COMPONENT_SELECTION_LINES, DISPLAY_SET_LINE],
+        pageHint: 'Write the page module to `$CRTR_CONTEXT_DIR/pages/<name>.tsx`; pass that path.',
+        // The page-surface wording names no document review and no live display:
+        // `human review` and `human show` are terminal-only and leave the tree on
+        // such a host (see `registerHuman`).
+        // No leading "when": the root renderer already emits `use when ${useWhen}`.
+        rootUseWhen: pageSurface
+            ? 'a person must decide something or receive structured content from you; use inline pages by default because the environment renders rich components.'
+            : 'a person must decide, review a document with you, or receive a live display.',
     };
 }
 export function resolveMaxPanes() {

package/dist/commands/human.js

@@ -1,47 +1,55 @@
-// `crtr human` creates bridge nodes and durable tickets for human decisions.
+// `crtr human` creates durable pages and review tickets for human decisions.
 //
-// Ask creates a bridge node and submits a ticket to the store. Review creation
-// asks crtrd to create a ticket, daemon-owned review, and companion. notify
-// enqueues a durable page with no node; show is passive display.
+// Send optionally creates a reply bridge; review creation asks crtrd to create
+// a ticket, daemon-owned review, and companion. Show is passive display.
 import { defineBranch } from '../core/command.js';
 import { readConfig } from '../core/config.js';
-import { humanAsk, humanNotify, humanShow } from './human/prompts.js';
+import { humanSend, humanShow } from './human/prompts.js';
 import { humanList, humanResolve, humanCancel } from './human/queue.js';
 import { humanReviewBranch } from './human/review.js';
-import { humanInbox } from './human/inbox.js';
-import { humanDoc } from './human/doc.js';
-import { humanHtml } from './human/html.js';
+import { humanFeedbackBranch } from './human/feedback.js';
+import { humanComponents } from './human/components.js';
 import { pageHelpText } from './human/shared.js';
 export function registerHuman() {
-    const pageHelp = pageHelpText(readConfig('user').html_surface);
+    // `page_surface` marks a host whose human surface is a rendered page product
+    // rather than a terminal. Review and show are terminal-only: a review is a
+    // live editor session with anchored comments driven by a companion node, and
+    // show is a passive tmux live-watch. Such a host can render neither, so both
+    // leave the surface entirely instead of filing tickets nobody can open.
+    const pageSurface = readConfig('user').page_surface;
+    const pageHelp = pageHelpText(pageSurface);
+    const concept = pageSurface
+        ? 'human-in-the-loop decisions and structured pages'
+        : 'human-in-the-loop decisions, document review, and live display';
+    const ticketModel = pageSurface
+        ? 'Tickets queue in the human inbox; nothing opens on screen. `send` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not.'
+        : 'Tickets queue in the human inbox; nothing opens on screen. `send` routes completion back when the page carries response-bearing components, and publishes a standalone announcement when it does not. `review` is for live document review with anchored comments; `show` is a passive tmux live-watch rather than a ticket.';
     return defineBranch({
         name: 'human',
         rootEntry: {
-            concept: 'human-in-the-loop decisions, document review, and live display',
-            desc: 'ask, review new/comment, notify, show, cancel, list',
+            concept,
+            desc: pageSurface ? 'send, components, feedback, cancel, list' : 'send, review new/comment, show, cancel, list',
             useWhen: pageHelp.rootUseWhen,
         },
         help: {
             name: 'human',
-            summary: 'human-in-the-loop decisions, document review, and live display',
+            summary: concept,
             model: [
-                "Tickets queue in the human inbox; nothing opens on screen. `ask` returns immediately and its answer is pushed to the asking node, while `notify` expects no reply. `review` is for live document review with anchored comments; `show` is a passive tmux live-watch rather than a ticket. Validate authored pages with `crtr human doc check`.",
+                ticketModel,
                 pageHelp.authoring,
                 pageHelp.componentSelection.join('\n'),
-                'Component contracts: `crtr human html`.',
+                'Props, response contracts, and the full component catalog: `crtr human components`.',
             ].join('\n\n'),
         },
         children: [
-            humanHtml,
-            humanAsk,
-            humanReviewBranch,
-            humanNotify,
-            humanShow,
+            humanComponents,
+            humanSend,
+            ...(pageSurface ? [] : [humanReviewBranch]),
+            humanFeedbackBranch,
+            ...(pageSurface ? [] : [humanShow]),
             humanCancel,
             humanList,
             humanResolve,
-            humanInbox,
-            humanDoc,
         ],
     });
 }

package/dist/commands/memory/origin.js

@@ -20,7 +20,7 @@ export const originLeaf = defineLeaf({
             { name: 'origin_recorded', type: 'boolean', required: true, constraint: 'true when the doc carries an `origin` provenance block; false for hand-authored or pre-provenance docs.' },
             { name: 'created', type: 'string', required: false, constraint: 'ISO timestamp the doc was created. Absent when origin_recorded is false.' },
             { name: 'cwd', type: 'string', required: false, constraint: 'Working directory the authoring conversation ran in.' },
-            { name: 'node', type: 'string', required: false, constraint: 'Node id that authored the doc, or null when written by a human at the CLI (no node).' },
+            { name: 'node', type: 'string', required: false, constraint: 'Node id that authored the doc, or null when written by the user at the CLI (no node).' },
             { name: 'node_present', type: 'boolean', required: false, constraint: 'true when that node still exists on the canvas (deref below is live); false when it has been pruned.' },
             { name: 'node_kind', type: 'string', required: false, constraint: 'Kind of the authoring node (only when node_present).' },
             { name: 'node_mode', type: 'string', required: false, constraint: 'Mode of the authoring node (only when node_present).' },
@@ -79,7 +79,7 @@ export const originLeaf = defineLeaf({
             ? `Read the originating conversation at \`${sessionFile ?? '(no session captured)'}\`, browse its shared docs at \`${contextDir(nodeId)}\`, or attach live with \`crtr surface attach ${nodeId}\`.`
             : nodeId !== null
                 ? `The authoring node \`${nodeId}\` has been pruned from the canvas; its context dir may persist at \`${contextDir(nodeId)}\`.`
-                : 'Authored by a human at the CLI \u2014 no node conversation to deref.';
+                : 'Authored by the user at the CLI \u2014 no node conversation to deref.';
         return {
             name: doc.name,
             path: doc.path,

package/dist/commands/node/bash.js

@@ -3,7 +3,7 @@ import { defineBranch, defineLeaf } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
 import { displayMessage } from '../../core/runtime/tmux-chrome.js';
 import { contextDir } from '../../core/canvas/paths.js';
-import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobPaths, formatBashElapsed, isSafeBashJobId, jobStartedAtMs, readJobPgid, stopBackgroundBashJob, tailJobLog } from '../../core/bash-jobs.js';
+import { activeBackgroundBashJobs, backgroundRunningBashJobs, bashJobCommandLine, bashJobPaths, formatBashElapsed, isSafeBashJobId, jobStartedAtMs, readJobPgid, stopBackgroundBashJob, tailJobLog } from '../../core/bash-jobs.js';
 import { cliClient, getNodeOrNull } from '../api-client.js';
 import { nodeInPane } from '../surface/node/placement.js';
 function resolveBashTarget(input, missingMessage) {
@@ -108,13 +108,13 @@ const nodeBashList = defineLeaf({
         const jobs = result['jobs'];
         if (jobs.length === 0)
             return `No background bash jobs for ${result['node_id']}.`;
-        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${job.command.split('\n')[0]}${job.purpose === null ? '' : `\n  purpose: ${job.purpose}`}\n  log: ${job.log_path}`).join('\n');
+        return jobs.map((job) => `${job.job_id} · ${formatBashElapsed(job.elapsed_ms)} · ${bashJobCommandLine(job.command)}${job.purpose === null ? '' : `\n  purpose: ${job.purpose}`}\n  log: ${job.log_path}`).join('\n');
     },
 });
 const nodeBashKill = defineLeaf({
     name: 'kill',
     description: 'stop one of a node’s background bash jobs',
-    whenToUse: 'a human watching the Inspector or the attach cockpit’s bash row wants a long-running background job to stop now, or an agent is abandoning work it backgrounded',
+    whenToUse: 'the user watching the Inspector or the attach cockpit’s bash row wants a long-running background job to stop now, or an agent is abandoning work it backgrounded',
     tier: 'hidden',
     help: {
         name: 'node bash kill',
@@ -166,7 +166,7 @@ const nodeBashKill = defineLeaf({
             });
         }
         await cliClient().sendMessage(node.node_id, {
-            body: `Background bash job ${jobId} was stopped by the human before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
+            body: `Background bash job ${jobId} was stopped by the user before it finished. Log: ${paths.jobLog}  Command: ${paths.cmdSh}`,
             tier: 'urgent',
         });
         return { node_id: node.node_id, job_id: jobId, signaled: stopped.signaled };

package/dist/commands/node/inspect.js

@@ -17,7 +17,7 @@ import { focusViewer, nodeInPane } from '../surface/node/placement.js';
 const nodeList = defineLeaf({
     name: 'list',
     description: 'list nodes on the canvas',
-    whenToUse: 'you want a flat roster of the nodes on the canvas, sliced by displayed name, status, kind, mode, lifecycle, profile, cwd, and graph scope (--under a node, for that node plus its subscription descendants). The filters AND together. Use `node inspect show` instead to drill into one node and its spine neighbors, `canvas dashboard` for the tree shape, and `canvas attention` to find nodes blocked on a human',
+    whenToUse: 'you want a flat roster of the nodes on the canvas, sliced by displayed name, status, kind, mode, lifecycle, profile, cwd, and graph scope (--under a node, for that node plus its subscription descendants). The filters AND together. Use `node inspect show` instead to drill into one node and its spine neighbors, `canvas dashboard` for the tree shape, and `canvas attention` to find nodes blocked on the user',
     help: {
         name: 'node inspect list',
         summary: 'list nodes on the canvas, filtered by any combination of attribute slices and a graph-scope (--under) that AND together',
@@ -239,7 +239,7 @@ const nodeShow = defineLeaf({
 export const nodeFork = defineLeaf({
     name: 'fork',
     description: 'fork a node into an independent idle root with the same conversation and durable context',
-    whenToUse: 'a conversation has already accumulated the context you want, and you want a new human-driven branch beside it without sending a prompt or inheriting any graph-management responsibility. This copies the conversation and durable context, then waits for the fork’s first real user message to supply its mandate. Use `node new --fork-from` instead when spawning a managed worker with an immediate task',
+    whenToUse: 'a conversation has already accumulated the context you want, and you want a new user-driven branch beside it without sending a prompt or inheriting any graph-management responsibility. This copies the conversation and durable context, then waits for the fork’s first real user message to supply its mandate. Use `node new --fork-from` instead when spawning a managed worker with an immediate task',
     help: {
         name: 'node fork',
         summary: 'create an independent resident root from a node’s conversation and durable context, with no kickoff prompt or model turn',
@@ -293,7 +293,7 @@ export const nodeFork = defineLeaf({
 export const nodeInspect = defineBranch({
     name: 'inspect',
     description: 'read one node — its graph position, context, and artifacts',
-    whenToUse: 'reading everything about ONE node you can name: enumerate the roster (`list`), inspect a node and its spine neighbors (`show`), browse its on-disk context dir (`context`), or list its reports/docs as refs (`artifacts`). Use `canvas dashboard` instead to render the whole tree SHAPE, or `canvas attention` to find which nodes are blocked on a human',
+    whenToUse: 'reading everything about ONE node you can name: enumerate the roster (`list`), inspect a node and its spine neighbors (`show`), browse its on-disk context dir (`context`), or list its reports/docs as refs (`artifacts`). Use `canvas dashboard` instead to render the whole tree SHAPE, or `canvas attention` to find which nodes are blocked on the user',
     help: {
         name: 'node inspect',
         summary: 'read one node (or the roster) — topology, context dir, and artifacts',

package/dist/commands/node/lifecycle.js

@@ -8,7 +8,7 @@ import { closePane, paneExists, respawnPaneSync, viewerEnv, viewerPaneOf, nodeIn
 const nodeRecycle = defineLeaf({
     name: 'recycle',
     description: 'finish the agent in your pane + recycle it into a fresh root',
-    whenToUse: 'you are at an agent\'s pane and done with it: finish it cleanly and recycle the pane in one move — push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane to keep working. The human-driver way to end an agent and immediately start over in place. Use `node lifecycle demote` instead to put it on a finishing track IN PLACE (flip terminal, keep it running) without ending it now, `node lifecycle close` to tear a node and its subtree down WITHOUT finishing (no report, revivable), and `push final` when the agent should finish ITSELF from inside its own turn',
+    whenToUse: 'you are at an agent\'s pane and done with it: finish it cleanly and recycle the pane in one move — push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane to keep working. The hands-on way to end an agent and immediately start over in place. Use `node lifecycle demote` instead to put it on a finishing track IN PLACE (flip terminal, keep it running) without ending it now, `node lifecycle close` to tear a node and its subtree down WITHOUT finishing (no report, revivable), and `push final` when the agent should finish ITSELF from inside its own turn',
     help: {
         name: 'node lifecycle recycle',
         summary: 'finish the agent in your current pane and recycle the pane — push its last message as a final report to everyone waiting on it, mark it done, then boot a fresh crtr root in the same pane',

package/dist/commands/node/message.js

@@ -49,7 +49,7 @@ function messageSendParams() {
         { kind: 'flag', name: 'self', type: 'bool', required: false, constraint: 'Target the calling node. Exactly one of --to or --self is required.' },
         { kind: 'flag', name: 'tier', type: 'enum', choices: ['critical', 'urgent', 'normal', 'deferred'], required: false, default: 'normal', constraint: 'Delivery urgency. Deferred never wakes an idle node.' },
         { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Non-empty hidden ambient context delivered beside the message, or alone.' },
-        { kind: 'flag', name: 'reopen', type: 'bool', required: false, hidden: true, constraint: 'Clear a finalized target latch before delivery or fresh revive.' },
+        { kind: 'flag', name: 'reopen', type: 'bool', required: false, constraint: 'Required to re-task a finalized target: clears its finalization latch before delivery. Rejected when the target is not finalized.' },
     ];
 }
 function messageRequestParams() {
@@ -132,7 +132,7 @@ const nodeMessageSend = defineLeaf({
         params: messageSendParams(),
         output: messageOutput(),
         outputKind: 'object',
-        effects: ['Appends one inbox entry. Critical, urgent, and normal delivery may revive a dormant target; deferred waits for its next natural cycle.'],
+        effects: ['Appends one inbox entry. Critical, urgent, and normal delivery may revive a dormant target; deferred waits for its next natural cycle.', '--reopen clears a finalized target\'s finalization latch before delivery, allowing it to take a new mandate. Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted.'],
     },
     run: (input) => runMessageEngine(input),
     render: (r) => String(r['guidance']),

package/dist/commands/node-worktree.js

@@ -41,7 +41,7 @@ function mapWorktreeApiError(err) {
 const worktreeClose = defineLeaf({
     name: 'close',
     description: 'land and close the current node-managed worktree',
-    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto its recorded local base branch, fast-forward that base onto it, and (best-effort) remove the worktree and delete the branch before finishing',
+    whenToUse: 'you are inside the node that owns an open managed worktree and are ready to rebase it onto its recorded local base branch and fast-forward that base before finishing; its active checkout is retained for deferred cleanup',
     help: {
         name: 'node worktree close',
         summary: 'land and close the current node-managed worktree',
@@ -50,15 +50,15 @@ const worktreeClose = defineLeaf({
             { name: 'node_id', type: 'string', required: true, constraint: 'The caller node id whose managed worktree was closed.' },
             { name: 'branch', type: 'string', required: true, constraint: 'The worktree branch that was fast-forwarded into its recorded local base branch.' },
             { name: 'landed_sha', type: 'string', required: true, constraint: 'The commit SHA that the recorded local base branch was fast-forwarded onto.' },
-            { name: 'worktree_path', type: 'string', required: true, constraint: 'The managed worktree path that was closed (best-effort removed; see worktree_removed).' },
-            { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'True when the worktree directory was removed; false means the landing still happened (the close is done) but automatic removal failed and needs a manual follow-up.' },
-            { name: 'worktree_remove_error', type: 'string', required: false, constraint: 'Present only when worktree_removed is false: the manual cleanup command to run.' },
-            { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'True when the local branch was deleted; false means the landing still happened (the close is done) but the local branch cleanup failed and needs a manual follow-up.' },
-            { name: 'branch_delete_error', type: 'string', required: false, constraint: 'Present only when branch_deleted is false: the manual cleanup command to run.' },
+            { name: 'worktree_path', type: 'string', required: true, constraint: 'The managed worktree path whose cleanup is deferred until its caller exits.' },
+            { name: 'worktree_removed', type: 'boolean', required: true, constraint: 'Always false for an active caller: its checkout remains intact rather than being removed beneath the node.' },
+            { name: 'worktree_remove_error', type: 'string', required: true, constraint: 'The named deferred-cleanup state and safe manual follow-up after the caller exits.' },
+            { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'False while the deferred-cleanup checkout still has this branch checked out.' },
+            { name: 'branch_delete_error', type: 'string', required: true, constraint: 'The safe branch-cleanup follow-up after the checkout is removed.' }
         ],
         outputKind: 'object',
         effects: [
-            'Rebases the worktree onto its recorded local base branch, fast-forwards that base onto it (never pushes to origin), marks the node-managed worktree closed, then attempts (best-effort) to remove the worktree and delete the local branch.',
+            'Rebases the worktree onto its recorded local base branch, fast-forwards that base onto it (never pushes to origin), marks the node-managed worktree closed with cleanup pending, and leaves the active caller checkout and branch intact.',
         ],
     },
     run: async () => {
@@ -93,7 +93,7 @@ const worktreeClose = defineLeaf({
 export const nodeWorktreeBranch = defineBranch({
     name: 'worktree',
     description: 'manage a node-owned git worktree — close the one born by `node new --worktree <base>`',
-    whenToUse: 'you are inside a node that was spawned with `node new --worktree <base>` and are ready to land it: rebase onto its recorded local base branch, fast-forward that base onto it, and close the worktree. Symmetric with `node new --worktree <base>`, which births it',
+    whenToUse: 'you are inside a node that was spawned with `node new --worktree <base>` and are ready to land it: rebase it onto its recorded local base branch, fast-forward that base onto it, and close the worktree with cleanup deferred until the node exits. Symmetric with `node new --worktree <base>`, which births it',
     help: {
         name: 'node worktree',
         summary: 'manage a node-owned git worktree — birth is `node new --worktree <base>`; this branch closes it',

package/dist/commands/pkg/browse.js

@@ -8,7 +8,7 @@ import { defineLeaf } from '../../core/command.js';
 export const pkgBrowseLeaf = defineLeaf({
     name: 'browse',
     description: 'open the interactive plugin browser',
-    whenToUse: 'a human wants to browse registered marketplaces and inspect or manage plugins interactively. Agents should use pkg market browse or pkg plugin list, which are scriptable.',
+    whenToUse: 'the user wants to browse registered marketplaces and inspect or manage plugins interactively. Agents should use pkg market browse or pkg plugin list, which are scriptable.',
     help: {
         name: 'pkg browse',
         summary: 'open the interactive plugin browser',