deadbyte-mcp 0.8.9 → 0.9.0

package/src/autonomous-local-supervisor.mjs

@@ -0,0 +1,249 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { access, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { startAutonomousSupervisor } from './autonomous-supervisor.mjs';
+
+const execFileAsync=promisify(execFile);
+export const AUTONOMOUS_SUPERVISOR_OWNER_SCHEMA='deadbyte.autonomous-supervisor-owner.v1';
+const HEX64=/^[0-9a-f]{64}$/;
+const RECOVERY_OPERATIONS=Object.freeze(['status','resume','park','disarmautonomous','disarmcoding','disarmprocess','disarmhost']);
+const RECOVERY_SET=new Set(RECOVERY_OPERATIONS);
+
+function sha256Bytes(bytes){ return createHash('sha256').update(bytes).digest('hex'); }
+function isIso(value){ return typeof value==='string' && Number.isFinite(Date.parse(value)); }
+function samePath(a,b){
+  if(typeof a!=='string'||typeof b!=='string') return false;
+  return path.resolve(a).toLowerCase()===path.resolve(b).toLowerCase();
+}
+function assertOptions(options){
+  if(!options||typeof options!=='object'||Array.isArray(options)) throw new Error('supervisor options invalid');
+  if(typeof options.markerPath!=='string'||options.markerPath.length<3) throw new Error('supervisor markerPath invalid');
+  return path.resolve(options.markerPath);
+}
+function validateMarker(marker){
+  if(!marker||typeof marker!=='object'||Array.isArray(marker)) return false;
+  const keys=Object.keys(marker).sort();
+  const expected=['creation_time_utc','image_path','image_sha256','instance_nonce','pid','schema','started_at_utc'].sort();
+  if(JSON.stringify(keys)!==JSON.stringify(expected)) return false;
+  return marker.schema===AUTONOMOUS_SUPERVISOR_OWNER_SCHEMA && Number.isInteger(marker.pid) && marker.pid>0 &&
+    isIso(marker.creation_time_utc) && typeof marker.image_path==='string' && marker.image_path.length>3 &&
+    HEX64.test(marker.image_sha256??'') && HEX64.test(marker.instance_nonce??'') && isIso(marker.started_at_utc);
+}
+async function powershellPath(){
+  if(process.platform!=='win32') return null;
+  const systemRoot=process.env.SystemRoot || process.env.WINDIR;
+  if(systemRoot){
+    const candidate=path.join(systemRoot,'System32','WindowsPowerShell','v1.0','powershell.exe');
+    try { await access(candidate); return candidate; } catch {}
+  }
+  return 'powershell.exe';
+}
+
+export async function observeCurrentProcessIdentity(pid=process.pid){
+  if(!Number.isInteger(pid)||pid<=0) throw new Error('process pid invalid');
+  const shell=await powershellPath();
+  if(!shell) return null;
+  const script=`$ErrorActionPreference='Stop'; $p=Get-Process -Id ${pid} -ErrorAction Stop; $image=''; try { $image=[string]$p.Path } catch {}; if([string]::IsNullOrWhiteSpace($image)){ try { $c=Get-CimInstance Win32_Process -Filter 'ProcessId=${pid}' -ErrorAction Stop; $image=[string]$c.ExecutablePath } catch {} }; if([string]::IsNullOrWhiteSpace($image)){ exit 3 }; [pscustomobject]@{pid=[int]$p.Id;creation_time_utc=$p.StartTime.ToUniversalTime().ToString('o');image_path=[System.IO.Path]::GetFullPath($image)} | ConvertTo-Json -Compress`;
+  let stdout;
+  try {
+    ({stdout}=await execFileAsync(shell,['-NoProfile','-NonInteractive','-ExecutionPolicy','Bypass','-Command',script],{
+      windowsHide:true,timeout:10_000,maxBuffer:1024*1024,encoding:'utf8'
+    }));
+  } catch { return null; }
+  let parsed;
+  try { parsed=JSON.parse(String(stdout).trim()); } catch { return null; }
+  if(parsed?.pid!==pid||!isIso(parsed?.creation_time_utc)||typeof parsed?.image_path!=='string') return null;
+  const imagePath=path.resolve(parsed.image_path);
+  let imageBytes;
+  try { imageBytes=await readFile(imagePath); } catch { return null; }
+  return Object.freeze({
+    pid,creation_time_utc:new Date(parsed.creation_time_utc).toISOString(),
+    image_path:imagePath,image_sha256:sha256Bytes(imageBytes)
+  });
+}
+
+async function readMarker(markerPath){
+  let raw;
+  try { raw=await readFile(markerPath); }
+  catch(error){ if(error?.code==='ENOENT') return {exists:false}; throw error; }
+  let marker;
+  try { marker=JSON.parse(raw.toString('utf8')); }
+  catch { return {exists:true,raw,raw_sha256:sha256Bytes(raw),valid:false,marker:null}; }
+  return {exists:true,raw,raw_sha256:sha256Bytes(raw),valid:validateMarker(marker),marker};
+}
+function markerFor(identity){
+  return {
+    schema:AUTONOMOUS_SUPERVISOR_OWNER_SCHEMA,
+    pid:identity.pid,creation_time_utc:identity.creation_time_utc,image_path:identity.image_path,
+    image_sha256:identity.image_sha256,instance_nonce:randomBytes(32).toString('hex'),
+    started_at_utc:new Date().toISOString()
+  };
+}
+async function currentMarker(){
+  const identity=await observeCurrentProcessIdentity();
+  if(!identity) throw new Error('supervisor current Windows process identity unavailable');
+  return markerFor(identity);
+}
+
+export async function observeSupervisor(options={}){
+  const markerPath=assertOptions(options);
+  const stored=await readMarker(markerPath);
+  if(!stored.exists) return {status:'absent',live:false,reason:'no_owner',marker:null,marker_sha256:null};
+  if(!stored.valid) return {status:'unverified',live:false,reason:'marker_invalid',marker:stored.marker,marker_sha256:stored.raw_sha256};
+  const observed=await observeCurrentProcessIdentity(stored.marker.pid);
+  if(!observed) return {status:'stale',live:false,reason:'process_unobservable',marker:stored.marker,marker_sha256:stored.raw_sha256};
+  if(observed.creation_time_utc!==new Date(stored.marker.creation_time_utc).toISOString()) {
+    return {status:'stale',live:false,reason:'pid_reused',marker:stored.marker,observation:observed,marker_sha256:stored.raw_sha256};
+  }
+  if(!samePath(observed.image_path,stored.marker.image_path)||observed.image_sha256!==stored.marker.image_sha256) {
+    return {status:'stale',live:false,reason:'identity_mismatch',marker:stored.marker,observation:observed,marker_sha256:stored.raw_sha256};
+  }
+  return {status:'owned',live:true,reason:'live_verified_owner',marker:stored.marker,observation:observed,marker_sha256:stored.raw_sha256};
+}
+
+export async function claimSupervisor(options={}){
+  const markerPath=assertOptions(options);
+  const marker=await currentMarker();
+  await mkdir(path.dirname(markerPath),{recursive:true});
+  try {
+    await writeFile(markerPath,`${JSON.stringify(marker)}\n`,{flag:'wx',mode:0o600});
+  } catch(error){
+    if(error?.code==='EEXIST') throw new Error('supervisor owner marker already exists; takeover required');
+    throw error;
+  }
+  return {status:'claimed',instance_nonce:marker.instance_nonce,marker};
+}
+
+export async function takeoverSupervisor(options={}){
+  const markerPath=assertOptions(options);
+  const prior=await observeSupervisor({markerPath});
+  if(prior.live&&prior.reason==='live_verified_owner') throw new Error('supervisor takeover refused: live verified owner');
+  if(prior.reason==='no_owner') return claimSupervisor({markerPath});
+  const marker=await currentMarker();
+  const before=await readMarker(markerPath);
+  if(!before.exists||before.raw_sha256!==prior.marker_sha256) throw new Error('supervisor ownership changed during takeover');
+  const temp=path.join(path.dirname(markerPath),`.${path.basename(markerPath)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+  try {
+    await writeFile(temp,`${JSON.stringify(marker)}\n`,{flag:'wx',mode:0o600});
+    const check=await readMarker(markerPath);
+    if(!check.exists||check.raw_sha256!==prior.marker_sha256) throw new Error('supervisor ownership changed during takeover');
+    await rename(temp,markerPath);
+  } finally { await rm(temp,{force:true}).catch(()=>{}); }
+  return {status:'claimed',instance_nonce:marker.instance_nonce,marker,taken_over_reason:prior.reason};
+}
+
+export async function releaseSupervisor(options={}){
+  const markerPath=assertOptions(options);
+  if(typeof options.instanceNonce!=='string'||!HEX64.test(options.instanceNonce)) throw new Error('supervisor ownership nonce invalid');
+  const observed=await observeSupervisor({markerPath});
+  if(observed.reason==='no_owner') return {status:'absent'};
+  if(!observed.live||observed.reason!=='live_verified_owner') throw new Error(`supervisor ownership is not a live verified owner: ${observed.reason}`);
+  if(observed.marker.instance_nonce!==options.instanceNonce) throw new Error('supervisor ownership nonce mismatch');
+  if(observed.marker.pid!==process.pid) throw new Error('supervisor ownership belongs to another process');
+  const current=await observeCurrentProcessIdentity();
+  if(!current||current.creation_time_utc!==observed.observation.creation_time_utc||
+    !samePath(current.image_path,observed.observation.image_path)||current.image_sha256!==observed.observation.image_sha256) {
+    throw new Error('supervisor ownership current process identity mismatch');
+  }
+  const check=await readMarker(markerPath);
+  if(!check.exists||check.raw_sha256!==observed.marker_sha256) throw new Error('supervisor ownership changed before release');
+  await rm(markerPath,{force:false});
+  return {status:'released'};
+}
+
+export function validateSupervisorRecoveryRequest(request){
+  if(!request||typeof request!=='object'||Array.isArray(request)) throw new Error('supervisor recovery request invalid');
+  const keys=Object.keys(request);
+  if(keys.length!==1||keys[0]!=='operation') throw new Error('supervisor recovery request fields invalid');
+  if(typeof request.operation!=='string'||!RECOVERY_SET.has(request.operation)) throw new Error('supervisor recovery operation is not in allowlist');
+  return {operation:request.operation};
+}
+
+export async function runPinnedControllerOperation(options={}){
+  if(!options||typeof options!=='object'||Array.isArray(options)) throw new Error('supervisor controller options invalid');
+  const keys=Object.keys(options).sort();
+  if(JSON.stringify(keys)!==JSON.stringify(['controllerPath','controllerSha256','operation'])) {
+    throw new Error('supervisor controller options fields invalid');
+  }
+  if(typeof options.controllerPath!=='string'||options.controllerPath.length<3) throw new Error('supervisor controller path invalid');
+  if(typeof options.controllerSha256!=='string'||!HEX64.test(options.controllerSha256)) throw new Error('supervisor controller hash invalid');
+  const {operation}=validateSupervisorRecoveryRequest({operation:options.operation});
+  const controllerPath=path.resolve(options.controllerPath);
+  let bytes;
+  try { bytes=await readFile(controllerPath); }
+  catch(error){ throw new Error(`supervisor controller unavailable: ${error?.code??String(error)}`); }
+  const actual=sha256Bytes(bytes);
+  if(actual!==options.controllerSha256) throw new Error(`supervisor controller hash mismatch: expected ${options.controllerSha256}, found ${actual}`);
+  const shell=await powershellPath();
+  if(!shell) throw new Error('supervisor controller requires Windows PowerShell');
+  try {
+    const {stdout,stderr}=await execFileAsync(shell,['-NoProfile','-NonInteractive','-ExecutionPolicy','Bypass','-File',controllerPath,operation],{
+      windowsHide:true,timeout:120_000,maxBuffer:4*1024*1024,encoding:'utf8'
+    });
+    return {exit_code:0,stdout:String(stdout??''),stderr:String(stderr??'')};
+  } catch(error) {
+    return {exit_code:Number.isInteger(error?.code)?error.code:1,stdout:String(error?.stdout??''),stderr:String(error?.stderr??error?.message??'')};
+  }
+}
+
+function parseRecoveryStatus(stdout){
+  const text=String(stdout??'');
+  const state=text.match(/^DEADBYTE MCP\s*=\s*(ONLINE|PARKED|OFFLINE|DEGRADED)\s*$/mi)?.[1]??null;
+  const authority={
+    process:text.match(/^Process plane\s*:\s*(ARMED|DISARMED|UNCONFIGURED)\b/mi)?.[1]??null,
+    coding:text.match(/^Coding plane\s*:\s*(ARMED|DISARMED|UNCONFIGURED)\b/mi)?.[1]??null,
+    autonomous:text.match(/^Autonomous\s*:\s*(ARMED|DISARMED|UNCONFIGURED)\b/mi)?.[1]??null,
+    host:text.match(/^Host plane\s*:\s*(ARMED|DISARMED|UNCONFIGURED)\b/mi)?.[1]??null
+  };
+  return {runtime_state:state,authority};
+}
+
+export async function recoverManagedRuntime({runControllerOperation}={}){
+  if(typeof runControllerOperation!=='function') throw new Error('supervisor recovery requires controller runner');
+  const operations=['resume','disarmautonomous','disarmcoding','disarmprocess','disarmhost','status'];
+  const results=[];
+  for(const operation of operations){
+    const request=validateSupervisorRecoveryRequest({operation});
+    const result=await runControllerOperation(request);
+    if(!result||result.exit_code!==0) throw new Error(`supervisor recovery operation '${operation}' failed`);
+    results.push({operation,...result});
+  }
+  const observed=parseRecoveryStatus(results.at(-1)?.stdout);
+  if(observed.runtime_state!=='ONLINE') throw new Error(`supervisor recovery expected ONLINE, observed ${observed.runtime_state??'unknown'}`);
+  for(const [plane,value] of Object.entries(observed.authority)) {
+    if(value!=='DISARMED') throw new Error(`supervisor recovery requires ${plane} DISARMED, observed ${value??'unknown'}`);
+  }
+  return {status:'recovered',...observed,operations:results.map(item=>item.operation)};
+}
+
+export async function startLocalSupervisorHost({runtime,policy=runtime?.policy,markerPath,idleDelayMs=750,maxCycles=32,logger=console,continuous=true}={}){
+  if(!runtime||!policy) throw new Error('local supervisor host requires runtime + policy');
+  const observed=await observeSupervisor({markerPath});
+  const claim=observed.reason==='no_owner'
+    ? await claimSupervisor({markerPath})
+    : await takeoverSupervisor({markerPath});
+  let supervisor;
+  try {
+    supervisor=startAutonomousSupervisor({runtime,policy,idleDelayMs,maxCycles,logger,continuous});
+  } catch(error) {
+    await releaseSupervisor({markerPath,instanceNonce:claim.instance_nonce}).catch(()=>{});
+    throw error;
+  }
+  let stopped=false;
+  return Object.freeze({
+    marker_path:path.resolve(markerPath),instance_nonce:claim.instance_nonce,supervisor,
+    get running(){ return !stopped&&supervisor.running; },
+    async scanNow(){ if(stopped) throw new Error('local supervisor host stopped'); return supervisor.scanNow(); },
+    async stop(){
+      if(stopped) return {status:'stopped'};
+      stopped=true;
+      await supervisor.stop();
+      await releaseSupervisor({markerPath,instanceNonce:claim.instance_nonce});
+      return {status:'stopped'};
+    }
+  });
+}
+
+export const AUTONOMOUS_SUPERVISOR_RECOVERY_OPERATIONS=RECOVERY_OPERATIONS;

package/src/autonomous-loop-state.mjs

@@ -0,0 +1,304 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+import { activePlanStep } from './autonomous-plan.mjs';
+
+export const AUTONOMOUS_LOOP_STATE_SCHEMA = 'deadbyte.autonomous-loop-state.v2';
+export const AUTONOMOUS_LOOP_PHASES = Object.freeze([
+  'PLAN','INSPECT','ACT','VERIFY','CRITIC','REPAIR','RELEASE','WAITING','SUCCEEDED','FAILED'
+]);
+
+const PHASES = new Set(AUTONOMOUS_LOOP_PHASES);
+const LEGACY_PHASES = new Map([
+  ['PLANNING','PLAN'],['INSPECTING','INSPECT'],['ACTING','ACT'],['VERIFYING','VERIFY'],
+  ['REPLANNING','REPAIR'],['WAITING','WAITING'],['COMPLETE','SUCCEEDED']
+]);
+const HEX64 = /^[0-9a-f]{64}$/;
+const ZERO_HASH = '0'.repeat(64);
+const FAILURE_CLASSES = new Set([
+  'verification_failure','stale_precondition','no_progress','insufficient_proof','provider_failure','other'
+]);
+const MUTABLE_TERMINAL_EVENTS = new Set([
+  'plan_created','plan_replanned','action_started','action_completed','inspection_completed','inspect_completed',
+  'progress_judged','critic_classified','repair_started','repair_completed','waiting_entered','waiting_resumed',
+  'native_diff_committed','step_completed','phase_changed'
+]);
+
+function sha256Object(value) {
+  return createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+}
+function hash(value,label) {
+  if (typeof value !== 'string' || !HEX64.test(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+function requireObject(value,label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+function requireText(value,label,max=1024) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > max) throw new Error(`${label} invalid`);
+  return value;
+}
+function normalizePhase(value,label) {
+  const normalized = LEGACY_PHASES.get(value) ?? value;
+  if (!PHASES.has(normalized)) throw new Error(`${label} invalid`);
+  return normalized;
+}
+function isLegacyPhase(value) { return LEGACY_PHASES.has(value) && !PHASES.has(value); }
+function terminal(phase) { return phase === 'SUCCEEDED' || phase === 'FAILED'; }
+
+function normalizedPlanForRepair(plan) {
+  if (!plan) return null;
+  return {
+    schema:plan.schema ?? null,
+    title:plan.title ?? null,
+    steps:Array.isArray(plan.steps) ? plan.steps.map(step => ({
+      step_id:step.step_id,
+      intent:step.intent,
+      status:step.status,
+      ...(Array.isArray(step.evidence) ? {evidence:step.evidence} : {})
+    })) : []
+  };
+}
+
+export function repairFingerprint({plan,hypothesis}) {
+  requireText(hypothesis,'repair hypothesis',2048);
+  return sha256Object({
+    schema:'deadbyte.autonomous-repair-fingerprint.v1',
+    hypothesis,
+    plan:normalizedPlanForRepair(plan)
+  });
+}
+
+function setPlan(state,plan,{replanned=false}={}) {
+  requireObject(plan,'loop plan');
+  const current = activePlanStep(plan);
+  state.plan = structuredClone(plan);
+  state.plan_id = hash(plan.plan_id,'loop plan_id');
+  if (!Number.isInteger(plan.plan_version) || plan.plan_version < 1) throw new Error('loop plan_version invalid');
+  state.plan_version = plan.plan_version;
+  state.current_step = current ? structuredClone(current) : null;
+  if (replanned) state.replan_count += 1;
+}
+
+function setPhase(state,rawFrom,rawTo) {
+  const from=normalizePhase(rawFrom,'loop phase from');
+  const to=normalizePhase(rawTo,'loop phase to');
+  if (state.phase !== from) throw new Error(`loop phase mismatch: journal says ${from} but derived phase is ${state.phase}`);
+  if (terminal(state.phase) && to !== state.phase) throw new Error(`loop ${state.phase} phase is terminal`);
+  const legacyTransition=isLegacyPhase(rawFrom)||isLegacyPhase(rawTo);
+  if (!legacyTransition && from === 'REPAIR' && ['ACT','INSPECT'].includes(to)) {
+    if (!state.repair?.completed || state.repair.previous_fingerprint === state.repair.repair_fingerprint) {
+      throw new Error('loop REPAIR requires repair fingerprint change before another ACT/INSPECT');
+    }
+  }
+  state.phase=to;
+  if (to !== 'WAITING') {
+    state.wait_reason=null;
+    state.pending_approval=false;
+  }
+}
+
+function classifyCritic(payload) {
+  const failureClass=requireText(payload.failure_class,'loop critic failure_class',64);
+  if (!FAILURE_CLASSES.has(failureClass)) throw new Error('loop critic failure_class invalid');
+  return {
+    failure_class:failureClass,
+    evidence_fingerprint:hash(payload.evidence_fingerprint,'loop critic evidence_fingerprint'),
+    detail:requireText(payload.detail,'loop critic detail',1024)
+  };
+}
+
+function repairStart(state,payload) {
+  if (state.phase !== 'REPAIR') throw new Error(`loop repair_started requires REPAIR phase, got ${state.phase}`);
+  const hypothesis=requireText(payload.hypothesis,'loop repair hypothesis',2048);
+  const previous=hash(payload.previous_fingerprint,'loop repair previous_fingerprint');
+  const expected=repairFingerprint({plan:state.plan,hypothesis});
+  if (previous !== expected) throw new Error('loop repair previous fingerprint mismatch');
+  state.repair={previous_fingerprint:previous,repair_fingerprint:null,hypothesis,completed:false};
+}
+
+function repairComplete(state,payload) {
+  if (state.phase !== 'REPAIR') throw new Error(`loop repair_completed requires REPAIR phase, got ${state.phase}`);
+  if (!state.repair) throw new Error('loop repair_completed requires repair_started');
+  const previous=hash(payload.previous_fingerprint,'loop repair completed previous_fingerprint');
+  const next=hash(payload.repair_fingerprint,'loop repair completed repair_fingerprint');
+  const hypothesis=requireText(payload.hypothesis,'loop repair completed hypothesis',2048);
+  if (previous !== state.repair.previous_fingerprint) throw new Error('loop repair previous fingerprint changed');
+  const expected=repairFingerprint({plan:state.plan,hypothesis});
+  if (next !== expected) throw new Error('loop repair fingerprint does not bind current plan/hypothesis');
+  if (next === previous) throw new Error('loop repair fingerprint must change before another ACT');
+  state.repair={previous_fingerprint:previous,repair_fingerprint:next,hypothesis,completed:true};
+}
+
+export function deriveLoopState(goal,events) {
+  requireObject(goal,'loop goal');
+  const goalId=hash(goal.goal_id,'loop goal_id');
+  if (!Array.isArray(events)) throw new Error('loop events must be an array');
+  const state={
+    schema:AUTONOMOUS_LOOP_STATE_SCHEMA,
+    phase:'PLAN',
+    plan:null,
+    plan_id:null,
+    plan_version:null,
+    current_step:null,
+    mutation_epoch:0,
+    planner_round:0,
+    replan_count:0,
+    pending_action:null,
+    pending_approval:false,
+    progress:null,
+    critic:null,
+    repair:null,
+    wait_reason:null,
+    evidence_head_sha256:null,
+    journal_head_sha256:ZERO_HASH
+  };
+
+  for (let index=0; index<events.length; index+=1) {
+    const event=requireObject(events[index],`loop event ${index+1}`);
+    if (event.goal_id !== goalId) throw new Error(`loop event ${index+1} goal mismatch`);
+    if (event.seq !== index+1) throw new Error(`loop event sequence mismatch at ${index+1}`);
+    hash(event.event_sha256,`loop event ${index+1} hash`);
+    const payload=event.payload===undefined?{}:requireObject(event.payload,`loop event ${index+1} payload`);
+
+    if (terminal(state.phase) && event.type !== 'release_completed' && event.type !== 'goal_cancelled') {
+      if (event.type === 'phase_changed') {
+        const to=normalizePhase(payload.to,'loop terminal phase to');
+        if (to !== state.phase) throw new Error(`loop ${state.phase} phase is terminal`);
+      } else if (MUTABLE_TERMINAL_EVENTS.has(event.type)) {
+        throw new Error(`loop ${state.phase} phase is terminal; event '${event.type}' is mutable`);
+      }
+    }
+
+    switch (event.type) {
+      case 'plan_created':
+        setPlan(state,payload.plan);
+        break;
+      case 'plan_replanned':
+        setPlan(state,payload.plan,{replanned:true});
+        break;
+      case 'step_completed':
+        if (payload.plan) setPlan(state,payload.plan);
+        break;
+      case 'phase_changed':
+        setPhase(state,payload.from,payload.to);
+        break;
+      case 'inspection_completed':
+      case 'inspect_completed':
+        if (payload.evidence_head_sha256 !== undefined) {
+          state.evidence_head_sha256=hash(payload.evidence_head_sha256,'loop evidence head');
+        }
+        break;
+      case 'action_started': {
+        const actionId=hash(payload.action_id,'loop action_id');
+        const requestSha=hash(payload.request_sha256,'loop action request_sha256');
+        if (state.pending_action) throw new Error('loop action_started while another action is pending');
+        state.pending_action={...structuredClone(payload),action_id:actionId,request_sha256:requestSha};
+        break;
+      }
+      case 'action_completed':
+        if (state.pending_action && payload.action_id !== state.pending_action.action_id) {
+          throw new Error('loop action completion identity mismatch');
+        }
+        if (payload.action_id !== undefined) hash(payload.action_id,'loop completed action_id');
+        state.pending_action=null;
+        break;
+      case 'action_reconciled':
+        if (payload.action_id !== undefined) hash(payload.action_id,'loop reconciled action_id');
+        break;
+      case 'progress_judged':
+        if (!['progress','stalled','regressed'].includes(payload.verdict)) throw new Error('loop progress verdict invalid');
+        state.progress=structuredClone(payload);
+        break;
+      case 'critic_classified':
+        state.critic=classifyCritic(payload);
+        break;
+      case 'repair_started':
+        repairStart(state,payload);
+        break;
+      case 'repair_completed':
+        repairComplete(state,payload);
+        break;
+      case 'waiting_entered':
+        state.phase='WAITING';
+        state.wait_reason=requireText(payload.reason,'loop wait reason');
+        state.pending_approval=payload.requires_approval===true;
+        break;
+      case 'waiting_resumed': {
+        if (state.phase !== 'WAITING') throw new Error('loop waiting_resumed outside WAITING phase');
+        const resumed=payload.to===undefined?'PLAN':normalizePhase(payload.to,'loop resume phase');
+        if (resumed === 'WAITING' || terminal(resumed)) throw new Error('loop waiting resume target invalid');
+        state.phase=resumed;
+        state.wait_reason=null;
+        state.pending_approval=false;
+        break;
+      }
+      case 'planner_requested':
+      case 'planner_decision':
+        if (Number.isInteger(payload.planner_round) && payload.planner_round >= 0) {
+          state.planner_round=Math.max(state.planner_round,payload.planner_round);
+        }
+        break;
+      case 'native_diff_committed':
+        if (!Number.isInteger(payload.mutation_epoch) || payload.mutation_epoch < state.mutation_epoch) {
+          throw new Error('loop mutation_epoch invalid');
+        }
+        state.mutation_epoch=payload.mutation_epoch;
+        break;
+      case 'goal_paused':
+        state.phase='WAITING';
+        state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'paused';
+        state.pending_approval=true;
+        break;
+      case 'goal_resumed':
+        if (state.phase === 'WAITING') {
+          state.phase='PLAN';
+          state.wait_reason=null;
+          state.pending_approval=false;
+        }
+        break;
+      case 'goal_cancelled':
+        state.phase='FAILED';
+        state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'cancelled';
+        state.pending_approval=false;
+        state.pending_action=null;
+        break;
+      case 'goal_failed':
+        state.phase='FAILED';
+        state.wait_reason=typeof payload.reason==='string'&&payload.reason.length>0?payload.reason:'failed';
+        state.pending_approval=false;
+        state.pending_action=null;
+        break;
+      case 'release_completed':
+        state.phase='SUCCEEDED';
+        state.wait_reason=null;
+        state.pending_approval=false;
+        state.pending_action=null;
+        break;
+      default:
+        break;
+    }
+    state.journal_head_sha256=event.event_sha256;
+  }
+
+  if (state.plan) state.current_step=activePlanStep(state.plan);
+  return state;
+}
+
+export function deriveTodoProjection(goal,events) {
+  const state=deriveLoopState(goal,events);
+  return Object.freeze({
+    schema:'deadbyte.autonomous-todo-projection.v1',
+    goal_id:goal.goal_id,
+    phase:state.phase,
+    plan_id:state.plan_id,
+    plan_version:state.plan_version,
+    journal_head_sha256:state.journal_head_sha256,
+    items:Object.freeze((state.plan?.steps ?? []).map(step => Object.freeze({
+      step_id:step.step_id,
+      intent:step.intent,
+      status:step.status,
+      ...(Array.isArray(step.evidence) ? {evidence:structuredClone(step.evidence)} : {})
+    })))
+  });
+}

package/src/autonomous-output-contracts.mjs

@@ -4,6 +4,24 @@ const hex64 = z.string().regex(/^[0-9a-f]{64}$/);
 const goalId = hex64;
 const jsonObject = z.record(z.string(),z.json());
 const goalState = z.enum(['pending','running','paused','cancelled','succeeded']);
+const loopPhase = z.enum(['PLANNING','INSPECTING','ACTING','VERIFYING','REPLANNING','WAITING','COMPLETE']);
+const loopStep = z.strictObject({
+  step_id:z.string().regex(/^[A-Za-z0-9._-]{1,64}$/), intent:z.string().min(1).max(512), status:z.literal('active')
+});
+const loopProgress = z.strictObject({
+  verdict:z.enum(['progress','stalled','regressed']), score:z.number(),
+  reason_codes:z.array(z.string().regex(/^[A-Za-z0-9._-]{1,64}$/)).max(32), fingerprint:hex64
+});
+const loopPendingAction = z.strictObject({
+  action_id:hex64, request_sha256:hex64, kind:z.string().regex(/^[A-Za-z0-9._-]{1,64}$/)
+});
+const publicLoopSchema = z.strictObject({
+  schema:z.literal('deadbyte.autonomous-loop-state.v1'), phase:loopPhase,
+  plan_id:hex64.nullable(), plan_version:z.number().int().min(1).nullable(),
+  current_step:loopStep.nullable(), replan_count:z.number().int().min(0),
+  progress:loopProgress.nullable(), pending_action:loopPendingAction.nullable(),
+  pending_approval:z.boolean(), wait_reason:z.string().min(1).max(1024).nullable()
+});
 function requireFields(value,ctx,fields) {
   for (const field of fields) if (value[field] === undefined) ctx.addIssue({ code:'custom', path:[field], message:`${field} is required` });
 }
@@ -72,7 +90,8 @@ export const autonomousGoalSubmitOutputSchema = statusContract({
 const runShape = Object.fromEntries(Object.entries(derivedShape).map(([key,schema]) => [key,schema.optional()]));
 export const autonomousGoalRunOutputSchema = z.strictObject({
   status:z.enum(['terminal','paused','cancelled','completed','yielded','running','input_required','failed']), error:z.string().optional(),
-  goal_id:goalId.optional(), release:jsonObject.optional(), planner_request:jsonObject.optional(), ...runShape
+  goal_id:goalId.optional(), release:jsonObject.optional(), planner_request:jsonObject.optional(), loop:publicLoopSchema.optional(),
+  cycles:z.number().int().min(1).max(32).optional(), ...runShape
 }).superRefine((value,ctx) => {
   if (value.error !== undefined) { if (value.status !== 'failed') ctx.addIssue({code:'custom',path:['error'],message:'error wrapper requires failed'}); return; }
   requireFields(value,ctx,['goal_id',...Object.keys(derivedShape)]);
@@ -81,7 +100,7 @@ export const autonomousGoalRunOutputSchema = z.strictObject({
 export const autonomousGoalStatusOutputSchema = statusContract({
   statuses:['ok','failed'], success:['ok'], required:['goal_id','goal_sha256','title','root_id','journal_verified',...Object.keys(derivedShape)],
   shape:{ goal_id:goalId.optional(), goal_sha256:hex64.optional(), title:z.string().optional(), root_id:z.string().optional(),
-    journal_verified:z.literal(true).optional(), ...runShape }
+    journal_verified:z.literal(true).optional(), loop:publicLoopSchema.optional(), ...runShape }
 });
 export const autonomousGoalEventsOutputSchema = statusContract({
   statuses:['ok','failed'], success:['ok'], required:['goal_id','journal_verified','journal_head_sha256','events'],
@@ -94,7 +113,7 @@ export const autonomousGoalCancelOutputSchema = statusContract({
 });
 export const autonomousGoalApproveOutputSchema = statusContract({
   statuses:['terminal','approved','rejected','failed'], success:['terminal','approved','rejected'], required:['goal_id','state'],
-  shape:{ goal_id:goalId.optional(), state:goalState.optional() }
+  shape:{ goal_id:goalId.optional(), state:goalState.optional(), loop:publicLoopSchema.optional() }
 });
 export const autonomousReleaseGateOutputSchema = statusContract({
   statuses:['blocked','paused','failed','passed','existing','error'], success:['blocked','paused','failed','passed','existing'],