@north-light/crouter 0.3.154

package/dist/clients/attach/chrome/cron-wait.js

@@ -0,0 +1,34 @@
+function relativeTime(iso, nowMs) {
+    const diff = Date.parse(iso) - nowMs;
+    if (diff <= 0)
+        return 'due now';
+    const minutes = Math.ceil(diff / 60_000);
+    if (minutes < 60)
+        return `in ${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    const remMinutes = minutes % 60;
+    if (hours < 24)
+        return `in ${hours}h${remMinutes > 0 ? ` ${remMinutes}m` : ''}`;
+    const days = Math.floor(hours / 24);
+    const remHours = hours % 24;
+    return `in ${days}d${remHours > 0 ? ` ${remHours}h` : ''}`;
+}
+function nextCron(crons) {
+    return [...crons].sort((a, b) => Date.parse(a.fire_at) - Date.parse(b.fire_at))[0];
+}
+/** Compact cockpit row: state first; the native Inspector owns details. */
+export function cronWaitSummary(crons, nowMs = Date.now()) {
+    if (crons.length === 0)
+        return undefined;
+    if (crons.length > 1) {
+        const next = nextCron(crons);
+        return `${crons.length} crons armed${next ? ` · next ${relativeTime(next.fire_at, nowMs)}` : ''}`;
+    }
+    const cron = crons[0];
+    const timing = relativeTime(cron.fire_at, nowMs);
+    if (cron.cancel_on_wake)
+        return `deadline · ${timing}`;
+    if (cron.recur !== null)
+        return `recurring cron · next ${timing}`;
+    return `scheduled cron · ${timing}`;
+}

package/dist/clients/attach/chrome/git-info.d.ts

@@ -0,0 +1,20 @@
+export interface GitInfo {
+    /** Last path segment of the cwd (always present). */
+    dir: string;
+    /** Current branch (or short SHA when detached); undefined outside a repo. */
+    branch?: string;
+    /** Working tree has uncommitted changes (staged, unstaged, or untracked). */
+    dirty: boolean;
+    /** Commits ahead of upstream. */
+    ahead: number;
+    /** Commits behind upstream. */
+    behind: number;
+}
+/** Parse `git status --porcelain=v1 --branch` into {@link GitInfo} flags. The
+ *  first `## ` line carries branch + `[ahead N, behind M]`; any further line is
+ *  a changed/untracked path → dirty. Exported pure for unit tests. */
+export declare function parseGitStatus(dir: string, stdout: string): GitInfo;
+/** Fetch git context for `cwd` without blocking. On any error (not a repo, git
+ *  missing, timeout) the callback still fires with dir-only info so the border
+ *  shows the folder name regardless. */
+export declare function fetchGitInfo(cwd: string, cb: (info: GitInfo) => void): void;

package/dist/clients/attach/chrome/git-info.js

@@ -0,0 +1,44 @@
+// chrome/git-info.ts — async, non-blocking git context for the attach editor border:
+// the working dir's last path segment, current branch, and a couple of status
+// symbols (dirty / ahead / behind). Shells out via execFile (NEVER sync — the
+// viewer must never block its input pump on a subprocess) and reports a plain
+// struct the caller styles into the editor's top border.
+import { execFile } from 'node:child_process';
+import { basename } from 'node:path';
+/** Parse `git status --porcelain=v1 --branch` into {@link GitInfo} flags. The
+ *  first `## ` line carries branch + `[ahead N, behind M]`; any further line is
+ *  a changed/untracked path → dirty. Exported pure for unit tests. */
+export function parseGitStatus(dir, stdout) {
+    const lines = stdout.split('\n').filter((l) => l.length > 0);
+    const info = { dir, dirty: false, ahead: 0, behind: 0 };
+    for (const line of lines) {
+        if (line.startsWith('## ')) {
+            // `## main...origin/main [ahead 1, behind 2]`  or `## HEAD (no branch)`
+            const head = line.slice(3);
+            if (!head.startsWith('HEAD (no branch)')) {
+                const branch = head.split(/\.\.\.| /, 1)[0];
+                if (branch)
+                    info.branch = branch;
+            }
+            info.ahead = Number(/ahead (\d+)/.exec(head)?.[1] ?? 0);
+            info.behind = Number(/behind (\d+)/.exec(head)?.[1] ?? 0);
+        }
+        else {
+            info.dirty = true;
+        }
+    }
+    return info;
+}
+/** Fetch git context for `cwd` without blocking. On any error (not a repo, git
+ *  missing, timeout) the callback still fires with dir-only info so the border
+ *  shows the folder name regardless. */
+export function fetchGitInfo(cwd, cb) {
+    const dir = basename(cwd) || cwd;
+    execFile('git', ['-C', cwd, 'status', '--porcelain=v1', '--branch'], { timeout: 2_000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+        if (err) {
+            cb({ dir, dirty: false, ahead: 0, behind: 0 });
+            return;
+        }
+        cb(parseGitStatus(dir, stdout));
+    });
+}

package/dist/clients/attach/chrome/roster.d.ts

@@ -0,0 +1,26 @@
+import type { AttachSession } from '../session/context.js';
+/** The slice of the session the roster reads. */
+export type RosterSession = Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'canvasSource' | 'tui' | 'pal' | 'editor' | 'containers'>;
+export interface RosterHooks {
+    /** Live per-node human-ticket counts — read fresh on every rebuild, since the
+     *  viewer's attention poll reassigns the map behind us. */
+    asks: () => Record<string, number>;
+    /** Transient footer notice (errors, "already fired", swap failures). */
+    setNotice: (msg: string) => void;
+    /** Ask the viewer to re-run the full chrome refresh. Detail popups call this
+     *  on close so a wait row that resolved while the popup was open disappears. */
+    requestChromeRefresh: () => void;
+    /** Open the viewer-owned Inspector popup (`surface inspect`) on a section —
+     *  the cron wait row routes to `schedule`; the native Inspector owns details. */
+    openInspector: (section: 'overview' | 'schedule') => void;
+}
+export interface AttachRoster {
+    /** Rebuild the rows from the canvas source, reconcile the selection, repaint. */
+    refresh(): Promise<void>;
+    /** Roster key routing, called BEFORE the editor sees the key. Returns true
+     *  when the roster consumed it (the editor must not see it). */
+    handleKey(data: string): boolean;
+    /** Report real tmux-pane focus (DECSET 1004). Repaints the editor cursor. */
+    setPaneFocused(focused: boolean): void;
+}
+export declare function createRoster(s: RosterSession, hooks: RosterHooks): AttachRoster;

package/dist/clients/attach/chrome/roster.js

@@ -0,0 +1,233 @@
+// chrome/roster.ts — the inline subagent scroll+swap roster below the editor.
+//
+// The one report list below the editor doubles as a navigable roster. ↓ at the
+// editor's visual bottom drops the cursor into the list; within it ↑/↓ move the
+// highlight, ↑ off the TOP row returns to the editor, ↓ CLAMPS at the bottom,
+// Enter opens the row (SWAPS this pane in place onto a node, or opens the wait
+// detail surface for a human/cron/bash row), Esc / any typed key returns to the
+// editor. Disabled entirely for a REMOTE attach: a remote graph id has no local
+// pane to swap into and no local jobs/crons to inspect.
+//
+// TWO EDITOR COUPLINGS ARE OWNED HERE, deliberately and exclusively:
+//   • `editor.onCursorDownAtBottom` — the boundary handoff. The editor owns
+//     native ↓ navigation and calls this only after both its visual cursor and
+//     its prompt history are exhausted, which makes the handoff a direct
+//     boundary transition rather than a global-listener replay.
+//   • `editor.paneFocused` — the hollow-cursor state. The cursor is dimmed
+//     whenever the tmux pane is blurred OR the roster holds the cursor: while
+//     scrolling the list the editor is "away", so it must read exactly like an
+//     unfocused pane. The viewer feeds pane focus in through `setPaneFocused`;
+//     the roster half of that conjunction is private to this module.
+//
+// Repainting a selection is purely local: canvas reads can traverse the whole
+// graph, so `refresh()` rebuilds the cached rows asynchronously while arrow
+// movement only reverses the selected cached row and renders immediately.
+import { execFile, execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Text, matchesKey } from '@earendil-works/pi-tui';
+import { cliClient } from '../../../commands/api-client.js';
+import { activeBackgroundBashJobs } from '../../../core/bash-jobs.js';
+import { contextDir } from '../../../core/canvas/paths.js';
+import { fillBar, fillWidth, REVERSE } from '../../../core/canvas/nav-render.js';
+import { inTmux, shellQuote } from '../../../core/runtime/placement-tmux.js';
+import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+import { buildCanvasPanelLines } from './canvas-panels.js';
+import { renderBashJobsDetails } from './bash-jobs.js';
+/** Seed pane focus from the pane's REAL active state, not an unconditional
+ *  `true`. tmux only emits DECSET 1004 focus events on a TRANSITION, so a viewer
+ *  spawned into a non-active pane (a `split -d` beside another node — the
+ *  auto-viewer for a background child) starts unfocused and NEVER receives a
+ *  FOCUS_OUT, leaving a solid cursor drawn until the user swaps in and back out.
+ *  Query `#{pane_active}` for our own pane once at startup so an unfocused split
+ *  renders hollow immediately; default true when not in tmux or the query fails. */
+function initialPaneActive() {
+    const pane = process.env['TMUX_PANE'];
+    if (pane === undefined || pane === '')
+        return true;
+    try {
+        const out = execFileSync('tmux', ['display-message', '-p', '-t', pane, '#{pane_active}'], { encoding: 'utf8' }).trim();
+        return out !== '0';
+    }
+    catch {
+        return true;
+    }
+}
+export function createRoster(s, hooks) {
+    const { editor, tui, pal, nodeId, remote, role, canvasSource } = s;
+    const reports = s.containers.reports;
+    let items = [];
+    let selKey; // undefined ⇒ roster inactive (editor owns the cursor)
+    // Set by the in-place swap to the previously open node id. That node becomes
+    // visible in the new viewer's self-excluding roster, preserving cursor continuity.
+    let autoSelect = process.env['CRTR_ATTACH_ROSTER'];
+    if (autoSelect !== undefined)
+        delete process.env['CRTR_ATTACH_ROSTER'];
+    let paneFocused = initialPaneActive();
+    const syncCursorDim = () => {
+        editor.paneFocused = paneFocused && selKey === undefined;
+    };
+    const paint = () => {
+        syncCursorDim();
+        reports.clear();
+        for (const item of items) {
+            const selected = item.key === selKey;
+            reports.addChild(new Text(selected ? fillBar(item.line, fillWidth(), REVERSE) : item.line, 1, 0));
+        }
+        tui.requestRender();
+    };
+    const refresh = async () => {
+        const ownedCrons = remote
+            ? []
+            : (await cliClient().listCrons()).filter((cron) => cron.created_by === nodeId);
+        // Local-only, same gate as ownedCrons: a remote graph has no local jobs dir
+        // to scan (and a local nodeId collision must never leak background jobs).
+        const bashJobs = remote ? [] : activeBackgroundBashJobs(contextDir(nodeId));
+        const built = await buildCanvasPanelLines(nodeId, hooks.asks(), pal, canvasSource, ownedCrons, bashJobs);
+        items = built.items;
+        // After an in-place swap, land on the previously open node, which has taken
+        // the swapped-to node's place in this self-excluding roster.
+        if (autoSelect !== undefined) {
+            const previousId = autoSelect;
+            autoSelect = undefined;
+            const previous = items.find((item) => item.kind === 'node' && item.nodeId === previousId);
+            if (previous !== undefined)
+                selKey = previous.key;
+        }
+        // The selected row may have vanished (child finished, ask answered, cron
+        // fired) — drop back to the editor so no ghost highlight lingers.
+        if (selKey !== undefined && !items.some((item) => item.key === selKey)) {
+            selKey = undefined;
+        }
+        paint();
+    };
+    const exit = () => {
+        if (selKey !== undefined) {
+            selKey = undefined;
+            paint();
+        }
+    };
+    editor.onCursorDownAtBottom = remote ? undefined : () => {
+        if (selKey !== undefined || items.length === 0)
+            return;
+        selKey = items[0].key;
+        paint();
+    };
+    /** Open a read-only markdown detail popup in nvim, deleting the temp file when
+     *  the popup closes and re-running the chrome refresh (background-bash wait row). */
+    const openDetailsPopup = (prefix, file, title, missingNvim, body) => {
+        const dir = mkdtempSync(join(tmpdir(), prefix));
+        const path = join(dir, file);
+        writeFileSync(path, body, 'utf8');
+        const cmd = `if command -v nvim >/dev/null 2>&1; then exec nvim -R -c 'setlocal filetype=markdown' -- ${shellQuote(path)}; else printf '${missingNvim}\\n'; printf 'Press Enter to close.'; read _; fi`;
+        execFile('tmux', ['display-popup', '-E', '-T', title, '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], () => {
+            rmSync(dir, { recursive: true, force: true });
+            hooks.requestChromeRefresh();
+        });
+    };
+    const openBashJobsDetails = () => {
+        const current = activeBackgroundBashJobs(contextDir(nodeId));
+        if (current.length === 0) {
+            hooks.setNotice('Background job already finished');
+            hooks.requestChromeRefresh();
+            return;
+        }
+        if (!inTmux()) {
+            hooks.setNotice('Background job details require tmux');
+            return;
+        }
+        openDetailsPopup('crtr-bash-jobs-', 'background-bash-jobs.md', ' background bash jobs ', 'nvim is required to inspect background bash jobs. Install Neovim and retry.', renderBashJobsDetails(current));
+    };
+    const openSelected = () => {
+        const item = items.find((candidate) => candidate.key === selKey);
+        if (item === undefined || remote)
+            return;
+        if (item.kind === 'human') {
+            if (role !== 'controller') {
+                hooks.setNotice('Read-only observer attach — cannot open the human inbox');
+                return;
+            }
+            exit();
+            execFile('hl', ['inbox', 'open'], () => { });
+            return;
+        }
+        if (item.kind === 'crons') {
+            exit();
+            hooks.openInspector('schedule');
+            return;
+        }
+        if (item.kind === 'bash') {
+            exit();
+            openBashJobsDetails();
+            return;
+        }
+        const id = item.nodeId;
+        if (id === nodeId) {
+            exit();
+            return;
+        } // already viewing this one
+        if (role !== 'controller') {
+            hooks.setNotice('Read-only observer attach — cannot focus nodes');
+            return;
+        }
+        const pane = process.env['TMUX_PANE'];
+        if (pane === undefined || pane === '') {
+            hooks.setNotice('cannot swap — no tmux pane');
+            return;
+        }
+        // Drive the respawn from OUTSIDE this pane's process tree: `surface node focus
+        // --in-place` re-execs THIS pane onto the child (respawn-pane -k), which would
+        // kill a direct child process mid-swap. `tmux run-shell` runs in the server
+        // context, detached from the pane. `crtr` is on PATH here (same assumption as
+        // the Alt+]/[ node-cycle bindings).
+        execFile('tmux', ['run-shell', '-b', `crtr surface node focus ${id} --pane ${pane} --in-place >/dev/null 2>&1`], () => { });
+    };
+    const handleKey = (data) => {
+        if (remote)
+            return false; // no local node/wait detail target on a remote graph
+        const down = matchesKey(data, 'down');
+        const up = matchesKey(data, 'up');
+        // Until the roster is active, every key follows the normal focused-editor
+        // path. TitledEditor invokes the boundary callback above only after native ↓
+        // can move neither its visual cursor nor prompt history.
+        if (selKey === undefined)
+            return false;
+        // Roster active. Explicit boundaries on the single list: ↑ off the TOP row
+        // returns to the editor; ↓ CLAMPS at the bottom row.
+        const i = items.findIndex((item) => item.key === selKey);
+        if (up) {
+            if (i <= 0)
+                exit();
+            else {
+                selKey = items[i - 1].key;
+                paint();
+            }
+            return true;
+        }
+        if (down) {
+            if (i >= 0 && i < items.length - 1) {
+                selKey = items[i + 1].key;
+                paint();
+            }
+            return true;
+        }
+        if (matchesKey(data, 'enter')) {
+            openSelected();
+            return true;
+        }
+        if (matchesKey(data, 'escape')) {
+            exit();
+            return true;
+        }
+        // Any other key (the user started typing) returns to the editor AND passes
+        // through, so the keystroke lands in the input.
+        exit();
+        return false;
+    };
+    const setPaneFocused = (focused) => {
+        paneFocused = focused;
+        syncCursorDim();
+    };
+    return { refresh, handleKey, setPaneFocused };
+}

package/dist/clients/attach/chrome/status-line.d.ts

@@ -0,0 +1,35 @@
+import type { BindingId, BindingResolution } from '../../../core/keybindings/index.js';
+import type { SessionState } from '../../../core/session-model/session-state.js';
+import type { AttachSession } from '../session/context.js';
+/** Shell/bash mode: 0 = off, 1 = `!` (output goes to the agent's context),
+ *  2 = `!!` (output hidden from the agent). Drives both the editor border hue
+ *  and the leading status segment explaining what will happen. */
+export type BashMode = 0 | 1 | 2;
+export type StatusLineSession = Pick<AttachSession, 'nodeId' | 'remote' | 'tui' | 'pal' | 'containers'>;
+export interface StatusLineHooks {
+    /** The reducer-folded broker state — role, engine, context tokens, queue. */
+    state: () => SessionState;
+    /** The editor's current bash level. */
+    bashMode: () => BashMode;
+    /** Per-node human-ticket counts for this canvas. */
+    asks: () => Record<string, number>;
+    /** The live resolved keybinding snapshot (refreshed by /reload), so shortcut
+     *  hints never go stale against a rebound key. */
+    bindings: () => BindingResolution<BindingId>;
+    /** Whether to render the closed-inbox affordance at all. Meaningful only for
+     *  a LOCAL in-tmux attach: a remote attach's local inbox registry cannot open
+     *  the remote canvas's filesystem tickets. */
+    inboxAffordance: boolean;
+}
+export interface AttachStatusLine {
+    /** Repaint the bar from current state. */
+    render: () => void;
+    /** Show a transient notice in the right slot. `sticky` keeps it up until
+     *  explicitly replaced instead of auto-clearing. */
+    setNotice: (msg: string, opts?: {
+        sticky?: boolean;
+    }) => void;
+    /** Cancel the pending auto-clear. Part of the viewer's local shutdown. */
+    dispose: () => void;
+}
+export declare function createStatusLine(s: StatusLineSession, hooks: StatusLineHooks): AttachStatusLine;

package/dist/clients/attach/chrome/status-line.js

@@ -0,0 +1,133 @@
+// chrome/status-line.ts — the bottom status bar and the transient notice slot.
+//
+// A themed, aligned bar: live state on the LEFT (bash mode · role · model ·
+// context · queued · attention · hint), the transient notice pushed to the
+// RIGHT edge — not jammed inline. Segments are ordered by priority because the
+// left side is ANSI-truncated to fit the terminal width: whatever is appended
+// LAST is what disappears first under a narrow pane.
+//
+// The bar RENDERS state, it does not hold it. Everything it shows lives
+// upstream — the reducer-folded `SessionState`, the editor's bash level, the
+// canvas ask counts, the resolved keybinding snapshot — and is read through the
+// hooks below on every paint, so the bar can never show a stale copy of a fact
+// that changed somewhere else.
+//
+// The one piece of state that IS the bar's own is the notice, because it has a
+// lifetime: transient notices auto-clear after a few seconds so a stale
+// "error: …" doesn't linger forever, while a `sticky` notice stays up until
+// explicitly replaced (the reconnect indicator, cleared by hand on redial).
+// That timer is why this module has a `dispose`.
+import { Text, truncateToWidth } from '@earendil-works/pi-tui';
+import { oldestRunningBashJobStartedAtMs } from '../../../core/bash-jobs.js';
+import { contextDir } from '../../../core/canvas/paths.js';
+import { visibleWidth } from '../../../core/canvas/nav-render.js';
+import { inTmux } from '../../../core/runtime/placement-tmux.js';
+import { backgroundBashHint, formatBinding, inboxOpenHint } from '../../../core/keybindings/index.js';
+const NOTICE_CLEAR_MS = 3_000;
+/** R4 (Alt+C -> b hint): how long a foreground bash command must have been
+ *  running before backgrounding it is worth suggesting. */
+const BASH_HINT_THRESHOLD_MS = 5_000;
+const formatTokens = (n) => n >= 1000 ? `${(n / 1000).toFixed(n >= 10000 ? 0 : 1)}k` : `${n}`;
+export function createStatusLine(s, hooks) {
+    const { pal, tui, nodeId, remote } = s;
+    const footer = s.containers.footer;
+    let notice = '';
+    let noticeTimer;
+    const render = () => {
+        const session = hooks.state();
+        const bashMode = hooks.bashMode();
+        const bindings = hooks.bindings();
+        const segs = [];
+        if (session.role !== 'controller')
+            segs.push(pal.muted('○ read-only'));
+        // Bash mode leads the bar (most salient while typing a `!` command) and
+        // spells out the consequence: a single `!` feeds output to the agent; `!!`
+        // hides it. Hue matches the editor border (dull vs bright green).
+        if (bashMode === 2)
+            segs.unshift(pal.bashModeAlt('● bash — output hidden from agent'));
+        else if (bashMode === 1)
+            segs.unshift(pal.bashMode('● bash — output added to context'));
+        const engine = session.engine;
+        if (engine?.model)
+            segs.push(pal.info(engine.model.id));
+        if (engine?.isStreaming)
+            segs.push(pal.active('⟳'));
+        // Live context occupancy is the prompt-token count of the most recent
+        // assistant turn (input + cacheRead + cacheWrite = everything sent to the
+        // model, since with prompt caching bare `input` is just the uncached slice
+        // and badly understates the context), folded by the reducer off the relayed
+        // message_end stream. It rides data the viewer already receives, so the
+        // indicator needs no broker/protocol change.
+        if (session.contextTokens !== undefined) {
+            segs.push(pal.muted(`${formatTokens(session.contextTokens)} ctx`));
+        }
+        if (engine && engine.pendingMessageCount > 0) {
+            segs.push(pal.muted(`queued ${engine.pendingMessageCount}`));
+        }
+        // Closed-inbox affordance (low-priority, after queued state): the pending
+        // human-ticket total for THIS canvas plus how to open the inbox popup. The
+        // segment disappears at zero. It is a count + affordance only: no ticket
+        // content, no picker, no auto-open. When the binding is disabled the
+        // shortcut clause is omitted in favor of the CLI affordance, never the word
+        // "Disabled".
+        if (hooks.inboxAffordance) {
+            const total = Object.values(hooks.asks()).reduce((sum, n) => sum + n, 0);
+            if (total > 0) {
+                segs.push(pal.muted(`⚑ ${total} · ${inboxOpenHint(bindings)}`));
+            }
+        }
+        // Lowest-priority segment (R4): the Alt+C -> b hint, shown only once the
+        // oldest still-foreground bash job has crossed the threshold. Read straight
+        // off this node's job files rather than tracked from relayed tool-execution
+        // events — that on-disk state is the valve's own authoritative record of
+        // what is really running, so a fresh or reconnected attach (which never
+        // replays past events) reads it correctly with no viewer-local map that
+        // could go stale across a broker/session replacement. Evaluated per paint
+        // and on the viewer's existing 5s chrome poll — no new timer.
+        if (!remote && inTmux()) {
+            const oldestStart = oldestRunningBashJobStartedAtMs(contextDir(nodeId));
+            if (oldestStart !== undefined && Date.now() - oldestStart >= BASH_HINT_THRESHOLD_MS) {
+                const hint = backgroundBashHint(bindings);
+                if (hint !== null)
+                    segs.push(pal.muted(`⧗ ${hint}`));
+            }
+        }
+        // The file-review affordance, tmux-only like the surface it opens.
+        if (inTmux() && bindings.gestures('crtr.attach.file-review').length > 0) {
+            segs.push(pal.muted(`${formatBinding(bindings, 'crtr.attach.file-review')} review file`));
+        }
+        const left = segs.join(pal.muted(' · '));
+        const right = notice ? pal.warning(`⚠ ${notice}`) : '';
+        // Text(_, 1, 0) pads 1 col each side, so the usable span is columns - 2.
+        const span = Math.max(1, (process.stdout.columns ?? 80) - 2);
+        const rightW = visibleWidth(right);
+        // Truncate the left segment (ANSI-aware) so a long model/notice never wraps;
+        // the right-aligned notice keeps its slot.
+        const maxLeft = right ? Math.max(0, span - rightW - 1) : span;
+        const leftFit = visibleWidth(left) > maxLeft ? truncateToWidth(left, maxLeft, '…') : left;
+        const gap = Math.max(right ? 1 : 0, span - visibleWidth(leftFit) - rightW);
+        const line = right ? leftFit + ' '.repeat(gap) + right : leftFit;
+        footer.clear();
+        footer.addChild(new Text(line, 1, 0));
+        tui.requestRender();
+    };
+    const clearTimer = () => {
+        if (noticeTimer !== undefined) {
+            clearTimeout(noticeTimer);
+            noticeTimer = undefined;
+        }
+    };
+    const setNotice = (msg, opts) => {
+        notice = msg;
+        clearTimer();
+        if (msg && !opts?.sticky) {
+            noticeTimer = setTimeout(() => {
+                noticeTimer = undefined;
+                notice = '';
+                render();
+            }, NOTICE_CLEAR_MS);
+        }
+        render();
+    };
+    return { render, setNotice, dispose: clearTimer };
+}

package/dist/clients/attach/chrome/widgets.d.ts

@@ -0,0 +1,9 @@
+import type { SessionState } from '../../../core/session-model/session-state.js';
+import type { AttachSession } from '../session/context.js';
+export interface ChromeWidgets {
+    /** Paint serializable extension widgets into their fixed cockpit slots. */
+    renderExtensionWidgets: () => void;
+    /** Paint the pending steering messages above the editor. */
+    renderQueued: () => void;
+}
+export declare function createChromeWidgets(ctx: Pick<AttachSession, 'tui' | 'pal' | 'containers'>, state: () => SessionState): ChromeWidgets;

package/dist/clients/attach/chrome/widgets.js

@@ -0,0 +1,61 @@
+// chrome/widgets.ts — the two broker-fed container painters: pi extension
+// widgets in their fixed cockpit slots, and the queued-steering panel above
+// the editor. Both read the folded `SessionState` the orchestrator owns, so it
+// arrives as a getter rather than a captured value.
+import { Text, truncateToWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { DynamicBorder } from '@earendil-works/pi-coding-agent';
+export function createChromeWidgets(ctx, state) {
+    const { tui, pal } = ctx;
+    const { chrome, aboveWidgets, belowWidgets, queued } = ctx.containers;
+    /** A recap line is `Goal:`/`State:` + body — bold the label, faint the body.
+     *  Styled BEFORE wrapping (wrapTextWithAnsi carries SGR state across wraps),
+     *  so a wrapped continuation stays faint. Unlabeled lines are all-faint. */
+    const styleRecapLine = (line) => {
+        const m = /^(Goal|State):\s*/.exec(line);
+        if (m === null)
+            return pal.faint(line);
+        return `${pal.bold(m[1] + ':')} ${pal.faint(line.slice(m[0].length))}`;
+    };
+    /** Paint serializable extension widgets into their fixed cockpit slots. The
+     *  recap sits immediately above the editor border and uses the faint palette:
+     *  persistent orientation, but visually a side note rather than primary UI. */
+    const renderExtensionWidgets = () => {
+        const session = state();
+        aboveWidgets.clear();
+        belowWidgets.clear();
+        // The brief is an inline annotation, so do not give it the chat/chrome divider
+        // that would make it read as a separate panel.
+        chrome.clear();
+        if (session.display.widgets['crtr-recap'] === undefined)
+            chrome.addChild(new DynamicBorder(pal.border));
+        const span = Math.max(1, (process.stdout.columns ?? 80) - 2);
+        for (const [key, widget] of Object.entries(session.display.widgets)) {
+            const target = widget.placement === 'belowEditor' ? belowWidgets : aboveWidgets;
+            for (const line of widget.lines) {
+                const styled = key === 'crtr-recap' ? styleRecapLine(line) : line;
+                for (const wrapped of wrapTextWithAnsi(styled, span)) {
+                    target.addChild(new Text(wrapped, 1, 0));
+                }
+            }
+        }
+        tui.requestRender();
+    };
+    // Queued steering/follow-up messages, shown above the editor so you can SEE
+    // what is waiting (not just the footer count). Texts arrive on `queue_update`;
+    // the welcome snapshot carries only a count, so the panel fills from the first
+    // queue change after attach.
+    const renderQueued = () => {
+        const session = state();
+        queued.clear();
+        if (session.queued.length > 0) {
+            const span = Math.max(1, (process.stdout.columns ?? 80) - 4);
+            queued.addChild(new Text(pal.muted(`queued (${session.queued.length}):`), 1, 0));
+            for (const msg of session.queued) {
+                const oneLine = msg.replace(/\s+/g, ' ').trim();
+                queued.addChild(new Text(pal.faint(`  ⋯ ${truncateToWidth(oneLine, span, '…')}`), 1, 0));
+            }
+        }
+        tui.requestRender();
+    };
+    return { renderExtensionWidgets, renderQueued };
+}

package/dist/clients/attach/command.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare function registerAttach(): BranchDef;