@crouton-kit/crouter 0.3.68 → 0.3.78

package/dist/core/tui/host.js

@@ -22,6 +22,7 @@ import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from
 import { createDraw, detectColorCaps } from './draw.js';
 import { initialChrome, deriveState } from '../view/chrome.js';
 import { createLocalTransport } from '../view/transport-local.js';
+import { formatBinding, matchesTerminalInput, resolveUserKeybindings, } from '../keybindings/index.js';
 // Numeric SGR codes only (a color NAME emits a broken CSI — see draw.ts guard).
 const FG = { cyan: '36', green: '32', yellow: '33', red: '31', grey: '90' };
 /** The persistent state signal: word + glyph + hue, derived from host signals so
@@ -179,15 +180,94 @@ function drawChrome(draw, size, manifest, c, now = Date.now()) {
     return { row: top, col: 0, width: cols, height };
 }
 export { drawChrome };
-// ── Dual-target core host (runCoreView) ─────────────────────────────────────
-//
-// Hosts a ViewCore + TuiPresenter under the dual-target contract
-// (src/core/view/contract.ts). The model is the immutable-state + intents thunk
-// runtime: the core owns all state + behavior, presenters are pure reads, and a
-// keystroke maps through the keymap to a named intent the host dispatches.
-/** Tokens a keystroke can match a keymap binding's `keys` against. Arrows →
- *  up/down/left/right, return → return|enter, escape → escape|esc, a printable
- *  char → the char itself (+ 'space' for ' '), ctrl+x → ctrl+x|c-x. */
+/** True when some effective binding claims the `ctrl+h` gesture — used to decide
+ * whether the ambiguous 0x08 byte is a Ctrl-H remap or a plain Backspace. */
+function bindingSetClaimsCtrlH(bindings) {
+    for (const eff of bindings.bindings.values()) {
+        if (eff.gestures.includes('ctrl+h'))
+            return true;
+    }
+    return false;
+}
+/** One-line summary of rejected hand-edited overrides, surfaced once per surface. */
+function summarizeKeybindingDiagnostics(diags) {
+    if (diags.length === 0)
+        return null;
+    const extra = diags.length > 1 ? ` (+${diags.length - 1} more)` : '';
+    return `keybindings: ${diags[0].message}${extra}`;
+}
+/** Extend the shared legacy parser with the terminal gestures the catalog can
+ * express. The raw shape goes only to the catalog matcher; custom literals keep
+ * their established Key-based matching. When `bindings` is supplied the ambiguous
+ * 0x08 byte resolves to Ctrl-H only if an effective binding claims it. */
+export function parseViewKeypress(data, bindings) {
+    const parsed = parseKeypress(data);
+    const raw = { ...parsed.key, input: parsed.input };
+    const sequence = data.toString('utf8');
+    const named = {
+        '\x1b[3~': 'delete', '\x1b[5~': 'pageUp', '\x1b[6~': 'pageDown',
+        '\x1b[H': 'home', '\x1b[F': 'end', '\x1b[1~': 'home', '\x1b[4~': 'end',
+        '\x1bOH': 'home', '\x1bOF': 'end',
+    };
+    const setModifiers = (code) => {
+        const value = Number(code);
+        raw.shift = value === 2 || value === 4 || value === 6 || value === 8;
+        raw.meta = value === 3 || value === 4 || value === 7 || value === 8;
+        raw.ctrl = value === 5 || value === 6 || value === 7 || value === 8;
+    };
+    const namedKey = named[sequence];
+    if (namedKey)
+        raw[namedKey] = true;
+    const arrow = /^\x1b\[(?:1;)?([2-8])?([ABCD])$/.exec(sequence);
+    if (arrow) {
+        setModifiers(arrow[1]);
+        raw[{ A: 'upArrow', B: 'downArrow', C: 'rightArrow', D: 'leftArrow' }[arrow[2]]] = true;
+    }
+    const modifiedNamed = /^\x1b\[(3|5|6|1|4);([2-8])~$/.exec(sequence);
+    if (modifiedNamed) {
+        raw[{ 3: 'delete', 5: 'pageUp', 6: 'pageDown', 1: 'home', 4: 'end' }[modifiedNamed[1]]] = true;
+        setModifiers(modifiedNamed[2]);
+    }
+    const modifiedHomeEnd = /^\x1b\[1;([2-8])([HF])$/.exec(sequence);
+    if (modifiedHomeEnd) {
+        raw[modifiedHomeEnd[2] === 'H' ? 'home' : 'end'] = true;
+        setModifiers(modifiedHomeEnd[1]);
+    }
+    // Alt+<char> gestures (ESC-prefixed printables/control letters) that the
+    // legacy parser leaves as a raw two-byte `input`. Only the raw catalog shape
+    // gains the alt modifier; `parsed` keeps its Key-based shape so custom literals
+    // still match exactly as before (Alt+<letter> must NOT match a bare literal).
+    // Special keys the legacy parser already decoded (Alt+Backspace, arrows, …)
+    // return `input: ''`, so `parsed.input === sequence` skips them here.
+    if (sequence.length === 2 && sequence.startsWith('\x1b') && parsed.input === sequence) {
+        const code = sequence.charCodeAt(1);
+        raw.input = code < 32 ? String.fromCharCode(code + 64).toLowerCase() : sequence[1];
+        raw.meta = true;
+        raw.ctrl = code < 32;
+    }
+    // Backspace family. \x7f, \b, and their Alt-prefixed forms all mean "delete one
+    // char" and canonicalize to plain backspace (there is no alt+backspace catalog
+    // action, so Alt+Backspace deletes exactly like Backspace, as before). The 0x08
+    // byte is ALSO Ctrl-H: honor a Ctrl-H remap only when an effective binding
+    // actually claims `ctrl+h`, otherwise it stays backspace so default deletion
+    // keeps working on ^H-erase terminals.
+    if (raw.backspace) {
+        const ctrlHByte = sequence === '\b' || sequence === '\x1b\b';
+        if (ctrlHByte && bindings && bindingSetClaimsCtrlH(bindings)) {
+            raw.input = 'h';
+            raw.ctrl = true;
+            raw.meta = false;
+            raw.backspace = false;
+        }
+        else {
+            raw.input = '';
+            raw.ctrl = false;
+            raw.meta = false;
+            raw.backspace = true;
+        }
+    }
+    return { ...parsed, raw };
+}
 function keyTokens(input, key) {
     const t = [];
     if (key.upArrow)
@@ -228,21 +308,53 @@ function isPrintable(input, key) {
 function sanitizePrintable(s) {
     return Array.from(s).filter((ch) => ch.charCodeAt(0) >= 32).join('');
 }
+/** Resolve footer hints for the CURRENT state: only bindings whose `when(state)`
+ * passes contribute, so mode-gated affordances (compose/react send/cancel/pick)
+ * appear exactly while active. Catalog bindings render the effective key label
+ * (omitted entirely when disabled); custom-view literal hints stay verbatim. */
+export function resolveViewKeyHints(keymap, bindings, state) {
+    const hints = [];
+    for (const binding of keymap) {
+        if (!binding.hint)
+            continue;
+        if (binding.when && !binding.when(state))
+            continue;
+        if ('bindingId' in binding) {
+            if (bindings.gestures(binding.bindingId).length === 0)
+                continue; // disabled: no hint
+            hints.push({ keys: formatBinding(bindings, binding.bindingId), label: binding.hint.label });
+        }
+        else if ('capture' in binding) {
+            hints.push('keys' in binding.hint ? binding.hint : { keys: 'type', label: binding.hint.label });
+        }
+        else {
+            hints.push(binding.hint);
+        }
+    }
+    return hints;
+}
 /** The first non-capture binding whose key matches and whose `when` (if any)
- *  passes — returns the intent name + resolved payload. */
-function matchBinding(keymap, input, key, state) {
+ * passes — catalog IDs use the terminal matcher; custom literals retain their
+ * presenter-authored matching. */
+export function matchViewBinding(keymap, bindings, input, key, state, raw = { ...key, input }) {
     const tokens = keyTokens(input, key);
-    for (const b of keymap) {
-        if ('capture' in b)
+    for (const binding of keymap) {
+        if ('capture' in binding)
             continue;
-        if (b.when && !b.when(state))
+        if (binding.when && !binding.when(state))
             continue;
-        if (b.keys.some((k) => tokens.includes(k))) {
-            return { intent: b.intent, payload: b.payload ? b.payload(state) : undefined };
-        }
+        const matches = 'bindingId' in binding
+            ? matchesTerminalInput(bindings, binding.bindingId, raw)
+            : binding.keys.some((literal) => tokens.includes(literal));
+        if (matches)
+            return { intent: binding.intent, payload: binding.payload ? binding.payload(state) : undefined };
     }
     return null;
 }
+/** Match a host-owned generic-view action through the same catalog snapshot. */
+export function matchesViewHostBinding(bindings, id, raw) {
+    return matchesTerminalInput(bindings, id, raw);
+}
 /** The active text-capture binding for this state, if any (compose-mode entry). */
 function activeCapture(keymap, state) {
     for (const b of keymap) {
@@ -271,9 +383,13 @@ async function runRequest(transport, src, args) {
  *  (or Ctrl-C). `text` is the optional text presenter for the piped path. */
 export async function runCoreView(core, tui, text, opts = {}) {
     const options = Object.freeze({ ...(opts.options ?? {}) });
+    const bindings = resolveUserKeybindings();
+    const keybindingNotice = summarizeKeybindingDiagnostics(bindings.diagnostics);
     const transport = createLocalTransport({ cwd: process.cwd() });
     // ── Non-TTY / piped path: init, best-effort refresh, dump, exit 0. ──
     if (!process.stdin.isTTY) {
+        if (keybindingNotice)
+            process.stderr.write(`${keybindingNotice}\n`);
         let dstate = core.init(options);
         const dchrome = initialChrome();
         const dsignal = {
@@ -307,13 +423,9 @@ export async function runCoreView(core, tui, text, opts = {}) {
     let state = core.init(options);
     const chrome = initialChrome();
     let tick = 0;
-    // Footer hints come from the keymap bindings' `hint` field (single source of
-    // truth) — projected into the (ChromeManifest, Chrome) shape drawChrome reads.
-    const hints = [];
-    for (const b of tui.keymap) {
-        if (b.hint)
-            hints.push(b.hint);
-    }
+    // Report rejected hand-edited overrides once, as a chrome notice.
+    if (keybindingNotice)
+        chrome.banner = { msg: keybindingNotice, level: 'action' };
     // Restore the terminal exactly once, however we leave.
     let restored = false;
     const cleanup = () => {
@@ -329,7 +441,9 @@ export async function runCoreView(core, tui, text, opts = {}) {
     const render = () => {
         const size = getTerminalSize();
         const { draw, frame } = createDraw(size, caps);
-        const chromeManifest = { ...core.manifest, keymap: hints };
+        // Footer hints are re-derived per draw so they track the active mode
+        // (compose/react affordances appear only while their `when(state)` holds).
+        const chromeManifest = { ...core.manifest, keymap: resolveViewKeyHints(tui.keymap, bindings, state) };
         const tickChrome = { ...chrome, tick };
         const content = drawChrome(draw, size, chromeManifest, tickChrome);
         try {
@@ -525,14 +639,14 @@ export async function runCoreView(core, tui, text, opts = {}) {
             return;
         let parsed;
         try {
-            parsed = parseKeypress(data);
+            parsed = parseViewKeypress(data, bindings);
         }
         catch {
             return;
         }
-        const { input, key } = parsed;
-        // Ctrl-C is the universal escape hatch — works even mid-flight.
-        if (key.ctrl && input === 'c') {
+        const { input, key, raw } = parsed;
+        // The catalog-backed escape hatch works even mid-flight.
+        if (matchesViewHostBinding(bindings, 'crtr.view.host.force-quit', raw)) {
             finish();
             return;
         }
@@ -544,13 +658,13 @@ export async function runCoreView(core, tui, text, opts = {}) {
         // fall through to the keymap so submit/cancel can be bound.
         const cap = activeCapture(tui.keymap, state);
         if (cap) {
-            if (isPrintable(input, key)) {
-                captureBuf += sanitizePrintable(input);
+            if (matchesViewHostBinding(bindings, 'crtr.view.host.editor.backspace', raw)) {
+                captureBuf = captureBuf.slice(0, -1);
                 await enqueueDispatch(cap.capture, captureBuf);
                 return;
             }
-            if (key.backspace) {
-                captureBuf = captureBuf.slice(0, -1);
+            if (isPrintable(input, key)) {
+                captureBuf += sanitizePrintable(input);
                 await enqueueDispatch(cap.capture, captureBuf);
                 return;
             }
@@ -558,7 +672,7 @@ export async function runCoreView(core, tui, text, opts = {}) {
         else {
             captureBuf = '';
         }
-        const m = matchBinding(tui.keymap, input, key, state);
+        const m = matchViewBinding(tui.keymap, bindings, input, key, state, raw);
         if (m)
             await enqueueDispatch(m.intent, m.payload);
     };

package/dist/core/view/__tests__/transport-remote.test.js

@@ -25,8 +25,12 @@ function startStalledServer() {
         });
     });
 }
-test('a stalled endpoint returns a timeout failure within the configured bound instead of hanging forever', async () => {
+test('a stalled endpoint returns a timeout failure within the configured bound instead of hanging forever', async (t) => {
     const server = await startStalledServer();
+    // Register the close BEFORE any assertion runs — a listening server left
+    // open by a thrown assertion keeps this test file's process alive forever
+    // (see the CI-hang postmortem on rebuild-coalescer.test.ts).
+    t.after(() => server.close());
     const exec = createRemoteExec(server.url, 'tok', 100); // small timeout for the test
     const started = Date.now();
     // Race against a generous outer deadline: if the transport doesn't
@@ -40,9 +44,8 @@ test('a stalled endpoint returns a timeout failure within the configured bound i
     assert.equal(result.ok, false);
     assert.match(result.stderr, /timeout/i);
     assert.ok(elapsed < 1000, `expected the timeout to fire near the configured 100ms bound, took ${elapsed}ms`);
-    await server.close();
 });
-test('a normal fast response is unaffected by the timeout wiring', async () => {
+test('a normal fast response is unaffected by the timeout wiring', async (t) => {
     const server = createServer((req, res) => {
         const chunks = [];
         req.on('data', (c) => chunks.push(c));
@@ -51,6 +54,7 @@ test('a normal fast response is unaffected by the timeout wiring', async () => {
             res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
         });
     });
+    t.after(() => new Promise((r) => server.close(() => r())));
     await new Promise((r) => server.listen(0, '127.0.0.1', r));
     const addr = server.address();
     const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
@@ -58,7 +62,6 @@ test('a normal fast response is unaffected by the timeout wiring', async () => {
     const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
     assert.equal(result.ok, true);
     assert.equal(result.stdout, JSON.stringify({ nodes: [] }));
-    await new Promise((r) => server.close(() => r()));
 });
 // --- Phase 3 review Minor 1: no token bytes may ever reach returned stderr ---
 test('an unreachable endpoint returns a flat generic network-error message, never the raw exception text', async () => {
@@ -75,7 +78,7 @@ test('a malformed token (contains a newline) is rejected up front with a generic
     assert.ok(!result.stderr.includes('bad\ntoken'));
     assert.ok(!result.stderr.includes('bad'));
 });
-test('a valid token containing typical bearer-token punctuation (-, _, .) still round-trips against a real server', async () => {
+test('a valid token containing typical bearer-token punctuation (-, _, .) still round-trips against a real server', async (t) => {
     const server = createServer((req, res) => {
         const chunks = [];
         req.on('data', (c) => chunks.push(c));
@@ -84,6 +87,7 @@ test('a valid token containing typical bearer-token punctuation (-, _, .) still
             res.end(JSON.stringify({ ok: true, exitCode: 0, stdout: JSON.stringify({ nodes: [] }), stderr: '' }));
         });
     });
+    t.after(() => new Promise((r) => server.close(() => r())));
     await new Promise((r) => server.listen(0, '127.0.0.1', r));
     const addr = server.address();
     const port = typeof addr === 'object' && addr !== null ? addr.port : 0;
@@ -91,5 +95,4 @@ test('a valid token containing typical bearer-token punctuation (-, _, .) still
     const result = await exec('crtr', ['--json', 'node', 'inspect', 'list']);
     assert.equal(result.ok, true);
     assert.equal(result.stdout, JSON.stringify({ nodes: [] }));
-    await new Promise((r) => server.close(() => r()));
 });

package/dist/core/view/contract.d.ts

@@ -154,7 +154,20 @@ export interface KeyHint {
     keys: string;
     label: string;
 }
+/** A catalog binding supplies only its semantic hint label: the host derives
+ * the rendered key label from the effective user binding snapshot. */
+export interface CatalogKeyHint {
+    label: string;
+}
 export type KeyBinding<S> = {
+    /** Closed crouter catalog action. Shipped presenters use this form. */
+    bindingId: import('../keybindings/index.js').BindingId;
+    intent: string;
+    payload?: (state: S) => unknown;
+    when?: (state: S) => boolean;
+    hint?: CatalogKeyHint;
+} | {
+    /** Literal keys remain owned by custom/plugin views, outside crouter's catalog. */
     keys: string[];
     intent: string;
     payload?: (state: S) => unknown;
@@ -162,11 +175,12 @@ export type KeyBinding<S> = {
     hint?: KeyHint;
 } | {
     /** Text-capture binding: while `when(state)` is true the host runs a
-     *  built-in line-edit buffer over raw printable/backspace keys and
-     *  dispatches `capture` with the next draft value on each edit. */
+     *  built-in line-edit buffer over raw printable keys and dispatches
+     *  `capture` with the next draft value on each edit. Deletion is the
+     *  host catalog action `crtr.view.host.editor.backspace`. */
     capture: string;
     when: (state: S) => boolean;
-    hint?: KeyHint;
+    hint?: KeyHint | CatalogKeyHint;
 };
 export interface TuiPresenter<S = unknown> {
     /** Pure read of state, paints via draw.*; never ANSI. */

package/dist/daemon/crtrd-cli.d.ts

@@ -1 +1 @@
-export {};
+import '../suppress-experimental-warnings.js';

package/dist/daemon/crtrd-cli.js

@@ -1,4 +1,5 @@
 // crtrd entry point — spawned detached by `crtr sys daemon start` and by bin/crtrd.
 // Calls runDaemon() and never returns (the loop drives via setTimeout).
+import '../suppress-experimental-warnings.js';
 import { runDaemon } from './crtrd.js';
 runDaemon();

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?: {