@north-light/crouter 0.3.249 → 0.3.250

package/dist/commands/sys/daemon.js

@@ -8,22 +8,25 @@
 // This subtree starts, checks, and stops the daemon process.
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { InputError } from '../../core/io.js';
-import { spawnDaemon, stopDaemonProcess, sweepStrayDaemons } from '../../daemon/manage.js';
+import { isDaemonServing, spawnDaemon, stopDaemonProcess, sweepStrayDaemons } from '../../daemon/manage.js';
 import { isDaemonRunning, readPidfile, isPidAlive } from '../../daemon/pidfile.js';
 import { cliClient } from '../api-client.js';
 // daemon start
 const daemonStart = defineLeaf({
     name: 'start',
     description: 'start the daemon in the background',
-    whenToUse: 'bringing the crtrd supervisor up for the first time in a session so node window-exits get handled (no-op if it is already running)',
+    whenToUse: 'bringing the crtrd supervisor up for the first time in a session so node window-exits get handled (no-op only when its Unix API socket already serves)',
     help: {
         name: 'sys daemon start',
-        summary: 'start the crtrd supervisor daemon in the background (no-op if already running)',
+        summary: 'start the crtrd supervisor daemon in the background (no-op only if its Unix API socket serves)',
         params: [],
         output: [
             { name: 'started', type: 'boolean', required: true, constraint: 'True when a new daemon process was spawned; false when one was already running.' },
             { name: 'pid', type: 'number', required: false, constraint: 'PID of the newly spawned daemon.' },
             { name: 'existing_pid', type: 'number', required: false, constraint: 'PID of the already-running daemon (when started=false).' },
+            { name: 'running', type: 'boolean', required: false, constraint: 'True only when a live pidfile owner does not serve its Unix API socket.' },
+            { name: 'serving', type: 'boolean', required: false, constraint: 'False only when a live pidfile owner does not answer /healthz.' },
+            { name: 'next', type: 'string', required: false, constraint: 'Recovery instruction when running=true and serving=false.' },
         ],
         outputKind: 'object',
         effects: [
@@ -46,18 +49,28 @@ const daemonStatus = defineLeaf({
         summary: 'check whether the crtrd supervisor daemon is currently running',
         params: [],
         output: [
-            { name: 'running', type: 'boolean', required: true, constraint: 'True when the daemon is alive.' },
+            { name: 'running', type: 'boolean', required: true, constraint: 'True when the daemon pidfile owner is alive.' },
+            { name: 'serving', type: 'boolean', required: false, constraint: 'True when the live daemon answers /healthz; false when it does not.' },
             { name: 'pid', type: 'number', required: false, constraint: 'PID of the running daemon.' },
+            { name: 'next', type: 'string', required: false, constraint: 'Recovery instruction when running=true and serving=false.' },
         ],
         outputKind: 'object',
-        effects: ['Read-only: reads the pidfile and probes the pid.'],
+        effects: ['Read-only: reads the pidfile, probes the pid, and requests /healthz without autostart.'],
     },
     run: async (_input) => {
         const pid = readPidfile();
         const running = pid !== null && isPidAlive(pid);
-        return running
-            ? { running: true, pid }
-            : { running: false };
+        if (!running)
+            return { running: false };
+        const serving = await isDaemonServing();
+        return serving
+            ? { running: true, serving: true, pid }
+            : {
+                running: true,
+                serving: false,
+                pid,
+                next: 'Run `crtr sys daemon stop` to release the non-serving daemon before starting it again.',
+            };
     },
 });
 // daemon restart

package/dist/commands/sys/setup-core.js

@@ -178,8 +178,8 @@ const PACKAGE_COPY = {
     },
     'crtr-extensions': {
         name: 'pi-crtr-extensions',
-        shortDescription: 'crtr companion extensions — command palette, help gating, statusline, subscription/OAuth rotation, nested context.',
-        longDescription: 'Bundles the extensions built for crtr: a crtr slash-command palette, crtr/crouter help gating, surfacing of Claude Code marketplace plugin commands, nested AGENTS.md/CLAUDE.md loading, a model/subscription/token statusline badge, OAuth login + rotation across multiple Claude subscriptions (provider-rotation), and system-prompt trimming. The OAuth/rotation piece is what lets crtr authenticate your Claude account.',
+        shortDescription: 'crtr companion extensions — command palette, help gating, subscription/OAuth rotation, nested context.',
+        longDescription: 'Bundles the extensions built for crtr: a crtr slash-command palette, crtr/crouter help gating, surfacing of Claude Code marketplace plugin commands, nested AGENTS.md/CLAUDE.md loading, OAuth login + rotation across multiple Claude subscriptions (provider-rotation), and system-prompt trimming. The OAuth/rotation piece is what lets crtr authenticate your Claude account.',
     },
     'oauth-adapter': {
         name: 'pi-claude-oauth-adapter',

package/dist/core/__tests__/broker-stream-watchdog-floor.test.d.ts

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

package/dist/core/__tests__/broker-stream-watchdog-floor.test.js

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { EventProjection } from '../runtime/broker/event-projection.js';
+import { RebindDriver } from '../runtime/broker/rebind.js';
+function generationFor(session) {
+    return {
+        id: 1,
+        session,
+        fallback: { blocked: false },
+        stagedProviderAgentEnd: null,
+        stagedWatchdogAbort: false,
+        stagedRefreshAbort: false,
+        stagedOverflowFailure: null,
+        executingTools: new Set(),
+    };
+}
+function projectionFor(session, generation) {
+    return new EventProjection({
+        registry: { broadcast: () => undefined },
+        faultRetry: { onEvent: () => undefined, clearTimer: () => undefined },
+        installedGeneration: () => generation,
+        currentSession: () => session,
+        notifyTurnAccepted: () => undefined,
+        emitStartupMilestone: () => undefined,
+        formatModelSpec: () => null,
+        refreshIntent: async () => false,
+        onRefreshIntentError: () => undefined,
+    });
+}
+test('agent_start arms the provider watchdog before another engine event arrives', (t) => {
+    t.mock.timers.enable({ apis: ['setTimeout'] });
+    let aborts = 0;
+    const session = { isStreaming: true, abort: async () => { aborts++; } };
+    const generation = generationFor(session);
+    const projection = projectionFor(session, generation);
+    projection.relayEvent({ type: 'agent_start' }, generation);
+    t.mock.timers.tick(5 * 60_000);
+    assert.equal(aborts, 1, 'the initial streaming event leaves a watchdog floor even if the engine falls silent immediately');
+    assert.equal(generation.stagedWatchdogAbort, true, 'the floor retains watchdog provenance for provider-fault recovery');
+});
+test('tool execution replaces the provider watchdog with the long ceiling', (t) => {
+    t.mock.timers.enable({ apis: ['setTimeout'] });
+    let aborts = 0;
+    const session = { isStreaming: true, abort: async () => { aborts++; } };
+    const generation = generationFor(session);
+    const projection = projectionFor(session, generation);
+    projection.relayEvent({ type: 'agent_start' }, generation);
+    projection.relayEvent({ type: 'tool_execution_start', toolCallId: 'stuck-tool' }, generation);
+    t.mock.timers.tick(5 * 60_000);
+    assert.equal(aborts, 0, 'a tool outlives the ordinary five-minute provider watchdog');
+    t.mock.timers.tick(15 * 60_000);
+    assert.equal(aborts, 1, 'a silent in-process tool cannot clear all watchdog coverage indefinitely');
+});
+test('rebind rearms the watchdog floor for a still-streaming replacement session', async () => {
+    const calls = [];
+    const projection = {
+        reset: () => calls.push('reset'),
+        rearmIfStreaming: (generation) => calls.push(`rearm:${generation.id}`),
+    };
+    const session = {
+        isStreaming: true,
+        systemPrompt: '',
+        bindExtensions: async () => undefined,
+        subscribe: () => () => undefined,
+    };
+    const driver = new RebindDriver({
+        nodeId: 'watchdog-floor-rebind',
+        cfg: {},
+        session,
+        services: {},
+        runtime: undefined,
+        uiContext: () => ({}),
+        registry: {},
+        toolGroups: { resetForSession: () => undefined },
+        faultRetry: () => ({ reset: () => undefined }),
+        projection: () => projection,
+        setActiveSession: () => undefined,
+        disposeAndExit: () => undefined,
+        onSessionRebind: () => undefined,
+        reWelcomeAll: () => undefined,
+    });
+    await driver.enqueueRebind(session, {});
+    assert.deepEqual(calls, ['reset', 'rearm:1'], 'a rebind that resets projection state immediately restores coverage for its live stream');
+});

package/dist/core/__tests__/broker-turn-admission.test.d.ts

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

package/dist/core/__tests__/broker-turn-admission.test.js

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createTurnAdmissionGate } from '../runtime/broker/turn-admission.js';
+function deferred() {
+    let resolve;
+    const promise = new Promise((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+test('concurrent starts admit one turn and reject the loser without a spurious settlement', async () => {
+    const gate = createTurnAdmissionGate();
+    const preflight = deferred();
+    const turn = deferred();
+    const enteredPreflight = deferred();
+    let streaming = false;
+    let admittedTurns = 0;
+    let settlements = 0;
+    const prompt = async (release) => {
+        enteredPreflight.resolve();
+        await preflight.promise;
+        if (streaming) {
+            release();
+            throw new Error('Agent is already processing');
+        }
+        streaming = true;
+        admittedTurns++;
+        release();
+        await turn.promise;
+        streaming = false;
+        settlements++;
+    };
+    const winner = gate.admit(prompt);
+    await enteredPreflight.promise;
+    const loser = gate.admit(prompt);
+    preflight.resolve();
+    await assert.rejects(loser, /Agent is already processing/);
+    assert.equal(admittedTurns, 1, 'only the winner entered a turn');
+    assert.equal(settlements, 0, 'the rejected call did not settle the live turn');
+    assert.equal(streaming, true, 'the winner remains live after the loser rejects');
+    turn.resolve();
+    await winner;
+    assert.equal(settlements, 1, 'the admitted turn alone settled');
+});

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.js

@@ -105,7 +105,11 @@ function ensureWatcherNode() {
         cwd: '/tmp',
         kind: 'general',
         mode: 'base',
-        lifecycle: 'terminal',
+        // Resident: these cases are about the watcher's own cursor/handoff/hold
+        // contract at each tier as sent. A terminal node's mail is raised to the
+        // steering tier on append (feed/inbox.ts), which would route every case
+        // here as a steer.
+        lifecycle: 'resident',
         status: 'active',
     });
     recordPid(nodeId, process.pid);

package/dist/core/__tests__/child-death-wake.test.js

@@ -48,9 +48,8 @@ function deadPid() {
 const GONE_PANE = '%999999';
 /** A booted child whose engine pid is DEAD and whose viewer pane is gone — the
  *  shape a crashed/finished child leaves behind. `pi_session_id` set so it is
- *  "booted"; `intent:null` so a delivered exit would classify as a crash
- *  (policy row 6, strict resume) — but no exit is delivered here: the tick
- *  alone must not touch it. */
+ *  "booted"; `intent:null` selects policy row 6 (strict resume) when the
+ *  authoritative tick observes the missing engine. */
 function deadEngineChild(id, over = {}) {
     createNode(node(id, {
         pane: GONE_PANE,
@@ -86,7 +85,7 @@ after(() => {
     delete process.env['CRTR_HOME'];
     resetFleetForTests();
 });
-test('exit-event authority: a dead-engine booted child is recovered, NOT reaped, and the tick fans NO wake to its dormant parent', async () => {
+test('a dead-engine booted child enters durable backoff before recovery, is NOT reaped, and fans NO wake to its dormant parent', async () => {
     const originalLaunch = headlessBrokerHost.launch;
     const launches = [];
     headlessBrokerHost.launch = (nodeId) => {
@@ -100,9 +99,14 @@ test('exit-event authority: a dead-engine booted child is recovered, NOT reaped,
         deadEngineChild('CHILD', { cwd: home }); // a cwd that exists — reviveNode's preflight refuses a missing one
         subscribe('PARENT', 'CHILD', true); // the spawn-time spine edge
         await superviseTick();
-        // A stale recorded pid is metadata, not a verdict: the row is relaunched on
-        // its saved session, never reaped to dead/done/idle.
-        assert.deepEqual(launches, ['CHILD'], 'the tick recovers the dead engine through the policy table');
+        const afterFirstTick = getNode('CHILD');
+        assert.deepEqual(launches, [], 'the first tick records the failed launch without relaunching');
+        assert.equal(afterFirstTick.respawn_failures, 1, 'the first tick records failure one durably');
+        assert.ok(afterFirstTick.respawn_not_before, 'the first tick records durable backoff');
+        await superviseTick(Date.parse(afterFirstTick.respawn_not_before));
+        // A stale recorded pid is metadata, not a verdict: once backoff matures,
+        // the row is relaunched on its saved session, never reaped to dead/done/idle.
+        assert.deepEqual(launches, ['CHILD'], 'the matured tick recovers the dead engine through the policy table');
         assert.equal(getNode('CHILD').status, 'active', 'CHILD is recovered, NOT reaped');
         assert.equal(readInboxSince('PARENT').length, 0, 'PARENT inbox EMPTY — no daemon liveness wake');
     }

package/dist/core/__tests__/collectible.test.d.ts

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

package/dist/core/__tests__/collectible.test.js

@@ -0,0 +1,88 @@
+import { after, before, beforeEach, test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, getRow, isCollectible, setFrozen, transitionStatusIntent, } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+let home;
+function node(id, over = {}) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        ...over,
+    };
+}
+function terminalRow(id, reason, status = 'done') {
+    createNode(node(id));
+    transitionStatusIntent(id, { status, terminal_reason: reason });
+    return getRow(id);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-collectible-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('isCollectible applies the terminal reason truth table and absolute retains', () => {
+    const terminalCases = [
+        ['finalized', 'done', true, true],
+        ['finished', 'done', true, true],
+        ['parked', 'done', true, true],
+        ['closed', 'dead', true, true],
+        ['retired', 'canceled', true, true],
+        ['crashed', 'dead', false, true],
+        ['stranded', 'canceled', false, true],
+        [null, 'done', false, true],
+    ];
+    for (const [reason, status, beforeTtl, pastTtl] of terminalCases) {
+        const row = terminalRow(`reason-${reason ?? 'null'}`, reason, status);
+        assert.equal(isCollectible(row), beforeTtl, `${reason ?? 'null'} before TTL`);
+        assert.equal(isCollectible(row, { pastTtl: true }), pastTtl, `${reason ?? 'null'} past TTL`);
+    }
+    const frozen = terminalRow('frozen', 'closed');
+    setFrozen(frozen.node_id, new Date().toISOString());
+    createNode(node('worktree', {
+        managed_worktree: {
+            state: 'open',
+            path: '/tmp/worktree',
+            branch: 'crtr/worktree',
+            repo_root: '/tmp/repo',
+            base_ref: 'main',
+            base_sha: 'base',
+            created: new Date().toISOString(),
+        },
+    }));
+    transitionStatusIntent('worktree', { status: 'done', terminal_reason: 'closed' });
+    const caller = terminalRow('caller', 'closed');
+    createNode(node('active'));
+    const nonTerminal = getRow('active');
+    const absoluteRows = [getRow(frozen.node_id), getRow('worktree'), caller, nonTerminal];
+    const previousNodeId = process.env['CRTR_NODE_ID'];
+    process.env['CRTR_NODE_ID'] = 'caller';
+    try {
+        for (const row of absoluteRows) {
+            assert.equal(isCollectible(row), false, `${row.node_id} before TTL`);
+            assert.equal(isCollectible(row, { pastTtl: true }), false, `${row.node_id} past TTL`);
+        }
+    }
+    finally {
+        if (previousNodeId === undefined)
+            delete process.env['CRTR_NODE_ID'];
+        else
+            process.env['CRTR_NODE_ID'] = previousNodeId;
+    }
+});

package/dist/core/__tests__/context-intro.test.js

@@ -2,8 +2,8 @@
 //   1. Situational context rides the bearings as a sibling block, and only
 //      once something has been set.
 //   2. canvas-context-intro injects the block as its own session message at
-//      session_start (before the first prompt), idempotent across resumes,
-//      inert without a node id — and its renderer never overruns the terminal.
+//      session_start (before the first prompt), idempotent across resumes, and
+//      inert without a node id.
 //
 // Run: node --import tsx/esm --test src/core/__tests__/context-intro.test.ts
 import { test, before, beforeEach, after, afterEach } from 'node:test';
@@ -15,7 +15,7 @@ import { closeDb } from '../canvas/db.js';
 import { apiSocketPath } from '../canvas/paths.js';
 import { spawnNode } from '../runtime/nodes.js';
 import { appendSituationalContext, formatSituationalProse, situationalContextEnvelope, } from '../runtime/situational-context.js';
-import registerCanvasContextIntro, { renderContextMessage, CONTEXT_INTRO_CUSTOM_TYPE, } from '../../pi-extensions/canvas-context-intro.js';
+import registerCanvasContextIntro, { CONTEXT_INTRO_CUSTOM_TYPE, } from '../../pi-extensions/canvas-context-intro.js';
 import { buildContextBearings as buildContextIntro } from '../runtime/bearings.js';
 import { createApiServer } from '../../daemon/api/server.js';
 let home;
@@ -61,18 +61,16 @@ function makeFakePi(entries = []) {
     return {
         sent: [],
         entries,
-        renderers: {},
         on(e, h) { if (e === 'session_start')
             this.handler = h; },
         sendMessage(m) {
             this.sent.push(m);
             this.entries.push({ type: 'custom_message', ...m });
         },
-        registerMessageRenderer(t, r) { this.renderers[t] = r; },
     };
 }
 function fakeCtx(pi) {
-    return { sessionManager: { getEntries: () => pi.entries } };
+    return { sessionManager: { getBranch: () => pi.entries } };
 }
 test('session_start injects the block as the first message of an empty session', async () => {
     const meta = spawnNode({ kind: 'general', cwd: '/tmp/work', parent: null });
@@ -111,38 +109,3 @@ test('session_start is inert when CRTR_NODE_ID is absent', async () => {
     await pi.handler({ reason: 'startup' }, fakeCtx(pi));
     assert.equal(pi.sent.length, 0);
 });
-test('renderer registered for the customType; collapsed hides body, ctrl+o expand reveals it', () => {
-    const pi = makeFakePi();
-    registerCanvasContextIntro(pi);
-    const renderer = pi.renderers[CONTEXT_INTRO_CUSTOM_TYPE];
-    assert.ok(renderer, 'message renderer registered for crtr-context');
-    const body = '<crtr-bearings>\nshared document store\n</crtr-bearings>';
-    const message = { customType: CONTEXT_INTRO_CUSTOM_TYPE, content: body };
-    const theme = {}; // no fg → plain text, easy to assert
-    // Collapsed (default): a single stub line, NONE of the body.
-    const collapsed = renderContextMessage(message, { expanded: false }, theme).render(80);
-    assert.equal(collapsed.length, 1, 'collapsed is one line');
-    assert.match(collapsed[0], /ctrl\+o to expand/);
-    assert.ok(!collapsed.join('\n').includes('shared document store'), 'body hidden when collapsed');
-    // Expanded (Ctrl+O): label + full body.
-    const expanded = renderContextMessage(message, { expanded: true }, theme).render(80);
-    const joined = expanded.join('\n');
-    assert.ok(joined.includes('shared document store'), 'body shown when expanded');
-    assert.ok(joined.includes(`[${CONTEXT_INTRO_CUSTOM_TYPE}]`), 'expanded shows the label');
-});
-test('renderer never emits a line wider than the terminal (truncates the collapsed stub)', () => {
-    // Regression: a fixed-width stub crashed pi's TUI at narrow widths
-    // ("Rendered line 1 exceeds terminal width"). Every emitted line — collapsed
-    // or expanded — must fit within the width handed to render().
-    const body = Array.from({ length: 6 }, () => 'x'.repeat(200)).join('\n');
-    const message = { customType: CONTEXT_INTRO_CUSTOM_TYPE, content: body };
-    const theme = {}; // no fg → plain text, so .length == visible width
-    for (const w of [1, 2, 5, 10, 20, 42, 80]) {
-        for (const expanded of [false, true]) {
-            const lines = renderContextMessage(message, { expanded }, theme).render(w);
-            for (const line of lines) {
-                assert.ok([...line].length <= w, `width=${w} expanded=${expanded}: line ${[...line].length} cols exceeds ${w}: ${JSON.stringify(line)}`);
-            }
-        }
-    }
-});

package/dist/core/__tests__/daemon-boot.test.js

@@ -62,23 +62,24 @@ after(() => {
 });
 // A broker that exits while pi_session_id was NEVER set: the vehicle died
 // before pi ever booted. The spawner already returned status="active", so the
-// parent must be told — the exit-policy job (table row 8) marks it dead AND
-// pushes urgent up. The old null-pid boot-grace clock is gone: the exit event
-// names the exact death, so there is nothing to bridge.
-test('never-booted broker exit is marked dead and surfaced to the parent as urgent', async () => {
+// authoritative tick applies table row 8 and tells the parent. The delivered
+// exit is observation-only.
+test('never-booted broker is marked dead by the tick and surfaced to the parent as urgent', async () => {
     createNode(node('P', { kind: 'developer', lifecycle: 'resident' }));
     createNode(node('C', {
         parent: 'P',
         kind: 'explore',
+        pi_pid: deadPid(), // launch recorded its process before it died
         pi_session_id: null, // never booted
         intent: null,
     }));
     spawnEdge('P', 'C');
-    // Exit-event authority: the launch's real child exit (delivered synthetically
-    // here — same path) classifies as table row 8: pi_session_id null, no fork
-    // claim → boot failure. No grace, no retry.
+    // The launch's real child exit is delivered synthetically here, then the
+    // authoritative tick classifies the dead recorded pid as table row 8:
+    // pi_session_id null, no fork claim → boot failure. No grace, no retry.
     tf.fleet.deliverExit('C', { code: 1, signal: null });
     await tf.drain();
+    await superviseTick();
     assert.equal(getNode('C').status, 'dead', 'never-booted child is dead');
     // Row 8 fans TWO entries: the urgent surfaceBootFailure push and the normal
     // doctrine wake (design flow B row 8 — crash + surfaceBootFailure + doctrine
@@ -115,7 +116,12 @@ test('a crashed booted child is relaunched on its saved session, not reaped, and
         spawnEdge('P2', 'C2');
         markBusy('C2'); // died mid-generation
         await superviseTick();
-        assert.deepEqual(launches, ['C2'], 'the tick recovers the crash through the policy table, exactly as the exit event would');
+        const afterFirstTick = getNode('C2');
+        assert.deepEqual(launches, [], 'the first tick records the failed launch without relaunching');
+        assert.equal(afterFirstTick.respawn_failures, 1, 'the first tick records failure one durably');
+        assert.ok(afterFirstTick.respawn_not_before, 'the first tick records durable backoff');
+        await superviseTick(Date.parse(afterFirstTick.respawn_not_before));
+        assert.deepEqual(launches, ['C2'], 'the matured tick recovers the crash through the policy table');
         assert.equal(getNode('C2').status, 'active', 'crashed booted child is relaunched, NOT marked dead');
         assert.equal(readInboxSince('P2').length, 0, 'no false boot-failure / child-death push on a crash (wake relocated to push/close)');
         clearBusy('C2');
@@ -155,19 +161,21 @@ test('idle-release node with a boot-cleared (null) pid and no unseen inbox is se
     assert.equal(after.intent, null, 'no revive fired — the row is settled, not relaunched');
     assert.equal(after.pi_pid, null, 'no fresh pid — reviveNode was never invoked');
 });
-// Daemon start guard: spawnDaemon must not report success before the daemon is
-// plausibly alive and has written its pidfile. This is a pure bounded poll over
-// injected clocks/probes, so we can lock it down deterministically without a
-// real daemon process.
-test('verifyDaemonStartup waits for pidfile + live pid, then reports success for the spawned pid', async () => {
+// Daemon start guard: spawnDaemon must not report success before the daemon's
+// pidfile owner is live AND its Unix API socket serves. This is a pure bounded
+// poll over injected clocks/probes, so we can lock it down deterministically
+// without a real daemon process.
+test('verifyDaemonStartup waits for pidfile, live pid, and serving socket before reporting success', async () => {
     let now = 0;
     let pidfileReady = false;
     let pidAliveReady = false;
+    let socketServing = false;
     let slept = 0;
     const existingPid = await verifyDaemonStartup(42, 50, {
         now: () => now,
         readPidfile: () => (pidfileReady ? 42 : null),
         isPidAlive: () => pidAliveReady,
+        isDaemonServing: async () => socketServing,
         sleepMs: (ms) => {
             slept += ms;
             now += ms;
@@ -175,12 +183,15 @@ test('verifyDaemonStartup waits for pidfile + live pid, then reports success for
                 pidfileReady = true;
             if (now >= 30)
                 pidAliveReady = true;
+            if (now >= 40)
+                socketServing = true;
         },
     });
     assert.equal(existingPid, null, 'the spawned daemon owns the pidfile when startup succeeds');
     assert.equal(pidfileReady, true, 'pidfile must have appeared before success');
     assert.equal(pidAliveReady, true, 'pid must have been alive before success');
-    assert.equal(slept > 0, true, 'the guard must actually poll');
+    assert.equal(socketServing, true, 'the Unix API socket must serve before success');
+    assert.equal(slept >= 40, true, 'the guard must actually poll through socket readiness');
 });
 test('runDaemon awaits activation before ownership and readiness', () => {
     const source = readFileSync(fileURLToPath(new URL('../../daemon/crtrd.ts', import.meta.url)), 'utf8');
@@ -204,6 +215,7 @@ test('verifyDaemonStartup default window tolerates a slower cold start', async (
         now: () => now,
         readPidfile: () => (pidfileReady ? 42 : null),
         isPidAlive: () => pidAliveReady,
+        isDaemonServing: async () => pidAliveReady,
         sleepMs: (ms) => {
             now += ms;
             if (now >= 600)
@@ -221,6 +233,7 @@ test('startup verification waits for delayed activation inside the shared window
         now: () => now,
         readPidfile: () => (activationComplete ? 42 : null),
         isPidAlive: () => activationComplete,
+        isDaemonServing: async () => activationComplete,
         sleepMs: (ms) => {
             now += ms;
             if (now >= 25_000)
@@ -239,6 +252,7 @@ test('verifyDaemonStartup returns the existing live daemon when another pid won
         now: () => now,
         readPidfile: () => 7,
         isPidAlive: (pid) => pid === 7,
+        isDaemonServing: async () => true,
         sleepMs: (ms) => {
             slept += ms;
             now += ms;
@@ -276,6 +290,7 @@ test('verifyDaemonStartup throws after its tiny startup window expires', async (
         now: () => now,
         readPidfile: () => null,
         isPidAlive: () => false,
+        isDaemonServing: async () => false,
         sleepMs: (ms) => {
             now += ms;
         },
@@ -299,6 +314,7 @@ test('verifyDaemonStartup throws when the spawned daemon exits before it can bec
     await assert.rejects(async () => verifyDaemonStartup(77, 2_000, {
         readPidfile: () => null,
         isPidAlive: () => false,
+        isDaemonServing: async () => false,
         childExited: () => exited,
     }), /exited before becoming ready \(with exit code 1\)/);
     assert.ok(Date.now() - started < 1_500, 'must fail fast on the real child exit, not run out the window');

package/dist/core/__tests__/daemon-wedge.test.js

@@ -1,41 +1,47 @@
 // Run with: node --import tsx/esm --test src/core/__tests__/daemon-wedge.test.ts
 //
 // Issue #110 — pid-alive WEDGED node detection. The pure decision core:
-// wedgeVerdict(busy, quietForMs, cpuPercent). No wall-clock sleeps, no ps
+// wedgeVerdict(busy, quietForMs, cpuPercent, hasDescendants). No wall-clock sleeps, no ps
 // shell-outs, no fake pids — every input is injected directly, mirroring the
 // yieldStallVerdict truth-table suite in refresh-stall-recycle.test.ts.
 //
-// LOCKS: (1) a routine long-running BUT ACTIVE turn (heartbeat recent, or CPU
-// non-trivial) must never verdict 'wedged' — false positives are the failure
-// mode this feature exists to avoid. (2) only busy+quiet+near-zero-CPU, all at
-// once, past the generous grace, fires. (3) a null/failed CPU sample never
+// LOCKS: (1) a routine long-running turn with a CPU-active subprocess must
+// never verdict 'wedged' — false positives are the failure mode this feature
+// exists to avoid. (2) a childless busy broker that is quiet past grace is
+// wedged even when its own CPU is high. (3) a null/failed CPU sample never
 // fires on its own (fails toward 'pending', not 'wedged').
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { wedgeVerdict, WEDGE_QUIET_MS, WEDGE_CPU_MAX_PERCENT, sumTreeCpu, treeHasDescendants, } from '../../daemon/reconcilers/broker-supervision.js';
 test('wedgeVerdict: a node whose turn already ended is never wedged, regardless of the other signals', () => {
-    assert.equal(wedgeVerdict({ busy: false, quietForMs: null, cpuPercent: null }), 'leave');
-    assert.equal(wedgeVerdict({ busy: false, quietForMs: 10 * 60 * 60_000, cpuPercent: 0 }), 'leave');
+    assert.equal(wedgeVerdict({ busy: false, quietForMs: null, cpuPercent: null, hasDescendants: null }), 'leave');
+    assert.equal(wedgeVerdict({ busy: false, quietForMs: 10 * 60 * 60_000, cpuPercent: 0, hasDescendants: null }), 'leave');
 });
 test('wedgeVerdict: a busy node with an unreadable heartbeat is left alone (not enough evidence)', () => {
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: null, cpuPercent: null }), 'leave');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: null, cpuPercent: null, hasDescendants: null }), 'leave');
 });
 test('wedgeVerdict: routine turns — even long ones — never trip before the grace elapses', () => {
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: 0, cpuPercent: 0 }), 'leave', 'just started');
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: 5 * 60_000, cpuPercent: 0 }), 'leave', 'a routine multi-minute tool call');
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS - 1, cpuPercent: 0 }), 'leave', 'just under the grace, even with 0% cpu');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: 0, cpuPercent: 0, hasDescendants: null }), 'leave', 'just started');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: 5 * 60_000, cpuPercent: 0, hasDescendants: null }), 'leave', 'a routine multi-minute tool call');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS - 1, cpuPercent: 0, hasDescendants: null }), 'leave', 'just under the grace, even with 0% cpu');
 });
 test('wedgeVerdict: past the grace with NO cpu corroboration only pends — never fires on time alone', () => {
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS, cpuPercent: null }), 'pending', 'cpu sample failed/unavailable — never treated as confirmation');
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 10, cpuPercent: null }), 'pending', 'no amount of extra quiet time substitutes for the corroborating signal');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS, cpuPercent: null, hasDescendants: null }), 'pending', 'cpu sample failed/unavailable — never treated as confirmation');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 10, cpuPercent: null, hasDescendants: null }), 'pending', 'no amount of extra quiet time substitutes for the corroborating signal');
 });
-test('wedgeVerdict: a long-quiet turn that is STILL VISIBLY WORKING (real cpu) is exonerated, not wedged', () => {
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 3, cpuPercent: WEDGE_CPU_MAX_PERCENT + 0.1 }), 'pending', 'cpu just above the ceiling — a genuinely churning long build — must not fire');
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 3, cpuPercent: 40 }), 'pending', 'clearly-active cpu never fires regardless of how quiet the heartbeat looks');
+test('wedgeVerdict: high CPU exonerates a broker with descendants but not a childless stalled engine', () => {
+    assert.equal(wedgeVerdict({
+        busy: true,
+        quietForMs: WEDGE_QUIET_MS * 3,
+        cpuPercent: WEDGE_CPU_MAX_PERCENT + 0.1,
+        hasDescendants: true,
+    }), 'pending', 'cpu just above the ceiling — a genuinely churning long build — must not fire');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 3, cpuPercent: 40, hasDescendants: true }), 'pending', 'clearly-active child cpu never fires regardless of how quiet the heartbeat looks');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS * 3, cpuPercent: 40, hasDescendants: false }), 'wedged', 'a childless broker spinning in-process is itself stalled');
 });
-test('wedgeVerdict: fires ONLY when busy + quiet-past-grace + near-zero cpu all corroborate', () => {
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS, cpuPercent: 0 }), 'wedged');
-    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS + 60_000, cpuPercent: WEDGE_CPU_MAX_PERCENT }), 'wedged', 'at the cpu ceiling (inclusive)');
+test('wedgeVerdict: fires when busy + quiet-past-grace + near-zero cpu all corroborate', () => {
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS, cpuPercent: 0, hasDescendants: true }), 'wedged');
+    assert.equal(wedgeVerdict({ busy: true, quietForMs: WEDGE_QUIET_MS + 60_000, cpuPercent: WEDGE_CPU_MAX_PERCENT, hasDescendants: true }), 'wedged', 'at the cpu ceiling (inclusive)');
 });
 // sumTreeCpu (pure) — process-tree CPU sampling. Review fix for issue #110:
 // sampling only the broker pid false-fired on a broker awaiting a busy CHILD