@north-light/crouter 0.3.221 → 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/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/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/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],
 });

package/dist/commands/sys/doctor.js

@@ -15,10 +15,12 @@ import { detectPackageManager } from './setup-core.js';
 import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
 import { discoverHookRegistry } from '../../core/command-hooks/discovery.js';
 import { resolveBinContributions } from '../../core/runtime/bin-contributions.js';
+import { inspectHumanActions } from '../../core/human-actions.js';
 import { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
 import { listAllPlugins } from '../../core/resolver.js';
 import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
 import { processGeneration, processLocatedGeneration, runtimeManifest, selectedGeneration } from './shared.js';
+import { CONFIG_FILE } from '../../types.js';
 function pass(scope, name, message) {
     return { scope, name, status: 'pass', message };
 }
@@ -198,6 +200,55 @@ function runBinContributionChecks(scopes) {
     }
     return results;
 }
+/** Validate every scope-configured completion action without executing it. */
+function runHumanActionChecks(scopes) {
+    const inScope = new Set(scopes);
+    const userConfig = join(scopeRoot('user'), CONFIG_FILE);
+    const results = [];
+    const winningOrigins = new Map();
+    for (const action of inspectHumanActions(process.cwd())) {
+        if ('kind' in action) {
+            if (action.kind === 'unknown_action')
+                continue;
+            const scope = action.configOrigin === userConfig ? 'user' : 'project';
+            const block = action.block === true;
+            const winningOrigin = block ? undefined : winningOrigins.get(action.name);
+            if (!block && winningOrigin === undefined)
+                winningOrigins.set(action.name, action.configOrigin);
+            if (!inScope.has(scope))
+                continue;
+            const checkName = block ? `humanActions:block@${action.configOrigin}` : `humanActions:${action.name}@${action.configOrigin}`;
+            const remediation = {
+                kind: 'human_action',
+                description: block
+                    ? `Fix or remove the \`humanActions\` block in ${action.configOrigin}. Actions run argv directly without a shell.`
+                    : `Fix or remove the \`humanActions.${action.name}\` declaration in ${action.configOrigin}. Actions run argv directly without a shell.`,
+            };
+            if (winningOrigin !== undefined) {
+                results.push({
+                    scope,
+                    name: checkName,
+                    status: 'pass',
+                    message: `warning: shadowed by ${winningOrigin}; ${action.configOrigin}: ${action.reason}`,
+                    remediation,
+                });
+            }
+            else {
+                results.push(failCheck(scope, checkName, `${action.configOrigin}: ${action.reason}`, remediation));
+            }
+            continue;
+        }
+        const scope = action.configOrigin === userConfig ? 'user' : 'project';
+        const winningOrigin = winningOrigins.get(action.name);
+        if (winningOrigin === undefined)
+            winningOrigins.set(action.name, action.configOrigin);
+        if (!inScope.has(scope))
+            continue;
+        const shadowedPrefix = winningOrigin === undefined ? '' : `shadowed by ${winningOrigin}; `;
+        results.push(pass(scope, `humanActions:${action.name}@${action.configOrigin}`, `${shadowedPrefix}${action.configOrigin} → ${action.argv[0]} (cwd ${action.cwd})`));
+    }
+    return results;
+}
 /** Check each enabled plugin's advisory PATH requirements against the exact
  *  broker environment a node launched from this cwd/profile receives. */
 function runRequiresChecks(scopes) {
@@ -506,12 +557,12 @@ export const sysDoctorLeaf = defineLeaf({
             { kind: 'flag', name: 'remote', type: 'bool', required: false, constraint: 'Check git remotes with ls-remote (slow — makes network calls).' },
         ],
         output: [
-            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/collision problems and carry disable/update/remove/show remediation; healthy hooks list effective target, phase, and op. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
+            { name: 'checks', type: 'object[]', required: true, constraint: 'Each: {scope, name, status, message, fixed?, remediation?}. status: pass | fail. scope may be user | project | canvas. bin:<name> checks report bare-binary contributions (a `bin` block in a plugin manifest or a scope config.json): a pass names the contributor and the resolved target, a fail names an unsafe/reserved command name, malformed target declaration, missing/non-executable/escaping target, or same-precedence name collision that installed nothing; their remediation is always a human_action. humanActions:<name>@<config-origin> checks validate each user/project scope completion-action declaration: action-name and argv shape, cwd directory, argv[0] regular-file existence, and execute permission; they never execute an action. A malformed effective declaration fails; a malformed shadowed declaration is a pass-level warning that names the winning and shadowed origins. requires:<name> checks report each enabled plugin manifest PATH requirement: a pass names the plugin and resolved executable path; a fail names the plugin and carries its declared install hint as remediation. Runtime checks validate selected and process generation manifests, sealing/containment, and full SHA-256 inventories. terminal:nerd-font (user scope) reports whether a Nerd Font is installed for the viewer\'s icon glyphs; its remediation is always a human_action carrying the platform install command, never auto-fixed. Plugin checks appear as plugin:<name>:commands and plugin:<name>:hooks; both are validated statically and never execute plugin code. Hook failures identify manifest/path/target/collision problems and carry disable/update/remove/show remediation; healthy hooks list effective target, phase, and op. remediation (when present) is {kind, description, ...payload} where kind is remove_config_key | rm_path | human_action; fault human_action remediations include the canonical logs command. Sorted by scope then name.' },
             { name: 'ok', type: 'boolean', required: true, constraint: 'True when no unresolved fail checks remain.' },
         ],
         outputKind: 'object',
         effects: [
-            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command and hook manifests, bare-binary (`bin`) declarations, and advisory `requires` PATH checks never execute plugin or contributed binaries.',
+            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command and hook manifests, bare-binary (`bin`) declarations, humanActions declarations, and advisory `requires` PATH checks never execute plugin or contributed binaries.',
             'With --fix: applies each non-pass check\'s `remediation` — removes stale config entries and deletes dangling plugin/marketplace directories; canvas fault findings and plugin command/hook findings stay read-only (--fix never chmods or rewrites third-party plugin content).',
             'Each non-pass result carries a structured `remediation` describing the fix action (absolute paths, exact config keys, or a human_action with its command) so callers can apply it directly without --fix.',
         ],
@@ -531,6 +582,7 @@ export const sysDoctorLeaf = defineLeaf({
         allResults.push(...await runCommandPluginChecks(scopes));
         allResults.push(...await runHookPluginChecks(scopes));
         allResults.push(...runBinContributionChecks(scopes));
+        allResults.push(...runHumanActionChecks(scopes));
         allResults.push(...runRequiresChecks(scopes));
         allResults.push(...await runFaultChecks());
         const processLocation = processGeneration();

package/dist/core/__tests__/broker-extension-canvas-db-boundary.test.js

@@ -41,10 +41,13 @@ function dbReach(root) {
     }
     return null;
 }
-test('every shipped broker extension is transitively canvas.db-free', () => {
-    for (const name of CANVAS_EXTENSION_NAMES) {
-        const root = join(SOURCE_ROOT, 'pi-extensions', `${name}.ts`);
+test('every shipped broker extension and the prospective preflight are transitively canvas.db-free', () => {
+    const roots = [
+        ...CANVAS_EXTENSION_NAMES.map((name) => join(SOURCE_ROOT, 'pi-extensions', `${name}.ts`)),
+        join(SOURCE_ROOT, 'core/runtime/prospective-inventory-cli.ts'),
+    ];
+    for (const root of roots) {
         const reach = dbReach(root);
-        assert.equal(reach, null, `${name} reaches canvas.db through:\n${reach?.join('\n')}`);
+        assert.equal(reach, null, `${root} reaches canvas.db through:\n${reach?.join('\n')}`);
     }
 });

package/dist/core/__tests__/fixtures/memory-slash-live-probe.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/fixtures/memory-slash-live-probe.js

@@ -0,0 +1,71 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DefaultResourceLoader, ExtensionRunner, } from '@earendil-works/pi-coding-agent';
+import { buildRefInventory } from '../../memory/inline-ref-inventory.js';
+import { gatewayCommandRows, gatewayMemoryRows } from '../../runtime/chat-inventory-rows.js';
+import { captureChatCapabilities, registrationChatSurface } from '../../runtime/command-surface.js';
+import { runProspectiveInventory } from '../../runtime/prospective-inventory.js';
+async function main() {
+    const extensionPath = process.argv[2];
+    const invocations = JSON.parse(process.argv[3] ?? '[]');
+    if (extensionPath === undefined)
+        throw new Error('extension path is required');
+    const cwd = process.cwd();
+    const home = process.env['CRTR_HOME'];
+    if (home === undefined || home === '')
+        throw new Error('CRTR_HOME is required');
+    const stateBeforeProspective = existsSync(home);
+    const prospective = await runProspectiveInventory({ cwd, profileId: null, extensions: [extensionPath] });
+    const stateAfterProspective = existsSync(home);
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir: join(cwd, '.pi'),
+        additionalExtensionPaths: [extensionPath],
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const loaded = loader.getExtensions();
+    if (loaded.errors.length > 0)
+        throw new Error(JSON.stringify(loaded.errors));
+    const sent = [];
+    let activeName = '';
+    loaded.runtime.sendMessage = (message, options) => sent.push({ name: activeName, message, options });
+    const runner = new ExtensionRunner(loaded.extensions, loaded.runtime, cwd, undefined, undefined);
+    const registered = runner.getRegisteredCommands();
+    captureChatCapabilities({ commands: registered, templates: [] });
+    const commands = gatewayCommandRows(registered.map((command) => {
+        const expansion = command.expansion;
+        return {
+            name: command.invocationName,
+            description: command.description ?? '',
+            source: 'command',
+            ...(expansion === undefined ? {} : { expansion }),
+            ...registrationChatSurface(command),
+        };
+    }));
+    const memoryRefs = gatewayMemoryRows(buildRefInventory().refs);
+    const notifications = [];
+    for (const invocation of invocations) {
+        const command = runner.getCommand(invocation.name);
+        if (command === undefined)
+            throw new Error(`command not registered: ${invocation.name}`);
+        activeName = invocation.name;
+        await command.handler(invocation.args, {
+            cwd,
+            ui: { notify: (...args) => notifications.push(args) },
+        });
+    }
+    writeFileSync(3, JSON.stringify({
+        prospective,
+        stateBeforeProspective,
+        stateAfterProspective,
+        commands,
+        memoryRefs,
+        sent,
+        notifications,
+    }));
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/core/__tests__/human-action-delivery.test.d.ts

@@ -0,0 +1 @@
+export {};