@north-light/crouter 0.3.198 → 0.3.200

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__/helpers/harness.js

@@ -28,7 +28,7 @@ import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
 import { createNode, getNode, recordPid, subscribersOf, subscriptionsOf, } from '../../canvas/canvas.js';
 import { closeDb } from '../../canvas/db.js';
-import { reviveNode } from '../../runtime/revive.js';
+import { spawnChild } from '../../runtime/spawn.js';
 import { superviseTick } from '../../../daemon/crtrd.js';
 import { DaemonFleet } from '../../../daemon/fleet.js';
 import { apiSocketPath } from '../../canvas/paths.js';
@@ -150,11 +150,11 @@ export async function createHarness(opts = {}) {
     const tmpHome = mkdtempSync(join(tmpdir(), 'crtr-harness-HOME-'));
     const session = `${opts.sessionPrefix ?? 'crtr-harness'}-${process.pid}-${Date.now().toString(36)}`;
     // The harness reads/writes the isolated canvas in-process. CRTR_PI_BINARY in
-    // OUR env makes in-process revives (superviseTick → reviveNode → openNodeWindow)
+    // OUR env makes in-process launches (spawnChild and superviseTick → reviveNode)
     // bake the fake-pi into the command string.
     process.env['CRTR_HOME'] = home;
     // HOME must be isolated in THIS process too, not just in the subprocess envs
-    // below: an in-process launch (spawnHeadlessChild's reviveNode, superviseTick
+    // below: an in-process launch (spawnHeadlessChild's spawnChild, superviseTick
     // pass-2 wakes) builds its broker env from process.env, so a real HOME here
     // makes every broker read the developer's OWN ~/.pi/agent — auth.json and the
     // managed subscription pools — instead of agentHome, and provider tests then
@@ -202,7 +202,7 @@ export async function createHarness(opts = {}) {
     resetEventSourceForTests();
     bindDaemonEventSource();
     // The harness also stands in for the daemon's FLEET: every in-harness broker
-    // launch (reviveNode from a test, superviseTick pass-2 wakes) registers its
+    // launch (spawnChild, reviveNode, superviseTick pass-2 wakes) registers its
     // ChildProcess handle here, and real child exits enqueue exit-policy jobs on
     // this serial work lane — the same single-lane discipline crtrd runs, but
     // drainable to a deterministic quiescent point. Reset first for the same
@@ -367,17 +367,9 @@ export async function createHarness(opts = {}) {
     }
     function nodeDirs() {
         try {
-            // Node ids are minted by newNodeId() (runtime/nodes.ts) as
-            // `<install>-<time36>-<rand4hex>` (a72554e3 stamped the canvas-install id
-            // onto the historical 2-segment `<time36>-<rand4hex>` shape, so the id is
-            // opaque and its segment count has already changed once — mirror
-            // profiles/manifest.ts's ID_SHAPE rather than hard-coding a segment
-            // count). Scope the scan to "one or more lowercase-alnum segments ending
-            // in an 8-hex random suffix" so a stray non-node sibling under nodes/ is
-            // never miscounted as a new node dir — e.g. a `reports/` dir created for
-            // an empty node id (the rare CI flake on compiled-seam run 27459304455 that
-            // broke the spawn counters with `expected exactly 1 new node dir, got
-            // [<id>, reports]`), or literal `reports` (no hyphen, no hex suffix).
+            // Node ids end in an 8-hex random suffix and may have any number of
+            // lowercase-alphanumeric prefix segments. Only return those node dirs so
+            // fixture cleanup never treats a non-node sibling as a canvas row.
             return readdirSync(join(home, 'nodes')).filter((d) => /^[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}$/.test(d));
         }
         catch {
@@ -507,46 +499,16 @@ export async function createHarness(opts = {}) {
             return id;
         },
         async spawnHeadlessChild(parentId, task, o = {}) {
-            const before = new Set(nodeDirs());
-            // The synchronous CLI must reach the separate API fixture process, which
-            // creates the row and necessarily starts a fixture-owned broker before
-            // returning. Production has one daemon/fleet; the harness split exists
-            // only because spawnSync blocks this process's event loop. Retire that
-            // fixture launch immediately, then perform the authoritative boot through
-            // THIS process's reviveNode so the harness fleet owns the ChildProcess
-            // handle and its real exit event (§H harness mode a).
-            const args = ['node', 'new', task, '--parent', parentId, '--cwd', CROUTER];
-            if (o.kind)
-                args.push('--kind', o.kind);
-            if (o.mode)
-                args.push('--mode', o.mode);
-            if (o.model)
-                args.push('--model', o.model);
-            const res = cli(parentId, args);
-            if (res.code !== 0) {
-                throw new Error(`spawnHeadlessChild(${parentId}) failed (code ${res.code})\n--stdout--\n${res.stdout}\n--stderr--\n${res.stderr}`);
-            }
-            const added = nodeDirs().filter((d) => !before.has(d));
-            if (added.length !== 1) {
-                throw new Error(`spawnHeadlessChild: expected exactly 1 new node dir, got [${added.join(', ')}]`);
-            }
-            const childId = added[0];
-            closeDb();
-            const fixtureRow = getNode(childId);
-            const fixturePid = fixtureRow?.pi_pid ?? null;
-            const fixtureIdentity = fixtureRow?.pi_pid_identity ?? null;
-            const priorBoots = harness.bootCount(childId);
-            if (fixturePid !== null && fixtureIdentity !== null && recordedPidLiveness(fixturePid, fixtureIdentity) === 'alive') {
-                process.kill(fixturePid, 'SIGTERM');
-                await waitFor(() => recordedPidLiveness(fixturePid, fixtureIdentity) !== 'alive', {
-                    timeoutMs: 10_000,
-                    intervalMs: 25,
-                    label: `API-fixture broker exit for ${childId}`,
-                });
-            }
-            reviveNode(childId, { resume: false });
-            await harness.awaitBoot(childId, { minCount: priorBoots + 1 });
-            return childId;
+            const result = await spawnChild({
+                kind: o.kind ?? 'general',
+                cwd: CROUTER,
+                prompt: task,
+                parent: parentId,
+                ...(o.mode !== undefined ? { mode: o.mode } : {}),
+                ...(o.model !== undefined ? { model: o.model } : {}),
+            });
+            await harness.awaitBoot(result.node.node_id);
+            return result.node.node_id;
         },
         cli,
         async stop(nodeId, reason = 'stop', errorMessage) {

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);
 });