@bitefoundry/retrieviewer 0.0.1 → 0.0.2

package/INSTALLING.md

@@ -1,6 +1,16 @@
-# Enable Retrieviewer in an agent TUI
+# Install Retrieviewer
 
-0.0.1 includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
+Windows desktop setup (Node20+ and the Windows .NET Framework4 compiler required):
+
+1. `npm install -g @bitefoundry/retrieviewer`
+2. `retrieviewer desktop` — select the app window in the picker.
+
+No agent configuration is needed for this separate transparent companion.
+See [desktop controls, compatibility and removal](WINDOWS-COMPANION.md).
+
+## Optional native OpenCode integration
+
+0.0.2 also includes an installer CLI and a native OpenCode TUI adapter. It does **not** claim
 that every MCP client can display animated UI. Native OpenCode rendering uses its
 official TUI plugin slot, not another terminal, a wrapper, or a modified binary.
 Other agent IDs are discoverable but refused until an adapter is implemented.
@@ -12,7 +22,7 @@ agent are required. Source code is MIT; bundled puppy artwork is CC BY-SA 4.0.
 Keep the included ATTRIBUTION.md and asset license when redistributing artwork.
 
 ```sh
-npm install -g @bitefoundry/retrieviewer@0.0.1
+npm install -g @bitefoundry/retrieviewer
 retrieviewer enable
 ```
 
@@ -31,9 +41,7 @@ version is **not automatically certified**. Existing project configuration can
 override global settings; doctor checks registration, not arbitrary host precedence.
 Do not put API keys in Retrieviewer settings. No credentials are needed by the pet.
 
-After a future public release, the install command will instead be
-`npm install -g @bitefoundry/retrieviewer@0.0.1`. Do not run that registry command
-before publication. The package also exports `./tui` for npm-aware OpenCode plugin
+The package also exports `./tui` for npm-aware OpenCode plugin
 loaders; package-name discovery has not yet been live-tested against npm.
 The verified installer continues using its local directory URL, not that new path.
 
@@ -54,6 +62,17 @@ the new package. No automatic global install is done by the package itself.
 
 ## Commands
 
+For the separate Windows overlay (included since0.0.2),
+see [Windows companion](WINDOWS-COMPANION.md). It does not register a Codex plugin
+or change the way an agent is launched:
+
+```powershell
+retrieviewer desktop
+retrieviewer desktop-status --json
+retrieviewer desktop-stop
+retrieviewer desktop-remove --yes
+```
+
 ```sh
 retrieviewer agents --json
 retrieviewer status --agent opencode

package/README.md

@@ -3,7 +3,7 @@
 An autonomous, fluffy Braille retriever that lives in a pane of your terminal UI.
 Give it a ball or a treat; otherwise it wanders and plays on its own. By BiteFoundry.
 
-**Version 0.0.1.** Source code is MIT; puppy artwork is CC BY-SA 4.0, including
+**Version 0.0.2.** Source code is MIT; puppy artwork is CC BY-SA 4.0, including
 commercial use and adaptations under its attribution/ShareAlike conditions.
 See [licensing](./LICENSE), [artwork terms](./ASSETS-LICENSE.md),
 [credits](./ATTRIBUTION.md) and [brand notice](./TRADEMARKS.md).
@@ -11,11 +11,36 @@ The complete package is not MIT-only.
 
 ## Install
 
-Node.js >=20 and a terminal font supporting Unicode Braille are required.
+Windows10/11 x64, Node.js >=20, and the Windows .NET Framework4 compiler are required
+for the desktop companion. The helper builds automatically on first launch.
+
+1. Install:
+
+   ```powershell
+   npm install -g @bitefoundry/retrieviewer
+   ```
+
+2. Run and choose the app window you want your puppy to live on:
+
+   ```powershell
+   retrieviewer desktop
+   ```
+
+That's it. Use your app normally. Ball/treat controls sit above the selected
+window; the pet lets ordinary clicks through. No Codex patch, wrapper, MCP setup,
+administrator access, or automatic startup registration. It follows a whole window,
+not individual tabs, and hides when you switch away. It is a separate transparent
+Windows window, **not a widget injected into another app**. macOS/Linux desktop
+overlays, exclusive fullscreen apps, and privileged/security surfaces are not certified.
+
+Exit from the tray icon or `retrieviewer desktop-stop`. To remove the companion's
+own cache, run `retrieviewer desktop-remove --yes`; then
+`npm uninstall -g @bitefoundry/retrieviewer` removes the package. See
+[desktop support and removal](./WINDOWS-COMPANION.md).
+
+## Optional: native OpenCode pane
 
 ```sh
-npm install -g @bitefoundry/retrieviewer@0.0.1
-retrieviewer enable --agent opencode --dry-run
 retrieviewer enable --agent opencode --yes
 opencode
 ```

package/RELEASING.md

@@ -1,6 +1,6 @@
-# Retrieviewer 0.0.1 release process
+# Retrieviewer 0.0.2 release process
 
-Target: `@bitefoundry/retrieviewer@0.0.1`, public npm registry, `latest` tag.
+Target: `@bitefoundry/retrieviewer@0.0.2`, public npm registry, `latest` tag.
 The npm organization `bitefoundry` uses the free public-packages plan; account
 `shinick` owns the organization.
 
@@ -12,6 +12,10 @@ artwork draft is superseded. ATTRIBUTION.md retains the photographic references
 and original license links. ASSET-PROVENANCE.md records the bounded review and
 remaining limits; this is not comprehensive legal clearance.
 
+The owner also explicitly authorized publishing0.0.2 with the Windows companion
+and the two-step npm install/desktop launch guide. No new art license or Codex
+modification is part of this release. Do not replace the0.0.1 registry artifact.
+
 `release-policy.json` has four independent approval gates and the CC artwork
 license identifier. The guard still refuses false/missing approvals, private
 packages, missing attribution/notices, install scripts and known leaked paths.
@@ -29,7 +33,7 @@ npm publish --dry-run --access public --registry=https://registry.npmjs.org/
 The package test packs the exact candidate, installs it in a fresh offline
 consumer, byte-compares all installed files and checks exports, frames,
 interactions, lifecycle, examples, JSONL and isolated installer settings.
-Its report is `dist/package-check.json`; it does not publish or edit live
+Its report is in a fresh `dist/package-check-*/package-check.json`; it does not publish or edit live
 agent configuration. Keep the final tarball hash and file inventory.
 
 The product workspace is not a Git repository. No public source repository,
@@ -37,7 +41,7 @@ Actions pipeline or npm trusted publisher is implied by this npm release.
 Do not upload this experimental workspace wholesale: original photos, source
 image sheets, workers, QA receipts, credentials and local settings stay local.
 
-## First publish
+## Publish the tested tarball
 
 Confirm `npm whoami` is the intended account. Publish only the tested candidate
 with explicit public access; complete any npm browser/2FA verification through
@@ -58,4 +62,9 @@ discovery alone is not live-host certification. Other agent-native renderers
 remain unimplemented. MCP alone cannot inject a pet into arbitrary agent UIs.
 See INSTALLING.md for support and removal.
 
+The separate Windows transparent companion uses native layered windows plus the
+same pet engine. Test its real installed copy with an isolated state directory and
+owned off-screen diagnostic windows; do not stop the user's live companion merely
+to run QA. Source/native diagnostic evidence is not a cross-platform certification.
+
 Historical research notes remain local and are not current support promises.

package/WINDOWS-COMPANION.md

@@ -0,0 +1,113 @@
+# Windows companion — 0.0.2
+
+This is a separate transparent desktop window, not a Codex plugin or a terminal
+wrapper. Version0.0.2 includes it; version0.0.1 does not. Setup is two steps:
+
+1. `npm install -g @bitefoundry/retrieviewer`
+2. `retrieviewer desktop` — choose the app window in the picker.
+
+Choose a supported ordinary Windows app window (including a terminal containing
+Codex). Then use your app normally, without a
+wrapper, shell alias, patched binary, changed credentials, or agent configuration.
+The helper uses native Windows/.NET Framework facilities and the existing Node
+pet engine. No Electron, Chromium, downloaded helper binary or new npm dependency.
+Windows10/11 x64 with Node20+ and the .NET Framework4 compiler is required. Other
+desktop platforms and exclusive fullscreen/security surfaces are not certified.
+Launch reports
+that the picker is ready, **not** that the user has selected a window or visually
+approved the pet.
+
+## Interaction and window scope
+
+- The original Q5 Braille artwork/behavior engine is reused without new sprites.
+- The pet is click-through and non-activating. It does not read keyboard input.
+- A small separate, non-activating control strip offers ball, treat, choose window,
+  pause and exit. These buttons consume their own clicks, not terminal typing.
+- Ball/treat use the existing engine interactions, including busy/cooldown rules.
+  Ball currently uses its existing preset destination, **not free mouse aiming**.
+- The overlay follows the selected window's client rectangle. It hides and stops
+  simulation when another app is foreground, the target is minimized, or paused.
+  The control strip remains available while paused in the selected window.
+- It binds a whole top-level window, **not a terminal tab/pane**. Switching tabs
+  inside that window does not automatically rebind or identify the running agent.
+- Selection is per launch. There is no process scanning to infer Codex sessions,
+  screen scraping/OCR, chat capture, global keyboard hook or input injection.
+  The picker locally reads window titles/process names; tracking reads window
+  geometry, foreground state, visibility and owning process ID.
+- No automatic startup, background scheduled task, registry entry or MCP is added.
+  Exit stops both the painter and engine. If either process closes, its counterpart
+  exits too. Losing the target hides the pet; tray selection can attach another.
+
+## Stop, remove, and recover
+
+```powershell
+retrieviewer desktop-status --json
+retrieviewer desktop-stop
+retrieviewer desktop-clean --yes
+```
+
+One-command companion removal (stop, wait for exit, remove only its cache):
+
+```powershell
+retrieviewer desktop-remove --yes
+```
+
+The tray icon also provides window selection, hide/resume and exit. `desktop-stop`
+asks the companion to exit through an authenticated local named pipe; it never
+kills a PID from a stale file. The worker may terminate only its own stuck child
+painter after a graceful timeout. Cache cleanup refuses a live/unreachable worker,
+symlinks/junctions and unrecognized session records. It removes only recognized
+helper cache filenames; unrelated files and agent/pet settings remain untouched.
+
+Own files are under `~/.config/retrieviewer/desktop` (or RETRIEVIEWER_HOME/desktop):
+one hash-named compiled helper and a transient local session capability record.
+The token is not printed by status and is never sent over a network. Same-user
+local software is not treated as an adversarial security boundary. No screenshot,
+terminal content or window title is persisted by this companion.
+
+For a globally installed copy, stop/remove the companion before
+`npm uninstall -g @bitefoundry/retrieviewer`. Other native OpenCode registrations,
+if any, must first be disconnected with the existing explicit disconnect command.
+This companion does not change or remove a pre-existing Codex `/pets` pack.
+
+## Rendering and bounded work
+
+Native pixels are dots decoded from the engine's existing Braille cells, on an
+alpha-transparent bitmap. Every frame starts clear, avoiding previous-frame paw
+trails. Only the nonblank bounding rectangle crosses IPC and is painted; the
+native window does not allocate a full-screen transparent bitmap. A request/ack
+bridge permits only one frame in flight. Viewport revisions discard frames from
+an old size/position; discarded frames are acknowledged to avoid deadlock. Hidden
+time is not replayed when the pet becomes visible. The engine targets30fps, but
+the actual frame rate depends on CPU, window resolution and Windows scheduling.
+
+## Search-first decision and evidence
+
+Reused `createPet` and its side-effect-free host API. A small native Win32 painter
+was selected for Windows instead of adding an Electron runtime or a PTY wrapper.
+The former adds another browser runtime; the latter changes how Codex is launched
+and was explicitly rejected. This is not a claim of cross-platform support or a
+benchmarked memory advantage; measurements belong to the local validation.
+
+- [Layered windows and mouse passthrough](https://learn.microsoft.com/en-us/windows/win32/winmsg/window-features#layered-windows)
+- [UpdateLayeredWindow](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-updatelayeredwindow)
+- [No-activate extended window style](https://learn.microsoft.com/en-us/windows/win32/winmsg/extended-window-styles)
+- [SetWindowPos without activation](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setwindowpos)
+- [Electron alternative](https://www.electronjs.org/docs/latest/tutorial/custom-window-interactions)
+
+`node --test retrieviewer-desktop.test.mjs` covers transport/cropping/backpressure,
+hidden-time resets, CLI isolation, authenticated control transport and conservative
+cleanup. Native validation must additionally test layered window rendering, focus,
+geometry, minimize/restore, controls and lifecycle on an actual Windows desktop.
+Do not equate style checks or a rendered PNG with end-user visual approval.
+
+Local validation on2026-10-23:281 automated tests passed, real packaged offline
+consumer passed, and the real native worker painted frames with the actual pet
+engine. The native ball button reached the engine and was accepted; an incorrect
+control token was rejected. Owned off-screen native-window checks passed position
+tracking, minimize/restore, passthrough/no-activate styles and foreground retention.
+The worker and painter both exited. Node RSS was about157MiB in that small-window
+check (not total app memory or a4K performance claim). A Windows GUI startup bug
+was fixed by building a GUI-subsystem helper and not applying SW_HIDE to it; the
+real user picker was verified in Windows' visible main-window list. User visual
+approval after selecting a terminal remains separate.

package/integrations/windows-overlay/Overlay.cs

@@ -0,0 +1,259 @@
+// Native Windows painter for the existing Braille engine. No injection, keyboard
+// hooks, terminal output, screen capture, network, registry or agent config access.
+// Built locally with the Windows .NET Framework compiler; no downloaded binaries.
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Drawing;
+using System.Drawing.Imaging;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using System.Web.Script.Serialization;
+using System.Windows.Forms;
+
+static class Native {
+    [StructLayout(LayoutKind.Sequential)] internal struct POINT { internal int X,Y; internal POINT(int x,int y){X=x;Y=y;} }
+    [StructLayout(LayoutKind.Sequential)] internal struct SIZE { internal int Width,Height; internal SIZE(int w,int h){Width=w;Height=h;} }
+    [StructLayout(LayoutKind.Sequential)] internal struct RECT { internal int Left,Top,Right,Bottom; }
+    [StructLayout(LayoutKind.Sequential,Pack=1)] internal struct BLEND { internal byte Op,Flags,Alpha,Format; }
+    internal delegate bool EnumProc(IntPtr hwnd,IntPtr data);
+    [DllImport("user32.dll")] internal static extern bool EnumWindows(EnumProc proc,IntPtr data);
+    [DllImport("user32.dll")] internal static extern bool IsWindowVisible(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern bool IsWindow(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern bool IsIconic(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern IntPtr GetForegroundWindow();
+    [DllImport("user32.dll",CharSet=CharSet.Unicode)] internal static extern int GetWindowText(IntPtr hwnd,StringBuilder text,int length);
+    [DllImport("user32.dll")] internal static extern uint GetWindowThreadProcessId(IntPtr hwnd,out uint pid);
+    [DllImport("user32.dll")] internal static extern bool GetClientRect(IntPtr hwnd,out RECT rect);
+    [DllImport("user32.dll")] internal static extern bool GetWindowRect(IntPtr hwnd,out RECT rect);
+    [DllImport("user32.dll")] internal static extern bool ClientToScreen(IntPtr hwnd,ref POINT point);
+    [DllImport("user32.dll")] internal static extern bool SetWindowPos(IntPtr hwnd,IntPtr after,int x,int y,int w,int h,uint flags);
+    [DllImport("user32.dll")] internal static extern int GetWindowLong(IntPtr hwnd,int index);
+    [DllImport("user32.dll")] internal static extern bool ShowWindow(IntPtr hwnd,int command);
+    [DllImport("user32.dll")] internal static extern bool SetProcessDPIAware();
+    [DllImport("user32.dll")] internal static extern bool SetProcessDpiAwarenessContext(IntPtr context);
+    [DllImport("user32.dll")] internal static extern IntPtr GetDC(IntPtr hwnd);
+    [DllImport("user32.dll")] internal static extern int ReleaseDC(IntPtr hwnd,IntPtr dc);
+    [DllImport("gdi32.dll")] internal static extern IntPtr CreateCompatibleDC(IntPtr dc);
+    [DllImport("gdi32.dll")] internal static extern IntPtr SelectObject(IntPtr dc,IntPtr bitmap);
+    [DllImport("gdi32.dll")] internal static extern bool DeleteDC(IntPtr dc);
+    [DllImport("gdi32.dll")] internal static extern bool DeleteObject(IntPtr obj);
+    [DllImport("user32.dll",SetLastError=true)] internal static extern bool UpdateLayeredWindow(IntPtr hwnd,IntPtr dc,ref POINT dst,ref SIZE size,IntPtr src,ref POINT point,int key,ref BLEND blend,int flags);
+    internal static Rectangle ClientBounds(IntPtr hwnd){
+        RECT r;POINT p=new POINT(0,0);
+        if(!GetClientRect(hwnd,out r)||!ClientToScreen(hwnd,ref p))return Rectangle.Empty;
+        return new Rectangle(p.X,p.Y,r.Right-r.Left,r.Bottom-r.Top);
+    }
+    internal static void Place(IntPtr hwnd,Rectangle rect){
+        SetWindowPos(hwnd,new IntPtr(-1),rect.X,rect.Y,rect.Width,rect.Height,0x10|0x40); // TOPMOST, NOACTIVATE, SHOWWINDOW
+    }
+}
+
+class QuietWindow : Form {
+    internal QuietWindow(){FormBorderStyle=FormBorderStyle.None;ShowInTaskbar=false;AutoScaleMode=AutoScaleMode.None;StartPosition=FormStartPosition.Manual;}
+    protected override bool ShowWithoutActivation {get{return true;}}
+    protected override CreateParams CreateParams {get{CreateParams p=base.CreateParams;p.ExStyle|=0x08000000|0x80;return p;}} // NOACTIVATE, TOOLWINDOW
+    protected override void WndProc(ref Message m){if(m.Msg==0x21){m.Result=new IntPtr(3);return;}base.WndProc(ref m);} // MA_NOACTIVATE
+}
+
+sealed class PetWindow : QuietWindow {
+    protected override CreateParams CreateParams {get{CreateParams p=base.CreateParams;p.ExStyle|=0x80000|0x20;return p;}} // LAYERED + TRANSPARENT
+    internal int PaintedDots;
+    internal Bitmap PaintFrame(Dictionary<string,object> m,int cell,Rectangle canvas){
+        int cols=Program.Int(m,"columns"),rows=Program.Int(m,"rows"),cx=Program.Int(m,"x"),cy=Program.Int(m,"y");
+        string text=Program.Str(m,"text");
+        if(cols==0&&rows==0&&text.Length==0){Hide();return null;}
+        if(cols<1||rows<1||cols*rows>125000||cx<0||cy<0||(cx+cols)*cell>canvas.Width||(cy+rows)*cell*2>canvas.Height)throw new Exception("Out-of-bounds overlay frame");
+        string[] lines=text.Split('\n');if(lines.Length!=rows)throw new Exception("Invalid overlay row count");
+        Bitmap image=new Bitmap(cols*cell,rows*cell*2,PixelFormat.Format32bppPArgb);
+        try{
+            using(Graphics g=Graphics.FromImage(image))using(Brush ink=new SolidBrush(Color.FromArgb(245,248,242,232))){
+                g.Clear(Color.Transparent);g.SmoothingMode=System.Drawing.Drawing2D.SmoothingMode.AntiAlias;
+                int[] dx={0,0,0,1,1,1,0,1},dy={0,1,2,0,1,2,3,3};float step=cell/2f,diameter=Math.Max(1.1f,step*.48f);PaintedDots=0;
+                for(int y=0;y<rows;y++){
+                    if(lines[y].Length!=cols)throw new Exception("Invalid overlay column count");
+                    for(int x=0;x<cols;x++){
+                        int mask=lines[y][x]-0x2800;if(mask<0||mask>255)throw new Exception("Not a Braille frame");
+                        for(int bit=0;bit<8;bit++)if((mask&(1<<bit))!=0){
+                            float px=x*cell+(dx[bit]+.5f)*step,py=y*cell*2+(dy[bit]+.5f)*step;
+                            g.FillEllipse(ink,px-diameter/2,py-diameter/2,diameter,diameter);PaintedDots++;
+                        }
+                    }
+                }
+            }
+            Rectangle destination=new Rectangle(canvas.X+cx*cell,canvas.Y+cy*cell*2,image.Width,image.Height);
+            if(!Visible){Bounds=destination;Show();}
+            IntPtr screen=Native.GetDC(IntPtr.Zero),memory=Native.CreateCompatibleDC(screen),bitmap=IntPtr.Zero,old=IntPtr.Zero;
+            try{
+                bitmap=image.GetHbitmap(Color.FromArgb(0));old=Native.SelectObject(memory,bitmap);
+                Native.POINT target=new Native.POINT(canvas.X+cx*cell,canvas.Y+cy*cell*2),source=new Native.POINT(0,0);
+                Native.SIZE size=new Native.SIZE(image.Width,image.Height);Native.BLEND blend=new Native.BLEND();blend.Alpha=255;blend.Format=1;
+                if(!Native.UpdateLayeredWindow(Handle,screen,ref target,ref size,memory,ref source,0,ref blend,2))throw new System.ComponentModel.Win32Exception(Marshal.GetLastWin32Error());
+                Native.Place(Handle,new Rectangle(target.X,target.Y,size.Width,size.Height));
+            }finally{if(old!=IntPtr.Zero)Native.SelectObject(memory,old);if(bitmap!=IntPtr.Zero)Native.DeleteObject(bitmap);Native.DeleteDC(memory);Native.ReleaseDC(IntPtr.Zero,screen);}
+            return image;
+        }catch{image.Dispose();throw;}
+    }
+}
+
+sealed class TargetItem {
+    internal IntPtr Window;internal uint Process;internal string Title;internal bool Terminal;
+    public override string ToString(){return Title;}
+}
+
+sealed class Companion : ApplicationContext {
+    readonly PetWindow pet=new PetWindow();readonly QuietWindow bar=new QuietWindow();
+    readonly NotifyIcon tray=new NotifyIcon();readonly System.Windows.Forms.Timer clock=new System.Windows.Forms.Timer();
+    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;
+    internal Companion(Mutex single,bool diagnostic){
+        mutex=single;testMode=diagnostic;bar.Text="Retrieviewer controls";bar.Size=new Size(354,40);bar.BackColor=Color.FromArgb(28,30,34);bar.ForeColor=Color.White;
+        bar.Font=new Font("Segoe UI",9);bar.Controls.Add(MakeButton("공",8,()=>Interact("ball")));bar.Controls.Add(MakeButton("간식",52,()=>Interact("treat")));
+        bar.Controls.Add(MakeButton("창",102,ChooseTarget));bar.Controls.Add(MakeButton("쉼",146,TogglePause));bar.Controls.Add(MakeButton("종료",190,Quit));
+        status.AutoSize=false;status.Location=new Point(240,12);status.Size=new Size(110,22);status.Text="준비 중";bar.Controls.Add(status);
+        ContextMenuStrip menu=new ContextMenuStrip();menu.Items.Add("다른 창 선택",null,(s,e)=>ChooseTarget());menu.Items.Add("숨기기 / 다시 표시",null,(s,e)=>TogglePause());menu.Items.Add("종료",null,(s,e)=>Quit());
+        tray.Icon=SystemIcons.Application;tray.Text="Retrieviewer · 창 선택";tray.ContextMenuStrip=menu;tray.Visible=true;tray.DoubleClick+=(s,e)=>ChooseTarget();
+        // Handles are created on the UI thread before the reader can signal EOF.
+        IntPtr unused=bar.Handle;unused=pet.Handle;
+        Thread reader=new Thread(ReadInput);reader.IsBackground=true;reader.Start();
+        clock.Interval=16;clock.Tick+=(s,e)=>Tick();clock.Start();
+        if(testMode){
+            testTarget=new QuietWindow();testTarget.Bounds=new Rectangle(-12000,-12000,1280,800);testTarget.Show();
+            target=new TargetItem{Window=testTarget.Handle,Process=(uint)Process.GetCurrentProcess().Id,Title="owned diagnostic window"};
+        }
+    }
+    Button MakeButton(string title,int x,Action action){
+        Button b=new Button();b.Text=title;b.TabStop=false;b.Size=new Size(title=="간식"?46:40,28);b.Location=new Point(x,6);b.FlatStyle=FlatStyle.Flat;b.FlatAppearance.BorderSize=0;b.BackColor=Color.FromArgb(48,51,58);b.ForeColor=Color.White;b.Click+=(s,e)=>action();return b;
+    }
+    void ReadInput(){
+        try{
+            string line;while((line=Program.Input.ReadLine())!=null){
+                if(line.Length>800000)break;
+                Dictionary<string,object> value=json.Deserialize<Dictionary<string,object>>(line);
+                lock(inputLock){if(messages.Count>4)break;messages.Enqueue(value);}
+            }
+        }catch{}
+        try{bar.BeginInvoke(new Action(Quit));}catch{}
+    }
+    void Interact(string kind){if(!loaded||paused)return;Program.Emit(new {type="interact",kind=kind});}
+    void TogglePause(){paused=!paused;Program.Emit(new {type="pause",paused=paused});Track(true);}
+    void Tick(){
+        if(quitting)return;
+        try{
+            if(!announced){announced=true;if(!testMode)ChooseTarget();Program.Emit(new {type="ready",pickerVisible=pickerWindow!=null&&pickerWindow.Visible});}
+            Track(false);
+            for(;;){Dictionary<string,object> m;lock(inputLock){if(messages.Count==0)break;m=messages.Dequeue();}
+                string type=Program.Str(m,"type");
+                if(type=="quit"){Quit();return;}
+                if(type=="loaded"){loaded=true;status.Text="함께 노는 중";if(testMode)((Button)bar.Controls[0]).PerformClick();continue;}
+                if(type=="interaction"){status.Text=Program.Bool(m,"accepted")?"좋아!":"잠깐 기다려";continue;}
+                if(type=="error"){status.Text="엔진 오류";Quit();return;}
+                if(type=="frame"){
+                    // Always acknowledge discarded frames too, otherwise resizing can deadlock the sender.
+                    bool painted=visible&&!paused&&Program.Int(m,"revision")==revision;
+                    if(painted){using(Bitmap image=pet.PaintFrame(m,cell,canvas)){} }
+                    Program.Emit(new {type="ack",painted=painted});
+                }
+            }
+        }catch(Exception error){Program.Emit(new {type="error",message=error.Message});Quit();}
+    }
+    void Track(bool force){
+        Rectangle next=Rectangle.Empty;bool show=false;uint pid;
+        if(target!=null&&(!Native.IsWindow(target.Window)||Native.GetWindowThreadProcessId(target.Window,out pid)==0||pid!=target.Process)){target=null;}
+        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 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();
+            Program.Emit(new {type="viewport",revision=revision,visible=show&&!paused,selected=target!=null,columns=columns,rows=rows,cellWidth=cell,cellHeight=cell*2});
+        }
+        if(visible){
+            if(!bar.Visible)bar.Show();Native.Place(bar.Handle,new Rectangle(canvas.Right-bar.Width-10,canvas.Top+10,bar.Width,bar.Height));
+            if(paused)pet.Hide();
+        }else{pet.Hide();bar.Hide();}
+    }
+    List<TargetItem> Targets(){
+        List<TargetItem> result=new List<TargetItem>();uint mine=(uint)Process.GetCurrentProcess().Id;
+        Native.EnumWindows((hwnd,data)=>{
+            uint pid;Native.GetWindowThreadProcessId(hwnd,out pid);if(pid==mine||!Native.IsWindowVisible(hwnd))return true;
+            StringBuilder name=new StringBuilder(512);Native.GetWindowText(hwnd,name,name.Capacity);if(name.Length==0)return true;
+            string process="";try{using(Process p=Process.GetProcessById((int)pid)){process=p.ProcessName;}}catch{}
+            bool terminal=process.Equals("WindowsTerminal",StringComparison.OrdinalIgnoreCase)||process.IndexOf("wezterm",StringComparison.OrdinalIgnoreCase)>=0||process=="OpenConsole"||process=="conhost"||process=="mintty";
+            result.Add(new TargetItem{Window=hwnd,Process=pid,Title=(terminal?"[터미널] ":"")+name.ToString()+" · "+process,Terminal=terminal});return true;
+        },IntPtr.Zero);
+        result.Sort((a,b)=>a.Terminal==b.Terminal?String.Compare(a.Title,b.Title,StringComparison.CurrentCulture):a.Terminal?-1:1);return result;
+    }
+    void ChooseTarget(){
+        if(picking||quitting)return;picking=true;Track(true);
+        Form picker=new Form();pickerWindow=picker;
+        {
+            picker.Text="Retrieviewer · 함께 있을 창";picker.Size=new Size(650,230);picker.StartPosition=FormStartPosition.CenterScreen;picker.FormBorderStyle=FormBorderStyle.FixedDialog;picker.MaximizeBox=false;picker.MinimizeBox=false;picker.Font=new Font("Segoe UI",10);
+            picker.ShowInTaskbar=true;picker.TopMost=true;
+            Label hint=new Label();hint.Text="Codex를 사용하는 터미널 창을 선택하세요.\n내용을 읽지 않고 창의 위치·크기만 따라갑니다. 탭은 구별하지 않습니다.";hint.SetBounds(18,16,610,50);
+            ComboBox list=new ComboBox();list.DropDownStyle=ComboBoxStyle.DropDownList;list.SetBounds(18,76,600,28);foreach(TargetItem item in Targets())list.Items.Add(item);if(list.Items.Count>0)list.SelectedIndex=0;
+            Button refresh=new Button();refresh.Text="새로 고침";refresh.SetBounds(18,124,100,34);refresh.Click+=(s,e)=>{list.Items.Clear();foreach(TargetItem item in Targets())list.Items.Add(item);if(list.Items.Count>0)list.SelectedIndex=0;};
+            Button attach=new Button();attach.Text="이 창에 붙이기";attach.SetBounds(378,124,140,34);attach.Click+=(s,e)=>{if(list.SelectedItem!=null){target=(TargetItem)list.SelectedItem;paused=false;Program.Emit(new {type="pause",paused=false});picker.Close();}};
+            Button cancel=new Button();cancel.Text="취소";cancel.SetBounds(528,124,90,34);cancel.Click+=(s,e)=>picker.Close();
+            picker.Controls.AddRange(new Control[]{hint,list,refresh,attach,cancel});
+            picker.FormClosed+=(s,e)=>{pickerWindow=null;picking=false;Program.Emit(new {type="picker",visible=false});if(!quitting){if(target==null)status.Text="트레이에서 창 선택";tray.Text=target==null?"Retrieviewer · 창 선택":"Retrieviewer · 창에 붙어 있음";Track(true);}picker.Dispose();};
+            picker.Show();Native.ShowWindow(picker.Handle,5);Program.Emit(new {type="picker",visible=Native.IsWindowVisible(picker.Handle)});
+        }
+    }
+    void Quit(){if(quitting)return;quitting=true;clock.Stop();if(pickerWindow!=null)pickerWindow.Close();pet.Close();bar.Close();tray.Visible=false;tray.Dispose();Program.Emit(new {type="quit"});ExitThread();}
+    protected override void Dispose(bool disposing){if(disposing){clock.Dispose();pet.Dispose();bar.Dispose();tray.Dispose();if(testTarget!=null)testTarget.Dispose();if(mutex!=null){mutex.ReleaseMutex();mutex.Dispose();mutex=null;}}base.Dispose(disposing);}
+}
+
+static class Program {
+    static readonly object outputLock=new object();
+    internal static TextReader Input;static TextWriter Output;
+    internal static void Emit(object value){lock(outputLock){try{Output.WriteLine(new JavaScriptSerializer().Serialize(value));Output.Flush();}catch{Environment.Exit(0);}}}
+    internal static int Int(Dictionary<string,object> m,string key){return Convert.ToInt32(m[key]);}
+    internal static string Str(Dictionary<string,object> m,string key){return Convert.ToString(m[key]);}
+    internal static bool Bool(Dictionary<string,object> m,string key){return Convert.ToBoolean(m[key]);}
+    [STAThread] static int Main(string[] args){
+        try{
+            // GUI-subsystem processes have redirected handles but no console code
+            // page. Setting Console.*Encoding can throw before startup on Windows.
+            Input=new StreamReader(Console.OpenStandardInput(),new UTF8Encoding(false),false);
+            Output=new StreamWriter(Console.OpenStandardOutput(),new UTF8Encoding(false));
+            try{Native.SetProcessDpiAwarenessContext(new IntPtr(-4));}catch(EntryPointNotFoundException){Native.SetProcessDPIAware();}
+            Application.EnableVisualStyles();Application.SetCompatibleTextRenderingDefault(false);
+            if(args.Length==2&&args[0]=="--self-test")return SelfTest(args[1]);
+            bool ipcTest=args.Length==1&&args[0]=="--ipc-test";
+            if(args.Length!=0&&!ipcTest)throw new Exception("Unsupported native painter argument");
+            // Diagnostics own only off-screen windows and must not stop or contend
+            // with a user's running companion during a release verification.
+            string mutexName="Local\\BiteFoundry.Retrieviewer.Overlay."+System.Security.Principal.WindowsIdentity.GetCurrent().User.Value+(ipcTest?".Diagnostics."+Process.GetCurrentProcess().Id:"");
+            bool first;Mutex single=new Mutex(true,mutexName,out first);
+            if(!first){single.Dispose();Emit(new {type="error",message="A Retrieviewer companion is already running"});return 2;}
+            using(Companion context=new Companion(single,ipcTest))Application.Run(context);return 0;
+        }catch(Exception error){Emit(new {type="error",message=error.Message});return 1;}
+    }
+    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();
+        Dictionary<string,object> frame=new JavaScriptSerializer().Deserialize<Dictionary<string,object>>(Input.ReadLine());
+        using(QuietWindow target=new QuietWindow())using(PetWindow pet=new PetWindow()){
+            target.Bounds=new Rectangle(-12000,-12000,1600,1000);target.Show();Application.DoEvents();
+            Rectangle first=Native.ClientBounds(target.Handle);using(Bitmap bitmap=pet.PaintFrame(frame,8,first)){bitmap.Save(proof,ImageFormat.Png);}
+            int styles=Native.GetWindowLong(pet.Handle,-20);bool clickThrough=(styles&0x20)!=0,noActivate=(styles&0x08000000)!=0,layered=(styles&0x80000)!=0;
+            target.Bounds=new Rectangle(-11000,-11500,1800,1100);Application.DoEvents();Rectangle moved=Native.ClientBounds(target.Handle);
+            using(Bitmap bitmap=pet.PaintFrame(frame,8,moved)){}
+            Native.RECT actual;Native.GetWindowRect(pet.Handle,out actual);
+            int expectedX=moved.Left+Int(frame,"x")*8,expectedY=moved.Top+Int(frame,"y")*16;
+            bool follows=actual.Left==expectedX&&actual.Top==expectedY;
+            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;
+        }
+    }
+}

package/integrations/windows-overlay/desktop.mjs

@@ -0,0 +1,87 @@
+// Explicit Windows companion launcher. Never imports the pet on help/status/stop.
+import {spawn,execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {readFile,mkdir,lstat,unlink,open,rename,readdir} from 'node:fs/promises';
+import {createHash,randomUUID} from 'node:crypto';
+import {join,dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createConnection} from 'node:net';
+import {getConfigPaths} from '../../retrieviewer-config.mjs';
+const exec=promisify(execFile);
+const SOURCE=new URL('./Overlay.cs',import.meta.url);
+export function desktopPaths(options={}){const root=join(getConfigPaths(options).root,'desktop');return {root,session:join(root,'session.json')};}
+export async function noLink(path){try{if((await lstat(path)).isSymbolicLink())throw Error('Refusing desktop symlink: '+path);}catch(e){if(e.code!=='ENOENT')throw e;}}
+export async function prepareRoot(options={}){
+ const parent=getConfigPaths(options).root,{root}=desktopPaths(options);await noLink(dirname(parent));await noLink(parent);await noLink(root);await mkdir(root,{recursive:true,mode:0o700});return desktopPaths(options);
+}
+export async function readSession(options={}){
+ const {root,session}=desktopPaths(options);await noLink(dirname(root));await noLink(root);await noLink(session);
+ let data;try{data=JSON.parse(await readFile(session,'utf8'));}catch(e){if(e.code==='ENOENT')return null;throw e;}
+ if(data?.owner!=='bitefoundry-retrieviewer-overlay-v1'||!Number.isInteger(data.pid)||data.pid<=0||!/^\\\\\.\\pipe\\retrieviewer-overlay-[a-f0-9-]{36}$/.test(data.pipe)||!/^[a-f0-9]{64}$/.test(data.token))throw Error('Unrecognized desktop session; not modifying it');
+ return data;
+}
+export function requestSession(session,command){
+ return new Promise((resolve,reject)=>{
+  const socket=createConnection(session.pipe);let text='',done=false;
+  const finish=(error,value)=>{if(done)return;done=true;socket.destroy();error?reject(error):resolve(value);};
+  socket.setTimeout(1800,()=>finish(Error('Desktop control timed out')));
+  socket.on('connect',()=>socket.write(JSON.stringify({token:session.token,command})+'\n'));
+  socket.on('data',bytes=>{text+=bytes.toString('utf8');if(text.length>65536)return finish(Error('Oversized desktop response'));if(text.includes('\n'))try{finish(null,JSON.parse(text.split('\n')[0]));}catch(e){finish(e);}});
+  socket.on('error',e=>finish(e));socket.on('end',()=>{if(!done)finish(Error('Desktop control closed without a response'));});
+ });
+}
+export async function desktopStatus(options={}){
+ const session=await readSession(options);if(!session)return {running:false};
+ try{return await requestSession(session,'status');}catch(error){let alive=true;try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')alive=false;}
+  return {running:alive,reachable:false,stale:!alive,pid:session.pid,reason:error.code??error.message};}
+}
+export async function stopDesktop(options={}){
+ const session=await readSession(options);if(!session)return {running:false,stopped:true};
+ const result=await desktopStatus(options);
+ if(result.stale){await unlink(desktopPaths(options).session);return {running:false,stopped:true,staleSessionRemoved:true};}
+ if(result.reachable===false)throw Error('Desktop process is not responding; close it from its tray icon. No PID was killed.');
+ await requestSession(session,'stop');
+ // The stop response acknowledges the request, not native process termination.
+ // Wait before advertising success so a following cleanup cannot race an in-use exe.
+ for(let i=0;i<60;i++){
+  try{process.kill(session.pid,0);}catch(e){if(e.code==='ESRCH')return {running:false,stopped:true};throw e;}
+  await new Promise(resolve=>setTimeout(resolve,100));
+ }
+ throw Error('Desktop accepted stop but has not exited; cache preserved. Retry after it closes.');
+}
+export async function buildHelper(options={}){
+ if(process.platform!=='win32')throw Error('The transparent companion currently supports Windows only');
+ const {root}=await prepareRoot(options),source=await readFile(SOURCE),hash=createHash('sha256').update(source).digest('hex').slice(0,20);
+ const executable=join(root,`overlay-${hash}.exe`);await noLink(executable);
+ try{await lstat(executable);return executable;}catch(e){if(e.code!=='ENOENT')throw e;}
+ const compiler=join(process.env.SystemRoot??'C:\\Windows','Microsoft.NET','Framework64','v4.0.30319','csc.exe');
+ const temporary=join(root,`build-${randomUUID()}.exe`);
+ try{
+  await exec(compiler,['/nologo','/target:winexe','/platform:anycpu','/optimize+','/codepage:65001','/reference:System.Windows.Forms.dll','/reference:System.Drawing.dll','/reference:System.Web.Extensions.dll','/out:'+temporary,fileURLToPath(SOURCE)],{windowsHide:true,timeout:30000,maxBuffer:1024*1024});
+  await rename(temporary,executable);
+ }catch(error){await unlink(temporary).catch(()=>{});throw Error('Windows overlay build failed: '+(error.stdout??error.message));}
+ return executable;
+}
+export async function startDesktop(options={}){
+ const status=await desktopStatus(options);if(status.running)return {...status,alreadyRunning:true};
+ if(status.stale)await stopDesktop(options);
+ const executable=await buildHelper(options);
+ return new Promise((resolve,reject)=>{
+  const child=spawn(process.execPath,[fileURLToPath(new URL('./worker.mjs',import.meta.url)),executable],{detached:true,windowsHide:true,stdio:['ignore','ignore','ignore','ipc'],env:{...process.env,RETRIEVIEWER_HOME:getConfigPaths(options).root}});
+  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+')')));
+ });
+}
+export async function cleanDesktop(options={}){
+ const status=await desktopStatus(options);if(status.running)throw Error('Stop the desktop companion before removing its cache');
+ const {root,session}=desktopPaths(options);if(status.stale)await unlink(session);
+ let files;try{await noLink(root);files=await readdir(root);}catch(e){if(e.code==='ENOENT')return {removed:[]};throw e;}
+ const removed=[];
+ for(const name of files)if(/^overlay-[a-f0-9]{20}\.exe$/.test(name)||/^build-[a-f0-9-]{36}\.exe$/.test(name)){
+  const path=join(root,name);await noLink(path);if(!(await lstat(path)).isFile())throw Error('Refusing non-file desktop cache entry');await unlink(path);removed.push(name);
+ }
+ // Unknown files and all other Retrieviewer/agent settings are deliberately kept.
+ return {removed,preservedOtherFiles:true};
+}
+export async function removeDesktop(options={}){await stopDesktop(options);return {stopped:true,...await cleanDesktop(options)};}

package/integrations/windows-overlay/protocol.mjs

@@ -0,0 +1,39 @@
+// Pure transport helpers: no art, timers, processes or I/O on import.
+export function viewportOf(message){
+ if(message?.type!=='viewport'||!Number.isSafeInteger(message.revision)||message.revision<1||typeof message.visible!=='boolean')throw Error('Invalid overlay viewport');
+ if(!message.visible)return null;
+ const {columns,rows,cellWidth,cellHeight}=message;
+ if(!Number.isInteger(columns)||!Number.isInteger(rows)||columns<1||rows<1||columns*rows>125000||![6,8,10,12,16].includes(cellWidth)||cellHeight!==cellWidth*2)throw Error('Invalid overlay grid');
+ return {columns,rows,cellAspect:.5,revision:message.revision,cellWidth,cellHeight};
+}
+export function cropFrame(frame,revision){
+ const lines=frame.text.split('\n');
+ if(lines.length!==frame.rows||lines.some(s=>s.length!==frame.columns))throw Error('Invalid frame dimensions');
+ let left=frame.columns,top=frame.rows,right=-1,bottom=-1;
+ for(let y=0;y<lines.length;y++)for(let x=0;x<lines[y].length;x++){
+  const c=lines[y].charCodeAt(x);if(c<0x2800||c>0x28ff)throw Error('Only Braille cells may cross the overlay bridge');
+  if(c!==0x2800){left=Math.min(left,x);right=Math.max(right,x);top=Math.min(top,y);bottom=Math.max(bottom,y);}
+ }
+ return {type:'frame',revision,x:right<0?0:left,y:right<0?0:top,columns:right<0?0:right-left+1,rows:right<0?0:bottom-top+1,
+  text:right<0?'':lines.slice(top,bottom+1).map(s=>s.slice(left,right+1)).join('\n')};
+}
+
+// Request/ack rendering: never queue obsolete frames behind a slow native painter.
+export function createFramePump({pet,send,now=()=>performance.now()}){
+ let viewport=null,inFlight=false,last=null,revision=0,paused=false,disposed=false;
+ const alive=()=>{if(disposed)throw Error('Overlay pump is disposed');};
+ return {
+  viewport(message){alive();const next=viewportOf(message);revision=message.revision;viewport=next;last=null;},
+  pause(value){alive();paused=!!value;last=null;},
+  ack(){alive();inFlight=false;},
+  tick(){
+   alive();if(inFlight||!viewport||paused)return false;
+   const t=now(),dt=last===null?0:Math.max(0,(t-last)/1000);last=t;
+   pet.step(dt);const frame=pet.frame(viewport);inFlight=true;
+   try{send(cropFrame(frame,revision));}catch(error){inFlight=false;throw error;}return true;
+  },
+  interact(kind){alive();if(!['ball','treat'].includes(kind))throw Error('Invalid overlay interaction');return pet.interact(kind);},
+  get hidden(){return !viewport||paused;},
+  dispose(){if(!disposed){disposed=true;viewport=null;pet.dispose();}},
+ };
+}

package/integrations/windows-overlay/worker.mjs

@@ -0,0 +1,60 @@
+// Private detached worker, started only by the explicit `desktop` command.
+import {spawn} from 'node:child_process';
+import {createServer} from 'node:net';
+import {createInterface} from 'node:readline';
+import {open,unlink,readFile} from 'node:fs/promises';
+import {randomBytes,randomUUID} from 'node:crypto';
+import {prepareRoot,noLink} from './desktop.mjs';
+import {createFramePump} from './protocol.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;
+const sendParent=message=>{if(process.connected)process.send(message);};
+async function stop(){
+ if(stopping)return;stopping=true;clearInterval(timer);pump?.dispose();
+ if(helper&&!helper.killed){try{helper.stdin.end(JSON.stringify({type:'quit'})+'\n');}catch{}}
+ if(server)server.close();
+ if(owned)try{const current=JSON.parse(await readFile(paths.session,'utf8'));if(current.token===session.token)await unlink(paths.session);}catch{}
+ // A wedged painter is our own child only, never the selected terminal.
+ const watchdog=setTimeout(()=>{helper?.kill();process.exit(0);},2500);watchdog.unref();
+ if(!helper||helper.exitCode!==null)process.exitCode=0;
+}
+process.on('SIGTERM',stop);process.on('SIGINT',stop);process.on('message',m=>{if(m?.command==='abort')stop();});
+try{
+ paths=await prepareRoot();await noLink(paths.session);
+ session={owner:'bitefoundry-retrieviewer-overlay-v1',pid:process.pid,pipe:'\\\\.\\pipe\\retrieviewer-overlay-'+randomUUID(),token:randomBytes(32).toString('hex')};
+ const record=await open(paths.session,'wx',0o600);owned=true;try{await record.writeFile(JSON.stringify(session)+'\n');}finally{await record.close();}
+ server=createServer(socket=>{
+  socket.setTimeout(1500,()=>socket.destroy());let body='';
+  socket.on('error',()=>{});socket.on('data',bytes=>{
+   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,pid:process.pid,painterPid:helper?.pid,rssBytes:process.memoryUsage().rss})+'\n');
+   if(command.command==='stop')stop();
+  });
+ });
+ await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(session.pipe,resolve);});
+ // GUI-subsystem exe: no console to hide. SW_HIDE here also hides its first UI.
+ helper=spawn(process.argv[2],process.argv[3]==='--ipc-test'?['--ipc-test']:[],{windowsHide:false,stdio:['pipe','pipe','pipe']});
+ helper.stdin.on('error',()=>stop());helper.stderr.resume();helper.once('error',error=>{sendParent({error:error.message});stop();});
+ helper.once('exit',code=>{if(!stopping)sendParent({error:'Windows painter exited ('+code+')'});stop();});
+ const write=message=>{if(!stopping&&!helper.stdin.destroyed)helper.stdin.write(JSON.stringify(message)+'\n');};
+ const reader=createInterface({input:helper.stdout});
+ reader.on('line',line=>{
+  if(line.length>100000)return stop();let m;try{m=JSON.parse(line);}catch{return stop();}
+  try{
+   if(m.type==='ready'){pickerVisible=m.pickerVisible===true;sendParent({running:true,windowPicker:pickerVisible,mode:'windows-overlay',pid:process.pid});}
+   else if(m.type==='picker')pickerVisible=m.visible===true;
+   else if(m.type==='viewport'){pendingViewport=m;visible=m.visible;selected=m.selected===true;pump?.viewport(m);}
+   else if(m.type==='ack'){frames++;if(m.painted)paintedFrames++;pump?.ack();}
+   else if(m.type==='pause')pump?.pause(m.paused);
+   else if(m.type==='interact'){const accepted=pump?.interact(m.kind)??false;lastInteraction={kind:m.kind,accepted};write({type:'interaction',kind:m.kind,accepted});}
+   else if(m.type==='quit')stop();
+  }catch(error){write({type:'error',message:error.message});stop();}
+ });
+ const {createPet}=await import('../../retrieviewer.mjs');const pet=await createPet();
+ if(stopping)pet.dispose();else{
+  pump=createFramePump({pet,send:write});if(pendingViewport)pump.viewport(pendingViewport);
+  write({type:'loaded'});timer=setInterval(()=>{try{pump.tick();}catch(error){write({type:'error',message:error.message});stop();}},1000/30);
+ }
+}catch(error){sendParent({error:error.message});await stop();}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@bitefoundry/retrieviewer",
-  "version": "0.0.1",
-  "description": "Embeddable autonomous Braille retriever for TUI panes; Q5 art included, host-owned input and screen.",
+  "version": "0.0.2",
+  "description": "A fluffy Braille desktop companion for Windows apps, plus an embeddable TUI pet. Give it a ball or a treat.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/BiteFoundry",
-  "keywords": ["tui", "braille", "pet", "retriever", "opencode"],
+  "keywords": ["tui", "braille", "pet", "retriever", "opencode", "desktop-pet", "windows", "overlay"],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
@@ -52,6 +52,11 @@
     "retrieviewer-config.mjs",
     "integrations/opencode/tui.tsx",
     "integrations/opencode/runtime.mjs",
+    "integrations/windows-overlay/protocol.mjs",
+    "integrations/windows-overlay/desktop.mjs",
+    "integrations/windows-overlay/worker.mjs",
+    "integrations/windows-overlay/Overlay.cs",
+    "WINDOWS-COMPANION.md",
     "INSTALLING.md",
     "PLUGIN.md",
     "EMBEDDING.md",
@@ -114,6 +119,7 @@
     "terminal": "node terminal.mjs",
     "pet": "node puppy-terminal.mjs",
     "pet:companion": "node examples/live.mjs",
+    "pet:desktop": "node retrieviewer-cli.mjs desktop",
     "test": "node --test \"*.test.mjs\"",
     "test:locomotion": "node check-locomotion.mjs",
     "test:package": "node check-pet-package.mjs",

package/retrieviewer-cli.mjs

@@ -13,11 +13,18 @@ Usage:
   retrieviewer doctor [--agent ID] [--json]
   retrieviewer agents [--json]
   retrieviewer preview [--original]
+  retrieviewer desktop
+  retrieviewer desktop-status [--json]
+  retrieviewer desktop-stop
+  retrieviewer desktop-clean --yes
+  retrieviewer desktop-remove --yes
 
 Enable opens a first-run selection/confirmation wizard on a real terminal.
 Non-interactive changes require --agent and --yes. Unsupported native renderers
 are refused: MCP connectivity alone is never treated as in-screen rendering.
 No command changes credentials, shell profiles or agent executables.
+Desktop is a separate Windows overlay, NOT a Codex plugin. Choose a window once;
+use Codex normally. Exit from its tray icon or desktop-stop. No auto-start is added.
 `;
 export function parseArguments(args){
  const [command='help',...rest]=args,options={};
@@ -30,14 +37,20 @@ export function parseArguments(args){
   else throw Error('Unknown argument: '+token);
  }
  if(options.agent&&!AGENTS.some(a=>a.id===options.agent))throw Error('Unknown agent: '+options.agent);
- if(!['help','--help','-h','enable','disable','disconnect','status','doctor','agents','preview'].includes(command))throw Error('Unknown command: '+command);
- const allowed={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']};
+ 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={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()}={}){
+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.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]());return 0;
+ }
  if(command==='preview'){await import('./examples/live.mjs');return 0;}
  if(['status','doctor','agents'].includes(command)){
   const result=command==='agents'?await installer.list():await installer[command](options.agent);