@north-light/crouter 0.3.221 → 0.3.223

package/dist/clients/inbox/controller.js

@@ -220,7 +220,7 @@ export class InboxController {
     async cancelFromInbox(dir) {
         this.submittingDir = dir;
         try {
-            await cancelTicketViaDaemon(dir, { reason: 'Canceled from the inbox.', actor: 'human' });
+            await cancelTicketViaDaemon(dir, { reason: 'Canceled from the inbox.', actor: 'human', disposition: 'dismissed' });
             this.status = 'canceled';
         }
         catch (error) {

package/dist/clients/inbox/page-adapter.js

@@ -12,6 +12,7 @@ export class PageAdapter {
         this.manifest = opts.ticket.manifest;
         this.panel = mountPanel({
             manifest: opts.ticket.manifest,
+            document: opts.ticket.document,
             productKinds: opts.productKinds,
             initialResponses: opts.ticket.progress,
             cols: opts.cols,
@@ -46,7 +47,7 @@ export class PageAdapter {
     }
     reload(ticket) {
         this.manifest = ticket.manifest;
-        this.panel.loadPage(ticket.manifest, { initialResponses: ticket.progress, productKinds: this.opts.productKinds });
+        this.panel.loadPage(ticket.manifest, { document: ticket.document, initialResponses: ticket.progress, productKinds: this.opts.productKinds });
         this.opts.onDirty();
     }
     close() { this.panel.unmount(); }

package/dist/clients/inbox/resolve.d.ts

@@ -4,6 +4,7 @@ export declare function resolveTicketPage(dir: string, responses: PageResponses)
 export declare function cancelTicketViaDaemon(dir: string, opts: {
     reason: string;
     actor: string;
+    disposition?: 'canceled' | 'dismissed';
 }): Promise<void>;
 export declare function daemonErrorMessage(err: unknown): string;
 export type ResolveFailure = 'unreachable' | 'already_resolved' | 'delivery_failed' | 'other';

package/dist/clients/inbox/review/review-client.js

@@ -67,7 +67,9 @@ export function createReviewClient(opts = {}) {
             };
         },
         async cancel(reviewId, reason) {
-            await request(() => cliClient().cancelReview(reviewId, { reason, actor: 'human' }));
+            // The recipient surface: closing a review here is a dismissal, never the
+            // requester withdrawing it.
+            await request(() => cliClient().cancelReview(reviewId, { reason, actor: 'human', disposition: 'dismissed' }));
         },
     };
 }

package/dist/clients/inbox/tui/panel.js

@@ -1,13 +1,32 @@
+import { projectPageDisplayMarkdown } from '../../../core/human/page-markdown.js';
 import { handleKeypress } from './input.js';
 import { clampItemReviewScroll, renderFinal, renderItemReview, renderOverview } from './render.js';
 import { pageComplete, slotAnswered } from './slots.js';
-function buildInitialState(manifest, initialResponses, productKinds, editorAvailable, wrapWidth) {
+/** Same projection the inline chat block reads (page-block.ts) — the authored
+ *  prose outside slot tags. A malformed or unreadable document just yields no
+ *  display content here, same as the inline block's own reload() fallback. */
+function displayMarkdownOf(manifest, document) {
+    if (manifest.dialect !== 'jsx' || document === undefined)
+        return '';
+    try {
+        return projectPageDisplayMarkdown(document, manifest);
+    }
+    catch {
+        return '';
+    }
+}
+function buildInitialState(manifest, document, initialResponses, productKinds, editorAvailable, wrapWidth) {
     const responses = new Map();
     const validIds = new Set(manifest.slots.flatMap((slot) => slot.id === undefined ? [] : [slot.id]));
     for (const [id, response] of Object.entries(initialResponses ?? {}))
         if (validIds.has(id))
             responses.set(id, response);
-    const state = { phase: manifest.slots.length === 1 ? 'item-review' : 'overview', currentIndex: 0, manifest, slots: manifest.slots, responses, productKinds, inputMode: null, selectedAction: 0, bodyMode: 'question', scrollOffset: 0, bodyScrollOffsets: { question: 0 }, hscrollOffset: 0, hscrollMax: 0, wrapWidth, editorAvailable };
+    const displayMarkdown = displayMarkdownOf(manifest, document);
+    // Single-slot pages skip straight to item-review to save a step — but only
+    // when there is no display prose to show first; otherwise that prose would
+    // never be seen.
+    const phase = manifest.slots.length === 1 && displayMarkdown === '' ? 'item-review' : 'overview';
+    const state = { phase, currentIndex: 0, manifest, displayMarkdown, slots: manifest.slots, responses, productKinds, inputMode: null, selectedAction: 0, bodyMode: 'question', scrollOffset: 0, bodyScrollOffsets: { question: 0 }, hscrollOffset: 0, hscrollMax: 0, wrapWidth, editorAvailable };
     const first = manifest.slots.findIndex((slot) => slot.id !== undefined && !slotAnswered(state, slot));
     if (first >= 0)
         state.currentIndex = first;
@@ -16,7 +35,7 @@ function buildInitialState(manifest, initialResponses, productKinds, editorAvail
 export function collectResponses(state) { return Object.fromEntries(state.responses); }
 function rebindPersist(internals) { internals.state.persist = () => internals.callbacks.onProgress?.(collectResponses(internals.state)); }
 export function mountPanel(opts) {
-    const internals = { state: buildInitialState(opts.manifest, opts.initialResponses, opts.productKinds ?? [], opts.onEditorRequest !== undefined, opts.cols), cols: opts.cols, rows: opts.rows, mounted: true, callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit, onDirty: opts.onDirty, onEditorRequest: opts.onEditorRequest } };
+    const internals = { state: buildInitialState(opts.manifest, opts.document, opts.initialResponses, opts.productKinds ?? [], opts.onEditorRequest !== undefined, opts.cols), cols: opts.cols, rows: opts.rows, mounted: true, callbacks: { onProgress: opts.onProgress, onComplete: opts.onComplete, onExit: opts.onExit, onDirty: opts.onDirty, onEditorRequest: opts.onEditorRequest } };
     rebindPersist(internals);
     const renderLines = () => {
         if (internals.state.phase === 'overview')
@@ -51,7 +70,7 @@ export function mountPanel(opts) {
                 return;
             const prior = collectResponses(internals.state);
             const merged = { ...(loadOpts?.initialResponses ?? {}), ...prior };
-            internals.state = buildInitialState(manifest, merged, loadOpts?.productKinds ?? internals.state.productKinds, internals.callbacks.onEditorRequest !== undefined, internals.cols);
+            internals.state = buildInitialState(manifest, loadOpts?.document, merged, loadOpts?.productKinds ?? internals.state.productKinds, internals.callbacks.onEditorRequest !== undefined, internals.cols);
             rebindPersist(internals);
         },
         canAcceptHostKeys: () => internals.mounted && internals.state.inputMode === null,

package/dist/clients/inbox/tui/render.js

@@ -29,10 +29,16 @@ function commentLabel(slot, anchor) {
 }
 export function renderOverview(state, cols, rows) {
     const maxW = Math.min(Math.max(20, cols - 4), 120);
+    const paneW = Math.max(20, cols - 4);
     const lines = ['', `  ${BOLD}${CYAN}${sanitize(state.manifest.title)}${RESET}`];
     if (state.manifest.subtitle)
         for (const line of wrap(sanitize(state.manifest.subtitle), maxW))
             lines.push(`  ${DIM}${line}${RESET}`);
+    if (state.displayMarkdown !== '') {
+        lines.push('');
+        for (const line of mdLines(state.displayMarkdown, maxW, paneW))
+            lines.push(`  ${line}`);
+    }
     const hasBody = state.slots.length > 0;
     if (hasBody)
         lines.push(`  ${DIM}${hline(maxW)}${RESET}`, '');

package/dist/clients/inbox/tui/types.d.ts

@@ -20,6 +20,10 @@ export interface TuiState {
     phase: Phase;
     currentIndex: number;
     manifest: PageManifest;
+    /** The authored display JSX (headings, paragraphs, prose outside slots),
+     *  projected to markdown — same projection the inline chat block uses.
+     *  Empty when the page has none, or its document was unavailable. */
+    displayMarkdown: string;
     slots: PageSlot[];
     responses: Map<string, SlotResponse>;
     productKinds: ProductPageComponents;
@@ -39,6 +43,9 @@ export interface TuiState {
 }
 export interface MountedPanelOpts {
     manifest: PageManifest;
+    /** The raw page document — needed only to project display markdown; a jsx
+     *  page without one just shows no display content, same as a read failure. */
+    document?: string;
     productKinds?: ProductPageComponents;
     initialResponses?: PageResponses | null;
     cols: number;
@@ -55,6 +62,7 @@ export interface MountedPanel {
     handleResize(cols: number, rows: number): string[];
     unmount(): void;
     loadPage(manifest: PageManifest, opts?: {
+        document?: string;
         initialResponses?: PageResponses | null;
         productKinds?: ProductPageComponents;
     }): void;

package/dist/commands/__tests__/human.test.js

@@ -101,11 +101,11 @@ test('human help carries the page authoring model and follows the page-surface s
 test('page_surface removes the terminal-only human surfaces from the tree', () => {
     const names = () => registerHuman().children.map((child) => child.name);
     withPageSurface(false, () => {
-        assert.deepEqual(names(), ['components', 'send', 'review', 'feedback', 'show', 'cancel', 'list', 'resolve']);
+        assert.deepEqual(names(), ['components', 'send', 'review', 'feedback', 'show', 'request', 'cancel', 'list', 'resolve']);
     });
     withPageSurface(true, () => {
         const children = names();
-        assert.deepEqual(children, ['components', 'send', 'feedback', 'cancel', 'list', 'resolve']);
+        assert.deepEqual(children, ['components', 'send', 'feedback', 'request', 'cancel', 'list', 'resolve']);
         const human = registerHuman();
         assert.doesNotMatch(human.help.model ?? '', /`review`|`show`/);
         assert.doesNotMatch(human.rootEntry?.useWhen ?? '', /review a document|live display/);

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

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

package/dist/commands/human/request.js

@@ -0,0 +1,281 @@
+// `crtr human request` — the command-line face of the durable programmatic
+// request contract. A request is an ordinary page ticket in the human inbox
+// whose creator may exit immediately: there is no reply bridge, the terminal
+// result is durable, and an optional named action carries the completion
+// document to a local command. Every leaf is a thin typed call on crtrd; the
+// daemon owns validation, settlement, and delivery.
+import { existsSync, readFileSync } from 'node:fs';
+import { defineBranch, defineLeaf } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+// ---------------------------------------------------------------------------
+// shared input helpers
+// ---------------------------------------------------------------------------
+function readJsonFile(path, field, shape) {
+    if (!existsSync(path)) {
+        throw new InputError({ error: 'not_found', message: `no such file: ${path}`, field, next: `Pass --${field} PATH pointing at a JSON file holding ${shape}.` });
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new InputError({ error: 'unreadable_file', message: `could not read ${path}: ${String(error)}`, field, next: 'Pass a readable JSON file.' });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new InputError({ error: 'invalid_json', message: `${path} is not valid JSON: ${String(error)}`, field, next: `Write ${shape} into the file as JSON.` });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new InputError({ error: 'invalid_field', message: `${path} must hold a JSON object`, field, next: `Write ${shape} into the file as a JSON object.` });
+    }
+    return parsed;
+}
+/** The page crosses the wire inline, so the CLI reads the authored file and
+ *  derives its dialect from the extension — the same rule page authoring uses. */
+function readPageFile(path) {
+    const html = /\.html?$/i.test(path);
+    if (!html && !path.endsWith('.tsx')) {
+        throw new InputError({ error: 'invalid_field', message: `page source file must be .tsx, .html, or .htm: ${path}`, field: 'page', next: 'Author the page as a .tsx module or a complete .html document.' });
+    }
+    if (!existsSync(path)) {
+        throw new InputError({ error: 'not_found', message: `page source file does not exist: ${path}`, field: 'page', next: 'Pass --page PATH pointing at the authored page.' });
+    }
+    return { dialect: html ? 'html' : 'jsx', source: readFileSync(path, 'utf8') };
+}
+function requestId(input) {
+    const id = typeof input['request_id'] === 'string' ? input['request_id'].trim() : '';
+    if (id === '') {
+        throw new InputError({ error: 'missing_request_id', message: 'a request id is required', field: 'request_id', next: 'Pass the request_id returned by `crtr human request create`.' });
+    }
+    return id;
+}
+/** The one projection of a request record onto leaf output. Absent fields stay
+ *  absent: a dismissal or a withdrawal has no responses to report. */
+function requestResult(dto) {
+    return {
+        request_id: dto.request_id,
+        state: dto.state,
+        title: dto.title,
+        ...(dto.subtitle === undefined ? {} : { subtitle: dto.subtitle }),
+        source: dto.source,
+        emitted_at: dto.emitted_at,
+        ...(dto.settled_at === undefined ? {} : { settled_at: dto.settled_at }),
+        ...(dto.responses === undefined ? {} : { responses: dto.responses }),
+        ...(dto.reason === undefined ? {} : { reason: dto.reason }),
+        ...(dto.actor === undefined ? {} : { actor: dto.actor }),
+        ...(dto.action === undefined ? {} : { action: dto.action }),
+        ...(dto.delivery === undefined ? {} : { delivery: dto.delivery }),
+    };
+}
+const RECORD_OUTPUT = [
+    { name: 'request_id', type: 'string', required: true, constraint: 'The request — the same 64-hex id the human inbox lists it under.' },
+    { name: 'state', type: 'pending | answered | dismissed | canceled', required: true, constraint: 'answered: the person (or an authorized responder) submitted the typed responses. dismissed: the recipient surface closed it unanswered. canceled: the requester withdrew it.' },
+    { name: 'title', type: 'string', required: true, constraint: 'Page title as currently published.' },
+    { name: 'subtitle', type: 'string', required: false, constraint: 'Page subtitle when the page carries one.' },
+    { name: 'source', type: 'object', required: true, constraint: 'Stored provenance from the request creator: sessionName?, askedBy?, emittedAt?, profileName?, nodeId?.' },
+    { name: 'emitted_at', type: 'string', required: true, constraint: 'UTC ISO instant of creation; a replace never changes it.' },
+    { name: 'settled_at', type: 'string', required: false, constraint: 'UTC ISO instant of the terminal result. Absent while pending.' },
+    { name: 'responses', type: 'object', required: false, constraint: 'The typed slot map, keyed by response-bearing component id. Present only when state is answered.' },
+    { name: 'reason', type: 'string', required: false, constraint: 'Note recorded by the dismissal or the withdrawal.' },
+    { name: 'actor', type: 'string', required: false, constraint: 'Who settled it, when the settling surface named itself.' },
+    { name: 'action', type: 'object', required: false, constraint: '{name, payload} frozen at creation; an omitted payload is frozen as null. Absent when no action is bound.' },
+    { name: 'delivery', type: 'object', required: false, constraint: 'Completion-delivery state for the bound action: {state: none | pending | running | accepted | permanent_failed, attempt, next_attempt_at?, accepted_at?, permanent_failed_at?, last_failure?}. Absent when no action is bound.' },
+];
+// ---------------------------------------------------------------------------
+// create
+// ---------------------------------------------------------------------------
+const createLeaf = defineLeaf({
+    name: 'create',
+    description: 'create a durable request from a JSON request file',
+    whenToUse: 'a script or backend needs a human decision that must survive its own exit, rather than an answer routed back to a live node.',
+    help: {
+        name: 'human request create',
+        summary: 'create one durable human request from the typed create object',
+        params: [
+            {
+                kind: 'flag',
+                name: 'request-file',
+                type: 'path',
+                required: true,
+                constraint: 'JSON file holding the create object: {"page":{"dialect":"jsx"|"html","source":"<the authored page text, inline>"}, "delivery"?:{"placement":"inline"|"panel"}, "source"?:{"sessionName"?,"askedBy"?,"emittedAt"?,"profileName"?,"nodeId"?}, "creator_cwd"?:"<absolute dir>", "action"?:{"name":"<declared action>","payload":<any JSON, null when omitted>}}. The page text is inline, never a path — the request must stay readable after the creating process is gone. creator_cwd defaults to this directory and is the scope the action name resolves from. delivery.inbox and delivery.reply are pinned: a programmatic request is always answerable from the inbox and never routes to an agent bridge. Unknown fields are rejected.',
+            },
+        ],
+        output: [
+            { name: 'request_id', type: 'string', required: true, constraint: 'The created request — pass it to get/replace/respond/cancel. Stable, and the deduplication key every completion destination keys on.' },
+            { name: 'state', type: 'string', required: true, constraint: 'Always "pending": creation never settles.' },
+            { name: 'action', type: 'object', required: false, constraint: '{name} of the frozen action binding. Absent when the request carries no action.' },
+            { name: 'delivery_state', type: 'string', required: true, constraint: 'Always "none" at creation: delivery is enqueued at settlement, not before.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Publishes one durable page ticket into the human inbox. It has no reply bridge and outlives this process.',
+            'An action name is resolved from the humanActions map in scope config (project ancestors, then user) BEFORE anything is written — an unknown or unusable name is rejected and leaves no inbox row for a person to answer.',
+            'A resolved action is frozen onto the ticket: name, payload, resolved argv, and cwd. replace can never change it; a different effect needs a cancel and a new request.',
+        ],
+    },
+    run: async (input) => {
+        const path = input['requestFile'];
+        const body = readJsonFile(path, 'request-file', 'the create object');
+        if (body['creator_cwd'] === undefined)
+            body['creator_cwd'] = process.cwd();
+        try {
+            const created = await cliClient().createHumanRequest(body);
+            return {
+                request_id: created.request_id,
+                state: created.state,
+                ...(created.action === undefined ? {} : { action: created.action }),
+                delivery_state: created.delivery_state,
+            };
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// get
+// ---------------------------------------------------------------------------
+const getLeaf = defineLeaf({
+    name: 'get',
+    description: 'read one request, its terminal result, and its delivery state',
+    whenToUse: 'you need the current state of a request you created — including the answers, once someone has settled it.',
+    help: {
+        name: 'human request get',
+        summary: 'read one durable request',
+        params: [{ kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' }],
+        output: [...RECORD_OUTPUT],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        try {
+            return requestResult(await cliClient().getHumanRequest(requestId(input)));
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// replace
+// ---------------------------------------------------------------------------
+const replaceLeaf = defineLeaf({
+    name: 'replace',
+    description: 'revise a pending request\'s page in place',
+    whenToUse: 'what you are asking changed while the request is still pending, and the same request should keep its identity and its frozen action.',
+    help: {
+        name: 'human request replace',
+        summary: 'republish a pending request\'s page',
+        params: [
+            { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
+            { kind: 'flag', name: 'page', type: 'path', required: true, constraint: 'The revised page: a .tsx module or a complete .html/.htm document. Read here and sent inline.' },
+        ],
+        output: [...RECORD_OUTPUT],
+        outputKind: 'object',
+        effects: [
+            'Rewrites the page and its typed response contract in place; open surfaces reload it without a second request.',
+            'Identity is untouched: request id, provenance, emitted time, delivery, and the frozen action binding all survive verbatim.',
+            'Refused with already_settled once the request has a terminal result — a settled request is revised by cancelling and creating a new one.',
+        ],
+    },
+    run: async (input) => {
+        const id = requestId(input);
+        const body = { page: readPageFile(input['page']) };
+        try {
+            return requestResult(await cliClient().replaceHumanRequest(id, body));
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// respond
+// ---------------------------------------------------------------------------
+const respondLeaf = defineLeaf({
+    name: 'respond',
+    description: 'settle a pending request with typed answers',
+    whenToUse: 'an authorized host is submitting the answers on the person\'s behalf, rather than the person answering in their inbox.',
+    help: {
+        name: 'human request respond',
+        summary: 'answer a pending request',
+        params: [
+            { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
+            {
+                kind: 'flag',
+                name: 'response-file',
+                type: 'path',
+                required: true,
+                constraint: 'JSON file holding the respond object: {"responses":{"<component_id>":{...}}, "actor"?:"<who answered>"}. One typed response per response-bearing component; the daemon validates the complete map against the currently published page.',
+            },
+        ],
+        output: [...RECORD_OUTPUT],
+        outputKind: 'object',
+        effects: [
+            'Settles the request as answered and drops it from the human inbox.',
+            'Competes with the person\'s own answer, a recipient dismissal, and a requester cancel through one first-writer-wins store: a losing attempt returns already_settled and changes nothing.',
+            'When an action is bound, the winning settlement enqueues one at-least-once completion delivery keyed on the request id.',
+        ],
+    },
+    run: async (input) => {
+        const id = requestId(input);
+        const body = readJsonFile(input['responseFile'], 'response-file', 'the respond object');
+        try {
+            return requestResult(await cliClient().respondHumanRequest(id, body));
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// cancel
+// ---------------------------------------------------------------------------
+const cancelLeaf = defineLeaf({
+    name: 'cancel',
+    description: 'withdraw a pending request',
+    whenToUse: 'the decision you asked for stopped mattering, or the effect must change — the action binding is immutable, so a new effect needs a new request.',
+    help: {
+        name: 'human request cancel',
+        summary: 'withdraw a pending request',
+        params: [
+            { kind: 'positional', name: 'request_id', type: 'string', required: true, constraint: 'request_id returned by `human request create`.' },
+            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Short note recorded on the terminal result and carried in the completion document.' },
+        ],
+        output: [...RECORD_OUTPUT],
+        outputKind: 'object',
+        effects: [
+            'Settles the request as canceled and drops it from the human inbox — the person is no longer asked.',
+            'Races the person\'s answer through the same first-writer-wins store; whoever lands first is authoritative and the loser returns already_settled.',
+            'When an action is bound, the winning settlement enqueues one completion delivery carrying the canceled event.',
+        ],
+    },
+    run: async (input) => {
+        const id = requestId(input);
+        const reason = typeof input['reason'] === 'string' && input['reason'] !== '' ? input['reason'] : undefined;
+        try {
+            return requestResult(await cliClient().cancelHumanRequest(id, reason === undefined ? {} : { reason }));
+        }
+        catch (error) {
+            rethrowAsCliError(error);
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export const humanRequestBranch = defineBranch({
+    name: 'request',
+    description: 'durable requests that outlive the process that made them',
+    whenToUse: 'a script or backend needs a human decision whose outcome must survive its own exit, instead of an answer pushed back to a live node.',
+    help: {
+        name: 'human request',
+        summary: 'durable programmatic human requests — create, read, revise, and settle',
+        model: 'A request is the same page ticket `human send` publishes, minus the agent bridge: nothing waits on it, and the outcome is read with `get` or carried to a local command by a named action. Reach for it when the caller will be gone before the person answers; when a live node should receive the answer, use `crtr human send` instead.\n\nThe page and its typed response contract stay revisable with `replace` while pending. The action binding does not: name, payload, resolved argv, and cwd are frozen at creation, so a different effect means `cancel` plus a new request. An action is a name declared in the humanActions map of scope config — there is no command, shell string, or callback URL anywhere in this surface.\n\nA request ends exactly once. `respond` (an authorized host answering), the person answering in their own inbox, a recipient dismissal, and `cancel` all compete through one first-writer-wins settlement; the loser gets already_settled and no second delivery. Only the winner enqueues the completion document, delivered at least once — the receiving command must deduplicate on the request id.',
+    },
+    children: [createLeaf, getLeaf, replaceLeaf, respondLeaf, cancelLeaf],
+});

package/dist/commands/human.js

@@ -9,6 +9,7 @@ import { humanList, humanResolve, humanCancel } from './human/queue.js';
 import { humanReviewBranch } from './human/review.js';
 import { humanFeedbackBranch } from './human/feedback.js';
 import { humanComponents } from './human/components.js';
+import { humanRequestBranch } from './human/request.js';
 import { pageHelpText } from './human/shared.js';
 export function registerHuman() {
     // `page_surface` marks a host whose human surface is a rendered page product
@@ -21,9 +22,10 @@ export function registerHuman() {
     const concept = pageSurface
         ? 'human-in-the-loop decisions and structured pages'
         : 'human-in-the-loop decisions, document review, and live display';
+    const durableRequests = '`request` publishes the same page with no bridge at all, for a caller that will have exited before the answer arrives: its outcome is read back or carried to a named local action.';
     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.';
+        ? `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. ${durableRequests}`
+        : `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. ${durableRequests} \`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: {
@@ -48,6 +50,7 @@ export function registerHuman() {
             ...(pageSurface ? [] : [humanReviewBranch]),
             humanFeedbackBranch,
             ...(pageSurface ? [] : [humanShow]),
+            humanRequestBranch,
             humanCancel,
             humanList,
             humanResolve,

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

@@ -105,8 +105,8 @@ export declare function overlayParam(name: string, overrides?: Partial<FlagParam
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export declare const DOC_RATIONALE_CONSTRAINT = "Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.";
-export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
+export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
 export declare const GUIDE_ROUTING_LINE = "The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: \"When planning or prioritizing work across this profile.\" Good: \"When the user mentions something from their todos, or asks what is still outstanding across this profile.\" The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: \"because only genuine first principles belong in taste memory.\" Bad: \"because keeping the test loop fast and free of speculative tests protects the development pace\" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: \"because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation.\" Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.";
-export declare const GUIDE_PREDICATE_VOCABULARY = "Gate and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.";
+export declare const GUIDE_PREDICATE_VOCABULARY = "Document gates, surface-entry gates, and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.";
 export declare const GUIDE_DOC_LINKS = "Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.";
 export {};

package/dist/commands/memory/shared.js

@@ -164,7 +164,7 @@ export function coerceGate(raw) {
     return result;
 }
 // The frontmatter keys one `surfaces` entry may carry.
-const SURFACE_ENTRY_KEYS = new Set(['on', 'match', 'match-frontmatter', 'at']);
+const SURFACE_ENTRY_KEYS = new Set(['on', 'match', 'match-frontmatter', 'gate', 'at']);
 /** Coerce one `--surface` value into a validated surfaces entry. Strict where
  *  the runtime parser is tolerant: a flag that would be silently dropped or
  *  trimmed at render time is an authoring mistake and fails HERE. The entry is
@@ -173,13 +173,13 @@ const SURFACE_ENTRY_KEYS = new Set(['on', 'match', 'match-frontmatter', 'at']);
 export function coerceSurface(raw) {
     const parsed = yamlParse(raw);
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw usage(`--surface must be a YAML/JSON object entry {on, at, match?, match-frontmatter?}, got ${JSON.stringify(parsed)}. ` +
+        throw usage(`--surface must be a YAML/JSON object entry {on, at, match?, match-frontmatter?, gate?}, got ${JSON.stringify(parsed)}. ` +
             `Example: --surface '{on: read, match: "src/**", at: content}'`);
     }
     const rec = parsed;
     for (const key of Object.keys(rec)) {
         if (!SURFACE_ENTRY_KEYS.has(key)) {
-            throw usage(`--surface: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, at)`);
+            throw usage(`--surface: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, gate, at)`);
         }
     }
     const on = rec['on'];
@@ -223,10 +223,15 @@ export function coerceSurface(raw) {
     if ((on === 'read' || on === 'memory-read' || on === 'command') && match === undefined && matchFrontmatter === undefined) {
         throw usage(`--surface: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`);
     }
+    const gate = rec['gate'];
+    if (gate !== undefined && (gate === null || typeof gate !== 'object' || Array.isArray(gate))) {
+        throw usage(`--surface: invalid \`gate\`: ${JSON.stringify(gate)} (expected a field→matcher object)`);
+    }
     return {
         on,
         ...(match !== undefined ? { match } : {}),
         ...(matchFrontmatter !== undefined ? { 'match-frontmatter': matchFrontmatter } : {}),
+        ...(gate !== undefined ? { gate } : {}),
         at,
     };
 }
@@ -503,7 +508,7 @@ export const FRONTMATTER_OVERLAY_PARAMS = {
     'when-and-why-to-read': { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'ONE routing sentence: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the reader\u2019s payoff \u2014 the consequence they secure for their task by reading \u2014 NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). Rendered verbatim as the preview.' },
     'short-form': { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form \u2014 a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
     'unlisted': { kind: 'flag', name: 'unlisted', type: 'bool', required: false, default: false, constraint: 'Suppress this doc from directory listings. Suppression only — explicit reads, [[links]], and surfaces entries still work.' },
-    'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to the doc’s own name directory. Constraints within one entry AND together; entries OR together.' },
+    'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to the doc’s own name directory. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
     'gate': { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate \u2014 YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
     'slash': { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) \u2014 the doc body becomes the command\u2019s injected prompt. Default false: most docs are consulted, not invoked.' },
 };
@@ -521,7 +526,7 @@ export function overlayParam(name, overrides = {}, extraConstraint) {
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export const DOC_RATIONALE_CONSTRAINT = 'Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.';
-export const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly — a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
+export const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly — a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.';
 export const GUIDE_ROUTING_LINE = 'The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: "When planning or prioritizing work across this profile." Good: "When the user mentions something from their todos, or asks what is still outstanding across this profile." The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: "because only genuine first principles belong in taste memory." Bad: "because keeping the test loop fast and free of speculative tests protects the development pace" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: "because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation." Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.';
-export const GUIDE_PREDICATE_VOCABULARY = 'Gate and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.';
+export const GUIDE_PREDICATE_VOCABULARY = 'Document gates, surface-entry gates, and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.';
 export const GUIDE_DOC_LINKS = 'Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.';

package/dist/commands/pkg/browse/doc-view.js

@@ -32,6 +32,8 @@ export function renderDocView(doc, width) {
             parts.push(entry.match.join(", "));
         if (entry.matchFrontmatter !== undefined)
             parts.push(JSON.stringify(entry.matchFrontmatter));
+        if (entry.gate !== undefined)
+            parts.push(JSON.stringify(entry.gate));
         out.push(...field(entry.on, parts.join("  "), viewWidth));
     }
     if (doc.unlisted)

package/dist/commands/sys/config.js

@@ -181,7 +181,7 @@ const configSet = defineLeaf({
         name: 'sys config set',
         summary: 'write a config value by dotted key',
         params: [
-            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: working_gerunds and whip_messages (non-empty JSON string arrays), brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys settings.` },
+            { kind: 'positional', name: 'key', type: 'string', required: true, constraint: `Dotted key path. User-scope scalar settings: ${SCALAR_SETTING_HELP}. Also supported: working_gerunds and whip_messages (non-empty JSON string arrays), brokerThresholds.warning and brokerThresholds.automaticReviveCap (user scope; integer >= 1), modelLadders.defaultProvider, and modelLadders.<anthropic|openai>.<ultra|strong|medium|light>. Keybindings are edited only through sys settings. humanActions is an object map edited directly in ~/.crouter/config.json or <repo>/.crouter/config.json.` },
             { kind: 'flag', name: 'value', type: 'string', required: true, constraint: 'value VALUE — string, required. working_gerunds and whip_messages accept JSON arrays; other values are stored as-is if quoted and coerced to number or boolean when unambiguous.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Scope to write to. Default: user. Project scope is supported only for modelLadders.' },
         ],
@@ -261,7 +261,7 @@ export const configBranch = defineBranch({
     whenToUse: 'inspecting crtr settings, changing supported scalar values, or locating config.json. Keybinding changes belong in sys settings.',
     help: {
         name: 'sys config',
-        summary: 'read and write crtr configuration, including model ladders',
+        summary: 'read and write crtr configuration, including model ladders; edit humanActions maps directly in ~/.crouter/config.json or <repo>/.crouter/config.json',
     },
     children: [configGet, configSet, configPath],
 });