@north-light/crouter 0.3.154

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

@@ -0,0 +1,985 @@
+// canvas-stophook.ts — pi extension for pi-native canvas agent nodes.
+//
+// Loaded into every canvas node's pi process via the node's launch.extensions
+// list. INERT when CRTR_NODE_ID is absent (plain pi session or legacy job agent).
+//
+// In the canvas model each node owns a dedicated pi window (one-window-per-node),
+// so the tmux pane-relocation swap-back guard of the legacy stophook is omitted —
+// there are no shared pane slots to restore.
+//
+// Responsibilities:
+//
+//   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_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) → idle-release: free the tmux window and shut
+//                          down; the daemon watches the inbox and revives it
+//                          (resume) when a subscribed worker delivers.
+//           • 'allow' (attended root) → stay alive, dormant; the human wakes it.
+//
+// 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 { publishFollowUpProgress } from '@crouton-kit/humanloop';
+import { getNode, jobDir, updateNode, recordPid, setPresence, dispatchFollowUpWork, dispatchVisualWork, getFollowUpWorkRow, getHumanWorkRow, reconcileFollowUpWork, reconcileVisualWork } 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 { 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';
+/** 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. */
+const ACTIVITY_CAP = 80;
+function summarizeActivity(toolName, args) {
+    const a = (args ?? {});
+    const pick = (v) => (typeof v === 'string' ? v : '');
+    const detail = pick(a['command']) || pick(a['path']) || pick(a['file_path']) || pick(a['pattern']) || pick(a['description']) || pick(a['prompt']);
+    const line = (detail !== '' ? `${toolName}: ${detail}` : toolName).replace(/\s+/g, ' ').trim();
+    return line.length > ACTIVITY_CAP ? line.slice(0, ACTIVITY_CAP) : line;
+}
+/**
+ * Merge accumulated token counts into nodes/<nodeId>/job/telemetry.json.
+ * Creates the directory when it doesn't yet exist. Best-effort; never throws.
+ * `contextTokens` is the live window gauge for THIS turn; when null (pi can't
+ * size the window yet) the last recorded value is preserved.
+ */
+function flushTelemetry(jobDirPath, tokensIn, tokensOut, model, contextTokens, activity) {
+    try {
+        if (!existsSync(jobDirPath))
+            mkdirSync(jobDirPath, { recursive: true });
+        const filePath = join(jobDirPath, 'telemetry.json');
+        // Merge with any existing record so concurrent readers always see a complete
+        // picture. Model name falls back to whatever was last recorded.
+        let existing = {};
+        if (existsSync(filePath)) {
+            try {
+                existing = JSON.parse(readFileSync(filePath, 'utf8'));
+            }
+            catch {
+                /* start fresh on a corrupt file */
+            }
+        }
+        const record = {
+            tokens_in: tokensIn,
+            tokens_out: tokensOut,
+            context_tokens: contextTokens ?? existing.context_tokens,
+            last_activity: activity ?? existing.last_activity,
+            model: model !== '' ? model : (existing.model ?? ''),
+            updated_at: new Date().toISOString(),
+        };
+        writeFileSync(filePath, JSON.stringify(record, null, 2), 'utf8');
+    }
+    catch {
+        /* telemetry is best-effort; never surface */
+    }
+}
+// ---------------------------------------------------------------------------
+// Message-extraction helpers
+// ---------------------------------------------------------------------------
+/** Walk backwards through the agent_end messages array to find the last
+ *  assistant turn. */
+function lastAssistantMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === 'assistant')
+            return messages[i];
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Context-size steering bands — a single shared schedule of thresholds that
+// ESCALATE in tone as input context grows. The first band is a gentle
+// "consider it"; a later band turns firm. The schedule TIGHTENS as it climbs:
+// 130k, 150k, 170k, 185k, 200k, then every 10k (210k, 220k, …) so a long-lived
+// node keeps getting reminded, more often the deeper it goes.
+//
+// The band schedule is shared across all node shapes; only the MESSAGE differs
+// (steerNote), keyed on MODE first, then LIFECYCLE — three reachable personas:
+//   orchestrator (terminal OR resident): HAS a roadmap (promotion / orchestrator
+//             birth seeds context/roadmap.md), so it is steered to checkpoint +
+//             yield — 130k gentle (consider yielding) → 150k firm (do it now) →
+//             185k+ pushy. Keyed on mode, NOT lifecycle: a terminal/orchestrator
+//             yields against its roadmap exactly like a resident one (the
+//             daemon's refresh-revive keys on intent='refresh', not lifecycle).
+//   resident/base (a root conversation): NO roadmap on disk yet, so it is not
+//             told to checkpoint one. `crtr node yield` is still its continue
+//             verb — mode-preserving, continuing fresh against its goal and its
+//             note — offered against wrap-up, since a root chat can simply end.
+//             `--promote` is mentioned only once the chat has genuinely grown
+//             into phases to delegate. Gentle → firm → pushy.
+//   terminal/base (a worker): steered to `crtr node yield` to continue in a
+//             fresh window, mode-preserving, when work remains, or `push final`
+//             when close. Gentle → firm → pushy.
+//
+// Every persona's "keep going" verb is `crtr node yield` — NEVER a bare `node
+// promote`, which framed promotion as a heavy "become an orchestrator" step and
+// bred yield-avoidance. A plain yield is always mode-preserving — a base node's
+// yield never auto-promotes, so the agent is never steered to decide about
+// promotion at all; `--promote` is a separate opt-in mentioned only for
+// became-multi-phase work. Only a terminal node is ever told `push final` (a
+// resident finishes by yielding or being closed); only an orchestrator already
+// HAS a roadmap to checkpoint before it yields.
+// ---------------------------------------------------------------------------
+const STEER_STEP = 10_000;
+// Shared escalation schedule (both lifecycles). Tightens as it climbs:
+// 130k, 150k, 170k, 185k, 200k, then every 10k (210k, 220k, …).
+const BANDS = [130_000, 150_000, 170_000, 185_000, 200_000];
+/** The highest band threshold at or below `tokens`. Below the first band →
+ *  null. At/past the last listed band, bands continue every STEER_STEP (so the
+ *  firmest nudge keeps recurring). */
+function steerBand(tokens) {
+    const first = BANDS[0];
+    const last = BANDS[BANDS.length - 1];
+    if (tokens < first)
+        return null;
+    if (tokens >= last)
+        return last + Math.floor((tokens - last) / STEER_STEP) * STEER_STEP;
+    let chosen = first;
+    for (const b of BANDS)
+        if (tokens >= b)
+            chosen = b;
+    return chosen;
+}
+/** The nudge text for a crossed band, specialized to the node's (mode,
+ *  lifecycle) persona + how far along the escalation it is. `crtr node yield` is
+ *  the single "keep going past this window" verb for every persona: it refreshes
+ *  the node into a clean window, MODE-PRESERVING — a base node stays base,
+ *  continuing fresh against its goal and its note. `--promote` is a separate,
+ *  explicit opt-in (never steered here as auto-behavior) for when what remains
+ *  has genuinely grown into phases to delegate across children — so no persona
+ *  is ever steered at a bare `node promote` (which framed promotion as a heavy
+ *  "become an orchestrator" step and bred yield-avoidance).
+ *
+ *  - orchestrator (terminal OR resident): checkpoint context/roadmap.md, then
+ *    yield (it already has a roadmap to bring current first).
+ *  - resident/base (root conversation): yield to continue fresh if the chat is
+ *    growing into a job, else wrap up — a root can simply end.
+ *  - terminal/base (worker): yield to continue if work remains, or `push final`
+ *    when close.
+ *
+ *  The wording strengthens with depth: gentle < 150k → firm < 185k → pushy at/
+ *  past 185k, where drifting further risks an overflow. */
+export function steerNote(at, lifecycle, mode) {
+    const k = Math.round(at / 1000);
+    const pushy = at >= 185_000;
+    // Keyed on MODE first: any orchestrator (terminal or resident) has a roadmap
+    // to checkpoint + yield against.
+    if (mode === 'orchestrator') {
+        if (at < 150_000) {
+            return `Context ~${k}k and growing. When you reach a good stopping point, consider updating context/roadmap.md and running \`crtr node yield\` to refresh against it — no rush yet.`;
+        }
+        if (!pushy) {
+            return `Context ~${k}k. Update context/roadmap.md so a fresh revive can continue, delegate any outstanding work, then \`crtr node yield\` to refresh.`;
+        }
+        return `Context ~${k}k — this is getting long. Stop taking on new work now: checkpoint context/roadmap.md, hand off anything outstanding, and \`crtr node yield\` immediately to refresh before this context overflows.`;
+    }
+    if (lifecycle === 'resident') {
+        // resident/base — a root conversation, mode-preserving `crtr node yield` is
+        // the natural "carry this forward" verb: it refreshes into a clean window
+        // and continues fresh against your goal and your note — no "become
+        // something" decision. Only mention --promote once the chat has genuinely
+        // grown into phases to delegate. Offer wrap-up as the alternative — a root
+        // chat can simply end.
+        const grow = `If this is turning into a multi-phase job, \`crtr node yield\` to continue fresh against your goal and your note — add --promote only once it has genuinely grown into phases you need to delegate across children.`;
+        if (at < 150_000) {
+            return `Context ~${k}k and growing. ${grow} Otherwise no rush — wrap up when you reach a good stopping point.`;
+        }
+        if (!pushy) {
+            return `Context ~${k}k. ${grow} If you're near done, just finish here; if there's more open-ended work, \`crtr node yield\` rather than letting this context grow.`;
+        }
+        return `Context ~${k}k — this is getting long. Wrap up now before this context overflows: finish what's in hand, or \`crtr node yield\` immediately to continue fresh against your goal and your note if substantial work remains.`;
+    }
+    // terminal/base — a worker. The natural "keep going past this window" verb is
+    // `crtr node yield`: it refreshes into a clean window, mode-preserving, and
+    // continues fresh against your goal and your note. --promote is a separate
+    // opt-in for when what remains needs delegating across children — mentioned
+    // only for became-multi-phase work, never steered as automatic. Steer it to
+    // yield-or-finish, never a bare promote.
+    if (at < 150_000) {
+        return `Context ~${k}k and growing. If you're near done, finish with \`crtr push final\`. If real work remains, \`crtr node yield\` to continue in a fresh window against your goal and your note — no rush yet.`;
+    }
+    if (!pushy) {
+        return `Context ~${k}k. If you're close, finish with \`crtr push final\`; otherwise \`crtr node yield\` now to refresh into a clean window and keep going against your goal and your note.`;
+    }
+    return `Context ~${k}k — this is getting long. Wrap up now before this context overflows: \`crtr push final\` if you're close, otherwise \`crtr node yield\` immediately to continue in a fresh window against your goal and your note.`;
+}
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+/**
+ * Register the canvas turn and settlement handlers on `pi`.
+ *
+ * Returns immediately when CRTR_NODE_ID is absent — the extension is fully
+ * inert in a non-canvas pi session. Safe to call multiple times (each call
+ * re-registers on the same `pi` instance, so it should only be called once
+ * per node lifecycle, matching how pi loads extensions).
+ */
+export function registerCanvasStophook(pi) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId.trim() === '')
+        return; // not a canvas node
+    const jobDirPath = jobDir(nodeId);
+    // Cumulative throughput across all turns in this pi session, for telemetry
+    // (job/telemetry.json) only — both turn_end and agent_end accumulate so tokens
+    // emitted in the final partial turn (if pi fires agent_end without a preceding
+    // turn_end for it) are captured. NOT used for context-size steering: that is a
+    // per-turn gauge (see contextTokens), not a running sum.
+    let totalIn = 0;
+    let totalOut = 0;
+    let model = '';
+    // Last live context-window gauge + last tool summary, tracked across handlers so
+    // a tool_execution_start flush (activity-only) preserves the latest token figure.
+    let lastContext = null;
+    let lastActivity = null;
+    // If this node IS a follow-up consult fork, its ticket binding never changes,
+    // so resolve it once and reuse it to narrate live activity back into the
+    // waiting ticket. `undefined` = not yet looked up, `null` = not a consult.
+    let consultTicket;
+    function narrateToTicket(line) {
+        if (line === null || line === '')
+            return;
+        if (consultTicket === undefined) {
+            const row = getFollowUpWorkRow(String(nodeId));
+            consultTicket = row === null ? null : { root: row.root, dir: row.dir, requestId: row.request_id };
+        }
+        if (consultTicket === null)
+            return;
+        // humanloop itself gates on the request still being the running one, so a
+        // superseded or already-answered ticket silently ignores this.
+        publishFollowUpProgress(consultTicket.root, consultTicket.dir, { requestId: consultTicket.requestId, line });
+    }
+    // Context-size steering. As input context grows we nudge the node once per
+    // band on an escalating, persona-specific schedule (see steerBand/steerNote).
+    // The node's (lifecycle, mode) persona is read at fire time, since a terminal
+    // worker can promote mid-session: an orchestrator is steered to checkpoint
+    // its roadmap + yield; a resident base (root chat) to yield-or-wrap-up (or
+    // yield --promote only once it has grown into phases to delegate); 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 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();
+            try {
+                parkContext?.shutdown?.();
+            }
+            catch { /* best-effort */ }
+        }
+        catch {
+            // A policy read failure must stay visible on the next poll rather than
+            // releasing from incomplete evidence.
+            resetParkClock();
+        }
+    };
+    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
+    // measured in minutes, so this throttle costs it nothing. Also clears any
+    // stale `daemon→node` wedge fault at the same throttled cadence: a sign of
+    // life should both refresh the heartbeat marker AND clear a stale wedge
+    // notice as one coherent act, same as every coarser progress site below
+    // (tool execution, turn_end, agent_settled) already does. clearFault is
+    // a cheap no-op when no fault exists, so this stays safe to call every time.
+    const HEARTBEAT_THROTTLE_MS = 3_000;
+    let lastHeartbeatAt = 0;
+    const heartbeat = () => {
+        const now = Date.now();
+        if (now - lastHeartbeatAt < HEARTBEAT_THROTTLE_MS)
+            return;
+        lastHeartbeatAt = now;
+        touchBusy(nodeId);
+        clearFault(nodeId, { link: 'daemon→node' });
+    };
+    // ---------------------------------------------------------------------------
+    // session_start — capture pi's session id, and detect `/new`.
+    //
+    // pi tags each session_start with a `reason`: 'startup' on boot (a fresh
+    // launch or a daemon revive — both new processes), 'new' when the user runs
+    // `/new` (a brand-new conversation in the SAME process), and 'resume' /
+    // 'reload' / 'fork' for the in-place conversation swaps that keep the same
+    // node. We branch on that reason — NOT on a remembered session id.
+    //
+    // Why reason, not a closure flag: pi RE-ACTIVATES extensions on every session
+    // swap, so any id we stash on boot is reset to its initial value before the
+    // next session_start fires and can never observe the change — a `/new` then
+    // 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).
+    // ---------------------------------------------------------------------------
+    pi.on('session_start', (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;
+            // The absolute path to this session's .jsonl, captured alongside the id.
+            // Resuming by path is immune to a cwd discrepancy (pi opens it directly),
+            // 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;
+            // `/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 {
+                    const m = getNode(nodeId);
+                    // 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 (m?.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.
+                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).
+            const existing = getNode(nodeId);
+            // A pending private fork is not bound until Pi exposes BOTH the fresh child
+            // id and its writable session file. Persist those identities and the phase
+            // flip in one meta write: recovery sees either fork_pending with no child,
+            // or session_started with the complete child coordinate, never a mixed
+            // state that could fork provenance twice.
+            if (existing?.private_fork_phase === 'fork_pending' && sessionFile === null) {
+                try {
+                    ctx?.shutdown?.();
+                }
+                catch { /* best-effort */ }
+                return;
+            }
+            // Identity (session id/file/phase) → 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, existing?.private_fork_phase === 'fork_pending'
+                ? {
+                    pi_session_id: id,
+                    pi_session_file: sessionFile,
+                    private_fork_phase: 'session_started',
+                    cycle_pending: false,
+                }
+                : {
+                    pi_session_id: id,
+                    pi_session_file: sessionFile,
+                    cycle_pending: false,
+                });
+            recordPid(nodeId, process.pid);
+            if (existing?.intent === 'refresh')
+                transition(nodeId, 'revive');
+        }
+        catch {
+            /* best-effort; never surface from an extension handler */
+        }
+    });
+    // ---------------------------------------------------------------------------
+    // agent_start — pi entered a turn. Mark the node mid-turn (busy) so a
+    // focus-away while it is genuinely working backstages it (Invariant F2)
+    // rather than reaping it. Cleared only after the whole run settles.
+    // ---------------------------------------------------------------------------
+    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);
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
+    // input — a new user-directed run is beginning. This is the ONLY place stop
+    // signals are cleared: `agent_start` re-fires for pi's automatic retries and
+    // post-compaction continuations within the SAME run, so clearing there would
+    // erase the `crtr human ask` / `crtr push final` marker written earlier in the
+    // run and make the eventual settlement fall back to a canvas read (exactly the
+    // read the marker exists to avoid). One run's markers survive until the one
+    // `agent_settled` consumes them; a leftover from an errored or interrupted run
+    // of this same broker is discarded here, when the next prompt arrives (the pid
+    // stamp only rules out a PRIOR broker's markers, not this broker's own).
+    // ---------------------------------------------------------------------------
+    pi.on('input', () => {
+        try {
+            clearStopSignals(nodeId);
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
+    // tool_execution_start — capture the live "what is it doing" cue. Writes the
+    // one-line tool summary to telemetry.json so out-of-process readers (the nav
+    // chrome) show it inline without a second file or any extra read on their side.
+    // ---------------------------------------------------------------------------
+    pi.on('tool_execution_start', (event) => {
+        try {
+            lastActivity = summarizeActivity(String(event?.toolName ?? ''), event?.args);
+            flushTelemetry(jobDirPath, totalIn, totalOut, model, lastContext, lastActivity);
+            narrateToTicket(lastActivity); // a consult fork streams its activity to the waiting ticket
+            touchBusy(nodeId); // wedge heartbeat: a fresh tool starting is a sign of life
+            clearFault(nodeId, { link: 'daemon→node' }); // a tool actually starting clears any prior wedge notice
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
+    // tool_execution_update — wedge heartbeat + fault clear only. Fired with
+    // partial/streaming tool output (when a tool reports progress); throttled via
+    // `heartbeat()` since it can arrive many times per second. Most tools (e.g.
+    // bash) don't stream progress today, so this is currently a light-touch no-op
+    // for them — it exists so any tool that DOES stream partial output (now or in
+    // the future) counts as live progress instead of tripping the wedge detector,
+    // AND clears any wedge notice that already fired before this progress resumed.
+    // ---------------------------------------------------------------------------
+    pi.on('tool_execution_update', () => {
+        try {
+            heartbeat();
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
+    // message_update — wedge heartbeat + fault clear only. Fired token-by-token
+    // while the assistant is actively streaming a reply — genuine progress,
+    // throttled the same way, and equally clears a stale wedge notice if streaming
+    // resumes before a coarser boundary. A node stuck streaming forever without
+    // ever firing this is exactly the daemon's busy+quiet wedge signature.
+    // ---------------------------------------------------------------------------
+    pi.on('message_update', () => {
+        try {
+            heartbeat();
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
+    // tool_execution_end — IMMEDIATE refresh-yield. When a tool this turn set
+    // intent='refresh' (the node ran `crtr node yield`), shut the broker down NOW
+    // instead of letting the model keep burning its bloated context to the turn's
+    // natural end (the settlement backstop would only catch it there). The yield
+    // command persists the yield-message + any existing roadmap checkpoint BEFORE
+    // it returns, so by the time this fires nothing is lost. Abort the live turn,
+    // then request shutdown; the broker exits after pi's settle boundary. The
+    // daemon then sees the dead pid + intent='refresh' and revives the node FRESH
+    // against its roadmap if it has one, else its original goal.
+    // 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) => {
+        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') {
+                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.
+    // ---------------------------------------------------------------------------
+    pi.on('session_shutdown', (event, _ctx) => {
+        sessionBound = false;
+        agentRunning = false;
+        parkContext = null;
+        resetParkClock();
+        if (parkTimer !== null) {
+            clearInterval(parkTimer);
+            parkTimer = null;
+        }
+        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);
+        }
+        catch { /* best-effort; never throw out of an extension handler */ }
+    });
+    /** Absorb usage + model from any assistant message (turn or final batch). */
+    const accumulate = (msg) => {
+        if (msg?.role !== 'assistant' || msg.usage == null)
+            return;
+        totalIn += Number(msg.usage.input ?? 0) || 0;
+        totalOut += Number(msg.usage.output ?? 0) || 0;
+        if (typeof msg.model === 'string' && msg.model !== '')
+            model = msg.model;
+    };
+    // ---------------------------------------------------------------------------
+    // turn_end — live telemetry refresh.
+    // event shape: { message: AssistantMessage, ... }
+    // ---------------------------------------------------------------------------
+    pi.on('turn_end', (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
+        // (so out-of-process readers like `crtr node new` can size this node) and
+        // the context-size steering below.
+        //   .tokens is null/undefined only when pi can't know the size yet (no model,
+        //   or right after a compaction before the next reply) — telemetry then keeps
+        //   its last value and steering is skipped for the turn.
+        let contextTokens = null;
+        try {
+            const t = ctx.getContextUsage()?.tokens;
+            if (typeof t === 'number')
+                contextTokens = t;
+        }
+        catch { /* gauge unavailable this turn */ }
+        if (contextTokens !== null)
+            lastContext = contextTokens;
+        // Fire-and-forget: flushTelemetry uses synchronous fs writes and never throws.
+        flushTelemetry(jobDirPath, totalIn, totalOut, model, contextTokens, lastActivity);
+        touchBusy(nodeId); // wedge heartbeat: a turn ending is a sign of life
+        clearFault(nodeId, { link: 'daemon→node' }); // reaching turn_end proves this turn wasn't wedged
+        clearFault(nodeId, { link: 'pi→provider' }); // a completed provider round-trip proves this episode is over
+        // Will the agent run CONTINUE past this turn? Deterministic at turn_end:
+        // the loop keeps going exactly when this assistant message carried tool
+        // calls and the run wasn't aborted/errored (those end unconditionally,
+        // before tools execute). A tool-calling turn ends with stopReason
+        // 'toolUse' — or 'length' when truncation failed the calls, which still
+        // continues the loop — NEVER 'stop', so gate on the abort/error reasons,
+        // not on an allowlist that excludes 'toolUse'.
+        // This handler runs BEFORE the loop drains the steering queue, so the read
+        // is race-free: zero tool calls ⇒ this is the run's FINAL message, and a
+        // steer sent now would not redirect at a boundary — it would EXTEND the run
+        // past the agent's closing reply, burying the summary the human comes back
+        // to read once the conversation goes quiet.
+        const turnContent = Array.isArray(event?.message?.content) ? event.message.content : [];
+        const turnStopReason = event?.message?.stopReason ?? '';
+        const runContinues = turnStopReason !== 'error' &&
+            turnStopReason !== 'aborted' &&
+            turnContent.some((c) => c?.type === 'toolCall');
+        // Context-size steering: fire the current band once, with lifecycle-specific
+        // guidance (lifecycle is read live — a terminal worker may have promoted to
+        // resident since launch).
+        // Delivery splits on runContinues:
+        //   • mid-run → STEER, not a followUp: guidance to become an orchestrator /
+        //     delegate / yield must redirect the node at the turn boundary, not queue
+        //     behind whatever it does next (where it rides along, easy to ignore).
+        //   • final message → HOLD via pi's 'nextTurn' queue: it injects alongside
+        //     the next user message without triggering a turn, so the nudge is read
+        //     at the start of the next engagement instead of spawning a phantom
+        //     continuation after the agent already said its piece.
+        // Never the cumulative totalIn: under prompt caching that never grows (input
+        // 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 at = contextTokens !== null ? steerBand(contextTokens) : null;
+            if (at !== null && !firedBands.has(at)) {
+                firedBands.add(at);
+                const note = `[crtr] ${steerNote(at, lifecycle, mode)}`;
+                if (runContinues) {
+                    pi.sendUserMessage(note, { deliverAs: 'steer' });
+                }
+                else {
+                    pi.sendMessage({ customType: 'crtr-context-nudge', 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);
+            if (drift !== null) {
+                pi.sendUserMessage(drift.guidance, { deliverAs: 'steer' });
+                commitPersonaAck(nodeId, drift.to);
+            }
+        }
+        catch {
+            /* persona steering is best-effort */
+        }
+    });
+    // Pi may emit several agent_end attempts while it compacts, retries, and
+    // drains queued continuations. Keep only the latest attempt here; no lifecycle
+    // effect is committed until Pi declares the whole run settled.
+    let stagedAgentEnd = null;
+    pi.on('agent_end', (event) => {
+        stagedAgentEnd = event;
+        try {
+            const messages = Array.isArray(event?.messages) ? event.messages : [];
+            for (const message of messages)
+                accumulate(message);
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
+    // agent_settled — whole-run lifecycle commit after recovery and continuations.
+    // ---------------------------------------------------------------------------
+    pi.on('agent_settled', (_event, ctx) => {
+        agentRunning = false;
+        resetParkClock();
+        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.
+        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.
+        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.
+            //
+            // EXCEPT a follow-up consultation fork (design-followup-consult-v2.md
+            // §B.2/§B.4; integrated-review Major-2): it is born `parent:null` with
+            // no subscriber and nothing left to re-steer it — there is no human or
+            // sibling that will ever send it another message. An exact-model turn
+            // failure (the broker's `modelExact` fail-closed gates deliberately
+            // refuse to substitute a different model/provider, so the turn just
+            // errors) would otherwise leave it parked here forever: `armed`/`pending`
+            // in the outbox with no future event guaranteed to reach it (the daemon
+            // only reconciles at its own startup, and `_consult`/`_deliver` only
+            // fire on a LATER human action on this SAME ticket). Identify it by the
+            // presence of its own outbox row (the delivery record) and settle it
+            // right here instead: crash the
+            // node (frees it from the daemon's supervised LIVE set) and reconcile
+            // its outbox immediately — `reconcileFollowUpWork`'s armed+dead branch
+            // turns this into the ticket's `error` result, event-driven, no polling.
+            if (stopReason !== 'stop' && stopReason !== 'length') {
+                let isConsultFork = false;
+                let isVisualFork = false;
+                try {
+                    const work = getHumanWorkRow(nodeId);
+                    isConsultFork = work?.work_kind === 'follow_up';
+                    isVisualFork = work?.work_kind === 'visual';
+                }
+                catch {
+                    /* best-effort read — treat as ordinary work on storage failure */
+                }
+                if (isConsultFork || isVisualFork) {
+                    // Minor-6 (integrated review): shutdown must fire even when
+                    // transition/reconcile throws — sharing one try with the shutdown
+                    // call let a reconciliation exception skip it entirely, stranding
+                    // an already-crashed consult broker (settlement then waits on
+                    // NOTHING, since this fork has no subscriber to ever retry it).
+                    // `finally` guarantees the shutdown regardless of the outcome
+                    // above; the outbox row itself is unaffected either way —
+                    // `reconcileFollowUpWork` is retried at the next
+                    // daemon-crash/startup/_consult/_deliver touchpoint.
+                    try {
+                        const cur = getNode(nodeId);
+                        if (cur !== null && (cur.status === 'active' || cur.status === 'idle'))
+                            transition(nodeId, 'crash');
+                        reconcileFollowUpWork();
+                        reconcileVisualWork();
+                    }
+                    catch {
+                        /* best-effort — reconcileFollowUpWork is retried at the next daemon-crash/startup/_consult/_deliver touchpoint */
+                    }
+                    finally {
+                        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 */ }
+                    // Consult-outbox dispatch (design-followup-consult-v2.md §B.4): if this
+                    // node is a follow-up consultation fork, its outbox row was promoted
+                    // armed→pending inside the SAME transaction that just committed this
+                    // final (feed.ts commitCanonicalFinal). Deliver it now, in-process, on
+                    // this fork's own settlement — the happy-path dispatch, event-driven,
+                    // no polling. A no-op for every non-consult node (no outbox row).
+                    try {
+                        dispatchFollowUpWork(nodeId);
+                        dispatchVisualWork(nodeId);
+                    }
+                    catch { /* best-effort — durable reconcilers retry */ }
+                }
+                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') {
+                try {
+                    ctx?.shutdown?.();
+                }
+                catch { /* ignore */ }
+                return;
+            }
+            //
+            // Idle-release: a node awaiting its workers (reason 'awaiting') is holding
+            // a tmux window for nothing. Free it — mark it idle-released and shut pi
+            // down; the daemon watches its inbox and revives it (resume) the moment a
+            // subscribed worker delivers. An 'attended' root never releases: the human
+            // is its wake source, so we keep its window 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;
+            }
+        }
+        catch {
+            /* agent_settled handler must never throw out of the extension */
+        }
+    });
+}
+export default registerCanvasStophook;