@north-light/crouter 0.3.306 → 0.3.308

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.306",
+  "version": "0.3.308",
   "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.306",
+  "version": "0.3.308",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.306",
+      "version": "0.3.308",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,17 +5206,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.306",
+      "version": "0.3.308",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.306",
+      "version": "0.3.308",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.306",
+      "version": "0.3.308",
       "license": "UNLICENSED",
       "dependencies": {
         "@north-light/crouter-api": "^0.3.295"