@north-light/crouter 0.3.221 → 0.3.223

package/dist/core/__tests__/prospective-inventory-capability-parity.test.js

@@ -0,0 +1,91 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DefaultResourceLoader, ExtensionRunner, } from '@earendil-works/pi-coding-agent';
+import { captureChatCapabilities, registrationChatSurface } from '../runtime/command-surface.js';
+test('startup capability capture preserves same-name lifecycle replacements and excludes new lifecycle registrations', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'crtr-prospective-capability-'));
+    const agentDir = join(root, '.pi');
+    const invoked = join(root, 'late-invoked');
+    mkdirSync(agentDir);
+    const first = join(root, 'first.js');
+    const second = join(root, 'second.js');
+    writeFileSync(first, `
+import { writeFileSync } from 'node:fs';
+export default function (pi) {
+  pi.registerCommand('collision', {
+    description: 'first factory command',
+    gateway: true,
+    argumentHint: '<first>',
+    handler: async () => {},
+  });
+  pi.on('session_start', () => {
+    pi.registerCommand('collision', {
+      description: 'lifecycle replacement',
+      argumentHint: '<replacement>',
+      handler: async () => {},
+    });
+    pi.registerCommand('late', {
+      description: 'lifecycle command',
+      gateway: true,
+      handler: async () => writeFileSync(${JSON.stringify(invoked)}, 'yes'),
+    });
+  });
+}
+`);
+    writeFileSync(second, `
+export default function (pi) {
+  pi.registerCommand('collision', {
+    description: 'second factory command',
+    gateway: true,
+    argumentHint: '<second>',
+    handler: async () => {},
+  });
+}
+`);
+    try {
+        const loader = new DefaultResourceLoader({
+            cwd: root,
+            agentDir,
+            additionalExtensionPaths: [first, second],
+            noContextFiles: true,
+        });
+        await loader.reload();
+        const loaded = loader.getExtensions();
+        assert.deepEqual(loaded.errors, []);
+        const runner = new ExtensionRunner(loaded.extensions, loaded.runtime, root, undefined, undefined);
+        const startupCommands = runner.getRegisteredCommands();
+        captureChatCapabilities({ commands: startupCommands, templates: [] });
+        const startupRows = startupCommands.map((command) => ({
+            name: command.invocationName,
+            ...registrationChatSurface(command),
+        }));
+        assert.deepEqual(startupRows, [
+            { name: 'collision:1', gatewayCapable: true, argumentHint: '<first>' },
+            { name: 'collision:2', gatewayCapable: true, argumentHint: '<second>' },
+        ]);
+        for (const extension of loaded.extensions) {
+            for (const handler of extension.handlers.get('session_start') ?? []) {
+                await handler({ type: 'session_start' }, {});
+            }
+        }
+        const reloadedRows = runner.getRegisteredCommands().map((command) => ({
+            name: command.invocationName,
+            ...registrationChatSurface(command),
+        }));
+        assert.deepEqual(reloadedRows, [
+            { name: 'collision:1', gatewayCapable: true, argumentHint: '<replacement>' },
+            { name: 'late', gatewayCapable: false },
+            { name: 'collision:2', gatewayCapable: true, argumentHint: '<second>' },
+        ]);
+        const late = runner.getCommand('late');
+        assert.ok(late, 'the lifecycle command remains registered and addressable');
+        await late.handler('', {});
+        assert.equal(existsSync(invoked), true, 'the lifecycle command remains invokable');
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});

package/dist/core/__tests__/seam/memory-slash-node-relative-inventory.test.d.ts

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

package/dist/core/__tests__/seam/memory-slash-node-relative-inventory.test.js

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { test } from 'node:test';
+import { loadedCommandPreview } from '../../../clients/attach/slash/prompt-preview.js';
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const EXTENSION = join(ROOT, 'dist/builtin-pi-packages/pi-crtr-extensions/extensions/memory-slash-commands.ts');
+const LIVE_PROBE = join(ROOT, 'dist/core/__tests__/fixtures/memory-slash-live-probe.js');
+const COMMAND_NAMES = ['acceptance-context-token', 'acceptance-node-token', 'acceptance-independent'];
+function writeSlashDoc(memoryDir, name, description, body) {
+    writeFileSync(join(memoryDir, `${name}.md`), `---\nkind: knowledge\nwhen-and-why-to-read: Acceptance fixture.\nshort-form: ${description}\nslash: true\n---\n${body}`);
+}
+function liveProbe(input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [LIVE_PROBE, EXTENSION, JSON.stringify(input.invocations)], {
+            cwd: input.cwd,
+            env: {
+                ...process.env,
+                CRTR_HOME: input.home,
+                CRTR_NODE_ID: input.nodeId,
+                CRTR_PROFILE_ID: '',
+                PI_CODING_AGENT_DIR: join(input.cwd, '.pi'),
+            },
+            stdio: ['ignore', 'pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let response = '';
+        const stdoutStream = child.stdout;
+        const stderrStream = child.stderr;
+        const responseStream = child.stdio[3];
+        if (stdoutStream === null || stderrStream === null || responseStream === null) {
+            child.kill('SIGKILL');
+            reject(new Error('live probe response channel unavailable'));
+            return;
+        }
+        stdoutStream.setEncoding('utf8');
+        stderrStream.setEncoding('utf8');
+        responseStream.setEncoding('utf8');
+        stdoutStream.on('data', (chunk) => { stdout += chunk; });
+        stderrStream.on('data', (chunk) => { stderr += chunk; });
+        responseStream.on('data', (chunk) => { response += chunk; });
+        child.on('error', reject);
+        child.on('close', (code, signal) => {
+            if (code !== 0) {
+                reject(new Error(`live probe exited ${code ?? signal ?? 'unknown'}: ${stderr}${stdout}`));
+                return;
+            }
+            resolve(JSON.parse(response));
+        });
+    });
+}
+function fixtureRows(rows) {
+    return COMMAND_NAMES.map((name) => {
+        const row = rows.find((candidate) => candidate.name === name);
+        assert.ok(row, `Gateway advertises /${name}`);
+        return row;
+    });
+}
+test('node-relative memory slash commands omit preview metadata without changing live sends', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-memory-slash-inventory-'));
+    const home = join(cwd, 'canvas');
+    const memoryDir = join(cwd, '.crouter', 'memory');
+    const nodeId = 'acceptance-live-node';
+    mkdirSync(memoryDir, { recursive: true });
+    writeSlashDoc(memoryDir, COMMAND_NAMES[0], 'Context-relative fixture.', 'Store $ARGUMENTS in $CRTR_CONTEXT_DIR/result.md.\n');
+    writeSlashDoc(memoryDir, COMMAND_NAMES[1], 'Node-relative fixture.', 'Node $CRTR_NODE_ID received $ARGUMENTS.\n');
+    writeSlashDoc(memoryDir, COMMAND_NAMES[2], 'Node-independent fixture.', 'Independent payload: $ARGUMENTS.\n');
+    try {
+        const live = await liveProbe({
+            cwd,
+            home,
+            nodeId,
+            invocations: COMMAND_NAMES.map((name) => ({ name, args: 'evidence' })),
+        });
+        assert.equal(live.stateBeforeProspective, false);
+        assert.equal(live.stateAfterProspective, false);
+        assert.deepEqual(live.commands, live.prospective.commands);
+        assert.deepEqual(live.memoryRefs, live.prospective.memory_refs);
+        const prospectiveRows = fixtureRows(live.prospective.commands);
+        const liveRows = fixtureRows(live.commands);
+        assert.deepEqual(liveRows, prospectiveRows);
+        assert.deepEqual(prospectiveRows, [
+            { name: COMMAND_NAMES[0], description: 'Context-relative fixture.', source: 'command' },
+            { name: COMMAND_NAMES[1], description: 'Node-relative fixture.', source: 'command' },
+            {
+                name: COMMAND_NAMES[2],
+                description: 'Node-independent fixture.',
+                source: 'command',
+                expansion: {
+                    kind: 'memory-slash',
+                    commandName: COMMAND_NAMES[2],
+                    body: 'Independent payload: $ARGUMENTS.\n',
+                },
+            },
+        ]);
+        const insightsInit = live.commands.find((row) => row.name === 'insights:init');
+        assert.ok(insightsInit, 'Gateway completion includes /insights:init');
+        assert.equal(insightsInit.expansion, undefined);
+        assert.equal(loadedCommandPreview('/insights:init agent-facing CLI', live.commands), undefined);
+        assert.equal(loadedCommandPreview('/acceptance-independent first evidence', live.commands)?.content, 'Independent payload: first evidence.\n');
+        assert.equal(loadedCommandPreview('/acceptance-independent changed evidence', live.commands)?.content, 'Independent payload: changed evidence.\n');
+        assert.deepEqual(live.notifications, []);
+        const sentContent = Object.fromEntries(live.sent.map((send) => [send.name, send.message.content]));
+        assert.deepEqual(sentContent, {
+            [COMMAND_NAMES[0]]: `Store evidence in ${join(home, 'nodes', nodeId, 'context', 'result.md')}.\n`,
+            [COMMAND_NAMES[1]]: `Node ${nodeId} received evidence.\n`,
+            [COMMAND_NAMES[2]]: 'Independent payload: evidence.\n',
+        });
+        for (const send of live.sent) {
+            assert.deepEqual(send.message, {
+                customType: 'memory-slash-command',
+                content: sentContent[send.name],
+                display: true,
+            });
+            assert.deepEqual(send.options, { triggerTurn: true });
+        }
+        assert.doesNotMatch(sentContent[COMMAND_NAMES[0]], /\$CRTR_CONTEXT_DIR|\$CRTR_NODE_ID/);
+        assert.doesNotMatch(sentContent[COMMAND_NAMES[1]], /\$CRTR_CONTEXT_DIR|\$CRTR_NODE_ID/);
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});

package/dist/core/__tests__/seam/prospective-inventory-stdout.test.d.ts

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

package/dist/core/__tests__/seam/prospective-inventory-stdout.test.js

@@ -0,0 +1,31 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { runProspectiveInventory } from '../../runtime/prospective-inventory.js';
+test('prospective preflight keeps package stdout out of its response channel', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-prospective-stdout-'));
+    const extension = join(cwd, 'loud-extension.mjs');
+    writeFileSync(extension, `
+export default function (pi) {
+  console.log('harmless package diagnostic');
+  pi.registerCommand('stdout-probe', {
+    description: 'survives package stdout',
+    gateway: true,
+    handler: async () => {},
+  });
+}
+`);
+    try {
+        const rows = await runProspectiveInventory({ cwd, profileId: null, extensions: [extension] });
+        assert.deepEqual(rows.commands.find((row) => row.name === 'stdout-probe'), {
+            name: 'stdout-probe',
+            description: 'survives package stdout',
+            source: 'command',
+        });
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});

package/dist/core/canvas/db.js

@@ -1153,6 +1153,28 @@ ALTER TABLE crons ADD COLUMN held INTEGER NOT NULL DEFAULT 0;
 ALTER TABLE crons ADD COLUMN last_poke_at TEXT;
 `);
 }
+/** v33 — durable, daemon-owned attempts to deliver settled human completions. */
+function addHumanActionDeliveries(db) {
+    db.exec(`
+CREATE TABLE human_action_deliveries (
+  request_id           TEXT PRIMARY KEY,
+  state                TEXT NOT NULL,
+  attempt              INTEGER NOT NULL DEFAULT 0,
+  argv_json            TEXT NOT NULL,
+  cwd                  TEXT NOT NULL,
+  completion_json      TEXT NOT NULL,
+  next_attempt_at      INTEGER NOT NULL,
+  claimed_at           INTEGER,
+  claim_owner          TEXT,
+  accepted_at          INTEGER,
+  permanent_failed_at  INTEGER,
+  last_failure_json    TEXT,
+  created_at           INTEGER NOT NULL,
+  updated_at           INTEGER NOT NULL
+);
+CREATE INDEX idx_human_action_deliveries_due ON human_action_deliveries(state, next_attempt_at);
+`);
+}
 /** The journaled lane of the state-migration registry, adapted to this chain's
  *  step shape. Registry order is preserved, so these versions stay stable as
  *  long as the registry is append-only (same contract as the local list). */
@@ -1198,6 +1220,7 @@ export const MIGRATIONS = [
     /* v30 */ dropConsultOutbox,
     /* v31 */ addReviewSubmitRequested,
     /* v32 */ addCronHeldColumns,
+    /* v33 */ addHumanActionDeliveries,
     ...JOURNALED_STATE_MIGRATIONS,
 ];
 /** Migration indexes that manage their OWN transaction and therefore must not

package/dist/core/canvas/human-deliveries.d.ts

@@ -0,0 +1,53 @@
+export type ActionDeliveryState = 'pending' | 'running' | 'accepted' | 'permanent_failed';
+export interface ActionDeliveryFailure {
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    exitCode?: number;
+    signal?: string;
+    message?: string;
+    stderr?: string;
+}
+export interface ActionDeliveryRecord {
+    requestId: string;
+    state: ActionDeliveryState;
+    attempt: number;
+    argv: string[];
+    cwd: string;
+    completion: unknown;
+    nextAttemptAt: number;
+    claimedAt: number | null;
+    claimOwner: string | null;
+    acceptedAt: number | null;
+    permanentFailedAt: number | null;
+    lastFailure: ActionDeliveryFailure | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Insert the one delivery row for a settled action-bound request. Idempotent
+ *  on requestId: a replayed settlement must not create a second row. */
+export declare function enqueueActionDelivery(row: {
+    requestId: string;
+    argv: string[];
+    cwd: string;
+    /** Complete HumanCompletionV1 with delivery.attempt set to 0. */
+    completion: unknown;
+}): void;
+/** Delivery state for `GET /v1/human/requests/:id`; null when no row exists. */
+export declare function readActionDelivery(requestId: string): ActionDeliveryRecord | null;
+/** Due pending records in deterministic order for the daemon's serial tick. */
+export declare function dueActionDeliveries(now: number): ActionDeliveryRecord[];
+/** Atomically start one due delivery attempt. A null result lost the claim. */
+export declare function claimActionDelivery(requestId: string, now: number, claimOwner: string): ActionDeliveryRecord | null;
+export type ActionDeliverySettlement = {
+    state: 'accepted';
+} | {
+    state: 'permanent_failed';
+    failure: ActionDeliveryFailure;
+} | {
+    state: 'pending';
+    nextAttemptAt: number;
+    failure: ActionDeliveryFailure;
+};
+/** Settle only the still-owned running attempt, so a stale process cannot overwrite a newer claim. */
+export declare function settleActionDelivery(requestId: string, attempt: number, claimOwner: string, settlement: ActionDeliverySettlement, now: number): boolean;
+/** A new daemon deliberately redelivers interrupted completions at least once. */
+export declare function recoverRunningActionDeliveries(now: number): number;

package/dist/core/canvas/human-deliveries.js

@@ -0,0 +1,75 @@
+// Durable action-completion delivery state. The terminal ticket is composed
+// before this row exists; this module schedules its already-complete document.
+import { openDb, withCanvasWrite } from './db.js';
+function actionDeliveryFrom(row) {
+    return {
+        requestId: row.request_id,
+        state: row.state,
+        attempt: row.attempt,
+        argv: JSON.parse(row.argv_json),
+        cwd: row.cwd,
+        completion: JSON.parse(row.completion_json),
+        nextAttemptAt: row.next_attempt_at,
+        claimedAt: row.claimed_at,
+        claimOwner: row.claim_owner,
+        acceptedAt: row.accepted_at,
+        permanentFailedAt: row.permanent_failed_at,
+        lastFailure: row.last_failure_json === null ? null : JSON.parse(row.last_failure_json),
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/** Insert the one delivery row for a settled action-bound request. Idempotent
+ *  on requestId: a replayed settlement must not create a second row. */
+export function enqueueActionDelivery(row) {
+    const now = Date.now();
+    withCanvasWrite((db) => {
+        db.prepare(`INSERT INTO human_action_deliveries
+        (request_id, state, attempt, argv_json, cwd, completion_json, next_attempt_at, created_at, updated_at)
+       VALUES (?, 'pending', 0, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(request_id) DO NOTHING`).run(row.requestId, JSON.stringify(row.argv), row.cwd, JSON.stringify(row.completion), now, now, now);
+    });
+}
+/** Delivery state for `GET /v1/human/requests/:id`; null when no row exists. */
+export function readActionDelivery(requestId) {
+    const row = openDb()
+        .prepare('SELECT * FROM human_action_deliveries WHERE request_id = ?')
+        .get(requestId);
+    return row === undefined ? null : actionDeliveryFrom(row);
+}
+/** Due pending records in deterministic order for the daemon's serial tick. */
+export function dueActionDeliveries(now) {
+    return openDb()
+        .prepare(`SELECT * FROM human_action_deliveries
+         WHERE state = 'pending' AND next_attempt_at <= ?
+         ORDER BY next_attempt_at, created_at, request_id`)
+        .all(now).map(actionDeliveryFrom);
+}
+/** Atomically start one due delivery attempt. A null result lost the claim. */
+export function claimActionDelivery(requestId, now, claimOwner) {
+    return withCanvasWrite((db) => {
+        const claimed = db.prepare(`UPDATE human_action_deliveries
+       SET state = 'running', attempt = attempt + 1, claimed_at = ?, claim_owner = ?, updated_at = ?
+       WHERE request_id = ? AND state = 'pending' AND next_attempt_at <= ?`).run(now, claimOwner, now, requestId, now);
+        if (Number(claimed.changes) === 0)
+            return null;
+        const row = db.prepare('SELECT * FROM human_action_deliveries WHERE request_id = ?').get(requestId);
+        return actionDeliveryFrom(row);
+    });
+}
+/** Settle only the still-owned running attempt, so a stale process cannot overwrite a newer claim. */
+export function settleActionDelivery(requestId, attempt, claimOwner, settlement, now) {
+    const failure = settlement.state === 'accepted' ? null : JSON.stringify(settlement.failure);
+    const result = withCanvasWrite((db) => db.prepare(`UPDATE human_action_deliveries
+     SET state = ?, next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL,
+         accepted_at = ?, permanent_failed_at = ?, last_failure_json = ?, updated_at = ?
+     WHERE request_id = ? AND state = 'running' AND attempt = ? AND claim_owner = ?`).run(settlement.state, settlement.state === 'pending' ? settlement.nextAttemptAt : now, settlement.state === 'accepted' ? now : null, settlement.state === 'permanent_failed' ? now : null, failure, now, requestId, attempt, claimOwner));
+    return Number(result.changes) === 1;
+}
+/** A new daemon deliberately redelivers interrupted completions at least once. */
+export function recoverRunningActionDeliveries(now) {
+    const result = withCanvasWrite((db) => db.prepare(`UPDATE human_action_deliveries
+     SET state = 'pending', next_attempt_at = ?, claimed_at = NULL, claim_owner = NULL, updated_at = ?
+     WHERE state = 'running'`).run(now, now));
+    return Number(result.changes);
+}

package/dist/core/config.d.ts

@@ -1,4 +1,4 @@
-import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
+import type { PageComponentRegistration, Scope, ScopeConfig, ScopeState, HumanActionConfig, KindConfig, ModelLaddersConfig, ModelProvider, ModelStrength, ModelRouteConfig, ModelRoutingConfig } from '../types.js';
 import { type BindingId } from './keybindings/catalog.js';
 export declare function configPath(scope: Scope): string | null;
 export declare function statePath(scope: Scope): string | null;
@@ -40,6 +40,18 @@ export declare function binDeclarationIssues(raw: unknown): BinDeclarationIssue[
  *  manifest's) to name → root-relative path. Invalid entries never become
  *  commands; `binDeclarationIssues` keeps them visible to Doctor. */
 export declare function normalizeBin(raw: unknown): Record<string, string>;
+export interface HumanActionDeclarationIssue {
+    name: string;
+    reason: string;
+    block?: true;
+}
+/** Validate `humanActions` declaration shape without touching the filesystem.
+ * Filesystem checks happen only when resolving an action or running Doctor. */
+export declare function humanActionDeclarationIssues(raw: unknown): HumanActionDeclarationIssue[];
+/** Normalize valid action declarations for scope-local config inspection.
+ * Invalid entries remain available through raw reads so resolution and Doctor
+ * can report them rather than silently treating them as absent. */
+export declare function normalizeHumanActions(raw: unknown): Record<string, HumanActionConfig>;
 /** STRICT install-time validation for a plugin-declared `bin` block. Target
  *  filesystem state is checked later by Doctor because it can change after
  *  install. */

package/dist/core/config.js

@@ -320,6 +320,55 @@ export function normalizeBin(raw) {
     }
     return out;
 }
+const HUMAN_ACTION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/** Validate `humanActions` declaration shape without touching the filesystem.
+ * Filesystem checks happen only when resolving an action or running Doctor. */
+export function humanActionDeclarationIssues(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return [{ name: 'humanActions', reason: 'humanActions must be a JSON object mapping action names to {argv, cwd}', block: true }];
+    }
+    const issues = [];
+    for (const [name, value] of Object.entries(raw)) {
+        const reasons = [];
+        if (!HUMAN_ACTION_NAME_PATTERN.test(name)) {
+            reasons.push(`action name must match ${HUMAN_ACTION_NAME_PATTERN.source}`);
+        }
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            reasons.push('action must be an object with argv and cwd');
+        }
+        else {
+            const action = value;
+            const extras = Object.keys(action).filter((key) => key !== 'argv' && key !== 'cwd');
+            if (extras.length > 0)
+                reasons.push(`action has unsupported field${extras.length === 1 ? '' : 's'}: ${extras.join(', ')}`);
+            if (!Array.isArray(action.argv) || action.argv.length === 0 || !action.argv.every((arg) => typeof arg === 'string' && arg.length > 0)) {
+                reasons.push('argv must be a non-empty array of non-empty strings');
+            }
+            if (typeof action.cwd !== 'string' || action.cwd.length === 0) {
+                reasons.push('cwd is required and must be a non-empty string');
+            }
+        }
+        if (reasons.length > 0)
+            issues.push({ name, reason: reasons.join('; ') });
+    }
+    return issues;
+}
+/** Normalize valid action declarations for scope-local config inspection.
+ * Invalid entries remain available through raw reads so resolution and Doctor
+ * can report them rather than silently treating them as absent. */
+export function normalizeHumanActions(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const invalid = new Set(humanActionDeclarationIssues(raw).map((issue) => issue.name));
+    const out = {};
+    for (const [name, value] of Object.entries(raw)) {
+        if (invalid.has(name))
+            continue;
+        const action = value;
+        out[name] = { argv: [...action.argv], cwd: action.cwd };
+    }
+    return out;
+}
 /** STRICT install-time validation for a plugin-declared `bin` block. Target
  *  filesystem state is checked later by Doctor because it can change after
  *  install. */
@@ -635,7 +684,8 @@ function mergeConfig(partial) {
     const remoteCanvas = mergeRemoteCanvas(partial.remoteCanvas);
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
     const bin = normalizeBin(partial.bin);
-    return { bin, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
+    const humanActions = normalizeHumanActions(partial.humanActions);
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, keybindings, tmux_passthrough, modelLadders, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer

package/dist/core/feed/inbox.d.ts

@@ -66,6 +66,12 @@ export declare function readCanceledEntryIds(nodeId: string): Set<InboxEntryId>;
  *  the interrupt's abort lands right behind, and covered handoffs are never
  *  re-delivered anyway. Returns the newly canceled entry ids. */
 export declare function cancelPendingHumanMessages(nodeId: string): InboxEntryId[];
+/** Cancel every not-yet-settled entry the predicate selects. Retraction, not
+ *  deletion: the append-only inbox is untouched and the sidecar grows. Safe to
+ *  call late — an entry already past the cursor is not pending, and the watcher
+ *  re-reads the set at plan time so a cancel racing a buffered entry still
+ *  lands. */
+export declare function cancelPendingEntries(nodeId: string, select: (entry: InboxEntry) => boolean): InboxEntryId[];
 /** Read and validate the persisted exact cursor identity. */
 export declare function readCursor(nodeId: string): InboxEntryId | undefined;
 /** Persist one validated exact cursor identity (atomic tmp+rename). */

package/dist/core/feed/inbox.js

@@ -245,11 +245,19 @@ export function readCanceledEntryIds(nodeId) {
  *  the interrupt's abort lands right behind, and covered handoffs are never
  *  re-delivered anyway. Returns the newly canceled entry ids. */
 export function cancelPendingHumanMessages(nodeId) {
+    return cancelPendingEntries(nodeId, (e) => e.from === 'human' && e.kind === 'message');
+}
+/** Cancel every not-yet-settled entry the predicate selects. Retraction, not
+ *  deletion: the append-only inbox is untouched and the sidecar grows. Safe to
+ *  call late — an entry already past the cursor is not pending, and the watcher
+ *  re-reads the set at plan time so a cancel racing a buffered entry still
+ *  lands. */
+export function cancelPendingEntries(nodeId, select) {
     const cursor = readCursor(nodeId);
     const pending = readInboxSince(nodeId, cursor);
     const already = readCanceledEntryIds(nodeId);
     const targets = pending
-        .filter((e) => e.from === 'human' && e.kind === 'message' && !already.has(e.entry_id))
+        .filter((e) => !already.has(e.entry_id) && select(e))
         .map((e) => e.entry_id);
     if (targets.length === 0)
         return [];

package/dist/core/human/action-binding.d.ts

@@ -0,0 +1,21 @@
+export declare const HUMAN_ACTION_NAME_PATTERN: RegExp;
+export interface TicketActionBinding {
+    schema: 'crtr.human-action-binding/v1';
+    /** Declared action name, matching HUMAN_ACTION_NAME_PATTERN. */
+    name: string;
+    /** Frozen creation payload; opaque JSON, never inspected. */
+    payload: unknown;
+    /** The creator's absolute cwd, captured verbatim. */
+    creatorCwd: string;
+    /** Absolute path of the config file that won resolution. */
+    configOrigin: string;
+    /** Fully resolved argv; argv[0] is an absolute executable path. */
+    argv: string[];
+    /** Fully resolved absolute working directory. */
+    cwd: string;
+}
+/** Publish the binding before the page exists, so a visible request is never
+ * unbound. A second write is a caller bug, not a race to tolerate. */
+export declare function publishTicketActionBinding(dir: string, binding: TicketActionBinding): void;
+/** The frozen binding, or null for a request with no completion action. */
+export declare function readTicketActionBinding(dir: string): TicketActionBinding | null;

package/dist/core/human/action-binding.js

@@ -0,0 +1,40 @@
+// The optional completion-action binding of a durable human request. Written
+// once at creation and never again: `replace` revises the page, so the approved
+// effect must not be reachable from any later write.
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { actionBindingPath, publishJsonExclusive } from './convention.js';
+export const HUMAN_ACTION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const bindingSchema = z.object({
+    schema: z.literal('crtr.human-action-binding/v1'),
+    name: z.string().regex(HUMAN_ACTION_NAME_PATTERN),
+    payload: z.unknown(),
+    creatorCwd: z.string().min(1),
+    configOrigin: z.string().min(1),
+    argv: z.array(z.string().min(1)).min(1),
+    cwd: z.string().min(1),
+}).strict();
+/** Publish the binding before the page exists, so a visible request is never
+ * unbound. A second write is a caller bug, not a race to tolerate. */
+export function publishTicketActionBinding(dir, binding) {
+    if (!publishJsonExclusive(actionBindingPath(dir), binding)) {
+        throw new Error(`action binding already exists: ${actionBindingPath(dir)}`);
+    }
+}
+/** The frozen binding, or null for a request with no completion action. */
+export function readTicketActionBinding(dir) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(actionBindingPath(dir), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const parsed = bindingSchema.parse(raw);
+    // `payload` is optional-by-absence in JSON but required in the type; z.unknown()
+    // accepts a missing key, so restore it explicitly as the JSON null the
+    // completion document must carry.
+    return { ...parsed, payload: raw.payload ?? null };
+}

package/dist/core/human/completion.d.ts

@@ -0,0 +1,38 @@
+import type { TicketActionBinding } from './action-binding.js';
+import type { PageSource } from './page-schema.js';
+import type { TicketResult } from './types.js';
+export type HumanCompletionEvent = 'answered' | 'dismissed' | 'canceled';
+export interface HumanCompletionV1 {
+    schema: 'crtr.human-completion/v1';
+    requestId: string;
+    event: HumanCompletionEvent;
+    settledAt: string;
+    /** Present only when `event` is `answered`; absent, never empty, otherwise. */
+    responses?: Record<string, Record<string, unknown>>;
+    action: {
+        name: string;
+        payload: unknown;
+    };
+    provenance: {
+        source: PageSource;
+        actor?: string;
+    };
+    /** The lane overwrites this with the real attempt before writing stdin. */
+    delivery: {
+        attempt: number;
+    };
+}
+/** The one place a cancellation record without `disposition` reads as
+ * `canceled`. Every other reader treats both dispositions alike. */
+export declare function completionEventFor(result: TicketResult): HumanCompletionEvent;
+/** Build the complete document with `delivery.attempt` as the lane's placeholder. */
+export declare function composeHumanCompletion(args: {
+    requestId: string;
+    result: PageTerminalResult;
+    binding: TicketActionBinding;
+    source: PageSource;
+}): HumanCompletionV1;
+/** A review result can never carry an action binding; the composer is total over the rest. */
+export type PageTerminalResult = Extract<TicketResult, {
+    kind: 'page' | 'canceled';
+}>;