@ashx-j/lunr-dev 0.2.19-dev.10.1 → 0.2.21-dev.12.1

package/docs/computer-use.md

@@ -1,277 +1,242 @@
-# Native computer use
+# Image-only computer use
 
-This implementation is available through the experimental `@ashx-j/lunr-dev`
-channel, based on stable lunR 0.2.19 plus PR #77. Install with
-`npm i -g @ashx-j/lunr-dev`, then run `lunr-dev`. Stable `@ashx-j/lunr` is unchanged.
-This is not production support certification. Windows
-MCP metadata interoperability and local runtime/lifecycle tests pass. The macOS
-launch path is implemented but has not run on macOS hardware. Neither platform
-has passed live desktop acceptance. Production publication remains blocked.
+This dev-channel integration combines stable lunR 0.2.21 with image-only computer
+use. Offline builds, focused automated tests, local scripted-provider startup
+checks, and isolated package installation pass. No live desktop capture or input,
+native runtime launch, or remote inference ran. Stable production publication
+remains blocked. Smooth cursor animation is not included.
 
-## Local setup
+The dev package is `@ashx-j/lunr-dev`, with command `lunr-dev` and update command
+`lunr-dev update`. Stable `@ashx-j/lunr` and `lunr` remain separate. Both commands
+share `~/.lunr/agent` credentials, settings, and sessions.
 
-Run `/computer setup` in the local lunR terminal. It verifies and installs the
-bundled runtime without downloading code, capturing the screen, or operating an
-application. Setup is user-invoked and unavailable from gateway or headless
-sessions.
-
-On Windows, keep the desktop logged in and unlocked. On macOS, setup prints the
-exact installed `CuaDriver.app` path. Add that app under System Settings > Privacy
-& Security to both Accessibility and Screen & System Audio Recording, named
-Screen Recording on older macOS versions. Enable both grants, then restart lunR.
-These OS grants require the user; Auto mode cannot supply them. Setup never
-selects or changes an existing `/Applications/CuaDriver.app` installation.
+## Setup and permissions
 
-Complete setup before assigning GUI tasks through cron or the gateway. A setup
-success verifies the runtime files, not permission grants or desktop behavior.
+Run `/computer setup` in the local lunR terminal. Setup verifies and installs the
+bundled runtime without downloading code, capturing the screen, or operating an
+application. It is unavailable in headless and gateway sessions.
 
-## Tools and permissions
+Windows needs an active, unlocked desktop. On Apple Silicon macOS, setup prints
+the exact installed `CuaDriver.app` path. Add that app to Accessibility and
+Screen & System Audio Recording in System Settings > Privacy & Security, then
+restart lunR. Older macOS versions call the second grant Screen Recording.
+Only the user can grant these permissions. Setup leaves an existing
+`/Applications/CuaDriver.app` alone.
 
 Computer use and Allow foreground control default to on. Windows x64/arm64 and
-Apple Silicon macOS expose `computer_load` before the first model request.
-The runtime loads only when a desktop operation needs it. Linux and Intel macOS
-have no default discovery tool.
-
-Loading activates app/window discovery, accessibility and image observation,
-single/right/double clicks, complete drags, scrolling, keys and modifier
-shortcuts, Unicode text, app launch, window management, and workflow release.
-Use these tools on the computer running lunR. Gateway sessions control the
-gateway host, not the Telegram or Discord client's machine.
-
-Prefer accessibility and background window input. Request window foreground
-input only after a background failure and a fresh observation. Primary-desktop
-input has no background route and requires `desktop=true` and `foreground=true`.
-Foreground off blocks desktop input, explicit foreground window input, app
-launches, and every window-management operation. Background delivery cannot
-prevent an application from changing its own focus.
-
-`computer_window` requires an exact window target and has no per-call foreground
-or desktop option. It moves/resizes with `action=frame`, or activates the exact
-window with `action=focus`. Minimize/restore invokes the supplied, freshly
-observed accessibility window-control element. The pinned driver has no portable
-minimize/restore RPC. If the control or minimized window cannot be observed, use
-freshly observed desktop controls rather than guessing a shortcut or window id.
-Text and keys can target an accessibility element, window-image coordinates,
-or the observed focused field. Desktop keyboard input targets the observed
-focused field; changing focus needs a separate grounded click.
-
-Manual asks before every computer call except `computer_end`, which only releases
-the workflow and never needs approval. Observation still requires approval.
-Plan permits relevant observation and workflow release but blocks mutation. Auto needs no
-lunR per-call prompt for requested, implied, or necessary GUI work. In Yolo,
-ask first when an otherwise non-GUI task newly requires GUI. This intent rule
-is agent guidance, not a natural-language authorization classifier.
-
-Native tools are excluded from children and also refuse child execution.
-Shell-capable children are not OS-sandboxed. No generic MCP registration or
-raw driver policy, update, recording, or administrative tool is exposed.
-
-## Grounding and outcomes
-
-Each observation invalidates the previous token before contacting the driver.
-A token identifies one exact window or the primary desktop, expires after thirty
-seconds, and permits one action. Accessibility input includes the driver's
-snapshot id. Structured refusals count as refusals even without MCP `isError`.
-Partial and unverifiable outcomes remain visible; transport success is not
-proof of an application change.
-
-Window PNGs are capped by the driver at 1024 pixels on their long edge.
-Window coordinates use that returned image, without another resize. Both pinned
-platform implementations retain the capture resize ratio for later pixel input.
-The adapter checks PNG dimensions and refuses inconsistent pixel grounding. Desktop
-images are resized to at most 1024 pixels locally. Their token records separate
-x/y ratios back to the driver's native desktop image. Coordinates outside the
-returned image are rejected. Pixel and desktop operations require an
-image-capable current model; accessibility-only observation remains available.
-
-Observe after every action. A timeout or cancelled call may already have
-changed the application. Never retry input blindly. Cancelling the MCP request
-does not retract input already delivered to the OS. Normal shutdown asks the
-owned runtime to drain and exit; forced process termination cannot prove that
-all held input was released. Live gesture cancellation remains an acceptance
-gate.
-
-## Ownership and lifecycle
-
-An OS-account lease holds the desktop across observe/action calls. Competing
-workflows get busy rather than queueing; calls within one workflow serialize.
-The lease uses the OS account home, not the selected lunR settings profile.
-One short cross-process acquisition lock protects creating, updating, and deleting
-the owner record. Updates replace the file atomically. Runtime installation uses
-a separate lock and never replaces an existing runtime. A live owner is never displaced because its heartbeat is late.
-After MCP initialization and before any driver tool call, the adapter records
-the transport PID and, on macOS, the daemon PID in that lease. Missing PIDs or
-failure to record ownership block tool dispatch. Driver-internal helper lifetime
-remains part of the unverified native shutdown acceptance gates.
-A crash during initialization can leave an unrecorded, idle runtime, but it has
-received no desktop action. Recovery requires both the owner and its recorded
-runtimes to have exited.
-PID reuse can conservatively leave the desktop busy rather than kill another
-process. A malformed owner record also fails closed.
-
-`computer_end`, cancellation, agent end, settings changes, and session shutdown
-close the owned runtime before releasing its lease. Queued operations cannot
-survive cancellation. Settings disable removes active tools immediately;
-session replacement discards loaded tools and grounding. The first-request
-hook also reapplies the loaded roster after extension registration refreshes it.
-If shutdown cannot be confirmed, the lease stays held. Confirm that the owned
-runtime has stopped before restarting the owning lunR process.
-
-Fresh gateway cron sessions get explicit permission contexts from the configured
-default mode. They inherit neither gateway approvals nor its interactive
-approval handler. Missing approval reports blocked. Session shutdown runs before
-context disposal, including partial extension-bind failure. TUI cron continues
-to use its live session mode.
-
-## Runtime and packaging
+Apple Silicon expose `computer_load`; detailed tools load on demand. Linux and
+Intel macOS have no native discovery tool. All computer tools except release
+require an image-capable model. There is no text-only accessibility fallback.
+Gateway sessions operate the gateway host, not the chat client's device.
+
+Manual approves observation and input. `computer_end` releases without approval.
+Plan allows relevant observation and release, but blocks mutation. Auto allows
+requested, implied, or necessary GUI work without lunR per-call prompts. In
+Yolo, ask before introducing GUI work into an otherwise non-GUI task. These
+intent rules are agent guidance, not a natural-language authorization classifier.
+
+Prefer background window input. Foreground window input requires a verified
+background failure and a fresh image. Desktop input requires `desktop=true` and
+`foreground=true`. Disabling foreground control blocks desktop input, foreground
+window input, launch, and window management. An application can still change its
+own focus after background input.
+
+Native tools are excluded from children and refuse child execution. Children
+with shell access are not OS-sandboxed. No raw driver administration, update,
+recording, or permission tool is exposed.
+
+## Observe, act, inspect
+
+1. Use `computer_apps` for app identities or windows for a PID. Results allowlist
+   at most 50 rows and truncate titles to 240 characters. Pass `next_offset` as
+   `offset` with the same PID selection to retrieve more apps or windows. Lists
+   refresh per call, so changing native order can shift page boundaries. PID zero
+   identifies an installed app that is not running. Window `bounds` are native
+   geometry, not screenshot coordinates.
+2. Use `computer_observe` with an exact `pid` and `window_id`, or `desktop=true`.
+   The result contains one image and a short coordinate/token record.
+3. Choose one action from that image. Pass its `observation` token and coordinates
+   in the returned image. The workflow applies the mapping; do not scale twice.
+4. Inspect the post-action image before continuing. The tool executes one action
+   and captures the same target once. It never polls or retries input internally.
+5. Call `computer_end` when finished.
+
+The token lasts 30 seconds, belongs to one exact target, and permits one action.
+Every new observation invalidates the previous token before capture. Failed,
+cancelled, or malformed captures issue no token. Old tokens cannot be replayed,
+including after a successful action returns a new image.
+
+Supported input is single, double, and right click with modifiers, a complete
+press-drag-release gesture, scrolling at image coordinates, Unicode text, and
+keys or modifier shortcuts. Window text/keys can use image coordinates or the
+observed focused field. Desktop text/keys use the observed focused field only;
+change focus with a separate grounded click.
+
+`computer_window` supports `frame` in native window-bounds units and `focus` on
+an exact observed window. Minimize/restore uses a grounded image click on a
+visible control. The pinned driver has no portable minimize/restore RPC.
+`computer_launch` returns bounded app metadata, not an inferred input target;
+capture an exact window before acting.
+
+A successful transport or a changed image does not prove the intended application
+effect. Results preserve partial/unverifiable outcomes and bounded refusal codes.
+When input returns but its post-image fails, the tool reports possible effects
+and stops the workflow. Capture again before deciding; never repeat input blindly.
+After an unchanged post-image, the same action against identical captured pixels
+is refused. Click signatures normalize omitted left-button/single-click/empty
+modifier defaults and modifier order. Three consecutive unchanged full observations
+stop polling in that workflow. Crops are explicit requests, not an automatic retry loop.
+
+Partial typing retains validated `requested_chars`, `delivered_chars`, `retryable`,
+and `retry_from_character` when supplied by the driver. Counts must be safe integers
+within the submitted text's Unicode code-point length, capped at 20000; the retry
+index must equal the delivered count. The index is zero-based in Unicode code
+points, not UTF-16 units. Verify the field in a fresh image before considering a
+remaining suffix. `retryable` is driver advice, not permission or proof that
+repeating input is safe. The workflow never retries typing automatically.
+
+## Image contract and cost limits
+
+Window capture requests `include_accessibility_tree:false` and
+`include_screenshot:true`. Neither native accessibility trees nor duplicate raw
+JSON reach the model. The macOS driver still reads minimal native accessibility
+facts for window identity and background-input safety. Windows window discovery
+can use UIA as a fallback. Image-only describes application observation sent to
+the model, not the removal of every native accessibility API call.
+
+Window capture requests a 2560-pixel maximum. The runtime can impose a lower
+configured ceiling, so this is not a promised capture resolution. The workflow
+checks actual PNG dimensions against native screenshot metadata and rejects
+invalid frames. Primary-desktop capture is tree-free and uses the native PNG.
+Desktop coordinates map back to that PNG once; macOS `scale_factor` is not an
+additional multiplier.
+
+Returned images have a maximum 1280-pixel edge, one million pixels, and 1.5 MiB
+of base64 payload. The existing image processor bounds dimensions and encoding
+size. The workflow refuses images it cannot decode or map. Source PNGs also have
+allocation limits. These are engineering bounds, not measured token savings.
+
+For small text or controls, request `crop:{x,y,width,height}` with the latest
+observation token. The rectangle uses that returned image's pixels. The workflow
+captures fresh pixels, maps the rectangle into the full capture, and sends only
+the crop. Its record gives the source dimensions, crop offset, and separate x/y
+ratios. Changed source dimensions or reported window bounds reject the crop;
+request a full image again. Cropping cannot recover detail absent from the native
+capture. Post-action captures return the full target so dialogs outside a crop
+remain visible.
+
+Saved sessions retain the returned screenshots. Provider-facing screenshot
+history also accumulates until normal compaction. This change does not prune
+user images, rewrite saved sessions, or implement a generic rolling history
+filter. A targeted `context` hook could remove old computer screenshots while
+leaving sessions intact, but a rolling cutoff changes an earlier prompt prefix
+and can invalidate cached input. That tradeoff needs approved provider measurements
+before adopting a retention policy. Image-only is not automatically cheaper than
+text. Current cost controls bound each new payload, remove tree/JSON duplication,
+and combine one action with its post-image.
+
+## Cursor status
+
+Cursor animation remains a separate native-runtime decision. The inherited
+runtime launch still uses `--no-overlay`. Upstream Windows drag animation uses a
+timer separate from actual input, and desktop pointer movement can teleport.
+This branch does not claim smooth actual-cursor motion or synchronized drag
+feedback. Any eventual animation must stay local, preserve full gestures and
+cancellation, and send zero intermediate frames to the model.
+
+## Ownership and cancellation
+
+An OS-account lease spans observations and actions, independent of settings
+profiles. Competing workflows receive busy rather than queueing. Calls within a
+workflow serialize. One cross-process lock covers creation, atomic replacement,
+and deletion of the owner record. A separate lock protects runtime installation.
+A live owner is not displaced because its heartbeat is late.
+
+After MCP initialization and before any driver tool dispatch, the adapter records
+the transport PID and, on macOS, daemon PID. Missing identities or failed lease
+updates refuse dispatch. Recovery requires both owner and recorded runtimes to
+have exited. PID reuse and malformed owner records fail closed. A crash during
+initialization can leave an unrecorded idle runtime that received no input.
+
+Release, cancellation, agent end, settings changes, and session shutdown close
+the owned runtime before releasing the lease. Queued work cannot survive
+cancellation. Unconfirmed shutdown retains ownership. Cancellation cannot retract
+already delivered input, and forced termination does not prove held input was
+released. Driver-internal helper lifetime and held-input cancellation still need
+native acceptance.
+
+Gateway cron creates fresh permission contexts with the configured default mode,
+without gateway approvals or its approval handler. Missing approval blocks calls.
+Session shutdown precedes disposal, even after partial extension binding failure.
+TUI cron continues to use its live permission context.
+
+## Runtime and distribution
 
 The development pin is [CuaDriver 0.28.1](https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.28.1),
-source `d8028a7943087ee258dc1b4d19dc12a7cd27669c`. This exact prerelease and its
-three archive hashes are approved for development-channel distribution only.
-`scripts/computer-use-release.json` is the authoritative archive inventory.
-The upstream MIT license is included under `native/computer-use`.
-
-The runtime never downloads an executable. It resolves the host's optional
-payload package, or the matching archive beside a standalone binary. It verifies that archive,
-extracts a fresh reference tree, and checks every cached file and helper against
-that tree before execution. Redirected install paths and escaping symlinks are
-rejected. Concurrent installers do not overwrite each other. A modified or
-older cache is refused rather than overwritten. After confirming no runtime is
-active, remove the inactive lunR runtime directory to reinstall it.
-
-Windows uses the system `tar.exe`, not a `PATH`-selected extractor, and launches
-`mcp --direct --embedded --no-overlay`. A bounded, hidden system PowerShell
-helper checks WTS session activity and the input desktop name before admission.
-It refuses session zero, disconnected sessions, and a non-Default or inaccessible
-input desktop. It reads metadata only and never switches desktops. The isolated
-runtime profile avoids the user's Cua config. Both platforms remove inherited `CUA_*` settings and explicitly
-set standard permission mode, disable unrestricted mode, and set
-`CUA_DRIVER_RS_TELEMETRY_ENABLED=false` and `CUA_DRIVER_RS_UPDATE_CHECK=false`.
-
-macOS preserves the signed `CuaDriver.app` at the stable lunR-owned path
-`~/.lunr/desktop/runtime-darwin-arm64/CuaDriver.app` and verifies its signature
-with `codesign --verify --deep --strict`. It never re-signs the bundle.
-LaunchServices selects that exact app path with `open -n -g -W -a`, not its
-shared bundle id or the user's `/Applications` installation. Explicit `--env`
-arguments pass telemetry/update/permission settings and a private HOME to the
-daemon. The private HOME also isolates the upstream default PID/config files.
-A private Unix socket carries the MCP proxy connection. A private stdin FIFO
-and the pinned `--parent-liveness-stdio` option tie daemon lifetime to lunR.
-Shutdown uses the private endpoint's PID-bound request and waits for the owned
-app to exit. Startup and shutdown have time limits. These construction and
-cleanup paths have local tests, not macOS execution evidence.
-
-Release staging creates `@ashx-j/lunr-computer-win32-x64`,
-`@ashx-j/lunr-computer-win32-arm64`, and
-`@ashx-j/lunr-computer-darwin-arm64`. Each package contains one unchanged archive,
-the MIT license, and a manifest with `os` and `cpu`. There are no install scripts.
-The payload packages follow the CLI release version, independently of the upstream
-runtime version. The staged CLI declares exact optional versions. npm installs
-only the matching payload; `--ignore-scripts` works. Missing optional dependencies
-leave the CLI usable and produce a reinstall instruction when computer use needs
-the runtime. Unsupported hosts have no native discovery tool.
-
-The CLI tarball is about 10.7 MB, without runtime archives. Packed payload sizes
-are about 28.8 MB for Windows x64, 27.2 MB for Windows arm64, and 69.8 MB for
-Apple Silicon. These are decimal sizes, not extracted runtime sizes.
-
-Workspace manifests and locks keep unpublished native dependencies out of
-ordinary developer installs. `scripts/publish.mjs` injects them into the staged
-CLI shrinkwrap and standalone installer lock. Public lock rewriting updates both
-package names and tarball filenames. Publication validates all seven packages,
-then publishes payloads before the CLI. Dev staging uses exact
-`0.2.19-dev.<run>.<attempt>` versions throughout package manifests, shrinkwrap,
-and installer locks. It publishes `@ashx-j/lunr-dev` with its own `latest` tag;
-shared libraries and runtime payloads use `dev` tags. Stable tags stay unchanged.
-Production publication still requires separate approval and an unpublished
-stable CLI version.
-
-`scripts/build-binaries.sh` and `copy-binary-assets` copy only the selected opaque
-archive into `native/computer-use` beside the executable. They preserve the macOS
-archive without extracting or signing it. Routine builds stay offline. Release
-preparation may fetch only the pinned official archives, then verifies their
-sizes and hashes. Stable npm and GitHub binary publication stop on the current
-development-only approval. The `dev/tui` workflow may publish the explicitly
-requested npm dev channel.
-
-An installed payload package must match the CLI version. A CLI upgrade that keeps
-the same runtime bytes can reuse the verified cache. A changed or older cached
-runtime fails closed rather than replacing a possibly running app. After all
-owned processes stop, removing the inactive lunR runtime directory allows a fresh
-extraction at the same stable macOS path.
-
-## Verification and remaining gates
-
-Local verification includes actual Windows initialize/tools/list and a
-metadata-only `health_report`, with capture and accessibility checks excluded.
-The binary reported 0.28.1 and 57 tools. Health results include human-readable
-text and `structuredContent`. Its `session_active` check reports MCP activity,
-not an unlocked or input-ready desktop. A separate real Windows metadata probe
-confirmed an active session and Default input desktop without screen, AX, or
-input calls. Snapshot identity and operation mapping
-were checked against the exact released tool schemas and source; no live
-snapshot was taken.
-
-Focused tests cover policy, result interpretation, image coordinate mapping,
-new GUI operation mapping, interrupted initialization, partial shutdown,
-settings/session tool rosters, real separate-process contention and death,
-orphan-runtime ownership, cache tampering, redirected paths, concurrent
-extraction, and the fresh gateway cron factory's approval/disposal lifecycle.
-The dev review passes 167 focused Vitest tests across 14 files and
-eight archive/package tests. All five offline production builds, including the
-coding-agent Node bundle, pass. Touched native TypeScript lint and the repository's
-relative-import, workflow-publication, browser-smoke, and diff checks pass.
-
-A loopback fixture registry served all seven public-name tarballs without changing
-their bytes. A fresh Windows install used `--ignore-scripts`, fetched only the host
-payload, then passed archive validation and first-paint/first-request fixtures
-after relocation. Separate npm installs selected the correct package for each
-supported OS/CPU combination and no package for Linux. An omitted-optional install
-returned the expected missing-payload error. The shipped installer lock passed
-`npm ci --ignore-scripts`. Standalone asset tests copied and rechecked all three
-opaque archives. No installed app or desktop operation ran in these packaging
-tests. Cross-platform npm selection on Windows is not macOS runtime acceptance.
-
-The first-request fixture strips inherited subagent environment state before
-checking the default tool inventory. The supported-host inventory includes only
-`computer_load`; detailed computer tools remain lazy. The unsupported-host
-baseline is unchanged.
-
-To repeat local distribution checks after the offline build, prepare the pinned
-archives with `scripts/bundle-computer-use.mjs`, create an empty temporary pack
-directory, then run:
-
-```sh
-node scripts/generate-computer-use-manifest.mjs --check
-node --test scripts/check-computer-use-release.test.mjs scripts/computer-use-packages.test.mjs
-node scripts/publish.mjs --channel dev --version 0.2.19-dev.0.1 --dry-run --pack-dir /absolute/temporary/pack-directory
-node scripts/check-computer-use-install.mjs /absolute/temporary/pack-directory
-```
-
-The install checker uses a loopback registry for the local public packages and
-npm's public registry for external dependencies. It isolates npm configuration,
-cache, and install directories and removes them afterward. It does not publish.
-These checks do not certify desktop behavior.
-
-External acceptance gates remain:
-
-- Windows locked, disconnected, UAC, and integrity-state acceptance for the
-  metadata admission check and the actual driver.
-- Authorized native and Electron fixture desktops, Unicode, moved/resized
-  windows, display scaling, stale accessibility handles, application exit,
-  outcome verification, and cancellation during held input.
-- Real macOS signature/notarization, TCC, LaunchServices/FIFO environment,
-  coexistence, upgrade, and shutdown acceptance.
-- Real macOS and Windows arm64 runtime installation and launch. Their npm
-  selection and unchanged archive copying pass locally, but their hardware
-  execution and upgrades remain unverified.
-- Full standalone executable acceptance. Payload asset copying passes; this
-  verification did not compile and exercise every Bun target.
-
-## Privacy and rollback
-
-GUI actions are outside lunR's filesystem rollback. Images, accessibility text,
-and typed text can enter selected-provider requests and saved sessions.
-Disabling driver telemetry does not disable lunR session storage. Application
-content is untrusted task data, never authorization. OS permissions, locked
-desktops, UAC, and integrity restrictions still apply.
+source `d8028a7943087ee258dc1b4d19dc12a7cd27669c`. Archive identities and approval
+are in `scripts/computer-use-release.json`; `release.generated.ts` derives from
+it. The upstream MIT license is under `native/computer-use`. No runtime pin or
+native binary changed in the image-only workflow work.
+
+The runtime resolves the host's optional payload package or matching archive
+beside a standalone executable. It verifies the archive, extracts a fresh
+reference tree, and checks cached files/helpers against it. Redirected paths and
+escaping symlinks are refused. Installers do not overwrite an existing runtime.
+After confirming all owned processes stopped, an inactive cache can be removed
+for reinstallation. Runtime code is never downloaded at first use.
+
+Windows uses system `tar.exe` and an isolated `mcp --direct --embedded
+--no-overlay` process. A hidden system PowerShell metadata probe refuses session
+zero, disconnected sessions, and inaccessible/non-Default input desktops. It
+never switches desktops. Both platforms isolate profiles, strip inherited
+`CUA_*`, set standard permission mode, and disable telemetry/update checks.
+
+macOS preserves the unchanged signed app at its stable lunR-owned path, verifies
+its signature with `codesign --verify --deep --strict`, and launches that exact
+path through `open -n -g -W -a`. A private HOME, socket, stdin FIFO, and
+`--parent-liveness-stdio` isolate daemon state and lifetime. Shutdown uses the
+private PID-bound endpoint and waits for the app to exit. No re-signing occurs.
+
+Release staging creates exact-version host-specific optional payload packages.
+They contain unchanged archives and no install scripts. Workspace manifests keep
+unpublished payload dependencies out. Standalone asset copying selects one
+opaque archive. Stable publication remains gated on production approval and a
+new CLI version. This integration retains dev-channel CLI naming, update routing,
+and exact-version package/lock rewriting. Dev publication uses `latest` only for
+`@ashx-j/lunr-dev`; shared libraries and payload packages use the `dev` tag. Stable
+tags remain unchanged. The user requested a dev-channel update and installation,
+with automated release checks complete. Publication and global installation remain
+separate distribution steps.
+
+## Pending acceptance
+
+Source tests cover image-only capture flags, metadata allowlists, image/crop
+mapping, fresh tokens, single-action post-images, bounded unchanged behavior,
+uncertain outcomes, permissions, and ownership. Source-review fixes add equivalent
+click defaults, app/window pagination, and Unicode partial-typing recovery coverage.
+The focused 23-suite run passes 265 tests, including a real Photon PNG crop
+fixture that checks output pixels and coordinate mapping. All five offline package
+builds and the Node bundle pass. Clean-parent first-request capture confirms that
+`computer_load` is the only addition to the unsupported-host tool inventory; the
+supported-host fingerprint is current. Private prompt and tool snapshots remain
+local validation artifacts.
+
+Seven dev package tarballs pass isolated installation and relocation checks,
+host-only payload selection, archive verification, omitted-optional handling, and
+the standalone installer lock. First-paint and first-turn subagent, MCP, LSP, and
+local HTTP fixtures pass without remote inference. These checks do not launch the
+native driver or prove application effects.
+
+Explicitly authorized desktop acceptance remains required. Native gates include
+Windows locked/UAC/integrity states,
+Electron/native apps, display scaling and moved/resized windows, Unicode,
+held-input cancellation, and macOS TCC/LaunchServices/FIFO/shutdown on hardware.
+Cursor/runtime changes need a separate scoped decision before implementation.
+
+## Privacy
+
+Images, window titles, and typed text can enter selected-provider requests and
+saved sessions. Disabling driver telemetry does not disable lunR session storage.
+GUI changes are outside filesystem rollback. Application content is untrusted
+task data, never authorization. OS permissions, locked desktops, UAC, and
+integrity restrictions still apply.

package/docs/features.md

@@ -21,13 +21,31 @@ 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.
 
+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.
 
+### 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.
+
+Asking returns a question ID without waiting. The child receives the question at a safe turn boundary, replies from its current findings, and continues its assigned task. Answers arrive separately from the run's final result and wake an idle parent. A delivery receipt is not an answer. Questions do not change the assignment, broadcast to other children, or restart finished children.
+
+The parent calls `subagent_supervisor({ action: "ask", id, index, reason, message })`. It must select an `index` or private `childId` when several children are running. The child answers with `contact_supervisor({ action: "reply", replyTo: questionId, message })`. If the parent's next decision must wait, `subagent_wait({ questionId })` returns the answer instead of sending a second notification. Read-only children can reply without receiving editing tools.
+
+A child must have an active question-capable input channel. Only one question may be outstanding per child. Questions expire after ten minutes by default, and child termination, failed delivery, process replacement, or parent session replacement cancels pending questions. A wait timeout ends the wait, not the question. Existing blocking child-to-parent requests take priority to avoid mutual waiting.
+
+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.
+
 ## 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. 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 (no leftover `✓ N done` footer).
 - **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.
@@ -83,10 +101,10 @@ Without runnable adapters (enabled platform + resolvable token), `lunr gateway`
 - `/fast [on|off|status]` controls `service_tier: "fast"` for OpenAI Codex subscriptions only. It persists across new sessions, gateway turns, and subagents. Paid `openai` API models do not use it.
 - Footer plan bar prefers a 5h window and falls back to weekly (`planUsageWindow`). In Customize, Plan usage hides the whole segment while Plan bar hides only the █░ fill and keeps the percent.
 - Click a ✻ Thought or tool card to expand/collapse that item. `app.tools.expand` is unbound. `/tree` still uses `ctrl+o` for filters.
-- Smooth streaming (`smoothStreaming`, default off) is **interactive TUI only** (grapheme reveal at ~30 FPS). Print, RPC, and gateway stay unsmoothed.
+- Smooth streaming (`smoothStreaming`, default off) reveals assistant text and thinking in small character batches at about 30 FPS in the interactive TUI. The thinking preview shows the last four revealed lines. Completed thinking collapses after its reveal catches up. Message completion flushes any remaining text immediately. Print, RPC, and gateway stay unsmoothed.
 - Image paste inserts `[image_n]` chips. Windows uses **Alt+V**; VS Code must forward it because it owns Ctrl+V and Alt+V. `/paste-image` bypasses terminal shortcuts.
-- Model tiers: every child launch selects `light`, `standard`, or `heavy`. Configure authenticated models for those routes in `/settings`; a missing, disabled, unauthenticated, or unavailable route fails closed. Per-tier thinking is optional; unset inherits the parent session.
-- Settings tools: `settings_load` is always available to the model. It injects four narrowly scoped tools for model tiers, model instruction subscriptions, rollback behavior, and session retention only after the model requests them.
+- Model selection: every child launch chooses exactly one of `tier: light|standard|heavy` (default) or an explicit `model: provider/id` when the user names a model. Configure tier routes in `/settings`. Optional `thinking` is only valid with an explicit model; tier launches use configured tier thinking. Direct model launches do not require tier mode. Missing, both, inherit, unavailable, or unauthenticated selections fail closed before spawn.
+- Settings changes stay on `/settings`. The agent does not get `settings_load` or other agent-managed settings tools, and direct file-tool writes to lunR `settings.json` are blocked.
 
 ## Updates, catalogs, local models