@north-light/crouter 0.3.231 → 0.3.232

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

@@ -9,7 +9,8 @@ import { parseArgv } from '../../core/command.js';
 import { renderLeafArgv } from '../../core/help.js';
 import { componentDoc, renderComponentCatalog, renderComponentContract } from '../../core/human/component-docs.js';
 import { humanComponents } from '../human/components.js';
-import { humanSend } from '../human/prompts.js';
+import { humanSend as buildHumanSend } from '../human/prompts.js';
+const humanSend = buildHumanSend();
 import { registerHuman } from '../human.js';
 import { pageHelpText } from '../human/shared.js';
 const nlThreadRegistration = {
@@ -69,7 +70,10 @@ describe('human page input', () => {
     });
     test('send help keeps page authoring at the human branch and makes reply routing explicit', () => {
         const rendered = renderLeafArgv(humanSend.help);
-        assert.match(rendered, /^human send: send a durable TSX or HTML page\./);
+        assert.match(rendered, /^human send: send a durable TSX page\./);
+        // HTML is named on the send leaf only where an HTML page can be read.
+        assert.doesNotMatch(rendered, /HTML|\.html/);
+        assert.match(renderLeafArgv(buildHumanSend(true).help), /^human send: send a durable TSX or HTML page\./);
         assert.match(rendered, /Page authoring: `crtr human -h`\./);
         assert.doesNotMatch(rendered, /--no-reply|--reply/);
         assert.match(rendered, /page_id/);
@@ -85,7 +89,12 @@ test('human help carries the page authoring model and follows the page-surface s
         assert.ok(human.help.model?.includes(help.authoring));
         assert.ok(human.help.model?.includes('`crtr human components`'));
         assert.doesNotMatch(human.help.model ?? '', /doc check/);
-        assert.match(human.help.model ?? '', /\.html/);
+        // A terminal renders an HTML page as its title and nothing else, so the
+        // dialect is not offered here; what IS offered is the reason each question
+        // must stand alone on this host.
+        assert.doesNotMatch(human.help.model ?? '', /\.html/);
+        assert.match(human.help.model ?? '', /one question at a time/);
+        assert.match(human.help.model ?? '', /rather than running your module/);
     });
     withPageSurface(true, () => {
         const human = registerHuman();
@@ -93,6 +102,12 @@ test('human help carries the page authoring model and follows the page-surface s
         assert.notEqual(help.authoring, pageHelpText(false).authoring);
         assert.equal(human.rootEntry?.useWhen, help.rootUseWhen);
         assert.ok(human.help.model?.includes(help.authoring));
+        assert.match(human.help.model ?? '', /\.html/);
+        // The flattening warning is terminal-only: a page surface runs the module.
+        assert.doesNotMatch(human.help.model ?? '', /rather than running your module/);
+        // Both surfaces reach for pages by default; only the reason differs.
+        for (const surface of [true, false])
+            assert.match(pageHelpText(surface).authoring, /Use inline pages as the default way/);
     });
 });
 // The gate itself, not its prose: a page-surface host must not carry the two

package/dist/commands/__tests__/node-message.test.js

@@ -2,13 +2,13 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { renderLeafArgv } from '../../core/help.js';
 import { nodeMessage } from '../node/message.js';
-test('node message send help documents the finalized-node re-task gate', () => {
+test('node message send help documents the reopen re-task semantics', () => {
     const send = nodeMessage.children.find((child) => child.kind === 'leaf' && child.name === 'send');
     if (send === undefined || send.kind !== 'leaf')
         assert.fail('node message send leaf is missing');
     const rendered = renderLeafArgv(send.help);
     assert.match(rendered, /--reopen/);
-    assert.match(rendered, /Required to re-task a finalized target/);
-    assert.match(rendered, /clears a finalized target's finalization latch before delivery/);
+    assert.match(rendered, /Re-task the target: commits it resident and clears any finalization latch before delivery/);
+    assert.match(rendered, /valid for live, parked, and finalized targets/);
     assert.match(rendered, /Without it, a finalized target rejects delivery before an inbox entry is appended or a revive is attempted/);
 });

package/dist/commands/api-client.js

@@ -18,7 +18,7 @@ import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
 import { join } from 'node:path';
 import { CrtrClient, ApiError } from '../api/index.js';
 import { apiErrorToCliError } from '../core/io.js';
-import { ensureDaemon } from '../daemon/manage.js';
+import { autostartDisabled, ensureDaemon } from '../daemon/manage.js';
 import { DAEMON_STARTUP_WINDOW_MS } from '../daemon/startup-policy.js';
 import { readState } from '../core/config.js';
 import { resolveRemoteCanvasTarget } from '../core/remote-canvas-target.js';
@@ -60,12 +60,6 @@ export async function getNodeOrNull(nodeId) {
 // ---------------------------------------------------------------------------
 // cliClient — the one place the CLI constructs a daemon client
 // ---------------------------------------------------------------------------
-/** Whether autostart is suppressed for this invocation. `--no-autostart` or
- *  `CRTR_NO_DAEMON_AUTOSTART=1` forces fail-loud on a cold socket (spec §7.1) —
- *  for environments that manage crtrd externally and want the diagnostic. */
-function autostartDisabled() {
-    return process.env['CRTR_NO_DAEMON_AUTOSTART'] === '1' || process.argv.includes('--no-autostart');
-}
 /** Bounded tail of crtrd.err surfaced on a cold-start `/healthz` timeout.
  *  Large enough to catch a real startup failure/stack trace,
  *  small enough that a runaway daemon log can never leak unbounded into a CLI

package/dist/commands/canvas-config.js

@@ -41,13 +41,7 @@ const canvasConfigAdd = defineLeaf({
             { kind: 'flag', name: 'relay-token', type: 'string', required: true, constraint: 'Must be exactly `-` — the raw token is read from stdin, never argv (keeps it out of shell history). Any other value is rejected.' },
             { kind: 'flag', name: 'cp', type: 'string', required: false, constraint: 'Optional control-plane origin, when this target has one distinct from the preview endpoint.' },
         ],
-        output: [
-            { name: 'name', type: 'string', required: true, constraint: 'The target name just registered.' },
-            { name: 'previewEndpoint', type: 'string', required: true, constraint: 'The stored preview endpoint.' },
-            { name: 'relayTokenRef', type: 'string', required: true, constraint: 'The secrets-store key the token was written under (equals name).' },
-            { name: 'cpOrigin', type: 'string', required: false, constraint: 'The stored control-plane origin, when --cp was given.' },
-            { name: 'tokenStored', type: 'boolean', required: true, constraint: 'Always true on success \u2014 confirms the token was written to the 0600 store.' },
-        ],
+        output: [],
         outputKind: 'object',
         effects: ['Writes remoteCanvas.targets.<name> to config.json (previewEndpoint, relayTokenRef, cpOrigin).', 'Writes the raw token to the 0600 secrets store under relayTokenRef \u2014 never to config.json or stdout.'],
     },
@@ -78,9 +72,9 @@ const canvasConfigAdd = defineLeaf({
             cfg.remoteCanvas.targets[name] = target;
         });
         setRelayToken(name, token, SCOPE);
-        return { name, previewEndpoint, relayTokenRef: name, ...(cp ? { cpOrigin: cp } : {}), tokenStored: true };
+        return {};
     },
-    render: (r) => `Registered remote canvas target '${r['name']}' → ${r['previewEndpoint']} (token stored).`,
+    render: () => 'Registered remote canvas target (token stored).',
 });
 // ---------------------------------------------------------------------------
 // canvas config list
@@ -169,9 +163,7 @@ const canvasConfigRemove = defineLeaf({
         params: [
             { kind: 'positional', name: 'name', required: true, constraint: 'Target name.' },
         ],
-        output: [
-            { name: 'removed', type: 'string', required: true, constraint: 'The target name removed.' },
-        ],
+        output: [],
         outputKind: 'object',
         effects: ['Deletes remoteCanvas.targets.<name> from config.json.', 'Deletes the stored token under relayTokenRef from the secrets store.'],
     },
@@ -190,9 +182,9 @@ const canvasConfigRemove = defineLeaf({
             delete c.remoteCanvas.targets[name];
         });
         deleteRelayToken(target.relayTokenRef, SCOPE);
-        return { removed: name };
+        return {};
     },
-    render: (r) => `Removed remote canvas target '${r['removed']}'.`,
+    render: () => 'Removed remote canvas target.'
 });
 // ---------------------------------------------------------------------------
 // Export — mounted under `crtr canvas`

package/dist/commands/canvas-use.js

@@ -18,9 +18,7 @@ export const canvasUseLeaf = defineLeaf({
             { kind: 'positional', name: 'name', required: false, constraint: 'A remote canvas target registered via `crtr canvas config add`. Mutually exclusive with --local; exactly one of the two is required.' },
             { kind: 'flag', name: 'local', type: 'bool', required: false, constraint: 'Switch back to the local canvas. Mutually exclusive with <name>.' },
         ],
-        output: [
-            { name: 'active', type: 'string', required: false, constraint: 'The now-active target name, or omitted/null for local.' },
-        ],
+        output: [],
         outputKind: 'object',
         effects: ['Writes state.json\u2019s activeCanvas (user scope).'],
     },
@@ -45,7 +43,7 @@ export const canvasUseLeaf = defineLeaf({
             updateState(SCOPE, (s) => {
                 s.activeCanvas = null;
             });
-            return { active: null };
+            return {};
         }
         if (getRemoteCanvasTarget(name, SCOPE) === undefined) {
             throw new InputError({
@@ -57,7 +55,7 @@ export const canvasUseLeaf = defineLeaf({
         updateState(SCOPE, (s) => {
             s.activeCanvas = name;
         });
-        return { active: name };
+        return {};
     },
-    render: (r) => (r['active'] ? `Active canvas: ${r['active']}.` : 'Active canvas: local.'),
+    render: () => 'Canvas selection updated.'
 });

package/dist/commands/cron.js

@@ -18,14 +18,14 @@ import { resolve as resolvePath } from 'node:path';
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError, readStdinRaw } from '../core/io.js';
 import { parseWhen, parseCadence, cadenceDisplay } from '../core/wake.js';
-import { loadProfileManifest } from '../core/profiles/manifest.js';
+import { resolveProfileOperand } from '../core/profiles/manifest.js';
 import { profilesStateBlock } from '../core/profiles/state-block.js';
 import { cliClient, rethrowAsCliError } from './api-client.js';
-/** Canonicalize a profile operand (id OR manifest name) to its profile id so
+/** Canonicalize a profile operand (id, manifest name, or nearest match) to its profile id so
  *  every cron row and scope query speaks the same identity. Resolution errors
  *  name the available profiles on this host. */
 function canonicalProfileId(raw) {
-    return loadProfileManifest(raw.trim()).profileId;
+    return resolveProfileOperand(raw.trim()).profileId;
 }
 /** Build ParseOpts, including `tz` only when actually provided. */
 function parseOpts(now, tz) {
@@ -147,12 +147,11 @@ const addLeaf = defineLeaf({
             { kind: 'flag', name: 'overlap', type: 'enum', choices: ['skip', 'queue', 'replace'], required: false, default: 'skip', constraint: 'A fire landing while the previous run is still going. skip (default): log the skip, do not start a second run. queue: run once more after the current finishes (depth 1; further fires collapse). replace: kill the running instance and start fresh.' },
             { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory every run executes in. Defaults to this one, must exist now, and is snapshotted onto the row — a cron never re-resolves its context.' },
             { kind: 'flag', name: 'env', type: 'string', required: false, repeatable: true, constraint: 'KEY=VALUE added to every run\'s env (repeat per variable). Snapshotted at arm time; overlays the operational env, alongside $CRTR_CRON_ID/$CRTR_CRON_NAME/$CRTR_RUN_ID.' },
-            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile the runs resolve config and credentials under, and — under --scope profile — the profile this cron lists and cancels within. A profile id or unique manifest name from the <profiles> list below; anything else is rejected. Defaults to the calling node\'s ($CRTR_PROFILE_ID).' },
+            { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile the runs resolve config and credentials under, and — under --scope profile — the profile this cron lists and cancels within. A profile id or manifest name from the <profiles> list below; a close-enough name resolves to the nearest profile. Defaults to the calling node\'s ($CRTR_PROFILE_ID).' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['profile', 'global'], required: false, constraint: 'Who lists and cancels this cron: profile (default when a profile is resolved) confines it to that profile; global makes it canvas-home-wide, visible from every profile.' },
         ],
         output: [
-            { name: 'cron_id', type: 'string', required: true, constraint: 'The armed cron — inspect with `cron show <cron_id>`, cancel with `cron cancel <cron_id>`.' },
-            { name: 'name', type: 'string', required: true, constraint: 'The label as armed.' },
+            { name: 'cron_id', type: 'string', required: true, constraint: 'The server-minted armed cron id — inspect with `cron show <cron_id>`, cancel with `cron cancel <cron_id>`.' },
             { name: 'fire_at', type: 'string', required: true, constraint: 'Next fire (UTC ISO).' },
             { name: 'recur', type: 'string', required: true, constraint: 'Cadence display; "none" for a one-shot.' },
         ],
@@ -267,12 +266,12 @@ const addLeaf = defineLeaf({
             overlap: input['overlap'] ?? 'skip',
         })
             .catch(rethrowAsCliError);
-        return { cron_id: dto.cron_id, name: dto.name, fire_at: dto.fire_at, recur: cadenceDisplay(dto.recur) };
+        return { cron_id: dto.cron_id, fire_at: dto.fire_at, recur: cadenceDisplay(dto.recur) };
     },
     render: (r) => {
         const recur = String(r['recur']);
         const cadence = recur === 'none' ? 'one-shot (row deleted after the run)' : recur;
-        return `Cron armed — ${String(r['name'])} (${String(r['cron_id'])}).\n\n- next fire: ${String(r['fire_at'])}\n- cadence: ${cadence}\n\nIt runs daemon-side; nothing more to do here. Inspect it with \`crtr cron show ${String(r['cron_id'])}\`; cancel any time with \`crtr cron cancel ${String(r['cron_id'])}\`.`;
+        return `Cron armed — ${String(r['cron_id'])}.\n\n- next fire: ${String(r['fire_at'])}\n- cadence: ${cadence}\n\nIt runs daemon-side; nothing more to do here. Inspect it with \`crtr cron show ${String(r['cron_id'])}\`; cancel any time with \`crtr cron cancel ${String(r['cron_id'])}\`.`;
     },
 });
 // ---------------------------------------------------------------------------
@@ -460,19 +459,16 @@ const pauseLeaf = defineLeaf({
         params: [
             { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to pause (from `cron list`).' },
         ],
-        output: [
-            { name: 'cron_id', type: 'string', required: true, constraint: 'The paused cron.' },
-            { name: 'state', type: 'string', required: true, constraint: 'Always "paused".' },
-        ],
+        output: [],
         outputKind: 'object',
         effects: ['Stops the cron firing until `cron resume`. An in-flight run settles normally; the row just stops being due.'],
     },
     run: async (input) => {
         const id = requireCronId(input);
-        const dto = await cliClient().pauseCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
-        return { cron_id: dto.cron_id, state: dto.state };
+        await cliClient().pauseCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
+        return {};
     },
-    render: (r) => `Cron ${String(r['cron_id'])} paused — it will not fire until \`crtr cron resume ${String(r['cron_id'])}\`.`,
+    render: () => 'Cron paused.'
 });
 const resumeLeaf = defineLeaf({
     name: 'resume',
@@ -485,8 +481,6 @@ const resumeLeaf = defineLeaf({
             { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to resume (from `cron list`).' },
         ],
         output: [
-            { name: 'cron_id', type: 'string', required: true, constraint: 'The resumed cron.' },
-            { name: 'state', type: 'string', required: true, constraint: 'Always "active".' },
             { name: 'fire_at', type: 'string', required: true, constraint: 'Next fire — if already past, it fires on the next daemon tick.' },
         ],
         outputKind: 'object',
@@ -495,9 +489,9 @@ const resumeLeaf = defineLeaf({
     run: async (input) => {
         const id = requireCronId(input);
         const dto = await cliClient().resumeCron(id, scopeQuery()).catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
-        return { cron_id: dto.cron_id, state: dto.state, fire_at: dto.fire_at };
+        return { fire_at: dto.fire_at };
     },
-    render: (r) => `Cron ${String(r['cron_id'])} resumed — next fire ${String(r['fire_at'])} (if that is already past, it fires on the next tick).`,
+    render: (r) => `Cron resumed — next fire ${String(r['fire_at'])} (if that is already past, it fires on the next tick).`,
 });
 // ---------------------------------------------------------------------------
 // cron cancel
@@ -512,7 +506,7 @@ const cancelLeaf = defineLeaf({
         params: [
             { kind: 'positional', name: 'cron-id', required: true, constraint: 'The cron to remove (from `cron list`, or $CRTR_CRON_ID inside a run).' },
         ],
-        output: [{ name: 'canceled', type: 'string', required: true, constraint: 'The removed (or already-absent) cron id.' }],
+        output: [],
         outputKind: 'object',
         effects: ['Deletes the cron row and its run history; kills any in-flight run. A no-op if already gone.'],
     },
@@ -525,9 +519,9 @@ const cancelLeaf = defineLeaf({
             ...(runId === undefined || runId === '' ? {} : { run_id: runId }),
         })
             .catch((err) => rethrowAsCliError(err, 'Check the id against `crtr cron list`.'));
-        return { canceled: id };
+        return {};
     },
-    render: (r) => `Cron ${String(r['canceled'])} canceled — it will not fire again.`,
+    render: () => 'Cron canceled.'
 });
 // ---------------------------------------------------------------------------
 // Registration

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

@@ -17,5 +17,5 @@ export declare function sender(): Promise<{
     source: PageSource;
     lifecycle: 'terminal' | 'resident' | null;
 }>;
-export declare const humanSend: import("../../core/command.js").LeafDef;
+export declare function humanSend(pageSurface?: boolean): import("../../core/command.js").LeafDef;
 export declare const humanShow: import("../../core/command.js").LeafDef;

package/dist/commands/human/prompts.js

@@ -15,7 +15,10 @@ import { pageManifestPath } from '../../core/human/convention.js';
 import { isResponseBearingSlot, validateAuthoredPageManifest } from '../../core/human/page-schema.js';
 import { display } from '../../core/termrender/display.js';
 import { pageHelpText, resolveMaxPanes } from './shared.js';
-const PAGE_HELP = pageHelpText();
+// Only `pageHint` is surface-independent; everything else this file reads off
+// PageHelpText is chosen per host, so the send leaf is built for a surface
+// rather than defined once as a const.
+const PAGE_HINT = pageHelpText().pageHint;
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
@@ -159,122 +162,125 @@ function queuedFollowUp() {
 // ---------------------------------------------------------------------------
 // send
 // ---------------------------------------------------------------------------
-export const humanSend = defineLeaf({
-    name: 'send',
-    description: 'send a durable page with explicit delivery',
-    whenToUse: 'you need to put structured TSX or HTML content in a conversation and optionally project it to the inbox; a page carrying response-bearing components routes completion back to this node.',
-    help: {
-        name: 'human send',
-        summary: 'send a durable TSX or HTML page',
-        guide: 'Page authoring: `crtr human -h`.',
-        params: [
-            { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: 'The page module source (TSX) on stdin. Provide exactly one of stdin or --page PATH. HTML is file-authored.' },
-            { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HELP.pageHint} A .tsx file is JSX; .html/.htm is complete HTML. Provide exactly one of --page or stdin.` },
-            { kind: 'flag', name: 'placement', type: 'enum', choices: ['inline', 'panel'], required: false, default: 'inline', constraint: "Where the page is delivered. inline renders in this conversation's transcript; panel opens from the inbox beside it." },
-            { kind: 'flag', name: 'inbox', type: 'bool', required: false, constraint: 'Project this page into the inbox. Mutually exclusive with --no-inbox.' },
-            { kind: 'flag', name: 'no-inbox', type: 'bool', required: false, constraint: "Do not project this page into the inbox, leaving this conversation's transcript as its only route to the user. Mutually exclusive with --inbox, and refused from a terminal node, whose transcript nobody reads once it finishes." },
-            { kind: 'flag', name: 'replace', type: 'string', required: false, constraint: 'Page id returned by an earlier send. Rewrites source in place while retaining its delivery and transcript anchor. Refused once the page is settled or canceled. Not combinable with delivery flags.' },
-        ],
-        output: [
-            { name: 'page_id', type: 'string', required: true, constraint: 'Identifier for the page; pass it as --replace to revise source in place.' },
-            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory holding page.tsx or page.html, optional page.js, page.json, and response lifecycle files when delivery needs them.' },
-            { name: 'placement', type: 'inline | panel', required: true, constraint: 'Resolved page placement.' },
-            { name: 'inbox', type: 'boolean', required: true, constraint: 'Whether the page is projected into the inbox.' },
-            { name: 'reply', type: 'boolean', required: true, constraint: 'Whether completion is routed back through a human bridge. Not a flag: true exactly when the page has response-bearing components.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'What happens next; never instructs the caller to poll.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Writes one durable page record. Inbox projection follows the delivery flags, except from a terminal node, which always projects; reply routing follows the page\'s own components.',
-            "A display-only page's inbox entry is a notice, not a task: it clears itself once the person has actually seen the page, wherever they see it.",
-            'A reply-bearing page creates a kind:"human" bridge under the caller and routes completion back.',
-            '--replace rewrites source in place while retaining delivery and emitted time; open surfaces reload it without creating another page.',
-        ],
-    },
-    run: async (input, context) => {
-        const { sourceFile, tempDir } = pageInput(input);
-        const replacePage = input['replace'];
-        const deliveryFlags = ['placement', 'inbox', 'noInbox'];
-        if (input['inbox'] === true && input['noInbox'] === true) {
-            throw new InputError({ error: 'bad_invocation', message: 'received conflicting delivery flags', field: 'inbox', next: 'Pass at most one of --inbox and --no-inbox.' });
-        }
-        if (replacePage !== undefined && deliveryFlags.some((flag) => context?.providedParams.has(flag) === true)) {
-            throw new InputError({ error: 'bad_invocation', message: '--replace cannot change delivery', field: 'replace', next: 'Remove delivery flags: replacement retains the page placement, inbox, reply, and emitted time.' });
-        }
-        try {
-            if (replacePage !== undefined) {
-                const prior = replacedPage(replacePage);
-                // The human's submit wins the race with a revision: once the ticket has
-                // any terminal outcome, replacement is refused, and that refusal is the
-                // reviser's signal that the ticket is closed.
-                if (readTicketResult(ticketDir(replacePage)) !== null) {
+export function humanSend(pageSurface = false) {
+    const pageHelp = pageHelpText(pageSurface);
+    return defineLeaf({
+        name: 'send',
+        description: 'send a durable page with explicit delivery',
+        whenToUse: pageHelp.sendWhenToUse,
+        help: {
+            name: 'human send',
+            summary: pageHelp.sendSummary,
+            guide: 'Page authoring: `crtr human -h`.',
+            params: [
+                { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: pageHelp.stdinConstraint },
+                { kind: 'flag', name: 'page', type: 'path', required: false, constraint: `${PAGE_HINT} ${pageHelp.pageFlagConstraint}` },
+                { kind: 'flag', name: 'placement', type: 'enum', choices: ['inline', 'panel'], required: false, default: 'inline', constraint: "Where the page is delivered. inline renders in this conversation's transcript; panel opens from the inbox beside it." },
+                { kind: 'flag', name: 'inbox', type: 'bool', required: false, constraint: 'Project this page into the inbox. Mutually exclusive with --no-inbox.' },
+                { kind: 'flag', name: 'no-inbox', type: 'bool', required: false, constraint: "Do not project this page into the inbox, leaving this conversation's transcript as its only route to the user. Mutually exclusive with --inbox, and refused from a terminal node, whose transcript nobody reads once it finishes." },
+                { kind: 'flag', name: 'replace', type: 'string', required: false, constraint: 'Page id returned by an earlier send. Rewrites source in place while retaining its delivery and transcript anchor. Refused once the page is settled or canceled. Not combinable with delivery flags.' },
+            ],
+            output: [
+                { name: 'page_id', type: 'string', required: true, constraint: 'Identifier for the page; pass it as --replace to revise source in place.' },
+                { name: 'dir', type: 'string', required: true, constraint: pageHelp.dirConstraint },
+                { name: 'placement', type: 'inline | panel', required: true, constraint: 'Resolved page placement.' },
+                { name: 'inbox', type: 'boolean', required: true, constraint: 'Whether the page is projected into the inbox.' },
+                { name: 'reply', type: 'boolean', required: true, constraint: 'Whether completion is routed back through a human bridge. Not a flag: true exactly when the page has response-bearing components.' },
+                { name: 'follow_up', type: 'string', required: true, constraint: 'What happens next; never instructs the caller to poll.' },
+            ],
+            outputKind: 'object',
+            effects: [
+                'Writes one durable page record. Inbox projection follows the delivery flags, except from a terminal node, which always projects; reply routing follows the page\'s own components.',
+                "A display-only page's inbox entry is a notice, not a task: it clears itself once the person has actually seen the page, wherever they see it.",
+                'A reply-bearing page creates a kind:"human" bridge under the caller and routes completion back.',
+                '--replace rewrites source in place while retaining delivery and emitted time; open surfaces reload it without creating another page.',
+            ],
+        },
+        run: async (input, context) => {
+            const { sourceFile, tempDir } = pageInput(input);
+            const replacePage = input['replace'];
+            const deliveryFlags = ['placement', 'inbox', 'noInbox'];
+            if (input['inbox'] === true && input['noInbox'] === true) {
+                throw new InputError({ error: 'bad_invocation', message: 'received conflicting delivery flags', field: 'inbox', next: 'Pass at most one of --inbox and --no-inbox.' });
+            }
+            if (replacePage !== undefined && deliveryFlags.some((flag) => context?.providedParams.has(flag) === true)) {
+                throw new InputError({ error: 'bad_invocation', message: '--replace cannot change delivery', field: 'replace', next: 'Remove delivery flags: replacement retains the page placement, inbox, reply, and emitted time.' });
+            }
+            try {
+                if (replacePage !== undefined) {
+                    const prior = replacedPage(replacePage);
+                    // The human's submit wins the race with a revision: once the ticket has
+                    // any terminal outcome, replacement is refused, and that refusal is the
+                    // reviser's signal that the ticket is closed.
+                    if (readTicketResult(ticketDir(replacePage)) !== null) {
+                        throw new InputError({
+                            error: 'page_settled',
+                            message: `page ${replacePage} already has a terminal outcome`,
+                            field: 'replace',
+                            next: 'The page was answered or canceled; nothing on it can change now. Raise a new page if more is needed.',
+                        });
+                    }
+                    // A revision changes only the content. Identity, routing, and emitted
+                    // time stay the original sender's, so the prior source is inherited
+                    // verbatim — a fork revising the page must not repoint its provenance.
+                    const revised = submitAuthoredPage(() => preparePage({ sourceFile, source: prior.source, productKinds: pageProductKinds(), delivery: prior.delivery }));
+                    const { dir } = publishPage(ticketDir(replacePage), revised);
+                    return { page_id: replacePage, dir, ...prior.delivery, follow_up: 'Replaced in place. Every open surface reloads it; delivery and emitted time are unchanged.' };
+                }
+                const { source, lifecycle } = await sender();
+                // A terminal node finishes and its transcript stops being read, so the
+                // inbox is the only surface its page can still reach a human on. Refuse
+                // rather than quietly overriding the flag: the caller asked for a page
+                // nobody would ever see, and that is worth knowing.
+                if (lifecycle === 'terminal' && input['noInbox'] === true) {
                     throw new InputError({
-                        error: 'page_settled',
-                        message: `page ${replacePage} already has a terminal outcome`,
-                        field: 'replace',
-                        next: 'The page was answered or canceled; nothing on it can change now. Raise a new page if more is needed.',
+                        error: 'invalid_page_delivery',
+                        message: 'a terminal node cannot send a page --no-inbox',
+                        field: 'inbox',
+                        next: 'Drop --no-inbox. This node finishes, and nobody reads a finished node\'s transcript, so a page kept out of the inbox reaches no one.',
                     });
                 }
-                // A revision changes only the content. Identity, routing, and emitted
-                // time stay the original sender's, so the prior source is inherited
-                // verbatim — a fork revising the page must not repoint its provenance.
-                const revised = submitAuthoredPage(() => preparePage({ sourceFile, source: prior.source, productKinds: pageProductKinds(), delivery: prior.delivery }));
-                const { dir } = publishPage(ticketDir(replacePage), revised);
-                return { page_id: replacePage, dir, ...prior.delivery, follow_up: 'Replaced in place. Every open surface reloads it; delivery and emitted time are unchanged.' };
-            }
-            const { source, lifecycle } = await sender();
-            // A terminal node finishes and its transcript stops being read, so the
-            // inbox is the only surface its page can still reach a human on. Refuse
-            // rather than quietly overriding the flag: the caller asked for a page
-            // nobody would ever see, and that is worth knowing.
-            if (lifecycle === 'terminal' && input['noInbox'] === true) {
-                throw new InputError({
-                    error: 'invalid_page_delivery',
-                    message: 'a terminal node cannot send a page --no-inbox',
-                    field: 'inbox',
-                    next: 'Drop --no-inbox. This node finishes, and nobody reads a finished node\'s transcript, so a page kept out of the inbox reaches no one.',
-                });
+                // Static extraction is an evaluation. Derive and validate delivery from this
+                // exact manifest so authored code runs once and cannot change between passes.
+                const productKinds = pageProductKinds();
+                const prepared = submitAuthoredPage(() => preparePage({ sourceFile, source, productKinds }));
+                const responseBearing = prepared.manifest.slots.some(isResponseBearingSlot);
+                const delivery = deliveryFrom(input, responseBearing, lifecycle);
+                prepared.manifest = submitAuthoredPage(() => validateAuthoredPageManifest({ ...prepared.manifest, delivery }, productKinds));
+                if (!delivery.reply) {
+                    const pageId = `page-${randomBytes(4).toString('hex')}`;
+                    const { dir } = publishPage(ticketDir(pageId), prepared);
+                    // A page with no reply route carries no response-bearing components, so what the
+                    // follow-up must get right is where the person will meet it and how it
+                    // settles: an inline page is already in this conversation, and its
+                    // inbox entry is a notice that clears itself the moment the page has
+                    // actually been seen — an agent that points the person at their inbox
+                    // for a page on their screen sends them to an empty list.
+                    const followUp = delivery.placement === 'inline' && delivery.inbox
+                        ? 'Shown in this conversation and queued in the user\'s inbox.'
+                        : delivery.placement === 'inline'
+                            ? 'Shown in this conversation as passive page content with no inbox entry.'
+                            : delivery.inbox
+                                ? 'Queued in the inbox; it opens in the panel and waits until dismissed.'
+                                : 'Published as passive page content with no inbox or response lifecycle.';
+                    return { page_id: pageId, dir, ...delivery, follow_up: followUp };
+                }
+                const originNodeId = askingNode();
+                const bridgeNodeId = (await cliClient().createHumanBridge({ kind: 'human', parent: originNodeId, cwd: process.cwd(), name: 'human-page' })).node_id;
+                const idir = ticketDir(bridgeNodeId);
+                bindTicketReplyRoute(idir, bridgeNodeId);
+                const { dir } = publishPage(idir, prepared);
+                if (originNodeId !== null && originNodeId !== '')
+                    markStopSignal(originNodeId, 'requestedHumanReply');
+                return { page_id: bridgeNodeId, dir, ...delivery, follow_up: queuedFollowUp() };
             }
-            // Static extraction is an evaluation. Derive and validate delivery from this
-            // exact manifest so authored code runs once and cannot change between passes.
-            const productKinds = pageProductKinds();
-            const prepared = submitAuthoredPage(() => preparePage({ sourceFile, source, productKinds }));
-            const responseBearing = prepared.manifest.slots.some(isResponseBearingSlot);
-            const delivery = deliveryFrom(input, responseBearing, lifecycle);
-            prepared.manifest = submitAuthoredPage(() => validateAuthoredPageManifest({ ...prepared.manifest, delivery }, productKinds));
-            if (!delivery.reply) {
-                const pageId = `page-${randomBytes(4).toString('hex')}`;
-                const { dir } = publishPage(ticketDir(pageId), prepared);
-                // A page with no reply route carries no response-bearing components, so what the
-                // follow-up must get right is where the person will meet it and how it
-                // settles: an inline page is already in this conversation, and its
-                // inbox entry is a notice that clears itself the moment the page has
-                // actually been seen — an agent that points the person at their inbox
-                // for a page on their screen sends them to an empty list.
-                const followUp = delivery.placement === 'inline' && delivery.inbox
-                    ? 'Shown in this conversation and queued in the user\'s inbox. The inbox entry clears itself the user has seen the page — someone viewing this conversation acknowledges it on sight, so do not send them to their inbox for it. They already know this, do not inform them.'
-                    : delivery.placement === 'inline'
-                        ? 'Shown in this conversation as passive page content with no inbox entry.'
-                        : delivery.inbox
-                            ? 'Queued in the inbox; it opens in the panel and waits until dismissed.'
-                            : 'Published as passive page content with no inbox or response lifecycle.';
-                return { page_id: pageId, dir, ...delivery, follow_up: followUp };
+            finally {
+                if (tempDir !== undefined)
+                    rmSync(tempDir, { recursive: true, force: true });
             }
-            const originNodeId = askingNode();
-            const bridgeNodeId = (await cliClient().createHumanBridge({ kind: 'human', parent: originNodeId, cwd: process.cwd(), name: 'human-page' })).node_id;
-            const idir = ticketDir(bridgeNodeId);
-            bindTicketReplyRoute(idir, bridgeNodeId);
-            const { dir } = publishPage(idir, prepared);
-            if (originNodeId !== null && originNodeId !== '')
-                markStopSignal(originNodeId, 'requestedHumanReply');
-            return { page_id: bridgeNodeId, dir, ...delivery, follow_up: queuedFollowUp() };
-        }
-        finally {
-            if (tempDir !== undefined)
-                rmSync(tempDir, { recursive: true, force: true });
-        }
-    },
-});
+        },
+    });
+}
 // ---------------------------------------------------------------------------
 // show (no job, non-blocking passthrough) — passive live document display, NOT
 // a ticket surface. `display()` puts a file live in a watch pane and never