@crouton-kit/crouter 0.3.78 → 0.3.80

package/dist/clients/attach/auth-pickers.d.ts

@@ -1,17 +1,5 @@
 import type { TUI } from '@earendil-works/pi-tui';
 import type { Picker, PickerControls } from './pickers.js';
-/** A compact auth summary for a provider — used by non-picker surfaces (e.g.
- *  the `crtr sys setup` login tab) to show which providers are already
- *  configured without mounting the full selector. */
-export interface ProviderAuthSummary {
-    id: string;
-    name: string;
-    configured: boolean;
-}
-/** Summarize which providers have a stored credential in `agentDir`'s auth.json.
- *  Mirrors the OAuth selector's provider list; `configured` is true when the
- *  provider has an explicit stored credential (OAuth token or API key). */
-export declare function summarizeProviderAuth(agentDir: string): ProviderAuthSummary[];
 /** `/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.
  *  Returns a Picker (OAuthSelectorComponent as the overlay). */

package/dist/clients/attach/auth-pickers.js

@@ -10,6 +10,8 @@
 import { join } from 'node:path';
 import { execFile } from 'node:child_process';
 import { AuthStorage, ModelRegistry, OAuthSelectorComponent, LoginDialogComponent, } from '@earendil-works/pi-coding-agent';
+import { loginAnthropic, loginOpenAICodex } from '@earendil-works/pi-ai/oauth';
+import { ANTHROPIC_PROVIDER_ID, commitManagedLogin, isManagedProvider, readSubscriptionPool, removeManagedProvider, } from '../../core/subscription-state.js';
 /** Build an AuthStorage + ModelRegistry from the broker's agentDir (or pi's
  *  default). Both point at the SAME auth.json the broker uses — the viewer and
  *  broker share the filesystem (tmux-local invariant). */
@@ -47,17 +49,6 @@ function buildProviderList(authStorage, registry) {
     }
     return providers;
 }
-/** Summarize which providers have a stored credential in `agentDir`'s auth.json.
- *  Mirrors the OAuth selector's provider list; `configured` is true when the
- *  provider has an explicit stored credential (OAuth token or API key). */
-export function summarizeProviderAuth(agentDir) {
-    const { authStorage, registry } = buildLocalAuth(agentDir);
-    return buildProviderList(authStorage, registry).map((p) => ({
-        id: p.id,
-        name: p.name,
-        configured: authStorage.get(p.id) !== undefined,
-    }));
-}
 /** 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';
@@ -112,6 +103,52 @@ export function buildLoginPicker(tui, agentDir, onAuthReloaded, notify, controls
         // 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);
+        if (isManagedProvider(providerId)) {
+            // Managed provider (anthropic / openai-codex): drive pi's OAuth flow ourselves so we hold
+            // the credential, then persist it through the coordinated writer (commitManagedLogin ->
+            // commitDefaultIdentity for the default slot) rather than authStorage.login(). That keeps
+            // auth.json + the rotation pool identity in lockstep and runs the account-uniqueness gate
+            // the raw path skipped. /login here manages only the DEFAULT slot (label === providerId).
+            const runLogin = providerId === ANTHROPIC_PROVIDER_ID ? loginAnthropic : loginOpenAICodex;
+            // Snapshot the default slot's rate-limit timestamp BEFORE OAuth begins: a strictly newer
+            // concurrent 429 recorded during the login must survive a same-account re-login.
+            const defaultLastRateLimitedAt = readSubscriptionPool(providerId).find((entry) => entry.label === providerId)?.lastRateLimitedAt ?? 0;
+            runLogin({
+                onAuth: (info) => {
+                    dialog.showAuth(info.url, info.instructions);
+                    openBrowser(info.url);
+                },
+                onPrompt: (prompt) => dialog.showPrompt(prompt.message, prompt.placeholder),
+                onProgress: (message) => {
+                    dialog.showProgress(message);
+                },
+                onManualCodeInput: () => dialog.showManualInput('Paste the code or URL:'),
+            })
+                .then((credential) => {
+                if (settled)
+                    return;
+                const accountId = typeof credential.accountId === 'string' && credential.accountId.trim()
+                    ? credential.accountId.trim()
+                    : undefined;
+                commitManagedLogin(providerId, providerId, {
+                    refresh: credential.refresh,
+                    access: credential.access,
+                    expires: credential.expires,
+                    accountId,
+                    defaultLastRateLimitedAt,
+                });
+                notify(`Logged in to ${provider.name}`);
+                onAuthReloaded();
+                finish();
+            })
+                .catch((err) => {
+                if (err?.name !== 'AbortError') {
+                    notify(`Login error: ${String(err?.message ?? err)}`);
+                }
+                finish();
+            });
+            return;
+        }
         if (provider.authType === 'oauth') {
             const isKnownOAuth = authStorage.getOAuthProviders().some((p) => p.id === providerId);
             if (!isKnownOAuth) {
@@ -195,10 +232,22 @@ export function buildLogoutPicker(agentDir, onAuthReloaded, notify, close) {
     const getAuthStatus = (id) => authStorage.getAuthStatus(id);
     const onSelect = (providerId) => {
         const provider = providers.find((p) => p.id === providerId);
-        authStorage.logout(providerId);
-        close();
-        notify(`Logged out of ${provider?.name ?? providerId}`);
-        onAuthReloaded();
+        try {
+            // Managed providers tear down the WHOLE provider (every rotation account + the auth.json
+            // default record) through the coordinated service, never a raw authStorage.logout() that
+            // would strip only auth.json and orphan the pool.
+            if (isManagedProvider(providerId))
+                removeManagedProvider(providerId);
+            else
+                authStorage.logout(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', authStorage, providers, onSelect, () => close(), getAuthStatus);
     return { component, focus: component };

package/dist/clients/attach/chat-view.d.ts

@@ -23,6 +23,10 @@ export interface ChatViewOptions {
     /** Theme palette for the activity spinner / dim status / error lines. Absent →
      *  the module defaults (faint + ANSI red) are used. */
     palette?: AttachPalette;
+    /** Pre-colored banner lines pinned as the FIRST child of the chat container,
+     *  above history (the crouton wordmark). Sits at the very top of the transcript
+     *  and scrolls up into scrollback as the chat grows. Absent → no banner. */
+    banner?: ReadonlyArray<string>;
 }
 export declare class ChatView {
     private readonly tui;

package/dist/clients/attach/chat-view.js

@@ -142,6 +142,16 @@ export class ChatView {
         this.spinnerStyle = opts.palette?.active ?? defaultSpinnerStyle;
         this.dimStyle = opts.palette?.muted ?? defaultDimStyle;
         this.errorStyle = opts.palette?.error ?? defaultErrorStyle;
+        // Banner sits above history and OUTSIDE it, so resetChat() (which clears only
+        // historyContainer) never wipes it — it persists across every welcome snapshot.
+        if (opts.banner && opts.banner.length > 0) {
+            const b = new Container();
+            b.addChild(new Spacer(1));
+            for (const line of opts.banner)
+                b.addChild(new Text(line, 1, 0));
+            b.addChild(new Spacer(1));
+            this.container.addChild(b);
+        }
         this.container.addChild(this.historyContainer);
         this.container.addChild(this.statusContainer);
     }

package/dist/clients/attach/graph-overlay.d.ts

@@ -1,4 +1,5 @@
 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 { AttachPalette } from './config-load.js';
 export declare class GraphOverlay implements Component {
@@ -6,6 +7,7 @@ export declare class GraphOverlay implements Component {
     private readonly self;
     private readonly getAsks;
     private readonly palette;
+    private bindings;
     private readonly source;
     private handle;
     /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
@@ -17,7 +19,7 @@ export declare class GraphOverlay implements Component {
     private cursorId;
     /** Viewport scroll offset (row index of the top visible tree row). */
     private scrollTop;
-    /** Transient y/n confirm gate (kill). */
+    /** Transient close confirmation gate. */
     private pendingConfirm;
     private snapshot;
     private snapshotSeq;
@@ -26,7 +28,15 @@ export declare class GraphOverlay implements Component {
      *  default and makes Enter/m/x no-op instead of shelling local focus/kill
      *  commands against a remote graph row. See the file header. */
     private readonly remote;
-    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>, palette: AttachPalette, source?: CanvasSource);
+    constructor(tui: TUI, self: string, getAsks: () => Record<string, number>, palette: AttachPalette, bindings: BindingResolution<BindingId>, source?: CanvasSource);
+    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;

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

@@ -1,4 +1,4 @@
-// graph-overlay.ts — the alt+g GRAPH navigator overlay for `crtr surface attach` (Unit Q).
+// graph-overlay.ts — the configurable GRAPH navigator overlay for `crtr surface attach`.
 //
 // Native reimplementation of canvas-nav.ts's GRAPH modal as a pi-tui OVERLAY
 // (the viewer has no pi extension host). `tui.showOverlay(this, …)` mounts this
@@ -6,12 +6,9 @@
 // CAPTURES keyboard focus (mirrors extension-dialogs.ts);
 // `OverlayHandle.hide()` tears it down and restores focus to the editor. While
 // shown, every key routes to handleInput() — a fold-aware NERDTree of the
-// active CanvasSource subscription graph with the canvas-nav keymap:
-//   j/k move · h/l fold/ascend-descend · g/G top/bottom · ↵ focus (swap into
-//   this pane) · m focus manager · x kill (y/n confirm) · esc close.
-// `e` is a tmux-menu prefixBind, not a GRAPH key, so it is swallowed (per
-// canvas-nav). Model/render uses the CanvasSource snapshot built for this
-// overlay; keys are decoded with pi-tui's canonical matchesKey (kitty/CSI-u aware).
+// active CanvasSource subscription graph. Actions and footer hints resolve from
+// the crouter binding catalog; input is decoded with pi-tui's canonical matcher
+// (kitty/CSI-u aware).
 //
 // Enter/m/x SHELL `crtr` out-of-process (node focus / node lifecycle close) — the viewer
 // itself never spawns pi or opens a session (the §0 one-writer invariant). It
@@ -30,6 +27,7 @@
 // graph structure + node metadata ONLY.
 import { execFile } from 'node:child_process';
 import { matchesKey, truncateToWidth } from '@earendil-works/pi-tui';
+import { formatBinding, matchesPiTuiInput, } from '../../core/keybindings/index.js';
 import { fullName } from '../../core/canvas/index.js';
 import { activeFaultForDisplay } from '../../core/canvas/render.js';
 import { readFault } from '../../core/runtime/fault.js';
@@ -43,18 +41,34 @@ import { beginFrame, navLabel, nodeGlyph, tokensCell, cycleBadge, askBadge, acti
 // clipped. margin keeps it off the screen edges.
 const HEIGHT_PCT = 0.72;
 const OVERLAY_OPTIONS = { anchor: 'center', width: '72%', minWidth: 48, maxHeight: '72%', margin: 1 };
-// Viewer-specific hint: nav-model's shared GRAPH_HINT advertises "e expand",
-// but that key is the tmux pane-expand prefix-bind canvas-nav installs in its
-// host pane — the attach overlay has no such bind and swallows `e`, so the key
-// would do nothing here. Drop it.
-const GRAPH_HINT = `${DIM}jk move · hl fold · ↵ focus · x kill · m mgr · esc${RESET}`;
-// REMOTE mode drops focus/kill/mgr — Enter/m/x no-op there (see the file header).
-const GRAPH_HINT_REMOTE = `${DIM}jk move · hl fold · esc${RESET}`;
+// The footer is width-budgeted (fitHints drops WHOLE trailing entries that
+// won't fit rather than mid-clipping the tail). List the keys a user most needs
+// to discover first — dismiss (the only way out) then the remapped local
+// actions — so they survive at the narrowest overlay width; routine navigation
+// trails and is the first to be dropped.
+const GRAPH_PRIMARY_LOCAL_HINTS = [
+    ['crtr.graph.dismiss', 'dismiss'],
+    ['crtr.graph.focus', 'focus'],
+    ['crtr.graph.close-subtree', 'close'],
+    ['crtr.graph.focus-manager', 'manager'],
+];
+const GRAPH_PRIMARY_REMOTE_HINTS = [
+    ['crtr.graph.dismiss', 'dismiss'],
+];
+const GRAPH_NAV_HINTS = [
+    ['crtr.graph.down', 'down'],
+    ['crtr.graph.up', 'up'],
+    ['crtr.graph.first', 'first'],
+    ['crtr.graph.last', 'last'],
+    ['crtr.graph.collapse-or-manager', 'fold/manager'],
+    ['crtr.graph.expand-or-child', 'expand/child'],
+];
 export class GraphOverlay {
     tui;
     self;
     getAsks;
     palette;
+    bindings;
     source;
     handle;
     /** Manual fold OVERRIDES (h collapses → userCollapsed, l expands → userExpanded);
@@ -66,7 +80,7 @@ export class GraphOverlay {
     cursorId;
     /** Viewport scroll offset (row index of the top visible tree row). */
     scrollTop = 0;
-    /** Transient y/n confirm gate (kill). */
+    /** Transient close confirmation gate. */
     pendingConfirm;
     snapshot;
     snapshotSeq = 0;
@@ -75,14 +89,43 @@ export class GraphOverlay {
      *  default and makes Enter/m/x no-op instead of shelling local focus/kill
      *  commands against a remote graph row. See the file header. */
     remote;
-    constructor(tui, self, getAsks, palette, source = localCanvasSource) {
+    constructor(tui, self, getAsks, palette, bindings, source = localCanvasSource) {
         this.tui = tui;
         this.self = self;
         this.getAsks = getAsks;
         this.palette = palette;
+        this.bindings = bindings;
         this.source = source;
         this.remote = source instanceof RemoteCanvasSource;
     }
+    setBindings(bindings) {
+        this.bindings = bindings;
+        if (this.handle !== undefined)
+            this.tui.requestRender();
+    }
+    matches(id, data) {
+        return matchesPiTuiInput(this.bindings, id, data, (input, gesture) => matchesKey(input, gesture));
+    }
+    hint(entries) {
+        return entries.flatMap(([id, label]) => this.bindings.gestures(id).length === 0 ? [] : [`${formatBinding(this.bindings, id)} ${label}`]);
+    }
+    /** 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. */
+    fitHints(entries, budget) {
+        const SEP = 3; // visible width of ' · '
+        const out = [];
+        let used = 0;
+        for (const piece of this.hint(entries)) {
+            const add = (out.length === 0 ? 0 : SEP) + visibleWidth(piece);
+            if (used + add > budget)
+                break;
+            out.push(piece);
+            used += add;
+        }
+        return out.join(' · ');
+    }
     isOpen() {
         return this.handle !== undefined;
     }
@@ -341,8 +384,14 @@ export class GraphOverlay {
             ? `${BOLD}⌗ canvas graph${RESET} ${DIM}(${cursorIdx + 1}/${rows.length})${RESET}`
             : `${BOLD}⌗ canvas graph${RESET} ${DIM}(loading)${RESET}`;
         const hint = this.pendingConfirm !== undefined
-            ? `${YELLOW}${this.pendingConfirm.label} ${BOLD}y/n${RESET}`
-            : this.remote ? GRAPH_HINT_REMOTE : GRAPH_HINT;
+            ? `${YELLOW}${this.pendingConfirm.label} ${BOLD}${this.hint([
+                ['crtr.graph.confirm.accept', 'accept'],
+                ['crtr.graph.confirm.cancel', 'cancel'],
+            ]).join(' · ')}${RESET}`
+            : `${DIM}${this.fitHints([
+                ...(this.remote ? GRAPH_PRIMARY_REMOTE_HINTS : GRAPH_PRIMARY_LOCAL_HINTS),
+                ...GRAPH_NAV_HINTS,
+            ], Math.max(1, width - 5))}${RESET}`; // budget matches borderRow's span
         // Frame the panel: title in the top border, hint in the bottom border, tree
         // rows boxed with themed side bars (truncate/pad to the inner width so the
         // right edge stays flush and opaque).
@@ -385,18 +434,19 @@ export class GraphOverlay {
     dispatch(data) {
         // y/n confirm gate takes precedence over everything.
         if (this.pendingConfirm !== undefined) {
-            if (matchesKey(data, 'y')) {
+            if (this.matches('crtr.graph.confirm.accept', data)) {
                 const act = this.pendingConfirm.action;
                 this.pendingConfirm = undefined;
                 act();
             }
             else {
-                this.pendingConfirm = undefined; // any other key cancels
+                // Preserve GRAPH's modal fallback: any non-accept key cancels close.
+                this.pendingConfirm = undefined;
             }
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'escape')) {
+        if (this.matches('crtr.graph.dismiss', data)) {
             this.close();
             return;
         }
@@ -427,29 +477,29 @@ export class GraphOverlay {
             }
             return idx;
         };
-        if (matchesKey(data, 'j')) {
+        if (this.matches('crtr.graph.down', data)) {
             idx = step(idx, 1);
             this.cursorId = rows[idx]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'k')) {
+        if (this.matches('crtr.graph.up', data)) {
             idx = step(idx, -1);
             this.cursorId = rows[idx]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'g')) {
+        if (this.matches('crtr.graph.first', data)) {
             this.cursorId = rows[edge(1)]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'shift+g')) {
+        if (this.matches('crtr.graph.last', data)) {
             this.cursorId = rows[edge(-1)]?.id ?? this.cursorId;
             this.tui.requestRender();
             return;
         }
-        if (matchesKey(data, 'h')) {
+        if (this.matches('crtr.graph.collapse-or-manager', data)) {
             if (cur !== undefined && cur.hasKids && !cur.collapsed) {
                 this.userCollapsed.add(cur.id);
                 this.userExpanded.delete(cur.id);
@@ -463,7 +513,7 @@ export class GraphOverlay {
             }
             return;
         }
-        if (matchesKey(data, 'l')) {
+        if (this.matches('crtr.graph.expand-or-child', data)) {
             if (cur !== undefined && cur.collapsed && cur.hasKids) {
                 this.userExpanded.add(cur.id);
                 this.userCollapsed.delete(cur.id);
@@ -477,12 +527,12 @@ export class GraphOverlay {
             }
             return;
         }
-        // Enter/m/x drive local lifecycle/focus (`crtr node focus` / `crtr node
+        // Focus/manager/close actions drive local lifecycle/focus (`crtr node focus` / `crtr node
         // lifecycle close`) against `this.cursorId` — a REMOTE graph row's id has no
         // relationship to this machine's canvas.db (or, worse, collides with one
         // that does), so all three no-op in remote mode instead of shelling a local
-        // mutation command against a remote id. GRAPH_HINT_REMOTE drops their hints.
-        if (matchesKey(data, 'enter')) {
+        // mutation command against a remote id. Their hints are omitted remotely.
+        if (this.matches('crtr.graph.focus', data)) {
             if (this.remote)
                 return;
             if (this.cursorId !== undefined)
@@ -490,7 +540,7 @@ export class GraphOverlay {
             this.close();
             return;
         }
-        if (matchesKey(data, 'm')) {
+        if (this.matches('crtr.graph.focus-manager', data)) {
             if (this.remote)
                 return;
             const mgr = snapshot?.managerOf.get(this.self);
@@ -500,7 +550,7 @@ export class GraphOverlay {
             }
             return;
         }
-        if (matchesKey(data, 'x')) {
+        if (this.matches('crtr.graph.close-subtree', data)) {
             if (this.remote)
                 return;
             const target = this.cursorId ?? this.self;
@@ -510,7 +560,7 @@ export class GraphOverlay {
             this.tui.requestRender();
             return;
         }
-        // Modal: swallow everything else (incl. the `e` tmux-menu bind) so a stray
+        // Modal: swallow everything else so a stray
         // key never reaches the editor underneath.
     }
     // -------------------------------------------------------------------------

package/dist/clients/attach/input-controller.d.ts

@@ -83,6 +83,13 @@ export declare class InputController {
     private state;
     /** Timestamp of the last lone Esc, for double-tap → tree detection (0 = none). */
     private lastEscapeAt;
+    /** Pasted-image registry: placeholder ordinal → temp-file path. The editor
+     *  shows a clean `[Image #N]` token instead of the ugly temp path; on submit
+     *  each token is expanded back to its path so the agent reads it off disk.
+     *  Cleared whenever the editor is emptied (send / clear). */
+    private pastedImages;
+    /** Monotonic paste counter — the `N` in `[Image #N]`. */
+    private pasteSeq;
     constructor(tui: TUI, editor: CustomEditor, keybindings: KeybindingsManager, hooks: InputControllerHooks);
     /** Central choke point for every command frame the input layer emits (direct
      *  keybindings, emitDrive, and the slash-command/picker `send` sink). Local
@@ -137,6 +144,13 @@ export declare class InputController {
     openAuthPicker(build: (controls: PickerControls) => Picker): void;
     private handleSubmit;
     private handleFollowUp;
+    /** Replace every `[Image #N]` token with the temp-file path of the image the
+     *  user pasted, so the agent receives a readable path even though the editor
+     *  only ever showed the clean placeholder. Unknown ordinals are left as-is. */
+    private expandImagePlaceholders;
+    /** Drop the pasted-image registry and reset the ordinal counter — called once
+     *  a submit has consumed the editor text. */
+    private clearPastedImages;
     /** Ctrl+G / app.editor.external — open the current editor text in $VISUAL/$EDITOR
      *  and load the saved result back. Ported from pi's `openExternalEditor`: stop
      *  the TUI to release the terminal, run the editor with inherited stdio, and on
@@ -154,5 +168,10 @@ export declare class InputController {
      *  images intact for the user to trim, never a socket-destroying overflow. */
     private emitDrive;
     private handlePaste;
+    /** Register an image path in the paste registry and splice a clean `[Image #N]`
+     *  token into the editor at the caret instead of the raw path. On submit the
+     *  token is expanded back to the path (see expandImagePlaceholders), so the
+     *  agent reads the image off disk. Shared by clipboard paste and drag-drop. */
+    private attachImage;
     private notify;
 }

package/dist/clients/attach/input-controller.js

@@ -77,6 +77,13 @@ export class InputController {
     state;
     /** Timestamp of the last lone Esc, for double-tap → tree detection (0 = none). */
     lastEscapeAt = 0;
+    /** Pasted-image registry: placeholder ordinal → temp-file path. The editor
+     *  shows a clean `[Image #N]` token instead of the ugly temp path; on submit
+     *  each token is expanded back to its path so the agent reads it off disk.
+     *  Cleared whenever the editor is emptied (send / clear). */
+    pastedImages = new Map();
+    /** Monotonic paste counter — the `N` in `[Image #N]`. */
+    pasteSeq = 0;
     constructor(tui, editor, keybindings, hooks) {
         this.tui = tui;
         this.editor = editor;
@@ -164,6 +171,14 @@ export class InputController {
         this.editor.onPasteImage = () => {
             void this.handlePaste();
         };
+        // A file DRAGGED into the pane arrives as bracketed-paste text (its path), not
+        // an image event — TitledEditor recognizes an image path and routes it here so
+        // it becomes an `[Image #N]` token just like a Ctrl+V paste.
+        const dropEditor = this.editor;
+        dropEditor.onPasteImagePath = (path) => {
+            this.attachImage(path);
+            return true;
+        };
         // Keyboard shortcuts that map 1:1 to a frame needing no engine-side data.
         this.editor.onAction('app.session.new', () => this.emitCommand({ type: 'new_session' }));
         this.editor.onAction('app.model.cycleForward', () => this.emitCommand({ type: 'cycle_model', direction: 'forward' }));
@@ -385,23 +400,43 @@ export class InputController {
         // running turn instead of queueing a fresh prompt. `isStreaming` is the
         // broker snapshot's busy signal; the broker routes `steer` → session.steer()
         // and `prompt` → session.prompt(). Idle / no state yet → prompt (safe default).
+        const expanded = this.expandImagePlaceholders(trimmed);
         const busy = this.state?.isStreaming === true;
         const frame = busy
-            ? { type: 'steer', text: trimmed }
-            : { type: 'prompt', text: trimmed };
+            ? { type: 'steer', text: expanded }
+            : { type: 'prompt', text: expanded };
         if (!this.emitDrive(frame))
             return; // too large — keep editor to trim
         this.editor.addToHistory(trimmed);
         this.editor.setText('');
+        this.clearPastedImages();
     }
     handleFollowUp() {
         const text = this.editor.getText().trim();
         if (!text)
             return;
-        if (!this.emitDrive({ type: 'follow_up', text }))
+        if (!this.emitDrive({ type: 'follow_up', text: this.expandImagePlaceholders(text) }))
             return;
         this.editor.addToHistory(text);
         this.editor.setText('');
+        this.clearPastedImages();
+    }
+    /** Replace every `[Image #N]` token with the temp-file path of the image the
+     *  user pasted, so the agent receives a readable path even though the editor
+     *  only ever showed the clean placeholder. Unknown ordinals are left as-is. */
+    expandImagePlaceholders(text) {
+        if (this.pastedImages.size === 0)
+            return text;
+        return text.replace(/\[Image #(\d+)\]/g, (match, digits) => {
+            const path = this.pastedImages.get(Number(digits));
+            return path ?? match;
+        });
+    }
+    /** Drop the pasted-image registry and reset the ordinal counter — called once
+     *  a submit has consumed the editor text. */
+    clearPastedImages() {
+        this.pastedImages.clear();
+        this.pasteSeq = 0;
     }
     /** Ctrl+G / app.editor.external — open the current editor text in $VISUAL/$EDITOR
      *  and load the saved result back. Ported from pi's `openExternalEditor`: stop
@@ -517,20 +552,29 @@ export class InputController {
                 this.notify(result.note ?? 'Image not pasted');
                 return;
             }
-            // Persist to a temp file and splice the PATH into the editor at the caret,
-            // so the agent reads the image off disk instead of relying on inline base64
-            // the viewer can't render.
+            // Persist to a temp file (the agent reads the image off disk instead of
+            // relying on inline base64 the viewer can't render), then attach it as an
+            // `[Image #N]` token (see attachImage).
             const path = writeClipboardImageToFile(result.image);
-            const cur = this.editor.getText();
-            const sep = cur && !/\s$/.test(cur) ? ' ' : '';
-            this.editor.insertTextAtCursor(`${sep}${path} `);
-            this.notify(result.note ? `Image saved (${result.note}) — path inserted` : 'Image saved — path inserted');
-            this.tui.requestRender();
+            this.attachImage(path, result.note);
         }
         catch {
             this.notify('Could not read the clipboard image');
         }
     }
+    /** Register an image path in the paste registry and splice a clean `[Image #N]`
+     *  token into the editor at the caret instead of the raw path. On submit the
+     *  token is expanded back to the path (see expandImagePlaceholders), so the
+     *  agent reads the image off disk. Shared by clipboard paste and drag-drop. */
+    attachImage(path, note) {
+        const n = ++this.pasteSeq;
+        this.pastedImages.set(n, path);
+        const cur = this.editor.getText();
+        const sep = cur && !/\s$/.test(cur) ? ' ' : '';
+        this.editor.insertTextAtCursor(`${sep}[Image #${n}] `);
+        this.notify(note ? `Image #${n} attached (${note})` : `Image #${n} attached`);
+        this.tui.requestRender();
+    }
     notify(message) {
         this.hooks.onNotice?.(message);
     }

package/dist/clients/attach/titled-editor.d.ts

@@ -26,6 +26,13 @@ export declare function thinkingTitleStyle(level: string | undefined, fallback:
  *  regression test. */
 export declare function composeTopBorder(width: number, title: string, info: string, titleStyle: (s: string) => string, borderColor: (s: string) => string): string;
 export declare function outlineCursorLine(line: string): string | undefined;
+/** Recognize a single input chunk as a filesystem path to an image file — how a
+ *  terminal delivers a file DRAGGED into the pane (the escaped path pasted in
+ *  bulk, optionally wrapped in bracketed-paste markers). Returns the resolved
+ *  path, or null when the chunk isn't a lone image path (normal typing, multi-
+ *  line text, a non-image path, or a path that doesn't point at a real file).
+ *  Conservative on purpose: it must never transform ordinary typed input. */
+export declare function detectDroppedImagePath(data: string): string | null;
 export declare class TitledEditor extends CustomEditor {
     /** crtr's OWN keybindings manager — the same one CustomEditor matches `app.*`
      *  against. We keep a reference so `handleInput` can resolve the newline chord
@@ -43,6 +50,20 @@ export declare class TitledEditor extends CustomEditor {
      *  override, so matching the chord here makes the newline behavior independent
      *  of cross-instance keybinding mirroring. Skipped while the autocomplete popup
      *  is open so Enter-to-confirm keeps working. */
+    /** Set by the input controller: called when a bulk input chunk is recognized
+     *  as a filesystem path to an image file (a file DRAGGED into the pane, which
+     *  the terminal delivers as bracketed-paste TEXT, not an image event). Returns
+     *  true when it consumed the drop, so the raw path is never inserted as text. */
+    onPasteImagePath?: (path: string) => boolean;
+    /** Width of an `[Image #N]` token sitting immediately before the cursor on the
+     *  current line, or 0 when the cursor isn't at the end of such a token — used to
+     *  delete/skip the token atomically. The token's separating space is a normal,
+     *  reachable character, deliberately NOT part of the atom. */
+    private imageTokenWidthBeforeCursor;
+    /** Width of an `[Image #N]` token sitting immediately after the cursor on the
+     *  current line, or 0 when the cursor isn't at the start of such a token — used
+     *  to skip the token with the right arrow. */
+    private imageTokenWidthAfterCursor;
     handleInput(data: string): void;
     /** Session-name chip painted into the LEFT of the top border. Empty → plain. */
     title: string;