@bitefoundry/retrieviewer 0.0.13 → 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/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,24 @@
-# Retrieviewer 0.0.13 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.

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.

package/integrations/windows-overlay/desktop.mjs

@@ -93,15 +93,24 @@ 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}});
+  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);

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();}},
  };

package/integrations/windows-overlay/worker.mjs

@@ -10,12 +10,15 @@ import {controlAddress,parseHelperSpec} from '../desktop/platform.mjs';
 
 let helper,pump,timer,server,session,paths,owned=false,stopping=false,frames=0,paintedFrames=0,visible=false,selected=false,pickerVisible=false,pendingViewport=null,lastInteraction=null;
 let nativeError=null,ready=false,detached=false;
+let attention=null,brain=null;
 const returnStyle=process.env.RETRIEVIEWER_RETURN_STYLE??'auto';
+const watchSource=process.env.RETRIEVIEWER_WATCH??'off';
+const brainSource=process.env.RETRIEVIEWER_BRAIN??'off';
 let nativeStderr='';
 const sendParent=message=>{if(process.connected)try{process.send(message,error=>{if(error&&!detached)stop();});}catch{if(!detached)stop();}};
 const starting=()=>{if(stopping||(!process.connected&&!detached))throw Error('Desktop launcher closed during startup');};
 async function stop(){
- const first=!stopping;stopping=true;clearInterval(timer);pump?.dispose();
+ const first=!stopping;stopping=true;clearInterval(timer);attention?.dispose();brain?.dispose();pump?.dispose();
  if(helper&&!helper.killed){try{helper.stdin.end(JSON.stringify({type:'quit'})+'\n');}catch{}}
  if(server?.listening)server.close();
  if(owned)try{const current=JSON.parse(await readFile(paths.session,'utf8'));if(current.token===session.token)await unlink(paths.session);}catch{}
@@ -41,7 +44,7 @@ try{
    body+=bytes.toString('utf8');if(body.length>2048)return socket.destroy();if(!body.includes('\n'))return;
    let command;try{command=JSON.parse(body.split('\n')[0]);}catch{return socket.destroy();}
    if(command.token!==session.token||!['status','stop'].includes(command.command))return socket.destroy();
-   socket.end(JSON.stringify(command.command==='stop'?{stopped:true}:{running:true,reachable:true,selected,visible,pickerVisible,frames,paintedFrames,lastInteraction,returnStyle,pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
+   socket.end(JSON.stringify(command.command==='stop'?{stopped:true}:{running:true,reachable:true,selected,visible,pickerVisible,frames,paintedFrames,lastInteraction,returnStyle,watch:{source:watchSource,...attention?.status??{state:'off',pendingCount:0}},brain:brain?.status??{provider:'off',state:'off'},pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
    if(command.command==='stop')stop();
   });
  });
@@ -49,7 +52,8 @@ try{
  if(process.platform!=='win32')await chmod(session.pipe,0o600);
  starting();
  // GUI-subsystem exe: no console to hide. SW_HIDE here also hides its first UI.
- helper=spawn(spec.command,spec.args,{windowsHide:false,stdio:['pipe','pipe','pipe']});
+ const helperEnv={...process.env};delete helperEnv.OPENROUTER_API_KEY;
+ helper=spawn(spec.command,spec.args,{windowsHide:false,stdio:['pipe','pipe','pipe'],env:helperEnv});
  helper.stdin.on('error',()=>stop());helper.stderr.setEncoding('utf8');helper.stderr.on('data',s=>{nativeStderr=(nativeStderr+s).slice(-4096);});helper.once('error',error=>{sendParent({error:error.message});stop();});
  helper.once('exit',code=>{if(!stopping)sendParent({error:nativeError??('Desktop painter exited ('+code+')'+(nativeStderr?' — '+nativeStderr.trim():''))});stop();});
  const write=message=>{if(!stopping&&!helper.stdin.destroyed)helper.stdin.write(JSON.stringify(message)+'\n');};
@@ -70,6 +74,18 @@ try{
  starting();const {createPet}=await import('../../retrieviewer.mjs');starting();const pet=await createPet({returnStyle});
  if(stopping)pet.dispose();else{
   pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
-  write({type:'loaded',ink:process.env.RETRIEVIEWER_INK??'cream'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);
+  if(!['off','stackbite'].includes(watchSource))throw Error('Invalid desktop watch source');
+  if(!['off','openrouter'].includes(brainSource)||brainSource==='openrouter'&&watchSource!=='stackbite')throw Error('Invalid desktop brain/watch combination');
+  if(brainSource==='openrouter'){const {createOpenRouterBrain}=await import('../openrouter/brain.mjs');starting();brain=createOpenRouterBrain();}
+  if(watchSource==='stackbite'){
+   const [{createAttentionMonitor},{createStackBiteSource}]=await Promise.all([import('../../retrieviewer-attention.mjs'),import('../stackbite/attention.mjs')]);starting();
+   const source=createStackBiteSource();
+   attention=createAttentionMonitor({readSnapshot:source.readSnapshot,...brain?{judgeNotice:input=>brain.decide(input)}:{},onNotice:notice=>pump.notify(notice),onClear:()=>pump.clearNotice(),onChange:status=>{
+    // Older POSIX helpers deliberately reject unknown message types. They can
+    // run the visual cue, but only the Windows bar implements this status label.
+    if(spec.mode==='windows-overlay')write({type:'attention',state:status.state,count:status.pendingCount});
+   }});
+  }
+  write({type:'loaded',ink:process.env.RETRIEVIEWER_INK??'cream'});timer=setInterval(()=>{try{attention?.tick({active:!pump.hidden});pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/spec.fps);
  }
 }catch(error){sendParent({error:error.message});await stop();}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "A fluffy Braille desktop pet for Windows and Linux X11, with experimental macOS support and an embeddable TUI engine.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://bitefoundry.github.io/retrieviewer/",
@@ -47,6 +47,14 @@
       "types": "./retrieviewer-plugin.d.mts",
       "default": "./retrieviewer-plugin.mjs"
     },
+    "./attention": {
+      "types": "./retrieviewer-attention.d.mts",
+      "default": "./retrieviewer-attention.mjs"
+    },
+    "./brain": {
+      "types": "./integrations/openrouter/brain.d.mts",
+      "default": "./integrations/openrouter/brain.mjs"
+    },
     "./tui": "./integrations/opencode/tui.tsx",
     "./opencode/tui": "./integrations/opencode/tui.tsx",
     "./package.json": "./package.json"
@@ -62,6 +70,8 @@
     "RELEASING.md",
     "retrieviewer.mjs",
     "retrieviewer.d.mts",
+    "retrieviewer-attention.mjs",
+    "retrieviewer-attention.d.mts",
     "retrieviewer-stdio.mjs",
     "retrieviewer-plugin.mjs",
     "retrieviewer-plugin.d.mts",
@@ -75,6 +85,11 @@
     "integrations/windows-overlay/worker.mjs",
     "integrations/windows-overlay/Overlay.cs",
     "integrations/desktop/platform.mjs",
+    "integrations/stackbite/attention.mjs",
+    "integrations/openrouter/brain.mjs",
+    "integrations/openrouter/brain.d.mts",
+    "BRAIN.md",
+    "ATTENTION.md",
     "integrations/linux-overlay/overlay.py",
     "integrations/linux-overlay/README.md",
     "integrations/macos-overlay/overlay.jxa",

package/puppy-companion-life.mjs

@@ -26,7 +26,7 @@ const LABEL={
  belly:'배를 보이고 발라당 쉬는 중',sleep:'새근새근 잠자는 중',tug:'장난감을 물고 당기는 중',
  butterflyNotice:'나비를 발견하고 귀를 쫑긋하는 중',butterfly:'나비를 폴짝폴짝 쫓는 중',butterflyBye:'날아가는 나비를 바라보는 중',
  fetch:'공을 쫓아가는 중',miss:'굴러가는 공을 한 번 놓친 중',reChase:'공을 다시 쫓아가는 중',tumble:'우당탕 균형을 되찾는 중',pickup:'공을 무는 중',carry:'공을 물고 돌아오는 중',drop:'공을 내려놓는 중',offer:'공을 내려놓고 기다리는 중',
- treatSit:'간식 앞에 앉는 중',chew:'간식 먹는 중'
+ treatSit:'간식 앞에 앉는 중',chew:'간식 먹는 중',notifySit:'확인할 일을 발견하고 앉는 중',notify:'확인할 일이 있는 쪽을 바라보는 중'
 };
 const PENDING_LABEL={treat:'곧 간식',tug:'곧 터그놀이'};
 // Baked interaction clips, played only while holding at the shared seated endpoint.
@@ -62,7 +62,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8,returnStyle='auto'
  let clock=0,decisions=0,lastEpisode=null,quiet=0;
  let queue=[],hold=0,holdIntent=null,waiting=null,gesture=null;
  let intent='start',label=LABEL.start,pending=null,active=null,ball=null,treat=null;
- let fetchPlan=null;
+ let fetchPlan=null,notice=null;
 
  const cmd=(name,args,step,when)=>({cmd:name,args,intent:step,label:LABEL[step],when});
  const wait=(seconds,step)=>({hold:seconds,intent:step,label:LABEL[step]});
@@ -236,6 +236,10 @@ export function createCompanionLife(actor,{seed=731,energy=.8,returnStyle='auto'
   holdIntent=null;gesture=null;
   if(!safe)return;
   if(pending&&!active)startInteraction();
+  if(notice?.phase==='queued'&&!active&&!pending){
+   notice.phase='showing';
+   queue=[sit('notifySit'),cmd('look',[notice.side],'notify'),wait(2.5,'notify'),fx(()=>{notice=null;})];
+  }
   // Run instant effects; stop at the first hold or issued command (at most one command per update).
   for(;;){
    if(!queue.length){
@@ -257,6 +261,7 @@ export function createCompanionLife(actor,{seed=731,energy=.8,returnStyle='auto'
   if(!['ball','treat','tug'].includes(kind))return false;
   if(kind==='tug'&&typeof actor.tug!=='function')return false;
   if(pending||active||cooldowns[kind]>0)return false;
+  clearNotice();
   quiet=0;
   if(butterfly||lastEpisode==='butterfly'){
    butterfly=null;queue=[];hold=0;holdIntent=null;gesture=null;waiting=null;
@@ -304,6 +309,21 @@ export function createCompanionLife(actor,{seed=731,energy=.8,returnStyle='auto'
   return true;
  }
 
+ function clearNotice(){
+  if(!notice)return;
+  notice=null;queue=[];hold=0;holdIntent=null;gesture=null;waiting=null;
+  // Let any connected head turn/sit finish naturally. No snap or new route.
+ }
+ function notify({kind,side='left'}={}){
+  if(!['approval','input'].includes(kind)||!['left','right'].includes(side))throw Error('Invalid pet notice');
+  // Explicit play/feeding always wins. Notifications never queue a second pet.
+  if(active||pending||notice)return false;
+  notice={kind,side,phase:'queued'};
+  butterfly=null;queue=[];hold=0;holdIntent=null;gesture=null;waiting=null;
+  actor.attend?.();
+  return true;
+ }
+
  // Recomputed from the live pose so the marker stays truthful before and after sitting.
  function treatReport(){
   if(!treat)return null;
@@ -322,13 +342,14 @@ export function createCompanionLife(actor,{seed=731,energy=.8,returnStyle='auto'
  }
 
  return {
-  update,interact,
+  update,interact,notify,clearNotice,
   setReturnStyle(style){validateReturnStyle(style);returnStyle=style;return style;},
   get report(){
    const interaction=active??pending;
    return {
     intent:actor.state==='scramble'&&fetchPlan?'tumble':intent,label:pending?`${label} · ${PENDING_LABEL[pending]}`:actor.state==='scramble'&&fetchPlan?LABEL.tumble:label,episode:lastEpisode,interaction,busy:interaction!==null,
     ball:ballReport(),fetchPattern:fetchPlan?.pattern??null,returnStyle,returnMode:fetchPlan?.returnMode??null,treat:treatReport(),butterfly:butterflyPoint(),tug:actor.state==='tug'?{progress:actor.sample(clock).comfortPose?.progress??0,grip:1}:null,
+    attention:notice?{...notice}:null,
     snore:actor.state==='sleep'?((clock%3.6)/3.6):null,energy:needs.energy,drowsiness:needs.drowsiness,decisions,cooldowns:{...cooldowns},
     // Local hold clock only: progress freezes between updates; null outside the stationary hold.
     gesture:gesture&&SAFE.has(actor.state)?{clip:gesture.clip,progress:clamp(gesture.elapsed/gesture.duration,0,1)}:null

package/retrieviewer-attention.d.mts

@@ -0,0 +1,33 @@
+export interface AttentionSnapshot {
+ source: string;
+ scope: string;
+ items: {id: string; generation: string; turnId: number | null; requestId?: string; kind: 'approval' | 'input'}[];
+}
+export interface AttentionStatus {
+ state: 'connecting' | 'connected' | 'unavailable' | 'paused' | 'stale' | 'off';
+ pendingCount: number;
+ retainedNotices: number;
+ inFlight: boolean;
+ judging?: boolean;
+ lastJudgment?: 'model_notify' | 'rule_override' | 'rule_fallback' | null;
+}
+export function validateAttentionSnapshot(value: unknown): AttentionSnapshot;
+/** Host owns tick/lifetime. Import and construction start no timers or I/O. */
+export function createAttentionMonitor(options: {
+ readSnapshot: (options: {signal: AbortSignal}) => Promise<AttentionSnapshot>;
+ onNotice: (notice: {kind: 'approval' | 'input'; side: 'left'}) => boolean;
+ onClear?: () => void;
+ onChange?: (status: AttentionStatus) => void;
+ /** Anonymous metadata only. Confirmed pending alerts cannot be suppressed. */
+ judgeNotice?: (input: {kind: 'approval' | 'input'; pendingCount: number; signal: AbortSignal}) => Promise<{decision: 'notify' | 'ignore' | 'uncertain'}>;
+ judgeTimeoutMs?: number;
+ now?: () => number;
+ intervalMs?: number;
+ staleMs?: number;
+ noticeCooldownMs?: number;
+}): {
+ tick(options?: {active?: boolean}): void;
+ readonly status: AttentionStatus;
+ settled(): Promise<void>;
+ dispose(): void;
+};

package/retrieviewer-attention.mjs

@@ -0,0 +1,99 @@
+// Opt-in attention coordinator. No I/O, timers, models or pet assets on import.
+// Screen/app text is data, never an instruction or an executable action.
+const MAX_ITEMS=32,MAX_SEEN=128;
+const bounded=(value,max=128)=>typeof value==='string'&&value.length>0&&value.length<=max&&!/[\x00-\x1f\x7f]/.test(value);
+export function validateAttentionSnapshot(value){
+ if(!value||!bounded(value.source,32)||!bounded(value.scope,256)||!Array.isArray(value.items)||value.items.length>MAX_ITEMS)throw Error('Invalid attention snapshot');
+ const identities=new Set();
+ const items=value.items.map(item=>{
+  if(!item||!bounded(item.id)||!bounded(item.generation)||!(item.turnId===null||Number.isSafeInteger(item.turnId)&&item.turnId>=1)||item.requestId!==undefined&&!bounded(item.requestId)||item.turnId===null&&item.requestId===undefined||!['approval','input'].includes(item.kind))throw Error('Invalid attention item');
+  const key=JSON.stringify([item.id,item.generation,item.turnId,item.requestId??null]);if(identities.has(key))throw Error('Duplicate attention item');identities.add(key);
+  // Do not retain arbitrary source fields, output text, prompts, paths or tokens.
+  return {id:item.id,generation:item.generation,turnId:item.turnId,...item.requestId===undefined?{}:{requestId:item.requestId},kind:item.kind};
+ });
+ return {source:value.source,scope:value.scope,items};
+}
+
+export function createAttentionMonitor({readSnapshot,onNotice,onClear=()=>{},onChange=()=>{},judgeNotice,judgeTimeoutMs=3500,now=()=>performance.now(),intervalMs=5000,staleMs=15000,noticeCooldownMs=20000}={}){
+ if(typeof readSnapshot!=='function'||typeof onNotice!=='function'||typeof onClear!=='function'||typeof onChange!=='function'||typeof now!=='function')throw TypeError('Attention callbacks must be functions');
+ if(judgeNotice!==undefined&&typeof judgeNotice!=='function')throw TypeError('judgeNotice must be a function');
+ if(!Number.isFinite(judgeTimeoutMs)||judgeTimeoutMs<100||judgeTimeoutMs>15000)throw RangeError('Invalid judge timeout');
+ if(!Number.isFinite(intervalMs)||intervalMs<1000||intervalMs>60000||!Number.isFinite(staleMs)||staleMs<intervalMs*2||staleMs>300000||!Number.isFinite(noticeCooldownMs)||noticeCooldownMs<1000||noticeCooldownMs>300000)throw RangeError('Invalid attention timing');
+ let disposed=false,paused=false,flight=null,nextRead=0,nextNotice=0,lastSuccess=null,snapshot=null,state='connecting',lastReport='',cueKey=null,judgment=null,lastJudgment=null;
+ const seen=new Map();
+ const identity=(value,item)=>JSON.stringify([value.source,value.scope,item.id,item.generation,item.turnId,item.requestId??null]);
+ const clearCue=()=>{if(cueKey!==null){cueKey=null;onClear();}};
+ const cancelJudgment=()=>{const old=judgment;judgment=null;old?.controller.abort();};
+ const report=()=>({state,pendingCount:snapshot?.items.length??0,retainedNotices:seen.size,inFlight:flight!==null,...judgeNotice?{judging:!!judgment&&!judgment.ready,lastJudgment}:{}});
+ const changed=()=>{const key=state+'|'+(snapshot?.items.length??0);if(key!==lastReport){lastReport=key;onChange(report());}};
+ const clear=next=>{snapshot=null;lastSuccess=null;state=next;cancelJudgment();clearCue();changed();};
+ function startRead(t){
+  const operation={controller:new AbortController()};flight=operation;nextRead=t+intervalMs;
+  operation.done=(async()=>{
+   try{
+    const result=validateAttentionSnapshot(await readSnapshot({signal:operation.controller.signal}));
+    if(disposed||paused||flight!==operation)return;
+    // A scope change cannot inherit either pending facts or dedupe identities.
+    if(snapshot&&(snapshot.scope!==result.scope||snapshot.source!==result.source))seen.clear();
+    snapshot=result;lastSuccess=now();state='connected';
+    if(cueKey!==null&&!snapshot.items.some(item=>identity(snapshot,item)===cueKey))clearCue();
+    if(judgment&&!snapshot.items.some(item=>identity(snapshot,item)===judgment.key))cancelJudgment();
+   }catch{
+    if(disposed||paused||flight!==operation)return;
+    // No source stderr, credentials, or stale pending facts escape on failure.
+    clear('unavailable');
+   }finally{
+    if(flight===operation){flight=null;nextRead=now()+intervalMs;if(!disposed&&!paused)changed();}
+   }
+  })();
+ }
+ return {
+  tick({active=true}={}){
+   if(disposed)return;
+   const t=now();if(!Number.isFinite(t))throw RangeError('Invalid attention clock');
+   if(!active){
+    if(!paused){paused=true;const old=flight;flight=null;old?.controller.abort();clear('paused');}
+    return;
+   }
+   if(paused){paused=false;nextRead=t;state='connecting';changed();}
+   if(snapshot&&t-lastSuccess>=staleMs)clear('stale');
+   if(!flight&&t>=nextRead)startRead(t);
+   // A refresh already in flight may resolve/replace the candidate. Do not emit
+   // an old cue in the microtask gap just before that fresh snapshot arrives.
+   if(!flight&&snapshot&&state==='connected'&&t<lastSuccess+staleMs&&t>=nextNotice){
+    // Approval and generic input for the same exact turn are one notification.
+    let item=null;
+    for(const row of snapshot.items)if(!seen.has(identity(snapshot,row))){if(!item)item=row;if(row.kind==='approval'){item=row;break;}}
+    if(item&&judgeNotice){
+     const key=identity(snapshot,item);
+     if(judgment?.key!==key){
+      cancelJudgment();const operation={key,controller:new AbortController(),ready:false,start:t};judgment=operation;
+      const facts={kind:item.kind,pendingCount:snapshot.items.length,signal:operation.controller.signal};
+      // Only anonymous enums/counts leave the coordinator; identities stay local.
+      operation.done=Promise.resolve().then(()=>{if(operation.controller.signal.aborted)throw Error('Canceled judgment');return judgeNotice(facts);}).then(result=>{
+       if(judgment===operation&&!disposed&&!paused&&!operation.controller.signal.aborted){operation.decision=['notify','ignore','uncertain'].includes(result?.decision)?result.decision:'uncertain';operation.ready=true;}
+      },()=>{if(judgment===operation&&!disposed&&!paused){operation.decision='uncertain';operation.ready=true;}});
+     }
+     if(!judgment.ready&&t-judgment.start>=judgeTimeoutMs){judgment.ready=true;judgment.decision='uncertain';judgment.controller.abort();}
+     if(!judgment.ready){changed();return;}
+     // These are confirmed pending human-input facts, not speculative screen
+     // guesses. A model may advise, but may never hide them or authorize input.
+    }
+    if(item&&onNotice({kind:item.kind,side:'left'})===true){
+     if(judgment)lastJudgment=judgment.decision==='notify'?'model_notify':judgment.decision==='ignore'?'rule_override':'rule_fallback';
+     const key=identity(snapshot,item);seen.set(key,true);cueKey=key;
+     // Still-pending identities cannot be evicted into repeated notifications.
+     const live=new Set(snapshot.items.map(row=>identity(snapshot,row)));
+     for(const prior of seen.keys()){if(seen.size<=MAX_SEEN)break;if(!live.has(prior))seen.delete(prior);}
+     nextNotice=t+noticeCooldownMs;
+     cancelJudgment();
+    }
+   }
+   changed();
+  },
+  get status(){return report();},
+  // For host shutdown/verification, not a second polling loop.
+  async settled(){await flight?.done;await judgment?.done;},
+  dispose(){if(disposed)return;disposed=true;const old=flight;flight=null;old?.controller.abort();cancelJudgment();clearCue();snapshot=null;seen.clear();state='off';},
+ };
+}

package/retrieviewer-cli.mjs

@@ -13,7 +13,9 @@ Usage:
   retrieviewer doctor [--agent ID] [--json]
   retrieviewer agents [--json]
   retrieviewer preview [--original]
-  retrieviewer desktop [--ink cream|gold|dark] [--return-style auto|brake|trot|run-trot]
+  retrieviewer desktop [--ink cream|gold|dark] [--return-style auto|brake|trot|run-trot] [--watch stackbite|off] [--brain openrouter|off]
+  retrieviewer brain-check [--json]
+  retrieviewer attention [--json]
   retrieviewer desktop-status [--json]
   retrieviewer desktop-stop
   retrieviewer desktop-clean --yes
@@ -28,12 +30,19 @@ use Codex normally. Exit from its tray icon or desktop-stop. No auto-start is ad
 Windows is verified; macOS and Linux X11 adapters are experimental. Native Wayland
 app tracking is not supported. Linux targets AlmaLinux8/GLIBC2.28, system Python3.6+.
 Return style defaults to auto (mix all three). Restart the companion to change it.
+Watch is OFF by default. Inside a live StackBite Seat, --watch stackbite reads only
+that Room's pending-input metadata. No screen capture, clicks or approvals.
+Hidden/paused companions stop polling. attention performs one read-only check.
+Brain is OFF by default. --brain openrouter requires --watch stackbite and
+OPENROUTER_API_KEY; sends only anonymous event kinds/counts to paid DeepSeek V4.1
+Flash 1017 with token price ceilings. Failures fall back to rule alerts.
+brain-check sends one synthetic event and incurs API usage charges.
 `;
 export function parseArguments(args){
  const [command='help',...rest]=args,options={};
  for(let i=0;i<rest.length;i++){
   const token=rest[i];
-  if(token==='--agent'||token==='--ink'||token==='--return-style'){
+  if(token==='--agent'||token==='--ink'||token==='--return-style'||token==='--watch'||token==='--brain'){
    const key=token.slice(2);
    if(options[key]||!rest[i+1]||rest[i+1].startsWith('-'))throw Error(token+' requires one value');
    options[key]=rest[++i];
@@ -43,19 +52,37 @@ export function parseArguments(args){
  if(options.agent&&!AGENTS.some(a=>a.id===options.agent))throw Error('Unknown agent: '+options.agent);
  if(options.ink&&!['cream','gold','dark'].includes(options.ink))throw Error('--ink must be cream, gold or dark');
  if(options['return-style']&&!['auto','brake','trot','run-trot'].includes(options['return-style']))throw Error('--return-style must be auto, brake, trot or run-trot');
- if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].includes(command))throw Error('Unknown command: '+command);
- const allowed={desktop:['ink','return-style'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
+ if(options.watch&&!['off','stackbite'].includes(options.watch))throw Error('--watch must be stackbite or off');
+ if(options.brain&&!['off','openrouter'].includes(options.brain))throw Error('--brain must be openrouter or off');
+ if(options.brain==='openrouter'&&options.watch!=='stackbite')throw Error('--brain openrouter requires --watch stackbite');
+ if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview','attention','brain-check','desktop','desktop-status','desktop-stop','desktop-clean','desktop-remove'].includes(command))throw Error('Unknown command: '+command);
+ const allowed={desktop:['ink','return-style','watch','brain'],attention:['json'],'brain-check':['json'],enable:['agent','yes','json','dry-run'],disconnect:['agent','yes','json','dry-run'],disable:['agent','json'],status:['agent','json'],doctor:['agent','json'],agents:['json'],preview:['original'],'desktop-status':['json'],'desktop-clean':['yes'],'desktop-remove':['yes']};
  for(const key of Object.keys(options))if(!(allowed[command]??[]).includes(key))throw Error(`--${key} is not supported by ${command}`);
  return {command,options};
 }
 export async function runCli(args,{input=process.stdin,output=process.stdout,error=process.stderr,installer=createInstaller(),desktop}={}){
  const {command,options}=parseArguments(args),emit=value=>output.write(JSON.stringify(value,null,2)+'\n');
  if(['help','--help','-h'].includes(command)){output.write(HELP);return 0;}
+ if(command==='brain-check'){
+  const {createOpenRouterBrain,BrainError}=await import('./integrations/openrouter/brain.mjs');
+  const brain=createOpenRouterBrain({timeoutMs:8000});
+  try{const result=await brain.decide({kind:'approval',pendingCount:1});emit({ok:true,synthetic:true,...result,brain:brain.status});return 0;}
+  catch(error){emit({ok:false,synthetic:true,error:error instanceof BrainError?error.code:'unavailable',brain:brain.status});return 2;}
+  finally{brain.dispose();}
+ }
+ if(command==='attention'){
+  const {createStackBiteSource}=await import('./integrations/stackbite/attention.mjs');
+  const snapshot=await createStackBiteSource().readSnapshot();
+  // Diagnostic metadata only; prompts/output/credentials were discarded upstream.
+  if(options.json)emit({...snapshot,pendingCount:snapshot.items.length});
+  else output.write(`StackBite current Room: ${snapshot.items.length} pending input item(s). No screen capture or actions.\n`);
+  return 0;
+ }
  if(command.startsWith('desktop')){
   if(['desktop-clean','desktop-remove'].includes(command)&&!options.yes)throw Error('Use '+command+' --yes to remove only the companion cache.');
   const api=desktop??await import('./integrations/windows-overlay/desktop.mjs');
   const action={'desktop':'startDesktop','desktop-status':'desktopStatus','desktop-stop':'stopDesktop','desktop-clean':'cleanDesktop','desktop-remove':'removeDesktop'}[command];
-  emit(await api[action]({...options.ink?{ink:options.ink}:{},...options['return-style']?{returnStyle:options['return-style']}:{} }));return 0;
+  emit(await api[action]({...options.ink?{ink:options.ink}:{},...options['return-style']?{returnStyle:options['return-style']}:{},...options.watch?{watch:options.watch}:{},...options.brain?{brain:options.brain}:{} }));return 0;
  }
  if(command==='preview'){await import('./examples/live.mjs');return 0;}
  if(['status','doctor','agents'].includes(command)){

package/retrieviewer.d.mts

@@ -40,6 +40,8 @@ export interface PetState {
   [key: string]: unknown;
 }
 export interface LifeReport {
+  /** Metadata-triggered visual cue only. No host input or approval authority. */
+  attention: {kind: 'approval' | 'input'; side: 'left' | 'right'; phase: 'queued' | 'showing'} | null;
   /** Last selected autonomous episode; null before the first decision. */
   episode: string | null;
   intent: string;
@@ -93,6 +95,10 @@ export interface Pet {
   needsFrame(options: FrameOptions): boolean;
   /** False when busy or cooling down. */
   interact(kind: 'ball' | 'treat' | 'tug'): boolean;
+  /** False during direct play/feeding or another cue. Does not operate the host. */
+  notify(notice: {kind: 'approval' | 'input'; side?: 'left' | 'right'}): boolean;
+  /** Cancel the cue, preserving any in-progress connected pose recovery. */
+  clearNotice(): void;
   /** Sets the next throw's return style. Does not interrupt a fetch in progress. */
   setReturnStyle(style: FetchReturnStyle): FetchReturnStyle;
   readonly disposed: boolean;

package/retrieviewer.mjs

@@ -167,6 +167,9 @@ export async function createPet({loadAsset=defaultLoadAsset,seed,energy,pawTrans
   },
   // 'ball' | 'treat' | 'tug'. False when busy or cooling down; unknown kinds throw.
   interact(kind){alive();if(!INTERACTIONS.includes(kind))throw TypeError(`Unknown interaction: ${kind}`);return life.interact(kind);},
+  // A bounded visual cue only; never clicks, types, focuses or approves anything.
+  notify(notice){alive();return life.notify(notice);},
+  clearNotice(){alive();life.clearNotice();},
   // Applies to the next ball throw; never rewrites a fetch already in motion.
   setReturnStyle(style){alive();return life.setReturnStyle(style);},
   get disposed(){return disposed;},