@north-light/crouter 0.3.220 → 0.3.222

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/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/launch.d.ts

@@ -3,8 +3,12 @@ import { type ResolvedReview } from './review-client.js';
 export interface ReviewSurfaceOptions {
     review: ResolvedReview;
 }
-/** Mount the review document. Both callers — the inbox's `ReviewAdapter` and
- *  the viewer's `launchFileReview` — refuse a remote attach and resolve the
- *  review record themselves, so this function is never reached from a remote
- *  viewer and never reads a review record of its own. */
+/** Open a dedicated viewer window for a review without replacing the caller's
+ *  conversation window. The fresh viewer consumes the review id at startup. */
+export declare function openReviewWindow(host: SurfaceHost, review: ResolvedReview): boolean;
+/** Consume the review id handed to a dedicated attach viewer. */
+export declare function takeStartupReviewId(): string | undefined;
+/** Resolve and mount the review seeded into a dedicated viewer window. */
+export declare function openReviewSurfaceById(host: SurfaceHost, reviewId: string): Promise<void>;
+/** Mount the review document inside its dedicated viewer window. */
 export declare function openReviewSurface(host: SurfaceHost, opts: ReviewSurfaceOptions): Promise<void>;

package/dist/clients/inbox/review/launch.js

@@ -1,10 +1,60 @@
+import { basename } from 'node:path';
+import { getPaneOption, openNodeWindow, paneLocation, selectWindow, shellQuote, viewerSplitEnv, } from '../../../core/runtime/placement-tmux.js';
 import { ReviewDocumentSurface } from './document-surface.js';
 import { openLiveSource } from './live-source.js';
-import { createReviewClient } from './review-client.js';
-/** Mount the review document. Both callers — the inbox's `ReviewAdapter` and
- *  the viewer's `launchFileReview` — refuse a remote attach and resolve the
- *  review record themselves, so this function is never reached from a remote
- *  viewer and never reads a review record of its own. */
+import { createReviewClient, ReviewTerminalError, terminalRefusalNotice, } from './review-client.js';
+const ATTACH_REVIEW_ENV = 'CRTR_ATTACH_REVIEW_ID';
+/** Open a dedicated viewer window for a review without replacing the caller's
+ *  conversation window. The fresh viewer consumes the review id at startup. */
+export function openReviewWindow(host, review) {
+    if (host.capabilities.remote) {
+        host.notice('The review is unavailable in a remote attach — the file and companion live on the host.');
+        return false;
+    }
+    const callerPane = host.capabilities.selfPane;
+    if (callerPane === undefined || callerPane === '') {
+        host.notice('Opening a review needs a local viewer in tmux.');
+        return false;
+    }
+    const location = paneLocation(callerPane);
+    const nodeId = getPaneOption(callerPane, '@crtr_node');
+    if (location === null || nodeId === undefined || nodeId === '') {
+        host.notice('Could not resolve the current viewer for this review.');
+        return false;
+    }
+    const opened = openNodeWindow({
+        session: location.session,
+        name: `review:${basename(review.file)}`,
+        cwd: review.cwd,
+        env: { ...viewerSplitEnv(), [ATTACH_REVIEW_ENV]: review.reviewId },
+        command: `crtr surface attach to ${shellQuote(nodeId)}`,
+    });
+    if (opened === null) {
+        host.notice('tmux could not open the review window.');
+        return false;
+    }
+    selectWindow(location.session, opened.window);
+    return true;
+}
+/** Consume the review id handed to a dedicated attach viewer. */
+export function takeStartupReviewId() {
+    const reviewId = process.env[ATTACH_REVIEW_ENV];
+    delete process.env[ATTACH_REVIEW_ENV];
+    return reviewId === undefined || reviewId === '' ? undefined : reviewId;
+}
+/** Resolve and mount the review seeded into a dedicated viewer window. */
+export async function openReviewSurfaceById(host, reviewId) {
+    try {
+        const review = await createReviewClient().byId(reviewId);
+        await openReviewSurface(host, { review });
+    }
+    catch (error) {
+        host.notice(error instanceof ReviewTerminalError
+            ? terminalRefusalNotice(error)
+            : `couldn't open review: ${describeError(error)}`);
+    }
+}
+/** Mount the review document inside its dedicated viewer window. */
 export async function openReviewSurface(host, opts) {
     const review = opts.review;
     let source;

package/dist/clients/inbox/review/review-client.d.ts

@@ -13,6 +13,7 @@ export interface ResolvedReview {
     cwd: string;
 }
 export interface ReviewClient {
+    byId(reviewId: string): Promise<ResolvedReview>;
     byBridge(bridgeNodeId: string): Promise<ResolvedReview>;
     createInline(p: {
         originNodeId: string;

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

@@ -36,6 +36,10 @@ export function createReviewClient(opts = {}) {
         }
     };
     return {
+        async byId(reviewId) {
+            const review = await request(() => cliClient().getReview(reviewId));
+            return await resolveReview(review, review.companion_node_id, request);
+        },
         async byBridge(bridgeNodeId) {
             const review = await request(() => cliClient().getReviewByBridge(bridgeNodeId));
             return await resolveReview(review, review.companion_node_id, request);
@@ -63,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/review-adapter.d.ts

@@ -3,20 +3,13 @@ export interface ReviewAdapterOptions {
     host: SurfaceHost;
     dir: string;
 }
-/**
- * Resolves a durable review ticket to its canonical daemon review and mounts
- * the one terminal review surface. Approval flows entirely through
- * `reviewClient.submit` inside that surface — this adapter owns only the
- * remote refusal, the bridge lookup, and the mounted surface's lifecycle.
- */
+/** Resolve a durable review ticket and open it in its own tmux window. */
 export declare class ReviewAdapter {
     private readonly opts;
     private running;
     private stopped;
-    private mountedHandle;
     constructor(opts: ReviewAdapterOptions);
     start(): Promise<void>;
-    /** Toggle, cancellation, and controller teardown all take this same path. */
     stop(): Promise<void>;
     private run;
 }

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

@@ -1,18 +1,12 @@
 import { basename } from 'node:path';
 import { ApiError } from '../../api/errors.js';
-import { openReviewSurface } from './review/launch.js';
+import { openReviewWindow } from './review/launch.js';
 import { createReviewClient, ReviewTerminalError, terminalRefusalNotice } from './review/review-client.js';
-/**
- * Resolves a durable review ticket to its canonical daemon review and mounts
- * the one terminal review surface. Approval flows entirely through
- * `reviewClient.submit` inside that surface — this adapter owns only the
- * remote refusal, the bridge lookup, and the mounted surface's lifecycle.
- */
+/** Resolve a durable review ticket and open it in its own tmux window. */
 export class ReviewAdapter {
     opts;
     running = null;
     stopped = false;
-    mountedHandle;
     constructor(opts) {
         this.opts = opts;
     }
@@ -22,18 +16,12 @@ export class ReviewAdapter {
         this.running = this.run();
         return this.running;
     }
-    /** Toggle, cancellation, and controller teardown all take this same path. */
     async stop() {
-        if (this.stopped)
-            return;
         this.stopped = true;
-        this.mountedHandle?.close();
         if (this.running !== null)
             await this.running;
     }
     async run() {
-        // The refusal precedes the record read: a remote viewer can reach neither
-        // the reviewed file nor the companion's pane.
         if (this.opts.host.capabilities.remote) {
             this.opts.host.notice('The review is unavailable in a remote attach — the file and companion live on the host.');
             return;
@@ -47,46 +35,10 @@ export class ReviewAdapter {
             this.opts.host.notice(noticeForBridgeFailure(error));
             return;
         }
-        if (this.stopped)
-            return;
-        let resolveClosed;
-        const closed = new Promise((resolve) => { resolveClosed = resolve; });
-        const host = wrapHostForMount(this.opts.host, (handle) => {
-            this.mountedHandle = handle;
-            handle.onClose(() => {
-                this.mountedHandle = undefined;
-                resolveClosed();
-            });
-        });
-        await openReviewSurface(host, { review });
-        // A live-source failure reports through `host.notice` and returns without
-        // ever mounting.
-        if (this.mountedHandle === undefined)
-            return;
-        if (this.stopped) {
-            this.mountedHandle.close();
-            return;
-        }
-        await closed;
+        if (!this.stopped)
+            openReviewWindow(this.opts.host, review);
     }
 }
-/** Observes the one surface `openReviewSurface` mounts so this adapter can
- *  await its close and close it itself from `stop()`, without widening
- *  `SurfaceHost` or reaching into the real host's internals. */
-function wrapHostForMount(host, onMount) {
-    return {
-        capabilities: host.capabilities,
-        mount: (component, opts) => {
-            const handle = host.mount(component, opts);
-            onMount(handle);
-            return handle;
-        },
-        notice: (text, opts) => host.notice(text, opts),
-        suspendForChild: () => host.suspendForChild(),
-        focusNode: (nodeId) => host.focusNode(nodeId),
-        pickReviewFile: (spec) => host.pickReviewFile(spec),
-    };
-}
 function noticeForBridgeFailure(error) {
     if (error instanceof ReviewTerminalError)
         return terminalRefusalNotice(error);

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/lint.js

@@ -283,8 +283,9 @@ export const lintLeaf = defineLeaf({
                 const { profileId, manifest } = loadProfileManifest(profileIdOrName);
                 profileResolved = true;
                 lintDir(profileMemoryDir(profileId), 'user');
-                for (const dir of manifest.projects) {
+                for (const project of manifest.projects) {
                     profileProjects += 1;
+                    const dir = project.path;
                     const doors = frontDoorDocs(join(dir, '.crouter', 'memory'));
                     if (doors.length === 0) {
                         findings.push({

package/dist/commands/memory/read.js

@@ -81,6 +81,7 @@ export const readLeaf = defineLeaf({
         outputKind: 'object',
         effects: [
             'Reads the document. A document that embeds shell (`!`cmd`` or a ```! block) runs those commands once, in the current working directory.',
+            'Records a content delivery for this node: a document whose profile project caps automatic boot and workspace-open disclosure below content is still returned whole here, and unsolicited channels stay quiet about it afterwards.',
         ],
     },
     run: async (input) => {

package/dist/commands/memory.js

@@ -23,7 +23,7 @@ export function registerMemory() {
         help: {
             name: 'memory',
             summary: 'list, read, search, and write memory documents — knowledge and preferences',
-            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name — a directory name is a valid read target answering with its listing. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content).',
+            model: 'Documents have path-derived identities and resolve across layered scopes in precedence order: node > project stack > profile > user > builtin. Browse the inventory with `list` to see what is stored; address a document directly with `read` once you know its name — a directory name is a valid read target answering with its listing. One verb per operation: `write` creates, `edit` revises (every revision carries a rationale and is recorded), `move` relocates or renames a doc and rewrites inbound `[[refs]]` corpus-wide, `delete` removes, and `history` reads how a document reached its current state. Beyond listings, delivery is explicit `surfaces` routing: each entry names the event that fires it (boot, workspace-open, read, memory-read, command) and how much delivers (name, preview, content). A selected profile widens the project stack to every project in its purview, and each of those relationships caps what its stores deliver to the boot and workspace-open events; `read`, find, listings, and file- and command-routed delivery see the full corpus regardless.',
         },
         children: [listLeaf, readLeaf, findLeaf, writeLeaf, editLeaf, moveLeaf, historyLeaf, deleteLeaf, originLeaf, lintLeaf],
     });