@bastani/atomic 0.9.13-alpha.1 → 0.9.13-alpha.3

package/docs/tools.md

@@ -28,11 +28,9 @@ Before writing, Atomic verifies the current file against the tagged snapshot. If
 
 ## `bash` and `bashInterceptor`
 
-The `bash` tool executes shell commands in the session workspace, with optional PTY or background-job handling. When `pty: true` is requested, local execution uses the bundled Rust-backed PTY session so commands see a real terminal, including headless/tool-only and async job calls; if the native PTY package is unavailable, Atomic degrades to normal pipe execution. Set `PI_NO_PTY=1` or `ATOMIC_NO_PTY=1` to force normal pipe execution. Completed foreground results include oh-my-pi-style `timeoutSeconds`, `requestedTimeoutSeconds`, `wallTimeMs`, and non-zero `exitCode` metadata; background jobs use `details.async: { state, jobId, type: "bash" }`, can be polled with `bash({"command":"__atomic_bash_job <id>"})`, can be cancelled with `bash({"command":"__atomic_bash_job_cancel <id>"})`, and preserve overflow output in a temporary `fullOutputPath` when polling output is truncated.
+The `bash` tool executes shell commands in the session workspace, with optional PTY handling. When `pty: true` is requested, local execution uses the bundled Rust-backed PTY session; if the native PTY package is unavailable, Atomic degrades to normal pipe execution. Set `PI_NO_PTY=1` or `ATOMIC_NO_PTY=1` to force normal pipe execution. Foreground results include oh-my-pi-style `timeoutSeconds`, `requestedTimeoutSeconds`, `wallTimeMs`, and non-zero `exitCode` metadata, and preserve overflow output in a temporary `fullOutputPath` when output is truncated.
 
-When a session-managed background bash job completes or fails, Atomic sends an `async-job-result` custom follow-up into the conversation automatically (`display: true`, delivered as a follow-up turn). Small results are inlined, and results whose raw output stays below the persistence threshold remain fully inline even if the formatted follow-up header pushes the message over the preview limit; persisted large results include a preview plus the retained `fullOutputPath` (persisted before the normal polling truncation limit so 12KB–50KB outputs remain recoverable). If the model explicitly polls a completed job with `__atomic_bash_job <id>` before the queued follow-up is delivered, or cancels a job with `__atomic_bash_job_cancel <id>`, Atomic acknowledges the result and suppresses duplicate auto-delivery while keeping the job pollable until normal bounded retention/TTL cleanup. Suppression is tied to the retained job rather than a short timer, so disposed-session jobs cannot later fall back into another session after a long-running command completes. Session delivery attempts are non-blocking across sessions: a live streaming session can defer its own follow-up until the stream boundary without delaying unrelated completed jobs. Session disposal removes that session's pending async delivery handlers; a shared manager remains alive while other live sessions still own active jobs, then cleans up when the last session is disposed. Direct SDK/tool-factory uses only get automatic delivery when they provide an async job manager/delivery handler; otherwise async jobs remain manually pollable.
-
-When explicitly enabled in settings, built-in bash interceptor rules block common shell substitutes for first-class tools (`cat`/`grep`/`find`/in-place `sed`/redirection, etc.) only when the corresponding tool is available. Enabled bash tool calls are also offered to `user_bash` extension handlers before local execution. Atomic checks the original command, the internal-URL-expanded command, configured-prefix forms, `spawnHook`-rewritten commands, and a leading `cd path && command` or `cd path; command`-stripped form only when structured `cwd` was omitted, so interceptors can route commands by effective working directory without overriding explicit `cwd`. The bash schema accepts `cwd`, `env`, `timeout`, `pty`, and `async`; `cwd` and `env` are honored by the local executor. Omitting `timeout` uses the 300-second default. An explicit timeout must be finite, greater than zero, and no more than Atomic's deliberate 3600-second ceiling; invalid values fail before execution instead of being defaulted or clamped. Valid fractional values are rounded down with a one-second floor. Normal sessions enable tracked async jobs with bounded retention. `bashInterceptor.enabled` defaults to `false`; interception is not auto-enabled.
+When explicitly enabled in settings, built-in bash interceptor rules block common shell substitutes for first-class tools (`cat`/`grep`/`find`/in-place `sed`/redirection, etc.) only when the corresponding tool is available. Enabled bash tool calls are also offered to `user_bash` extension handlers before local execution. Atomic checks the original command, the internal-URL-expanded command, configured-prefix forms, `spawnHook`-rewritten commands, and a leading `cd path && command` or `cd path; command`-stripped form only when structured `cwd` was omitted, so interceptors can route commands by effective working directory without overriding explicit `cwd`. The bash schema accepts `cwd`, `env`, `timeout`, and `pty`; `cwd` and `env` are honored by the local executor. Omitting `timeout` uses the 300-second default. An explicit timeout must be finite, greater than zero, and no more than Atomic's deliberate 3600-second ceiling; invalid values fail before execution instead of being defaulted or clamped. Valid fractional values are rounded down with a one-second floor. `bashInterceptor.enabled` defaults to `false`; interception is not auto-enabled.
 
 ```json
 {
@@ -42,10 +40,30 @@ When explicitly enabled in settings, built-in bash interceptor rules block commo
 
 ## `find` and `search`
 
-`find` finds filesystem paths by glob; use `search` when you need content matches instead of path matches. `find.paths` is required and accepts file, directory, internal URL, or glob paths; copied quoted paths are normalized, exact filesystem paths with spaces/commas/semicolons are preserved before delimiter expansion, comma/semicolon-joined paths are split when at least one part resolves, whitespace-joined paths are split only when every part resolves, hidden files are included by default, `.gitignore` is respected by default (including nested `.gitignore` files outside a Git checkout), broad scans keep `node_modules`/`.git` pruned even with `gitignore:false` unless `node_modules` is explicitly present in the requested path or glob, results are capped at 200 by default, and timeout defaults to 5 seconds. Local `find` prefers the bundled Rust native `glob` implementation derived from oh-my-pi, falling back to the packaged `fd` helper only when native bindings are unavailable. Results include `scopePath`, `fileCount`, `files`, truncation/missing-path metadata, and streamed `onUpdate` snapshots during long scans.
+`find` finds filesystem paths by glob; use `search` when you need content matches instead of path matches. `find.paths` is required and accepts file, directory (including a filesystem root), internal URL, or glob paths; copied quoted paths are normalized, exact filesystem paths with spaces/commas/semicolons are preserved before delimiter expansion, comma/semicolon-joined paths are split when at least one part resolves, whitespace-joined paths are split only when every part resolves, hidden files are included by default, `.gitignore` is respected by default (including nested `.gitignore` files outside a Git checkout), broad scans keep `node_modules`/`.git` pruned even with `gitignore:false` unless `node_modules` is explicitly present in the requested path or glob, results are capped at 200 by default, and timeout defaults to 5 seconds. Local `find` prefers the bundled Rust native `glob` implementation derived from oh-my-pi, falling back to the packaged `fd` helper only when native bindings are unavailable. Results include `scopePath`, `fileCount`, `files`, truncation/missing-path metadata, and streamed `onUpdate` snapshots during long scans.
 
 `search` searches file contents with a regex across files, directories, globs, archive members, SQLite selectors, and internal URLs. It accepts `pattern`, optional `paths`, `i`, `case`, `gitignore`, and `skip`. Omitted, empty-string, or empty-array `paths` search the workspace root; copied quoted paths are normalized, exact filesystem paths with delimiters are preserved, and comma/semicolon-joined filesystem/resource paths are split when at least one part resolves while whitespace joins require every part to resolve. Whitespace-only patterns are rejected; other patterns are preserved verbatim, including ripgrep-style inline flags such as `(?i)`, `(?m)`, and `(?x)` for resource-backed selectors. Default search output is paged by matching files (20 by default), caps multi-file output to 20 matches per file while single-file searches allow 200 matches, uses `search.contextBefore`/`search.contextAfter` settings (1 before and 3 after by default), and `skip` pages files while single-file searches ignore it. When pagination reaches the internal collection ceiling, the output tells you to refine the pattern/path instead of silently reporting that later matches do not exist. Line selectors scope matches first and then render context around in-range matches, so context-only lines outside the selected range do not count as hits. Local filesystem search prefers the bundled Rust ripgrep-backed native `grep` implementation derived from oh-my-pi, preserving upstream 4 MiB file caps, context, line truncation, hidden-file defaults, and `.gitignore` handling; resource-backed searches use the native in-memory matcher when available and keep the JS fallback for multiline/resource edge cases. Search details include scope, counts, file lists, per-file match counts, missing paths, displayed content metadata, and `fileLimitReached`/`meta.limits.fileLimit` when pagination has more matching files. Hashline search rows preserve match/context markers as `*LINE:...` and ` LINE:...`.
 
 Directory `read` output renders an oh-my-pi-style depth-2 tree sorted by most-recent modification time, includes file sizes/relative ages, prunes `.git`/`node_modules`, and caps child directories to 12 entries with an elision marker while preserving the oldest shown entry. `read`, `write`, and `search` support local zip/jar/tar/tgz/gzip archive members without a Python dependency, including archive members literally named `raw`, `conflicts`, `1`, `L1`, or paths like `raw:notes.txt`, SQLite table/row selectors (`limit`, `offset`, `where`, `order`, `schema`, and `sampleRows` query parameters), `skill://` and source-backed `local://` selectors (which use the underlying filesystem path for mutable hashline labels/snapshots), and session-router-backed internal resources such as `artifact://`, `agent://`, `history://`, `issue://`, `pr://`, `rule://`, `mcp://`, and `vault://` when the host exposes a router. Workspace-scoped selectors (`local://`, built-in `skill://`, local archives, and SQLite selectors) reject lexical and symlink escapes outside the workspace or skill root. Existing non-SQLite `.db`/`.sqlite` files remain plain files; archive writes reject directory targets ending in `/`; archive writes return their resolved archive path, SQLite writes return source-path metadata, shebang writes are chmodded executable and report `madeExecutable`, SQLite table reads show schema plus a 5-row sample by default, SQLite query reads default to 20 rows with a 500 cap (raw `?q=` supports single-statement `SELECT` queries only, rejects `sqlite_%` internals, `pragma_*` table-valued functions, and dangerous keywords such as `ATTACH`, and is capped to 1000 rows via streaming iteration; table lists cap to 500 excluding `sqlite_%` tables, and table row counts probe at most 50,001 rows), table writes accept `{}` as `INSERT DEFAULT VALUES`, row writes parse non-empty JSON5-style objects including comments, and SQLite writes validate column names/scalar values before binding (empty SQLite row writes delete only when a row id is present). `conflict://<id>` and `conflict://*` writes splice conflict marker regions, expand `@ours`, `@theirs`, and `@base`, and return fresh hashline snapshot headers for resolved files; scoped conflict sides such as `conflict://1/ours` are read-only. Plain `write` refuses to overwrite generated-looking files when generated markers appear near the top of the file. `read` extracts readable text for HTML URLs and notebooks (`.ipynb` cells use 0-based `cell:N` IDs and preserve unknown top-level notebook fields), and routes PDFs plus Office/document formats (`.doc`, `.docx`, `.ppt`, `.pptx`, `.xls`, `.xlsx`, `.rtf`, `.epub`) through the same `markit-ai` converter path as oh-my-pi, including upstream unsupported-format messages when no converter is available. Extensionless URL downloads are decoded when the `Content-Type` identifies the document type. Oversized URL/resource/document reads return guidance plus structured details so collapsed renderers still surface the block reason. Successful `read` results consistently return `details.meta.source`/`sourcePath` (plus `truncation`/`limits` when truncation or list limits apply), and `read`/`search` accept line selectors such as `file.ts:5-16`, `file.ts:5+3`, `file.ts:5-16,960-973`, or `https://example.test/page:5-8`; bounded read selectors include one leading and three trailing context lines unless `:raw` is used for unformatted content, and out-of-range selectors report a clear beyond-EOF message instead of returning an empty success.
 
 Plain URL reads follow oh-my-pi's fetch-pipeline truncation contract: unselected URL output shows the first 300 rendered lines (capped at 50 KiB), preserves full-output artifact/truncation metadata when available, and does not hard-block solely because the rendered URL body is large. By default Atomic rejects private, localhost, cloud-metadata, numeric/short-form private-IP URL targets (for example `2130706433`, octal/hex dotted forms, and `127.1`), IPv4-compatible and IPv4-mapped IPv6, NAT64, 6to4 private-address forms, and the full IPv6 link-local `fe80::/10` range, revalidates each manual redirect, pins DNS-validated addresses for outbound fetches, and caps streamed URL bodies; `ATOMIC_ALLOW_PRIVATE_URL_READS=1` is a dev-only escape hatch for trusted local tests and must not be set from untrusted project configuration. Local text reads use the shared 3,000-line/50 KiB output cap, while search match/context lines use the upstream 512-character cap before emitting a truncation notice.
+
+## Persisted tool output
+
+Output that does not fit in a tool result is written to a file, and the result points at it — `Full output: <path>` for `bash`, `Full output saved to: <path>` for any tool result that crosses the persistence threshold. Those files are storage, so Atomic bounds where they go, how large they get, and how long they live.
+
+**Where.** A session that persists to disk keeps its tool results in `<sessionDir>/tool-results/`, unchanged. Everything else — `bash` overflow logs, streamed spill files, and tool results for in-memory sessions — goes under one owner- and session-scoped temp tree:
+
+```text
+<tmpdir>/atomic-<uid>/<session-id>/
+```
+
+On Windows, where there is no uid, the account name is used instead — qualified by its domain and followed by a short digest, so that `CONTOSO\Alice` and `FABRIKAM\Alice`, or two names that reduce to the same safe path component, do not share one tree. The session id is reduced to a single safe path component, so a session id containing separators or `..` cannot place files outside that tree.
+
+Directories are created with `0700` and files with `0600` on platforms that support them. On POSIX that is enforced: a root owned by another account is refused and a too-permissive one is tightened. On Windows, Node exposes neither an owner SID nor a POSIX mode, so before adopting an existing component Atomic reads its security descriptor through PowerShell `Get-Acl` and decides from SIDs: the owner must be the current user, SYSTEM, or Administrators, and every access-allowed DACL entry must grant only those principals. A foreign-owned root, a root other accounts can access (a machine-wide redirected `TMP`), and a descriptor that cannot be read or fully parsed are all refused. A successful verification is cached per path per process, keyed to the directory's metadata identity — creation, change, and last-write times — so both a directory swapped underneath the path and an in-place DACL edit (which bumps the NTFS change time) force a fresh descriptor read; only a directory whose metadata is unchanged skips the subprocess.
+
+Because that path is predictable, Atomic validates it rather than trusting it. Every component below the system temp directory is created one level at a time and checked: a symlink is refused outright, a directory owned by another account is refused, and a directory of this account's left too permissive is tightened to `0700` and re-checked. Refusal fails closed — the tool runs with no spill file and reports no path, instead of writing your command output into a directory someone else planted. Only the final session directory is treated as replaceable: a stale file or link sitting exactly where a session directory belongs is removed (a link by itself, never its target) and recreated.
+
+**How large.** No single persisted-output file exceeds 64 MB. Output that lands exactly on the cap is kept whole; only output that passes it is cut off there, with `[Output truncated: persisted-output cap of 67108864 bytes reached]` appended in place of the rest. The cut lands on a character boundary even when a multi-byte character is split across two chunks of streamed output, and bytes that are not valid UTF-8 — binary command output — are written through unchanged rather than decoded. The truncation is in the file only; the tool result and its `fullOutputPath` are unaffected. If a spill file cannot be written at all, `bash` reports no path rather than one pointing at a file that is not there.
+
+**How long.** Tool-output storage is reaped on age. A sweep runs shortly after startup, off the startup path, and removes session temp trees and `tool-results` directories whose newest file is more than 30 days old. It covers the default project-nested session roots and a custom session directory chosen with `--session-dir`, `ATOMIC_CODING_AGENT_SESSION_DIR`, or the `sessionDir` setting. The newest entry decides the whole directory: one fresh file keeps everything beside it, so a path recorded weeks ago stays readable as long as the tree is still in use. Each target is throttled to once a day by a `.last-cleanup` marker and guarded by a `.cleanup.lock` exclusive lock, so concurrent Atomic sessions never race each other; for session storage that pair lives in a control directory under the temp root rather than inside the scanned directory. A tree belonging to a session the running process is using is never reaped, so a `Full output saved to:` path stays valid for the life of the session that produced it. Session transcripts and `.jsonl` session files are outside the sweep entirely: only the temp trees and `tool-results` directories are ever deleted, symlinks are never followed out of a target, and a directory the sweep cannot verify as a real directory is skipped rather than read.

package/docs/tui.md

@@ -13,7 +13,7 @@ All components implement:
 ```typescript
 interface Component {
   render(width: number): string[];
-  handleInput?(data: string): void;
+  handleInput?(data: string): boolean | void;
   wantsKeyRelease?: boolean;
   invalidate(): void;
 }
@@ -22,10 +22,12 @@ interface Component {
 | Method | Description |
 |--------|-------------|
 | `render(width)` | Return array of strings (one per line). Each line **must not exceed `width`**. |
-| `handleInput?(data)` | Receive keyboard input when component has focus. |
+| `handleInput?(data)` | Receive keyboard input when the component has focus. A focused overlay also receives mouse input before the fullscreen viewport. Return `true` when it consumes input; return `false`, `undefined`, or `void` when a matching fullscreen viewport key or overlay mouse event should fall through to viewport handling. Non-overlay focused components leave mouse input with pi-tui so transcript scrolling, scrollbar interaction, and drag selection remain available. |
 | `wantsKeyRelease?` | If true, component receives key release events (Kitty protocol). Default: false. |
 | `invalidate()` | Clear cached render state. Called on theme changes. |
 
+The installed pi-tui type still permits handlers that return `void`; Atomic treats a missing or `undefined` result as unhandled only for a matching fullscreen viewport key or a mouse event deferred to a focused overlay. Components that mutate state for such an input must return `true` so the viewport does not apply it a second time.
+
 The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
 
 ## Focusable Interface (IME Support)
@@ -99,21 +101,20 @@ pi.on("session_start", async (_event, ctx) => {
 
 Pass `{ signal }` to `ctx.ui.custom()` when the UI belongs to an abortable operation. If the signal aborts, Atomic dismisses the custom UI and rejects the returned promise with the signal reason. For overlays, use `options.onHandle` to receive an overlay handle for programmatic visibility control.
 
-In Atomic's default interactive mode, the component instance remains in the isolated engine child. The terminal host caches rendered lines and forwards input asynchronously, so `render()` and `handleInput()` must not depend on direct access to host process objects. The remote bridge preserves pi-tui's key-release contract: release events are filtered unless the child component sets `wantsKeyRelease = true`, matching a directly mounted component. Return values passed to `done()` must be JSON-safe.
+In Atomic's default interactive mode, the component instance remains in the isolated engine child. The terminal host caches rendered lines and forwards input asynchronously, so `render()` and `handleInput()` must not depend on direct access to host process objects. For a matching fullscreen viewport key, or for mouse input while a workflow overlay has focus, the host waits for the child's boolean input reply: `true` keeps the input local, while `false` lets the host transcript process it. Left-button selection events are also mirrored to pi-tui when an overlay handles them, so drag and multi-click selection stays available over fullscreen workflow overlays. Mouse input remains with pi-tui when a non-overlay component has focus, preserving transcript scrolling, scrollbar interaction, and drag selection. A stalled reply has a bounded fallback. The remote bridge preserves pi-tui's key-release contract: release events are filtered unless the child component sets `wantsKeyRelease = true`, matching a directly mounted component. Return values passed to `done()` must be JSON-safe.
 
 ### Host terminal modes from an isolated component
 
-Because the component runs in the engine child — whose stdout is the JSONL transport, not a TTY — writing raw terminal escape sequences to `process.stdout` from `render()`/`handleInput()` is a no-op and never reaches the real host terminal. For the two host-terminal modes an overlay commonly needs, the factory `tui.terminal` exposes typed, allowlisted setters that the host applies to the real TTY over the engine protocol:
+Because the component runs in the engine child — whose stdout is the JSONL transport, not a TTY — writing raw terminal escape sequences to `process.stdout` from `render()`/`handleInput()` is a no-op and never reaches the real host terminal. For the host autowrap mode an overlay may need, the factory `tui.terminal` exposes a typed, allowlisted setter that the host applies to the real TTY over the engine protocol:
 
 ```typescript
 await ctx.ui.custom((tui, theme, keybindings, done) => {
-  tui.terminal.setMouseScrollTracking?.(true); // enable SGR mouse-scroll reporting on the host TTY
-  tui.terminal.setAutowrap?.(false);           // disable autowrap (DECAWM) — Windows terminals only
+  tui.terminal.setAutowrap?.(false); // disable autowrap (DECAWM) — Windows terminals only
   return new MyOverlay({ onClose: done });
 }, { overlay: true });
 ```
 
-These are the only terminal controls exposed; arbitrary child bytes are never forwarded to the terminal. The host resets any mode a component enabled when the overlay hides, closes, is disposed, or when the engine child crashes/restarts, so a stranded child can never leave the terminal in mouse-reporting or autowrap-off mode. On non-isolated hosts and test seams the setters are absent, and callers should fall back to writing escape sequences to their own `process.stdout`.
+This is the only terminal control exposed; arbitrary child bytes are never forwarded to the terminal. The host resets the mode when a component hides, closes, is disposed, or when the engine child crashes or restarts. In fullscreen, pi-tui owns its baseline mouse and autowrap modes; non-isolated overlay fallbacks do not disable that baseline. On regular non-isolated hosts and test seams the setter is absent, and callers may fall back to writing escape sequences to their own `process.stdout`.
 
 ### Host-native session picker
 
@@ -327,16 +328,21 @@ Use `matchesKey()` for key detection:
 ```typescript
 import { matchesKey, Key } from "@earendil-works/pi-tui";
 
-handleInput(data: string) {
+handleInput(data: string): boolean {
   if (matchesKey(data, Key.up)) {
     this.selectedIndex--;
+    return true;
   } else if (matchesKey(data, Key.enter)) {
     this.onSelect?.(this.selectedIndex);
+    return true;
   } else if (matchesKey(data, Key.escape)) {
     this.onCancel?.();
+    return true;
   } else if (matchesKey(data, Key.ctrl("c"))) {
     // CTRL+C
+    return true;
   }
+  return false;
 }
 ```
 
@@ -387,18 +393,23 @@ class MySelector {
     this.items = items;
   }
 
-  handleInput(data: string): void {
+  handleInput(data: string): boolean {
     if (matchesKey(data, Key.up) && this.selected > 0) {
       this.selected--;
       this.invalidate();
+      return true;
     } else if (matchesKey(data, Key.down) && this.selected < this.items.length - 1) {
       this.selected++;
       this.invalidate();
+      return true;
     } else if (matchesKey(data, Key.enter)) {
       this.onSelect?.(this.items[this.selected]);
+      return true;
     } else if (matchesKey(data, Key.escape)) {
       this.onCancel?.();
+      return true;
     }
+    return false;
   }
 
   render(width: number): string[] {
@@ -693,7 +704,11 @@ pi.registerCommand("pick", {
       return {
         render: (w) => container.render(w),
         invalidate: () => container.invalidate(),
-        handleInput: (data) => { selectList.handleInput(data); tui.requestRender(); },
+        handleInput: (data) => {
+          selectList.handleInput(data);
+          tui.requestRender();
+          return true;
+        },
       };
     });
 
@@ -773,7 +788,10 @@ pi.registerCommand("settings", {
       return {
         render: (w) => container.render(w),
         invalidate: () => container.invalidate(),
-        handleInput: (data) => settingsList.handleInput?.(data),
+        handleInput: (data) => {
+          settingsList.handleInput?.(data);
+          return true;
+        },
       };
     });
   },
@@ -895,35 +913,33 @@ type Mode = "normal" | "insert";
 class VimEditor extends CustomEditor {
   private mode: Mode = "insert";
 
-  handleInput(data: string): void {
+  handleInput(data: string): boolean {
     // Escape: switch to normal mode, or pass through for app handling
     if (matchesKey(data, "escape")) {
       if (this.mode === "insert") {
         this.mode = "normal";
-        return;
+        return true;
       }
       // In normal mode, escape aborts agent (handled by CustomEditor)
-      super.handleInput(data);
-      return;
+      return super.handleInput(data);
     }
 
     // Insert mode: pass everything to CustomEditor
     if (this.mode === "insert") {
-      super.handleInput(data);
-      return;
+      return super.handleInput(data);
     }
 
     // Normal mode: vim-style navigation
     switch (data) {
-      case "i": this.mode = "insert"; return;
-      case "h": super.handleInput("\x1b[D"); return; // Left
-      case "j": super.handleInput("\x1b[B"); return; // Down
-      case "k": super.handleInput("\x1b[A"); return; // Up
-      case "l": super.handleInput("\x1b[C"); return; // Right
+      case "i": this.mode = "insert"; return true;
+      case "h": return super.handleInput("\x1b[D"); // Left
+      case "j": return super.handleInput("\x1b[B"); // Down
+      case "k": return super.handleInput("\x1b[A"); // Up
+      case "l": return super.handleInput("\x1b[C"); // Right
     }
     // Pass unhandled keys to super (ctrl+c, etc.), but filter printable chars
-    if (data.length === 1 && data.charCodeAt(0) >= 32) return;
-    super.handleInput(data);
+    if (data.length === 1 && data.charCodeAt(0) >= 32) return false;
+    return super.handleInput(data);
   }
 
   render(width: number): string[] {
@@ -954,6 +970,7 @@ export default function (pi: ExtensionAPI) {
 - **Extend `CustomEditor`** (not base `Editor`) to get app keybindings (escape to abort, ctrl+d to exit, model switching, etc.)
 - **Call `super.handleInput(data)`** for keys you don't handle
 - **Factory pattern**: `setEditorComponent` receives a factory function that gets `tui`, `theme`, and `keybindings`
+- **Autocomplete limit**: custom editors installed through `setEditorComponent()` that expose `setAutocompleteMaxVisible()` inherit the active `autocompleteMaxVisible` setting
 - **Pass `undefined`** to restore the default editor: `ctx.ui.setEditorComponent(undefined)`
 
 **Examples:** [modal-editor.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/modal-editor.ts)

package/docs/usage.md

@@ -108,12 +108,14 @@ See [Sessions](/sessions) and [Compaction](/compaction) for details.
 
 ## Context Files
 
-Atomic loads `AGENTS.md` or `CLAUDE.md` at startup from:
+Atomic loads `AGENTS.override.md`, `AGENTS.md`, or `CLAUDE.md` at startup from:
 
-- `~/.atomic/agent/AGENTS.md` for global instructions
+- `~/.atomic/agent/` for global instructions (legacy `~/.pi/agent/` also works)
 - parent directories, walking up from the current working directory
 - the current directory
 
+If a directory contains `AGENTS.override.md`, Atomic uses it instead of that directory's `AGENTS.md` or `CLAUDE.md`. Context files from other directories still layer normally.
+
 Use context files for project conventions, commands, safety rules, and preferences. Disable loading with `--no-context-files` or `-nc`.
 
 ### System Prompt Files
@@ -177,17 +179,26 @@ See [Atomic Packages](/packages) for package sources and security notes.
 ### Credential Commands
 
 ```bash
+atomic auth check [--provider <p>] [--model <model>] [--json] [--credentials] [--no-refresh]
 atomic auth print-api-key --model <model> [--provider <p>]
 atomic auth print-bearer-token --model <model> [--provider <p>] [--min-expiry <dur>]
 ```
 
-Print one configured credential for an external client — a proxy, a script, or another tool that needs the same key Atomic already holds. The credential goes to **stdout and nothing else**; warnings, provider selection, refresh notices, and help all go to stderr, so `KEY=$(atomic auth print-api-key --model gpt-5.5)` can never capture a diagnostic.
+`atomic auth check` verifies the effective credential a provider or model would use before a session starts. It requires at least one of `--provider` or `--model`, prints `ready`, `not_ready`, or `invalid` to stdout, and exits `0`, `1`, or `2` for those states. `--json` adds the resolved provider when one is found, credential kind, and any reason. By default, a check never emits credential material.
+
+`--credentials` is an explicit export opt-in. It requires `--provider` or an exact `--model` target; a fuzzy model match on an otherwise-ready provider is refused as `invalid` (exit `2`) rather than exporting a credential for a provider you did not name. If that provider is not ready, the check remains `not_ready` (exit `1`). On a ready check, plain stdout becomes the resolved credential alone and JSON adds it only in the `credentials` field. A non-ready raw export leaves stdout empty and reports its status on stderr; a JSON export returns the status object without a credential. Credential writes can also exit `8` (nothing written) or `9` (only a fragment written). Treat the stream like `print-api-key` or `print-bearer-token` output.
+
+Checks refresh expired OAuth credentials by default, using Atomic's normal locked `auth.json` update path. Pass `--no-refresh` to read credentials without creating, locking, or mutating `auth.json`; this is useful when a probe must not change stored auth state. It still reads Atomic's primary and legacy credential paths and resolves configured API-key values, including `!command`, through the normal provider configuration. In this read-only mode, malformed `auth.json` is `invalid` (exit `2`) rather than an unavailable credential. An OAuth credential export requires at least 30 minutes of life: the normal path can refresh it, while `--no-refresh` refuses a shorter-lived token.
+
+The credential commands print one configured credential for an external client — a proxy, a script, or another tool that needs the same key Atomic already holds. The credential goes to **stdout and nothing else**; warnings, provider selection, refresh notices, and help all go to stderr, so `KEY=$(atomic auth print-api-key --model gpt-5.5)` can never capture a diagnostic.
 
-`--model` is required. There is no ambient "current model", so the command cannot emit a credential you did not name. When several configured providers offer the model, pass `--provider` to choose one. `--provider` and `--model` are the only options either subcommand accepts: any other flag — including `--export`, `--session-dir`, `--print`, and `--help` — is a usage error rather than a flag this path happens to ignore.
+`--model` is required for the two `print-*` exports. An exporting auth check needs `--provider` or an exact `--model` target. When several configured providers offer a model, pass `--provider` to choose one. The two `print-*` subcommands accept only `--provider` and `--model`: any other flag — including `--export`, `--session-dir`, `--print`, and `--help` — is a usage error rather than a flag this path happens to ignore.
 
-`atomic auth` on its own — and `atomic auth help`, `--help`, or `-h` — prints this usage on stderr and exits `0`. Any other subcommand exits `1` and names the two valid ones. Help never uses stdout, so stdout from this command family is a credential or empty.
+`atomic auth` on its own — and `atomic auth help`, `--help`, or `-h` — prints this usage on stderr and exits `0`. `atomic auth check --help` (or `-h`) does the same until a `--` terminator; after it, the flag is not help. Any other subcommand exits `1` and names all three valid commands. Help never uses stdout, so raw credential export stdout is a credential or empty; a JSON export writes an object that carries a credential only in its `credentials` field.
 
-`print-bearer-token` works only on OAuth providers and `print-api-key` only on API-key providers; asking for the wrong kind is an error rather than a silent fallback. A bearer token with less than `--min-expiry` remaining (default `30m`, accepting `ms`, `s`, `m`, or `h`) is refreshed first. Both `--min-expiry 30m` and `--min-expiry=30m` are accepted. `--min-expiry` with `print-api-key` is a usage error — an API key has no expiry. A failed refresh leaves your stored credential untouched.
+`print-bearer-token` works only on OAuth providers and `print-api-key` only on API-key providers; asking for the wrong kind is an error rather than a silent fallback. A bearer token with less than `--min-expiry` remaining (default `30m`, accepting `ms`, `s`, `m`, or `h`) is refreshed first. Both `--min-expiry 30m` and `--min-expiry=30m` are accepted. `--min-expiry` with `print-api-key` is a usage error — even after a `--` terminator — because an API key has no expiry. A failed refresh leaves your stored credential untouched.
+
+Credential-export exits (`print-api-key`, `print-bearer-token`, and the `--credentials` write itself):
 
 | Exit | Meaning |
 |------|---------|
@@ -202,27 +213,39 @@ Print one configured credential for an external client — a proxy, a script, or
 | `8` | The credential could not be written; nothing was emitted |
 | `9` | Only part of the credential was written; discard the output |
 
+Auth-check exits:
+
+| Exit | `atomic auth check` |
+|------|---------------------|
+| `0` | `ready` |
+| `1` | `not_ready`, including a fuzzy `--model` with `--credentials` when its resolved provider is not ready |
+| `2` | `invalid`, including check usage errors (unknown option, neither `--provider` nor `--model`, and a fuzzy `--model` with `--credentials` when its resolved provider is otherwise ready) |
+| `8` | With `--credentials`, the credential could not be written; nothing was emitted |
+| `9` | With `--credentials`, only part of the credential was written; discard the output |
+
 Exit `5` is reported only for a refresh that itself failed, which happens before anything is persisted; that is the only exit that promises your stored credential is untouched. Any other OAuth failure exits `7` and makes no such promise.
 
-Stdout is empty on every non-zero exit but one. Once the credential reaches stdout the command has succeeded: if the stream then fails to drain — a reader that closed the pipe, for example — that is reported on stderr and the exit code stays `0`, because a non-zero exit here would contradict the bytes the caller already holds. The exception is exit `9`, which reports that only part of the credential was written before the stream failed; those bytes cannot be recalled, so stdout is not empty, and the output is a fragment to discard rather than a credential to use. See [Security](/security#credential-export) before wiring this into a script.
+For raw credential exports, stdout is empty on every non-zero exit but one. Once the credential reaches stdout the command has succeeded: if the stream then fails to drain — a reader that closed the pipe, for example — that is reported on stderr and the exit code stays `0`, because a non-zero exit here would contradict the bytes the caller already holds. The exception is exit `9`, which reports that only part of the credential was written before the stream failed; those bytes cannot be recalled, so stdout is not empty, and the output is a fragment to discard rather than a credential to use. `auth check --credentials --json` may instead write a credential-free JSON status object on a non-zero check result. See [Security](/security#credential-export) before wiring this into a script.
 
 ### Modes
 
 | Flag | Description |
 |------|-------------|
-| default | Interactive mode |
+| default | Interactive mode (fullscreen TUI) |
 | `-p`, `--print` | Print response and exit |
 | `--mode json` | Output all events as JSON lines; see [JSON mode](/json) |
 | `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](/rpc) |
 | `--export <in> [out]` | Export a session to HTML |
 
+Interactive sessions always use fullscreen: the transcript scrolls independently above a sticky dock containing the editor, status line, usage meter, extension widgets, and footer. Wheel and trackpad gestures go first to a focused workflow graph or stage chat overlay; events those overlays do not consume fall through to the alternate-screen viewport. Non-overlay focused components do not block pi-tui's mouse path, so transcript scrolling, scrollbar interaction, and drag selection still work.
+
 In print mode, Atomic also reads piped stdin and merges it into the initial prompt:
 
 ```bash
 cat README.md | atomic -p "Summarize this text"
 ```
 
-When a print-mode turn correctly finishes by calling an opt-in terminating structured-output tool created with `createStructuredOutputTool` (for example from an extension, SDK caller, or workflow item with a schema), Atomic ends after that tool result without an extra follow-up assistant turn. Print-mode stdout contains the terminating structured JSON payload, so `atomic -p` remains script-friendly while the same value is also available through the SDK `capture` sink, tool `details`, a configured file sink, workflow `result.structured`, or subagent `result.structuredOutput`. This also works for custom factory names such as `final_decision`. Non-terminating or unrelated tool results are not printed as the final response.
+When a print-mode turn correctly finishes by calling an opt-in terminating structured-output tool created with `createStructuredOutputTool` (for example from an extension, SDK caller, or workflow item with a schema), Atomic ends after that tool result without an extra follow-up assistant turn. Print-mode stdout contains the terminating structured JSON payload, so `atomic -p` remains script-friendly while the same value is also available through the SDK `capture` sink, tool `details`, a configured file sink, or workflow `result.structured`. This also works for custom factory names such as `final_decision`. Non-terminating or unrelated tool results are not printed as the final response.
 
 ### Model Options
 
@@ -273,14 +296,14 @@ Project trust gates `.atomic`/legacy `.pi` project resources, project package se
 | Option | Description |
 |--------|-------------|
 | `-e`, `--extension <source>` | Load an extension from path, npm, or git; repeatable |
-| `--no-extensions` | Disable extension discovery |
+| `--no-extensions`, `-ne` | Disable extension discovery |
 | `--skill <path>` | Load a skill; repeatable |
-| `--no-skills` | Disable skill discovery |
+| `--no-skills`, `-ns` | Disable skill discovery |
 | `--prompt-template <path>` | Load a prompt template; repeatable |
-| `--no-prompt-templates` | Disable prompt template discovery |
+| `--no-prompt-templates`, `-np` | Disable prompt template discovery |
 | `--theme <path>` | Load a theme; repeatable |
 | `--no-themes` | Disable theme discovery |
-| `--no-context-files`, `-nc` | Disable `AGENTS.md` and `CLAUDE.md` discovery |
+| `--no-context-files`, `-nc` | Disable context-file discovery and loading |
 
 Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings. Example:
 
@@ -294,6 +317,7 @@ atomic --no-extensions -e ./my-extension.ts
 |--------|-------------|
 | `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
 | `--append-system-prompt <text>` | Append to system prompt |
+| `--offline` | Disable startup network operations, including update checks, package updates, and telemetry |
 | `--verbose` | Force verbose startup |
 | `-h`, `--help` | Show help |
 | `-v`, `--version` | Show version |
@@ -340,6 +364,7 @@ atomic --tools read,search,find,ls -p "Review the code"
 
 | Variable | Description |
 |----------|-------------|
+| `AI_AGENT` | Set to `atomic` by the CLI, RPC, and compiled binary entry points and in every Atomic-owned child-process environment so generic tooling can identify Atomic processes; child environments override caller-supplied values without mutating the caller's environment object |
 | `ATOMIC_CODING_AGENT_DIR` | Override config directory; default is `~/.atomic/agent`. Bundled intercom runtime/config files live under its `intercom/` subdirectory |
 | `ATOMIC_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
 | `ATOMIC_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
@@ -349,9 +374,10 @@ atomic --tools read,search,find,ls -p "Review the code"
 | `ATOMIC_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
 | `NODE_COMPILE_CACHE` | Override the directory for Node's persistent compile cache, which Atomic enables automatically on Node >= 22.8 to speed up startup (most noticeable on Windows). Set `NODE_DISABLE_COMPILE_CACHE=1` to opt out |
 | `PI_CACHE_RETENTION` | Provider/upstream-specific prompt-cache retention knob; set to `long` where supported |
+| `ATOMIC_NO_PTY` | Set to `1` to disable PTY use for bash commands (`PI_NO_PTY` is a legacy alias) |
 | `VISUAL`, `EDITOR` | External editor for CTRL+G |
 
-Every foreground or background bash execution receives one execution-time snapshot of the active session:
+Every bash execution runs in the foreground and receives one execution-time snapshot of the active session:
 
 | Atomic variable | Exact compatibility alias | Value |
 |-----------------|---------------------------|-------|
@@ -367,6 +393,6 @@ The snapshot is taken when the command executes, not when the tool is created, s
 
 ## Design Principles
 
-Atomic keeps the core CLI small, while this distribution bundles first-party package extensions for workflows, subagents, MCP, web access, and [intercom](/intercom). Other workflows can still be installed as extensions or packages, or handled externally with tools such as containers and tmux.
+Atomic keeps the core CLI small, while this distribution bundles first-party package extensions for workflows, subagents, MCP, web access, [intercom](/intercom), and [i-have-adhd](/i-have-adhd). Other workflows can still be installed as extensions or packages, or handled externally with tools such as containers and tmux.
 
 For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).

package/docs/windows.md

@@ -16,9 +16,11 @@ For most users, [Git for Windows](https://git-scm.com/download/win) is sufficien
 }
 ```
 
+Paths copied from Git Bash, MSYS2, Cygwin, or WSL are accepted anywhere Atomic resolves a file path. For example, `/c/Users/name/project/file.ts`, `/cygdrive/c/Users/name/project/file.ts`, and `/mnt/c/Users/name/project/file.ts` resolve as the matching Windows drive path.
+
 ## Filesystem Watchers
 
-On Windows, Atomic canonicalizes paths before starting native filesystem watchers. If a watcher target cannot be canonicalized or still contains an unsafe 8.3 short-name component such as `USERNA~1`, Atomic avoids native `fs.watch` for that target and uses polling where the feature supports it. This protects long-running sessions, async subagent result notifications, footer git status refreshes, and custom theme reloads from Windows/libuv path-prefix assertion crashes.
+On Windows, Atomic canonicalizes paths before starting native filesystem watchers. If a watcher target cannot be canonicalized or still contains an unsafe 8.3 short-name component such as `USERNA~1`, Atomic avoids native `fs.watch` for that target and uses polling where the feature supports it. This protects long-running sessions, footer git status refreshes, and custom theme reloads from Windows/libuv path-prefix assertion crashes.
 
 ## Self-Update Behavior