@crouton-kit/crouter 0.3.70 → 0.3.79

package/dist/daemon/crtrd.js

@@ -139,6 +139,160 @@ function clearStrandedRelaunchState(id) {
     strandedRelaunchAttempts.delete(id);
     strandedRelaunchLastAttempt.delete(id);
 }
+// Idle-release/inbox retry cap (2026-07-10 diagnosis, round 2): the SAME
+// livelock shape as the stranded-relaunch case above, but on the SEPARATE
+// pass-2 path that resumes a dormant idle-released node the instant its inbox
+// gains an unseen entry. That path called reviveNode() unconditionally every
+// poll with no grace, no backoff, and no attempt cap.
+//
+// ROUND 1 keyed the retry counter on row-state residency (pid liveness),
+// cleared the instant the pid-alive branch observed a live engine. That
+// caught a broker that never boots at all — but the RECURRING incident's
+// actual failure is TURN-level, not launch-level: the revive succeeds (broker
+// launches, records a pid — clearing the round-1 counter), the turn then
+// faults against the provider, the engine exits with the inbox CURSOR
+// UNADVANCED, the node re-enters idle/idle-release, pass-2 sees the same
+// unseen entries again, and — because the counter was just cleared by the
+// transiently-alive engine — starts over at attempt 1/6 every single cycle.
+// crtrd.err showed exactly this: hundreds of `attempt 1/6` lines, never
+// `2/6`, interleaved with `fatal-fault <id> (other, pi→provider)`.
+//
+// ROUND 2 fix: key the counter on INBOX-CURSOR PROGRESS, not row-state
+// residency or pid liveness. `readCursor(id)` is recorded as the state's
+// baseline the first time a stuck delivery is observed; a transiently-alive
+// engine does NOT reset it (there is no pid-alive clear for this state
+// anymore — see handleNodeLiveness). Only an ADVANCED cursor on the NEXT
+// observation — proof the wake actually delivered something — resets the
+// counter (via `progressed` below); an unchanged cursor is the SAME stuck
+// delivery and increments/backs off exactly like the stranded-relaunch path.
+const IDLE_RELEASE_RELAUNCH_MAX_ATTEMPTS = 6;
+const IDLE_RELEASE_RELAUNCH_MAX_BACKOFF_MS = 10 * 60_000; // 10 minutes
+const idleReleaseRelaunchState = new Map();
+function idleReleaseRelaunchBackoffMs(attempts) {
+    return Math.min(REVIVE_GRACE_MS * 2 ** attempts, IDLE_RELEASE_RELAUNCH_MAX_BACKOFF_MS);
+}
+/** Cleared ONLY when the node row itself is gone, or once the counter gives
+ *  up and terminalizes the node — NEVER on a transiently-alive engine (that
+ *  was round 1's bug) and never on a bare idle-release status flap (the
+ *  fault-recovery cycle flaps status EVERY episode, so clearing on that would
+ *  reproduce the exact same livelock one level up). */
+function clearIdleReleaseRelaunchState(id) {
+    idleReleaseRelaunchState.delete(id);
+}
+// ---------------------------------------------------------------------------
+// Concurrency cap (2026-07-10 incident): nothing previously bounded how many
+// live brokers the daemon's automatic supervision sweep would launch. Each pi
+// broker is tens-to-hundreds of MB resident and grows with context; on one
+// machine 223 accumulated, exhausted ~19GB of swap, and froze the host — all
+// parked idle in kevent, not doing work, just wedged. Cap the FIVE reviveNode
+// call sites in THIS file (the daemon's automatic sweep) at a sane per-host
+// default; override via CRTR_MAX_LIVE_BROKERS for a beefier host. Deliberately
+// does NOT apply to `node lifecycle revive` / `node focus` — those call
+// reviveNode directly from their own command files, never through this file,
+// so an explicit human ask for a specific node is never blocked by this cap.
+const DEFAULT_MAX_LIVE_BROKERS = 64;
+function maxLiveBrokers() {
+    const raw = process.env['CRTR_MAX_LIVE_BROKERS'];
+    if (raw === undefined || raw === '')
+        return DEFAULT_MAX_LIVE_BROKERS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : DEFAULT_MAX_LIVE_BROKERS;
+}
+// Row-census blind spot (2026-07-10 incident, round 2): the cap's `count`
+// originally seeded ONLY from rows whose recorded `pi_pid` reads confirmed-
+// alive. A broker that spawns but never re-records its pid (the exact
+// stranded-relaunch shape REVIVE_GRACE_MS/strandedRelaunch* exist to recover
+// from) is INVISIBLE to that census — the row still shows pid=null or a stale
+// dead pid. So the row census stayed near-zero while ~190 such brokers piled
+// up as real OS processes, every 2s tick believed it had headroom under
+// max=16, and kept launching straight past the cap.
+//
+// Fix: also census the ACTUAL OS processes. Every broker is launched as
+// `<hostExecPath> <.../broker-cli.js> <nodeId>` (host.ts's one launch()
+// call site) — `broker-cli.js` is a stable, distinctive substring of every
+// broker's full command line and nothing else's. One `ps` shell-out per tick
+// (same primitive/cost class as the wedge detector's own `ps -ax` sample
+// just below) counts them directly, with no dependency on any canvas-row
+// state at all. `count` is then max(rowCensus, osCensus) — see superviseTick
+// — so a failed/unavailable probe (null here) can only ever make the daemon
+// MORE permissive than the row census alone, never less; it is never treated
+// as "zero live brokers" and can only widen the effective cap toward the row
+// census, matching the "never undercount, fail toward the row census" brief.
+function countLiveBrokerProcesses() {
+    try {
+        const r = spawnSync('ps', ['-ax', '-o', 'command='], { encoding: 'utf8', timeout: 2000 });
+        if (r.status !== 0 || typeof r.stdout !== 'string')
+            return null;
+        let count = 0;
+        for (const line of r.stdout.split('\n')) {
+            if (line.includes('broker-cli.js'))
+                count++;
+        }
+        return count;
+    }
+    catch {
+        return null;
+    }
+}
+// Over-cap surfacing (2026-07-10 incident follow-up): the daemon's own launch
+// sites are all capacity-gated, so the OS census EXCEEDING the cap means
+// brokers are leaking or arriving out-of-band (explicit `node lifecycle
+// revive`/`node focus` runs, the ungated fresh_revive clock pass, or a
+// stranded-spawn pile-up). That condition was invisible in crtrd.err unless
+// someone went looking — and the last time it went unnoticed it ended in swap
+// exhaustion and a frozen host. Surface it where the human actually is: a
+// throttled `tmux display-message` on every attached client (tmux is crtr's
+// one guaranteed viewer surface). No tmux server / no clients → silent no-op;
+// the stderr line still records the condition either way.
+const OVER_CAP_WARN_THROTTLE_MS = 5 * 60_000;
+let lastOverCapWarnAt = Number.NEGATIVE_INFINITY;
+function warnOverCapInTmux(count, max) {
+    const now = Date.now();
+    if (now - lastOverCapWarnAt < OVER_CAP_WARN_THROTTLE_MS)
+        return;
+    lastOverCapWarnAt = now;
+    process.stderr.write(`[crtrd] over-cap: ${count} live brokers exceed max ${max} — surfacing to tmux clients\n`);
+    const msg = `⚠ crtrd: ${count} live brokers (cap ${max}) — possible broker leak. ps -ax | grep broker-cli.js`;
+    try {
+        const clients = spawnSync('tmux', ['list-clients', '-F', '#{client_name}'], {
+            encoding: 'utf8',
+            timeout: 2000,
+        });
+        if (clients.status !== 0 || typeof clients.stdout !== 'string')
+            return;
+        for (const client of clients.stdout.split('\n')) {
+            if (client === '')
+                continue;
+            // -d 10000 holds the message for 10s (tmux ≥3.2); if this tmux predates
+            // -d, fall back to the default display-time rather than not warning.
+            const r = spawnSync('tmux', ['display-message', '-d', '10000', '-c', client, msg], { encoding: 'utf8', timeout: 2000 });
+            if (r.status !== 0) {
+                spawnSync('tmux', ['display-message', '-c', client, msg], {
+                    encoding: 'utf8',
+                    timeout: 2000,
+                });
+            }
+        }
+    }
+    catch {
+        /* no tmux server — the stderr line above still records the condition */
+    }
+}
+// Throttle for the "at capacity" log line: without it, every deferred revive
+// on every 2s poll would spam crtrd.err as badly as the livelock this cap
+// exists to prevent.
+const CAPACITY_LOG_THROTTLE_MS = 30_000;
+let lastCapacityLogAt = Number.NEGATIVE_INFINITY;
+function hasBrokerCapacity(capacity) {
+    if (capacity.count < capacity.max)
+        return true;
+    const now = Date.now();
+    if (now - lastCapacityLogAt >= CAPACITY_LOG_THROTTLE_MS) {
+        lastCapacityLogAt = now;
+        process.stderr.write(`[crtrd] at broker capacity (${capacity.count}/${capacity.max}) — deferring automatic revives to next poll\n`);
+    }
+    return false;
+}
 // §H refresh-authority grace: how long a node may sit with intent='refresh', its
 // turn OVER (busy marker absent) and its engine still ALIVE before the daemon
 // concludes the refresh stalled and force-kills the engine. The healthy window is
@@ -697,7 +851,7 @@ export function retryResumeMode(meta) {
  *      dead engine's last launch attempt was itself a cycling revive that never
  *      reached session_start (cycle_pending) — then retry it AS a cycle instead
  *      (retryResumeMode). */
-async function handleNodeLiveness(row, now, revivedThisTick) {
+async function handleNodeLiveness(row, now, revivedThisTick, capacity) {
     const id = row.node_id;
     const pid = row.pi_pid;
     // The engine is live → nothing pending; clear any boot/grace timer. THEN
@@ -725,6 +879,11 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
     if (pid != null && recordedPidLiveness(pid, row.pi_pid_identity) === 'alive') {
         unhealthySince.delete(id);
         clearStrandedRelaunchState(id); // a live engine means the stranding resolved
+        // Deliberately NOT clearing idleReleaseRelaunchState here (2026-07-10,
+        // round 2): a TRANSIENTLY-alive engine — one that boots, then faults its
+        // turn and dies again with the inbox cursor unadvanced — is exactly the
+        // recurrence this state now guards against. Only cursor PROGRESS (checked
+        // in pass 2, keyed on readCursor) may reset that counter.
         handleYieldStall(row, pid, now);
         handleWedgeDetection(id, pid, now);
         handleFatalFault(id, now);
@@ -800,10 +959,13 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
             const backoff = strandedRelaunchBackoffMs(attempts);
             if (lastAttempt !== undefined && now - lastAttempt < backoff)
                 return; // backing off before the next attempt
+            if (!hasBrokerCapacity(capacity))
+                return; // deferred, not attempted — costs no retry budget
             strandedRelaunchAttempts.set(id, attempts + 1);
             strandedRelaunchLastAttempt.set(id, now);
             process.stderr.write(`[crtrd] revive ${id} (stranded relaunch — pid never re-recorded, attempt ${attempts + 1}/${STRANDED_RELAUNCH_MAX_ATTEMPTS})\n`);
             reviveNode(id, { resume: retryResumeMode(meta) });
+            capacity.count++;
             revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
             return;
         }
@@ -824,9 +986,13 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
     yieldTermAt.delete(id);
     if (row.intent === 'refresh') {
         // Clean yield — or the §H force-kill above just landed — → respawn FRESH,
-        // immediately (no grace wait).
+        // immediately (no grace wait), UNLESS the daemon is already at its live-
+        // broker cap — then defer to the next poll rather than launching over it.
+        if (!hasBrokerCapacity(capacity))
+            return;
         process.stderr.write(`[crtrd] revive ${id} (refresh-yield)\n`);
         reviveNode(id, { resume: false });
+        capacity.count++;
         revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
         return;
     }
@@ -883,8 +1049,11 @@ async function handleNodeLiveness(row, now, revivedThisTick) {
         }
         return;
     }
+    if (!hasBrokerCapacity(capacity))
+        return; // deferred — retried plainly next poll
     process.stderr.write(`[crtrd] revive ${id} (engine dead, intent=${String(row.intent)})\n`);
     reviveNode(id, { resume: retryResumeMode(meta) });
+    capacity.count++;
     revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
 }
 /** Fail loud for a drifted/broken trigger (design §6.6/Q5): wake the ARMER
@@ -1137,6 +1306,24 @@ export async function superviseTick(now = Date.now()) {
     // Node-ids revived in pass 1 + pass 2 THIS tick — the third pass's bare branch
     // skips them so it never launches a second pi on the same .jsonl (Maj-4).
     const revivedThisTick = new Set();
+    // Concurrency-cap budget for this tick (2026-07-10 incident, round 2 — see
+    // countLiveBrokerProcesses's doc for the row-census blind spot this closes).
+    // Seed from max(rowCensus, osCensus): the row census alone undercounts any
+    // broker that spawned but never re-recorded its pid, so it can never be the
+    // sole source of truth for a HARD cap; `?? 0` on a failed/unavailable OS
+    // probe degrades exactly to the row census (never lower — a null probe must
+    // never be read as "zero live brokers"). Threaded by reference through both
+    // automatic-revive passes below so a burst of due revives in one tick can't
+    // collectively launch past the cap.
+    const rowLiveBrokerCount = rows.filter((r) => r.pi_pid != null && recordedPidLiveness(r.pi_pid, r.pi_pid_identity) === 'alive').length;
+    const capacity = {
+        count: Math.max(rowLiveBrokerCount, countLiveBrokerProcesses() ?? 0),
+        max: maxLiveBrokers(),
+    };
+    // Already OVER the cap at tick start — the daemon can't have done this
+    // (every launch site below is gated), so tell the human about the leak.
+    if (capacity.count > capacity.max)
+        warnOverCapInTmux(capacity.count, capacity.max);
     for (const row of rows) {
         try {
             // Every node is broker-hosted (host_kind always 'broker'; pane/window/
@@ -1144,7 +1331,7 @@ export async function superviseTick(now = Date.now()) {
             // pane, if any, is just a viewer — the daemon never consults it and a viewer
             // closing is not a node death. There is no inline-root carve-out and no
             // pane-gone reaping: one liveness path for all.
-            await handleNodeLiveness(row, now, revivedThisTick);
+            await handleNodeLiveness(row, now, revivedThisTick, capacity);
         }
         catch (err) {
             // One bad node must never kill the loop.
@@ -1155,13 +1342,32 @@ export async function superviseTick(now = Date.now()) {
     // The in-process inbox-watcher dies with pi, so the daemon owns wake-on-message
     // for dormant nodes. readCursor is the cursor the watcher persisted before
     // exit; any entry past it is undelivered work — resume the node to handle it.
+    //
+    // Backoff + attempt cap, keyed on CURSOR PROGRESS (2026-07-10 incident, round
+    // 2 — see the idleReleaseRelaunchState doc above for the full failure-mode
+    // writeup): a node whose delivery keeps failing — whether the broker never
+    // boots, OR it boots and then faults its turn before advancing the cursor —
+    // used to be relaunched here every poll (round 1) or every fault-recovery
+    // cycle (round 1's fix, still exploitable), forever. The counter now only
+    // resets when readCursor(id) has actually moved since the last time this
+    // node's stuck delivery was considered — proof the wake accomplished
+    // something — never on a bare status flap or a transiently-alive engine.
+    // Capacity-checked too, so a burst of due idle-release wakes can't stampede
+    // past the live-broker cap either.
     for (const row of rows) {
+        const id = row.node_id;
         try {
             // Re-read the ROW for fresh runtime (the first pass may have mutated it);
             // no meta needed — status/intent live in the row.
-            const r = getRow(row.node_id);
-            if (r === null)
+            const r = getRow(id);
+            if (r === null) {
+                clearIdleReleaseRelaunchState(id); // node gone — nothing left to track
                 continue;
+            }
+            // NOT idle-release right now (e.g. mid fault-recovery, briefly active) —
+            // leave idleReleaseRelaunchState UNTOUCHED. Clearing here would let the
+            // fault-recovery cycle (idle-release → briefly alive → fault → idle-
+            // release again) reset the counter every episode — the exact round-2 bug.
             if (r.status !== 'idle' || r.intent !== 'idle-release')
                 continue;
             // The in-process inbox-watcher only owns delivery while the engine is LIVE.
@@ -1169,18 +1375,53 @@ export async function superviseTick(now = Date.now()) {
             // has no watcher and the daemon must wake it. Gate the skip on engine
             // liveness alone — viewer panes are irrelevant here. Identity-aware: a
             // bare isPidAlive would misread a reused pid as "still alive" and skip
-            // the revive forever, stranding the node on its unseen inbox entry.
+            // the revive forever, stranding the node on its unseen inbox entry. Same
+            // no-clear rule as above — a transiently-alive engine proves nothing about
+            // delivery progress.
             if (r.pi_pid != null && isRecordedPidAlive(r.pi_pid, r.pi_pid_identity))
                 continue;
-            const entries = readInboxSince(row.node_id, readCursor(row.node_id));
-            if (entries.length > 0) {
-                process.stderr.write(`[crtrd] revive ${row.node_id} (idle-release, inbox)\n`);
-                reviveNode(row.node_id, { resume: true });
-                revivedThisTick.add(row.node_id); // third-pass bare double-spawn guard (Maj-4)
+            const cursorNow = readCursor(id);
+            const entries = readInboxSince(id, cursorNow);
+            if (entries.length === 0) {
+                clearIdleReleaseRelaunchState(id); // fully delivered — no stuck episode to track
+                continue;
+            }
+            const prior = idleReleaseRelaunchState.get(id);
+            // Cursor progress since the LAST time this episode was considered (or no
+            // prior episode at all) — the ONLY thing allowed to reset the counter.
+            const progressed = prior === undefined || prior.cursor !== cursorNow;
+            const attempts = progressed ? 0 : prior.attempts;
+            if (attempts >= IDLE_RELEASE_RELAUNCH_MAX_ATTEMPTS) {
+                clearIdleReleaseRelaunchState(id);
+                const meta = getNode(id);
+                process.stderr.write(`[crtrd] giving up on ${id} after ${attempts} idle-release relaunch attempts (no inbox-cursor progress)\n`);
+                transition(id, 'crash');
+                if (meta !== null) {
+                    try {
+                        fanDoctrineWake(id, subscribersOf(id), `Child crashed — ${fullName(meta)} (${id}) failed to relaunch after ${attempts} attempts while trying to ` +
+                            `deliver a pending inbox message (no delivery progress across any attempt), and is now dead. It stays ` +
+                            `dead until you revive it — \`crtr node lifecycle revive ${id}\`.`, { reason: 'child-crashed', child: id });
+                    }
+                    catch {
+                        /* best-effort, mirrors every other fan-out in this file */
+                    }
+                }
+                continue;
             }
+            const lastAttempt = progressed ? undefined : prior?.lastAttempt;
+            const backoff = idleReleaseRelaunchBackoffMs(attempts);
+            if (lastAttempt !== undefined && now - lastAttempt < backoff)
+                continue; // backing off before the next attempt
+            if (!hasBrokerCapacity(capacity))
+                continue; // deferred, not attempted — costs no retry budget
+            idleReleaseRelaunchState.set(id, { cursor: cursorNow, attempts: attempts + 1, lastAttempt: now });
+            process.stderr.write(`[crtrd] revive ${id} (idle-release, inbox, attempt ${attempts + 1}/${IDLE_RELEASE_RELAUNCH_MAX_ATTEMPTS})\n`);
+            reviveNode(id, { resume: true });
+            capacity.count++;
+            revivedThisTick.add(id); // third-pass bare double-spawn guard (Maj-4)
         }
         catch (err) {
-            process.stderr.write(`[crtrd] error polling inbox ${row.node_id}: ${err.message}\n`);
+            process.stderr.write(`[crtrd] error polling inbox ${id}: ${err.message}\n`);
         }
     }
     // Third pass: FIRE DUE CLOCK TRIGGERS (the triggers engine, migration v9).

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

@@ -21,6 +21,7 @@ import { closeDb } from '../../core/canvas/db.js';
 import { reportsDir } from '../../core/canvas/paths.js';
 import { readInboxSince } from '../../core/feed/inbox.js';
 import { STALL_REPROMPT } from '../../core/runtime/stop-guard.js';
+import { recordFault, readFault } from '../../core/runtime/fault.js';
 let home;
 let origNode;
 let origPane;
@@ -262,6 +263,46 @@ test('refresh-yield (intent=refresh) writes NO push — silent to subscribers',
     assert.equal(readInboxSince('root').length, 0, 'a yield is silent: NO inbox pointer');
     assert.equal(pi.injected.length, 0, 'no reprompt on a refresh-yield');
 });
+// ---------------------------------------------------------------------------
+// turn_end — stale-⚠ fix: reaching turn_end proves the current provider
+// round-trip and any wedge episode are both over, so both fault links clear.
+// ---------------------------------------------------------------------------
+/** A turn_end event carrying one assistant text block. */
+function turnEndEvent(text) {
+    return { message: { role: 'assistant', content: [{ type: 'text', text }] } };
+}
+test('turn_end clears a stale pi→provider fatal fault (a completed round-trip proves the episode is over)', () => {
+    createNode(node('leaf', { parent: null, lifecycle: 'terminal' }));
+    recordFault('leaf', {
+        link: 'pi→provider',
+        op: 'generation turn',
+        kind: 'other',
+        retry: { disposition: 'fatal' },
+        message: 'terminated',
+    });
+    assert.notEqual(readFault('leaf'), null, 'precondition: fault marker recorded');
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('turn_end', turnEndEvent('all good now'), {});
+    assert.equal(readFault('leaf'), null, 'the pi→provider fault is cleared at turn_end');
+});
+test('turn_end still clears a daemon→node wedge fault (existing behavior, unchanged)', () => {
+    createNode(node('leaf', { parent: null, lifecycle: 'terminal' }));
+    recordFault('leaf', {
+        link: 'daemon→node',
+        op: 'wedge detection',
+        kind: 'wedged',
+        retry: { disposition: 'manual' },
+        message: 'no progress for 20m',
+    });
+    assert.notEqual(readFault('leaf'), null, 'precondition: wedge fault recorded');
+    process.env['CRTR_NODE_ID'] = 'leaf';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('turn_end', turnEndEvent('turn completed'), {});
+    assert.equal(readFault('leaf'), null, 'the daemon→node wedge fault is still cleared at turn_end');
+});
 test('stalled leaf (nothing live to await, no final) is still reprompted', () => {
     createNode(node('mgr', { parent: null, lifecycle: 'terminal', mode: 'orchestrator' }));
     createNode(node('leaf', { parent: 'mgr', lifecycle: 'terminal', status: 'active' }));

package/dist/pi-extensions/__tests__/canvas-stophook-context-nudge.test.d.ts

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

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

@@ -0,0 +1,121 @@
+// Run with: node --import tsx/esm --test src/pi-extensions/__tests__/canvas-stophook-context-nudge.test.ts
+//
+// The context-size nudge's delivery mode splits on whether the agent run
+// continues past the turn. The regression this pins: the nudge used to be an
+// unconditional STEER, and pi's agent loop drains the steering queue right
+// after turn_end — so a band crossing on the run's FINAL message (no tool
+// calls) extended the run past the agent's closing reply, burying the summary
+// a human comes back to read once the conversation goes quiet.
+//   • turn_end with toolCall content (mid-run) → sendUserMessage steer
+//   • turn_end with text-only content (final)  → sendMessage 'nextTurn' hold
+//
+// Second regression pinned here: a tool-calling turn ends with stopReason
+// 'toolUse' (pi-ai's StopReason), NEVER 'stop'. Gating the steer path on
+// stopReason 'stop'/'length' made runContinues unconditionally false, so the
+// nudge was ALWAYS appended as nextTurn and never steered mid-run.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import registerCanvasStophook from '../canvas-stophook.js';
+import { createNode } from '../../core/canvas/canvas.js';
+import { closeDb } from '../../core/canvas/db.js';
+let home;
+let origNode;
+function node(id) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: '/tmp/work',
+        kind: 'general',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+    };
+}
+function makeFakePi() {
+    const handlers = {};
+    return {
+        steered: [],
+        held: [],
+        on(e, h) { handlers[e] = h; },
+        sendUserMessage(content, options) { this.steered.push({ content, deliverAs: options?.deliverAs }); },
+        sendMessage(m, options) {
+            this.held.push({ customType: m.customType, content: m.content, deliverAs: options?.deliverAs, triggerTurn: options?.triggerTurn });
+        },
+        fire(e, ev, ctx) { handlers[e]?.(ev, ctx); },
+    };
+}
+/** A turn_end event whose assistant message crossed a steering band. A
+ *  tool-calling turn really ends with stopReason 'toolUse'; text-only finals
+ *  end with 'stop'. */
+function turnEnd(content, stopReason = 'stop') {
+    return { message: { role: 'assistant', stopReason, content, usage: { input: 1, output: 1 } }, toolResults: [] };
+}
+const ctxAt = (tokens) => ({ getContextUsage: () => ({ tokens }) });
+before(() => { origNode = process.env['CRTR_NODE_ID']; });
+beforeEach(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    home = mkdtempSync(join(tmpdir(), 'crtr-stophook-nudge-'));
+    process.env['CRTR_HOME'] = home;
+});
+after(() => {
+    closeDb();
+    if (home)
+        rmSync(home, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+    if (origNode === undefined)
+        delete process.env['CRTR_NODE_ID'];
+    else
+        process.env['CRTR_NODE_ID'] = origNode;
+});
+test('band crossing mid-run (tool calls present) → context nudge is a STEER', () => {
+    createNode(node('midrun'));
+    process.env['CRTR_NODE_ID'] = 'midrun';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'toolUse'), ctxAt(150_000));
+    assert.equal(pi.steered.length, 1, 'exactly one steer delivered');
+    assert.equal(pi.steered[0].deliverAs, 'steer');
+    assert.match(pi.steered[0].content, /^\[crtr\] Context ~150k/);
+    assert.equal(pi.held.length, 0, 'nothing held for nextTurn');
+});
+test('band crossing on the FINAL message (no tool calls) → nudge is HELD as nextTurn, never a steer', () => {
+    createNode(node('final'));
+    process.env['CRTR_NODE_ID'] = 'final';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('turn_end', turnEnd([{ type: 'text', text: 'here is my summary' }]), ctxAt(150_000));
+    assert.equal(pi.steered.length, 0, 'no steer — a steer here would extend the run past the closing reply');
+    assert.equal(pi.held.length, 1, 'nudge held for the next user message');
+    assert.equal(pi.held[0].deliverAs, 'nextTurn');
+    assert.equal(pi.held[0].customType, 'crtr-context-nudge');
+    assert.match(pi.held[0].content, /^\[crtr\] Context ~150k/);
+    assert.notEqual(pi.held[0].triggerTurn, true, 'must not trigger a turn');
+});
+test('a truncated tool-calling turn (stopReason length) still steers — the loop continues past failed calls', () => {
+    createNode(node('lengthrun'));
+    process.env['CRTR_NODE_ID'] = 'lengthrun';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'length'), ctxAt(150_000));
+    assert.equal(pi.steered.length, 1);
+    assert.equal(pi.steered[0].deliverAs, 'steer');
+    assert.equal(pi.held.length, 0);
+});
+test('an aborted final turn also holds (the loop ends unconditionally on abort)', () => {
+    createNode(node('aborted'));
+    process.env['CRTR_NODE_ID'] = 'aborted';
+    const pi = makeFakePi();
+    registerCanvasStophook(pi);
+    // Aborted mid-tool-call: toolCall content present, but the run ends anyway —
+    // a steer would sit queued and leak into the NEXT run's start instead.
+    pi.fire('turn_end', turnEnd([{ type: 'toolCall', id: 't1', name: 'bash', arguments: {} }], 'aborted'), ctxAt(150_000));
+    assert.equal(pi.steered.length, 0);
+    assert.equal(pi.held.length, 1);
+    assert.equal(pi.held[0].deliverAs, 'nextTurn');
+});

package/dist/pi-extensions/canvas-inbox-watcher.d.ts

@@ -1,4 +1,4 @@
-type PiEvents = 'session_start' | 'turn_end' | 'agent_start' | 'agent_end' | 'session_shutdown';
+type PiEvents = 'session_start' | 'turn_end' | 'agent_start' | 'agent_end' | 'agent_settled' | 'session_shutdown';
 interface PiLike {
     on: (event: PiEvents, handler: (event: any, ctx: any) => void | Promise<void>) => void;
     sendUserMessage: (content: string, options?: {