@ycheung5/pi-computer-use 0.0.0-stage → 0.1.1

package/assets/wgc.cs

@@ -0,0 +1,167 @@
+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.Runtime.InteropServices.WindowsRuntime;
+using System.Text;
+using System.Threading;
+using System.Web.Script.Serialization;
+using Windows.Foundation;
+using Windows.Graphics.Capture;
+using Windows.Graphics.DirectX;
+using Windows.Graphics.DirectX.Direct3D11;
+using Windows.Graphics.Imaging;
+
+// Isolated composited-frame fallback. It owns no UI and never sends input.
+class WgcBridge {
+  [ComImport, Guid("3628E81B-3CAC-4C60-B7F4-23CE0E0C3356"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface CaptureInterop {
+    IntPtr CreateForWindow(IntPtr window, ref Guid iid);
+    IntPtr CreateForMonitor(IntPtr monitor, ref Guid iid);
+  }
+  [ComImport, Guid("5B0D3235-4DBA-4D44-865E-8F1D0E4FD04D"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+  interface MemoryBytes { void GetBuffer(out IntPtr bytes, out uint capacity); }
+  [StructLayout(LayoutKind.Sequential)] struct Rect { public int Left, Top, Right, Bottom; }
+  [DllImport("user32.dll")] static extern bool IsWindow(IntPtr window);
+  [DllImport("user32.dll")] static extern bool IsIconic(IntPtr window);
+  [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr window);
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr window, out Rect rect);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr window, out uint process);
+  [DllImport("dwmapi.dll")] static extern int DwmGetWindowAttribute(IntPtr window, int attribute, out Rect rect, int bytes);
+  [DllImport("user32.dll")] static extern bool SetProcessDpiAwarenessContext(IntPtr context);
+  [DllImport("d3d11.dll")] static extern int D3D11CreateDevice(IntPtr adapter, int driver, IntPtr software, uint flags, IntPtr levels, uint count, uint sdk, out IntPtr device, out int level, out IntPtr context);
+  [DllImport("d3d11.dll")] static extern int CreateDirect3D11DeviceFromDXGIDevice(IntPtr device, out IntPtr inspectable);
+
+  static Rectangle Bounds(IntPtr window) {
+    Rect rect;
+    if (DwmGetWindowAttribute(window, 9, out rect, 16) != 0 && !GetWindowRect(window, out rect)) throw new InvalidOperationException("WINDOW_BOUNDS_UNAVAILABLE");
+    return Rectangle.FromLTRB(rect.Left, rect.Top, rect.Right, rect.Bottom);
+  }
+
+  static void Identity(IntPtr window, uint owner) {
+    uint current; GetWindowThreadProcessId(window, out current);
+    if (!IsWindow(window) || current != owner) throw new InvalidOperationException("WINDOW_IDENTITY_CHANGED");
+    if (!IsWindowVisible(window) || IsIconic(window)) throw new InvalidOperationException("WGC_SURFACE_UNAVAILABLE: target is hidden or minimized");
+  }
+
+  static IDirect3DDevice Device() {
+    IntPtr raw = IntPtr.Zero, context = IntPtr.Zero, dxgi = IntPtr.Zero, projected = IntPtr.Zero;
+    try {
+      int level;
+      Marshal.ThrowExceptionForHR(D3D11CreateDevice(IntPtr.Zero, 1, IntPtr.Zero, 0x20, IntPtr.Zero, 0, 7, out raw, out level, out context));
+      Guid iid = new Guid("54EC77FA-1377-44E6-8C32-88FD5F44C84C");
+      Marshal.ThrowExceptionForHR(Marshal.QueryInterface(raw, ref iid, out dxgi));
+      Marshal.ThrowExceptionForHR(CreateDirect3D11DeviceFromDXGIDevice(dxgi, out projected));
+      return (IDirect3DDevice)Marshal.GetObjectForIUnknown(projected);
+    } finally {
+      foreach (IntPtr pointer in new IntPtr[] { projected, dxgi, context, raw }) if (pointer != IntPtr.Zero) Marshal.Release(pointer);
+    }
+  }
+
+  static Bitmap CopyPixels(SoftwareBitmap software) {
+    using (BitmapBuffer buffer = software.LockBuffer(BitmapBufferAccessMode.Read))
+    using (IMemoryBufferReference reference = buffer.CreateReference()) {
+      IntPtr source; uint capacity;
+      ((MemoryBytes)reference).GetBuffer(out source, out capacity);
+      BitmapPlaneDescription plane = buffer.GetPlaneDescription(0);
+      int width = software.PixelWidth, height = software.PixelHeight, rowLength = checked(width * 4);
+      if (width <= 0 || height <= 0 || (long)width * height > 40000000 || plane.StartIndex < 0 || plane.Stride < rowLength || (long)plane.StartIndex + (long)(height - 1) * plane.Stride + rowLength > capacity) throw new InvalidOperationException("WGC_INVALID_PIXEL_BUFFER");
+      Bitmap bitmap = new Bitmap(width, height, PixelFormat.Format32bppArgb);
+      BitmapData output = bitmap.LockBits(new Rectangle(0, 0, width, height), ImageLockMode.WriteOnly, PixelFormat.Format32bppArgb);
+      try {
+        byte[] row = new byte[rowLength];
+        for (int y = 0; y < height; y++) {
+          Marshal.Copy(IntPtr.Add(source, checked(plane.StartIndex + y * plane.Stride)), row, 0, rowLength);
+          Marshal.Copy(row, 0, IntPtr.Add(output.Scan0, y * output.Stride), rowLength);
+        }
+      } catch { bitmap.UnlockBits(output); bitmap.Dispose(); throw; }
+      bitmap.UnlockBits(output); return bitmap;
+    }
+  }
+
+  static void ValidateMarker(Dictionary<string,object> args,IntPtr window,uint owner) {
+    object raw;if(!args.TryGetValue("_windowMarker",out raw) || raw==null)return;
+    var marker=raw as Dictionary<string,object>;object name;
+    if(marker==null || !marker.TryGetValue("name",out name) || !WindowMarker.Matches(window,owner,Convert.ToString(name)))throw new InvalidOperationException("WINDOW_REFERENCE_LOST: delegated capture lifetime proof is unavailable");
+  }
+  static object Capture(Dictionary<string, object> args) {
+    IntPtr window = new IntPtr(Convert.ToInt64(args["nativeWindowHandle"]));
+    uint owner = Convert.ToUInt32(args["processId"]);
+    int maximum = Convert.ToInt32(args["maxWidth"]);
+    ValidateMarker(args,window,owner);Identity(window, owner);
+    Rectangle bounds = Bounds(window);
+    if (bounds.Width <= 0 || bounds.Height <= 0 || (long)bounds.Width * bounds.Height > 40000000) throw new InvalidOperationException("WGC_INVALID_BOUNDS");
+    if (!GraphicsCaptureSession.IsSupported()) throw new InvalidOperationException("WGC_UNSUPPORTED");
+    object factory = WindowsRuntimeMarshal.GetActivationFactory(typeof(GraphicsCaptureItem));
+    Guid itemIid = new Guid("79C3F95B-31F7-4EC2-A464-632EF5D30760");
+    IntPtr itemPointer = ((CaptureInterop)factory).CreateForWindow(window, ref itemIid);
+    GraphicsCaptureItem item;
+    try { item = (GraphicsCaptureItem)Marshal.GetObjectForIUnknown(itemPointer); }
+    finally { Marshal.Release(itemPointer); }
+    Stopwatch deadline = Stopwatch.StartNew();
+    using (IDirect3DDevice device = Device())
+    using (Direct3D11CaptureFramePool pool = Direct3D11CaptureFramePool.CreateFreeThreaded(device, DirectXPixelFormat.B8G8R8A8UIntNormalized, 1, item.Size))
+    using (GraphicsCaptureSession session = pool.CreateCaptureSession(item)) {
+      session.IsCursorCaptureEnabled = true;
+      session.StartCapture();
+      Direct3D11CaptureFrame frame = null;
+      while (frame == null && deadline.ElapsedMilliseconds < 4000) { frame = pool.TryGetNextFrame(); if (frame == null) Thread.Sleep(20); }
+      if (frame == null) throw new TimeoutException("WGC_FRAME_TIMEOUT");
+      using (frame) {
+        IAsyncOperation<SoftwareBitmap> copy = SoftwareBitmap.CreateCopyFromSurfaceAsync(frame.Surface, BitmapAlphaMode.Premultiplied);
+        while (copy.Status == AsyncStatus.Started && deadline.ElapsedMilliseconds < 4000) Thread.Sleep(10);
+        if (copy.Status == AsyncStatus.Started) { copy.Cancel(); throw new TimeoutException("WGC_COPY_TIMEOUT"); }
+        if (copy.Status != AsyncStatus.Completed) throw new InvalidOperationException("WGC_COPY_FAILED: " + copy.Status);
+        using (SoftwareBitmap software = copy.GetResults())
+        using (Bitmap bitmap = CopyPixels(software)) {
+          ValidateMarker(args,window,owner);Identity(window, owner);
+          if (Bounds(window) != bounds) throw new InvalidOperationException("WINDOW_MOVED_DURING_CAPTURE");
+          Bitmap output = bitmap;
+          try {
+            if (maximum > 0 && bitmap.Width > maximum) {
+              output = new Bitmap(maximum, Math.Max(1, (int)Math.Round((double)bitmap.Height * maximum / bitmap.Width)), PixelFormat.Format32bppArgb);
+              using (Graphics graphics = Graphics.FromImage(output)) {
+                graphics.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.HighQualityBicubic;
+                graphics.DrawImage(bitmap, new Rectangle(0, 0, output.Width, output.Height));
+              }
+            }
+            byte[] png;
+            using (MemoryStream memory = new MemoryStream()) { output.Save(memory, ImageFormat.Png); png = memory.ToArray(); }
+            ValidateMarker(args,window,owner);
+            return new Dictionary<string, object> {
+              { "ok", true }, { "action", "screenshot" }, {"windowRef",args.ContainsKey("_windowMarker") && args["_windowMarker"] is Dictionary<string,object>?((Dictionary<string,object>)args["_windowMarker"])["windowRef"]:null}, { "screenshot", new Dictionary<string, object> {
+                { "base64", Convert.ToBase64String(png) }, { "mimeType", "image/png" }, { "bytes", png.Length },
+                { "width", output.Width }, { "height", output.Height }, { "method", "wgc" },
+                { "bounds", new Dictionary<string, object> { { "x", bounds.X }, { "y", bounds.Y }, { "width", bounds.Width }, { "height", bounds.Height } } },
+                { "origin", new Dictionary<string, object> { { "x", bounds.X }, { "y", bounds.Y } } },
+                { "imageScale", (double)output.Width / bounds.Width }, { "imageScaleY", (double)output.Height / bounds.Height },
+                { "windowRef",args.ContainsKey("_windowMarker") && args["_windowMarker"] is Dictionary<string,object>?((Dictionary<string,object>)args["_windowMarker"])["windowRef"]:null }, { "source", "window" }, { "occludedPossible", false }, { "windowCaptureFailed", false }, { "captureWarnings", new string[0] }
+              } }
+            };
+          } finally { if (output != bitmap) output.Dispose(); }
+        }
+      }
+    }
+  }
+
+  [MTAThread]
+  static void Main() {
+    Console.InputEncoding = new UTF8Encoding(false); Console.OutputEncoding = new UTF8Encoding(false);
+    SetProcessDpiAwarenessContext(new IntPtr(-4));
+    JavaScriptSerializer json = new JavaScriptSerializer { MaxJsonLength = 32 * 1024 * 1024 };
+    string line;
+    while ((line = Console.ReadLine()) != null) {
+      try {
+        Dictionary<string, object> request = json.Deserialize<Dictionary<string, object>>(line);
+        if (request.ContainsKey("cancel")) continue;
+        object result;
+        try { result = Capture((Dictionary<string, object>)request["args"]); }
+        catch (Exception error) { result = new Dictionary<string, object> { { "ok", false }, { "action", "screenshot" }, { "error", "WGC_CAPTURE_FAILED: " + error.Message } }; }
+        Console.WriteLine(json.Serialize(new Dictionary<string, object> { { "id", request["id"] }, { "result", result } })); Console.Out.Flush();
+      } catch (Exception error) { Console.Error.WriteLine("WGC_PROTOCOL_ERROR: " + error.Message); }
+    }
+  }
+}

package/assets/window-management.cs

@@ -0,0 +1,217 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Runtime.InteropServices;
+using System.Text;
+using System.Threading;
+using Microsoft.Win32;
+
+partial class WindowsBridge {
+  [DllImport("user32.dll",EntryPoint="ShowWindowAsync")] static extern bool ManagementShow(IntPtr window,int command);
+  [DllImport("user32.dll",EntryPoint="SetWindowPos",SetLastError=true)] static extern bool ManagementMove(IntPtr window,IntPtr after,int x,int y,int width,int height,uint flags);
+  [DllImport("user32.dll",EntryPoint="PostMessageW",SetLastError=true)] static extern bool ManagementPost(IntPtr window,uint message,IntPtr wParam,IntPtr lParam);
+  [DllImport("user32.dll",EntryPoint="AttachThreadInput")] static extern bool ManagementAttach(uint from,uint to,bool attach);
+  [DllImport("kernel32.dll",EntryPoint="GetCurrentThreadId")] static extern uint ManagementThread();
+  static uint ManagementOwner(IntPtr window) {uint owner;GetWindowThreadProcessId(window,out owner);return owner;}
+  static void ManagementAssert(IntPtr window,uint owner) {CheckWindowReference(window);if(!IsWindow(window)||ManagementOwner(window)!=owner)throw new InvalidOperationException("WINDOW_IDENTITY_CHANGED: refresh window observations before acting");}
+  static bool? ManagementResponsive(IntPtr window) {UIntPtr ignored;bool answered=SendMessageTimeout(window,0,UIntPtr.Zero,IntPtr.Zero,3,100,out ignored)!=IntPtr.Zero;int error=Marshal.GetLastWin32Error();return !answered&&error==5?(bool?)null:answered;}
+  static Dictionary<string,object> ManagementWindow(IntPtr window,uint owner) {
+    Rect bounds;if(!GetWindowRect(window,out bounds))throw new InvalidOperationException("WINDOW_BOUNDS_UNAVAILABLE");
+    StringBuilder title=new StringBuilder(2048);GetWindowText(window,title,title.Capacity);
+    return new Dictionary<string,object>{{"nativeWindowHandle",window.ToInt64()},{"processId",owner},{"name",title.ToString()},{"boundingBox",new Dictionary<string,object>{{"x",bounds.Left},{"y",bounds.Top},{"width",bounds.Right-bounds.Left},{"height",bounds.Bottom-bounds.Top}}}};
+  }
+  // Read only the documented, 8-byte-aligned WTSINFOEX level-1 prefix;
+  // account-name fields are never copied or reported.
+  [StructLayout(LayoutKind.Explicit,Size=20)]struct ManagementSessionHeader {
+    [FieldOffset(0)]public uint Level;[FieldOffset(8)]public uint Session;
+    [FieldOffset(12)]public uint Connection;[FieldOffset(16)]public int Flags;
+  }
+  [DllImport("kernel32.dll",EntryPoint="GetCurrentProcessId")]static extern uint ManagementProcessId();
+  [DllImport("kernel32.dll",EntryPoint="ProcessIdToSessionId")]static extern bool ManagementSessionId(uint process,out uint session);
+  [DllImport("wtsapi32.dll",EntryPoint="WTSQuerySessionInformationW")]static extern bool ManagementQuerySession(IntPtr server,uint session,int kind,out IntPtr buffer,out uint bytes);
+  [DllImport("wtsapi32.dll",EntryPoint="WTSFreeMemory")]static extern void ManagementFreeSession(IntPtr buffer);
+  static void ManagementEnsureUnlockedSession() {
+    uint session;if(!ManagementSessionId(ManagementProcessId(),out session))return;
+    IntPtr buffer=IntPtr.Zero;uint bytes;
+    try {
+      if(!ManagementQuerySession(IntPtr.Zero,session,25,out buffer,out bytes) || buffer==IntPtr.Zero || bytes<20)return;
+      ManagementSessionHeader state=(ManagementSessionHeader)Marshal.PtrToStructure(buffer,typeof(ManagementSessionHeader));
+      if(state.Level==1 && state.Session==session && state.Flags==0)throw new InvalidOperationException("DESKTOP_SESSION_LOCKED: unlock Windows before requesting foreground input");
+    }finally {if(buffer!=IntPtr.Zero)ManagementFreeSession(buffer);}
+    // Unknown/unavailable session state does not invent a lock diagnosis;
+    // the existing identity, foreground and input guards still apply.
+  }
+  [DllImport("user32.dll",EntryPoint="BringWindowToTop")]static extern bool ManagementBringToTop(IntPtr window);
+  sealed class ActivationRefusedException : InvalidOperationException {
+    public readonly Dictionary<string,object> Diagnostic;
+    public ActivationRefusedException(Dictionary<string,object> diagnostic) : base("TARGET_ACTIVATION_REFUSED: Windows did not grant foreground access") {Diagnostic=diagnostic;}
+  }
+  static string ManagementForegroundRelationship(IntPtr foreground,IntPtr window,uint owner) {
+    if(foreground==IntPtr.Zero)return "unavailable";
+    if(foreground==window)return "target";
+    if(GetAncestor(foreground,2)==window)return "target_child";
+    return ManagementOwner(foreground)==owner?"same_process":"other_process";
+  }
+  static bool ManagementActivate(IntPtr window,uint owner) {return ManagementActivate(window,owner,null);}
+  // One active operation per desktop; retain the existing lifetime witness,
+  // not another element cache. A helper restart forgets visible intent safely.
+  static string visibleOperation;
+  static WindowReference visibleTarget;
+  static void ApplyVisibleIntent(Dictionary<string,object> args,IntPtr window) {
+    if(args.ContainsKey("activate") || TextOption(args,"dispatch","")=="background" || TextOption(args,"method","")=="background")return;
+    if(visibleTarget!=null && visibleOperation==pointerOperation && visibleTarget.Window==window && visibleTarget.Owner==WindowOwner(window) && WindowMarker.Matches(window,visibleTarget.Owner,visibleTarget.Marker))args["activate"]=true;
+  }
+  static bool ManagementActivate(IntPtr window,uint owner,Dictionary<string,object> diagnostics) {
+    ManagementAssert(window,owner);ManagementEnsureUnlockedSession();
+    if(IsIconic(window)){BeginWindowDispatch();ManagementShow(window,9);}
+    if(GetForegroundWindow()==window)return true;
+    BeginWindowDispatch();bool initial=SetForegroundWindow(window);
+    if(diagnostics!=null)diagnostics["initialRequestAccepted"]=initial;
+    if(GetForegroundWindow()==window)return true;
+    IntPtr front=GetForegroundWindow();uint ignored;uint frontThread=GetWindowThreadProcessId(front,out ignored),own=ManagementThread();bool attached=false;
+    if(diagnostics!=null)diagnostics["foregroundBeforeFallback"]=ManagementForegroundRelationship(front,window,owner);
+    try {
+      bool attempted=frontThread!=0&&frontThread!=own;
+      if(attempted)attached=ManagementAttach(own,frontThread,true);
+      if(diagnostics!=null){diagnostics["inputThreadAttachAttempted"]=attempted;if(attempted)diagnostics["inputThreadAttached"]=attached;}
+      ManagementAssert(window,owner);BeginWindowDispatch();bool raised=ManagementBringToTop(window);ManagementAssert(window,owner);BeginWindowDispatch();bool requested=SetForegroundWindow(window);
+      if(diagnostics!=null){diagnostics["raiseAccepted"]=raised;diagnostics["fallbackRequestAccepted"]=requested;}
+    }
+    finally {if(attached)ManagementAttach(own,frontThread,false);}
+    for(int index=0;index<8&&GetForegroundWindow()!=window;index++)Thread.Sleep(10);
+    IntPtr finalForeground=GetForegroundWindow();
+    if(diagnostics!=null)diagnostics["foregroundAfterFallback"]=ManagementForegroundRelationship(finalForeground,window,owner);
+    return finalForeground==window;
+  }
+  static object ManageNativeWindow(string action,Dictionary<string,object> args) {
+    if(action=="launch_app")return LaunchFromDesktop(args);
+    // Shared Win32 capture resolver performs HWND/PID/title matching without resolving UIA.
+    IntPtr window=ResolveCaptureWindow(args);uint owner=ManagementOwner(window);ManagementAssert(window,owner);
+    Dictionary<string,object> result=Result(true,action);result["nativeWindowHandle"]=window.ToInt64();result["processId"]=owner;result["window"]=ManagementWindow(window,owner);
+    bool? responsive=ManagementResponsive(window);result["targetResponsive"]=responsive;
+    ManagementAssert(window,owner);
+    if(action=="close_window") {
+      BeginWindowDispatch();bool posted=ManagementPost(window,0x0010,IntPtr.Zero,IntPtr.Zero);result["posted"]=posted;result["verification"]=posted?"sent":"unconfirmed";result["note"]=posted?"WM_CLOSE was dispatched; the application may veto closure or show a save dialog. Observe windows to verify.":"Windows refused posting WM_CLOSE; no closure was confirmed.";if(!posted)result["nativeError"]=Marshal.GetLastWin32Error();return result;
+    }
+    if(action=="move_window") {
+      int x=Convert.ToInt32(args["x"]),y=Convert.ToInt32(args["y"]);
+      BeginWindowDispatch();bool moved=ManagementMove(window,IntPtr.Zero,x,y,0,0,0x0001|0x0004|0x0010|0x4000);
+      result["moved"]=moved;result["x"]=x;result["y"]=y;result["verification"]=moved?"sent":"unconfirmed";
+      if(!moved)result["warning"]="SetWindowPos refused the move; the window may be unavailable or maximized.";
+      if(!args.ContainsKey("activate")||!Convert.ToBoolean(args["activate"]))return result;
+    }
+    bool activated=responsive==true&&ManagementActivate(window,owner);result["activated"]=activated;
+    if(activated){visibleOperation=pointerOperation;visibleTarget=ObserveWindowReference(window,result);if(visibleTarget!=null){currentReference=visibleTarget;result["windowRef"]=visibleTarget.Id;}}
+    if(!activated){result["verification"]="unconfirmed";result["warning"]=responsive==true?"Windows foreground rules refused activation; no keyboard or mouse workaround was sent.":"The target is unresponsive or inaccessible; activation was not attempted.";}
+    else if(action=="activate_window")result["verification"]="sent";
+    return result;
+  }
+
+  static readonly HashSet<string> ManagementCommandHosts=new HashSet<string>(StringComparer.OrdinalIgnoreCase){"cmd","powershell","pwsh","wt","wsl","bash","conhost","wscript","cscript","mshta","rundll32","regsvr32","msiexec","forfiles","schtasks"};
+  [DllImport("shlwapi.dll",CharSet=CharSet.Unicode,EntryPoint="AssocQueryStringW")]static extern int ManagementAssociation(uint flags,int kind,string association,string verb,StringBuilder output,ref uint length);
+  static string AssociationString(string association,bool protocol,int kind) {
+    // ASSOCF_INIT_IGNOREUNKNOWN refuses the generic Open-With fallback;
+    // ASSOCF_IS_PROTOCOL honors current-user HTTP(S) associations.
+    uint length=0;uint flags=0x400u|(protocol?0x1000u:0u);
+    ManagementAssociation(flags,kind,association,"open",null,ref length);
+    if(length==0 || length>32768)return "";
+    StringBuilder output=new StringBuilder((int)length);
+    return ManagementAssociation(flags,kind,association,"open",output,ref length)==0?output.ToString():"";
+  }
+  static Dictionary<string,object> DefaultLaunchHandler(string association,bool protocol) {
+    string executable=AssociationString(association,protocol,2),name=AssociationString(association,protocol,4),progId=AssociationString(association,protocol,20);
+    if(executable.Length==0 && name.Length==0 && progId.Length==0)throw new InvalidOperationException("DEFAULT_APP_UNAVAILABLE: Windows did not resolve an open handler for "+association);
+    return new Dictionary<string,object>{{"association",association},{"executable",executable},{"name",name},{"progId",progId},{"source","windows-association"}};
+  }
+  static void ReleaseLaunchCom(object value) {try{if(value!=null&&Marshal.IsComObject(value))Marshal.ReleaseComObject(value);}catch(InvalidComObjectException){}}
+  static bool FullyQualifiedLaunchPath(string value) {return value.Length>=3&&Char.IsLetter(value[0])&&value[1]==':'&&(value[2]=='\\'||value[2]=='/')||value.StartsWith("\\\\",StringComparison.Ordinal)&&value.TrimStart('\\').Split('\\').Length>=2;}
+  static string ResolveLaunchFile(string target) {
+    if(Path.IsPathRooted(target)) {
+      if(!FullyQualifiedLaunchPath(target))throw new InvalidOperationException("LAUNCH_INVALID_TARGET: use a fully qualified absolute path");
+      if(!File.Exists(target))throw new InvalidOperationException("LAUNCH_NOT_FOUND: target file does not exist");
+      return Path.GetFullPath(target);
+    }
+    if(target.IndexOfAny(new char[]{'\\','/',':'})>=0)return null;
+    string[] extensions=Path.GetExtension(target).Length>0?new string[]{""}:new string[]{".exe",".com",".lnk"};
+    foreach(string directory in (Environment.GetEnvironmentVariable("PATH")??"").Split(';'))foreach(string extension in extensions) {
+      string candidate;try{candidate=Path.Combine(directory.Trim('"'),target+extension);}catch(ArgumentException){continue;}
+      if(File.Exists(candidate))return Path.GetFullPath(candidate);
+    }
+    string name=target.EndsWith(".exe",StringComparison.OrdinalIgnoreCase)?target:target+".exe";
+    foreach(RegistryHive hive in new RegistryHive[]{RegistryHive.CurrentUser,RegistryHive.LocalMachine})foreach(RegistryView view in new RegistryView[]{RegistryView.Registry64,RegistryView.Registry32}) {
+      try{using(RegistryKey root=RegistryKey.OpenBaseKey(hive,view))using(RegistryKey key=root.OpenSubKey("SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\"+name)){
+        string candidate=key==null?null:Convert.ToString(key.GetValue(""));if(String.IsNullOrEmpty(candidate))continue;candidate=Environment.ExpandEnvironmentVariables(candidate.Trim('"'));if(File.Exists(candidate))return Path.GetFullPath(candidate);
+      }}catch(System.Security.SecurityException){}
+    }
+    return null;
+  }
+  static string ResolveInstalledLaunch(string target) {
+    object application=null,folder=null,items=null;List<string> matches=new List<string>();
+    try{
+      application=Activator.CreateInstance(Type.GetTypeFromProgID("Shell.Application"));folder=((dynamic)application).NameSpace("shell:AppsFolder");if(folder==null)throw new InvalidOperationException("Installed app enumeration is unavailable");items=((dynamic)folder).Items();int count=((dynamic)items).Count;
+      for(int index=0;index<count;index++) {
+        object item=null;try{item=((dynamic)items).Item(index);string name=Convert.ToString(((dynamic)item).Name),id=Convert.ToString(((dynamic)item).ExtendedProperty("System.AppUserModel.ID"));
+          if(String.Equals(target,name,StringComparison.OrdinalIgnoreCase)||String.Equals(target,id,StringComparison.OrdinalIgnoreCase)){if(String.IsNullOrEmpty(id))id=Convert.ToString(((dynamic)item).Path);if(!String.IsNullOrEmpty(id))matches.Add(id);}
+        }finally{ReleaseLaunchCom(item);}
+      }
+    }finally{ReleaseLaunchCom(items);ReleaseLaunchCom(folder);ReleaseLaunchCom(application);}
+    if(matches.Count==0)throw new InvalidOperationException("LAUNCH_NOT_FOUND: use an executable path or exact installed app name/AppUserModelID");
+    if(matches.Count!=1)throw new InvalidOperationException("LAUNCH_AMBIGUOUS: use a full executable path or AppUserModelID");
+    return "shell:AppsFolder\\"+matches[0];
+  }
+  static void CheckLaunchProgram(string file,string arguments) {
+    string program=file,embedded="";HashSet<string> seen=new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+    while(String.Equals(Path.GetExtension(program),".lnk",StringComparison.OrdinalIgnoreCase)){
+      if(!seen.Add(program)||seen.Count>8)throw new InvalidOperationException("LAUNCH_INVALID_TARGET: shortcut chain is cyclic or too deep");
+      object shell=null,link=null;try{shell=Activator.CreateInstance(Type.GetTypeFromProgID("WScript.Shell"));link=((dynamic)shell).CreateShortcut(program);embedded+=" "+Convert.ToString(((dynamic)link).Arguments);program=Environment.ExpandEnvironmentVariables(Convert.ToString(((dynamic)link).TargetPath));if(String.IsNullOrWhiteSpace(program))throw new InvalidOperationException("LAUNCH_INVALID_TARGET: shortcut has no executable target");}finally{ReleaseLaunchCom(link);ReleaseLaunchCom(shell);}
+    }
+    if((arguments.Trim().Length>0||embedded.Trim().Length>0)&&ManagementCommandHosts.Contains(Path.GetFileNameWithoutExtension(program)))throw new InvalidOperationException("LAUNCH_COMMAND_REFUSED: command/script hosts accept no arguments through launch_app; use Pi's shell tool");
+  }
+  static object LaunchFromDesktop(Dictionary<string,object> args) {
+    Dictionary<string,object> result=null;Exception failure=null;
+    Thread thread=new Thread(delegate(){
+      try{
+        string target=Convert.ToString(args["target"]).Trim(),arguments=Convert.ToString(args["arguments"]),directory=Convert.ToString(args["workingDirectory"]);
+        Uri uri;bool protocol=Uri.TryCreate(target,UriKind.Absolute,out uri)&&(uri.Scheme=="http"||uri.Scheme=="https");
+        if(!protocol)target=Environment.ExpandEnvironmentVariables(target);
+        if(protocol && String.IsNullOrEmpty(uri.Host))throw new InvalidOperationException("LAUNCH_INVALID_TARGET: HTTP(S) URL requires a host");
+        bool browser=String.Equals(target,"browser",StringComparison.OrdinalIgnoreCase);
+        string file=protocol||browser?null:ResolveLaunchFile(target),kind=browser?"default-browser":protocol?"url":file==null?"installed-app":"file";
+        Dictionary<string,object> handler=null;
+        if(file!=null){string extension=Path.GetExtension(file);if(String.Equals(extension,".exe",StringComparison.OrdinalIgnoreCase)||String.Equals(extension,".com",StringComparison.OrdinalIgnoreCase)||String.Equals(extension,".lnk",StringComparison.OrdinalIgnoreCase))CheckLaunchProgram(file,arguments);else {
+          if(new HashSet<string>(StringComparer.OrdinalIgnoreCase){".bat",".cmd",".ps1",".vbs",".vbe",".js",".jse",".wsf",".wsh",".hta",".reg",".msi",".msp",".scr",".cpl"}.Contains(extension))throw new InvalidOperationException("LAUNCH_COMMAND_REFUSED: use Pi's shell tool for scripts/installers");
+          kind="document";handler=DefaultLaunchHandler(Path.GetExtension(file),false);
+        }target=file;}
+        else if(browser)handler=DefaultLaunchHandler("https",true);
+        else if(protocol)handler=DefaultLaunchHandler(uri.Scheme,true);
+        else target=ResolveInstalledLaunch(target);
+        if(handler!=null) {
+          if(arguments.Length>0||directory.Length>0)throw new InvalidOperationException("LAUNCH_INVALID_ARGUMENTS: default-handler URLs/documents do not accept arguments or workingDirectory");
+          string handlerExecutable=Convert.ToString(handler["executable"]);
+          if(ManagementCommandHosts.Contains(Path.GetFileNameWithoutExtension(handlerExecutable)))throw new InvalidOperationException("LAUNCH_COMMAND_REFUSED: default handler is a command/script host; use Pi's shell tool");
+        }
+        if(directory.Length>0){directory=Environment.ExpandEnvironmentVariables(directory);if(!FullyQualifiedLaunchPath(directory)||!Directory.Exists(directory))throw new InvalidOperationException("LAUNCH_INVALID_DIRECTORY: use an existing fully qualified directory");directory=Path.GetFullPath(directory);}
+        if(kind=="installed-app"&&(arguments.Length>0||directory.Length>0))throw new InvalidOperationException("LAUNCH_INVALID_ARGUMENTS: installed AppUserModelID launches do not accept arguments or workingDirectory");
+        if(Option(args,"resolveOnly",false)) {
+          result=Result(true,"launch_app");result["target"]=target;result["targetKind"]=kind;result["handler"]=handler;result["verification"]="resolved";result["launched"]=false;
+          result["note"]="Resolution only; no app was opened. Select and observe the intended existing window before creating a task tab/document. Handler metadata is not a window identity.";return;
+        }
+        if(browser){target=Convert.ToString(handler["executable"]);if(target.Length==0)throw new InvalidOperationException("DEFAULT_APP_UNAVAILABLE: Windows resolved the browser but did not provide a blank-window launch executable; reuse its observed window or open a requested HTTP(S) URL");}
+        object windows=null,desktop=null,document=null,application=null;
+        try{
+          windows=Activator.CreateInstance(Type.GetTypeFromCLSID(new Guid("9BA05972-F6A8-11CF-A442-00A0C90A8F39")));
+          object location=0,root=null;int handle=0;desktop=((dynamic)windows).FindWindowSW(ref location,ref root,8,out handle,1);
+          if(desktop==null)throw new InvalidOperationException("interactive Explorer desktop is unavailable");
+          document=((dynamic)desktop).Document;application=((dynamic)document).Application;
+          ((dynamic)application).ShellExecute(target,arguments,directory,"open",Convert.ToBoolean(args["activate"])?1:4);
+        }catch(Exception error){throw new InvalidOperationException("LAUNCH_SHELL_FAILED: "+error.Message+"; no child-process fallback or replay was attempted",error);}
+        finally{ReleaseLaunchCom(application);ReleaseLaunchCom(document);ReleaseLaunchCom(desktop);ReleaseLaunchCom(windows);}
+        result=Result(true,"launch_app");result["target"]=target;result["targetKind"]=kind;if(handler!=null)result["handler"]=handler;result["launchMethod"]="explorer-shell";result["verification"]="dispatched";result["note"]="Explorer accepted the launch. New windows are observations, not confirmed matches. The app can reuse a window or activate itself; use list_windows/wait_for to verify. No elevation was requested.";
+      }catch(Exception error){failure=error;}
+    });
+    thread.IsBackground=true;thread.SetApartmentState(ApartmentState.STA);thread.Start();
+    if(!thread.Join(15000))throw new InvalidOperationException("LAUNCH_PENDING_TIMEOUT: Explorer outcome is unknown; do not replay the launch");
+    if(failure!=null)throw failure;
+    return result;
+  }
+}

package/assets/window-marker.cs

@@ -0,0 +1,23 @@
+using System;
+using System.Runtime.InteropServices;
+
+// Stateless witness checks shared by the authoritative bridge and delegated WGC.
+static class WindowMarker {
+  [DllImport("user32.dll",CharSet=CharSet.Unicode,SetLastError=true)] static extern bool SetProp(IntPtr window,string name,IntPtr value);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern IntPtr GetProp(IntPtr window,string name);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern IntPtr RemoveProp(IntPtr window,string name);
+  [DllImport("user32.dll")] static extern bool IsWindow(IntPtr window);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr window,out uint owner);
+  internal static bool Matches(IntPtr window,uint owner,string name) {
+    uint actual;GetWindowThreadProcessId(window,out actual);
+    return owner!=0 && actual==owner && IsWindow(window) && GetProp(window,name)==new IntPtr(1);
+  }
+  internal static bool Bind(IntPtr window,uint owner,string name,out int error) {
+    uint actual;GetWindowThreadProcessId(window,out actual);error=0;
+    if(actual!=owner || owner==0 || !IsWindow(window))return false;
+    if(!SetProp(window,name,new IntPtr(1))){error=Marshal.GetLastWin32Error();return false;}
+    if(Matches(window,owner,name))return true;
+    Remove(window,owner,name);return false;
+  }
+  internal static void Remove(IntPtr window,uint owner,string name) {if(Matches(window,owner,name))RemoveProp(window,name);}
+}

package/assets/window-references.cs

@@ -0,0 +1,80 @@
+using System;
+using System.Collections.Generic;
+
+partial class WindowsBridge {
+  sealed class WindowReference {
+    internal string Id,Marker;internal IntPtr Window;internal uint Owner;internal DateTime Seen;
+  }
+  static readonly string referenceEpoch=Convert.ToBase64String(Guid.NewGuid().ToByteArray()).TrimEnd('=').Replace('+','-').Replace('/','_');
+  static long referenceSequence,elementSequence;
+  static readonly Dictionary<string,WindowReference> windowReferences=new Dictionary<string,WindowReference>();
+  static WindowReference currentReference;
+  static bool windowDispatchAttempted;
+  static void BeginWindowDispatch(){CheckReferenceBeforeDispatch();windowDispatchAttempted=true;}
+  static void FinishWindowReference(Dictionary<string,object> payload){
+    if(currentReference==null)return;
+    bool cleanupFailed=payload.ContainsKey("cleanupConfirmed") && !Convert.ToBoolean(payload["cleanupConfirmed"]);
+    if(!cleanupFailed && Convert.ToString(payload["action"])=="close_window" && windowDispatchAttempted && payload.ContainsKey("posted") && Convert.ToBoolean(payload["posted"]) && !IsWindow(currentReference.Window)){
+      // WM_CLOSE was posted; observing its intended disappearance is not a failed action.
+      payload["targetState"]="absent";payload["windowRef"]=currentReference.Id;return;
+    }
+    if(!CurrentReferenceIntact()){
+      payload["ok"]=false;payload.Remove("inputRequired");payload["dispatchAttempted"]=windowDispatchAttempted;
+      string warning=windowDispatchAttempted?"WINDOW_REFERENCE_LOST_AFTER_DISPATCH: app effects may have occurred; observe before further action; never replay":"WINDOW_REFERENCE_LOST: lifetime proof is unavailable; observe again";
+      if(payload.ContainsKey("cleanupConfirmed") && !Convert.ToBoolean(payload["cleanupConfirmed"]))payload["identityWarning"]=warning;else payload["error"]=warning;
+      if(windowDispatchAttempted){payload["effectsUncertain"]=true;if(!payload.ContainsKey("verification"))payload["verification"]="unconfirmed";}
+    }
+    payload["windowRef"]=currentReference.Id;
+  }
+  static bool CurrentReferenceIntact() {return currentReference==null || WindowMarker.Matches(currentReference.Window,currentReference.Owner,currentReference.Marker);}
+  static void CheckReferenceBeforeDispatch() {if(currentReference!=null)CheckWindowReference(currentReference.Window);}
+  static void CheckWindowReference(IntPtr window) {
+    if(currentReference!=null && currentReference.Window==window && !WindowMarker.Matches(window,currentReference.Owner,currentReference.Marker))throw new InvalidOperationException("WINDOW_REFERENCE_LOST: lifetime proof is unavailable; observe again; never replay uncertain effects");
+  }
+  static WindowReference ResolveWindowReference(Dictionary<string,object> args) {
+    if(!args.ContainsKey("windowRef"))return null;
+    string id=Convert.ToString(args["windowRef"]);WindowReference entry;
+    if(!windowReferences.TryGetValue(id,out entry))throw new InvalidOperationException("STALE_WINDOW_REFERENCE: unknown or expired reference; observe again");
+    if(entry.Seen<DateTime.UtcNow.AddMinutes(-5)){WindowMarker.Remove(entry.Window,entry.Owner,entry.Marker);windowReferences.Remove(id);throw new InvalidOperationException("STALE_WINDOW_REFERENCE: reference expired; observe again");}
+    if(!WindowMarker.Matches(entry.Window,entry.Owner,entry.Marker))throw new InvalidOperationException("WINDOW_REFERENCE_LOST: lifetime proof is unavailable; observe again");
+    if((args.ContainsKey("nativeWindowHandle") && Convert.ToInt64(args["nativeWindowHandle"])!=entry.Window.ToInt64()) || (args.ContainsKey("processId") && Convert.ToUInt32(args["processId"])!=entry.Owner) || (args.ContainsKey("windowTitle") && WindowTitle(entry.Window).IndexOf(Convert.ToString(args["windowTitle"]),StringComparison.OrdinalIgnoreCase)<0))throw new InvalidOperationException("WINDOW_REFERENCE_CONFLICT: selectors disagree with the observed lifetime");
+    if(TextOption(args,"scope","")=="desktop" || args.ContainsKey("browserTab"))throw new InvalidOperationException("WINDOW_REFERENCE_CONFLICT: window reference cannot target desktop or browser channel");
+    entry.Seen=DateTime.UtcNow;currentReference=entry;return entry;
+  }
+  static object ObserveReferencePresence(Dictionary<string,object> args) {
+    WindowReference entry;string id=Convert.ToString(args["windowRef"]);
+    if(windowReferences.TryGetValue(id,out entry) && ((args.ContainsKey("nativeWindowHandle") && Convert.ToInt64(args["nativeWindowHandle"])!=entry.Window.ToInt64()) || (args.ContainsKey("processId") && Convert.ToUInt32(args["processId"])!=entry.Owner)))throw new InvalidOperationException("WINDOW_REFERENCE_CONFLICT: selectors disagree with the observed lifetime");
+    if(windowReferences.TryGetValue(id,out entry) && entry.Seen>=DateTime.UtcNow.AddMinutes(-5) && !IsWindow(entry.Window)){
+      if(args.ContainsKey("windowTitle"))throw new InvalidOperationException("WINDOW_REFERENCE_CONSTRAINT_UNAVAILABLE: destroyed window title cannot be verified");
+      return new Dictionary<string,object>{{"ok",true},{"action","list_windows"},{"referencePresent",false},{"windows",new List<object>()}};
+    }
+    entry=ResolveWindowReference(args);
+    return new Dictionary<string,object>{{"ok",true},{"action","list_windows"},{"referencePresent",true},{"windows",new List<object>()}};
+  }
+  static void PruneWindowReferences() {
+    var remove=new List<string>();
+    foreach(var pair in windowReferences)if(pair.Value.Seen<DateTime.UtcNow.AddMinutes(-5) || !WindowMarker.Matches(pair.Value.Window,pair.Value.Owner,pair.Value.Marker))remove.Add(pair.Key);
+    foreach(string id in remove){WindowReference entry=windowReferences[id];WindowMarker.Remove(entry.Window,entry.Owner,entry.Marker);windowReferences.Remove(id);}
+  }
+  static WindowReference ObserveWindowReference(IntPtr window,Dictionary<string,object> metadata) {
+    if(window==IntPtr.Zero){metadata["windowRefUnavailable"]="WINDOW_REFERENCE_UNAVAILABLE: no native root could be established";return null;}
+    CheckWindowReference(window);uint owner=WindowOwner(window);
+    foreach(var pair in windowReferences)if(pair.Value.Window==window && pair.Value.Owner==owner && pair.Value.Seen>=DateTime.UtcNow.AddMinutes(-5) && WindowMarker.Matches(window,owner,pair.Value.Marker)){pair.Value.Seen=DateTime.UtcNow;return pair.Value;}
+    PruneWindowReferences();
+    if(windowReferences.Count>=4096){metadata["windowRefUnavailable"]="REFERENCE_CAPACITY: observe again after expiry";return null;}
+    string serial=(++referenceSequence).ToString("x"),marker="PiComputerUse.Window."+referenceEpoch+"."+serial;int error;
+    if(!WindowMarker.Bind(window,owner,marker,out error)){metadata["windowRefUnavailable"]="WINDOW_REFERENCE_UNAVAILABLE: marker acquisition failed (native error "+error+")";return null;}
+    var entry=new WindowReference {Id="w:"+referenceEpoch+":"+serial,Marker=marker,Window=window,Owner=owner,Seen=DateTime.UtcNow};windowReferences.Add(entry.Id,entry);return entry;
+  }
+  static void AddWindowReference(Dictionary<string,object> metadata,IntPtr window) {
+    WindowReference entry=ObserveWindowReference(window,metadata);if(entry!=null)metadata["windowRef"]=entry.Id;
+  }
+  static Dictionary<string,object> WindowReferenceDescriptor(IntPtr window) {
+    WindowReference entry=currentReference!=null && currentReference.Window==window?currentReference:ObserveWindowReference(window,new Dictionary<string,object>());
+    return entry==null?null:new Dictionary<string,object>{{"name",entry.Marker},{"windowRef",entry.Id}};
+  }
+  static void CleanupWindowReferences() {
+    foreach(var pair in windowReferences)WindowMarker.Remove(pair.Value.Window,pair.Value.Owner,pair.Value.Marker);
+    windowReferences.Clear();observed.Clear();elementKeys.Clear();
+  }
+}