@crouton-kit/crouter 0.3.26 → 0.3.28

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

@@ -43,10 +43,9 @@
 //
 // 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 { execFile, execFileSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { getNode, subscribersOf, subscriptionsOf, jobDir, fullName, listFocuses } from '../core/canvas/index.js';
+import { execFile } from 'node:child_process';
+import { fullName } from '../core/canvas/index.js';
+import { beginFrame, cNode, managerOf, liveReports, sortedChildIds, subtreeIds, climbRoot, computeSubtreeActivity, buildGraphModel, renderGraphRow, navLabel, coloredGlyph, truncate, tokensCell, cycleBadge, childBadge, liveBelowBadge, askBadge, activityCell, focusedNodeIds, graphWidgetBudget, fetchAsksMap, shortId, DIM, RESET, BOLD, YELLOW, GRAPH_HINT, } from '../core/canvas/nav-model.js';
 import { readConfig } from '../core/config.js';
 // ---------------------------------------------------------------------------
 // Module-level state — persists across /reload so guards don't stack and fold
@@ -65,6 +64,10 @@ let view = 'base';
  *  userExpanded. Both survive renders AND BASE↔GRAPH toggles. */
 const userCollapsed = new Set();
 const userExpanded = new Set();
+/** A live view of the manual fold overrides for the pure nav-model layer; the
+ *  Sets above are mutated in place, so this reference stays current across
+ *  renders and BASE↔GRAPH toggles. */
+const folds = { userExpanded, userCollapsed };
 /** GRAPH cursor (a node id, not an index — indices shift as topology changes). */
 let cursorId;
 /** GRAPH viewport scroll offset (row index of the top visible row). */
@@ -78,366 +81,6 @@ let asksMap = {};
 // ---------------------------------------------------------------------------
 const ASK_POLL_MS = 5_000;
 const RENDER_DEBOUNCE_MS = 150;
-/** pi's InteractiveMode.MAX_WIDGET_LINES — the hard cap on lines in a string
- *  array widget; anything beyond it pi truncates with its own "... (widget
- *  truncated)". Our GRAPH viewport stays at/under this and scrolls internally. */
-const PI_MAX_WIDGET_LINES = 10;
-const VIEWPORT_FALLBACK_ROWS = 30;
-// ---------------------------------------------------------------------------
-// ANSI styling. pi renders embedded escapes in widget lines and measures width
-// ANSI-aware, so raw escapes are safe and need no pi-tui dependency. The cursor
-// (selected row) uses a theme-agnostic ATTRIBUTE (reverse), so it reads under
-// NO_COLOR; the attached-row tint is a background COLOUR, while the dot glyph
-// (●/○/✓/✗) carries the running signal independently, even where colour is
-// stripped.
-// ---------------------------------------------------------------------------
-const ESC = '\x1b[';
-const RESET = `${ESC}0m`;
-const BOLD = `${ESC}1m`;
-const DIM = `${ESC}2m`;
-const REVERSE = `${ESC}7m`;
-/** Dark-green background bar marking an ATTACHED node (a human is currently
- *  watching it) — distinct from the cursor's reverse-video bar; chosen so
- *  default-fg text stays readable. */
-const BG_ATTACHED = `${ESC}48;5;22m`;
-const GREEN = `${ESC}32m`;
-const RED = `${ESC}31m`;
-const YELLOW = `${ESC}33m`;
-const CYAN = `${ESC}36m`;
-const GRAY = `${ESC}90m`;
-/** Status glyph colored by state: active green, idle dim, done cyan, dead red. */
-function coloredGlyph(node) {
-    if (node === null)
-        return '?';
-    switch (node.status) {
-        case 'active': return `${GREEN}●${RESET}`;
-        case 'idle': return `${GRAY}○${RESET}`;
-        case 'done': return `${CYAN}✓${RESET}`;
-        case 'dead': return `${RED}✗${RESET}`;
-        case 'canceled': return `${YELLOW}⊘${RESET}`;
-        default: return '?';
-    }
-}
-const ANSI_RE = /\x1b\[[0-9;]*m/g;
-/** Visible width, ignoring ANSI escapes. */
-function visibleWidth(s) {
-    return s.replace(ANSI_RE, '').length;
-}
-/** Truncate to `max` VISIBLE columns: escape sequences are copied through
- *  verbatim (so a cut never lands mid-escape) and the result always ends in
- *  RESET, so a clipped style can't bleed into the editor below. */
-function truncate(s, max = fillWidth()) {
-    if (visibleWidth(s) <= max)
-        return s;
-    let out = '';
-    let w = 0;
-    let i = 0;
-    while (i < s.length && w < max - 1) {
-        if (s[i] === '\x1b') {
-            const m = /^\x1b\[[0-9;]*m/.exec(s.slice(i));
-            if (m) {
-                out += m[0];
-                i += m[0].length;
-                continue;
-            }
-        }
-        out += s[i];
-        w++;
-        i++;
-    }
-    return `${out}…${RESET}`;
-}
-/** Visible columns available to ONE widget line — the cap for every line we
- *  emit, and the width a full-width reverse-video SELF bar fills to.
- *
- *  pi does NOT clip widget lines; it WRAPS them. Each string line is wrapped in
- *  a `Text(paddingX = 1)` inside a full-terminal-width container, so the usable
- *  content width is `columns - 2` (a 1-col margin on each side). A line wider
- *  than that wraps, and the overflow spills onto a second row as a stray
- *  reverse-video block (the bug this guards against). Clamp to `columns - 2`. */
-function fillWidth() {
-    return Math.max(20, Math.min((process.stdout.columns ?? 80) - 2, 180));
-}
-/** Wrap `content` in a full-width background bar opened by `open` (REVERSE for
- *  the cursor, BG_ATTACHED for a human-watched node). `open` is re-asserted after every
- *  embedded RESET so a coloured cell (the status dot) can't punch a hole in the
- *  bar; the visible width is padded out to `width`; the line closes with a real
- *  RESET so the style never bleeds into the editor below. */
-function fillBar(content, width, open) {
-    const clipped = truncate(content, width);
-    const reasserted = clipped.replace(/\x1b\[0m/g, `${RESET}${open}`);
-    const pad = Math.max(0, width - visibleWidth(clipped));
-    return `${open}${reasserted}${' '.repeat(pad)}${RESET}`;
-}
-function readTelemetry(nodeId) {
-    try {
-        const p = join(jobDir(nodeId), 'telemetry.json');
-        if (!existsSync(p))
-            return {};
-        return JSON.parse(readFileSync(p, 'utf8'));
-    }
-    catch {
-        return {};
-    }
-}
-function fmtTokens(n) {
-    return n < 1_000 ? `${n}` : `${Math.round(n / 1_000)}k`;
-}
-function tokensCell(id) {
-    return fmtTokens(readTelemetry(id).tokens_in ?? 0);
-}
-function shortId(id) {
-    return id.slice(0, 8);
-}
-// ---------------------------------------------------------------------------
-// Attachment — is a human currently WATCHING a node? A separate axis from
-// running (status 'active' = the engine is live on its host, which may be an
-// unwatched backstage pane or a paneless broker). Two hosts, two signals:
-//   tmux   — a `focuses` row points at the node (one cheap sqlite read per
-//            render pass; pane-existence alone is NOT the signal).
-//   broker — the broker persists its helloed-viewer count to job/attach.json
-//            on every viewer change (src/core/runtime/broker.ts). Trusted only
-//            while the node is 'active': a broker crash can leave a stale file.
-// ---------------------------------------------------------------------------
-/** Node ids currently shown in a tmux focus viewport. Built once per render. */
-function focusedNodeIds() {
-    try {
-        return new Set(listFocuses().map((f) => f.node_id));
-    }
-    catch {
-        return new Set();
-    }
-}
-/** True when a human is watching `id` right now (tmux focus or broker viewer). */
-function isAttached(id, node, focused) {
-    if (focused.has(id))
-        return true;
-    if (node?.status !== 'active')
-        return false; // stale attach.json from a crash
-    try {
-        const p = join(jobDir(id), 'attach.json');
-        if (!existsSync(p))
-            return false;
-        const rec = JSON.parse(readFileSync(p, 'utf8'));
-        return typeof rec.viewers === 'number' && rec.viewers > 0;
-    }
-    catch {
-        return false;
-    }
-}
-// ---------------------------------------------------------------------------
-// Per-node ask counts — ONE shell-out per poll. `crtr canvas attention map`
-// buckets a whole sub-DAG's pending asks by node in a single process, so the
-// timer stays cheap (< 2 s) regardless of how many nodes are visible. --json
-// gives a parseable {counts} blob (the default render is XML chrome).
-// ---------------------------------------------------------------------------
-function fetchAsksMap(rootId) {
-    try {
-        const raw = execFileSync('crtr', ['canvas', 'attention', 'map', '--view', rootId, '--json'], {
-            timeout: 2_500,
-            encoding: 'utf8',
-        });
-        const parsed = JSON.parse(raw.trim());
-        return parsed.counts ?? {};
-    }
-    catch {
-        return {};
-    }
-}
-// ---------------------------------------------------------------------------
-// Graph queries (dependency-free, straight off the canvas db)
-// ---------------------------------------------------------------------------
-/** First manager (by created) — the UP step for the ancestry spine. */
-function managerOf(id) {
-    try {
-        return subscribersOf(id)[0]?.node_id;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** A kind:'human' node is a control-plane ASK (a humanloop deck on the human's
- *  screen), NOT a pi conversation — it has no session, so focusing/reviving it
- *  boots a confused blank "you have been revived" pi. Its pending-ask signal
- *  already rides the ⚑ badge on the ASKING node (attention.ts attributes asks by
- *  source.nodeId, never to the human node), so the row carries no signal of its
- *  own. Drop it from every navigable list (the tree, BASE reports, child counts,
- *  subtree expansion) so it can never be selected. */
-function isHumanAsk(id) {
-    return getNode(id)?.kind === 'human';
-}
-/** A node's direct children that are navigable conversations — human-ask nodes
- *  dropped. The one place the nav chrome enumerates children. */
-function convoChildIds(id) {
-    try {
-        return subscriptionsOf(id).map((s) => s.node_id).filter((cid) => !isHumanAsk(cid));
-    }
-    catch {
-        return [];
-    }
-}
-/** Live reports (active|idle) of a node — the DOWN set in BASE. */
-function liveReports(id) {
-    return convoChildIds(id).filter((cid) => {
-        const st = getNode(cid)?.status;
-        return st === 'active' || st === 'idle';
-    });
-}
-/** Direct navigable children — used for the ⤳ badge and fold counts (human-ask
- *  nodes excluded, so the count matches what the tree actually shows). */
-function childCount(id) {
-    return convoChildIds(id).length;
-}
-/** Climb first-manager edges from `self` to the ancestry root (cycle-guarded). */
-function climbRoot(self) {
-    let cur = self;
-    const seen = new Set([cur]);
-    for (;;) {
-        const mgr = managerOf(cur);
-        if (mgr === undefined || seen.has(mgr))
-            break;
-        seen.add(mgr);
-        cur = mgr;
-    }
-    return cur;
-}
-/** Space-joined ids of a node's subtree (cursor-relative {subtree} var). */
-function subtreeIds(root) {
-    const out = [];
-    const seen = new Set([root]);
-    const q = convoChildIds(root);
-    while (q.length > 0) {
-        const id = q.shift();
-        if (seen.has(id))
-            continue;
-        seen.add(id);
-        out.push(id);
-        for (const cid of convoChildIds(id))
-            if (!seen.has(cid))
-                q.push(cid);
-    }
-    return out;
-}
-// ---------------------------------------------------------------------------
-// Shared cell builders
-// ---------------------------------------------------------------------------
-/** ⤳M direct-children badge — only on orchestrator rows. */
-function childBadge(node) {
-    if (node === null || node.mode !== 'orchestrator')
-        return '';
-    const m = childCount(node.node_id);
-    return m > 0 ? ` ${DIM}⤳${m}${RESET}` : '';
-}
-/** ⚑K pending-asks badge for a node, read from the cached map. */
-function askBadge(id) {
-    const k = asksMap[id] ?? 0;
-    return k > 0 ? ` ${YELLOW}⚑${k}${RESET}` : '';
-}
-/** Sort rank for sibling ordering — live nodes (active, then idle) ahead of
- *  terminal ones, so sessions still running surface at the TOP of each child
- *  group instead of being buried under finished/failed ones. */
-function statusRank(id) {
-    switch (getNode(id)?.status) {
-        case 'active': return 0;
-        case 'idle': return 1;
-        case 'done': return 2;
-        case 'canceled': return 3;
-        case 'dead': return 4;
-        default: return 5;
-    }
-}
-/** Direct children, live-first — the sibling order used both when flattening
- *  the tree and when stepping into a subtree (`l`). Array.sort is stable, so
- *  equal-status siblings keep their creation order. */
-function sortedChildIds(id) {
-    return convoChildIds(id).sort((a, b) => statusRank(a) - statusRank(b));
-}
-/** Default fold policy: which nodes auto-EXPAND. A node expands only when one
- *  of its child subtrees holds a running ('active') agent or self — so the path
- *  to any live agent (and to you) is revealed while quiescent branches stay
- *  folded. One bottom-up O(N) pass from the ancestry root; cycle-guarded. */
-function computeDefaultExpanded(root, self) {
-    const expand = new Set();
-    const seen = new Set();
-    // Returns whether subtree(id), INCLUDING id, holds an active node or self.
-    const visit = (id) => {
-        if (seen.has(id))
-            return id === self || getNode(id)?.status === 'active';
-        seen.add(id);
-        let childRevealing = false;
-        for (const c of convoChildIds(id))
-            if (visit(c))
-                childRevealing = true;
-        if (childRevealing)
-            expand.add(id); // a descendant is worth revealing → unfold id
-        return childRevealing || id === self || getNode(id)?.status === 'active';
-    };
-    visit(root);
-    return expand;
-}
-function buildGraphModel(self) {
-    const rootId = climbRoot(self);
-    const defaultExpanded = computeDefaultExpanded(rootId, self);
-    // userExpanded / userCollapsed override the auto policy; absent → policy decides.
-    const isFolded = (id) => userExpanded.has(id) ? false : userCollapsed.has(id) ? true : !defaultExpanded.has(id);
-    const rows = [];
-    const visited = new Set();
-    const walk = (id, prefix, isRoot, isLast) => {
-        if (visited.has(id)) {
-            const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
-            rows.push({ id, hasKids: false, isSelf: id === self, branch: prefix + connector, cycle: true, collapsed: false });
-            return;
-        }
-        visited.add(id);
-        const kids = sortedChildIds(id);
-        const folded = isFolded(id);
-        const connector = isRoot ? '' : isLast ? '└─ ' : '├─ ';
-        rows.push({ id, hasKids: kids.length > 0, isSelf: id === self, branch: prefix + connector, cycle: false, collapsed: folded });
-        if (folded)
-            return; // folded — don't descend
-        const childPrefix = isRoot ? '' : prefix + (isLast ? '   ' : '│  ');
-        for (let i = 0; i < kids.length; i++)
-            walk(kids[i], childPrefix, false, i === kids.length - 1);
-    };
-    walk(rootId, '', true, true);
-    return rows;
-}
-/** Render one GRAPH row. CURSOR (selected) → reverse-video bar; an ATTACHED
- *  (human-watched) node → a coloured background bar; SELF → bold name. The
- *  cursor outranks the attached tint when both land on the same row. Running
- *  is signaled by the dot glyph alone (● green = active engine). */
-function renderGraphRow(r, isCursor, focused) {
-    const wrap = (line, attached) => isCursor ? fillBar(line, fillWidth(), REVERSE)
-        : attached ? fillBar(line, fillWidth(), BG_ATTACHED)
-            : truncate(line);
-    if (r.cycle) {
-        const line = `${r.branch}  ${DIM}↺ ${shortId(r.id)}${RESET}`;
-        return wrap(line, false);
-    }
-    const node = getNode(r.id);
-    const dot = coloredGlyph(node);
-    const rawName = node !== null ? fullName(node) : shortId(r.id);
-    const name = r.isSelf ? `${BOLD}${rawName}${RESET}` : rawName;
-    const kind = `${DIM}${node?.kind ?? ''}${RESET}`;
-    const tokens = `${DIM}${tokensCell(r.id)}${RESET}`;
-    // ▸ marks an expandable (collapsed-with-kids) row. The cursor row gets no
-    // caret — its reverse-video bar already distinguishes it — so the triangle
-    // reads purely as "this unfolds".
-    const expandable = r.hasKids && r.collapsed;
-    const caret = !isCursor && expandable ? `${DIM}▸${RESET} ` : '  ';
-    const fold = expandable ? ` ${DIM}[+${childCount(r.id)}]${RESET}` : '';
-    const line = `${r.branch}${caret}${dot} ${name} ${kind} ${tokens}${childBadge(node)}${fold}${askBadge(r.id)}`;
-    return wrap(line, isAttached(r.id, node, focused));
-}
-/** Total lines the GRAPH widget may emit. pi hard-caps extension widgets at
- *  MAX_WIDGET_LINES — anything past that pi truncates itself, eating our own
- *  scroll chrome — so never exceed it (and shrink on a very short terminal).
- *  The viewport scrolls WITHIN this cap as the cursor moves. */
-function graphWidgetBudget() {
-    const rows = process.stdout.rows ?? VIEWPORT_FALLBACK_ROWS;
-    return Math.max(4, Math.min(PI_MAX_WIDGET_LINES, rows - 4));
-}
-const GRAPH_HINT = `${DIM}jk move · hl fold · ↵ focus · e expand · x kill · m mgr · esc${RESET}`;
 // ---------------------------------------------------------------------------
 // Key decoding — recognizers tolerant of legacy, kitty/CSI-u and
 // modifyOtherKeys encodings (pi enables the kitty / modifyOtherKeys protocols,
@@ -552,31 +195,31 @@ export function registerCanvasNav(pi) {
     const renderBase = () => {
         if (ui === undefined)
             return;
+        // One subtree-activity pass (rooted at the ancestry root) feeds the ⇣N
+        // live-work-below badge on both the manager line and every report row.
+        const activity = computeSubtreeActivity(climbRoot(nodeId), nodeId);
         const mgr = managerOf(nodeId);
         if (mgr === undefined) {
             // Root node: no manager → drop the widget rather than show "↑ (root)" chrome.
             ui.setWidget('crtr-managers', undefined, { placement: 'aboveEditor' });
         }
         else {
-            const mn = getNode(mgr);
-            const name = mn !== null ? fullName(mn) : shortId(mgr);
-            const mgrLine = truncate(`↑ ${name} ${coloredGlyph(mn)} ${DIM}${mn?.kind ?? ''}${RESET} ${DIM}${tokensCell(mgr)}${RESET}${childBadge(mn)}${askBadge(mgr)}`);
+            const mn = cNode(mgr);
+            const name = navLabel(mn, mgr);
+            const mgrLine = truncate(`↑ ${name} ${coloredGlyph(mn)} ${DIM}${mn?.kind ?? ''}${RESET} ${DIM}${tokensCell(mgr)}${RESET}${cycleBadge(mn)}${childBadge(mn)}${liveBelowBadge(mn, activity.activeBelow)}${askBadge(mgr, asksMap)}${activityCell(mgr, mn)}`);
             ui.setWidget('crtr-managers', [mgrLine], { placement: 'aboveEditor' });
         }
         const reports = liveReports(nodeId);
         const lines = [];
         // Report rows only — no "↓ reports (N)" header (the label carries no signal).
         if (reports.length > 0) {
-            const nameW = Math.min(20, Math.max(...reports.map((id) => {
-                const n = getNode(id);
-                return (n !== null ? fullName(n) : shortId(id)).length;
-            })));
+            const nameW = Math.min(20, Math.max(...reports.map((id) => navLabel(cNode(id), id).length)));
             for (const id of reports) {
-                const n = getNode(id);
-                const name = (n !== null ? fullName(n) : shortId(id)).padEnd(nameW);
+                const n = cNode(id);
+                const name = navLabel(n, id).padEnd(nameW);
                 const kind = `${DIM}${(n?.kind ?? '').padEnd(6)}${RESET}`;
                 const tokens = `${DIM}${tokensCell(id).padStart(5)}${RESET}`;
-                lines.push(truncate(`  ${coloredGlyph(n)} ${name} ${kind} ${tokens}${childBadge(n)}${askBadge(id)}`));
+                lines.push(truncate(`  ${coloredGlyph(n)} ${name} ${kind} ${tokens}${cycleBadge(n)}${childBadge(n)}${liveBelowBadge(n, activity.activeBelow)}${askBadge(id, asksMap)}${activityCell(id, n)}`));
             }
         }
         // Self's own pending asks (no self row in BASE) → a trailing inline line.
@@ -592,7 +235,10 @@ export function registerCanvasNav(pi) {
     const renderGraph = () => {
         if (ui === undefined)
             return;
-        const rows = buildGraphModel(nodeId);
+        // One subtree-activity pass feeds BOTH the fold policy (which rows show) and
+        // the ⇣N live-work-below badge — computed once here, never re-walked per row.
+        const activity = computeSubtreeActivity(climbRoot(nodeId), nodeId);
+        const rows = buildGraphModel(nodeId, folds, activity.expand);
         // Re-resolve the cursor id → row (it may have vanished under a fold or a
         // close); clamp to nearest visible row.
         let cursorIdx = rows.findIndex((r) => r.id === cursorId);
@@ -634,7 +280,7 @@ export function registerCanvasNav(pi) {
         if (scrollTop > 0)
             lines.push(`${DIM}  ↑ ${scrollTop} more${RESET}`);
         for (let i = scrollTop; i < end; i++)
-            lines.push(renderGraphRow(rows[i], i === cursorIdx, focused));
+            lines.push(renderGraphRow(rows[i], i === cursorIdx, focused, activity.activeBelow, asksMap));
         if (end < rows.length)
             lines.push(`${DIM}  ↓ ${rows.length - end} more${RESET}`);
         const hint = pendingConfirm !== undefined
@@ -649,6 +295,9 @@ export function registerCanvasNav(pi) {
     const render = () => {
         if (ui === undefined)
             return;
+        // Fresh snapshot per render: drop last frame's memoized node/telemetry/edge
+        // reads so this paint reflects current disk+db state, then read-once within it.
+        beginFrame();
         try {
             if (view === 'graph')
                 renderGraph();
@@ -697,7 +346,7 @@ export function registerCanvasNav(pi) {
         view = 'graph';
         pendingConfirm = undefined;
         scrollTop = 0;
-        if (cursorId === undefined || getNode(cursorId) === null)
+        if (cursorId === undefined || cNode(cursorId) === null)
             cursorId = nodeId;
         render();
     };
@@ -714,7 +363,7 @@ export function registerCanvasNav(pi) {
     };
     /** Template vars for a graphBind, resolved against the CURSOR node. */
     const graphVars = (cur) => {
-        const cn = getNode(cur);
+        const cn = cNode(cur);
         return {
             id: cur,
             self: nodeId,
@@ -749,7 +398,7 @@ export function registerCanvasNav(pi) {
             exitGraph();
             return { consume: true };
         }
-        const rows = buildGraphModel(nodeId);
+        const rows = buildGraphModel(nodeId, folds);
         let idx = rows.findIndex((r) => r.id === cursorId);
         if (idx < 0)
             idx = Math.max(0, rows.findIndex((r) => r.id === nodeId));
@@ -815,13 +464,9 @@ export function registerCanvasNav(pi) {
             render();
             return { consume: true };
         }
-        if (isPlain(data, 'e')) {
-            shellCrtr(['canvas', 'tmux-spread', nodeId]);
-            return { consume: true };
-        }
         if (isPlain(data, 'x')) {
             const target = cursorId ?? nodeId;
-            const n = getNode(target);
+            const n = cNode(target);
             const nm = n !== null ? fullName(n) : shortId(target);
             pendingConfirm = { label: `kill ${nm}?`, action: () => shellCrtr(['node', 'close', '--node', target], render) };
             render();
@@ -838,7 +483,7 @@ export function registerCanvasNav(pi) {
             if (argv.length === 0)
                 return { consume: true };
             if (bind.confirm === true) {
-                const n = getNode(target);
+                const n = cNode(target);
                 const nm = n !== null ? fullName(n) : shortId(target);
                 pendingConfirm = { label: `${bind.desc ?? bind.run} ${nm}?`, action: () => shellCrtr(argv, render) };
             }

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

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

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

@@ -36,13 +36,24 @@ import { personaDrift, commitPersonaAck } from '../core/runtime/persona.js';
 import { reviveInPlace } from '../core/runtime/revive.js';
 import { handleNewSession, markCleanExitDone } from '../core/runtime/reset.js';
 import { focusOf, handFocusToManager, tearDownNode, closeFocusToShell } from '../core/runtime/placement.js';
+/** Condense a tool call into one short line for the activity cue. Picks the most
+ *  identifying arg (command / path / pattern / description), collapses whitespace,
+ *  and hard-caps the length so a giant bash command can't bloat telemetry.json. */
+const ACTIVITY_CAP = 80;
+function summarizeActivity(toolName, args) {
+    const a = (args ?? {});
+    const pick = (v) => (typeof v === 'string' ? v : '');
+    const detail = pick(a['command']) || pick(a['path']) || pick(a['file_path']) || pick(a['pattern']) || pick(a['description']) || pick(a['prompt']);
+    const line = (detail !== '' ? `${toolName}: ${detail}` : toolName).replace(/\s+/g, ' ').trim();
+    return line.length > ACTIVITY_CAP ? line.slice(0, ACTIVITY_CAP) : line;
+}
 /**
  * Merge accumulated token counts into nodes/<nodeId>/job/telemetry.json.
  * Creates the directory when it doesn't yet exist. Best-effort; never throws.
  * `contextTokens` is the live window gauge for THIS turn; when null (pi can't
  * size the window yet) the last recorded value is preserved.
  */
-function flushTelemetry(jobDirPath, tokensIn, tokensOut, model, contextTokens) {
+function flushTelemetry(jobDirPath, tokensIn, tokensOut, model, contextTokens, activity) {
     try {
         if (!existsSync(jobDirPath))
             mkdirSync(jobDirPath, { recursive: true });
@@ -62,6 +73,7 @@ function flushTelemetry(jobDirPath, tokensIn, tokensOut, model, contextTokens) {
             tokens_in: tokensIn,
             tokens_out: tokensOut,
             context_tokens: contextTokens ?? existing.context_tokens,
+            last_activity: activity ?? existing.last_activity,
             model: model !== '' ? model : (existing.model ?? ''),
             updated_at: new Date().toISOString(),
         };
@@ -205,6 +217,10 @@ export function registerCanvasStophook(pi) {
     let totalIn = 0;
     let totalOut = 0;
     let model = '';
+    // Last live context-window gauge + last tool summary, tracked across handlers so
+    // a tool_execution_start flush (activity-only) preserves the latest token figure.
+    let lastContext = null;
+    let lastActivity = null;
     // Context-size steering. As input context grows we nudge the node once per
     // band on an escalating, persona-specific schedule (see steerBand/steerNote).
     // The node's (lifecycle, mode) persona is read at fire time, since a terminal
@@ -294,6 +310,18 @@ export function registerCanvasStophook(pi) {
         catch { /* best-effort */ }
     });
     // ---------------------------------------------------------------------------
+    // tool_execution_start — capture the live "what is it doing" cue. Writes the
+    // one-line tool summary to telemetry.json so out-of-process readers (the nav
+    // chrome) show it inline without a second file or any extra read on their side.
+    // ---------------------------------------------------------------------------
+    pi.on('tool_execution_start', (event) => {
+        try {
+            lastActivity = summarizeActivity(String(event?.toolName ?? ''), event?.args);
+            flushTelemetry(jobDirPath, totalIn, totalOut, model, lastContext, lastActivity);
+        }
+        catch { /* best-effort */ }
+    });
+    // ---------------------------------------------------------------------------
     // session_shutdown — clean exit → done.
     //
     // pi hands us a reason as a session tears down. Only 'quit' is a node-ending
@@ -347,8 +375,10 @@ export function registerCanvasStophook(pi) {
                 contextTokens = t;
         }
         catch { /* gauge unavailable this turn */ }
+        if (contextTokens !== null)
+            lastContext = contextTokens;
         // Fire-and-forget: flushTelemetry uses synchronous fs writes and never throws.
-        flushTelemetry(jobDirPath, totalIn, totalOut, model, contextTokens);
+        flushTelemetry(jobDirPath, totalIn, totalOut, model, contextTokens, lastActivity);
         // 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "crtr — fast access to skills, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",