deadbyte-mcp 0.14.0 → 0.15.0

package/src/codex-app-server-r44.mjs

@@ -0,0 +1,154 @@
+import path from 'node:path';
+import { createAgentBackendR44 } from './agent-backend-r44.mjs';
+
+const ID=/^[A-Za-z0-9._-]{1,64}$/;
+function insist(ok,message){if(!ok)throw new Error(message);}
+function text(value,label,max=262144){insist(typeof value==='string'&&value.length>=1&&value.length<=max,`${label} invalid`);return value;}
+function threadIdFromResponse(value){
+  const id=value?.thread?.id;insist(typeof id==='string'&&id.length>=1&&id.length<=512,'Codex thread response missing thread.id');return id;
+}
+function turnIdFromResponse(value){
+  const id=value?.turn?.id;insist(typeof id==='string'&&id.length>=1&&id.length<=512,'Codex turn response missing turn.id');return id;
+}
+function safeThreadParams({model,cwd}){
+  return {model,cwd,approvalPolicy:'never',approvalsReviewer:'user',sandbox:'read-only',ephemeral:false};
+}
+function approvalHandler({method}){
+  if(method==='item/commandExecution/requestApproval'||method==='item/fileChange/requestApproval')return {decision:'decline'};
+  if(method==='item/permissions/requestApproval')return {permissions:{},scope:'turn'};
+  if(method==='item/tool/requestUserInput')return {answers:{}};
+  const error=new Error(`Codex server request denied: ${method}`);error.code=-32001;throw error;
+}
+
+export async function createCodexAppServerR44({
+  stateDir,model,cwd,clientVersion='0.15.0',transportFactory=null,
+  executable=null,executableSha256=null,args=['app-server'],env=null
+}={}){
+  insist(typeof stateDir==='string'&&path.isAbsolute(stateDir),'Codex stateDir must be absolute');
+  text(model,'Codex model',128);insist(typeof cwd==='string'&&path.isAbsolute(cwd),'Codex cwd must be absolute');
+  text(clientVersion,'Codex client version',64);
+  const turns=new Map();
+  const attachedThreads=new Set();
+  let initialized=false;
+
+  function turnRecord(turnId,threadId=null){
+    let rec=turns.get(turnId);
+    if(!rec){rec={turn_id:turnId,thread_id:threadId,final_answer:null,unknown_answer:null,status:null,error:null,waiters:[]};turns.set(turnId,rec);}
+    else if(threadId&&rec.thread_id===null)rec.thread_id=threadId;
+    return rec;
+  }
+  function settle(rec){
+    if(!rec.status||!['completed','failed','interrupted'].includes(rec.status))return;
+    const waiters=rec.waiters.splice(0);
+    if(rec.status==='completed'){
+      const raw=rec.final_answer??rec.unknown_answer;
+      for(const waiter of waiters){
+        clearTimeout(waiter.timer);
+        if(typeof raw==='string'&&raw.length>0)waiter.resolve({raw_text:raw});
+        else waiter.reject(new Error('Codex turn completed without agent final response'));
+      }
+    }else{
+      for(const waiter of waiters){clearTimeout(waiter.timer);waiter.reject(new Error(rec.error??`Codex turn ${rec.status}`));}
+    }
+  }
+  async function notificationHandler({method,params}){
+    if(method==='item/completed'){
+      const tid=params?.turnId,threadId=params?.threadId,item=params?.item;
+      if(typeof tid!=='string'||!item||typeof item!=='object')return;
+      const rec=turnRecord(tid,typeof threadId==='string'?threadId:null);
+      if(item.type==='agentMessage'||item.type==='agent_message'){
+        if(typeof item.text!=='string')return;
+        if(item.phase==='final_answer'||item.phase==='finalAnswer')rec.final_answer=item.text;
+        else if(item.phase===null||item.phase===undefined)rec.unknown_answer=item.text;
+      }
+      return;
+    }
+    if(method==='turn/completed'){
+      const turn=params?.turn;const tid=turn?.id;
+      if(typeof tid!=='string')return;
+      const rec=turnRecord(tid,typeof params?.threadId==='string'?params.threadId:null);
+      rec.status=String(turn.status??'completed');
+      if(rec.status==='failed')rec.error=turn.error?.message??'Codex turn failed';
+      settle(rec);
+    }
+  }
+
+  const backend=await createAgentBackendR44({
+    backendId:'codex-app-server',stateDir:path.join(stateDir,'backend'),transportFactory,
+    executable,executableSha256,args,cwd,env,wireMode:'codex-app-server',
+    serverRequestHandler:approvalHandler,notificationHandler
+  });
+
+  async function start(){
+    if(initialized)return {status:'ok',initialized:true};
+    await backend.start();
+    await backend.request({method:'initialize',params:{
+      clientInfo:{name:'deadbyte-mcp',version:clientVersion},
+      capabilities:{experimentalApi:false,requestAttestation:false,optOutNotificationMethods:null}
+    },timeoutMs:30000});
+    await backend.notify({method:'initialized',params:{}});
+    initialized=true;
+    return {status:'ok',initialized:true,backend:'codex_app_server'};
+  }
+  async function ensureStarted(){if(!initialized)await start();}
+  async function ensureThread({logicalId}={}){
+    await ensureStarted();insist(typeof logicalId==='string'&&ID.test(logicalId),'Codex logical thread id invalid');
+    const status=await backend.status();const existing=status.threads[logicalId];
+    if(existing){
+      if(!attachedThreads.has(existing)){
+        const response=await backend.request({method:'thread/resume',params:{threadId:existing,...safeThreadParams({model,cwd}),excludeTurns:true},timeoutMs:60000});
+        const resumed=threadIdFromResponse(response);insist(resumed===existing,'Codex resumed thread identity mismatch');attachedThreads.add(existing);
+      }
+      return {status:'ok',logical_id:logicalId,thread_id:existing,resumed:true};
+    }
+    const response=await backend.request({method:'thread/start',params:safeThreadParams({model,cwd}),timeoutMs:60000});
+    const created=threadIdFromResponse(response);
+    await backend.bindThread({logicalId,threadId:created});attachedThreads.add(created);
+    return {status:'ok',logical_id:logicalId,thread_id:created,resumed:false};
+  }
+  function waitTurn(turnId,threadId,timeoutMs){
+    insist(Number.isInteger(timeoutMs)&&timeoutMs>=100&&timeoutMs<=900000,'Codex turn timeout invalid');
+    const rec=turnRecord(turnId,threadId);
+    if(rec.status&&['completed','failed','interrupted'].includes(rec.status)){
+      return new Promise((resolve,reject)=>{
+        const timer=setTimeout(()=>{},1);rec.waiters.push({resolve,reject,timer});settle(rec);
+      });
+    }
+    return new Promise((resolve,reject)=>{
+      const timer=setTimeout(()=>{
+        const index=rec.waiters.findIndex(x=>x.timer===timer);if(index>=0)rec.waiters.splice(index,1);
+        reject(new Error('Codex turn completion timeout'));
+      },timeoutMs);
+      rec.waiters.push({resolve,reject,timer});
+    });
+  }
+  async function runPlanner({logicalId='planner',prompt,timeoutMs=120000}={}){
+    text(prompt,'Codex planner prompt',1024*1024);
+    const thread=await ensureThread({logicalId});
+    const started=await backend.request({method:'turn/start',params:{
+      threadId:thread.thread_id,input:[{type:'text',text:prompt}],approvalPolicy:'never'
+    },timeoutMs:Math.min(timeoutMs,60000)});
+    const turnId=turnIdFromResponse(started);turnRecord(turnId,thread.thread_id);
+    const completed=await waitTurn(turnId,thread.thread_id,timeoutMs);
+    return {backend:'codex_app_server',model,raw_text:completed.raw_text,response_id:turnId,thread_id:thread.thread_id};
+  }
+  async function steer({threadId,turnId,text:message,timeoutMs=30000}={}){
+    await ensureStarted();text(threadId,'Codex threadId',512);text(turnId,'Codex turnId',512);text(message,'Codex steer text',262144);
+    return backend.request({method:'turn/steer',params:{threadId,expectedTurnId:turnId,input:[{type:'text',text:message}]},timeoutMs});
+  }
+  async function interrupt({threadId,turnId,timeoutMs=30000}={}){
+    await ensureStarted();text(threadId,'Codex threadId',512);text(turnId,'Codex turnId',512);
+    return backend.request({method:'turn/interrupt',params:{threadId,turnId},timeoutMs});
+  }
+  async function modelList({includeHidden=false}={}){
+    await ensureStarted();return backend.request({method:'model/list',params:{includeHidden:includeHidden===true},timeoutMs:30000});
+  }
+  async function status(){const value=await backend.status();return {...value,initialized,attached_threads:[...attachedThreads].sort()};}
+  async function close(){
+    for(const rec of turns.values()){
+      for(const waiter of rec.waiters.splice(0)){clearTimeout(waiter.timer);waiter.reject(new Error('Codex adapter closed before turn completion'));}
+    }
+    initialized=false;attachedThreads.clear();return backend.close();
+  }
+  return Object.freeze({start,ensureThread,runPlanner,steer,interrupt,modelList,status,close,backend});
+}

package/src/coding-plane.mjs

@@ -153,6 +153,25 @@ export async function assertCodingArmed(policy, rootId = null, now = new Date())
   return status;
 }
 
+export async function recheckCodingAuthority(policy, initial, rootId = null, now = new Date()) {
+  if (!initial?.armed || typeof initial.instance_nonce !== 'string' || !Array.isArray(initial.root_ids)) {
+    throw new Error('coding authority recheck requires an armed initial snapshot');
+  }
+  let current;
+  try { current = await assertCodingArmed(policy, rootId, now); }
+  catch (error) { throw new Error(`coding authority changed during operation: ${String(error?.message ?? error)}`); }
+  const initialRoots = [...initial.root_ids].sort();
+  const currentRoots = [...current.root_ids].sort();
+  const changed =
+    current.instance_nonce !== initial.instance_nonce ||
+    current.standing !== initial.standing ||
+    current.expires_at_utc !== initial.expires_at_utc ||
+    initialRoots.length !== currentRoots.length ||
+    initialRoots.some((id, index) => id !== currentRoots[index]);
+  if (changed) throw new Error('coding authority changed during operation');
+  return current;
+}
+
 function getRoot(policy, rootId, permission) {
   if (!ID_RE.test(rootId)) throw new Error('invalid coding root id');
   const root = policy.roots[rootId];
@@ -185,7 +204,7 @@ async function nearestExistingParent(candidate) {
     }
   }
 }
-async function resolveCodingWritable(policy, lease, rootId, relativePath) {
+async function resolveCodingWritable(policy, lease, rootId, relativePath, authorityCheck = null) {
   validatePortableRelativePath(relativePath);
   if (!lease.root_ids.includes(rootId)) throw new Error(`coding root '${rootId}' is outside active lease`);
   const root = getRoot(policy, rootId, 'write');
@@ -196,6 +215,7 @@ async function resolveCodingWritable(policy, lease, rootId, relativePath) {
   const existingParent = await nearestExistingParent(parent);
   const realExisting = await realpath(existingParent);
   if (!isInside(root.real_path, realExisting)) throw new Error('coding parent symlink escapes allowed root');
+  if (authorityCheck) await authorityCheck();
   await mkdir(parent, { recursive: true });
   const realParent = await realpath(parent);
   if (!isInside(root.real_path, realParent)) throw new Error('coding parent resolves outside allowed root');
@@ -240,12 +260,13 @@ function decodeContent(content, encoding) {
   }
   throw new Error('encoding must be utf8 or base64');
 }
-async function atomicWrite(target, bytes, expectedSha256) {
+async function atomicWrite(target, bytes, expectedSha256, authorityCheck = null) {
   const before = await targetState(target);
   checkExpected(before, expectedSha256);
   const temp = path.join(path.dirname(target), `.${path.basename(target)}.deadbyte-coding-${process.pid}-${randomBytes(8).toString('hex')}.tmp`);
   let handle;
   try {
+    if (authorityCheck) await authorityCheck();
     handle = await open(temp, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);
     await handle.writeFile(bytes);
     await handle.sync();
@@ -253,6 +274,7 @@ async function atomicWrite(target, bytes, expectedSha256) {
     handle = null;
     const race = await targetState(target);
     checkExpected(race, expectedSha256);
+    if (authorityCheck) await authorityCheck();
     await rename(temp, target);
   } catch (error) {
     if (handle) await handle.close().catch(() => {});
@@ -394,13 +416,15 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
   }
   async function fileWrite({ rootId, relativePath, content, encoding = 'utf8', expectedSha256, receiptId = null, requestSha256 = null }) {
     const lease = await assertCodingArmed(policy, rootId);
-    const { lexical } = await resolveCodingWritable(policy, lease, rootId, relativePath);
+    let activeLease = lease;
+    const authorityCheck = async () => { activeLease = await recheckCodingAuthority(policy, lease, rootId); return activeLease; };
+    const { lexical } = await resolveCodingWritable(policy, lease, rootId, relativePath, authorityCheck);
     const bytes = decodeContent(content, encoding);
     if (bytes.length > policy.max_write_bytes) throw new Error(`coding write exceeds ${policy.max_write_bytes} byte limit`);
     const request = requestSha256 ?? requestSha('coding_file_write', { root_id: rootId, path: relativePath, encoding, expected_sha256: expectedSha256, content_sha256: sha256Bytes(bytes) });
     const started = new Date().toISOString();
-    const { before, after } = await atomicWrite(lexical, bytes, expectedSha256);
-    const signed = await signCodingReceipt(policy, signingKeyPath, lease, {
+    const { before, after } = await atomicWrite(lexical, bytes, expectedSha256, authorityCheck);
+    const signed = await signCodingReceipt(policy, signingKeyPath, activeLease, {
       operation: 'coding_file_write', request_sha256: request, root_id: rootId, path: relativePath,
       started_at_utc: started, completed_at_utc: new Date().toISOString(),
       before_sha256: before.sha256, after_sha256: after.sha256, bytes: after.bytes
@@ -421,11 +445,12 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
     const tombstone = path.join(path.dirname(lexical), `.${path.basename(lexical)}.deadbyte-delete-${id}.tmp`);
     const request = requestSha256 ?? requestSha('coding_file_delete', { root_id: rootId, path: relativePath, expected_sha256: expectedSha256 });
     const started = new Date().toISOString();
+    const activeLease = await recheckCodingAuthority(policy, lease, rootId);
     await rename(lexical, tombstone);
     try {
       const tombstoneState = await targetState(tombstone);
       if (!tombstoneState.exists || tombstoneState.sha256 !== expectedSha256) throw new Error('coding delete tombstone hash mismatch');
-      const signed = await signCodingReceipt(policy, signingKeyPath, lease, {
+      const signed = await signCodingReceipt(policy, signingKeyPath, activeLease, {
         operation: 'coding_file_delete', request_sha256: request, root_id: rootId, path: relativePath,
         started_at_utc: started, completed_at_utc: new Date().toISOString(),
         before_sha256: expectedSha256, after_sha256: null, bytes: before.bytes
@@ -463,8 +488,10 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
       old_sha256: sha256Bytes(Buffer.from(oldString, 'utf8')), new_sha256: sha256Bytes(Buffer.from(newString, 'utf8'))
     });
     const started = new Date().toISOString();
-    const { after } = await atomicWrite(lexical, nextBytes, expectedSha256);
-    const signed = await signCodingReceipt(policy, signingKeyPath, lease, {
+    let activeLease = lease;
+    const authorityCheck = async () => { activeLease = await recheckCodingAuthority(policy, lease, rootId); return activeLease; };
+    const { after } = await atomicWrite(lexical, nextBytes, expectedSha256, authorityCheck);
+    const signed = await signCodingReceipt(policy, signingKeyPath, activeLease, {
       operation: 'coding_text_replace', request_sha256: request, root_id: rootId, path: relativePath,
       started_at_utc: started, completed_at_utc: new Date().toISOString(), before_sha256: beforeSha,
       after_sha256: after.sha256, replacements: count, bytes: after.bytes
@@ -473,7 +500,8 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
       bytes: after.bytes, replacements: count, receipt_id: signed.receipt.receipt_id,
       receipt_sha256: signed.receipt.receipt_sha256, request_sha256: request };
   }
-  async function runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args = [], cwd = '.', timeoutMs = null }) {
+  async function runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args = [], cwd = '.', timeoutMs = null,
+    executionDeadlineUtc = null, preExecutionCheck = null }) {
     const lease = await assertCodingArmed(policy, rootId);
     if (!ID_RE.test(commandId ?? '')) throw new Error('invalid coding command id');
     const command = policy.commands[commandId];
@@ -498,8 +526,22 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
       if (!(await stat(cwdResolved)).isDirectory()) throw new Error('coding command cwd must be a directory');
     }
     const requestedTimeout = timeoutMs === null ? command.timeout_ms : finiteInteger(timeoutMs, 'timeout_ms', 100, command.timeout_ms, command.timeout_ms);
-    const grantBound = Number.isFinite(lease.remaining_ms) ? lease.remaining_ms : command.timeout_ms;
-    const effectiveTimeout = Math.max(100, Math.min(requestedTimeout, command.timeout_ms, grantBound));
+    if (preExecutionCheck !== null) {
+      if (typeof preExecutionCheck !== 'function') throw new Error('pre_execution_check must be a function or null');
+      await preExecutionCheck();
+    }
+    const activeLease = await recheckCodingAuthority(policy, lease, rootId);
+    const grantBound = Number.isFinite(activeLease.remaining_ms) ? Math.floor(activeLease.remaining_ms) : command.timeout_ms;
+    if (grantBound < 100) throw new Error('coding lease expires too soon to execute command');
+    let deadlineAtMs = null;
+    if (executionDeadlineUtc !== null) {
+      if (typeof executionDeadlineUtc !== 'string') throw new Error('execution_deadline_utc must be an ISO timestamp or null');
+      deadlineAtMs = Date.parse(executionDeadlineUtc);
+      if (!Number.isFinite(deadlineAtMs)) throw new Error('execution_deadline_utc must be a valid ISO timestamp');
+    }
+    const deadlineBound = deadlineAtMs === null ? command.timeout_ms : Math.floor(deadlineAtMs - Date.now());
+    if (deadlineBound < 100) throw new Error('coding execution deadline expires too soon to execute command');
+    const effectiveTimeout = Math.min(requestedTimeout, command.timeout_ms, grantBound, deadlineBound);
     const argv = [...command.prefix_args, script.resolved, ...args];
     const startMs = performance.now();
     const child = spawn(command.executable, argv, {
@@ -512,10 +554,13 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
     collectBounded(child.stderr, command.max_output_bytes, stderrState, 'stderr', () => child.kill('SIGKILL'));
     let timedOut = false;
     let timer;
+    const timerDelay = deadlineAtMs === null
+      ? effectiveTimeout
+      : Math.max(1, Math.min(effectiveTimeout, Math.floor(deadlineAtMs - Date.now())));
     const completion = new Promise((resolve, reject) => {
       child.once('error', reject);
       child.once('close', (code, signal) => resolve({ code, signal }));
-      timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, effectiveTimeout);
+      timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timerDelay);
       timer.unref?.();
     });
     let result;
@@ -524,22 +569,23 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
     const stdoutBytes = Buffer.concat(stdoutState.chunks);
     const stderrBytes = Buffer.concat(stderrState.chunks);
     return {
-      lease, command_id: commandId, root_id: rootId,
+      lease: activeLease, command_id: commandId, root_id: rootId,
       executable_sha256: actualExecutableHash, script_sha256: actualScriptHash,
       exit_code: result.code, signal: result.signal, timed_out: timedOut,
-      timeout_ms: effectiveTimeout, elapsed_ms: Math.round((performance.now() - startMs) * 1000) / 1000,
+      timeout_ms: timerDelay, elapsed_ms: Math.round((performance.now() - startMs) * 1000) / 1000,
       stdout: decodeUtf8Strict(stdoutBytes), stderr: decodeUtf8Strict(stderrBytes),
       stdout_sha256: sha256Bytes(stdoutBytes), stderr_sha256: sha256Bytes(stderrBytes)
     };
   }
 
-  async function commandRun({ rootId, commandId, scriptPath, scriptSha256, args = [], cwd = '.', timeoutMs = null, receiptId = null, requestSha256 = null }) {
+  async function commandRun({ rootId, commandId, scriptPath, scriptSha256, args = [], cwd = '.', timeoutMs = null,
+    executionDeadlineUtc = null, preExecutionCheck = null, receiptId = null, requestSha256 = null }) {
     const request = requestSha256 ?? requestSha('coding_command_run', {
       root_id: rootId, command_id: commandId, script_path: scriptPath, script_sha256: scriptSha256,
       args, cwd, timeout_ms: timeoutMs
     });
     const started = new Date().toISOString();
-    const result = await runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args, cwd, timeoutMs });
+    const result = await runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args, cwd, timeoutMs, executionDeadlineUtc, preExecutionCheck });
     const signed = await signCodingReceipt(policy, signingKeyPath, result.lease, {
       operation: 'coding_command_run', request_sha256: request, root_id: rootId, command_id: commandId,
       script_path: scriptPath, executable_sha256: result.executable_sha256, script_sha256: result.script_sha256,
@@ -570,7 +616,8 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
   }
 
   async function benchmarkRun({ rootId, commandId, scriptPath, scriptSha256, args = [], cwd = '.', timeoutMs = null,
-    warmups = 1, iterations = 5, baselineMedianMs = null, maxRegressionPct = 5, receiptId = null, requestSha256 = null }) {
+    executionDeadlineUtc = null, preExecutionCheck = null, warmups = 1, iterations = 5, baselineMedianMs = null, maxRegressionPct = 5,
+    receiptId = null, requestSha256 = null }) {
     if (!Number.isInteger(warmups) || warmups < 0 || warmups > 3) throw new Error('warmups must be in [0, 3]');
     if (!Number.isInteger(iterations) || iterations < 1 || iterations > 20) throw new Error('iterations must be in [1, 20]');
     if (baselineMedianMs !== null && (!Number.isFinite(baselineMedianMs) || baselineMedianMs <= 0)) throw new Error('baseline_median_ms must be positive or null');
@@ -581,13 +628,13 @@ export function createCodingRuntime({ policy, signingKeyPath, verifyKeyPath }) {
       max_regression_pct: maxRegressionPct
     });
     for (let i = 0; i < warmups; i += 1) {
-      const warm = await runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args, cwd, timeoutMs });
+      const warm = await runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args, cwd, timeoutMs, executionDeadlineUtc, preExecutionCheck });
       if (warm.timed_out || warm.exit_code !== 0) throw new Error(`benchmark warmup failed exit=${String(warm.exit_code)} timed_out=${warm.timed_out}`);
     }
     const samples = [];
     let last = null;
     for (let i = 0; i < iterations; i += 1) {
-      last = await runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args, cwd, timeoutMs });
+      last = await runCommandOnce({ rootId, commandId, scriptPath, scriptSha256, args, cwd, timeoutMs, executionDeadlineUtc, preExecutionCheck });
       if (last.timed_out || last.exit_code !== 0) throw new Error(`benchmark iteration ${i + 1} failed exit=${String(last.exit_code)} timed_out=${last.timed_out}`);
       samples.push(last.elapsed_ms);
     }

package/src/durable-job-r44.mjs

@@ -0,0 +1,145 @@
+import { randomBytes } from 'node:crypto';
+import { lstat, mkdir, open, readFile, realpath, rename } from 'node:fs/promises';
+import path from 'node:path';
+
+const SCHEMA='deadbyte.durable-job-state.v1';
+const HEX64=/^[0-9a-f]{64}$/;
+const ID=/^[A-Za-z0-9._-]{1,64}$/;
+const LIFETIMES=new Set(['controller','session','persistent']);
+function insist(ok,message){if(!ok)throw new Error(message);}
+function now(){return new Date().toISOString();}
+async function atomicJson(file,value){
+  await mkdir(path.dirname(file),{recursive:true});
+  const bytes=Buffer.from(`${JSON.stringify(value,null,2)}\n`,'utf8');
+  const temp=`${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  const h=await open(temp,'wx');
+  try{await h.writeFile(bytes);await h.sync();}finally{await h.close();}
+  await rename(temp,file);
+}
+function validateJob(job,id){
+  insist(job&&typeof job==='object'&&!Array.isArray(job)&&job.job_id===id&&HEX64.test(id),'durable job identity invalid');
+  insist(LIFETIMES.has(job.lifetime),'durable job lifetime invalid');
+  insist(ID.test(job.profile_id??'')&&ID.test(job.root_id??''),'durable job profile/root invalid');
+  insist(['starting','running','terminated','failed','interrupted','orphaned'].includes(job.state),'durable job state invalid');
+  insist(typeof job.owner_instance_id==='string'&&job.owner_instance_id.length>=1,'durable job owner invalid');
+  if(job.state==='running'||job.state==='terminated'||job.state==='orphaned'){
+    insist(typeof job.handle_id==='string'&&job.handle_id.length>=1,'durable job handle invalid');
+    insist(Number.isInteger(job.pid)&&job.pid>0,'durable job pid invalid');
+    insist(typeof job.creation_id==='string'&&job.creation_id.length>=1,'durable job creation identity invalid');
+  }
+}
+function validateState(value){
+  insist(value&&typeof value==='object'&&!Array.isArray(value)&&value.schema===SCHEMA,'durable job state schema mismatch');
+  insist(value.jobs&&typeof value.jobs==='object'&&!Array.isArray(value.jobs),'durable jobs invalid');
+  for(const [id,job] of Object.entries(value.jobs))validateJob(job,id);
+  return value;
+}
+async function loadState(file){
+  try{
+    const st=await lstat(file);insist(st.isFile()&&!st.isSymbolicLink(),'durable job state must be real file');
+    let value;try{value=JSON.parse(await readFile(file,'utf8'));}catch(error){throw new Error(`durable job state JSON invalid: ${error.message}`);}
+    return validateState(value);
+  }catch(error){
+    if(error?.code!=='ENOENT')throw error;
+    return {schema:SCHEMA,jobs:{},updated_at_utc:now()};
+  }
+}
+function descriptor(provider){
+  insist(provider&&typeof provider.descriptor==='function'&&typeof provider.start==='function'&&typeof provider.reattach==='function'&&
+    typeof provider.status==='function'&&typeof provider.terminate==='function','durable job provider contract invalid');
+  const d=provider.descriptor();
+  insist(d&&['external-supervisor','controller-local'].includes(d.kind),'durable job provider kind invalid');
+  insist(typeof d.instance_id==='string'&&d.instance_id.length>=1&&d.instance_id.length<=256,'durable job provider instance invalid');
+  return d;
+}
+function validHandle(handle,profileId){
+  return handle&&typeof handle.handle_id==='string'&&handle.handle_id.length>=1&&Number.isInteger(handle.pid)&&handle.pid>0&&
+    typeof handle.creation_id==='string'&&handle.creation_id.length>=1&&handle.profile_id===profileId;
+}
+function publicJob(job){return structuredClone(job);}
+
+export async function createDurableJobSupervisorR44({stateDir,provider,ownerInstanceId}={}){
+  insist(typeof stateDir==='string'&&path.isAbsolute(stateDir),'durable job stateDir must be absolute');
+  insist(typeof ownerInstanceId==='string'&&ownerInstanceId.length>=1&&ownerInstanceId.length<=256,'durable job ownerInstanceId invalid');
+  const providerDesc=descriptor(provider);
+  await mkdir(stateDir,{recursive:true});const root=await realpath(stateDir),stateFile=path.join(root,'jobs.json');
+  let state=await loadState(stateFile);
+  let dirty=false;
+  for(const job of Object.values(state.jobs)){
+    if(['terminated','failed','interrupted','orphaned'].includes(job.state))continue;
+    if(job.state==='starting'){
+      job.state='interrupted';job.error_code='owner_restart_before_handle_commit';job.updated_at_utc=now();dirty=true;continue;
+    }
+    if(job.lifetime!=='persistent'){
+      if(job.owner_instance_id!==ownerInstanceId){
+        job.state='interrupted';job.error_code='owner_instance_changed';job.updated_at_utc=now();dirty=true;
+      }
+      continue;
+    }
+    if(providerDesc.kind!=='external-supervisor'){
+      job.state='orphaned';job.error_code='persistent_provider_not_external';job.updated_at_utc=now();dirty=true;continue;
+    }
+    let live=null;try{live=await provider.reattach({handle_id:job.handle_id,pid:job.pid,creation_id:job.creation_id,profile_id:job.profile_id});}catch{}
+    if(!validHandle(live,job.profile_id)||live.handle_id!==job.handle_id||live.pid!==job.pid||live.creation_id!==job.creation_id||live.state!=='running'){
+      job.state='orphaned';job.error_code='persistent_identity_mismatch';job.updated_at_utc=now();dirty=true;continue;
+    }
+    job.owner_instance_id=ownerInstanceId;job.provider_instance_id=providerDesc.instance_id;job.recovered=true;job.updated_at_utc=now();dirty=true;
+  }
+  if(dirty){state.updated_at_utc=now();await atomicJson(stateFile,state);}
+  else{try{await lstat(stateFile);}catch(error){if(error?.code==='ENOENT')await atomicJson(stateFile,state);else throw error;}}
+
+  let lock=Promise.resolve();
+  const withLock=fn=>{const run=lock.then(fn,fn);lock=run.catch(()=>{});return run;};
+  const persist=async()=>{state.updated_at_utc=now();await atomicJson(stateFile,state);};
+
+  async function start({lifetime,profileId,rootId,cwd='.',args=[]}={}){
+    insist(LIFETIMES.has(lifetime),'durable job lifetime invalid');
+    insist(ID.test(profileId??'')&&ID.test(rootId??''),'durable job profile/root invalid');
+    insist(typeof cwd==='string'&&cwd.length>=1&&cwd.length<=512,'durable job cwd invalid');
+    insist(Array.isArray(args)&&args.length<=64&&args.every(v=>typeof v==='string'&&v.length<=4096),'durable job args invalid');
+    if(lifetime==='persistent')insist(providerDesc.kind==='external-supervisor','persistent lifetime requires external supervisor');
+    const jobId=randomBytes(32).toString('hex');
+    await withLock(async()=>{
+      state.jobs[jobId]={job_id:jobId,lifetime,profile_id:profileId,root_id:rootId,cwd,args_sha256:null,state:'starting',
+        owner_instance_id:ownerInstanceId,provider_kind:providerDesc.kind,provider_instance_id:providerDesc.instance_id,recovered:false,
+        created_at_utc:now(),updated_at_utc:now()};
+      await persist();
+    });
+    let handle;
+    try{handle=await provider.start({job_id:jobId,lifetime,profile_id:profileId,root_id:rootId,cwd,args});}
+    catch(error){
+      return withLock(async()=>{const job=state.jobs[jobId];job.state='failed';job.error_code='provider_start_failed';job.error=String(error?.message??error);job.updated_at_utc=now();await persist();return publicJob(job);});
+    }
+    insist(validHandle(handle,profileId),'durable job provider returned invalid handle');
+    return withLock(async()=>{
+      const job=state.jobs[jobId];insist(job.state==='starting','durable job start state changed before handle commit');
+      Object.assign(job,{handle_id:handle.handle_id,pid:handle.pid,creation_id:handle.creation_id,state:handle.state==='running'?'running':'failed',updated_at_utc:now()});
+      if(job.state==='failed')job.error_code='provider_not_running_after_start';
+      await persist();return publicJob(job);
+    });
+  }
+  async function status({jobId}={}){
+    insist(HEX64.test(jobId??''),'durable job id invalid');
+    const job=state.jobs[jobId];insist(job,'unknown durable job');
+    if(job.state==='running'&&job.lifetime==='persistent'){
+      let live=null;try{live=await provider.status({handle_id:job.handle_id,pid:job.pid,creation_id:job.creation_id,profile_id:job.profile_id});}catch{}
+      if(!validHandle(live,job.profile_id)||live.handle_id!==job.handle_id||live.pid!==job.pid||live.creation_id!==job.creation_id){
+        await withLock(async()=>{job.state='orphaned';job.error_code='persistent_identity_mismatch';job.updated_at_utc=now();await persist();});
+      }else if(live.state==='terminated'){
+        await withLock(async()=>{job.state='terminated';job.updated_at_utc=now();await persist();});
+      }
+    }
+    return publicJob(job);
+  }
+  async function terminate({jobId}={}){
+    insist(HEX64.test(jobId??''),'durable job id invalid');
+    const job=state.jobs[jobId];insist(job,'unknown durable job');
+    if(['terminated','failed','interrupted','orphaned'].includes(job.state))return publicJob(job);
+    insist(job.handle_id&&job.pid&&job.creation_id,'durable job has no committed handle');
+    const live=await provider.terminate({handle_id:job.handle_id,pid:job.pid,creation_id:job.creation_id,profile_id:job.profile_id});
+    insist(validHandle(live,job.profile_id)&&live.handle_id===job.handle_id&&live.pid===job.pid&&live.creation_id===job.creation_id,'durable job terminate identity mismatch');
+    return withLock(async()=>{job.state='terminated';job.updated_at_utc=now();await persist();return publicJob(job);});
+  }
+  async function list(){return {status:'ok',jobs:Object.values(state.jobs).map(publicJob).sort((a,b)=>a.job_id.localeCompare(b.job_id))};}
+  return Object.freeze({start,status,terminate,list,state_file:stateFile,provider:providerDesc});
+}

package/src/external-job-provider-r44.mjs

@@ -0,0 +1,126 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { lstat, mkdir, open, readFile, realpath, rename, rm } from 'node:fs/promises';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const HEX64=/^[0-9a-f]{64}$/;
+const ID=/^[A-Za-z0-9._-]{1,64}$/;
+const sha=bytes=>createHash('sha256').update(bytes).digest('hex');
+function insist(ok,message){if(!ok)throw new Error(message);}
+async function atomicJson(file,value){
+  const bytes=Buffer.from(`${JSON.stringify(value,null,2)}\n`,'utf8');
+  const temp=`${file}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  const h=await open(temp,'wx');try{await h.writeFile(bytes);await h.sync();}finally{await h.close();}
+  await rename(temp,file);
+}
+async function hashFile(file,label){
+  const st=await lstat(file);insist(st.isFile()&&!st.isSymbolicLink(),`${label} must be real file`);
+  return sha(await readFile(file));
+}
+function inside(root,target){const rel=path.relative(root,target);return rel===''||(!rel.startsWith('..'+path.sep)&&rel!=='..'&&!path.isAbsolute(rel));}
+
+export async function createExternalJobProviderR44({
+  stateDir,nodeExecutable,nodeExecutableSha256,workerPath,workerSha256,roots={},profiles={}
+}={}){
+  insist(typeof stateDir==='string'&&path.isAbsolute(stateDir),'external supervisor stateDir must be absolute');
+  await mkdir(stateDir,{recursive:true});const root=await realpath(stateDir);
+  insist(typeof nodeExecutable==='string'&&path.isAbsolute(nodeExecutable)&&HEX64.test(nodeExecutableSha256??''),'external supervisor Node identity invalid');
+  insist(await hashFile(nodeExecutable,'Node executable')===nodeExecutableSha256,'external supervisor Node executable hash mismatch');
+  insist(typeof workerPath==='string'&&path.isAbsolute(workerPath)&&HEX64.test(workerSha256??''),'external supervisor worker identity invalid');
+  insist(await hashFile(workerPath,'worker')===workerSha256,'external supervisor worker hash mismatch');
+  const normalizedRoots={};
+  for(const [id,value] of Object.entries(roots)){
+    insist(ID.test(id)&&typeof value==='string'&&path.isAbsolute(value),'external supervisor root invalid');
+    const real=await realpath(value),st=await lstat(real);insist(st.isDirectory()&&!st.isSymbolicLink(),'external supervisor root must be real directory');normalizedRoots[id]=real;
+  }
+  const normalizedProfiles={};
+  for(const [id,p] of Object.entries(profiles)){
+    insist(ID.test(id)&&p&&typeof p==='object','external supervisor profile invalid');
+    insist(typeof p.executable==='string'&&path.isAbsolute(p.executable)&&HEX64.test(p.executable_sha256??''),'external supervisor profile executable invalid');
+    insist(await hashFile(p.executable,`profile ${id} executable`)===p.executable_sha256,`external supervisor profile ${id} executable hash mismatch`);
+    insist(Array.isArray(p.root_ids)&&p.root_ids.length>=1&&p.root_ids.every(r=>Object.hasOwn(normalizedRoots,r)),'external supervisor profile roots invalid');
+    insist(Array.isArray(p.prefix_args)&&p.prefix_args.length<=32&&p.prefix_args.every(v=>typeof v==='string'&&v.length<=8192),'external supervisor prefix args invalid');
+    insist(Number.isInteger(p.max_args)&&p.max_args>=0&&p.max_args<=64&&Number.isInteger(p.max_arg_bytes)&&p.max_arg_bytes>=1&&p.max_arg_bytes<=8192,'external supervisor profile bounds invalid');
+    normalizedProfiles[id]={...p};
+  }
+  const authPath=path.join(root,'supervisor-auth.json'),endpointPath=path.join(root,'supervisor-endpoint.json');
+  let token;
+  try{
+    const st=await lstat(authPath);insist(st.isFile()&&!st.isSymbolicLink(),'external supervisor auth must be real file');
+    const auth=JSON.parse(await readFile(authPath,'utf8'));insist(auth?.schema==='deadbyte.job-supervisor-auth.v1'&&HEX64.test(auth.token??''),'external supervisor auth invalid');token=auth.token;
+  }catch(error){
+    if(error?.code!=='ENOENT')throw error;
+    token=randomBytes(32).toString('hex');await atomicJson(authPath,{schema:'deadbyte.job-supervisor-auth.v1',token,created_at_utc:new Date().toISOString()});
+  }
+  async function endpoint(){
+    const st=await lstat(endpointPath);insist(st.isFile()&&!st.isSymbolicLink(),'external supervisor endpoint must be real file');
+    const value=JSON.parse(await readFile(endpointPath,'utf8'));
+    insist(value?.schema==='deadbyte.job-supervisor-endpoint.v1'&&value.host==='127.0.0.1'&&Number.isInteger(value.port)&&value.port>=1&&value.port<=65535&&HEX64.test(value.instance_id??''),'external supervisor endpoint invalid');
+    return value;
+  }
+  async function rpcWith(ep,op,args={},timeoutMs=5000){
+    return new Promise((resolve,reject)=>{
+      const socket=net.createConnection({host:ep.host,port:ep.port});let buffer='';let settled=false;
+      const finish=(error,value)=>{if(settled)return;settled=true;clearTimeout(timer);socket.destroy();error?reject(error):resolve(value);};
+      const timer=setTimeout(()=>finish(new Error('external supervisor RPC timeout')),timeoutMs);
+      socket.setEncoding('utf8');
+      socket.once('error',error=>finish(error));
+      socket.on('data',chunk=>{
+        buffer+=chunk;if(Buffer.byteLength(buffer,'utf8')>1024*1024){finish(new Error('external supervisor RPC response limit exceeded'));return;}
+        const nl=buffer.indexOf('\n');if(nl<0)return;
+        let response;try{response=JSON.parse(buffer.slice(0,nl));}catch(error){finish(error);return;}
+        if(response?.ok!==true){finish(new Error(response?.error??'external supervisor RPC failed'));return;}
+        finish(null,response.result);
+      });
+      socket.once('connect',()=>socket.write(JSON.stringify({token,op,args})+'\n'));
+    });
+  }
+  async function tryHello(){
+    try{const ep=await endpoint();const hello=await rpcWith(ep,'hello',{},1500);if(hello?.instance_id===ep.instance_id)return {ep,hello};}catch{}
+    return null;
+  }
+  let live=await tryHello();
+  if(!live){
+    await rm(endpointPath,{force:true}).catch(()=>{});
+    const child=spawn(nodeExecutable,[workerPath,'--state-dir',root],{cwd:path.dirname(workerPath),windowsHide:true,shell:false,detached:true,stdio:'ignore'});
+    child.unref();
+    const deadline=Date.now()+8000;
+    while(Date.now()<deadline){await new Promise(resolve=>setTimeout(resolve,50));live=await tryHello();if(live)break;}
+    insist(live,'external supervisor failed to become ready');
+  }
+  let descriptorValue={kind:'external-supervisor',instance_id:live.hello.instance_id};
+
+  async function call(op,args={},timeout=5000){
+    let ep=await endpoint();
+    try{return await rpcWith(ep,op,args,timeout);}
+    catch(error){
+      const refreshed=await tryHello();
+      if(!refreshed)throw error;
+      descriptorValue={kind:'external-supervisor',instance_id:refreshed.hello.instance_id};
+      return rpcWith(refreshed.ep,op,args,timeout);
+    }
+  }
+  async function resolveSpec(spec){
+    insist(spec&&ID.test(spec.profile_id??'')&&ID.test(spec.root_id??''),'external job spec identity invalid');
+    const profile=normalizedProfiles[spec.profile_id];insist(profile,'external job profile unknown');
+    insist(profile.root_ids.includes(spec.root_id),'external job root denied by profile');
+    insist(Array.isArray(spec.args)&&spec.args.length<=profile.max_args&&spec.args.every(v=>typeof v==='string'&&Buffer.byteLength(v,'utf8')<=profile.max_arg_bytes),'external job args exceed bounds');
+    const rootPath=normalizedRoots[spec.root_id];
+    insist(typeof spec.cwd==='string'&&spec.cwd.length>=1&&spec.cwd.length<=512&&!spec.cwd.includes('\0'),'external job cwd invalid');
+    const lexical=path.resolve(rootPath,spec.cwd);insist(inside(rootPath,lexical),'external job cwd escapes root');
+    const cwd=await realpath(lexical);insist(inside(rootPath,cwd),'external job cwd symlink escapes root');
+    insist(await hashFile(profile.executable,`profile ${spec.profile_id} executable`)===profile.executable_sha256,'external job executable hash changed');
+    return {job_id:spec.job_id,profile_id:spec.profile_id,executable:profile.executable,executable_sha256:profile.executable_sha256,
+      argv:[...profile.prefix_args,...spec.args],cwd};
+  }
+  return Object.freeze({
+    descriptor:()=>({...descriptorValue}),
+    start:async spec=>call('start',await resolveSpec(spec),8000),
+    reattach:async handle=>call('reattach',handle),
+    status:async handle=>call('status',handle),
+    terminate:async handle=>call('terminate',handle,5000),
+    shutdown:async()=>{try{return await call('shutdown',{},3000);}finally{await new Promise(resolve=>setTimeout(resolve,100));}},
+    state_dir:root
+  });
+}