deadbyte-mcp 0.15.1 → 0.15.3

package/src/runtime-update.mjs

@@ -1,5 +1,5 @@
 import { createHash, createPrivateKey, createPublicKey, randomBytes, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { lstat, mkdir, open, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
@@ -22,6 +22,7 @@ const HEX64=/^[0-9a-f]{64}$/;
 const SEMVER=/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const RECEIPT_DOMAIN=Buffer.from('DEADBYTE-R27-SLOT-UPDATE-V1\0','utf8');
 const UPDATE_SCHEMA='deadbyte.r27-slot-update-receipt.v1';
+const HANDOFF_SCHEMA='deadbyte.r27-slot-update-handoff.v1';
 const FAILURE_SCHEMA='deadbyte.r27-slot-update-failure.v1';
 const ROLLBACK_SCHEMA='deadbyte.r31-slot-rollback-receipt.v1';
 const DEFAULT_STATE_ROOT=path.join(os.homedir(),'.deadbyte-mcp');
@@ -45,8 +46,8 @@ 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,enableDesktop:false,enableAutonomousSupervisor:false,cloudTransport:null,bridgeBootstrap:null,processPolicyBootstrap:null,hostPolicyBootstrap:null,desktopPolicyBootstrap:null,semanticLspBootstrap:null,hostCommandPins:[]};
-  const cloud={},bridge={},processPolicy={},hostPolicy={},desktopPolicy={},semanticLsp={},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,enableDesktop:false,enableAutonomousSupervisor:false,cloudTransport:null,bridgeBootstrap:null,processPolicyBootstrap:null,hostPolicyBootstrap:null,codingPolicyBootstrap:null,desktopPolicyBootstrap:null,semanticLspBootstrap:null,hostCommandPins:[]};
+  const cloud={},bridge={},processPolicy={},hostPolicy={},codingPolicy={},desktopPolicy={},semanticLsp={},seen=new Set(),hostPinIds=new Set();
   const bridgeFlags=new Map([
     ['--bridge-root','root'],['--bridge-script-sha256','scriptSha256']
   ]);
@@ -56,6 +57,9 @@ export function parseUpdateArgs(argv){
   const hostPolicyFlags=new Map([
     ['--host-policy','path'],['--host-policy-sha256','sha256']
   ]);
+  const codingPolicyFlags=new Map([
+    ['--coding-policy','path'],['--coding-policy-sha256','sha256']
+  ]);
   const desktopPolicyFlags=new Map([
     ['--desktop-policy','path'],['--desktop-policy-sha256','sha256']
   ]);
@@ -67,7 +71,7 @@ export function parseUpdateArgs(argv){
     ['--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(),...hostPolicyFlags.keys(),...desktopPolicyFlags.keys(),...semanticLspFlags.keys(),...cloudFlags.keys()]);
+  const valued=new Set(['--stage','--development-root','--expected-version','--expected-manifest','--source-root','--host-command-pin',...bridgeFlags.keys(),...processPolicyFlags.keys(),...hostPolicyFlags.keys(),...codingPolicyFlags.keys(),...desktopPolicyFlags.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'||arg==='--enable-desktop'||arg==='--enable-autonomous-supervisor'){
@@ -103,6 +107,7 @@ export function parseUpdateArgs(argv){
     else if(bridgeFlags.has(arg)) bridge[bridgeFlags.get(arg)]=value;
     else if(processPolicyFlags.has(arg)) processPolicy[processPolicyFlags.get(arg)]=value;
     else if(hostPolicyFlags.has(arg)) hostPolicy[hostPolicyFlags.get(arg)]=value;
+    else if(codingPolicyFlags.has(arg)) codingPolicy[codingPolicyFlags.get(arg)]=value;
     else if(desktopPolicyFlags.has(arg)) desktopPolicy[desktopPolicyFlags.get(arg)]=value;
     else if(semanticLspFlags.has(arg)) semanticLsp[semanticLspFlags.get(arg)]=value;
     else cloud[cloudFlags.get(arg)]=value;
@@ -132,6 +137,13 @@ export function parseUpdateArgs(argv){
     if(!HEX64.test(sha256)) throw new Error('host policy SHA-256 must be lowercase hex');
     out.hostPolicyBootstrap={path:path.resolve(hostPolicy.path),sha256};
   }
+  const codingPolicyFields=[...codingPolicyFlags.values()],codingPolicyPresent=codingPolicyFields.filter(key=>codingPolicy[key]!==undefined);
+  if(codingPolicyPresent.length!==0&&codingPolicyPresent.length!==codingPolicyFields.length) throw new Error('coding policy bootstrap requires path plus SHA-256 as one pair');
+  if(codingPolicyPresent.length===codingPolicyFields.length){
+    const sha256=String(codingPolicy.sha256).toLowerCase();
+    if(!HEX64.test(sha256)) throw new Error('coding policy SHA-256 must be lowercase hex');
+    out.codingPolicyBootstrap={path:path.resolve(codingPolicy.path),sha256};
+  }
   const desktopPolicyFields=[...desktopPolicyFlags.values()],desktopPolicyPresent=desktopPolicyFields.filter(key=>desktopPolicy[key]!==undefined);
   if(desktopPolicyPresent.length!==0&&desktopPolicyPresent.length!==desktopPolicyFields.length) throw new Error('desktop policy bootstrap requires path plus SHA-256 as one pair');
   if(desktopPolicyPresent.length===desktopPolicyFields.length){
@@ -358,6 +370,18 @@ export async function prepareHostPolicyBootstrap(bootstrap){
   return {...pinned,policy};
 }
 
+export async function prepareCodingPolicyBootstrap(bootstrap){
+  if(!bootstrap) return null;
+  const pinned=await verifyPinnedRegularFile(bootstrap.path,bootstrap.sha256,'coding policy');
+  const policy=await readJson(pinned.path);
+  if(policy?.schema!=='deadbyte.coding-policy.v1'||policy?.enabled!==true||
+     !policy?.roots||typeof policy.roots!=='object'||Array.isArray(policy.roots)||
+     !policy?.commands||typeof policy.commands!=='object'||Array.isArray(policy.commands)) {
+    throw new Error('coding policy schema/enabled/roots/commands mismatch');
+  }
+  return {...pinned,policy};
+}
+
 export async function prepareDesktopPolicyBootstrap(bootstrap){
   if(!bootstrap) return null;
   const pinned=await verifyPinnedRegularFile(bootstrap.path,bootstrap.sha256,'desktop policy');
@@ -769,13 +793,20 @@ async function workspacePlan(currentWorkspace,stateRoot){
 }
 async function applyWorkspacePlan(plan){
   if(plan.mode==='existing'||plan.mode==='target-existing') return plan;
+  const sourceExists=existsSync(plan.source),targetExists=existsSync(plan.target);
+  if(plan.mode==='create'){
+    if(targetExists){ plan.created=true; return plan; }
+    await mkdir(path.dirname(plan.target),{recursive:true});
+    await mkdir(plan.target,{recursive:false}); plan.created=true; return plan;
+  }
+  if(targetExists&&!sourceExists){ plan.moved=true; return plan; }
+  if(sourceExists&&targetExists) throw new Error('workspace migration conflict: both source and stable target exist ('+plan.source+', '+plan.target+')');
   await mkdir(path.dirname(plan.target),{recursive:true});
-  if(plan.mode==='create'){ await mkdir(plan.target,{recursive:false}); plan.created=true; return plan; }
   await rename(plan.source,plan.target); plan.moved=true; return plan;
 }
 async function rollbackWorkspacePlan(plan){
-  if(plan.moved&&existsSync(plan.target)&&!existsSync(plan.source)){ await rename(plan.target,plan.source); plan.moved=false; return true; }
-  if(plan.created&&existsSync(plan.target)){ await rm(plan.target,{recursive:true,force:true}); plan.created=false; return true; }
+  if(plan.mode==='rename'&&existsSync(plan.target)&&!existsSync(plan.source)){ await rename(plan.target,plan.source); plan.moved=false; return true; }
+  if(plan.mode==='create'&&existsSync(plan.target)){ await rm(plan.target,{recursive:true,force:true}); plan.created=false; return true; }
   return false;
 }
 async function launcherPlan(stateRoot){
@@ -792,7 +823,9 @@ async function installLaunchers(plan){
   return plan;
 }
 async function rollbackLaunchers(plan){
-  if(!plan?.installed) return false;
+  if(!plan) return false;
+  const touched=plan.installed===true || (existsSync(plan.ps1)&&sha256Bytes(await readFile(plan.ps1))===plan.launcher_sha256);
+  if(!touched) return false;
   await restoreFile(plan.ps1,plan.snapshots.ps1); await restoreFile(plan.cmd,plan.snapshots.cmd); await restoreFile(plan.top,plan.snapshots.top);
   plan.installed=false; return true;
 }
@@ -872,7 +905,13 @@ export function verifySlotUpdateEnvelope(envelope,publicKey){
 }
 async function writeEnvelope(file,body,key){ const envelope=signEnvelope(body,key); await atomicBytes(file,Buffer.from(`${JSON.stringify(envelope,null,2)}\n`,'utf8')); return envelope; }
 async function writeState(file,state,phase,extra={}){
-  Object.assign(state,extra,{phase,updated_at_utc:new Date().toISOString()});
+  let observed=null;
+  try { observed=await readJson(file); } catch(error) { if(error?.code!=='ENOENT') throw error; }
+  const observedRank=phaseRank(observed?.phase);
+  const requestedRank=phaseRank(phase);
+  const effectivePhase=observedRank>requestedRank?String(observed.phase):phase;
+  if(observed) Object.assign(state,observed);
+  Object.assign(state,extra,{phase:effectivePhase,updated_at_utc:new Date().toISOString()});
   await atomicBytes(file,Buffer.from(`${JSON.stringify(state,null,2)}\n`,'utf8'));
 }
 function generationTuple(runtime){
@@ -888,40 +927,433 @@ 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,hostPolicyBootstrap=null,desktopPolicyBootstrap=null,semanticLspBootstrap=null,enableMachineFs=false,enableObservation=false,enableDesktop=false,enableAutonomousSupervisor=false,hostCommandPins=[]}){
+
+function encodeSnapshot(snapshot){
+  if(!snapshot||typeof snapshot!=='object') throw new Error('snapshot object required');
+  return {exists:snapshot.exists===true,sha256:snapshot.sha256??null,bytes_base64:snapshot.exists&&snapshot.bytes?Buffer.from(snapshot.bytes).toString('base64'):null};
+}
+function decodeSnapshot(snapshot,label){
+  if(!snapshot||typeof snapshot!=='object'||typeof snapshot.exists!=='boolean') throw new Error(label+' snapshot invalid');
+  if(snapshot.exists){
+    if(typeof snapshot.bytes_base64!=='string') throw new Error(label+' snapshot bytes missing');
+    const bytes=Buffer.from(snapshot.bytes_base64,'base64'),actual=sha256Bytes(bytes);
+    if(snapshot.sha256!==actual) throw new Error(label+' snapshot SHA-256 mismatch');
+    return {exists:true,bytes,sha256:actual};
+  }
+  return {exists:false,bytes:null,sha256:null};
+}
+const UPDATE_PHASE_RANK=Object.freeze({
+  initial:0,candidate_prepared:10,old_runtime_verified:20,shutdown_handoff_armed:25,supervisor_spawned:30,
+  authority_revoked:40,old_runtime_stopped:50,workspace_ready:60,launcher_installed:70,pointer_committed:80,
+  fresh_runtime_verified:90,authority_verified:100,completed:110,superseded:120,failed:1000,failed_receipted:1001,failed_unreceipted:1002
+});
+function phaseRank(phase){ return UPDATE_PHASE_RANK[String(phase)]??-1; }
+function activeTransitionPhase(phase){
+  const rank=phaseRank(phase);
+  return rank>=phaseRank('shutdown_handoff_armed')&&rank<phaseRank('completed')&&rank<phaseRank('failed');
+}
+function samePublicPointer(a,b){
+  if(!a&&!b) return true;
+  if(!a||!b) return false;
+  return canonicalJson(publicPointer(a))===canonicalJson(publicPointer(b));
+}
+function statePointer(state,key){
+  if(!state?.[key]) return null;
+  return parseActivePointer(JSON.stringify(state[key]));
+}
+async function spawnDetachedSupervisor({script,handoffPath,cwd}){
+  const absoluteScript=path.resolve(script),absoluteHandoff=path.resolve(handoffPath);
+  const stat=await lstat(absoluteScript);
+  if(!stat.isFile()||stat.isSymbolicLink()) throw new Error('detached updater supervisor script must be a regular file');
+  const child=await new Promise((resolve,reject)=>{
+    const proc=spawn(process.execPath,[absoluteScript,'--resume-handoff',absoluteHandoff],{
+      cwd:path.resolve(cwd),detached:true,windowsHide:true,stdio:'ignore'
+    });
+    const onError=error=>reject(error);
+    proc.once('error',onError);
+    proc.once('spawn',()=>{
+      proc.removeListener('error',onError);
+      proc.unref();
+      resolve(proc);
+    });
+  });
+  if(!child.pid||child.pid<1) throw new Error('detached updater supervisor did not return a valid PID');
+  return {pid:child.pid,script_sha256:await sha256File(absoluteScript)};
+}
+async function acquireSupervisorLease(handoffPath){
+  const lockDir=path.resolve(handoffPath)+'.lock',lockFile=path.join(lockDir,'owner.json');
+  for(let attempt=0;attempt<2;attempt+=1){
+    try{
+      await mkdir(lockDir,{recursive:false});
+      await atomicBytes(lockFile,Buffer.from(JSON.stringify({pid:process.pid,handoff:path.resolve(handoffPath),started_at_utc:new Date().toISOString()})+'\n','utf8'));
+      return async()=>{ await rm(lockDir,{recursive:true,force:true}); };
+    }catch(error){
+      if(error?.code!=='EEXIST') throw error;
+      let owner=null; try{ owner=await readJson(lockFile); }catch{}
+      const ownerPid=Number(owner?.pid),needle=path.resolve(handoffPath).replaceAll('/','\\\\').toLowerCase();
+      const alive=Number.isInteger(ownerPid)&&ownerPid>0&&nodeProcesses().some(item=>
+        Number(item.ProcessId)===ownerPid&&String(item.CommandLine??'').replaceAll('/','\\\\').toLowerCase().includes(needle)
+      );
+      if(alive) throw new Error('slot update supervisor already active pid='+ownerPid);
+      await rm(lockDir,{recursive:true,force:true});
+    }
+  }
+  throw new Error('unable to acquire slot update supervisor lease');
+}
+export function parseResumeHandoffArgs(argv){
+  let handoff=null;
+  for(let index=0;index<argv.length;index+=1){
+    const arg=argv[index];
+    if(arg!=='--resume-handoff') throw new Error("unknown supervisor argument '"+arg+"'");
+    if(handoff!==null) throw new Error("duplicate supervisor argument '--resume-handoff'");
+    const value=argv[++index];
+    if(!value) throw new Error('--resume-handoff requires a value');
+    handoff=path.resolve(value);
+  }
+  if(!handoff) throw new Error('--resume-handoff is required');
+  return {handoff};
+}
+async function readHandoffEnvelope(handoffPath,stateRoot){
+  const envelope=await readJson(handoffPath),key=await loadUpdateKey(stateRoot);
+  if(!verifySlotUpdateEnvelope(envelope,key.publicKey)) throw new Error('slot-update handoff signature invalid');
+  if(envelope.body?.schema!==HANDOFF_SCHEMA) throw new Error('slot-update handoff schema invalid');
+  const body=envelope.body;
+  if(typeof body.update_id!=='string'||!HEX64.test(String(body.supervisor_script_sha256??''))||
+     !path.isAbsolute(String(body.supervisor_script??''))||!path.isAbsolute(String(body.state_path??''))) {
+    throw new Error('slot-update handoff identity invalid');
+  }
+  const actualSupervisorHash=await sha256File(path.resolve(body.supervisor_script));
+  if(actualSupervisorHash!==body.supervisor_script_sha256) throw new Error('slot-update handoff supervisor hash drift');
+  return {envelope,body,key};
+}
+async function writeHandoff({stateRoot,state,journal,statePath,evidenceDir,key,pointerInfo,newPointer,predecessor,priorStatus,workspace,launchers,stableMcpUrl,mcpUrlSnapshot,controlCtx}){
+  const supervisorScript=path.join(path.resolve(newPointer.release_root),'scripts','runtime-self-update.mjs');
+  const supervisorScriptSha256=await sha256File(supervisorScript);
+  const handoffPath=path.join(path.resolve(evidenceDir),'handoff.json');
+  const body={
+    schema:HANDOFF_SCHEMA,update_id:state.update_id,created_at_utc:new Date().toISOString(),
+    state_root:path.resolve(stateRoot),state_path:path.resolve(statePath),handoff_path:path.resolve(handoffPath),
+    supervisor_script:path.resolve(supervisorScript),supervisor_script_sha256:supervisorScriptSha256,
+    prior_pointer:publicPointer(pointerInfo.pointer),new_pointer:publicPointer(newPointer),predecessor_mode:predecessor.mode,
+    old_runtime:generationTuple(predecessor.runtime),
+    prior_authority:{
+      process_armed:priorStatus.process_armed,coding_armed:priorStatus.coding_armed,autonomous_armed:priorStatus.autonomous_armed,
+      desktop_armed:priorStatus.desktop_armed,host_armed:priorStatus.host_armed
+    },
+    pointer_snapshot:encodeSnapshot(pointerInfo.snapshot),
+    workspace:{source:workspace.source,target:workspace.target,mode:workspace.mode,moved:workspace.moved===true,created:workspace.created===true},
+    launchers:{
+      ps1:launchers.ps1,cmd:launchers.cmd,top:launchers.top,launcher_sha256:launchers.launcher_sha256,
+      ps1_bytes:Buffer.from(launchers.ps1Bytes).toString('base64'),cmd_bytes:Buffer.from(launchers.cmdBytes).toString('base64'),
+      snapshots:{
+        ps1:encodeSnapshot(launchers.snapshots.ps1),cmd:encodeSnapshot(launchers.snapshots.cmd),top:encodeSnapshot(launchers.snapshots.top)
+      }
+    },
+    stable_mcp_url:stableMcpUrl?{path:stableMcpUrl.path,sha256:stableMcpUrl.sha256,origin:stableMcpUrl.origin,changed:stableMcpUrl.changed===true}:null,
+    mcp_url_snapshot:stableMcpUrl?.changed?encodeSnapshot(mcpUrlSnapshot):null,
+    restore_standing_grants:state.restore_standing_grants===true
+  };
+  const receipt=await writeEnvelope(handoffPath,body,key);
+  await writeState(statePath,journal,'shutdown_handoff_armed',{
+    handoff_path:handoffPath,handoff_receipt_sha256:receipt.receipt_sha256,
+    supervisor_script:supervisorScript,supervisor_script_sha256:supervisorScriptSha256
+  });
+  return {path:handoffPath,body,receipt};
+}
+async function parseCurrentPointer(file){
+  if(!existsSync(file)) return null;
+  return parseActivePointer(await readFile(file,'utf8'));
+}
+async function ensurePointerCommitted(pointerFile,priorPointer,newPointer){
+  const current=await parseCurrentPointer(pointerFile);
+  if(samePublicPointer(current,newPointer)) return {committed:true,already:true};
+  if(!samePublicPointer(current,priorPointer)) throw new Error('active pointer changed unexpectedly before slot commit');
+  await atomicWriteActivePointer(pointerFile,newPointer);
+  const verify=await parseCurrentPointer(pointerFile);
+  if(!samePublicPointer(verify,newPointer)) throw new Error('active pointer commit readback mismatch');
+  return {committed:true,already:false};
+}
+async function coreGone(runtime){
+  return !runtime||!(await nodeProcesses()).some(item=>
+    Number(item.ProcessId)===Number(runtime.core.pid)&&String(item.CreationDate??'')===String(runtime.core.creation_date)
+  );
+}
+async function runtimeAlreadyOnline(ctx,oldRuntime){
+  const statusText=controllerCaptured(ctx,'status',15000),status=parseControllerStatus(statusText);
+  if(!status.online||!status.bridge_pid||!status.cloud_pid||!status.local_ready) return null;
+  const bridge=await readLedger(ctx,'bridge'),cloud=await readLedger(ctx,'cloud'),core=coreProcess(ctx.core_root,bridge);
+  if(oldRuntime?.bridge&&sameGeneration(oldRuntime.bridge,bridge)) throw new Error('fresh bridge generation gate failed');
+  if(oldRuntime?.cloud&&sameGeneration(oldRuntime.cloud,cloud)) throw new Error('fresh cloud generation gate failed');
+  if(oldRuntime?.core&&oldRuntime.core.pid===core.pid&&oldRuntime.core.creation_date===core.creation_date) {
+    throw new Error('fresh downstream core generation gate failed');
+  }
+  return {status,status_text:statusText.trim(),bridge,cloud,core};
+}
+async function ensureFreshRuntime(ctx,oldRuntime){
+  let existing=null;
+  try{ existing=await runtimeAlreadyOnline(ctx,oldRuntime); }
+  catch(error){ if(/generation gate/.test(String(error?.message??''))) throw error; }
+  return existing??await startAndVerify(ctx,oldRuntime);
+}
+async function ensureAuthorityRevoked(ctx,prior){
+  const status=parseControllerStatus(controllerCaptured(ctx,'status',15000));
+  if(status.host_armed) throw new Error('host plane armed during authority revoke recovery');
+  if(!status.process_armed&&!status.coding_armed&&!status.autonomous_armed&&!status.desktop_armed) {
+    return {revoked:prior.process_armed||prior.coding_armed||prior.autonomous_armed||prior.desktop_armed,status};
+  }
+  return revokeAuthority(ctx,status);
+}
+function handoffPriorPointer(body){
+  return body.prior_pointer?parseActivePointer(JSON.stringify(body.prior_pointer)):null;
+}
+function handoffNewPointer(body){
+  return body.new_pointer?parseActivePointer(JSON.stringify(body.new_pointer)):null;
+}
+async function resumeSlotUpdate({handoffPath}){
+  const absoluteHandoff=path.resolve(handoffPath),probe=await readJson(absoluteHandoff);
+  const stateRoot=path.resolve(String(probe?.body?.state_root??path.dirname(path.dirname(path.dirname(path.dirname(absoluteHandoff))))));
+  const {body,key}=await readHandoffEnvelope(absoluteHandoff,stateRoot);
+  const statePath=path.resolve(body.state_path),releaseState=await readJson(statePath);
+  if(releaseState.schema!=='deadbyte.r27-slot-update-state.v1'||releaseState.update_id!==body.update_id) throw new Error('handoff state binding mismatch');
+  let phase=String(releaseState.phase??'');
+  if(phase==='completed'){
+    return {ok:true,resumed:false,completed:true,update_id:body.update_id,state_path:statePath,
+      receipt_path:releaseState.receipt_path??null,receipt_sha256:releaseState.receipt_sha256??null};
+  }
+  if(phase.startsWith('failed')) throw new Error('slot update already failed at phase='+phase);
+  const priorPointer=handoffPriorPointer(body),candidatePointer=handoffNewPointer(body);
+  const statePrior=statePointer(releaseState,'prior_pointer'),stateCandidate=statePointer(releaseState,'new_pointer');
+  if(!samePublicPointer(priorPointer,statePrior)||!samePublicPointer(candidatePointer,stateCandidate)) throw new Error('handoff pointer binding mismatch');
+  if(!candidatePointer) throw new Error('handoff candidate pointer missing');
+  const pointerFile=path.join(stateRoot,'active-release.json'),currentPointer=await parseCurrentPointer(pointerFile);
+  if(!samePublicPointer(currentPointer,priorPointer)&&!samePublicPointer(currentPointer,candidatePointer)) throw new Error('active pointer is neither handoff predecessor nor candidate');
+  const pointerInfo={file:pointerFile,pointer:currentPointer,snapshot:decodeSnapshot(body.pointer_snapshot,'active pointer')};
+  const ctx=slotContext(stateRoot,priorPointer),newCtx=slotContext(stateRoot,candidatePointer);
+  const priorStatus={
+    process_armed:body.prior_authority?.process_armed===true,coding_armed:body.prior_authority?.coding_armed===true,
+    autonomous_armed:body.prior_authority?.autonomous_armed===true,desktop_armed:body.prior_authority?.desktop_armed===true,
+    host_armed:body.prior_authority?.host_armed===true
+  };
+  if(priorStatus.autonomous_armed&&!priorStatus.coding_armed) throw new Error('invalid prior authority in handoff');
+  const oldRuntime=body.old_runtime?{bridge:body.old_runtime.bridge??null,cloud:body.old_runtime.cloud??null,core:body.old_runtime.core??null}:null;
+  if(oldRuntime?.core&&(!Number.isInteger(Number(oldRuntime.core.pid))||String(oldRuntime.core.creation_date??'').length<1)) throw new Error('handoff old runtime core identity invalid');
+  const launchers={
+    ps1:path.resolve(String(body.launchers?.ps1??'')),cmd:path.resolve(String(body.launchers?.cmd??'')),top:path.resolve(String(body.launchers?.top??TOP_LAUNCHER)),
+    launcher_sha256:String(body.launchers?.launcher_sha256??''),
+    ps1Bytes:Buffer.from(String(body.launchers?.ps1_bytes??''),'base64'),cmdBytes:Buffer.from(String(body.launchers?.cmd_bytes??''),'base64'),
+    snapshots:{
+      ps1:decodeSnapshot(body.launchers?.snapshots?.ps1,'launcher.ps1'),cmd:decodeSnapshot(body.launchers?.snapshots?.cmd,'launcher.cmd'),top:decodeSnapshot(body.launchers?.snapshots?.top,'launcher.top')
+    },
+    installed:phaseRank(phase)>=phaseRank('launcher_installed')
+  };
+  if(!HEX64.test(launchers.launcher_sha256)||sha256Bytes(launchers.ps1Bytes)!==launchers.launcher_sha256) throw new Error('handoff launcher bytes/hash mismatch');
+  const workspace={
+    source:path.resolve(String(body.workspace?.source??releaseState.workspace?.source??'')),
+    target:path.resolve(String(body.workspace?.target??releaseState.workspace?.target??'')),
+    mode:String(body.workspace?.mode??releaseState.workspace?.mode??''),
+    moved:releaseState.workspace?.moved===true,created:releaseState.workspace?.created===true
+  };
+  if(!['existing','target-existing','create','rename'].includes(workspace.mode)) throw new Error('handoff workspace mode invalid');
+  const stableMcpUrl=body.stable_mcp_url?{...body.stable_mcp_url}:releaseState.stable_mcp_url?{...releaseState.stable_mcp_url}:null;
+  const mcpUrlSnapshot=body.mcp_url_snapshot?decodeSnapshot(body.mcp_url_snapshot,'MCP URL'):{exists:false,bytes:null,sha256:null};
+  const cleanup=await acquireSupervisorLease(absoluteHandoff);
+  try{
+    const journal=releaseState;
+    if(phaseRank(phase)<phaseRank('supervisor_spawned')){
+      await writeState(statePath,journal,'supervisor_spawned',{supervisor_pid:process.pid,supervisor_script:body.supervisor_script,supervisor_script_sha256:body.supervisor_script_sha256});
+      phase='supervisor_spawned';
+    }
+    let revoked=phaseRank(phase)>=phaseRank('authority_revoked')||journal.revoked_before_switch===true;
+    let stopped=phaseRank(phase)>=phaseRank('old_runtime_stopped');
+    let pointerCommitted=phaseRank(phase)>=phaseRank('pointer_committed')||samePublicPointer(currentPointer,candidatePointer);
+    let newRuntime=null,stabilization=null;
+
+    if(phaseRank(phase)<phaseRank('authority_revoked')){
+      const revoke=await ensureAuthorityRevoked(ctx,priorStatus);
+      revoked=revoke.revoked;
+      await writeState(statePath,journal,'authority_revoked',{revoked_before_switch:revoked});
+      phase='authority_revoked';
+    }
+    if(!stopped){
+      const status=parseControllerStatus(controllerCaptured(ctx,'status',15000)),gone=await coreGone(oldRuntime);
+      if(!oldRuntime||(status.offline&&gone)){
+        await writeState(statePath,journal,'old_runtime_stopped',{stop_output:'recovery observed predecessor already OFFLINE'});
+      }else{
+        const stoppedResult=await stopAndVerify(ctx,oldRuntime);
+        await writeState(statePath,journal,'old_runtime_stopped',{stop_output:stoppedResult.output});
+      }
+      stopped=true; phase='old_runtime_stopped';
+    }
+    if(phaseRank(phase)<phaseRank('workspace_ready')){
+      await applyWorkspacePlan(workspace);
+      await writeState(statePath,journal,'workspace_ready',{workspace:{source:workspace.source,target:workspace.target,mode:workspace.mode,moved:workspace.moved===true,created:workspace.created===true}});
+      phase='workspace_ready';
+    }else{
+      workspace.moved=journal.workspace?.moved===true; workspace.created=journal.workspace?.created===true;
+    }
+    if(phaseRank(phase)<phaseRank('launcher_installed')){
+      await installLaunchers(launchers);
+      await writeState(statePath,journal,'launcher_installed',{launcher_sha256:launchers.launcher_sha256,launcher_path:launchers.ps1,top_launcher:launchers.top});
+      phase='launcher_installed';
+    }
+    if(!pointerCommitted){
+      await ensurePointerCommitted(pointerFile,priorPointer,candidatePointer);
+      pointerCommitted=true;
+      await writeState(statePath,journal,'pointer_committed',{active_pointer:publicPointer(candidatePointer)});
+      phase='pointer_committed';
+    }
+    await verifyActiveInstallation(stateRoot,candidatePointer);
+    newRuntime=await ensureFreshRuntime(newCtx,oldRuntime);
+    stabilization=await stabilizeRuntime(newCtx,newRuntime);
+    await writeState(statePath,journal,'fresh_runtime_verified',{new_runtime:generationTuple(newRuntime),stabilization});
+    phase='fresh_runtime_verified';
+
+    const finalAuthority=await restoreStandingAuthority(newCtx,priorStatus,journal.restore_standing_grants===true);
+    await writeState(statePath,journal,'authority_verified',{final_authority:{
+      process_armed:finalAuthority.process_armed,coding_armed:finalAuthority.coding_armed,autonomous_armed:finalAuthority.autonomous_armed,
+      desktop_armed:finalAuthority.desktop_armed,host_armed:finalAuthority.host_armed
+    }});
+    phase='authority_verified';
+
+    const bodyReceipt={
+      schema:UPDATE_SCHEMA,update_id:body.update_id,release_version:journal.expected_version,candidate_manifest_sha256:journal.expected_manifest_sha256,
+      completed_at_utc:new Date().toISOString(),activation_boundary:'active-release-pointer',
+      mechanism:'immutable-release-slot-plus-atomic-pointer-rename-plus-detached-supervisor-handoff',
+      predecessor_mode:journal.predecessor_mode??body.predecessor_mode,prior_pointer:publicPointer(priorPointer),active_pointer:publicPointer(candidatePointer),
+      release_slot:journal.release_slot,generation:journal.generation,
+      launcher:{path:launchers.ps1,sha256:launchers.launcher_sha256,top_path:launchers.top},
+      workspace:{root:workspace.target,migrated:workspace.moved===true},development_root:journal.development_root,
+      host_repin:journal.host_repin??{requested:false,repinned:false},coding_repin:journal.coding_repin??{requested:false,repinned:false},
+      old_runtime:journal.old_runtime??body.old_runtime,new_runtime:generationTuple(newRuntime),stabilization,
+      authority:{
+        prior:priorStatus,revoked_before_switch:revoked,restore_requested:journal.restore_standing_grants===true,desktop_restore_policy:'explicit-rearm-required',
+        final:{
+          process_armed:finalAuthority.process_armed,coding_armed:finalAuthority.coding_armed,autonomous_armed:finalAuthority.autonomous_armed,
+          desktop_armed:finalAuthority.desktop_armed,host_armed:finalAuthority.host_armed
+        }
+      },
+      rollback_performed:false
+    };
+    const receiptPath=path.join(path.dirname(statePath),'receipt.json'),receipt=await writeEnvelope(receiptPath,bodyReceipt,key);
+    await writeState(statePath,journal,'completed',{receipt_path:receiptPath,receipt_sha256:receipt.receipt_sha256});
+    return {ok:true,resumed:true,completed:true,update_id:body.update_id,state_path:statePath,receipt_path:receiptPath,receipt_sha256:receipt.receipt_sha256,
+      pointer:candidatePointer,new_runtime:newRuntime,final_authority:finalAuthority,workspace_root:workspace.target};
+  }catch(error){
+    let controllerStartFailure=null,controllerStartFailurePreservationError=null;
+    if(pointerCommitted){
+      try{
+        controllerStartFailure=await preserveControllerStartFailure(newCtx,path.dirname(statePath));
+        const claimed=/evidence_sha256=([0-9a-f]{64})/.exec(String(error?.message??error));
+        if(claimed&&(!controllerStartFailure||controllerStartFailure.sha256!==claimed[1])){
+          controllerStartFailurePreservationError='controller start failure evidence claim mismatch expected='+claimed[1]+' preserved='+(controllerStartFailure?.sha256??'missing');
+        }
+      }catch(preserveError){ controllerStartFailurePreservationError=String(preserveError?.message??preserveError); }
+    }
+    const rollback={attempted:false,new_runtime_stopped:false,pointer_restored:false,launchers_restored:false,workspace_restored:false,mcp_url_restored:false,old_runtime_restarted:false,authority_restored:false,errors:[]};
+    try{
+      if(pointerCommitted){
+        rollback.attempted=true;
+        try{ controllerCaptured(newCtx,'stop',30000); rollback.new_runtime_stopped=true; }catch(stopError){ rollback.errors.push('stop-new:'+stopError.message); }
+      }
+      const currentAfter=await parseCurrentPointer(pointerFile);
+      if(samePublicPointer(currentAfter,candidatePointer)){
+        try{ await restoreFile(pointerFile,pointerInfo.snapshot); rollback.pointer_restored=true; }catch(pointerError){ rollback.errors.push('pointer:'+pointerError.message); }
+      }
+      if(stableMcpUrl?.changed&&mcpUrlSnapshot){
+        try{ await restoreFile(stableMcpUrl.path,mcpUrlSnapshot); rollback.mcp_url_restored=true; }catch(mcpUrlError){ rollback.errors.push('mcp-url:'+mcpUrlError.message); }
+      }
+      if(phaseRank(journal.phase)>=phaseRank('launcher_installed')||launchers.installed){
+        try{ await rollbackLaunchers({...launchers,installed:true}); rollback.launchers_restored=true; }catch(launcherError){ rollback.errors.push('launcher:'+launcherError.message); }
+      }
+      if(phaseRank(journal.phase)>=phaseRank('workspace_ready')||workspace.moved||workspace.created){
+        try{ rollback.workspace_restored=await rollbackWorkspacePlan(workspace); }catch(workspaceError){ rollback.errors.push('workspace:'+workspaceError.message); }
+      }
+      if(stopped&&oldRuntime&&rollback.pointer_restored){
+        try{ await startAndVerify(ctx,oldRuntime); rollback.old_runtime_restarted=true; }catch(startError){ rollback.errors.push('restart-old:'+startError.message); }
+      }
+      if((!stopped||rollback.old_runtime_restarted)&&journal.restore_standing_grants===true){
+        try{ await restoreStandingAuthority(ctx,priorStatus,true); rollback.authority_restored=true; }catch(authorityError){ rollback.errors.push('restore-authority:'+authorityError.message); }
+      }
+    }catch(rollbackError){ rollback.errors.push('rollback:'+rollbackError.message); }
+    const failure={
+      schema:FAILURE_SCHEMA,update_id:body.update_id,release_version:journal.expected_version,candidate_manifest_sha256:journal.expected_manifest_sha256,
+      failed_at_utc:new Date().toISOString(),phase:journal.phase??phase,error:{name:error?.name??'Error',code:error?.code??null,message:String(error?.message??error)},
+      controller_start_failure:controllerStartFailure,controller_start_failure_preservation_error:controllerStartFailurePreservationError,
+      predecessor_mode:journal.predecessor_mode??body.predecessor_mode,prior_pointer:publicPointer(priorPointer),attempted_pointer:publicPointer(candidatePointer),
+      old_runtime:journal.old_runtime??body.old_runtime,rollback
+    };
+    await writeState(statePath,journal,'failed',{failure,rollback}).catch(()=>{});
+    let failureReceipt=null;
+    try{
+      const failurePath=path.join(path.dirname(statePath),'failure-receipt.json');
+      failureReceipt=await writeEnvelope(failurePath,failure,key);
+      await writeState(statePath,journal,'failed_receipted',{failure_receipt_path:failurePath,failure_receipt_sha256:failureReceipt.receipt_sha256});
+    }catch(receiptError){
+      rollback.errors.push('failure-receipt:'+receiptError.message);
+      await writeState(statePath,journal,'failed_unreceipted',{rollback}).catch(()=>{});
+    }
+    const wrapped=new Error('R27 slot update failed in detached supervisor: '+(error?.message??error));
+    wrapped.cause=error; wrapped.statePath=statePath; wrapped.failureReceiptPath=failureReceipt?path.join(path.dirname(statePath),'failure-receipt.json'):null; throw wrapped;
+  }finally{
+    await cleanup();
+  }
+}
+export async function recoverInterruptedSlotUpdates({stateRoot=DEFAULT_STATE_ROOT}={}){
+  const evidenceRoot=path.join(path.resolve(stateRoot),'evidence','updates');
+  if(!existsSync(evidenceRoot)) return {ok:true,launched:0,updates:[]};
+  const entries=await readdir(evidenceRoot,{withFileTypes:true});
+  const pointerPath=path.join(path.resolve(stateRoot),'active-release.json');
+  const activePointer=existsSync(pointerPath)?await parseCurrentPointer(pointerPath):null;
+  let launched=0;const updates=[];
+  for(const entry of entries){
+    if(!entry.isDirectory()) continue;
+    const statePath=path.join(evidenceRoot,entry.name,'state.json');
+    if(!existsSync(statePath)) continue;
+    let state;try{ state=await readJson(statePath); }catch{ continue; }
+    if(!activeTransitionPhase(state?.phase)) continue;
+    const pendingPointer=statePointer(state,'new_pointer');
+    if(activePointer&&pendingPointer&&samePublicPointer(activePointer,pendingPointer)){
+      await writeState(statePath,state,'superseded',{superseded_at_utc:new Date().toISOString(),superseded_by_pointer:publicPointer(activePointer)});
+      continue;
+    }
+    const handoffPath=String(state?.handoff_path??'');
+    if(!handoffPath||!path.isAbsolute(handoffPath)||!existsSync(handoffPath)) continue;
+    const handoff=await readJson(handoffPath);
+    if(handoff?.body?.schema!==HANDOFF_SCHEMA) continue;
+    const script=path.resolve(String(handoff.body.supervisor_script??''));
+    if(await sha256File(script)!==handoff.body.supervisor_script_sha256) throw new Error('interrupted update supervisor hash drift: '+state.update_id);
+    const result=await spawnDetachedSupervisor({script,handoffPath,cwd:path.dirname(script)});
+    launched+=1;updates.push({update_id:state.update_id,state_path:statePath,handoff_path:handoffPath,supervisor_pid:result.pid});
+    await atomicBytes(path.join(path.dirname(statePath),'recovery-launch.json'),Buffer.from(JSON.stringify({update_id:state.update_id,launched_at_utc:new Date().toISOString(),supervisor_pid:result.pid})+'\n','utf8'));
+  }
+  return {ok:true,launched,updates};
+}
+
+export async function performSlotUpdate({stage,developmentRoot,expectedVersion,expectedManifest,sourceRoot=null,stateRoot=DEFAULT_STATE_ROOT,restoreStandingGrants=false,recoverOfflinePredecessor=false,cloudTransport=null,bridgeBootstrap=null,processPolicyBootstrap=null,hostPolicyBootstrap=null,codingPolicyBootstrap=null,desktopPolicyBootstrap=null,semanticLspBootstrap=null,enableMachineFs=false,enableObservation=false,enableDesktop=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')}`;
-  const evidenceDir=path.join(state,'evidence','updates',updateId),statePath=path.join(evidenceDir,'state.json');
-  const receiptPath=path.join(evidenceDir,'receipt.json'),failurePath=path.join(evidenceDir,'failure-receipt.json');
+  const key=await loadUpdateKey(state),updateId='r27-'+expectedManifest.slice(0,16)+'-'+Date.now().toString(36)+'-'+randomBytes(4).toString('hex');
+  const evidenceDir=path.join(state,'evidence','updates',updateId),statePath=path.join(evidenceDir,'state.json'),failurePath=path.join(evidenceDir,'failure-receipt.json');
   await mkdir(evidenceDir,{recursive:true});
   const journal={schema:'deadbyte.r27-slot-update-state.v1',update_id:updateId,stage_root:stageRoot,development_root:development,
     source_root:sourceRoot?path.resolve(sourceRoot):null,expected_version:expectedVersion,expected_manifest_sha256:expectedManifest,
     restore_standing_grants:restoreStandingGrants,recover_offline_predecessor:recoverOfflinePredecessor,created_at_utc:new Date().toISOString()};
   await writeState(statePath,journal,'initial');
-  let pointerInfo=null,control=null,predecessor=null,oldRuntime=null,priorStatus=null,authorityPreparation=null,workspace=null,launchers=null,newPointer=null,newCtx=null;
+  let pointerInfo=null,control=null,predecessor=null,oldRuntime=null,priorStatus=null,authorityPreparation=null,workspace=null,launchers=null,newPointer=null;
   let stableMcpUrl=null,mcpUrlSnapshot=null;
-  let revoked=false,stopped=false,pointerCommitted=false,newStarted=false;
-  try {
+  try{
     pointerInfo=await loadPointerIfPresent(state);
     const stageVerified=await verifyPackageRoot(stageRoot,expectedVersion,expectedManifest,'stage');
     const developmentVerified=await verifyPackageRoot(development,expectedVersion,expectedManifest,'development');
     const slot=await materializeReleaseSlot({source:stageRoot,stateRoot:state,version:expectedVersion,manifestSha256:expectedManifest});
     control=await loadControlInputs({stateRoot:state,sourceRoot,pointerInfo});
-    const hostBootstrap=await prepareHostPolicyBootstrap(hostPolicyBootstrap);
-    if(hostBootstrap) control.hostPolicy=hostBootstrap.policy;
+    const hostBootstrap=await prepareHostPolicyBootstrap(hostPolicyBootstrap);if(hostBootstrap) control.hostPolicy=hostBootstrap.policy;
+    const codingBootstrap=await prepareCodingPolicyBootstrap(codingPolicyBootstrap);if(codingBootstrap) control.codingPolicy=codingBootstrap.policy;
     const processBootstrap=await prepareProcessPolicyBootstrap(processPolicyBootstrap);
-    if(processBootstrap){
-      control.processPolicy=processBootstrap.policy;
-      control.config.ProcessRuntimeEnabled=true;
-    }
-    const desktopBootstrap=await prepareDesktopPolicyBootstrap(desktopPolicyBootstrap);
-    if(desktopBootstrap) control.desktopPolicy=desktopBootstrap.policy;
+    if(processBootstrap){ control.processPolicy=processBootstrap.policy;control.config.ProcessRuntimeEnabled=true; }
+    const desktopBootstrap=await prepareDesktopPolicyBootstrap(desktopPolicyBootstrap);if(desktopBootstrap) control.desktopPolicy=desktopBootstrap.policy;
     const semanticBootstrap=await prepareSemanticLspConfigBootstrap(semanticLspBootstrap);
-    if(semanticBootstrap){
-      control.config.SemanticLspConfigFile=semanticBootstrap.path;
-      control.config.SemanticLspConfigSha256=semanticBootstrap.sha256;
-    }
+    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;
@@ -939,142 +1371,45 @@ export async function performSlotUpdate({stage,developmentRoot,expectedVersion,e
     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;
+    control.hostPolicy=authorityPreparation.hostPolicy;control.codingPolicy=authorityPreparation.codingPolicy;
     const stableMcp=await ensureStableMcpPath({stateRoot:state,sourceRoot:pointerInfo.pointer?null:sourceRoot});
     control.config.McpPathFile=stableMcp.path;
     if(cloudTransport?.publicOrigin){
-      const mcpUrlFile=path.join(state,'bridge','mcp-url.txt');
-      mcpUrlSnapshot=await snapshotFile(mcpUrlFile);
+      const mcpUrlFile=path.join(state,'bridge','mcp-url.txt');mcpUrlSnapshot=await snapshotFile(mcpUrlFile);
       stableMcpUrl=await ensureStableMcpUrl({stateRoot:state,publicOrigin:cloudTransport.publicOrigin,mcpPathFile:stableMcp.path});
-      control.config.McpUrlFile=stableMcpUrl.path;
-      control.config.McpUrlFileSha256=stableMcpUrl.sha256;
-    } else if(control.config.Cloud?.Transport==='deadbyte.named-tunnel.v2') {
-      if(typeof control.config.McpUrlFile!=='string'||!path.isAbsolute(control.config.McpUrlFile)||!HEX64.test(String(control.config.McpUrlFileSha256??''))) {
-        throw new Error('existing named tunnel v2 requires pinned McpUrlFile before update');
-      }
+      control.config.McpUrlFile=stableMcpUrl.path;control.config.McpUrlFileSha256=stableMcpUrl.sha256;
+    }else if(control.config.Cloud?.Transport==='deadbyte.named-tunnel.v2'){
+      if(typeof control.config.McpUrlFile!=='string'||!path.isAbsolute(control.config.McpUrlFile)||!HEX64.test(String(control.config.McpUrlFileSha256??''))) throw new Error('existing named tunnel v2 requires pinned McpUrlFile before update');
       const pinned=await verifyPinnedRegularFile(control.config.McpUrlFile,control.config.McpUrlFileSha256,'existing named tunnel MCP URL file');
-      control.config.McpUrlFile=pinned.path;
-      control.config.McpUrlFileSha256=pinned.sha256;
+      control.config.McpUrlFile=pinned.path;control.config.McpUrlFileSha256=pinned.sha256;
     }
-    workspace=await workspacePlan(control.workspaceRoot,state);
-    launchers=await launcherPlan(state);
-    const generation=await createGenerationBundle({stateRoot:state,releaseRoot:slot.release_root,developmentRoot:development,
-      workspaceRoot:workspace.target,releaseId:slot.release_id,currentConfig:control.config,codingPolicy:control.codingPolicy,
-      autonomousPolicy:control.autonomousPolicy,hostPolicy:control.hostPolicy,processPolicy:control.processPolicy,desktopPolicy:control.desktopPolicy});
-    newPointer={schema:'deadbyte.active-release.v1',release_id:slot.release_id,version:expectedVersion,manifest_sha256:expectedManifest,
-      release_root:slot.release_root,generation_root:generation.generation_root,generation_manifest_sha256:generation.generation_manifest_sha256,
-      launcher_sha256:launchers.launcher_sha256,config_path:generation.config_path};
+    workspace=await workspacePlan(control.workspaceRoot,state);launchers=await launcherPlan(state);
+    const generation=await createGenerationBundle({stateRoot:state,releaseRoot:slot.release_root,developmentRoot:development,workspaceRoot:workspace.target,releaseId:slot.release_id,currentConfig:control.config,codingPolicy:control.codingPolicy,autonomousPolicy:control.autonomousPolicy,hostPolicy:control.hostPolicy,processPolicy:control.processPolicy,desktopPolicy:control.desktopPolicy});
+    newPointer={schema:'deadbyte.active-release.v1',release_id:slot.release_id,version:expectedVersion,manifest_sha256:expectedManifest,release_root:slot.release_root,generation_root:generation.generation_root,generation_manifest_sha256:generation.generation_manifest_sha256,launcher_sha256:launchers.launcher_sha256,config_path:generation.config_path};
     parseActivePointer(JSON.stringify(newPointer));
-    await writeState(statePath,journal,'candidate_prepared',{prior_pointer:publicPointer(pointerInfo.pointer),stage:stageVerified,
-      development:developmentVerified,release_slot:slot,generation:{generation_id:generation.generation_id,generation_root:generation.generation_root,
-      generation_manifest_sha256:generation.generation_manifest_sha256,files:generation.files},workspace:{source:workspace.source,target:workspace.target,mode:workspace.mode},
-      stable_mcp_path:{path:stableMcp.path,sha256:stableMcp.sha256},
+    await writeState(statePath,journal,'candidate_prepared',{prior_pointer:publicPointer(pointerInfo.pointer),stage:stageVerified,development:developmentVerified,
+      release_slot:slot,generation:{generation_id:generation.generation_id,generation_root:generation.generation_root,generation_manifest_sha256:generation.generation_manifest_sha256,files:generation.files},
+      workspace:{source:workspace.source,target:workspace.target,mode:workspace.mode},stable_mcp_path:{path:stableMcp.path,sha256:stableMcp.sha256},
       stable_mcp_url:stableMcpUrl?{path:stableMcpUrl.path,sha256:stableMcpUrl.sha256,origin:stableMcpUrl.origin,changed:stableMcpUrl.changed}:null,
       bridge:{working_directory:control.config.Bridge.WorkingDirectory,script_path:control.config.Bridge.ScriptPath,script_sha256:control.config.Bridge.ScriptSha256},
-      host_repin:{requested:hostCommandPins.length>0,repinned:authorityPreparation.hostRepinned},
-      coding_repin:{requested:hostCommandPins.length>0,repinned:authorityPreparation.codingRepinned},new_pointer:publicPointer(newPointer)});
-    predecessor=await capturePredecessor(control.ctx,recoverOfflinePredecessor); oldRuntime=predecessor.runtime; priorStatus=predecessor.status;
+      host_repin:{requested:hostCommandPins.length>0,repinned:authorityPreparation.hostRepinned},coding_repin:{requested:hostCommandPins.length>0,repinned:authorityPreparation.codingRepinned},
+      new_pointer:publicPointer(newPointer)});
+    predecessor=await capturePredecessor(control.ctx,recoverOfflinePredecessor);oldRuntime=predecessor.runtime;priorStatus=predecessor.status;
     await writeState(statePath,journal,'old_runtime_verified',{predecessor_mode:predecessor.mode,old_runtime:generationTuple(oldRuntime),
-      prior_authority:{coding_armed:priorStatus.coding_armed,autonomous_armed:priorStatus.autonomous_armed,desktop_armed:priorStatus.desktop_armed,host_armed:priorStatus.host_armed}});
-    const revoke=await revokeAuthority(control.ctx,priorStatus); revoked=revoke.revoked;
-    await writeState(statePath,journal,'authority_revoked',{revoked_before_switch:revoked});
-    if(oldRuntime){
-      const stoppedResult=await stopAndVerify(control.ctx,oldRuntime); stopped=true;
-      await writeState(statePath,journal,'old_runtime_stopped',{stop_output:stoppedResult.output});
-    } else {
-      await writeState(statePath,journal,'old_runtime_stopped',{stop_output:'predecessor already OFFLINE; recovery mode performed no stop'});
-    }
-    await applyWorkspacePlan(workspace);
-    await writeState(statePath,journal,'workspace_ready',{workspace:{source:workspace.source,target:workspace.target,mode:workspace.mode,moved:workspace.moved===true,created:workspace.created===true}});
-    await installLaunchers(launchers);
-    await writeState(statePath,journal,'launcher_installed',{launcher_sha256:launchers.launcher_sha256,launcher_path:launchers.ps1,top_launcher:launchers.top});
-    await atomicWriteActivePointer(pointerInfo.file,newPointer); pointerCommitted=true;
-    await writeState(statePath,journal,'pointer_committed',{active_pointer:publicPointer(newPointer)});
-    await verifyActiveInstallation(state,newPointer);
-    newCtx=slotContext(state,newPointer);
-    const newRuntime=await startAndVerify(newCtx,oldRuntime); newStarted=true;
-    const stabilization=await stabilizeRuntime(newCtx,newRuntime);
-    await writeState(statePath,journal,'fresh_runtime_verified',{new_runtime:generationTuple(newRuntime),stabilization});
-    const finalAuthority=await restoreStandingAuthority(newCtx,priorStatus,restoreStandingGrants);
-    await writeState(statePath,journal,'authority_verified',{final_authority:{process_armed:finalAuthority.process_armed,coding_armed:finalAuthority.coding_armed,
-      autonomous_armed:finalAuthority.autonomous_armed,desktop_armed:finalAuthority.desktop_armed,host_armed:finalAuthority.host_armed}});
-    const body={schema:UPDATE_SCHEMA,update_id:updateId,release_version:expectedVersion,candidate_manifest_sha256:expectedManifest,
-      completed_at_utc:new Date().toISOString(),activation_boundary:'active-release-pointer',mechanism:'immutable-release-slot-plus-atomic-pointer-rename',
-      predecessor_mode:predecessor.mode,prior_pointer:publicPointer(pointerInfo.pointer),active_pointer:publicPointer(newPointer),release_slot:{release_id:slot.release_id,release_root:slot.release_root,
-      adopted:slot.adopted,files:slot.files},generation:{generation_id:generation.generation_id,generation_root:generation.generation_root,
-      generation_manifest_sha256:generation.generation_manifest_sha256,adopted:generation.adopted,files:generation.files},
-      launcher:{path:launchers.ps1,sha256:launchers.launcher_sha256,top_path:launchers.top},workspace:{root:workspace.target,migrated:workspace.moved===true},
-      development_root:development,
-      host_repin:{requested:hostCommandPins.length>0,repinned:authorityPreparation.hostRepinned},
-      coding_repin:{requested:hostCommandPins.length>0,repinned:authorityPreparation.codingRepinned},old_runtime:generationTuple(oldRuntime),new_runtime:generationTuple(newRuntime),stabilization,
-      authority:{prior:{process_armed:priorStatus.process_armed,coding_armed:priorStatus.coding_armed,
-      autonomous_armed:priorStatus.autonomous_armed,desktop_armed:priorStatus.desktop_armed,host_armed:priorStatus.host_armed},revoked_before_switch:revoked,restore_requested:restoreStandingGrants,
-      desktop_restore_policy:'explicit-rearm-required',
-      final:{process_armed:finalAuthority.process_armed,coding_armed:finalAuthority.coding_armed,autonomous_armed:finalAuthority.autonomous_armed,desktop_armed:finalAuthority.desktop_armed,host_armed:finalAuthority.host_armed}},rollback_performed:false};
-    const receipt=await writeEnvelope(receiptPath,body,key);
-    await writeState(statePath,journal,'completed',{receipt_path:receiptPath,receipt_sha256:receipt.receipt_sha256});
-    return {ok:true,update_id:updateId,state_path:statePath,receipt_path:receiptPath,receipt_sha256:receipt.receipt_sha256,
-      pointer:newPointer,new_runtime:newRuntime,final_authority:finalAuthority,workspace_root:workspace.target};
-  } catch(error){
-    let controllerStartFailure=null,controllerStartFailurePreservationError=null;
-    if(pointerCommitted&&newCtx){
-      try {
-        controllerStartFailure=await preserveControllerStartFailure(newCtx,evidenceDir);
-        const claimed=/evidence_sha256=([0-9a-f]{64})/.exec(String(error?.message??error));
-        if(claimed&&(!controllerStartFailure||controllerStartFailure.sha256!==claimed[1])) {
-          controllerStartFailurePreservationError=`controller start failure evidence claim mismatch expected=${claimed[1]} preserved=${controllerStartFailure?.sha256??'missing'}`;
-        }
-      } catch(preserveError) {
-        controllerStartFailurePreservationError=String(preserveError?.message??preserveError);
-      }
-    }
-    const rollback={attempted:false,new_runtime_stopped:false,pointer_restored:false,launchers_restored:false,workspace_restored:false,
-      mcp_url_restored:false,old_runtime_restarted:false,authority_restored:false,errors:[]};
-    try {
-      if(pointerCommitted&&newCtx){
-        rollback.attempted=true;
-        try { controllerCaptured(newCtx,'stop',30000); rollback.new_runtime_stopped=true; }
-        catch(stopError){ rollback.errors.push(`stop-new:${stopError.message}`); }
-      }
-      if(pointerCommitted&&pointerInfo){
-        try { await restoreFile(pointerInfo.file,pointerInfo.snapshot); rollback.pointer_restored=true; }
-        catch(pointerError){ rollback.errors.push(`pointer:${pointerError.message}`); }
-      }
-      if(stableMcpUrl?.changed&&mcpUrlSnapshot){
-        rollback.attempted=true;
-        try { await restoreFile(stableMcpUrl.path,mcpUrlSnapshot); rollback.mcp_url_restored=true; }
-        catch(mcpUrlError){ rollback.errors.push(`mcp-url:${mcpUrlError.message}`); }
-      }
-      if(launchers?.installed){
-        try { await rollbackLaunchers(launchers); rollback.launchers_restored=true; }
-        catch(launcherError){ rollback.errors.push(`launcher:${launcherError.message}`); }
-      }
-      if(workspace){
-        try { rollback.workspace_restored=await rollbackWorkspacePlan(workspace); }
-        catch(workspaceError){ rollback.errors.push(`workspace:${workspaceError.message}`); }
-      }
-      if(stopped&&control?.ctx){
-        try { await startAndVerify(control.ctx,oldRuntime); rollback.old_runtime_restarted=true; }
-        catch(startError){ rollback.errors.push(`restart-old:${startError.message}`); }
-      }
-      const predecessorReadyForAuthorityRestore=!stopped||rollback.old_runtime_restarted;
-      if(predecessorReadyForAuthorityRestore&&priorStatus&&restoreStandingGrants){
-        try { await restoreStandingAuthority(control.ctx,priorStatus,true); rollback.authority_restored=true; }
-        catch(authorityError){ rollback.errors.push(`restore-authority:${authorityError.message}`); }
-      }
-    } catch(rollbackError){ rollback.errors.push(`rollback:${rollbackError.message}`); }
-    const failure={schema:FAILURE_SCHEMA,update_id:updateId,release_version:expectedVersion,candidate_manifest_sha256:expectedManifest,
-      failed_at_utc:new Date().toISOString(),phase:journal.phase??'unknown',error:{name:error?.name??'Error',code:error?.code??null,message:String(error?.message??error)},
-      controller_start_failure:controllerStartFailure,
-      controller_start_failure_preservation_error:controllerStartFailurePreservationError,
-      predecessor_mode:predecessor?.mode??null,prior_pointer:publicPointer(pointerInfo?.pointer??null),attempted_pointer:publicPointer(newPointer),old_runtime:generationTuple(oldRuntime),rollback};
-    await writeState(statePath,journal,'failed',{failure,rollback}).catch(()=>{});
+      prior_authority:{process_armed:priorStatus.process_armed,coding_armed:priorStatus.coding_armed,autonomous_armed:priorStatus.autonomous_armed,desktop_armed:priorStatus.desktop_armed,host_armed:priorStatus.host_armed}});
+    const handoff=await writeHandoff({stateRoot:state,state:journal,journal,statePath,evidenceDir,key,pointerInfo,newPointer,predecessor,priorStatus,workspace,launchers,stableMcpUrl,mcpUrlSnapshot,controlCtx:control.ctx});
+    const supervisor=await spawnDetachedSupervisor({script:handoff.body.supervisor_script,handoffPath:handoff.path,cwd:control.ctx.core_root});
+    return {ok:true,handed_off:true,completed:false,update_id:updateId,state_path:statePath,handoff_path:handoff.path,handoff_receipt_sha256:handoff.receipt.receipt_sha256,supervisor_pid:supervisor.pid,pointer:newPointer};
+  }catch(error){
+    const failure={schema:FAILURE_SCHEMA,update_id:updateId,release_version:expectedVersion,candidate_manifest_sha256:expectedManifest,failed_at_utc:new Date().toISOString(),
+      phase:journal.phase??'unknown',error:{name:error?.name??'Error',code:error?.code??null,message:String(error?.message??error)},
+      predecessor_mode:predecessor?.mode??null,prior_pointer:publicPointer(pointerInfo?.pointer??null),attempted_pointer:publicPointer(newPointer),old_runtime:generationTuple(oldRuntime),
+      rollback:{attempted:false,new_runtime_stopped:false,pointer_restored:false,launchers_restored:false,workspace_restored:false,mcp_url_restored:false,old_runtime_restarted:false,authority_restored:false,errors:[]}};
+    await writeState(statePath,journal,'failed',{failure}).catch(()=>{});
     let failureReceipt=null;
-    try { failureReceipt=await writeEnvelope(failurePath,failure,key); await writeState(statePath,journal,'failed_receipted',{failure_receipt_path:failurePath,failure_receipt_sha256:failureReceipt.receipt_sha256}); }
-    catch(receiptError){ rollback.errors.push(`failure-receipt:${receiptError.message}`); await writeState(statePath,journal,'failed_unreceipted',{rollback}).catch(()=>{}); }
-    const wrapped=new Error(`R27 slot update failed: ${error?.message??error}`); wrapped.cause=error; wrapped.statePath=statePath;
-    wrapped.failureReceiptPath=failureReceipt?failurePath:null; throw wrapped;
+    try{ failureReceipt=await writeEnvelope(failurePath,failure,key);await writeState(statePath,journal,'failed_receipted',{failure_receipt_path:failurePath,failure_receipt_sha256:failureReceipt.receipt_sha256});}
+    catch(receiptError){ await writeState(statePath,journal,'failed_unreceipted',{failure_receipt_error:String(receiptError?.message??receiptError)}).catch(()=>{}); }
+    const wrapped=new Error('R27 slot update handoff failed: '+(error?.message??error));wrapped.cause=error;wrapped.statePath=statePath;wrapped.failureReceiptPath=failureReceipt?failurePath:null;throw wrapped;
   }
 }
 
@@ -1134,18 +1469,47 @@ export async function runSlotUpdateCli(argv=process.argv.slice(2),{stateRoot=DEF
     const args=parseRollbackArgs(argv);
     const result=await performSlotRollback({activationReceipt:args.activationReceipt,stateRoot});
     console.log('R31_SLOT_ROLLBACK_PASS');
-    console.log(`ROLLBACK_ID ${result.rollback_id}`); console.log(`RECEIPT_SHA256 ${result.receipt_sha256}`);
-    console.log(`STATE_PATH ${result.state_path}`); console.log(`ACTIVE_RELEASE ${result.pointer.release_id}`);
+    console.log('ROLLBACK_ID '+result.rollback_id); console.log('RECEIPT_SHA256 '+result.receipt_sha256);
+    console.log('STATE_PATH '+result.state_path); console.log('ACTIVE_RELEASE '+result.pointer.release_id);
+    return result;
+  }
+  if(argv.includes('--resume-handoff')){
+    const args=parseResumeHandoffArgs(argv);
+    const result=await resumeSlotUpdate({handoffPath:args.handoff});
+    console.log(result.completed?'R27_SLOT_UPDATE_RESUME_PASS':'R27_SLOT_UPDATE_RESUME_DEFERRED');
+    console.log('UPDATE_ID '+result.update_id);
+    console.log('STATE_PATH '+result.state_path);
+    if(result.receipt_sha256) console.log('RECEIPT_SHA256 '+result.receipt_sha256);
+    return result;
+  }
+  if(argv.includes('--recover-interrupted')){
+    const result=await recoverInterruptedSlotUpdates({stateRoot});
+    console.log('R27_SLOT_UPDATE_RECOVERY launched='+result.launched);
+    for(const update of result.updates) console.log('UPDATE_ID '+update.update_id+' SUPERVISOR_PID '+update.supervisor_pid);
     return result;
   }
   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,hostPolicyBootstrap:args.hostPolicyBootstrap,desktopPolicyBootstrap:args.desktopPolicyBootstrap,semanticLspBootstrap:args.semanticLspBootstrap,enableMachineFs:args.enableMachineFs,
-    enableObservation:args.enableObservation,enableDesktop:args.enableDesktop,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}`);
+  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,
+    hostPolicyBootstrap:args.hostPolicyBootstrap,codingPolicyBootstrap:args.codingPolicyBootstrap,desktopPolicyBootstrap:args.desktopPolicyBootstrap,
+    semanticLspBootstrap:args.semanticLspBootstrap,enableMachineFs:args.enableMachineFs,enableObservation:args.enableObservation,
+    enableDesktop:args.enableDesktop,enableAutonomousSupervisor:args.enableAutonomousSupervisor,hostCommandPins:args.hostCommandPins
+  });
+  if(result.handed_off){
+    console.log('R27_SLOT_UPDATE_HANDOFF version='+args.expectedVersion);
+    console.log('UPDATE_ID '+result.update_id);
+    console.log('HANDOFF_PATH '+result.handoff_path);
+    console.log('HANDOFF_RECEIPT_SHA256 '+result.handoff_receipt_sha256);
+    console.log('SUPERVISOR_PID '+result.supervisor_pid);
+  }else{
+    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);
+  }
   return result;
 }
 const invoked=process.argv[1]&&path.resolve(process.argv[1])===path.resolve(fileURLToPath(import.meta.url));