@north-light/crouter 0.3.305 → 0.3.307

package/dist/api/plugin-manifest-schema.d.ts

@@ -103,7 +103,8 @@ export interface ManifestTimeouts {
     streamIdleMs?: number;
 }
 /** Exec transport only: forward every argv token after this branch to an
- *  external binary instead of parsing children. A passthrough branch is
+ *  external binary instead of parsing children. `bin` is either a bare PATH
+ *  command or a plugin-root-relative executable path. A passthrough branch is
  *  childless by construction; an HTTP manifest rejects it, because an HTTP
  *  transport must not name a local binary to execute. */
 export interface ManifestPassthrough {

package/dist/builtin-memory/internal/plugins.md

@@ -266,7 +266,7 @@ An HTTP-transport plugin replaces that declaration with:
 "transport": { "kind": "http", "endpoint": "https://example.com", "authEnv": "DEPLOY_TOKEN" }
 ```
 
-For `exec`, `executable` is required when the manifest has any executable leaf; a passthrough-only manifest omits it. When declared, it is plugin-root-relative, resolves inside the plugin root to a regular file, and carries the POSIX exec bit. For `http`, `transport.endpoint` is the backend origin and `authEnv` is optional. crouter stores only the environment variable **name**, never its credential; it reads the credential when invoking a leaf. A crouter-materialized archive plugin additionally records its archive URL separately in `bundle` for installation and update.
+For `exec`, `executable` is required when the manifest has any executable leaf; a passthrough-only manifest omits it. When declared, it is plugin-root-relative, resolves inside the plugin root to a regular file, and carries the POSIX exec bit. A passthrough `bin` is either a bare command resolved through `PATH` or a plugin-root-relative executable path subject to the same containment and permission checks. For `http`, `transport.endpoint` is the backend origin and `authEnv` is optional. crouter stores only the environment variable **name**, never its credential; it reads the credential when invoking a leaf. A crouter-materialized archive plugin additionally records its archive URL separately in `bundle` for installation and update.
 
 Only an installed, **enabled** plugin's command manifest contributes. Discovery is per-invocation and reads the installed `commands.json` only: enable, disable, update, and remove take effect on the next `crtr` call with no daemon restart, cache clearing, or network fetch.
 

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/git-optional-locks.test.d.ts

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

package/dist/core/__tests__/integration/git-optional-locks.test.js

@@ -0,0 +1,81 @@
+// Run with: npm run test:integration
+//
+// Regression: crouter's read-only git calls must not take `.git/index.lock`.
+//
+// `git status` refreshes the index stat cache and writes the index back, which
+// means creating `.git/index.lock` and renaming it over `.git/index`. A process
+// killed between those two steps orphans the lock, and it then blocks every
+// later writer in that checkout with no owning process left to name. Agent
+// processes are killed mid-command routinely — a closed node, a cancelled daemon
+// tick, a timed-out shell — so the residue accumulates in a shared checkout
+// until someone removes it by hand.
+//
+// `GIT_OPTIONAL_LOCKS=0` suppresses exactly that optional lock. These tests pin
+// the two paths that reach git: the shared spawner in `core/git.ts`, and the
+// bearings project-context block, which renders on every node boot and revive
+// and is therefore the most frequent git caller in the runtime.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { gitSync } from '../../git.js';
+import { buildProjectContextBlock } from '../../runtime/bearings-render.js';
+/** A repo with one committed file whose stat cache is deliberately stale, so a
+ *  status that refreshes the index has a reason to write it back. Without the
+ *  stale stat there is nothing to refresh and the assertion passes vacuously. */
+function repoWithStaleStatCache() {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-git-locks-'));
+    const git = (args) => {
+        const result = spawnSync('git', args, { cwd: dir, encoding: 'utf8' });
+        assert.equal(result.status, 0, `git ${args.join(' ')}: ${result.stderr}`);
+    };
+    writeFileSync(join(dir, 'f.txt'), 'a\n', 'utf8');
+    git(['init', '-q', '.']);
+    git(['-c', 'user.email=t@t', '-c', 'user.name=t', 'add', 'f.txt']);
+    git(['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'init']);
+    // Move the file's mtime forward so git's cached stat no longer matches.
+    const future = new Date(Date.now() + 10_000);
+    utimesSync(join(dir, 'f.txt'), future, future);
+    return dir;
+}
+function indexMtime(dir) {
+    return statSync(join(dir, '.git', 'index')).mtimeMs;
+}
+test('gitSync status does not rewrite the index', (t) => {
+    if (spawnSync('git', ['--version']).status !== 0) {
+        t.skip('git is unavailable');
+        return;
+    }
+    const dir = repoWithStaleStatCache();
+    try {
+        const before = indexMtime(dir);
+        const result = gitSync(['status', '--porcelain'], dir);
+        assert.equal(result.status, 0, result.stderr);
+        // Suppressing the lock must not change what the command reports.
+        assert.equal(result.stdout, '');
+        assert.equal(indexMtime(dir), before, 'status took .git/index.lock and rewrote the index');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('the bearings project-context block does not rewrite the index', (t) => {
+    if (spawnSync('git', ['--version']).status !== 0) {
+        t.skip('git is unavailable');
+        return;
+    }
+    const dir = repoWithStaleStatCache();
+    try {
+        const before = indexMtime(dir);
+        const block = buildProjectContextBlock(dir);
+        // The snapshot still reports real git state; it just does not lock to do it.
+        assert.match(block, /Git: /);
+        assert.match(block, /clean/);
+        assert.equal(indexMtime(dir), before, 'the bearings snapshot took .git/index.lock');
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

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/git.js

@@ -1,7 +1,21 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { network } from './errors.js';
+/** Git takes `.git/index.lock` to refresh the index stat cache even during
+ *  otherwise read-only commands — `status` is the common one. Killed between
+ *  creating that lock and renaming it over the index, the lock orphans and
+ *  blocks every later writer in the checkout with no owning process left to
+ *  name. Agent processes are killed mid-command routinely (a closed node, a
+ *  cancelled daemon tick, a timed-out shell), so the residue accumulates.
+ *
+ *  `GIT_OPTIONAL_LOCKS=0` suppresses exactly those optional locks and nothing
+ *  else: a commit, rebase, or `add` still takes the lock it requires, and
+ *  command output is byte-identical. Built per call rather than snapshotted at
+ *  module load, so a later change to the ambient environment still reaches git. */
+function gitEnv(base = process.env) {
+    return { ...base, GIT_OPTIONAL_LOCKS: '0' };
+}
 export function gitSync(args, cwd, input, options = {}) {
-    const res = spawnSync('git', args, { cwd, encoding: 'utf8', input, timeout: options.timeoutMs });
+    const res = spawnSync('git', args, { cwd, encoding: 'utf8', input, env: gitEnv(), timeout: options.timeoutMs });
     const status = typeof res.status === 'number' ? res.status : 1;
     const completed = typeof res.status === 'number';
     const stdout = typeof res.stdout === 'string' ? res.stdout : '';
@@ -12,7 +26,7 @@ export function gitSync(args, cwd, input, options = {}) {
 }
 export async function gitAsync(args, cwd, input, options = {}) {
     return new Promise((resolve) => {
-        const child = spawn('git', args, { cwd, ...(options.env === undefined ? {} : { env: options.env }) });
+        const child = spawn('git', args, { cwd, env: gitEnv(options.env) });
         if (input === undefined)
             child.stdin.end();
         else

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/bearings-render.js

@@ -57,8 +57,8 @@ function directoryListingLines(cwd) {
         return ['Directory listing: unavailable (cwd missing or unreadable).'];
     }
 }
-function runCommand(cwd, cmd, args) {
-    const result = spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+function runCommand(cwd, cmd, args, env) {
+    const result = spawnSync(cmd, args, { cwd, encoding: 'utf8', ...(env === undefined ? {} : { env }) });
     if (result.error !== undefined) {
         return { ok: false, stdout: '', stderr: result.error.message };
     }
@@ -68,8 +68,17 @@ function runCommand(cwd, cmd, args) {
         stderr: (result.stderr ?? '').trim(),
     };
 }
+/** This snapshot renders on every node boot and every revive, which makes it the
+ *  most frequent git caller in the runtime — and boot is exactly when a process
+ *  gets killed. `git status` would take `.git/index.lock` to refresh the stat
+ *  cache; suppressing that optional lock keeps an interrupted render from
+ *  orphaning a lock that then blocks every writer in the user's checkout.
+ *  Only optional locks are affected, and the output is unchanged. */
+function gitEnv() {
+    return { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+}
 function runGit(cwd, args) {
-    const result = runCommand(cwd, 'git', args);
+    const result = runCommand(cwd, 'git', args, gitEnv());
     return result.ok ? result.stdout : '';
 }
 function parseWorktrees(lines) {
@@ -98,7 +107,7 @@ function parseWorktrees(lines) {
  *  benign state. Every other probe here is genuinely optional and already
  *  falls back to 'unknown'/'HEAD'/a zero count on failure, which stays as-is. */
 function gitSnapshotLines(cwd) {
-    const probe = runCommand(cwd, 'git', ['rev-parse', '--is-inside-work-tree']);
+    const probe = runCommand(cwd, 'git', ['rev-parse', '--is-inside-work-tree'], gitEnv());
     if (!probe.ok) {
         if (/not a git repository/i.test(probe.stderr)) {
             return ['Git: not a git repository.'];

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;

package/dist/core/runtime/host.js

@@ -128,84 +128,153 @@ const BROKER_SIGKILL_GRACE_MS = 2_000;
  *  full grace ceilings above are reserved for the genuinely-wedged case,
  *  where the added latency is the whole point. */
 const TEARDOWN_POLL_MS = 150;
-/** Poll `isAlive` every `TEARDOWN_POLL_MS` until it reports dead. If it is
- *  STILL alive once `timeoutMs` elapses, fire `onTimeout` exactly once (the
- *  next escalation rung) and keep polling so the caller can confirm that
- *  rung actually worked — up to `hardCeilingMs` total, after which this gives
- *  up (an unkillable/D-state descendant is out of scope for this primitive).
- *
- *  Deliberately a recursive, NEVER-`.unref()`'d `setTimeout` rather than a
- *  fixed unref'd wait: most teardown callers
- *  are short-lived CLI subprocesses (`node lifecycle close`, `canvas prune`)
- *  that would otherwise exit before an unref'd SIGKILL timer ever fires,
- *  silently skipping the last-resort rung. Polling (instead of a blind fixed
- *  wait) is what keeps the happy path cheap despite being ref'd. */
-function pollUntil(isAlive, timeoutMs, onTimeout, hardCeilingMs = timeoutMs + 5_000) {
-    const start = Date.now();
-    let escalated = false;
-    const tick = () => {
-        if (!isAlive())
-            return; // confirmed dead — stop polling
-        const elapsed = Date.now() - start;
-        if (!escalated && elapsed >= timeoutMs) {
-            escalated = true;
-            onTimeout();
-        }
-        if (elapsed >= hardCeilingMs)
-            return; // best-effort exhausted — give up
-        setTimeout(tick, TEARDOWN_POLL_MS);
-    };
-    tick();
+/** Wait against the fixed snapshot. The ref'd timer keeps a short-lived
+ * caller alive through the final SIGKILL confirmation. */
+async function waitForTreeExit(tree, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (isAnyPidAlive(tree)) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, Math.min(TEARDOWN_POLL_MS, remaining)));
+    }
+    return true;
 }
-/** Escalate teardown of a broker/tree that did not exit cleanly off the
- *  graceful `shutdown` frame (or was never reachable at all): SIGTERM the
- *  whole tree, then — once `BROKER_SIGKILL_GRACE_MS` has elapsed with the tree
- *  still alive — SIGKILL the whole tree as the last resort.
- *
- *  Takes an ALREADY-CAPTURED `tree` (pid list) and `identities` (a
- *  `captureTeardownSnapshot` identity map over that same list) — both taken
- *  ONCE by `teardown()` synchronously at its very top, before EITHER
- *  escalation path (connect-error or post-shutdown-frame) can run, and
- *  threaded through here unchanged. This
- *  function must NEVER re-walk the process tree itself: `launch()` spawns the
- *  broker `detached: true`, so
- *  signaling the broker's OWN group (the first thing `killProcessTreePids`
- *  does) typically kills the broker itself almost immediately — and the
- *  kernel reparents any surviving child away from the broker's pid the
- *  INSTANT the broker exits, severing the very ppid link a fresh
- *  `descendantPids` walk depends on. Re-deriving descendants at ANY point
- *  after the broker may have exited (including a per-rung re-walk here, or a
- *  poll that re-derives instead of checking this fixed list) would silently
- *  "lose" a still-alive detached descendant — e.g. the pi bash tool's shell
- *  child, itself `detached: true` and thus its own group leader, distinct
- *  from the broker's group, so a plain `kill(-brokerPid)` never reaches it
- *  either. `identities` guards each signal against
- *  PID REUSE across the multi-second escalation window —
- *  see `killProcessTreePids`. `null` means the initial `captureTeardownSnapshot`
- *  probe itself failed (no baseline to compare against) — `killProcessTreePids`
- *  falls through to its normal unguarded signal path in that case, never
- *  reading a probe failure as proof the pid is gone or reused. */
-function escalateBrokerTeardown(tree, identities) {
+/** Finish one teardown using the snapshot captured before any signal can sever
+ * broker parentage. A failed confirmation is explicit so post-teardown cleanup
+ * never runs against an engine tree that may still own its resources. */
+async function terminateBrokerTree(tree, identities, graceful) {
+    if (tree.length === 0)
+        return { confirmed: true };
+    if (graceful && await waitForTreeExit(tree, BROKER_SHUTDOWN_GRACE_MS))
+        return { confirmed: true };
     killProcessTreePids(tree, 'SIGTERM', identities);
-    pollUntil(() => isAnyPidAlive(tree), BROKER_SIGKILL_GRACE_MS, () => killProcessTreePids(tree, 'SIGKILL', identities));
+    if (await waitForTreeExit(tree, BROKER_SIGKILL_GRACE_MS))
+        return { confirmed: true };
+    killProcessTreePids(tree, 'SIGKILL', identities);
+    if (await waitForTreeExit(tree, 5_000))
+        return { confirmed: true };
+    return { confirmed: false, error: new Error(`broker process tree for ${tree.join(', ')} remained alive after SIGKILL`) };
+}
+/** Capture the one authoritative process snapshot before a caller can reap the
+ * node row. No signal or socket operation occurs here; execution remains queued
+ * until the close response has settled. */
+function prepareBrokerTeardown(nodeId, opts) {
+    const node = getNode(nodeId);
+    const pid = node?.pi_pid;
+    const snapshot = pid != null
+        ? captureTeardownSnapshot(pid, node?.pi_pid_identity ?? null, opts.excludePid)
+        : null;
+    if (snapshot?.reused === true) {
+        emitEvent({
+            level: 'warn',
+            event: 'broker.teardown.pid_reuse_refused',
+            node_id: nodeId,
+            fields: { recorded_pid: pid, expected_identity: node?.pi_pid_identity ?? null },
+        });
+    }
+    return {
+        tree: snapshot?.tree ?? [],
+        identities: snapshot?.identities ?? null,
+        sockPath: viewSocketPath(nodeId),
+    };
+}
+async function runPreparedBrokerTeardown(prepared) {
+    // Even a dead broker pid can still be the process-group leader for an orphan
+    // that the initial ppid walk could no longer reach. The connect-failure path
+    // must retain that leader id for group signaling rather than treating its dead
+    // status as confirmation that no descendant survives.
+    return new Promise((resolve) => {
+        let connected = false;
+        let settled = false;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const cleanupSocket = () => {
+            try {
+                if (existsSync(prepared.sockPath))
+                    unlinkSync(prepared.sockPath);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        };
+        const finish = (graceful) => {
+            void terminateBrokerTree(prepared.tree, prepared.identities, graceful).then(settle, (error) => settle({ confirmed: false, error: error instanceof Error ? error : new Error(String(error)) }));
+        };
+        const sock = connect(prepared.sockPath);
+        sock.once('error', () => {
+            if (connected)
+                return;
+            cleanupSocket();
+            finish(false);
+        });
+        sock.once('connect', () => {
+            connected = true;
+            try {
+                sock.write(encodeFrame({ type: 'shutdown' }));
+            }
+            catch {
+                /* the broker may have raced us to exit */
+            }
+            sock.end();
+            cleanupSocket();
+            finish(true);
+        });
+    });
 }
 const requestedTeardowns = new Map();
-/** Queue broker teardown onto the daemon event loop after the close response can
- * settle. Repeated terminal reconciliation coalesces on the same node. */
-export function requestBrokerTeardown(nodeId, opts = {}) {
+/** Queue broker teardown after the close response settles. Completion includes
+ * any post-teardown work, which lets the daemon drain it during shutdown. */
+export function requestBrokerTeardown(nodeId, opts = {}, after) {
     const existing = requestedTeardowns.get(nodeId);
     if (existing !== undefined) {
-        if (existing.excludePid === undefined && opts.excludePid !== undefined)
-            existing.excludePid = opts.excludePid;
-        return;
+        if (after !== undefined)
+            existing.after.push(after);
+        return existing.completion;
+    }
+    let resolve;
+    const completion = new Promise((done) => { resolve = done; });
+    const request = { completion, resolve, after: after === undefined ? [] : [after] };
+    requestedTeardowns.set(nodeId, request);
+    let prepared;
+    try {
+        prepared = prepareBrokerTeardown(nodeId, opts);
+    }
+    catch (error) {
+        const failure = { confirmed: false, error: error instanceof Error ? error : new Error(String(error)) };
+        requestedTeardowns.delete(nodeId);
+        emitEvent({ level: 'error', event: 'broker.teardown.unconfirmed', node_id: nodeId, error: failure.error });
+        request.resolve(failure);
+        return completion;
     }
-    requestedTeardowns.set(nodeId, { ...opts });
     setImmediate(() => {
-        const request = requestedTeardowns.get(nodeId);
         requestedTeardowns.delete(nodeId);
-        if (request !== undefined)
-            headlessBrokerHost.teardown(nodeId, request);
+        void runPreparedBrokerTeardown(prepared).then(async (result) => {
+            if (result.confirmed) {
+                for (const callback of request.after) {
+                    try {
+                        await callback();
+                    }
+                    catch (error) {
+                        emitEvent({ level: 'error', event: 'broker.teardown.after_failed', node_id: nodeId, error });
+                    }
+                }
+            }
+            else {
+                emitEvent({ level: 'error', event: 'broker.teardown.unconfirmed', node_id: nodeId, error: result.error });
+            }
+            request.resolve(result);
+        }, (error) => {
+            const failure = { confirmed: false, error: error instanceof Error ? error : new Error(String(error)) };
+            emitEvent({ level: 'error', event: 'broker.teardown.unconfirmed', node_id: nodeId, error: failure.error });
+            request.resolve(failure);
+        });
     });
+    return completion;
 }
 export const headlessBrokerHost = {
     launch(nodeId, inv, opts) {
@@ -364,117 +433,15 @@ export const headlessBrokerHost = {
         return isPidAlive((typeof node === 'string' ? getNode(node) : node)?.pi_pid);
     },
     teardown(nodeId, opts = {}) {
-        // Graceful: connect to view.sock + send a `shutdown` frame → the broker
-        // dispose()s the engine, unlinks the socket, exits 0. Status is already
-        // flipped done/canceled by the caller (crash-safe ordering), so the daemon
-        // won't revive. On connect failure (broker dead/crashed/wedged) fall back
-        // to escalateBrokerTeardown — a tree-wide SIGTERM now, a tree-wide SIGKILL
-        // as the last resort — so no orphaned descendant of a dead/wedged broker
-        // survives the node — + unlink the stale socket.
-        //
-        // Capture the broker pid ONCE, synchronously, right here — never re-query
-        // `getNode(nodeId)` inside the async callbacks/timers below. Callers such
-        // as placement.ts's `reapIfEmpty()` call `teardown()` then immediately
-        // `deleteNode()` in the same tick; by the time an async callback fires the
-        // row can already be gone, so a re-query would silently resolve to
-        // `undefined` and skip escalation entirely.
-        const node = getNode(nodeId);
-        const pid = node?.pi_pid;
-        // Snapshot the full descendant TREE — the
-        // root pid plus every transitive descendant — and a stable identity
-        // fingerprint for every pid in it, BOTH from ONE `ps`
-        // table read (`captureTeardownSnapshot`, final review: closes the small
-        // race between two separate probes), exactly ONCE, right here, while the
-        // broker (if alive) still holds parentage over any detached descendant.
-        // EVERY escalation path below — connect-error AND post-shutdown-frame —
-        // reuses this ONE fixed snapshot; neither may re-walk `ps` by ppid once
-        // the broker might have exited, because the kernel reparents any
-        // surviving child away from `pid` the INSTANT the broker exits, severing
-        // the ppid link a fresh walk depends on — exactly the reparenting hazard
-        // this fix closes. (If the broker is ALREADY dead when `teardown()`
-        // starts, its detached descendants were already reparented before we ever
-        // got here — unrecoverable by ppid, and out of scope: the #98 repro is
-        // the wedged-but-ALIVE broker, which this covers.)
-        //
-        // `node?.pi_pid_identity` is the LAUNCH-time baseline `recordPid` captured
-        // the instant this broker was spawned/bound (final review, Fix 1): if
-        // `pid` has ALREADY been recycled for an unrelated process before
-        // teardown ever ran — the pid-reuse hazard this guard exists for — the
-        // snapshot's `reused: true` comes back with an EMPTY tree, so nothing
-        // below ever signals the stranger (or walks its process tree looking for
-        // "descendants", which would be the stranger's children, not ours).
-        const snapshot = pid != null ? captureTeardownSnapshot(pid, node?.pi_pid_identity ?? null, opts.excludePid) : null;
-        if (snapshot?.reused === true) {
-            emitEvent({
-                level: 'warn',
-                event: 'broker.teardown.pid_reuse_refused',
-                node_id: nodeId,
-                fields: {
-                    recorded_pid: pid,
-                    expected_identity: node?.pi_pid_identity ?? null,
-                },
+        try {
+            return runPreparedBrokerTeardown(prepareBrokerTeardown(nodeId, opts));
+        }
+        catch (error) {
+            return Promise.resolve({
+                confirmed: false,
+                error: error instanceof Error ? error : new Error(String(error)),
             });
         }
-        const tree = snapshot?.tree ?? [];
-        const identities = snapshot?.identities ?? null;
-        const sockPath = viewSocketPath(nodeId);
-        const cleanupSocket = () => {
-            try {
-                if (existsSync(sockPath))
-                    unlinkSync(sockPath);
-            }
-            catch {
-                /* best-effort cleanup */
-            }
-        };
-        const sock = connect(sockPath);
-        let connected = false;
-        sock.on('error', () => {
-            // A post-connect error (broker exiting after we sent shutdown) is benign
-            // and swallowed; only a connect failure triggers the escalation fallback.
-            if (connected)
-                return;
-            if (tree.length > 0)
-                escalateBrokerTeardown(tree, identities);
-            cleanupSocket();
-        });
-        sock.once('connect', () => {
-            connected = true;
-            try {
-                sock.write(encodeFrame({ type: 'shutdown' }));
-            }
-            catch {
-                /* the broker may have raced us to exit */
-            }
-            sock.end();
-            cleanupSocket();
-            // Bounded exit confirmation: a broker that connects fine but then HANGS
-            // inside session.dispose() (disposeAndExit catches a throw, not a hang)
-            // would leak the process holding the sole .jsonl writer — and any
-            // bash→test→app descendants it spawned along the way. Poll
-            // the whole process TREE (not just the broker's own pid) for up to
-            // `BROKER_SHUTDOWN_GRACE_MS`, UNCONDITIONAL on the broker's own liveness:
-            // a broker that exits cleanly can still
-            // leave a live descendant behind (dispose() partially failed, or never
-            // reached a detached SDK child), which is exactly the shape this
-            // closes. `pollUntil` is ref'd — not `.unref()`'d — so a short-lived
-            // CLI caller stays alive long enough for the SIGKILL rung to actually
-            // fire, while the happy path (tree already dead) still pays only a
-            // couple of poll ticks.
-            //
-            // Checks `isAnyPidAlive(tree)` against the FIXED pre-signal snapshot,
-            // NEVER a fresh `isProcessTreeAlive`/`descendantPids` re-walk: the broker
-            // can exit at any point during this
-            // grace window while leaving a detached descendant alive, and the
-            // instant it does, the kernel reparents that descendant away from `pid`
-            // — a re-walk-by-ppid would then find nothing and silently skip
-            // escalation, even though the descendant is still very much alive. The
-            // fixed `tree` snapshot (taken before the shutdown frame was even sent)
-            // has no such blind spot.
-            if (tree.length > 0) {
-                pollUntil(() => isAnyPidAlive(tree), BROKER_SHUTDOWN_GRACE_MS, () => escalateBrokerTeardown(tree, identities));
-            }
-        });
     },
     signal(nodeId, sig) {
         const pid = getNode(nodeId)?.pi_pid;

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

@@ -86,7 +86,7 @@ export declare function detachToBackground(nodeId: string, pane?: string): boole
  *  its node identity so the worktree remains owned and can later be closed.
  *  Returns true when it reaped. No-op (false) on a node that produced output,
  *  is mid-first-turn, owns an open managed worktree, or no longer exists. */
-export declare function reapIfEmpty(nodeId: string, keepPane?: string): boolean;
+export declare function reapIfEmpty(nodeId: string, keepPane?: string, teardown?: boolean): boolean;
 /** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
  *  behind `crtr canvas prune --empty`, for the husks that accumulated before
  *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), dead rows,

package/dist/core/runtime/placement.js

@@ -342,11 +342,12 @@ function isEmptyNode(nodeId) {
  *  its node identity so the worktree remains owned and can later be closed.
  *  Returns true when it reaped. No-op (false) on a node that produced output,
  *  is mid-first-turn, owns an open managed worktree, or no longer exists. */
-export function reapIfEmpty(nodeId, keepPane) {
+export function reapIfEmpty(nodeId, keepPane, teardown = true) {
     const meta = getNode(nodeId);
     if (meta?.managed_worktree?.state === 'open' || !isEmptyNode(nodeId))
         return false;
-    headlessBrokerHost.teardown(nodeId);
+    if (teardown)
+        void headlessBrokerHost.teardown(nodeId);
     tearDownNode(nodeId, keepPane);
     return deleteNode(nodeId).deleted;
 }

package/dist/daemon/api/handlers/nodes.js

@@ -47,6 +47,7 @@ import { fullName } from '../../../core/canvas/labels.js';
 import { reportsForNode } from './reports.js';
 import { getCron } from '../../../core/canvas/crons.js';
 import { cronWakeOrigin } from '../../../core/runtime/bearings.js';
+import { boundDaemonControl } from '../../control.js';
 import { notFound, usage } from '../../../core/errors.js';
 import { toCloseResultDTO, toNodeDetailDTO, toNodeSummaryDTO, toReviveResultDTO } from '../map.js';
 import { ApiError } from '../../../api/index.js';
@@ -604,9 +605,11 @@ function handleClose(ctx) {
     if (body?.caller_pid !== undefined && (!Number.isInteger(body.caller_pid) || body.caller_pid <= 0)) {
         throw usage('caller_pid must be a positive integer when provided');
     }
+    const daemon = boundDaemonControl();
     const result = closeNode(id, {
         rootEvent: body?.finish === true ? 'finish' : 'cancel',
         callerPid: body?.caller_pid,
+        ...(daemon === null ? {} : { registerDetached: daemon.registerDetached }),
     });
     return { status: 200, body: toCloseResultDTO(result) };
 }

package/dist/daemon/control.d.ts

@@ -12,6 +12,8 @@ export interface DaemonControl {
     requestHandover(): {
         graceMs: number;
     };
+    /** Register daemon-owned post-response work for shutdown draining. */
+    registerDetached(work: Promise<void>): void;
 }
 /** Bind this process's control surface. Called once, by `runDaemon`. */
 export declare function bindDaemonControl(control: DaemonControl): void;

package/dist/daemon/crtrd.js

@@ -607,7 +607,7 @@ export async function runDaemon(opts = {}) {
         // The self-control seam the API's handover handler reaches this closure
         // through (see control.ts). Bound alongside the fleet so anything that can
         // launch a broker can also hand the fleet over.
-        bindDaemonControl({ epoch, requestHandover });
+        bindDaemonControl({ epoch, requestHandover, registerDetached });
         operationIdContext.fresh(() => {
             emitEvent({
                 level: 'info',

package/dist/hook-authoring.d.ts

@@ -43,11 +43,11 @@ export interface AfterHookRequest extends HookRequestBase {
 export interface ReplaceHookRequest extends HookRequestBase {
     phase: 'replace';
 }
-/** Lifecycle handlers run on every matching event. They must be idempotent because `node:start` fires for birth and every revive. */
+/** Lifecycle handlers run on every matching event. `node:start` handlers must be idempotent because they fire for birth and every revive. */
 export interface LifecycleHookRequest {
     protocolVersion: 1;
     op: string;
-    event: 'node:start';
+    event: 'node:start' | 'node:close';
     phase: 'on';
     operationId: string;
     node: LifecycleHookNode;

package/dist/hook-authoring.js

@@ -249,7 +249,7 @@ function validateRequest(value) {
     if (value['phase'] === 'on') {
         if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'event', 'phase', 'operationId', 'node', 'runtime', 'context']))
             return invalid('lifecycle request contains unknown fields');
-        if (value['event'] !== 'node:start')
+        if (value['event'] !== 'node:start' && value['event'] !== 'node:close')
             return invalid('unsupported lifecycle event');
         if (!isLifecycleNode(value['node']))
             return invalid('lifecycle request node contains invalid fields');
@@ -260,7 +260,7 @@ function validateRequest(value) {
         return valid({
             protocolVersion: 1,
             op: value['op'],
-            event: 'node:start',
+            event: value['event'],
             phase: 'on',
             operationId: value['operationId'],
             node: value['node'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.305",
+  "version": "0.3.307",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.305",
+  "version": "0.3.307",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.305",
+      "version": "0.3.307",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,17 +5206,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.305",
+      "version": "0.3.307",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.305",
+      "version": "0.3.307",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.305",
+      "version": "0.3.307",
       "license": "UNLICENSED",
       "dependencies": {
         "@north-light/crouter-api": "^0.3.295"