deadbyte-mcp 0.8.7

package/src/observation-runtime.mjs

@@ -0,0 +1,257 @@
+import { createHash, randomBytes, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { lstat, mkdir, open, readFile, readdir, realpath } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { canonicalJson } from './canonical-json.mjs';
+import { decodeUtf8Strict } from './text-policy.mjs';
+import { isInside, validatePortableRelativePath } from './path-policy.mjs';
+import { loadPrivateSigningKey, loadPublicVerifyKey } from './trust.mjs';
+
+export const OBSERVATION_RECEIPT_SCHEMA='deadbyte.observation-receipt.v1';
+const RECEIPT_DOMAIN=Buffer.from('DEADBYTE-OBSERVATION-RECEIPT-V1\0','utf8');
+const ZERO='0'.repeat(64);
+const HEX64=/^[0-9a-f]{64}$/;
+const ID=/^[A-Za-z0-9._-]{1,64}$/;
+const sha256Bytes=bytes=>createHash('sha256').update(bytes).digest('hex');
+const sha256Object=value=>sha256Bytes(Buffer.from(canonicalJson(value),'utf8'));
+const nowUtc=()=>new Date().toISOString();
+
+function denied(root,relative){
+  const value=relative.replaceAll('\\','/').replace(/^\.\//,'').toLowerCase();
+  return root.deny_paths.some(item=>value===item||value.startsWith(`${item}/`));
+}
+function rootFor(policy,rootId){
+  if(!ID.test(rootId??'')) throw new Error('invalid observation root id');
+  const root=policy.roots[rootId];
+  if(!root||root.read!==true) throw new Error(`observation root '${rootId}' is not readable`);
+  return root;
+}
+async function resolveObservationRoot(policy,rootId,relativePath){
+  const root=rootFor(policy,rootId);
+  let resolved=root.real_path;
+  let reported='.';
+  if(relativePath!=='.'){
+    validatePortableRelativePath(relativePath);
+    if(denied(root,relativePath)) throw new Error(`observation path '${relativePath}' is denied by policy`);
+    const lexical=path.resolve(root.real_path,relativePath);
+    if(!isInside(root.real_path,lexical)) throw new Error('observation path escapes root');
+    resolved=await realpath(lexical);
+    if(!isInside(root.real_path,resolved)) throw new Error('observation symlink escapes root');
+    reported=relativePath.replaceAll('\\','/');
+  }
+  const info=await lstat(resolved);
+  if(!info.isDirectory()) throw new Error('observation search path must be a directory');
+  return {root,resolved,reported};
+}
+function encodeCursor(value){ return Buffer.from(JSON.stringify(value),'utf8').toString('base64url'); }
+function decodeCursor(value){
+  try { return JSON.parse(Buffer.from(String(value),'base64url').toString('utf8')); }
+  catch { throw new Error('invalid observation cursor'); }
+}
+async function writeReceipt(runtime,kind,requestSha,resultHead,summary){
+  const receiptId=randomBytes(12).toString('hex');
+  const body={schema:OBSERVATION_RECEIPT_SCHEMA,receipt_id:receiptId,kind,
+    policy_sha256:runtime.policy.policy_sha256,request_sha256:requestSha,result_head_sha256:resultHead,
+    observed_at_utc:nowUtc(),summary};
+  const receiptSha256=sha256Object(body);
+  const signed={...body,receipt_sha256:receiptSha256};
+  const signing=await runtime.signing();
+  const bytes=Buffer.from(canonicalJson(signed),'utf8');
+  const signature=cryptoSign(null,Buffer.concat([RECEIPT_DOMAIN,bytes]),signing.privateKey).toString('base64');
+  const receipt={...signed,attestation:{algorithm:'ed25519',key_id:signing.keyId,signature_base64:signature}};
+  const dir=path.join(runtime.policy.evidence_dir,'observation');
+  await mkdir(dir,{recursive:true});
+  const file=path.join(dir,`${receiptId}.json`);
+  const handle=await open(file,'wx',0o600);
+  try { await handle.writeFile(`${canonicalJson(receipt)}\n`); await handle.sync(); }
+  finally { await handle.close(); }
+  return {receipt_id:receiptId,receipt_sha256:receiptSha256};
+}
+
+export async function verifyObservationReceiptFile({policy,verifyKeyPath,receiptId}){
+  try {
+    if(!/^[0-9a-f]{24}$/.test(receiptId??'')) return {ok:false,reason:'invalid receipt id'};
+    const receipt=JSON.parse(decodeUtf8Strict(await readFile(path.join(policy.evidence_dir,'observation',`${receiptId}.json`))));
+    if(receipt.schema!==OBSERVATION_RECEIPT_SCHEMA||receipt.receipt_id!==receiptId||receipt.policy_sha256!==policy.policy_sha256) return {ok:false,reason:'receipt identity mismatch'};
+    const {attestation,receipt_sha256:claimed,...body}=receipt;
+    if(!HEX64.test(claimed??'')||sha256Object(body)!==claimed) return {ok:false,reason:'receipt hash mismatch'};
+    const verify=await loadPublicVerifyKey(verifyKeyPath);
+    if(attestation?.algorithm!=='ed25519'||attestation?.key_id!==verify.keyId) return {ok:false,reason:'receipt attestation mismatch'};
+    const signedBytes=Buffer.from(canonicalJson({...body,receipt_sha256:claimed}),'utf8');
+    const sig=Buffer.from(attestation.signature_base64??'','base64');
+    if(sig.length!==64||!cryptoVerify(null,Buffer.concat([RECEIPT_DOMAIN,signedBytes]),verify.publicKey,sig)) return {ok:false,reason:'receipt signature mismatch'};
+    return {ok:true,signature_valid:true,receipt_sha256:claimed,request_sha256:receipt.request_sha256,result_head_sha256:receipt.result_head_sha256,kind:receipt.kind};
+  } catch { return {ok:false,reason:'receipt missing or unreadable'}; }
+}
+function defaultProcessSnapshotProvider(){
+  if(process.platform!=='win32') return [];
+  const exe=path.join(process.env.SystemRoot||'C:\\Windows','System32','WindowsPowerShell','v1.0','powershell.exe');
+  const command="Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name,ExecutablePath,CommandLine | ConvertTo-Json -Compress";
+  const result=spawnSync(exe,['-NoLogo','-NoProfile','-Command',command],{encoding:'utf8',windowsHide:true,timeout:15000,maxBuffer:8*1024*1024});
+  if(result.status!==0) throw new Error(`process observation failed: ${result.stderr||result.stdout}`);
+  const text=(result.stdout??'').trim(); if(!text) return [];
+  const parsed=JSON.parse(text); const rows=Array.isArray(parsed)?parsed:[parsed];
+  return rows.map(item=>({pid:Number(item.ProcessId),parent_pid:Number(item.ParentProcessId),name:String(item.Name??''),
+    executable_path:typeof item.ExecutablePath==='string'?item.ExecutablePath:null,
+    command_line:typeof item.CommandLine==='string'?item.CommandLine:null}));
+}
+async function defaultOwnedRuntimePidProvider(stateRoot){
+  const pids=new Set([process.pid]);
+  for(const name of ['bridge','cloud']){
+    try {
+      const value=JSON.parse(await readFile(path.join(stateRoot,'runtime',`${name}.instance.json`),'utf8'));
+      if(Number.isInteger(Number(value.pid))) pids.add(Number(value.pid));
+    } catch {}
+  }
+  return pids;
+}
+function defaultSystemSnapshotProvider(){
+  return {hostname:os.hostname(),platform:process.platform,architecture:process.arch,uptime_seconds:Math.floor(os.uptime()),
+    total_memory_bytes:os.totalmem(),free_memory_bytes:os.freemem(),cpu_count:os.cpus().length,load_average:os.loadavg().map(Number)};
+}
+function requestSha(policy,operation,args){
+  return sha256Object({schema:'deadbyte.observation-request.v1',policy_sha256:policy.policy_sha256,operation,args});
+}
+export function createObservationRuntime({policy,signingKeyPath,verifyKeyPath,processRuntime=null,stateRoot=path.join(os.homedir(),'.deadbyte-mcp'),
+  processSnapshotProvider=defaultProcessSnapshotProvider,systemSnapshotProvider=defaultSystemSnapshotProvider,
+  ownedRuntimePidProvider=defaultOwnedRuntimePidProvider}={}){
+  if(!policy||!signingKeyPath||!verifyKeyPath) throw new Error('observation runtime requires policy and trust keys');
+  const searches=new Map(),snapshots=new Map();
+  let signingPromise=null;
+  const runtime={policy,signing:()=>signingPromise??=(loadPrivateSigningKey(signingKeyPath))};
+  function searchFor(searchId){
+    if(!HEX64.test(searchId??'')) throw new Error('invalid search id');
+    const session=searches.get(searchId); if(!session) throw new Error(`unknown search '${searchId}'`); return session;
+  }
+  async function finalizeSearch(session,state,error=null){
+    session.error=error?String(error):null;
+    const receipt=await writeReceipt(runtime,'machine_search',session.request_sha256,session.result_head_sha256,{
+      search_id:session.search_id,state,result_count:session.results.length,files_scanned:session.files_scanned,
+      bytes_scanned:session.bytes_scanned,truncated:session.truncated,error:session.error
+    });
+    session.receipt_id=receipt.receipt_id; session.receipt_sha256=receipt.receipt_sha256;
+    session.state=state;
+  }
+  async function executeSearch(session){
+    if(session.cancel_requested){ await finalizeSearch(session,'cancelled'); return; }
+    session.state='running';
+    try {
+      const start=await resolveObservationRoot(policy,session.root_id,session.path);
+      const files=[]; const queue=[{dir:start.resolved,rel:start.reported==='.'?'':start.reported}];
+      while(queue.length&&files.length<session.max_files&&!session.cancel_requested){
+        const current=queue.shift(); const children=await readdir(current.dir,{withFileTypes:true});
+        children.sort((a,b)=>a.name.localeCompare(b.name));
+        for(const child of children){
+          const rel=current.rel?`${current.rel}/${child.name}`:child.name;
+          if(denied(start.root,rel)) continue;
+          const full=path.join(current.dir,child.name); const info=await lstat(full);
+          if(info.isSymbolicLink()) continue;
+          if(info.isDirectory()) queue.push({dir:full,rel});
+          else if(info.isFile()){ files.push({path:rel,full,bytes:info.size}); if(files.length>=session.max_files) break; }
+        }
+      }
+      files.sort((a,b)=>a.path.localeCompare(b.path));
+      if(queue.length) session.truncated=true;
+      const needle=session.case_sensitive?session.pattern:session.pattern.toLowerCase();
+      for(const file of files){
+        if(session.cancel_requested) break;
+        if(file.bytes>session.max_file_bytes) continue;
+        if(session.bytes_scanned+file.bytes>session.max_bytes){ session.truncated=true; break; }
+        const bytes=await readFile(file.full); let text;
+        try { text=decodeUtf8Strict(bytes); } catch { continue; }
+        session.files_scanned++; session.bytes_scanned+=bytes.length;
+        const lines=text.split(/\r?\n/);
+        for(let i=0;i<lines.length;i++){
+          const hay=session.case_sensitive?lines[i]:lines[i].toLowerCase(); const index=hay.indexOf(needle);
+          if(index<0) continue;
+          const result={path:file.path,line:i+1,column:index+1,preview:lines[i].slice(Math.max(0,index-40),index+Math.min(200,session.pattern.length+120))};
+          session.results.push(result); session.result_head_sha256=sha256Object({previous_result_sha256:session.result_head_sha256,result});
+          if(session.results.length>=session.max_results){ session.truncated=true; break; }
+        }
+        if(session.results.length>=session.max_results) break;
+        await new Promise(resolve=>setImmediate(resolve));
+      }
+      await finalizeSearch(session,session.cancel_requested?'cancelled':'completed');
+    } catch(error){ await finalizeSearch(session,'failed',error); }
+  }
+  async function searchStart({rootId,relativePath='.',pattern,caseSensitive=false,maxResults=200,maxFiles=2000,maxBytes=4*1024*1024,maxFileBytes=262144}){
+    if(typeof pattern!=='string'||pattern.length<1||pattern.length>256) throw new Error('search pattern must be 1-256 characters');
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>1000) throw new Error('max_results must be in [1,1000]');
+    if(!Number.isInteger(maxFiles)||maxFiles<1||maxFiles>10000) throw new Error('max_files must be in [1,10000]');
+    if(!Number.isInteger(maxBytes)||maxBytes<1||maxBytes>64*1024*1024) throw new Error('max_bytes out of range');
+    if(!Number.isInteger(maxFileBytes)||maxFileBytes<1||maxFileBytes>4*1024*1024) throw new Error('max_file_bytes out of range');
+    rootFor(policy,rootId); if(relativePath!=='.') validatePortableRelativePath(relativePath);
+    const args={root_id:rootId,path:relativePath,pattern,case_sensitive:caseSensitive,max_results:maxResults,max_files:maxFiles,max_bytes:maxBytes,max_file_bytes:maxFileBytes};
+    const session={search_id:randomBytes(32).toString('hex'),root_id:rootId,path:relativePath,pattern,case_sensitive:caseSensitive,
+      max_results:maxResults,max_files:maxFiles,max_bytes:maxBytes,max_file_bytes:maxFileBytes,state:'pending',cancel_requested:false,
+      results:[],files_scanned:0,bytes_scanned:0,truncated:false,result_head_sha256:ZERO,error:null,receipt_id:null,receipt_sha256:null,
+      request_sha256:requestSha(policy,'machine_search_start',args)};
+    searches.set(session.search_id,session); setImmediate(()=>{ void executeSearch(session); });
+    return {status:'accepted',search_id:session.search_id,state:session.state,request_sha256:session.request_sha256};
+  }
+  async function searchStatus({searchId}){
+    const s=searchFor(searchId); return {status:'ok',search_id:s.search_id,state:s.state,result_count:s.results.length,files_scanned:s.files_scanned,
+      bytes_scanned:s.bytes_scanned,truncated:s.truncated,request_sha256:s.request_sha256,result_head_sha256:s.result_head_sha256,
+      receipt_id:s.receipt_id,receipt_sha256:s.receipt_sha256,error:s.error};
+  }
+  async function searchCancel({searchId}){
+    const s=searchFor(searchId); const terminal=['completed','cancelled','failed'].includes(s.state);
+    if(!terminal) s.cancel_requested=true;
+    return {status:'ok',search_id:s.search_id,state:s.state,cancel_requested:!terminal};
+  }
+  async function searchPage({searchId,limit=100,cursor=null}){
+    const s=searchFor(searchId);
+    if(!Number.isInteger(limit)||limit<1||limit>500) throw new Error('search page limit must be in [1,500]');
+    let index=0;
+    if(cursor!==null){ const parsed=decodeCursor(cursor); if(parsed.search_id!==searchId||!Number.isInteger(parsed.index)||parsed.index<0) throw new Error('search cursor mismatch'); index=parsed.index; }
+    const results=s.results.slice(index,index+limit); const next=index+results.length<s.results.length?encodeCursor({search_id:searchId,index:index+results.length}):null;
+    return {status:'ok',search_id:s.search_id,state:s.state,results,next_cursor:next,result_head_sha256:s.result_head_sha256,
+      request_sha256:s.request_sha256,receipt_id:s.receipt_id,receipt_sha256:s.receipt_sha256};
+  }
+  async function captureProcessSnapshot(includeExternal){
+    const observedAt=nowUtc(); const rows=await processSnapshotProvider();
+    if(!Array.isArray(rows)||rows.length>8192) throw new Error('process observation snapshot exceeds bounds');
+    const sessionPids=new Set();
+    if(processRuntime){ const listed=await processRuntime.list(); for(const item of listed.sessions??[]) if(Number.isInteger(item.child_pid)) sessionPids.add(item.child_pid); }
+    const runtimePids=await ownedRuntimePidProvider(stateRoot);
+    const processes=rows.filter(item=>Number.isInteger(item.pid)&&item.pid>0).map(item=>{
+      const ownership=sessionPids.has(item.pid)?'deadbyte-session':runtimePids.has(item.pid)?'deadbyte-runtime':'external';
+      if(ownership==='external'&&!includeExternal) return null;
+      return {pid:item.pid,parent_pid:Number.isInteger(item.parent_pid)?item.parent_pid:0,name:String(item.name??'').slice(0,260),ownership,
+        executable_path:ownership==='external'?null:(typeof item.executable_path==='string'?item.executable_path.slice(0,2048):null),
+        command_line:ownership==='external'?null:(typeof item.command_line==='string'?item.command_line.slice(0,4096):null)};
+    }).filter(Boolean).sort((a,b)=>a.pid-b.pid||a.name.localeCompare(b.name));
+    const snapshotId=randomBytes(32).toString('hex'); let head=ZERO;
+    for(const item of processes) head=sha256Object({previous_result_sha256:head,result:item});
+    const req=requestSha(policy,'machine_process_list',{include_external:includeExternal,snapshot_id:snapshotId});
+    const receipt=await writeReceipt(runtime,'machine_process_list',req,head,{snapshot_id:snapshotId,process_count:processes.length,observed_at_utc:observedAt});
+    const snap={snapshot_id:snapshotId,observed_at_utc:observedAt,processes,request_sha256:req,result_head_sha256:head,...receipt};
+    snapshots.set(snapshotId,snap); while(snapshots.size>16) snapshots.delete(snapshots.keys().next().value);
+    return snap;
+  }
+  async function processList({limit=100,includeExternal=false,cursor=null}={}){
+    if(!Number.isInteger(limit)||limit<1||limit>256) throw new Error('process page limit must be in [1,256]');
+    let snap,index=0;
+    if(cursor===null) snap=await captureProcessSnapshot(includeExternal);
+    else {
+      const parsed=decodeCursor(cursor);
+      if(!HEX64.test(parsed.snapshot_id??'')||!Number.isInteger(parsed.index)||parsed.index<0) throw new Error('process cursor invalid');
+      snap=snapshots.get(parsed.snapshot_id); if(!snap) throw new Error('process snapshot expired'); index=parsed.index;
+    }
+    const processes=snap.processes.slice(index,index+limit);
+    const next=index+processes.length<snap.processes.length?encodeCursor({snapshot_id:snap.snapshot_id,index:index+processes.length}):null;
+    return {status:'ok',snapshot_id:snap.snapshot_id,observed_at_utc:snap.observed_at_utc,processes,next_cursor:next,
+      request_sha256:snap.request_sha256,result_head_sha256:snap.result_head_sha256,receipt_id:snap.receipt_id,receipt_sha256:snap.receipt_sha256};
+  }
+  async function systemStatus(){
+    const observedAt=nowUtc(); const snapshot=await systemSnapshotProvider();
+    const result={status:'ok',observed_at_utc:observedAt,hostname:String(snapshot.hostname),platform:String(snapshot.platform),architecture:String(snapshot.architecture),
+      uptime_seconds:Number(snapshot.uptime_seconds),total_memory_bytes:Number(snapshot.total_memory_bytes),free_memory_bytes:Number(snapshot.free_memory_bytes),
+      cpu_count:Number(snapshot.cpu_count),load_average:Array.isArray(snapshot.load_average)?snapshot.load_average.slice(0,3).map(Number):[0,0,0]};
+    const req=requestSha(policy,'machine_system_status',{}); const head=sha256Object(result);
+    const receipt=await writeReceipt(runtime,'machine_system_status',req,head,{observed_at_utc:observedAt});
+    return {...result,request_sha256:req,result_head_sha256:head,...receipt};
+  }
+  return Object.freeze({policy,searchStart,searchPage,searchStatus,searchCancel,processList,systemStatus});
+}

package/src/observation-smoke-client.mjs

@@ -0,0 +1,97 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/client/stdio';
+import { loadCodingPolicy } from './coding-plane.mjs';
+import { verifyObservationReceiptFile } from './observation-runtime.mjs';
+import { generateTrustKeypair } from './trust.mjs';
+
+const here=path.dirname(fileURLToPath(import.meta.url));
+const repoRoot=path.resolve(here,'..');
+const serverPath=path.join(repoRoot,'src','mcp-server.mjs');
+const sha=bytes=>createHash('sha256').update(bytes).digest('hex');
+const structured=(result,label)=>{
+  if(result.isError) throw new Error(`${label} error: ${JSON.stringify(result.structuredContent??result.content)}`);
+  if(!result.structuredContent||typeof result.structuredContent!=='object') throw new Error(`${label} missing structured output`);
+  return result.structuredContent;
+};
+const sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+const scratch=await mkdtemp(path.join(os.tmpdir(),'deadbyte-observation-smoke-'));
+const core=path.join(scratch,'core'),state=path.join(scratch,'state'),trust=path.join(scratch,'trust');
+await mkdir(core,{recursive:true}); await mkdir(state,{recursive:true}); await mkdir(trust,{recursive:true});
+await writeFile(path.join(core,'a.txt'),'needle alpha\n');
+await writeFile(path.join(core,'b.txt'),'beta needle\n');
+const releaseRoot=path.join(state,'release'),generationRoot=path.join(state,'generation');
+await mkdir(releaseRoot,{recursive:true}); await mkdir(generationRoot,{recursive:true});
+const releaseManifest=Buffer.from('smoke  package.json\n','utf8');
+const generationManifest=Buffer.from('smoke  controller-config.psd1\n','utf8');
+await writeFile(path.join(releaseRoot,'MANIFEST.SHA256'),releaseManifest);
+await writeFile(path.join(generationRoot,'GENERATION.SHA256'),generationManifest);
+await writeFile(path.join(generationRoot,'controller-config.psd1'),'@{}\n');
+const releaseSha=sha(releaseManifest),generationSha=sha(generationManifest);
+await writeFile(path.join(state,'active-release.json'),`${JSON.stringify({
+  schema:'deadbyte.active-release.v1',release_id:`v0.8.7-${releaseSha.slice(0,16)}`,version:'0.8.7',
+  manifest_sha256:releaseSha,release_root:releaseRoot,generation_root:generationRoot,
+  generation_manifest_sha256:generationSha,launcher_sha256:'0'.repeat(64),
+  config_path:path.join(generationRoot,'controller-config.psd1')
+},null,2)}\n`);
+const policyPath=path.join(scratch,'coding-policy.json');
+const rawPolicy={schema:'deadbyte.coding-policy.v1',enabled:true,lease_file:path.join(scratch,'missing-grant.json'),
+  evidence_dir:path.join(scratch,'evidence'),roots:{core:{path:core,read:true,write:false,exec:false,deny_paths:[]}},
+  commands:{},max_read_bytes:1048576,max_write_bytes:1048576};
+await writeFile(policyPath,`${JSON.stringify(rawPolicy,null,2)}\n`);
+const policy=await loadCodingPolicy(policyPath);
+const keys=await generateTrustKeypair({privateKeyPath:path.join(trust,'private.pem'),publicKeyPath:path.join(trust,'public.pem')});
+const client=new Client({name:'deadbyte-observation-smoke',version:'0.8.0'},
+  {versionNegotiation:{mode:{pin:'2026-07-28'}}});
+const transport=new StdioClientTransport({command:process.execPath,args:[serverPath],cwd:repoRoot,
+  env:{...getDefaultEnvironment(),DEADBYTE_MACHINE_RUNTIME:'1',DEADBYTE_CODING_RUNTIME:'1',DEADBYTE_OBSERVATION_RUNTIME:'1',
+    DEADBYTE_CODING_POLICY:policyPath,DEADBYTE_STATE_ROOT:state,DEADBYTE_SIGNING_KEY:keys.privateKeyPath,DEADBYTE_VERIFY_KEY:keys.publicKeyPath},stderr:'pipe'});
+const stderr=[]; transport.stderr?.on('data',chunk=>stderr.push(Buffer.from(chunk)));
+const base=['contained_transform','evidence_verify','file_read','proof_execute','workspace_open'];
+const machine=['machine_list','machine_ping','machine_revoke','machine_status'];
+const coding=['coding_benchmark_run','coding_command_run','coding_file_read','coding_file_write','coding_receipt_verify','coding_search',
+  'coding_session_status','coding_stat','coding_task_approve','coding_task_cancel','coding_task_events','coding_task_run','coding_task_status',
+  'coding_task_submit','coding_task_verify','coding_text_replace','coding_tree'];
+const observation=['machine_process_list','machine_search_cancel','machine_search_page','machine_search_start','machine_search_status','machine_system_status'];
+const expected=[...base,...machine,...coding,...observation].sort();
+try{
+  await client.connect(transport);
+  const listed=await client.listTools(); const names=listed.tools.map(tool=>tool.name).sort();
+  if(JSON.stringify(names)!==JSON.stringify(expected)) throw new Error(`observation smoke catalog mismatch: ${JSON.stringify(names)}`);
+  for(const tool of listed.tools) if(tool.outputSchema?.type!=='object'||tool.outputSchema?.additionalProperties!==false) throw new Error(`tool ${tool.name} missing strict output schema`);
+  const codingStatus=structured(await client.callTool({name:'coding_session_status',arguments:{}}),'coding_session_status');
+  if(codingStatus.status!=='ok'||codingStatus.armed!==false) throw new Error('observation smoke requires coding mutation authority disarmed');
+  const system=structured(await client.callTool({name:'machine_system_status',arguments:{}}),'machine_system_status');
+  if(system.status!=='ok'||!/^[0-9a-f]{24}$/.test(system.receipt_id??'')) throw new Error('system observation missing signed receipt');
+  const systemVerify=await verifyObservationReceiptFile({policy,verifyKeyPath:keys.publicKeyPath,receiptId:system.receipt_id});
+  if(!systemVerify.ok||systemVerify.signature_valid!==true||systemVerify.request_sha256!==system.request_sha256) throw new Error('system observation receipt verification failed');
+  const processes=structured(await client.callTool({name:'machine_process_list',arguments:{limit:16,include_external:false,cursor:null}}),'machine_process_list');
+  if(processes.status!=='ok'||!/^[0-9a-f]{24}$/.test(processes.receipt_id??'')) throw new Error('process observation missing signed receipt');
+  const started=structured(await client.callTool({name:'machine_search_start',arguments:{root_id:'core',path:'.',pattern:'needle',case_sensitive:true,
+    max_results:10,max_files:20,max_bytes:65536,max_file_bytes:4096}}),'machine_search_start');
+  let status=null;
+  for(let attempt=0;attempt<100;attempt++){
+    status=structured(await client.callTool({name:'machine_search_status',arguments:{search_id:started.search_id}}),'machine_search_status');
+    if(['completed','cancelled','failed'].includes(status.state)) break;
+    await sleep(20);
+  }
+  if(status?.state!=='completed'||status.result_count!==2||!/^[0-9a-f]{24}$/.test(status.receipt_id??'')) throw new Error(`search did not complete with receipt: ${JSON.stringify(status)}`);
+  const page=structured(await client.callTool({name:'machine_search_page',arguments:{search_id:started.search_id,limit:10,cursor:null}}),'machine_search_page');
+  if(page.results.map(item=>item.path).join(',')!=='a.txt,b.txt'||page.next_cursor!==null) throw new Error(`search ordering mismatch: ${JSON.stringify(page.results)}`);
+  const searchVerify=await verifyObservationReceiptFile({policy,verifyKeyPath:keys.publicKeyPath,receiptId:status.receipt_id});
+  if(!searchVerify.ok||searchVerify.signature_valid!==true||searchVerify.result_head_sha256!==status.result_head_sha256) throw new Error('search receipt verification failed');
+  console.log(JSON.stringify({status:'passed',protocol_revision:'2026-07-28',tool_count:names.length,
+    coding_armed:false,search_results:page.results.length,process_snapshot_id:processes.snapshot_id,
+    system_receipt_id:system.receipt_id,search_receipt_id:status.receipt_id,strict_output_schemas:true,
+    signature_valid:true,policy_sha256:policy.policy_sha256},null,2));
+}catch(error){
+  const detail=Buffer.concat(stderr).toString('utf8').trim(); if(detail) console.error(`server stderr:\n${detail}`);
+  console.error(error instanceof Error?error.stack:String(error)); process.exitCode=1;
+}finally{
+  await client.close().catch(()=>{});
+  await rm(scratch,{recursive:true,force:true}).catch(()=>{});
+}

package/src/operation-policy.mjs

@@ -0,0 +1,19 @@
+// Compile-time semantic resource policy. MCP callers cannot widen these values.
+export const PROOF_EXECUTION_POLICY = Object.freeze({
+  maxInputBytes: 1024 * 1024,
+  maxCaptureBytes: 1024 * 1024,
+  maxOutputBytes: (1024 * 1024) + 16,
+  timeoutMs: 5000
+});
+
+export const CONTAINED_OPERATION_POLICY = Object.freeze({
+  uppercase_ascii: Object.freeze({ maxInputBytes: 1024 * 1024, maxOutputBytes: 1024 * 1024, launcherTimeoutMs: 15000 }),
+  lowercase_ascii: Object.freeze({ maxInputBytes: 1024 * 1024, maxOutputBytes: 1024 * 1024, launcherTimeoutMs: 15000 }),
+  reverse_bytes: Object.freeze({ maxInputBytes: 1024 * 1024, maxOutputBytes: 1024 * 1024, launcherTimeoutMs: 15000 })
+});
+
+export function operationPolicy(operation) {
+  const policy = CONTAINED_OPERATION_POLICY[operation];
+  if (!policy) throw new Error('unsupported contained transform operation');
+  return policy;
+}

package/src/output-contracts.mjs

@@ -0,0 +1,252 @@
+import * as z from 'zod/v4';
+import { CONTAINED_TRANSFORM_OPERATIONS } from './contained-executor.mjs';
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const TASK_ID_RE = /^[0-9a-f]{64}$/;
+const STEP_ID_RE = /^[A-Za-z0-9._-]{1,48}$/;
+
+const hex64 = z.string().regex(HEX64_RE);
+const taskId = z.string().regex(TASK_ID_RE);
+const stepId = z.string().regex(STEP_ID_RE);
+const jsonObject = z.record(z.string(), z.json());
+const agentState = z.enum(['pending', 'running', 'paused', 'failed', 'cancelled', 'succeeded']);
+
+function requireFields(value, ctx, fields) {
+  for (const field of fields) {
+    if (value[field] === undefined) {
+      ctx.addIssue({ code: 'custom', path: [field], message: `${field} is required for this result state` });
+    }
+  }
+}
+
+function statusContract({ statuses, shape = {}, successStatuses, successRequired, errorStatuses }) {
+  return z.strictObject({ status: z.enum(statuses), error: z.string().optional(), ...shape })
+    .superRefine((value, ctx) => {
+      if (value.error !== undefined) {
+        if (!errorStatuses.includes(value.status)) ctx.addIssue({ code: 'custom', path: ['error'], message: 'error is not valid for this status' });
+        return;
+      }
+      if (errorStatuses.includes(value.status) && !successStatuses.includes(value.status)) {
+        ctx.addIssue({ code: 'custom', path: ['error'], message: 'error is required for this status' });
+        return;
+      }
+      if (successStatuses.includes(value.status)) requireFields(value, ctx, successRequired);
+    });
+}
+const agentStepSchema = z.strictObject({
+  step_id: stepId,
+  kind: z.enum(['checkpoint', 'proof_execute', 'contained_transform']),
+  state: z.enum(['pending', 'running', 'succeeded', 'waiting_approval']),
+  attempts: z.number().int().min(0),
+  result: jsonObject.nullable(),
+  error: z.string().nullable(),
+  output_path: z.string().nullable().optional(),
+  receipt_path: z.string().nullable().optional()
+});
+
+const agentDerivedShape = {
+  state: agentState,
+  reason: z.string().nullable(),
+  active_step_id: stepId.nullable(),
+  steps: z.array(agentStepSchema).max(32),
+  completed_steps: z.number().int().min(0).max(32),
+  journal_head_sha256: hex64
+};
+
+const agentAttestationSchema = z.strictObject({
+  algorithm: z.literal('ed25519'),
+  key_id: hex64,
+  signature_base64: z.string().min(1)
+});
+
+const agentEventSchema = z.strictObject({
+  schema: z.literal('deadbyte.agent-event.v1'),
+  seq: z.number().int().min(1),
+  task_id: taskId,
+  created_at_utc: z.string().min(1),
+  prev_sha256: hex64,
+  type: z.string().min(1).max(64),
+  step_id: stepId.optional(),
+  payload: jsonObject,
+  event_sha256: hex64,
+  attestation: agentAttestationSchema
+});
+export const workspaceOpenOutputSchema = statusContract({
+  statuses: ['ok', 'denied'],
+  shape: { workspace_id: z.string().min(1).max(64).optional(), workspace: z.string().min(1).optional() },
+  successStatuses: ['ok'], successRequired: ['workspace_id', 'workspace'], errorStatuses: ['denied']
+});
+
+export const fileReadOutputSchema = statusContract({
+  statuses: ['ok', 'denied'],
+  shape: { path: z.string().min(1).max(512).optional(), text: z.string().optional() },
+  successStatuses: ['ok'], successRequired: ['path', 'text'], errorStatuses: ['denied']
+});
+
+export const proofExecuteOutputSchema = statusContract({
+  statuses: ['passed', 'failed'],
+  shape: {
+    receipt_path: z.string().min(1).optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional(),
+    key_id: hex64.optional(), signature_algorithm: z.literal('ed25519').optional(), output_sha256: hex64.optional()
+  },
+  successStatuses: ['passed'],
+  successRequired: ['receipt_path', 'receipt_sha256', 'request_sha256', 'key_id', 'signature_algorithm', 'output_sha256'],
+  errorStatuses: ['failed']
+});
+
+export const containedTransformOutputSchema = statusContract({
+  statuses: ['passed', 'failed'],
+  shape: {
+    operation: z.enum(CONTAINED_TRANSFORM_OPERATIONS).optional(), output: z.string().min(1).optional(),
+    receipt_path: z.string().min(1).optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional(),
+    key_id: hex64.optional(), signature_algorithm: z.literal('ed25519').optional(), worker_id: z.string().min(1).optional(),
+    worker_sha256: hex64.optional(), output_sha256: hex64.optional(), containment: jsonObject.optional()
+  },
+  successStatuses: ['passed'],
+  successRequired: ['operation', 'output', 'receipt_path', 'receipt_sha256', 'request_sha256', 'key_id', 'signature_algorithm', 'worker_id', 'worker_sha256', 'output_sha256', 'containment'],
+  errorStatuses: ['failed']
+});
+export const evidenceVerifyOutputSchema = z.strictObject({
+  ok: z.boolean(),
+  reason: z.string().optional(),
+  receipt_id: z.string().min(1).optional(),
+  receipt_sha256: hex64.optional(),
+  key_id: hex64.optional(),
+  signature_valid: z.literal(true).optional(),
+  receipt_schema: z.enum(['deadbyte.receipt.v1', 'deadbyte.receipt.v2']).optional(),
+  request_sha256: hex64.optional(),
+  runtime_instance_nonce: hex64.optional(),
+  operation: z.enum(['proof_execute', 'contained_transform']).optional(),
+  input_sha256: hex64.optional(),
+  output_sha256: hex64.optional(),
+  containment_verified: z.literal(true).optional(),
+  active_network_denial_verified: z.boolean().optional()
+}).superRefine((value, ctx) => {
+  if (value.ok) {
+    requireFields(value, ctx, ['receipt_id', 'receipt_sha256', 'key_id', 'signature_valid', 'receipt_schema', 'operation', 'input_sha256', 'output_sha256']);
+    if (value.reason !== undefined) ctx.addIssue({ code: 'custom', path: ['reason'], message: 'reason is invalid for a successful verification' });
+  } else if (value.reason === undefined) {
+    ctx.addIssue({ code: 'custom', path: ['reason'], message: 'reason is required when ok=false' });
+  }
+});
+
+export const agentTaskSubmitOutputSchema = statusContract({
+  statuses: ['accepted', 'existing', 'failed'],
+  shape: { task_id: taskId.optional(), plan_sha256: hex64.optional(), state: agentState.optional() },
+  successStatuses: ['accepted', 'existing'], successRequired: ['task_id', 'plan_sha256', 'state'], errorStatuses: ['failed']
+});
+export const agentTaskRunOutputSchema = z.strictObject({
+  status: z.enum(['terminal', 'paused', 'completed', 'cancelled', 'failed', 'yielded', 'succeeded']),
+  error: z.string().optional(),
+  task_id: taskId.optional(),
+  ...Object.fromEntries(Object.entries(agentDerivedShape).map(([key, schema]) => [key, schema.optional()]))
+}).superRefine((value, ctx) => {
+  if (value.error !== undefined) {
+    if (value.status !== 'failed') ctx.addIssue({ code: 'custom', path: ['error'], message: 'error wrapper requires status=failed' });
+    return;
+  }
+  requireFields(value, ctx, ['task_id', ...Object.keys(agentDerivedShape)]);
+});
+
+export const agentTaskStatusOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: {
+    task_id: taskId.optional(), plan_sha256: hex64.optional(),
+    ...Object.fromEntries(Object.entries(agentDerivedShape).map(([key, schema]) => [key, schema.optional()])),
+    journal_verified: z.literal(true).optional()
+  },
+  successStatuses: ['ok'],
+  successRequired: ['task_id', 'plan_sha256', ...Object.keys(agentDerivedShape), 'journal_verified'],
+  errorStatuses: ['failed']
+});
+
+export const agentTaskEventsOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: {
+    task_id: taskId.optional(), plan_sha256: hex64.optional(), journal_verified: z.literal(true).optional(),
+    journal_head_sha256: hex64.optional(), events: z.array(agentEventSchema).max(200).optional()
+  },
+  successStatuses: ['ok'],
+  successRequired: ['task_id', 'plan_sha256', 'journal_verified', 'journal_head_sha256', 'events'],
+  errorStatuses: ['failed']
+});
+export const agentTaskCancelOutputSchema = statusContract({
+  statuses: ['terminal', 'requested', 'existing', 'failed'],
+  shape: { task_id: taskId.optional(), state: agentState.optional() },
+  successStatuses: ['terminal', 'requested', 'existing'], successRequired: ['task_id', 'state'], errorStatuses: ['failed']
+});
+
+export const agentTaskApproveOutputSchema = z.strictObject({
+  status: z.enum(['existing', 'approved', 'rejected', 'failed']),
+  error: z.string().optional(),
+  task_id: taskId.optional(), step_id: stepId.optional(),
+  ...Object.fromEntries(Object.entries(agentDerivedShape).map(([key, schema]) => [key, schema.optional()]))
+}).superRefine((value, ctx) => {
+  if (value.error !== undefined) {
+    if (value.status !== 'failed') ctx.addIssue({ code: 'custom', path: ['error'], message: 'error wrapper requires status=failed' });
+    return;
+  }
+  requireFields(value, ctx, ['task_id', 'step_id', 'state']);
+  if (value.status !== 'existing') requireFields(value, ctx, Object.keys(agentDerivedShape));
+});
+
+export const agentTaskVerifyOutputSchema = z.strictObject({
+  status: z.literal('failed').optional(), error: z.string().optional(),
+  ok: z.boolean().optional(), reason: z.string().optional(),
+  task_id: taskId.optional(), plan_sha256: hex64.optional(), task_receipt_sha256: hex64.optional(),
+  signature_valid: z.literal(true).optional(), journal_head_sha256: hex64.optional(),
+  step_receipts_verified: z.number().int().min(0).max(32).optional()
+}).superRefine((value, ctx) => {
+  if (value.status === 'failed') {
+    requireFields(value, ctx, ['error']);
+    if (value.ok !== undefined) ctx.addIssue({ code: 'custom', path: ['ok'], message: 'ok is invalid for wrapper failure' });
+    return;
+  }
+  if (value.ok === undefined) { ctx.addIssue({ code: 'custom', path: ['ok'], message: 'ok is required' }); return; }
+  if (!value.ok) { requireFields(value, ctx, ['reason']); return; }
+  requireFields(value, ctx, ['task_id', 'plan_sha256', 'task_receipt_sha256', 'signature_valid', 'journal_head_sha256', 'step_receipts_verified']);
+});
+export const hostFileReadOutputSchema = statusContract({
+  statuses: ['ok', 'denied'],
+  shape: {
+    root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
+    bytes: z.number().int().min(0).optional(), sha256: hex64.optional(),
+    encoding: z.enum(['utf8', 'base64']).optional(), content: z.string().optional()
+  },
+  successStatuses: ['ok'], successRequired: ['root_id', 'path', 'bytes', 'sha256', 'encoding', 'content'], errorStatuses: ['denied']
+});
+
+export const hostFileWriteOutputSchema = statusContract({
+  statuses: ['committed', 'denied'],
+  shape: {
+    root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
+    previous_sha256: hex64.nullable().optional(), sha256: hex64.optional(),
+    bytes: z.number().int().min(0).optional(), created: z.boolean().optional()
+  },
+  successStatuses: ['committed'], successRequired: ['root_id', 'path', 'previous_sha256', 'sha256', 'bytes', 'created'], errorStatuses: ['denied']
+});
+
+export const hostExecOutputSchema = statusContract({
+  statuses: ['passed', 'failed', 'denied'],
+  shape: {
+    root_id: z.string().min(1).max(64).optional(), command_id: z.string().min(1).max(64).optional(),
+    executable_sha256: hex64.optional(), script_sha256: hex64.optional(), exit_code: z.number().int().nullable().optional(),
+    signal: z.string().nullable().optional(), timed_out: z.boolean().optional(), timeout_ms: z.number().int().min(100).optional(),
+    stdout: z.string().optional(), stderr: z.string().optional()
+  },
+  successStatuses: ['passed', 'failed'],
+  successRequired: ['root_id', 'command_id', 'executable_sha256', 'script_sha256', 'exit_code', 'signal', 'timed_out', 'timeout_ms', 'stdout', 'stderr'],
+  errorStatuses: ['denied']
+});
+
+export function structuredToolResult(schema, object, isError = false) {
+  const parsed = schema.safeParse(object);
+  if (!parsed.success) {
+    throw new Error(`DEADBYTE output contract violation: ${z.prettifyError(parsed.error)}`);
+  }
+  return {
+    isError,
+    structuredContent: parsed.data,
+    content: [{ type: 'text', text: JSON.stringify(parsed.data) }]
+  };
+}