deadbyte-mcp 0.8.7

package/src/runtime-update.mjs

@@ -0,0 +1,961 @@
+import { createHash, createPrivateKey, createPublicKey, randomBytes, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { 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';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  atomicWriteActivePointer,
+  materializeReleaseSlot,
+  parseActivePointer,
+  parseManifest,
+  releaseId,
+  renderStableLauncherCmd,
+  renderStableLauncherPs1,
+  sha256Bytes,
+  verifyManifestTree
+} from './release-slot.mjs';
+import { createGenerationBundle, verifyGenerationBundle } from './release-generation.mjs';
+
+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 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');
+const TOP_LAUNCHER=path.join(os.homedir(),'Downloads','DEADBYTE-MCP.cmd');
+const RUNTIME_STABILITY_MS=12000;
+const RUNTIME_STABILITY_POLL_MS=500;
+
+const sha256File=async file=>sha256Bytes(await readFile(file));
+const sleep=ms=>new Promise(resolve=>setTimeout(resolve,ms));
+const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'
+  ?Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonical(value[key])])):value;
+const canonicalJson=value=>JSON.stringify(canonical(value));
+function normalizePersistentPublicOrigin(value){
+  let publicOrigin;
+  try { publicOrigin=new URL(String(value)); }
+  catch { throw new Error('named tunnel public origin must be one persistent HTTPS origin'); }
+  if(publicOrigin.protocol!=='https:'||publicOrigin.username||publicOrigin.password||publicOrigin.search||publicOrigin.hash||publicOrigin.pathname!=='/'||!publicOrigin.hostname) {
+    throw new Error('named tunnel public origin must be one persistent HTTPS origin without path, query, fragment, or credentials');
+  }
+  if(publicOrigin.hostname.toLowerCase().endsWith('.trycloudflare.com')) throw new Error('named tunnel public origin must be persistent; trycloudflare is forbidden');
+  return publicOrigin.origin;
+}
+export function parseUpdateArgs(argv){
+  const out={stage:null,developmentRoot:null,expectedVersion:null,expectedManifest:null,sourceRoot:null,restoreStandingGrants:false,recoverOfflinePredecessor:false,enableMachineFs:false,enableObservation:false,cloudTransport:null,bridgeBootstrap:null,processPolicyBootstrap:null,hostCommandPins:[]};
+  const cloud={},bridge={},processPolicy={},seen=new Set(),hostPinIds=new Set();
+  const bridgeFlags=new Map([
+    ['--bridge-root','root'],['--bridge-script-sha256','scriptSha256']
+  ]);
+  const processPolicyFlags=new Map([
+    ['--process-policy','path'],['--process-policy-sha256','sha256']
+  ]);
+  const cloudFlags=new Map([
+    ['--cloud-cloudflared','cloudflaredPath'],['--cloud-cloudflared-sha256','cloudflaredSha256'],
+    ['--cloud-token-file','tokenFilePath'],['--cloud-token-sha256','tokenFileSha256'],
+    ['--cloud-child-working-directory','childWorkingDirectory'],['--cloud-public-origin','publicOrigin']
+  ]);
+  const valued=new Set(['--stage','--development-root','--expected-version','--expected-manifest','--source-root','--host-command-pin',...bridgeFlags.keys(),...processPolicyFlags.keys(),...cloudFlags.keys()]);
+  for(let index=0;index<argv.length;index++){
+    const arg=argv[index];
+    if(arg==='--restore-standing-grants'||arg==='--recover-offline-predecessor'||arg==='--enable-machine-fs'||arg==='--enable-observation'){
+      if(seen.has(arg)) throw new Error(`duplicate self-update argument '${arg}'`);
+      seen.add(arg);
+      if(arg==='--restore-standing-grants') out.restoreStandingGrants=true;
+      else if(arg==='--recover-offline-predecessor') out.recoverOfflinePredecessor=true;
+      else if(arg==='--enable-machine-fs') out.enableMachineFs=true;
+      else out.enableObservation=true;
+      continue;
+    }
+    if(arg==='--host-command-pin'){
+      const value=argv[++index];
+      if(!value) throw new Error('--host-command-pin requires command_id=sha256');
+      const match=/^([A-Za-z0-9._-]{1,64})=([0-9a-f]{64})$/.exec(value);
+      if(!match) throw new Error('host command pin must be command_id=lowercase_sha256');
+      const [,commandId,sha256]=match;
+      if(hostPinIds.has(commandId)) throw new Error(`duplicate host command pin '${commandId}'`);
+      hostPinIds.add(commandId); out.hostCommandPins.push({commandId,sha256}); continue;
+    }
+    if(!valued.has(arg)) throw new Error(`unknown self-update argument '${arg}'`);
+    if(seen.has(arg)) throw new Error(`duplicate self-update argument '${arg}'`);
+    seen.add(arg);
+    const value=argv[++index];
+    if(!value) throw new Error(`${arg} requires a value`);
+    if(arg==='--stage') out.stage=path.resolve(value);
+    else if(arg==='--development-root') out.developmentRoot=path.resolve(value);
+    else if(arg==='--expected-version') out.expectedVersion=value;
+    else if(arg==='--expected-manifest') out.expectedManifest=value.toLowerCase();
+    else if(arg==='--source-root') out.sourceRoot=path.resolve(value);
+    else if(bridgeFlags.has(arg)) bridge[bridgeFlags.get(arg)]=value;
+    else if(processPolicyFlags.has(arg)) processPolicy[processPolicyFlags.get(arg)]=value;
+    else cloud[cloudFlags.get(arg)]=value;
+  }
+  if(!out.stage) throw new Error('--stage is required');
+  if(!out.developmentRoot) throw new Error('--development-root is required');
+  if(!SEMVER.test(String(out.expectedVersion??''))) throw new Error('--expected-version must be SemVer');
+  if(!HEX64.test(String(out.expectedManifest??''))) throw new Error('--expected-manifest must be lowercase SHA-256 hex');
+  const bridgeFields=[...bridgeFlags.values()],bridgePresent=bridgeFields.filter(key=>bridge[key]!==undefined);
+  if(bridgePresent.length!==0&&bridgePresent.length!==bridgeFields.length) throw new Error('bridge bootstrap requires root plus script SHA-256 as one pair');
+  if(bridgePresent.length===bridgeFields.length){
+    const scriptSha256=String(bridge.scriptSha256).toLowerCase();
+    if(!HEX64.test(scriptSha256)) throw new Error('bridge script SHA-256 must be lowercase hex');
+    out.bridgeBootstrap={root:path.resolve(bridge.root),scriptSha256};
+  }
+  const processPolicyFields=[...processPolicyFlags.values()],processPolicyPresent=processPolicyFields.filter(key=>processPolicy[key]!==undefined);
+  if(processPolicyPresent.length!==0&&processPolicyPresent.length!==processPolicyFields.length) throw new Error('process policy bootstrap requires path plus SHA-256 as one pair');
+  if(processPolicyPresent.length===processPolicyFields.length){
+    const sha256=String(processPolicy.sha256).toLowerCase();
+    if(!HEX64.test(sha256)) throw new Error('process policy SHA-256 must be lowercase hex');
+    out.processPolicyBootstrap={path:path.resolve(processPolicy.path),sha256};
+  }
+  const cloudFields=[...cloudFlags.values()],present=cloudFields.filter(key=>cloud[key]!==undefined);
+  if(present.length!==0&&present.length!==cloudFields.length) throw new Error('named tunnel bootstrap requires cloud path/hash/token/workdir plus persistent public origin');
+  if(present.length===cloudFields.length){
+    for(const key of ['cloudflaredSha256','tokenFileSha256']) cloud[key]=String(cloud[key]).toLowerCase();
+    if(!HEX64.test(cloud.cloudflaredSha256)||!HEX64.test(cloud.tokenFileSha256)) throw new Error('named tunnel dependency SHA-256 must be lowercase hex');
+    const publicOrigin=normalizePersistentPublicOrigin(cloud.publicOrigin);
+    out.cloudTransport={
+      cloudflared:{path:path.resolve(cloud.cloudflaredPath),sha256:cloud.cloudflaredSha256},
+      tokenFile:{path:path.resolve(cloud.tokenFilePath),sha256:cloud.tokenFileSha256},
+      childWorkingDirectory:path.resolve(cloud.childWorkingDirectory),
+      publicOrigin
+    };
+  }
+  return out;
+}
+
+export function parseRollbackArgs(argv){
+  let activationReceipt=null;
+  for(let index=0;index<argv.length;index++){
+    const arg=argv[index];
+    if(arg!=='--rollback-receipt') throw new Error(`unknown rollback argument '${arg}'`);
+    if(activationReceipt!==null) throw new Error("duplicate rollback argument '--rollback-receipt'");
+    const value=argv[++index];
+    if(!value) throw new Error('--rollback-receipt requires a value');
+    activationReceipt=path.resolve(value);
+  }
+  if(!activationReceipt) throw new Error('--rollback-receipt is required');
+  return {activationReceipt};
+}
+
+function powershellPath(){
+  return path.join(process.env.SystemRoot||'C:\\Windows','System32','WindowsPowerShell','v1.0','powershell.exe');
+}
+function windowsPowerShellEnvironment(base=process.env){
+  const systemRoot=base.SystemRoot||base.SYSTEMROOT||'C:\\Windows';
+  const userProfile=base.USERPROFILE||os.homedir();
+  const programFiles=base.ProgramFiles||base.PROGRAMFILES||'C:\\Program Files';
+  return {...base,PSModulePath:[
+    path.join(userProfile,'Documents','WindowsPowerShell','Modules'),
+    path.join(programFiles,'WindowsPowerShell','Modules'),
+    path.join(systemRoot,'System32','WindowsPowerShell','v1.0','Modules')
+  ].join(';')};
+}
+function commandEnvironment(exe,base=process.env){
+  return path.resolve(exe).toLowerCase()===path.resolve(powershellPath()).toLowerCase()
+    ?windowsPowerShellEnvironment(base):base;
+}
+function runCaptured(exe,args,{cwd,env,timeoutMs=45000}={}){
+  const baseEnv=env??process.env;
+  const childEnv=commandEnvironment(exe,baseEnv);
+  const result=spawnSync(exe,args,{cwd,env:childEnv,encoding:'utf8',windowsHide:true,timeout:timeoutMs,maxBuffer:16*1024*1024});
+  return {status:result.status,signal:result.signal,error:result.error?{code:result.error.code??null,message:result.error.message}:null,stdout:result.stdout??'',stderr:result.stderr??''};
+}
+function assertRun(result,label){
+  if(result.error||result.status!==0) throw new Error(`${label} failed status=${result.status} error=${result.error?.message??'none'}\n${result.stderr||result.stdout}`);
+  return result.stdout;
+}
+export async function loadPowerShellDataFile(file){
+  const env={...process.env,DEADBYTE_R27_CONFIG_READ:path.resolve(file)};
+  const command="$ErrorActionPreference='Stop'; $v=Import-PowerShellDataFile -LiteralPath $env:DEADBYTE_R27_CONFIG_READ; $v | ConvertTo-Json -Depth 16 -Compress";
+  const result=runCaptured(powershellPath(),['-NoLogo','-NoProfile','-Command',command],{env,timeoutMs:15000});
+  const text=assertRun(result,'PowerShell data-file load').trim();
+  let value; try { value=JSON.parse(text); } catch(error){ throw new Error(`controller config JSON conversion failed: ${error.message}`); }
+  if(!value||typeof value!=='object'||Array.isArray(value)) throw new Error('controller config must be an object');
+  return value;
+}
+async function readJson(file){
+  const text=(await readFile(file,'utf8')).replace(/^\uFEFF/,'');
+  let value; try { value=JSON.parse(text); } catch(error){ throw new Error(`JSON invalid ${file}: ${error.message}`); }
+  return value;
+}
+async function atomicBytes(file,bytes){
+  await mkdir(path.dirname(file),{recursive:true});
+  const temp=`${file}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`;
+  const handle=await open(temp,'wx');
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+  try { await rename(temp,file); } catch(error){ await rm(temp,{force:true}).catch(()=>{}); throw error; }
+  if(sha256Bytes(await readFile(file))!==sha256Bytes(bytes)) throw new Error(`atomic write readback mismatch: ${file}`);
+}
+async function normalizeComponentIdentities(config){
+  const next=structuredClone(config);
+  for(const name of ['Bridge','Cloud']){
+    const spec=next[name];
+    if(!spec||typeof spec!=='object') throw new Error(`${name} launch specification missing`);
+    if(typeof spec.FilePath!=='string'||!path.isAbsolute(spec.FilePath)) throw new Error(`${name} FilePath must be absolute`);
+    const exe=path.resolve(spec.FilePath);
+    const stat=await lstat(exe);
+    if(!stat.isFile()||stat.isSymbolicLink()) throw new Error(`${name} executable must be a regular file`);
+    const actual=await sha256File(exe);
+    if(spec.FileSha256!==undefined&&spec.FileSha256!==''&&spec.FileSha256!==actual) throw new Error(`${name} executable pin drift detected`);
+    spec.FilePath=exe; spec.FileSha256=actual;
+    const dependencies=spec.Dependencies??[];
+    if(!Array.isArray(dependencies)||dependencies.length>16) throw new Error(`${name} Dependencies invalid`);
+    const normalizedDependencies=[];
+    for(const dependency of dependencies){
+      const depName=String(dependency?.Name??'');
+      const depPath=path.resolve(String(dependency?.Path??''));
+      const depHash=String(dependency?.Sha256??'').toLowerCase();
+      if(!/^[A-Za-z0-9._-]{1,32}$/.test(depName)||!path.isAbsolute(String(dependency?.Path??''))||!HEX64.test(depHash)) throw new Error(`${name} dependency contract invalid`);
+      const depStat=await lstat(depPath); if(!depStat.isFile()||depStat.isSymbolicLink()) throw new Error(`${name} dependency must be a regular file: ${depName}`);
+      const depActual=await sha256File(depPath); if(depActual!==depHash) throw new Error(`${name} dependency pin drift detected: ${depName}`);
+      normalizedDependencies.push({Name:depName,Path:depPath,Sha256:depHash});
+    }
+    spec.Dependencies=normalizedDependencies;
+    if(name==='Cloud'&&spec.Transport!==undefined){
+      const transport=String(spec.Transport);
+      const valid=(transport==='deadbyte.named-tunnel.v1'&&normalizedDependencies.length===3)||
+        (transport==='deadbyte.named-tunnel.v2'&&normalizedDependencies.length===2);
+      if(!valid) throw new Error('Cloud named tunnel transport contract invalid');
+    }
+  }
+  const bridge=next.Bridge;
+  const raw=String(bridge.Arguments??'');
+  const normalized=raw.replaceAll('\\','/');
+  if(!/^[A-Za-z0-9._/-]+\.(?:mjs|js)$/.test(normalized)||path.posix.isAbsolute(normalized)||normalized.split('/').includes('..')) {
+    throw new Error('R27 Bridge Arguments must be one relative .mjs/.js script path');
+  }
+  if(typeof bridge.WorkingDirectory!=='string'||!path.isAbsolute(bridge.WorkingDirectory)) throw new Error('Bridge WorkingDirectory must be absolute');
+  const script=path.resolve(bridge.WorkingDirectory,...normalized.split('/'));
+  const scriptStat=await lstat(script);
+  if(!scriptStat.isFile()||scriptStat.isSymbolicLink()) throw new Error('Bridge script must be a regular file');
+  const scriptHash=await sha256File(script);
+  if(bridge.ScriptSha256!==undefined&&bridge.ScriptSha256!==''&&bridge.ScriptSha256!==scriptHash) throw new Error('Bridge script pin drift detected');
+  bridge.ScriptPath=script; bridge.ScriptSha256=scriptHash;
+  return next;
+}
+
+export async function prepareBridgeSpec(config,bootstrap){
+  if(!bootstrap) return structuredClone(config);
+  if(typeof bootstrap.root!=='string'||!path.isAbsolute(bootstrap.root)||!HEX64.test(String(bootstrap.scriptSha256??''))) {
+    throw new Error('bridge bootstrap requires absolute root plus lowercase script SHA-256');
+  }
+  const root=path.resolve(bootstrap.root),rootStat=await lstat(root);
+  if(!rootStat.isDirectory()||rootStat.isSymbolicLink()) throw new Error('bridge root must be a real directory');
+  const packageFile=path.join(root,'package.json'),script=path.join(root,'src','bridge.mjs');
+  const packageStat=await lstat(packageFile),scriptStat=await lstat(script);
+  if(!packageStat.isFile()||packageStat.isSymbolicLink()) throw new Error('bridge package.json must be a regular file');
+  if(!scriptStat.isFile()||scriptStat.isSymbolicLink()) throw new Error('bridge script must be a regular file');
+  const pkg=JSON.parse(await readFile(packageFile,'utf8'));
+  if(pkg?.name!=='deadbyte-chatgpt-bridge') throw new Error('bridge package identity mismatch');
+  const actual=await sha256File(script),expected=String(bootstrap.scriptSha256).toLowerCase();
+  if(actual!==expected) throw new Error(`bridge script SHA-256 mismatch: expected ${expected}, found ${actual}`);
+  const next=structuredClone(config);
+  if(!next.Bridge||typeof next.Bridge!=='object') throw new Error('Bridge launch specification missing');
+  next.Bridge.WorkingDirectory=root;
+  next.Bridge.Arguments='src\\bridge.mjs';
+  next.Bridge.ScriptPath=script;
+  next.Bridge.ScriptSha256=actual;
+  return next;
+}
+
+function quoteWindowsArgument(value){
+  const text=String(value??'');
+  if(text.length<1||/["\r\n\0]/.test(text)) throw new Error('named tunnel argument contains unsafe characters');
+  const trailing=(/\\+$/.exec(text)?.[0].length??0);
+  return `"${text}${'\\'.repeat(trailing)}"`;
+}
+async function verifyPinnedRegularFile(file,expected,label){
+  if(typeof file!=='string'||!path.isAbsolute(file)||!HEX64.test(String(expected??''))) throw new Error(`${label} pin contract invalid`);
+  const absolute=path.resolve(file),stat=await lstat(absolute);
+  if(!stat.isFile()||stat.isSymbolicLink()) throw new Error(`${label} must be a regular file`);
+  const actual=await sha256File(absolute);
+  if(actual!==expected) throw new Error(`${label} SHA-256 mismatch: expected ${expected}, found ${actual}`);
+  return {path:absolute,sha256:actual};
+}
+
+export async function prepareProcessPolicyBootstrap(bootstrap){
+  if(!bootstrap) return null;
+  const pinned=await verifyPinnedRegularFile(bootstrap.path,bootstrap.sha256,'process policy');
+  const policy=await readJson(pinned.path);
+  if(policy?.schema!=='deadbyte.process-policy.v1'||policy?.enabled!==true) throw new Error('process policy schema/enabled mismatch');
+  return {...pinned,policy};
+}
+
+async function preparePinnedCommandPolicy(policy,{commandPins=[],schema,label}={}){
+  if(!policy) return {policy:null,repinned:[],matchedCommandIds:[]};
+  if(policy.schema!==schema||policy.enabled!==true||!policy.commands||typeof policy.commands!=='object'||Array.isArray(policy.commands)) {
+    throw new Error(`${label} policy schema/enabled/commands mismatch`);
+  }
+  const requested=new Map();
+  for(const pin of commandPins){
+    const commandId=String(pin?.commandId??''),sha256=String(pin?.sha256??'').toLowerCase();
+    if(!/^[A-Za-z0-9._-]{1,64}$/.test(commandId)||!HEX64.test(sha256)) throw new Error(`${label} command pin contract invalid`);
+    if(requested.has(commandId)) throw new Error(`duplicate ${label} command pin '${commandId}'`);
+    requested.set(commandId,sha256);
+  }
+  const next=structuredClone(policy),repinned=[],matchedCommandIds=[];
+  for(const [commandId,command] of Object.entries(next.commands)){
+    const executable=String(command?.executable??''),expected=String(command?.executable_sha256??'').toLowerCase();
+    if(!path.isAbsolute(executable)||!HEX64.test(expected)) throw new Error(`${label} command '${commandId}' executable pin contract invalid`);
+    const absolute=path.resolve(executable),stat=await lstat(absolute);
+    if(!stat.isFile()||stat.isSymbolicLink()) throw new Error(`${label} command '${commandId}' executable must be a regular file`);
+    const actual=await sha256File(absolute),explicit=requested.get(commandId);
+    if(explicit) matchedCommandIds.push(commandId);
+    if(actual!==expected){
+      if(!explicit) throw new Error(`${label} command '${commandId}' executable pin drift detected; explicit --host-command-pin ${commandId}=${actual} required`);
+      if(explicit!==actual) throw new Error(`${label} command '${commandId}' repin mismatch: supplied ${explicit}, observed ${actual}`);
+      command.executable_sha256=actual;
+      repinned.push({command_id:commandId,executable:absolute,prior_sha256:expected,new_sha256:actual});
+    } else if(explicit&&explicit!==actual){
+      throw new Error(`${label} command '${commandId}' repin mismatch: supplied ${explicit}, observed ${actual}`);
+    }
+  }
+  return {policy:next,repinned,matchedCommandIds};
+}
+
+export async function prepareHostPolicy(policy,{commandPins=[]}={}){
+  if(!policy&&commandPins.length) throw new Error('host command pins supplied but host policy is not configured');
+  const result=await preparePinnedCommandPolicy(policy,{commandPins,schema:'deadbyte.host-policy.v1',label:'host'});
+  const matched=new Set(result.matchedCommandIds);
+  const unknown=commandPins.find(pin=>!matched.has(String(pin?.commandId??'')));
+  if(unknown) throw new Error(`unknown host command pin '${unknown.commandId}'`);
+  return {policy:result.policy,repinned:result.repinned};
+}
+
+export async function prepareAuthorityPolicies({hostPolicy,codingPolicy},{commandPins=[]}={}){
+  const host=await preparePinnedCommandPolicy(hostPolicy,{commandPins,schema:'deadbyte.host-policy.v1',label:'host'});
+  const coding=await preparePinnedCommandPolicy(codingPolicy,{commandPins,schema:'deadbyte.coding-policy.v1',label:'coding'});
+  const matched=new Set([...host.matchedCommandIds,...coding.matchedCommandIds]);
+  const unknown=commandPins.find(pin=>!matched.has(String(pin?.commandId??'')));
+  if(unknown) throw new Error(`unknown authority command pin '${unknown.commandId}'`);
+  return {hostPolicy:host.policy,codingPolicy:coding.policy,hostRepinned:host.repinned,codingRepinned:coding.repinned};
+}
+
+export async function prepareNamedTunnelCloudSpec(config,{releaseRoot,bootstrap=null}={}){
+  const next=structuredClone(config),cloud=next.Cloud??{};
+  const useNamed=bootstrap!==null||cloud.Transport==='deadbyte.named-tunnel.v1'||cloud.Transport==='deadbyte.named-tunnel.v2';
+  if(!useNamed) return next;
+  const release=path.resolve(releaseRoot),hostPath=path.join(release,'bin','deadbyte-tunnel-host.exe');
+  const hostStat=await lstat(hostPath); if(!hostStat.isFile()||hostStat.isSymbolicLink()) throw new Error('named tunnel host must be a regular release file');
+  const hostSha256=await sha256File(hostPath);
+  if(bootstrap!==null){
+    const cloudflared=await verifyPinnedRegularFile(bootstrap.cloudflared.path,bootstrap.cloudflared.sha256,'named tunnel cloudflared');
+    const tokenFile=await verifyPinnedRegularFile(bootstrap.tokenFile.path,bootstrap.tokenFile.sha256,'named tunnel token file');
+    const childWorkingDirectory=path.resolve(bootstrap.childWorkingDirectory),workStat=await lstat(childWorkingDirectory);
+    if(!workStat.isDirectory()||workStat.isSymbolicLink()) throw new Error('named tunnel child working directory must be a real directory');
+    next.Cloud={...cloud,FilePath:hostPath,FileSha256:hostSha256,
+      Arguments:[cloudflared.path,tokenFile.path,childWorkingDirectory].map(quoteWindowsArgument).join(' '),
+      WorkingDirectory:release,Transport:'deadbyte.named-tunnel.v2',Dependencies:[
+        {Name:'cloudflared',Path:cloudflared.path,Sha256:cloudflared.sha256},
+        {Name:'tunnel-token',Path:tokenFile.path,Sha256:tokenFile.sha256}
+      ]};
+  } else {
+    if(cloud.Transport!=='deadbyte.named-tunnel.v2') throw new Error('legacy named tunnel transport requires explicit v2 bootstrap');
+    if(!Array.isArray(cloud.Dependencies)||cloud.Dependencies.length!==2) throw new Error('existing named tunnel dependency contract missing');
+    next.Cloud={...cloud,FilePath:hostPath,FileSha256:hostSha256,WorkingDirectory:release};
+  }
+  return next;
+}
+async function ensureStableMcpPath({stateRoot,sourceRoot}){
+  const bridgeDir=path.join(stateRoot,'bridge');
+  const tokenFile=path.join(bridgeDir,'path-token.txt');
+  let token='';
+  try { token=(await readFile(tokenFile,'utf8')).trim(); } catch(error){
+    if(error?.code!=='ENOENT') throw error;
+    if(!sourceRoot) throw new Error('bridge path token missing and no bootstrap source root supplied');
+    const legacy=(await readFile(path.join(sourceRoot,'controller','runtime','mcp-path.txt'),'utf8')).trim();
+    const match=/^\/mcp\/([0-9a-f]{64})$/.exec(legacy);
+    if(!match) throw new Error('legacy MCP path cannot seed stable token');
+    token=match[1];
+    await mkdir(bridgeDir,{recursive:true});
+    await atomicBytes(tokenFile,Buffer.from(`${token}\n`,'ascii'));
+  }
+  if(!HEX64.test(token)) throw new Error('bridge path token invalid');
+  const stableFile=path.join(bridgeDir,'mcp-path.txt');
+  const desired=Buffer.from(`/mcp/${token}\n`,'ascii');
+  if(existsSync(stableFile)){
+    const found=await readFile(stableFile);
+    if(!found.equals(desired)) throw new Error('stable MCP path file conflicts with token');
+  } else await atomicBytes(stableFile,desired);
+  return {path:stableFile,sha256:sha256Bytes(desired)};
+}
+export async function ensureStableMcpUrl({stateRoot,publicOrigin,mcpPathFile}){
+  const origin=normalizePersistentPublicOrigin(publicOrigin);
+  if(typeof mcpPathFile!=='string'||!path.isAbsolute(mcpPathFile)) throw new Error('stable MCP path file must be absolute');
+  const pathStat=await lstat(mcpPathFile);
+  if(!pathStat.isFile()||pathStat.isSymbolicLink()) throw new Error('stable MCP path file must be a regular file');
+  const mcpPath=(await readFile(mcpPathFile,'ascii')).trim();
+  if(!/^\/mcp\/[0-9a-f]{64}$/.test(mcpPath)) throw new Error('stable MCP path file is invalid');
+  const bridgeDir=path.join(path.resolve(stateRoot),'bridge'),stableFile=path.join(bridgeDir,'mcp-url.txt');
+  const desired=Buffer.from(`${origin}${mcpPath}\n`,'ascii');
+  const before=existsSync(stableFile)?await readFile(stableFile):null;
+  if(!before||!before.equals(desired)) await atomicBytes(stableFile,desired);
+  return {path:stableFile,sha256:sha256Bytes(desired),origin,changed:!before||!before.equals(desired)};
+}
+
+async function snapshotFile(file){
+  try { const bytes=await readFile(file); return {exists:true,bytes,sha256:sha256Bytes(bytes)}; }
+  catch(error){ if(error?.code==='ENOENT') return {exists:false,bytes:null,sha256:null}; throw error; }
+}
+async function restoreFile(file,snapshot){
+  if(snapshot.exists) await atomicBytes(file,snapshot.bytes);
+  else await rm(file,{force:true});
+}
+
+export function parseControllerStatus(text){
+  const number=re=>{const match=re.exec(text);return match?Number(match[1]):null;};
+  return {
+    online:/DEADBYTE MCP = ONLINE/.test(text),
+    offline:/DEADBYTE MCP = OFFLINE/.test(text),
+    bridge_pid:number(/Bridge PID\s*:\s*(\d+)\s*\[verified\]/),
+    cloud_pid:number(/Cloud PID\s*:\s*(\d+)\s*\[verified\]/),
+    local_ready:/Local ready\s*:\s*True/.test(text),
+    coding_armed:/Coding plane\s*:\s*ARMED \[standing-grant\]/.test(text),
+    autonomous_armed:/Autonomous\s*:\s*ARMED \[standing-grant\]/.test(text),
+    host_armed:/Host plane\s*:\s*ARMED \[standing-grant\]/.test(text)
+  };
+}
+function controlResult(exe,args,{cwd,env,timeoutMs=45000,stdio='pipe'}={}){
+  if(stdio==='ignore'){
+    const result=spawnSync(exe,args,{cwd,env:commandEnvironment(exe,env??process.env),windowsHide:true,timeout:timeoutMs,stdio:'ignore'});
+    return {status:result.status,signal:result.signal,error:result.error?{code:result.error.code??null,message:result.error.message}:null,stdout:'',stderr:''};
+  }
+  return runCaptured(exe,args,{cwd,env,timeoutMs});
+}
+export function legacyContext(sourceRoot){
+  const root=path.resolve(sourceRoot);
+  const candidates=['deadbyte-controller-r26.ps1','deadbyte-controller.ps1'];
+  const controller=candidates.map(name=>path.join(root,'controller',name)).find(existsSync);
+  if(!controller) throw new Error('legacy controller entry missing');
+  return {kind:'legacy',source_root:root,core_root:root,controller_path:controller,
+    cwd:root,runtime_root:path.join(root,'controller','runtime'),state_root:null};
+}
+function slotContext(stateRoot,pointer){
+  return {kind:'slot',source_root:null,core_root:path.resolve(pointer.release_root),
+    controller_path:path.join(pointer.release_root,'controller','deadbyte-controller.ps1'),
+    cwd:path.resolve(pointer.release_root),runtime_root:path.join(path.resolve(stateRoot),'runtime'),
+    state_root:path.resolve(stateRoot),pointer};
+}
+function launcherPath(stateRoot){ return path.join(path.resolve(stateRoot),'bin','DEADBYTE-MCP.ps1'); }
+function controllerInvocation(ctx,command){
+  if(ctx.kind==='slot') return {exe:powershellPath(),args:['-NoLogo','-NoProfile','-ExecutionPolicy','Bypass','-File',launcherPath(ctx.state_root),command],cwd:ctx.state_root};
+  return {exe:powershellPath(),args:['-NoLogo','-NoProfile','-ExecutionPolicy','Bypass','-File',ctx.controller_path,command],cwd:ctx.cwd};
+}
+function controllerCaptured(ctx,command,timeoutMs=45000){
+  const call=controllerInvocation(ctx,command); const result=controlResult(call.exe,call.args,{cwd:call.cwd,timeoutMs});
+  return assertRun(result,`controller ${command}`);
+}
+export function runControllerStartNoCapture(ctx,timeoutMs=45000){
+  const call=controllerInvocation(ctx,'start');
+  return controlResult(call.exe,call.args,{cwd:call.cwd,timeoutMs,stdio:'ignore'});
+}
+async function readLedger(ctx,name){
+  const file=path.join(ctx.runtime_root,`${name}.instance.json`);
+  const value=JSON.parse((await readFile(file,'utf8')).replace(/^\uFEFF/,''));
+  if(value.schema!=='deadbyte.controller.v1'||value.component!==name||!Number.isInteger(Number(value.pid))||
+      !HEX64.test(String(value.instance_nonce))||!HEX64.test(String(value.image_sha256))) {
+    throw new Error(`${name} ledger identity invalid`);
+  }
+  return {schema:value.schema,component:value.component,instance_nonce:String(value.instance_nonce),
+    pid:Number(value.pid),creation_time_utc:String(value.creation_time_utc??''),image_path:String(value.image_path??''),
+    image_sha256:String(value.image_sha256)};
+}
+function sameGeneration(a,b){
+  return a.pid===b.pid&&a.instance_nonce===b.instance_nonce&&a.creation_time_utc===b.creation_time_utc&&a.image_sha256===b.image_sha256;
+}
+function nodeProcesses(){
+  const command=`Get-CimInstance Win32_Process -Filter \"Name='node.exe'\" | Select-Object ProcessId,ParentProcessId,CreationDate,ExecutablePath,CommandLine | ConvertTo-Json -Compress`;
+  const result=runCaptured(powershellPath(),['-NoLogo','-NoProfile','-Command',command],{timeoutMs:15000});
+  const text=assertRun(result,'node process query').trim(); if(!text) return [];
+  const parsed=JSON.parse(text); return Array.isArray(parsed)?parsed:[parsed];
+}
+function coreProcess(coreRoot,bridgePid){
+  const needle=path.join(coreRoot,'src','mcp-server.mjs').replaceAll('/','\\').toLowerCase();
+  const matches=nodeProcesses().filter(item=>Number(item.ParentProcessId)===bridgePid&&String(item.CommandLine??'').toLowerCase().includes(needle));
+  if(matches.length!==1) throw new Error(`expected one downstream core for bridge ${bridgePid}, found ${matches.length}`);
+  const item=matches[0]; return {pid:Number(item.ProcessId),parent_pid:Number(item.ParentProcessId),creation_date:String(item.CreationDate??''),
+    executable_path:String(item.ExecutablePath??''),command_line:String(item.CommandLine??'')};
+}
+async function captureRuntime(ctx){
+  const statusText=controllerCaptured(ctx,'status',15000); const status=parseControllerStatus(statusText);
+  if(!status.online||!status.bridge_pid||!status.cloud_pid||!status.local_ready) throw new Error(`slot update requires ONLINE runtime: ${statusText}`);
+  if(status.host_armed) throw new Error('slot update requires host plane DISARMED');
+  if(status.autonomous_armed&&!status.coding_armed) throw new Error('invalid runtime authority: autonomous armed without coding');
+  const bridge=await readLedger(ctx,'bridge'); const cloud=await readLedger(ctx,'cloud'); const core=coreProcess(ctx.core_root,status.bridge_pid);
+  return {status,status_text:statusText.trim(),bridge,cloud,core};
+}
+async function capturePredecessor(ctx,recoverOfflinePredecessor){
+  const statusText=controllerCaptured(ctx,'status',15000),status=parseControllerStatus(statusText);
+  if(status.online&&status.bridge_pid&&status.cloud_pid&&status.local_ready){
+    const runtime=await captureRuntime(ctx);
+    return {mode:'online',status:runtime.status,status_text:runtime.status_text,runtime};
+  }
+  if(!recoverOfflinePredecessor) throw new Error(`slot update requires ONLINE runtime: ${statusText}`);
+  if(!status.offline||status.bridge_pid||status.cloud_pid||status.local_ready) throw new Error(`offline predecessor recovery requires clean OFFLINE controller state: ${statusText}`);
+  if(status.host_armed) throw new Error('offline predecessor recovery requires host plane DISARMED');
+  if(status.autonomous_armed&&!status.coding_armed) throw new Error('invalid runtime authority: autonomous armed without coding');
+  return {mode:'offline-recovery',status,status_text:statusText.trim(),runtime:null};
+}
+async function waitCoreGone(runtime,timeoutMs=10000){
+  const started=Date.now();
+  while(Date.now()-started<timeoutMs){
+    const found=nodeProcesses().find(item=>Number(item.ProcessId)===runtime.core.pid&&String(item.CreationDate??'')===runtime.core.creation_date);
+    if(!found) return true; await sleep(250);
+  }
+  return false;
+}
+async function startAndVerify(ctx,oldRuntime){
+  let start=null;
+  for(let attempt=1;attempt<=3;attempt+=1){
+    start=runControllerStartNoCapture(ctx,45000);
+    if(!start.error&&start.status===0) break;
+    if(attempt<3) await sleep(1500);
+  }
+  if(start.error||start.status!==0) throw new Error(`controller start transport failed status=${start.status} error=${start.error?.message??'none'}`);
+  let statusText=''; let status=null;
+  const started=Date.now();
+  while(Date.now()-started<45000){
+    try { statusText=controllerCaptured(ctx,'status',15000); status=parseControllerStatus(statusText); if(status.online&&status.bridge_pid&&status.cloud_pid&&status.local_ready) break; }
+    catch {} await sleep(500);
+  }
+  if(!status?.online||!status.bridge_pid||!status.cloud_pid||!status.local_ready) throw new Error(`new runtime failed ONLINE gate: ${statusText}`);
+  const bridge=await readLedger(ctx,'bridge'); const cloud=await readLedger(ctx,'cloud'); const core=coreProcess(ctx.core_root,status.bridge_pid);
+  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 stabilizeRuntime(ctx,runtime){
+  const started=Date.now(); let probes=0;
+  while(Date.now()-started<RUNTIME_STABILITY_MS){
+    await sleep(RUNTIME_STABILITY_POLL_MS);
+    const statusText=controllerCaptured(ctx,'status',15000),status=parseControllerStatus(statusText);
+    if(!status.online||!status.local_ready||status.bridge_pid!==runtime.bridge.pid||status.cloud_pid!==runtime.cloud.pid) {
+      throw new Error(`new runtime lost stability gate: ${statusText}`);
+    }
+    const bridge=await readLedger(ctx,'bridge'),cloud=await readLedger(ctx,'cloud');
+    if(!sameGeneration(runtime.bridge,bridge)||!sameGeneration(runtime.cloud,cloud)) throw new Error('new runtime generation changed during stability gate');
+    probes++;
+  }
+  controllerCaptured(ctx,'test',60000);
+  const finalText=controllerCaptured(ctx,'status',15000),final=parseControllerStatus(finalText);
+  if(!final.online||!final.local_ready||final.bridge_pid!==runtime.bridge.pid||final.cloud_pid!==runtime.cloud.pid) {
+    throw new Error(`new runtime failed post-public stability gate: ${finalText}`);
+  }
+  return {duration_ms:Date.now()-started,probes,public_mcp_gate:'passed'};
+}
+async function verifyPackageRoot(root,expectedVersion,expectedManifest,label){
+  const absolute=path.resolve(root); const info=await lstat(absolute);
+  if(!info.isDirectory()||info.isSymbolicLink()) throw new Error(`${label} root must be a real directory`);
+  const manifestBytes=await readFile(path.join(absolute,'MANIFEST.SHA256'));
+  const digest=sha256Bytes(manifestBytes); if(digest!==expectedManifest) throw new Error(`${label} manifest digest mismatch: ${digest}`);
+  const entries=parseManifest(manifestBytes.toString('utf8')); await verifyManifestTree(absolute,entries);
+  const pkg=await readJson(path.join(absolute,'package.json'));
+  if(pkg?.name!=='deadbyte-mcp'||pkg?.version!==expectedVersion) throw new Error(`${label} package identity mismatch`);
+  return {root:absolute,manifest_sha256:digest,entries:entries.size};
+}
+async function verifyActiveInstallation(stateRoot,pointer){
+  const state=path.resolve(stateRoot); const expectedRelease=path.join(state,'releases',releaseId(pointer.version,pointer.manifest_sha256));
+  if(path.resolve(pointer.release_root)!==path.resolve(expectedRelease)) throw new Error('active pointer release root is not content-addressed store path');
+  const release=await verifyPackageRoot(pointer.release_root,pointer.version,pointer.manifest_sha256,'active release');
+  const generation=await verifyGenerationBundle(pointer.generation_root,pointer.generation_manifest_sha256);
+  const expectedConfig=path.join(path.resolve(pointer.generation_root),'controller-config.psd1');
+  if(path.resolve(pointer.config_path)!==path.resolve(expectedConfig)) throw new Error('active pointer config path mismatch');
+  const currentLauncher=await sha256File(launcherPath(state));
+  if(currentLauncher!==pointer.launcher_sha256) throw new Error('active pointer launcher digest mismatch');
+  return {release,generation};
+}
+async function loadPointerIfPresent(stateRoot){
+  const file=path.join(path.resolve(stateRoot),'active-release.json');
+  if(!existsSync(file)) return {file,pointer:null,snapshot:await snapshotFile(file)};
+  const snapshot=await snapshotFile(file); const pointer=parseActivePointer(snapshot.bytes.toString('utf8'));
+  await verifyActiveInstallation(stateRoot,pointer); return {file,pointer,snapshot};
+}
+async function loadControlInputs({stateRoot,sourceRoot,pointerInfo}){
+  let configPath,ctx;
+  if(pointerInfo.pointer){
+    configPath=pointerInfo.pointer.config_path; ctx=slotContext(stateRoot,pointerInfo.pointer);
+  } else {
+    if(!sourceRoot) throw new Error('--source-root is required for initial slot migration');
+    ctx=legacyContext(sourceRoot); configPath=path.join(ctx.source_root,'controller','deadbyte-controller.config.psd1');
+  }
+  let config=await loadPowerShellDataFile(configPath); config=await normalizeComponentIdentities(config);
+  const codingPath=String(config.CodingPolicyFile??''); const autonomousPath=String(config.AutonomousPolicyFile??''); const hostPath=String(config.HostPolicyFile??''); const processPath=String(config.ProcessPolicyFile??'');
+  if(!path.isAbsolute(codingPath)||!path.isAbsolute(autonomousPath)) throw new Error('coding/autonomous policy paths must be absolute');
+  if(processPath&&!path.isAbsolute(processPath)) throw new Error('process policy path must be absolute');
+  const codingPolicy=await readJson(codingPath); const autonomousPolicy=await readJson(autonomousPath); const hostPolicy=hostPath?await readJson(hostPath):null; const processPolicy=processPath?await readJson(processPath):null;
+  const legacyCore=typeof config.CoreRoot==='string'&&config.CoreRoot?path.resolve(config.CoreRoot):ctx.core_root;
+  const workspaceRoot=typeof config.WorkspaceRoot==='string'&&config.WorkspaceRoot?path.resolve(config.WorkspaceRoot):path.join(legacyCore,'workspaces');
+  return {ctx,configPath,config,codingPolicy,autonomousPolicy,hostPolicy,processPolicy,workspaceRoot};
+}
+export function assertDevelopmentRootSafe(developmentRoot,stateRoot){
+  const dev=path.resolve(developmentRoot),state=path.resolve(stateRoot);
+  const forbidden=[path.join(state,'releases'),path.join(state,'generations'),path.join(state,'runtime')].map(item=>path.resolve(item).toLowerCase());
+  const lower=dev.toLowerCase();
+  if(forbidden.some(prefix=>lower===prefix||lower.startsWith(`${prefix}${path.sep}`))) throw new Error('development root cannot live inside immutable/runtime state stores');
+  return dev;
+}
+async function workspacePlan(currentWorkspace,stateRoot){
+  const source=path.resolve(currentWorkspace),target=path.join(path.resolve(stateRoot),'workspaces');
+  if(source.toLowerCase()===path.resolve(target).toLowerCase()) return {source,target,mode:'existing',moved:false};
+  const sourceExists=existsSync(source),targetExists=existsSync(target);
+  if(targetExists){
+    const info=await lstat(target); if(!info.isDirectory()||info.isSymbolicLink()) throw new Error('stable workspace root must be a real directory');
+    if(sourceExists) throw new Error(`workspace migration conflict: both source and stable target exist (${source}, ${target})`);
+    return {source,target,mode:'target-existing',moved:false};
+  }
+  if(!sourceExists) return {source,target,mode:'create',moved:false};
+  const info=await lstat(source); if(!info.isDirectory()||info.isSymbolicLink()) throw new Error('legacy workspace root must be a real directory');
+  if(path.parse(source).root.toLowerCase()!==path.parse(target).root.toLowerCase()) throw new Error('workspace migration requires same-volume rename');
+  return {source,target,mode:'rename',moved:false};
+}
+async function applyWorkspacePlan(plan){
+  if(plan.mode==='existing'||plan.mode==='target-existing') return plan;
+  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; }
+  return false;
+}
+async function launcherPlan(stateRoot){
+  const bin=path.join(path.resolve(stateRoot),'bin');
+  const ps1=path.join(bin,'DEADBYTE-MCP.ps1'),cmd=path.join(bin,'DEADBYTE-MCP.cmd'),top=TOP_LAUNCHER;
+  const ps1Bytes=Buffer.from(renderStableLauncherPs1(),'utf8'),cmdBytes=Buffer.from(renderStableLauncherCmd(),'utf8');
+  return {ps1,cmd,top,ps1Bytes,cmdBytes,launcher_sha256:sha256Bytes(ps1Bytes),
+    snapshots:{ps1:await snapshotFile(ps1),cmd:await snapshotFile(cmd),top:await snapshotFile(top)},installed:false};
+}
+async function installLaunchers(plan){
+  await atomicBytes(plan.ps1,plan.ps1Bytes); await atomicBytes(plan.cmd,plan.cmdBytes); await atomicBytes(plan.top,plan.cmdBytes);
+  plan.installed=true;
+  if(await sha256File(plan.ps1)!==plan.launcher_sha256) throw new Error('stable launcher post-install hash mismatch');
+  return plan;
+}
+async function rollbackLaunchers(plan){
+  if(!plan?.installed) 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;
+}
+async function revokeAuthority(ctx,prior){
+  let revoked=false;
+  if(prior.autonomous_armed){ controllerCaptured(ctx,'disarmautonomous',15000); revoked=true; }
+  if(prior.coding_armed){ controllerCaptured(ctx,'disarmcoding',15000); revoked=true; }
+  const status=parseControllerStatus(controllerCaptured(ctx,'status',15000));
+  if(status.coding_armed||status.autonomous_armed) throw new Error('standing authority revoke gate failed');
+  if(status.host_armed) throw new Error('host plane became armed during revoke');
+  return {revoked,status};
+}
+async function restoreStandingAuthority(ctx,prior,enabled){
+  if(!enabled){
+    const status=parseControllerStatus(controllerCaptured(ctx,'status',15000));
+    if(status.coding_armed||status.autonomous_armed) throw new Error('standing authority unexpectedly survived slot switch');
+    if(status.host_armed) throw new Error('host plane became armed during slot switch');
+    return status;
+  }
+  if(prior.autonomous_armed&&!prior.coding_armed) throw new Error('invalid prior authority: autonomous armed without coding');
+  if(prior.coding_armed) controllerCaptured(ctx,'armcoding',15000);
+  if(prior.autonomous_armed) controllerCaptured(ctx,'armautonomous',15000);
+  const status=parseControllerStatus(controllerCaptured(ctx,'status',15000));
+  if(status.coding_armed!==prior.coding_armed) throw new Error('coding standing-grant restore gate failed');
+  if(status.autonomous_armed!==prior.autonomous_armed) throw new Error('autonomous standing-grant restore gate failed');
+  if(status.host_armed) throw new Error('host plane became armed during slot switch');
+  return status;
+}
+async function stopAndVerify(ctx,runtime){
+  const output=controllerCaptured(ctx,'stop',30000);
+  if(!(await waitCoreGone(runtime,10000))) throw new Error(`old downstream core ${runtime.core.pid} survived verified stop`);
+  const status=parseControllerStatus(controllerCaptured(ctx,'status',15000));
+  if(!status.offline) throw new Error(`controller stop did not reach OFFLINE: ${output}`);
+  return {output:output.trim(),status};
+}
+async function loadUpdateKey(stateRoot){
+  const trust=path.join(path.resolve(stateRoot),'trust');
+  const privateKey=createPrivateKey(await readFile(path.join(trust,'ed25519-private.pem')));
+  const publicKey=createPublicKey(await readFile(path.join(trust,'ed25519-public.pem'))); const derived=createPublicKey(privateKey);
+  if(privateKey.asymmetricKeyType!=='ed25519'||publicKey.asymmetricKeyType!=='ed25519') throw new Error('slot-update trust key must be Ed25519');
+  const der=key=>Buffer.from(key.export({type:'spki',format:'der'})); const keyId=sha256Bytes(der(publicKey));
+  if(sha256Bytes(der(derived))!==keyId) throw new Error('slot-update private/public key mismatch');
+  return {privateKey,publicKey,keyId};
+}
+function signEnvelope(body,key){
+  const bodyBytes=Buffer.from(canonicalJson(body),'utf8'); const signature=cryptoSign(null,Buffer.concat([RECEIPT_DOMAIN,bodyBytes]),key.privateKey);
+  const envelope={body,body_sha256:sha256Bytes(bodyBytes),attestation:{algorithm:'ed25519',domain:'DEADBYTE-R27-SLOT-UPDATE-V1',key_id:key.keyId,signature_base64:signature.toString('base64')}};
+  envelope.receipt_sha256=sha256Bytes(Buffer.from(canonicalJson(envelope),'utf8'));
+  if(!cryptoVerify(null,Buffer.concat([RECEIPT_DOMAIN,bodyBytes]),key.publicKey,signature)) throw new Error('slot-update signature self-check failed');
+  return envelope;
+}
+export function verifySlotUpdateEnvelope(envelope,publicKey){
+  if(!envelope?.body||!envelope?.attestation) return false; const bodyBytes=Buffer.from(canonicalJson(envelope.body),'utf8');
+  if(sha256Bytes(bodyBytes)!==envelope.body_sha256) return false; const {receipt_sha256,...unsigned}=envelope;
+  if(sha256Bytes(Buffer.from(canonicalJson(unsigned),'utf8'))!==receipt_sha256) return false;
+  if(envelope.attestation.algorithm!=='ed25519'||envelope.attestation.domain!=='DEADBYTE-R27-SLOT-UPDATE-V1') return false;
+  const keyId=sha256Bytes(Buffer.from(publicKey.export({type:'spki',format:'der'}))); if(keyId!==envelope.attestation.key_id) return false;
+  return cryptoVerify(null,Buffer.concat([RECEIPT_DOMAIN,bodyBytes]),publicKey,Buffer.from(envelope.attestation.signature_base64,'base64'));
+}
+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()});
+  await atomicBytes(file,Buffer.from(`${JSON.stringify(state,null,2)}\n`,'utf8'));
+}
+function generationTuple(runtime){
+  if(!runtime) return null;
+  return {bridge:{pid:runtime.bridge.pid,instance_nonce:runtime.bridge.instance_nonce,creation_time_utc:runtime.bridge.creation_time_utc,image_sha256:runtime.bridge.image_sha256},
+    cloud:{pid:runtime.cloud.pid,instance_nonce:runtime.cloud.instance_nonce,creation_time_utc:runtime.cloud.creation_time_utc,image_sha256:runtime.cloud.image_sha256},
+    core:{pid:runtime.core.pid,parent_pid:runtime.core.parent_pid,creation_date:runtime.core.creation_date,command_line:runtime.core.command_line}};
+}
+function publicPointer(pointer){
+  if(!pointer) return null;
+  return {schema:pointer.schema,release_id:pointer.release_id,version:pointer.version,manifest_sha256:pointer.manifest_sha256,
+    release_root:pointer.release_root,generation_root:pointer.generation_root,generation_manifest_sha256:pointer.generation_manifest_sha256,
+    launcher_sha256:pointer.launcher_sha256,config_path:pointer.config_path};
+}
+export async function performSlotUpdate({stage,developmentRoot,expectedVersion,expectedManifest,sourceRoot=null,stateRoot=DEFAULT_STATE_ROOT,restoreStandingGrants=false,recoverOfflinePredecessor=false,cloudTransport=null,bridgeBootstrap=null,processPolicyBootstrap=null,enableMachineFs=false,enableObservation=false,hostCommandPins=[]}){
+  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');
+  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 stableMcpUrl=null,mcpUrlSnapshot=null;
+  let revoked=false,stopped=false,pointerCommitted=false,newStarted=false;
+  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 processBootstrap=await prepareProcessPolicyBootstrap(processPolicyBootstrap);
+    if(processBootstrap){
+      control.processPolicy=processBootstrap.policy;
+      control.config.ProcessRuntimeEnabled=true;
+    }
+    if(enableMachineFs){
+      if(control.config.CodingRuntimeEnabled!==true) throw new Error('MachineFsRuntimeEnabled requires CodingRuntimeEnabled');
+      control.config.MachineFsRuntimeEnabled=true;
+    }
+    if(enableObservation){
+      if(control.config.MachineRuntimeEnabled===false) throw new Error('ObservationRuntimeEnabled requires MachineRuntimeEnabled');
+      if(control.config.CodingRuntimeEnabled!==true) throw new Error('ObservationRuntimeEnabled requires CodingRuntimeEnabled');
+      control.config.ObservationRuntimeEnabled=true;
+    }
+    control.config=await prepareBridgeSpec(control.config,bridgeBootstrap);
+    control.config=await prepareNamedTunnelCloudSpec(control.config,{releaseRoot:slot.release_root,bootstrap:cloudTransport});
+    authorityPreparation=await prepareAuthorityPolicies({hostPolicy:control.hostPolicy,codingPolicy:control.codingPolicy},{commandPins:hostCommandPins});
+    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);
+      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');
+      }
+      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;
+    }
+    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});
+    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},
+      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;
+    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,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:{coding_armed:finalAuthority.coding_armed,
+      autonomous_armed:finalAuthority.autonomous_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:{coding_armed:priorStatus.coding_armed,
+      autonomous_armed:priorStatus.autonomous_armed,host_armed:priorStatus.host_armed},revoked_before_switch:revoked,restore_requested:restoreStandingGrants,
+      final:{coding_armed:finalAuthority.coding_armed,autonomous_armed:finalAuthority.autonomous_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){
+    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)},
+      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(()=>{});
+    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;
+  }
+}
+
+export async function performSlotRollback({activationReceipt,stateRoot=DEFAULT_STATE_ROOT}){
+  if(process.platform!=='win32') throw new Error('R31 slot rollback is Windows-only');
+  const state=path.resolve(stateRoot),receiptFile=path.resolve(activationReceipt);
+  const key=await loadUpdateKey(state);
+  const activationEnvelope=await readJson(receiptFile);
+  if(!verifySlotUpdateEnvelope(activationEnvelope,key.publicKey)) throw new Error('activation receipt signature invalid');
+  if(activationEnvelope.body?.schema!==UPDATE_SCHEMA||activationEnvelope.body?.rollback_performed!==false) throw new Error('activation receipt is not one successful slot activation');
+  const priorPointer=parseActivePointer(JSON.stringify(activationEnvelope.body.prior_pointer));
+  const activePointer=parseActivePointer(JSON.stringify(activationEnvelope.body.active_pointer));
+  const pointerInfo=await loadPointerIfPresent(state);
+  if(!pointerInfo.pointer||canonicalJson(publicPointer(pointerInfo.pointer))!==canonicalJson(publicPointer(activePointer))) throw new Error('rollback current pointer does not match signed activation pointer');
+  await verifyActiveInstallation(state,priorPointer);
+  const currentCtx=slotContext(state,pointerInfo.pointer),currentRuntime=await captureRuntime(currentCtx);
+  if(/Process plane\s*:\s*ARMED/.test(currentRuntime.status_text)) controllerCaptured(currentCtx,'disarmprocess',15000);
+  const revoked=await revokeAuthority(currentCtx,currentRuntime.status);
+  const authorityText=controllerCaptured(currentCtx,'status',15000);
+  if(/Process plane\s*:\s*ARMED/.test(authorityText)) throw new Error('process standing authority revoke gate failed');
+  const rollbackId=`r31-rollback-${activationEnvelope.receipt_sha256.slice(0,16)}-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+  const evidenceDir=path.join(state,'evidence','updates',rollbackId),statePath=path.join(evidenceDir,'state.json'),receiptPath=path.join(evidenceDir,'receipt.json');
+  await mkdir(evidenceDir,{recursive:true});
+  const journal={schema:'deadbyte.r31-slot-rollback-state.v1',rollback_id:rollbackId,activation_receipt:path.resolve(receiptFile),
+    activation_receipt_sha256:activationEnvelope.receipt_sha256,from_pointer:publicPointer(activePointer),to_pointer:publicPointer(priorPointer),created_at_utc:new Date().toISOString()};
+  await writeState(statePath,journal,'verified');
+  let stopped=false,pointerCommitted=false,priorCtx=null,priorRuntime=null;
+  try {
+    await stopAndVerify(currentCtx,currentRuntime); stopped=true;
+    await writeState(statePath,journal,'successor_stopped');
+    await atomicWriteActivePointer(pointerInfo.file,priorPointer); pointerCommitted=true;
+    await verifyActiveInstallation(state,priorPointer);
+    await writeState(statePath,journal,'prior_pointer_restored',{active_pointer:publicPointer(priorPointer)});
+    priorCtx=slotContext(state,priorPointer);
+    priorRuntime=await startAndVerify(priorCtx,currentRuntime);
+    const stabilization=await stabilizeRuntime(priorCtx,priorRuntime);
+    const finalStatus=parseControllerStatus(controllerCaptured(priorCtx,'status',15000));
+    if(finalStatus.coding_armed||finalStatus.autonomous_armed||finalStatus.host_armed) throw new Error('rollback predecessor authority must remain disarmed');
+    const body={schema:ROLLBACK_SCHEMA,rollback_id:rollbackId,activation_receipt_sha256:activationEnvelope.receipt_sha256,
+      completed_at_utc:new Date().toISOString(),from_pointer:publicPointer(activePointer),active_pointer:publicPointer(priorPointer),
+      old_runtime:generationTuple(currentRuntime),new_runtime:generationTuple(priorRuntime),stabilization,authority_revoked:revoked.revoked,rollback_performed:true};
+    const receipt=await writeEnvelope(receiptPath,body,key);
+    await writeState(statePath,journal,'completed',{receipt_path:receiptPath,receipt_sha256:receipt.receipt_sha256});
+    return {ok:true,rollback_id:rollbackId,state_path:statePath,receipt_path:receiptPath,receipt_sha256:receipt.receipt_sha256,pointer:priorPointer,new_runtime:priorRuntime};
+  } catch(error){
+    const recovery={attempted:false,prior_runtime_stopped:false,successor_pointer_restored:false,successor_runtime_restarted:false,errors:[]};
+    if(stopped){
+      recovery.attempted=true;
+      if(pointerCommitted&&priorCtx){ try { controllerCaptured(priorCtx,'stop',30000); recovery.prior_runtime_stopped=true; } catch(recoveryError){ recovery.errors.push(`stop-prior:${recoveryError.message}`); } }
+      if(pointerCommitted){ try { await atomicWriteActivePointer(pointerInfo.file,activePointer); await verifyActiveInstallation(state,activePointer); recovery.successor_pointer_restored=true; } catch(recoveryError){ recovery.errors.push(`restore-pointer:${recoveryError.message}`); } }
+      try { await startAndVerify(currentCtx,currentRuntime); recovery.successor_runtime_restarted=true; } catch(recoveryError){ recovery.errors.push(`restart-successor:${recoveryError.message}`); }
+    }
+    await writeState(statePath,journal,'failed',{error:{name:error?.name??'Error',message:String(error?.message??error)},recovery}).catch(()=>{});
+    const wrapped=new Error(`R31 slot rollback failed: ${error?.message??error}`); wrapped.cause=error; wrapped.statePath=statePath; throw wrapped;
+  }
+}
+
+export async function runSlotUpdateCli(argv=process.argv.slice(2),{stateRoot=DEFAULT_STATE_ROOT}={}){
+  if(argv.includes('--rollback-receipt')){
+    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}`);
+    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,enableMachineFs:args.enableMachineFs,
+    enableObservation:args.enableObservation,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}`);
+  return result;
+}
+const invoked=process.argv[1]&&path.resolve(process.argv[1])===path.resolve(fileURLToPath(import.meta.url));
+if(invoked){
+  try { await runSlotUpdateCli(); }
+  catch(error){
+    console.error(`R27_SLOT_UPDATE_FAIL ${error?.message??error}`);
+    if(error?.statePath) console.error(`STATE_PATH ${error.statePath}`);
+    if(error?.failureReceiptPath) console.error(`FAILURE_RECEIPT_PATH ${error.failureReceiptPath}`);
+    process.exitCode=1;
+  }
+}