@north-light/crouter 0.3.173 → 0.3.175

package/dist/pi-extensions/canvas-stophook.js

@@ -12,50 +12,26 @@
 //   turn_end — accumulate token usage and flush telemetry.json under the node's
 //              job/ dir so the dashboard shows live counts.
 //
-//   agent_end — stage the completed attempt for Pi's settlement boundary.
+//   agent_end — stage the latest Pi attempt for Pi's settlement boundary.
 //
-//   agent_settled — decide what happens after recovery and queued continuations:
-//     (a) stopReason is 'aborted' or 'error' → stay alive for re-steering; return.
-//     (b) node.status is already 'done' (agent called `crtr push --final` this
-//         turn, which sets status synchronously) → shut down; work is complete.
-//     (c) Natural stop ('stop' | 'length') — run the stop-guard (the node is
-//         NEVER auto-pushed; it reports only via its own explicit `crtr push`):
-//           • 'reprompt' → pi.sendUserMessage so the node finishes or escalates.
-//           • 'allow' (awaiting) → stay dormant when focused; otherwise release
-//                          and shut down. A subscribed node, controller, or
-//                          background bash job delivers the inbox wake.
-//           • 'allow' (attended root) → stay alive, dormant; the human wakes it.
+//   agent_settled — report Pi-only stop facts to crtrd, then enact its one
+//                   returned directive: follow-up reprompt, stay dormant, or
+//                   shut down. crtrd owns every stop-policy and canvas effect.
 //
 // Plain TS-with-types — no imports from @earendil-works/* so this compiles inside
 // crouter's own tsc build without a dep on the pi packages.
 import { writeFileSync, mkdirSync, existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { getNode, jobDir, updateNode, recordPid, setPresence } from '../core/canvas/index.js';
-import { transition } from '../core/runtime/lifecycle.js';
-import { markBusy, clearBusy, touchBusy, isBusy } from '../core/runtime/busy.js';
-import { clearFault, readFault } from '../core/runtime/fault.js';
-import { nextFaultRetry } from '../core/runtime/fault-recovery.js';
-import { evaluateStop } from '../core/runtime/stop-guard.js';
-import { personaDrift, commitPersonaAck } from '../core/runtime/persona.js';
-import { clearYieldMessage } from '../core/runtime/kickoff.js';
-import { handleNewSession, markCleanExitDone } from '../core/runtime/reset.js';
+import { contextDir, jobDir } from '../core/canvas/paths.js';
+import { markBusy, clearBusy, touchBusy } from '../core/runtime/busy.js';
+import { clearFault } from '../core/runtime/fault.js';
+import { personaDriftFromBrokerState } from '../core/runtime/broker-persona-guidance.js';
 import { clearStopSignals, consumeStopSignals } from '../core/runtime/stop-signals.js';
-import { cliClient } from '../commands/api-client.js';
-import { focusOf, tearDownNode } from '../core/runtime/placement.js';
-import { readCursor, readInboxSince } from '../core/feed/inbox.js';
+import { bindBrokerSession, brokerExtensionState, commitBrokerPersonaAck, relaunchBrokerRoot, settleBroker } from '../core/runtime/broker/daemon-ops.js';
+import { emitEvent } from '../core/events/emit.js';
+import { activeBackgroundBashJobs } from '../core/bash-jobs.js';
 import { CONTEXT_NUDGE_CUSTOM_TYPE, formatContextNudge, formatPersonaTransition } from '../shared/generated-context.js';
 import { isReviewBoundary } from '../core/runtime/session-visibility.js';
-/** Universal upper bound for an unfocused broker parked without runnable work. */
-export const UNATTENDED_PARK_MS = (() => {
-    const testOverride = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
-    if (testOverride === undefined)
-        return 15 * 60_000;
-    const parsed = Number(testOverride);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : 15 * 60_000;
-})();
-/** Production cadence for the bounded-release clock. A shorter test bound also
- * shortens the cadence, so the full-tier regression need not sleep for a minute. */
-export const PARK_POLL_MS = Math.min(60_000, UNATTENDED_PARK_MS);
 /** Condense a tool call into one short line for the activity cue. Picks the most
  *  identifying arg (command / path / pattern / description), collapses whitespace,
  *  and hard-caps the length so a giant bash command can't bloat telemetry.json. */
@@ -115,6 +91,32 @@ function lastAssistantMessage(messages) {
     }
     return undefined;
 }
+/** Review markers present in Pi's current branch. The broker reports only this
+ * Pi-owned fact; crtrd compares it with the node's daemon-owned review binding. */
+function currentReviewBoundaryIds(ctx) {
+    try {
+        const manager = ctx?.sessionManager;
+        const entries = typeof manager?.getBranch === 'function'
+            ? manager.getBranch()
+            : typeof manager?.getEntries === 'function'
+                ? manager.getEntries()
+                : [];
+        if (!Array.isArray(entries))
+            return [];
+        const ids = new Set();
+        for (const entry of entries) {
+            if (!isReviewBoundary(entry))
+                continue;
+            const reviewId = entry.details?.reviewId;
+            if (typeof reviewId === 'string')
+                ids.add(reviewId);
+        }
+        return [...ids];
+    }
+    catch {
+        return [];
+    }
+}
 // ---------------------------------------------------------------------------
 // Context-size steering bands — a single shared schedule of thresholds that
 // ESCALATE in tone as input context grows. The first band is a gentle
@@ -267,79 +269,28 @@ export function registerCanvasStophook(pi) {
     // yield --promote only when worthwhile independent work can run in parallel);
     // a terminal worker to yield-or-push-final.
     const firedBands = new Set();
-    // Every broker enters this bounded-release path at session_start, including a
-    // boot-revived settled node that never produces another agent_settled event.
-    // Focus, real work, pending inbox delivery, and bounded in-process fault retry
-    // justify parking; anything else gets at most UNATTENDED_PARK_MS before the
-    // existing release transition + shutdown path makes it process-free.
-    let sessionBound = false;
-    let agentRunning = false;
-    let parkedSince = null;
-    let parkTimer = null;
-    let parkContext = null;
-    const resetParkClock = () => { parkedSince = null; };
-    const hasActiveAutoFaultRetry = (now) => {
-        const fault = readFault(nodeId);
-        if (fault === null || fault.retry.disposition !== 'auto' || fault.retry.by !== 'daemon')
-            return false;
-        if (fault.kind !== 'connection' && fault.kind !== 'rate-limit' && fault.kind !== 'overloaded')
-            return false;
-        return fault.retry.nextAt !== undefined || nextFaultRetry(fault, now) !== null;
+    const backgroundJobsRunning = () => activeBackgroundBashJobs(contextDir(nodeId)).length > 0;
+    const emitDaemonOperationFailure = (operation, error) => {
+        emitEvent({
+            event: 'broker.daemon.operation.failed',
+            level: 'error',
+            node_id: nodeId,
+            error,
+            fields: { operation },
+        });
     };
-    const pollParkClock = () => {
-        try {
-            if (!sessionBound || agentRunning || parkContext === null) {
-                resetParkClock();
-                return;
-            }
-            const row = getNode(nodeId);
-            if (row === null || row.intent !== null || row.status === 'done' || row.status === 'canceled' || row.status === 'dead') {
-                resetParkClock();
-                return;
-            }
-            if (isBusy(nodeId)) {
-                resetParkClock();
-                return;
-            }
-            if (focusOf(nodeId) !== null) {
-                resetParkClock();
-                return;
-            }
-            if (readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred')) {
-                resetParkClock();
-                return;
-            }
-            const now = Date.now();
-            if (hasActiveAutoFaultRetry(now)) {
-                resetParkClock();
-                return;
-            }
-            parkedSince ??= now;
-            if (now - parkedSince < UNATTENDED_PARK_MS)
-                return;
-            transition(nodeId, 'release');
-            resetParkClock();
+    const enactSettleDirective = (directive, ctx) => {
+        if (directive.action === 'reprompt') {
+            pi.sendUserMessage(directive.prompt, { deliverAs: 'followUp' });
+            return;
+        }
+        if (directive.action === 'shutdown') {
             try {
-                parkContext?.shutdown?.();
+                ctx?.shutdown?.();
             }
-            catch { /* best-effort */ }
-        }
-        catch {
-            // A policy read failure must stay visible on the next poll rather than
-            // releasing from incomplete evidence.
-            resetParkClock();
+            catch { /* Pi shutdown is local best-effort */ }
         }
     };
-    const armParkClock = (ctx) => {
-        sessionBound = true;
-        parkContext = ctx;
-        resetParkClock();
-        if (parkTimer !== null)
-            return;
-        parkTimer = setInterval(pollParkClock, PARK_POLL_MS);
-        if (typeof parkTimer.unref === 'function')
-            parkTimer.unref();
-    };
     // Wedge-heartbeat throttle: message_update/tool_execution_update can fire many
     // times per second while streaming, and touchBusy is a disk write — rate-limit
     // it to at most once per HEARTBEAT_THROTTLE_MS. The daemon's wedge grace is
@@ -374,15 +325,11 @@ export function registerCanvasStophook(pi) {
     // looks identical to a boot. The event reason is delivered fresh on every fire
     // and is immune to the re-activation.
     //
-    // `/new` splits by who ran it: a ROOT relaunches into a genuinely new node
-    // (relaunchRoot — park the old root `done`, boot a fresh node, re-point this
-    // pane), a non-root CHILD just refreshes its session id (handleNewSession).
+    // `/new` splits by who ran it: crtrd derives rootness from the node row and
+    // either directs a root relaunch or resets a child's session coordinates.
     // ---------------------------------------------------------------------------
-    pi.on('session_start', (event, ctx) => {
+    pi.on('session_start', async (event, ctx) => {
         try {
-            // This clock bounds every boot, including one whose durable bookkeeping
-            // below fails transiently; never leave it behind a swallowed handler error.
-            armParkClock(ctx);
             const id = ctx?.sessionManager?.getSessionId?.();
             if (typeof id !== 'string' || id === '')
                 return;
@@ -391,93 +338,55 @@ export function registerCanvasStophook(pi) {
             // whereas a bare id is resolved cwd-relative and forks across projects.
             const filed = ctx?.sessionManager?.getSessionFile?.();
             const sessionFile = typeof filed === 'string' && filed !== '' ? filed : null;
-            const existing = getNode(nodeId);
-            const reviewId = existing?.review_binding?.review_id;
-            if (reviewId !== undefined) {
-                let hasBoundary = false;
-                try {
-                    const manager = ctx?.sessionManager;
-                    const entries = typeof manager?.getBranch === 'function'
-                        ? manager.getBranch()
-                        : typeof manager?.getEntries === 'function'
-                            ? manager.getEntries()
-                            : [];
-                    hasBoundary = entries.some((entry) => isReviewBoundary(entry, reviewId));
-                }
-                catch {
-                    hasBoundary = false;
-                }
-                if (!hasBoundary) {
-                    try {
-                        ctx?.shutdown?.();
-                    }
-                    catch { /* best-effort */ }
-                    return;
-                }
-            }
-            // `/new` — a brand-new conversation in the same process. The broker already
-            // drove the engine-side new_session (the viewer's /new → broker
-            // new_session frame); the runtime side then splits on root-ness: a ROOT
-            // relaunches into a freshly-minted node (park the old root `done`, boot a
-            // new broker, re-point the viewer pane), a non-root CHILD just refreshes
-            // its session id on the SAME node.
-            if (event?.reason === 'new') {
-                try {
-                    // A root relaunch LAUNCHES a broker, and launches are daemon-owned
-                    // (fleet-bound) — so the broker never runs relaunchRoot in-process.
-                    // It asks crtrd via POST /v1/nodes/:id/relaunch-root instead; the
-                    // rejection is swallowed here (the enclosing sync catch can't catch
-                    // an async one) to keep `/new` best-effort.
-                    if (existing?.parent == null)
-                        void cliClient().relaunchRoot(nodeId).catch(() => { });
-                    else
-                        handleNewSession(nodeId, id, sessionFile);
-                }
-                catch { /* best-effort */ }
-                // Clear in-memory context-steering so the fresh conversation starts clean.
+            const reason = typeof event?.reason === 'string' ? event.reason : null;
+            // Pi has already swapped to the fresh conversation. Its local steering
+            // counters reset independently of the durable root/child consequence.
+            if (reason === 'new') {
                 totalIn = 0;
                 totalOut = 0;
                 firedBands.clear();
-                return;
             }
-            // Boot / startup / resume / reload / fork → (re)bind this process to its
-            // session id, record our OS pid (the daemon's broker-liveness signal), and
-            // CONFIRM any pending refresh-yield / pending cycle. Reaching session_start
-            // proves a fresh engine actually booted, so it is now safe to clear
-            // intent='refresh' — a refresh shuts the broker down and the daemon
-            // relaunches it FRESH, which leaves intent='refresh' set until this boot
-            // clears it (the only proof the relaunch worked; otherwise a failed relaunch
-            // would look like a success). Clearing `cycle_pending` here is the same
-            // proof for reviveNode's cycling-attempt marker and the one-shot yield
-            // note — both remain pending through any pre-session_start failure and are
-            // safe to clear on any confirmed boot (cycling, resuming, or fresh).
-            // An ordinary fork is not bound until Pi exposes BOTH the fresh child id
-            // and its writable session file. Recovery sees either an unbound fork or
-            // complete child coordinates, never a mixed state that could fork
-            // provenance twice.
-            if (existing?.fork_from != null && existing?.pi_session_id == null && sessionFile === null) {
+            // crtrd validates the review binding and fork coordinates, derives whether
+            // this node is a root, and commits every durable session-start mutation.
+            const binding = await bindBrokerSession(nodeId, {
+                piSessionId: id,
+                sessionFile,
+                pid: process.pid,
+                reason,
+                reviewBoundaryIds: currentReviewBoundaryIds(ctx),
+            });
+            if (binding.action === 'shutdown') {
                 try {
                     ctx?.shutdown?.();
                 }
                 catch { /* best-effort */ }
                 return;
             }
-            // Identity (session id/file) → meta; runtime (pid, intent) → atomic row
-            // setters. Any confirmed boot owns the one-shot yield note, if any;
-            // clear it once here so a pre-session_start retry preserves it, but a
-            // successful revival can still only consume it once.
-            clearYieldMessage(nodeId);
-            updateNode(nodeId, {
-                pi_session_id: id,
-                pi_session_file: sessionFile,
-                cycle_pending: false,
-            });
-            recordPid(nodeId, process.pid);
-            if (existing?.intent === 'refresh')
-                transition(nodeId, 'revive');
+            if (binding.action === 'relaunch_root') {
+                // The session-bound handler selects this consequence but never calls
+                // back into its calling broker. Do not await the operation that tears
+                // this broker down from Pi's session-start dispatch.
+                void relaunchBrokerRoot(nodeId).catch((error) => {
+                    emitEvent({
+                        event: 'broker.daemon.operation.failed',
+                        level: 'error',
+                        node_id: nodeId,
+                        error,
+                        fields: { operation: 'relaunch_root' },
+                    });
+                });
+            }
         }
-        catch {
-            /* best-effort; never surface from an extension handler */
+        catch (error) {
+            // Binding failure leaves Pi alive; crtrd remains the only process that
+            // can retry or reconcile the durable state.
+            emitEvent({
+                event: 'broker.daemon.operation.failed',
+                level: 'error',
+                node_id: nodeId,
+                error,
+                fields: { operation: 'session_bound' },
+            });
         }
     });
     // ---------------------------------------------------------------------------
@@ -488,8 +397,6 @@ export function registerCanvasStophook(pi) {
     pi.on('agent_start', () => {
         // A fresh turn started. Keep any active fault marker in place so the daemon's
         // retry accounting survives a failed retry cycle; just mark the turn busy.
-        agentRunning = true;
-        resetParkClock();
         try {
             markBusy(nodeId);
         }
@@ -567,56 +474,43 @@ export function registerCanvasStophook(pi) {
     // intent only flips to 'refresh' via `node yield`, so this can't false-fire.
     // (A node that somehow boots already carrying intent='refresh' correctly
     // refreshes on its first tool — the desired outcome.)
-    pi.on('tool_execution_end', (_event, ctx) => {
+    pi.on('tool_execution_end', async (_event, ctx) => {
         try {
             touchBusy(nodeId); // wedge heartbeat: the tool returning is a sign of life
             clearFault(nodeId, { link: 'daemon→node' }); // a tool that was "stuck" just returned — the wedge notice was resolved
-            if (getNode(nodeId)?.intent === 'refresh') {
+            if ((await brokerExtensionState(nodeId)).node.intent === 'refresh') {
+                // Stop this turn immediately so the large context does not keep running,
+                // but leave the broker alive through agent_settled. Only a successful
+                // daemon settle directive may request Pi shutdown.
                 try {
                     ctx?.abort?.();
                 }
                 catch { /* ignore */ }
-                try {
-                    ctx?.shutdown?.();
-                }
-                catch { /* ignore */ }
             }
         }
         catch { /* best-effort */ }
     });
     // ---------------------------------------------------------------------------
-    // session_shutdown — clean exit → done.
-    //
-    // pi hands us a reason as a session tears down. Only 'quit' is a node-ending
-    // event we record (markCleanExitDone guards against clobbering a node
-    // settlement already routed to done/refresh/idle-release). 'new' is owned by
-    // the session_start trigger above; reload/resume/fork keep the SAME node id on
-    // a swapped conversation. A true crash fires NO session_shutdown and falls
-    // through to the daemon's window-gone 'dead'.
-    //
-    // MUST stay synchronous (no await): the synchronous DatabaseSync write then
-    // lands within pi's awaited shutdown emit, before pi exits.
+    // session_shutdown — Pi's clean /quit fact goes to crtrd, which owns the
+    // finish transition, focus teardown, presence clear, and fault clear. Other
+    // session swaps keep the same node and need no durable settlement.
     // ---------------------------------------------------------------------------
-    pi.on('session_shutdown', (event, _ctx) => {
-        sessionBound = false;
-        agentRunning = false;
-        parkContext = null;
-        resetParkClock();
-        if (parkTimer !== null) {
-            clearInterval(parkTimer);
-            parkTimer = null;
-        }
+    pi.on('session_shutdown', async (event, ctx) => {
+        clearBusy(nodeId); // turn marker is meaningless once Pi is exiting
+        if (event?.reason !== 'quit')
+            return;
         try {
-            clearBusy(nodeId); // turn marker is meaningless once pi is exiting
-            clearFault(nodeId); // ditto the active fault marker
-            // Clean /quit (reason='quit') resolves the node to done; if it held the
-            // user's viewport, Q1-close it (tearDownNode kills the frozen focus pane +
-            // closes the focus row → returns the user to a shell, §1.5/flow (e)). pi is
-            // already exiting here, so killing its own pane is not a self-saw.
-            if (markCleanExitDone(nodeId, event?.reason))
-                tearDownNode(nodeId);
+            const directive = await settleBroker(nodeId, {
+                stopReason: 'quit',
+                backgroundJobsRunning: backgroundJobsRunning(),
+                pushedFinal: false,
+                askedHuman: false,
+            });
+            enactSettleDirective(directive, ctx);
+        }
+        catch (error) {
+            emitDaemonOperationFailure('settle_quit', error);
         }
-        catch { /* best-effort; never throw out of an extension handler */ }
     });
     /** Absorb usage + model from any assistant message (turn or final batch). */
     const accumulate = (msg) => {
@@ -631,7 +525,7 @@ export function registerCanvasStophook(pi) {
     // turn_end — live telemetry refresh.
     // event shape: { message: AssistantMessage, ... }
     // ---------------------------------------------------------------------------
-    pi.on('turn_end', (event, ctx) => {
+    pi.on('turn_end', async (event, ctx) => {
         accumulate(event?.message);
         // The CURRENT context size via ctx.getContextUsage() — the exact figure pi's
         // footer shows. Captured once here for two consumers: the telemetry flush
@@ -686,13 +580,11 @@ export function registerCanvasStophook(pi) {
         // is a ~2-token uncached delta each turn), so the bands were unreachable and
         // the nudge never fired.
         try {
-            const node = getNode(nodeId);
-            const lifecycle = node?.lifecycle ?? 'terminal';
-            const mode = node?.mode ?? 'base';
+            const node = (await brokerExtensionState(nodeId)).node;
             const at = contextTokens !== null ? steerBand(contextTokens) : null;
             if (at !== null && !firedBands.has(at)) {
                 firedBands.add(at);
-                const note = formatContextNudge(steerNote(at, lifecycle, mode));
+                const note = formatContextNudge(steerNote(at, node.lifecycle, node.mode));
                 if (runContinues) {
                     pi.sendUserMessage(note, { deliverAs: 'steer' });
                 }
@@ -700,27 +592,17 @@ export function registerCanvasStophook(pi) {
                     pi.sendMessage({ customType: CONTEXT_NUDGE_CUSTOM_TYPE, content: note, display: true }, { deliverAs: 'nextTurn' });
                 }
             }
-        }
-        catch {
-            /* steering is best-effort */
-        }
-        // Persona-transition steering. When this node's mode or lifecycle changed
-        // since it was last GIVEN guidance (it ran `crtr node promote` / `node
-        // lifecycle` this turn, or a sibling/human flipped it while the node was
-        // active), inject the guidance for its NEW persona once, then commit the
-        // ack so the next turn sees no drift. This is the single delivery site for
-        // in-session transitions — state-changing commands never hand-emit guidance.
-        // Delivered as a STEER (like the context nudge): a persona change must
-        // redirect the node at the turn boundary, not queue behind its next action.
-        try {
-            const drift = personaDrift(nodeId);
+            // Persona-transition steering. The daemon read snapshots both the
+            // expected ack and current persona; its guarded ack below can only commit
+            // exactly the transition this broker just described.
+            const drift = personaDriftFromBrokerState(node);
             if (drift !== null) {
                 pi.sendUserMessage(formatPersonaTransition(drift.guidance), { deliverAs: 'steer' });
-                commitPersonaAck(nodeId, drift.to);
+                await commitBrokerPersonaAck(nodeId, { from: drift.from, to: drift.to });
             }
         }
         catch {
-            /* persona steering is best-effort */
+            /* steering is best-effort */
         }
     });
     // Pi may emit several agent_end attempts while it compacts, retries, and
@@ -737,199 +619,35 @@ export function registerCanvasStophook(pi) {
         catch { /* best-effort */ }
     });
     // ---------------------------------------------------------------------------
-    // agent_settled — whole-run lifecycle commit after recovery and continuations.
+    // agent_settled — Pi supplies stop facts; crtrd commits every canvas effect
+    // and returns the one Pi-side consequence to enact.
     // ---------------------------------------------------------------------------
-    pi.on('agent_settled', (_event, ctx) => {
-        agentRunning = false;
-        resetParkClock();
+    pi.on('agent_settled', async (_event, ctx) => {
         const event = stagedAgentEnd;
         stagedAgentEnd = null;
-        // Busy and wedge state describe the whole run, so settlement clears them
-        // even when an abnormal engine path produced no stageable agent_end payload.
+        // Busy is a broker-local job marker. The daemon operation below owns the
+        // fault marker, stop policy, lifecycle transition, focus, and inbox cursor
+        // decision even when Pi had no stageable final agent_end payload.
         clearBusy(nodeId);
-        clearFault(nodeId, { link: 'daemon→node' });
-        if (event === null)
-            return;
-        // All routing here is synchronous fs. Provider-fault publication belongs to
-        // the broker's richer AgentSession event stream and commits at the same
-        // settlement boundary before its retry/notification scheduling proceeds.
+        const messages = Array.isArray(event?.messages) ? event.messages : [];
+        const last = lastAssistantMessage(messages);
+        const stopReason = typeof last?.stopReason === 'string' ? last.stopReason : '';
+        const stopSignals = event === null
+            ? { pushedFinal: false, askedHuman: false }
+            : consumeStopSignals(nodeId);
         try {
-            const messages = Array.isArray(event?.messages) ? event.messages : [];
-            const last = lastAssistantMessage(messages);
-            const stopReason = last?.stopReason ?? '';
-            // Interrupted or errored runs stay alive for re-steering. The broker
-            // publishes any settled provider fault from its subscriber event stream.
-            if (stopReason !== 'stop' && stopReason !== 'length') {
-                // A refresh-yield aborts its OWN turn (the tool_execution_end handler
-                // above calls ctx.abort() the instant `crtr node yield` returns), so a
-                // non-'stop' stopReason here is the deliberate refresh, never a failed
-                // run. Shut down and let the daemon relaunch the node fresh against
-                // its roadmap; classifying it below would crash the node instead and
-                // the daemon's exit policy would then forget an already-dead row,
-                // stranding the yield.
-                if (getNode(nodeId)?.intent === 'refresh') {
-                    try {
-                        ctx?.shutdown?.();
-                    }
-                    catch { /* ignore */ }
-                }
-                return;
-            }
-            // TRULY-DONE (pushed `final` this turn). The engine is a detached
-            // broker, not a pane, so there is no engine to hand off — just close
-            // this node's VIEWER pane (if any) and shut the broker down. The daemon
-            // won't revive a done node. tearDownNode closes the viewer focus row +
-            // pane; ctx.shutdown() exits the broker process.
-            //
-            // EVERY step here is best-effort and the shutdown lives in `finally`: the
-            // `pushedFinal` marker path exists precisely so a broker need not read
-            // canvas state to know it finished, so a failing local canvas read/write
-            // (focusOf/setPresence) must not be what keeps a finalized broker alive.
-            // The enclosing agent_settled catch would swallow the throw and leave the
-            // process running forever.
-            const shutDownFinished = () => {
-                try {
-                    try {
-                        clearFault(nodeId);
-                    }
-                    catch { /* best-effort */ }
-                    try {
-                        if (focusOf(nodeId) !== null)
-                            tearDownNode(nodeId);
-                    }
-                    catch { /* best-effort */ }
-                    try {
-                        setPresence(nodeId, { pane: null, tmux_session: null, window: null });
-                    }
-                    catch { /* best-effort */ }
-                }
-                finally {
-                    try {
-                        ctx?.shutdown?.();
-                    }
-                    catch { /* ignore */ }
-                }
-            };
-            // A successful command records its own outcome before it returns to pi.
-            // Consume that outcome before any canvas read: a broker must not re-read
-            // state which crtrd just committed in order to decide whether this turn
-            // can finish or wait for the human.
-            const stopSignals = consumeStopSignals(nodeId);
-            if (stopSignals.pushedFinal) {
-                shutDownFinished();
-                return;
-            }
-            if (stopSignals.askedHuman) {
-                try {
-                    clearFault(nodeId);
-                }
-                catch { /* best-effort */ }
-                return;
-            }
-            // (b) Already done: `crtr push --final` was called this turn, which
-            //     transitions node.status → 'done' synchronously. Shut down cleanly.
-            const node = getNode(nodeId);
-            if (node?.status === 'done') {
-                shutDownFinished();
-                return;
-            }
-            // (b') Refresh-yield BACKSTOP: the node ran `crtr node yield` this turn,
-            //     setting intent='refresh'. The primary exit is the tool_execution_end
-            //     handler above, which shuts down the instant the yield tool returns
-            //     (so the model never burns more context finishing the turn); this
-            //     branch only fires if that shutdown was missed. Either way: shut the
-            //     broker down — the daemon sees the dead pid + intent='refresh' and
-            //     reviveNode relaunches the broker FRESH (no resume) so the node
-            //     re-reads its roadmap. (The daemon also force-recycles a stuck
-            //     refresh whose engine never exits, so a stale in-process stophook
-            //     can't strand the yield — see crtrd.)
-            if (node?.intent === 'refresh') {
-                // A yield is SILENT to subscribers: the node keeps its identity and
-                // subscription edges across the revive and reports only through its own
-                // explicit `crtr push` calls, so there is no checkpoint push here.
-                try {
-                    ctx?.shutdown?.();
-                }
-                catch { /* ignore */ }
-                return;
-            }
-            // (c) Natural stop — run the stop-guard to classify this stop. Nothing
-            //     is auto-pushed: the node reaches its subscribers only through its
-            //     own explicit `crtr push` calls this turn. The guard decides
-            //     whether the stop is a legitimate dormancy (idle-release, or an
-            //     attended root staying live) or a stall to reprompt.
-            const decision = evaluateStop(nodeId, stopSignals);
-            if (decision.action === 'reprompt') {
-                // Stalled — re-prompt so the node finishes or escalates with an
-                // explicit `crtr push final` (or `crtr human ask`). Deliver as a
-                // followUp: the turn just ended but pi may still be flushing, so an
-                // unqualified sendUserMessage races with 'already processing'.
-                pi.sendUserMessage(decision.message, { deliverAs: 'followUp' });
-                try {
-                    clearFault(nodeId);
-                }
-                catch { /* best-effort */ }
-                return;
-            }
-            // 'allow' — the node legitimately stopped. The active-fault marker can
-            // clear now; any report it owed its subscribers was sent by an explicit
-            // `crtr push` during the turn.
-            try {
-                clearFault(nodeId);
-            }
-            catch { /* best-effort */ }
-            if (decision.reason === 'finished') {
-                // A canonical final can race the in-process watcher just like an
-                // awaiting stop: keep the broker alive until any non-deferred entry
-                // beyond the durable cursor has been delivered and committed.
-                if (readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred'))
-                    return;
-                try {
-                    ctx?.shutdown?.();
-                }
-                catch { /* ignore */ }
-                return;
-            }
-            //
-            // Idle-release: an unfocused node awaiting a subscribed node, controller,
-            // or background bash job (reason 'awaiting') is holding a live broker for
-            // nothing. Mark it idle-released and shut pi down; the daemon watches its
-            // inbox and revives it (resume) when the awaited delivery arrives. A
-            // resident node never releases: the human is its wake source, so we keep
-            // its broker live and dormant.
-            if (decision.reason === 'awaiting' || decision.reason === 'scheduled') {
-                // AWAITING ≠ done (no manager-takeover). What happens next splits on
-                // whether the user is WATCHING this node:
-                //   • FOCUSED → it holds the user's viewport, so keep pi LIVE and
-                //     dormant (exactly like a resident root): do NOT release or shut
-                //     down. The in-process inbox-watcher (still alive) wakes it the
-                //     instant a worker pushes — no respawn, no frozen pane, the pane
-                //     stays interactive. When the user later focuses AWAY, placement's
-                //     retarget reclassifies it as a parked terminal viewer and releases
-                //     it then (transition 'release' + pane reaped), so the kept-alive
-                //     pi is reclaimed on focus-away, never held forever.
-                //   • UNFOCUSED → no one is watching, so holding a live pi for a window
-                //     is waste. Release it (idle + idle-release) and shut pi down; its
-                //     backstage pane closes and the daemon revives it (resume) on the
-                //     next unseen inbox entry.
-                if (focusOf(nodeId) !== null)
-                    return; // focused → stay alive, dormant
-                // Match the daemon's idle-release wake gate: a resume wake does not
-                // drainBearings, so a non-deferred entry past the durable cursor must
-                // keep this broker alive for the watcher to deliver and commit it.
-                // Deferred entries ride the next natural cycle (#341).
-                if (readInboxSince(nodeId, readCursor(nodeId)).some((entry) => entry.tier !== 'deferred'))
-                    return;
-                transition(nodeId, 'release');
-                try {
-                    ctx?.shutdown?.();
-                }
-                catch { /* ignore */ }
-                return;
-            }
+            const directive = await settleBroker(nodeId, {
+                stopReason,
+                backgroundJobsRunning: backgroundJobsRunning(),
+                pushedFinal: stopSignals.pushedFinal,
+                askedHuman: stopSignals.askedHuman,
+            });
+            enactSettleDirective(directive, ctx);
         }
-        catch {
-            /* agent_settled handler must never throw out of the extension */
+        catch (error) {
+            // A daemon failure is observable and leaves this broker alive; it must not
+            // masquerade as a completed release, teardown, or cursor settlement.
+            emitDaemonOperationFailure('settle', error);
         }
     });
 }