@north-light/crouter 0.3.306 → 0.3.308

package/dist/commands/cron.js

@@ -132,7 +132,7 @@ const addLeaf = defineLeaf({
             { kind: 'stdin', name: 'command', required: true, constraint: "Arbitrary bash the daemon runs at each fire. Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes. Runs via `bash -c` in this cwd with $CRTR_CRON_ID, $CRTR_CRON_NAME, and $CRTR_RUN_ID in the env ($CRTR_ANCHOR too when anchored). The scheduler does not interpret it as a node action; a bash predicate can decide whether this fire acts, not arm a native predicate trigger. A run that must branch on canvas state should call `crtr --json <cmd>` and read the leaf's declared outputs, rather than parsing the prose output." },
             { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'Agent-legible label — how the cron shows in `cron list`.' },
             { kind: 'flag', name: 'at', type: 'string', required: false, constraint: 'One-shot: run the stored bash once at <when> — a duration ("90s","1h30m"), a zoned ISO ("2026-06-07T09:00:00Z"), or a bare ISO ("2026-06-07T09:00", interpreted in --tz else host zone). Exactly one of --at / --every is required. The row is deleted after its run unless the run\'s disposition pauses it.' },
-            { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Recurring: run the stored bash at each cadence — a fixed interval ("6h" — first fire one interval from now), a 5-field cron ("0 9 * * *"), or an @alias ("@daily"). Each fire is another bash run. Minimum cadence 60s. Exactly one of --at / --every is required. For a gated cron (a command that exits 75 while ineligible), pick a LONG cadence: each natural slot is only the backstop re-check, and the daemon poke supplies the latency — "6h" plus poke beats "15m" polling on both latency and cost.' },
+            { kind: 'flag', name: 'every', type: 'string', required: false, constraint: 'Recurring: run the stored bash at each cadence — a fixed interval ("6h" — first fire one interval from now), a 5-field cron ("0 9 * * *"), or an @alias ("@daily"). Each fire is another bash run. Minimum cadence 60s. Exactly one of --at / --every is required. Use this for a bash condition that only the local filesystem knows: if it exits 75, the next cadence re-checks it. A host platform can also re-check it early by calling the daemon\'s `POST /v1/crons/poke` endpoint.' },
             { kind: 'flag', name: 'tz', type: 'string', required: false, constraint: 'IANA zone (e.g. "America/New_York") for a bare-ISO --at or a calendar --every. Defaults to the host zone.' },
             { kind: 'flag', name: 'on-output', type: 'enum', choices: ['silent', 'on-failure', 'always', 'on-change'], required: false, constraint: 'What each run does with its output. Defaults to on-change for a node:<id> sink; otherwise on-failure. silent: record in the run log, tell nobody — never escalate. on-failure: no success delivery; a failing run pauses the cron and spawns a node to deal with it. always: deliver stdout every run to --sink at --tier. on-change: deliver stdout only when it differs from the previous run\'s — the shape polling wants.' },
             { kind: 'flag', name: 'sink', type: 'string', required: false, constraint: 'Where always/on-change stdout deliveries go: "node:<id>" (an existing node\'s inbox — must exist now; gone/finalized at fire time is a failure), "spawn:<kind>" (each delivered output creates a self-finishing node with stdout as kickoff — a managed child while its creator exists, otherwise a terminal parentless root), or "human" (the humanloop inbox). Required by always/on-change, rejected otherwise.' },
@@ -282,7 +282,7 @@ const listLeaf = defineLeaf({
         summary: 'every cron in scope, next-fire order',
         params: [],
         output: [
-            { name: 'crons', type: 'object[]', required: true, constraint: 'One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), held (true while parked by an exit-75 gate — fires on daemon poke, else at fire_at), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered — null if it never ran).' },
+            { name: 'crons', type: 'object[]', required: true, constraint: 'One row per cron: cron_id, name, fire_at (next fire, UTC), recur (cadence display), state (active|paused), held (true after an exit-75 gate; a recurring row re-checks at fire_at or when a host platform calls `POST /v1/crons/poke`, while a one-shot needs that call or `crtr cron run <cron-id>`), on_output, sink, expires_at, last_run (the most recent settled run: finished, exit_code, delivered — null if it never ran).' },
         ],
         outputKind: 'object',
         effects: ['None. Read-only.'],
@@ -325,7 +325,9 @@ const listLeaf = defineLeaf({
                     ? ' [PAUSED (held) — resume or cancel]'
                     : ' [PAUSED — resume or cancel]'
                 : c.held
-                    ? ' [HELD — last run exited 75; fires on daemon poke]'
+                    ? c.recur === 'none'
+                        ? ` [HELD — last run exited 75; run manually with \`crtr cron run ${c.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`]`
+                        : ' [HELD — last run exited 75; re-checks at the next cadence or when a host platform calls `POST /v1/crons/poke`]'
                     : '';
             return `- ${c.name} (${c.cron_id}) — ${bits.join(', ')}${marker}`;
         });
@@ -366,10 +368,10 @@ const showLeaf = defineLeaf({
         const scheduleLine = !c.held
             ? `- schedule: ${schedule}${tzPart} — next fire ${c.fire_at}`
             : c.recur !== null
-                ? `- schedule: ${schedule}${tzPart} — backstop ${c.fire_at} (held — fires early on daemon poke; last run exited 75)`
+                ? `- schedule: ${schedule}${tzPart} — next re-check ${c.fire_at} (held — also re-checks when a host platform calls \`POST /v1/crons/poke\`; last run exited 75)`
                 : c.expires_at !== null
-                    ? `- schedule: ${schedule}${tzPart} — backstop none — expires ${c.expires_at} (held — fires on daemon poke; deleted unfired at expiry)`
-                    : `- schedule: ${schedule}${tzPart} — backstop none (held — fires only on daemon poke)`;
+                    ? `- schedule: ${schedule}${tzPart} — no scheduled re-check — expires ${c.expires_at} (held — run manually with \`crtr cron run ${c.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`; deleted unfired at expiry)`
+                    : `- schedule: ${schedule}${tzPart} — no scheduled re-check (held — run manually with \`crtr cron run ${c.cron_id}\`, or wait for a host platform to call \`POST /v1/crons/poke\`)`;
         const stateTag = c.state === 'paused' ? (c.held ? ' — PAUSED (held)' : ' — PAUSED') : c.held ? ' — HELD' : '';
         const lines = [
             `# ${c.name} (${c.cron_id})${stateTag}`,
@@ -525,7 +527,7 @@ export function registerCron() {
         help: {
             name: 'cron',
             summary: 'scheduled bash commands, daemon-run',
-            model: 'A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node (its disposition defaults to on-change), an existing node\'s lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent — right when the recurrence is your polling cadence. Exit 75 and the occurrence is OWED: the row is held, fires again the moment the daemon receives an eligibility poke from the host platform, and otherwise re-checks at its next natural slot (a held one-shot instead waits for a poke until --expires deletes it unfired). Any other nonzero exit is a real failure and escalates per --on-output. Use 75 for "not yet — retry when conditions change" (a device coming online); keep gate ERRORS nonzero so a broken probe is loud instead of silently parked. Beyond the exit-code contract, cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run\'s disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it.',
+            model: 'A cron stores and daemon-runs arbitrary bash at its clock. Use ordinary bash for ordinary work; choose node:<id> for stdout as inbox information to an existing node (its disposition defaults to on-change), an existing node\'s lifecycle fresh-revive action in the bash for a clean re-check without inbox output, or spawn:<kind> to route each output-producing fire to a fresh self-finishing node (a managed child while its creator exists, otherwise a terminal parentless root). Per-fire fresh agent work belongs on the existing spawn:<kind> sink, not an independent resident-root birth. A gate is bash, at the top of the command. Exit 0 after deciding not to act and the occurrence is simply spent — right when the recurrence is your polling cadence. Exit 75 holds the row. A held recurring row re-checks at its next natural slot, or when a host platform calls the daemon\'s `POST /v1/crons/poke` endpoint. A held one-shot has no scheduled re-check: it stays held until that endpoint is called, or you execute its bash explicitly with `crtr cron run <cron-id>` (which does not unhold or reschedule the row). A local filesystem condition does not call the daemon, so use --every for that condition or run the cron explicitly after it changes. Any other nonzero exit is a real failure and escalates per --on-output. Keep gate errors nonzero so a broken probe is loud instead of silently held. Beyond the exit-code contract, cron has no native predicate-trigger semantics. --at runs once and deletes the row unless the run\'s disposition pauses it; --every runs each cadence. Output disposition (--on-output) records silently, escalates failures, or routes stdout to its --sink. Anchor a cron to delete it with a node; --cancel-on-wake instead deletes it when the anchor wakes. An unanchored recurring cron ends through --expires, explicit cancellation, or self-cancellation from its bash. Every run lands in a bounded per-cron run log (`cron show`); cwd, env, and profile are snapshotted at arm time, and --scope controls who lists and cancels it.',
         },
         children: [addLeaf, listLeaf, showLeaf, runLeaf, pauseLeaf, resumeLeaf, cancelLeaf],
     });

package/dist/core/__tests__/integration/command-plugins.test.js

@@ -153,7 +153,7 @@ process.stdin.on('end', () => {
   process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { value: request.input.thing } }));
 });
 `;
-function passthroughCommandsJson() {
+function passthroughCommandsJson(bin = 'capture') {
     return {
         schemaVersion: 1,
         mounts: [{
@@ -169,7 +169,7 @@ function passthroughCommandsJson() {
                         whenToUse: 'driving a browser through the Capture CLI',
                     },
                     summary: 'browser automation through Capture',
-                    passthrough: { bin: 'capture', installHint: 'Install @crouton-kit/capture globally.' },
+                    passthrough: { bin, installHint: 'Install @crouton-kit/capture globally.' },
                     children: [],
                 },
             }],
@@ -417,17 +417,17 @@ describe('protocol integration', () => {
         });
     }
 });
+const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'dist', 'cli.js');
 // 4b. True end-to-end CLI invocation (argv → parseArgv → adapter → renderer)
 describe('end-to-end CLI invocation', () => {
     // dist/cli.js is up 4 from src/core/__tests__/integration/. Requires a prior
     // `npm run build` (the harness/CI builds before tests). Drives the WHOLE seam: the
     // declared positional `app-id` must arrive as `appId` in the request, and
     // the rendered + --json outputs come through the real dispatcher.
-    const cli = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'dist', 'cli.js');
     const runCrtr = (args) => {
         installPlugin(userRoot, 'deploy-tools');
         resetScopeCache();
-        return execFileSync(process.execPath, [cli, ...args], {
+        return execFileSync(process.execPath, [CLI, ...args], {
             cwd: emptyStart,
             env: { ...process.env, HOME: home, CRTR_FRONT_DOOR: '' },
             encoding: 'utf8',
@@ -445,6 +445,38 @@ describe('end-to-end CLI invocation', () => {
         assert.equal(obj.status, 'running');
     });
 });
+// Passthrough paths resolve inside their plugin during discovery. Bare names are
+// deliberately left for the invoking process's PATH.
+describe('passthrough binary resolution', () => {
+    function runPassthrough(args, env = process.env) {
+        return execFileSync(process.execPath, [CLI, ...args], {
+            cwd: emptyStart,
+            env: { ...env, HOME: home, CRTR_FRONT_DOOR: '' },
+            encoding: 'utf8',
+        });
+    }
+    test('a plugin-relative bin runs the plugin program', () => {
+        const root = installPlugin(userRoot, 'passthrough-fixture', { manifest: passthroughCommandsJson('bin/passthrough.js'), executable: null });
+        const program = join(root, 'bin', 'passthrough.js');
+        writeFileSync(program, '#!/bin/sh\nprintf "plugin program: %s\\n" "$*"\n');
+        chmodSync(program, 0o755);
+        const validation = validatePluginCommands(listInstalledPluginsInRoot('user', userRoot).find((plugin) => plugin.name === 'passthrough-fixture'), RESERVED);
+        assert.equal(validation.issues.length, 0, JSON.stringify(validation.issues));
+        assert.equal(validation.contributions[0].node.passthrough?.bin, realpathSync(program));
+        assert.equal(runPassthrough(['capture', 'one', '--two']).trim(), 'plugin program: one --two');
+    });
+    test('a bare bin runs the program from PATH', () => {
+        installPlugin(userRoot, 'passthrough-fixture', { manifest: passthroughCommandsJson('capture-fixture'), executable: null });
+        const pathDir = mintDir('crtr-cmdplugin-path-');
+        const program = join(pathDir, 'capture-fixture');
+        writeFileSync(program, '#!/bin/sh\nprintf "PATH program: %s\\n" "$*"\n');
+        chmodSync(program, 0o755);
+        const validation = validatePluginCommands(listInstalledPluginsInRoot('user', userRoot).find((plugin) => plugin.name === 'passthrough-fixture'), RESERVED);
+        assert.equal(validation.issues.length, 0, JSON.stringify(validation.issues));
+        assert.equal(validation.contributions[0].node.passthrough?.bin, 'capture-fixture');
+        assert.equal(runPassthrough(['capture', 'three'], { ...process.env, PATH: `${pathDir}:${process.env['PATH'] ?? ''}` }).trim(), 'PATH program: three');
+    });
+});
 // Extensible plugin command branches — repository fragments attach to a marked
 // top-level branch as one native forest and stay entirely inside the existing
 // parser/help/exec contract.
@@ -794,6 +826,14 @@ describe('typed validation issues', () => {
         const v = validate(commandsJson(), { executable: '../../../../bin/sh' });
         assert.ok(v.issues.some((i) => i.code === 'command_path_unsafe'));
     });
+    test('passthrough path escaping the plugin root → command_path_unsafe', () => {
+        const v = validate(passthroughCommandsJson('../../../../bin/sh'), { executable: null });
+        assert.ok(v.issues.some((i) => i.code === 'command_path_unsafe'));
+    });
+    test('non-executable passthrough path → command_not_executable', () => {
+        const v = validate(passthroughCommandsJson('bin/cmd.js'), { executable: null, execBit: false });
+        assert.ok(v.issues.some((i) => i.code === 'command_not_executable'));
+    });
     test('a top-level leaf (no rootEntry) → command_node_invalid', () => {
         const m = {
             schemaVersion: 1,

package/dist/core/__tests__/integration/lifecycle-hooks.test.js

@@ -171,6 +171,11 @@ test('hooks.json v1 remains command-only while v2 accepts a lifecycle-only decla
         hooks: [],
         lifecycle: [{ event: 'node:start', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }],
     });
+    const close = validateHookManifest({
+        schemaVersion: 2,
+        lifecycle: [{ event: 'node:close', phase: 'on', op: 'cleanup', description: 'cleanup', effects: ['removes a directory'] }],
+    });
+    assert.deepEqual(close.issues, []);
     for (const manifest of [
         { schemaVersion: 2, hooks: [], lifecycle: [] },
         { schemaVersion: 2, lifecycle: [{ event: 'node:stop', phase: 'on', op: 'prepare', description: 'prepare', effects: ['creates a directory'] }] },

package/dist/core/__tests__/relaunch-root.test.js

@@ -61,7 +61,7 @@ function makeDeps(pid) {
         },
         waitForViewSocket: () => true,
         respawnViewer: () => true,
-        teardownBroker: () => { },
+        teardownBroker: async () => ({ confirmed: true }),
     };
     return { deps, launched };
 }
@@ -151,7 +151,7 @@ test('relaunchRoot at capacity refuses visibly and settles the half-born row bef
         },
         waitForViewSocket: () => true,
         respawnViewer: () => true,
-        teardownBroker: () => { },
+        teardownBroker: async () => ({ confirmed: true }),
     };
     await assert.rejects(() => relaunchRoot('root', deps), (error) => {
         const details = error.details ?? {};

package/dist/core/command-hooks/lifecycle-catalog.d.ts

@@ -1,3 +1,3 @@
-export declare const LIFECYCLE_EVENTS: readonly ["node:start"];
+export declare const LIFECYCLE_EVENTS: readonly ["node:start", "node:close"];
 export type LifecycleEvent = typeof LIFECYCLE_EVENTS[number];
 export declare function isLifecycleEvent(value: string): value is LifecycleEvent;

package/dist/core/command-hooks/lifecycle-catalog.js

@@ -1,4 +1,4 @@
-export const LIFECYCLE_EVENTS = ['node:start'];
+export const LIFECYCLE_EVENTS = ['node:start', 'node:close'];
 export function isLifecycleEvent(value) {
     return LIFECYCLE_EVENTS.includes(value);
 }

package/dist/core/command-hooks/transport/exec-lifecycle.d.ts

@@ -8,5 +8,5 @@ export interface LifecycleHookInvocation {
 }
 /** Runs one lifecycle hook. The node launch remains authoritative on every failure. */
 export declare function invokeLifecycleHook(hook: EffectiveLifecycleHook, invocation: LifecycleHookInvocation, timeoutMs: number): Promise<void>;
-/** Executes lifecycle hooks in discovery order, within one bounded start-event budget. */
+/** Executes lifecycle hooks in discovery order, within one bounded event budget. */
 export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: LifecycleHookInvocation): Promise<void>;

package/dist/core/command-hooks/transport/exec-lifecycle.js

@@ -34,7 +34,7 @@ export async function invokeLifecycleHook(hook, invocation, timeoutMs) {
         diag(`crtr: ${label(hook)} failed: ${describeError(error)}`);
     }
 }
-/** Executes lifecycle hooks in discovery order, within one bounded start-event budget. */
+/** Executes lifecycle hooks in discovery order, within one bounded event budget. */
 export async function invokeLifecycleHooks(hooks, invocation) {
     const deadline = Date.now() + LIFECYCLE_EVENT_BUDGET_MS;
     for (const hook of hooks) {

package/dist/core/command-manifests/schema.js

@@ -436,7 +436,8 @@ function validateBranch(raw, path, topLevel, transport, issue, options) {
         ...(passthrough !== undefined ? { passthrough } : {}), children: validated,
     };
 }
-/** `passthrough: { bin, installHint }` — both required non-empty strings. */
+/** `passthrough: { bin, installHint }` — `bin` is a bare PATH command or a
+ *  plugin-root-relative executable path; both fields are required non-empty strings. */
 function validatePassthrough(raw, path, issue) {
     if (!isRecord(raw)) {
         issue('command_node_invalid', 'passthrough must be an object', typeName(raw), 'an object { bin, installHint }', 'Fix or remove passthrough.', path);

package/dist/core/command-plugins/discovery.js

@@ -1,5 +1,5 @@
 import { realpathSync, readFileSync, statSync } from 'node:fs';
-import { resolve, sep } from 'node:path';
+import { isAbsolute, resolve, sep } from 'node:path';
 import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
 import { projectScopeRoots } from '../scope.js';
 import { validateCommandManifest } from '../command-manifests/manifest.js';
@@ -82,6 +82,38 @@ function validateExecExecutable(plugin, transport, manifest, issues) {
     }
     return { kind: 'exec', executable };
 }
+function namesPath(bin) {
+    return isAbsolute(bin) || bin.startsWith('.') || bin.includes('/') || bin.includes('\\');
+}
+/** Resolve plugin-owned passthrough programs during discovery. Bare program
+ * names intentionally remain untouched so spawn resolves them through PATH. */
+function resolvePassthroughBinaries(plugin, manifest, issues) {
+    let valid = true;
+    const visit = (node) => {
+        if (node.kind !== 'branch')
+            return;
+        const passthrough = node.passthrough;
+        if (passthrough !== undefined && namesPath(passthrough.bin)) {
+            const executable = safePath(plugin.root, passthrough.bin);
+            if (executable === null) {
+                issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'passthrough binary escapes the plugin root or is not a regular file', received: passthrough.bin, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix passthrough.bin in commands.json.', path: 'passthrough.bin' });
+                valid = false;
+            }
+            else if ((statSync(executable).mode & 0o111) === 0) {
+                issues.push({ code: 'command_not_executable', plugin: plugin.name, message: 'passthrough binary lacks the POSIX exec bit', received: passthrough.bin, expected: 'a file with an executable permission bit', next: 'chmod +x the plugin executable, then update commands.json.', path: 'passthrough.bin' });
+                valid = false;
+            }
+            else {
+                node.passthrough = { ...passthrough, bin: executable };
+            }
+        }
+        for (const child of node.children)
+            visit(child);
+    };
+    for (const root of manifest.roots)
+        visit(root);
+    return valid;
+}
 export function validatePluginCommands(plugin, reservedNames = new Set(), coreCommandPaths) {
     const issues = [];
     const commands = plugin.manifest.commands;
@@ -131,6 +163,9 @@ export function validatePluginCommands(plugin, reservedNames = new Set(), coreCo
         : transport;
     if (resolvedTransport === undefined)
         return { plugin, manifestPath, transport, contributions: [], issues };
+    if (resolvedTransport.kind === 'exec' && !resolvePassthroughBinaries(plugin, validation.manifest, issues)) {
+        return { plugin, manifestPath, transport: resolvedTransport, contributions: [], issues };
+    }
     const roots = validation.manifest.roots;
     if (!roots.every((node) => node.kind === 'branch')) {
         throw new Error('plugin manifest validation returned a top-level leaf');

package/dist/core/command.d.ts

@@ -82,7 +82,8 @@ export interface BranchDef {
     /** Opt this branch out of the tree model entirely: every token after this
      *  branch's name is forwarded VERBATIM (raw argv, not the `--json`-filtered
      *  tokens) to an external binary via spawn, with stdio inherited and the
-     *  child's exit code propagated. A deliberate, documented exception for
+     *  child's exit code propagated. Plugin-owned paths have already resolved to
+     *  absolute executable paths; bare program names resolve through PATH. A deliberate, documented exception for
      *  wrapping an external CLI whose own schema crtr cannot and must not
      *  duplicate (the official marketplace's `capture` plugin mounts `crtr
      *  capture` this way) — not a general escape hatch. A

package/dist/core/human/component-docs.js

@@ -9,6 +9,7 @@ const SLOT_RULES = `Component contract
 - \`id\` is required, must match \`^[A-Za-z0-9_-]{1,64}$\`, and must be unique across the page.
 - When a page has two or more response-bearing components, every one needs a nonempty \`label\`.
 - Config objects and every documented nested object reject unknown fields.
+- A quoted JSX attribute does not interpret escape sequences, so \`body="one.\\n\\ntwo."\` reaches the reader as one run-on paragraph with a literal backslash-n in the middle of it. Write any markdown body that has a line or paragraph break as a braced string — \`body={"one.\\n\\ntwo."}\` — where the escape is real.
 - The page is rendered once at submit to build the ticket manifest, so every prop reaches it whatever its shape — mapped data, a helper component, a value from \`useState\`. Event handlers are dropped, because a manifest is JSON. The user's answer lands in \`response.json\` keyed by this \`id\`.`;
 const COMMENT_SHAPE = `Comments are \`{id:string (nonempty), text:string, anchor:Anchor}\` and qualify the answer itself. \`Anchor\` is \`{kind:"option",optionId:string}\` or \`{kind:"row",rowId:string}\`; each component accepts only the anchors named next. The reader writes one against a specific option or row in whatever host they read in — in the terminal inbox, \`c\` on the selected one — so every option and row needs a label that reads on its own. Feedback on the page's own prose is a separate channel, offered only by hosts that render the page, and never part of a response.`;
 const DISPLAY_RULES = `Display-only: it is not recorded in the page manifest and contributes nothing to the response. Every display component also takes \`className\` for Tailwind utilities, and standard shadcn props otherwise.`;
@@ -92,7 +93,8 @@ Response rules
 
 Example
 \`\`\`jsx
-<UserQuestion id="lane" label="Release lane" body="The audit closes tomorrow." mode="single" allowFreetext
+<UserQuestion id="lane" label="Release lane" mode="single" allowFreetext
+  body={"The audit closes tomorrow.\\n\\nBoth release gates are green as of this morning."}
   freetextLabel="Something else"
   options={[
     { id: 'now', label: 'Ship now', description: 'Both gates are green.', recommended: true },

package/dist/core/runtime/close.d.ts

@@ -33,4 +33,6 @@ export interface CloseNodeResult {
 export declare function closeNode(rootId: string, opts?: {
     rootEvent?: 'cancel' | 'finish';
     callerPid?: number;
+    /** Daemon-owned close work that must drain before this daemon exits. */
+    registerDetached?: (work: Promise<void>) => void;
 }): CloseNodeResult;

package/dist/core/runtime/close.js

@@ -36,6 +36,10 @@ import { cancelCronsOnWake, getNode, subscriptionsOf, subscribersOf, } from '../
 import { transition } from './lifecycle.js';
 import { requestBrokerTeardown } from './host.js';
 import { tearDownNode, reapIfEmpty } from './placement.js';
+import { crtrHome, contextDir, jobDir, nodeDir, reportsDir } from '../canvas/paths.js';
+import { discoverLifecycleHookRegistry } from '../command-hooks/discovery.js';
+import { invokeLifecycleHooks } from '../command-hooks/transport/exec-lifecycle.js';
+import { emitEvent } from '../events/emit.js';
 import { appendInbox } from '../feed/inbox.js';
 import { appendPassive } from '../feed/passive.js';
 /** Fan a lifecycle or birth notice to every given subscriber. Active subscribers
@@ -173,12 +177,50 @@ export function closeNode(rootId, opts = {}) {
             // Surviving managers captured BEFORE any teardown — a reap (below) deletes
             //    this node's edges, so the step-4 fan-out must read them up front.
             const survivors = subscribersOf(id).filter((s) => !closing.has(s.node_id));
+            // Capture the target-scoped hook plan and payload before an empty node's
+            // reap can remove its row and directories. The executable still runs from
+            // its plugin root; the payload paths can therefore name a reaped directory.
+            let afterTeardown;
+            try {
+                const hooks = discoverLifecycleHookRegistry(m.cwd, m.profile_id).plans.get('node:close') ?? [];
+                if (hooks.length > 0) {
+                    const invocation = {
+                        node: {
+                            id,
+                            name: m.name,
+                            kind: m.kind,
+                            mode: m.mode,
+                            lifecycle: m.lifecycle,
+                            cwd: m.cwd,
+                            nodeDir: nodeDir(id),
+                            contextDir: contextDir(id),
+                            jobDir: jobDir(id),
+                            reportsDir: reportsDir(id),
+                        },
+                        runtime: { isBirth: false, canvasHome: crtrHome(), profile: m.profile_id ?? null },
+                    };
+                    afterTeardown = () => invokeLifecycleHooks(hooks, invocation);
+                }
+            }
+            catch (error) {
+                emitEvent({ level: 'error', event: 'node.close_hook.discovery_failed', node_id: id, error });
+            }
+            // Capture the process snapshot while the row exists, then execute after
+            // the response settles. A failed teardown skips the lifecycle hook rather
+            // than claiming cleanup was safe.
+            const teardown = requestBrokerTeardown(id, id === rootId ? { excludePid: opts.callerPid } : {}, afterTeardown);
+            try {
+                opts.registerDetached?.(teardown.then(() => { }));
+            }
+            catch (error) {
+                emitEvent({ level: 'error', event: 'node.close_hook.detached_registration_failed', node_id: id, error });
+            }
             // 0) A node with no substantive assistant output is a useless shell — don't
             //    park it as a canceled husk; reap it outright (engine + viewer + row +
-            //    dir). reapIfEmpty handles the teardown; when it fires we
-            //    skip the cancel transition + resume notice (the node is gone) but still
-            //    fan the "child gone" wake out to surviving managers below.
-            if (!reapIfEmpty(id)) {
+            //    dir). Its teardown was queued above from the preserved snapshot; when
+            //    reaping fires we skip the cancel transition + resume notice (the node
+            //    is gone) but still fan the "child gone" wake out to survivors below.
+            if (!reapIfEmpty(id, undefined, false)) {
                 // 1) Terminal status set BEFORE the window dies (daemon race). The root may
                 //    finish to `done` (a deliberate "mark complete" close-out); every
                 //    descendant, and the root by default, `cancel`s. finish is legal only
@@ -199,9 +241,9 @@ export function closeNode(rootId, opts = {}) {
                 else {
                     transition(id, 'cancel', { reason: 'closed' });
                 }
-                // 2) Ask the daemon to tear the engine down after this close response
-                //    settles. The root caller's shell is excluded from its own broker tree.
-                requestBrokerTeardown(id, id === rootId ? { excludePid: opts.callerPid } : {});
+                // 2) The daemon-owned teardown was queued above after capturing this
+                //    node's process tree. The root caller's shell was excluded from its
+                //    own broker tree before the response can settle.
                 tearDownNode(id);
                 // 3) Leave the resume notice AFTER the watcher is gone, so it survives.
                 appendInbox(id, {
@@ -226,8 +268,8 @@ export function closeNode(rootId, opts = {}) {
             fanDoctrineWake(id, survivors, `Child closed — ${m.name} (${id}) was closed from the canvas and is no longer running.`, { reason: 'child-closed', child: id });
             closed.push(id);
         }
-        catch {
-            /* one bad node never aborts the cascade */
+        catch (error) {
+            emitEvent({ level: 'error', event: 'node.close.failed', node_id: id, error });
         }
     }
     return { root: rootId, closed, spared };

package/dist/core/runtime/host.d.ts

@@ -25,6 +25,13 @@ export interface HostHandle {
 export interface TeardownOptions {
     excludePid?: number;
 }
+/** The only completion signal a caller may use for post-teardown work. A false
+ * result means the original engine tree could not be confirmed dead, so no
+ * cleanup may claim it was safe to remove resources it owned. */
+export interface TeardownResult {
+    confirmed: boolean;
+    error?: Error;
+}
 export interface Host {
     /** Bring a node's ENGINE into existence from its launch recipe; return a
      *  supervisable handle. */
@@ -33,8 +40,9 @@ export interface Host {
      *  both call sites — the revive guard (passes the id) and the daemon (passes a
      *  row) — share one selector. For the broker this IS isPidAlive(pi_pid). */
     isAlive(node: string | NodeRow): boolean;
-    /** Tear the engine down (close/cancel teardown). */
-    teardown(nodeId: string, opts?: TeardownOptions): void;
+    /** Tear the engine down (close/cancel teardown). Resolves only after the
+     * fixed process snapshot is confirmed dead, or with a diagnostic failure. */
+    teardown(nodeId: string, opts?: TeardownOptions): Promise<TeardownResult>;
     /** Deliver an OS signal to the engine container — present so the daemon never
      *  reaches around the abstraction. */
     signal(nodeId: string, sig: NodeJS.Signals): void;
@@ -43,7 +51,7 @@ export interface Host {
  *  the fast-fail seam for known module/path errors: a bad engine resolve or a
  *  missing plain session path throws here, before spawn(). */
 export declare function preflightBrokerLaunch(nodeId: string, inv: PiInvocation, cwd: string): void;
-/** Queue broker teardown onto the daemon event loop after the close response can
- * settle. Repeated terminal reconciliation coalesces on the same node. */
-export declare function requestBrokerTeardown(nodeId: string, opts?: TeardownOptions): void;
+/** Queue broker teardown after the close response settles. Completion includes
+ * any post-teardown work, which lets the daemon drain it during shutdown. */
+export declare function requestBrokerTeardown(nodeId: string, opts?: TeardownOptions, after?: () => Promise<void>): Promise<TeardownResult>;
 export declare const headlessBrokerHost: Host;