deadbyte-mcp 0.8.9 → 0.9.0

package/src/deadbyte-cli.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import { lstat, mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { spawn, spawnSync } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { defaultPublicKeyPath } from './trust.mjs';
 import { verifyAuditChain } from './audit-verify.mjs';
+import { openRemoteResultJournal, parseRemoteResultCursor } from './remote-result-journal.mjs';
 
 const REMOTE_COMMANDS=new Set([
   'menu','start','resume','park','stop','restart','status','url','test','fulltest','toggle','clean','machinetest',
@@ -22,15 +23,23 @@ const SESSION_STATUS=[
   ['hoststatus',/^Host plane\s*:\s*ARMED\b/m]
 ];
 const SESSION_CLEANUP=['disarmautonomous','disarmcoding','disarmprocess','disarmhost','park'];
+const SUPERVISOR_COMMANDS=Object.freeze({
+  start:'supervisorstart',stop:'supervisorstop',status:'supervisorstatus',recover:'supervisorrecover'
+});
 
 function stateRoot(){return path.resolve(process.env.DEADBYTE_STATE_ROOT||path.join(os.homedir(),'.deadbyte-mcp'));}
 async function requireRegular(file,label){const info=await lstat(file);if(!info.isFile()||info.isSymbolicLink()) throw new Error(`${label} must be a regular non-symlink file`);return file;}
 function printHelp(){
   process.stdout.write([
     'DEADBYTE MCP CLI','',
-    '  npx deadbyte-mcp@latest remote              # foreground device session',
+    '  npx deadbyte-mcp@latest mcp                 # stdio MCP server for local clients',
+    '  npx deadbyte-mcp@latest remote              # compact foreground device session',
+    '  npx deadbyte-mcp@latest remote --verbose    # detailed audit + bridge logs',
+    '  npx deadbyte-mcp@latest remote --resume <cursor> # replay missed compact results, then reconnect',
     '  npx deadbyte-mcp@latest remote status',
     '  npx deadbyte-mcp@latest remote restart',
+    '  npx deadbyte-mcp@latest supervisor status',
+    '  npx deadbyte-mcp@latest supervisor recover',
     '  npx deadbyte-mcp@latest audit verify',
     '  npx deadbyte-mcp@latest audit status',''
   ].join('\n'));
@@ -43,7 +52,7 @@ async function remoteContext(){
   const powershell=await requireRegular(path.join(systemRoot,'System32','WindowsPowerShell','v1.0','powershell.exe'),'Windows PowerShell');
   return {root,launcher,powershell};
 }
-function invokeController(ctx,command,{capture=false,allowFailure=false}={}){
+function invokeController(ctx,command,{capture=false,allowFailure=false,echoCaptured=true}={}){
   const result=spawnSync(ctx.powershell,['-NoLogo','-NoProfile','-ExecutionPolicy','Bypass','-File',ctx.launcher,command],{
     stdio:capture?['ignore','pipe','pipe']:'inherit',encoding:capture?'utf8':undefined,windowsHide:false,shell:false
   });
@@ -51,7 +60,7 @@ function invokeController(ctx,command,{capture=false,allowFailure=false}={}){
   const status=Number.isInteger(result.status)?result.status:1;
   const stdout=capture?String(result.stdout||''):'';
   const stderr=capture?String(result.stderr||''):'';
-  if(capture){if(stdout) process.stdout.write(stdout);if(stderr) process.stderr.write(stderr);}
+  if(capture&&echoCaptured){if(stdout) process.stdout.write(stdout);if(stderr) process.stderr.write(stderr);}
   if(status!==0&&!allowFailure) throw new Error(`remote controller '${command}' failed exit=${status}`);
   return {status,stdout,stderr};
 }
@@ -68,19 +77,64 @@ async function listLogFiles(root){
   }
   return files;
 }
-function formatLogLine(file,line){
+function formatLogLine(file,line,{verbose=false}={}){
   if(!line) return null;
   if(/^segment-\d{8}\.jsonl$/.test(path.basename(file))){
     try{
       const event=JSON.parse(line);
+      if(!verbose){
+        if(event.event_type!=='tool.result') return null;
+        const tool=typeof event.tool==='string'&&event.tool?event.tool:'tool';
+        return `${event.outcome?.is_error===true?'[ERR]':'[OK]'} ${tool}`;
+      }
       const seq=Number.isInteger(event.seq)?`#${event.seq}`:'#?';
       const request=typeof event.request_id==='string'?` ${event.request_id.slice(0,8)}`:'';
       const tool=typeof event.tool==='string'?` ${event.tool}`:'';
-      return `[AUDIT ${seq}] ${event.event_type||'event'}${tool}${request}`;
-    }catch{return `[AUDIT] ${line}`;}
+      let marker='';
+      if(event.event_type==='tool.request') marker='📥 ';
+      else if(event.event_type==='tool.result'){
+        if(event.outcome?.is_error===true) marker='📤❌ ';
+        else if(event.outcome?.is_error===false) marker='📤✅ ';
+        else marker='📤 ';
+      }
+      return `${marker}[AUDIT ${seq}] ${event.event_type||'event'}${tool}${request}`;
+    }catch{return verbose?`[AUDIT] ${line}`:null;}
   }
+  if(!verbose) return null;
   const label=path.basename(file).replace(/\.log$/i,'').toUpperCase();
-  return `[${label}] ${line}`;
+  let marker='';
+  if(/\[TOOL IN \]/.test(line)) marker='📥 ';
+  else if(/\[TOOL OUT\]/.test(line)){
+    if(/"is_error"\s*:\s*true/.test(line)) marker='📤❌ ';
+    else if(/"is_error"\s*:\s*false/.test(line)) marker='📤✅ ';
+    else marker='📤 ';
+  }
+  return `${marker}[${label}] ${line}`;
+}
+function remoteResultJournalPath(root,sessionId){return path.join(root,'runtime','remote-results',`${sessionId}.json`);}
+function auditTerminalResult(file,line){
+  if(!/^segment-\d{8}\.jsonl$/.test(path.basename(file))||!line) return null;
+  let event;try{event=JSON.parse(line);}catch{return null;}
+  if(event?.event_type!=='tool.result'||typeof event.request_id!=='string'||!event.request_id||typeof event.tool!=='string'||!event.tool) return null;
+  const observed=Number.isFinite(Date.parse(event.created_at_utc))?new Date(Date.parse(event.created_at_utc)).toISOString():new Date().toISOString();
+  return {request_id:event.request_id,tool:event.tool,status:event.outcome?.is_error===true?'error':'ok',observed_at_utc:observed,
+    payload_sha256:createHash('sha256').update(Buffer.from(line,'utf8')).digest('hex')};
+}
+async function replayRemoteResults(root,cursor,{verbose=false}={}){
+  const parsed=parseRemoteResultCursor(cursor);
+  const file=remoteResultJournalPath(root,parsed.session_id);
+  await requireRegular(file,'remote result journal');
+  const journal=await openRemoteResultJournal({filePath:file,sessionId:parsed.session_id,maxEntries:2048});
+  let next=cursor;
+  for(;;){
+    const page=await journal.replayAfter(next,{limit:200});
+    for(const event of page.events){
+      const marker=event.status==='error'?'[ERR]':'[OK]';
+      process.stdout.write(`${verbose?'[REPLAY] ': '[REPLAY] '}${marker} ${event.tool} [cursor r1:${event.session_id}:${event.seq}]\n`);
+    }
+    next=page.next_cursor;
+    if(!page.has_more) return next;
+  }
 }
 async function readAppend(file,offset){
   let info;try{info=await stat(file);}catch(error){if(error?.code==='ENOENT') return {offset:0,text:''};throw error;}
@@ -93,29 +147,42 @@ async function readAppend(file,offset){
   try{await handle.read(buffer,0,length,start);}finally{await handle.close();}
   return {offset:info.size,text:buffer.toString('utf8')};
 }
-async function tailRemoteLogs(root,signal){
+async function tailRemoteLogs(root,signal,{verbose=false,journal=null}={}){
   const offsets=new Map();
   for(const file of await listLogFiles(root)){
     try{offsets.set(file,(await stat(file)).size);}catch{}
   }
-  process.stdout.write('📜 [LOG] Live logs active. Press Ctrl+C to disconnect and revoke authority.\n');
+  process.stdout.write(verbose
+    ?'📜 [LOG] Live logs active. Press Ctrl+C to disconnect and revoke authority.\n'
+    :'[LOG] Live tool results. Ctrl+C disconnects and revokes authority.\n');
   while(!signal.aborted){
     for(const file of await listLogFiles(root)){
       const prior=offsets.has(file)?offsets.get(file):0;
       const next=await readAppend(file,prior);
       offsets.set(file,next.offset);
       for(const line of next.text.split(/\r?\n/)){
-        const formatted=formatLogLine(file,line);
-        if(formatted) process.stdout.write(`${formatted}\n`);
+        const terminal=auditTerminalResult(file,line);
+        let recorded=null;
+        if(terminal&&journal) recorded=await journal.recordTerminal(terminal);
+        if(recorded?.duplicate&&!verbose) continue;
+        const formatted=formatLogLine(file,line,{verbose});
+        if(!formatted) continue;
+        if(!verbose&&recorded) process.stdout.write(`${formatted} [cursor ${recorded.cursor}]\n`);
+        else process.stdout.write(`${formatted}\n`);
       }
     }
     try{await sleep(250,null,{signal});}catch(error){if(error?.name!=='AbortError') throw error;}
   }
 }
-async function cleanupRemoteSession(ctx){
+async function cleanupRemoteSession(ctx,{verbose=false}={}){
   for(const command of SESSION_CLEANUP){
-    try{invokeController(ctx,command,{allowFailure:true});}
-    catch(error){process.stderr.write(`[WARN] cleanup ${command}: ${String(error?.message||error)}\n`);}
+    try{
+      const result=invokeController(ctx,command,verbose
+        ?{allowFailure:true}
+        :{allowFailure:true,capture:true,echoCaptured:false});
+      if(result.status!==0) process.stderr.write(`⚠️ [WARN] cleanup ${command} exit=${result.status}\n`);
+    }
+    catch(error){process.stderr.write(`⚠️ [WARN] cleanup ${command}: ${String(error?.message||error)}\n`);}
   }
 }
 const GUARDIAN_SCRIPT=fileURLToPath(new URL('./remote-session-guardian.mjs',import.meta.url));
@@ -136,7 +203,8 @@ async function readRemoteSessionMarker(root){
   if(value?.schema==='deadbyte.remote-session.v2'){
     if(!Number.isInteger(value?.owner_pid)||value.owner_pid<1||
        !/^[0-9a-f]{64}$/.test(String(value?.session_nonce||''))||
-       !Number.isInteger(value?.guardian_pid)||value.guardian_pid<1) throw new Error('remote session marker schema invalid');
+       !Number.isInteger(value?.guardian_pid)||value.guardian_pid<1||
+       (value.result_session_id!==undefined&&!/^[0-9a-f]{24}$/.test(String(value.result_session_id)))) throw new Error('remote session marker schema invalid');
     return value;
   }
   throw new Error('remote session marker schema invalid');
@@ -156,14 +224,16 @@ async function recoverRemoteSession(ctx){
     }
     throw new Error(`remote session guardian cleanup still active pid=${prior.guardian_pid}`);
   }
-  process.stdout.write(`[RECOVERY] Stale remote session pid=${ownerPid}; revoking authority before restart.\n`);
+  process.stdout.write(`♻️ [RECOVERY] Stale remote session pid=${ownerPid}; revoking authority before restart.\n`);
   await cleanupRemoteSession(ctx);
   await rm(remoteSessionMarker(ctx.root),{force:true});
 }
 async function claimRemoteSession(ctx){
   const dir=path.join(ctx.root,'runtime');await mkdir(dir,{recursive:true});
   const nonce=randomBytes(32).toString('hex');
-  const marker={schema:'deadbyte.remote-session.v2',owner_pid:process.pid,guardian_pid:0,session_nonce:nonce,started_at_utc:new Date().toISOString()};
+  const resultSessionId=randomBytes(12).toString('hex');
+  const marker={schema:'deadbyte.remote-session.v2',owner_pid:process.pid,guardian_pid:0,session_nonce:nonce,
+    result_session_id:resultSessionId,started_at_utc:new Date().toISOString()};
   const markerPath=remoteSessionMarker(ctx.root);
   try{await writeFile(markerPath,`${JSON.stringify(marker)}\n`,{encoding:'utf8',flag:'wx'});}
   catch(error){if(error?.code==='EEXIST') throw new Error('remote session already claimed');throw error;}
@@ -184,14 +254,18 @@ async function claimRemoteSession(ctx){
   }
 }
 async function releaseRemoteSession(ctx,marker){
-  let current=null;try{current=await readRemoteSessionMarker(ctx.root);}catch(error){process.stderr.write(`[WARN] remote session marker cleanup: ${String(error?.message||error)}\n`);return;}
+  let current=null;try{current=await readRemoteSessionMarker(ctx.root);}catch(error){process.stderr.write(`⚠️ [WARN] remote session marker cleanup: ${String(error?.message||error)}\n`);return;}
   const same=current?.schema==='deadbyte.remote-session.v2'&&current.owner_pid===marker.owner_pid&&current.session_nonce===marker.session_nonce;
   if(same) await rm(remoteSessionMarker(ctx.root),{force:true});
 }
-async function runRemoteSession(){
+async function runRemoteSession({verbose=false,resumeCursor=null}={}){
   const ctx=await remoteContext();
+  if(resumeCursor!==null) await replayRemoteResults(ctx.root,resumeCursor,{verbose});
   await recoverRemoteSession(ctx);
   const marker=await claimRemoteSession(ctx);
+  const resultJournal=await openRemoteResultJournal({
+    filePath:remoteResultJournalPath(ctx.root,marker.result_session_id),sessionId:marker.result_session_id,maxEntries:2048
+  });
   const aborter=new AbortController();
   const abort=()=>aborter.abort();
   const watchStdin=!process.stdin.isTTY;
@@ -199,33 +273,59 @@ async function runRemoteSession(){
   if(watchStdin){process.stdin.once('end',abort);process.stdin.once('close',abort);process.stdin.resume();}
   let ready=false;
   try{
-    process.stdout.write('DEADBYTE MCP DEVICE SESSION\n');
-    process.stdout.write('[INFO] Starting local + remote runtime...\n');
-    for(const command of SESSION_START) invokeController(ctx,command);
-    process.stdout.write('[AUTHORITY] Verifying runtime planes...\n');
+    if(verbose){
+      process.stdout.write('DEADBYTE MCP DEVICE SESSION\n');
+      process.stdout.write('[INFO] Starting local + remote runtime...\n');
+      for(const command of SESSION_START) invokeController(ctx,command);
+      process.stdout.write('🛡️ [AUTHORITY] Verifying runtime planes...\n');
+    }else{
+      process.stdout.write('DEADBYTE MCP\n');
+      const started=[];
+      for(const command of SESSION_START) started.push(invokeController(ctx,command,{capture:true,echoCaptured:false}));
+      const startText=started[0]?.stdout||'';
+      const url=startText.match(/^URL\s*:\s*(\S+)/m)?.[1]||'';
+      process.stdout.write('[OK] ONLINE\n');
+      if(url) process.stdout.write(`URL: ${url}\n`);
+    }
     for(const [command,pattern] of SESSION_STATUS){
-      const result=invokeController(ctx,command,{capture:true});
+      const result=invokeController(ctx,command,{capture:true,echoCaptured:verbose});
       if(!pattern.test(result.stdout)) throw new Error(`remote session authority verification failed: ${command} did not report ARMED`);
     }
     ready=true;
-    process.stdout.write('[DEVICE] DEADBYTE MCP online; all authority planes ARMED.\n');
-    await tailRemoteLogs(ctx.root,aborter.signal);
+    if(verbose) process.stdout.write('[DEVICE] DEADBYTE MCP online; all authority planes ARMED.\n');
+    else process.stdout.write('[OK] Authority ARMED: process, coding, autonomous, host\n');
+    await tailRemoteLogs(ctx.root,aborter.signal,{verbose,journal:resultJournal});
   }finally{
     process.removeListener('SIGINT',abort);process.removeListener('SIGTERM',abort);
     if(watchStdin){process.stdin.removeListener('end',abort);process.stdin.removeListener('close',abort);process.stdin.pause();}
-    if(ready||!aborter.signal.aborted) process.stdout.write('[INFO] Closing remote device session and revoking authority...\n');
-    await cleanupRemoteSession(ctx);
+    if(ready||!aborter.signal.aborted) process.stdout.write(verbose?'[INFO] Closing remote device session and revoking authority...\n':'[INFO] Disconnecting; revoking authority...\n');
+    await cleanupRemoteSession(ctx,{verbose});
     await releaseRemoteSession(ctx,marker);
   }
 }
 async function runRemote(args){
   if(args.length===0){await runRemoteSession();return;}
-  if(args.length>1) throw new Error('remote accepts at most one controller command');
+  if(args.length===1&&args[0]==='--verbose'){await runRemoteSession({verbose:true});return;}
+  if(args.length===2&&args[0]==='--resume'){await runRemoteSession({resumeCursor:args[1]});return;}
+  if(args.length===3&&args[0]==='--verbose'&&args[1]==='--resume'){
+    await runRemoteSession({verbose:true,resumeCursor:args[2]});return;
+  }
+  if(args.length===3&&args[0]==='--resume'&&args[2]==='--verbose'){
+    await runRemoteSession({verbose:true,resumeCursor:args[1]});return;
+  }
+  if(args.length>1) throw new Error('remote accepts one controller command, --verbose, or --resume <cursor>');
   const command=args[0];if(!REMOTE_COMMANDS.has(command)) throw new Error(`unsupported remote command '${command}'`);
   const ctx=await remoteContext();
   const result=invokeController(ctx,command,{allowFailure:true});
   process.exitCode=result.status;
 }
+async function runSupervisor(args){
+  const action=args[0]||'status';
+  if(args.length>1||!Object.hasOwn(SUPERVISOR_COMMANDS,action)) throw new Error(`unsupported supervisor command '${action}'`);
+  const ctx=await remoteContext();
+  const result=invokeController(ctx,SUPERVISOR_COMMANDS[action],{allowFailure:true});
+  process.exitCode=result.status;
+}
 async function runAudit(args){
   const command=args[0]||'status';if(args.length>1) throw new Error('audit accepts one command');
   if(!['verify','status'].includes(command)) throw new Error(`unsupported audit command '${command}'`);
@@ -237,7 +337,13 @@ async function runAudit(args){
 async function main(argv){
   const [command,...rest]=argv;
   if(!command||command==='help'||command==='--help'||command==='-h'){printHelp();return;}
+  if(command==='mcp'){
+    if(rest.length) throw new Error('mcp accepts no arguments');
+    await import('./mcp-server.mjs');
+    return;
+  }
   if(command==='remote'){await runRemote(rest);return;}
+  if(command==='supervisor'){await runSupervisor(rest);return;}
   if(command==='audit'){await runAudit(rest);return;}
   throw new Error(`unknown command '${command}'`);
 }

package/src/document-adapter.mjs

@@ -0,0 +1,43 @@
+const ID=/^[A-Za-z0-9._-]{1,64}$/;
+const OP=/^[a-z][a-z0-9._-]{0,63}$/;
+const MIME=/^[A-Za-z0-9!#$&^_.+-]+\/[A-Za-z0-9!#$&^_.+-]+$/;
+function bound(value,name,min,max){if(!Number.isInteger(value)||value<min||value>max)throw new Error(`${name} must be an integer in [${min}, ${max}]`);return value;}
+function validateDescriptor(value){
+  if(!value||typeof value!=='object'||Array.isArray(value))throw new Error('document adapter must be an object');
+  if(!ID.test(value.id??''))throw new Error('document adapter id invalid');
+  if(!OP.test(value.operation??''))throw new Error('document adapter operation invalid');
+  if(!Array.isArray(value.inputMime)||value.inputMime.length<1||value.inputMime.length>16||value.inputMime.some(x=>typeof x!=='string'||!MIME.test(x)))throw new Error('document adapter inputMime invalid');
+  if(typeof value.outputMime!=='string'||!MIME.test(value.outputMime))throw new Error('document adapter outputMime invalid');
+  if(typeof value.transform!=='function')throw new Error('document adapter transform must be a function');
+  return {id:value.id,operation:value.operation,inputMime:[...new Set(value.inputMime)],outputMime:value.outputMime,transform:value.transform};
+}
+function metadataObject(value){
+  if(value===undefined)return {};
+  if(!value||typeof value!=='object'||Array.isArray(value))throw new Error('document adapter metadata must be an object');
+  JSON.stringify(value);
+  return value;
+}
+export function createDocumentAdapterRegistry({maxInputBytes=8*1024*1024,maxOutputBytes=16*1024*1024}={}){
+  bound(maxInputBytes,'maxInputBytes',1,64*1024*1024); bound(maxOutputBytes,'maxOutputBytes',1,128*1024*1024);
+  const adapters=new Map();
+  function register(value){
+    const adapter=validateDescriptor(value);
+    if(adapters.has(adapter.id))throw new Error(`document adapter '${adapter.id}' already registered`);
+    adapters.set(adapter.id,adapter);
+    return {id:adapter.id};
+  }
+  function list(){return [...adapters.values()].map(a=>({id:a.id,operation:a.operation,input_mime:[...a.inputMime],output_mime:a.outputMime})).sort((a,b)=>a.id.localeCompare(b.id));}
+  async function run({adapterId,operation,inputMime,bytes}){
+    const adapter=adapters.get(adapterId);
+    if(!adapter)throw new Error(`document adapter '${adapterId}' is not registered`);
+    if(operation!==adapter.operation)throw new Error(`document adapter operation mismatch: expected ${adapter.operation}`);
+    if(!adapter.inputMime.includes(inputMime))throw new Error(`document adapter input MIME denied: ${inputMime}`);
+    if(!Buffer.isBuffer(bytes))throw new Error('document adapter input bytes must be a Buffer');
+    if(bytes.length>maxInputBytes)throw new Error(`document adapter input exceeds ${maxInputBytes} byte limit`);
+    const result=await adapter.transform({bytes:Buffer.from(bytes),inputMime,operation});
+    if(!result||!Buffer.isBuffer(result.bytes))throw new Error('document adapter transform must return Buffer bytes');
+    if(result.bytes.length>maxOutputBytes)throw new Error(`document adapter output exceeds ${maxOutputBytes} byte limit`);
+    return {status:'ok',adapter_id:adapter.id,operation:adapter.operation,input_mime:inputMime,output_mime:adapter.outputMime,bytes:Buffer.from(result.bytes),metadata:metadataObject(result.metadata)};
+  }
+  return Object.freeze({register,list,run});
+}

package/src/lsp-stdio-client.mjs

@@ -0,0 +1,112 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const HEX64=/^[0-9a-f]{64}$/;
+const sha256File=file=>createHash('sha256').update(readFileSync(file)).digest('hex');
+const frame=value=>{const body=Buffer.from(JSON.stringify(value),'utf8');return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`,'ascii'),body]);};
+
+export function createLspStdioClient({executablePath,expectedSha256,args=[],cwd,env={},dependencies=[],requestTimeoutMs=10000,maxMessageBytes=4*1024*1024}){
+  if(typeof executablePath!=='string'||executablePath.length<1) throw new Error('LSP executable path missing');
+  if(!HEX64.test(expectedSha256??'')) throw new Error('LSP executable SHA-256 invalid');
+  const actual=sha256File(executablePath);
+  if(actual!==expectedSha256) throw new Error(`LSP executable SHA-256 mismatch: expected ${expectedSha256}, found ${actual}`);
+  if(!Array.isArray(dependencies)) throw new Error('LSP dependencies must be an array');
+  for(const dependency of dependencies){
+    if(!dependency||typeof dependency!=='object'||typeof dependency.path!=='string'||dependency.path.length<1||!HEX64.test(dependency.expectedSha256??'')) throw new Error('LSP dependency identity invalid');
+    const observed=sha256File(dependency.path);
+    if(observed!==dependency.expectedSha256) throw new Error(`LSP dependency SHA-256 mismatch: expected ${dependency.expectedSha256}, found ${observed}`);
+  }
+  if(!Array.isArray(args)||args.some(item=>typeof item!=='string')) throw new Error('LSP args must be strings');
+  if(!Number.isInteger(requestTimeoutMs)||requestTimeoutMs<1) throw new Error('LSP request timeout invalid');
+  if(!Number.isInteger(maxMessageBytes)||maxMessageBytes<256) throw new Error('LSP max message bytes invalid');
+  const child=spawn(executablePath,args,{cwd,env:{...env},stdio:['pipe','pipe','pipe'],shell:false,windowsHide:true});
+  let input=Buffer.alloc(0);
+  let nextId=1;
+  let closed=false;
+  let expectedExit=false;
+  let initialized=false;
+  let fatalError=null;
+  const pending=new Map();
+
+  const rejectAll=error=>{
+    if(!fatalError) fatalError=error;
+    for(const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(error); }
+    pending.clear();
+  };
+  const fail=error=>{
+    rejectAll(error instanceof Error?error:new Error(String(error)));
+    if(!child.killed) child.kill();
+  };
+  const dispatch=message=>{
+    if(!message||typeof message!=='object') return;
+    if(message.id===undefined||message.id===null) return;
+    const entry=pending.get(message.id);
+    if(!entry) return;
+    pending.delete(message.id); clearTimeout(entry.timer);
+    if(message.error) entry.reject(new Error(`LSP error ${message.error.code??''}: ${message.error.message??'unknown'}`));
+    else entry.resolve(message.result);
+  };
+  const drain=()=>{
+    while(input.length>0){
+      const marker=input.indexOf('\r\n\r\n');
+      if(marker<0){ if(input.length>8192) fail(new Error('LSP header exceeds 8192 bytes')); return; }
+      const header=input.subarray(0,marker).toString('ascii');
+      const match=/(?:^|\r\n)Content-Length:\s*(\d+)\s*(?:\r\n|$)/i.exec(header);
+      if(!match){ fail(new Error('LSP Content-Length header missing')); return; }
+      const size=Number(match[1]);
+      if(!Number.isSafeInteger(size)||size<0){ fail(new Error('LSP Content-Length invalid')); return; }
+      if(size>maxMessageBytes){ fail(new Error(`LSP message exceeds ${maxMessageBytes} bytes`)); return; }
+      const start=marker+4;
+      if(input.length<start+size) return;
+      const body=input.subarray(start,start+size); input=input.subarray(start+size);
+      let parsed;
+      try { parsed=JSON.parse(body.toString('utf8')); }
+      catch { fail(new Error('LSP message JSON invalid')); return; }
+      dispatch(parsed);
+    }
+  };
+  child.stdout.on('data',chunk=>{ if(closed) return; input=Buffer.concat([input,chunk]); drain(); });
+  child.on('error',error=>rejectAll(new Error(`LSP process error: ${error.message}`)));
+  child.on('exit',(code,signal)=>{
+    closed=true;
+    if(!expectedExit) rejectAll(new Error(`LSP process exited unexpectedly with code ${code===null?'null':code}${signal?` signal ${signal}`:''}`));
+    else rejectAll(new Error('LSP process closed'));
+  });
+
+  const send=value=>{
+    if(fatalError) throw fatalError;
+    if(closed||child.stdin.destroyed) throw new Error('LSP process is closed');
+    child.stdin.write(frame(value));
+  };
+  const request=(method,params=undefined)=>{
+    if(typeof method!=='string'||method.length<1) return Promise.reject(new Error('LSP request method missing'));
+    if(fatalError) return Promise.reject(fatalError);
+    const id=nextId++;
+    return new Promise((resolve,reject)=>{
+      const timer=setTimeout(()=>{pending.delete(id);reject(new Error(`LSP request timeout after ${requestTimeoutMs}ms: ${method}`));},requestTimeoutMs);
+      pending.set(id,{resolve,reject,timer,method});
+      try { const message={jsonrpc:'2.0',id,method}; if(params!==undefined) message.params=params; send(message); }
+      catch(error){clearTimeout(timer);pending.delete(id);reject(error);}
+    });
+  };
+  const notify=(method,params=undefined)=>{const message={jsonrpc:'2.0',method};if(params!==undefined)message.params=params;send(message);};
+  const initialize=async params=>{
+    const result=await request('initialize',params??{});
+    initialized=true;
+    notify('initialized',{});
+    return result;
+  };
+  const shutdown=async()=>{
+    if(expectedExit||closed) return;
+    expectedExit=true;
+    let shutdownError=null;
+    try { if(initialized) await request('shutdown'); }
+    catch(error){ shutdownError=error; }
+    try { if(!closed) notify('exit'); } catch {}
+    if(!closed) await new Promise(resolve=>{const timer=setTimeout(()=>{if(!child.killed)child.kill();resolve();},250);child.once('exit',()=>{clearTimeout(timer);resolve();});});
+    closed=true;
+    if(shutdownError) throw shutdownError;
+  };
+  return Object.freeze({initialize,notify,request,shutdown});
+}

package/src/machine-fs-smoke-client.mjs

@@ -58,8 +58,9 @@ const stderrChunks = [];
 transport.stderr?.on('data', chunk => stderrChunks.push(Buffer.from(chunk)));
 const baseTools = ['contained_transform','evidence_verify','file_read','proof_execute','workspace_open'];
 const codingTools = [
-  'coding_benchmark_run','coding_command_run','coding_file_read','coding_file_write',
+  'coding_benchmark_run','coding_command_run','coding_file_read','coding_file_write','coding_files_read',
   'coding_receipt_verify','coding_search','coding_session_status','coding_stat',
+  'coding_symbol_definition','coding_symbol_outline','coding_symbol_references','coding_symbol_replace',
   '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'
 ];

package/src/mcp-server.mjs

@@ -24,6 +24,8 @@ import { createProcessRuntime } from './process-runtime.mjs';
 import { registerProcessTools } from './process-mcp-tools.mjs';
 import { createCodingRuntime, loadCodingPolicy } from './coding-plane.mjs';
 import { createCodingTaskRuntime } from './coding-task-runtime.mjs';
+import { createSemanticCodeRuntime } from './semantic-code.mjs';
+import { loadSemanticLspBackends, semanticConfigBindingFromEnv } from './semantic-lsp-config.mjs';
 import { registerCodingTools } from './coding-mcp-tools.mjs';
 import { createMachineFsRuntime } from './machine-fs.mjs';
 import { registerMachineFsTools } from './machine-fs-mcp-tools.mjs';
@@ -36,6 +38,7 @@ import { startAutonomousSupervisor } from './autonomous-supervisor.mjs';
 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 {
   containedTransformOutputSchema,
   evidenceVerifyOutputSchema,
@@ -99,6 +102,11 @@ if (codingRuntimeMode === '1' && !codingPolicyPath) throw new Error('DEADBYTE_CO
 const codingPolicy = codingRuntimeMode === '1' ? await loadCodingPolicy(codingPolicyPath) : null;
 const codingRuntime = codingPolicy ? createCodingRuntime({ policy: codingPolicy, signingKeyPath, verifyKeyPath }) : null;
 const codingTaskRuntime = codingRuntime ? createCodingTaskRuntime({ codingRuntime, signingKeyPath, verifyKeyPath }) : null;
+const semanticLspBinding = semanticConfigBindingFromEnv(process.env);
+const semanticLsp = codingRuntime && semanticLspBinding
+  ? await loadSemanticLspBackends({ ...semanticLspBinding, codingRuntime })
+  : { backends: [], required_ids: [] };
+const semanticRuntime = codingRuntime ? createSemanticCodeRuntime({ codingRuntime, backends: semanticLsp.backends }) : null;
 const machineFsRuntimeMode = process.env.DEADBYTE_MACHINE_FS_RUNTIME ?? '0';
 if (!['0','1'].includes(machineFsRuntimeMode)) throw new Error('DEADBYTE_MACHINE_FS_RUNTIME must be 0 or 1');
 if (machineFsRuntimeMode === '1' && !codingPolicy) throw new Error('DEADBYTE_MACHINE_FS_RUNTIME=1 requires DEADBYTE_CODING_RUNTIME=1');
@@ -116,6 +124,10 @@ const observationRuntime = observationRuntimeMode === '1'
 
 const autonomousRuntimeMode = process.env.DEADBYTE_AUTONOMOUS_RUNTIME ?? '0';
 if (!['0','1'].includes(autonomousRuntimeMode)) throw new Error('DEADBYTE_AUTONOMOUS_RUNTIME must be 0 or 1');
+const autonomousSupervisorMode = process.env.DEADBYTE_AUTONOMOUS_SUPERVISOR_MODE ?? 'in_process';
+if (!['in_process','external'].includes(autonomousSupervisorMode)) {
+  throw new Error('DEADBYTE_AUTONOMOUS_SUPERVISOR_MODE must be in_process or external');
+}
 if (autonomousRuntimeMode === '1' && !codingRuntime) throw new Error('DEADBYTE_AUTONOMOUS_RUNTIME=1 requires DEADBYTE_CODING_RUNTIME=1');
 const localAutonomousPolicyPath = path.join(packageRoot,'controller','deadbyte-autonomous-policy.json');
 let autonomousPolicyPath = process.env.DEADBYTE_AUTONOMOUS_POLICY ?? '';
@@ -128,7 +140,8 @@ const autonomousPolicy = autonomousRuntimeMode === '1' ? await loadAutonomousPol
 const nativeDiffRuntime = autonomousPolicy ? createNativeDiffRuntime({ policy:autonomousPolicy,codingRuntime,signingKeyPath,verifyKeyPath }) : null;
 const autonomousRuntime = autonomousPolicy ? createAutonomousRuntime({ policy:autonomousPolicy,codingRuntime,nativeDiffRuntime,
   machineFsRuntime,observationRuntime,processRuntime,signingKeyPath,verifyKeyPath }) : null;
-const autonomousSupervisor = autonomousRuntime && autonomousPolicy.planner.backend === 'openai_compatible'
+const autonomousSupervisor = autonomousRuntime && autonomousPolicy.planner.backend === 'openai_compatible' &&
+  autonomousSupervisorMode === 'in_process'
   ? startAutonomousSupervisor({ runtime: autonomousRuntime, policy: autonomousPolicy })
   : null;
 void autonomousSupervisor;
@@ -158,6 +171,7 @@ function textResult(schema, object, isError = false) {
 
 serveStdio(() => {
   const server = new McpServer({ name: 'deadbyte-mcp', version: DEADBYTE_VERSION });
+  registerOperatorSurface(server,{packageRoot});
   if (toolAudit) installToolAudit(server,toolAudit);
 
   server.registerTool(
@@ -313,8 +327,8 @@ serveStdio(() => {
     registerProcessTools(server, { runtime: processRuntime });
   }
 
-  if (codingRuntime && codingTaskRuntime) {
-    registerCodingTools(server, { codingRuntime, taskRuntime: codingTaskRuntime });
+  if (codingRuntime && codingTaskRuntime && semanticRuntime) {
+    registerCodingTools(server, { codingRuntime, taskRuntime: codingTaskRuntime, semanticRuntime });
   }
 
   if (machineFsRuntime) {

package/src/observation-smoke-client.mjs

@@ -53,8 +53,9 @@ const transport=new StdioClientTransport({command:process.execPath,args:[serverP
 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',
+const coding=['coding_benchmark_run','coding_command_run','coding_file_read','coding_file_write','coding_files_read','coding_receipt_verify','coding_search',
+  'coding_session_status','coding_stat','coding_symbol_definition','coding_symbol_outline','coding_symbol_references','coding_symbol_replace',
+  '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();

package/src/operator-surface.mjs

@@ -0,0 +1,37 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import * as z from 'zod/v4';
+
+function userMessage(text){return {messages:[{role:'user',content:{type:'text',text}}]};}
+function workflow(goal,verb){
+  return [
+    `${verb}: ${goal}`,
+    'Read deadbyte://context only if domain vocabulary or invariants are needed.',
+    'Inspect the smallest relevant source/evidence slice; prefer semantic navigation or bounded search over whole-repo reads.',
+    'State the acceptance condition, reproduce the current behavior, then make one surgical change.',
+    'Verify with the narrow test first, then relevant regression gates. If a tool fails, change the hypothesis instead of retrying blindly.',
+    'Report observed outcome and remaining blockers; never call a claim verified without evidence.'
+  ].join('\n');
+}
+
+export function registerOperatorSurface(server,{packageRoot}){
+  if(!server||!packageRoot) throw new Error('operator surface requires server and packageRoot');
+  const contextPath=path.join(packageRoot,'CONTEXT.md');
+  const architecturePath=path.join(packageRoot,'docs','ADR-0001-PRODUCTION-BASELINE-SEAMS.md');
+  const argSchema=z.strictObject({goal:z.string().min(1).max(2000)});
+  for(const [name,title,verb] of [
+    ['deadbyte.review','Review','Review the requested code or change'],
+    ['deadbyte.patch','Patch','Patch the requested behavior'],
+    ['deadbyte.diagnose','Diagnose','Diagnose the reported failure'],
+    ['deadbyte.run-tests','Run tests','Verify the requested behavior with tests']
+  ]){
+    server.registerPrompt(name,{title,description:`Compact DEADBYTE ${title.toLowerCase()} workflow with evidence-first verification.`,argsSchema:argSchema},
+      async ({goal})=>userMessage(workflow(goal,verb)));
+  }
+  server.registerResource('deadbyte-context','deadbyte://context',{
+    title:'DEADBYTE MCP Context',description:'Canonical production vocabulary, context discipline, and Final-baseline invariants.',mimeType:'text/markdown'
+  },async uri=>({contents:[{uri:uri.href,mimeType:'text/markdown',text:await readFile(contextPath,'utf8')}]}));
+  server.registerResource('deadbyte-architecture','deadbyte://architecture',{
+    title:'DEADBYTE MCP Architecture',description:'Production module seams, tracer bullet, policy, telemetry, semantic and remote decisions.',mimeType:'text/markdown'
+  },async uri=>({contents:[{uri:uri.href,mimeType:'text/markdown',text:await readFile(architecturePath,'utf8')}]}));
+}