deadbyte-mcp 0.11.2 → 0.12.0

package/src/desktop-input-r40.mjs

@@ -0,0 +1,148 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const DESKTOP_NATIVE_INPUT_SCHEMA='deadbyte.desktop-native-input.v1';
+const HEX64=/^[0-9a-f]{64}$/;
+const HWND=/^0x[0-9a-f]{1,16}$/;
+const KINDS=new Set(['pointer_move','click_primary','click_secondary','double_click_primary','scroll','key_chord','text_input']);
+const sha256Bytes=value=>createHash('sha256').update(value).digest('hex');
+
+function insist(condition,message){if(!condition)throw new Error(message);}
+function sideEffectError(error,state){
+  const e=error instanceof Error?error:new Error(String(error));
+  if(e.side_effect_state!=='not_started'&&e.side_effect_state!=='unknown') e.side_effect_state=state;
+  return e;
+}
+function integer(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 hwnd(value){
+  const text=String(value??'').toLowerCase();
+  insist(HWND.test(text),'desktop native input hwnd invalid');
+  return text;
+}
+function lineValue(value,label){
+  const text=String(value??'');
+  insist(text.length>=1&&Buffer.byteLength(text,'utf8')<=512&&!/[\r\n\0]/.test(text),`${label} invalid`);
+  return text;
+}
+
+export function serializeNativeDesktopInputRequest(action,{inputDesktop,expectedBounds,expectedWindow}={}){
+  insist(action&&typeof action==='object'&&action.schema==='deadbyte.desktop-action.v1','desktop native input action invalid');
+  insist(HEX64.test(action.action_sha256??''),'desktop native input action hash invalid');
+  insist(KINDS.has(action.kind),'desktop native input kind invalid');
+  insist(expectedBounds&&typeof expectedBounds==='object','desktop native input bounds missing');
+  const left=integer(expectedBounds.left,'desktop native input left',{min:-131072,max:131072});
+  const top=integer(expectedBounds.top,'desktop native input top',{min:-131072,max:131072});
+  const width=integer(expectedBounds.width,'desktop native input width',{min:1,max:131072});
+  const height=integer(expectedBounds.height,'desktop native input height',{min:1,max:131072});
+  insist(left+width<=262144&&top+height<=262144,'desktop native input bounds extent invalid');
+  const desktop=lineValue(inputDesktop,'desktop native input desktop');
+  const window=expectedWindow??null;
+  const expectedHwnd=window===null?'0x0':hwnd(window.hwnd);
+  const expectedPid=window===null?0:integer(window.pid,'desktop native input pid',{min:1,max:0x7fffffff});
+  const pointer=['pointer_move','click_primary','click_secondary','double_click_primary','scroll'].includes(action.kind);
+  const x=pointer?integer(action.point?.x,'desktop native input x',{min:-131072,max:131072}):0;
+  const y=pointer?integer(action.point?.y,'desktop native input y',{min:-131072,max:131072}):0;
+  if(pointer) insist(x>=left&&y>=top&&x<left+width&&y<top+height,'desktop native input point outside bounds');
+  const delta=action.kind==='scroll'?integer(action.scroll_delta,'desktop native input scroll',{min:-12000,max:12000}):0;
+  if(action.kind==='scroll') insist(delta!==0,'desktop native input scroll cannot be zero');
+  const keys=action.kind==='key_chord'?[...(action.key_chord??[])]:[];
+  if(action.kind==='key_chord') insist(keys.length>=1&&keys.length<=5,'desktop native input key chord invalid');
+  else insist(action.key_chord===null,'desktop native input unexpected key chord');
+  const text=action.kind==='text_input'?String(action.text??''):'';
+  const textBytes=Buffer.from(text,'utf8');
+  if(action.kind==='text_input') insist(textBytes.length>=1&&textBytes.length<=64*1024&&!text.includes('\0'),'desktop native input text invalid');
+  else insist(action.text===null,'desktop native input unexpected text');
+
+  const lines=[
+    'DEADBYTE_DESKTOP_INPUT_V1',
+    `action_sha256=${action.action_sha256}`,
+    `kind=${action.kind}`,
+    `expected_desktop=${desktop}`,
+    `expected_hwnd=${expectedHwnd}`,
+    `expected_pid=${expectedPid}`,
+    `left=${left}`,`top=${top}`,`width=${width}`,`height=${height}`,
+    `x=${x}`,`y=${y}`,`scroll_delta=${delta}`,
+    `key_count=${keys.length}`,
+    ...keys.map(key=>`key=${lineValue(key,'desktop native input key')}`),
+    `text_bytes=${textBytes.length}`
+  ];
+  const header=Buffer.from(lines.join('\n')+'\n','utf8');
+  const request=Buffer.concat([header,textBytes]);
+  insist(request.length<=128*1024,'desktop native input request exceeds bound');
+  return request;
+}
+
+export function parseNativeDesktopInputResponse(bytes,{actionSha256,kind,inputDesktop,expectedWindow}={}){
+  insist(Buffer.isBuffer(bytes)&&bytes.length>=2&&bytes.length<=64*1024,'desktop native input response invalid');
+  let raw;
+  try{raw=JSON.parse(bytes.toString('utf8').trim());}catch{throw new Error('desktop native input response JSON invalid');}
+  insist(raw?.schema===DESKTOP_NATIVE_INPUT_SCHEMA,'desktop native input response schema mismatch');
+  insist(raw.injected===true&&raw.backend==='win32-sendinput','desktop native input response did not confirm injection');
+  insist(raw.action_sha256===actionSha256&&raw.kind===kind,'desktop native input response action mismatch');
+  insist(raw.input_desktop===inputDesktop,'desktop native input response desktop mismatch');
+  const expected=expectedWindow??null;
+  insist(hwnd(raw.foreground_hwnd)===(expected===null?'0x0':hwnd(expected.hwnd)),'desktop native input response foreground hwnd mismatch');
+  insist(integer(raw.foreground_pid,'desktop native input response pid',{min:0,max:0x7fffffff})===(expected===null?0:expected.pid),'desktop native input response foreground pid mismatch');
+  integer(raw.event_count,'desktop native input event_count',{min:1,max:65536});
+  return Object.freeze({
+    injected:true,backend:raw.backend,event_count:raw.event_count,
+    provider_receipt_sha256:sha256Bytes(bytes)
+  });
+}
+
+export async function invokeNativeDesktopInput(action,{
+  inputPath,expectedInputSha256,timeoutMs=5000,inputDesktop,expectedBounds,expectedWindow
+}={}){
+  let request;
+  try{
+    insist(typeof inputPath==='string'&&path.isAbsolute(inputPath),'desktop inputPath must be absolute');
+    insist(HEX64.test(expectedInputSha256??''),'desktop expectedInputSha256 invalid');
+    integer(timeoutMs,'desktop input timeoutMs',{min:100,max:30000});
+    const exe=await readFile(inputPath);
+    insist(exe.length>0&&exe.length<=4*1024*1024,'desktop input binary size invalid');
+    insist(sha256Bytes(exe)===expectedInputSha256,'desktop input executable hash mismatch');
+    request=serializeNativeDesktopInputRequest(action,{inputDesktop,expectedBounds,expectedWindow});
+  }catch(error){throw sideEffectError(error,'not_started');}
+  return await new Promise((resolve,reject)=>{
+    let child;
+    try{child=spawn(inputPath,[],{shell:false,windowsHide:true,stdio:['pipe','pipe','pipe']});}
+    catch(error){reject(sideEffectError(error,'not_started'));return;}
+    const stdout=[];let stdoutBytes=0,stderr='',done=false,timer=null;
+    const finish=(error,value,state='unknown')=>{
+      if(done)return;done=true;if(timer!==null)clearTimeout(timer);
+      error?reject(sideEffectError(error,state)):resolve(value);
+    };
+    child.stdout.on('data',chunk=>{
+      stdoutBytes+=chunk.length;
+      if(stdoutBytes>64*1024){try{child.kill('SIGKILL');}catch{};return finish(new Error('desktop input stdout exceeds bound'));}
+      stdout.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 input stderr exceeds bound'));}
+    });
+    child.once('error',error=>finish(error,null,'not_started'));
+    child.once('exit',(code,signal)=>{
+      if(code!==0)return finish(new Error(`desktop input exit=${code} signal=${signal??'none'} stderr=${stderr.slice(-8192)}`));
+      try{
+        finish(null,parseNativeDesktopInputResponse(Buffer.concat(stdout),{
+          actionSha256:action.action_sha256,kind:action.kind,inputDesktop,expectedWindow
+        }));
+      }catch(error){finish(error);}
+    });
+    child.stdin.on('error',error=>finish(error));
+    child.stdin.end(request);
+    timer=setTimeout(()=>{try{child.kill('SIGKILL');}catch{};finish(new Error(`desktop input timed out after ${timeoutMs}ms`));},timeoutMs);
+  });
+}
+
+export function createNativeDesktopInputProvider({inputPath,expectedInputSha256,timeoutMs=5000}={}){
+  return async(action,context={})=>invokeNativeDesktopInput(action,{
+    inputPath,expectedInputSha256,timeoutMs:context.timeoutMs??timeoutMs,
+    inputDesktop:context.inputDesktop,expectedBounds:context.expectedBounds,expectedWindow:context.expectedWindow
+  });
+}

package/src/desktop-mcp-tools-r40.mjs

@@ -0,0 +1,126 @@
+import { createHash } from 'node:crypto';
+import * as z from 'zod/v4';
+import { compactGatewayOutputSchema,compactGatewayResult } from './compact-gateway-output-contracts.mjs';
+
+const hex64=z.string().regex(/^[0-9a-f]{64}$/);
+const point=z.strictObject({
+  x:z.number().int().min(-131072).max(131072),
+  y:z.number().int().min(-131072).max(131072)
+});
+const rect=z.strictObject({
+  left:z.number().int().min(-131072).max(131072),
+  top:z.number().int().min(-131072).max(131072),
+  width:z.number().int().min(1).max(131072),
+  height:z.number().int().min(1).max(131072)
+});
+const key=z.string().regex(/^(?:[A-Z0-9]|F(?:[1-9]|1[0-2])|ENTER|ESC|TAB|SPACE|BACKSPACE|DELETE|INSERT|HOME|END|PAGEUP|PAGEDOWN|LEFT|RIGHT|UP|DOWN|CTRL|ALT|SHIFT|WIN)$/);
+const actionKinds=z.enum(['pointer_move','click_primary','click_secondary','double_click_primary','scroll','key_chord','text_input']);
+const pointerKinds=new Set(['pointer_move','click_primary','click_secondary','double_click_primary','scroll']);
+
+export const desktopStatusInputSchema=z.strictObject({});
+export const desktopObserveInputSchema=z.strictObject({preview:z.boolean().default(false)});
+const uiaQuery=z.strictObject({
+  kind:z.enum(['root','name_exact','name_contains','automation_id_exact','control_type']),
+  value:z.string().max(512).default(''),max_results:z.number().int().min(1).max(16).default(8),
+  ordinal:z.number().int().min(0).max(15).default(0)
+}).superRefine((value,ctx)=>{
+  if(value.ordinal>=value.max_results)ctx.addIssue({code:'custom',path:['ordinal'],message:'ordinal must be below max_results'});
+  if(value.kind==='root'&&value.value!=='')ctx.addIssue({code:'custom',path:['value'],message:'root query cannot carry value'});
+  if(value.kind!=='root'&&value.value.length<1)ctx.addIssue({code:'custom',path:['value'],message:'UIA query value required'});
+});
+const explicitTargetFields={
+  frame_id:hex64,rect,source:z.enum(['visual','uia','accessibility','geometry']),
+  confidence:z.number().min(0).max(1),semantic_label_sha256:hex64.nullable().default(null)
+};
+const uiaTargetFields={frame_id:hex64,uia_query:uiaQuery};
+export const desktopTargetInputSchema=z.union([
+  z.strictObject(explicitTargetFields),z.strictObject(uiaTargetFields)
+]);
+const actionFields={
+  intent_id:hex64,kind:actionKinds,expected_frame_id:hex64,target_id:hex64.nullable().default(null),
+  point:point.nullable().default(null),scroll_delta:z.number().int().min(-12000).max(12000).nullable().default(null),
+  key_chord:z.array(key).min(1).max(5).nullable().default(null),
+  text:z.string().min(1).max(4096).refine(value=>!value.includes('\u0000'),'text contains NUL').nullable().default(null)
+};
+function validateAction(value,ctx){
+  const pointer=pointerKinds.has(value.kind);
+  if(pointer){
+    if((value.target_id===null)===(value.point===null)) ctx.addIssue({code:'custom',message:'pointer action requires exactly one of target_id or point'});
+  }else if(value.target_id!==null||value.point!==null) ctx.addIssue({code:'custom',message:'non-pointer action cannot carry target_id or point'});
+  if(value.kind==='scroll'){
+    if(value.scroll_delta===null||value.scroll_delta===0) ctx.addIssue({code:'custom',path:['scroll_delta'],message:'scroll requires non-zero scroll_delta'});
+  }else if(value.scroll_delta!==null) ctx.addIssue({code:'custom',path:['scroll_delta'],message:'non-scroll action cannot carry scroll_delta'});
+  if(value.kind==='key_chord'){
+    if(value.key_chord===null||new Set(value.key_chord).size!==value.key_chord.length) ctx.addIssue({code:'custom',path:['key_chord'],message:'key_chord missing or duplicate'});
+  }else if(value.key_chord!==null) ctx.addIssue({code:'custom',path:['key_chord'],message:'non-key action cannot carry key_chord'});
+  if(value.kind==='text_input'){
+    if(value.text===null) ctx.addIssue({code:'custom',path:['text'],message:'text_input requires text'});
+  }else if(value.text!==null) ctx.addIssue({code:'custom',path:['text'],message:'non-text action cannot carry text'});
+}
+export const desktopActionInputSchema=z.strictObject(actionFields).superRefine(validateAction);
+
+const statusOp=z.strictObject({op:z.literal('status')});
+const observeOp=z.strictObject({op:z.literal('observe'),preview:z.boolean().default(false)});
+const targetOp=z.union([
+  z.strictObject({op:z.literal('target'),...explicitTargetFields}),
+  z.strictObject({op:z.literal('target'),...uiaTargetFields})
+]);
+const actionOp=z.strictObject({op:z.literal('action'),...actionFields}).superRefine(validateAction);
+export const desktopControlInputSchema=z.union([statusOp,observeOp,targetOp,actionOp]);
+
+const sha256=value=>createHash('sha256').update(value).digest('hex');
+function publicResult(value){
+  if(!value||typeof value!=='object'||!value.action) return value;
+  const {action,...rest}=value;
+  const summary={
+    schema:'deadbyte.desktop-action-summary.v1',intent_id:action.intent_id,kind:action.kind,frame_id:action.frame_id,
+    desktop_epoch:action.desktop_epoch,topology_sha256:action.topology_sha256,expected_window:action.expected_window,
+    target_id:action.target_id,point:action.point,scroll_delta:action.scroll_delta,key_chord:action.key_chord,
+    text_sha256:action.text_sha256,action_sha256:action.action_sha256,
+    ...(action.kind==='text_input'?{text_bytes:Buffer.byteLength(action.text??'','utf8')}: {})
+  };
+  return Object.freeze({...rest,action_summary:Object.freeze(summary)});
+}
+
+export async function invokeDesktopOperation(args,runtime){
+  const op=args.op;
+  if(!runtime) return compactGatewayResult({status:'unavailable',op,error:'desktop runtime unavailable'},true);
+  try{
+    let value;
+    if(op==='status') value=await runtime.status();
+    else if(op==='observe') value=await runtime.observe({preview:args.preview??false});
+    else if(op==='target'&&args.uia_query) value=await runtime.ground({frameId:args.frame_id,query:args.uia_query});
+    else if(op==='target') value=await runtime.target({
+      frameId:args.frame_id,rect:args.rect,source:args.source,confidence:args.confidence,
+      semanticLabelSha256:args.semantic_label_sha256
+    });
+    else if(op==='action') value=await runtime.action({
+      intentId:args.intent_id,kind:args.kind,expectedFrameId:args.expected_frame_id,targetId:args.target_id,
+      point:args.point,scrollDelta:args.scroll_delta,keyChord:args.key_chord,text:args.text
+    });
+    else throw new Error('desktop operation unsupported');
+    return compactGatewayResult({status:'ok',op,result:publicResult(value)},false);
+  }catch(error){
+    return compactGatewayResult({status:'denied',op,error:String(error?.message??error)},true);
+  }
+}
+
+export function registerDesktopTools(server,{runtime}={}){
+  if(!server||!runtime) throw new Error('desktop tool registration requires server/runtime');
+  server.registerTool('desktop_status',{
+    description:'Read Desktop runtime configuration and standing-grant state. This never arms Desktop authority.',
+    inputSchema:desktopStatusInputSchema,outputSchema:compactGatewayOutputSchema
+  },()=>invokeDesktopOperation({op:'status'},runtime));
+  server.registerTool('desktop_observe',{
+    description:'Capture one bounded Windows desktop frame and signed observation evidence. Observation does not require Desktop mutation authority.',
+    inputSchema:desktopObserveInputSchema,outputSchema:compactGatewayOutputSchema
+  },args=>invokeDesktopOperation({op:'observe',...args},runtime));
+  server.registerTool('desktop_target',{
+    description:'Bind one explicit rectangle or one local Windows UIA query to fresh desktop evidence. UIA query text is matched locally and is not returned.',
+    inputSchema:desktopTargetInputSchema,outputSchema:compactGatewayOutputSchema
+  },args=>invokeDesktopOperation({op:'target',...args},runtime));
+  server.registerTool('desktop_action',{
+    description:'Perform one guarded Desktop effect against a fresh observed frame. Requires separate Desktop standing authority and signed before/after evidence.',
+    inputSchema:desktopActionInputSchema,outputSchema:compactGatewayOutputSchema
+  },args=>invokeDesktopOperation({op:'action',...args},runtime));
+}

package/src/desktop-memory-r40.mjs

@@ -0,0 +1,272 @@
+import { createHash, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { mkdir, open, opendir, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalJson } from './canonical-json.mjs';
+import { verifyDesktopReceiptObject } from './desktop-runtime-r40.mjs';
+
+export const DESKTOP_MEMORY_SCHEMA='deadbyte.desktop-memory.v1';
+export const DESKTOP_MEMORY_SNAPSHOT_SCHEMA='deadbyte.desktop-memory-snapshot.v1';
+const DOMAIN=Buffer.from('DEADBYTE-DESKTOP-MEMORY-V1\0','utf8');
+const HEX64=/^[0-9a-f]{64}$/;
+const RECEIPT_FILE=/^[0-9a-f]{24}\.json$/;
+const sha=value=>createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+const uniq=values=>[...new Set(values.filter(v=>typeof v==='string'&&v.length>0))];
+
+function insist(c,m){if(!c)throw new Error(m);}
+function safeWindow(value){
+  if(value===null||value===undefined)return null;
+  if(typeof value!=='object'||Array.isArray(value))return null;
+  const hwnd=typeof value.hwnd==='string'?value.hwnd:null;
+  const pid=Number.isInteger(value.pid)?value.pid:null;
+  if(!hwnd||pid===null)return null;
+  return Object.freeze({
+    hwnd,pid,
+    process_image_sha256:HEX64.test(value.process_image_sha256??'')?value.process_image_sha256:null,
+    title_sha256:HEX64.test(value.title_sha256??'')?value.title_sha256:null
+  });
+}
+function windowKey(w){return w?sha({schema:'deadbyte.desktop-window-memory-key.v1',...w}):null;}
+function boundedPush(array,value,max){array.push(value);while(array.length>max)array.shift();}
+function receiptSort(a,b){
+  const at=Date.parse(a?.observed_at_utc??''),bt=Date.parse(b?.observed_at_utc??'');
+  if(Number.isFinite(at)&&Number.isFinite(bt)&&at!==bt)return at-bt;
+  return String(a?.receipt_id??'').localeCompare(String(b?.receipt_id??''),'en');
+}
+
+export function deriveDesktopMemory(receipts,{policySha256,publicKey,keyId,maxTrajectory=32,maxWindows=32}={}){
+  insist(Array.isArray(receipts),'desktop memory receipts must be array');
+  insist(HEX64.test(policySha256??''),'desktop memory policy sha invalid');
+  insist(publicKey,'desktop memory publicKey missing');
+  insist(typeof keyId==='string'&&keyId.length>=1,'desktop memory keyId invalid');
+  insist(Number.isInteger(maxTrajectory)&&maxTrajectory>=1&&maxTrajectory<=256,'desktop memory maxTrajectory invalid');
+  insist(Number.isInteger(maxWindows)&&maxWindows>=1&&maxWindows<=128,'desktop memory maxWindows invalid');
+
+  const verified=[...receipts].sort(receiptSort);
+  for(const receipt of verified){
+    const proof=verifyDesktopReceiptObject(receipt,{policySha256,publicKey,keyId});
+    insist(proof.ok,'desktop memory rejected unauthenticated receipt '+String(receipt?.receipt_id??'unknown')+': '+String(proof.reason??'invalid'));
+  }
+
+  const windows=new Map();
+  const started=new Map();
+  const trajectory=[];
+  const groundedTargets=[];
+  const rejectedTargetFingerprints=[];
+  const unknownEffects=new Map();
+  let lastVerifiedDesktop=null;
+
+  const rememberWindow=value=>{
+    const w=safeWindow(value);if(!w)return;
+    const key=windowKey(w);windows.set(key,{window_id:key,...w});
+    while(windows.size>maxWindows)windows.delete(windows.keys().next().value);
+  };
+
+  for(const receipt of verified){
+    const p=receipt.payload&&typeof receipt.payload==='object'?receipt.payload:{};
+    if(receipt.kind==='desktop_observation'){
+      rememberWindow(p.active_window);
+      if(HEX64.test(p.frame_id??'')&&HEX64.test(p.desktop_epoch??'')&&HEX64.test(p.topology_sha256??'')){
+        lastVerifiedDesktop={
+          frame_id:p.frame_id,desktop_epoch:p.desktop_epoch,topology_sha256:p.topology_sha256,
+          window_id:windowKey(safeWindow(p.active_window)),observed_at_utc:receipt.observed_at_utc,
+          receipt_sha256:receipt.receipt_sha256
+        };
+      }
+    }else if(receipt.kind==='desktop_grounding'){
+      if(HEX64.test(p.target_id??'')&&HEX64.test(p.query_sha256??'')){
+        boundedPush(groundedTargets,{
+          target_id:p.target_id,query_sha256:p.query_sha256,query_kind:String(p.query_kind??''),
+          frame_id:HEX64.test(p.grounded_frame_id??'')?p.grounded_frame_id:null,
+          control_type:Number.isInteger(p.control_type)?p.control_type:null,
+          receipt_sha256:receipt.receipt_sha256
+        },maxTrajectory);
+      }
+    }else if(receipt.kind==='desktop_action_started'){
+      if(HEX64.test(p.effect_id??'')) started.set(p.effect_id,{
+        effect_id:p.effect_id,effect_fingerprint:HEX64.test(p.effect_fingerprint??'')?p.effect_fingerprint:null,
+        action_sha256:HEX64.test(p.action_sha256??'')?p.action_sha256:null,
+        target_id:HEX64.test(p.target_id??'')?p.target_id:null,kind:String(p.kind??''),
+        frame_id:HEX64.test(p.pre_frame_id??'')?p.pre_frame_id:null,
+        receipt_sha256:receipt.receipt_sha256
+      });
+    }else if(receipt.kind==='desktop_post_observation'){
+      rememberWindow(p.active_window);
+      if(HEX64.test(p.frame_id??'')&&HEX64.test(p.desktop_epoch??'')&&HEX64.test(p.topology_sha256??'')){
+        lastVerifiedDesktop={
+          frame_id:p.frame_id,desktop_epoch:p.desktop_epoch,topology_sha256:p.topology_sha256,
+          window_id:windowKey(safeWindow(p.active_window)),observed_at_utc:receipt.observed_at_utc,
+          receipt_sha256:receipt.receipt_sha256
+        };
+      }
+    }else if(receipt.kind==='desktop_action_completed'){
+      const effectId=HEX64.test(p.effect_id??'')?p.effect_id:null;
+      const s=effectId?started.get(effectId):null;
+      if(effectId&&HEX64.test(p.effect_fingerprint??'')&&p.effect?.side_effect_state==='confirmed_injected'){
+        boundedPush(trajectory,{
+          effect_id:effectId,effect_fingerprint:p.effect_fingerprint,
+          action_sha256:HEX64.test(p.action_sha256??'')?p.action_sha256:s?.action_sha256??null,
+          target_id:s?.target_id??null,kind:s?.kind??null,side_effect_state:'confirmed_injected',
+          chain_sha256:HEX64.test(p.action_chain?.chain_sha256??'')?p.action_chain.chain_sha256:null,
+          post_observation_sha256:HEX64.test(p.post_observation?.post_observation_sha256??'')?p.post_observation.post_observation_sha256:null,
+          window_transition:p.post_observation?.foreground_transition?.changed===true,
+          receipt_sha256:receipt.receipt_sha256
+        },maxTrajectory);
+        unknownEffects.delete(effectId);
+      }
+    }else if(receipt.kind==='desktop_action_effect_failed'){
+      const effectId=HEX64.test(p.effect_id??'')?p.effect_id:null;
+      const s=effectId?started.get(effectId):null;
+      if(p.side_effect_state==='not_started'&&s?.target_id){
+        boundedPush(rejectedTargetFingerprints,sha({
+          schema:'deadbyte.desktop-rejected-target.v1',target_id:s.target_id,
+          effect_fingerprint:s.effect_fingerprint,action_sha256:s.action_sha256
+        }),maxTrajectory);
+      }
+    }else if(receipt.kind==='desktop_action_outcome_unknown'){
+      const effectId=HEX64.test(p.effect_id??'')?p.effect_id:null;
+      if(effectId) unknownEffects.set(effectId,{
+        effect_id:effectId,effect_fingerprint:HEX64.test(p.effect_fingerprint??'')?p.effect_fingerprint:null,
+        action_sha256:HEX64.test(p.action_sha256??'')?p.action_sha256:null,
+        receipt_sha256:receipt.receipt_sha256
+      });
+    }
+  }
+
+  const body={
+    schema:DESKTOP_MEMORY_SCHEMA,policy_sha256:policySha256,
+    source_receipt_sha256:verified.map(r=>r.receipt_sha256),
+    last_verified_desktop:lastVerifiedDesktop,
+    windows:[...windows.values()].sort((a,b)=>a.window_id.localeCompare(b.window_id,'en')),
+    grounded_targets:groundedTargets,
+    rejected_target_fingerprints:uniq(rejectedTargetFingerprints),
+    recent_effects:trajectory,
+    unresolved_unknown_effects:[...unknownEffects.values()].sort((a,b)=>a.effect_id.localeCompare(b.effect_id,'en'))
+  };
+  return Object.freeze({...body,memory_sha256:sha(body)});
+}
+
+export function signDesktopMemory(memory,{privateKey,keyId}={}){
+  insist(memory?.schema===DESKTOP_MEMORY_SCHEMA&&HEX64.test(memory.memory_sha256??''),'desktop memory invalid');
+  insist(privateKey,'desktop memory privateKey missing');
+  insist(typeof keyId==='string'&&keyId.length>=1&&keyId.length<=128,'desktop memory signing key id invalid');
+  const body={schema:DESKTOP_MEMORY_SNAPSHOT_SCHEMA,memory};
+  const snapshotSha256=sha(body);
+  const signed={...body,snapshot_sha256:snapshotSha256};
+  const signature=cryptoSign(null,Buffer.concat([DOMAIN,Buffer.from(canonicalJson(signed),'utf8')]),privateKey).toString('base64');
+  return Object.freeze({...signed,attestation:Object.freeze({algorithm:'ed25519',key_id:keyId,signature_base64:signature})});
+}
+
+export function verifyDesktopMemorySnapshot(snapshot,{publicKey,keyId,policySha256}={}){
+  try{
+    insist(snapshot?.schema===DESKTOP_MEMORY_SNAPSHOT_SCHEMA,'desktop memory snapshot schema mismatch');
+    insist(snapshot.memory?.schema===DESKTOP_MEMORY_SCHEMA,'desktop memory payload schema mismatch');
+    insist(snapshot.memory.policy_sha256===policySha256,'desktop memory policy mismatch');
+    const {attestation,snapshot_sha256:claimed,...body}=snapshot;
+    insist(HEX64.test(claimed??'')&&sha(body)===claimed,'desktop memory snapshot hash mismatch');
+    const {memory_sha256,...memoryBody}=snapshot.memory;
+    insist(HEX64.test(memory_sha256??'')&&sha(memoryBody)===memory_sha256,'desktop memory hash mismatch');
+    insist(attestation?.algorithm==='ed25519'&&attestation.key_id===keyId,'desktop memory attestation mismatch');
+    const signature=Buffer.from(attestation.signature_base64??'','base64');
+    insist(signature.length===64,'desktop memory signature length invalid');
+    insist(cryptoVerify(null,Buffer.concat([DOMAIN,Buffer.from(canonicalJson({...body,snapshot_sha256:claimed}),'utf8')]),publicKey,signature),'desktop memory signature invalid');
+    return {ok:true,snapshot_sha256:claimed,memory_sha256};
+  }catch(error){return {ok:false,reason:String(error?.message??error)};}
+}
+
+export async function writeDesktopMemorySnapshot(file,snapshot){
+  insist(typeof file==='string'&&path.isAbsolute(file),'desktop memory path must be absolute');
+  insist(snapshot?.schema===DESKTOP_MEMORY_SNAPSHOT_SCHEMA,'desktop memory snapshot invalid');
+  await mkdir(path.dirname(file),{recursive:true});
+  const tmp=file+'.tmp';
+  await rm(tmp,{force:true});
+  const handle=await open(tmp,'wx',0o600);
+  try{await handle.writeFile(canonicalJson(snapshot)+'\n','utf8');await handle.sync();}
+  finally{await handle.close();}
+  await rename(tmp,file);
+  return Object.freeze({path:file,snapshot_sha256:snapshot.snapshot_sha256,memory_sha256:snapshot.memory.memory_sha256});
+}
+
+
+export async function loadDesktopEvidenceReceipts(evidenceDir,{
+  policySha256=null,maxReceipts=2048,maxDirectoryEntries=4096,maxReceiptBytes=512*1024,maxTotalBytes=32*1024*1024
+}={}){
+  if(policySha256!==null) insist(HEX64.test(policySha256??''),'desktop evidence policy sha invalid');
+  insist(typeof evidenceDir==='string'&&path.isAbsolute(evidenceDir),'desktop evidence directory must be absolute');
+  for(const [name,value,min,max] of [
+    ['maxReceipts',maxReceipts,1,8192],['maxDirectoryEntries',maxDirectoryEntries,1,16384],
+    ['maxReceiptBytes',maxReceiptBytes,1024,4*1024*1024],['maxTotalBytes',maxTotalBytes,1024,128*1024*1024]
+  ]) insist(Number.isInteger(value)&&value>=min&&value<=max,'desktop memory '+name+' invalid');
+  const names=[];let directoryEntries=0;
+  const dir=await opendir(evidenceDir);
+  for await(const entry of dir){
+    directoryEntries++;
+    insist(directoryEntries<=maxDirectoryEntries,'desktop evidence directory entry limit exceeded');
+    if(!entry.isFile()||!RECEIPT_FILE.test(entry.name))continue;
+    names.push(entry.name);
+    if(policySha256===null) insist(names.length<=maxReceipts,'desktop evidence receipt limit exceeded; compact/rotate evidence before continuing');
+  }
+  names.sort((a,b)=>a.localeCompare(b,'en'));
+  const receipts=[];let totalBytes=0;
+  for(const name of names){
+    const file=path.join(evidenceDir,name);
+    const handle=await open(file,'r');
+    try{
+      const st=await handle.stat();
+      insist(st.isFile()&&st.size>=2&&st.size<=maxReceiptBytes,'desktop evidence receipt size invalid: '+name);
+      totalBytes+=st.size;
+      insist(totalBytes<=maxTotalBytes,'desktop evidence total byte limit exceeded; compact/rotate evidence before continuing');
+      const bytes=await handle.readFile();
+      insist(bytes.length===st.size,'desktop evidence receipt changed while reading: '+name);
+      let parsed;try{parsed=JSON.parse(bytes.toString('utf8'));}catch{throw new Error('desktop evidence receipt JSON invalid: '+name);}
+      insist(parsed?.receipt_id===name.slice(0,24),'desktop evidence receipt filename/id mismatch: '+name);
+      if(policySha256!==null&&parsed?.policy_sha256!==policySha256) continue;
+      receipts.push(parsed);
+      insist(receipts.length<=maxReceipts,'desktop evidence receipt limit exceeded; compact/rotate evidence before continuing');
+    }finally{await handle.close();}
+  }
+  return Object.freeze(receipts);
+}
+
+export function desktopMemoryPlannerProjection(snapshot,{maxWindows=8,maxTargets=16,maxEffects=16,maxUnknown=16}={}){
+  insist(snapshot?.schema===DESKTOP_MEMORY_SNAPSHOT_SCHEMA,'desktop memory snapshot invalid');
+  const m=snapshot.memory;
+  insist(m?.schema===DESKTOP_MEMORY_SCHEMA&&HEX64.test(m.memory_sha256??''),'desktop memory payload invalid');
+  const body={
+    schema:'deadbyte.desktop-memory-planner.v1',
+    snapshot_sha256:snapshot.snapshot_sha256,memory_sha256:m.memory_sha256,policy_sha256:m.policy_sha256,
+    source_receipt_count:m.source_receipt_sha256.length,
+    last_verified_desktop:m.last_verified_desktop,
+    windows:m.windows.slice(-maxWindows),
+    grounded_targets:m.grounded_targets.slice(-maxTargets),
+    rejected_target_fingerprints:m.rejected_target_fingerprints.slice(-maxTargets),
+    recent_effects:m.recent_effects.slice(-maxEffects),
+    unresolved_unknown_effects:m.unresolved_unknown_effects.slice(-maxUnknown)
+  };
+  return Object.freeze(body);
+}
+
+export function createDesktopMemoryProvider({
+  evidenceDir,snapshotPath,policySha256,privateKey,publicKey,keyId,
+  maxReceipts=2048,maxDirectoryEntries=4096,maxReceiptBytes=512*1024,maxTotalBytes=32*1024*1024
+}={}){
+  insist(typeof evidenceDir==='string'&&path.isAbsolute(evidenceDir),'desktop memory evidenceDir invalid');
+  insist(typeof snapshotPath==='string'&&path.isAbsolute(snapshotPath),'desktop memory snapshotPath invalid');
+  insist(HEX64.test(policySha256??''),'desktop memory provider policy sha invalid');
+  insist(privateKey&&publicKey,'desktop memory provider trust keys missing');
+  insist(typeof keyId==='string'&&keyId.length>=1&&keyId.length<=128,'desktop memory provider key id invalid');
+  async function refresh(){
+    const receipts=await loadDesktopEvidenceReceipts(evidenceDir,{policySha256,maxReceipts,maxDirectoryEntries,maxReceiptBytes,maxTotalBytes});
+    const memory=deriveDesktopMemory(receipts,{policySha256,publicKey,keyId});
+    const snapshot=signDesktopMemory(memory,{privateKey,keyId});
+    const proof=verifyDesktopMemorySnapshot(snapshot,{publicKey,keyId,policySha256});
+    insist(proof.ok,'desktop memory self-verification failed: '+String(proof.reason??'unknown'));
+    const written=await writeDesktopMemorySnapshot(snapshotPath,snapshot);
+    return Object.freeze({
+      status:'ok',source_receipt_count:receipts.length,
+      snapshot_sha256:written.snapshot_sha256,memory_sha256:written.memory_sha256,
+      planner_context:desktopMemoryPlannerProjection(snapshot)
+    });
+  }
+  async function plannerContext(){return (await refresh()).planner_context;}
+  return Object.freeze({refresh,plannerContext});
+}