@north-light/crouter 0.3.198 → 0.3.199

package/dist/commands/sys/doctor.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { lstat, readFile, readdir, readlink } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
-import { readConfig, updateConfig } from '../../core/config.js';
+import { normalizeRequires, readConfig, updateConfig } from '../../core/config.js';
 import { scopeRoot, listScopes, marketplacesDir, pluginsDir } from '../../core/scope.js';
 import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
 import { pathExists, listDirs, removePath } from '../../core/fs-utils.js';
@@ -13,6 +13,9 @@ import { readFault } from '../../core/runtime/fault.js';
 import { detectNerdFont, nerdFontInstallCommand, NERD_FONT_SELECT_HINT } from '../../core/runtime/nerd-font.js';
 import { detectPackageManager } from './setup-core.js';
 import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { resolveBinContributions } from '../../core/runtime/bin-contributions.js';
+import { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
+import { listAllPlugins } from '../../core/resolver.js';
 import { SUBTREE_NAMES, coreCommandPaths } from '../../build-root.js';
 import { processGeneration, processLocatedGeneration, runtimeManifest, selectedGeneration } from './shared.js';
 function pass(scope, name, message) {
@@ -138,6 +141,58 @@ async function runCommandPluginChecks(scopes) {
     }
     return results;
 }
+/**
+ * Report every bare-binary contribution (`bin` in a plugin manifest or a scope
+ * `config.json`) that failed to reach a node's PATH, plus the ones that did.
+ * Purely static — the declared executable is NEVER run, exactly as plugin
+ * command manifests are only ever validated. Every remediation is a
+ * human_action: fixing a contributor's declaration or its file is the owner's
+ * call, never doctor's. Only contributions from a scope in `scopes` are
+ * reported, so `--scope` narrows these checks too.
+ */
+function runBinContributionChecks(scopes) {
+    const inScope = new Set(scopes);
+    const { bins, issues } = resolveBinContributions(process.cwd(), process.env['CRTR_PROFILE_ID'] || null);
+    const results = [];
+    for (const issue of issues) {
+        if (!inScope.has(issue.scope))
+            continue;
+        results.push(failCheck(issue.scope, `bin:${issue.name}`, `${issue.origin}: ${issue.message}`, {
+            kind: 'human_action',
+            description: `Fix the \`bin.${issue.name}\` declaration in ${issue.origin} — point it at an executable regular file inside that contributor's own root, or remove it. A same-precedence collision is resolved by renaming one of the claimants.`,
+        }));
+    }
+    for (const bin of bins.values()) {
+        if (!inScope.has(bin.scope))
+            continue;
+        results.push(pass(bin.scope, `bin:${bin.name}`, `${bin.origin} → ${bin.target}`));
+    }
+    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) {
+    const inScope = new Set(scopes);
+    const env = buildBrokerEnv({ argv: [], env: { CRTR_NODE_CWD: process.cwd(), CRTR_PROFILE_ID: process.env['CRTR_PROFILE_ID'] ?? '' } });
+    const results = [];
+    for (const plugin of listAllPlugins()) {
+        if (!inScope.has(plugin.scope) || !plugin.enabled || plugin.manifest.requires === undefined)
+            continue;
+        for (const [name, hint] of Object.entries(normalizeRequires(plugin.manifest.requires))) {
+            const target = resolvePathExecutable(name, env, process.cwd());
+            if (target !== null) {
+                results.push(pass(plugin.scope, `requires:${name}`, `plugin "${plugin.name}" → ${target}`));
+            }
+            else {
+                results.push(failCheck(plugin.scope, `requires:${name}`, `plugin "${plugin.name}" requires executable "${name}" on PATH`, {
+                    kind: 'human_action',
+                    description: hint,
+                }));
+            }
+        }
+    }
+    return results;
+}
 async function inventory(root) {
     const files = [];
     async function walk(dir) {
@@ -422,12 +477,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. 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 manifest checks appear as plugin:<name>:commands (validated statically, never executed); their remediation is always a human_action (disable/update/remove the plugin). 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. 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 manifest checks appear as plugin:<name>:commands (validated statically, never executed); their remediation is always a human_action (disable/update/remove the plugin). 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 manifests are validated statically — the plugin executable is never run, at any time.',
+            'Read-only unless --fix is passed. Runtime verification reads and hashes every selected/process generation file; plugin command manifests, bare-binary (`bin`) 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 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.',
         ],
@@ -445,6 +500,8 @@ export const sysDoctorLeaf = defineLeaf({
         if (scopes.includes('user'))
             allResults.push(runNerdFontCheck());
         allResults.push(...await runCommandPluginChecks(scopes));
+        allResults.push(...runBinContributionChecks(scopes));
+        allResults.push(...runRequiresChecks(scopes));
         allResults.push(...await runFaultChecks());
         const processLocation = processGeneration();
         allResults.push(...await generationChecks('selected', selectedGeneration(), processLocation === null));

package/dist/commands/sys/feedback.js

@@ -1,9 +1,18 @@
-// `crtr sys feedback` — file a GitHub issue against the crtr repo when the
-// harness itself misbehaves (a command errors unexpectedly, hangs, churns, or
-// acts contrary to its documented contract). The agent supplies one prose
-// description; everything else (version, node identity, recent activity) is
-// auto-collected and templated into the issue body. gh-less / unauthed hosts
-// fall back to a durable local file so the report is never lost.
+// `crtr sys feedback` — report a crtr harness bug when the harness itself
+// misbehaves (a command errors unexpectedly, hangs, churns, or acts contrary to
+// its documented contract). The agent supplies one prose description; everything
+// else (version, node identity, recent activity) is auto-collected and templated
+// into the report body.
+//
+// WHERE the report goes is a property of the deployment, not of the agent: this
+// command owns the report — its contract, its context collection, its templating
+// — while the deployment owns delivery. A host with `gh` and a person behind it
+// opens the issue directly; a hosted runtime (a Northlight guest VM, say) has no
+// GitHub credential and shouldn't be given one, so it sets
+// CRTR_FEEDBACK_ENDPOINT and its backend forwards the report with an identity
+// crtr never has to hold. Exactly one sink is chosen per deployment — this is a
+// configured provider, not a fallback chain. Delivery failure on either path
+// still writes a durable local file so the report is never lost.
 import { spawnSync } from 'node:child_process';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -19,6 +28,12 @@ import { readPackageVersion } from './shared.js';
 /** Canonical repo for crtr harness feedback — feedback is always about the
  *  tool, regardless of which project the reporting agent is working in. */
 const FEEDBACK_REPO = 'vallum-security/crouter';
+/** Deployment-configured delivery. When CRTR_FEEDBACK_ENDPOINT names an HTTP
+ *  endpoint, it is the sink and gh is not consulted; CRTR_FEEDBACK_TOKEN, when
+ *  present, is sent as a bearer credential. */
+const ENDPOINT_ENV = 'CRTR_FEEDBACK_ENDPOINT';
+const TOKEN_ENV = 'CRTR_FEEDBACK_TOKEN';
+const ENDPOINT_TIMEOUT_MS = 15_000;
 async function collectContext() {
     const env = process.env;
     const nodeId = env['CRTR_NODE_ID'] ?? null;
@@ -106,7 +121,47 @@ function buildBody(message, ctx) {
     }
     return parts.join('\n') + '\n';
 }
-/** Persist a report locally when gh can't file it, so nothing is lost. Returns
+/** POST the report to the deployment's configured endpoint. The endpoint may
+ *  answer with a `url` naming where the report landed; anything else about the
+ *  response body is the backend's business, not ours. */
+async function deliverToEndpoint(endpoint, title, body, message, ctx) {
+    const token = process.env[TOKEN_ENV];
+    try {
+        const res = await fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                ...(token !== undefined && token !== '' ? { authorization: `Bearer ${token}` } : {}),
+            },
+            body: JSON.stringify({ title, body, message, context: ctx }),
+            signal: AbortSignal.timeout(ENDPOINT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            const detail = (await res.text().catch(() => '')).trim().slice(0, 400);
+            return { error: `${ENDPOINT_ENV} returned HTTP ${res.status}${detail === '' ? '' : `: ${detail}`}` };
+        }
+        const payload = (await res.json().catch(() => null));
+        const url = typeof payload?.url === 'string' ? payload.url : undefined;
+        return url === undefined ? {} : { url };
+    }
+    catch (err) {
+        return { error: `${ENDPOINT_ENV} unreachable: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/** Open the GitHub issue directly with the host's own gh credential. */
+function deliverToGitHub(title, body) {
+    const res = spawnSync('gh', ['issue', 'create', '--repo', FEEDBACK_REPO, '--title', title, '--body-file', '-'], { input: body, encoding: 'utf8' });
+    if (res.error === undefined && res.status === 0) {
+        const url = res.stdout.trim().split('\n').filter((l) => l.startsWith('http')).pop() ?? res.stdout.trim();
+        return { url };
+    }
+    return {
+        error: res.error !== undefined
+            ? `gh not available: ${res.error.message}`
+            : (res.stderr?.trim() || `gh exited ${res.status}`),
+    };
+}
+/** Persist a report locally when delivery fails, so nothing is lost. Returns
  *  the absolute path written. */
 function saveLocally(title, body) {
     const dir = join(userScopeRoot(), 'feedback');
@@ -118,17 +173,17 @@ function saveLocally(title, body) {
 }
 export const sysFeedbackLeaf = defineLeaf({
     name: 'feedback',
-    description: 'report a crtr harness bug as a GitHub issue',
-    whenToUse: 'a crtr command itself misbehaves — it errors unexpectedly, hangs, churns, double-spawns, or acts contrary to its documented contract. NOT for your task work or decisions a human should make (that is `crtr human ask`); this reports the TOOL, filing an issue against the crtr repo with your node context auto-attached.',
+    description: 'report a crtr harness bug to whoever maintains this crtr install',
+    whenToUse: 'a crtr command itself misbehaves — it errors unexpectedly, hangs, churns, double-spawns, or acts contrary to its documented contract. NOT for your task work or decisions the user should make (that is `crtr human send`); this reports the TOOL, filing a report with the crtr maintainers with your node context auto-attached.',
     help: {
         name: 'sys feedback',
-        summary: 'file a GitHub issue describing a crtr harness bug, with node context auto-attached',
+        summary: 'file a report describing a crtr harness bug, with node context auto-attached',
         params: [
             {
                 kind: 'positional',
                 name: 'message',
                 required: true,
-                constraint: 'What broke, in your own words: the command you ran, what you expected, what happened instead. Be concrete — this is the only part a human writes; everything else is auto-collected.',
+                constraint: 'What broke, in your own words: the command you ran, what you expected, what happened instead. Be concrete — this is the only part you write; everything else is auto-collected.',
             },
             {
                 kind: 'flag',
@@ -140,14 +195,14 @@ export const sysFeedbackLeaf = defineLeaf({
         ],
         output: [
             { name: 'status', type: 'string', required: true, constraint: 'filed | saved-locally.' },
-            { name: 'url', type: 'string', required: false, constraint: 'Issue URL when status is filed.' },
-            { name: 'path', type: 'string', required: false, constraint: 'Local report path when status is saved-locally (gh unavailable).' },
+            { name: 'url', type: 'string', required: false, constraint: 'Where the report landed, when the sink names a location.' },
+            { name: 'path', type: 'string', required: false, constraint: 'Local report path when status is saved-locally.' },
             { name: 'error', type: 'string', required: false, constraint: 'Why filing fell back to local save.' },
         ],
         outputKind: 'object',
         effects: [
-            `Opens a public GitHub issue on ${FEEDBACK_REPO} via gh.`,
-            'On gh failure (missing / unauthenticated), writes the report to ~/.crouter/feedback/ instead — never lost.',
+            `Sends the report where this install delivers harness feedback: the ${ENDPOINT_ENV} endpoint when the deployment sets one, otherwise a public GitHub issue on ${FEEDBACK_REPO} via gh.`,
+            'On delivery failure, writes the report to ~/.crouter/feedback/ instead — never lost.',
         ],
     },
     run: async (input) => {
@@ -158,17 +213,16 @@ export const sysFeedbackLeaf = defineLeaf({
         const ctx = await collectContext();
         const title = deriveTitle(input['title'], message);
         const body = buildBody(message, ctx);
-        const res = spawnSync('gh', ['issue', 'create', '--repo', FEEDBACK_REPO, '--title', title, '--body-file', '-'], { input: body, encoding: 'utf8' });
-        if (res.error === undefined && res.status === 0) {
-            const url = res.stdout.trim().split('\n').filter((l) => l.startsWith('http')).pop() ?? res.stdout.trim();
-            return { status: 'filed', url };
+        const endpoint = process.env[ENDPOINT_ENV]?.trim();
+        const delivery = endpoint !== undefined && endpoint !== ''
+            ? await deliverToEndpoint(endpoint, title, body, message, ctx)
+            : deliverToGitHub(title, body);
+        if (delivery.error === undefined) {
+            return delivery.url === undefined ? { status: 'filed' } : { status: 'filed', url: delivery.url };
         }
-        // gh missing, unauthenticated, or the API call failed — persist locally so
-        // the report survives, and tell the agent how to escalate.
-        const reason = res.error !== undefined
-            ? `gh not available: ${res.error.message}`
-            : (res.stderr?.trim() || `gh exited ${res.status}`);
+        // The sink rejected or was unreachable — persist locally so the report
+        // survives, and tell the agent why.
         const path = saveLocally(title, body);
-        return { status: 'saved-locally', path, error: reason };
+        return { status: 'saved-locally', path, error: delivery.error };
     },
 });

package/dist/commands/sys/settings.js

@@ -9,7 +9,7 @@ import { BROKER_LIMIT_OVERRIDE_PRECEDENCE } from './setup.js';
 export const sysSettingsLeaf = defineLeaf({
     name: 'settings',
     description: 'open the settings page — providers, models, keybindings, display, panes, broker limits, updates',
-    whenToUse: 'a human wants to change crouter configuration interactively. Agents should use sys config get/set, which is scriptable; sys setup installs a fresh machine.',
+    whenToUse: 'the user wants to change crouter configuration interactively. Agents should use sys config get/set, which is scriptable; sys setup installs a fresh machine.',
     help: {
         name: 'sys settings',
         summary: 'open the interactive settings page for an already-installed crouter',

package/dist/core/__tests__/cron-broker-capacity.test.js

@@ -104,7 +104,7 @@ test('an on-change cron that cancels itself still delivers its final output', as
     assert.equal(markSelfCanceledCronRun('self-cancel-delivery', readFileSync(runIdPath, 'utf8')), true);
     assert.equal(cancelCron('self-cancel-delivery', { preserveRunningProcess: true }), true);
     const record = await run;
-    assert.equal(record?.delivered, 'delivered: human notify');
+    assert.equal(record?.delivered, 'delivered: human send --inbox');
 });
 test('cronLaunchesNode classifies by command verb and armed sink', () => {
     const of = (command, sink = '{}') => cronLaunchesNode({ command, sink });

package/dist/core/__tests__/extension-abort.test.js

@@ -10,9 +10,12 @@ test('refresh extension abort clears Pi follow-ups before abort while an ordinar
     abortSessionFromExtension(session);
     assert.deepEqual(events, ['abort'], 'ordinary extension abort leaves queued messages in the current conversation');
     events.length = 0;
-    runRefreshAbort(() => abortSessionFromExtension(session));
+    let refreshAborts = 0;
+    runRefreshAbort(() => abortSessionFromExtension(session, () => { refreshAborts += 1; }));
     assert.deepEqual(events, ['clear', 'abort'], 'refresh removes queued messages before stopping the discarded conversation');
+    assert.equal(refreshAborts, 1, 'refresh stages provenance with the host abort');
     events.length = 0;
-    abortSessionFromExtension(session);
+    abortSessionFromExtension(session, () => { refreshAborts += 1; });
     assert.deepEqual(events, ['abort'], 'the refresh scope does not leak into a later critical abort');
+    assert.equal(refreshAborts, 1, 'an ordinary extension abort does not stage refresh provenance');
 });

package/dist/core/__tests__/fixtures/fake-engine.d.ts

@@ -188,8 +188,19 @@ declare class FakeSession {
     private syncTreeSnapshot;
     setSessionName(_name: string): void;
     prompt(text: string, _options?: unknown): Promise<void>;
-    steer(_text: string): Promise<void>;
-    followUp(_text: string): Promise<void>;
+    /** The unrun queues the welcome snapshot reports (`snapshot.queued`). Real
+     *  pi holds a steer + followUp queue and drains it when the next turn runs;
+     *  the fake records the same texts and clears them in emitTurn, so a client
+     *  attaching mid-queue sees what a real broker would hand it. Both readers
+     *  exist on the real AgentSession, so omitting them does not make the fake
+     *  merely queueless — it makes buildSnapshot throw, and every attach test
+     *  then times out waiting for a welcome the broker never built. */
+    private readonly steering;
+    private readonly followUps;
+    getSteeringMessages(): readonly string[];
+    getFollowUpMessages(): readonly string[];
+    steer(text: string): Promise<void>;
+    followUp(text: string): Promise<void>;
     /** In-memory recording only — no proof file, matching the offline in-process
      *  contract broker-sdk-wiring.test.ts's REAL-SDK tests already use. Purely
      *  defensive: broker.ts's driveEngine now calls `session.sendCustomMessage`

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -224,7 +224,22 @@ class SessionTree {
     buildSessionContext() {
         return { messages: this.branchMessages(), thinkingLevel: 'off', model: null };
     }
+    /** Every entry in the session file, active branch or abandoned tail alike —
+     *  the real SessionManager.getEntries(). */
+    getEntries() {
+        return [...this.entries.values()];
+    }
+    /** The active branch root→leaf — the real SessionManager.getBranch(). The
+     *  extensions that scan for their own marker read THIS, not the whole file:
+     *  a new cycle must not see a previous branch's markers. */
+    getBranch() {
+        return this.branchIds().map((id) => this.entries.get(id)).filter((entry) => entry !== undefined);
+    }
     branchMessages() {
+        return this.branchIds().map((id) => this.entries.get(id)?.message).filter((m) => m !== undefined);
+    }
+    /** The active branch's entry ids, root→leaf. */
+    branchIds() {
         const ids = [];
         let cur = this.leafId;
         while (cur !== null) {
@@ -235,7 +250,7 @@ class SessionTree {
             cur = entry.parentId;
         }
         ids.reverse();
-        return ids.map((id) => this.entries.get(id)?.message).filter((m) => m !== undefined);
+        return ids;
     }
     node(id) {
         const entry = this.entries.get(id);
@@ -446,10 +461,27 @@ class FakeSession {
             this.promptFailuresRemaining--;
         return this.emitTurn(text, { fail, runHooks: true });
     }
-    steer(_text) {
+    /** The unrun queues the welcome snapshot reports (`snapshot.queued`). Real
+     *  pi holds a steer + followUp queue and drains it when the next turn runs;
+     *  the fake records the same texts and clears them in emitTurn, so a client
+     *  attaching mid-queue sees what a real broker would hand it. Both readers
+     *  exist on the real AgentSession, so omitting them does not make the fake
+     *  merely queueless — it makes buildSnapshot throw, and every attach test
+     *  then times out waiting for a welcome the broker never built. */
+    steering = [];
+    followUps = [];
+    getSteeringMessages() {
+        return this.steering;
+    }
+    getFollowUpMessages() {
+        return this.followUps;
+    }
+    steer(text) {
+        this.steering.push(text);
         return Promise.resolve();
     }
-    followUp(_text) {
+    followUp(text) {
+        this.followUps.push(text);
         return Promise.resolve();
     }
     /** In-memory recording only — no proof file, matching the offline in-process
@@ -560,6 +592,9 @@ class FakeSession {
         // still climbs monotonically past the 32 MiB byte cap and is shed. Without the
         // pace the burst outruns the reader's event loop and sheds the fast viewer too.
         const yieldTick = () => pad > 0 ? new Promise((r) => setTimeout(r, 3)) : new Promise((r) => setImmediate(r));
+        // A turn consumes whatever was queued for it, as the real session does.
+        this.steering.length = 0;
+        this.followUps.length = 0;
         this.streaming = true;
         if (opts.runHooks === true) {
             await this.fire('agent_start', {}, this.buildCtx());
@@ -789,6 +824,7 @@ class FakeSession {
                 CRTR_MODE: env['CRTR_MODE'] ?? null,
                 CRTR_LIFECYCLE: env['CRTR_LIFECYCLE'] ?? null,
                 CRTR_NODE_CWD: env['CRTR_NODE_CWD'] ?? null,
+                CRTR_PROFILE_ID: env['CRTR_PROFILE_ID'] ?? null,
                 CRTR_HOME: env['CRTR_HOME'] ?? null,
                 CRTR_PARENT_NODE_ID: env['CRTR_PARENT_NODE_ID'] ?? null,
                 CRTR_ROOT_SESSION: env['CRTR_ROOT_SESSION'] ?? null,
@@ -829,6 +865,14 @@ class FakeSession {
                 getSessionId: () => this.sm.getSessionId(),
                 getSessionFile: () => this.sm.getSessionFile(),
                 getLeafId: () => this.turnEndLeafId ?? this.tree.getLeafId(),
+                // The session-scanning extensions (context-intro, review-boundary,
+                // recap) read the branch at session_start to decide whether their own
+                // marker is already present. Both exist on the real SessionManager, so
+                // a fake missing them is not a degraded fixture but a broken one: the
+                // handler throws, session_start never completes, and every attach test
+                // times out waiting for a welcome that the broker never sends.
+                getBranch: () => this.tree.getBranch(),
+                getEntries: () => this.tree.getEntries(),
             },
             getContextUsage: () => ({ tokens: 1000 }),
             // Wired to the broker's shutdownHandler: the stophook calls ctx.shutdown()

package/dist/core/__tests__/human-cancel-guard.test.js

@@ -1,16 +1,19 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/human-cancel-guard.test.ts
 //
-// N2 — humanCancel on an already-canceled (but unresolved) interaction node must
-// short-circuit to {canceled:false, reason:'already_resolved'} instead of falling
-// through to transition('finalize'), which is illegal from status='canceled' and
-// would throw. Guards the one-line hardening in queue.ts's status guard.
+// N2 — humanCancel on a ticket the store has already settled must short-circuit to
+// {canceled:false, reason:'already_resolved'} rather than throwing. A second cancel
+// is the ordinary race (the human submits while the agent retracts), so the client
+// guard in queue.ts turns the daemon's 409 into an idempotent no-op.
 import { test, before, after, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, rmSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { createNode, setStatus } from '../canvas/canvas.js';
+import { createNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
+import { nodeDir } from '../canvas/paths.js';
+import { atomicWriteJson, bindTicketReplyRoute, pageManifestPath } from '../human/convention.js';
+import { cancelTicket } from '../human/tickets.js';
 import { humanCancel } from '../../commands/human/queue.js';
 import { createApiServer } from '../../daemon/api/server.js';
 import { apiSocketPath } from '../canvas/paths.js';
@@ -35,12 +38,29 @@ function node(id) {
         name: id,
         created: new Date().toISOString(),
         cwd: '/tmp/work',
-        kind: 'general',
+        kind: 'human',
         mode: 'base',
         lifecycle: 'terminal',
         status: 'active',
     };
 }
+/** Publish a reply-bearing page ticket in the bridge node's directory, exactly as
+ *  `human send` does: reply route first, then the page manifest. */
+function publishTicket(id) {
+    const dir = nodeDir(id);
+    mkdirSync(dir, { recursive: true });
+    bindTicketReplyRoute(dir, id);
+    atomicWriteJson(pageManifestPath(dir), {
+        schema: 'crtr.page/v2',
+        dialect: 'jsx',
+        title: id,
+        subtitle: 'Acknowledge this ticket so the request can proceed.',
+        delivery: { placement: 'inline', inbox: true, reply: true },
+        document: 'page.tsx',
+        steps: 1,
+        slots: [],
+    });
+}
 before(() => {
     home = mkdtempSync(join(tmpdir(), 'crtr-humancancel-'));
     process.env['CRTR_HOME'] = home;
@@ -60,12 +80,13 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-test('cancel on an already-canceled node is a no-op, never throws on the finalize', async () => {
+test('cancel on an already-canceled ticket is a no-op, never throws on the finalize', async () => {
     const id = 'canceledJob';
     createNode(node(id));
-    setStatus(id, 'canceled'); // canceled but no response.json written yet
-    const res = (await humanCancel.run({ job_id: id }));
+    publishTicket(id);
+    cancelTicket(nodeDir(id), { actor: 'human' }); // settled by the first cancel
+    const res = (await humanCancel.run({ ticket_id: id }));
     assert.equal(res['canceled'], false);
     assert.equal(res['reason'], 'already_resolved');
-    assert.equal(res['job_id'], id);
+    assert.equal(res['ticket_id'], id);
 });

package/dist/core/__tests__/human-deliver.test.js

@@ -8,12 +8,13 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createApiServer } from '../../daemon/api/server.js';
 import { cancelHumanTicket, deliverTerminalResult, resolvePageTicket } from '../../daemon/human/finish.js';
-import { humanAsk, humanNotify } from '../../commands/human/prompts.js';
+import { humanSend } from '../../commands/human/prompts.js';
 import { getNode, listNodes, closeDb } from '../canvas/index.js';
 import { readInboxSince } from '../feed/inbox.js';
 import { resolveRef } from '../canvas/history.js';
 import { apiSocketPath } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
+import { bindTicketReplyRoute } from '../human/convention.js';
 import { ticketDir } from '../human/root.js';
 import { readTicketResult, submitPage } from '../human/tickets.js';
 let home;
@@ -39,16 +40,17 @@ async function withMutedStdout(fn) {
 }
 function bridgeUnder() {
     const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
-    const bridge = spawnNode({ kind: 'human', parent, cwd: home, name: 'human-ask', lifecycle: 'terminal' }).node_id;
+    const bridge = spawnNode({ kind: 'human', parent, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
     return { parent, bridge };
 }
 function submitBridgePage(bridge) {
     const dir = ticketDir(bridge);
     const sourceDir = mkdtempSync(join(tmpdir(), 'crtr-deliver-page-'));
-    const sourceFile = join(sourceDir, 'page.html');
-    writeFileSync(sourceFile, '<!doctype html><html><head><meta name="crtr-page-title" content="Ship it?"><meta name="crtr-page-subtitle" content="Decide whether to ship now so the release can proceed."></head><body><crtr-pages><crtr-page><crtr-text id="question"><script type="application/json">{"initialText":"","editable":true}</script></crtr-text></crtr-page></crtr-pages></body></html>');
+    const sourceFile = join(sourceDir, 'page.tsx');
+    writeFileSync(sourceFile, 'export default () => (\n  <Page title="Ship it?" subtitle="Decide whether to ship now so the release can proceed.">\n    <UserText id="question" initialText="" />\n  </Page>\n);\n');
     try {
-        submitPage({ dir, sourceFile, dialect: 'html' });
+        bindTicketReplyRoute(dir, bridge);
+        submitPage({ dir, sourceFile, delivery: { placement: 'inline', inbox: true, reply: true } });
     }
     finally {
         rmSync(sourceDir, { recursive: true, force: true });
@@ -87,40 +89,41 @@ after(() => {
     delete process.env['CRTR_NODE_ID'];
 });
 describe('enqueue is producer-only', () => {
-    test('ask preserves title and subtitle from the authored page', async () => {
+    test('send preserves title and subtitle from the authored page', async () => {
         const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
         process.env['CRTR_NODE_ID'] = parent;
-        const page = join(home, 'release-decision.html');
-        writeFileSync(page, '<!doctype html><html><head><meta name="crtr-page-title" content="Release decision"><meta name="crtr-page-subtitle" content="Decide whether to release now so the launch can proceed."></head><body><p>This first line stays page content.</p><crtr-pages><crtr-page><crtr-text id="question"><script type="application/json">{"initialText":"","editable":true}</script></crtr-text></crtr-page></crtr-pages></body></html>');
-        await assert.rejects(() => humanAsk.run({}), /a page source is required/);
-        await assert.rejects(() => humanAsk.run({ page, document: '<!doctype html><html></html>' }), /received both --page and a piped page document/);
-        const result = (await humanAsk.run({ page, document: '' }));
-        assert.equal(typeof result['job_id'], 'string');
+        const page = join(home, 'release-decision.tsx');
+        writeFileSync(page, 'export default () => (\n  <Page title="Release decision" subtitle="Decide whether to release now so the launch can proceed.">\n    <p>This first line stays page content.</p>\n    <UserText id="question" initialText="" />\n  </Page>\n);\n');
+        await assert.rejects(() => humanSend.run({}), /a page source is required/);
+        await assert.rejects(() => humanSend.run({ page, document: 'export default () => <Page title="Dup" />;' }), /received both --page and a piped page document/);
+        const result = (await humanSend.run({ page, document: '' }));
+        assert.equal(typeof result['page_id'], 'string');
+        assert.equal(result['reply'], true);
         assert.equal(typeof result['dir'], 'string');
         for (const forbidden of ['pane_id', 'render_pane_id', 'pid', 'worker_pid'])
-            assert.ok(!(forbidden in result), `ask result must not expose ${forbidden}`);
+            assert.ok(!(forbidden in result), `send result must not expose ${forbidden}`);
         const manifest = JSON.parse(readFileSync(join(result['dir'], 'page.json'), 'utf8'));
         assert.equal(manifest.title, 'Release decision');
         assert.equal(manifest.subtitle, 'Decide whether to release now so the launch can proceed.');
-        const document = readFileSync(join(result['dir'], 'page.html'), 'utf8');
+        const document = readFileSync(join(result['dir'], 'page.tsx'), 'utf8');
         assert.ok(document.includes('This first line stays page content.'));
         assert.equal(manifest.slots.filter((slot) => slot.kind === 'text').length, 1);
     });
-    test('ask materializes a piped page before validation and publication', async () => {
+    test('send materializes a piped page before validation and publication', async () => {
         const parent = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'asker' }).node_id;
         process.env['CRTR_NODE_ID'] = parent;
-        const document = '<!doctype html><html><head><meta name="crtr-page-title" content="Piped question"><meta name="crtr-page-subtitle" content="Answer the question to unblock this task."></head><body><crtr-pages><crtr-page><crtr-text id="question"><script type="application/json">{"initialText":""}</script></crtr-text></crtr-page></crtr-pages></body></html>';
-        const result = (await humanAsk.run({ document }));
+        const document = 'export default () => (\n  <Page title="Piped question" subtitle="Answer the question to unblock this task.">\n    <UserText id="question" initialText="" />\n  </Page>\n);\n';
+        const result = (await humanSend.run({ document }));
         const manifest = JSON.parse(readFileSync(join(result['dir'], 'page.json'), 'utf8'));
         assert.equal(manifest.title, 'Piped question');
-        assert.equal(readFileSync(join(result['dir'], 'page.html'), 'utf8'), document);
+        assert.equal(readFileSync(join(result['dir'], 'page.tsx'), 'utf8'), document);
     });
 });
 describe('terminal ticket delivery', () => {
     test('resolvePageTicket pushFinals the readable answer once and wakes the subscribed parent', async () => {
         const { parent, bridge } = bridgeUnder();
         const dir = submitBridgePage(bridge);
-        const result = await resolvePageTicket(bridge, { question: { text: 'yes, ship', edited: true, comments: [] } });
+        const result = await resolvePageTicket(bridge, { question: { text: 'yes, ship', edited: true } });
         assert.equal(result.kind, 'page');
         closeDb();
         assert.equal(getNode(bridge)?.status, 'done');
@@ -133,7 +136,7 @@ describe('terminal ticket delivery', () => {
     test('a replay against a terminal bridge is a no-op', async () => {
         const { parent, bridge } = bridgeUnder();
         submitBridgePage(bridge);
-        await resolvePageTicket(bridge, { question: { text: 'yes', edited: true, comments: [] } });
+        await resolvePageTicket(bridge, { question: { text: 'yes', edited: true } });
         assert.equal(await deliverTerminalResult(bridge), true);
         closeDb();
         const finals = readInboxSince(parent).filter((entry) => entry.from === bridge && entry.kind === 'final');
@@ -141,7 +144,7 @@ describe('terminal ticket delivery', () => {
     });
     test('cancelHumanTicket finishes the bridge and notifies non-actor subscribers', async () => {
         const actor = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'actor' }).node_id;
-        const bridge = spawnNode({ kind: 'human', parent: actor, cwd: home, name: 'human-ask', lifecycle: 'terminal' }).node_id;
+        const bridge = spawnNode({ kind: 'human', parent: actor, cwd: home, name: 'human-page', lifecycle: 'terminal' }).node_id;
         const other = spawnNode({ kind: 'general', parent: null, cwd: home, name: 'other' }).node_id;
         const { subscribe } = await import('../canvas/canvas.js');
         subscribe(other, bridge, true);
@@ -156,12 +159,14 @@ describe('terminal ticket delivery', () => {
         assert.match(notes[0].label, /canceled/);
     });
 });
-test('notify enqueues an authored page and creates no canvas node', async () => {
-    const page = join(home, 'build-done.html');
-    writeFileSync(page, '<!doctype html><html><head><meta name="crtr-page-title" content="Build done"><meta name="crtr-page-subtitle" content="The build passed, so the change is ready to review."></head><body><p>Build output is ready.</p></body></html>');
+test('a display-only page publishes passively and creates no canvas node', async () => {
+    const page = join(home, 'build-done.tsx');
+    writeFileSync(page, 'export default () => (\n  <Page title="Build done" subtitle="The build passed, so the change is ready to review.">\n    <p>Build output is ready.</p>\n  </Page>\n);\n');
     const before = listNodes().length;
-    const result = (await humanNotify.run({ page }));
-    assert.equal(result['queued'], true);
+    const result = (await humanSend.run({ page }));
+    assert.equal(result['reply'], false);
+    assert.equal(result['inbox'], false);
+    assert.equal(typeof result['page_id'], 'string');
     assert.equal(typeof result['dir'], 'string');
     assert.ok(existsSync(join(result['dir'], 'page.json')));
     assert.ok(readTicketResult(result['dir']) === null);