deadbyte-mcp 0.15.14 → 0.15.16

package/src/mcp-server.mjs

@@ -51,6 +51,11 @@ import { registerAutonomousTools } from './autonomous-mcp-tools.mjs';
 import { createToolAudit, installToolAudit } from './tool-audit.mjs';
 import { createAuditContextProvider } from './audit-context.mjs';
 import { registerOperatorSurface } from './operator-surface.mjs';
+import { createCommanderExtendedRuntime } from './commander-extended-runtime.mjs';
+import { registerCommanderCoreBridge } from './commander-core-bridge.mjs';
+import { registerCommanderRemoteBridge } from './commander-remote-bridge-r47.mjs';
+import { createCommanderRemoteRelayR47 } from './commander-remote-relay-r47.mjs';
+import { createRemoteDevicePlaneR44 } from './remote-device-r44.mjs';
 import { capabilityProfileFromEnv, COMPACT_SURFACE_TOOL_LIMIT, R36_CAPABILITY_LEDGER } from './capability-ledger.mjs';
 import { registerCompactGatewayTools } from './compact-gateway-mcp-tools.mjs';
 import { createSkillPlane } from './skill-plane-r44.mjs';
@@ -238,6 +243,17 @@ const skillRoot=path.join(runtimeStateRoot,'skills');
 await mkdir(skillRoot,{recursive:true});
 const skillRuntime=await createSkillPlane({root:skillRoot,verifyKeyPath});
 
+const remoteRelayEndpoint=process.env.DEADBYTE_REMOTE_RELAY_ENDPOINT||process.env.DEADBYTE_REMOTE_ENDPOINT||'';
+const remoteRelayCapabilities=new Set(String(process.env.DEADBYTE_REMOTE_CAPABILITIES||'').split(',').map(value=>value.trim()).filter(Boolean));
+const remoteRelay=remoteRelayEndpoint ? await createCommanderRemoteRelayR47({endpoint:remoteRelayEndpoint}) : null;
+const remoteDevicePlane=remoteRelay
+  ? await createRemoteDevicePlaneR44({
+      stateDir:path.join(runtimeStateRoot,'remote-device-r44'),
+      relay:remoteRelay,
+      authorizeCapability:async({capabilityId})=>remoteRelayCapabilities.has(capabilityId)
+    })
+  : null;
+
 installStdioConsoleGuard();
 if (process.env.DEADBYTE_STDIO_CONSOLE_GUARD_PROBE === '1') console.log('DEADBYTE_STDIO_CONSOLE_GUARD_PROBE');
 
@@ -276,9 +292,83 @@ serveStdio(() => {
     return server.registerTool(name,...args);
   }};
   registerOperatorSurface(server,{packageRoot,surfaceProfile,compactToolLimit:COMPACT_SURFACE_TOOL_LIMIT});
+  const commanderExtendedRuntime=createCommanderExtendedRuntime({
+    stateRoot:runtimeStateRoot,
+    history:null,
+    prompts:[
+      {name:'deadbyte.review',title:'Review'},
+      {name:'deadbyte.patch',title:'Patch'},
+      {name:'deadbyte.diagnose',title:'Diagnose'},
+      {name:'deadbyte.run-tests',title:'Run tests'}
+    ],
+    resources:[
+      {uri:'deadbyte://context',mime_type:'text/markdown'},
+      {uri:'deadbyte://architecture',mime_type:'text/markdown'},
+      {uri:'deadbyte://surface-profile',mime_type:'application/json'}
+    ]
+  });
   if (toolAudit) installToolAudit(server,toolAudit);
 
   if (surfaceProfile === 'full') {
+  toolServer.registerTool('get_config',{
+    description:'Read bounded DEADBYTE Commander-compatible configuration.',
+    inputSchema:z.strictObject({key:z.string().min(1).max(128).nullable().default(null)})
+  },async args=>commanderExtendedRuntime.getConfig(args));
+
+  toolServer.registerTool('set_config_value',{
+    description:'Atomically update one bounded configuration scalar with an exact hash precondition.',
+    inputSchema:z.strictObject({key:z.string().min(1).max(128),value:z.union([z.string().max(16384),z.number(),z.boolean(),z.null()]),expected_sha256:z.string().regex(/^[0-9a-f]{64}$/)})
+  },async args=>commanderExtendedRuntime.setConfigValue(args));
+
+  toolServer.registerTool('give_feedback_to_desktop_commander',{
+    description:'Persist bounded operator feedback locally; no external network transmission.',
+    inputSchema:z.strictObject({message:z.string().min(1).max(4096),category:z.string().min(1).max(64).default('general')})
+  },async args=>commanderExtendedRuntime.feedback(args));
+
+  toolServer.registerTool('get_prompts',{
+    description:'Return the bounded native prompt catalog.',
+    inputSchema:z.strictObject({})
+  },async()=>commanderExtendedRuntime.getPrompts());
+
+  toolServer.registerTool('resources',{
+    description:'Return the bounded native resource catalog.',
+    inputSchema:z.strictObject({})
+  },async()=>commanderExtendedRuntime.getResources());
+
+  toolServer.registerTool('file_preview',{
+    description:'Return a bounded preview slice from an explicitly rooted file.',
+    inputSchema:z.strictObject({root_id:z.string().min(1).max(512),path:z.string().min(1).max(512),offset:z.number().int().min(0).default(0),max_bytes:z.number().int().min(1).max(65536).default(65536),mime_type:z.string().max(128).default('text/plain')})
+  },async({root_id,path:relativePath,offset,max_bytes,mime_type})=>commanderExtendedRuntime.filePreview({rootId:root_id,path:relativePath,offset,maxBytes:max_bytes,mimeType:mime_type}));
+
+  toolServer.registerTool('write_pdf',{
+    description:'Generate a bounded self-contained PDF document from text.',
+    inputSchema:z.strictObject({text:z.string().max(65536),metadata:z.record(z.string(),z.unknown()).default({})})
+  },async args=>commanderExtendedRuntime.writePdf(args));
+
+  toolServer.registerTool('markdown_editor',{
+    description:'Hash-preconditioned bounded Markdown exact edit using the native machine filesystem transaction.',
+    inputSchema:z.strictObject({root_id:z.string().min(1).max(64),path:z.string().min(1).max(512),expected_sha256:z.string().regex(/^[0-9a-f]{64}$/),old_string:z.string().min(1).max(262144),new_string:z.string().max(524288),expected_replacements:z.number().int().min(1).max(64).default(1)})
+  },async args=>{
+    if(!machineFsRuntime) return textResult(z.any(),{status:'denied',error:'machine filesystem runtime is disabled'},true);
+    return machineFsRuntime.editExact({rootId:args.root_id,relativePath:args.path,expectedSha256:args.expected_sha256,oldString:args.old_string,newString:args.new_string,expectedReplacements:args.expected_replacements});
+  });
+
+  toolServer.registerTool('get_usage_stats',{
+    description:'Return bounded audit/runtime usage status.',
+    inputSchema:z.strictObject({})
+  },async()=>{
+    if(!toolAudit) return {status:'unavailable',reason:'audit runtime is disabled'};
+    return {status:'ok',audit:await toolAudit.status()};
+  });
+
+  toolServer.registerTool('get_recent_tool_calls',{
+    description:'Return a bounded, cursorable recent signed audit event window.',
+    inputSchema:z.strictObject({limit:z.number().int().min(1).max(256).default(50),after_seq:z.number().int().min(0).default(0)})
+  },async({limit,after_seq})=>{
+    if(!toolAudit) return {status:'unavailable',reason:'audit runtime is disabled'};
+    return {status:'ok',audit:await toolAudit.recent({limit,after_seq})};
+  });
+
   toolServer.registerTool(
     'workspace_open',
     {
@@ -589,5 +679,9 @@ serveStdio(() => {
     );
   }
 
+  if (surfaceProfile === 'full') {
+    registerCommanderCoreBridge(toolServer,{machineFsRuntime,processRuntime,searchRuntime:codingRuntime?.search??null});
+    registerCommanderRemoteBridge(toolServer,{remoteDevicePlane});
+  }
   return server;
 }, { legacy: 'reject' });

package/src/observation-output-contracts.mjs

@@ -5,7 +5,8 @@ const hex64=z.string().regex(/^[0-9a-f]{64}$/);
 const receiptId=z.string().regex(/^[0-9a-f]{24}$/);
 const searchState=z.enum(['pending','running','completed','cancelled','failed']);
 const evidenceShape={request_sha256:hex64,result_head_sha256:hex64,receipt_id:receiptId.nullable(),receipt_sha256:hex64.nullable()};
-const resultSchema=z.strictObject({path:z.string().min(1).max(512),line:z.number().int().min(1),column:z.number().int().min(1),preview:z.string().max(512)});
+const overflowSchema=z.strictObject({occurred:z.boolean(),reason:z.enum(['result_cap','byte_cap','time_limit','producer_failure']).nullable(),emitted:z.number().int().nonnegative(),dropped:z.union([z.number().int().nonnegative(),z.literal('unknown')]),resume_supported:z.boolean()});
+const resultSchema=z.strictObject({result_id:hex64,path:z.string().min(1).max(512),file_sha256:hex64,line:z.number().int().min(1),column:z.number().int().min(1),preview:z.string().max(512)});
 const processSchema=z.strictObject({pid:z.number().int().positive(),parent_pid:z.number().int().nonnegative(),name:z.string().max(260),
   ownership:z.enum(['deadbyte-runtime','deadbyte-session','external']),executable_path:z.string().max(2048).nullable(),command_line:z.string().max(4096).nullable()});
 
@@ -17,18 +18,18 @@ function statusContract(shape,successRequired=[]){
 }
 
 export const observationSearchStartOutputSchema=z.strictObject({
-  status:z.enum(['accepted','failed']),error:z.string().optional(),search_id:hex64.optional(),state:searchState.optional(),request_sha256:hex64.optional()
-}).superRefine((v,ctx)=>{if(v.status==='accepted'){for(const k of ['search_id','state','request_sha256']) if(v[k]===undefined) ctx.addIssue({code:'custom',path:[k],message:`${k} required`});} else if(!v.error) ctx.addIssue({code:'custom',path:['error'],message:'error required'});});
+  status:z.enum(['accepted','failed']),error:z.string().optional(),search_id:hex64.optional(),snapshot_id:hex64.optional(),state:searchState.optional(),request_sha256:hex64.optional()
+}).superRefine((v,ctx)=>{if(v.status==='accepted'){for(const k of ['search_id','snapshot_id','state','request_sha256']) if(v[k]===undefined) ctx.addIssue({code:'custom',path:[k],message:`${k} required`});} else if(!v.error) ctx.addIssue({code:'custom',path:['error'],message:'error required'});});
 export const observationSearchPageOutputSchema=statusContract({
-  search_id:hex64.optional(),state:searchState.optional(),results:z.array(resultSchema).max(500).optional(),next_cursor:z.string().max(512).nullable().optional(),
+  search_id:hex64.optional(),snapshot_id:hex64.optional(),state:searchState.optional(),results:z.array(resultSchema).max(500).optional(),next_cursor:z.string().max(1024).nullable().optional(),sequence:z.number().int().min(0).optional(),overflow:overflowSchema.optional(),
   ...Object.fromEntries(Object.entries(evidenceShape).map(([k,v])=>[k,v.optional()]))
-},['search_id','state','results','next_cursor','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
+},['search_id','snapshot_id','state','results','next_cursor','sequence','overflow','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
 
 export const observationSearchStatusOutputSchema=statusContract({
-  search_id:hex64.optional(),state:searchState.optional(),result_count:z.number().int().nonnegative().optional(),files_scanned:z.number().int().nonnegative().optional(),
-  bytes_scanned:z.number().int().nonnegative().optional(),truncated:z.boolean().optional(),search_error:z.string().nullable().optional(),
+  search_id:hex64.optional(),snapshot_id:hex64.optional(),state:searchState.optional(),result_count:z.number().int().nonnegative().optional(),files_scanned:z.number().int().nonnegative().optional(),
+  bytes_scanned:z.number().int().nonnegative().optional(),truncated:z.boolean().optional(),overflow:overflowSchema.optional(),search_error:z.string().nullable().optional(),
   ...Object.fromEntries(Object.entries(evidenceShape).map(([k,v])=>[k,v.optional()]))
-},['search_id','state','result_count','files_scanned','bytes_scanned','truncated','search_error','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
+},['search_id','snapshot_id','state','result_count','files_scanned','bytes_scanned','truncated','overflow','search_error','request_sha256','result_head_sha256','receipt_id','receipt_sha256']);
 
 export const observationSearchCancelOutputSchema=statusContract({
   search_id:hex64.optional(),state:searchState.optional(),cancel_requested:z.boolean().optional()

package/src/observation-runtime.mjs

@@ -51,6 +51,8 @@ function decodeCursor(value){
   try { return JSON.parse(Buffer.from(String(value),'base64url').toString('utf8')); }
   catch { throw new Error('invalid observation cursor'); }
 }
+function cursorTag(secret, body){ return sha256Bytes(Buffer.concat([secret,Buffer.from(canonicalJson(body),'utf8')])); }
+function makeStableResultId({path,fileSha256,line,column}){ return sha256Object({schema:'deadbyte.search-result.v1',path:path.replaceAll('\\\\','/'),file_sha256:fileSha256,line,column}); }
 async function writeReceipt(runtime,kind,requestSha,resultHead,summary){
   const receiptId=randomBytes(12).toString('hex');
   const body={schema:OBSERVATION_RECEIPT_SCHEMA,receipt_id:receiptId,kind,
@@ -140,6 +142,9 @@ export function createObservationRuntime({policy,signingKeyPath,verifyKeyPath,pr
   if(!Number.isInteger(maxSearchSessions)||maxSearchSessions<1||maxSearchSessions>4096) throw new Error('maxSearchSessions out of range');
   if(typeof clockMs!=='function') throw new Error('clockMs must be a function');
   const searches=new Map(),snapshots=new Map();
+  const searchCursorSecrets=new Map();
+  const SEARCH_CURSOR_SCHEMA='deadbyte.search-cursor.v1';
+  const overflowReason=Object.freeze({result_cap:'result_cap',byte_cap:'byte_cap',time_limit:'time_limit',producer_failure:'producer_failure'});
   let signingPromise=null;
   const runtime={policy,signing:()=>signingPromise??=(loadPrivateSigningKey(signingKeyPath))};
   const terminalSearchState=state=>['completed','cancelled','failed'].includes(state);
@@ -175,7 +180,7 @@ export function createObservationRuntime({policy,signingKeyPath,verifyKeyPath,pr
     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}];
+      const snapshotId=session.snapshot_id; const queue=[{dir:start.resolved,rel:start.reported==='.'?'':start.reported}]; const files=[];
       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));
@@ -189,28 +194,30 @@ export function createObservationRuntime({policy,signingKeyPath,verifyKeyPath,pr
         }
       }
       files.sort((a,b)=>a.path.localeCompare(b.path));
-      if(queue.length) session.truncated=true;
+      if(queue.length){ session.truncated=true; session.overflow={occurred:true,reason:overflowReason.result_cap,emitted:session.results.length,dropped:'unknown',resume_supported:false}; }
       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;
+        if(session.bytes_scanned+file.bytes>session.max_bytes){ session.truncated=true; session.overflow={occurred:true,reason:overflowReason.byte_cap,emitted:session.results.length,dropped:'unknown',resume_supported:false}; break; }
+        const bytes=await readFile(file.full); const fileSha256=sha256Bytes(bytes); 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))};
+          const resultBase={path:file.path,file_sha256:fileSha256,line:i+1,column:index+1,preview:lines[i].slice(Math.max(0,index-40),index+Math.min(200,session.pattern.length+120))};
+          const result={...resultBase,result_id:makeStableResultId(resultBase)};
           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){ session.truncated=true; session.overflow={occurred:true,reason:overflowReason.result_cap,emitted:session.results.length,dropped:'unknown',resume_supported:false}; break; }
         }
         if(session.results.length>=session.max_results) break;
         await new Promise(resolve=>setImmediate(resolve));
       }
+      if(session.cancel_requested){ session.overflow={occurred:session.truncated,reason:session.truncated?overflowReason.result_cap:null,emitted:session.results.length,dropped:session.truncated?'unknown':0,resume_supported:false}; }
       await finalizeSearch(session,session.cancel_requested?'cancelled':'completed');
-    } catch(error){ await finalizeSearch(session,'failed',error); }
+    } catch(error){ session.overflow={occurred:true,reason:overflowReason.producer_failure,emitted:session.results.length,dropped:'unknown',resume_supported:false}; 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');
@@ -224,14 +231,16 @@ export function createObservationRuntime({policy,signingKeyPath,verifyKeyPath,pr
     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,
-      created_at_ms:Number(clockMs()),completed_at_ms:null,request_sha256:requestSha(policy,'machine_search_start',args)};
+      snapshot_id:randomBytes(32).toString('hex'),snapshot_expires_at_ms:Number(clockMs())+searchSessionTtlMs,
+      results:[],files_scanned:0,bytes_scanned:0,truncated:false,overflow:{occurred:false,reason:null,emitted:0,dropped:0,resume_supported:true},result_head_sha256:ZERO,error:null,receipt_id:null,receipt_sha256:null,
+      created_at_ms:Number(clockMs()),completed_at_ms:null,max_ack_position:0,last_cursor:null,last_cursor_response:null,request_sha256:requestSha(policy,'machine_search_start',args)};
+    searchCursorSecrets.set(session.search_id,randomBytes(32));
     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};
+    return {status:'accepted',search_id:session.search_id,snapshot_id:session.snapshot_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,
+    const s=searchFor(searchId); return {status:'ok',search_id:s.search_id,snapshot_id:s.snapshot_id,state:s.state,result_count:s.results.length,files_scanned:s.files_scanned,
+      bytes_scanned:s.bytes_scanned,truncated:s.truncated,overflow:s.overflow,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}){
@@ -241,12 +250,33 @@ export function createObservationRuntime({policy,signingKeyPath,verifyKeyPath,pr
   }
   async function searchPage({searchId,limit=100,cursor=null}){
     const s=searchFor(searchId);
+    const now=Number(clockMs());
+    if(now>=s.snapshot_expires_at_ms) throw new Error('search snapshot expired');
     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};
+    let position=0, nextSequence=1;
+    if(cursor!==null){
+      const parsed=decodeCursor(cursor);
+      const body={schema:SEARCH_CURSOR_SCHEMA,search_id:parsed.search_id,snapshot_id:parsed.snapshot_id,next_sequence:parsed.next_sequence,position:parsed.position};
+      const secret=searchCursorSecrets.get(searchId);
+      if(!secret||parsed.search_id!==searchId||parsed.snapshot_id!==s.snapshot_id||!Number.isInteger(parsed.next_sequence)||!Number.isInteger(parsed.position)||parsed.position<0||parsed.next_sequence<1||parsed.next_sequence!==parsed.position+1||parsed.integrity!==cursorTag(secret,body)){
+        throw new Error('invalid, tampered, rewound, or mismatched search cursor');
+      }
+      position=parsed.position; nextSequence=parsed.next_sequence;
+    }
+    if(position>s.results.length) throw new Error('search cursor is ahead of producer boundary');
+    if(position<s.max_ack_position){
+      if(cursor!==null && cursor===s.last_cursor && s.last_cursor_response) return s.last_cursor_response;
+      throw new Error('rewound search cursor rejected');
+    }
+    const results=s.results.slice(position,position+limit);
+    const nextPosition=position+results.length;
+    s.max_ack_position=Math.max(s.max_ack_position,nextPosition);
+    const next=nextPosition<s.results.length ? (()=>{ const body={schema:SEARCH_CURSOR_SCHEMA,search_id:s.search_id,snapshot_id:s.snapshot_id,next_sequence:nextPosition+1,position:nextPosition}; const integrity=cursorTag(searchCursorSecrets.get(searchId),body); return encodeCursor({...body,integrity}); })() : null;
+    const response=Object.freeze({status:'ok',search_id:s.search_id,snapshot_id:s.snapshot_id,state:s.state,results,next_cursor:next,
+      sequence:nextSequence+results.length-1,overflow:s.overflow,result_head_sha256:s.result_head_sha256,
+      request_sha256:s.request_sha256,receipt_id:s.receipt_id,receipt_sha256:s.receipt_sha256});
+    if(cursor!==null) { s.last_cursor=cursor; s.last_cursor_response=response; }
+    return response;
   }
   async function captureProcessSnapshot(includeExternal){
     const observedAt=nowUtc(); const rows=await processSnapshotProvider();

package/src/operation-history.mjs

@@ -0,0 +1,95 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+const ZERO_HASH='0'.repeat(64);
+const sha256=value=>createHash('sha256').update(value).digest('hex');
+const objectHash=value=>sha256(Buffer.from(canonicalJson(value),'utf8'));
+
+export const OPERATION_HISTORY_SCHEMA='deadbyte.operation-history.v1';
+
+export function createOperationHistory({maxEvents=1024,maxBytes=1024*1024,clockMs=()=>Date.now(),operationId=randomBytes(16).toString('hex')}={}){
+  if(!Number.isInteger(maxEvents)||maxEvents<1||maxEvents>100000) throw new Error('maxEvents out of range');
+  if(!Number.isInteger(maxBytes)||maxBytes<1024||maxBytes>64*1024*1024) throw new Error('maxBytes out of range');
+  if(typeof clockMs!=='function') throw new Error('clockMs must be a function');
+  if(typeof operationId!=='string'||operationId.length<1||operationId.length>128) throw new Error('invalid operationId');
+  const events=[];
+  let bytes=0,sequence=0,head=ZERO_HASH;
+  let overflow={occurred:false,reason:null,dropped:0,dropped_bytes:0,resume_supported:true};
+
+  function append(eventType,payload={}){
+    if(typeof eventType!=='string'||eventType.length<1||eventType.length>128) throw new Error('invalid eventType');
+    const payloadDigest=objectHash(payload);
+    const body={
+      schema:OPERATION_HISTORY_SCHEMA,
+      operation_id:operationId,
+      sequence:++sequence,
+      event_type:eventType,
+      at_ms:Number(clockMs()),
+      payload_digest:payloadDigest,
+      previous_event_hash:head
+    };
+    const eventHash=objectHash(body);
+    const frozenPayload=JSON.parse(canonicalJson(payload));
+    const event=Object.freeze({...body,event_hash:eventHash,payload:Object.freeze(frozenPayload)});
+    const size=Buffer.byteLength(canonicalJson(event),'utf8');
+    if(size>maxBytes) throw new Error('operation history event exceeds byte cap');
+    while(events.length&&bytes+size>maxBytes){
+      const dropped=events.shift();
+      bytes-=dropped.__bytes;
+      overflow={occurred:true,reason:'byte_cap',dropped:overflow.dropped+1,dropped_bytes:overflow.dropped_bytes+dropped.__bytes,resume_supported:false};
+    }
+    events.push(Object.freeze({...event,__bytes:size}));
+    bytes+=size; head=eventHash;
+    if(events.length>maxEvents){
+      const dropped=events.shift();
+      bytes-=dropped.__bytes;
+      overflow={occurred:true,reason:'event_cap',dropped:overflow.dropped+1,dropped_bytes:overflow.dropped_bytes+dropped.__bytes,resume_supported:false};
+    }
+    return event;
+  }
+
+  function read({afterSequence=0,limit=100}={}){
+    if(!Number.isInteger(afterSequence)||afterSequence<0) throw new Error('invalid history cursor');
+    if(!Number.isInteger(limit)||limit<1||limit>1000) throw new Error('history limit out of range');
+    const earliest=events[0]?.sequence??sequence+1;
+    if(afterSequence<earliest-1&&events.length) throw new Error('history cursor expired by bounded retention');
+    const selected=events.filter(e=>e.sequence>afterSequence).slice(0,limit).map(({__bytes,...e})=>e);
+    return {
+      schema:OPERATION_HISTORY_SCHEMA,operation_id:operationId,events:selected,
+      next_sequence:selected.length?selected.at(-1).sequence:afterSequence,
+      head_event_hash:head,earliest_sequence:earliest,
+      overflow:Object.freeze({...overflow})
+    };
+  }
+
+  function verify(){
+    let previous=events.length&&overflow.occurred ? events[0].previous_event_hash : ZERO_HASH;
+    for(let i=0;i<events.length;i++){
+      const {event_hash,payload,__bytes,...body}=events[i];
+      if(body.operation_id!==operationId||body.sequence!==events[i].sequence||body.previous_event_hash!==previous) return {ok:false,reason:'continuity_mismatch'};
+      if(body.payload_digest!==objectHash(payload)||event_hash!==objectHash(body)) return {ok:false,reason:'event_hash_mismatch'};
+      previous=event_hash;
+    }
+    return {ok:true,head_event_hash:head,earliest_sequence:events[0]?.sequence??sequence+1,next_sequence:sequence+1,overflow:{...overflow}};
+  }
+
+  return Object.freeze({
+    operationId,
+    append,
+    read,
+    verify,
+    snapshot:()=>read({afterSequence:Math.max(0,(events[0]?.sequence??sequence+1)-1),limit:Math.min(maxEvents,1000)})
+  });
+}
+export function operationHistoryReceipt(history){
+  const verified=history.verify();
+  if(!verified.ok) throw new Error('operation history integrity verification failed');
+  return Object.freeze({
+    schema:OPERATION_HISTORY_SCHEMA,
+    operation_id:history.operationId,
+    head_event_hash:verified.head_event_hash,
+    earliest_sequence:verified.earliest_sequence,
+    next_sequence:verified.next_sequence,
+    overflow:verified.overflow
+  });
+}

package/src/operation-lifecycle.mjs

@@ -0,0 +1,63 @@
+import { randomBytes } from 'node:crypto';
+import { createOperationHistory, operationHistoryReceipt } from './operation-history.mjs';
+
+export const OPERATION_LIFECYCLE_SCHEMA='deadbyte.operation-lifecycle.v1';
+const TERMINAL=new Set(['success','failure','cancelled','timed_out']);
+const ACTIVE=new Set(['start','running','cancel_requested','canceling','output','error']);
+const ALLOWED=new Map([
+  ['start',new Set(['running','cancel_requested','output','error','success','failure','cancelled','timed_out'])],
+  ['running',new Set(['running','cancel_requested','canceling','output','error','success','failure','cancelled','timed_out'])],
+  ['cancel_requested',new Set(['canceling','cancelled','timed_out','output','error'])],
+  ['canceling',new Set(['cancelled','timed_out','output','error'])],
+  ['output',new Set(['running','cancel_requested','canceling','output','error','success','failure','cancelled','timed_out'])],
+  ['error',new Set(['running','cancel_requested','canceling','success','failure','cancelled','timed_out','error'])],
+  ['success',new Set()], ['failure',new Set()], ['cancelled',new Set()], ['timed_out',new Set()]
+]);
+
+export function createOperationLifecycle({operationId=randomBytes(32).toString('hex'),clockMs=()=>Date.now(),maxEvents=1024,maxBytes=1024*1024}={}){
+  const history=createOperationHistory({operationId,clockMs,maxEvents,maxBytes});
+  let state='new';
+  let terminalSequence=null;
+  let terminalEventHash=null;
+  let terminalType=null;
+
+  function emit(type,payload={}){
+    if(typeof type!=='string'||(!ACTIVE.has(type)&&!TERMINAL.has(type))) throw new Error('invalid lifecycle event');
+    if(terminalType) {
+      if(TERMINAL.has(type)) throw new Error('terminal transition already committed');
+      throw new Error('late operation event rejected after terminal');
+    }
+    if(type==='start' && state!=='new') throw new Error('duplicate operation start');
+    const allowed=state==='new' ? new Set(['start']) : ALLOWED.get(state);
+    if(!allowed?.has(type)) throw new Error('invalid operation transition '+state+' -> '+type);
+    const event=history.append(type,payload);
+    state=type;
+    if(TERMINAL.has(type)){ terminalSequence=event.sequence; terminalEventHash=event.event_hash; terminalType=type; }
+    return Object.freeze({schema:OPERATION_LIFECYCLE_SCHEMA,operation_id:operationId,state,event});
+  }
+
+  function terminal(type,payload={}) {
+    if(!TERMINAL.has(type)) throw new Error('terminal type required');
+    return emit(type,payload);
+  }
+
+  function snapshot(){
+    const verified=history.verify();
+    return Object.freeze({
+      schema:OPERATION_LIFECYCLE_SCHEMA,operation_id:operationId,state,
+      terminal:{type:terminalType,sequence:terminalSequence,event_hash:terminalEventHash},
+      history_head_sha256:verified.head_event_hash,
+      next_sequence:verified.next_sequence,
+      overflow:verified.overflow
+    });
+  }
+
+  function receipt(){
+    if(!terminalType) throw new Error('terminal receipt unavailable before terminal transition');
+    const h=operationHistoryReceipt(history);
+    if(h.next_sequence!==terminalSequence+1 || h.head_event_hash!==terminalEventHash) throw new Error('terminal receipt/history mismatch');
+    return Object.freeze({...h,terminal_type:terminalType,terminal_sequence:terminalSequence,terminal_event_hash:terminalEventHash});
+  }
+
+  return Object.freeze({operationId,history,emit,terminal,snapshot,receipt,isTerminal:()=>Boolean(terminalType)});
+}

package/src/process-output-contracts.mjs

@@ -4,6 +4,17 @@ import { structuredToolResult } from './output-contracts.mjs';
 const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
 const digits = z.string().regex(/^[0-9]+$/);
 const processState = z.enum(['running','exited','terminated']);
+const operationSnapshot = z.strictObject({
+  schema:z.literal('deadbyte.operation-lifecycle.v1'), operation_id:hex64,
+  state:z.string().min(1).max(32),
+  terminal:z.strictObject({type:z.enum(['success','failure','cancelled','timed_out']).nullable(),sequence:z.number().int().positive().nullable(),event_hash:hex64.nullable()}),
+  history_head_sha256:hex64,next_sequence:z.number().int().positive(),overflow:z.object({}).passthrough()
+});
+const operationReceipt = z.strictObject({
+  schema:z.literal('deadbyte.operation-terminal-receipt.v1'),operation_id:hex64,session_id:hex64,
+  terminal:z.object({}).passthrough(),root_id:z.string().min(1).max(64),policy_sha256:hex64,
+  key_id:z.string().min(1).max(128),signature:z.string().min(1).max(512)
+});
 const termination = z.strictObject({
   deadline_exceeded:z.boolean(), cancellation_requested:z.boolean(), physical_termination:z.boolean(), verified:z.boolean(),
   terminal_semantics:z.string().min(1).max(64)
@@ -11,6 +22,12 @@ const termination = z.strictObject({
 const deadline = z.strictObject({
   schema:z.literal('deadbyte.deadline.v1'), id:hex64.nullable(), created_at_ms:z.number(), timeout_ms:z.number().int().positive().nullable(), deadline_ms:z.number().nullable()
 });
+const readiness = z.strictObject({
+  state:z.enum(['running','ready_for_input','finished']),
+  evidence:z.string().min(1).max(64),
+  prompt:z.strictObject({profile:z.string().min(1).max(32),prompt:z.string().min(1).max(64)}).nullable(),
+  exit_code:z.number().int().nullable()
+});
 const streamCoverage = z.strictObject({
   logical_first_seq:z.number().int().min(1), logical_last_seq:z.number().int().min(0),
   retained_first_seq:z.number().int().min(1), retained_last_seq:z.number().int().min(0),
@@ -40,7 +57,13 @@ export const processSessionRecordSchema = z.strictObject({
   stream_coverage: streamCoverage.nullable(),
   termination: termination.nullable(),
   deadline: deadline.nullable(),
-  journal_head_sha256: hex64
+  readiness: readiness.optional().nullable(),
+  journal_head_sha256: hex64,
+  operation_id: hex64.nullable().optional(),
+  operation: operationSnapshot.nullable().optional(),
+  operation_history_head_sha256: hex64.nullable().optional(),
+  operation_receipt: operationReceipt.nullable().optional(),
+  operation_history_error: z.string().max(4096).nullable().optional()
 });
 
 function resultWithSession(okStatus = 'ok') {

package/src/process-readiness.mjs

@@ -0,0 +1,120 @@
+const PROMPTS = Object.freeze({
+  python: ['>>> ', '... '],
+  node: ['> ', '... '],
+  powershell: ['PS> ', 'PS C:\\', '>> '],
+  cmd: ['> ', 'More? '],
+  shell: ['$ ', '# ', '% '],
+  mysql: ['mysql> ', '    -> '],
+  postgres: ['=# ', '-# '],
+  redis: ['redis> ']
+});
+
+const COMPLETION = [
+  /(?:^|\n)Process finished(?:\r?\n|$)/i,
+  /(?:^|\n)Command completed(?:\r?\n|$)/i,
+  /(?:^|\n)\[Process completed\]/i,
+  /(?:^|\n)Program terminated(?:\r?\n|$)/i,
+  /(?:^|\n)Exit code:\s*-?\d+/i
+];
+
+const ERROR_TERMINAL = [
+  /^\s*SyntaxError:/m,
+  /^\s*TypeError:/m,
+  /^\s*ReferenceError:/m,
+  /^\s*NameError:/m,
+  /^\s*Traceback/m,
+  /^\s*Unhandled exception/m
+];
+
+const stripAnsi = value => String(value ?? '').replace(/\x1b\[[0-?]*[ -\/]*[@-~]/g, '');
+
+export function normalizeProcessText(value) {
+  return stripAnsi(value).replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+export function detectPrompt(text, profiles = PROMPTS) {
+  const normalized = normalizeProcessText(text);
+  const lastLine = normalized.split('\n').at(-1) ?? '';
+  for (const [profile, prompts] of Object.entries(profiles)) {
+    for (const prompt of prompts) {
+      if (lastLine.endsWith(prompt) || lastLine === prompt.trimEnd()) {
+        return { profile, prompt };
+      }
+    }
+  }
+  return null;
+}
+
+export function analyzeReadiness({stdout='', stderr='', state='running', exitCode=null} = {}) {
+  const out = normalizeProcessText(stdout);
+  const err = normalizeProcessText(stderr);
+  if (state === 'exited' || state === 'terminated') {
+    return Object.freeze({ state: 'finished', evidence: 'process_terminal', prompt: null, exit_code: exitCode });
+  }
+  const prompt = detectPrompt(out);
+  if (prompt) {
+    return Object.freeze({ state: 'ready_for_input', evidence: 'prompt', prompt, exit_code: null });
+  }
+  if (COMPLETION.some(pattern => pattern.test(out)) || ERROR_TERMINAL.some(pattern => pattern.test(err || out))) {
+    return Object.freeze({ state: 'finished', evidence: 'terminal_output', prompt: null, exit_code: exitCode });
+  }
+  if (out.length === 0 && err.length === 0) {
+    return Object.freeze({ state: 'running', evidence: 'no_output', prompt: null, exit_code: null });
+  }
+  return Object.freeze({ state: 'running', evidence: 'output_without_terminal_marker', prompt: null, exit_code: null });
+}
+
+export function lineEndingProfile(text) {
+  const value = String(text ?? '');
+  let crlf = 0, lf = 0, cr = 0;
+  for (let i = 0; i < value.length; i += 1) {
+    if (value[i] === '\r') {
+      if (value[i + 1] === '\n') { crlf += 1; i += 1; } else cr += 1;
+    } else if (value[i] === '\n') lf += 1;
+  }
+  const total = crlf + lf + cr;
+  const styles = [crlf > 0, lf > 0, cr > 0].filter(Boolean).length;
+  const style = crlf >= lf && crlf >= cr && crlf > 0 ? '\r\n' : lf > 0 ? '\n' : cr > 0 ? '\r' : null;
+  return Object.freeze({ style, crlf, lf, cr, total, mixed: styles > 1 });
+}
+
+export function normalizeLineEndings(text, target) {
+  const lf = String(text ?? '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  if (target === '\r\n') return lf.replace(/\n/g, '\r\n');
+  if (target === '\r') return lf.replace(/\n/g, '\r');
+  return lf;
+}
+
+export function createReadinessTracker({maxEvidenceBytes=16384}={}) {
+  if (!Number.isInteger(maxEvidenceBytes) || maxEvidenceBytes < 256) {
+    throw new Error('maxEvidenceBytes must be >= 256');
+  }
+  let stdout = '';
+  let stderr = '';
+  let sequence = 0;
+  let last = analyzeReadiness();
+
+  const append = (channel, chunk) => {
+    const value = normalizeProcessText(chunk);
+    if (channel === 'stderr') stderr = (stderr + value).slice(-maxEvidenceBytes);
+    else stdout = (stdout + value).slice(-maxEvidenceBytes);
+    sequence += 1;
+    last = analyzeReadiness({stdout, stderr});
+    return Object.freeze({sequence, channel, readiness: last});
+  };
+
+  const updateTerminal = (state, exitCode) => {
+    last = analyzeReadiness({stdout, stderr, state, exitCode});
+    sequence += 1;
+    return Object.freeze({sequence, readiness: last});
+  };
+
+  const snapshot = () => Object.freeze({
+    sequence,
+    readiness: last,
+    stdout_tail: stdout.slice(-2048),
+    stderr_tail: stderr.slice(-2048)
+  });
+
+  return Object.freeze({append, updateTerminal, snapshot});
+}