@crouton-kit/crouter 0.3.33 → 0.3.35

package/dist/clients/attach/crtr-output-render.js

@@ -0,0 +1,646 @@
+import { truncateToVisualLines } from '@earendil-works/pi-coding-agent';
+import { Box, Text, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { HELP_ICON, iconForPath, suppressOutputForPath, summarizePath, } from '../../core/preview-registry.js';
+// Hard cap on a collapsed crtr card's total rendered lines (rule 12,
+// inline-ui-placement): help synthesis or a normal truncated result never
+// shows more than this many lines total, blank spacer + status + body +
+// expand hint included. PREVIEW_BODY_BUDGET reserves the 3 fixed/possible
+// non-body lines (leading blank, status line, one-line expand hint — shown
+// unconditionally for help, conditionally for a normal truncated result) so
+// blank(1) + status(1) + body(<=budget) + hint(<=1) never exceeds the cap.
+const PREVIEW_MAX_LINES = 20;
+const PREVIEW_BODY_BUDGET = PREVIEW_MAX_LINES - 3;
+const HEREDOC_OPEN = /<<-?\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+const CRTR_IN_COMMAND_POSITION = /(?:^|[\n;&|()]\s*)(?:[A-Za-z_][A-Za-z0-9_]*=\S+\s+)*(?:[^\s;&|()]+\/)?(?:crtr|crouter)(?=\s|$)/;
+export const CRTR_OUTPUT_CUSTOM_TYPE = 'crtr-output';
+export function stripHeredocBodies(command) {
+    const lines = command.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        out.push(line);
+        i++;
+        const delims = [];
+        HEREDOC_OPEN.lastIndex = 0;
+        let match;
+        while ((match = HEREDOC_OPEN.exec(line)) !== null)
+            delims.push(match[2]);
+        for (const delim of delims) {
+            while (i < lines.length) {
+                const probe = lines[i].replace(/^\t+/, '');
+                i++;
+                if (probe === delim)
+                    break;
+            }
+        }
+    }
+    return out.join('\n');
+}
+export function isCrtrBashCommand(command) {
+    return typeof command === 'string' && CRTR_IN_COMMAND_POSITION.test(stripHeredocBodies(command));
+}
+/** Pull the crtr/crouter invocation's own argv tokens out of a full shell
+ *  command string: drop everything before the matched binary token, then cut
+ *  at the next shell-level terminator so a chained `&& echo done` or piped
+ *  `| cat` doesn't leak into the "argv". Tokenized with quote-awareness (see
+ *  tokenizeShellSegment) so a quoted argument that merely *contains* `-h` (a
+ *  prompt string, a literal flag mentioned in prose) is one opaque token, not
+ *  split into a bare `-h` — still not a real shell parse (no backslash escapes,
+ *  no `$()`), but adequate for viewer-only chrome (worst case: a stale/empty
+ *  lookup, never a wrong agent result). */
+function extractCrtrInvocationTokens(command) {
+    const stripped = stripHeredocBodies(command);
+    const match = CRTR_IN_COMMAND_POSITION.exec(stripped);
+    if (match === null)
+        return undefined;
+    const tail = stripped.slice(match.index + match[0].length);
+    const stopAt = tail.search(/[\n;&|)]/);
+    const segment = (stopAt === -1 ? tail : tail.slice(0, stopAt)).trim();
+    return segment === '' ? [] : dropRedirectTail(tokenizeShellSegment(segment));
+}
+/** A crtr invocation's own argv never includes a shell redirect (`>`, `>>`,
+ *  `<`, `<<`, with an optional leading fd digit and/or trailing `&fd`
+ *  duplication, e.g. `2>&1`, `&>`, `1>`) — that's plumbing on the OUTER bash
+ *  call, not part of crtr's own path/args. The terminator scan above already
+ *  cuts the segment on a bare `&`, which coincidentally lands mid-redirect
+ *  for something like `-h 2>&1` (segment becomes `-h 2>`, leaving a dangling
+ *  `2>` token) — rather than special-case that scan, this drops the first
+ *  token that STARTS WITH a redirect operator (and everything after it, since
+ *  nothing past a redirect is ever crtr's own arg). Matching on the prefix
+ *  (not the whole token) is what catches an operator glued to its target with
+ *  no separating space, e.g. `2>/tmp/log` / `>/tmp/log` — bash treats those as
+ *  operator+word regardless of spacing, but this whitespace tokenizer keeps
+ *  them as one token, so a full-string match would miss them. */
+const REDIRECT_TOKEN = /^(?:\d*|&)(?:>>|<<|>|<)/;
+function dropRedirectTail(tokens) {
+    const redirectIdx = tokens.findIndex((t) => REDIRECT_TOKEN.test(t));
+    return redirectIdx === -1 ? tokens : tokens.slice(0, redirectIdx);
+}
+/** Split a shell command segment into tokens, treating a single- or
+ *  double-quoted span as one opaque token (quote characters stripped, no
+ *  escape handling) instead of letting whitespace inside it create extra
+ *  tokens. This is what keeps `-h` embedded in a quoted prompt string (e.g.
+ *  `node new "write about -h flags"`) from ever being mistaken for a real
+ *  `-h` token by isCrtrHelpInvocation below. */
+function tokenizeShellSegment(segment) {
+    const tokens = [];
+    let current = '';
+    let inToken = false;
+    let quote = null;
+    for (const ch of segment) {
+        if (quote !== null) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            inToken = true;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            inToken = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (inToken) {
+                tokens.push(current);
+                current = '';
+                inToken = false;
+            }
+            continue;
+        }
+        current += ch;
+        inToken = true;
+    }
+    if (inToken)
+        tokens.push(current);
+    return tokens;
+}
+/** True when a crtr bash invocation's OWN argv carries a bare -h/--help
+ *  token — the dispatcher renders the leaf's schema, not a result, so it is
+ *  never useful to preview like a normal command's output (see
+ *  src/core/help.ts renderLeafArgv: schema text, not agent-facing result
+ *  text). Checked against extractCrtrInvocationTokens' tokens (scoped to the
+ *  crtr segment only, quote-aware), never the raw command string — a `-h`
+ *  appearing before the crtr segment (`echo -h && crtr canvas snapshot`),
+ *  after it (`crtr canvas snapshot && echo --help`), or inside a quoted
+ *  argument (`crtr node new "write about -h flags"`) must never count. This is
+ *  structural (every leaf's -h has the same shape), so it needs no per-leaf
+ *  metadata — unlike suppressOutput below, which is command-owned. */
+export function isCrtrHelpInvocation(command) {
+    if (typeof command !== 'string')
+        return false;
+    const tokens = extractCrtrInvocationTokens(command);
+    return tokens !== undefined && tokens.some((t) => t === '-h' || t === '--help');
+}
+export function commandPreviewMeta(command) {
+    const tokens = extractCrtrInvocationTokens(command);
+    const isHelp = tokens !== undefined && tokens.some((t) => t === '-h' || t === '--help');
+    return {
+        isHelp,
+        suppressOutput: tokens !== undefined && tokens.length > 0 && suppressOutputForPath(tokens),
+    };
+}
+function commandFromArgs(args) {
+    if (!args || typeof args !== 'object')
+        return '';
+    const command = args.command;
+    return typeof command === 'string' ? command : '';
+}
+function resultText(result) {
+    return (result.content ?? [])
+        .filter((part) => part?.type === 'text' || typeof part?.text === 'string')
+        .map((part) => part.text ?? '')
+        .join('\n')
+        .trimEnd();
+}
+function lineStyle(line, theme) {
+    const trimmed = line.trim();
+    if (trimmed === '')
+        return '';
+    if (/^<\/?(?:command|subcommand|runtime-state|crtr-[^>\s]+|error)(?:\s|>|$)/.test(trimmed)) {
+        const color = trimmed.startsWith('<error') ? 'error' : 'accent';
+        return theme.fg(color, theme.bold(line));
+    }
+    if (/^(Input|Output|Effects|Branches|Output \(|Effects$)/.test(trimmed)) {
+        return theme.fg('toolTitle', theme.bold(line));
+    }
+    if (/^(Spawned|Created|Updated|Wrote|Deleted|Promoted|Demoted|Closed|Revived|Recycled)\b/.test(trimmed)) {
+        return theme.fg('success', line);
+    }
+    if (/^(crtr:|Command exited|Command timed out|Command aborted|unknown subcommand|error\b)/i.test(trimmed)) {
+        return theme.fg('error', line);
+    }
+    if (/^(warning|warn|blocked|attention)\b/i.test(trimmed) || trimmed.includes('⚠')) {
+        return theme.fg('warning', line);
+    }
+    if (/^[●✓]/.test(trimmed))
+        return theme.fg('success', line);
+    if (/^[○◌]/.test(trimmed))
+        return theme.fg('muted', line);
+    if (/^[✗⊘]/.test(trimmed))
+        return theme.fg('error', line);
+    if (/^[├└│]/.test(trimmed))
+        return theme.fg('toolOutput', line);
+    if (/^\s*-\s+/.test(line)) {
+        const idx = line.indexOf('-');
+        return `${line.slice(0, idx)}${theme.fg('muted', '-')}${theme.fg('toolOutput', line.slice(idx + 1))}`;
+    }
+    return theme.fg('toolOutput', line);
+}
+export function renderCrtrOutputText(text, theme) {
+    const body = text || '(no output)';
+    return body.split('\n').map((line) => lineStyle(line, theme)).join('\n');
+}
+// ---------------------------------------------------------------------------
+// Help preview synthesis
+// ---------------------------------------------------------------------------
+//
+// A collapsed `-h` card must never just parrot the call header (the command
+// path, already shown by renderCall) or bottom out in a bare "(schema — ctrl+o
+// to expand)" with zero information. Instead it synthesizes a short,
+// human-useful slice straight out of the command's own rendered help text —
+// still the command's own words (rule 12: previews are command-owned content,
+// not generic renderer chrome), just the compact slice of it. Parsed directly
+// off the exact shapes renderRoot/renderBranch/renderLeafArgv produce
+// (src/core/help.ts) — text-only parsing (no import of help.ts/command.ts:
+// this file must stay bundle-safe, see preview-registry.ts's header) so it is
+// necessarily best-effort, not a real re-parse.
+/** A slash-command echo message's body is `$ crtr <argv>\n\n<schema>`
+ *  (see isHelpFromCrtrOutputContent below); strip that echo line + its
+ *  blank-line separator so synthesis always sees the bare schema, same as
+ *  the bash-card path where `text` already IS the bare schema. */
+function stripCrtrEchoPrefix(text) {
+    if (!text.startsWith('$ '))
+        return text;
+    const nlIdx = text.indexOf('\n');
+    if (nlIdx === -1)
+        return '';
+    const rest = text.slice(nlIdx + 1);
+    return rest.startsWith('\n') ? rest.slice(1) : rest;
+}
+/** renderRoot emits one `<command name="X">` block per subtree with NO
+ *  description attribute; renderBranch emits exactly one `<command
+ *  name="X" description="Y">` block (always WITH the attribute) for the
+ *  branch itself. Leaf help (renderLeafArgv) never emits a `<command>` tag at
+ *  all. That structural difference is enough to tell all three apart from
+ *  the rendered text alone, with no shared type import. */
+function classifyHelpText(text) {
+    const tag = /<command name="[^"]*"([^>]*)>/.exec(text);
+    if (tag === null)
+        return 'leaf';
+    return /\bdescription="/.test(tag[1]) ? 'branch' : 'root';
+}
+/** Root help: a tagline, then one `<command name="X">\n<concept line>` block
+ *  per subtree (see renderRoot). Preview = tagline + `name — concept` per
+ *  subtree, in source order — the same information density as the root -h's
+ *  own orientation line, just one row per subtree instead of the full
+ *  useWhen/subcommand-listing/state detail. */
+function synthesizeRootPreview(text) {
+    const firstTagIdx = text.indexOf('<command name="');
+    const tagline = (firstTagIdx === -1 ? text : text.slice(0, firstTagIdx)).trim();
+    const commands = [];
+    const re = /<command name="([^"]*)">\n([^\n]*)/g;
+    let m;
+    while ((m = re.exec(text)) !== null)
+        commands.push(`${m[1]} \u2014 ${m[2]}`);
+    return [tagline, ...(commands.length > 0 ? ['', ...commands] : [])].join('\n');
+}
+/** Branch help: one `<command name="X" description="Y">` block, then one
+ *  self-closing `<subcommand name="..." description="..." whenToUse="..."/>`
+ *  per child (see renderBranch). Preview = `name — description` for the
+ *  branch itself, then the same for each subcommand — dropping whenToUse
+ *  (already the longest field) and any dynamicState/model prose, which is
+ *  exactly the detail ctrl+o exists to reveal. */
+function synthesizeBranchPreview(text) {
+    const head = /^<command name="([^"]*)" description="([^"]*)">/.exec(text);
+    const name = head?.[1] ?? '';
+    const description = head?.[2] ?? '';
+    const subs = [];
+    const re = /<subcommand name="([^"]*)" description="([^"]*)"[^>]*\/>/g;
+    let m;
+    while ((m = re.exec(text)) !== null)
+        subs.push(`${m[1]} \u2014 ${m[2]}`);
+    return [`${name} \u2014 ${description}`, ...(subs.length > 0 ? ['', ...subs] : [])].join('\n');
+}
+/** Leaf help: `name: summary.` first line, then an `Input`-headed param block
+ *  (each row `  LABEL  description...`, or one un-indented note line when the
+ *  leaf takes no params — see renderLeafArgv/paramLabel). Preview = the
+ *  summary line verbatim (already concise) plus a compact param-name roll-call
+ *  (or the note line) — never the per-param descriptions, Output, or
+ *  Effects sections, which is exactly the schema detail ctrl+o reveals. */
+function synthesizeLeafPreview(text) {
+    const lines = text.split('\n');
+    const out = [lines[0] ?? ''];
+    const inputIdx = lines.indexOf('Input');
+    if (inputIdx === -1)
+        return out.join('\n');
+    const outputIdx = lines.findIndex((l) => l.startsWith('Output ('));
+    const end = outputIdx === -1 ? lines.length : outputIdx;
+    const block = lines.slice(inputIdx + 1, end).filter((l) => l.trim() !== '');
+    const paramNames = block.map((l) => /^\s{2}(\S+)/.exec(l)?.[1]);
+    if (block.length > 0 && paramNames.every((n) => n !== undefined)) {
+        out.push('', `Params: ${paramNames.join(', ')}`);
+    }
+    else if (block.length > 0) {
+        // No param rows (renderLeafArgv's inputNote path) — the note is itself
+        // already a one-line summary, e.g. "No input parameters."
+        out.push('', block[0]);
+    }
+    return out.join('\n');
+}
+/** Synthesize a collapsed-preview body for any `-h` schema text, dispatching
+ *  on classifyHelpText. This is the ONLY place that turns raw help text into
+ *  preview prose — both the bash-card path (CrtrResultComponent) and the
+ *  slash-command echo path (CrtrOutputMessageComponent, via
+ *  stripCrtrEchoPrefix) route through it, so the two surfaces read the same
+ *  way. */
+function synthesizeHelpPreviewText(rawText) {
+    const text = stripCrtrEchoPrefix(rawText);
+    const kind = classifyHelpText(text);
+    if (kind === 'root')
+        return synthesizeRootPreview(text);
+    if (kind === 'branch')
+        return synthesizeBranchPreview(text);
+    return synthesizeLeafPreview(text);
+}
+/** Style one summarizer-produced SummaryLine for terminal rendering: an
+ *  empty text stays blank (no color codes to wrap nothing in), otherwise the
+ *  tone maps straight to a theme color name \u2014 'plain' is the same
+ *  'toolOutput' color the generic renderer's default line style uses,
+ *  everything else (success/error/warning/muted/accent) is already a real
+ *  theme color name used elsewhere in this file. */
+function renderSummaryLine(line, theme) {
+    if (line.text === '')
+        return '';
+    const color = line.tone === undefined || line.tone === 'plain' ? 'toolOutput' : line.tone;
+    return theme.fg(color, line.text);
+}
+/** Only ever rendered for a running or failed call (see statusLines below): a
+ *  SUCCESSFUL call shows no body status line at all, so the success/help
+ *  branches would be dead here. */
+function statusLine(options, theme) {
+    return options.isPartial ? theme.fg('warning', '⟳ crtr running') : theme.fg('error', '✗ crtr failed');
+}
+const DEFAULT_PREVIEW_STATE = { isHelp: false, suppressOutput: false };
+function clampRenderedLines(lines, width) {
+    if (width <= 0)
+        return lines.map(() => '');
+    return lines.map((line) => truncateToWidth(line, width, '…'));
+}
+const PI_TRUNCATION_MARKER = /^\[Showing lines \d+-\d+ of \d+ \([^)]+ limit\)\. Full output: .+\]$/;
+function isPiTruncationMarker(line) {
+    return PI_TRUNCATION_MARKER.test(line.trim());
+}
+function splitGenericTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.includes('|'))
+        return null;
+    // GFM permits omitting either outer pipe (`name | version`, `--- | ---`);
+    // only strip the ones actually present rather than requiring both.
+    const body = trimmed.replace(/^\|/, '').replace(/\|$/, '');
+    const cells = [];
+    let current = '';
+    let i = 0;
+    while (i < body.length) {
+        const ch = body[i];
+        if (ch === '\\' && body[i + 1] === '|') {
+            current += '|';
+            i += 2;
+            continue;
+        }
+        if (ch === '|') {
+            cells.push(current.trim());
+            current = '';
+            i++;
+            continue;
+        }
+        current += ch;
+        i++;
+    }
+    cells.push(current.trim());
+    return cells.length >= 2 ? cells : null;
+}
+function isTableSeparator(cells) {
+    return cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+function hasEdgePipe(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith('|') || trimmed.endsWith('|');
+}
+function readGenericTableBlock(lines, start) {
+    const first = splitGenericTableRow(lines[start]);
+    if (first === null)
+        return null;
+    const rows = [first];
+    let next = start + 1;
+    while (next < lines.length) {
+        const cells = splitGenericTableRow(lines[next]);
+        if (cells === null || cells.length !== first.length)
+            break;
+        rows.push(cells);
+        next++;
+    }
+    // A single matched row with no edge pipe at all (e.g. prose that happens
+    // to contain one literal `|`, `warning: use x | y`) is too weak a signal
+    // to treat as a table — a real GFM row omitting both edges only reads as
+    // one when it's part of a multi-row block (header+separator, or several
+    // consecutive same-shaped rows).
+    if (rows.length === 1 && !hasEdgePipe(lines[start]))
+        return null;
+    const separatorIndex = rows.findIndex(isTableSeparator);
+    if (separatorIndex === 1) {
+        return { next, rows: [rows[0], ...rows.slice(2)], headerRows: 1 };
+    }
+    if (separatorIndex !== -1) {
+        return { next, rows: rows.filter((_, i) => i !== separatorIndex), headerRows: 0 };
+    }
+    return { next, rows, headerRows: 0 };
+}
+function sum(nums) {
+    return nums.reduce((acc, n) => acc + n, 0);
+}
+function tableColumnWidths(rows, width) {
+    const columnCount = rows[0]?.length ?? 0;
+    if (columnCount === 0)
+        return [];
+    const separatorWidth = Math.max(0, columnCount - 1) * 2;
+    const available = Math.max(columnCount, width - separatorWidth);
+    const minWidth = available >= columnCount * 3 ? 3 : 1;
+    const widths = Array.from({ length: columnCount }, (_, col) => Math.max(1, ...rows.map((row) => visibleWidth(row[col] ?? ''))));
+    while (sum(widths) > available) {
+        let widest = -1;
+        for (let i = 0; i < widths.length; i++) {
+            if (widths[i] > minWidth && (widest === -1 || widths[i] > widths[widest]))
+                widest = i;
+        }
+        if (widest === -1)
+            break;
+        widths[widest] = widths[widest] - 1;
+    }
+    return widths;
+}
+function padToVisibleWidth(text, width) {
+    const missing = width - visibleWidth(text);
+    return missing > 0 ? `${text}${' '.repeat(missing)}` : text;
+}
+function formatGenericTableRow(cells, widths) {
+    return cells
+        .map((cell, i) => padToVisibleWidth(truncateToWidth(cell, widths[i] ?? 1, '…'), widths[i] ?? 1))
+        .join('  ')
+        .trimEnd();
+}
+function collectGenericPreviewLines(text, lineBudget, width) {
+    const sourceLines = (text || '(no output)').split('\n');
+    const lines = [];
+    let skippedCount = 0;
+    const push = (line) => {
+        if (lines.length < lineBudget)
+            lines.push(line);
+        else
+            skippedCount++;
+    };
+    let i = 0;
+    while (i < sourceLines.length) {
+        const table = readGenericTableBlock(sourceLines, i);
+        if (table !== null) {
+            const widths = tableColumnWidths(table.rows, width);
+            for (let rowIndex = 0; rowIndex < table.rows.length; rowIndex++) {
+                push({
+                    text: formatGenericTableRow(table.rows[rowIndex], widths),
+                    tone: rowIndex < table.headerRows ? 'accent' : undefined,
+                });
+            }
+            i = table.next;
+            continue;
+        }
+        const textLine = sourceLines[i];
+        push({
+            text: truncateToWidth(textLine, width, '…'),
+            tone: isPiTruncationMarker(textLine) ? 'muted' : undefined,
+        });
+        i++;
+    }
+    return { lines, skippedCount };
+}
+function renderGenericPreview(text, lineBudget, width, theme) {
+    const preview = collectGenericPreviewLines(text, lineBudget, width);
+    return {
+        skippedCount: preview.skippedCount,
+        lines: preview.lines.map((line) => {
+            if (line.tone !== undefined)
+                return renderSummaryLine(line, theme);
+            return lineStyle(line.text, theme);
+        }),
+    };
+}
+class CrtrResultComponent {
+    text;
+    options;
+    context;
+    theme;
+    command;
+    staticPreview;
+    constructor(text, options, context, theme, 
+    /** Source command for the preview lookup (the bash-call path). Omit (or
+     *  pass a static preview below) for a path with no per-leaf lookup, e.g.
+     *  CrtrOutputMessageComponent. */
+    command, staticPreview = DEFAULT_PREVIEW_STATE) {
+        this.text = text;
+        this.options = options;
+        this.context = context;
+        this.theme = theme;
+        this.command = command;
+        this.staticPreview = staticPreview;
+    }
+    /** Both isHelp and suppressOutput are synchronous structural lookups (see
+     *  commandPreviewMeta), so this never needs to invalidate/upgrade a later
+     *  paint — the first render already has the final answer. */
+    currentPreview() {
+        if (this.command === undefined)
+            return this.staticPreview;
+        return commandPreviewMeta(this.command);
+    }
+    render(width) {
+        const preview = this.currentPreview();
+        const isPartial = Boolean(this.options.isPartial);
+        const isError = Boolean(this.context.isError);
+        const isRunningOrFailed = isPartial || isError;
+        // The body carries a status line ONLY while running or failed (⟳ running /
+        // ✗ failed) — the states the call header never shows and where the detail
+        // matters. A SUCCESSFUL call (help or normal) gets NO body status: the
+        // header already named the command (<icon> crtr <path> / <icon> crtr help) and the
+        // output speaks for itself, so a "✓ crtr done" line is pure noise.
+        const statusLines = isRunningOrFailed ? [statusLine(this.options, this.theme)] : [];
+        if (this.options.expanded) {
+            // Expanded = raw truth (never redirect-/-h-stripped, never
+            // synthesized): the exact command as invoked, plus the exact output,
+            // still lineStyle-colored for readability but otherwise unmodified.
+            const styled = renderCrtrOutputText(this.text, this.theme);
+            const commandLine = this.command !== undefined
+                ? [this.theme.fg('muted', `$ ${this.command}`), '']
+                : [];
+            return clampRenderedLines(['', ...statusLines, ...commandLine, ...styled.split('\n')], width);
+        }
+        // Collapse order (rule 12, inline-ui-placement): help schema synthesis,
+        // then a command-owned computed summary (summarizePath — memory read,
+        // memory lint, ...), then a bare suppressOutput hint, then generic
+        // truncation. A still-RUNNING command is always shown raw — there is
+        // nothing to summarize yet. A FAILED command still tries the
+        // command-owned summarizer first: a real `crtr memory lint` failure
+        // (findings) IS command-owned computed content the same as its 0-findings
+        // success shape, not noise to suppress — only when the summarizer
+        // recognizes neither shape (returns null) does the raw failed output show.
+        // suppressOutput stays success-only (checked below): a failure is exactly
+        // when a suppressed leaf's raw output becomes diagnostically important.
+        if (!isPartial) {
+            if (preview.isHelp) {
+                // A collapsed -h card gets a synthesized preview of the schema (rule
+                // 12), never the header's own path repeated and never the raw schema
+                // dump — see synthesizeHelpPreviewText. A -h invocation is never
+                // partial-or-failed in practice (the dispatcher renders the schema
+                // unconditionally), so statusLines is effectively always [] here and
+                // the body is JUST the preview content, no repeated help label.
+                const styled = renderCrtrOutputText(synthesizeHelpPreviewText(this.text), this.theme);
+                const truncated = truncateToVisualLines(styled, PREVIEW_BODY_BUDGET, width);
+                const lines = truncated.visualLines ?? [];
+                const hint = this.theme.fg('muted', '(schema — ctrl+o to expand)');
+                return clampRenderedLines(['', ...statusLines, ...lines, hint], width);
+            }
+            const tokens = this.command !== undefined ? extractCrtrInvocationTokens(this.command) : undefined;
+            const summary = tokens !== undefined ? summarizePath(tokens, this.text) : null;
+            if (summary !== null) {
+                // A command-owned computed summary (e.g. memory read's frontmatter
+                // glance, memory lint's PASS/findings line) — never the raw payload.
+                const summaryLines = summary.map((line) => renderSummaryLine(line, this.theme));
+                const truncated = truncateToVisualLines(summaryLines.join('\n'), PREVIEW_BODY_BUDGET, width);
+                const lines = truncated.visualLines ?? [];
+                const hint = this.theme.fg('muted', '(ctrl+o to expand)');
+                return clampRenderedLines(['', ...statusLines, ...lines, hint], width);
+            }
+            if (!isError && preview.suppressOutput) {
+                // suppressOutput leaves (command-owned, e.g. canvas snapshot) stay a
+                // bare hint — the payload is a machine-readable dump with no useful
+                // human slice to synthesize, unlike help text's structured shape.
+                // Success-only: a failed run of a suppressed leaf still shows the raw
+                // output below, since that is exactly when the detail matters.
+                const hint = this.theme.fg('muted', '(suppressed — ctrl+o to expand)');
+                return clampRenderedLines(['', ...statusLines, hint], width);
+            }
+        }
+        const generic = renderGenericPreview(this.text, PREVIEW_BODY_BUDGET, width, this.theme);
+        if (generic.skippedCount > 0) {
+            const hint = this.theme.fg('muted', `… (${generic.skippedCount} more lines, ctrl+o to expand)`);
+            return clampRenderedLines(['', ...statusLines, ...generic.lines, hint], width);
+        }
+        return clampRenderedLines(['', ...statusLines, ...generic.lines], width);
+    }
+    invalidate() {
+        this.context.invalidate?.();
+    }
+}
+/** First-line convention from crtr-commands/index.ts's pi.sendMessage:
+ *  `$ crtr <argv>\n\n<output>`. Help-only here, never suppressOutput: this
+ *  path renders a slash-command's own static `$ crtr ...` echo, not a live
+ *  bash-call result keyed to a real leaf path, so there is no per-leaf
+ *  suppressOutput lookup to make. */
+function isHelpFromCrtrOutputContent(content) {
+    const firstLine = content.split('\n', 1)[0];
+    return firstLine.startsWith('$ ') && isCrtrHelpInvocation(firstLine.slice(2));
+}
+export class CrtrOutputMessageComponent extends Box {
+    content;
+    theme;
+    body;
+    expanded;
+    constructor(content, expanded, theme) {
+        super(1, 1, (text) => theme.bg('customMessageBg', text));
+        this.content = content;
+        this.theme = theme;
+        this.expanded = expanded;
+        const preview = { isHelp: isHelpFromCrtrOutputContent(content), suppressOutput: false };
+        this.body = new CrtrResultComponent(content, { expanded }, {}, theme, undefined, preview);
+        this.addChild(this.body);
+    }
+    setExpanded(expanded) {
+        if (this.expanded === expanded)
+            return;
+        this.expanded = expanded;
+        const preview = { isHelp: isHelpFromCrtrOutputContent(this.content), suppressOutput: false };
+        this.body = new CrtrResultComponent(this.content, { expanded }, {}, this.theme, undefined, preview);
+        this.clear();
+        this.addChild(this.body);
+    }
+}
+export function createCrtrBashToolDefinition(args) {
+    const command = commandFromArgs(args);
+    if (!isCrtrBashCommand(command))
+        return undefined;
+    return {
+        name: 'bash',
+        label: 'bash',
+        description: 'Render crtr bash output with crtr-specific chrome in the attach viewer.',
+        parameters: {},
+        renderCall(callArgs, theme) {
+            const currentCommand = commandFromArgs(callArgs) || command;
+            // Semantic card, not a bash echo: the header names what the invocation
+            // IS (help schema vs. a crtr command), and the body previews only the
+            // crtr segment's own path/args (extractCrtrInvocationTokens, -h/--help
+            // stripped) — no leading `$`, no raw shell chrome (chained `&&`/`|`
+            // siblings, env-var prefixes) leaking through.
+            const tokens = extractCrtrInvocationTokens(currentCommand);
+            const isHelp = tokens !== undefined && tokens.some((t) => t === '-h' || t === '--help');
+            const pathTokens = (tokens ?? []).filter((t) => t !== '-h' && t !== '--help');
+            const path = pathTokens.join(' ');
+            const icon = isHelp ? HELP_ICON : iconForPath(pathTokens);
+            const prefix = isHelp ? `${icon} crtr help` : `${icon} crtr`;
+            const styledPrefix = theme.fg('accent', theme.bold(prefix));
+            const styledPath = path ? ` ${theme.fg('toolTitle', theme.bold(path))}` : '';
+            return new Text(`${styledPrefix}${styledPath}`, 0, 0);
+        },
+        renderResult(result, options, theme, context) {
+            return new CrtrResultComponent(resultText(result), options, context, theme, command);
+        },
+    };
+}

package/dist/clients/attach/extension-dialogs.js

@@ -1,4 +1,4 @@
-// extension-dialogs.ts — the blocking-dialog renderer for `crtr attach` (T5).
+// extension-dialogs.ts — the blocking-dialog renderer for `crtr surface attach` (T5).
 //
 // The broker forwards an extension's user-blocking UI request as an
 // `extension_ui_request` frame (RpcExtensionUIRequest). The viewer renders it

package/dist/clients/attach/graph-overlay.js

@@ -1,4 +1,4 @@
-// graph-overlay.ts — the alt+g GRAPH navigator overlay for `crtr attach` (Unit Q).
+// graph-overlay.ts — the alt+g GRAPH navigator overlay for `crtr surface attach` (Unit Q).
 //
 // Native reimplementation of canvas-nav.ts's GRAPH modal as a pi-tui OVERLAY
 // (the viewer has no pi extension host). `tui.showOverlay(this, …)` mounts this
@@ -13,7 +13,7 @@
 // canvas-nav). All model/render comes from the shared nav-model layer; keys are
 // decoded with pi-tui's canonical matchesKey (kitty/CSI-u aware).
 //
-// Enter/m/x SHELL `crtr` out-of-process (node focus / node close) — the viewer
+// Enter/m/x SHELL `crtr` out-of-process (node focus / node lifecycle close) — the viewer
 // itself never spawns pi or opens a session (the §0 one-writer invariant). It
 // passes its own pane as `crtr node focus --pane <anchor>`: under the
 // one-viewer-per-node model the target's existing viewer is navigated in place,
@@ -276,7 +276,7 @@ export class GraphOverlay {
             const target = this.cursorId ?? this.self;
             const n = cNode(target);
             const nm = n !== null ? fullName(n) : shortId(target);
-            this.pendingConfirm = { label: `kill ${nm}?`, action: () => this.shellCrtr(['node', 'close', '--node', target]) };
+            this.pendingConfirm = { label: `kill ${nm}?`, action: () => this.shellCrtr(['node', 'lifecycle', 'close', '--node', target]) };
             this.tui.requestRender();
             return;
         }