deadbyte-mcp 0.8.9 → 0.9.0

package/src/remote-result-journal.mjs

@@ -0,0 +1,114 @@
+import { lstat, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const REMOTE_RESULT_JOURNAL_SCHEMA='deadbyte.remote-result-journal.v1';
+const SESSION=/^[0-9a-f]{24}$/;
+const HASH=/^[0-9a-f]{64}$/;
+const STATUS=new Set(['ok','error']);
+
+function text(value,label,max){
+  if(typeof value!=='string'||value.length<1||value.length>max||value.includes('\0')) throw new Error(`${label} invalid`);
+  return value;
+}
+function iso(value,label){
+  const parsed=Date.parse(value);
+  if(typeof value!=='string'||!Number.isFinite(parsed)) throw new Error(`${label} invalid`);
+  return new Date(parsed).toISOString();
+}
+function validateSession(value){
+  if(typeof value!=='string'||!SESSION.test(value)) throw new Error('remote result session_id invalid');
+  return value;
+}
+function validateEvent(raw,index=null){
+  if(!raw||typeof raw!=='object'||Array.isArray(raw)) throw new Error('remote result event invalid');
+  const seq=raw.seq;
+  if(!Number.isSafeInteger(seq)||seq<1) throw new Error('remote result seq invalid');
+  const sessionId=validateSession(raw.session_id);
+  const requestId=text(raw.request_id,'remote result request_id',256);
+  const tool=text(raw.tool,'remote result tool',128);
+  if(!STATUS.has(raw.status)) throw new Error('remote result status invalid');
+  const observed=iso(raw.observed_at_utc,'remote result observed_at_utc');
+  if(typeof raw.payload_sha256!=='string'||!HASH.test(raw.payload_sha256)) throw new Error('remote result payload_sha256 invalid');
+  if(index!==null&&seq!==index) throw new Error('remote result sequence mismatch');
+  return Object.freeze({session_id:sessionId,seq,request_id:requestId,tool,status:raw.status,
+    observed_at_utc:observed,payload_sha256:raw.payload_sha256});
+}
+function identity(item){return `${item.request_id}\0${item.status}\0${item.payload_sha256}`;}
+export function parseRemoteResultCursor(cursor){
+  if(typeof cursor!=='string') throw new Error('remote result cursor invalid');
+  const match=/^r1:([0-9a-f]{24}):(0|[1-9][0-9]{0,15})$/.exec(cursor);
+  if(!match) throw new Error('remote result cursor invalid');
+  const seq=Number(match[2]);
+  if(!Number.isSafeInteger(seq)||seq<0) throw new Error('remote result cursor invalid');
+  return {session_id:match[1],seq};
+}
+function cursorFor(sessionId,seq){return `r1:${sessionId}:${seq}`;}
+async function requireRegularIfExists(file){
+  try{
+    const info=await lstat(file);
+    if(!info.isFile()||info.isSymbolicLink()) throw new Error('remote result journal must be regular non-symlink file');
+    return true;
+  }catch(error){if(error?.code==='ENOENT') return false;throw error;}
+}
+function validateStored(value,sessionId){
+  if(!value||typeof value!=='object'||Array.isArray(value)||value.schema!==REMOTE_RESULT_JOURNAL_SCHEMA) throw new Error('remote result journal schema invalid');
+  if(value.session_id!==sessionId) throw new Error('remote result journal session mismatch');
+  if(!Array.isArray(value.events)) throw new Error('remote result journal events invalid');
+  let prior=0;
+  const events=value.events.map(raw=>{
+    const event=validateEvent(raw);
+    if(event.session_id!==sessionId||event.seq<=prior) throw new Error('remote result journal sequence invalid');
+    prior=event.seq;return event;
+  });
+  if(!Number.isSafeInteger(value.next_seq)||value.next_seq<1||value.next_seq!==(events.at(-1)?.seq??0)+1) throw new Error('remote result journal next_seq invalid');
+  return {schema:REMOTE_RESULT_JOURNAL_SCHEMA,session_id:sessionId,next_seq:value.next_seq,events};
+}
+async function atomicWrite(file,value){
+  await mkdir(path.dirname(file),{recursive:true});
+  const temp=`${file}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+  await writeFile(temp,`${JSON.stringify(value)}\n`,{encoding:'utf8',flag:'wx'});
+  await rename(temp,file);
+}
+
+export async function openRemoteResultJournal({filePath,sessionId,maxEntries=2048}={}){
+  const file=path.resolve(text(filePath,'remote result journal path',1024));
+  const sid=validateSession(sessionId);
+  if(!Number.isInteger(maxEntries)||maxEntries<1||maxEntries>100000) throw new Error('remote result maxEntries invalid');
+  let state;
+  if(await requireRegularIfExists(file)){
+    let raw;try{raw=JSON.parse(await readFile(file,'utf8'));}catch{throw new Error('remote result journal JSON invalid');}
+    state=validateStored(raw,sid);
+  }else{
+    state={schema:REMOTE_RESULT_JOURNAL_SCHEMA,session_id:sid,next_seq:1,events:[]};
+    await atomicWrite(file,state);
+  }
+  async function persist(){
+    state.events=state.events.slice(-maxEntries);
+    await atomicWrite(file,state);
+  }
+  return Object.freeze({
+    file_path:file,session_id:sid,
+    cursor(){return cursorFor(sid,state.next_seq-1);},
+    async recordTerminal(input){
+      const candidate=validateEvent({session_id:sid,seq:state.next_seq,...input});
+      const key=identity(candidate);
+      const existing=state.events.find(event=>identity(event)===key);
+      if(existing) return {duplicate:true,event:existing,cursor:cursorFor(sid,state.next_seq-1)};
+      const event=candidate;
+      state.events.push(event);state.next_seq+=1;await persist();
+      return {duplicate:false,event,cursor:cursorFor(sid,event.seq)};
+    },
+    async replayAfter(cursor,{limit=100}={}){
+      if(!Number.isInteger(limit)||limit<1||limit>500) throw new Error('remote result replay limit invalid');
+      const parsed=parseRemoteResultCursor(cursor);
+      if(parsed.session_id!==sid) throw new Error('remote result cursor session mismatch');
+      const first=state.events[0]?.seq??state.next_seq;
+      const last=state.next_seq-1;
+      if(parsed.seq<first-1) throw new Error('cursor_outside_retention');
+      if(parsed.seq>last) throw new Error('remote result cursor ahead of journal');
+      const events=state.events.filter(event=>event.seq>parsed.seq).slice(0,limit);
+      const nextSeq=events.at(-1)?.seq??parsed.seq;
+      return {events:events.map(event=>({...event})),next_cursor:cursorFor(sid,nextSeq),has_more:state.events.some(event=>event.seq>nextSeq)};
+    }
+  });
+}

package/src/runtime-update.mjs

@@ -45,29 +45,33 @@ function normalizePersistentPublicOrigin(value){
   return publicOrigin.origin;
 }
 export function parseUpdateArgs(argv){
-  const out={stage:null,developmentRoot:null,expectedVersion:null,expectedManifest:null,sourceRoot:null,restoreStandingGrants:false,recoverOfflinePredecessor:false,enableMachineFs:false,enableObservation:false,cloudTransport:null,bridgeBootstrap:null,processPolicyBootstrap:null,hostCommandPins:[]};
-  const cloud={},bridge={},processPolicy={},seen=new Set(),hostPinIds=new Set();
+  const out={stage:null,developmentRoot:null,expectedVersion:null,expectedManifest:null,sourceRoot:null,restoreStandingGrants:false,recoverOfflinePredecessor:false,enableMachineFs:false,enableObservation:false,enableAutonomousSupervisor:false,cloudTransport:null,bridgeBootstrap:null,processPolicyBootstrap:null,semanticLspBootstrap:null,hostCommandPins:[]};
+  const cloud={},bridge={},processPolicy={},semanticLsp={},seen=new Set(),hostPinIds=new Set();
   const bridgeFlags=new Map([
     ['--bridge-root','root'],['--bridge-script-sha256','scriptSha256']
   ]);
   const processPolicyFlags=new Map([
     ['--process-policy','path'],['--process-policy-sha256','sha256']
   ]);
+  const semanticLspFlags=new Map([
+    ['--semantic-lsp-config','path'],['--semantic-lsp-config-sha256','sha256']
+  ]);
   const cloudFlags=new Map([
     ['--cloud-cloudflared','cloudflaredPath'],['--cloud-cloudflared-sha256','cloudflaredSha256'],
     ['--cloud-token-file','tokenFilePath'],['--cloud-token-sha256','tokenFileSha256'],
     ['--cloud-child-working-directory','childWorkingDirectory'],['--cloud-public-origin','publicOrigin']
   ]);
-  const valued=new Set(['--stage','--development-root','--expected-version','--expected-manifest','--source-root','--host-command-pin',...bridgeFlags.keys(),...processPolicyFlags.keys(),...cloudFlags.keys()]);
+  const valued=new Set(['--stage','--development-root','--expected-version','--expected-manifest','--source-root','--host-command-pin',...bridgeFlags.keys(),...processPolicyFlags.keys(),...semanticLspFlags.keys(),...cloudFlags.keys()]);
   for(let index=0;index<argv.length;index++){
     const arg=argv[index];
-    if(arg==='--restore-standing-grants'||arg==='--recover-offline-predecessor'||arg==='--enable-machine-fs'||arg==='--enable-observation'){
+    if(arg==='--restore-standing-grants'||arg==='--recover-offline-predecessor'||arg==='--enable-machine-fs'||arg==='--enable-observation'||arg==='--enable-autonomous-supervisor'){
       if(seen.has(arg)) throw new Error(`duplicate self-update argument '${arg}'`);
       seen.add(arg);
       if(arg==='--restore-standing-grants') out.restoreStandingGrants=true;
       else if(arg==='--recover-offline-predecessor') out.recoverOfflinePredecessor=true;
       else if(arg==='--enable-machine-fs') out.enableMachineFs=true;
-      else out.enableObservation=true;
+      else if(arg==='--enable-observation') out.enableObservation=true;
+      else out.enableAutonomousSupervisor=true;
       continue;
     }
     if(arg==='--host-command-pin'){
@@ -91,6 +95,7 @@ export function parseUpdateArgs(argv){
     else if(arg==='--source-root') out.sourceRoot=path.resolve(value);
     else if(bridgeFlags.has(arg)) bridge[bridgeFlags.get(arg)]=value;
     else if(processPolicyFlags.has(arg)) processPolicy[processPolicyFlags.get(arg)]=value;
+    else if(semanticLspFlags.has(arg)) semanticLsp[semanticLspFlags.get(arg)]=value;
     else cloud[cloudFlags.get(arg)]=value;
   }
   if(!out.stage) throw new Error('--stage is required');
@@ -111,6 +116,13 @@ export function parseUpdateArgs(argv){
     if(!HEX64.test(sha256)) throw new Error('process policy SHA-256 must be lowercase hex');
     out.processPolicyBootstrap={path:path.resolve(processPolicy.path),sha256};
   }
+  const semanticLspFields=[...semanticLspFlags.values()],semanticLspPresent=semanticLspFields.filter(key=>semanticLsp[key]!==undefined);
+  if(semanticLspPresent.length!==0&&semanticLspPresent.length!==semanticLspFields.length) throw new Error('semantic LSP config bootstrap requires path plus SHA-256 as one pair');
+  if(semanticLspPresent.length===semanticLspFields.length){
+    const sha256=String(semanticLsp.sha256).toLowerCase();
+    if(!HEX64.test(sha256)) throw new Error('semantic LSP config SHA-256 must be lowercase hex');
+    out.semanticLspBootstrap={path:path.resolve(semanticLsp.path),sha256};
+  }
   const cloudFields=[...cloudFlags.values()],present=cloudFields.filter(key=>cloud[key]!==undefined);
   if(present.length!==0&&present.length!==cloudFields.length) throw new Error('named tunnel bootstrap requires cloud path/hash/token/workdir plus persistent public origin');
   if(present.length===cloudFields.length){
@@ -262,6 +274,30 @@ export async function prepareBridgeSpec(config,bootstrap){
   return next;
 }
 
+export async function prepareAutonomousSupervisorSpec(config,{releaseRoot,enable=false}={}){
+  const next=structuredClone(config);
+  if(!enable) return next;
+  if(next.AutonomousRuntimeEnabled!==true) throw new Error('autonomous supervisor bootstrap requires AutonomousRuntimeEnabled');
+  if(typeof releaseRoot!=='string'||!path.isAbsolute(releaseRoot)) throw new Error('autonomous supervisor release root must be absolute');
+  const release=path.resolve(releaseRoot),script=path.join(release,'src','autonomous-supervisor-host.mjs');
+  const scriptStat=await lstat(script);
+  if(!scriptStat.isFile()||scriptStat.isSymbolicLink()) throw new Error('autonomous supervisor script must be a regular release file');
+  const bridge=next.Bridge;
+  if(!bridge||typeof bridge.FilePath!=='string'||!path.isAbsolute(bridge.FilePath)||!HEX64.test(String(bridge.FileSha256??''))) {
+    throw new Error('autonomous supervisor bootstrap requires pinned Bridge executable identity');
+  }
+  const executable=path.resolve(bridge.FilePath),exeStat=await lstat(executable);
+  if(!exeStat.isFile()||exeStat.isSymbolicLink()) throw new Error('autonomous supervisor executable must be a regular file');
+  const executableSha256=await sha256File(executable);
+  if(executableSha256!==String(bridge.FileSha256)) throw new Error('autonomous supervisor executable pin drift detected');
+  next.AutonomousSupervisorEnabled=true;
+  next.Supervisor={
+    FilePath:executable,FileSha256:executableSha256,Arguments:'src\\autonomous-supervisor-host.mjs',WorkingDirectory:release,
+    ScriptPath:script,ScriptSha256:await sha256File(script)
+  };
+  return next;
+}
+
 function quoteWindowsArgument(value){
   const text=String(value??'');
   if(text.length<1||/["\r\n\0]/.test(text)) throw new Error('named tunnel argument contains unsafe characters');
@@ -285,6 +321,14 @@ export async function prepareProcessPolicyBootstrap(bootstrap){
   return {...pinned,policy};
 }
 
+export async function prepareSemanticLspConfigBootstrap(bootstrap){
+  if(!bootstrap) return null;
+  const pinned=await verifyPinnedRegularFile(bootstrap.path,bootstrap.sha256,'semantic LSP config');
+  const config=await readJson(pinned.path);
+  if(config?.schema!=='deadbyte.semantic-lsp-config.v1'||!Array.isArray(config.servers)) throw new Error('semantic LSP config schema invalid');
+  return {...pinned,config};
+}
+
 async function preparePinnedCommandPolicy(policy,{commandPins=[],schema,label}={}){
   if(!policy) return {policy:null,repinned:[],matchedCommandIds:[]};
   if(policy.schema!==schema||policy.enabled!==true||!policy.commands||typeof policy.commands!=='object'||Array.isArray(policy.commands)) {
@@ -715,7 +759,7 @@ function publicPointer(pointer){
     release_root:pointer.release_root,generation_root:pointer.generation_root,generation_manifest_sha256:pointer.generation_manifest_sha256,
     launcher_sha256:pointer.launcher_sha256,config_path:pointer.config_path};
 }
-export async function performSlotUpdate({stage,developmentRoot,expectedVersion,expectedManifest,sourceRoot=null,stateRoot=DEFAULT_STATE_ROOT,restoreStandingGrants=false,recoverOfflinePredecessor=false,cloudTransport=null,bridgeBootstrap=null,processPolicyBootstrap=null,enableMachineFs=false,enableObservation=false,hostCommandPins=[]}){
+export async function performSlotUpdate({stage,developmentRoot,expectedVersion,expectedManifest,sourceRoot=null,stateRoot=DEFAULT_STATE_ROOT,restoreStandingGrants=false,recoverOfflinePredecessor=false,cloudTransport=null,bridgeBootstrap=null,processPolicyBootstrap=null,semanticLspBootstrap=null,enableMachineFs=false,enableObservation=false,enableAutonomousSupervisor=false,hostCommandPins=[]}){
   if(process.platform!=='win32') throw new Error('R27 slot update is Windows-only');
   const state=path.resolve(stateRoot),stageRoot=path.resolve(stage),development=assertDevelopmentRootSafe(developmentRoot,state);
   const key=await loadUpdateKey(state); const updateId=`r27-${expectedManifest.slice(0,16)}-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
@@ -740,6 +784,11 @@ export async function performSlotUpdate({stage,developmentRoot,expectedVersion,e
       control.processPolicy=processBootstrap.policy;
       control.config.ProcessRuntimeEnabled=true;
     }
+    const semanticBootstrap=await prepareSemanticLspConfigBootstrap(semanticLspBootstrap);
+    if(semanticBootstrap){
+      control.config.SemanticLspConfigFile=semanticBootstrap.path;
+      control.config.SemanticLspConfigSha256=semanticBootstrap.sha256;
+    }
     if(enableMachineFs){
       if(control.config.CodingRuntimeEnabled!==true) throw new Error('MachineFsRuntimeEnabled requires CodingRuntimeEnabled');
       control.config.MachineFsRuntimeEnabled=true;
@@ -751,6 +800,7 @@ export async function performSlotUpdate({stage,developmentRoot,expectedVersion,e
     }
     control.config=await prepareBridgeSpec(control.config,bridgeBootstrap);
     control.config=await prepareNamedTunnelCloudSpec(control.config,{releaseRoot:slot.release_root,bootstrap:cloudTransport});
+    control.config=await prepareAutonomousSupervisorSpec(control.config,{releaseRoot:slot.release_root,enable:enableAutonomousSupervisor});
     authorityPreparation=await prepareAuthorityPolicies({hostPolicy:control.hostPolicy,codingPolicy:control.codingPolicy},{commandPins:hostCommandPins});
     control.hostPolicy=authorityPreparation.hostPolicy;
     control.codingPolicy=authorityPreparation.codingPolicy;
@@ -942,8 +992,8 @@ export async function runSlotUpdateCli(argv=process.argv.slice(2),{stateRoot=DEF
   const args=parseUpdateArgs(argv);
   const result=await performSlotUpdate({stage:args.stage,developmentRoot:args.developmentRoot,expectedVersion:args.expectedVersion,
     expectedManifest:args.expectedManifest,sourceRoot:args.sourceRoot,stateRoot,restoreStandingGrants:args.restoreStandingGrants,recoverOfflinePredecessor:args.recoverOfflinePredecessor,
-    cloudTransport:args.cloudTransport,bridgeBootstrap:args.bridgeBootstrap,processPolicyBootstrap:args.processPolicyBootstrap,enableMachineFs:args.enableMachineFs,
-    enableObservation:args.enableObservation,hostCommandPins:args.hostCommandPins});
+    cloudTransport:args.cloudTransport,bridgeBootstrap:args.bridgeBootstrap,processPolicyBootstrap:args.processPolicyBootstrap,semanticLspBootstrap:args.semanticLspBootstrap,enableMachineFs:args.enableMachineFs,
+    enableObservation:args.enableObservation,enableAutonomousSupervisor:args.enableAutonomousSupervisor,hostCommandPins:args.hostCommandPins});
   console.log(`R27_SLOT_UPDATE_PASS version=${args.expectedVersion}`);
   console.log(`UPDATE_ID ${result.update_id}`); console.log(`RECEIPT_SHA256 ${result.receipt_sha256}`);
   console.log(`STATE_PATH ${result.state_path}`); console.log(`ACTIVE_RELEASE ${result.pointer.release_id}`);

package/src/semantic-backend-registry.mjs

@@ -0,0 +1,39 @@
+import path from 'node:path';
+
+const REQUIRED_METHODS=['outline','definition','references','replaceSymbol','diagnostics'];
+
+function normalizeExtension(value){
+  if(typeof value!=='string'||value.length<2||!value.startsWith('.')) throw new Error(`invalid semantic extension: ${String(value)}`);
+  return value.toLowerCase();
+}
+
+export function createSemanticBackendRegistry({backends}){
+  if(!Array.isArray(backends)||backends.length<1) throw new Error('semantic backend registry requires backends');
+  const ids=new Set();
+  const byExtension=new Map();
+  const normalized=[];
+  for(const backend of backends){
+    if(!backend||typeof backend!=='object'||Array.isArray(backend)) throw new Error('semantic backend must be an object');
+    if(typeof backend.id!=='string'||backend.id.length<1) throw new Error('semantic backend id missing');
+    if(ids.has(backend.id)) throw new Error(`duplicate semantic backend id: ${backend.id}`);
+    ids.add(backend.id);
+    if(!(backend.extensions instanceof Set)||backend.extensions.size<1) throw new Error(`semantic backend ${backend.id} extensions missing`);
+    for(const method of REQUIRED_METHODS) if(typeof backend[method]!=='function') throw new Error(`semantic backend ${backend.id} missing method ${method}`);
+    const extensions=[...backend.extensions].map(normalizeExtension).sort();
+    for(const ext of extensions){
+      if(byExtension.has(ext)) throw new Error(`semantic extension ${ext} already owned by ${byExtension.get(ext).id}`);
+      byExtension.set(ext,backend);
+    }
+    normalized.push({id:backend.id,extensions});
+  }
+  normalized.sort((a,b)=>a.id.localeCompare(b.id,'en'));
+  return Object.freeze({
+    backendForPath(relativePath){
+      const ext=path.extname(String(relativePath)).toLowerCase();
+      const backend=byExtension.get(ext);
+      if(!backend) throw new Error(`unsupported semantic language: ${ext||'<none>'}`);
+      return backend;
+    },
+    languages(){return normalized.map(item=>({id:item.id,extensions:[...item.extensions]}));}
+  });
+}

package/src/semantic-code.mjs

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import * as ts from 'typescript';
+import { createSemanticBackendRegistry } from './semantic-backend-registry.mjs';
+
+const SOURCE_EXTENSIONS=new Set(['.ts','.tsx','.mts','.cts','.js','.jsx','.mjs','.cjs']);
+const MAX_PROJECT_ENTRIES=2000;
+const MAX_SOURCE_FILES=1000;
+
+function digest(value){return createHash('sha256').update(JSON.stringify(value)).digest('hex');}
+function relNormalized(value){return value.replaceAll('\\','/').replace(/^\.\//,'');}
+function inside(root,target){const rel=path.relative(root,target);return rel===''||(!rel.startsWith(`..${path.sep}`)&&rel!=='..'&&!path.isAbsolute(rel));}
+function denied(root,absolute){
+  if(!inside(root.real_path,absolute)) return true;
+  const rel=relNormalized(path.relative(root.real_path,absolute)).toLowerCase();
+  return root.deny_paths.some(item=>rel===item||rel.startsWith(`${item}/`));
+}
+function sourceExtension(file){return SOURCE_EXTENSIONS.has(path.extname(file).toLowerCase());}
+function defaultOptions(){return {target:ts.ScriptTarget.ES2022,module:ts.ModuleKind.NodeNext,moduleResolution:ts.ModuleResolutionKind.NodeNext,allowJs:true,checkJs:true,strict:false,noEmit:true,jsx:ts.JsxEmit.Preserve,resolveJsonModule:true,skipLibCheck:true};}
+function parseOptions(configText,rootPath){
+  if(!configText) return defaultOptions();
+  const parsed=ts.parseConfigFileTextToJson(path.join(rootPath,'tsconfig.json'),configText);
+  if(parsed.error) return defaultOptions();
+  const converted=ts.convertCompilerOptionsFromJson(parsed.config?.compilerOptions??{},rootPath);
+  return {...defaultOptions(),...converted.options,noEmit:true};
+}
+function lineColumn(source,pos){const p=source.getLineAndCharacterOfPosition(Math.max(0,Math.min(pos,source.getFullWidth())));return {line:p.line,column:p.character};}
+function locationFromSpan(project,fileName,textSpan,name='',kind='unknown'){
+  const absolute=path.resolve(fileName);
+  if(!inside(project.root.real_path,absolute)||denied(project.root,absolute)) return null;
+  const source=project.service.getProgram()?.getSourceFile(absolute);
+  if(!source) return null;
+  const start=lineColumn(source,textSpan.start); const end=lineColumn(source,textSpan.start+textSpan.length);
+  return {path:relNormalized(path.relative(project.root.real_path,absolute)),name:String(name||''),kind:String(kind||'unknown'),start_line:start.line,start_column:start.column,end_line:end.line,end_column:end.column};
+}
+async function buildProject(codingRuntime,rootId){
+  const status=await codingRuntime.sessionStatus();
+  if(!status.armed) throw new Error(`coding plane is disarmed: ${status.reason}`);
+  if(!status.root_ids.includes(rootId)) throw new Error(`coding root '${rootId}' is outside active lease`);
+  const root=codingRuntime.policy.roots[rootId];
+  if(!root||root.read!==true) throw new Error(`coding root '${rootId}' does not allow read`);
+  const tree=await codingRuntime.tree({rootId,path:'.',maxDepth:12,maxEntries:MAX_PROJECT_ENTRIES});
+  if(tree.truncated) throw new Error(`semantic project exceeds ${MAX_PROJECT_ENTRIES} entry bound; use a narrower coding root`);
+  const relativeFiles=tree.entries.filter(item=>item.type==='file'&&sourceExtension(item.path)).map(item=>item.path);
+  if(relativeFiles.length>MAX_SOURCE_FILES) throw new Error(`semantic project exceeds ${MAX_SOURCE_FILES} source file bound`);
+  const files=relativeFiles.map(rel=>path.join(root.real_path,...rel.split('/')));
+  let configText='';
+  if(tree.entries.some(item=>item.type==='file'&&item.path==='tsconfig.json')) configText=await readFile(path.join(root.real_path,'tsconfig.json'),'utf8');
+  const options=parseOptions(configText,root.real_path);
+  const versions=new Map(files.map(file=>[path.resolve(file),'1']));
+  const tsLibRoot=path.dirname(ts.getDefaultLibFilePath(options));
+  const allowedRead=file=>{
+    const absolute=path.resolve(file);
+    if(inside(tsLibRoot,absolute)) return true;
+    return inside(root.real_path,absolute)&&!denied(root,absolute);
+  };
+  const host={
+    getScriptFileNames:()=>files,
+    getScriptVersion:file=>versions.get(path.resolve(file))??'1',
+    getScriptSnapshot:file=>{if(!allowedRead(file))return undefined;const text=ts.sys.readFile(file);return text===undefined?undefined:ts.ScriptSnapshot.fromString(text);},
+    getCurrentDirectory:()=>root.real_path,
+    getCompilationSettings:()=>options,
+    getDefaultLibFileName:opts=>ts.getDefaultLibFilePath(opts),
+    fileExists:file=>allowedRead(file)&&ts.sys.fileExists(file),
+    readFile:file=>allowedRead(file)?ts.sys.readFile(file):undefined,
+    readDirectory:(dir,extensions,excludes,includes,depth)=>inside(root.real_path,path.resolve(dir))?ts.sys.readDirectory(dir,extensions,excludes,includes,depth):[],
+    directoryExists:dir=>allowedRead(path.join(dir,'_probe'))&&ts.sys.directoryExists?.(dir),
+    getDirectories:dir=>inside(root.real_path,path.resolve(dir))?(ts.sys.getDirectories?.(dir)??[]):[],
+    useCaseSensitiveFileNames:()=>ts.sys.useCaseSensitiveFileNames,
+    getNewLine:()=>ts.sys.newLine
+  };
+  const service=ts.createLanguageService(host,ts.createDocumentRegistry());
+  return {root,files,service,options};
+}
+function targetFile(project,relativePath){
+  const absolute=path.resolve(project.root.real_path,...relNormalized(relativePath).split('/'));
+  if(!inside(project.root.real_path,absolute)||denied(project.root,absolute)||!sourceExtension(absolute)) throw new Error('semantic target must be an allowed JS/TS source file');
+  const source=project.service.getProgram()?.getSourceFile(absolute);
+  if(!source) throw new Error(`semantic source unavailable: ${relativePath}`);
+  return {absolute,source};
+}
+function offsetAt(source,line,column){
+  if(!Number.isInteger(line)||line<0||!Number.isInteger(column)||column<0) throw new Error('line and column must be non-negative integers');
+  if(line>=source.getLineStarts().length) throw new Error('line is outside source file');
+  const lineStart=source.getPositionOfLineAndCharacter(line,0);
+  const lineEnd=line+1<source.getLineStarts().length?source.getPositionOfLineAndCharacter(line+1,0):source.getFullWidth();
+  const pos=lineStart+column;
+  if(pos>lineEnd) throw new Error('column is outside source line');
+  return pos;
+}
+function flattenNavigation(project,target,fileSha,maxSymbols){
+  const tree=project.service.getNavigationTree(target.absolute);
+  const out=[];
+  const visit=(item,container='')=>{
+    if(out.length>=maxSymbols) return;
+    const span=item.spans?.[0];
+    if(span&&item.text&&item.text!=='<global>'){
+      const loc=locationFromSpan(project,target.absolute,span,item.text,item.kind);
+      if(loc){
+        const nameSpan=item.nameSpan??span; const nameLoc=locationFromSpan(project,target.absolute,nameSpan,item.text,item.kind)??loc;
+        const symbolId=digest({schema:'deadbyte.semantic-symbol.v1',backend:'typescript',path:loc.path,file_sha256:fileSha,name:item.text,kind:item.kind,start:span.start,length:span.length});
+        out.push({...loc,symbol_id:symbolId,container_name:container,name_start_line:nameLoc.start_line,name_start_column:nameLoc.start_column,_span:span});
+      }
+    }
+    for(const child of item.childItems??[]) visit(child,item.text&&item.text!=='<global>'?item.text:container);
+  };
+  visit(tree,'');
+  return {symbols:out.slice(0,maxSymbols),truncated:out.length>=maxSymbols};
+}
+function diagnosticCategory(category){return ts.DiagnosticCategory[category]?.toLowerCase?.()??'unknown';}
+
+export function createTypeScriptSemanticBackend({codingRuntime}){
+  if(!codingRuntime) throw new Error('TypeScript semantic backend requires coding runtime');
+  async function outline({rootId,relativePath,maxSymbols=200}){
+    if(!Number.isInteger(maxSymbols)||maxSymbols<1||maxSymbols>500) throw new Error('max_symbols must be in [1, 500]');
+    const file=await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath);
+    const flat=flattenNavigation(project,target,file.sha256,maxSymbols);
+    return {status:'ok',root_id:rootId,path:relativePath,file_sha256:file.sha256,engine:`typescript-${ts.version}`,symbols:flat.symbols.map(({_span,...x})=>x),truncated:flat.truncated};
+  }
+  async function definition({rootId,relativePath,line,column,maxResults=50}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>200) throw new Error('max_results must be in [1, 200]');
+    await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath); const pos=offsetAt(target.source,line,column);
+    const defs=project.service.getDefinitionAtPosition(target.absolute,pos)??[];
+    const locations=defs.map(item=>locationFromSpan(project,item.fileName,item.textSpan,item.name,item.kind)).filter(Boolean).slice(0,maxResults);
+    return {status:'ok',root_id:rootId,path:relativePath,line,column,engine:`typescript-${ts.version}`,locations,truncated:defs.length>maxResults};
+  }
+  async function references({rootId,relativePath,line,column,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath); const pos=offsetAt(target.source,line,column);
+    const refs=project.service.getReferencesAtPosition(target.absolute,pos)??[];
+    const locations=refs.map(item=>locationFromSpan(project,item.fileName,item.textSpan,'','reference')).filter(Boolean).slice(0,maxResults);
+    return {status:'ok',root_id:rootId,path:relativePath,line,column,engine:`typescript-${ts.version}`,locations,truncated:refs.length>maxResults};
+  }
+  async function replaceSymbol({rootId,relativePath,symbolId,newBody,expectedSha256}){
+    if(typeof newBody!=='string'||newBody.length>524288) throw new Error('new_body exceeds 524288 characters');
+    const file=await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    if(file.sha256!==expectedSha256) throw new Error(`semantic replace precondition mismatch: expected ${expectedSha256}, found ${file.sha256}`);
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath);
+    const flat=flattenNavigation(project,target,file.sha256,500);
+    const symbol=flat.symbols.find(item=>item.symbol_id===symbolId);
+    if(!symbol) throw new Error('semantic symbol_id is stale or unknown for current file');
+    const oldBody=target.source.text.slice(symbol._span.start,symbol._span.start+symbol._span.length);
+    const result=await codingRuntime.textReplace({rootId,relativePath,oldString:oldBody,newString:newBody,expectedSha256,expectedReplacements:1});
+    return {...result,symbol_id:symbolId,symbol_name:symbol.name,engine:`typescript-${ts.version}`};
+  }
+  async function diagnostics({rootId,relativePath,maxResults=200}){
+    if(!Number.isInteger(maxResults)||maxResults<1||maxResults>500) throw new Error('max_results must be in [1, 500]');
+    await codingRuntime.fileRead({rootId,relativePath,encoding:'utf8'});
+    const project=await buildProject(codingRuntime,rootId); const target=targetFile(project,relativePath);
+    const all=[...project.service.getSyntacticDiagnostics(target.absolute),...project.service.getSemanticDiagnostics(target.absolute)];
+    const diagnosticsOut=all.slice(0,maxResults).map(item=>{
+      const span=Number.isInteger(item.start)&&Number.isInteger(item.length)?{start:item.start,length:item.length}:{start:0,length:0};
+      const loc=locationFromSpan(project,target.absolute,span,'','diagnostic');
+      return {message:ts.flattenDiagnosticMessageText(item.messageText,'\n'),code:String(item.code),severity:diagnosticCategory(item.category),...(loc?{location:loc}:{})};
+    });
+    return {status:'ok',root_id:rootId,path:relativePath,engine:`typescript-${ts.version}`,diagnostics:diagnosticsOut,truncated:all.length>maxResults};
+  }
+  return Object.freeze({id:'typescript',extensions:new Set(SOURCE_EXTENSIONS),outline,definition,references,replaceSymbol,diagnostics});
+}
+
+export function createSemanticCodeRuntime({codingRuntime,backends=[]}){
+  if(!codingRuntime) throw new Error('semantic runtime requires coding runtime');
+  if(!Array.isArray(backends)) throw new Error('semantic runtime backends must be an array');
+  const typescript=createTypeScriptSemanticBackend({codingRuntime});
+  const registry=createSemanticBackendRegistry({backends:[typescript,...backends]});
+  const route=(method,args)=>registry.backendForPath(args.relativePath)[method](args);
+  return Object.freeze({
+    outline:async args=>route('outline',args),
+    definition:async args=>route('definition',args),
+    references:async args=>route('references',args),
+    replaceSymbol:async args=>route('replaceSymbol',args),
+    diagnostics:async args=>route('diagnostics',args),
+    languages:()=>registry.languages()
+  });
+}