@mogragsigma/dsh-dual-host-plugin 0.0.0-stage → 0.33.2

package/bundle/onboarding-runtime-reclaim-client.js

@@ -0,0 +1,94 @@
+// Operator-only persistent reclamation requests; never retry an uncertain send.
+import {createHash,randomUUID} from 'node:crypto';
+import {credentialKey} from '@deepseek-ai/dsh-credentials';
+import {runtimeProgram,runtimeCommand} from './onboarding-runtime-program.js';
+const hash=x=>createHash('sha256').update(JSON.stringify(x)).digest('hex');
+const fail=c=>{throw Error('ONBOARDING_CLOUD_RECLAIM_'+c);};
+const exact=(v,k)=>v&&typeof v==='object'&&!Array.isArray(v)&&Object.keys(v).sort().join()===k.slice().sort().join();
+const uuid=x=>typeof x==='string'&&/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(x);
+const hex=x=>typeof x==='string'&&/^[a-f0-9]{64}$/.test(x),integer=x=>Number.isSafeInteger(x)&&x>=0;
+const scope='stopped_owned_runtime_keep_user_data';
+export const reclaimRecordKey=id=>credentialKey('dsh-task-gateway','onboarding-runtime-reclaim-v1-'+id);
+const active=d=>d?.requests?.filter(r=>r.receipt?.state!=='refused')??[];
+export const reclaimBlocked=d=>active(d).length>0;
+export const reclaimPending=d=>active(d).some(r=>r.state!=='observed'||r.receipt?.state!=='committed');
+const common=(operationId,runtimeId)=>({contract:1,operationId,runtimeId,scope,hostStarted:false,initialization:false,automaticRetry:false,userDataPreserved:true,backupsRetained:true,userDataDeleted:false,irreversible:true});
+const fields=['contract','operationId','runtimeId','scope','hostStarted','initialization','automaticRetry','userDataPreserved','backupsRetained','userDataDeleted','irreversible','id','state','completed','total','recoveryRequired','managedRestartBlocked','runtimeFilesRemoved'];
+const receiptFields=v=>[...fields,...(Object.hasOwn(v??{},'backgroundSupported')?['backgroundSupported','workerActive','executionState']:[])];
+function check(v,d,id,{absent=false,allowRefused=false}={}){
+ if(!v||Object.entries(common(d.operationId,d.runtimeId)).some(([k,x])=>v[k]!==x))fail('RESPONSE_REVIEW');
+ const background=Object.hasOwn(v,'backgroundSupported');
+ if(background&&(v.backgroundSupported!==true||typeof v.workerActive!=='boolean'||v.executionState!==(v.state==='not_requested'?'not_requested':v.state==='committed'?'completed':v.state==='deleting'?(v.workerActive?'running':'interrupted'):null)||v.state==='not_requested'&&v.workerActive))fail('RESPONSE_REVIEW');
+ if(allowRefused&&v.state==='refused'){if(v.id!==id||v.completed!==0||v.total!==0||v.recoveryRequired!==false||v.managedRestartBlocked!==false||v.runtimeFilesRemoved!==false)fail('RESPONSE_REVIEW');return;}
+ if(absent&&v.state==='not_requested'){
+  if(v.id!==null||v.completed!==0||v.total!==0||v.recoveryRequired!==false||v.managedRestartBlocked!==false||v.runtimeFilesRemoved!==false)fail('RESPONSE_REVIEW');return;
+ }
+ if(v.id!==id||!['deleting','committed'].includes(v.state)||!integer(v.completed)||!integer(v.total)||v.total<1||v.total>150000||v.completed>v.total||v.state==='committed'&&v.completed!==v.total||v.recoveryRequired!==(v.state==='deleting'&&!(background&&v.workerActive))||v.managedRestartBlocked!==true||v.runtimeFilesRemoved!==(v.state==='committed'))fail('RESPONSE_REVIEW');
+}
+export function parseReclaimRequest(record,operationId){
+ if(!record)return null;const d=record.payload;
+ if(record.kind!=='grant'||!exact(d,['schema','operationId','runtimeId','binding','revision','plans','requests'])||d.schema!==1||d.operationId!==operationId||!uuid(d.runtimeId)||!hex(d.binding)||!integer(d.revision)||d.revision<1||!Array.isArray(d.plans)||d.plans.length>128||!Array.isArray(d.requests)||d.requests.length>128||Buffer.byteLength(JSON.stringify(d))>262144)fail('LOCAL_LEDGER_REVIEW');
+ const ids=new Set();for(const p of d.plans){if(!exact(p,['id','kind','targetId','fingerprint','expiresAt'])||!uuid(p.id)||ids.has(p.id)||!['apply','recover'].includes(p.kind)||!uuid(p.targetId)||!hex(p.fingerprint)||!integer(p.expiresAt))fail('LOCAL_LEDGER_REVIEW');ids.add(p.id);}
+ for(const p of d.plans)if(p.kind==='apply'?p.id!==p.targetId:!d.plans.some(x=>x.kind==='apply'&&x.id===p.targetId))fail('LOCAL_LEDGER_REVIEW');
+ const keys=new Set();for(const r of d.requests){const p=d.plans.find(x=>x.id===r?.planId&&x.kind===r?.action);
+  if(!exact(r,['key','action','planId','targetId','fingerprint','state','receipt','observedAbsent'])||!p||r.key!==r.action+':'+r.planId||keys.has(r.key)||r.targetId!==p.targetId||r.fingerprint!==p.fingerprint||!['requested','observed'].includes(r.state)||typeof r.observedAbsent!=='boolean'||r.state==='requested'&&r.receipt!==null||r.state==='observed'&&r.observedAbsent)fail('LOCAL_LEDGER_REVIEW');keys.add(r.key);
+  if(r.state==='observed'){if(!exact(r.receipt,receiptFields(r.receipt)))fail('LOCAL_LEDGER_REVIEW');try{check(r.receipt,d,r.targetId,{allowRefused:true});}catch{fail('LOCAL_LEDGER_REVIEW');}}
+ }if(new Set(active(d).map(r=>r.targetId)).size>1)fail('LOCAL_LEDGER_REVIEW');return d;
+}
+export async function runtimeReclaimClient({args,p,a,b,runtimeId,credentials,ssh,now=Date.now}){
+ const actions={reclaim_record:[],reclaim_preview:[],reclaim_apply:['id','fingerprint','confirm'],reclaim_status:['id'],reclaim_recover_preview:['id'],reclaim_recover:['id','fingerprint','confirm']},action=args?.action,kind=action?.slice(8),mutation=['reclaim_apply','reclaim_recover'].includes(action);
+ if(!Object.hasOwn(actions,action)||!exact(args,['action','operationId',...actions[action]])||args.operationId!==p.id||Object.hasOwn(args,'id')&&!uuid(args.id)||mutation&&(args.confirm!==true||!hex(args.fingerprint)))fail('CONFIRMATION_REQUIRED');
+ const c=credentials(),key=reclaimRecordKey(p.id),binding=hash({operationId:p.id,archiveHash:p.archiveHash,bindingFingerprint:p.bindingFingerprint});let ledger=parseReclaimRequest(await c.readRecord(key),p.id);
+ if(ledger&&(ledger.binding!==binding||runtimeId&&ledger.runtimeId!==runtimeId))fail('BINDING_CHANGED');
+ const decode=n=>{const f=a.files.find(x=>x.path==='plugin/'+n);if(!f)fail('ARCHIVE_REVIEW');return Buffer.from(f.data,'base64').toString();},compat=JSON.parse(decode('compatibility.json'));
+ const workerSupported=compat.onboardingRuntimeReclamationWorker===1;
+ const supported=['onboardingPluginVersion','onboardingPluginVersionLifecycle','onboardingPluginVersionArtifacts','onboardingPluginUninstall','onboardingRuntimeReclamation','onboardingRuntimeReclamationRequests'].every(k=>compat[k]===1);
+ if(action==='reclaim_record')return {operationId:p.id,runtimeId:ledger?.runtimeId??runtimeId??null,supported,workerSupported,pending:reclaimPending(ledger),blocked:reclaimBlocked(ledger),plans:ledger?.plans??[],requests:ledger?.requests??[],cached:true,historical:true,hostStarted:false,initialization:false};
+ if(!supported)fail('UNSUPPORTED');if(!uuid(runtimeId))fail('RUNTIME_RECORD_REQUIRED');
+ const empty={schema:1,operationId:p.id,runtimeId,binding,revision:0,plans:[],requests:[]},current=()=>ledger??empty;
+ async function save(next){const old=ledger,value={...next,revision:(ledger?.revision??0)+1};parseReclaimRequest({kind:'grant',payload:value},p.id);await c.modifyRecord(key,r=>{if(JSON.stringify(parseReclaimRequest(r,p.id))!==JSON.stringify(old))fail('LOCAL_CONFLICT');return {kind:'grant',payload:value};});ledger=value;}
+ const prior=mutation?current().requests.find(r=>r.key===kind+':'+args.id):null;
+ if(prior){if(prior.fingerprint!==args.fingerprint)fail('PLAN_DRIFT');return {...prior.receipt??common(p.id,runtimeId),id:prior.targetId,state:prior.receipt?.state??'reclamation_outcome_unknown',cached:true,historical:true,notResent:true,requestState:prior.state};}
+ if(['reclaim_preview','reclaim_apply'].includes(action)&&reclaimBlocked(ledger))fail('RECOVERY_REQUIRED');
+ let plan,target=args.id,remoteArgs={};
+ if(mutation){plan=current().plans.find(x=>x.id===args.id&&x.kind===kind);if(!plan||plan.fingerprint!==args.fingerprint||plan.expiresAt<=now())fail('PLAN_EXPIRED');target=plan.targetId;remoteArgs={id:target,fingerprint:plan.fingerprint,confirm:true};}
+ else if(action!=='reclaim_preview'&&!current().plans.some(x=>x.kind==='apply'&&x.id===args.id))fail('TRANSACTION_UNKNOWN');
+ const last=id=>current().requests.filter(r=>r.targetId===id).at(-1);
+ if(kind==='recover'||kind==='recover_preview'){
+  const r=last(target);if(!r||r.state==='requested'&&!r.observedAbsent||r.receipt?.state==='committed'||r.receipt?.workerActive===true)fail('OUTCOME_UNKNOWN');
+ }
+ const input=JSON.stringify({action:'runtime_version',root:p.root,operationId:p.id,installationId:p.installationId,proof:p.proof,planHash:p.planHash,versionAction:action==='reclaim_recover_preview'?'reclaim_recoveryPreview':action,args:remoteArgs});
+ const command=runtimeCommand(a.baseline.node.path,runtimeProgram(decode('onboarding-remote-control.js'),decode('onboarding-runtime-extension.js')),'runtimeVersionCLI');
+ if(mutation){if(current().requests.length>=128)fail('HISTORY_FULL');await save({...current(),requests:[...current().requests,{key:kind+':'+args.id,action:kind,planId:args.id,targetId:target,fingerprint:plan.fingerprint,state:'requested',receipt:null,observedAbsent:false}]});}
+ let result;try{result=JSON.parse(await ssh.execute(b,command,input,{timeoutMs:120000}));}catch{fail('OUTCOME_UNKNOWN');}
+ if(result?.ok!==true){
+  // This exact target error is emitted only before creating any deletion intent.
+  // Other errors can happen after partial deletion and must remain unknown.
+  if(action==='reclaim_apply'&&result?.error==='ONBOARDING_CLOUD_RUNTIME_RECLAIM_PLAN_EXPIRED'){
+   const receipt={...common(p.id,runtimeId),id:target,state:'refused',completed:0,total:0,recoveryRequired:false,managedRestartBlocked:false,runtimeFilesRemoved:false};
+   await save({...current(),requests:current().requests.map(r=>r.key===kind+':'+args.id?{...r,state:'observed',receipt,observedAbsent:false}:r)});
+  }
+  throw Error(typeof result?.error==='string'&&/^ONBOARDING_CLOUD_[A-Z_]{1,120}$/.test(result.error)?result.error:'ONBOARDING_CLOUD_RECLAIM_RESPONSE_REVIEW');
+ }
+ const v=result.value,base=common(p.id,runtimeId);if(!v||Object.entries(base).some(([k,x])=>v[k]!==x))fail('RESPONSE_REVIEW');
+ if(['reclaim_preview','reclaim_recover_preview'].includes(action)){
+  const recovery=kind==='recover_preview';if(!uuid(v.id)||!hex(v.fingerprint)||!recovery&&(!integer(v.expiresAt)||v.expiresAt<=now()||v.expiresAt>now()+301000||v.canApply!==true||!integer(v.entries)||v.entries<1||v.entries>150000||!integer(v.files)||v.files>v.entries||!integer(v.bytes)||!Array.isArray(v.removeRoots)||v.removeRoots.length>256||!Array.isArray(v.retainedPaths)||v.retainedPaths.length>16)||v.requiresExplicitConfirmation!==true)fail('RESPONSE_REVIEW');
+  if(recovery){
+   if(v.id!==target||!['continue_original_manifest_only','start_original_manifest_if_still_unobserved'].includes(v.action)||v.recoveryRequired!==true)fail('RESPONSE_REVIEW');
+   if(v.action==='continue_original_manifest_only')check(v,current(),target);
+   else if(v.state!=='unobserved'||v.completed!==0||!integer(v.total)||v.total<1||v.total>150000||v.managedRestartBlocked!==true||v.runtimeFilesRemoved!==false)fail('RESPONSE_REVIEW');
+  }
+  if(!recovery&&(!v.removeRoots.length||v.removeRoots.some(x=>typeof x!=='string'||!/^runtime\/[^/]+$/.test(x)||['runtime/plugin','runtime/native-home','runtime/native-tmp','runtime/workspace','runtime/.','runtime/..'].includes(x))||hash(v.retainedPaths.slice().sort())!==hash(['runtime/native-home','runtime/native-tmp','runtime/workspace','runtime','.control','plugin'].sort())))fail('RESPONSE_REVIEW');
+  if(!recovery&&[...v.removeRoots,...v.retainedPaths].some(x=>typeof x!=='string'||x.length>300||/[\x00-\x1f\x7f]/.test(x)))fail('RESPONSE_REVIEW');
+  if(current().plans.length>=128)fail('HISTORY_FULL');const id=recovery?randomUUID():v.id;if(current().plans.some(x=>x.id===id))fail('PLAN_DRIFT');const expiresAt=recovery?now()+300000:v.expiresAt;
+  await save({...current(),plans:[...current().plans,{id,kind:recovery?'recover':'apply',targetId:v.id,fingerprint:v.fingerprint,expiresAt}]});return {...v,id,transactionId:v.id,expiresAt,cached:false};
+ }
+ if(workerSupported&&v.backgroundSupported!==true)fail('RESPONSE_REVIEW');
+ check(v,current(),target,{absent:action==='reclaim_status'});
+ if(v.state==='not_requested'){
+  if(last(target))await save({...current(),requests:current().requests.map(r=>r.targetId===target&&r.state==='requested'?{...r,observedAbsent:true}:r)});
+  return {...v,id:target,state:'reclamation_outcome_unknown',observedState:'not_requested',outcomeUnknown:true,historical:true,cached:false};
+ }
+ const receipt=Object.fromEntries(receiptFields(v).map(k=>[k,v[k]]));if(last(target))await save({...current(),requests:current().requests.map(r=>r.targetId===target?{...r,state:'observed',receipt,observedAbsent:false}:r)});
+ return {...receipt,cached:false,historical:action==='reclaim_status'};
+}

package/bundle/onboarding-runtime-reclaim-worker.js

@@ -0,0 +1,63 @@
+// Original-archive worker authority. A launch is separate from deletion success.
+// No retries: a dead/unknown worker requires a new explicit recovery approval.
+import {randomUUID} from 'node:crypto';
+import {spawn as runtimeSpawn} from 'node:child_process';
+const uuid=x=>typeof x==='string'&&/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(x);
+const hex=x=>typeof x==='string'&&/^[a-f0-9]{64}$/.test(x);
+const exact=(x,k)=>x&&typeof x==='object'&&!Array.isArray(x)&&Object.keys(x).sort().join()===k.slice().sort().join();
+const birth=x=>exact(x,['platform','pid','start','boot'])&&x.platform==='linux'&&Number.isSafeInteger(x.pid)&&x.pid>0&&/^\d+$/.test(x.start)&&typeof x.boot==='string'&&/^[a-f0-9-]{36}$/.test(x.boot);
+
+export function createReclamationWorker(api,q,j,{ledger,boundPlan,finish,bindWorker}){
+ const {path,hash,regular,verified,signed,atomicJSON,checkAncestors,runtimeAlive}=api;
+ const file=path.join(q.root,'.control/runtime/reclaim-worker.json'),binding=hash({operationId:q.operationId,runtimeId:j.id,inventoryHash:j.inventoryHash,workerHash:j.workerHash});
+ const fail=c=>api.fail('RUNTIME_RECLAIM_WORKER_'+c);
+ async function read(d){
+  await checkAncestors(path.dirname(file));const f=await regular(file,262144);if(!f){if(d?.workerBound)fail('REVIEW');return null;}
+  if(f.identity.uid!==process.getuid()||f.identity.mode!==0o600)fail('REVIEW');let x;try{x=verified(JSON.parse(f.data),q.proof);}catch{fail('REVIEW');}
+  if(!exact(x,['schema','binding','revision','launches'])||x.schema!==1||x.binding!==binding||!Number.isSafeInteger(x.revision)||x.revision<1||!Array.isArray(x.launches)||!x.launches.length||x.launches.length>128)fail('REVIEW');
+  const ids=new Set();for(const r of x.launches){
+   if(!exact(r,['id','reclaimId','planHash','identity','state','error'])||!uuid(r.id)||ids.has(r.id)||r.reclaimId!==d?.id||r.planHash!==d.planHash||!hex(r.planHash)||!['prepared','running','finished','failed'].includes(r.state)||r.identity!==null&&!birth(r.identity)||r.state!=='prepared'&&r.identity===null||r.error!==null&&(!/^ONBOARDING_CLOUD_[A-Z_]{1,160}$/.test(r.error)||r.state!=='failed'))fail('REVIEW');ids.add(r.id);
+  }return x;
+ }
+ async function save(x){x.revision++;if(Buffer.byteLength(JSON.stringify(x))>250000)fail('LIMIT');await atomicJSON(file,signed(x,q.proof));}
+ async function observe(d){
+  const x=await read(d),r=x?.launches.at(-1),active=r?.identity?await runtimeAlive(r.identity):false;
+  return {backgroundSupported:true,workerActive:active,executionState:!d?'not_requested':d.state==='committed'?'completed':active?'running':'interrupted',recoveryRequired:d?.state==='deleting'&&!active};
+ }
+ async function inactive(d){if((await observe(d)).workerActive)fail('ACTIVE');}
+ async function begin(d){
+  await inactive(d);const x=await read(d)??{schema:1,binding,revision:0,launches:[]};if(x.launches.length>=128)fail('LIMIT');
+  if(typeof api.runtimeReclaimLaunch!=='function'&&typeof api.reclaimWorkerSource!=='string'||typeof api.deferReclaimStart!=='function')fail('UNAVAILABLE');
+  const r={id:randomUUID(),reclaimId:d.id,planHash:d.planHash,identity:null,state:'prepared',error:null};x.launches.push(r);await save(x);if(!d.workerBound)await bindWorker(d);
+  const launch=api.runtimeReclaimLaunch??((...args)=>launchReclamationWorker({...api,processInfo:api.runtimeProcessInfo,source:api.reclaimWorkerSource},...args));
+  const handle=await launch(q,j,{id:r.id,planHash:d.planHash},async identity=>{
+   if(!birth(identity))fail('IDENTITY');r.identity=identity;r.state='running';await save(x);
+  });
+  // The dispatcher releases the original owner lock before delivering stdin.
+  // Parent loss before that point closes stdin: no unrecorded launch may execute.
+  api.deferReclaimStart(handle);return observe(d);
+ }
+ async function execute(a){
+  if(!exact(a,['id','planHash'])||!uuid(a.id)||!hex(a.planHash))fail('ARGUMENTS');
+  const d=await ledger(),x=await read(d),r=x?.launches.at(-1),self=await api.runtimeProcessInfo();
+  if(!d||d.state!=='deleting'||!r||r.id!==a.id||r.planHash!==a.planHash||r.state!=='running'||!birth(self)||hash(r.identity)!==hash(self))fail('NOT_AUTHORIZED');
+  try{const result=await finish(d,await boundPlan(d));r.state='finished';await save(x);return result;}
+  catch(e){r.state='failed';r.error=/^ONBOARDING_CLOUD_[A-Z_]{1,160}$/.test(e.message)?e.message:'ONBOARDING_CLOUD_RUNTIME_RECLAIM_WORKER_FAILED';await save(x);throw e;}
+ }
+ return {observe,inactive,begin,execute,fingerprint:async d=>hash({journal:d,worker:await read(d)})};
+}
+
+export async function launchReclamationWorker(api,q,j,args,persistIdentity){
+ const {fs,path,hash,regular,fail,runtimeDir,runtimeEnv,processInfo,source:originalProgram}=api;
+ const worker=path.join(runtimeDir(q),'worker.mjs'),source=await regular(worker,200000);
+ if(!source||source.identity.uid!==process.getuid()||source.identity.mode!==0o600||source.sha256!==j.workerHash||source.sha256!==hash(originalProgram))fail('RUNTIME_RECLAIM_WORKER_SOURCE_REVIEW');
+ const log=await fs.open(path.join(runtimeDir(q),'reclaim-'+args.id+'.log'),'wx',0o600);let child;
+ try{
+  child=runtimeSpawn(process.execPath,[worker],{cwd:q.root,detached:true,env:runtimeEnv(q),stdio:['pipe',log.fd,log.fd]});
+  child.stdin.on('error',()=>{});
+  await new Promise((resolve,reject)=>{child.once('spawn',resolve);child.once('error',reject);});
+  await persistIdentity(await processInfo(child.pid));child.unref();let sent=false;
+  const input=JSON.stringify({action:'runtime_version',root:q.root,operationId:q.operationId,installationId:q.installationId,proof:q.proof,planHash:q.planHash,versionAction:'reclaim_worker',args});
+  return {start:()=>{if(!sent){sent=true;child.stdin.end(input);}},cancel:()=>{if(!sent){sent=true;child.stdin.end();}}};
+ }catch(e){child?.stdin.end();child?.unref();throw e;}finally{await log.close();}
+}

package/bundle/onboarding-runtime-reclaim.js

@@ -0,0 +1,132 @@
+// Original-archive, offline runtime reclamation. Never adopts current user data.
+// Requires completed three-artifact removal. Retains home/workspace/temp, source,
+// every control receipt and backup. Deletion is irreversible and separately approved.
+import {randomUUID} from 'node:crypto';
+
+const retained=['runtime/native-home','runtime/native-tmp','runtime/workspace'];
+const within=(p,root)=>p===root||p.startsWith(root+'/');
+const keep=p=>p==='runtime'||retained.some(root=>within(p,root));
+const uuid=x=>typeof x==='string'&&/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(x);
+const hex=x=>typeof x==='string'&&/^[a-f0-9]{64}$/.test(x);
+const exact=(x,keys)=>x&&typeof x==='object'&&!Array.isArray(x)&&Object.keys(x).sort().join()===keys.slice().sort().join();
+const identity=s=>({dev:s.dev,ino:s.ino,uid:s.uid,mode:s.mode&0o777});
+const rowKeys=x=>['path','dev','ino','uid','mode','kind',...(x.kind==='file'?['bytes','sha256']:x.kind==='link'?['target']:[])];
+
+export function createRuntimeReclamation(api,q,j,{prerequisite,background=false}){
+ const {fs,path,hash,fail,regular,signed,verified,atomicJSON,checkAncestors,runtimeSource,runtimeRecord,runtimeAlive,runtimeStopLedger,runtimeBaseInventory,runtimeInventory}=api;
+ const now=api.reclaimNow??Date.now,hook=api.reclaimHook??(async()=>{});
+ let workerPromise;const worker=()=>workerPromise??=import('./onboarding-runtime-reclaim-worker.js').then(m=>m.createReclamationWorker(api,q,j,{ledger,boundPlan,finish,bindWorker:d=>persist(d,{workerBound:true})}));
+ const result=async d=>({...view(d),...(background?await(await worker()).observe(d):{})});
+ const run=async(d,p)=>background?{...view(d),...await(await worker()).begin(d)}:finish(d,p);
+ const recoveryHash=async d=>background?(await worker()).fingerprint(d):hash(d);
+ const dir=path.join(q.root,'.control/runtime'),planFile=path.join(dir,'runtime-reclaim-plan.json'),journalFile=path.join(dir,'runtime-reclaim.json');
+ const binding=hash({root:q.root,operationId:q.operationId,runtimeId:j?.id,inventoryHash:j?.inventoryHash});
+ const bad=c=>fail('RUNTIME_RECLAIM_'+c);
+ async function stat(p){await checkAncestors(path.dirname(p));try{return await fs.lstat(p);}catch(e){if(e.code==='ENOENT')return null;throw e;}}
+ async function read(p,limit=67108864){await checkAncestors(path.dirname(p));const f=await regular(p,limit);if(!f)return null;if(f.identity.uid!==process.getuid()||f.identity.mode!==0o600)bad('LEDGER_REVIEW');try{return verified(JSON.parse(f.data),q.proof);}catch{bad('LEDGER_REVIEW');}}
+ async function save(p,v){if(Buffer.byteLength(JSON.stringify(v))>66000000)bad('LIMIT');await atomicJSON(p,signed(v,q.proof));}
+ async function guard(){
+  await runtimeSource(q);const current=await runtimeRecord(q);
+  if(!j?.inventoryHash||!j.nativeReceipt?.ok||!current||hash(current)!==hash(j)||!['host_ready','failed','stopped'].includes(j.state))bad('RUNTIME_CHANGED');
+  for(const member of [j.host,j.worker,j.child,j.restart?.launcher])if(await runtimeAlive(member))bad('PROCESS_ACTIVE');
+  await runtimeStopLedger(q,j,true);
+ }
+ function entries(rows){
+  if(!Array.isArray(rows)||rows.length>150000)bad('PLAN_REVIEW');const names=new Set();
+  for(const x of rows){
+   if(!x||!['file','directory','link'].includes(x.kind)||!exact(x,rowKeys(x))||typeof x.path!=='string'||!x.path.startsWith('runtime/')||keep(x.path)||within(x.path,'runtime/plugin')||x.path.split('/').some(s=>!s||s==='.'||s==='..'||/[\x00-\x1f\x7f\\]/.test(s))||names.has(x.path)||x.uid!==process.getuid()||![x.dev,x.ino,x.uid,x.mode].every(Number.isSafeInteger)||x.mode<0||x.mode>0o777)bad('PLAN_REVIEW');
+   if(x.kind==='file'&&(!Number.isSafeInteger(x.bytes)||x.bytes<0||x.bytes>268435456||!hex(x.sha256)))bad('PLAN_REVIEW');
+   if(x.kind==='link'&&(typeof x.target!=='string'||path.isAbsolute(x.target)||!within(path.posix.normalize(path.posix.join(path.posix.dirname(x.path),x.target)),'runtime')))bad('PLAN_REVIEW');
+   names.add(x.path);
+  }
+  // Every directory follows its children in deletion order.
+  const positions=new Map(rows.map((x,i)=>[x.path,i]));
+  for(const [i,x] of rows.entries()){const parent=path.posix.dirname(x.path);if(parent!=='runtime'&&(!positions.has(parent)||positions.get(parent)<=i||rows[positions.get(parent)].kind!=='directory'))bad('PLAN_REVIEW');}
+  return rows;
+ }
+ function planShape(p){
+  if(!p||!exact(p,['schema','binding','id','createdAt','expiresAt','journalHash','uninstallId','uninstallHash','rows','roots','fingerprint'])||p.schema!==1||p.binding!==binding||!uuid(p.id)||!uuid(p.uninstallId)||![p.journalHash,p.uninstallHash,p.fingerprint].every(hex)||!Number.isSafeInteger(p.createdAt)||p.expiresAt!==p.createdAt+300000||!Array.isArray(p.roots)||!p.roots.length)bad('PLAN_REVIEW');
+  const {fingerprint,...body}=p;if(hash(body)!==fingerprint||p.journalHash!==hash(j))bad('PLAN_REVIEW');entries(p.rows);
+  const names=new Set();for(const x of p.roots){if(!exact(x,['path','dev','ino','uid','mode','kind'])||!['runtime',...retained].includes(x.path)||x.kind!=='directory'||names.has(x.path)||x.uid!==process.getuid()||![x.dev,x.ino,x.uid,x.mode].every(Number.isSafeInteger)||x.mode<0||x.mode>0o777)bad('PLAN_REVIEW');names.add(x.path);}
+  if(!names.has('runtime'))bad('PLAN_REVIEW');return p;
+ }
+ async function ledger(){
+  const d=await read(journalFile,262144);if(!d)return null;
+  if(!exact(d,['schema','binding','id','fingerprint','planHash','state','revision','cursor','pendingEnd','total','updatedAt',...(background?['workerBound']:[])])||d.schema!==(background?2:1)||background&&typeof d.workerBound!=='boolean'||d.binding!==binding||!uuid(d.id)||![d.fingerprint,d.planHash].every(hex)||!['deleting','committed'].includes(d.state)||![d.revision,d.cursor,d.pendingEnd,d.total,d.updatedAt].every(Number.isSafeInteger)||d.revision<1||d.cursor<0||d.pendingEnd<d.cursor||d.pendingEnd>d.total||d.pendingEnd-d.cursor>32||d.total<1||d.total>150000||d.state==='committed'&&(d.cursor!==d.total||d.pendingEnd!==d.total))bad('LEDGER_REVIEW');
+  return d;
+ }
+ async function boundPlan(d){const p=planShape(await read(planFile));if(p.id!==d.id||p.fingerprint!==d.fingerprint||hash(p)!==d.planHash||p.rows.length!==d.total)bad('PLAN_REVIEW');return p;}
+ async function pinnedRoots(p){
+  for(const row of p.roots){const s=await stat(path.join(q.root,row.path));if(!s||!s.isDirectory()||s.isSymbolicLink()||hash(identity(s))!==hash({dev:row.dev,ino:row.ino,uid:row.uid,mode:row.mode}))bad('RETAINED_ROOT_DRIFT');}
+  // Never follow a newly substituted retained root, even though its data is kept.
+  for(const name of retained){const s=await stat(path.join(q.root,name));if(s&&(!s.isDirectory()||s.isSymbolicLink()||!p.roots.some(x=>x.path===name)))bad('RETAINED_ROOT_DRIFT');}
+ }
+ async function snapshot(){return runtimeInventory(q,new Set(retained));}
+ function compare(expected,current,cursor,end){
+  const found=new Map(current.filter(x=>!keep(x.path)).map(x=>[x.path,x]));
+  for(const [i,row] of expected.entries()){const x=found.get(row.path);found.delete(row.path);if(i<cursor?!!x:i>=end?!x||hash(x)!==hash(row):x&&hash(x)!==hash(row))bad('DRIFT');}
+  if(found.size)bad('DRIFT');
+ }
+ async function validate(d,p){await guard();if(hash(await prerequisite())!==p.uninstallHash)bad('PREREQUISITE_CHANGED');await pinnedRoots(p);compare(p.rows,await snapshot(),d.cursor,d.pendingEnd);}
+ const view=d=>({contract:1,operationId:q.operationId,runtimeId:j.id,scope:'stopped_owned_runtime_keep_user_data',id:d?.id??null,state:d?.state??'not_requested',completed:d?.cursor??0,total:d?.total??0,recoveryRequired:d?.state==='deleting',managedRestartBlocked:!!d,hostStarted:false,initialization:false,automaticRetry:false,userDataPreserved:true,backupsRetained:true,userDataDeleted:false,runtimeFilesRemoved:d?.state==='committed',irreversible:true});
+ function publicPlan(p){return {...view(null),id:p.id,fingerprint:p.fingerprint,expiresAt:p.expiresAt,canApply:true,files:p.rows.filter(x=>x.kind==='file').length,entries:p.rows.length,bytes:p.rows.reduce((n,x)=>n+(x.bytes??0),0),removeRoots:[...new Set(p.rows.map(x=>x.path.split('/').slice(0,2).join('/')))].sort(),retainedPaths:[...retained,'runtime','.control','plugin'],requiresExplicitConfirmation:true};}
+ async function preview(a={}){
+  if(!exact(a,[]))bad('ARGUMENTS');await guard();if(await ledger())bad('ALREADY_REQUESTED');
+  const u=await prerequisite();if(u?.state!=='committed'||u.pluginInstalled!==false||u.recoveryRequired||!uuid(u.id))bad('PLUGIN_UNINSTALL_REQUIRED');
+  const original=await runtimeBaseInventory(q,j),rows=entries(original.items.filter(x=>!keep(x.path)&&!within(x.path,'runtime/plugin')).reverse());
+  if(!rows.length)bad('NOTHING_OWNED');const roots=original.items.filter(x=>['runtime',...retained].includes(x.path));
+  const createdAt=now(),body={schema:1,binding,id:randomUUID(),createdAt,expiresAt:createdAt+300000,journalHash:hash(j),uninstallId:u.id,uninstallHash:hash(u),rows,roots};
+  const p=planShape({...body,fingerprint:hash(body)});await pinnedRoots(p);compare(rows,await snapshot(),0,0);
+  await save(planFile,p);return publicPlan(p);
+ }
+ async function syncParents(rows){
+  const names=new Set();for(const row of rows){let n=path.dirname(path.join(q.root,row.path));while(!await stat(n)){if(n===q.root)bad('DRIFT');n=path.dirname(n);}names.add(n);}
+  for(const n of names){const h=await fs.open(n,'r');try{await h.sync();}finally{await h.close();}}
+ }
+ async function remove(row,parents){
+  const name=path.join(q.root,row.path),s=await stat(name);if(!s)return;
+  for(let parent=path.posix.dirname(row.path);parent!=='runtime';parent=path.posix.dirname(parent)){
+   const expected=parents.get(parent),actual=await stat(path.join(q.root,parent));
+   if(!expected||!actual||!actual.isDirectory()||actual.isSymbolicLink()||hash(identity(actual))!==hash(identityRow(expected)))bad('DRIFT');
+  }
+  if(hash(identity(s))!==hash({dev:row.dev,ino:row.ino,uid:row.uid,mode:row.mode}))bad('DRIFT');
+  if(row.kind==='directory'){if(!s.isDirectory()||s.isSymbolicLink())bad('DRIFT');await fs.rmdir(name);}
+  else if(row.kind==='link'){if(!s.isSymbolicLink()||await fs.readlink(name)!==row.target)bad('DRIFT');await fs.unlink(name);}
+  else{const f=await regular(name,268435456);if(!f||f.sha256!==row.sha256||s.size!==row.bytes||hash(f.identity)!==hash(identityRow(row)))bad('DRIFT');const latest=await stat(name);if(!latest||latest.nlink!==1||hash(identity(latest))!==hash(identityRow(row)))bad('DRIFT');await fs.unlink(name);}
+ }
+ const identityRow=x=>({dev:x.dev,ino:x.ino,uid:x.uid,mode:x.mode});
+ async function persist(d,fields){Object.assign(d,fields,{revision:d.revision+1,updatedAt:now()});await save(journalFile,d);}
+ async function finish(d,p){
+  await validate(d,p);const parents=new Map(p.rows.filter(x=>x.kind==='directory').map(x=>[x.path,x]));
+  while(d.cursor<d.total){
+   await guard();await pinnedRoots(p);const start=d.cursor;await persist(d,{pendingEnd:Math.min(start+32,d.total)});await hook('batch_intent',d);
+   for(let i=start;i<d.pendingEnd;i++){await remove(p.rows[i],parents);await hook('item_removed',{index:i,path:p.rows[i].path});}
+   await syncParents(p.rows.slice(start,d.pendingEnd));await persist(d,{cursor:d.pendingEnd});await hook('batch_recorded',d);
+  }
+  await validate(d,p);await persist(d,{state:'committed'});await hook('committed',d);return view(d);
+ }
+ async function apply(a){
+  if(!exact(a,['id','fingerprint','confirm'])||!uuid(a.id)||!hex(a.fingerprint)||a.confirm!==true)bad('CONFIRMATION_REQUIRED');
+  await guard();const old=await ledger();if(old){if(old.id!==a.id||old.fingerprint!==a.fingerprint)bad('ALREADY_REQUESTED');return {...await result(old),notResent:true};}
+  const p=planShape(await read(planFile));if(p.id!==a.id||p.fingerprint!==a.fingerprint||now()>p.expiresAt||now()<p.createdAt)bad('PLAN_EXPIRED');
+  const u=await prerequisite();if(hash(u)!==p.uninstallHash)bad('PREREQUISITE_CHANGED');
+  const d={schema:background?2:1,...(background?{workerBound:false}:{}),binding,id:p.id,fingerprint:p.fingerprint,planHash:hash(p),state:'deleting',revision:1,cursor:0,pendingEnd:0,total:p.rows.length,updatedAt:now()};
+  await validate(d,p);await save(journalFile,d);await hook('intent_saved',d);return run(d,p);
+ }
+ async function status(a={}){if(!exact(a,[]))bad('ARGUMENTS');const d=await ledger();if(d)await boundPlan(d);return {...await result(d),historical:true};}
+ function intent(p){return {schema:background?2:1,...(background?{workerBound:false}:{}),binding,id:p.id,fingerprint:p.fingerprint,planHash:hash(p),state:'deleting',revision:1,cursor:0,pendingEnd:0,total:p.rows.length,updatedAt:now()};}
+ const unobserved=p=>hash({state:'intent_unobserved',planHash:hash(p)});
+ async function recoveryPreview(a={}){
+  if(!exact(a,[]))bad('ARGUMENTS');const d=await ledger();
+  if(!d){const p=planShape(await read(planFile));await validate(intent(p),p);return {...view(null),id:p.id,state:'unobserved',recoveryRequired:true,managedRestartBlocked:true,total:p.rows.length,fingerprint:unobserved(p),action:'start_original_manifest_if_still_unobserved',requiresExplicitConfirmation:true};}
+  if(d.state!=='deleting')bad('RECOVERY_REQUIRED');if(background)await(await worker()).inactive(d);const p=await boundPlan(d);await validate(d,p);
+  return {...await result(d),fingerprint:await recoveryHash(d),action:'continue_original_manifest_only',requiresExplicitConfirmation:true};
+ }
+ async function recover(a){
+  if(!exact(a,['id','fingerprint','confirm'])||a.confirm!==true||!uuid(a.id)||!hex(a.fingerprint))bad('CONFIRMATION_REQUIRED');
+  const d=await ledger();
+  if(!d){const p=planShape(await read(planFile));if(p.id!==a.id||unobserved(p)!==a.fingerprint)bad('RECOVERY_CHANGED');const next=intent(p);await validate(next,p);await save(journalFile,next);await hook('intent_saved',next);return run(next,p);}
+  if(d.state!=='deleting'||d.id!==a.id||await recoveryHash(d)!==a.fingerprint)bad('RECOVERY_CHANGED');if(background)await(await worker()).inactive(d);const p=await boundPlan(d);await validate(d,p);return run(d,p);
+ }
+ return {preview,apply,status,recoveryPreview,recover,worker:async a=>{if(!background)bad('WORKER_UNSUPPORTED');return(await worker()).execute(a);}};
+}

package/bundle/onboarding-runtime-repair-client.js

@@ -0,0 +1,50 @@
+// Local durable intent is separate from the native runtime status receipt.
+import {credentialKey} from '@deepseek-ai/dsh-credentials';
+import {runtimeProgram,runtimeCommand} from './onboarding-runtime-program.js';
+export const repairRecordKey=id=>credentialKey('dsh-task-gateway','onboarding-runtime-repair-v1-'+id);
+export const repairPending=p=>!!p&&(p.state==='requested'||p.receipt?.repair?.recoveryRequired===true);
+const uuid=x=>typeof x==='string'&&/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(x);
+const hex=x=>typeof x==='string'&&/^[a-f0-9]{64}$/.test(x);
+const exact=(x,k)=>x&&Object.keys(x).sort().join()===k.slice().sort().join();
+const fail=c=>{throw Error('ONBOARDING_CLOUD_RUNTIME_REPAIR_'+c);};
+export function parseRepairRequest(r,operationId){
+ if(!r)return null;const p=r.payload;
+ if(r.kind!=='grant'||!exact(p,['schema','operationId','id','action','fingerprint','state','receipt'])||p.schema!==1||p.operationId!==operationId||!uuid(p.id)||!['runtime_repair_apply','runtime_repair_recover'].includes(p.action)||p.fingerprint!==null&&!hex(p.fingerprint)||!['requested','observed'].includes(p.state))fail('LOCAL_LEDGER_REVIEW');if(p.state==='requested'?p.receipt!==null:(!p.receipt||typeof p.receipt.state!=='string'||p.receipt.repair?.id!==p.id||typeof p.receipt.repair?.recoveryRequired!=='boolean'))fail('LOCAL_LEDGER_REVIEW');return p;
+}
+export async function runtimeRepairClient({args,p,a,b,credentials,ssh}){
+ const action=args?.action,verifying=action==='runtime_repair_verify',mutating=['runtime_repair_apply','runtime_repair_recover'].includes(action);
+ if(!['runtime_repair_preview','runtime_repair_status','runtime_repair_apply','runtime_repair_recover','runtime_repair_verify'].includes(action)||!exact(args,['action','operationId',...(mutating?['repairId','confirm']:verifying?['repairId']:[]),...(action==='runtime_repair_apply'?['fingerprint']:[])])||args.operationId!==p.id||mutating&&(!uuid(args.repairId)||args.confirm!==true)||verifying&&!uuid(args.repairId)||action==='runtime_repair_apply'&&!hex(args.fingerprint))fail('CONFIRMATION_REQUIRED');
+ const compat=a.files.find(f=>f.path==='plugin/compatibility.json');if(!compat||JSON.parse(Buffer.from(compat.data,'base64')).onboardingPluginRepair!==1)fail('UNSUPPORTED');
+ if(verifying&&JSON.parse(Buffer.from(compat.data,'base64')).onboardingPluginRepairActivation!==1)fail('ACTIVATION_UNSUPPORTED');
+ const controller=a.files.find(f=>f.path==='plugin/onboarding-remote-control.js'),extension=a.files.find(f=>f.path==='plugin/onboarding-runtime-extension.js');if(!controller||!extension)fail('ARCHIVE_REVIEW');
+ const key=repairRecordKey(p.id),c=credentials(),old=parseRepairRequest(await c.readRecord(key),p.id);
+ if(mutating&&old?.id===args.repairId&&old.action===action&&(action==='runtime_repair_apply'||old.state==='requested')){
+  if(old.fingerprint!==(args.fingerprint??null))fail('PLAN_DRIFT');return {operationId:p.id,initialization:false,hostStarted:false,state:old.state==='requested'?'repair_outcome_unknown':old.receipt?.state??'repair_outcome_unknown',repair:old.receipt?.repair??null,notResent:true,cached:true};
+ }
+ if(repairPending(old)&&(verifying||['runtime_repair_preview','runtime_repair_apply'].includes(action)||action==='runtime_repair_recover'&&old.id!==args.repairId))fail('RECOVERY_REQUIRED');
+ const q={action,root:p.root,operationId:p.id,installationId:p.installationId,proof:p.proof,planHash:p.planHash,...(mutating||verifying?{repairId:args.repairId}:{}),...(action==='runtime_repair_apply'?{fingerprint:args.fingerprint}:{})};
+ const program=runtimeProgram(Buffer.from(controller.data,'base64').toString(),Buffer.from(extension.data,'base64').toString());
+ const command=runtimeCommand(a.baseline.node.path,program,'runtimeCLI');
+ let request=old;
+ if(mutating){
+  request={schema:1,operationId:p.id,id:args.repairId,action,fingerprint:args.fingerprint??null,state:'requested',receipt:null};
+  await c.modifyRecord(key,r=>{if(JSON.stringify(parseRepairRequest(r,p.id))!==JSON.stringify(old))fail('LOCAL_CONFLICT');return {kind:'grant',payload:request};});
+ }
+ let result;try{
+  const raw=await ssh.execute(b,command,JSON.stringify(q),{timeoutMs:120000});
+  result=JSON.parse(raw);
+ }catch{fail('OUTCOME_UNKNOWN');}
+ if(!result.ok){
+  if(mutating&&result.error==='ONBOARDING_CLOUD_RUNTIME_REPAIR_PREFLIGHT_REFUSED')await c.modifyRecord(key,r=>{const cur=parseRepairRequest(r,p.id);if(JSON.stringify(cur)!==JSON.stringify(request))fail('LOCAL_CONFLICT');return {kind:'grant',payload:{...request,state:'observed',receipt:{state:'repair_refused',repair:{id:request.id,state:'refused',recoveryRequired:false}}}};});
+  throw Error(/^ONBOARDING_CLOUD_[A-Z_]+$/.test(result.error)?result.error:'ONBOARDING_CLOUD_RUNTIME_REPAIR_RESPONSE_REVIEW');
+ }
+ const v=result.value;
+ if(!v||v.operationId!==p.id||!uuid(v.runtimeId)||v.initialization!==false||typeof v.hostStarted!=='boolean'||action==='runtime_repair_preview'&&(!uuid(v.id)||!hex(v.fingerprint)||typeof v.canApply!=='boolean')||action!=='runtime_repair_preview'&&(!v.repair||v.repair.contract!==1||typeof v.repair.recoveryRequired!=='boolean'))fail('RESPONSE_REVIEW');
+ if(verifying&&(v.repair.id!==args.repairId||v.repair.state!=='committed'||v.activation?.contract!==1||v.activation.activationVerified!==true||v.activation.cached!==false||v.activation.repairId!==args.repairId||!Number.isSafeInteger(v.activation.observedAt)))fail('RESPONSE_REVIEW');
+ if(request&&action!=='runtime_repair_preview'){
+  const matched=v.repair.id===request.id;
+  await c.modifyRecord(key,r=>{if(JSON.stringify(parseRepairRequest(r,p.id))!==JSON.stringify(request))fail('LOCAL_CONFLICT');return {kind:'grant',payload:{...request,state:matched?'observed':request.state,receipt:matched?v:request.receipt}};});
+  if(!matched&&request.state==='requested')return {...v,state:'repair_outcome_unknown',originalRepairId:request.id,notResent:true};
+ }
+ return v;
+}

package/bundle/onboarding-runtime-repair.js

@@ -0,0 +1,88 @@
+// Loaded only from the original verified archive, under the runtime owner lock.
+// Replaces only original plugin files. Never rebases a whole filesystem scan.
+import {createPluginRepair} from './onboarding-plugin-repair.js';
+import {createRuntimeActivation} from './onboarding-runtime-activation.js';
+export async function createRuntimeRepair(api,q,j){
+ const {fs,path,hash,fail,regular,verified,signed,atomicJSON,runtimeOwnedInventory,runtimeInventory,runtimeAlive,runtimeRecord,runtimeStopLedger,runtimeSource}=api;
+ if(!j)fail('RUNTIME_REPAIR_NOT_READY');const c=JSON.parse((await regular(path.join(q.root,'plugin/compatibility.json'))).data);if(c.onboardingPluginRepair!==1)fail('RUNTIME_REPAIR_UNSUPPORTED');
+ const source=await runtimeSource(q),original=await runtimeOwnedInventory(q,j),file=path.join(q.root,'.control/runtime/plugin-maintenance.json');
+ const manifest=source.owner.manifest.map(f=>({path:f.path.slice(7),sha256:f.sha256}));
+ const sources=new Map(source.owner.manifest.map(f=>['runtime/'+f.path,f]));
+ const mutable=p=>['runtime/native-home','runtime/native-tmp','runtime/workspace'].some(x=>p===x||p.startsWith(x+'/'));
+ const terminal=r=>['committed','rolled_back'].includes(r.state);
+ const scope='stopped_owned_plugin_files_only';
+ const exact=(x,ks)=>x&&Object.keys(x).sort().join()===ks.slice().sort().join();
+ const uuid=x=>typeof x==='string'&&/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(x);
+ const hex=x=>typeof x==='string'&&/^[a-f0-9]{64}$/.test(x);
+ async function ledger(){
+  let folder;try{folder=await fs.lstat(path.join(q.root,'.control/runtime/plugin-repairs'));}catch(e){if(e.code!=='ENOENT')throw e;}
+  if(folder&&(!folder.isDirectory()||folder.isSymbolicLink()||folder.uid!==process.getuid()||(folder.mode&0o777)!==0o700))fail('RUNTIME_REPAIR_LEDGER_REVIEW');
+  const names=folder?await fs.readdir(path.join(q.root,'.control/runtime/plugin-repairs')):[];
+  const f=await regular(file,16777216);if(!f&&folder)fail('RUNTIME_REPAIR_LEDGER_REVIEW');if(!f)return {schema:1,operationId:q.operationId,runtimeId:j.id,inventoryHash:j.inventoryHash,records:[]};
+  if(f.identity.uid!==process.getuid()||f.identity.mode!==0o600)fail('RUNTIME_REPAIR_LEDGER_REVIEW');
+  const d=verified(JSON.parse(f.data),q.proof);
+  if(!exact(d,['schema','operationId','runtimeId','inventoryHash','records'])||d.schema!==1||d.operationId!==q.operationId||d.runtimeId!==j.id||d.inventoryHash!==j.inventoryHash||!Array.isArray(d.records)||d.records.length>128||new Set(d.records.map(x=>x.id)).size!==d.records.length)fail('RUNTIME_REPAIR_LEDGER_REVIEW');
+  for(const r of d.records)if(!exact(r,['id','fingerprint','baseHash','state','delta','updatedAt'])||!uuid(r.id)||!hex(r.fingerprint)||!hex(r.baseHash)||!['applying','committed','rolled_back','needs_review'].includes(r.state)||!Array.isArray(r.delta)||r.delta.length>512||!Number.isSafeInteger(r.updatedAt)||r.state!=='committed'&&r.delta.length)fail('RUNTIME_REPAIR_LEDGER_REVIEW');
+  if(names.some(n=>!d.records.some(r=>r.id===n)))fail('RUNTIME_REPAIR_LEDGER_REVIEW');
+  if(d.records.slice(0,-1).some(x=>!terminal(x)))fail('RUNTIME_REPAIR_LEDGER_REVIEW');return d;
+ }
+ async function save(d){const value=signed(d,q.proof);if(Buffer.byteLength(JSON.stringify(value))>16777216)fail('RUNTIME_REPAIR_HISTORY_LIMIT');await atomicJSON(file,value);}
+ function merged(d,requireTerminal=false){
+  const map=new Map(original.items.map(x=>[x.path,x]));
+  for(const r of d.records){
+   if(r.baseHash!==hash([...map.values()]))fail('RUNTIME_REPAIR_OWNERSHIP_REVIEW');
+   if(!terminal(r)&&requireTerminal)fail('RUNTIME_REPAIR_RECOVERY_REQUIRED');
+   const seen=new Set();
+   for(const delta of r.delta){const e=delta.after,f=sources.get(e?.path),old=map.get(e?.path);
+    if(!exact(delta,['before','after'])||!f||seen.has(e.path)||!old||hash(delta.before)!==hash(old)||!exact(e,['path','kind','dev','ino','uid','mode','bytes','sha256'])||e.kind!=='file'||![e.dev,e.ino,e.uid,e.bytes].every(Number.isSafeInteger)||e.uid!==process.getuid()||e.mode!==0o600||e.sha256!==f.sha256||e.bytes!==f.bytes)fail('RUNTIME_REPAIR_OWNERSHIP_REVIEW');
+    seen.add(e.path);map.set(e.path,e);
+   }
+  }
+  return [...map.values()];
+ }
+ async function stopped(){
+  const current=await runtimeRecord(q);
+  if(current?.id!==j.id||current.inventoryHash!==j.inventoryHash||current.revision!==j.revision)fail('RUNTIME_REPAIR_RUNTIME_CHANGED');
+  if(!current.nativeReceipt?.ok||!['host_ready','failed','stopped'].includes(current.state))fail('RUNTIME_REPAIR_NOT_READY');
+  for(const p of [current.host,current.worker,current.child,current.restart?.launcher])if(await runtimeAlive(p))fail('RUNTIME_PROCESS_ACTIVE');
+  await runtimeStopLedger(q,current,true);
+ }
+ async function outside(d){
+  await stopped();const expected=merged(d),omit=new Set(sources.keys()),current=await runtimeInventory(q,omit);
+  const filter=x=>!mutable(x.path)&&!omit.has(x.path);
+  if(hash(current.filter(filter))!==hash(expected.filter(filter)))fail('RUNTIME_REPAIR_OUTSIDE_DRIFT');
+ }
+ const inventory=original.items.filter(x=>x.path.startsWith('runtime/plugin/')).map(x=>({path:x.path.slice(15),kind:x.kind,identity:{dev:x.dev,ino:x.ino,mode:x.mode},sha256:x.sha256??null}));
+ const repair=createPluginRepair({root:q.root,operationId:q.operationId,runtimeId:j.id,proof:q.proof,manifest,inventory,exclusive:fn=>fn(),verifyOwnedStopped:async()=>{await stopped();return {operationId:q.operationId,runtimeId:j.id,stopped:true,ownershipVerified:true};}});
+ function view(d,r=d.records.at(-1)){return {operationId:q.operationId,runtimeId:j.id,initialization:false,hostStarted:false,state:r?'repair_'+r.state:'repair_not_started',scope,repair:{contract:1,id:r?.id??null,state:r?.state??'not_started',recoveryRequired:!!r&&!terminal(r),ownershipRebased:r?.state==='committed',activationVerified:false,versionUpgrade:false,files:r?.delta.map(x=>x.after.path.slice(15))??[]},automaticRetry:false};}
+ async function finish(d,r,result){
+  await outside(d);
+  if(result.state==='committed'){
+   const current=merged(d),map=new Map(current.map(x=>[x.path,x])),rows=await repair.ownership({id:r.id});
+   r.delta=rows.map(x=>{const name='runtime/plugin/'+x.path,before=map.get(name);if(!before)fail('RUNTIME_REPAIR_OWNERSHIP_REVIEW');return {before,after:{path:name,dev:x.identity.dev,ino:x.identity.ino,uid:process.getuid(),mode:x.identity.mode,kind:'file',bytes:x.bytes,sha256:x.sha256}};});
+  }
+  r.state=result.state;r.updatedAt=Date.now();merged(d);await save(d);return view(d);
+ }
+ async function action(name,args){
+  const d=await ledger();merged(d);
+  const activation=()=>createRuntimeActivation(api,q,j,{repair:d.records.at(-1),inventory:merged(d,true),source,compat:c});
+  if(name==='verify'){if(c.onboardingPluginRepairActivation!==1)fail('RUNTIME_ACTIVATION_UNSUPPORTED');return {...view(d),activation:await activation().verify(args.id)};}
+  if(name==='status')return {...view(d),activation:c.onboardingPluginRepairActivation===1?await createRuntimeActivation(api,q,j,{repair:d.records.at(-1),inventory:[],source,compat:c}).status():null};
+  try{await outside(d);}catch(e){if(name==='apply'&&!d.records.some(x=>x.id===args.id))fail('RUNTIME_REPAIR_PREFLIGHT_REFUSED');throw e;}
+  if(name==='preview'){if(d.records.some(x=>!terminal(x)))fail('RUNTIME_REPAIR_RECOVERY_REQUIRED');const p=await repair.preview();return {...p,operationId:q.operationId,runtimeId:j.id,initialization:false,repairSupported:true,ownershipRebased:false,activationVerified:false};}
+  if(name==='apply'){
+   const old=d.records.find(x=>x.id===args.id);if(old){if(old.fingerprint!==args.fingerprint)fail('RUNTIME_REPAIR_PLAN_DRIFT');return {...view(d,old),notResent:true,cached:true};}
+   if(d.records.some(x=>!terminal(x)))fail('RUNTIME_REPAIR_RECOVERY_REQUIRED');if(d.records.length>=128)fail('RUNTIME_REPAIR_HISTORY_LIMIT');
+   try{await repair.validate(args);}catch{fail('RUNTIME_REPAIR_PREFLIGHT_REFUSED');}const r={id:args.id,fingerprint:args.fingerprint,baseHash:hash(merged(d)),state:'applying',delta:[],updatedAt:Date.now()};d.records.push(r);await save(d);
+   // Unknown publication is never retried. Recovery examines the same signed journal.
+   try{return await finish(d,r,await repair.apply(args));}catch(e){r.state='needs_review';r.delta=[];r.updatedAt=Date.now();await save(d);throw e;}
+  }
+  if(name==='recover'){
+   const r=d.records.at(-1);if(!r||r.id!==args.id)fail('RUNTIME_REPAIR_RECOVERY_REQUIRED');if(terminal(r))return {...view(d),notResent:true};
+   return finish(d,r,await repair.recover(args));
+  }
+  fail('ARGUMENTS');
+ }
+ async function dispatch(){try{const v=await action(q.action.slice(15),{...(q.repairId?{id:q.repairId,confirm:true}:{}),...(q.fingerprint?{fingerprint:q.fingerprint}:{})});return {...v,hostStarted:await runtimeAlive(j.host)};}catch(e){if(/^ONBOARDING_PLUGIN_REPAIR_[A-Z_]+$/.test(e.message))fail('RUNTIME_REPAIR_'+e.message.slice(25));throw e;}}
+ return {action,dispatch,effective:async()=>merged(await ledger(),true)};
+}

package/bundle/onboarding-runtime-stop.js

@@ -0,0 +1,90 @@
+import {observeRuntimeHost} from './onboarding-host-stop-observation.js';
+// Fixed archived stop controller. Native Host shutdown needs an independent
+// risk-confirmed schema-2 plan; an idle snapshot is never a lossless drain.
+export function createRuntimeStop(api){
+ const {fs,path,randomUUID,runtimeDir,regular,verified,signed,exact,uuid,hash,fail,runtimeAlive,runtimeRecord,runtimeView,atomicJSON}=api;
+// Stop authorization is separate from the worker journal, which the installer
+// may update concurrently. Legacy installer plans never authorize a Host signal.
+const observeHost=(q,j)=>observeRuntimeHost(api,q,j);
+const hostScope='owned_host_with_loss_risk';
+const risk={contract:1,lateNativeInputMayAbort:true,imInFlightMayAbort:true,ownQueuesRetained:true,ingressFrozen:false,automaticStop:false,requiresExplicitAcknowledgement:true};
+const stopPath=q=>path.join(runtimeDir(q),'stop.json');
+async function runtimeStopLedger(q,j,terminalOnly=false){
+ const r=await regular(stopPath(q),262144);if(!r)return {schema:1,operationId:q.operationId,runtimeId:j.id,records:[]};
+ if(r.identity.mode!==0o600||r.identity.uid!==process.getuid())fail('RUNTIME_STOP_LEDGER_REVIEW');
+ const d=verified(JSON.parse(r.data),q.proof);
+ if(!exact(d,['schema','operationId','runtimeId','records'])||d.schema!==1||d.operationId!==q.operationId||d.runtimeId!==j.id||!Array.isArray(d.records)||d.records.length>32)fail('RUNTIME_STOP_LEDGER_REVIEW');
+ const ids=new Set();for(const row of d.records){
+  if(!exact(row,['plan','phase','updatedAt','error'])||!['requested','signalled','needs_review','ended'].includes(row.phase)||!Number.isSafeInteger(row.updatedAt)||row.error!==null&&!/^ONBOARDING_CLOUD_[A-Z_]+$/.test(row.error))fail('RUNTIME_STOP_LEDGER_REVIEW');
+  const p=runtimeStopPlan(q,j,row.plan);if(ids.has(p.id))fail('RUNTIME_STOP_LEDGER_REVIEW');ids.add(p.id);
+  if(terminalOnly&&row.phase!=='ended')fail('RUNTIME_STOP_RECONCILE_REQUIRED');
+ }
+ return d;
+}
+function runtimeStopPlan(q,j,value){
+ const p=verified(value,q.proof);
+ const host=p.schema===2;
+ if(!exact(p,['schema','id','operationId','runtimeId','revision','scope','createdAt','expiresAt','members','host','canApply','reason',...(host?['risk','observation']:[])])||![1,2].includes(p.schema)||!uuid(p.id)||p.operationId!==q.operationId||p.runtimeId!==j.id||!Number.isSafeInteger(p.revision)||p.revision<1||p.scope!==(host?hostScope:'installer_processes_only')||!Number.isSafeInteger(p.createdAt)||p.expiresAt!==p.createdAt+300000||!exact(p.members,['worker','child','launcher'])||typeof p.canApply!=='boolean'||!['ready','no_active_installer','host_drain_required','prior_stop_unresolved','host_busy','host_observation_required','installer_active'].includes(p.reason))fail('RUNTIME_STOP_PLAN_REVIEW');
+ for(const m of [...Object.values(p.members),p.host])if(m!==null&&(!exact(m,['platform','pid','boot','start'])||m.platform!=='linux'||!Number.isSafeInteger(m.pid)||m.pid<2||typeof m.boot!=='string'||typeof m.start!=='string'))fail('RUNTIME_STOP_PLAN_REVIEW');
+ if(host&&(p.host===null||hash(p.risk)!==hash(risk)||p.observation!==null&&(!exact(p.observation,['contract','nativeNonce','instances','idle','reasons','observedAt','ingressFrozen','imInFlightVerified'])||p.observation.contract!==1||!uuid(p.observation.nativeNonce)||!exact(p.observation.instances,['onboarding','agents','gateway','im'])||Object.values(p.observation.instances).some(x=>x!==null&&!uuid(x))||typeof p.observation.idle!=='boolean'||!Array.isArray(p.observation.reasons)||p.observation.reasons.some(x=>!['component_unavailable','own_work_active','native_work_active_or_unknown','im_maintenance_pending'].includes(x))||!Number.isSafeInteger(p.observation.observedAt)||p.observation.ingressFrozen!==false||p.observation.imInFlightVerified!==false)))fail('RUNTIME_STOP_PLAN_REVIEW');
+ return p;
+}
+async function runtimeStopSnapshot(j){
+ const members={worker:null,child:null,launcher:null};for(const [key,m] of [['worker',j.worker],['child',j.child],['launcher',j.restart?.launcher]])if(await runtimeAlive(m))members[key]=m;
+ return {members,host:await runtimeAlive(j.host)?j.host:null};
+}
+async function runtimeStopView(q,j){
+ const d=await runtimeStopLedger(q,j),row=d.records.at(-1);if(!row)return null;
+ const p=runtimeStopPlan(q,j,row.plan);let active=0;for(const m of Object.values(p.members))if(await runtimeAlive(m))active++;
+ return {id:p.id,phase:row.phase,scope:p.scope,activeInstallerMembers:active,reconcileRequired:row.phase!=='ended',stopPlan:row.plan,error:row.error,hostActive:p.schema===2&&await runtimeAlive(p.host),hostStopAuthorized:p.schema===2,nativeInputMayAbort:p.schema===2,automaticRetry:false};
+}
+async function runtimeStopPreview(q,j){
+ if(process.platform!=='linux')fail('RUNTIME_PLATFORM_UNSUPPORTED');
+ const d=await runtimeStopLedger(q,j),s=await runtimeStopSnapshot(j),now=Date.now();
+ let observation=null;if(s.host&&typeof observeHost==='function')try{observation=await observeHost(q,j);}catch{}
+ const active=Object.values(s.members).some(Boolean),reason=d.records.some(x=>x.phase!=='ended')?'prior_stop_unresolved':s.host?(active?'installer_active':!observation?'host_observation_required':!observation.idle?'host_busy':'ready'):active?'ready':'no_active_installer';
+ const host=!!s.host,p={schema:host?2:1,id:randomUUID(),operationId:q.operationId,runtimeId:j.id,revision:j.revision,scope:host?hostScope:'installer_processes_only',createdAt:now,expiresAt:now+300000,...s,canApply:reason==='ready',reason,...(host?{risk,observation}:{})};
+ return {operationId:q.operationId,runtimeId:j.id,initialization:false,hostStarted:host,scope:p.scope,canApply:p.canApply,reason,expiresAt:p.expiresAt,stopPlan:signed(p,q.proof),hostStopAuthorized:false,...(host?{risk,observation}:{})};
+}
+async function runtimeStop(q,j,io={}){
+ if(process.platform!=='linux')fail('RUNTIME_PLATFORM_UNSUPPORTED');
+ const p=runtimeStopPlan(q,j,q.stopPlan),d=await runtimeStopLedger(q,j),old=d.records.find(x=>x.plan.id===p.id);
+ if(old){if(hash(old.plan)!==hash(q.stopPlan))fail('RUNTIME_STOP_PLAN_REVIEW');
+  if(q.action==='runtime_stop_reconcile'){
+   for(const m of [...Object.values(p.members),...(p.schema===2?[p.host]:[])])if(await runtimeAlive(m))fail('RUNTIME_STOP_STILL_ACTIVE');
+   if(old.phase!=='ended'){old.phase='ended';old.updatedAt=Date.now();await atomicJSON(stopPath(q),signed(d,q.proof));}
+  }
+  return {...await runtimeView(q,j),stopRequested:true,notResent:true};
+ }
+ if(q.action==='runtime_stop_reconcile')fail('RUNTIME_STOP_NOT_REQUESTED');
+ const host=p.schema===2;if(host&&q.acknowledgeNativeInterruption!==true)fail('RUNTIME_HOST_STOP_CONSENT_REQUIRED');
+ if(!p.canApply||p.reason!=='ready')fail(p.reason==='host_drain_required'?'RUNTIME_HOST_DRAIN_REQUIRED':'RUNTIME_STOP_NOT_READY');
+ if(p.expiresAt<=Date.now()||p.createdAt>Date.now()+1000)fail('RUNTIME_STOP_PLAN_EXPIRED');
+ if(d.records.some(x=>x.phase!=='ended'))fail('RUNTIME_STOP_RECONCILE_REQUIRED');if(d.records.length>=32)fail('RUNTIME_STOP_HISTORY_LIMIT');
+ const fresh=await runtimeRecord(q),s=await runtimeStopSnapshot(fresh);
+ if(!host&&s.host)fail('RUNTIME_HOST_DRAIN_REQUIRED');if(fresh.revision!==p.revision||hash(s.members)!==hash(p.members)||host&&hash(s.host)!==hash(p.host))fail('RUNTIME_STOP_PLAN_DRIFT');
+ const checkHost=async current=>{const o=await observeHost(q,current);if(!o.idle)fail('RUNTIME_HOST_BUSY');if(hash(o.instances)!==hash(p.observation?.instances)||o.nativeNonce!==p.observation?.nativeNonce)fail('RUNTIME_STOP_PLAN_DRIFT');};
+ if(host)try{await checkHost(fresh);}catch{fail('RUNTIME_HOST_STOP_PREFLIGHT_REFUSED');}
+ const row={plan:q.stopPlan,phase:'requested',updatedAt:Date.now(),error:null};d.records.push(row);await atomicJSON(stopPath(q),signed(d,q.proof));
+ try{
+  await io.afterStopIntent?.();
+  const latest=await runtimeRecord(q);if(!host&&await runtimeAlive(latest.host))fail('RUNTIME_HOST_DRAIN_REQUIRED');
+  if(latest.id!==j.id||latest.revision!==p.revision)fail('RUNTIME_STOP_PLAN_DRIFT');
+  if(host){
+   if(hash(latest.host)!==hash(p.host)||Object.values((await runtimeStopSnapshot(latest)).members).some(Boolean))fail('RUNTIME_STOP_PLAN_DRIFT');
+   await checkHost(latest);if(!await runtimeAlive(p.host))fail('RUNTIME_STOP_PLAN_DRIFT');
+   process.kill(p.host.pid,'SIGTERM');
+  }else{
+  // A native Host is detached into another process group. Only recorded installer
+  // members are signalled; birth identities are checked immediately before use.
+  if(await runtimeAlive(p.members.launcher))process.kill(p.members.launcher.pid,'SIGTERM');
+  const member=await runtimeAlive(p.members.worker)?p.members.worker:await runtimeAlive(p.members.child)?p.members.child:null;
+  if(member){const raw=await fs.readFile('/proc/'+member.pid+'/stat','utf8'),parts=raw.slice(raw.lastIndexOf(')')+2).split(' ');if(Number(parts[2])!==j.worker?.pid)fail('RUNTIME_PROCESS_REVIEW');process.kill(-j.worker.pid,'SIGTERM');}
+  }
+  row.phase='signalled';row.updatedAt=Date.now();await atomicJSON(stopPath(q),signed(d,q.proof));
+ }catch(e){row.phase='needs_review';row.error=/^ONBOARDING_CLOUD_[A-Z_]+$/.test(e.message)?e.message:'ONBOARDING_CLOUD_RUNTIME_STOP_UNKNOWN';row.updatedAt=Date.now();await atomicJSON(stopPath(q),signed(d,q.proof));throw e;}
+ return {...await runtimeView(q,await runtimeRecord(q)),stopRequested:true};
+}
+
+ return {ledger:runtimeStopLedger,view:runtimeStopView,preview:runtimeStopPreview,apply:runtimeStop};
+}