@crouton-kit/crouter 0.3.28 → 0.3.29

package/dist/clients/attach/clipboard-image.js

@@ -2,9 +2,15 @@
 //
 // pi's `readClipboardImage` is NOT re-exported (it lives behind a native
 // clipboard binding + Photon worker the package gates off `.`-only exports), so
-// we reimplement the READ by shelling out to the platform clipboard tool
-// (pngpaste on macOS, wl-paste on Wayland, xclip on X11) — small + best-effort:
-// no tool / empty clipboard → `null` and the caller shows a brief notice.
+// we reimplement the READ by shelling out to the platform clipboard tool. macOS:
+// `pngpaste` is a faster path IF present, but it is NOT a built-in (`brew install
+// pngpaste`), so the authoritative read is the dependency-free `osascript` path
+// (`the clipboard as «class PNGf»` → temp PNG), which works on a stock Mac.
+// Linux: `wl-paste` on Wayland, `xclip` on X11. The reader DISTINGUISHES three
+// outcomes — got bytes, clipboard genuinely empty, or no clipboard tool / read
+// failure — so the caller's notice is accurate ("No image in the clipboard" vs a
+// precise "install xclip" / "osascript failed") instead of collapsing every
+// miss to "no image".
 //
 // The bytes are then resized AGGRESSIVELY through pi's exported `resizeImage`
 // (which is reusable, unlike the reader) so the base64 stays well within the
@@ -22,6 +28,9 @@
 // straight into a `prompt`/`steer`/`follow_up` frame's `images?` array (or, when
 // dropped, a `note`-only result and no image).
 import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { convertToPng, formatDimensionNote, resizeImage, } from '@earendil-works/pi-coding-agent';
 /** Longest edge (px) the pasted image is resized to — aggressive, matches the
  *  ~1568px long-edge guidance vision models use. */
@@ -34,13 +43,32 @@ const MAX_BYTES = 3 * 1024 * 1024;
 /** Bound the shell read so a giant/garbage clipboard can't blow up memory. */
 const SPAWN_MAX_BUFFER = 64 * 1024 * 1024;
 const SPAWN_TIMEOUT_MS = 3000;
-/** Read + resize the current clipboard image. Returns `null` when there is no
- *  image, no clipboard tool, or the read fails (all best-effort — the caller
- *  shows a brief notice and carries on). */
+/** Persist a (already-resized) clipboard image to a stable temp file and return
+ *  its absolute path, so the attach editor can drop the PATH inline into the
+ *  prompt instead of inlining base64 the agent can't see. The broker runs on the
+ *  same host, so a tmpdir path is readable by the engine. */
+export function writeClipboardImageToFile(image) {
+    const dir = join(tmpdir(), 'crtr-clip-images');
+    mkdirSync(dir, { recursive: true });
+    const ext = image.mimeType === 'image/jpeg' ? 'jpg' : 'png';
+    const path = join(dir, `paste-${Date.now()}-${process.pid}.${ext}`);
+    writeFileSync(path, Buffer.from(image.data, 'base64'));
+    return path;
+}
+/** Read + resize the current clipboard image. Returns `null` ONLY when the
+ *  clipboard genuinely holds no image; a `note`-only result means there is a
+ *  precise reason to surface (no clipboard tool, read failure, or an over-cap
+ *  drop). All best-effort — the caller shows a brief notice and carries on. */
 export async function readClipboardImage() {
-    const raw = readRawClipboardImage();
-    if (!raw)
-        return null;
+    const outcome = readRawClipboardImage();
+    const raw = outcome.image;
+    if (!raw) {
+        // No bytes. A `note` means a precise reason worth surfacing (no clipboard
+        // tool, or a read failure) — return it so the caller shows it instead of the
+        // generic "No image in the clipboard". No note → the clipboard is genuinely
+        // empty → null (caller shows the generic notice).
+        return outcome.note ? { note: outcome.note } : null;
+    }
     // Primary path: resize aggressively. Handles format (PNG/JPEG) + size bound.
     const resized = await resizeImage(new Uint8Array(raw.bytes), raw.mimeType, {
         maxWidth: MAX_EDGE,
@@ -78,36 +106,132 @@ function capped(image) {
 /** Shell out to the platform clipboard tool for raw image bytes. */
 function readRawClipboardImage() {
     if (process.platform === 'darwin') {
-        const out = run('pngpaste', ['-']);
-        return out ? { bytes: out, mimeType: 'image/png' } : null;
+        return selectMacOutcome(run, readMacClipboardViaOsascript);
     }
-    // Linux: Wayland first (wl-paste), then X11 (xclip). Try PNG then JPEG.
-    if (isWayland()) {
-        const out = run('wl-paste', ['--type', 'image/png', '--no-newline']);
-        if (out)
-            return { bytes: out, mimeType: 'image/png' };
+    return selectLinuxOutcome(run, isWayland());
+}
+/** Pure macOS dispatch (the regression-test seam): try `pngpaste` if present,
+ *  else fall through to the native osascript read — a missing `pngpaste` must
+ *  NOT collapse to "no image", which was the stock-Mac bug. */
+export function selectMacOutcome(runTool, readNative) {
+    const fast = runTool('pngpaste', ['-']);
+    if (fast.bytes)
+        return { image: { bytes: fast.bytes, mimeType: 'image/png' } };
+    // pngpaste missing OR clipboard empty → osascript is authoritative.
+    return readNative();
+}
+/** Pure Linux dispatch (the regression-test seam): Wayland (`wl-paste`) first,
+ *  then X11 (`xclip`), PNG then JPEG. If NO tool binary was found, surface a
+ *  precise "install …" note; if a tool ran but found no image, report empty. */
+export function selectLinuxOutcome(runTool, wayland) {
+    let anyToolPresent = false;
+    if (wayland) {
+        const out = runTool('wl-paste', ['--type', 'image/png', '--no-newline']);
+        if (out.bytes)
+            return { image: { bytes: out.bytes, mimeType: 'image/png' } };
+        if (!out.missing)
+            anyToolPresent = true;
     }
     for (const mimeType of ['image/png', 'image/jpeg']) {
-        const out = run('xclip', ['-selection', 'clipboard', '-t', mimeType, '-o']);
-        if (out)
-            return { bytes: out, mimeType };
+        const out = runTool('xclip', ['-selection', 'clipboard', '-t', mimeType, '-o']);
+        if (out.bytes)
+            return { image: { bytes: out.bytes, mimeType } };
+        if (!out.missing)
+            anyToolPresent = true;
+    }
+    if (!anyToolPresent) {
+        return {
+            note: wayland
+                ? 'No clipboard tool found — install wl-clipboard (wl-paste) to paste images'
+                : 'No clipboard tool found — install xclip to paste images',
+        };
+    }
+    return {}; // a tool ran but the clipboard holds no image
+}
+/** AppleScript that writes the clipboard's PNG representation to the temp path
+ *  in `argv`. `the clipboard as «class PNGf»` THROWS when the clipboard has no
+ *  PNG-convertible image — caught → "NO_IMAGE" (a clean empty signal, distinct
+ *  from a failure). A write failure (after `set eof` already truncated the file)
+ *  closes the handle and returns "WRITE_FAILED" rather than swallowing the error
+ *  and reporting a false "OK" over a 0-byte/partial file — so "OK" reliably means
+ *  the full bytes are in the temp file, preserving the empty-vs-failure split. */
+const MAC_PNG_SCRIPT = `on run argv
+  set outPath to item 1 of argv
+  try
+    set pngData to (the clipboard as «class PNGf»)
+  on error
+    return "NO_IMAGE"
+  end try
+  set fh to open for access (POSIX file outPath) with write permission
+  try
+    set eof fh to 0
+    write pngData to fh
+    close access fh
+  on error
+    try
+      close access fh
+    end try
+    return "WRITE_FAILED"
+  end try
+  return "OK"
+end run`;
+/** Native, dependency-free macOS read: osascript (always present) writes the
+ *  clipboard PNG to a temp file we then read. Distinguishes empty ("NO_IMAGE")
+ *  from a genuine read failure so the caller's notice is accurate. */
+function readMacClipboardViaOsascript() {
+    const tmpFile = join(tmpdir(), `crtr-clip-${process.pid}-${Date.now()}.png`);
+    try {
+        const result = spawnSync('osascript', ['-e', MAC_PNG_SCRIPT, tmpFile], {
+            timeout: SPAWN_TIMEOUT_MS,
+            maxBuffer: SPAWN_MAX_BUFFER,
+            encoding: 'utf-8',
+        });
+        if (result.error || result.status !== 0) {
+            return { note: 'Could not read the clipboard (osascript failed)' };
+        }
+        const signal = (result.stdout ?? '').trim();
+        if (signal === 'NO_IMAGE')
+            return {}; // clipboard genuinely holds no image
+        if (signal !== 'OK')
+            return { note: 'Could not read the clipboard image' };
+        let bytes;
+        try {
+            bytes = readFileSync(tmpFile);
+        }
+        catch {
+            return { note: 'Could not read the clipboard image' };
+        }
+        return bytes.length > 0 ? { image: { bytes, mimeType: 'image/png' } } : {};
+    }
+    finally {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch {
+            /* ignore temp-file cleanup errors (NO_IMAGE never created it) */
+        }
     }
-    return null;
 }
 function isWayland() {
     return Boolean(process.env.WAYLAND_DISPLAY) || process.env.XDG_SESSION_TYPE === 'wayland';
 }
-/** Run a clipboard tool; return its stdout Buffer, or `null` on any failure
- *  (missing binary, non-zero exit, timeout, empty output). */
+/** Run a clipboard tool; return its stdout bytes, or a `missing` flag when the
+ *  binary isn't on PATH (so the caller can distinguish "no tool" from "no
+ *  image"). Any other failure (non-zero exit, timeout, empty output) → an empty
+ *  result ({}), i.e. the tool ran but yielded no image. */
 function run(command, args) {
     const result = spawnSync(command, args, {
         timeout: SPAWN_TIMEOUT_MS,
         maxBuffer: SPAWN_MAX_BUFFER,
     });
-    if (result.error || result.status !== 0)
-        return null;
+    if (result.error) {
+        const missing = result.error.code === 'ENOENT';
+        return { missing };
+    }
+    if (result.status !== 0)
+        return {};
     const stdout = result.stdout;
     if (!stdout || stdout.length === 0)
-        return null;
-    return Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
+        return {};
+    return { bytes: Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout) };
 }

package/dist/clients/attach/clipboard-text.d.ts

@@ -0,0 +1,3 @@
+/** Write `text` to the system clipboard. Returns true on success, false when no
+ *  clipboard tool is available or every attempt failed. Never throws. */
+export declare function writeClipboardText(text: string): boolean;

package/dist/clients/attach/clipboard-text.js

@@ -0,0 +1,39 @@
+// clipboard-text.ts — write text to the system clipboard for `crtr attach` (/copy).
+//
+// pi's clipboard binding is not re-exported (see clipboard-image.ts), so we shell
+// out to the platform clipboard tool, mirroring the read path: macOS `pbcopy`
+// (always present), Linux `wl-copy` (Wayland) or `xclip` (X11). Best-effort —
+// returns false (with no throw) when no tool is available or the write fails, so
+// the caller can surface an accurate notice.
+import { spawnSync } from 'node:child_process';
+const SPAWN_TIMEOUT_MS = 3000;
+/** Ordered list of [command, args] clipboard-write tools to try for this
+ *  platform. The first one present on PATH that succeeds wins. */
+function writers() {
+    if (process.platform === 'darwin')
+        return [['pbcopy', []]];
+    const wayland = Boolean(process.env.WAYLAND_DISPLAY) || process.env.XDG_SESSION_TYPE === 'wayland';
+    const xclip = ['xclip', ['-selection', 'clipboard']];
+    const wlcopy = ['wl-copy', []];
+    return wayland ? [wlcopy, xclip] : [xclip, wlcopy];
+}
+/** Write `text` to the system clipboard. Returns true on success, false when no
+ *  clipboard tool is available or every attempt failed. Never throws. */
+export function writeClipboardText(text) {
+    for (const [command, args] of writers()) {
+        const result = spawnSync(command, args, {
+            input: text,
+            timeout: SPAWN_TIMEOUT_MS,
+            encoding: 'utf-8',
+        });
+        // ENOENT → tool not installed; try the next one.
+        if (result.error) {
+            if (result.error.code === 'ENOENT')
+                continue;
+            continue;
+        }
+        if (result.status === 0)
+            return true;
+    }
+    return false;
+}

package/dist/clients/attach/config-load.d.ts

@@ -7,14 +7,15 @@ export declare function defaultAgentDir(): string;
  * wrapper; a missing/malformed file → `undefined` (fall back to defaults).
  */
 export declare function loadUserKeybindings(agentDir?: string): KeybindingsConfig | undefined;
-/**
- * Build the KeybindingsManager the attach viewer drives input with: TUI defaults
- * + vendored `app.*` defs, with the user's overrides applied, registered as the
- * global pi-tui keybindings so reused components pick up the same bindings.
- * (`as unknown as` bridges the readonly `TUI_KEYBINDINGS`/string-literal defs to
- * the mutable `KeybindingDefinitions` param — vendoring cast, no behavior change.)
- */
 export declare function createKeybindingsManager(agentDir?: string): KeybindingsManager;
+/** Register the manager on the editor's pi-tui instance too (see `editorPiTui`),
+ *  so the editor's newline/submit handling honors the same (user-overridden)
+ *  bindings as the rest of the viewer. Call once, after `createKeybindingsManager`. */
+export declare function mirrorKeybindingsToEditor(km: KeybindingsManager): Promise<void>;
+/** Mirror the negotiated kitty-keyboard-protocol flag onto the editor's pi-tui
+ *  instance (ProcessTerminal sets it only on OUR copy). Call after the terminal
+ *  has negotiated, i.e. after `tui.start()`. */
+export declare function mirrorKittyProtocolToEditor(active: boolean): Promise<void>;
 /**
  * The user's theme name from pi settings — project (`<cwd>/.pi/settings.json`)
  * overrides global (`~/.pi/agent/settings.json`). `undefined` → pi's default.
@@ -29,3 +30,49 @@ export declare function applyTheme(opts?: {
     agentDir?: string;
     cwd?: string;
 }): void;
+/**
+ * The named styling roles the attach chrome paints with, all theme-derived so the
+ * viewer matches whatever theme the user configured for pi. Each is a
+ * `str => str` colorizer applied to a whole token.
+ */
+export interface AttachPalette {
+    /** Headings / badges / panel titles — the theme accent (gold in the default). */
+    accent: (s: string) => string;
+    /** Live/active markers + the working spinner — the theme's bright accent (teal). */
+    active: (s: string) => string;
+    /** Informational values (model name, counts) — the theme link color (blue). */
+    info: (s: string) => string;
+    /** Secondary text — the theme muted gray. */
+    muted: (s: string) => string;
+    /** Least-important text — SGR faint (a style, not a hue). */
+    faint: (s: string) => string;
+    /** Border rules / frames — the theme border color. */
+    border: (s: string) => string;
+    /** Distinct-surface paint for a modal/overlay: wraps a WHOLE rendered line so
+     *  it sits on the theme's `selectedBg` background, edge to edge, re-asserting
+     *  the bg after every embedded full-reset so an inner `\x1b[0m` (a status dot,
+     *  the cursor bar) can't punch a hole in the surface. Closes with a bg-only
+     *  reset so the surface never bleeds past the line. */
+    surface: (s: string) => string;
+    /** Emphasis. */
+    bold: (s: string) => string;
+    /** Error text. pi's public theme API does NOT surface the `error` ThemeColor
+     *  (only markdown/select-list/settings-list derived colors are re-exported), so
+     *  this is the semantically-correct ANSI red — NOT an ad-hoc hardcode. */
+    error: (s: string) => string;
+    /** Warning / transient notices. Same constraint as `error` → ANSI yellow. */
+    warning: (s: string) => string;
+}
+/**
+ * Build the attach chrome's color palette from the LIVE theme. Call AFTER
+ * `applyTheme()` — the colors are pulled from pi's `getMarkdownTheme()` /
+ * `getSelectListTheme()`, which read the active theme singleton at call time.
+ *
+ * pi does not re-export the raw `Theme` instance (its `.` export map omits the
+ * `theme` const and `getEditorTheme`/`getTheme`), so the accent/border/muted hues
+ * are sourced from the markdown + select-list theme colorizers, which ARE
+ * re-exported and are themselves backed by `theme.fg(...)`. The two semantic
+ * colors pi never exposes through that surface — `error`/`warning` — fall back to
+ * standard ANSI red/yellow.
+ */
+export declare function attachPalette(): AttachPalette;

package/dist/clients/attach/config-load.js

@@ -16,10 +16,13 @@
 // never fire). We also register it globally via `setKeybindings` so the reused
 // pi-tui components (SelectList autocomplete, the dialog editor) honor overrides.
 import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { KeybindingsManager, TUI_KEYBINDINGS, setKeybindings, } from '@earendil-works/pi-tui';
-import { initTheme } from '@earendil-works/pi-coding-agent';
+import { initTheme, getMarkdownTheme, getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { surfaceBgAnsi } from '../../core/runtime/surface-bg.js';
 /** pi's user config dir: `~/.pi/agent/`. */
 export function defaultAgentDir() {
     return join(homedir(), '.pi', 'agent');
@@ -44,7 +47,10 @@ const APP_KEYBINDINGS = {
     'app.tools.expand': { defaultKeys: 'ctrl+o', description: 'Toggle tool output' },
     'app.thinking.toggle': { defaultKeys: 'ctrl+t', description: 'Toggle thinking blocks' },
     'app.editor.external': { defaultKeys: 'ctrl+g', description: 'Open external editor' },
-    'app.message.followUp': { defaultKeys: 'alt+enter', description: 'Queue follow-up message' },
+    // Alt+Enter inserts a newline in the attach editor (shift+enter is unreliable
+    // across terminals), so the follow-up-queue action drops its alt+enter default
+    // to free the chord — see ATTACH_KEYBINDING_OVERRIDES below.
+    'app.message.followUp': { defaultKeys: [], description: 'Queue follow-up message' },
     'app.message.dequeue': { defaultKeys: 'alt+up', description: 'Restore queued messages' },
     'app.clipboard.pasteImage': { defaultKeys: ['alt+v', 'ctrl+v'], description: 'Paste image from clipboard' },
     'app.session.new': { defaultKeys: [], description: 'Start a new session' },
@@ -78,12 +84,66 @@ export function loadUserKeybindings(agentDir = defaultAgentDir()) {
  * (`as unknown as` bridges the readonly `TUI_KEYBINDINGS`/string-literal defs to
  * the mutable `KeybindingDefinitions` param — vendoring cast, no behavior change.)
  */
+/**
+ * Attach-specific default overrides applied OVER pi's TUI defaults. Alt+Enter
+ * inserts a newline here (the follow-up-queue action gives up its alt+enter
+ * default above), because shift+enter — pi's stock newline chord — does not
+ * transmit a distinct sequence in many terminals. User `keybindings.json` still
+ * wins on top of these (applied as the manager's override config).
+ */
+const ATTACH_KEYBINDING_OVERRIDES = {
+    'tui.input.newLine': { defaultKeys: ['shift+enter', 'alt+enter'], description: 'Insert new line' },
+};
 export function createKeybindingsManager(agentDir = defaultAgentDir()) {
-    const definitions = { ...TUI_KEYBINDINGS, ...APP_KEYBINDINGS };
+    const definitions = {
+        ...TUI_KEYBINDINGS,
+        ...APP_KEYBINDINGS,
+        ...ATTACH_KEYBINDING_OVERRIDES,
+    };
     const km = new KeybindingsManager(definitions, loadUserKeybindings(agentDir));
     setKeybindings(km);
     return km;
 }
+/**
+ * pi-coding-agent's `CustomEditor` resolves `@earendil-works/pi-tui` from its OWN
+ * `node_modules`, which can be a SEPARATE module instance from the one this file
+ * imports (a non-deduped install leaves a nested copy). The editor's newline /
+ * submit handling reads keybindings AND the kitty-protocol flag from THAT
+ * instance's module-globals via `getKeybindings()` / `isKittyProtocolActive()`,
+ * so state we set only on our copy is invisible to it — the user's `alt+enter`
+ * newline binding never applies and Enter falls through to submit. We mirror our
+ * state onto the editor's instance too. When the install IS deduped both resolve
+ * to one module and the mirror is a harmless re-set. Best-effort: a resolution /
+ * import failure leaves the editor on our copy's state (the deduped case).
+ */
+let editorPiTuiPromise;
+function editorPiTui() {
+    if (!editorPiTuiPromise) {
+        editorPiTuiPromise = (async () => {
+            try {
+                const pcaEntry = import.meta.resolve('@earendil-works/pi-coding-agent');
+                const piTuiPath = createRequire(pcaEntry).resolve('@earendil-works/pi-tui');
+                return (await import(pathToFileURL(piTuiPath).href));
+            }
+            catch {
+                return undefined;
+            }
+        })();
+    }
+    return editorPiTuiPromise;
+}
+/** Register the manager on the editor's pi-tui instance too (see `editorPiTui`),
+ *  so the editor's newline/submit handling honors the same (user-overridden)
+ *  bindings as the rest of the viewer. Call once, after `createKeybindingsManager`. */
+export async function mirrorKeybindingsToEditor(km) {
+    (await editorPiTui())?.setKeybindings(km);
+}
+/** Mirror the negotiated kitty-keyboard-protocol flag onto the editor's pi-tui
+ *  instance (ProcessTerminal sets it only on OUR copy). Call after the terminal
+ *  has negotiated, i.e. after `tui.start()`. */
+export async function mirrorKittyProtocolToEditor(active) {
+    (await editorPiTui())?.setKittyProtocolActive(active);
+}
 /**
  * The user's theme name from pi settings — project (`<cwd>/.pi/settings.json`)
  * overrides global (`~/.pi/agent/settings.json`). `undefined` → pi's default.
@@ -111,3 +171,39 @@ export function loadThemeName(opts) {
 export function applyTheme(opts) {
     initTheme(loadThemeName(opts));
 }
+const FAINT = (s) => `\x1b[2m${s}\x1b[22m`;
+const RED = (s) => `\x1b[31m${s}\x1b[39m`;
+const YELLOW = (s) => `\x1b[33m${s}\x1b[39m`;
+/**
+ * Build the attach chrome's color palette from the LIVE theme. Call AFTER
+ * `applyTheme()` — the colors are pulled from pi's `getMarkdownTheme()` /
+ * `getSelectListTheme()`, which read the active theme singleton at call time.
+ *
+ * pi does not re-export the raw `Theme` instance (its `.` export map omits the
+ * `theme` const and `getEditorTheme`/`getTheme`), so the accent/border/muted hues
+ * are sourced from the markdown + select-list theme colorizers, which ARE
+ * re-exported and are themselves backed by `theme.fg(...)`. The two semantic
+ * colors pi never exposes through that surface — `error`/`warning` — fall back to
+ * standard ANSI red/yellow.
+ */
+export function attachPalette() {
+    const md = getMarkdownTheme();
+    const sel = getSelectListTheme();
+    // The distinct-surface bg-on SGR, captured once. Re-asserted after every
+    // embedded `\x1b[0m` (full reset) inside a line so a coloured cell can't drop
+    // back to the default background mid-row; the line ends with `\x1b[49m` (reset
+    // background only) so the surface never bleeds onto the next line.
+    const bgOn = surfaceBgAnsi();
+    return {
+        accent: md.heading,
+        active: md.code,
+        info: md.link,
+        muted: sel.description,
+        faint: FAINT,
+        border: md.hr,
+        bold: md.bold,
+        error: RED,
+        warning: YELLOW,
+        surface: (line) => `${bgOn}${line.replace(/\x1b\[0m/g, `\x1b[0m${bgOn}`)}\x1b[49m`,
+    };
+}

package/dist/clients/attach/context-message.d.ts

@@ -0,0 +1,12 @@
+import { type Component } from '@earendil-works/pi-tui';
+export declare class ContextMessageComponent implements Component {
+    private readonly body;
+    private readonly dim;
+    private readonly label;
+    private expanded;
+    constructor(body: string, expanded: boolean, dim: (s: string) => string, label: (s: string) => string);
+    /** Ctrl+O global tool-output toggle (ChatView.isExpandable duck-type). */
+    setExpanded(expanded: boolean): void;
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/clients/attach/context-message.js

@@ -0,0 +1,72 @@
+// context-message.ts — the viewer's foldable renderer for the `<crtr-context>`
+// bearings block (a `crtr-context` custom message). The broker runs the
+// canvas-context-intro extension, so the VIEWER has no message renderer for it
+// and would otherwise show the full block always. This reimplements the
+// extension's `renderContextMessage` natively (src/pi-extensions/
+// canvas-context-intro.ts): collapsed → one dim line; expanded (Ctrl+O) →
+// label + full wrapped body. It implements `setExpanded`, so the Ctrl+O
+// tool-output toggle (ChatView.toggleToolsExpanded → isExpandable) folds it
+// alongside tool output.
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+/** The label shown in both states. Mirrors the extension's customType stamp. */
+const LABEL = 'crtr context';
+/** Char-based wrap that never emits an over-width line (pi-tui hard-crashes on
+ *  one). Visible-width aware so wide glyphs in the bearings tree count right. */
+function wrapLine(line, width) {
+    if (line === '')
+        return [''];
+    const out = [];
+    let cur = '';
+    for (const ch of line) {
+        if (cur !== '' && visibleWidth(cur + ch) > width) {
+            out.push(cur);
+            cur = ch;
+        }
+        else {
+            cur += ch;
+        }
+    }
+    if (cur !== '')
+        out.push(cur);
+    return out;
+}
+export class ContextMessageComponent {
+    body;
+    dim;
+    label;
+    expanded;
+    constructor(body, expanded, dim, label) {
+        this.body = body;
+        this.dim = dim;
+        this.label = label;
+        this.expanded = expanded;
+    }
+    /** Ctrl+O global tool-output toggle (ChatView.isExpandable duck-type). */
+    setExpanded(expanded) {
+        this.expanded = expanded;
+    }
+    render(width) {
+        const w = width > 0 ? width : 80;
+        if (!this.expanded) {
+            // Paint the [crtr context] label in the accent color and the rest dim, so
+            // the label reads distinctly in BOTH states. Truncate BEFORE painting so the
+            // ANSI wrappers never inflate the measured width (an over-wide line aborts
+            // the whole TUI render).
+            const labelText = `[${LABEL}]`;
+            const rest = ' orienting bearings — ctrl+o to expand';
+            const labelW = visibleWidth(labelText);
+            if (labelW >= w)
+                return [this.label(truncateToWidth(labelText, w, '…'))];
+            return [this.label(labelText) + this.dim(truncateToWidth(rest, w - labelW, '…'))];
+        }
+        const lines = [this.label(truncateToWidth(`[${LABEL}]`, w, '…')), ''];
+        for (const raw of this.body.split('\n')) {
+            for (const seg of wrapLine(raw, w))
+                lines.push(seg);
+        }
+        return lines;
+    }
+    invalidate() {
+        /* stateless — nothing to clear */
+    }
+}

package/dist/clients/attach/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/git-info.js

@@ -0,0 +1,44 @@
+// 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));
+    });
+}