@north-light/api 0.3.580 → 0.3.588

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,247 @@
+// 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 { CredentialSynchronizationError, ModelRuntime, OAuthSelectorComponent, LoginDialogComponent, } from '@earendil-works/pi-coding-agent';
+import { ApiCredentialStore } from '../../../core/model-auth/api-credential-store.js';
+import { secretsDir } from '../../../core/layout.js';
+import { dialogAuthInteraction } from '../../../core/auth-interaction.js';
+import { isManagedProvider } from '../../../core/managed-providers.js';
+import { daemonManagedLogin } from '../../../core/model-auth/daemon-login.js';
+import { cliClient } from '../../../commands/api-client.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(secretsDir(), 'auth.json');
+    const modelsPath = join(agentDir, 'models.json');
+    const store = new ApiCredentialStore(() => cliClient());
+    let mutationBoundary;
+    const credentials = {
+        read: (providerId) => store.read(providerId),
+        list: () => store.list(),
+        modify: (providerId, fn) => {
+            const enter = mutationBoundary;
+            mutationBoundary = undefined;
+            if (enter !== undefined && !enter())
+                return Promise.reject(new Error('Login cancelled'));
+            return store.modify(providerId, fn);
+        },
+        delete: (providerId) => store.delete(providerId),
+    };
+    const runtime = await ModelRuntime.create({ credentials, modelsPath });
+    return {
+        runtime,
+        authPath,
+        beforeNextCredentialMutation: (callback) => { mutationBoundary = callback; },
+    };
+}
+/** 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, beforeNextCredentialMutation } = 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) => {
+                // ModelRuntime persists the credential before synchronizing its provider
+                // state. A synchronization failure is therefore a successful login with
+                // a refresh warning, not a failed login.
+                if (err instanceof CredentialSynchronizationError) {
+                    notify(`Logged in to ${provider.name}; provider refresh failed: ${err.message}`);
+                    onAuthReloaded();
+                    finish();
+                    return;
+                }
+                // 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 subscriptions sign in through the daemon (RT-LLM-24/45): it runs the
+                // vendor flow and writes the pool account; this dialog only shows the URL or
+                // code and relays Anthropic's pasted code.
+                daemonManagedLogin(cliClient(), providerId, interaction)
+                    .then(() => {
+                    if (settled)
+                        return;
+                    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.
+                beforeNextCredentialMutation(beginCommit);
+                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)
+                    .finally(() => beforeNextCredentialMutation(undefined));
+            }
+            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 cliClient().installCredential(providerId, { kind: 'api_key', api_key: key.trim() });
+                        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.
+                    await cliClient().removeCredential(providerId);
+                    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 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`.
+//
+// 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 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,10 @@
+import type { SurfaceHost } from '../../surfaces/host.js';
+import type { Picker } from './pickers.js';
+import { extractFilePaths } from '../../../core/human/visible-paths.js';
+export declare function buildFileReviewPicker(candidates: readonly string[], cwd: string, onChoose: (file: string) => void, close: () => void, notify: (message: string) => void): Picker;
+/** Open an inline review of a file path, or of a document given as `[[ref]]`. */
+export declare function launchFileReview(host: SurfaceHost, file: string, opts: {
+    originNodeId: string;
+    onNotice: (message: string) => void;
+}): Promise<void>;
+export { extractFilePaths };

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

@@ -0,0 +1,146 @@
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { Input, SelectList, getKeybindings, } from '@earendil-works/pi-tui';
+import { getSelectListTheme } from '@earendil-works/pi-coding-agent';
+import { openReviewWindow } from '../../inbox/review/launch.js';
+import { createReviewClient, ReviewTerminalError, terminalRefusalNotice } from '../../inbox/review/review-client.js';
+import { checkReviewableFile, extractFilePaths } from '../../../core/human/visible-paths.js';
+import { docLinkText } from '../render/doc-links.js';
+const MAX_VISIBLE_ROWS = 12;
+/** A candidate naming a canvas document, as `[[ref]]`. */
+function documentRef(candidate) {
+    const match = /^\[\[([^[\]\n]+)\]\]$/.exec(candidate.trim());
+    return match === null ? undefined : match[1].trim();
+}
+function labelForPath(file, cwd) {
+    const ref = documentRef(file);
+    if (ref !== undefined)
+        return `${docLinkText(ref)}  (document)`;
+    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 or document 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 : documentRef(typed) !== undefined ? typed.trim() : 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;
+        if (documentRef(picked) !== undefined) {
+            this.onChoose(picked);
+            this.close();
+            return;
+        }
+        const file = resolveTypedPath(picked, this.cwd);
+        const check = checkReviewableFile(file);
+        if (!check.ok) {
+            this.notify(check.reason);
+            return;
+        }
+        this.onChoose(file);
+        this.close();
+    }
+}
+export function buildFileReviewPicker(candidates, cwd, onChoose, close, notify) {
+    const picker = new FileReviewPicker(candidates, cwd, onChoose, close, notify);
+    return { component: picker, focus: picker };
+}
+/** Open an inline review of a file path, or of a document given as `[[ref]]`. */
+export async function launchFileReview(host, file, opts) {
+    // The refusal precedes the record creation: a remote viewer can reach neither
+    // the reviewed file nor the companion's pane.
+    if (host.capabilities.remote) {
+        opts.onNotice('The review is unavailable in a remote attach — the file and companion live on the host.');
+        return;
+    }
+    const document = documentRef(file);
+    let review;
+    try {
+        review = await createReviewClient().createInline(document === undefined
+            ? { originNodeId: opts.originNodeId, file }
+            : { originNodeId: opts.originNodeId, document });
+    }
+    catch (err) {
+        opts.onNotice(err instanceof ReviewTerminalError ? terminalRefusalNotice(err) : err instanceof Error ? err.message : String(err));
+        return;
+    }
+    openReviewWindow(host, review);
+}
+export { extractFilePaths };

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

@@ -0,0 +1,83 @@
+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);
+    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;
+    /** Local: ONE `/v1/canvas/graph` read supplies the display rows, both edge
+     *  directions, and the focus set — no enriched node list, no roster call, no
+     *  separate focus query. Remote: unchanged — a remote canvas exposes only the
+     *  per-node `CanvasSource` reads, and its focus set stays empty (a remote node
+     *  id may collide with a local focus row). */
+    private fetchInput;
+    private buildSnapshot;
+    /** Fold state is presentation-only. Reproject the visible DFS from the fully
+     * fetched topology so h/l never cross the daemon boundary. The explicit stack
+     * also keeps a deep graph from consuming the JavaScript call stack. */
+    private projectRows;
+    private repaintFolds;
+    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, in-process: the same decision
+     *  `crtr surface node focus <id> --pane <here>` makes (core/runtime/focus-viewer.ts),
+     *  without paying a cold `crtr` boot before the target's viewer pane even
+     *  spawns. THIS pane is the ANCHOR: if `id` has no viewer yet a fresh one
+     *  splits beside it; if it already has one, that viewer is navigated in place
+     *  (this pane is left as-is). Finished work opens its saved-transcript popup. */
+    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;
+}