@north-light/crouter 0.3.154

package/dist/clients/attach/overlays/auth.d.ts

@@ -0,0 +1,13 @@
+import type { TUI } from '@earendil-works/pi-tui';
+import type { Picker, PickerControls } from './pickers.js';
+/** `/login` — show the provider selector, then run pi's native login flow in
+ *  the viewer. On success, notifies the broker to reload auth via reload_auth.
+ *
+ *  Two-stage: composing the ModelRuntime and reading each provider's auth status
+ *  is async (pi 0.82), while the picker itself must be built synchronously from
+ *  the controls the overlay host hands out. So this resolves the runtime first and
+ *  returns the sync picker factory. */
+export declare function buildLoginPicker(tui: TUI, agentDir: string, onAuthReloaded: () => void, notify: (msg: string) => void): Promise<(controls: PickerControls) => Picker>;
+/** `/logout` — show the provider selector in logout mode. On select, deletes the
+ *  provider's credential directly, then notifies the broker to reload. */
+export declare function buildLogoutPicker(agentDir: string, onAuthReloaded: () => void, notify: (msg: string) => void): Promise<(controls: PickerControls) => Picker>;

package/dist/clients/attach/overlays/auth.js

@@ -0,0 +1,245 @@
+// overlays/auth.ts — native /login and /logout overlays for `crtr surface attach`.
+//
+// Runs pi's REAL OAuth/API-key login flow locally in the viewer process.
+// Since crtr surface attach is tmux-local only (viewer + broker = same machine, same
+// filesystem), we can construct a local ModelRuntime over the SAME auth.json the
+// broker uses — no socket round-trip needed for auth mutations.
+//
+// The OAuthSelectorComponent (provider picker) and LoginDialogComponent (the
+// actual login flow UI) are pi's own exported components, used verbatim.
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { ModelRuntime, OAuthSelectorComponent, LoginDialogComponent, } from '@earendil-works/pi-coding-agent';
+import { deleteAuthCredential, setAuthCredential } from '../../../core/auth-file.js';
+import { PoolCredentialStore } from '../../../core/pool-credential-store.js';
+import { dialogAuthInteraction } from '../../../core/auth-interaction.js';
+import { commitManagedLogin, isManagedProvider, readSubscriptionPool, removeManagedProvider, } from '../../../core/subscription-state.js';
+/** Build a ModelRuntime over the broker's agentDir (or pi's default). It reads the
+ *  SAME auth.json the broker uses — the viewer and broker share the filesystem
+ *  (tmux-local invariant). */
+async function buildLocalAuth(agentDir) {
+    const authPath = join(agentDir, 'auth.json');
+    const modelsPath = join(agentDir, 'models.json');
+    const runtime = await ModelRuntime.create({
+        credentials: new PoolCredentialStore(authPath),
+        modelsPath,
+    });
+    return { runtime, authPath };
+}
+/** Assemble the AuthSelectorProvider list for the OAuth selector: every composed
+ *  provider, OAuth ones first, each carrying its current auth status (which the
+ *  selector renders as the configured indicator). */
+async function buildProviderList(runtime) {
+    const all = runtime.getProviders();
+    const ordered = [
+        ...all.filter((provider) => provider.auth.oauth !== undefined),
+        ...all.filter((provider) => provider.auth.oauth === undefined),
+    ];
+    return Promise.all(ordered.map(async (provider) => ({
+        id: provider.id,
+        name: provider.name,
+        authType: provider.auth.oauth !== undefined ? 'oauth' : 'api_key',
+        status: await runtime.checkAuth(provider.id),
+    })));
+}
+/** Open the browser with a URL (best-effort; platform-specific). */
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    execFile(cmd, [url], { timeout: 5_000 }, () => {
+        /* best-effort: browser open is fire-and-forget */
+    });
+}
+/** `/login` — show the provider selector, then run pi's native login flow in
+ *  the viewer. On success, notifies the broker to reload auth via reload_auth.
+ *
+ *  Two-stage: composing the ModelRuntime and reading each provider's auth status
+ *  is async (pi 0.82), while the picker itself must be built synchronously from
+ *  the controls the overlay host hands out. So this resolves the runtime first and
+ *  returns the sync picker factory. */
+export async function buildLoginPicker(tui, agentDir, onAuthReloaded, notify) {
+    const { runtime, authPath } = await buildLocalAuth(agentDir);
+    const providers = await buildProviderList(runtime);
+    return ({ close, replace }) => {
+        const onSelect = (providerId) => {
+            const provider = providers.find((p) => p.id === providerId);
+            if (provider === undefined) {
+                notify(`Unknown provider: ${providerId}`);
+                close();
+                return;
+            }
+            // `finish()` is the single idempotent exit for the login dialog: tear the
+            // whole picker down (which restores editor focus), exactly once, no matter
+            // which path (success, failure, or an Esc-cancel that aborts mid-flow) gets
+            // there first. The OAuth/cancel paths resolve through DIFFERENT channels (the
+            // login() promise vs the dialog's onComplete), so the guard prevents a double
+            // close + double notify.
+            let settled = false;
+            let committing = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                close();
+            };
+            const dialog = new LoginDialogComponent(tui, providerId, (success, message) => {
+                // The dialog's own completion (chiefly an Esc-cancel). On a real OAuth
+                // success the login() promise below already finished + notified, so the
+                // settled guard makes this a no-op then.
+                if (settled)
+                    return;
+                if (success) {
+                    notify(`Logged in to ${provider.name}`);
+                    onAuthReloaded();
+                }
+                else {
+                    notify(message ? `Login failed: ${message}` : `Login to ${provider.name} was cancelled`);
+                }
+                finish();
+            }, provider.name);
+            // Swap the provider selector for the login dialog IN PLACE — it renders
+            // inline under the editor (same slot as the model picker), not as a centered
+            // overlay. `replace` focuses the dialog; `close()` (via finish) unmounts it.
+            replace(dialog, dialog);
+            const handleDialogInput = dialog.handleInput.bind(dialog);
+            dialog.handleInput = (data) => { if (!committing)
+                handleDialogInput(data); };
+            const beginCommit = () => {
+                if (settled || dialog.signal.aborted)
+                    return false;
+                committing = true;
+                dialog.showDetails(['Saving credentials…']);
+                return true;
+            };
+            const interaction = dialogAuthInteraction(dialog, {
+                openBrowser,
+                isActive: () => !settled && !dialog.signal.aborted,
+            });
+            const fail = (err) => {
+                // An Esc-cancel aborts the flow; the dialog's onComplete already notified +
+                // finished, so only report a genuine error here.
+                const error = err;
+                if (error?.name !== 'AbortError' && error?.message !== 'Login cancelled') {
+                    notify(`Login error: ${String(error?.message ?? err)}`);
+                }
+                finish();
+            };
+            if (isManagedProvider(providerId)) {
+                // Managed provider OAuth is collected here and persisted through the coordinated pool
+                // writer rather than runtime.login(). The pool is the credential store and owns account
+                // identity, deduplication, and label selection.
+                const oauth = runtime.getProvider(providerId)?.auth.oauth;
+                if (oauth === undefined) {
+                    notify(`Provider "${provider.name}" has no OAuth flow`);
+                    finish();
+                    return;
+                }
+                // Snapshot the pool's newest cooldown before OAuth. A later 429 remains authoritative
+                // when the successful login updates that account.
+                const lastRateLimitedAt = Math.max(0, ...readSubscriptionPool(providerId).map((entry) => entry.lastRateLimitedAt));
+                // `auth.oauth.login()` RETURNS the credential without persisting it (0.82 made
+                // persistence app-owned), which is exactly the collect-without-persist half we need.
+                oauth
+                    .login(interaction)
+                    .then(async (credential) => {
+                    if (!beginCommit())
+                        return;
+                    const accountId = typeof credential.accountId === 'string' && credential.accountId.trim()
+                        ? credential.accountId.trim()
+                        : undefined;
+                    await commitManagedLogin(providerId, providerId, {
+                        refresh: credential.refresh,
+                        access: credential.access,
+                        expires: credential.expires,
+                        accountId,
+                        lastRateLimitedAt,
+                        autoLabel: true,
+                    });
+                    notify(`Logged in to ${provider.name}`);
+                    onAuthReloaded();
+                    finish();
+                })
+                    .catch(fail);
+                return;
+            }
+            if (provider.authType === 'oauth') {
+                if (runtime.getProvider(providerId)?.auth.oauth === undefined) {
+                    // An extension-registered provider: its OAuth impl lives in the broker's
+                    // runtime, not the viewer's local one, so we cannot drive the flow here.
+                    dialog.showInfo([
+                        `Provider "${provider.name}" is extension-registered and cannot be logged in`,
+                        `from the viewer (the extension runs in the broker, not here).`,
+                        `Run /login directly in the node's terminal, or log in via the pi CLI.`,
+                    ].join('\n'));
+                    // The dialog stays up; an Esc routes through onComplete → finish().
+                    return;
+                }
+                // Non-managed OAuth: `runtime.login` persists through crouter's own credential
+                // store, so auth.json lands exactly where the broker reads it.
+                runtime
+                    .login(providerId, 'oauth', interaction)
+                    .then(() => {
+                    if (settled)
+                        return; // a cancel/abort already closed it
+                    notify(`Logged in to ${provider.name}`);
+                    onAuthReloaded();
+                    finish();
+                })
+                    .catch(fail);
+            }
+            else {
+                // API-key provider: prompt for the key and persist it locally.
+                dialog
+                    .showPrompt(`Enter API key for ${provider.name}:`, 'sk-...')
+                    .then(async (key) => {
+                    if (settled)
+                        return;
+                    if (key.trim()) {
+                        if (!beginCommit())
+                            return;
+                        await setAuthCredential(providerId, { type: 'api_key', key: key.trim() }, authPath);
+                        notify(`API key saved for ${provider.name}`);
+                        onAuthReloaded();
+                    }
+                    else {
+                        notify('No key entered — login cancelled');
+                    }
+                    finish();
+                })
+                    .catch(() => finish());
+            }
+        };
+        const component = new OAuthSelectorComponent('login', providers, onSelect, () => close());
+        return { component, focus: component };
+    };
+}
+/** `/logout` — show the provider selector in logout mode. On select, deletes the
+ *  provider's credential directly, then notifies the broker to reload. */
+export async function buildLogoutPicker(agentDir, onAuthReloaded, notify) {
+    const { runtime, authPath } = await buildLocalAuth(agentDir);
+    const providers = await buildProviderList(runtime);
+    return ({ close }) => {
+        const onSelect = (providerId) => {
+            const provider = providers.find((p) => p.id === providerId);
+            void (async () => {
+                try {
+                    // Managed providers tear down the WHOLE provider (every rotation account) through the
+                    // coordinated service, never a raw credential delete that would strip only auth.json and
+                    // orphan the pool.
+                    if (isManagedProvider(providerId))
+                        await removeManagedProvider(providerId);
+                    else
+                        await deleteAuthCredential(providerId, authPath);
+                    close();
+                    notify(`Logged out of ${provider?.name ?? providerId}`);
+                    onAuthReloaded();
+                }
+                catch (error) {
+                    close();
+                    notify(`Logout error: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            })();
+        };
+        const component = new OAuthSelectorComponent('logout', providers, onSelect, () => close());
+        return { component, focus: component };
+    };
+}

package/dist/clients/attach/overlays/dialogs.d.ts

@@ -0,0 +1,27 @@
+import { KeybindingsManager, type TUI } from '@earendil-works/pi-tui';
+import type { RpcExtensionUIRequest, RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
+/** Handle for a rendered dialog: tear it down (without responding) when the
+ *  request is superseded, answered, or dismissed by the broker. */
+export interface DialogHandle {
+    dismiss(): void;
+}
+/** The 4 user-blocking dialog methods. Other RpcExtensionUIRequest methods are
+ *  non-blocking display ops; callers handle them before rendering a dialog. */
+export declare function isBlockingDialog(req: RpcExtensionUIRequest): boolean;
+/**
+ * Render a blocking extension dialog as a focused overlay over `tui`, and resolve
+ * by invoking `onRespond` with the matching `extension_ui_response` (or a
+ * `cancelled` response on user-cancel/timeout). Returns a {@link DialogHandle}
+ * whose `dismiss()` removes the overlay without responding (idempotent; safe to
+ * call after the dialog already resolved).
+ *
+ * @param keybindings - used only by the `editor` dialog, which calls
+ *   `keybindings.matches(key, "app.editor.external")` for the Ctrl+G external-editor
+ *   shortcut. Defaults to a fresh `KeybindingsManager(TUI_KEYBINDINGS)` — that
+ *   knows the base TUI bindings but not pi's app-level `app.editor.external`, so
+ *   Ctrl+G is inert until the input controller (T6) passes the app keybindings
+ *   manager. `ExtensionEditorComponent` is typed against pi's CORE
+ *   KeybindingsManager (a subclass of pi-tui's), so we widen via the constructor's
+ *   own parameter type rather than importing the core class (type-only export).
+ */
+export declare function renderDialog(tui: TUI, req: RpcExtensionUIRequest, onRespond: (resp: RpcExtensionUIResponse) => void, keybindings?: KeybindingsManager): DialogHandle;

package/dist/clients/attach/overlays/dialogs.js

@@ -0,0 +1,102 @@
+// overlays/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
+// with pi's matching exported component and ships the resolved
+// `extension_ui_response` (RpcExtensionUIResponse) back over the socket.
+//
+// Every `ctx.ui.*` call arrives in that ONE envelope, discriminated by `method`;
+// only the 4 blocking methods render overlays here. The non-blocking rest are
+// handled by the viewer before calling `renderDialog` (notify becomes the normal
+// notice line; setStatus/setWidget/setTitle paint footer/widget/title chrome).
+// If one still reaches `renderDialog`, it returns an inert handle — no overlay,
+// no response, because there is nothing to answer. `InputController.attachDialog`
+// additionally refuses them BEFORE its supersede-teardown, so a chrome paint can
+// never orphan a live blocking request.
+//
+// Mapping (mirrors interactive-mode.js): select → ExtensionSelectorComponent;
+// confirm → the SAME selector over ["Yes","No"] (pi has no separate confirm
+// component, :1658); input → ExtensionInputComponent; editor →
+// ExtensionEditorComponent. The select/input components run their own
+// timeout/countdown when `req.timeout` is present; editor takes none. The broker
+// ALSO arms a default timeout, so a dialog may be superseded by the broker
+// resolving first — `dismiss()` tears the overlay down cleanly without
+// responding (the response would be a no-op the broker drops by id).
+import { KeybindingsManager, TUI_KEYBINDINGS, } from '@earendil-works/pi-tui';
+import { ExtensionEditorComponent, ExtensionInputComponent, ExtensionSelectorComponent, } from '@earendil-works/pi-coding-agent';
+/** The 4 user-blocking dialog methods. Other RpcExtensionUIRequest methods are
+ *  non-blocking display ops; callers handle them before rendering a dialog. */
+export function isBlockingDialog(req) {
+    return (req.method === 'select' ||
+        req.method === 'confirm' ||
+        req.method === 'input' ||
+        req.method === 'editor');
+}
+const INERT = { dismiss: () => { } };
+const OVERLAY_OPTIONS = { anchor: 'center', width: '70%', maxHeight: '80%' };
+/**
+ * Render a blocking extension dialog as a focused overlay over `tui`, and resolve
+ * by invoking `onRespond` with the matching `extension_ui_response` (or a
+ * `cancelled` response on user-cancel/timeout). Returns a {@link DialogHandle}
+ * whose `dismiss()` removes the overlay without responding (idempotent; safe to
+ * call after the dialog already resolved).
+ *
+ * @param keybindings - used only by the `editor` dialog, which calls
+ *   `keybindings.matches(key, "app.editor.external")` for the Ctrl+G external-editor
+ *   shortcut. Defaults to a fresh `KeybindingsManager(TUI_KEYBINDINGS)` — that
+ *   knows the base TUI bindings but not pi's app-level `app.editor.external`, so
+ *   Ctrl+G is inert until the input controller (T6) passes the app keybindings
+ *   manager. `ExtensionEditorComponent` is typed against pi's CORE
+ *   KeybindingsManager (a subclass of pi-tui's), so we widen via the constructor's
+ *   own parameter type rather than importing the core class (type-only export).
+ */
+export function renderDialog(tui, req, onRespond, keybindings) {
+    if (!isBlockingDialog(req))
+        return INERT;
+    let done = false;
+    let handle;
+    let component;
+    const teardown = () => {
+        handle?.hide();
+        const disposable = component;
+        try {
+            disposable?.dispose?.();
+        }
+        catch {
+            /* ignore dispose errors during teardown */
+        }
+    };
+    const respond = (resp) => {
+        if (done)
+            return;
+        done = true;
+        teardown();
+        onRespond(resp);
+    };
+    const cancel = () => respond({ type: 'extension_ui_response', id: req.id, cancelled: true });
+    switch (req.method) {
+        case 'select':
+            component = new ExtensionSelectorComponent(req.title, req.options, (option) => respond({ type: 'extension_ui_response', id: req.id, value: option }), cancel, { tui, timeout: req.timeout });
+            break;
+        case 'confirm':
+            component = new ExtensionSelectorComponent(`${req.title}\n${req.message}`, ['Yes', 'No'], (option) => respond({ type: 'extension_ui_response', id: req.id, confirmed: option === 'Yes' }), cancel, { tui, timeout: req.timeout });
+            break;
+        case 'input':
+            component = new ExtensionInputComponent(req.title, req.placeholder, (value) => respond({ type: 'extension_ui_response', id: req.id, value }), cancel, { tui, timeout: req.timeout });
+            break;
+        case 'editor':
+            component = new ExtensionEditorComponent(tui, (keybindings ?? new KeybindingsManager(TUI_KEYBINDINGS)), req.title, req.prefill, (value) => respond({ type: 'extension_ui_response', id: req.id, value }), cancel);
+            break;
+        default:
+            return INERT;
+    }
+    handle = tui.showOverlay(component, OVERLAY_OPTIONS);
+    return {
+        dismiss: () => {
+            if (done)
+                return;
+            done = true;
+            teardown();
+        },
+    };
+}

package/dist/clients/attach/overlays/file-review.d.ts

@@ -0,0 +1,9 @@
+import type { AccessoryOutcome } from '@crouton-kit/humanloop';
+import type { Picker } from './pickers.js';
+import { extractFilePaths } from '../visible-paths.js';
+export declare function buildFileReviewPicker(candidates: readonly string[], cwd: string, onChoose: (file: string) => void, close: () => void, notify: (message: string) => void): Picker;
+export declare function launchFileReview(file: string, cwd: string, opts: {
+    onDone: (outcome: AccessoryOutcome) => void;
+    onNotice: (message: string) => void;
+}): void;
+export { extractFilePaths };

package/dist/clients/attach/overlays/file-review.js

@@ -0,0 +1,181 @@
+import { execFile } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Input, SelectList, getKeybindings, } from '@earendil-works/pi-tui';
+import { getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { shellQuote } from '../../../core/runtime/placement-tmux.js';
+import { surfaceTmuxStyleArgs } from '../../../core/runtime/surface-bg.js';
+import { checkReviewableFile, extractFilePaths } from '../visible-paths.js';
+const MAX_VISIBLE_ROWS = 12;
+function labelForPath(file, cwd) {
+    const rel = relative(cwd, file);
+    if (rel !== '' && !rel.startsWith('..') && !isAbsolute(rel))
+        return rel;
+    const home = homedir();
+    return file === home || file.startsWith(`${home}/`) ? `~${file.slice(home.length)}` : file;
+}
+function resolveTypedPath(value, cwd) {
+    const expanded = value === '~' ? homedir() : value.startsWith('~/') ? join(homedir(), value.slice(2)) : value;
+    return resolve(cwd, expanded);
+}
+class FileReviewPicker {
+    candidates;
+    cwd;
+    onChoose;
+    close;
+    notify;
+    focused = false;
+    input = new Input();
+    list = new SelectList([], MAX_VISIBLE_ROWS, getSelectListTheme());
+    constructor(candidates, cwd, onChoose, close, notify) {
+        this.candidates = candidates;
+        this.cwd = cwd;
+        this.onChoose = onChoose;
+        this.close = close;
+        this.notify = notify;
+        this.input.onEscape = close;
+        this.input.onSubmit = () => this.chooseSelected();
+        this.refreshList();
+    }
+    render(width) {
+        this.input.focused = this.focused;
+        const inputWidth = Math.max(1, width - 8);
+        return [
+            'Review a file named in this transcript',
+            ...this.input.render(inputWidth).map((line) => `Path: ${line}`),
+            ...this.list.render(width),
+        ];
+    }
+    handleInput(data) {
+        const kb = getKeybindings();
+        if (kb.matches(data, 'tui.select.up') || kb.matches(data, 'tui.select.down')) {
+            this.list.handleInput(data);
+            return;
+        }
+        if (kb.matches(data, 'tui.select.confirm') || data === '\n') {
+            this.chooseSelected();
+            return;
+        }
+        const before = this.input.getValue();
+        this.input.handleInput(data);
+        if (this.input.getValue() !== before)
+            this.refreshList();
+    }
+    invalidate() {
+        this.input.invalidate();
+        this.list.invalidate();
+    }
+    refreshList() {
+        const typed = this.input.getValue();
+        const query = typed.toLowerCase();
+        const matches = this.candidates.filter((file) => {
+            const label = labelForPath(file, this.cwd).toLowerCase();
+            return query === '' || label.includes(query) || file.toLowerCase().includes(query);
+        });
+        const typedPath = typed === '' ? undefined : resolveTypedPath(typed, this.cwd);
+        const hasExactCandidate = typedPath !== undefined && this.candidates.some((file) => file === typedPath);
+        // Matches first: typing is primarily a filter, so Enter picks the best
+        // visible match. The free-typed path is the escape hatch and sits last —
+        // it is selected by default only when nothing matches.
+        const items = [
+            // No description: the label already IS the path, and a detail column
+            // repeating it just spends width twice on the same string.
+            ...matches.map((file) => ({ value: file, label: labelForPath(file, this.cwd) })),
+            ...(typedPath !== undefined && !hasExactCandidate
+                ? [{ value: typedPath, label: `use ${JSON.stringify(typed)}`, description: typedPath }]
+                : []),
+        ];
+        this.list = new SelectList(items, MAX_VISIBLE_ROWS, getSelectListTheme());
+        this.list.onSelect = () => this.chooseSelected();
+        this.list.onCancel = this.close;
+    }
+    chooseSelected() {
+        const typed = this.input.getValue();
+        const item = this.list.getSelectedItem();
+        const picked = item?.value ?? typed;
+        if (picked === '')
+            return;
+        const file = resolveTypedPath(picked, this.cwd);
+        const check = checkReviewableFile(file);
+        if (!check.ok) {
+            this.notify(check.reason);
+            return;
+        }
+        this.close();
+        this.onChoose(file);
+    }
+}
+export function buildFileReviewPicker(candidates, cwd, onChoose, close, notify) {
+    const picker = new FileReviewPicker(candidates, cwd, onChoose, close, notify);
+    return { component: picker, focus: picker };
+}
+function parseOutcome(path, notify) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return { kind: 'cancel' };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        notify('File review result was invalid');
+        return { kind: 'cancel' };
+    }
+    if (typeof raw !== 'object' || raw === null || !('kind' in raw)) {
+        notify('File review result was invalid');
+        return { kind: 'cancel' };
+    }
+    const result = raw;
+    if (result.kind === 'cancel')
+        return { kind: 'cancel' };
+    if ((result.kind === 'insert' || result.kind === 'copy') && typeof result.text === 'string') {
+        return { kind: result.kind, text: result.text };
+    }
+    notify('File review result was invalid');
+    return { kind: 'cancel' };
+}
+export function launchFileReview(file, cwd, opts) {
+    let dir;
+    try {
+        dir = mkdtempSync(join(tmpdir(), 'crtr-review-'));
+    }
+    catch (err) {
+        opts.onNotice(`Could not prepare file review: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const result = join(dir, 'result.json');
+    // Run the humanloop CLI we depend on, not whatever `hl` is first on PATH: a global hl
+    // older than our exact pin has no `review file` leaf and the popup dies on an unknown command.
+    const hlCli = fileURLToPath(import.meta.resolve('@crouton-kit/humanloop/cli'));
+    const cmd = `cd ${shellQuote(cwd)} && exec ${shellQuote(process.execPath)} ${shellQuote(hlCli)} review file --path ${shellQuote(file)} --cwd ${shellQuote(cwd)} --result ${shellQuote(result)}`;
+    try {
+        execFile('tmux', ['display-popup', '-E', '-T', ' file review ', '-w', '90%', '-h', '85%', ...surfaceTmuxStyleArgs(), cmd], (err) => {
+            try {
+                if (err && !existsSync(result)) {
+                    opts.onNotice(`File review did not run: ${err.message}`);
+                    opts.onDone({ kind: 'cancel' });
+                    return;
+                }
+                const outcome = parseOutcome(result, opts.onNotice);
+                opts.onDone(outcome);
+            }
+            catch (err) {
+                opts.onNotice(`Could not finish file review: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                rmSync(dir, { recursive: true, force: true });
+            }
+        });
+    }
+    catch (err) {
+        rmSync(dir, { recursive: true, force: true });
+        opts.onNotice(`Could not open file review: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export { extractFilePaths };

package/dist/clients/attach/overlays/graph.d.ts

@@ -0,0 +1,76 @@
+import { type Component, type TUI } from '@earendil-works/pi-tui';
+import { type BindingResolution, type BindingId } from '../../../core/keybindings/index.js';
+import type { CanvasSource } from '../../../core/canvas/source.js';
+import type { ClientRole } from '../../../core/runtime/broker-protocol.js';
+import type { AttachPalette } from '../config.js';
+export declare class GraphOverlay implements Component {
+    private readonly tui;
+    private readonly self;
+    private readonly getAsks;
+    private readonly palette;
+    private bindings;
+    private readonly source;
+    private readonly role;
+    private readonly onRefreshFailure;
+    private readonly onNotice;
+    private handle;
+    /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
+     *  both override the default activity-driven policy and survive open/close. */
+    private readonly userExpanded;
+    private readonly userCollapsed;
+    private readonly folds;
+    /** Cursor as a node id (indices shift as topology changes). */
+    private cursorId;
+    /** Viewport scroll offset (row index of the top visible tree row). */
+    private scrollTop;
+    /** Transient close confirmation gate. */
+    private pendingConfirm;
+    private snapshot;
+    private snapshotSeq;
+    /** True when `source` is a `RemoteCanvasSource` — gates every local disk/
+     *  SQLite adornment (tokens, activity, fault, attach, focus) to a safe
+     *  default and makes Enter/r/m/x no-op instead of shelling local lifecycle
+     *  commands against a remote graph row. See the file header. */
+    private readonly remote;
+    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>, palette: AttachPalette, bindings: BindingResolution<BindingId>, source: CanvasSource, role?: ClientRole, onRefreshFailure?: (cause?: unknown) => void, onNotice?: (message: string) => void);
+    /** The tmux-focus set for `isAttached`, fetched via crtrd (was nav-model's
+     *  focusedNodeIds → listFocuses db read). Empty for a remote source (a remote
+     *  node id may collide with a local focus row); a failed API call degrades to
+     *  empty rather than throwing the whole snapshot. */
+    private fetchFocused;
+    setBindings(bindings: BindingResolution<BindingId>): void;
+    private matches;
+    private hint;
+    /** Compose footer hints in priority order, dropping WHOLE entries that would
+     *  overflow `budget` visible columns rather than letting the border mid-clip
+     *  the tail — so the prioritized head (dismiss + remapped local actions) stays
+     *  discoverable even in a narrow overlay. */
+    private fitHints;
+    isOpen(): boolean;
+    open(): void;
+    close(): void;
+    toggle(): void;
+    /** Repaint if shown (the low-rate ask poll calls this). */
+    refresh(): void;
+    invalidate(): void;
+    private buildSnapshot;
+    private renderSnapshotRow;
+    render(width: number): string[];
+    /** A top/bottom border row: `<lc>─ <label> ────<rc>`, frame in the theme border
+     *  color, the label keeping its own styling. The label is visible-truncated to
+     *  the available span so a long label (a narrow pane, or a long `kill <name>?`
+     *  confirm) never spills past the corner. */
+    private borderRow;
+    handleInput(data: string): void;
+    private dispatch;
+    /** Focus node `id` from the overlay by shelling `crtr surface node focus <id> --pane <here>`.
+     *  Under the one-viewer-per-node model `--pane` is the ANCHOR to open beside: if
+     *  `id` has no viewer yet a fresh one splits beside this pane; if it already has
+     *  one, that viewer is navigated in place (this pane is left as-is). We pass
+     *  TMUX_PANE explicitly so the anchor is THIS pane even if env resolution differs. */
+    private focusTarget;
+    /** Revive is deliberate and separate from Enter's inspect-or-focus behavior.
+     * After the broker reports ready, focus opens its live attach viewer. */
+    private reviveTarget;
+    private shellCrtr;
+}