@crouton-kit/crouter 0.3.68 → 0.3.78

package/dist/pi-extensions/canvas-inbox-watcher.js

@@ -25,6 +25,55 @@
 //     (kind 'final') ALSO steers — a completion the subscriber may be blocked on
 //     must interrupt the current turn, not wait behind it as a follow-up.
 //
+// Durable delivery — honest at-least-once with one conservative boundary:
+//   pi's sendUserMessage/sendMessage return `void`. Their loader dispatches an
+//   asynchronous runtime action and does NOT return the promise; a later
+//   delivery/prompt/queue/persist failure is caught and reported by the runtime,
+//   NOT thrown back here. So a send returning is a HANDOFF, not an acknowledgment
+//   — pi now owns the message, but has not necessarily accepted it.
+//
+//   We do NOT try to correlate an exactly-once acknowledgment (every scheme —
+//   content-matching message_start, getEntries confirmation, per-send identity —
+//   adds worse defects than it closes: input-hook transforms break content
+//   matching, message_start precedes persistence, getEntries matches historical
+//   entries). Instead the model is deliberately at-least-once:
+//     • The read `cursor` advances at buffer time (so a burst is never re-read
+//       into the same watcher's buffer) — NOT the durability boundary.
+//     • `handedOffWatermark` advances when a send call RETURNS NORMALLY. A sync
+//       throw or a critical-abort re-buffer never advances it.
+//     • The durable cursor commits `handedOffWatermark` (clamped below anything
+//       still in `buffer`) ONLY at `agent_settled` — and at `session_shutdown` as
+//       the graceful safety net. NOT at agent_end (fires on failure/abort before
+//       pi decides on retry/continuation), NOT on the idle send return, NOT on
+//       message_start. One rule: an idle send starts a turn, and that turn's
+//       settle commits it.
+//     • Defensive hold at settle when pi still reports unconsumed sends. In the
+//       installed pi 0.80.6 `AgentSession`, retry/compaction/queued
+//       continuations are all drained WITHIN the same prompt cycle (the
+//       `_handlePostAgentRun`→`agent.continue()` loop) BEFORE the sole
+//       extension-facing `agent_settled` fires — a low-level failure/abort emits
+//       `agent_end` first, but any handed-off steer/followUp is consumed before
+//       that same cycle's settle. So the NORMAL production settle already sees
+//       `ctx.hasPendingMessages() === false`. The hold is therefore a
+//       conservative coarse guard, not a load-bearing part of a
+//       failure→pending-settle→later-settle sequence: IF a context ever reports
+//       pending sends at settle (steer+followUp queue length > 0), committing
+//       would durably consume a message pi has not yet delivered, so we DECLINE
+//       and let a later drained settle advance the cursor. It is a global
+//       boolean we never match to a specific send, and it clears on its own once
+//       pi drains, so it can never permanently stall the cursor.
+//
+//   Accepted, deliberate residual windows (at-least-once by design):
+//     • A send whose promise pi later rejects INTERNALLY (swallowed by the
+//       runtime) never enters the queue, so hasPendingMessages() cannot see it
+//       and settle commits past it → rare silent loss. The alternative
+//       (correlation) demonstrably breaks the normal flow, so we accept this.
+//     • Crash/SIGKILL before settle → the fresh watcher re-reads from the last
+//       durable cursor and re-delivers (a duplicate coalesced pointer list, and
+//       an idempotent situational upsert re-read). Duplicate re-delivery, never
+//       silent loss.
+//   See `commitTarget` / `commitDurableCursor` / the agent_settled handler below.
+//
 // Double-notify prevention (copied from legacy watcher):
 //   A module-level `liveTimer` ensures that a /reload re-init clears the previous
 //   setInterval before starting a new one — exactly one watcher is live at a time.
@@ -91,6 +140,12 @@ export function registerCanvasInboxWatcher(pi) {
     pi.on('agent_end', (_e, ctx) => {
         captureCtx(_e, ctx);
         streaming = false;
+        // agent_end is NOT a durable-commit point. It fires when a low-level run
+        // ends, but pi may still auto-retry, auto-compact, or run a queued
+        // continuation (it fires on the failure/abort path too, before pi decides).
+        // Committing here would durably consume a still-queued followUp that a
+        // failure agent_end preceded. Commit happens only at agent_settled (or the
+        // session_shutdown safety net), never here.
     });
     /**
      * True when pi is not currently streaming a response.
@@ -108,21 +163,117 @@ export function registerCanvasInboxWatcher(pi) {
         return !streaming;
     };
     // ---------------------------------------------------------------------------
-    // Debounce state
+    // Debounce + durable-cursor state
     // ---------------------------------------------------------------------------
     /** Entries received since the last flush — coalesced into one message. */
     let buffer = [];
     /** Epoch-ms of the most recent entry arrival. Used to detect burst-quiet. */
     let lastArrival = 0;
     /**
-     * Durable cursor — ISO 8601 of the last entry we've consumed.
-     * Seeded from the persisted cursor file on first resolution; undefined means
-     * "read from the beginning" (no prior cursor → process all existing entries).
-     * NOT reset to `now` on first tick: that would silently drop entries that
-     * arrived between node creation and watcher startup (the startup race).
+     * In-memory read watermark — ISO 8601 of the last entry we've consumed FROM
+     * THE FILE. Seeded from the persisted cursor on first resolution; undefined
+     * means "read from the beginning" (no prior cursor → process all existing
+     * entries). NOT reset to `now` on first tick: that would silently drop
+     * entries that arrived between node creation and watcher startup (the
+     * startup race).
+     *
+     * This advances at buffer time (tick(), before delivery) purely to stop the
+     * same entries being re-read into `buffer` on the next tick — it is NOT the
+     * durability boundary. See `handedOffWatermark` / `commitDurableCursor` for that.
      */
     let cursor;
+    /**
+     * Cursor value actually persisted to `inbox.jsonl.cursor` on disk — the
+     * durability boundary a fresh watcher reseeds from after a crash/kick. It
+     * tracks work committed at a settle, never merely read.
+     */
+    let durableCursor;
+    /**
+     * High-water ts of batches whose send call RETURNED NORMALLY — pi now owns
+     * them (a handoff, not an acknowledgment). It never advances on a sync send
+     * throw or a critical-abort re-buffer (those roll back to `buffer`), and it is
+     * never itself the durability boundary: it is only committed, clamped, at a
+     * settle. The read `cursor` races ahead of it (advancing at buffer time before
+     * any send), which is why `cursor` is never persisted.
+     */
+    let handedOffWatermark;
     let seeded = false;
+    /** Record a batch handoff — pi's send returned normally. Never moves back. */
+    const handOff = (maxTs) => {
+        if (handedOffWatermark === undefined || maxTs > handedOffWatermark)
+            handedOffWatermark = maxTs;
+    };
+    /** Max ts across a batch of entries (its high-water for advancement). */
+    const batchMaxTs = (entries) => entries.reduce((a, b) => (a.ts > b.ts ? a : b)).ts;
+    /**
+     * The ts safe to persist right now: the handed-off high-water, but NEVER at or
+     * past anything still in `buffer` (debounced, re-buffered after a sync send
+     * throw, or held for a critical-abort retry). When a buffered entry sits at or
+     * below the handed-off high-water — a rare out-of-order case — we decline to
+     * advance at all rather than risk committing past it. Conservative by design:
+     * at worst a fresh watcher re-delivers an already-handled entry, never loses
+     * one.
+     */
+    const commitTarget = () => {
+        if (handedOffWatermark === undefined)
+            return undefined;
+        let earliest;
+        for (const e of buffer)
+            if (earliest === undefined || e.ts < earliest)
+                earliest = e.ts;
+        if (earliest === undefined)
+            return handedOffWatermark;
+        return handedOffWatermark < earliest ? handedOffWatermark : undefined;
+    };
+    /** Persist the commit watermark to disk if it has advanced past what's durable. */
+    const commitDurableCursor = (nodeId) => {
+        const target = commitTarget();
+        if (target === undefined)
+            return;
+        if (durableCursor === undefined || target > durableCursor) {
+            writeCursor(nodeId, target);
+            durableCursor = target;
+        }
+    };
+    const commitIfNode = () => {
+        const nodeId = process.env['CRTR_NODE_ID'];
+        if (nodeId !== undefined && nodeId.trim() !== '')
+            commitDurableCursor(nodeId);
+    };
+    /**
+     * Commit at a settle boundary, with a defensive HOLD while pi still reports
+     * unconsumed sends. `ctx.hasPendingMessages()` is the steer+followUp queue
+     * length — pi's own coarse truth. In the installed pi 0.80.6 `AgentSession`
+     * retry/compaction/queued continuations drain within the same prompt cycle
+     * before the sole extension-facing settle, so the normal production settle
+     * already sees this false. The hold is a conservative guard: IF a context ever
+     * reports pending sends at settle, committing would durably consume an entry
+     * pi has not yet delivered, so we decline. It is a global boolean, never
+     * matched to a specific send, and it clears on its own once pi drains, so it
+     * can never permanently stall the cursor. When the API is absent (older pi) we
+     * fall back to the plain commit-at-settle baseline.
+     */
+    const commitAtSettle = (ctx) => {
+        try {
+            if (ctx?.hasPendingMessages?.() === true)
+                return;
+        }
+        catch {
+            /* can't tell — fall through to the commit-at-settle baseline */
+        }
+        commitIfNode();
+    };
+    // ---------------------------------------------------------------------------
+    // agent_settled — the ONLY durable-commit boundary (session_shutdown is its
+    // graceful safety net). It fires once pi will not continue automatically (no
+    // retry, compaction, or queued continuation left). Commit the handed-off
+    // high-water, clamped below anything still buffered, and only when pi holds no
+    // unconsumed sends (hasPendingMessages()).
+    // ---------------------------------------------------------------------------
+    pi.on('agent_settled', (event, ctx) => {
+        captureCtx(event, ctx);
+        commitAtSettle(ctx);
+    });
     // ---------------------------------------------------------------------------
     // Flush: deliver the buffered entries as a single pi user message.
     // ---------------------------------------------------------------------------
@@ -145,28 +296,34 @@ export function registerCanvasInboxWatcher(pi) {
         // (context alone, no accompanying visible body) are dropped from the
         // visible batch entirely — they exist purely as a wake marker for this
         // delivery and must never surface a line in the digest.
-        const hasSituational = batch.some((e) => e.data?.['situational'] === true);
+        const situationalEntries = batch.filter((e) => e.data?.['situational'] === true);
         const visibleBatch = batch.filter((e) => e.data?.['situationalOnly'] !== true);
-        if (hasSituational) {
+        if (situationalEntries.length > 0) {
             const nodeId = process.env['CRTR_NODE_ID'];
             const text = nodeId !== undefined ? readSituationalContext(nodeId) : null;
             if (text !== null) {
+                const situationalContent = `<situational-context>\n${text}\n</situational-context>`;
                 try {
                     pi.sendMessage({
                         customType: SITUATIONAL_CONTEXT_CUSTOM_TYPE,
-                        content: `<situational-context>\n${text}\n</situational-context>`,
+                        content: situationalContent,
                         display: true,
                         details: { nodeId },
                     }, { deliverAs: 'followUp', triggerTurn: true });
+                    // Handed off — pi's send returned normally. It commits at the next
+                    // agent_settled (a custom send that async-rejected is the accepted
+                    // silent-loss window; hasPendingMessages() covers only user steer/
+                    // followUp, so a situational miss is not held).
+                    handOff(batchMaxTs(situationalEntries));
                 }
                 catch {
-                    // Re-queue on delivery failure — same durability contract as the visible
-                    // digest path below. The cursor already advanced past these entries in
-                    // tick(), so a swallowed failure here would otherwise drop the hidden
-                    // wake permanently (never re-read from the inbox, never retried). Only
-                    // the situational-only entries go back; a real re-send re-reads the
-                    // CURRENT sidecar value (upsert, not append), so retrying is idempotent
-                    // even if the text changed again in between.
+                    // Re-queue on a SYNCHRONOUS send failure (a stale-extension assertion
+                    // — an async delivery failure is swallowed by the runtime, not thrown
+                    // here). The read cursor already advanced past these entries in
+                    // tick(), so a swallowed failure with no re-queue would drop the
+                    // hidden wake permanently. Only the situational-only entries go back;
+                    // a real re-send re-reads the CURRENT sidecar value (upsert, not
+                    // append), so retrying is idempotent even if the text changed again.
                     buffer = batch.filter((e) => e.data?.['situationalOnly'] === true).concat(buffer);
                 }
             }
@@ -184,8 +341,11 @@ export function registerCanvasInboxWatcher(pi) {
         const steerMidStream = anyCritical || visibleBatch.some((e) => e.tier === 'urgent' || e.kind === 'final');
         try {
             if (isIdle()) {
-                // Idle → trigger a new turn immediately (sendUserMessage always triggers).
+                // Idle → trigger a new turn immediately (sendUserMessage always
+                // triggers). The send returns void (a handoff, not an ack), so we do NOT
+                // commit here — the turn this starts commits at its agent_settled.
                 pi.sendUserMessage(digest);
+                handOff(batchMaxTs(visibleBatch));
             }
             else if (anyCritical) {
                 // Critical mid-stream → TRUE preempt. ctx.abort() cancels the live LLM
@@ -194,7 +354,9 @@ export function registerCanvasInboxWatcher(pi) {
                 // path — by then the turn has torn down and sendUserMessage starts a fresh
                 // turn. Relying on the proven idle path (not steer-after-abort semantics)
                 // keeps this robust; if abort hasn't settled by the next tick we simply
-                // abort again and retry — idempotent and self-healing.
+                // abort again and retry — idempotent and self-healing. Nothing is handed
+                // off here (handedOffWatermark stays put) and the entry stays buffered,
+                // so the abort-generated agent_end/settle cannot commit past it.
                 try {
                     lastCtx?.abort?.();
                 }
@@ -203,13 +365,19 @@ export function registerCanvasInboxWatcher(pi) {
             }
             else {
                 // Mid-stream → steer on urgency or a finished node, else enqueue for the
-                // turn after this one.
+                // turn after this one. Handed to pi's in-memory queue now (returns
+                // normally = handoff). It commits at the turn's agent_settled — and if
+                // the turn fails/aborts before pi consumes it, hasPendingMessages() holds
+                // the commit until a later settle drains it.
                 pi.sendUserMessage(digest, { deliverAs: steerMidStream ? 'steer' : 'followUp' });
+                handOff(batchMaxTs(visibleBatch));
             }
         }
         catch {
-            // Re-queue on delivery failure so a transient error doesn't silently drop
-            // inbox entries. They will be retried on the next flush.
+            // Re-queue on a SYNCHRONOUS delivery failure so a transient error doesn't
+            // silently drop inbox entries. handedOffWatermark was not advanced and the
+            // entries are back in `buffer`, so no settle can commit past them. They
+            // will be retried on the next flush.
             buffer = visibleBatch.concat(buffer);
         }
     };
@@ -230,6 +398,7 @@ export function registerCanvasInboxWatcher(pi) {
             // with undefined returns ALL entries (no truncation to `now`).
             if (!seeded) {
                 cursor = readCursor(nodeId);
+                durableCursor = cursor;
                 seeded = true;
             }
             const newEntries = readInboxSince(nodeId, cursor);
@@ -244,12 +413,12 @@ export function registerCanvasInboxWatcher(pi) {
                 return;
             }
             if (newEntries.length > 0) {
-                // Advance and persist the cursor BEFORE buffering, so a crash after this
-                // point loses at most one coalesced message rather than re-injecting
-                // already-delivered entries on restart (exactly-once over restart contract).
+                // Advance the in-memory read watermark BEFORE buffering, so a re-tick
+                // during the debounce window never re-reads the same entries into
+                // `buffer`. This does NOT persist to disk — the durable cursor commits
+                // the handed-off high-water only at agent_settled (see commitDurableCursor).
                 const latest = newEntries.reduce((a, b) => (a.ts > b.ts ? a : b));
                 cursor = latest.ts;
-                writeCursor(nodeId, cursor);
                 buffer.push(...newEntries);
                 lastArrival = Date.now();
             }
@@ -277,6 +446,15 @@ export function registerCanvasInboxWatcher(pi) {
     // pi DOES fire session_shutdown — use it as the authoritative teardown so a
     // re-init (e.g. /reload) never discovers a live sibling timer.
     pi.on('session_shutdown', () => {
+        // Safety net on the graceful-teardown path: a last chance to persist the
+        // handed-off high-water. Same settle gate — commitTarget clamps below
+        // anything still buffered, and we HOLD if pi still holds unconsumed sends
+        // (they die with the process on shutdown, so a fresh watcher must re-read
+        // them). This does NOT cover the abrupt-kill path: the broker's SIGTERM
+        // handler runs disposeAndExit (session.dispose() + process.exit) without
+        // emitting this extension's session_shutdown, so this never fires on a kill
+        // — exactly why the durable cursor only ever advances at a settle boundary.
+        commitAtSettle(lastCtx);
         clearInterval(timer);
         if (liveTimer === timer)
             liveTimer = undefined;

package/dist/pi-extensions/canvas-recap.d.ts

@@ -22,6 +22,10 @@ interface ExtensionCtxLike {
     ui?: UIContextLike;
     mode?: string;
     sessionManager?: SessionManagerLike;
+    model?: {
+        provider?: string;
+        id?: string;
+    };
 }
 type PiEvents = 'session_start' | 'input' | 'turn_end' | 'session_shutdown';
 interface PiLike {

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

@@ -1,11 +1,12 @@
 // canvas-recap.ts — pi extension for pi-native canvas agent nodes.
 //
-// A per-node INACTIVITY RECAP, drawn as the topmost chrome above the editor.
-// When a node has had NO new message (user or assistant) for IDLE_MS (300s by
-// default), it runs Haiku over the literal conversation and pins a terse
-// three-fragment card — goal / doing-now / next — above canvas-nav's manager
-// line. The card disappears the instant the next message arrives, and the idle
-// clock restarts.
+// A per-node INACTIVITY BRIEF, drawn faintly immediately above the editor border.
+// When a node has had NO new message (user or assistant) for IDLE_MS (60s by
+// default), it runs a stripped-down headless call on the conversation's current
+// working model and pins one concise, wrapped briefing above the editor, so a
+// developer returning to the conversation sees where it left off at a glance.
+// The card disappears the instant the next message arrives, and the idle clock
+// restarts.
 //
 //   trigger/clear are keyed off MESSAGES, not turns-of-work:
 //     • a user `input` event OR an assistant `turn_end` resets the idle clock
@@ -13,15 +14,12 @@
 //     • a single low-rate timer (no busy-loop) checks elapsed-since-last-message
 //       and, on crossing IDLE_MS, generates + shows the recap once.
 //
-//   Haiku input = ALL user + assistant LITERAL text, most-recent within a char
+//   Brief input = ALL user + assistant LITERAL text, most-recent within a char
 //   budget. Tool calls, tool results, thinking blocks, and extension-injected
 //   custom messages are excluded (only `message` entries with role user/assistant,
 //   and only their `text` content blocks).
 //
-//   Placement: key `crtr-recap`, placement `aboveEditor`, ordered ABOVE
-//   `crtr-managers` via the widget-order bus (pi's widget store is insertion-
-//   ordered and re-setting moves a key to the bottom; after we paint the recap
-//   we ask canvas-nav to re-assert its manager line, which drops it below us).
+//   Placement: key `crtr-recap`, placement `aboveEditor`.
 //
 //   Surface gating: shows in BOTH the in-pane pi TUI (mode 'tui') and the
 //   headless broker → attach/web viewers (mode 'print', setWidget broadcasts to
@@ -35,21 +33,19 @@
 // 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 { generateRecap } from '../core/runtime/recap.js';
-import { requestNavRerender } from './widget-order-bus.js';
 // ---------------------------------------------------------------------------
 // Tuning constants
 // ---------------------------------------------------------------------------
-/** No-new-message window before a recap is shown. 300s by default; override with
+/** No-new-message window before a recap is shown. 60s by default; override with
  *  CRTR_RECAP_IDLE_MS (for fast runtime verification). */
 function idleMs() {
     const raw = process.env['CRTR_RECAP_IDLE_MS'];
     const n = raw !== undefined ? parseInt(raw, 10) : NaN;
-    return Number.isFinite(n) && n > 0 ? n : 300_000;
+    return Number.isFinite(n) && n > 0 ? n : 60_000;
 }
-/** How often the (single, low-rate) timer checks elapsed-since-last-message.
- *  Mirrors canvas-nav's ASK_POLL_MS — cheap and tmux/crtr-free. */
+/** How often the single low-rate timer checks elapsed-since-last-message. */
 const POLL_MS = 7_000;
-/** Char budget on the conversation fed to Haiku — the model only needs the gist,
+/** Char budget on the conversation fed to the brief model — it only needs the gist,
  *  so we keep the MOST-RECENT text within this cap (a recap is about where we
  *  left off, not the whole history). */
 const CONVO_CHAR_BUDGET = 12_000;
@@ -124,12 +120,22 @@ export function registerCanvasRecap(pi) {
     // Captured on session_start; used by the timer and the message handlers.
     let ui;
     let sessionManager;
+    /** Exact provider/model that most recently ran this conversation successfully.
+     *  The recap subprocess prefers it over a hard-pinned provider that may be in
+     *  cooldown (the failure mode that made the old recap silently disappear). */
+    let liveModel;
+    const captureLiveModel = (ctx) => {
+        const provider = ctx.model?.provider?.trim();
+        const id = ctx.model?.id?.trim();
+        if (provider && id)
+            liveModel = `${provider}/${id}`;
+    };
     /** Wall-clock of the most recent user/assistant message. The idle clock. */
     let lastMessageAt = Date.now();
     /** True while a recap is currently shown (so we generate at most once per
      *  idle window, and know whether a clear is needed on the next message). */
     let recapShown = false;
-    /** True while a Haiku generation is in flight (so we don't fire a second). */
+    /** True while a briefing generation is in flight (so we don't fire a second). */
     let generating = false;
     const canPaint = () => ui !== undefined && typeof ui.setWidget === 'function';
     const clearRecap = () => {
@@ -140,21 +146,14 @@ export function registerCanvasRecap(pi) {
         }
         catch { /* best-effort */ }
     };
-    /** Render the three fragments as the topmost above-editor card. */
-    const showRecap = (fragments) => {
-        if (!canPaint())
-            return;
-        const labels = ['◷ goal', '· now ', '→ next'];
-        const lines = fragments.slice(0, 3).map((f, i) => `${labels[i] ?? '    '}  ${f}`);
-        if (lines.length === 0)
+    /** Render the briefing into the viewer's low-contrast above-editor slot. */
+    const showRecap = (briefing) => {
+        if (!canPaint() || briefing === '')
             return;
         try {
-            ui.setWidget(WIDGET_KEY, lines, { placement: 'aboveEditor' });
+            ui.setWidget(WIDGET_KEY, [`Brief: ${briefing}`], { placement: 'aboveEditor' });
         }
         catch { /* best-effort */ }
-        // Re-assert the manager line BELOW us (pi's widget store is insertion-
-        // ordered; re-setting crtr-managers drops it under crtr-recap).
-        requestNavRerender();
     };
     /** A user or assistant message landed: reset the idle clock and clear any
      *  shown recap (the conversation has moved on). */
@@ -163,7 +162,6 @@ export function registerCanvasRecap(pi) {
         if (recapShown) {
             recapShown = false;
             clearRecap();
-            requestNavRerender();
         }
     };
     // -------------------------------------------------------------------------
@@ -172,6 +170,7 @@ export function registerCanvasRecap(pi) {
     pi.on('session_start', (_event, ctx) => {
         ui = ctx.ui;
         sessionManager = ctx.sessionManager;
+        captureLiveModel(ctx);
         // Fresh session / hot-swap: start the idle clock now and drop any stale
         // recap that bled through a /reload.
         lastMessageAt = Date.now();
@@ -183,12 +182,14 @@ export function registerCanvasRecap(pi) {
         // Every user message (any source) is activity — reset + clear.
         onMessage();
     });
-    pi.on('turn_end', (_event, _ctx) => {
-        // A completed assistant turn is activity — reset + clear.
+    pi.on('turn_end', (_event, ctx) => {
+        // A completed assistant turn is activity — reset + clear, and remember the
+        // exact model/provider that successfully produced it for the later recap.
+        captureLiveModel(ctx);
         onMessage();
     });
     // -------------------------------------------------------------------------
-    // The single low-rate idle poll — no busy-loop, mirrors canvas-nav's timer.
+    // The single low-rate idle poll.
     // -------------------------------------------------------------------------
     if (liveTimer !== undefined)
         clearInterval(liveTimer);
@@ -203,19 +204,19 @@ export function registerCanvasRecap(pi) {
             const convo = buildConversation(sessionManager);
             if (convo === '')
                 return; // nothing to summarize yet
-            // Snapshot the clock: if a message arrives while Haiku runs, discard the
+            // Snapshot the clock: if a message arrives while generation runs, discard the
             // (now-stale) result instead of painting over the live conversation.
             const startedAt = lastMessageAt;
             generating = true;
-            generateRecap(convo, (fragments) => {
+            generateRecap(convo, (briefing) => {
                 generating = false;
                 if (lastMessageAt !== startedAt)
                     return; // a message landed mid-flight
                 if (!canPaint())
                     return;
                 recapShown = true;
-                showRecap(fragments);
-            });
+                showRecap(briefing);
+            }, liveModel);
             // generateRecap is silent on failure (never calls back), so clear the
             // in-flight flag after the timeout window even if no callback fires.
             setTimeout(() => { generating = false; }, 30_000).unref?.();

package/dist/pi-extensions/canvas-stophook.d.ts

@@ -4,6 +4,17 @@ interface PiLike {
     sendUserMessage: (content: string, options?: {
         deliverAs?: 'steer' | 'followUp';
     }) => void;
+    /** Custom-message injection — used for the 'nextTurn' hold (queued silently,
+     *  injected alongside the NEXT user message, never triggers a turn). */
+    sendMessage: (message: {
+        customType: string;
+        content: string;
+        display?: boolean;
+        details?: Record<string, unknown>;
+    }, options?: {
+        deliverAs?: 'steer' | 'followUp' | 'nextTurn';
+        triggerTurn?: boolean;
+    }) => void;
 }
 /** 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

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

@@ -481,12 +481,35 @@ export function registerCanvasStophook(pi) {
         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).
-        // Delivered as a 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).
+        // 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.
@@ -497,7 +520,13 @@ export function registerCanvasStophook(pi) {
             const at = contextTokens !== null ? steerBand(contextTokens) : null;
             if (at !== null && !firedBands.has(at)) {
                 firedBands.add(at);
-                pi.sendUserMessage(`[crtr] ${steerNote(at, lifecycle, mode)}`, { deliverAs: 'steer' });
+                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 {

package/dist/suppress-experimental-warnings.d.ts

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

package/dist/suppress-experimental-warnings.js

@@ -0,0 +1,15 @@
+const originalEmit = process.emit;
+process.emit = function (name, ...args) {
+    const [data] = args;
+    if (name === 'warning' &&
+        data instanceof Error &&
+        data.name === 'ExperimentalWarning' &&
+        data.message.includes('SQLite')) {
+        return false;
+    }
+    return originalEmit.apply(this, [
+        name,
+        ...args,
+    ]);
+};
+export {};