@crouton-kit/crouter 0.3.78 → 0.3.80

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/canvas-recap.js

@@ -14,10 +14,13 @@
 //     • a single low-rate timer (no busy-loop) checks elapsed-since-last-message
 //       and, on crossing IDLE_MS, generates + shows the recap once.
 //
-//   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).
+//   Brief input = the FIRST 5 and MOST RECENT 5 user/assistant messages (literal
+//   text only — the first messages carry the original request, the last carry
+//   where it left off), plus the node's roadmap file when one exists. 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). Long messages are truncated per-message so the
+//   opening request is never crowded out by a recent wall of text.
 //
 //   Placement: key `crtr-recap`, placement `aboveEditor`.
 //
@@ -33,6 +36,7 @@
 // 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 { readRoadmap } from '../core/runtime/roadmap.js';
 // ---------------------------------------------------------------------------
 // Tuning constants
 // ---------------------------------------------------------------------------
@@ -45,10 +49,12 @@ function idleMs() {
 }
 /** How often the single low-rate timer checks elapsed-since-last-message. */
 const POLL_MS = 7_000;
-/** 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;
+/** How many messages from each end of the conversation feed the brief model —
+ *  the first N carry the original request, the last N carry where it left off. */
+const CONVO_EDGE_MESSAGES = 5;
+/** Per-message char cap — keeps one giant paste from crowding out the rest
+ *  (10 messages × this ≈ the total budget the model needs for the gist). */
+const MESSAGE_CHAR_BUDGET = 1_200;
 const WIDGET_KEY = 'crtr-recap';
 // ---------------------------------------------------------------------------
 // Module-level state — persists across /reload so the timer doesn't stack.
@@ -73,9 +79,11 @@ function messageText(msg) {
         .join('\n')
         .trim();
 }
-/** Concatenate the conversation's user + assistant literal text into a single
- *  `User:`/`Agent:` transcript, keeping only the MOST-RECENT CONVO_CHAR_BUDGET
- *  characters. Excludes tool calls/results (role toolResult, plus toolCall/
+/** Concatenate the FIRST and MOST-RECENT CONVO_EDGE_MESSAGES user/assistant
+ *  messages into a single `User:`/`Agent:` transcript (each message capped at
+ *  MESSAGE_CHAR_BUDGET chars), with an omission marker where the middle was
+ *  dropped — the opening messages carry the original request the brief exists
+ *  to surface. Excludes tool calls/results (role toolResult, plus toolCall/
  *  thinking content blocks dropped by messageText) and extension-injected
  *  custom messages (entry.type !== 'message'). Returns '' when there is nothing
  *  to summarize. */
@@ -94,15 +102,23 @@ function buildConversation(sm) {
         const role = e.message.role;
         if (role !== 'user' && role !== 'assistant')
             continue; // drop toolResult etc.
-        const text = messageText(e.message);
+        let text = messageText(e.message);
         if (text === '')
             continue;
+        if (text.length > MESSAGE_CHAR_BUDGET)
+            text = `${text.slice(0, MESSAGE_CHAR_BUDGET)} …[truncated]`;
         parts.push(`${role === 'user' ? 'User' : 'Agent'}: ${text}`);
     }
     if (parts.length === 0)
         return '';
-    const full = parts.join('\n\n');
-    return full.length > CONVO_CHAR_BUDGET ? full.slice(full.length - CONVO_CHAR_BUDGET) : full;
+    if (parts.length <= CONVO_EDGE_MESSAGES * 2)
+        return parts.join('\n\n');
+    const omitted = parts.length - CONVO_EDGE_MESSAGES * 2;
+    return [
+        ...parts.slice(0, CONVO_EDGE_MESSAGES),
+        `[… ${omitted} message${omitted === 1 ? '' : 's'} omitted …]`,
+        ...parts.slice(parts.length - CONVO_EDGE_MESSAGES),
+    ].join('\n\n');
 }
 // ---------------------------------------------------------------------------
 // Extension
@@ -146,12 +162,17 @@ export function registerCanvasRecap(pi) {
         }
         catch { /* best-effort */ }
     };
-    /** Render the briefing into the viewer's low-contrast above-editor slot. */
+    /** Render the briefing into the viewer's low-contrast above-editor slot.
+     *  The briefing arrives as the two-line `Goal:`/`State:` format — one widget
+     *  line each (the viewer wraps long lines itself). */
     const showRecap = (briefing) => {
         if (!canPaint() || briefing === '')
             return;
+        const lines = briefing.split('\n').filter((l) => l.trim() !== '');
+        if (lines.length === 0)
+            return;
         try {
-            ui.setWidget(WIDGET_KEY, [`Brief: ${briefing}`], { placement: 'aboveEditor' });
+            ui.setWidget(WIDGET_KEY, lines, { placement: 'aboveEditor' });
         }
         catch { /* best-effort */ }
     };
@@ -208,6 +229,11 @@ export function registerCanvasRecap(pi) {
             // (now-stale) result instead of painting over the live conversation.
             const startedAt = lastMessageAt;
             generating = true;
+            let roadmap;
+            try {
+                roadmap = readRoadmap(nodeId) ?? undefined;
+            }
+            catch { /* best-effort */ }
             generateRecap(convo, (briefing) => {
                 generating = false;
                 if (lastMessageAt !== startedAt)
@@ -216,7 +242,7 @@ export function registerCanvasRecap(pi) {
                     return;
                 recapShown = true;
                 showRecap(briefing);
-            }, liveModel);
+            }, liveModel, roadmap);
             // 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/types.d.ts

@@ -20,6 +20,12 @@ export interface PluginManifest {
     source?: string;
     owner?: OwnerRef;
     kinds?: string[];
+    /** Plugin-root-relative path to one declarative command manifest
+     *  (`commands.json`). When present on an installed, enabled plugin, that
+     *  manifest contributes top-level command branches to the `crtr` tree —
+     *  crtr owns parse/help/render/errors and direct-spawns the plugin's one
+     *  executable per leaf invocation. See `src/core/command-plugins/`. */
+    commands?: string;
 }
 export interface MarketplacePluginEntry {
     name: string;
@@ -72,18 +78,6 @@ export interface CanvasMenuItem {
     action: CanvasAction;
     confirm?: boolean;
 }
-export interface CanvasBind {
-    run: string;
-    confirm?: boolean;
-    desc?: string;
-}
-export interface CanvasNavConfig {
-    prefixKey?: string;
-    prefixBinds: Record<string, CanvasAction & {
-        desc?: string;
-    }>;
-    graphBinds: Record<string, CanvasBind>;
-}
 export type ModelStrength = 'ultra' | 'strong' | 'medium' | 'light';
 export type ModelProvider = 'anthropic' | 'openai';
 export interface ModelLaddersConfig {
@@ -257,6 +251,5 @@ export declare function defaultRemoteCanvasConfig(): RemoteCanvasConfig;
  *  ancestor) — `product/teardown` is included explicitly below for parity
  *  even though its value equals the default. */
 export declare function defaultKindsConfig(): Record<string, KindConfig>;
-export declare function defaultCanvasNavConfig(): CanvasNavConfig;
 export declare function defaultModelLaddersConfig(): ModelLaddersConfig;
 export declare function defaultScopeState(): ScopeState;

package/dist/types.js

@@ -119,9 +119,6 @@ export function defaultKindsConfig() {
         },
     };
 }
-export function defaultCanvasNavConfig() {
-    throw new Error('runtime consumer must resolve semantic crouter keybindings');
-}
 export function defaultModelLaddersConfig() {
     return {
         anthropic: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.78",
+  "version": "0.3.80",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,6 @@
     "scripts/postinstall.mjs"
   ],
   "scripts": {
-    "prebuild": "rm -rf node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-agent-core",
     "build": "rm -rf dist && tsc && cp -R src/builtin-views dist/builtin-views && cp -R src/builtin-memory dist/builtin-memory && cp -R src/builtin-pi-packages dist/builtin-pi-packages && npm run build:attach && vite build --config src/clients/web/web-client/vite.config.ts",
     "lint:web-px": "node scripts/lint-web-px.mjs",
     "build:attach": "esbuild src/clients/attach/attach-cmd.ts --bundle --minify --format=esm --platform=node --target=node22 --alias:@earendil-works/pi-tui=$PWD/node_modules/@earendil-works/pi-tui --external:@crouton-kit/humanloop --outfile=dist/clients/attach/attach-cmd.js --log-level=warning --banner:js=\"import{createRequire as __cr}from'node:module';const require=__cr(import.meta.url);\"",
@@ -44,13 +43,18 @@
     "test:full:live": "node --import tsx/esm --test-concurrency=1 --test src/core/__tests__/live-mutation-verbs.test.ts",
     "test:full:heavy": "node --import tsx/esm --test-concurrency=1 --test 'src/core/__tests__/full/*.test.ts'"
   },
+  "overrides": {
+    "@earendil-works/pi-ai": "0.80.6",
+    "@earendil-works/pi-agent-core": "0.80.6",
+    "@earendil-works/pi-tui": "0.80.6"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vallum-security/crouter.git"
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.33",
+    "@crouton-kit/humanloop": "^0.3.34",
     "@earendil-works/pi-agent-core": "0.80.6",
     "@earendil-works/pi-ai": "0.80.6",
     "@earendil-works/pi-coding-agent": "0.80.6",