@north-light/crouter 0.3.172 → 0.3.174

package/dist/pi-extensions/__tests__/canvas-recap.test.js

@@ -1,20 +1,18 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-recap.test.ts
+//
+// Failure atomicity: a recap that has been requested but has not produced a
+// briefing yet must leave the pinned recap alone. A regenerating (or failing)
+// recap that cleared the widget first would blank the user's pinned summary.
 import { 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 { registerCanvasRecap } from '../canvas-recap.js';
-import { createNode } from '../../core/canvas/canvas.js';
-import { closeDb } from '../../core/canvas/db.js';
-test('a streaming manual recap snapshots the partial response and replaces the pinned recap only on success', () => {
+test('a recap replaces the pinned widget only when its generation succeeds', () => {
     const originalNodeId = process.env['CRTR_NODE_ID'];
     process.env['CRTR_NODE_ID'] = 'recap-regression-node';
     const handlers = new Map();
     let commandHandler;
     const widgetWrites = [];
-    const notifications = [];
     const generations = [];
-    let idleWaits = 0;
     const recapGenerator = (conversation, finish) => {
         generations.push({ conversation, finish });
     };
@@ -24,133 +22,38 @@ test('a streaming manual recap snapshots the partial response and replaces the p
             commandHandler = options.handler;
         },
     };
-    const sessionManager = {
-        getEntries: () => [{ type: 'message', message: { role: 'user', content: 'Build the recap command.' } }],
-    };
     const ctx = {
         ui: {
             setWidget: (_key, content) => { widgetWrites.push(content); },
-            notify: (message) => { notifications.push(message); },
+            notify: () => undefined,
+        },
+        sessionManager: {
+            getEntries: () => [{ type: 'message', message: { role: 'user', content: 'Build the recap command.' } }],
         },
-        sessionManager,
         model: { provider: 'test', id: 'light' },
         isIdle: () => false,
-        waitForIdle: async () => { idleWaits += 1; },
+        waitForIdle: async () => undefined,
     };
     try {
         registerCanvasRecap(pi, recapGenerator);
         handlers.get('session_start')?.({}, ctx);
         commandHandler?.('', ctx);
-        assert.equal(notifications.at(-1), 'Generating recap…', 'the manually selected command confirms that generation started');
         generations[0]?.finish('Goal: Existing goal\nState: Existing state');
         assert.deepEqual(widgetWrites.at(-1), ['Goal: Existing goal', 'State: Existing state']);
-        assert.equal(notifications.at(-1), 'Recap ready', 'a completed manual recap confirms that the widget was refreshed');
+        // A second recap requested mid-response must not disturb the pinned one
+        // until its own briefing arrives.
         handlers.get('message_update')?.({
             message: { role: 'assistant', content: [{ type: 'text', text: 'I am editing the live implementation now.' }] },
         }, ctx);
         const writesBeforeRequest = widgetWrites.length;
-        const result = commandHandler?.('', ctx);
-        assert.equal(result, undefined, 'the command starts synchronously while the main response is streaming');
-        assert.equal(idleWaits, 0);
-        assert.equal(generations.length, 2);
-        assert.match(generations[1].conversation, /Agent: I am editing the live implementation now\./);
+        commandHandler?.('', ctx);
+        assert.equal(generations.length, 2, 'the second request started its own generation');
         assert.equal(widgetWrites.length, writesBeforeRequest, 'the pinned recap remains while its replacement generates');
-        handlers.get('message_update')?.({
-            message: { role: 'assistant', content: [{ type: 'text', text: 'I am now verifying the implementation.' }] },
-        }, ctx);
         generations[1].finish('Goal: Updated goal\nState: Updated click-time state');
-        assert.deepEqual(widgetWrites.at(-1), ['Goal: Updated goal', 'State: Updated click-time state']);
-    }
-    finally {
-        handlers.get('session_shutdown')?.({}, ctx);
-        if (originalNodeId === undefined)
-            delete process.env['CRTR_NODE_ID'];
-        else
-            process.env['CRTR_NODE_ID'] = originalNodeId;
-    }
-});
-test('review recap and naming input exclude inherited entries while retaining the post-boundary conversation', () => {
-    const originalNodeId = process.env['CRTR_NODE_ID'];
-    const originalHome = process.env['CRTR_HOME'];
-    const home = mkdtempSync(join(tmpdir(), 'crtr-recap-boundary-'));
-    const nodeId = 'review-recap-node';
-    const handlers = new Map();
-    let commandHandler;
-    const widgetWrites = [];
-    const recapInputs = [];
-    const namingInputs = [];
-    let entries = [
-        { type: 'message', message: { role: 'user', content: 'PREBOUNDARY_CANARY inherited request' } },
-        { type: 'message', message: { role: 'assistant', content: 'inherited answer' } },
-        {
-            type: 'custom_message',
-            customType: 'crtr-review-boundary',
-            details: { reviewId: 'review-1' },
-        },
-        { type: 'message', message: { role: 'user', content: 'review-only finding' } },
-        { type: 'message', message: { role: 'assistant', content: 'review-only resolution' } },
-    ];
-    const pi = {
-        on: (event, handler) => { handlers.set(event, handler); },
-        registerCommand: (_name, options) => {
-            commandHandler = options.handler;
-        },
-        getSessionName: () => 'developer',
-        setSessionName: () => undefined,
-    };
-    const sessionManager = { getEntries: () => entries };
-    const ctx = {
-        ui: { setWidget: (_key, content) => { widgetWrites.push(content); } },
-        sessionManager,
-    };
-    const recapGenerator = (conversation) => { recapInputs.push(conversation); };
-    try {
-        closeDb();
-        process.env['CRTR_HOME'] = home;
-        process.env['CRTR_NODE_ID'] = nodeId;
-        createNode({
-            node_id: nodeId,
-            name: 'developer',
-            created: new Date().toISOString(),
-            cwd: '/tmp/work',
-            kind: 'developer',
-            mode: 'base',
-            lifecycle: 'terminal',
-            status: 'active',
-            review_binding: {
-                review_id: 'review-1',
-                origin_node_id: 'origin',
-                branch_file: '/tmp/review.jsonl',
-                target_file: '/tmp/target.ts',
-            },
-        });
-        registerCanvasRecap(pi, recapGenerator, (_id, conversation) => { namingInputs.push(conversation); });
-        handlers.get('session_start')?.({}, ctx);
-        commandHandler?.('', ctx);
-        assert.equal(recapInputs.length, 1);
-        assert.equal(namingInputs.length, 1);
-        for (const input of [...recapInputs, ...namingInputs]) {
-            assert.doesNotMatch(input, /PREBOUNDARY_CANARY/);
-            assert.match(input, /review-only finding/);
-            assert.match(input, /review-only resolution/);
-        }
-        entries = [{ type: 'message', message: { role: 'user', content: 'PREBOUNDARY_CANARY without a boundary' } }];
-        handlers.get('message_update')?.({
-            message: { role: 'assistant', content: 'PREBOUNDARY_CANARY streaming response without a boundary' },
-        }, ctx);
-        commandHandler?.('', ctx);
-        assert.equal(recapInputs.length, 1, 'a markerless review produces no recap input, including a streaming partial');
-        assert.equal(namingInputs.length, 1, 'a markerless review produces no naming input, including a streaming partial');
-        assert.equal(widgetWrites.at(-1), undefined, 'a markerless review clears the recap widget');
+        assert.deepEqual(widgetWrites.at(-1), ['Goal: Updated goal', 'State: Updated click-time state'], 'success replaces the pinned recap');
     }
     finally {
         handlers.get('session_shutdown')?.({}, ctx);
-        closeDb();
-        rmSync(home, { recursive: true, force: true });
-        if (originalHome === undefined)
-            delete process.env['CRTR_HOME'];
-        else
-            process.env['CRTR_HOME'] = originalHome;
         if (originalNodeId === undefined)
             delete process.env['CRTR_NODE_ID'];
         else

package/dist/pi-extensions/__tests__/canvas-stophook-agentend.test.js

@@ -9,7 +9,7 @@
 // Every assertion is on DB / disk effects (report files, inbox pointers) plus
 // the captured sendUserMessage — tmux is unavailable here, so the focus/respawn
 // helpers no-op (TMUX_PANE is cleared) and we drive a clean shutdown path.
-import { test, before, after, beforeEach } from 'node:test';
+import { test, before, after, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, rmSync, existsSync, readdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -18,6 +18,9 @@ import registerCanvasStophook from '../canvas-stophook.js';
 import { createNode, subscribe, getNode, setStatus } from '../../core/canvas/canvas.js';
 import { openFocusRow, getFocusByNode, getFocusById, listFocuses } from '../../core/canvas/focuses.js';
 import { closeDb } from '../../core/canvas/db.js';
+import { apiSocketPath } from '../../core/canvas/paths.js';
+import { createApiServer } from '../../daemon/api/server.js';
+import { CrtrClient } from '../../api/client.js';
 import { reportsDir } from '../../core/canvas/paths.js';
 import { readInboxSince, appendInbox } from '../../core/feed/inbox.js';
 import { STALL_REPROMPT } from '../../core/runtime/stop-guard.js';
@@ -25,6 +28,7 @@ import { markStopSignal } from '../../core/runtime/stop-signals.js';
 import { isBusy } from '../../core/runtime/busy.js';
 import { recordFault, readFault } from '../../core/runtime/fault.js';
 let home;
+let server;
 let origNode;
 let origPane;
 function node(id, over = {}) {
@@ -46,12 +50,12 @@ function makeFakePi() {
         injected: [],
         on(e, h) { handlers[e] = h; },
         sendUserMessage(content, options) { this.injected.push({ content, deliverAs: options?.deliverAs }); },
-        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+        async fire(e, ev, ctx) { await handlers[e]?.(ev, ctx); },
     };
 }
-function settle(pi, event, ctx) {
-    pi.fire('agent_end', event, ctx);
-    pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
+async function settle(pi, event, ctx) {
+    await pi.fire('agent_end', event, ctx);
+    await pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
 }
 /** A natural-stop agent_end event carrying one assistant text block. */
 function stopEvent(text) {
@@ -66,16 +70,39 @@ before(() => {
     origNode = process.env['CRTR_NODE_ID'];
     origPane = process.env['TMUX_PANE'];
 });
-beforeEach(() => {
+async function waitForSocket() {
+    const probe = CrtrClient.forLocalSocket({ autostart: false });
+    for (let i = 0; i < 200; i++) {
+        if (existsSync(apiSocketPath())) {
+            try {
+                await probe.healthz();
+                return;
+            }
+            catch {
+                // The socket path appears before the in-process server accepts requests.
+            }
+        }
+        await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+    throw new Error(`api socket never answered at ${apiSocketPath()}`);
+}
+beforeEach(async () => {
     closeDb();
     if (home)
         rmSync(home, { recursive: true, force: true });
     home = mkdtempSync(join(tmpdir(), 'crtr-stophook-end-'));
     process.env['CRTR_HOME'] = home;
+    server = createApiServer();
+    await waitForSocket();
     // Force the clean-shutdown path (no in-place respawn) so the refresh test is
     // deterministic even when the suite runs inside a tmux pane.
     delete process.env['TMUX_PANE'];
 });
+afterEach(async () => {
+    await server?.close();
+    server = undefined;
+    closeDb();
+});
 after(() => {
     closeDb();
     if (home)
@@ -90,7 +117,7 @@ after(() => {
     else
         process.env['TMUX_PANE'] = origPane;
 });
-test('natural stop commits idle-release only at agent_settled', { timeout: 1_000 }, () => {
+test('natural stop commits idle-release only at agent_settled', { timeout: 1_000 }, async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
     createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
@@ -101,12 +128,12 @@ test('natural stop commits idle-release only at agent_settled', { timeout: 1_000
     registerCanvasStophook(pi);
     let shutdown = false;
     const ctx = { shutdown: () => { shutdown = true; } };
-    pi.fire('agent_start', { type: 'agent_start' }, ctx);
-    pi.fire('agent_end', stopEvent('still waiting on the worker'), ctx);
+    await pi.fire('agent_start', { type: 'agent_start' }, ctx);
+    await pi.fire('agent_end', stopEvent('still waiting on the worker'), ctx);
     assert.equal(getNode('mgr')?.status, 'active', 'agent_end is staging-only');
     assert.equal(isBusy('mgr'), true, 'agent_end cannot clear whole-run busy state');
     assert.equal(shutdown, false, 'agent_end cannot route a natural stop');
-    pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
+    await pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
     const m = getNode('mgr');
     assert.equal(isBusy('mgr'), false, 'agent_settled clears whole-run busy state');
     assert.equal(m?.intent, 'idle-release', 'mgr idle-released');
@@ -120,7 +147,7 @@ test('natural stop commits idle-release only at agent_settled', { timeout: 1_000
     // the done-branch handoff/openFocus on an idle-release would leave a row here.
     assert.equal(listFocuses().length, 0, 'awaiting+unfocused leaves the focuses table empty');
 });
-test('gh-451: idle-release does NOT release while a non-deferred inbox entry sits past the cursor', { timeout: 1_000 }, () => {
+test('gh-451: idle-release does NOT release while a non-deferred inbox entry sits past the cursor', { timeout: 1_000 }, async () => {
     // Reproduces the #451 race: a subscriber's push landed in mgr's inbox but the
     // in-process watcher has not yet flushed/committed the durable cursor past it
     // (its DEBOUNCE_MS hold). If this settle released anyway, the daemon would
@@ -138,12 +165,12 @@ test('gh-451: idle-release does NOT release while a non-deferred inbox entry sit
     registerCanvasStophook(pi);
     let shutdown = false;
     const ctx = { shutdown: () => { shutdown = true; } };
-    settle(pi, stopEvent('still waiting on the worker'), ctx);
+    await settle(pi, stopEvent('still waiting on the worker'), ctx);
     assert.equal(getNode('mgr')?.status, 'active', 'mgr stays active — NOT idle-released while behind the cursor');
     assert.equal(getNode('mgr')?.intent ?? null, null, 'no idle-release intent while a non-deferred entry is unseen');
     assert.equal(shutdown, false, 'pi stays alive so the in-process watcher can still deliver/commit');
 });
-test('gh-451: finished does NOT shut down while a non-deferred inbox entry sits past the cursor', { timeout: 1_000 }, () => {
+test('gh-451: finished does NOT shut down while a non-deferred inbox entry sits past the cursor', { timeout: 1_000 }, async () => {
     // A canonical final can settle while the in-process watcher has delivered a
     // child report into the inbox but has not yet committed the durable cursor.
     // The finished branch must keep this broker alive for that delivery.
@@ -154,12 +181,12 @@ test('gh-451: finished does NOT shut down while a non-deferred inbox entry sits
     registerCanvasStophook(pi);
     let shutdown = false;
     const ctx = { shutdown: () => { shutdown = true; } };
-    settle(pi, stopEvent('already finalized'), ctx);
+    await settle(pi, stopEvent('already finalized'), ctx);
     assert.equal(getNode('mgr')?.status, 'active', 'mgr stays active while the watcher catches up');
     assert.equal(getNode('mgr')?.intent ?? null, null, 'no idle-release intent while a non-deferred entry is unseen');
     assert.equal(shutdown, false, 'pi stays alive so the in-process watcher can still deliver/commit');
 });
-test('gh-451: a DEFERRED-only unseen entry does not block idle-release (matches the daemon\'s own wake gate)', { timeout: 1_000 }, () => {
+test('gh-451: a DEFERRED-only unseen entry does not block idle-release (matches the daemon\'s own wake gate)', { timeout: 1_000 }, async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
     createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
@@ -171,26 +198,26 @@ test('gh-451: a DEFERRED-only unseen entry does not block idle-release (matches
     registerCanvasStophook(pi);
     let shutdown = false;
     const ctx = { shutdown: () => { shutdown = true; } };
-    settle(pi, stopEvent('still waiting on the worker'), ctx);
+    await settle(pi, stopEvent('still waiting on the worker'), ctx);
     assert.equal(getNode('mgr')?.intent, 'idle-release', 'a deferred-only unseen entry does not block release (#341 parity)');
     assert.equal(getNode('mgr')?.status, 'idle');
     assert.equal(shutdown, true, 'pi shuts down — deferred entries ride the next natural cycle, not this settle');
 });
-test('queued continuation finishes before natural-stop routing commits', { timeout: 1_000 }, () => {
+test('queued continuation finishes before natural-stop routing commits', { timeout: 1_000 }, async () => {
     createNode(node('leaf', { parent: null, lifecycle: 'terminal' }));
     process.env['CRTR_NODE_ID'] = 'leaf';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
     let shutdown = false;
     const ctx = { shutdown: () => { shutdown = true; } };
-    pi.fire('agent_start', { type: 'agent_start' }, ctx);
-    pi.fire('agent_end', stopEvent('first attempt ended while a continuation was queued'), ctx);
+    await pi.fire('agent_start', { type: 'agent_start' }, ctx);
+    await pi.fire('agent_end', stopEvent('first attempt ended while a continuation was queued'), ctx);
     assert.equal(shutdown, false, 'the intermediate agent_end cannot route a natural stop');
     assert.equal(getNode('leaf')?.status, 'active');
     setStatus('leaf', 'done');
-    pi.fire('agent_start', { type: 'agent_start' }, ctx);
-    pi.fire('agent_end', stopEvent('queued continuation completed the assignment'), ctx);
-    pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
+    await pi.fire('agent_start', { type: 'agent_start' }, ctx);
+    await pi.fire('agent_end', stopEvent('queued continuation completed the assignment'), ctx);
+    await pi.fire('agent_settled', { type: 'agent_settled' }, ctx);
     assert.equal(shutdown, true, 'settlement routes from the completed continuation');
     assert.equal(getNode('leaf')?.intent ?? null, null, 'the intermediate natural stop never idle-released the node');
 });
@@ -201,42 +228,12 @@ test('queued continuation finishes before natural-stop routing commits', { timeo
 // used by the handler now GC-prunes a viewer row whose pane is not a LIVE tmux
 // pane (liveOrPrune → paneExists), so a fabricated '%pane' id is pruned on the
 // first read. To drive the handler's focus path deterministically in the
-// tmux-free fast tier we register viewer rows with a NULL pane (a registered-
+// tmux-free ordinary suite we register viewer rows with a NULL pane (a registered-
 // but-not-yet-realized viewer, which liveOrPrune passes through). status='done'
 // is reached by setting the runtime row directly (the branch reads
 // getNode(nodeId).status).
 // ---------------------------------------------------------------------------
-test('§5.1.1 truly-done + focused → focus row CLOSED, NO manager takeover (broker cut deleted handFocusToManager)', () => {
-    // Regression guard for the broker-host cut: the engine is now a detached
-    // broker, not a pane, so there is no engine to hand to a manager. The old
-    // "dormant idle-release manager takes over the finished node's focus row"
-    // path (handFocusToManager) is DELETED — a truly-done focused node just
-    // tearDownNode's its own viewer and shuts down, EVEN when a dormant
-    // idle-release manager exists (the exact case that used to trigger takeover).
-    createNode(node('root', { parent: null, lifecycle: 'resident' }));
-    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator', status: 'idle', intent: 'idle-release' }));
-    // M starts WITH a recorded LOCATION so the done-path presence-null is observable.
-    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal', pane: '%m', tmux_session: 'Suser', window: '@wm' }));
-    subscribe('mgr', 'M', true);
-    openFocusRow('fM', null, 'Suser', 'M'); // null pane → focusOf returns it → drives tearDownNode
-    process.env['CRTR_NODE_ID'] = 'M';
-    setStatus('M', 'done'); // pushed final this turn
-    const pi = makeFakePi();
-    registerCanvasStophook(pi);
-    let shutdown = false;
-    settle(pi, stopEvent('done — pushed final'), { shutdown: () => { shutdown = true; } });
-    // The done branch: focusOf('M') != null → tearDownNode('M') CLOSES fM. The
-    // manager is NOT handed anything (takeover deleted). Non-vacuous: a takeover
-    // impl would leave getFocusByNode('mgr').focus_id === 'fM'.
-    assert.equal(getFocusByNode('mgr'), null, 'the manager is NOT handed the finished node\'s focus (takeover deleted)');
-    assert.equal(getFocusById('fM'), null, 'the finished node\'s viewer focus row is closed');
-    assert.equal(getFocusByNode('M'), null, 'the finished node no longer occupies any focus');
-    assert.equal(shutdown, true, 'pi shut down after teardown');
-    // The done node's own presence is nulled (setPresence(null) on the done path).
-    assert.equal(getNode('M')?.pane ?? null, null, 'the finished node\'s own LOCATION pane is nulled');
-    assert.equal(getNode('M')?.window ?? null, null, 'the finished node\'s window presence is nulled too');
-});
-test('§5.1.2 truly-done + focused + NO manager (root) → focus row CLOSED (Q1)', () => {
+test('§5.1.2 truly-done + focused → focus row CLOSED, own presence nulled (Q1)', async () => {
     // R carries a LOCATION so the close-path presence-null is observable.
     createNode(node('R', { parent: null, lifecycle: 'terminal', pane: '%r', tmux_session: 'Suser', window: '@wr' }));
     openFocusRow('fR', '%r', 'Suser', 'R');
@@ -244,40 +241,16 @@ test('§5.1.2 truly-done + focused + NO manager (root) → focus row CLOSED (Q1)
     setStatus('R', 'done');
     const pi = makeFakePi();
     registerCanvasStophook(pi);
-    settle(pi, stopEvent('root done'), { shutdown: () => { } });
-    // managerId = R.parent(null) ?? subscribersOf(R)[0](none) = null →
-    // handFocusToManager returns false → the close path: closeFocusRow(fR) +
+    await settle(pi, stopEvent('root done'), { shutdown: () => { } });
+    // The done branch closes the viewer row: closeFocusRow(fR) +
     // setRemainOnExit(%r's window, false) (return-to-shell) + null R's presence.
-    // Non-vacuous: a takeover-instead-of-close impl would leave the row present;
-    // an impl that skips the MINOR presence-null leaves getNode('R').pane === '%r'.
-    assert.equal(getFocusById('fR'), null, 'a manager-less finished focus is closed, not handed off');
+    // Non-vacuous: an impl that leaves the row open keeps it present; one that
+    // skips the presence-null leaves getNode('R').pane === '%r'.
+    assert.equal(getFocusById('fR'), null, 'a finished node\'s focus row is closed');
     assert.equal(listFocuses().length, 0, 'no focus rows survive');
     assert.equal(getNode('R')?.pane ?? null, null, 'the finished root\'s own LOCATION pane is nulled (close path reaps)');
 });
-test('§5.1.3 truly-done + focused + manager ALREADY focused elsewhere → focus CLOSED, manager UNMOVED', () => {
-    createNode(node('root', { parent: null, lifecycle: 'resident' }));
-    createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
-    createNode(node('M', { parent: 'mgr', lifecycle: 'terminal', pane: '%m', tmux_session: 'Sa', window: '@wm' }));
-    subscribe('mgr', 'M', true);
-    openFocusRow('fOther', '%o', 'Sb', 'mgr'); // mgr already on its OWN viewport
-    openFocusRow('fM', '%m', 'Sa', 'M');
-    process.env['CRTR_NODE_ID'] = 'M';
-    setStatus('M', 'done');
-    const pi = makeFakePi();
-    registerCanvasStophook(pi);
-    settle(pi, stopEvent('M done'), { shutdown: () => { } });
-    // handFocusToManager sees getFocusByNode('mgr') != null → returns false →
-    // closeFocusRow(fM). Non-vacuous: moving mgr would either repoint its focus_id
-    // to fM (and a wrong impl that didn't close fM would leave it present) or throw
-    // UNIQUE(node_id); this pins mgr's OTHER focus untouched and M's focus gone.
-    assert.equal(getFocusById('fM'), null, "M's focus is closed");
-    assert.equal(getFocusByNode('mgr')?.focus_id, 'fOther', "the manager's other viewport is NOT stolen");
-    // MINOR: M (done) is reaped on the close path — its own presence nulled.
-    // Non-vacuous: an impl that skips the done-path setPresence-null leaves
-    // getNode('M').pane === '%m'.
-    assert.equal(getNode('M')?.pane ?? null, null, "the finished node's own LOCATION pane is nulled");
-});
-test('§5.1.4 truly-done + UNFOCUSED → no focus row created/touched, shuts down (Invariant P)', () => {
+test('§5.1.4 truly-done + UNFOCUSED → no focus row created/touched, shuts down (Invariant P)', async () => {
     createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
     createNode(node('M', { parent: 'mgr', lifecycle: 'terminal' }));
     subscribe('mgr', 'M', true);
@@ -286,28 +259,28 @@ test('§5.1.4 truly-done + UNFOCUSED → no focus row created/touched, shuts dow
     const pi = makeFakePi();
     registerCanvasStophook(pi);
     let shutdown = false;
-    settle(pi, stopEvent('done, never had a viewport'), { shutdown: () => { shutdown = true; } });
+    await settle(pi, stopEvent('done, never had a viewport'), { shutdown: () => { shutdown = true; } });
     // focusOf(M) is null → the focus block is skipped entirely → just shutdown.
     // Non-vacuous: an impl that created or handed off a focus row would leave
     // listFocuses non-empty.
     assert.equal(shutdown, true, 'an unfocused done node shuts down');
     assert.equal(listFocuses().length, 0, 'no focus row was created or touched');
 });
-test('§5.1.5 awaiting + FOCUSED → STAY ALIVE: pi keeps running (no release), focus row untouched (F3)', () => {
+test('§5.1.5 awaiting + FOCUSED → STAY ALIVE: pi keeps running (no release), focus row untouched (F3)', async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('mgr', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator' }));
     createNode(node('worker', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
     subscribe('root', 'mgr', true);
     subscribe('mgr', 'worker', true); // mgr awaits a live worker → would idle-release if UNfocused
     // null pane (broker cut): focusOf passes a null-pane viewer row through, so the
-    // handler reads mgr as FOCUSED in the tmux-free fast tier (a fabricated %pane
+    // handler reads mgr as FOCUSED in the tmux-free ordinary suite (a fabricated %pane
     // would be GC-pruned by liveOrPrune and the node would wrongly release).
     openFocusRow('fMgr', null, 'Suser', 'mgr');
     process.env['CRTR_NODE_ID'] = 'mgr';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
     let shutdown = false;
-    settle(pi, stopEvent('still waiting on the worker'), { shutdown: () => { shutdown = true; } });
+    await settle(pi, stopEvent('still waiting on the worker'), { shutdown: () => { shutdown = true; } });
     // A FOCUSED awaiting node holds the user's viewport, so the awaiting branch
     // keeps pi LIVE and dormant (the in-process inbox-watcher wakes it) instead of
     // releasing + shutting down. It must NOT release, NOT shut down, and NOT touch
@@ -318,14 +291,14 @@ test('§5.1.5 awaiting + FOCUSED → STAY ALIVE: pi keeps running (no release),
     assert.equal(shutdown, false, 'a focused awaiting node is NOT shut down — pi stays live');
     assert.equal(getFocusByNode('mgr')?.focus_id, 'fMgr', 'the focus row is UNCHANGED — not closed, not handed off');
 });
-test('§5.1.7 resident attended (no live subs) → nothing happens; focus + status survive', () => {
+test('§5.1.7 resident attended (no live subs) → nothing happens; focus + status survive', async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     openFocusRow('fR', '%r', 'Suser', 'root');
     process.env['CRTR_NODE_ID'] = 'root';
     const pi = makeFakePi();
     registerCanvasStophook(pi);
     let shutdown = false;
-    settle(pi, stopEvent('I have wrapped up'), { shutdown: () => { shutdown = true; } });
+    await settle(pi, stopEvent('I have wrapped up'), { shutdown: () => { shutdown = true; } });
     // evaluateStop on a resident → reason 'dormant' (NOT 'awaiting'), so the
     // awaiting branch is skipped and the handler does nothing: no release, no
     // shutdown, no focus touch. Non-vacuous: an impl that idle-released a resident
@@ -336,7 +309,7 @@ test('§5.1.7 resident attended (no live subs) → nothing happens; focus + stat
     assert.equal(getFocusByNode('root')?.focus_id, 'fR', 'focus row survives untouched');
     assert.equal(shutdown, false, 'a resident attended node is not shut down');
 });
-test('refresh-yield (intent=refresh) writes NO push — silent to subscribers', () => {
+test('refresh-yield (intent=refresh) writes NO push — silent to subscribers', async () => {
     createNode(node('root', { parent: null, lifecycle: 'resident' }));
     createNode(node('orch', { parent: 'root', lifecycle: 'terminal', mode: 'orchestrator', intent: 'refresh' }));
     subscribe('root', 'orch', true);
@@ -344,7 +317,7 @@ test('refresh-yield (intent=refresh) writes NO push — silent to subscribers',
     const pi = makeFakePi();
     registerCanvasStophook(pi);
     let shutdown = false;
-    settle(pi, stopEvent('checkpoint before refreshing'), { shutdown: () => { shutdown = true; } });
+    await settle(pi, stopEvent('checkpoint before refreshing'), { shutdown: () => { shutdown = true; } });
     assert.equal(shutdown, true, 'pi shut down (no tmux pane → clean shutdown)');
     assert.equal(reportCount('orch'), 0, 'a yield is silent: NO report file');
     assert.equal(readInboxSince('root').length, 0, 'a yield is silent: NO inbox pointer');
@@ -390,19 +363,19 @@ test('turn_end still clears a daemon→node wedge fault (existing behavior, unch
     pi.fire('turn_end', turnEndEvent('turn completed'), {});
     assert.equal(readFault('leaf'), null, 'the daemon→node wedge fault is still cleared at turn_end');
 });
-test('a successful final or human ask suppresses the stop reprompt without a canvas read', () => {
+test('a successful final or human ask suppresses the stop reprompt without a canvas read', async () => {
     for (const [signal, shutsDown] of [['pushedFinal', true], ['askedHuman', false]]) {
         process.env['CRTR_NODE_ID'] = 'signal-only';
         markStopSignal('signal-only', signal);
         const pi = makeFakePi();
         registerCanvasStophook(pi);
         let shutdown = false;
-        settle(pi, stopEvent(`completed ${signal}`), { shutdown: () => { shutdown = true; } });
+        await settle(pi, stopEvent(`completed ${signal}`), { shutdown: () => { shutdown = true; } });
         assert.equal(pi.injected.length, 0, `${signal} does not re-prompt when the broker cannot read its node`);
         assert.equal(shutdown, shutsDown, `${signal} takes its expected settled action`);
     }
 });
-test('an in-run retry (agent_start with no new input) does not erase this run\'s stop signal', () => {
+test('an in-run retry (agent_start with no new input) does not erase this run\'s stop signal', async () => {
     // Regression: pi re-fires agent_start for automatic retries and post-compaction
     // continuations WITHIN one run. Clearing the marker there erased the ask/final
     // recorded earlier in the same run, so settlement fell back to a canvas read
@@ -418,15 +391,15 @@ test('an in-run retry (agent_start with no new input) does not erase this run\'s
     pi.fire('agent_start', { type: 'agent_start' }, ctx);
     markStopSignal('leaf', 'askedHuman'); // the node ran `crtr human ask` mid-run
     pi.fire('agent_start', { type: 'agent_start' }, ctx); // pi auto-retried after a provider error
-    settle(pi, stopEvent('waiting on the human now'), ctx);
+    await settle(pi, stopEvent('waiting on the human now'), ctx);
     assert.equal(pi.injected.length, 0, 'the ask survives the in-run retry — no stall reprompt');
     // ...and the NEXT user-directed run does start clean.
     markStopSignal('leaf', 'askedHuman');
     pi.fire('input', { type: 'input' }, ctx);
-    settle(pi, stopEvent('I think I am basically done here'), ctx);
+    await settle(pi, stopEvent('I think I am basically done here'), ctx);
     assert.equal(pi.injected.length, 1, 'a new input discards a leftover marker from a prior run');
 });
-test('stalled leaf (nothing live to await, no final) is still reprompted', () => {
+test('stalled leaf (nothing live to await, no final) is still reprompted', async () => {
     createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
     createNode(node('leaf', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));
     subscribe('mgr', 'leaf', true); // mgr subscribes to leaf; leaf itself awaits nothing
@@ -434,7 +407,7 @@ test('stalled leaf (nothing live to await, no final) is still reprompted', () =>
     const pi = makeFakePi();
     registerCanvasStophook(pi);
     let shutdown = false;
-    settle(pi, stopEvent('I think I am basically done here'), { shutdown: () => { shutdown = true; } });
+    await settle(pi, stopEvent('I think I am basically done here'), { shutdown: () => { shutdown = true; } });
     assert.equal(pi.injected.length, 1, 'the stall reprompt fired');
     assert.equal(pi.injected[0].content, STALL_REPROMPT, 'reprompt carries the stall nudge to push final / ask');
     assert.equal(pi.injected[0].deliverAs, 'followUp', 'reprompt delivered as a followUp');