@crouton-kit/crouter 0.3.27 → 0.3.28

package/dist/core/__tests__/fixtures/fake-engine.js

@@ -167,6 +167,16 @@ class FakeSession {
     get messages() {
         return this.messageLog;
     }
+    // The broker's catch-up snapshot reconstructs history from the persisted
+    // session tree (sessionManager.buildSessionContext) — the single source of
+    // truth, since `session.messages` can be sliced by pi's retry/overflow/
+    // compaction recovery. Mirror that surface so the fake's snapshot still serves
+    // the accrued history (G2/G3). The fake's persisted analog IS messageLog.
+    get sessionManager() {
+        return {
+            buildSessionContext: () => ({ messages: this.messageLog, thinkingLevel: 'off', model: null }),
+        };
+    }
     get sessionId() {
         return this.sm.getSessionId();
     }

package/dist/core/__tests__/full/placement-teardown.test.js

@@ -145,6 +145,82 @@ test('handFocusToManager: LIVE backstage manager → swaps its pane INTO the foc
         spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
     }
 });
+// ---------------------------------------------------------------------------
+// BUG REGRESSION (lost focus pane on the push-final race): a focused child's
+// `crtr push final` seeds its manager's inbox MID-TURN; the daemon's second pass
+// can revive the dormant manager BACKSTAGE (the focus row still points at the
+// child) before the child's agent_end runs this handoff. At that point the
+// manager is status='active' with a real backstage pane whose pi is still
+// BOOTING — its recorded pi_pid is the OLD dead pid (the fresh pi records its
+// pid only at session_start). Pre-fix, MAJOR 1 gated on isPidAlive(pi_pid), so
+// it missed the booting manager; the dormant branch missed it too (no longer
+// idle-release) → handFocusToManager returned false → the stophook disarmed the
+// freeze and the USER'S VIEWPORT PANE REAPED while the manager ran on invisibly
+// backstage — the "pane gets lost" bug. The gate is now the PANE itself
+// (paneRunning: exists + command running), which a booting pi satisfies.
+// ---------------------------------------------------------------------------
+test('handFocusToManager (BUG REGRESSION): just-revived manager (RUNNING pane, STALE dead pi_pid) → swap, not reap', { skip: !hasTmux() }, () => {
+    const user = `crtr-hfm-race-user-${process.pid}`;
+    const back = `crtr-hfm-race-back-${process.pid}`;
+    spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600']);
+    spawnSync('tmux', ['new-session', '-d', '-s', back, '-c', '/tmp', 'sleep 600']);
+    try {
+        const userWindow = tmuxOut(['list-windows', '-t', user, '-F', '#{window_id}']).split('\n')[0];
+        const backWindow = tmuxOut(['list-windows', '-t', back, '-F', '#{window_id}']).split('\n')[0];
+        const focusPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']);
+        // The manager's backstage pane: a RUNNING command (the booting pi stand-in).
+        const mgrPane = tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${back}:${backWindow}`, 'sleep 600']);
+        createNode(node('M', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done' }));
+        // The just-revived state: active (transition 'revive'), intent cleared, but
+        // pi_pid NOT yet re-recorded — dead/stale (revive deliberately leaves it).
+        createNode(node('mgr', { pane: mgrPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: null }));
+        openFocusRow('f', focusPane, user, 'M');
+        assert.equal(handFocusToManager('f', 'mgr'), true, 'a booting just-revived manager takes the focus — the pane is what matters, not the stale pid');
+        assert.equal(getFocusByNode('mgr')?.focus_id, 'f', 'the manager occupies the focus row');
+        assert.equal(getFocusById('f')?.pane, mgrPane, 'focus row re-anchored to the manager pane (swap happened)');
+        assert.equal(paneSession(mgrPane), user, 'the booting manager pane physically moved into the user viewport');
+        // Non-vacuous: the pre-fix isPidAlive(mgr.pi_pid) gate fails on pi_pid=null →
+        // returns false without repointing → every assert above fails, and the caller
+        // would have reaped the user's pane.
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
+    }
+});
+test('handFocusToManager: manager pane is a FROZEN remain-on-exit corpse (pane_dead=1) → false, no swap (dead-focus-pane guarantee holds under the pane gate)', { skip: !hasTmux() }, async () => {
+    const user = `crtr-hfm-corpse-user-${process.pid}`;
+    const back = `crtr-hfm-corpse-back-${process.pid}`;
+    spawnSync('tmux', ['new-session', '-d', '-s', user, '-c', '/tmp', 'sleep 600']);
+    spawnSync('tmux', ['new-session', '-d', '-s', back, '-c', '/tmp', 'sleep 600']);
+    try {
+        const userWindow = tmuxOut(['list-windows', '-t', user, '-F', '#{window_id}']).split('\n')[0];
+        const backWindow = tmuxOut(['list-windows', '-t', back, '-F', '#{window_id}']).split('\n')[0];
+        const focusPane = tmuxOut(['display-message', '-p', '-t', `${user}:${userWindow}`, '#{pane_id}']);
+        // A short-lived command frozen by remain-on-exit → pane EXISTS but pane_dead=1.
+        const mgrPane = tmuxOut(['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', `${back}:${backWindow}`, 'sleep 0.2']);
+        spawnSync('tmux', ['set-option', '-p', '-t', mgrPane, 'remain-on-exit', 'on'], { stdio: 'ignore' });
+        // Wait until tmux reports the pane dead (frozen corpse), bounded.
+        for (let i = 0; i < 50; i++) {
+            if (tmuxOut(['display-message', '-p', '-t', mgrPane, '#{pane_dead}']) === '1')
+                break;
+            await new Promise((r) => setTimeout(r, 100));
+        }
+        assert.equal(tmuxOut(['display-message', '-p', '-t', mgrPane, '#{pane_dead}']), '1', 'precondition: the manager pane is a frozen corpse');
+        createNode(node('M', { pane: focusPane, tmux_session: user, window: userWindow, status: 'done' }));
+        createNode(node('mgr', { pane: mgrPane, tmux_session: back, window: backWindow, status: 'active', pi_pid: null }));
+        openFocusRow('f', focusPane, user, 'M');
+        assert.equal(handFocusToManager('f', 'mgr'), false, 'a corpse pane never claims the viewport — caller disarms + reaps');
+        assert.equal(getFocusByNode('mgr'), null, 'occupant NOT repointed (no stranded frozen focus)');
+        assert.equal(getFocusById('f')?.node_id, 'M', 'M still occupies the focus → caller runs closeFocusToShell');
+        // Non-vacuous: a gate of bare paneExists (existence without pane_dead) would
+        // swap the corpse into the viewport and return true — both asserts fail.
+    }
+    finally {
+        spawnSync('tmux', ['kill-session', '-t', user], { stdio: 'ignore' });
+        spawnSync('tmux', ['kill-session', '-t', back], { stdio: 'ignore' });
+    }
+});
 test('handFocusToManager: DORMANT idle-release manager (dead pane) → occupant repointed, NO swap, focus pane UNCHANGED', () => {
     openFocusRow('f', '%focus', 'Suser', 'M');
     // The manager is dormant + idle-release (the ONLY dormant manager the daemon

package/dist/core/__tests__/human-stranded-deliver.test.d.ts

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

package/dist/core/__tests__/human-stranded-deliver.test.js

@@ -0,0 +1,108 @@
+// Run with: node --import tsx/esm --test src/core/__tests__/human-stranded-deliver.test.ts
+//
+// BUG REGRESSION (human-ask broker round-trip): a headless-broker asker strips
+// $TMUX, so the detached `crtr human _run` worker — whose `pushFinal` is the SOLE
+// deliver-back + reap step — never spawned. Worse, the `crtr human inbox` drain
+// path writes response.json directly (humanloop's inbox()) and ALSO never calls
+// pushFinal, so an answered deck strands on disk: the asker never learns the
+// answer and the bridge node leaks active forever.
+//
+// This locks the SECONDARY heal: finalizeResolvedInteraction must, for a still-
+// LIVE bridge node whose interaction is resolved on disk, deliver the answer to
+// the asker (parent auto-subscribed) and reap the bridge node — exactly what the
+// _run worker's pushFinal would have done. Idempotent (no double-deliver once
+// done); a canceled-on-disk response reaps without delivering a result.
+import { test, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createNode, subscribe, getNode } from '../canvas/canvas.js';
+import { closeDb } from '../canvas/db.js';
+import { readInboxSince } from '../feed/inbox.js';
+import { interactionDir, interactionsRoot } from '../artifact.js';
+import { atomicWriteJson, deckPath } from '@crouton-kit/humanloop';
+import { finalizeResolvedInteraction } from '../../commands/human/queue.js';
+let home;
+// A unique cwd so interactionDir (keyed off the REAL homedir + mangled cwd, NOT
+// CRTR_HOME) lands in an isolated, cleanable subtree.
+let workCwd;
+function node(id, parent) {
+    return {
+        node_id: id,
+        name: id,
+        created: new Date().toISOString(),
+        cwd: workCwd,
+        kind: 'developer',
+        mode: 'base',
+        lifecycle: 'terminal',
+        status: 'active',
+        parent,
+    };
+}
+/** Seed an interaction dir on disk the way the kickoff + a resolution would. */
+function seed(jobId, run, response) {
+    const idir = interactionDir(jobId, workCwd);
+    mkdirSync(idir, { recursive: true });
+    atomicWriteJson(deckPath(idir), { interactions: [] });
+    atomicWriteJson(join(idir, 'run.json'), run);
+    atomicWriteJson(join(idir, 'response.json'), response);
+}
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-stranded-'));
+    process.env['CRTR_HOME'] = home;
+    workCwd = mkdtempSync(join(tmpdir(), 'crtr-stranded-cwd-'));
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(interactionsRoot(workCwd), { recursive: true, force: true });
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(interactionsRoot(workCwd), { recursive: true, force: true });
+    rmSync(workCwd, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('answered-but-undelivered ask delivers back to the asker and reaps the bridge', async () => {
+    // Asker A, bridge B under A (parent auto-subscribes to its child bridge).
+    createNode(node('A', null));
+    createNode(node('B', 'A'));
+    subscribe('A', 'B');
+    seed('B', { mode: 'ask', job_id: 'B' }, { responses: [{ id: 'q', selectedOptionId: 'resync', freetext: 'go ahead' }], completedAt: '2026-06-10T22:27:07.000Z' });
+    const acted = await finalizeResolvedInteraction('B');
+    assert.equal(acted, true, 'should have delivered + reaped');
+    // Bridge reaped.
+    assert.equal(getNode('B')?.status, 'done', 'bridge node must be reaped to done');
+    // Answer fanned into the asker's inbox, carrying the choice.
+    const inbox = readInboxSince('A');
+    assert.equal(inbox.length >= 1, true, 'asker inbox must receive the answer pointer');
+    const blob = JSON.stringify(inbox);
+    assert.match(blob, /resync/, 'delivered answer should carry the human selection');
+    // Idempotent: a second sweep is a no-op (node already done — no double-deliver).
+    const again = await finalizeResolvedInteraction('B');
+    assert.equal(again, false, 'must not re-deliver an already-finalized interaction');
+});
+test('a canceled-on-disk response reaps the bridge without delivering a result', async () => {
+    createNode(node('A', null));
+    createNode(node('B', 'A'));
+    subscribe('A', 'B');
+    seed('B', { mode: 'ask', job_id: 'B' }, { canceled: true, canceledAt: '2026-06-10T22:42:04.000Z', reason: 'stale' });
+    const acted = await finalizeResolvedInteraction('B');
+    assert.equal(acted, true);
+    assert.equal(getNode('B')?.status, 'done', 'a canceled stranded bridge must still be reaped');
+    // The asker gets a quiet "no answer is coming" note, not a result.
+    const blob = JSON.stringify(readInboxSince('A'));
+    assert.match(blob, /no answer is coming/);
+});
+test('an unresolved (no response.json) live bridge is left untouched', async () => {
+    createNode(node('A', null));
+    createNode(node('B', 'A'));
+    subscribe('A', 'B');
+    const idir = interactionDir('B', workCwd);
+    mkdirSync(idir, { recursive: true });
+    atomicWriteJson(join(idir, 'run.json'), { mode: 'ask', job_id: 'B' });
+    assert.equal(await finalizeResolvedInteraction('B'), false);
+    assert.equal(getNode('B')?.status, 'active', 'still-pending bridge must stay live');
+});

package/dist/core/__tests__/on-read-dedup-resume.test.d.ts

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

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -0,0 +1,81 @@
+// Bug-regression: on-read doc injection "fires a second time per session".
+//
+// The on-read substrate hook dedups so a doc surfaces at most once per
+// conversation. That dedup set USED to live only in the pi process heap (cleared
+// on session_start). But a node's logical session — the .jsonl transcript —
+// spans MULTIPLE pi processes: a dormancy → revive(resume) cycle exits the old
+// process and launches a fresh `pi --session` that REUSES the same transcript.
+// The fresh process started with an empty set, so any doc already injected
+// before dormancy got injected AGAIN on the next read.
+//
+// The fix persists the set to nodes/<id>/injected-docs.json: a resume rehydrates
+// it (dedup holds), and only the FRESH-transcript launch paths clear it. These
+// tests lock in both halves: the store round-trip, and the dedup surviving a
+// simulated revive(resume) while re-surfacing after a fresh launch.
+//
+// Run: node --import tsx/esm --test src/core/__tests__/on-read-dedup-resume.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { injectedDocsPath } from '../canvas/paths.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { renderOnReadDocs } from '../substrate/on-read.js';
+import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../substrate/injected-store.js';
+const FIXTURE_BODY = 'Fixture body that must surface exactly once.';
+let home;
+let work;
+before(() => {
+    home = mkdtempSync(join(tmpdir(), 'crtr-onread-home-'));
+    process.env['CRTR_HOME'] = home;
+});
+beforeEach(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    work = mkdtempSync(join(tmpdir(), 'crtr-onread-work-'));
+});
+after(() => {
+    closeDb();
+    rmSync(home, { recursive: true, force: true });
+    rmSync(work, { recursive: true, force: true });
+    delete process.env['CRTR_HOME'];
+});
+test('injected-store round-trips and clears', () => {
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    assert.deepEqual([...loadInjectedDocs(node)], [], 'cold load is empty');
+    saveInjectedDocs(node, new Set(['/a', '/b']));
+    assert.deepEqual([...loadInjectedDocs(node)].sort(), ['/a', '/b'], 'save then load round-trips');
+    clearInjectedDocs(node);
+    assert.ok(!existsSync(injectedDocsPath(node)), 'clear removes the file');
+    assert.deepEqual([...loadInjectedDocs(node)], [], 'load after clear is empty');
+});
+test('on-read doc surfaces once, stays deduped across a revive(resume), re-surfaces after a fresh launch', () => {
+    const node = spawnNode({ kind: 'general', cwd: work, parent: null }).node_id;
+    // A positional substrate doc in a `.crouter/memory/` ancestor of the read file.
+    const memDir = join(work, '.crouter', 'memory');
+    mkdirSync(memDir, { recursive: true });
+    writeFileSync(join(memDir, 'onread-fixture.md'), '---\nkind: reference\n' +
+        'when-and-why-to-read: When reading work files, this reference should be read because it is the on-read regression fixture\n' +
+        'file-read-visibility: content\n---\n' +
+        `${FIXTURE_BODY}\n`);
+    const readFile = join(work, 'src', 'file.ts');
+    mkdirSync(join(work, 'src'), { recursive: true });
+    writeFileSync(readFile, 'export const x = 1;\n');
+    // --- pi process #1: cold load; first read surfaces the doc ---
+    const seen = loadInjectedDocs(node);
+    const first = renderOnReadDocs(node, readFile, seen);
+    assert.match(first, new RegExp(FIXTURE_BODY.replace(/[.]/g, '\\.')), 'first read surfaces the doc body');
+    saveInjectedDocs(node, seen);
+    // Same process, repeat read of the same file → deduped in-memory.
+    assert.ok(!renderOnReadDocs(node, readFile, seen).includes(FIXTURE_BODY), 'same-process repeat read is deduped');
+    // --- dormancy → revive(resume): NEW process rehydrates the set from disk ---
+    const seenAfterRevive = loadInjectedDocs(node);
+    assert.deepEqual(seenAfterRevive, seen, 'revive(resume) rehydrates the persisted dedup set');
+    assert.ok(!renderOnReadDocs(node, readFile, seenAfterRevive).includes(FIXTURE_BODY), 'resumed process does NOT re-inject the doc (the bug)');
+    // --- fresh launch (revive resume=false / reviveInPlace) clears the set ---
+    clearInjectedDocs(node);
+    const seenFresh = loadInjectedDocs(node);
+    assert.ok(renderOnReadDocs(node, readFile, seenFresh).includes(FIXTURE_BODY), 'a fresh transcript surfaces the doc again');
+});

package/dist/core/canvas/nav-model.d.ts

@@ -0,0 +1,162 @@
+import type { NodeMeta, SubscriptionRef } from './index.js';
+/** 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. */
+export declare const PI_MAX_WIDGET_LINES = 10;
+export declare const VIEWPORT_FALLBACK_ROWS = 30;
+export declare const ESC = "\u001B[";
+export declare const RESET = "\u001B[0m";
+export declare const BOLD = "\u001B[1m";
+export declare const DIM = "\u001B[2m";
+export declare const REVERSE = "\u001B[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. */
+export declare const BG_ATTACHED = "\u001B[48;5;22m";
+export declare const GREEN = "\u001B[32m";
+export declare const RED = "\u001B[31m";
+export declare const YELLOW = "\u001B[33m";
+export declare const CYAN = "\u001B[36m";
+export declare const GRAY = "\u001B[90m";
+/** Status glyph colored by state: active green, idle dim, done cyan, dead red. */
+export declare function coloredGlyph(node: NodeMeta | null): string;
+/** Visible width, ignoring ANSI escapes. */
+export declare function visibleWidth(s: string): number;
+/** 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. */
+export declare function truncate(s: string, max?: number): string;
+/** 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`. */
+export declare function fillWidth(): number;
+/** 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. */
+export declare function fillBar(content: string, width: number, open: string): string;
+export declare function beginFrame(): void;
+/** getNode memoized for the current frame (meta.json read + sqlite row). */
+export declare function cNode(id: string): NodeMeta | null;
+/** subscriptionsOf (a node's reports) memoized for the current frame. */
+export declare function cSubscriptions(id: string): SubscriptionRef[];
+/** subscribersOf (a node's managers) memoized for the current frame. */
+export declare function cSubscribers(id: string): SubscriptionRef[];
+export interface Telemetry {
+    /** Live context-window size (pi's getContextUsage) — the figure pi's own footer
+     *  shows. This is the node's window fill, NOT a per-turn delta. */
+    context_tokens?: number;
+    /** One-line "what is it doing" cue (`tool: detail`), written on every tool start. */
+    last_activity?: string;
+}
+export declare function readTelemetry(nodeId: string): Telemetry;
+export declare function fmtTokens(n: number): string;
+/** The context-window cell — live window fill rounded to the nearest 1k (the same
+ *  figure pi's footer shows), NOT a per-turn token delta. */
+export declare function tokensCell(id: string): string;
+/** Dimmed live "what is it doing" cue for an ACTIVE node — the last tool it ran.
+ *  Empty for non-active rows (stale once a node parks) and when none is recorded. */
+export declare function activityCell(id: string, node: NodeMeta | null): string;
+/** Revive-count badge (meta.cycles). Hidden on the first cycle (0) to cut noise. */
+export declare function cycleBadge(node: NodeMeta | null): string;
+/** Short on-screen label: the explicit handle when set, else the pi-generated
+ *  description, else the bare name. fullName joins BOTH (`handle description`);
+ *  the nav chrome shows just the first so rows stay compact. */
+export declare function navLabel(node: NodeMeta | null, id: string): string;
+export declare function shortId(id: string): string;
+/** Node ids currently shown in a tmux focus viewport. Built once per render. */
+export declare function focusedNodeIds(): Set<string>;
+/** True when a human is watching `id` right now (tmux focus or broker viewer). */
+export declare function isAttached(id: string, node: NodeMeta | null, focused: ReadonlySet<string>): boolean;
+export declare function fetchAsksMap(rootId: string): Record<string, number>;
+/** First manager (by created) — the UP step for the ancestry spine. */
+export declare function managerOf(id: string): string | 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. */
+export declare function isHumanAsk(id: string): boolean;
+/** A node's direct children that are navigable conversations — human-ask nodes
+ *  dropped. The one place the nav chrome enumerates children. */
+export declare function convoChildIds(id: string): string[];
+/** Live reports (active|idle) of a node — the DOWN set in BASE. */
+export declare function liveReports(id: string): string[];
+/** Direct navigable children — used for the ⤳ badge and fold counts (human-ask
+ *  nodes excluded, so the count matches what the tree actually shows). */
+export declare function childCount(id: string): number;
+/** Climb first-manager edges from `self` to the ancestry root (cycle-guarded). */
+export declare function climbRoot(self: string): string;
+/** Space-joined ids of a node's subtree (cursor-relative {subtree} var). */
+export declare function subtreeIds(root: string): string[];
+/** ⤳M direct-children badge — only on orchestrator rows. */
+export declare function childBadge(node: NodeMeta | null): string;
+/** ⚑K pending-asks badge for a node, read from the supplied per-node ask map. */
+export declare function askBadge(id: string, asks: Record<string, number>): string;
+/** "Live work below" badge — green ⇣N when this node is NOT itself active but has
+ *  N active descendants. The one signal that an idle/parked node isn't dead: real
+ *  work is still running beneath it. Count comes from the single subtree-activity
+ *  pass (no per-row walk). Suppressed on active rows (their own ● already says so). */
+export declare function liveBelowBadge(node: NodeMeta | null, activeBelow: ReadonlyMap<string, number>): string;
+/** 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. */
+export declare function statusRank(id: string): number;
+/** 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. */
+export declare function sortedChildIds(id: string): string[];
+export interface FlatRow {
+    id: string;
+    hasKids: boolean;
+    isSelf: boolean;
+    branch: string;
+    cycle: boolean;
+    collapsed: boolean;
+}
+/** Manual fold OVERRIDES, keyed by id. `userCollapsed` forces a fold, `userExpanded`
+ *  forces an unfold; both override the default activity-driven policy. Held by the
+ *  consumer (the extension / viewer) and threaded into buildGraphModel so this layer
+ *  carries no mutable singletons. */
+export interface FoldState {
+    userExpanded: ReadonlySet<string>;
+    userCollapsed: ReadonlySet<string>;
+}
+/** One bottom-up O(N) pass over the local graph, computing TWO things at once so
+ *  the render path never walks twice:
+ *   - `expand`: which nodes auto-UNFOLD — a node expands when a child subtree holds
+ *     a running ('active') agent or self, so the path to any live agent (and to
+ *     you) is revealed while quiescent branches stay folded.
+ *   - `activeBelow`: per node, the count of ACTIVE descendants (excluding itself) —
+ *     drives the ⇣N "live work below" badge on idle/parked nodes.
+ *  Cycle-guarded (the graph is declared acyclic; a re-seen id contributes only
+ *  its own status, never its subtree again, so counts can't double or loop). */
+export interface SubtreeActivity {
+    expand: Set<string>;
+    activeBelow: Map<string, number>;
+}
+export declare function computeSubtreeActivity(root: string, self: string): SubtreeActivity;
+/** Fold policy alone — thin wrapper over computeSubtreeActivity for the keypress
+ *  path (buildGraphModel without a precomputed set). The render path computes the
+ *  activity once and threads `expand` in, so it never recomputes here. */
+export declare function computeDefaultExpanded(root: string, self: string): Set<string>;
+export declare function buildGraphModel(self: string, folds: FoldState, expand?: ReadonlySet<string>): FlatRow[];
+/** 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). */
+export declare function renderGraphRow(r: FlatRow, isCursor: boolean, focused: ReadonlySet<string>, activeBelow: ReadonlyMap<string, number>, asks: Record<string, number>): string;
+/** 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. */
+export declare function graphWidgetBudget(): number;
+export declare const GRAPH_HINT = "\u001B[2mjk move \u00B7 hl fold \u00B7 \u21B5 focus \u00B7 e expand \u00B7 x kill \u00B7 m mgr \u00B7 esc\u001B[0m";