@crouton-kit/crouter 0.3.40 → 0.3.42

package/dist/core/profiles/select.js

@@ -5,7 +5,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { basename, resolve as resolvePath, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
-import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, } from './manifest.js';
+import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, addProfileProject, } from './manifest.js';
 /** Resolve cwd to an absolute, realpath'd form so it compares against the
  *  realpath'd project dirs `createProfile`/`addProfileProject` already store
  *  (manifest.ts resolves every project dir through `realpathSync`). Falls back
@@ -66,6 +66,25 @@ function recoveryMessage(cwd) {
  *  artifact or a queued interaction, not a two-choice gate on the same TTY pi
  *  is about to take over — a raw `readline` question is the actual minimal
  *  fit here. */
+/** Explicit `--profile` names a profile whose manifest does NOT cover cwd.
+ *  Interactive only: offer to widen the profile's purview to include this
+ *  directory (default yes), so the next node started here is covered without a
+ *  separate `crtr profile add-project`. Declining leaves the manifest untouched
+ *  and runs the node under the profile anyway. Same raw-readline rationale as
+ *  `promptCreateOrRoot` — this gates pi's boot on the same TTY. */
+async function promptAddDirToProfile(entry, cwd) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        process.stdout.write(`\nProfile "${entry.manifest.name}" does not cover this directory:\n  ${cwd}\n\n`);
+        const choice = (await rl.question('Add it to the profile? [Y/n]: ')).trim().toLowerCase();
+        if (choice === 'n' || choice === 'no')
+            return;
+        addProfileProject(entry.profileId, cwd);
+    }
+    finally {
+        rl.close();
+    }
+}
 async function promptCreateOrRoot(cwd) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -86,8 +105,10 @@ async function promptCreateOrRoot(cwd) {
 }
 /** Select the profile a node about to boot at `cwd` should run under.
  *
- *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`,
- *     bump `last_used_at`, return the id.
+ *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If
+ *     its manifest does not already cover `cwd` and the session is interactive,
+ *     offer to add `cwd` to its purview (default yes). Bump `last_used_at`,
+ *     return the id.
  *  2. Else, among profiles whose project list COVERS `cwd`, pick the
  *     most-recently-used (nulls oldest), bump its `last_used_at`, return it.
  *  3. Else — nothing covers cwd. Interactive session: prompt synchronously to
@@ -95,12 +116,17 @@ async function promptCreateOrRoot(cwd) {
  *     interactive (no TTY): default to root (null) and print the recovery
  *     instruction to STDERR — never stdout, which the caller may be piping. */
 export async function selectProfileForCwd(cwd, explicitProfile) {
+    const resolvedCwd = resolveCwd(cwd);
     if (explicitProfile !== undefined && explicitProfile !== null && explicitProfile !== '') {
         const entry = loadProfileManifest(explicitProfile);
+        // Selecting a profile from a directory it does not yet cover: offer to
+        // widen its purview (interactive only, default yes) before pi boots.
+        if (!profileCoversCwd(entry, resolvedCwd) && isInteractive()) {
+            await promptAddDirToProfile(entry, resolvedCwd);
+        }
         updateProfileLastUsed(entry.profileId);
         return entry.profileId;
     }
-    const resolvedCwd = resolveCwd(cwd);
     const covering = listProfiles().filter((p) => profileCoversCwd(p, resolvedCwd));
     if (covering.length > 0) {
         const winner = pickMostRecent(covering);

package/dist/core/runtime/bearings.js

@@ -446,6 +446,10 @@ export function buildContextBearings(nodeId) {
     const profileSection = profileNote(nodeId);
     if (profileSection !== '')
         bearings.push('', profileSection);
+    const wt = node?.managed_worktree;
+    if (wt?.state === 'open') {
+        bearings.push('', '## Your managed worktree', `Branch: \`${wt.branch}\`\nWorktree: \`${wt.path}\`\nBase: \`${wt.base_ref}\` @ \`${wt.base_sha}\`\nCommit work here. Land it with \`crtr worktree close\` before finishing; \`crtr push final\` is blocked until this worktree is closed.`);
+    }
     // Orchestrator-only: the across-cycles framing (a terminal has no future cycle).
     if (node?.mode === 'orchestrator')
         bearings.push('', orchestratorContextNote(nodeId));

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

@@ -3,6 +3,13 @@
  *  to the installed node, shared across every canvas home. */
 export declare function brandedHostDir(): string;
 export declare function brandedHostBin(): string;
+/** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
+ *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the
+ *  portable default for machines without a local signing certificate. */
+export declare function codesignIdentitiesForBrandedHost(opts?: {
+    configured?: string | null;
+    discovered?: string | null;
+}): string[];
 export declare function signBrandedHostArtifacts(binPath: string, libnodePath: string | null, sign?: (path: string) => void): void;
 export declare function brandedHostWorks(binPath: string): boolean;
 /** Ensure the branded host binary exists and matches the live node; return its

package/dist/core/runtime/branded-host.js

@@ -72,30 +72,57 @@ function readMarker() {
         return null;
     }
 }
-/** Sign a copied branded-host artifact with the Apple Development identity.
- *  macOS keys FDA grants on the Mach-O cdhash, so ad-hoc signing loses grants
- *  after each rebuild. Stable signing preserves them. Non-fatal — if signing
- *  fails (no certificate, non-macOS, etc), return silently. */
+/** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
+ *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the
+ *  portable default for machines without a local signing certificate. */
+export function codesignIdentitiesForBrandedHost(opts = {}) {
+    const configured = opts.configured?.trim();
+    if (configured)
+        return [configured];
+    const discovered = opts.discovered?.trim();
+    return [discovered || '-'];
+}
+function discoverCodesignIdentity() {
+    if (process.platform !== 'darwin')
+        return null;
+    const res = spawnSync('security', ['find-identity', '-v', '-p', 'codesigning'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    if (res.status !== 0)
+        return null;
+    const stdout = (res.stdout ?? '').toString();
+    const identities = stdout
+        .split('\n')
+        .map((line) => line.match(/\)\s+[A-Fa-f0-9]{40}\s+"([^"]+)"/)?.[1] ?? null)
+        .filter((identity) => identity !== null);
+    return identities.find((identity) => identity.startsWith('Apple Development:'))
+        ?? identities.find((identity) => identity.startsWith('Developer ID Application:'))
+        ?? identities[0]
+        ?? null;
+}
+function runCodesign(binPath, identity) {
+    const res = spawnSync('codesign', ['-s', identity, '--deep', '--force', binPath], { stdio: ['pipe', 'pipe', 'pipe'] });
+    return { ok: res.status === 0, stderr: (res.stderr ?? '').toString().trim() };
+}
 function signBrandedHost(binPath) {
     if (process.platform !== 'darwin')
         return;
     try {
-        const res = spawnSync('codesign', [
-            '-s',
-            'Apple Development: Silas Rhyneer (8W9CF7WS32)',
-            '--deep',
-            '--force',
-            binPath,
-        ], { stdio: ['pipe', 'pipe', 'pipe'] });
-        if (res.status !== 0) {
-            const stderr = (res.stderr ?? '').toString().trim();
-            if (stderr && !stderr.includes('valid on disk')) {
-                console.debug(`[crouter] codesign failed (expected on some systems): ${stderr}`);
-            }
+        const identities = codesignIdentitiesForBrandedHost({
+            configured: process.env['CRTR_CODESIGN_IDENTITY'],
+            discovered: discoverCodesignIdentity(),
+        });
+        let lastError = '';
+        for (const identity of identities) {
+            const res = runCodesign(binPath, identity);
+            if (res.ok)
+                return;
+            lastError = res.stderr;
+        }
+        if (lastError && !lastError.includes('valid on disk')) {
+            console.debug(`[crouter] codesign failed (expected on some systems): ${lastError}`);
         }
     }
     catch {
-        // codesign not found or other spawn error — non-fatal, continue.
+        // codesign/security not found or other spawn error — non-fatal, continue.
     }
 }
 export function signBrandedHostArtifacts(binPath, libnodePath, sign = signBrandedHost) {

package/dist/core/runtime/broker-sdk.js

@@ -1,20 +1,18 @@
 // broker-sdk.ts — the single import-and-version-assert shim between the headless
 // broker and the pi SDK (`@earendil-works/pi-coding-agent`).
 //
-// crouter has never imported the SDK before — it only ever forked the `pi` binary
-// (see `launch.ts buildPiArgv`). The broker (T4) is the first consumer. This shim
-// is the one place the dependency is named, so:
+// The broker imports the SDK in-process, and the bundled pi CLI is used only for
+// incidental headless helper commands and the version tripwire. This shim is the
+// one place the dependency is named, so:
 //   - the version tripwire (`assertEngineVersion`) lives here, and
 //   - the `CRTR_BROKER_ENGINE` test seam (T11) has a single dynamic-import
 //     indirection point (`loadBrokerEngine`) to swap in the fake engine.
-//
-// Nothing else in the tree imports this yet; it compiles but stays inert so the
-// lifecycle suite stays green until the broker is wired up.
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { delimiter, join } from 'node:path';
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, } from '@earendil-works/pi-coding-agent';
 import { crtrHome } from '../canvas/paths.js';
+import { resolveBundledPiCliPath } from './pi-cli.js';
 // Static re-exports — the real SDK surface the broker drives in production.
 export { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, };
 /**
@@ -44,44 +42,10 @@ export async function loadBrokerEngine() {
         VERSION: typeof mod.VERSION === 'string' ? mod.VERSION : 'unknown',
     };
 }
-/**
- * Boot-time tripwire: compare the imported SDK `VERSION` against the `pi` binary
- * crouter forks elsewhere (`pi --version`). On mismatch (or if the binary can't be
- * probed) it logs a LOUD warning to stderr and proceeds — it NEVER throws. The v3
- * session format auto-migrates on load, so minor skew round-trips; a hard fail here
- * would risk a grace-revive crash loop. Phase 5 may harden this to fail-fast once
- * the broker is the only host.
- *
- * @param engineVersion the version actually loaded (defaults to the statically
- *   imported `VERSION`; pass `engine.VERSION` from `loadBrokerEngine` to assert the
- *   version the broker is really driving).
- */
-/** Resolve the `pi` executable on PATH without spawning anything — a plain walk
- *  of `$PATH` entries (`statSync` follows symlinks, so an npm/brew bin shim
- *  resolves to the real target). Returns the first match, or undefined. */
-function resolvePiBinary() {
-    const path = process.env['PATH'];
-    if (path === undefined || path === '')
-        return undefined;
-    for (const dir of path.split(delimiter)) {
-        if (dir === '')
-            continue;
-        const candidate = join(dir, 'pi');
-        try {
-            if (existsSync(candidate))
-                return candidate;
-        }
-        catch {
-            /* unreadable PATH entry — skip */
-        }
-    }
-    return undefined;
-}
 const PI_VERSION_CACHE = () => join(crtrHome(), 'pi-version.json');
-/** Cached `pi --version`, keyed on the binary's path+mtime+size so a pi upgrade
- *  re-probes but the steady state never spawns. Returns undefined when the
- *  binary can't be resolved/stat'd or the cache misses — the caller then spawns
- *  once and back-fills via {@link writePiVersionCache}. */
+/** Cached `pi --version`, keyed on the CLI's path+mtime+size so a pi upgrade
+ *  re-probes but the steady state never spawns. Returns undefined when the cache
+ *  misses — the caller then spawns once and back-fills via {@link writePiVersionCache}. */
 function readPiVersionCache(binPath, mtimeMs, size) {
     try {
         const c = JSON.parse(readFileSync(PI_VERSION_CACHE(), 'utf8'));
@@ -103,41 +67,37 @@ function writePiVersionCache(entry) {
     }
 }
 export function assertEngineVersion(engineVersion = VERSION) {
-    // Resolve + stat the binary (no spawn). When its path+mtime+size matches the
-    // cache, reuse the stored version and skip the ~0.4s `pi --version` boot — the
-    // common path on every broker start. A pi upgrade changes the stat and re-probes.
-    const binPath = resolvePiBinary();
+    // Resolve + stat the bundled CLI (no spawn). When its path+mtime+size matches
+    // the cache, reuse the stored version and skip the ~0.4s `pi --version` boot —
+    // the common path on every broker start. A pi upgrade changes the stat and re-probes.
+    let binPath;
     let stat;
-    if (binPath !== undefined) {
-        try {
-            const s = statSync(binPath);
-            stat = { mtimeMs: s.mtimeMs, size: s.size };
-        }
-        catch {
-            stat = undefined;
-        }
+    try {
+        binPath = resolveBundledPiCliPath();
+        const s = statSync(binPath);
+        stat = { mtimeMs: s.mtimeMs, size: s.size };
     }
-    let binaryVersion;
-    if (binPath !== undefined && stat !== undefined) {
-        binaryVersion = readPiVersionCache(binPath, stat.mtimeMs, stat.size);
+    catch (err) {
+        process.stderr.write(`[broker] WARNING: could not resolve bundled pi CLI to verify engine parity ` +
+            `(SDK ${engineVersion}): ${err.message}\n`);
+        return;
     }
+    let binaryVersion = readPiVersionCache(binPath, stat.mtimeMs, stat.size);
     if (binaryVersion === undefined) {
         try {
-            binaryVersion = execFileSync('pi', ['--version'], { encoding: 'utf8' }).trim();
+            binaryVersion = execFileSync(process.execPath, [binPath, '--version'], { encoding: 'utf8' }).trim();
         }
         catch (err) {
-            process.stderr.write(`[broker] WARNING: could not run 'pi --version' to verify engine parity ` +
+            process.stderr.write(`[broker] WARNING: could not run bundled 'pi --version' to verify engine parity ` +
                 `(SDK ${engineVersion}): ${err.message}\n`);
             return;
         }
-        if (binPath !== undefined && stat !== undefined) {
-            writePiVersionCache({ path: binPath, mtimeMs: stat.mtimeMs, size: stat.size, version: binaryVersion });
-        }
+        writePiVersionCache({ path: binPath, mtimeMs: stat.mtimeMs, size: stat.size, version: binaryVersion });
     }
     if (binaryVersion !== engineVersion) {
         process.stderr.write(`[broker] WARNING: pi SDK version mismatch — imported SDK is ${engineVersion} but ` +
-            `the 'pi' binary is ${binaryVersion}. The v3 session format auto-migrates on load so ` +
-            `minor skew round-trips, but pin '@earendil-works/pi-coding-agent' to the binary version ` +
-            `to keep the in-process engine and the forked binary in lockstep.\n`);
+            `the bundled pi CLI is ${binaryVersion}. The v3 session format auto-migrates on load so ` +
+            `minor skew round-trips, but keep the crouter dependency on '@earendil-works/pi-coding-agent' ` +
+            `in lockstep with the in-process engine.\n`);
     }
 }

package/dist/core/runtime/broker.js

@@ -32,6 +32,7 @@ import { isModelNotFoundError, readFault, recordFault } from './fault.js';
 import { CONNECTION_FAULT_RECOVERY_BODY, PROVIDER_FAULT_RECOVERY_BODY } from './fault-recovery-nudge.js';
 import { markFatalOnExhaust, nextFaultRetry, policyFor } from './fault-recovery.js';
 import { probeOnline as probeOnlineReal } from './connectivity.js';
+import { CRTR_CYCLE_CUSTOM_TYPE, cycleAwareMessages } from './session-cycles.js';
 import { BUILTIN_SLASH_COMMANDS } from './pi-vendored.js';
 import { encodeFrame, FrameDecoder, FrameOverflowError, BROKER_READ_CAPS, } from './broker-protocol.js';
 const THINKING_LEVELS = new Set(['off', 'minimal', 'low', 'medium', 'high', 'xhigh']);
@@ -1646,9 +1647,19 @@ export async function runBroker(nodeId) {
 //
 // `AgentSession.sessionManager` is a public readonly field of the real pi SDK; the
 // fake-engine test fixture mirrors the same `sessionManager.buildSessionContext()`
-// surface, so this is a single path with no engine-capability fallback.
+// surface (plus, where present, the tree accessors `cycleAwareMessages` reads).
+// A refresh-yielded node keeps every prior cycle in the SAME `.jsonl` as sibling
+// branches (session-cycles.ts) — `cycleAwareMessages` replays them ahead of the
+// live cycle's context so the welcome snapshot renders one continuous
+// conversation instead of just the post-yield window; single-cycle sessions and
+// the fake-engine fixture (no tree accessors) fall through to plain
+// `buildSessionContext().messages` unchanged.
 export function snapshotMessages(session) {
-    return session.sessionManager.buildSessionContext().messages;
+    // Cast: the real SDK's `SessionEntry.data` is `unknown` (untyped custom-entry
+    // payload), narrower than `CycleSessionManagerLike`'s structural read of the
+    // `crtr-cycle` marker's `{cycle, fromLeaf}` shape — the fields we read off it
+    // are ones ONLY this module's own `appendCustomEntry` call (above) ever writes.
+    return cycleAwareMessages(session.sessionManager);
 }
 // ---------------------------------------------------------------------------
 // buildBrokerSession (plan T4 steps 2–4) — turn the launch recipe into a live
@@ -1745,7 +1756,19 @@ export async function buildBrokerSession(engine, cfg) {
     // A fork is a fresh spawn (resuming=false) so the kickoff firstPrompt fires: a
     // `node new --fork-from <id>` gives the new node the source's full history AND a
     // new task to start on. A resume replays the inbox instead and sends no kickoff.
-    const resuming = !forking && resumePath !== undefined && resumePath !== '';
+    //
+    // A refresh-yield CYCLES instead: `cfg.newCycle` (the `--crtr-new-cycle` token)
+    // marks a revive that reuses this SAME `.jsonl` rather than resuming it — the
+    // session manager opens the file, then resets the leaf and roots a `crtr-cycle`
+    // marker entry (data: `{cycle, fromLeaf}`) as the new cycle's ROOT before the
+    // session is built. Custom entries never enter LLM context, so the freshly
+    // rooted branch is exactly as clean as a brand-new session; `cycleAwareMessages`
+    // (session-cycles.ts) is the display-side counterpart that replays every prior
+    // cycle for snapshot rendering. cycling ⇒ resuming=false, so the kickoff
+    // firstPrompt fires below just like a true fresh launch.
+    const hasSessionPath = !forking && resumePath !== undefined && resumePath !== '';
+    const cycling = hasSessionPath && cfg.newCycle === true;
+    const resuming = hasSessionPath && !cycling;
     let sessionManager;
     if (forking) {
         // Spawn-time fork via pi's REAL fork seam, SessionManager.forkFrom — the exact
@@ -1759,8 +1782,16 @@ export async function buildBrokerSession(engine, cfg) {
         // fails loudly here (forkFrom throws on an empty/invalid/header-less source).
         sessionManager = engine.SessionManager.forkFrom(cfg.forkFrom, cfg.cwd);
     }
-    else if (resuming) {
+    else if (resuming || cycling) {
         sessionManager = engine.SessionManager.open(resumePath);
+        if (cycling) {
+            const fromLeaf = sessionManager.getLeafId();
+            sessionManager.resetLeaf();
+            sessionManager.appendCustomEntry(CRTR_CYCLE_CUSTOM_TYPE, {
+                cycle: Number(process.env['CRTR_CYCLES']),
+                fromLeaf,
+            });
+        }
     }
     else {
         sessionManager = engine.SessionManager.create(cfg.cwd);

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

@@ -11,9 +11,9 @@ export interface LaunchPlacement {
  *  the broker pid recorded as pi_pid; no tmux placement coords exist (the engine
  *  is never in a pane). */
 export interface HostHandle {
-    /** Supervised pid (signal-0 target). May be null right at launch before the
-     *  detached child reports its pid; the broker re-records pi_pid during its
-     *  extension bind, and reviveNode clearPid()s right after launch. */
+    /** Supervised pid (signal-0 target). Null means the host failed to spawn an
+     *  engine at all. Spawn/revive record this pid immediately; the broker
+     *  re-records the same pid during extension bind. */
     pid: number | null;
     /** Real child-exit signal from the launch handle. Resolves when the detached
      *  broker exits, so readiness waits can fail fast without pid probes. */

package/dist/core/runtime/host.js

@@ -20,7 +20,8 @@ import { nodeDir, jobDir, viewSocketPath } from '../canvas/paths.js';
 import { encodeFrame } from './broker-protocol.js';
 import { FRONT_DOOR_ENV } from './front-door.js';
 import { hostExecPath } from './branded-host.js';
-import { isPidAlive } from '../canvas/pid.js';
+import { isPidAlive, killProcessTreePids, isAnyPidAlive, captureTeardownSnapshot } from '../canvas/pid.js';
+import { logger } from '../log.js';
 // ---------------------------------------------------------------------------
 // HeadlessBrokerHost (design §3.3): a detached broker PROCESS, no tmux pane. It
 // boots the dedicated broker-cli entry directly (NEVER src/cli.ts), supervises
@@ -88,8 +89,80 @@ export function preflightBrokerLaunch(nodeId, inv, cwd) {
     }
 }
 /** How long teardown waits after sending the graceful `shutdown` frame before
- *  SIGTERMing a broker that connected but never exited (e.g. a hung dispose()). */
+ *  escalating a broker/tree that connected but never fully exited (e.g. a hung
+ *  dispose(), or a dispose() that reaped the broker but left a descendant
+ *  behind). */
 const BROKER_SHUTDOWN_GRACE_MS = 2_000;
+/** How long teardown waits after the tree-wide SIGTERM before the final
+ *  tree-wide SIGKILL sweep — the last resort for a broker (or its
+ *  descendants) that ignores SIGTERM entirely. */
+const BROKER_SIGKILL_GRACE_MS = 2_000;
+/** How often `pollUntilTreeDead` re-checks the process TREE. Short enough that
+ *  the common/happy path (tree already dead) pays only a couple of ticks; the
+ *  full grace ceilings above are reserved for the genuinely-wedged case,
+ *  where the added latency is the whole point (crouter#98 review finding 3). */
+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 (crouter#98 review finding 3): 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();
+}
+/** 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 (crouter#98 review finding 1). 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 (crouton-labs/crouter#98). `identities` guards each signal against
+ *  PID REUSE across the multi-second escalation window (review finding 3) —
+ *  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) {
+    killProcessTreePids(tree, 'SIGTERM', identities);
+    pollUntil(() => isAnyPidAlive(tree), BROKER_SIGKILL_GRACE_MS, () => killProcessTreePids(tree, 'SIGKILL', identities));
+}
 export const headlessBrokerHost = {
     launch(nodeId, inv, opts) {
         // Fast-fail known launch errors before we detach a broker process.
@@ -136,8 +209,51 @@ export const headlessBrokerHost = {
         // 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) fall back to a
-        // SIGTERM of the broker pid + unlink the stale socket.
+        // 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 (crouton-labs/crouter#98) — + 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 (crouter#98 review finding 2).
+        const node = getNode(nodeId);
+        const pid = node?.pi_pid;
+        // Snapshot the full descendant TREE (crouter#98 review finding 1) — the
+        // root pid plus every transitive descendant — and a stable identity
+        // fingerprint for every pid in it (review finding 3), 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) : null;
+        if (snapshot?.reused === true) {
+            logger('host').warn('refusing to signal a reused pid — launch-time identity mismatch', {
+                nodeId,
+                pid,
+            });
+        }
+        const tree = snapshot?.tree ?? [];
+        const identities = snapshot?.identities ?? null;
         const sockPath = viewSocketPath(nodeId);
         const cleanupSocket = () => {
             try {
@@ -152,18 +268,11 @@ export const headlessBrokerHost = {
         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 SIGTERM fallback.
+            // and swallowed; only a connect failure triggers the escalation fallback.
             if (connected)
                 return;
-            const pid = getNode(nodeId)?.pi_pid;
-            if (pid != null) {
-                try {
-                    process.kill(pid, 'SIGTERM');
-                }
-                catch {
-                    /* already gone */
-                }
-            }
+            if (tree.length > 0)
+                escalateBrokerTeardown(tree, identities);
             cleanupSocket();
         });
         sock.once('connect', () => {
@@ -176,25 +285,31 @@ export const headlessBrokerHost = {
             }
             sock.end();
             cleanupSocket();
-            // Bounded exit confirmation (review Mn-3): 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. Arm a
-            // short UNREF'd timer; if the captured pid is still alive when it fires,
-            // SIGTERM it. unref'd so the happy path adds NO latency — a short-lived CLI
-            // caller's loop is kept alive only by the still-open socket, i.e. precisely
-            // the hung case where the fallback must run.
-            const pid = getNode(nodeId)?.pi_pid;
-            if (pid != null) {
-                setTimeout(() => {
-                    if (isPidAlive(pid)) {
-                        try {
-                            process.kill(pid, 'SIGTERM');
-                        }
-                        catch {
-                            /* already gone */
-                        }
-                    }
-                }, BROKER_SHUTDOWN_GRACE_MS).unref();
+            // 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 (crouter#98). 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
+            // (crouter#98 review finding 1): 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 (crouter#98
+            // review finding 1, fixed): 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));
             }
         });
     },