@ashx-j/lunr 0.2.20 → 0.2.22

package/dist/node-runtime/usage-service-LFB2SWYV.js

@@ -0,0 +1,37 @@
+import { createRequire as __lunrRequire } from "node:module"; const require = __lunrRequire(import.meta.url);
+import {
+  PLAN_USAGE_CACHE_TTL_MS,
+  USAGE_SERVICE_BRIDGE_SYMBOL,
+  clearPlanUsageCache,
+  footerPlanLabel,
+  getAllPlanUsageResults,
+  getPlanUsage,
+  getPlanUsageResult,
+  getUsageServiceBridge,
+  hasPlanUsageAdapter,
+  isFiveHourPlanWindow,
+  isWeeklyPlanWindow,
+  peekPlanUsage,
+  pickPlanWindow,
+  planUsageAuthError,
+  registerUsageServiceBridge
+} from "./chunk-2MI5OPMN.js";
+import "./chunk-IMLCWLPI.js";
+import "./chunk-BRJX2PRC.js";
+export {
+  PLAN_USAGE_CACHE_TTL_MS,
+  USAGE_SERVICE_BRIDGE_SYMBOL,
+  clearPlanUsageCache,
+  footerPlanLabel,
+  getAllPlanUsageResults,
+  getPlanUsage,
+  getPlanUsageResult,
+  getUsageServiceBridge,
+  hasPlanUsageAdapter,
+  isFiveHourPlanWindow,
+  isWeeklyPlanWindow,
+  peekPlanUsage,
+  pickPlanWindow,
+  planUsageAuthError,
+  registerUsageServiceBridge
+};

package/dist/node-runtime/{video-extract-OYT5WKS5.js → video-extract-OOZHR7SU.js}

@@ -11,8 +11,8 @@ import {
 } from "./chunk-3WFAEVKS.js";
 import {
   extractHeadingTitle
-} from "./chunk-WJVFOIB5.js";
-import "./chunk-7NBZ5P7I.js";
+} from "./chunk-UQUCFAJ3.js";
+import "./chunk-NAY6UUQZ.js";
 import {
   activityMonitor
 } from "./chunk-DAPBPCBP.js";

package/dist/node-runtime/{youtube-extract-TQYKGFGS.js → youtube-extract-FNPAUNHU.js}

@@ -1,4 +1,8 @@
 import { createRequire as __lunrRequire } from "node:module"; const require = __lunrRequire(import.meta.url);
+import {
+  isPerplexityAvailable,
+  searchWithPerplexity
+} from "./chunk-XBWPBZBN.js";
 import {
   isGeminiWebAvailable,
   queryWithCookies
@@ -8,14 +12,10 @@ import {
   isGeminiApiAvailable,
   queryGeminiApiWithVideo
 } from "./chunk-3WFAEVKS.js";
-import {
-  isPerplexityAvailable,
-  searchWithPerplexity
-} from "./chunk-XBWPBZBN.js";
 import {
   extractHeadingTitle
-} from "./chunk-WJVFOIB5.js";
-import "./chunk-7NBZ5P7I.js";
+} from "./chunk-UQUCFAJ3.js";
+import "./chunk-NAY6UUQZ.js";
 import {
   activityMonitor
 } from "./chunk-DAPBPCBP.js";

package/docs/browser.md

@@ -0,0 +1,86 @@
+# Headless browser
+
+The built-in `browser` tool runs Chromium through Playwright. Use it for pages that need JavaScript and for explicit website interactions. `web_search` still handles discovery; `fetch_content` still reads URLs. Neither tool automatically opens this browser. An interaction task can start with `browser` without fetching the page first.
+
+## Installation and settings
+
+Browser is on by default. Normal npm installation and updates automatically install the Chromium revision required by the pinned `playwright-core` dependency, including Playwright's supporting binaries. The same lifecycle works in source workspaces and published packages. Existing matching binaries are reused from Playwright's OS cache. Ordinary builds and CLI startup never download or launch a browser; Playwright loads on first browser use.
+
+Use **Browser** in `/settings` to turn it off or on. Turning it off immediately hides the tool and closes the session's browser, including pending initialization. It does not delete cached binaries. Turning it on makes the tool available without launching Chromium. The global `browserEnabled` setting defaults to true for new and existing users. A legacy explicit `features.browser.enabled: false` in `install-features.json` remains off until the user changes the new setting. An explicit `browserEnabled` value takes precedence; no legacy file is rewritten.
+
+`npm install --ignore-scripts`, `npm --offline`, `PI_OFFLINE=1`, and `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1` skip automatic Chromium installation. A failed download warns without making the rest of lunR unusable. Browser calls diagnose missing binaries and never install them silently. When online, run:
+
+```sh
+lunr browser install
+```
+
+`lunr setup` also installs matching Chromium automatically, including for Node-based standalone layouts. `PLAYWRIGHT_BROWSERS_PATH` selects an alternate cache and must be consistent between installation and execution. Linux may require Chromium system libraries; install those through your OS administrator. lunR does not install OS packages or disable Chromium's sandbox. Standalone compiled Bun browser installation has not been validated.
+
+## Actions
+
+There is one tool, `browser`, with these actions:
+
+| Action | Parameters and result |
+| --- | --- |
+| `navigate` | Required `url`, optional `tab`. Opens a browser if needed and navigates the selected tab. Returns its id and URL. |
+| `inspect` | Returns an accessible snapshot. Optional `role` with exact `name`, or exact `label`, scopes the snapshot to one element. |
+| `act` | Required `interaction` and target. Supports `click`, `fill`, `select`, `check`, `press`. |
+| `tabs` | Required `operation`: `list`, `create`, `select`, `close`. `create` optionally takes a URL; `select` requires `tab`. |
+| `screenshot` | Returns an explicit JPEG of the current viewport. It is never taken automatically. |
+| `close` | Closes Chromium, the proxy, and every tab. Discards cookies and in-memory storage. |
+
+Targets use an accessible `role` and optional exact `name`, or an exact field `label`. Inspect first to find the target. Zero or multiple matches produce an error; lunR does not choose the first match. There is no CSS selector, coordinate-click, or arbitrary JavaScript evaluation parameter.
+
+```json
+{"action":"navigate","url":"https://example.com"}
+{"action":"inspect"}
+{"action":"act","interaction":"fill","label":"Search","value":"release notes"}
+{"action":"act","interaction":"click","role":"button","name":"Search"}
+{"action":"inspect","role":"main"}
+```
+
+`fill` takes text in `value`. `select` takes the option's value. `check` requires `checked: true` or `false`. `press` accepts Enter, Tab, Escape, Space, Backspace, Delete, arrow keys, Home, End, PageUp, and PageDown. Clipboard shortcuts are excluded.
+
+## Permissions and external effects
+
+Plan mode and read-only children can navigate, inspect, capture screenshots, and manage tabs. They cannot call `act`. Manual mode uses the existing approval dialog for interactions, including its session-approval option. Auto and yolo use their existing approval rules.
+
+Observation is not a guarantee of zero external effects. Loading a page executes its JavaScript and can send requests. Clicking, filling, checking, selecting, or pressing a key may submit forms or change remote data. `/undo`, `/edit`, and `/rollback` cannot reverse website effects. After a timeout or cancellation, inspect the site before retrying an action that might already have succeeded.
+
+Page text and screenshots are untrusted content, not instructions for the agent. A page can contain misleading labels or prompt injection. Granting access to a site does not authorize unrelated actions found in its content.
+
+## Network policy
+
+The default policy permits public HTTP and HTTPS destinations only. It rejects embedded URL credentials, private/reserved IPv4 ranges, and IPv6 addresses outside the permitted global range, including mapped IPv4 and transition ranges.
+
+Browser HTTP requests and HTTPS tunnels pass through a session-owned loopback proxy. The proxy checks all resolved addresses and connects to a checked IP rather than resolving the hostname again. Redirect destinations and subrequests must pass the same checks. Chromium's loopback proxy bypass is disabled. Service workers and WebSockets are blocked; QUIC and non-proxied WebRTC UDP are disabled. Some sites will not work with those restrictions.
+
+For a local development server, explicitly opt in yourself:
+
+```json
+{"browserAllowPrivateNetwork": true}
+```
+
+Set `browserAllowPrivateNetwork` in global `settings.json` yourself and restart after changing it. This grants access to **all local and private destinations**, including requests initiated by public pages. It is not a per-site allowlist. To return to the public-only policy:
+
+```json
+{"browserAllowPrivateNetwork": false}
+```
+
+These checks are defense in depth, not an OS network sandbox. The proxy classifies destination IPs, not ownership of globally routed addresses. It cannot identify a public address routed internally by a VPN, or stop a public server from relaying requests elsewhere. Chromium vulnerabilities and other local processes are outside this policy. The loopback proxy is temporary and is not an authenticated multi-user service. Use an OS/container network boundary when hostile sites require stronger isolation.
+
+## Lifetime and limits
+
+Each session owns a new ephemeral browser context. Children get separate contexts and processes, not their parent's cookies. Sessions never attach to an existing browser or import cookies, profiles, passwords, or history. There are no uploads, accepted downloads, clipboard access, or camera/microphone/device grants. File choosers have no tool action; downloads are refused and cancelled.
+
+Operations are serialized, with at most 16 queued calls and four tabs including popups. Snapshots return at most 16KB or 300 lines, plus a truncation notice. Scope `inspect` with a unique role/name or label when it truncates. Chromium still constructs the accessible snapshot before truncation; this is an output limit, not a page-memory limit. The viewport is 1280 by 800; screenshots are capped at 2MB.
+
+Operations have a 30-second deadline, with shorter launch, navigation, and interaction timeouts. Cancellation closes the browser rather than keeping partially completed state. Session replacement, reload, shutdown, and aborted turns also close it. Five minutes without a browser operation discards the context. Resuming a conversation does not restore its browser state. Forced process termination cannot promise the same cleanup as a normal shutdown.
+
+## Development validation
+
+Install Chromium into an isolated cache explicitly, then use that same `PLAYWRIGHT_BROWSERS_PATH` for tests. `test/browser.test.ts` runs policy tests without Chromium and enables its actual-browser cases only when this variable is set. `test/browser-lifecycle.test.ts` covers missing binaries, deferred loading, settings-driven cleanup, and cancellation during launch. Browser settings and install tests cover default-on behavior, legacy explicit disable, npm lifecycle execution, offline installs, and ignored scripts.
+
+After the offline package builds and coding-agent Node bundle, run `node scripts/check-browser.mjs`. It uses a local scripted provider and fixture website, with the normal child permission environment for auto and read-only CLI sessions. A third session verifies missing-Chromium recovery. The checker terminates completed print processes after the final answer because of the existing headless exit behavior. It saves sanitized fixture results, tool inventories, and isolated prompts under `.artifacts/browser-smoke/`; nothing is sent to an external model.
+
+`node scripts/check-interactive-first-paint.mjs` verifies both disabled and enabled browser tool inventories while the implementation imports are stalled. No Chromium launch is needed for that check.

package/docs/extensions.md

@@ -2737,6 +2737,8 @@ See [tui.md](tui.md) Pattern 7 for a complete example with mode indicator.
 
 ### Message and Entry Rendering
 
+Clicking a custom message or entry toggles the renderer's `expanded` option. Child components that handle a click themselves take priority. Expansion survives theme invalidation; new or restored cards use the current tool-expansion setting.
+
 Register a custom renderer for messages with your `customType`. Use message renderers for content that should participate in LLM context:
 
 ```typescript

package/docs/features.md

@@ -21,12 +21,34 @@ Permission modes: `manual | yolo | plan | auto`. Shift+Tab (`app.mode.cycle`) cy
 
 Advertised subagents always start **fresh** (no forked parent context). Default parallel concurrency / max tasks / global run cap are unlimited; an explicit `concurrency` is still honored.
 
-Collapsed subagent rows (foreground and async) are one line: status glyph, description, selected tier or explicit model, tokens, and elapsed time. Running rows keep a live spinner and clock; completed collapsed rows freeze those stats. Async launches show `subagent async` in the tool header. Completed notify cards show title and status only; the model still receives the full result text.
+Single, parallel, and chain launches run async when `async` is omitted. Set `async:false` for an immediate foreground result or use `clarify:true` for the interactive preview/editor. Continue independent work after an async launch, then yield for normal interactive completion. Use `subagent_wait` only when the same turn or skill must finish after its children. Headless sessions auto-drain current-session work. Use status for one-time inspection rather than polling or sleeping for completion.
+
+The legacy extension config keys `asyncByDefault` and `forceTopLevelAsync` remain accepted but no longer change launch mode. Omitted `async` resolves to async, while explicit `async:false`, `clarify:true`, and internal `foregroundOnly` calls stay foreground. RPC and scheduled launches remain always async.
+
+Collapsed subagent rows (foreground and async) are one line: status glyph, description, selected tier or explicit model, tokens, and elapsed time. Mixed async runs use the same flat child rows without an aggregate tree. Running rows keep a live spinner and clock; completed collapsed rows freeze those stats. Choose the running child spinner under `/settings` → Customize. Async launches show `subagent async` in the tool header. Completed notify cards show title and status only; the model still receives the full result text.
 
 A launch of 3+ parallel children in one `tasks`/`chain.parallel` call, or 3+ same-turn SINGLE `subagent` calls, receives one aggregate confirmation in **manual and yolo**. Sequential work stays `chain`. Auto bypasses this confirmation, and it can be disabled independently in `/settings`.
 
 `/goal` sets a session goal and **forces session auto** permission mode.
 
+### Child communication
+
+Children own reversible implementation choices within their assigned scope. Define file ownership and required outputs at launch. Establish a shared contract before dependent parallel work, then pass it through chain outputs or an artifact. Native child intercom reaches the supervisor only; it cannot discover or message siblings.
+
+`contact_supervisor` separates delivery by purpose:
+
+- `progress_update` records a UI-only entry. It never enters parent model context or starts a parent turn. Existing activity indicators usually make an explicit progress call unnecessary.
+- `handoff` delivers actionable dependency findings or corrections without waiting for a reply. State what another task can now do, consolidate related findings, and reference one artifact for supporting detail. Continue independent work.
+- `need_decision` and `interview_request` wait for a supervisor reply. Use them for decisions outside the child's authority, permission or safety concerns, and blockers. Include the blocked decision, evidence, and recommended choice.
+
+Blocking requests and handoffs wake an idle parent. Headless waits yield to queued messages so a child can receive a decision before it finishes. Expired requests, stopped runs, and requests owned by another session cannot wake it. Legacy children retain model-facing progress delivery; UI-only progress requires the new protocol advertised by the spawning parent.
+
+Inactivity and threshold notices stay in diagnostic entries rather than parent context or intercom relays. Repeated tool failures remain model-facing. Completion-guard diagnostics do not duplicate the normal terminal failure report.
+
+Return one self-contained final report with outcomes, verification, blockers, and artifact paths. The runtime delivers it. A final report that only says findings were sent earlier is insufficient.
+
+Communication cards are collapsed tool-style rows. Click to show `From` or `To`, the child's description, and the message. Routing IDs stay in structured diagnostics. Outgoing steering also shows its delivery state when expanded; delivery acknowledgement is not a model answer.
+
 ### Questions to async children
 
 The parent can use `subagent_supervisor` with `action: "ask"` to ask a running async child for information it needs before the final report. The request names the run, selects one child, and includes a `reason` explaining which decision needs the answer.
@@ -39,9 +61,13 @@ A child must have an active question-capable input channel. Only one question ma
 
 The agent must ask only when the child has missing context, the answer changes a concrete next decision, and waiting for completion would block progress or risk rework. It must use available results first and batch related questions. Routine progress checks, duplicate questions, polling, and step-by-step supervision are prohibited. A follow-up is appropriate only when the answer leaves the original decision unresolved.
 
+### Measuring communication cost
+
+Compare the same task, models, thinking levels, and starting checkout before and after a communication change. Count parent wakeups by their triggering event, provider calls in both parent and child sessions, duplicate deliveries, input/output tokens, cache reads/writes, elapsed time, and blocked time. Check task correctness and delivery of required escalations before comparing cost. Cached input is separate from uncached input; fewer messages or a quieter UI alone do not establish savings. Keep transcript evidence local.
+
 ## Todos, memory, and global instructions
 
-- **Todos** — lunr-todos is a full-replace list. Completed todos prune on the next user turn (no leftover `✓ N done` footer).
+- **Todos** — lunr-todos is a full-replace list. `/settings` → Todos disables its system-prompt guidance, model-facing tool, and editor widget. Collapsed lists show all four active items; lists of five or more show three and a `+N more` line. Completed todos prune on the next user turn, so the footer does not leave a `✓ N done` line.
 - **Agent memory** — durable established facts and stable preferences in `~/.lunr/simple-memory/memory.md`. `/settings` → Agent memory controls injection and the `memory_add`, `memory_remove`, and `memory_load` tools without deleting stored facts. `memoryCharCap` defaults to 5000. Behavior instructions, transient task state, transcripts, guesses, and secrets do not belong in memory.
 - **Global instructions** — create `~/.lunr/agent/agents/AGENTS.md` yourself when you want global behavior or instructions. lunR injects it through the normal context loader; `/reload` picks up changes. The model cannot modify this user-managed file. The retired `behavior.md` file and behavior presets are no longer loaded.
 - **Model instructions** — `/settings` can enable `~/.lunr/agent/agents/<model-name>/AGENTS.md` and choose **Both** (global then model-specific) or **Model only**. The folder name is provider-independent and filesystem-safe. Project `AGENTS.md`/`CLAUDE.md` files are unaffected, and `--no-context-files` disables all instruction files.
@@ -56,33 +82,81 @@ Jobs persist in `~/.lunr/agent/cron/` (`jobs.json`). Interactive TUI cron runs i
 
 Schedule examples: `every 30m`, `every 2h`, `every 1d`, a duration one-shot (`30m`), an ISO timestamp, or a 5-field cron expression.
 
-## Gateway (Telegram / Discord)
+## Gateway for Telegram and Discord
+
+Run `lunr gateway setup` in your terminal. It explains bot creation and permissions, masks token entry, validates the bot identity, and asks for your user ID, project roots, saved model, and startup preference. Log in to a model provider locally with `/login` first. Setup does not create model-provider accounts.
+
+Telegram uses BotFather and long polling. Discord needs the bot and `applications.commands` installation scopes. Enable Message Content Intent for ordinary text messages. GuildMembers intent is not required. Discord registers native slash commands; Telegram registers a command menu. Both platforms use buttons for selections and approvals.
+
+Your computer must stay awake and online. Startup cannot make a sleeping or disconnected computer available.
 
-Enable the chat-platforms feature, then run the daemon:
+### Service controls
 
 ```bash
-lunr setup
-lunr features enable chat-platforms
-lunr gateway
+lunr gateway setup
+lunr gateway start
+lunr gateway stop
+lunr gateway restart
+lunr gateway status
+lunr gateway logs
+lunr gateway doctor
+lunr gateway run
+lunr gateway autostart login
+lunr gateway autostart boot
+lunr gateway autostart off
 ```
 
-Config: `~/.lunr/agent/gateway.json` (chmod 0600; may hold bot tokens). Secrets do not go in `install-features.json`.
+Bare `lunr gateway` also runs in the foreground. The terminal's `/settings` Gateway menu opens setup, service controls, logs, and diagnostics.
+
+Login startup runs after you sign in. Boot startup runs before login and may require administrator approval or OS-managed account credentials. Linux uses a systemd user service, with lingering for boot startup. macOS uses a LaunchAgent for login or a LaunchDaemon running as your user for boot. Windows uses Scheduled Tasks; its boot option asks Windows to obtain the account credentials rather than saving the password in lunR. lunR checks the native installation command before recording a successful startup change. Changing or disabling startup removes the previous lunR service, not other applications' services.
+
+Encrypted home directories, missing user-service support, network restrictions, and OS permissions can prevent boot startup. Use `status`, `doctor`, and `logs` to check the installed service and bot connections. Service definitions are separate for each lunR profile. Native startup specifications have automated tests; installing and rebooting services on all three operating systems still requires host verification.
+
+### Owner access
 
-Token resolution: `LUNR_<PLATFORM>_BOT_TOKEN` env → `<PLATFORM>_BOT_TOKEN` env → file token.
+Configuration lives in `~/.lunr/agent/gateway.json` and may contain bot tokens. It is written with mode 0600 where supported; Windows security follows the profile directory's ACL. Tokens are not stored in `install-features.json` or startup command arguments. Environment tokens override file tokens in this order: `LUNR_<PLATFORM>_BOT_TOKEN`, then `<PLATFORM>_BOT_TOKEN`.
+
+If you skipped your user ID during setup, message the bot privately and approve its pairing code locally:
 
 ```bash
-lunr gateway                     # run the daemon
-lunr gateway pair approve <platform> <code>
+lunr gateway pair approve telegram <code> --owner
+lunr gateway pair approve discord <code> --owner
 lunr gateway pair list
-lunr gateway status
 ```
 
-- Telegram: long-poll bot. Talk to @BotFather, put the token in `gateway.json` or `LUNR_TELEGRAM_BOT_TOKEN`, set `telegram.enabled = true`.
-- Discord: mention-gated by default (`requireMention: true`). Enable the Message Content intent. No GuildMembers intent. Put the token in `gateway.json` or `LUNR_DISCORD_BOT_TOKEN`.
-- Authz is fail-closed. Unauthorized DMs pair (`unauthorizedDmBehavior: "pair"`) unless you set `ignore`.
-- Gateway `/new` while a session is busy aborts the live turn and drops the queue.
+Owner access includes local projects and saved TUI conversation history. Ordinary pairing, group access, and Discord roles do not grant it. Project browsing, cross-project sessions, permission changes, and file downloads require an explicitly configured owner in a private DM. Removing owner access invalidates later owner actions and approvals.
+
+### Projects and mobile controls
+
+Use `/project` to browse approved roots, open child folders, go back, select a folder, or create one. `/project <path>` opens the browser at an approved path. The gateway remembers the selected working directory for that conversation. Project instruction files, skills, tools, and trust checks use that directory rather than the daemon's launch directory.
+
+**The selected project is a working directory, not a shell sandbox.** Shell commands and tools can access other locations allowed by your OS account. The folder browser and `/download` check their own path boundaries, including symlinks.
+
+- `/model`, `/thinking`, `/settings`, and `/mode` control the active session. `/fast` controls Codex fast mode.
+- `/plan <task>` starts planning. The plan appears in chat with approval buttons. Approval returns the session to manual mode.
+- `/goal`, `/cron`, `/run`, `/chain`, and `/parallel` use the same built-in extensions as the terminal. Pass arguments when an extension's interactive editor requires the terminal.
+- `/skill` selects a loaded skill and asks for a task. `/mcp` and `/lsp` expose their text status commands; the agent retains the configured coding tools.
+- `/usage` reports session tokens and provider-plan usage. `/status` includes the selected project.
+- `/stop` aborts the current turn and pending transfer. `/stopall` also requests cancellation of background subagents and tracked shell processes. `/processes` lists this session's processes; `/processes stop <pid>` requests a stop.
+- `/cancel` cancels a pending selection or transfer. `/new` aborts the current turn and drops queued input, but refuses to discard a session that still has attached background work.
+
+Upload images or documents in chat. Images reach the model as images; documents are saved under the project's `.lunr/uploads/` directory and passed to the model as paths. `/download <project-relative path>` sends a file back. Files are limited to 8 MB; common credential filenames are blocked from download. This filename check is not a content-based secret scanner. Only send files you intend to share with the chat platform.
+
+Extension notices and background results reach the originating conversation even after the foreground answer. Undelivered notices persist for retry. Tool approvals, pickers, and text questions do not become model prompts; they expire when the session changes. Terminal-only custom screens report that limitation rather than pretending they accepted a selection.
+
+### Continue between desktop and phone
 
-Without runnable adapters (enabled platform + resolvable token), `lunr gateway` prints setup instructions and exits 1.
+In the terminal, `/handoff` marks the current saved session for eight hours. Repeat it to refresh the mark; `/handoff cancel` removes it. Unsaved sessions must be persisted first.
+
+On your phone, `/continue` opens the only marked session, or offers a picker if several are marked. Without an active mark, it selects the latest TUI activity. TUI activation, user prompts, and state-changing user commands count as activity. Background results and file timestamps do not. Closed TUI sessions remain eligible.
+
+`/sessions [filter]` browses saved sessions across projects, including locally registered custom session paths. It works before you have sent the bot its first task. Continuation preserves the session file, selected conversation branch, original project directory, and permission checkpoint. Resuming `auto` or `yolo` asks for confirmation on the phone and defaults to manual if declined.
+
+Only one updated lunR process may write a persistent session at a time. A running owner must release it cooperatively. If it is busy, choose Wait, Stop and continue, or Cancel. Wait retries busy requests for up to two minutes. Stop and continue aborts the foreground turn; it does not migrate children or shell processes. Those must finish or actually stop before transfer. Cancellation stops pending acquisition, but cannot undo extension shutdown once release has begun.
+
+A detached terminal keeps its draft and can use `/reclaim` to reopen fresh state after the phone releases ownership. It does not append from its old in-memory conversation. Marks remain until expiry or cancellation, even after a successful continuation. Expiry only removes the preference; it neither deletes the conversation nor disconnects it.
+
+All concurrent writers must use a lunR version with session ownership support. Old versions and external file editors cannot honor these locks. Recovery only clears an owner after verified local process death. Uncertain, foreign-host, or incomplete ownership records fail closed; inspect them rather than deleting a live lock.
 
 ## MCP, LSP, web search
 
@@ -90,6 +164,14 @@ Without runnable adapters (enabled platform + resolvable token), `lunr gateway`
 - **LSP** — `/lsp`, `/lsp-restart`, `/lsp-config`. Footer LSP segment is off by default (`footerLsp`). On Windows, npm `.cmd` shims need a real LSP start (`shell: true`); if the server never starts, tools silently fall back to tree-sitter. Check `/lsp` if language features look missing.
 - **Web search** — `/websearch` (and related search commands). Interactive TUI attaches web-access after first paint; print/RPC/gateway load it before the first turn.
 
+## Headless browser
+
+The first-party `browser` tool is on by default. Normal installation and updates install matching Chromium automatically. Browser in `/settings` turns the tool off and closes active contexts immediately; cached binaries remain. Offline or ignored-script installs can recover later with `lunr browser install`. Startup and tool execution never install Chromium. The browser handles JavaScript-rendered pages and accessible website interactions, while `web_search` remains discovery and `fetch_content` remains URL reading. There is no automatic browser fallback.
+
+The browser uses ephemeral session-owned contexts. Plan/read-only blocks interactions, and manual mode approves them through the existing permission gate. Public HTTP(S) is the default; local/private access requires explicit user configuration. Website effects cannot be reversed by `/undo`.
+
+See [Headless browser](browser.md) for action parameters, installation exceptions, legacy setting precedence, private-network risks, lifecycle limits, and validation.
+
 ## Thinking, usage, streaming, UI
 
 - `/thinking`, `/effort`, and `/reasoning` are full-parity aliases. `/off`, `/minimal`, `/low`, `/medium`, `/high`, `/xhigh`, and `/max` set a level when the current model supports it. `/thinking` completions follow the session model. `xhigh` and `max` are opt-in. `/thinking hide|show|toggle` still hides thinking blocks.

package/docs/interactive-startup.md

@@ -22,6 +22,7 @@ opening the prompt barrier. It does not replace tool schemas with placeholders.
 The expensive implementations load when needed:
 
 - Web tools load providers, extraction, and browser curation separately.
+- The built-in headless browser is enabled by default and can be hidden in `/settings`. Its runtime and Playwright load on first browser use. Installation, not startup, installs Chromium. See [Headless browser](browser.md) for recovery and network limits.
 - LSP registers its tools before loading clients and Tree-sitter. Configured
   autostart runs in the background; first use waits for the required services.
 - MCP registers the proxy and cached direct-tool definitions without loading its
@@ -54,7 +55,7 @@ The check stalls or fails runtime loading and verifies the real frame, editable
 draft, and terminal cleanup. It also blocks optional implementation imports and
 checks a complete first request against the baseline tool-payload hash. Separate
 first-turn fixtures exercise subagent status, MCP status, Tree-sitter parsing,
-and local HTTP extraction. The default CI run checks the workspace build on
+and local HTTP extraction. Disabled and enabled headless-browser fixtures verify conditional tool registration while browser runtime imports are stalled. The default CI run checks the workspace build on
 Ubuntu. Passing a CLI path runs the same checks against a relocated installation,
 but CI does not currently pack that installation or run this check on Windows.
 

package/docs/sessions.md

@@ -25,6 +25,8 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 | Command | Description |
 |---------|-------------|
 | `/resume` | Browse and select previous sessions |
+| `/handoff [cancel]` | Mark this saved TUI session for phone continuation, or remove the mark |
+| `/reclaim` | Reopen fresh state after a phone-owned session releases control |
 | `/new` | Start a new session |
 | `/name <name>` | Set the current session display name |
 | `/session` | Show session info |
@@ -35,6 +37,14 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 
+## Session ownership
+
+Persistent sessions allow one writer at a time across the TUI, gateway, SDK, print, and RPC modes. Browsing and export use read-only snapshots. SDK callers that only inspect a saved file should use `SessionManager.openReadOnly(path)`. Mutable managers and sessions must be disposed before another writer opens the same file.
+
+The active branch and permission mode survive reopening. Transfers release the current runtime and create a fresh one; they do not move live child agents or shell processes. A heartbeat timeout alone never permits taking ownership from another process. All simultaneous lunR writers must use a version with ownership support.
+
+For marking a desktop session, choosing it on Telegram or Discord, and handling busy transfers, see [Continue between desktop and phone](features.md#continue-between-desktop-and-phone).
+
 ## Resuming and Deleting Sessions
 
 `/resume` opens an interactive session picker for the current project. `pi -r` opens the same picker at startup.

package/docs/settings.md

@@ -55,6 +55,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `externalEditor` | string | `$VISUAL`, then `$EDITOR`, then Notepad on Windows or `nano` elsewhere | Command for Ctrl+G external editor; takes precedence over environment variables |
 | `quietStartup` | boolean | `false` | Hide startup header |
 | `smoothStreaming` | boolean | `false` | Reveal streamed responses grapheme by grapheme (~30 FPS). Interactive TUI only |
+| `subagentSpinner` | string | `"braille"` | Foreground and async running child indicator: `"braille"`, `"orbit"`, `"snake"`, or `"sparkle"` |
 | `thinkingCollapse` | boolean | `true` | Collapse completed thinking blocks to a short label plus the first sentence |
 | `cacheRetention` | string | unset → `PI_CACHE_RETENTION` → `"short"` | `"none"`, `"short"`, or `"long"` prompt-cache retention |
 | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
@@ -62,6 +63,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `openaiFastMode` | boolean | `false` | Persist OpenAI Codex subscription Fast mode. Ignored by other providers |
 | `memoryEnabled` | boolean | `true` | Enable durable-fact injection and the model-facing memory tools. Global-only; disabling preserves the file |
 | `memoryCharCap` | number | `5000` | Durable-facts memory character cap (1–30000) |
+| `todosEnabled` | boolean | `true` | Enable todo guidance, the `todo` tool, and its editor widget. Global-only |
 | `sessionRetentionDays` | number | `30` | Delete session files older than N days at launch; `0` keeps forever |
 | `modelTiers` | object | - | Enable model tiers and per-tier thinking |
 | `modelInstructions` | object | `{ enabled: false, mode: "both" }` | Model-specific instructions and whether they append to or replace global instructions |
@@ -238,7 +240,7 @@ When multiple sources specify a session directory, precedence is `--session-dir`
 | `footerPlanBar` | boolean | `true` | Show the █░ fill; off keeps the percent only |
 | `planUsageWindow` | string | `"5h"` | Preferred plan window: `"5h"` or `"weekly"`. Missing 5h falls back to weekly |
 
-Customize these from `/settings` → Customize as well.
+Customize these from `/settings` → Customize as well. The same menu controls `subagentSpinner` with an animated preview.
 
 ### Cron, rollback, subscriptions
 

package/docs/tui.md

@@ -14,6 +14,7 @@ All components implement:
 interface Component {
   render(width: number): string[];
   handleInput?(data: string): void;
+  handleClick?(localY: number, width: number, localX?: number): boolean;
   wantsKeyRelease?: boolean;
   invalidate(): void;
 }
@@ -23,6 +24,7 @@ interface Component {
 |--------|-------------|
 | `render(width)` | Return array of strings (one per line). Each line **must not exceed `width`**. |
 | `handleInput?(data)` | Receive keyboard input when component has focus. |
+| `handleClick?(localY, width, localX?)` | Handle a click. Coordinates are zero-based within the component. `localX` is optional for compatibility with row-only handlers. Return `true` when handled. |
 | `wantsKeyRelease?` | If true, component receives key release events (Kitty protocol). Default: false. |
 | `invalidate()` | Clear cached render state. Called on theme changes. |
 

package/docs/usage.md

@@ -30,6 +30,22 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 
 See [Keybindings](keybindings.md) for all shortcuts and customization. Shift+Tab cycles permission mode (`manual` → `yolo` → `plan` → `auto`). Ctrl+O cycles `/tree` filters; it does not expand tool cards. `app.tools.expand` is unbound.
 
+### Copyable response blocks
+
+An assistant response can put a Copy button under a selected reusable excerpt, prompt, or code fragment. The button copies that block rather than the whole response. Each block has its own success or failure feedback.
+
+The assistant marks a block with the exact fenced Markdown info string `lunr-copy`:
+
+````markdown
+```lunr-copy
+Run the focused tests, then summarize failures.
+```
+````
+
+The copied payload starts after the opening fence's line break and ends before the line break immediately preceding the closing fence. lunR preserves its indentation, whitespace, and internal newlines without trimming, and does not copy either fence line. Use a longer backtick or tilde fence when the payload contains shorter fenced code.
+
+A streamed block stays readable while incomplete, but its Copy button appears only after the closing fence is received and revealed. Reopened sessions reconstruct buttons from the saved assistant message. Print, JSON, RPC, and gateway modes leave the fences readable and never perform clipboard writes.
+
 ## Slash Commands
 
 Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.2.19",
+  "version": "0.2.22",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.2.19",
+      "version": "0.2.22",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.2.19",
+	"version": "0.2.22",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.2.19",
+	"version": "0.2.22",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "0.2.19",
+	"version": "0.2.22",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "0.2.19",
+			"version": "0.2.22",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-gondolin",
 	"private": true,
-	"version": "0.2.19",
+	"version": "0.2.22",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "0.2.19",
+	"version": "0.2.22",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "0.2.19",
+			"version": "0.2.22",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "0.2.19",
+	"version": "0.2.22",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.2.19",
+  "version": "0.2.22",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.2.19",
+      "version": "0.2.22",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-with-deps",
 	"private": true,
-	"version": "0.2.19",
+	"version": "0.2.22",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ashx-j/lunr",
-	"version": "0.2.20",
+	"version": "0.2.22",
 	"description": "lunR — terminal coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -24,10 +24,12 @@
 	"files": [
 		"dist",
 		"docs",
+		"scripts/install-browser.mjs",
 		"examples",
 		"CHANGELOG.md"
 	],
 	"scripts": {
+		"postinstall": "node scripts/install-browser.mjs",
 		"clean": "shx rm -rf dist",
 		"build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets && node ../../scripts/build-node-runtime.mjs",
 		"build:binary": "npm --prefix ../tui run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm run build && bun build --compile ./dist/bun/cli.js ./src/utils/image-resize-worker.ts --outfile dist/lunr && npm run copy-binary-assets",
@@ -37,9 +39,9 @@
 		"shrinkwrap": "node ../../scripts/generate-coding-agent-shrinkwrap.mjs"
 	},
 	"dependencies": {
-		"@ashx-j/lunr-agent": "^0.2.20",
-		"@ashx-j/lunr-ai": "^0.2.20",
-		"@ashx-j/lunr-tui": "^0.2.20",
+		"@ashx-j/lunr-agent": "^0.2.22",
+		"@ashx-j/lunr-ai": "^0.2.22",
+		"@ashx-j/lunr-tui": "^0.2.22",
 		"@modelcontextprotocol/ext-apps": "1.7.4",
 		"@modelcontextprotocol/sdk": "1.30.0",
 		"@mozilla/readability": "0.6.0",
@@ -59,6 +61,7 @@
 		"minimatch": "10.2.5",
 		"open": "10.2.0",
 		"p-limit": "6.2.0",
+		"playwright-core": "1.63.0",
 		"proper-lockfile": "4.1.2",
 		"recheck": "4.5.0",
 		"semver": "7.8.0",