deadbyte-mcp 0.11.2 → 0.12.0

package/src/desktop-observer-r40.mjs

@@ -0,0 +1,231 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical-json.mjs';
+import { createDesktopFrame } from './desktop-contract.mjs';
+
+const NATIVE_SCHEMA='deadbyte.desktop-native-frame.v1';
+const BACKENDS=new Set(['gdi-bitblt-fallback','desktop-duplication','windows-graphics-capture']);
+const PIXEL_FORMAT='BGRA8';
+const HEX64=/^[0-9a-f]{64}$/;
+const HWND=/^0x[0-9a-f]{1,16}$/;
+const HEADER_MAX_BYTES=64*1024;
+
+const sha256Bytes=value=>createHash('sha256').update(value).digest('hex');
+const sha256Object=value=>sha256Bytes(Buffer.from(canonicalJson(value),'utf8'));
+
+function insist(condition,message){ if(!condition) throw new Error(message); }
+function safeInt(value,label,{min=Number.MIN_SAFE_INTEGER,max=Number.MAX_SAFE_INTEGER}={}){
+  insist(Number.isSafeInteger(value)&&value>=min&&value<=max,`${label} invalid`);
+  return value;
+}
+function boundedString(value,label,max=32768){
+  insist(typeof value==='string'&&Buffer.byteLength(value,'utf8')<=max,`${label} invalid`);
+  return value;
+}
+function normalizeMonitor(item,index){
+  insist(item&&typeof item==='object'&&!Array.isArray(item),`monitor[${index}] invalid`);
+  return Object.freeze({
+    left:safeInt(item.left,`monitor[${index}].left`,{min:-131072,max:131072}),
+    top:safeInt(item.top,`monitor[${index}].top`,{min:-131072,max:131072}),
+    width:safeInt(item.width,`monitor[${index}].width`,{min:1,max:131072}),
+    height:safeInt(item.height,`monitor[${index}].height`,{min:1,max:131072}),
+    primary:item.primary===true,
+    device:boundedString(item.device,`monitor[${index}].device`,512)
+  });
+}
+function monitorWithin(bounds,monitor){
+  return monitor.left>=bounds.left&&monitor.top>=bounds.top&&
+    monitor.left+monitor.width<=bounds.left+bounds.width&&
+    monitor.top+monitor.height<=bounds.top+bounds.height;
+}
+
+export function parseNativeDesktopFrame(buffer,{maxFrameBytes=128*1024*1024}={}){
+  insist(Buffer.isBuffer(buffer),'native desktop frame must be Buffer');
+  safeInt(maxFrameBytes,'maxFrameBytes',{min:1024,max:256*1024*1024});
+  const newline=buffer.indexOf(0x0a);
+  insist(newline>0&&newline<=HEADER_MAX_BYTES,'native desktop frame header missing or oversized');
+  let header;
+  try { header=JSON.parse(buffer.subarray(0,newline).toString('utf8')); }
+  catch { throw new Error('native desktop frame header JSON invalid'); }
+  insist(header?.schema===NATIVE_SCHEMA,'native desktop frame schema mismatch');
+  insist(BACKENDS.has(header.backend),'native desktop frame backend invalid');
+  insist(header.pixel_format===PIXEL_FORMAT,'native desktop frame pixel format mismatch');
+  const left=safeInt(header.left,'native left',{min:-131072,max:131072});
+  const top=safeInt(header.top,'native top',{min:-131072,max:131072});
+  const width=safeInt(header.width,'native width',{min:1,max:32768});
+  const height=safeInt(header.height,'native height',{min:1,max:32768});
+  const stride=safeInt(header.stride,'native stride',{min:4,max:131072});
+  const byteLength=safeInt(header.byte_length,'native byte_length',{min:4,max:maxFrameBytes});
+  insist(stride===width*4,'native desktop stride mismatch');
+  insist(byteLength===stride*height,'native desktop byte_length mismatch');
+  insist(buffer.length===newline+1+byteLength,'native desktop frame payload length mismatch');
+  const systemDpi=safeInt(header.system_dpi,'system_dpi',{min:48,max:960});
+  const sessionId=safeInt(header.session_id,'session_id',{min:0,max:0xffffffff});
+  const inputDesktop=boundedString(header.input_desktop,'input_desktop',512);
+  const hwnd=String(header.foreground_hwnd??'').toLowerCase();
+  insist(HWND.test(hwnd),'foreground_hwnd invalid');
+  const foregroundPid=safeInt(header.foreground_pid,'foreground_pid',{min:0,max:0x7fffffff});
+  const foregroundTitle=boundedString(header.foreground_title??'','foreground_title',64*1024);
+  const foregroundImage=boundedString(header.foreground_image??'','foreground_image',64*1024);
+  insist(Array.isArray(header.monitors)&&header.monitors.length>=1&&header.monitors.length<=32,'native monitor list invalid');
+  const monitors=header.monitors.map(normalizeMonitor);
+  insist(monitors.filter(item=>item.primary).length===1,'native monitor list must have exactly one primary monitor');
+  const bounds=Object.freeze({left,top,width,height});
+  insist(monitors.every(item=>monitorWithin(bounds,item)),'native monitor lies outside virtual desktop bounds');
+  const pixels=buffer.subarray(newline+1);
+  const imageSha256=sha256Bytes(pixels);
+  const topology={
+    schema:'deadbyte.desktop-topology.v1',bounds,system_dpi:systemDpi,
+    monitors:[...monitors].sort((a,b)=>a.left-b.left||a.top-b.top||a.device.localeCompare(b.device))
+  };
+  const topologySha256=sha256Object(topology);
+  const activeWindow=foregroundPid>0&&hwnd!=='0x0'?Object.freeze({
+    hwnd,pid:foregroundPid,
+    ...(foregroundImage?{process_image_sha256:sha256Bytes(Buffer.from(foregroundImage,'utf8'))}:{}),
+    ...(foregroundTitle?{title_sha256:sha256Bytes(Buffer.from(foregroundTitle,'utf8'))}:{})
+  }):null;
+  return Object.freeze({
+    schema:NATIVE_SCHEMA,backend:header.backend,pixel_format:PIXEL_FORMAT,bounds,stride,byte_length:byteLength,
+    system_dpi:systemDpi,session_id:sessionId,input_desktop:inputDesktop,monitors,topology_sha256:topologySha256,
+    active_window:activeWindow,image_sha256:imageSha256,pixels
+  });
+}
+
+export async function captureNativeDesktop({
+  observerPath,expectedObserverSha256,maxFrameBytes=128*1024*1024,timeoutMs=10000
+}={}){
+  insist(typeof observerPath==='string'&&path.isAbsolute(observerPath),'observerPath must be absolute');
+  insist(HEX64.test(expectedObserverSha256??''),'expectedObserverSha256 invalid');
+  safeInt(maxFrameBytes,'maxFrameBytes',{min:1024,max:256*1024*1024});
+  safeInt(timeoutMs,'timeoutMs',{min:100,max:60000});
+  const exeBytes=await readFile(observerPath);
+  insist(exeBytes.length>0&&exeBytes.length<=4*1024*1024,'desktop observer binary size invalid');
+  insist(sha256Bytes(exeBytes)===expectedObserverSha256,'desktop observer executable hash mismatch');
+  return await new Promise((resolve,reject)=>{
+    const child=spawn(observerPath,[],{shell:false,windowsHide:true,stdio:['ignore','pipe','pipe']});
+    const chunks=[]; let stdoutBytes=0,stderr='',done=false;
+    const finish=(error,value)=>{
+      if(done)return;done=true;clearTimeout(timer);
+      error?reject(error):resolve(value);
+    };
+    child.stdout.on('data',chunk=>{
+      stdoutBytes+=chunk.length;
+      if(stdoutBytes>maxFrameBytes+HEADER_MAX_BYTES+1){
+        try{child.kill('SIGKILL');}catch{}
+        return finish(new Error('desktop observer stdout exceeds bound'));
+      }
+      chunks.push(Buffer.from(chunk));
+    });
+    child.stderr.on('data',chunk=>{
+      stderr+=chunk.toString('utf8');
+      if(Buffer.byteLength(stderr,'utf8')>64*1024){
+        try{child.kill('SIGKILL');}catch{}
+        finish(new Error('desktop observer stderr exceeds bound'));
+      }
+    });
+    child.once('error',error=>finish(error));
+    child.once('exit',(code,signal)=>{
+      if(code!==0) return finish(new Error(`desktop observer exit=${code} signal=${signal??'none'} stderr=${stderr.slice(-8192)}`));
+      try { finish(null,parseNativeDesktopFrame(Buffer.concat(chunks),{maxFrameBytes})); }
+      catch(error){ finish(error); }
+    });
+    const timer=setTimeout(()=>{
+      try{child.kill('SIGKILL');}catch{}
+      finish(new Error(`desktop observer timed out after ${timeoutMs}ms`));
+    },timeoutMs);
+  });
+}
+
+export function createDesktopPreview({pixels,width,height,stride,maxBytes=1024*1024}={}){
+  insist(Buffer.isBuffer(pixels),'desktop preview pixels invalid');
+  safeInt(width,'preview width',{min:1,max:32768}); safeInt(height,'preview height',{min:1,max:32768});
+  safeInt(stride,'preview stride',{min:4,max:131072}); insist(stride===width*4,'preview stride mismatch');
+  safeInt(maxBytes,'preview maxBytes',{min:64,max:4*1024*1024});
+  insist(pixels.length>=stride*height,'desktop preview pixel payload truncated');
+  let step=Math.max(1,Math.ceil(Math.sqrt((width*height*3)/Math.max(1,maxBytes-64))));
+  let outWidth,outHeight,header,total;
+  for(;;){
+    outWidth=Math.ceil(width/step);outHeight=Math.ceil(height/step);
+    header=Buffer.from('P6\n'+outWidth+' '+outHeight+'\n255\n','ascii');
+    total=header.length+outWidth*outHeight*3;
+    if(total<=maxBytes)break;
+    step++;
+    insist(step<=Math.max(width,height),'desktop preview cannot satisfy byte bound');
+  }
+  const data=Buffer.alloc(total);header.copy(data,0);let o=header.length;
+  for(let y=0;y<height;y+=step){
+    const row=y*stride;
+    for(let x=0;x<width;x+=step){
+      const i=row+x*4;
+      data[o++]=pixels[i+2];data[o++]=pixels[i+1];data[o++]=pixels[i];
+    }
+  }
+  insist(o===data.length,'desktop preview size mismatch');
+  return Object.freeze({
+    schema:'deadbyte.desktop-preview.v1',encoding:'ppm-base64',pixel_format:'RGB8',
+    width:outWidth,height:outHeight,source_width:width,source_height:height,sample_step:step,
+    byte_length:data.length,sha256:sha256Bytes(data),data_base64:data.toString('base64')
+  });
+}
+
+export function createDesktopObserverRuntime({
+  captureProvider=null,observerPath=null,expectedObserverSha256=null,maxFrameBytes=128*1024*1024,
+  timeoutMs=10000,maxCachedFrames=2,allowInputDesktops=['Default'],now=()=>new Date().toISOString(),
+  runtimeNonce=randomBytes(32).toString('hex')
+}={}){
+  insist(Array.isArray(allowInputDesktops)&&allowInputDesktops.length>=1&&allowInputDesktops.length<=8,'allowInputDesktops invalid');
+  const allowed=new Set(allowInputDesktops.map(item=>boundedString(item,'allowed input desktop',512)));
+  safeInt(maxCachedFrames,'maxCachedFrames',{min:1,max:8});
+  insist(HEX64.test(sha256Bytes(Buffer.from(runtimeNonce,'utf8'))),'runtimeNonce invalid');
+  const provider=captureProvider??(()=>captureNativeDesktop({observerPath,expectedObserverSha256,maxFrameBytes,timeoutMs}));
+  const frames=new Map();
+  let generation=0;
+
+  async function capture(){
+    const native=await provider();
+    insist(native&&native.schema===NATIVE_SCHEMA,'desktop capture provider returned invalid native frame');
+    insist(allowed.has(native.input_desktop),`desktop input desktop '${native.input_desktop}' is not allowed`);
+    generation++;
+    const desktopEpoch=sha256Object({
+      schema:'deadbyte.desktop-epoch.v1',runtime_nonce:runtimeNonce,session_id:native.session_id,
+      input_desktop:native.input_desktop,observer_sha256:expectedObserverSha256??'provider',generation_family:1
+    });
+    const observedAtUtc=now();
+    const frame=createDesktopFrame({
+      desktopEpoch,topologySha256:native.topology_sha256,observedAtUtc,bounds:native.bounds,
+      activeWindow:native.active_window,imageSha256:native.image_sha256
+    });
+    const record=Object.freeze({
+      frame,backend:native.backend,pixel_format:native.pixel_format,stride:native.stride,byte_length:native.byte_length,
+      system_dpi:native.system_dpi,session_id:native.session_id,input_desktop:native.input_desktop,
+      monitors:native.monitors,pixels:native.pixels,generation
+    });
+    frames.set(frame.frame_id,record);
+    while(frames.size>maxCachedFrames) frames.delete(frames.keys().next().value);
+    return Object.freeze({
+      status:'ok',frame,backend:record.backend,pixel_format:record.pixel_format,stride:record.stride,byte_length:record.byte_length,
+      system_dpi:record.system_dpi,session_id:record.session_id,input_desktop:record.input_desktop,
+      monitors:record.monitors,generation
+    });
+  }
+  function getFrameRecord(frameId){
+    insist(HEX64.test(frameId??''),'frameId invalid');
+    const found=frames.get(frameId);
+    if(!found) throw new Error('desktop frame expired or unknown');
+    return found;
+  }
+  function frameStatus(frameId){
+    const r=getFrameRecord(frameId);
+    return Object.freeze({status:'ok',frame:r.frame,backend:r.backend,byte_length:r.byte_length,generation:r.generation});
+  }
+  function framePixels(frameId){
+    return getFrameRecord(frameId).pixels;
+  }
+  function framePreview(frameId,{maxBytes=1024*1024}={}){
+    const r=getFrameRecord(frameId);
+    return createDesktopPreview({pixels:r.pixels,width:r.frame.bounds.width,height:r.frame.bounds.height,stride:r.stride,maxBytes});
+  }
+  return Object.freeze({capture,frameStatus,framePixels,framePreview});
+}

package/src/desktop-policy-r40.mjs

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { decodeUtf8Strict } from './text-policy.mjs';
+
+export const DESKTOP_POLICY_SCHEMA='deadbyte.desktop-policy.v1';
+export const DESKTOP_GRANT_SCHEMA='deadbyte.desktop-grant.v1';
+export const DESKTOP_ACTION_KINDS=Object.freeze([
+  'pointer_move','click_primary','click_secondary','double_click_primary','scroll','key_chord','text_input'
+]);
+
+const HEX64=/^[0-9a-f]{64}$/;
+const sha256Bytes=bytes=>createHash('sha256').update(bytes).digest('hex');
+
+function insist(condition,message){if(!condition)throw new Error(message);}
+function integer(value,name,min,max,fallback){
+  const n=value??fallback;
+  if(!Number.isInteger(n)||n<min||n>max)throw new Error(`${name} must be in [${min}, ${max}]`);
+  return n;
+}
+function absolute(value,label){
+  insist(typeof value==='string'&&path.isAbsolute(value),`${label} must be absolute`);
+  return path.resolve(value);
+}
+function hash(value,label){insist(typeof value==='string'&&HEX64.test(value),`${label} must be sha256`);return value;}
+function actions(value,label='allowed_actions'){
+  insist(Array.isArray(value)&&value.length>=1&&value.length<=DESKTOP_ACTION_KINDS.length,`${label} invalid`);
+  const unique=[...new Set(value)];
+  insist(unique.length===value.length&&unique.every(item=>DESKTOP_ACTION_KINDS.includes(item)),`${label} invalid`);
+  return Object.freeze(unique);
+}
+function desktopNames(value){
+  insist(Array.isArray(value)&&value.length>=1&&value.length<=8,'allowed_input_desktops invalid');
+  const result=[...new Set(value)];
+  insist(result.length===value.length&&result.every(item=>typeof item==='string'&&item.length>=1&&item.length<=128&&!item.includes('\0')),'allowed_input_desktops invalid');
+  return Object.freeze(result);
+}
+
+export async function loadDesktopPolicy(policyPath){
+  if(!policyPath) throw new Error('missing DEADBYTE desktop policy path');
+  const absolutePath=path.resolve(policyPath);
+  const bytes=await readFile(absolutePath);
+  const raw=JSON.parse(decodeUtf8Strict(bytes));
+  insist(raw&&typeof raw==='object'&&!Array.isArray(raw),'desktop policy malformed');
+  insist(raw.schema===DESKTOP_POLICY_SCHEMA&&raw.enabled===true,'desktop policy schema/enabled mismatch');
+  const observer=raw.observer??{};
+  const input=raw.input??{};
+  const grounder=raw.grounder??{};
+  const limits=raw.limits??{};
+  const policy={
+    schema:DESKTOP_POLICY_SCHEMA,enabled:true,policy_path:absolutePath,
+    grant_file:absolute(raw.grant_file,'desktop grant_file'),
+    evidence_dir:absolute(raw.evidence_dir,'desktop evidence_dir'),
+    observer:Object.freeze({
+      executable:absolute(observer.executable,'desktop observer executable'),
+      sha256:hash(observer.sha256,'desktop observer sha256'),
+      backend:typeof observer.backend==='string'?observer.backend:'gdi-bitblt-fallback'
+    }),
+    input:Object.freeze({
+      executable:absolute(input.executable,'desktop input executable'),
+      sha256:hash(input.sha256,'desktop input sha256')
+    }),
+    grounder:Object.freeze({
+      executable:absolute(grounder.executable,'desktop grounder executable'),
+      sha256:hash(grounder.sha256,'desktop grounder sha256')
+    }),
+    allowed_input_desktops:desktopNames(raw.allowed_input_desktops??['Default']),
+    allowed_actions:actions(raw.allowed_actions??DESKTOP_ACTION_KINDS),
+    limits:Object.freeze({
+      max_frame_age_ms:integer(limits.max_frame_age_ms,'limits.max_frame_age_ms',100,10000,2000),
+      max_frame_bytes:integer(limits.max_frame_bytes,'limits.max_frame_bytes',1024*1024,256*1024*1024,128*1024*1024),
+      capture_timeout_ms:integer(limits.capture_timeout_ms,'limits.capture_timeout_ms',100,60000,10000),
+      input_timeout_ms:integer(limits.input_timeout_ms,'limits.input_timeout_ms',100,30000,5000),
+      ground_timeout_ms:integer(limits.ground_timeout_ms,'limits.ground_timeout_ms',100,30000,5000),
+      post_observe_timeout_ms:integer(limits.post_observe_timeout_ms,'limits.post_observe_timeout_ms',100,60000,10000),
+      max_preview_bytes:integer(limits.max_preview_bytes,'limits.max_preview_bytes',16*1024,4*1024*1024,1024*1024),
+      max_text_bytes:integer(limits.max_text_bytes,'limits.max_text_bytes',1,64*1024,4096)
+    })
+  };
+  policy.policy_sha256=sha256Bytes(bytes);
+  await mkdir(policy.evidence_dir,{recursive:true});
+  return Object.freeze(policy);
+}
+
+export async function desktopSessionStatus(policy){
+  if(!policy||policy.schema!==DESKTOP_POLICY_SCHEMA) throw new Error('desktop policy invalid');
+  let grant;
+  try{grant=JSON.parse(decodeUtf8Strict(await readFile(policy.grant_file)));}
+  catch(error){
+    return Object.freeze({configured:true,armed:false,reason:error?.code==='ENOENT'?'disarmed':'invalid-grant',standing:false,action_kinds:[]});
+  }
+  if(!grant||grant.schema!==DESKTOP_GRANT_SCHEMA) return Object.freeze({configured:true,armed:false,reason:'grant-schema',standing:false,action_kinds:[]});
+  if(grant.policy_sha256!==policy.policy_sha256) return Object.freeze({configured:true,armed:false,reason:'policy-digest',standing:false,action_kinds:[]});
+  if(typeof grant.instance_nonce!=='string'||!HEX64.test(grant.instance_nonce)) return Object.freeze({configured:true,armed:false,reason:'nonce-invalid',standing:false,action_kinds:[]});
+  let granted;
+  try{granted=actions(grant.action_kinds,'grant.action_kinds');}
+  catch{return Object.freeze({configured:true,armed:false,reason:'actions-invalid',standing:false,action_kinds:[]});}
+  if(granted.some(item=>!policy.allowed_actions.includes(item))) return Object.freeze({configured:true,armed:false,reason:'actions-outside-policy',standing:false,action_kinds:[]});
+  return Object.freeze({
+    configured:true,armed:true,reason:'standing-grant',standing:true,instance_nonce:grant.instance_nonce,action_kinds:granted
+  });
+}
+
+export async function assertDesktopArmed(policy,actionKind){
+  insist(DESKTOP_ACTION_KINDS.includes(actionKind),'desktop action kind invalid');
+  const status=await desktopSessionStatus(policy);
+  if(!status.armed) throw new Error(`desktop plane is disarmed: ${status.reason}`);
+  if(!status.action_kinds.includes(actionKind)) throw new Error(`desktop action '${actionKind}' is outside active grant`);
+  return status;
+}

package/src/desktop-runtime-r40.mjs

@@ -0,0 +1,318 @@
+import { createHash, createPublicKey, randomBytes, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { mkdir, open, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical-json.mjs';
+import { createDesktopAction,createDesktopTarget,guardDesktopAction,bindDesktopPostObservation,bindDesktopActionChain } from './desktop-contract.mjs';
+import { effectIdentity,bindEffectCompletion } from './effect-ledger.mjs';
+import { DESKTOP_ACTION_KINDS,DESKTOP_POLICY_SCHEMA,assertDesktopArmed,desktopSessionStatus } from './desktop-policy-r40.mjs';
+
+export const DESKTOP_RECEIPT_SCHEMA='deadbyte.desktop-receipt.v1';
+const RECEIPT_DOMAIN=Buffer.from('DEADBYTE-DESKTOP-RECEIPT-V1\0','utf8');
+const HEX64=/^[0-9a-f]{64}$/;
+const RECEIPT_ID=/^[0-9a-f]{24}$/;
+const sha256Bytes=bytes=>createHash('sha256').update(bytes).digest('hex');
+const sha256Object=value=>sha256Bytes(Buffer.from(canonicalJson(value),'utf8'));
+
+function insist(condition,message){if(!condition)throw new Error(message);}
+function sameWindow(a,b){
+  if(a===null||b===null)return a===b;
+  return a.hwnd===b.hwnd&&a.pid===b.pid&&
+    (a.process_image_sha256??null)===(b.process_image_sha256??null)&&
+    (a.title_sha256??null)===(b.title_sha256??null);
+}
+function frameAgeMs(frame,nowUtc){
+  const a=Date.parse(frame.observed_at_utc),b=Date.parse(nowUtc);
+  insist(Number.isFinite(a)&&Number.isFinite(b),'desktop frame time invalid');
+  return b-a;
+}
+function targetCenter(rect){
+  return Object.freeze({
+    x:rect.left+Math.floor(rect.width/2),
+    y:rect.top+Math.floor(rect.height/2)
+  });
+}
+async function writeReceipt({policy,privateKey,keyId,evidenceDir,kind,payload,nowUtc}){
+  insist(policy?.schema===DESKTOP_POLICY_SCHEMA,'desktop receipt policy invalid');
+  insist(privateKey,'desktop receipt privateKey missing');
+  insist(typeof keyId==='string'&&keyId.length>=1&&keyId.length<=128,'desktop receipt keyId invalid');
+  const receiptId=randomBytes(12).toString('hex');
+  const body={
+    schema:DESKTOP_RECEIPT_SCHEMA,receipt_id:receiptId,kind,
+    policy_sha256:policy.policy_sha256,observed_at_utc:nowUtc,payload
+  };
+  const receiptSha256=sha256Object(body);
+  const signed={...body,receipt_sha256:receiptSha256};
+  const signature=cryptoSign(null,Buffer.concat([RECEIPT_DOMAIN,Buffer.from(canonicalJson(signed),'utf8')]),privateKey).toString('base64');
+  const receipt={...signed,attestation:{algorithm:'ed25519',key_id:keyId,signature_base64:signature}};
+  await mkdir(evidenceDir,{recursive:true});
+  const file=path.join(evidenceDir,`${receiptId}.json`);
+  const handle=await open(file,'wx',0o600);
+  try{await handle.writeFile(`${canonicalJson(receipt)}\n`);await handle.sync();}
+  finally{await handle.close();}
+  return Object.freeze({receipt_id:receiptId,receipt_sha256:receiptSha256,path:file,receipt});
+}
+
+export function verifyDesktopReceiptObject(receipt,{policySha256,publicKey,keyId}={}){
+  try{
+    insist(receipt&&receipt.schema===DESKTOP_RECEIPT_SCHEMA,'receipt schema mismatch');
+    insist(RECEIPT_ID.test(receipt.receipt_id??''),'receipt id invalid');
+    insist(receipt.policy_sha256===policySha256,'receipt policy mismatch');
+    insist(HEX64.test(receipt.receipt_sha256??''),'receipt hash invalid');
+    const {attestation,receipt_sha256:claimed,...body}=receipt;
+    insist(sha256Object(body)===claimed,'receipt hash mismatch');
+    insist(attestation?.algorithm==='ed25519'&&attestation.key_id===keyId,'receipt attestation mismatch');
+    const sig=Buffer.from(attestation.signature_base64??'','base64');
+    insist(sig.length===64,'receipt signature length invalid');
+    const signed={...body,receipt_sha256:claimed};
+    insist(cryptoVerify(null,Buffer.concat([RECEIPT_DOMAIN,Buffer.from(canonicalJson(signed),'utf8')]),publicKey,sig),'receipt signature invalid');
+    return {ok:true,receipt_sha256:claimed,kind:receipt.kind,receipt_id:receipt.receipt_id};
+  }catch(error){return {ok:false,reason:String(error?.message??error)};}
+}
+
+export function createDesktopRuntime({
+  policy,observerRuntime,inputProvider,grounderProvider=null,privateKey,publicKey=null,keyId,evidenceDir=policy?.evidence_dir,
+  now=()=>new Date().toISOString(),maxTargets=64
+}={}){
+  insist(policy?.schema===DESKTOP_POLICY_SCHEMA,'desktop runtime policy invalid');
+  insist(observerRuntime?.capture&&observerRuntime?.frameStatus,'desktop runtime observer invalid');
+  insist(typeof inputProvider==='function','desktop runtime inputProvider required');
+  insist(privateKey,'desktop runtime privateKey required');
+  insist(typeof keyId==='string'&&keyId.length>=1,'desktop runtime keyId invalid');
+  insist(Number.isInteger(maxTargets)&&maxTargets>=1&&maxTargets<=1024,'maxTargets invalid');
+  const receiptPublicKey=publicKey??createPublicKey(privateKey);
+  const targets=new Map();
+
+  async function receipt(kind,payload,stamp=now()){
+    return writeReceipt({policy,privateKey,keyId,evidenceDir,kind,payload,nowUtc:stamp});
+  }
+  async function verifyReceipt({receiptId}={}){
+    insist(RECEIPT_ID.test(receiptId??''),'desktop receipt id invalid');
+    const bytes=await readFile(path.join(evidenceDir,receiptId+'.json'));
+    insist(bytes.length>=2&&bytes.length<=512*1024,'desktop receipt file size invalid');
+    let parsed;try{parsed=JSON.parse(bytes.toString('utf8'));}catch{throw new Error('desktop receipt JSON invalid');}
+    const proof=verifyDesktopReceiptObject(parsed,{policySha256:policy.policy_sha256,publicKey:receiptPublicKey,keyId});
+    insist(proof.ok,'desktop receipt verification failed: '+String(proof.reason??'unknown'));
+    return Object.freeze(proof);
+  }
+  async function status(){
+    const authority=await desktopSessionStatus(policy);
+    return Object.freeze({
+      status:'ok',configured:true,armed:authority.armed,reason:authority.reason,
+      action_kinds:authority.action_kinds,policy_sha256:policy.policy_sha256,
+      observer_backend:policy.observer.backend
+    });
+  }
+  async function observe({preview=false}={}){
+    insist(typeof preview==='boolean','desktop preview flag invalid');
+    const observed=await observerRuntime.capture();
+    const previewValue=preview
+      ?observerRuntime.framePreview?.(observed.frame.frame_id,{maxBytes:policy.limits.max_preview_bytes})
+      :null;
+    if(preview) insist(previewValue?.schema==='deadbyte.desktop-preview.v1','desktop preview unavailable');
+    const evidence=await receipt('desktop_observation',{
+      frame_id:observed.frame.frame_id,desktop_epoch:observed.frame.desktop_epoch,
+      topology_sha256:observed.frame.topology_sha256,image_sha256:observed.frame.image_sha256,
+      observed_at_utc:observed.frame.observed_at_utc,active_window:observed.frame.active_window,
+      bounds:observed.frame.bounds,backend:observed.backend,byte_length:observed.byte_length,
+      preview:previewValue?{sha256:previewValue.sha256,byte_length:previewValue.byte_length,width:previewValue.width,height:previewValue.height,encoding:previewValue.encoding}:null
+    },observed.frame.observed_at_utc);
+    return Object.freeze({...observed,...(previewValue?{preview:previewValue}:{}),receipt_id:evidence.receipt_id,receipt_sha256:evidence.receipt_sha256});
+  }
+  function targetFor(targetId){
+    insist(HEX64.test(targetId??''),'targetId invalid');
+    const found=targets.get(targetId);if(!found)throw new Error('desktop target expired or unknown');return found;
+  }
+  async function target({frameId,rect,source,confidence,semanticLabelSha256=null,windowBinding=undefined}={}){
+    const record=observerRuntime.frameStatus(frameId);
+    const created=createDesktopTarget({
+      frame:record.frame,rect,source,confidence,semanticLabelSha256,windowBinding
+    });
+    targets.set(created.target_id,created);
+    while(targets.size>maxTargets)targets.delete(targets.keys().next().value);
+    return Object.freeze({status:'ok',target:created});
+  }
+  async function ground({frameId,query}={}){
+    insist(typeof grounderProvider==='function','desktop UIA grounder unavailable');
+    const expectedRecord=observerRuntime.frameStatus(frameId);
+    const expected=expectedRecord.frame;
+    const age=frameAgeMs(expected,now());
+    insist(age>=0&&age<=policy.limits.max_frame_age_ms,'desktop grounding frame is stale');
+    const fresh=await observerRuntime.capture();
+    insist(fresh.frame.desktop_epoch===expected.desktop_epoch,'desktop epoch changed before grounding');
+    insist(fresh.frame.topology_sha256===expected.topology_sha256,'desktop topology changed before grounding');
+    insist(sameWindow(fresh.frame.active_window,expected.active_window),'desktop foreground window changed before grounding');
+    const grounded=await grounderProvider({frame:fresh.frame,query});
+    insist(grounded&&grounded.status==='ok','desktop UIA grounder invalid result');
+    insist(grounded.ordinal<grounded.matches.length,'desktop UIA query produced no candidate at requested ordinal');
+    const candidate=grounded.matches[grounded.ordinal];
+    insist(candidate.enabled===true&&!candidate.offscreen,'desktop UIA candidate is not actionable');
+    const confidence=grounded.query_kind==='name_contains'?0.98:1;
+    const created=createDesktopTarget({
+      frame:fresh.frame,rect:candidate.rect,source:'uia',confidence,
+      semanticLabelSha256:grounded.query_sha256,windowBinding:fresh.frame.active_window
+    });
+    targets.set(created.target_id,created);
+    while(targets.size>maxTargets)targets.delete(targets.keys().next().value);
+    const evidence=await receipt('desktop_grounding',{
+      requested_frame_id:expected.frame_id,grounded_frame_id:fresh.frame.frame_id,
+      target_id:created.target_id,query_sha256:grounded.query_sha256,query_kind:grounded.query_kind,
+      ordinal:grounded.ordinal,match_count:grounded.matches.length,visited:grounded.visited,truncated:grounded.truncated,
+      provider_receipt_sha256:grounded.provider_receipt_sha256,control_type:candidate.control_type
+    },fresh.frame.observed_at_utc);
+    return Object.freeze({
+      status:'ok',frame:fresh.frame,target:created,
+      grounding:Object.freeze({
+        query_sha256:grounded.query_sha256,query_kind:grounded.query_kind,ordinal:grounded.ordinal,
+        match_count:grounded.matches.length,visited:grounded.visited,truncated:grounded.truncated,
+        control_type:candidate.control_type,provider_receipt_sha256:grounded.provider_receipt_sha256,
+        receipt_id:evidence.receipt_id,receipt_sha256:evidence.receipt_sha256
+      })
+    });
+  }
+  async function action({
+    intentId,kind,expectedFrameId,targetId=null,expectedWindow=undefined,point=null,
+    scrollDelta=null,keyChord=null,text=null,effectContext=null
+  }={}){
+    insist(DESKTOP_ACTION_KINDS.includes(kind),'desktop action kind invalid');
+    const authority=await assertDesktopArmed(policy,kind);
+    if(kind==='text_input'){
+      insist(typeof text==='string','desktop text input invalid');
+      insist(Buffer.byteLength(text,'utf8')<=policy.limits.max_text_bytes,'desktop text input exceeds policy byte limit');
+    }
+    const expectedRecord=observerRuntime.frameStatus(expectedFrameId);
+    const expected=expectedRecord.frame;
+    const requestAt=now();
+    const age=frameAgeMs(expected,requestAt);
+    insist(age>=0&&age<=policy.limits.max_frame_age_ms,'desktop expected frame is stale');
+
+    let chosenTarget=null;
+    if(targetId!==null){
+      chosenTarget=targetFor(targetId);
+      insist(chosenTarget.frame_id===expected.frame_id,'desktop target/frame mismatch');
+    }
+
+    const pre=await observerRuntime.capture();
+    insist(pre.frame.desktop_epoch===expected.desktop_epoch,'desktop epoch changed before action');
+    insist(pre.frame.topology_sha256===expected.topology_sha256,'desktop topology changed before action');
+    insist(sameWindow(pre.frame.active_window,expected.active_window),'desktop foreground window changed before action');
+    // Pointer and text actions depend on visual/control state. A key chord is window-scoped:
+    // bind it to the same fresh desktop/topology/foreground identity and let the native helper
+    // revalidate HWND/PID immediately before SendInput instead of requiring unrelated pixels to freeze.
+    if(kind!=='key_chord') insist(pre.frame.image_sha256===expected.image_sha256,'desktop pixels changed before action');
+
+    let actionPoint=point;
+    if(chosenTarget&&['pointer_move','click_primary','click_secondary','double_click_primary','scroll'].includes(kind)){
+      actionPoint=targetCenter(chosenTarget.rect);
+    }
+    const expectedWindowValue=expectedWindow===undefined?pre.frame.active_window:expectedWindow;
+    const actionObject=createDesktopAction({
+      intentId,kind,frameId:pre.frame.frame_id,desktopEpoch:pre.frame.desktop_epoch,
+      topologySha256:pre.frame.topology_sha256,expectedWindow:expectedWindowValue,
+      point:actionPoint,scrollDelta,keyChord,text,targetId:chosenTarget?.target_id??null
+    });
+    const guarded=guardDesktopAction({
+      frame:pre.frame,action:actionObject,nowUtc:now(),maxFrameAgeMs:policy.limits.max_frame_age_ms
+    });
+    const effectAction=Object.freeze({
+      kind:`desktop_${kind}`,action_sha256:actionObject.action_sha256,frame_id:pre.frame.frame_id,
+      target_id:actionObject.target_id,point:actionObject.point,scroll_delta:actionObject.scroll_delta,
+      key_chord:actionObject.key_chord,text_sha256:actionObject.text_sha256
+    });
+    const ctx=effectContext??{};
+    const effectLedger=effectIdentity({
+      goalId:ctx.goalId??intentId,planId:ctx.planId??pre.frame.frame_id,
+      stepId:ctx.stepId??`desktop.${kind}`,mutationEpoch:ctx.mutationEpoch??0,
+      action:effectAction,observationHeadSha256:ctx.observationHeadSha256??pre.frame.frame_id
+    });
+    const started=await receipt('desktop_action_started',{
+      intent_id:intentId,kind,expected_frame_id:expected.frame_id,pre_frame_id:pre.frame.frame_id,
+      target_id:chosenTarget?.target_id??null,action_sha256:actionObject.action_sha256,
+      guard_sha256:guarded.guard_sha256,authority_instance_nonce:authority.instance_nonce,
+      effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint
+    });
+
+    let effect;
+    try{
+      effect=await inputProvider(actionObject,{
+        timeoutMs:policy.limits.input_timeout_ms,guard:guarded,
+        inputDesktop:pre.input_desktop??null,expectedBounds:pre.frame.bounds,expectedWindow:pre.frame.active_window
+      });
+      insist(effect&&effect.injected===true,'desktop input provider did not confirm injection');
+    }catch(error){
+      const sideEffectState=error?.side_effect_state==='not_started'?'not_started':'unknown';
+      const evidenceKind=sideEffectState==='not_started'?'desktop_action_effect_failed':'desktop_action_outcome_unknown';
+      const failure=await receipt(evidenceKind,{
+        started_receipt_id:started.receipt_id,started_receipt_sha256:started.receipt_sha256,
+        action_sha256:actionObject.action_sha256,guard_sha256:guarded.guard_sha256,
+        effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,
+        side_effect_state:sideEffectState,error_sha256:sha256Bytes(Buffer.from(String(error?.message??error),'utf8'))
+      });
+      const wrapped=new Error(sideEffectState==='not_started'
+        ?'desktop input effect did not start'
+        :'desktop action outcome unknown after input dispatch; inspect fresh desktop state before retry');
+      wrapped.side_effect_state=sideEffectState;
+      wrapped.receipt_id=failure.receipt_id;wrapped.receipt_sha256=failure.receipt_sha256;
+      wrapped.effect_id=effectLedger.effect_id;wrapped.effect_fingerprint=effectLedger.fingerprint;
+      throw wrapped;
+    }
+
+    try{
+      const post=await observerRuntime.capture();
+      const bound=bindDesktopPostObservation({guard:guarded,beforeFrame:pre.frame,action:actionObject,afterFrame:post.frame});
+      const postEvidence=await receipt('desktop_post_observation',{
+        started_receipt_id:started.receipt_id,started_receipt_sha256:started.receipt_sha256,
+        effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,
+        frame_id:post.frame.frame_id,desktop_epoch:post.frame.desktop_epoch,
+        topology_sha256:post.frame.topology_sha256,image_sha256:post.frame.image_sha256,
+        observed_at_utc:post.frame.observed_at_utc,active_window:post.frame.active_window,
+        bounds:post.frame.bounds,backend:post.backend,byte_length:post.byte_length,
+        post_observation_sha256:bound.post_observation_sha256
+      },post.frame.observed_at_utc);
+      const chain=bindDesktopActionChain({
+        beforeFrameId:pre.frame.frame_id,actionSha256:actionObject.action_sha256,
+        afterFrameId:post.frame.frame_id,guardSha256:guarded.guard_sha256,
+        postObservationSha256:bound.post_observation_sha256,postReceiptSha256:postEvidence.receipt_sha256,
+        effectId:effectLedger.effect_id,effectFingerprint:effectLedger.fingerprint
+      });
+      const effectCompletion=bindEffectCompletion(effectLedger,{
+        side_effect_state:'confirmed_injected',provider_receipt_sha256:HEX64.test(effect.provider_receipt_sha256??'')?effect.provider_receipt_sha256:null,
+        post_observation_sha256:bound.post_observation_sha256,post_receipt_sha256:postEvidence.receipt_sha256,
+        chain_sha256:chain.chain_sha256
+      });
+      const completed=await receipt('desktop_action_completed',{
+        started_receipt_id:started.receipt_id,started_receipt_sha256:started.receipt_sha256,
+        post_receipt_id:postEvidence.receipt_id,post_receipt_sha256:postEvidence.receipt_sha256,
+        action_sha256:actionObject.action_sha256,guard_sha256:guarded.guard_sha256,
+        effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,effect_completion:effectCompletion,
+        effect:{injected:true,side_effect_state:'confirmed_injected',provider_receipt_sha256:HEX64.test(effect.provider_receipt_sha256??'')?effect.provider_receipt_sha256:null},
+        action_chain:chain,post_observation:bound
+      },post.frame.observed_at_utc);
+      return Object.freeze({
+        status:'ok',injected:true,task_success:null,side_effect_state:'confirmed_injected',
+        action:actionObject,guard:guarded,post_observation:bound,action_chain:chain,
+        effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,effect_completion:effectCompletion,
+        started_receipt_id:started.receipt_id,started_receipt_sha256:started.receipt_sha256,
+        post_receipt_id:postEvidence.receipt_id,post_receipt_sha256:postEvidence.receipt_sha256,
+        receipt_id:completed.receipt_id,receipt_sha256:completed.receipt_sha256
+      });
+    }catch(error){
+      if(error?.receipt_id&&error?.side_effect_state) throw error;
+      let unknown=null;
+      try{
+        unknown=await receipt('desktop_action_outcome_unknown',{
+          started_receipt_id:started.receipt_id,started_receipt_sha256:started.receipt_sha256,
+          action_sha256:actionObject.action_sha256,guard_sha256:guarded.guard_sha256,
+          effect_id:effectLedger.effect_id,effect_fingerprint:effectLedger.fingerprint,
+          side_effect_state:'unknown',injection_confirmed:true,
+          provider_receipt_sha256:HEX64.test(effect.provider_receipt_sha256??'')?effect.provider_receipt_sha256:null,
+          error_sha256:sha256Bytes(Buffer.from(String(error?.message??error),'utf8'))
+        });
+      }catch{}
+      const wrapped=new Error('desktop action outcome unknown after confirmed input; post-observation/evidence incomplete; inspect fresh desktop state before retry');
+      wrapped.side_effect_state='unknown';wrapped.effect_id=effectLedger.effect_id;wrapped.effect_fingerprint=effectLedger.fingerprint;
+      if(unknown){wrapped.receipt_id=unknown.receipt_id;wrapped.receipt_sha256=unknown.receipt_sha256;}
+      throw wrapped;
+    }
+  }
+  return Object.freeze({status,observe,target,ground,action,verifyReceipt});
+}