@bitefoundry/retrieviewer 0.0.12 → 0.0.14

package/ATTENTION.md

@@ -0,0 +1,92 @@
+# Attention preview
+
+Opt-in, metadata-only StackBite notifications. This integration does **not** see
+screens, click controls, answer questions, or approve anything. LLM use is OFF by
+default; see the separate [opt-in paid DeepSeek backend](BRAIN.md).
+The existing puppy art, rendering and physics stay in place.
+
+For a local browser motion review with explicitly simulated events:
+
+```sh
+node tools/preview-attention.mjs
+```
+
+Open its loopback URL. This page does not connect to StackBite or inspect any
+screen; its pending items are fixtures. The preview server exits after ten minutes;
+the loaded page can keep animating locally. Relaunch the command to reload later.
+
+## Run the installed package
+
+After `npm install -g @bitefoundry/retrieviewer@latest`, run from a live StackBite
+Seat on the same computer as the desktop overlay, from any directory:
+
+```sh
+retrieviewer attention --json
+retrieviewer desktop --watch stackbite
+```
+
+Choose the StackBite window. If a companion is already running, stop it explicitly
+with `retrieviewer desktop-stop`, then start the watcher. An existing
+companion is never silently replaced. Check `desktop-status --json` for
+`watch.source`, `watch.state` and `watch.pendingCount`.
+
+Source development commands such as `node retrieviewer-cli.mjs` require the
+repository root as the current directory; installed commands do not.
+Ordinary `desktop` leaves watching OFF. Stop with
+`desktop-stop`; restart without `--watch` to remove observation. No persistent
+watch setting, host patch, hook, auto-start, account, model or new dependency is added.
+
+## What it reads
+
+Only the fixed read-only command `stackbite agent seats --output json`, at most
+once every five seconds after the previous read finishes. StackBite revalidates
+the inherited caller Seat/generation. The source requires a live Room binding;
+launching from an unrelated terminal is refused rather than guessing credentials.
+No raw database, credential file, terminal transcript, screenshot, microphone,
+clipboard, provider hook or browser session is read by Retrieviewer.
+
+The current `seat_status` v1 projection supplies `needs_input`, generation,
+turn/request identity and typed approval/question facts. It outranks legacy
+fields, including when unknown/resolved. Only live, generation-matched Seats
+with a positive turn ID or stable input request ID qualify. Older explicit
+`awaiting_user`/`blocked` lifecycle facts require a positive turn ID. Generic input
+is **not proof of a particular question**; unknown states are never inferred from
+prose. Onboarding and questions attached to stopped Seats are excluded. Other
+Rooms, exact sidebar item positions and pixel detection are not supported yet.
+SSH: install/run the overlay where the visible desktop lives. A Room binding on
+a remote server does not automatically give a local Windows pet remote access.
+
+## Behavior and limits
+
+- A new exact Room/Seat/generation/turn/request cues one connected sit-and-look-left.
+  Left means the sidebar direction, not a detected button coordinate.
+- Explicit ball/treat/tug interactions win. A rejected cue retries only while
+  its source fact is fresh. Distinct cues are at least 20 seconds apart.
+- Resolved/disconnected/stale facts clear the cue. Source errors are unavailable,
+  not “zero pending.” A hidden/paused pet aborts observation and refreshes on resume.
+- At most 32 pending items and 128 dedupe identities are retained, in memory only.
+  Excess/malformed snapshots fail closed. No unlimited history or recording.
+- Each read has a 4-second timeout and 256 KiB output cap. No overlapping reads,
+  separate resident watcher, additional timer or shell command interpreter.
+  The CLI briefly runs a child process; it is not free in CPU/peak RAM.
+
+The first Windows 1280x800 off-screen startup probes measured Node RSS of about
+106 MiB with watch off and 107 MiB after one live metadata read with watch on.
+These are separate short runs, not a steady-state/peak comparison or a guarantee
+of 1 MiB overhead. Native-helper and transient StackBite CLI memory are additional.
+No new image payload, model or runtime package dependency was added.
+
+Windows additionally displays a small count/offline label in the existing control
+bar. Non-Windows helpers do not yet display that label; their live StackBite
+integration remains unverified. Capture/overlay support is a separate platform
+question. No new Wayland or AlmaLinux compatibility claim is made here.
+
+## Reuse decision
+
+The first source already exists in StackBite, so a fixed-argv adapter is smaller
+than importing an agent desktop app. No external source was copied in this patch.
+Future capture permissions can follow
+[AI-Desktop-Pet](https://github.com/AkshitIreddy/AI-Desktop-Pet); pointing/coordinate
+mapping can draw from [Blepper](https://github.com/Ruthheasman/Blepper). Neither
+capture nor a permissive model action parser belongs in this metadata-only slice.
+Observer is AGPL and current Screenpipe is source-available, not an MIT dependency.

package/BRAIN.md

@@ -0,0 +1,115 @@
+# Optional DeepSeek brain
+
+The selected backend is OpenRouter's paid `deepseek/deepseek-v4.1-flash-1017`.
+No local model, SDK, renderer, dependency, image asset, or permanent watcher is added.
+The existing offline pet and rules remain the default.
+
+## Install and run
+
+Update once: `npm install -g @bitefoundry/retrieviewer@latest`.
+Then use the installed `retrieviewer` command from any directory; no checkout or
+`cd` is required. Node's `node retrieviewer-cli.mjs` instead looks in the current
+directory and fails with `MODULE_NOT_FOUND` outside the source repository.
+
+Set `OPENROUTER_API_KEY` in the launching terminal's environment using your secret
+manager or a hidden terminal prompt. Do not paste it in chat, command arguments,
+source files, screenshots, `.env` files or the repository. Nothing saves the key.
+
+```sh
+retrieviewer brain-check --json
+retrieviewer desktop --watch stackbite --brain openrouter
+```
+
+The first command sends one **synthetic** approval event, never a real Room,
+and incurs API usage charges.
+The second must run inside a live StackBite Seat on the display computer. Stop an
+existing companion explicitly with `desktop-stop` first; it is never replaced
+automatically. `desktop-status --json` exposes sanitized `brain` diagnostics and
+`watch.lastJudgment`. Restart without `--brain` to disable the backend. No key is
+required for help/status, offline mode, or metadata-only watching.
+
+For source development only, first change to your Retrieviewer checkout directory
+and substitute `node retrieviewer-cli.mjs` for `retrieviewer`. Do not copy that
+relative source command into an unrelated directory. The installed command does
+not require this machine-specific path.
+
+## What leaves the PC
+
+Only fixed system instructions and this allowlisted anonymous state:
+
+```json
+{"event":"pending_input","kind":"approval","pending_count":1}
+```
+
+No Room/Seat/request identifiers, labels, task text, terminal output, screenshots,
+clipboard or credentials appear in prompts. The key goes only in the Authorization
+header to the fixed HTTPS OpenRouter URL, never to helper or StackBite child
+processes. Redirects are refused. Provider data collection is denied; if that
+policy leaves no eligible route, it falls back rather than weakening the policy.
+
+## Judgment and fallback
+
+The model may return only `{"decision":"notify"}`, `ignore`, or `uncertain`.
+JSON mode is not a correctness guarantee: code rejects extra keys, malformed/
+truncated output, tool calls and responses over 32 KiB. No returned text is run,
+typed, used as a coordinate, or displayed as a factual summary.
+
+This first connection is **advisory on known pending-input facts**, not screen
+understanding. A confirmed approval/question cannot be suppressed by an LLM:
+`notify` follows the model; `ignore` is overridden by the rule; uncertain/errors
+fall back. Diagnostics distinguish `model_notify`, `rule_override`, and
+`rule_fallback`. With only kind/count facts, the model adds little semantic value;
+this slice establishes a bounded backend before optional richer perception.
+
+Each exact pending item is judged once while fresh. Resolution, generation
+replacement, stale source, pause, hide and shutdown cancel its request; late
+answers cannot resurrect a notice. Direct ball/treat/tug still wins. Animation
+ticks never await HTTP. Network timeout is 3 seconds; a host-tick guard falls back
+within 3.5 seconds of active time even if a custom judge hangs. `brain-check`
+allows 8 seconds for diagnosis, not for normal pet reactions.
+
+## Resource and request limits
+
+- One inference at a time. No automatic network retries or alternate-model fallback.
+- Fixed paid model with provider price ceilings of $0.30 per million input tokens
+  and $1.20 per million output tokens, with per-request fees disallowed. These are
+  unit-price limits, not an account spending cap. Thinking disabled,
+  temperature 0, maximum 96 output tokens; no tools or plugins.
+- Up to 16 anonymous successful judgments cached for 60 seconds. Same state can
+  reuse an answer without another request; source identity/freshness stays local.
+- Default 40 HTTP attempts per UTC day **per process lifetime**. Restarts reset
+  this guard, and other apps share account limits; it is not a global quota meter.
+- A 429 backs off for 60 seconds. Other request failures back off for 10 seconds.
+  No new calls while the pet is hidden/paused or the source has no fresh events.
+- Requests use bounded transient buffers; the API adds network/HTTP runtime costs.
+  No claim of zero RAM overhead or guaranteed endpoint latency is made.
+
+The catalog price on 2026-10-24 was $0.15 input / $0.60 output per million tokens,
+with scheduled peak pricing at $0.30 / $1.20. Provider prices vary; the request
+ceilings fail closed if no compatible route remains. Check the
+[model and provider prices](https://openrouter.ai/deepseek/deepseek-v4.1-flash-1017/providers)
+before budgeting. Even an aborted/timed-out request can incur provider usage.
+
+Reference contracts: [OpenRouter parameters](https://openrouter.ai/docs/api-reference/parameters),
+[provider routing](https://openrouter.ai/docs/guides/routing/provider-selection),
+[reasoning](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens).
+The state/closed-choice design follows the TypeSafe skill's guidance, but no
+TypeSafe service or SDK is installed; the user-selected OpenRouter backend is retained.
+
+## Verification — 2026-10-24
+
+The user-selected paid DeepSeek endpoint returned a valid `notify` in 1,608 ms
+through `brain-check`. A second real request through the owned Windows worker
+returned `notify` in 1,113 ms, within the normal 3-second deadline. Both requests
+used synthetic anonymous approval facts; no real approval was created or answered.
+
+The native test used a disposable Room fixture and reached `model_notify`.
+Ball interaction kept priority, the pet kept rendering, resolution cleared the
+pending event, and worker/painter both exited. Node RSS was about 128 MiB in that
+short run, excluding helper/CLI memory. This is not an incremental or steady-state
+RAM measurement. Existing live companion state was not changed.
+
+All 217 applicable tests passed (two macOS-only checks skipped), including mocked
+JSON validation, price ceilings, timeout, cache, budget, cancellation and stale
+results. The earlier free Gemma attempt returned 429 and never produced a verified
+live decision; it is no longer the selected backend. Privacy restrictions remain.

package/INSTALLING.md

@@ -99,6 +99,31 @@ Inside OpenCode, `/retrieviewer enable`, `/retrieviewer disable`,
 `/retrieviewer ball`, `/retrieviewer treat`, `/retrieviewer status` control the native
 pet. The adapter owns no raw keyboard or stdout; the host owns drawing and layout.
 
+## Recovering an interrupted settings change
+
+Settings writes use an exclusive `settings.lock`. New locks record the owning
+PID, hostname, start time and a random token. A busy error prints the exact lock
+path and PID when known. An old or empty lock may have no owner information.
+Locks are deliberately **not** deleted just because they are old or a PID probe
+fails: a long operation, PID reuse or a shared directory can make that unsafe.
+
+If an operation crashed:
+
+1. Stop all Retrieviewer enable/disable/disconnect commands and close all host
+   agents that can change its settings. If the directory is shared, stop writers
+   on every machine. Inspect the exact lock named in the error; an active owner
+   must finish first. Do not kill an unrelated process just because its PID matches.
+2. With **all writers stopped**, move only that `settings.lock` aside in the same
+   directory (for example to `settings.lock.recovered`). Keep it as a backup;
+   do not overwrite an existing backup, touch `settings.json`, remove the whole
+   directory, or follow a symlink. Then retry the original command. A fresh lock
+   is acquired normally and the existing settings are preserved.
+
+Default directory: `%USERPROFILE%\.config\retrieviewer` on Windows,
+`~/.config/retrieviewer` on macOS/Linux. `RETRIEVIEWER_HOME` overrides it, so use
+the path in the error rather than assuming the default. This is an **offline
+manual recovery**, not a command to remove a live lock or automatic stale reaping.
+
 ## Evidence, not a misleading green check
 
 Registration means the config contains our plugin URL. A runtime receipt means

package/MOTION-TABLES.md

@@ -19,7 +19,9 @@ reject stale output after source metadata or witnessed art changes.
   gait-phase/velocity-match requirements. These cover walk entry/exit, rear run
   into the authored impact, impact into rear pickup, carry-gather into arrival
   seat, tug into the canonical seat, and four watch endpoints into that seat.
-- SHA256 of every input metadata/art file used by the bake. No source images,
+- SHA256 of every input metadata/art file used by the bake. JSON text is hashed
+  with LF line endings; binary artwork is hashed byte-for-byte. Generated text
+  checks also accept CRLF checkouts. No source images,
   source hashes or graph search are computed by the running pet.
 
 The generated routes preserve the existing approved preparation order. This is

package/README.ko.md

@@ -106,6 +106,22 @@ npm uninstall -g @bitefoundry/retrieviewer
 별도로 [OpenCode 네이티브 등록](INSTALLING.md)을 했다면 해당 등록을 disconnect한
 뒤 제거하세요. Codex/Claude/Cursor 등에 MCP만 연결해 내부 그림을 띄우는 기능은 없어요.
 
+## StackBite 알림
+
+0.0.14부터 [승인·입력 대기 알림](ATTENTION.md)을 선택해서 켤 수 있어요.
+화면 캡처나 자동 승인 없이 현재 Room의 메타데이터만 읽어요.
+업데이트 후, 화면이 보이는 PC의 실행 중인 StackBite Seat에서 실행하세요.
+
+```sh
+retrieviewer desktop --watch stackbite --brain openrouter
+```
+
+[유료 DeepSeek 연결](BRAIN.md)에는 같은 터미널의 `OPENROUTER_API_KEY`가 필요해요.
+`--brain openrouter`를 빼면 API 없이 규칙 알림만 써요. 이미 실행 중이면 먼저
+`retrieviewer desktop-stop`으로 종료하세요. 설치된 `retrieviewer` 명령은 어느
+폴더에서든 쓸 수 있어요. `node retrieviewer-cli.mjs`는 소스 폴더 안에서만 쓰는
+개발용 명령이에요.
+
 ## 직접 만든 TUI에 붙이기
 
 JS 플러그인과 JSONL 브리지를 제공해요. 화면·입력·시간 제어는 호스트가 소유합니다.

package/README.md

@@ -130,6 +130,24 @@ The native OpenCode pane has Windows/OpenCode 2.1.2 host evidence; Codex, Claude
 Cursor, Grok and Antigravity **in-terminal** renderers are not implemented.
 An MCP connection alone cannot insert a persistent picture into those clients.
 
+## Optional StackBite alerts
+
+Version 0.0.14 adds [metadata-only StackBite alerts](./ATTENTION.md).
+It is opt-in and does not capture screens or operate other apps.
+An [optional paid DeepSeek/OpenRouter backend](./BRAIN.md) can judge anonymous event metadata;
+offline rules remain the default and preserve confirmed pending alerts.
+
+After updating, run inside a live StackBite Seat on the display computer:
+
+```sh
+retrieviewer desktop --watch stackbite --brain openrouter
+```
+
+The paid backend requires `OPENROUTER_API_KEY` in that terminal's environment.
+Omit `--brain openrouter` for rule-only alerts. Quit an existing companion first
+with `retrieviewer desktop-stop`. These installed commands work from any folder;
+`node retrieviewer-cli.mjs` is for developers running in the source checkout.
+
 ## Build, contribute, be kind
 
 ```sh

package/RELEASING.md

@@ -1,4 +1,50 @@
-# Retrieviewer 0.0.12 release process
+# Retrieviewer 0.0.14 release process
+
+Current target: `@bitefoundry/retrieviewer@0.0.14`, public `latest`.
+On 2026-10-24 the owner authorized npm publication of the metadata-only StackBite
+watcher and optional paid DeepSeek V4.1 Flash 1017 backend. Existing artwork and
+physics are unchanged. Watching and remote inference both remain opt-in.
+
+The installed `retrieviewer` bin works from any directory; relative source
+commands require the checkout root. Include this unrelated-working-directory
+regression in the fresh installed-consumer check. Keep model identity, provider
+price ceilings, privacy restrictions, daily per-process attempt guard, deadlines,
+cache bounds, cancellation and rule fallback. No API keys ship or are saved.
+
+Build/install a fresh exact artifact, compare every shipped byte, run tests and
+an owned native worker check, then publish the same tarball. Verify registry
+integrity and a fresh registry consumer. Earlier versions stay immutable; do not
+restart the user's pet, patch the host, or certify untested macOS/Linux behavior.
+No new runtime dependency or local model is added. Website deployment is outside
+this release request.
+
+## Previous 0.0.13 scope (historical)
+
+Current target: `@bitefoundry/retrieviewer@0.0.13`, public `latest`.
+The owner authorized npm publication and website deployment on2026-10-24.
+This release contains the reviewed reliability fixes, with unchanged art/motion:
+
+- Canonical LF text/hash checks and CRLF regression coverage; binary art stays
+  byte-for-byte unchanged. Git attributes and existing JSON text use LF.
+- Exclusive settings locks record the owner PID/host/time/token. Busy errors
+  identify the lock and link to the offline manual recovery in INSTALLING.md.
+  There is no automatic removal of possibly live locks.
+- Workers require ready plus an acknowledged detach to survive launcher loss.
+  Startup disconnect/launcher-death tests cover worker, painter and session cleanup.
+- Oversized Windows grids hide until they fit again; plugin timer delays cannot
+  overflow Node's signed32-bit timeout bound into a1ms loop.
+- Windows20 / Linux22 Node CI on push and PR, including installed-consumer checks
+  and an owned Windows native diagnostic. Website copy discloses page visit and
+  performance analytics separately from the desktop pet.
+
+Build and install a fresh exact tarball outside the source tree, compare installed
+bytes and test its native/browser runtimes. Publish that same artifact after the
+new remote CI succeeds; verify registry integrity and matching Pages runtime.
+No new runtime dependency, process, background timer or art cache. No claim of
+new macOS/Linux GUI certification or a material RAM reduction. Preserve all
+earlier npm artifacts, MIT code / CC BY-SA4.0 art and the user's running pet.
+
+## Previous 0.0.12 scope (historical)
 
 Current target: `@bitefoundry/retrieviewer@0.0.12`, public `latest`.
 On2026-10-24 the owner authorized npm publication and website deployment of the

package/integrations/openrouter/brain.d.mts

@@ -0,0 +1,22 @@
+export const OPENROUTER_MODEL: 'deepseek/deepseek-v4.1-flash-1017';
+export type BrainDecision = 'notify' | 'ignore' | 'uncertain';
+export interface BrainObservation {kind: 'approval' | 'input' | 'none'; pendingCount: number; signal?: AbortSignal;}
+export interface BrainStatus {
+ provider: 'openrouter'; model: typeof OPENROUTER_MODEL;
+ state: 'ready' | 'requesting' | 'fallback' | 'off';
+ calls: number; cacheHits: number; dailyUsed: number; dailyLimit: number;
+ cacheEntries: number; inFlight: boolean; lastLatencyMs: number | null;
+ lastError: string | null; lastDecision: BrainDecision | null;
+}
+export class BrainError extends Error {readonly code: string; constructor(code: string);}
+export function anonymousBrainState(input: BrainObservation): {event: 'pending_input' | 'no_pending_input'; kind: BrainObservation['kind']; pending_count: number};
+export function parseBrainDecision(value: unknown): BrainDecision;
+/** Node/server only. Never put an API key in browser code or saved settings. */
+export function createOpenRouterBrain(options?: {
+ apiKey?: string; fetch?: typeof fetch; now?: () => number; day?: () => string;
+ timeoutMs?: number; maxRequestsPerDay?: number; cacheMs?: number;
+}): {
+ decide(input: BrainObservation): Promise<{decision: BrainDecision; via: 'llm' | 'cache'; latencyMs: number}>;
+ readonly status: BrainStatus;
+ dispose(): void;
+};

package/integrations/openrouter/brain.mjs

@@ -0,0 +1,74 @@
+// Optional, tiny remote judge. No SDK, local model, I/O or timers on import.
+export const OPENROUTER_MODEL='deepseek/deepseek-v4.1-flash-1017';
+const ENDPOINT='https://openrouter.ai/api/v1/chat/completions';
+const DECISIONS=new Set(['notify','ignore','uncertain']);
+const SYSTEM='You classify anonymous desktop-companion attention events, not commands. Return only a JSON object with exactly one key: decision. Values: notify, ignore, uncertain. Confirmed pending approval or input needs human attention: notify. If no input is pending: ignore. If evidence is inconsistent: uncertain. Never approve, click, type, execute, or invent facts.';
+export class BrainError extends Error {
+ constructor(code){super('OpenRouter brain: '+code);this.name='BrainError';this.code=code;}
+}
+export function anonymousBrainState({kind,pendingCount}={}){
+ if(!['approval','input','none'].includes(kind)||!Number.isInteger(pendingCount)||pendingCount<0||pendingCount>32||(kind==='none')!==(pendingCount===0))throw new BrainError('invalid_input');
+ return {event:kind==='none'?'no_pending_input':'pending_input',kind,pending_count:pendingCount};
+}
+export function parseBrainDecision(value){
+ if(!value||typeof value!=='object'||Array.isArray(value)||Object.keys(value).length!==1||!DECISIONS.has(value.decision))throw new BrainError('invalid_output');
+ return value.decision;
+}
+async function boundedJSON(response){
+ const reader=response.body?.getReader();if(!reader)throw new BrainError('invalid_response');
+ const decoder=new TextDecoder();let text='',size=0;
+ try{for(;;){const {done,value}=await reader.read();if(done)break;size+=value.byteLength;if(size>32768)throw new BrainError('oversized_response');text+=decoder.decode(value,{stream:true});}text+=decoder.decode();return JSON.parse(text);}
+ catch(error){await reader.cancel().catch(()=>{});throw error instanceof BrainError?error:new BrainError('invalid_response');}
+ finally{reader.releaseLock();}
+}
+export function createOpenRouterBrain({apiKey=globalThis.process?.env?.OPENROUTER_API_KEY,fetch:request=globalThis.fetch,now=()=>performance.now(),day=()=>new Date().toISOString().slice(0,10),timeoutMs=3000,maxRequestsPerDay=40,cacheMs=60000}={}){
+ if(typeof apiKey!=='string'||apiKey.length<10||apiKey.length>512||/\s/.test(apiKey))throw new BrainError('missing_key');
+ if(typeof request!=='function'||typeof now!=='function'||typeof day!=='function')throw new BrainError('invalid_options');
+ if(!Number.isFinite(timeoutMs)||timeoutMs<100||timeoutMs>15000||!Number.isInteger(maxRequestsPerDay)||maxRequestsPerDay<1||maxRequestsPerDay>1000||!Number.isFinite(cacheMs)||cacheMs<0||cacheMs>300000)throw new BrainError('invalid_options');
+ const cache=new Map();let disposed=false,flight=null,dayKey=day(),used=0,calls=0,cacheHits=0,nextAllowed=0,lastLatencyMs=null,lastError=null,lastDecision=null,state='ready';
+ return {
+  async decide(input){
+   if(disposed)throw new BrainError('disposed');
+   const facts=anonymousBrainState(input),signal=input?.signal,key=JSON.stringify(facts),start=now();
+   if(signal?.aborted)throw new BrainError('aborted');
+   const stored=cache.get(key);if(stored&&start<stored.expires){cacheHits++;lastDecision=stored.decision;lastError=null;state='ready';return {decision:stored.decision,via:'cache',latencyMs:0};}
+   if(flight)throw new BrainError('busy');
+   if(start<nextAllowed)throw new BrainError('backoff');
+   const today=day();if(today!==dayKey){dayKey=today;used=0;}
+   if(used>=maxRequestsPerDay){state='fallback';lastError='daily_budget';throw new BrainError('daily_budget');}
+   const operation={controller:new AbortController()};flight=operation;used++;calls++;state='requesting';
+   let timer,rejectAbort;
+   const interrupted=new Promise((_,reject)=>{rejectAbort=reject;});
+   const abort=()=>{rejectAbort(new BrainError('aborted'));operation.controller.abort();};
+   signal?.addEventListener('abort',abort,{once:true});
+   operation.abort=abort;
+   timer=setTimeout(()=>{rejectAbort(new BrainError('timeout'));operation.controller.abort();},timeoutMs);
+   try{
+    const result=await Promise.race([(async()=>{
+     const response=await request(ENDPOINT,{
+      method:'POST',redirect:'error',signal:operation.controller.signal,
+      headers:{'Authorization':'Bearer '+apiKey,'Content-Type':'application/json'},
+      // USD per million tokens; no per-request fee or alternate-model fallback.
+      body:JSON.stringify({model:OPENROUTER_MODEL,messages:[{role:'system',content:SYSTEM},{role:'user',content:key}],temperature:0,max_tokens:96,reasoning:{enabled:false},response_format:{type:'json_object'},provider:{require_parameters:true,data_collection:'deny',max_price:{prompt:0.3,completion:1.2,request:0}}}),
+     });
+     if(!response.ok){await response.body?.cancel().catch(()=>{});throw new BrainError(response.status===429?'rate_limited':[401,403].includes(response.status)?'authorization_failed':response.status===404?'route_unavailable':'service_unavailable');}
+     const body=await boundedJSON(response),choice=body.choices?.[0];
+     if(choice?.finish_reason!=='stop'||typeof choice.message?.content!=='string'||choice.message.tool_calls?.length)throw new BrainError('invalid_output');
+     let value;try{value=JSON.parse(choice.message.content);}catch{throw new BrainError('invalid_output');}
+     return {decision:parseBrainDecision(value),via:'llm',latencyMs:Math.max(0,Math.round(now()-start))};
+    })(),interrupted]);
+    if(disposed||signal?.aborted||flight!==operation)throw new BrainError('aborted');
+    lastLatencyMs=result.latencyMs;lastError=null;lastDecision=result.decision;state='ready';
+    cache.delete(key);cache.set(key,{decision:result.decision,expires:now()+cacheMs});
+    while(cache.size>16)cache.delete(cache.keys().next().value);
+    return result;
+   }catch(error){
+    const safe=error instanceof BrainError?error:new BrainError('network_error');
+    if(!disposed){lastError=safe.code;lastLatencyMs=Math.max(0,Math.round(now()-start));state='fallback';if(safe.code!=='aborted')nextAllowed=now()+(safe.code==='rate_limited'?60000:10000);}
+    throw safe;
+   }finally{clearTimeout(timer);signal?.removeEventListener('abort',abort);if(flight===operation)flight=null;}
+  },
+  get status(){return {provider:'openrouter',model:OPENROUTER_MODEL,state,calls,cacheHits,dailyUsed:day()===dayKey?used:0,dailyLimit:maxRequestsPerDay,cacheEntries:cache.size,inFlight:flight!==null,lastLatencyMs,lastError,lastDecision};},
+  dispose(){if(disposed)return;disposed=true;flight?.abort();flight=null;cache.clear();apiKey='';state='off';},
+ };
+}

package/integrations/stackbite/attention.mjs

@@ -0,0 +1,47 @@
+// Narrow projection of `stackbite agent seats --output json`, not terminal text.
+// Uses StackBite's own binding validation; never reads its credential files.
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {validateAttentionSnapshot} from '../../retrieviewer-attention.mjs';
+const execute=promisify(execFile);
+const identifier=value=>typeof value==='string'&&/^[a-zA-Z0-9_.:-]{1,128}$/.test(value);
+
+export function stackBiteBinding(env=process.env){
+ if(!identifier(env.STACKBITE_ROOM_ID)||!identifier(env.STACKBITE_SEAT_KEY)||!identifier(env.STACKBITE_SESSION_GENERATION)||!env.STACKBITE_STATE_DIR||!env.STACKBITE_ROOM_BRIDGE_URL)throw Error('Start desktop --watch stackbite inside a live StackBite Seat. No Room binding was found.');
+ return {roomId:env.STACKBITE_ROOM_ID};
+}
+export function projectStackBiteSeats(value,{roomId}={}){
+ if(!identifier(roomId)||value?.room_id!==roomId||!Array.isArray(value.seats)||value.seats.length>256)throw Error('Invalid or mismatched StackBite Room snapshot');
+ const items=[];
+ for(const seat of value.seats){
+  if(!seat||typeof seat!=='object')throw Error('Invalid StackBite Seat');
+  if(seat.is_alive!==true||!identifier(seat.seat_key)||!identifier(seat.generation))continue;
+  const status=seat.seat_status;
+  if(status!==undefined){
+   // The current public projection outranks legacy fields. Never revive an
+   // unknown/resolved/foreign projection from a stale legacy flag.
+   if(status?.schema_version!==1||status.generation!==seat.generation||status.phase!=='needs_input'||status.input_kind==='onboarding')continue;
+   const turnId=Number.isSafeInteger(status.turn_id)&&status.turn_id>0?status.turn_id:null;
+   const requestId=identifier(status.input_request_id)?status.input_request_id:undefined;
+   if(turnId===null&&requestId===undefined)continue;
+   items.push({id:seat.seat_key,generation:seat.generation,turnId,...requestId===undefined?{}:{requestId},kind:status.input_kind==='approval'?'approval':'input'});
+  }else{
+   // Older explicit lifecycle facts are accepted only with an exact turn.
+   if(!['awaiting_user','blocked'].includes(seat.lifecycle_state)||!Number.isSafeInteger(seat.turn_id)||seat.turn_id<1)continue;
+   items.push({id:seat.seat_key,generation:seat.generation,turnId:seat.turn_id,kind:seat.provider_permission_pending===true||seat.input_kind==='approval'?'approval':'input'});
+  }
+ }
+ return validateAttentionSnapshot({source:'stackbite',scope:roomId,items});
+}
+export function createStackBiteSource({env=process.env,exec=execute}={}){
+ const binding=stackBiteBinding(env);
+ const childEnv={...env};delete childEnv.OPENROUTER_API_KEY;
+ return {
+  async readSnapshot({signal}={}){
+   // Fixed argv, no shell, no input/click/report/approval command. The CLI checks
+   // that the inherited caller Seat/generation is still live on every read.
+   const {stdout}=await exec('stackbite',['agent','seats','--output','json'],{env:childEnv,signal,encoding:'utf8',windowsHide:true,timeout:4000,maxBuffer:262144});
+   return projectStackBiteSeats(JSON.parse(stdout),binding);
+  },
+ };
+}

package/integrations/windows-overlay/Overlay.cs

@@ -110,7 +110,7 @@ sealed class Companion : ApplicationContext {
     readonly JavaScriptSerializer json=new JavaScriptSerializer();readonly object inputLock=new object();
     readonly Queue<Dictionary<string,object>> messages=new Queue<Dictionary<string,object>>();
     TargetItem target;Form pickerWindow;QuietWindow testTarget;readonly bool testMode;Rectangle canvas;int revision=0,cell=8;bool visible=false,paused=false,loaded=false,quitting=false,picking=false,announced=false;
-    Label status=new Label();Mutex mutex;
+    Label status=new Label();Mutex mutex;string attentionText=null;
     internal Companion(Mutex single,bool diagnostic){
         mutex=single;testMode=diagnostic;bar.Text="Retrieviewer controls";bar.Size=new Size(538,40);bar.BackColor=Color.FromArgb(28,30,34);bar.ForeColor=Color.White;
         bar.Font=new Font("Segoe UI",9);bar.Controls.Add(MakeButton("Ball",8,()=>Interact("ball")));bar.Controls.Add(MakeButton("Treat",76,()=>Interact("treat")));
@@ -151,7 +151,13 @@ sealed class Companion : ApplicationContext {
                 string type=Program.Str(m,"type");
                 if(type=="quit"){Quit();return;}
                 if(type=="loaded"){string ink=m.ContainsKey("ink")?Program.Str(m,"ink"):"cream";if(ink!="cream"&&ink!="gold"&&ink!="dark")throw new Exception("Invalid ink");pet.Ink=ink=="gold"?Color.FromArgb(245,231,184,103):ink=="dark"?Color.FromArgb(245,67,48,24):Color.FromArgb(245,248,242,232);loaded=true;status.Text="Playing";if(testMode)((Button)bar.Controls[0]).PerformClick();continue;}
-                if(type=="interaction"){status.Text=Program.Bool(m,"accepted")?"Ready!":"Please wait";continue;}
+                if(type=="interaction"){status.Text=attentionText??(Program.Bool(m,"accepted")?"Ready!":"Please wait");continue;}
+                if(type=="attention"){
+                    int count=Program.Int(m,"count");string state=Program.Str(m,"state");
+                    if(count<0||count>32)throw new Exception("Invalid attention count");
+                    attentionText=state=="connected"?(count>0?count+" need input":"Watching"):state=="paused"?"Watch paused":state=="connecting"?"Connecting...":"Watch offline";status.Text=attentionText;
+                    continue;
+                }
                 if(type=="error"){status.Text="Engine error";Quit();return;}
                 if(type=="frame"){
                     // Always acknowledge discarded frames too, otherwise resizing can deadlock the sender.
@@ -168,8 +174,10 @@ sealed class Companion : ApplicationContext {
         if(target!=null&&!Native.IsIconic(target.Window)&&Native.IsWindowVisible(target.Window)){
             next=Native.ClientBounds(target.Window);IntPtr foreground=Native.GetForegroundWindow();show=!picking&&(testMode||foreground==target.Window||foreground==bar.Handle)&&next.Width>=160&&next.Height>=120;
         }
-        int nextCell=8;while(next.Width/nextCell*(next.Height/(nextCell*2))>125000&&nextCell<16)nextCell+=2;
-        if(nextCell==14)nextCell=16;
+        int nextCell=Program.GridCell(next.Width,next.Height);
+        // A huge target may exceed the transport budget even at the largest cell.
+        // Hide until its size fits again; never send an invalid visible grid.
+        if(nextCell==0){show=false;nextCell=16;}
         int columns=next.Width/nextCell,rows=next.Height/(nextCell*2);
         if(force||show!=visible||next!=canvas||nextCell!=cell){
             visible=show;canvas=next;cell=nextCell;revision++;pet.Hide();
@@ -237,6 +245,13 @@ static class Program {
             using(Companion context=new Companion(single,ipcTest))Application.Run(context);return 0;
         }catch(Exception error){Emit(new {type="error",message=error.Message});return 1;}
     }
+    internal static int GridCell(int width,int height){
+        foreach(int size in new int[]{8,10,12,16}){
+            long columns=(long)width/size,rows=(long)height/(size*2);
+            if(columns>0&&rows>0&&columns*rows<=125000)return size;
+        }
+        return 0;
+    }
     static int SelfTest(string proof){
         // Uses only our own off-screen windows. Does NOT click/type in or capture a user application.
         IntPtr foreground=Native.GetForegroundWindow();
@@ -253,8 +268,9 @@ static class Program {
             Native.ShowWindow(target.Handle,7);Application.DoEvents();bool minimized=Native.IsIconic(target.Handle);pet.Hide();bool hidden=!pet.Visible;
             Native.ShowWindow(target.Handle,4);Application.DoEvents();bool restored=!Native.IsIconic(target.Handle);
             bool focus=Native.GetForegroundWindow()==foreground;
-            bool passed=clickThrough&&noActivate&&layered&&follows&&minimized&&hidden&&restored&&focus&&pet.PaintedDots>0;
-            Emit(new {type="self-test",passed=passed,clickThroughStyle=clickThrough,noActivateStyle=noActivate,layered=layered,followGeometry=follows,expectedX=expectedX,expectedY=expectedY,actualX=actual.Left,actualY=actual.Top,minimize=minimized,hide=hidden,restore=restored,foregroundPreserved=focus,dots=pet.PaintedDots,proof=proof});return passed?0:1;
+            bool gridBounds=GridCell(3840,2160)==8&&GridCell(7680,4320)==12&&GridCell(32000,18000)==0&&GridCell(int.MaxValue,int.MaxValue)==0&&GridCell(0,0)==0;
+            bool passed=clickThrough&&noActivate&&layered&&follows&&minimized&&hidden&&restored&&focus&&pet.PaintedDots>0&&gridBounds;
+            Emit(new {type="self-test",passed=passed,gridBounds=gridBounds,clickThroughStyle=clickThrough,noActivateStyle=noActivate,layered=layered,followGeometry=follows,expectedX=expectedX,expectedY=expectedY,actualX=actual.Left,actualY=actual.Top,minimize=minimized,hide=hidden,restore=restored,foregroundPreserved=focus,dots=pet.PaintedDots,proof=proof});return passed?0:1;
         }
     }
 }

package/integrations/windows-overlay/desktop.mjs

@@ -93,18 +93,33 @@ export async function desktopHelper(options={}){
  throw Error('Linux desktop needs system Python3.6+ (AlmaLinux8 platform-python is supported). No packages or system settings were installed.');
 }
 export async function startDesktop(options={}){
+ const watch=options.watch??'off';if(!['off','stackbite'].includes(watch))throw Error('Invalid desktop watch source');
+ const brain=options.brain??'off';if(!['off','openrouter'].includes(brain))throw Error('Invalid desktop brain');
+ if(brain==='openrouter'){
+  if(watch!=='stackbite')throw Error('--brain openrouter requires --watch stackbite');
+  const {createOpenRouterBrain}=await import('../openrouter/brain.mjs');createOpenRouterBrain().dispose();
+ }
+ if(watch==='stackbite'){const {stackBiteBinding}=await import('../stackbite/attention.mjs');stackBiteBinding();}
  const ink=options.ink??'cream';if(!['cream','gold','dark'].includes(ink))throw Error('Invalid desktop ink');
  const returnStyle=options.returnStyle??'auto';if(!['auto','brake','trot','run-trot'].includes(returnStyle))throw Error('Invalid return style');
  // Fail before creating any cache/session on unsupported desktops (e.g. Wayland).
  desktopPlatform(options);
- const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true,...status.returnStyle!==returnStyle?{requestedReturnStyle:returnStyle,restartRequired:true}:{}};
+ const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true,...status.returnStyle!==returnStyle?{requestedReturnStyle:returnStyle,restartRequired:true}:{},...(status.watch?.source??'off')!==watch?{requestedWatch:watch,restartRequired:true}:{},...(status.brain?.provider??'off')!==brain?{requestedBrain:brain,restartRequired:true}:{}};
  if(status.stale)await stopDesktop(options);
  const helper=await desktopHelper(options);
+ const workerEnv={...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root,RETRIEVIEWER_INK:ink,RETRIEVIEWER_RETURN_STYLE:returnStyle,RETRIEVIEWER_WATCH:watch,RETRIEVIEWER_BRAIN:brain};
+ if(brain==='off')delete workerEnv.OPENROUTER_API_KEY;
  return new Promise((resolve,reject)=>{
-  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root,RETRIEVIEWER_INK:ink,RETRIEVIEWER_RETURN_STYLE:returnStyle}});
-  let settled=false;const finish=(error,message)=>{if(settled)return;settled=true;clearTimeout(timer);if(child.connected)child.disconnect();child.unref();error?reject(error):resolve(message);};
-  const timer=setTimeout(()=>{if(child.connected)child.send({command:'abort'});finish(Error('Desktop startup timed out; no agent settings changed'));},20000);
-  child.on('error',error=>finish(error));child.on('message',message=>message.error?finish(Error(message.error)):finish(null,message));child.on('exit',code=>finish(Error('Desktop exited during startup ('+code+')')));
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),'--helper-spec',JSON.stringify(helper)],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:workerEnv});
+  let settled=false,ready=null;const finish=(error,message)=>{if(settled)return;settled=true;clearTimeout(timer);if(child.connected)child.disconnect();child.unref();error?reject(error):resolve(message);};
+  // Disconnect on failure aborts startup. Only an acknowledged detach may live on.
+  const timer=setTimeout(()=>finish(Error('Desktop startup timed out; no agent settings changed')),20000);
+  child.on('error',error=>finish(error));child.on('message',message=>{
+   if(settled)return;
+   if(message?.error)return finish(Error(message.error));
+   if(message?.detached===true&&ready)return finish(null,ready);
+   if(message?.running===true&&!ready){ready=message;child.send({command:'detach'},error=>{if(error)finish(error);});}
+  });child.on('disconnect',()=>{if(!settled)finish(Error('Desktop disconnected during startup'));});child.on('exit',code=>finish(Error('Desktop exited during startup ('+code+')')));
  });
 }
 export async function cleanDesktop(options={}){

package/integrations/windows-overlay/protocol.mjs

@@ -42,6 +42,8 @@ export function createFramePump({pet,send,now=()=>performance.now()}){
    try{send(frame);lastFrame=frame;}catch(error){inFlight=false;lastFrame=null;nextPaint=0;throw error;}return true;
   },
   interact(kind){alive();if(!['ball','treat','tug'].includes(kind))throw Error('Invalid overlay interaction');const accepted=pet.interact(kind);if(accepted){lastFrame=null;nextPaint=0;}return accepted;},
+  notify(notice){alive();const accepted=pet.notify(notice);if(accepted){lastFrame=null;nextPaint=0;}return accepted;},
+  clearNotice(){alive();pet.clearNotice();lastFrame=null;nextPaint=0;},
   get hidden(){return !viewport||paused;},
   dispose(){if(!disposed){disposed=true;viewport=lastFrame=null;pet.dispose();}},
  };