@josephyulei/summon-foundation 0.1.3 → 0.1.5

package/README.md

@@ -1,15 +1,19 @@
 # summon foundation
 
+0.1.5 配合 Foundation 0.2.11。选中 Skill 后由程序接续精确确认；`--update --root <安装根> --version <固定版本>`、`--uninstall --root <安装根>` 组织维护步骤。`--resume <同次结果文件>` 仅恢复程序成功后的所选 Skill，不重装或重放批准。
+
+0.1.5 提供获取期间只读进度页。获取成功后同一页面关联运行程序返回的目录/确认页，仍由 Codex 内置浏览器打开；配合 Foundation 0.2.11 展示本次流程、当前目标和剩余动作。临时服务只随本次任务运行，不是守护进程，不执行未核验归档，也不替本人确认。原操作回执仍可独立只读查询，页断开不改写已核实终态。
+
 Foundation 的薄获取入口，不包含完整运行包，没有 npm 安装生命周期脚本。
 只有明确执行才查询/获取；安装和 Skill 注册继续各自需要用户确认。
 
 可用性以 npm registry 的实际版本和公共 GitHub Release 为准；本目录或说明存在不是发布回执。只使用本项目已核验的包名，缺包时不换同名来源。
 
 ```text
-npx --yes --package @josephyulei/summon-foundation@0.1.3 summon foundation
+npx --yes --package @josephyulei/summon-foundation@0.1.5 summon foundation
 ```
 
-0.1.3 入口配合 Foundation 0.2.8 或后续支持目录选择的正式发行使用。默认命令实际查询、固定版本、披露缓存、下载并校验，然后保持运行等待安装页目录选择。选择目录后还要亲自确认精确安装计划；不会注册 Skill 或接入项目。实际获取仍须通过 registry 与 Release 校验，本文不替代发布证明。
+0.1.5 入口配合 Foundation 0.2.11 正式发行使用。默认命令实际查询、固定版本、披露缓存、下载并校验，然后保持运行等待安装页目录选择。选择目录后还要亲自确认精确安装计划；不会自动注册 Skill 或接入项目。实际获取仍须通过 registry 与 Release 校验，本文不替代发布证明。
 
 Codex 需要打开返回的内置浏览器网址，并分段等待同次操作结果。npm 不能自行操控或唤醒 Codex，对话主动告知不是程序退出码保证；新对话接续仍待真人验收。系统浏览器只是明确告知后的备用，不自动打开。
 

package/bin/summon.mjs

@@ -2,8 +2,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {spawn,spawnSync} from 'node:child_process';
-import {inspectRelease,acquireRelease,plainPath} from '../lib/acquire.mjs';
+import {inspectRelease,plainPath} from '../lib/acquire.mjs';
 
+import {acquireInWorker} from '../lib/acquisition-task.mjs';
+import {startProgressPage} from '../lib/progress-page.mjs';
+import {followSelectedSkill} from '../lib/skill-handoff.mjs';
+import {followMaintenance} from '../lib/maintenance-handoff.mjs';
+import {resumeSkillHandoff} from '../lib/resume-handoff.mjs';
 import {parseSummonArgs} from '../lib/cli-options.mjs';
 import {createOperation,saveOperation,readOperation,runtimeObservation} from '../lib/operation-result.mjs';
 
@@ -12,11 +17,16 @@ summon foundation --inspect [--version x.y.z]
 summon foundation --prepare --version x.y.z --destination /absolute/folder
 summon foundation --acquire --version x.y.z
 summon foundation --status /absolute/acquisition/operation-result.json
+summon foundation --update --root /absolute/installed-folder --version x.y.z
+summon foundation --uninstall --root /absolute/installed-folder
+summon foundation --resume /absolute/acquisition/operation-result.json
 默认命令下载并验证正式发行，进入安装准备；未给目录时在安装页选择。不会静默安装或注册 Skill。
 --inspect 才只读查询发行，不下载运行归档。
 --prepare 下载并核验固定发行，打开 Foundation 本人确认流程；不会代替确认。
 --acquire 仅下载并核验更新材料，返回候选与回执；不启动安装或执行更新。
 --status 只读本次结果记录；中间记录不证明进程仍在运行，不重试或重放确认。
+--update / --uninstall 从已安装稳定入口组织必要步骤；每一步仍需页面独立确认，不自动注册原本没有的 Skill。
+--resume 明确恢复程序已完成后的所选 Skill；核验当前安装与旧记录后仅准备未完成项的新确认，不重复安装。
 仅 macOS arm64。npm 入口需要 Node/npm；已安装 Foundation 使用随包运行时。
 普通终端不能控制 Codex 对话或内置浏览器。无需 npm 的引导见公共仓库安装说明。`;
 function fail(message){throw Error(message);}
@@ -37,8 +47,8 @@ function stageDirectory(){
   const stat=fs.lstatSync(cache);if(stat.uid!==process.getuid()||(stat.mode&0o777)!==0o700)fail('获取缓存必须由当前用户独占 0700；不会自动 chmod 已有目录');
   return fs.mkdtempSync(path.join(cache,'acquisition.'));
 }
-let operation=null,stage=null;
-function updateOperation(patch){if(!operation)return;Object.assign(operation,patch,{updatedAt:new Date().toISOString()});const file=saveOperation(operation,stage);console.log(JSON.stringify({status:'FOUNDATION_INSTALL_OPERATION',...operation,resultFile:file,recordSaved:!!file}));}
+let operation=null,stage=null,progressPage=null;
+function updateOperation(patch){if(!operation)return;Object.assign(operation,patch,{updatedAt:new Date().toISOString()});const file=saveOperation(operation,stage);if(file)operation.resultFile=file;progressPage?.publish();console.log(JSON.stringify({status:'FOUNDATION_INSTALL_OPERATION',...operation,resultFile:file,recordSaved:!!file}));}
 async function openInstalledWorkbench(root,env){
   let child;
   try{
@@ -63,28 +73,51 @@ try{
   const [major,minor]=process.versions.node.split('.').map(Number);
   if(major<22||(major===22&&minor<9))fail('获取入口需要 Node.js 22.9 或以上；尚未安装，不自动安装依赖');
   if(process.platform!=='darwin'||process.arch!=='arm64')fail('当前仅支持 macOS arm64；尚未安装');
-  if(args.prepare||args.acquire)sourceGuard();
-  if(args.prepare||args.acquire){operation=createOperation();stage=stageDirectory();updateOperation({});if(!saveOperation(operation,stage))fail('无法在已披露的获取目录保存操作记录；尚未联网或安装');}
+  const maintenance=args.update||args.uninstall;
+  if(args.prepare||args.acquire||maintenance||args.resume)sourceGuard();
+  if(args.prepare||args.acquire||maintenance){operation=createOperation();stage=stageDirectory();updateOperation({});if(!saveOperation(operation,stage))fail('无法在已披露的获取目录保存操作记录；尚未联网或安装');}
   if(args.prepare)console.log('正在准备 Foundation 安装：将查询并固定本次正式版本，说明缓存位置后下载核验。未选目录会在安装页选择；之后仍需本人确认精确计划。请保持当前 Codex 任务等待并打开返回的内置浏览器网址；不会自动改用系统浏览器。');
-  const context=inspectRelease(args.version);
-  const guide=`https://github.com/${context.repository.full_name}/blob/${context.documentationCommit}/docs/install-with-codex.md`;
-  if(!args.prepare&&!args.acquire){
+  if(args.resume){
+    const env={...process.env};for(const key of ['NODE_OPTIONS','NODE_PATH','NODE_V8_COVERAGE','NODE_REDIRECT_WARNINGS','NODE_COMPILE_CACHE','NODE_COMPILE_CACHE_PORTABLE','NODE_PRESERVE_SYMLINKS'])delete env[key];
+    const result=await resumeSkillHandoff({file:args.resume,env,onChange:patch=>{if(!operation){operation=patch;stage=path.dirname(plainPath(args.resume));}updateOperation(patch);}});
+    updateOperation(result);process.exitCode=result.state==='completed'?0:1;
+  }else if(maintenance){
+    plainPath(args.root);
+    const env={...process.env};for(const key of ['NODE_OPTIONS','NODE_PATH','NODE_V8_COVERAGE','NODE_REDIRECT_WARNINGS','NODE_COMPILE_CACHE','NODE_COMPILE_CACHE_PORTABLE','NODE_PRESERVE_SYMLINKS'])delete env[key];
+    updateOperation({kind:args.update?'update':'uninstall',installationRoot:args.root});
+    progressPage=await startProgressPage(()=>operation);updateOperation({progressUrl:progressPage.url});
+    let candidate;
+    if(args.update){
+      const {context,receipt}=await acquireInWorker({version:args.version,stage,operationId:operation.operationId,onContext:context=>updateOperation({version:context.version,sourceCommit:context.sourceCommit}),onProgress:download=>updateOperation({download}),onPhase:phase=>updateOperation({phase})});
+      const directory=plainPath(path.dirname(receipt.launcher)),manifest=JSON.parse(fs.readFileSync(plainPath(path.join(directory,'manifest.json'))));
+      if(manifest.productVersion!==context.version)fail('获取版本与候选不一致');
+      candidate={path:directory,manifestHash:manifest.candidateHash,version:manifest.productVersion,bytes:manifest.totalBytes,runtimeHash:manifest.files.find(f=>f.path===manifest.runtime.path)?.sha256};
+    }
+    updateOperation(await followMaintenance({operation,kind:operation.kind,candidate,env,onChange:updateOperation}));
+    process.exitCode=operation.state==='completed'?0:1;
+    await progressPage.close();progressPage=null;
+  }else if(!args.prepare&&!args.acquire){
+    const context=inspectRelease(args.version);
+    const guide=`https://github.com/${context.repository.full_name}/blob/${context.documentationCommit}/docs/install-with-codex.md`;
     console.log(JSON.stringify({schemaVersion:'1.0.0',status:'RELEASE_DISCOVERED_NOT_ACQUIRED',product:'Foundation',version:context.version,sourceCommit:context.sourceCommit,documentationCommit:context.documentationCommit,repository:context.repository.full_name,guide,installationPerformed:false,skillRegistered:false,
       conversationNextStep:'本次 --inspect 仅查询；未下载、未安装，不自动接续写入。需要安装时由用户发起默认安装入口，并核对当前任务权限。',
       terminalBoundary:'普通终端无法创建或唤醒 Codex 对话；请在有相应权限的 Codex 任务发起安装。',
       acquisition:'尚未下载或验证运行归档。默认入口或 --prepare 执行匿名 GitHub 证明与完整性核验。'},null,2));
   }else{
     if(args.destination)plainPath(args.destination);console.log(`本次独占获取目录：${stage}`);
-    const receipt=await acquireRelease(context,stage,{operationId:operation.operationId,onProgress:download=>updateOperation({download}),onPhase:phase=>updateOperation({phase,version:context.version,sourceCommit:context.sourceCommit})});console.log(JSON.stringify({status:'GITHUB_ACQUISITION_VERIFIED',...receipt,destinationIntent:args.destination}));
+    progressPage=await startProgressPage(()=>operation);
+    updateOperation({progressUrl:progressPage.url});
+    console.log(JSON.stringify({status:'FOUNDATION_ACQUISITION_PROGRESS_PAGE',url:progressPage.url,operationId:operation.operationId,next:'在 Codex 内置浏览器打开同次只读进度页，保持任务等待；不会自动打开系统浏览器。'}));
+    const {context,receipt}=await acquireInWorker({version:args.version,stage,operationId:operation.operationId,onContext:context=>updateOperation({version:context.version,sourceCommit:context.sourceCommit}),onProgress:download=>updateOperation({download}),onPhase:phase=>updateOperation({phase})});console.log(JSON.stringify({status:'GITHUB_ACQUISITION_VERIFIED',...receipt,destinationIntent:args.destination}));
     updateOperation({phase:'acquired',version:context.version,sourceCommit:context.sourceCommit});
-    if(args.acquire){updateOperation({state:'update-input-ready',terminal:true});console.log(JSON.stringify({status:'UPDATE_INPUT_READY_NOT_APPLIED',candidate:path.dirname(receipt.launcher),receipt:path.join(stage,'acquisition.json'),next:'使用当前健康安装的稳定入口生成独立更新计划；本人确认后才更新。获取回执不是删除授权。'}));process.exit(0);}
+    if(args.acquire){updateOperation({state:'update-input-ready',terminal:true});console.log(JSON.stringify({status:'UPDATE_INPUT_READY_NOT_APPLIED',candidate:path.dirname(receipt.launcher),receipt:path.join(stage,'acquisition.json'),next:'使用当前健康安装的稳定入口生成独立更新计划；本人确认后才更新。获取回执不是删除授权。'}));await progressPage.close();progressPage=null;process.exit(0);}
     const env={...process.env};for(const key of ['NODE_OPTIONS','NODE_PATH','NODE_V8_COVERAGE','NODE_REDIRECT_WARNINGS','NODE_COMPILE_CACHE','NODE_COMPILE_CACHE_PORTABLE','NODE_PRESERVE_SYMLINKS'])delete env[key];
+    const supported=spawnSync(receipt.launcher,['--help'],{encoding:'utf8',env,timeout:15000});
     if(!args.destination){
-      const supported=spawnSync(receipt.launcher,['--help'],{encoding:'utf8',env,timeout:15000});
       if(supported.status!==0||!supported.stdout.includes('--choose-destination'))fail('本次发行尚不支持页面选择目录；未启动安装。请由当前对话取得目录后使用明确的 --destination，或等待新版发行，不静默采用默认位置');
     }
     updateOperation({phase:'starting-confirmation-service',installationWrites:'unknown'});
-    const child=spawn(receipt.launcher,['install',...(args.destination?['--destination',args.destination]:['--choose-destination']),'--browser','codex'],{stdio:['inherit','pipe','inherit'],env});
+    const child=spawn(receipt.launcher,['install',...(!args.destination&&supported.stdout?.includes('--journey-id')?['--journey-id',operation.operationId]:[]),...(args.destination?['--destination',args.destination]:['--choose-destination']),'--browser','codex'],{stdio:['inherit','pipe','inherit'],env});
     child.stdout.setEncoding('utf8');
     let pending='',json='';
     child.stdout.on('data',bytes=>{process.stdout.write(bytes);pending+=bytes.toString();if(pending.length>1_000_000){pending='';json='';return;}let end;while((end=pending.indexOf('\n'))>=0){const line=pending.slice(0,end);pending=pending.slice(end+1);if(!json&&!line.trim().startsWith('{'))continue;json+=line+'\n';if(json.length>1_000_000){json='';continue;}let e;try{e=JSON.parse(json)}catch{continue}json='';
@@ -95,11 +128,15 @@ try{
     process.once('SIGINT',int);process.once('SIGTERM',term);
     const ended=await new Promise((resolve,reject)=>{child.once('error',reject);child.once('close',(code,signal)=>resolve({code,signal}));}).finally(()=>{process.off('SIGINT',int);process.off('SIGTERM',term);});
     if(ended.signal||ended.code===null)fail(`确认服务未正常返回；结果待核实，保留 ${stage}，不要自动重试安装`);
+    if(operation.state==='awaiting-skill'){
+      try{updateOperation(await followSelectedSkill({operation,env,onChange:updateOperation}));}
+      catch(error){updateOperation({state:'partial',phase:'finished',terminal:true,skillRegistered:false,handoffFailure:{code:error.code||'SKILL_HANDOFF_REQUIRES_VERIFICATION',command:error.command||null,exitCode:error.exitCode??null},next:'程序已安装，Skill 接续未完成；保留当前计划与结果，仅核实未完成步骤，不重装程序或重放确认。'});}
+    }
     if(!operation.terminal)updateOperation({state:'verification-required',terminal:true,childExitCode:ended.code,next:'服务退出不等于成功或取消；只读核验原 session 与 installed 状态，不自动重试'});
     if(operation.state==='completed'&&operation.installationRoot){
       const workbench=await openInstalledWorkbench(operation.installationRoot,env);
-      updateOperation({phase:'finished',workbench,next:workbench.state==='ready'?'在 Codex 内置浏览器打开已就绪工作台；Skill 与项目仍未接入，按用户偏好另行询问':'安装已完成，但工作台未就绪；保留安装结果并只读检查'});
+      updateOperation({phase:'finished',workbench,next:workbench.state==='ready'?(operation.skillRegistered?'打开已安装工作台；Skill 文件已注册，新对话识别与项目接入另验':'打开已安装工作台；本次未注册 Skill，项目接入另行确认'):'安装已完成，但工作台未就绪；保留安装结果并只读检查'});
     }
-    process.exitCode=ended.code;
+    process.exitCode=operation.state==='partial'?1:ended.code;
   }
-}catch(e){updateOperation({state:operation&&operation.installationWrites!=='none'?'verification-required':'failed',terminal:true,errorCode:['ACQUISITION_TRANSPORT_FAILED','ACQUISITION_VALIDATION_FAILED'].includes(e.code)?e.code:'INSTALL_ENTRY_FAILED',diagnostic:e.diagnostic||null,next:'先核验旧工具进程已结束及同次结果；保留材料，不自动重试或重放安装确认'});const message=String(e.message).replace(/https?:\/\/\S+/g,'[已脱敏网址]').replace(/(?:github_pat_|ghp_|npm_)[A-Za-z0-9_]+/g,'[已脱敏凭据]');console.error(`错误：${message}`);process.exitCode=1;}
+}catch(e){const message=String(e.message).replace(/https?:\/\/\S+/g,'[已脱敏网址]').replace(/(?:github_pat_|ghp_|npm_)[A-Za-z0-9_]+/g,'[已脱敏凭据]');updateOperation({state:operation?.programState==='completed'?'partial':operation&&operation.installationWrites!=='none'?'verification-required':'failed',terminal:true,...(operation?.programState==='completed'?{failedPhase:operation.phase,phase:'finished'}:{}),errorCode:['ACQUISITION_TRANSPORT_FAILED','ACQUISITION_VALIDATION_FAILED'].includes(e.code)?e.code:'INSTALL_ENTRY_FAILED',diagnostic:e.diagnostic||null,next:message+'。先核验旧工具进程已结束及同次结果；保留材料，不自动重试或重放安装确认'});console.error(`错误：${message}`);process.exitCode=1;}finally{if(progressPage)await progressPage.close();}

package/lib/acquisition-task.mjs

@@ -0,0 +1,24 @@
+import {Worker} from 'node:worker_threads';
+
+export function acquireInWorker({version,stage,operationId,onContext=()=>{},onPhase=()=>{},onProgress=()=>{}}) {
+  return new Promise((resolve,reject)=>{
+    const worker=new Worker(new URL('./acquisition-worker.mjs',import.meta.url),{workerData:{version,stage,operationId}});
+    let receipt,context,failure;
+    const interrupt=()=>{failure=Object.assign(Error('获取任务被中断；保留本次材料'),{code:'ACQUISITION_INTERRUPTED'});void worker.terminate();};
+    process.once('SIGINT',interrupt);process.once('SIGTERM',interrupt);
+    worker.on('message',event=>{
+      if(event.type==='context'){context=event.context;onContext(context);}
+      else if(event.type==='phase')onPhase(event.phase);
+      else if(event.type==='progress')onProgress(event.download);
+      else if(event.type==='complete')receipt=event.receipt;
+      else if(event.type==='failure')failure=Object.assign(Error(event.message),{code:event.code,diagnostic:event.diagnostic});
+    });
+    worker.on('error',error=>{failure=error;});
+    worker.once('exit',code=>{
+      process.off('SIGINT',interrupt);process.off('SIGTERM',interrupt);
+      if(failure)reject(failure);
+      else if(code!==0||!receipt||!context)reject(Error('获取进程未提供已验证结果；不启动运行文件'));
+      else resolve({context,receipt});
+    });
+  });
+}

package/lib/acquisition-worker.mjs

@@ -0,0 +1,17 @@
+// Trusted npm code only. Network/proof routines contain synchronous calls;
+// isolate those calls so the read-only progress server remains responsive.
+import {parentPort, workerData} from 'node:worker_threads';
+import {inspectRelease, acquireRelease} from './acquire.mjs';
+
+try {
+  const context = inspectRelease(workerData.version);
+  parentPort.postMessage({type:'context',context});
+  const receipt = await acquireRelease(context, workerData.stage, {
+    operationId:workerData.operationId,
+    onPhase:phase=>parentPort.postMessage({type:'phase',phase}),
+    onProgress:download=>parentPort.postMessage({type:'progress',download}),
+  });
+  parentPort.postMessage({type:'complete',receipt});
+} catch(error) {
+  parentPort.postMessage({type:'failure',code:error.code,diagnostic:error.diagnostic||null,message:String(error.message).replace(/https?:\/\/\S+/g,'[已脱敏网址]').replace(/(?:github_pat_|ghp_|npm_)[A-Za-z0-9_]+/g,'[已脱敏凭据]')});
+}

package/lib/cli-options.mjs

@@ -8,11 +8,18 @@ export function parseSummonArgs(args){
     if(flag==='--prepare')result.prepare=true;
     else if(flag==='--acquire')result.acquire=true;
     else if(flag==='--inspect')result.inspect=true;
-    else if(flag==='--version'||flag==='--destination'||flag==='--status'){if(!args.length||args[0].startsWith('--'))fail('参数缺值');result[flag.slice(2)]=args.shift();}
+    else if(flag==='--update'||flag==='--uninstall')result[flag.slice(2)]=true;
+    else if(['--version','--destination','--status','--root','--resume'].includes(flag)){if(!args.length||args[0].startsWith('--'))fail('参数缺值');result[flag.slice(2)]=args.shift();}
     else fail('未知参数；请查看 --help');
   }
   if((result.prepare||result.acquire||result.destination)&&result.inspect||result.prepare&&result.acquire||result.destination&&result.acquire)fail('参数组合不支持');
   if(seen.has('--status')){if(!result.status||seen.size!==1)fail('结果查询需要非空路径且不能与其他操作组合');return result;}
+  if(seen.has('--resume')){if(!result.resume||seen.size!==1)fail('恢复需要单一结果路径，不接受新目标或额外操作');return result;}
+  if(result.update||result.uninstall){
+    if(result.update&&result.uninstall||!result.root||result.inspect||result.acquire||result.prepare||result.destination||result.uninstall&&result.version||result.update&&!result.version)fail('维护需要单一动作、明确 --root；更新还需要固定 --version');
+    return result;
+  }
+  if(result.root)fail('--root 仅用于明确的更新或卸载');
   if(!result.inspect&&!result.acquire)result.prepare=true;
   if(result.acquire&&!result.version)fail('获取更新材料前须固定版本');
   return result;

package/lib/journey-view.mjs

@@ -0,0 +1,12 @@
+// Presentation only. Planned steps never grant execution authority.
+export function journeyView({id,kind='install',observations={},skillChoice='undecided',includeAcquisition=false,includeSelection=false,includeHealth=true,includeCleanup=false,includeSkillRemoval=false}) {
+  const labels={acquire:'获取并核验运行文件',select:'选择安装目录',program:({install:'安装程序',update:'更新程序',uninstall:'移除程序'})[kind]||'执行当前维护',health:'验证稳定入口',cleanup:'处理本次暂存',material:'准备对话能力材料',register:'注册到 Codex',remove:'移除 Codex 注册'};
+  const statusLabels={completed:'已完成',pending:'待确认',planned:'尚待处理',running:'进行中',executing:'进行中',consumed:'进行中',failed:'失败',cancelled:'已取消',expired:'已过期',skipped:'已跳过',undecided:'可选，待选择',retained:'已处理，保留部分材料','verification-required':'待核实'};
+  const keys=[...(includeAcquisition?['acquire']:[]),...(includeSelection?['select']:[]),...(includeSkillRemoval?['remove']:[]),'program',...(includeHealth?['health']:[]),...(includeCleanup?['cleanup']:[])];
+  if(kind!=='uninstall'&&(observations.material||observations.register||skillChoice==='selected'))keys.push('material','register');else if(kind!=='uninstall')keys.push('optional-skill');
+  const steps=keys.map(key=>{const supplied=observations[key],state=key==='optional-skill'?(skillChoice==='skipped'?'skipped':'undecided'):supplied?.state||'planned';return{id:`${id}:${key}`,key,title:labels[key]||'Codex 对话能力',state,label:statusLabels[state]||'待核实',evidence:supplied?.evidence||null,required:key!=='optional-skill'};});
+  const unresolved=steps.filter(s=>s.required&&!['completed','skipped','retained'].includes(s.state)),name=({install:'安装',update:'更新',uninstall:'卸载'})[kind]||'维护';
+  const program=observations.program?.state==='completed',trouble=unresolved.find(s=>['failed','cancelled','expired','verification-required'].includes(s.state));
+  const title=!unresolved.length?`${name}完成`:program?`程序已完成，${(trouble||unresolved[0]).title}${trouble?'未完成':'仍待处理'}`:trouble?`${name}未完成`:`${name}流程`;
+  return {schemaVersion:'1.1.0',id,kind,title,ended:unresolved.length===0,steps,remaining:unresolved.map(s=>s.title),summary:unresolved.length?`尚余：${unresolved.map(s=>s.title+'（'+s.label+'）').join('、')}`:kind==='uninstall'?'本次卸载步骤已完成。请查看卸载回执中的实际删除范围、保留文件与清理说明。':skillChoice==='undecided'&&!observations.register?'已确定操作已完成；对话能力可选，尚未选择。项目接入独立。':'本次已选择步骤均已处理；新任务发现及项目接入另验。',executionAuthority:false};
+}

package/lib/maintenance-handoff.mjs

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {isDeepStrictEqual} from 'node:util';
+import {plainPath} from './acquire.mjs';
+import {installedClient,observePlan} from './manager-step.mjs';
+import {followSelectedSkill} from './skill-handoff.mjs';
+
+// The running owned engine emits the result body; disk additionally stores its
+// integrity envelope. Bind every body field to that live result, not to the
+// receipt's self-asserted signature (the uninstall may remove its local key).
+export function matchesUninstallResult(receipt,payload,installId) {
+  const {integrity,...body}=receipt||{};
+  return body.state==='uninstalled'&&body.installId===installId&&
+    typeof body.operationId==='string'&&body.operationId===payload?.operationId&&
+    integrity?.algorithm==='hmac-sha256'&&/^[a-f0-9]{64}$/.test(integrity.hash||'')&&
+    isDeepStrictEqual(body,payload);
+}
+
+// Only coordinates the installed exact-plan API. Every mutation waits for its
+// own manager confirmation. Even the first update uses the OLD stable launcher.
+export async function followMaintenance({operation,kind,candidate,env,onChange}) {
+  if(!['update','uninstall'].includes(kind))throw Error('维护类型无效');
+  const client=installedClient(operation.installationRoot,env),{root,call}=client;
+  const before=call(['manager','inspect','--root',root]),current=before.installation?.current;
+  if(!current?.identity?.installId||before.bridge?.currentVersion!==current.version)throw Error('当前安装无法核实');
+  if(kind==='update'&&(!candidate||candidate.version===current.version))throw Error('目标版本无效或已经安装；不重复更新或解除 Skill');
+  const manifest=plainPath(path.join(root,current.appPath,'artifacts/skills/ai-product-foundation-kit/capability.json'));
+  if(!manifest.startsWith(root+path.sep))throw Error('当前材料路径越界');
+  // On 0.2.10 inspect has no codexSkill field. File presence only requests an
+  // ownership-checked plan; the old engine validates its signed receipt/files.
+  const registration=plainPath(path.join(root,'state/codex-skill-registration.json'));
+  const hadSkill=fs.existsSync(registration);
+  let previousPlanRef=null;
+  const steps={};
+  onChange({kind,currentVersion:current.version,installId:current.identity.installId,previousCandidateHash:current.candidateHash,journeyContext:{id:operation.operationId,skillChoice:kind==='update'&&hadSkill?'selected':'skipped'},next:hadSkill?(kind==='update'?'先确认程序更新，再确认刷新完整归属的 Codex 文件；未知或修改文件保留。':'先核对并确认解除已关联的 Codex 副本，再继续程序卸载；未知或修改文件保留。'):'核对程序操作；本次不会新增 Codex Skill。'});
+  const run=async(key,op,parameters)=>{
+    const now=call(['manager','inspect','--root',root]).installation?.current;
+    if(now?.identity?.installId!==current.identity.installId||now.candidateHash!==current.candidateHash)throw Error('维护期间安装身份变化，停止接续');
+    const requested=call(['manager','request-plan','--operation',op,'--parameters-json',JSON.stringify(parameters),...(previousPlanRef?['--previous-plan-ref',previousPlanRef]:[])]);
+    steps[key]={state:'pending',evidence:{planRef:requested.planRef}};
+    onChange({phase:key==='program'?'awaiting-confirmation':'skill-confirmation',currentPlanRef:requested.planRef,maintenanceSteps:{...steps},terminal:false});
+const event=await observePlan(client,requested,observation=>onChange({phase:observation.state==='pending'?(key==='program'?'awaiting-confirmation':'skill-confirmation'):(key==='program'?'executing':'skill-executing'),...(observation.state!=='pending'?{installationWrites:'possible'}:{}),...(observation.temporaryManager?{temporaryManager:observation.temporaryManager}:{}),...(observation.confirmationUrl?{confirmationUrl:observation.confirmationUrl}:{}),maintenanceSteps:{...steps,[key]:{state:observation.state,evidence:{planRef:requested.planRef,sessionId:observation.sessionId}}}}));
+    // Uninstall removes the executable, but its result and external receipt are
+    // emitted by the already-running manager. Other steps are reread normally.
+    const result=kind==='uninstall'&&key==='program'?event:call(['manager','status','--plan-ref',requested.planRef]);
+    if(result.sessionId!==event.sessionId||result.state!==event.state)throw Error('维护结果与会话不一致');
+    steps[key]={state:result.state,evidence:{planRef:requested.planRef,sessionId:result.sessionId,recordLocation:result.recordLocation},result:result.result};
+    previousPlanRef=requested.planRef;
+    onChange({maintenanceSteps:{...steps},previousPlanRef});
+    return result;
+  };
+  if(hadSkill&&kind==='uninstall'){
+    const removed=await run('remove','capability-uninstall',{installationRoot:root,manifestFile:manifest});
+    if(removed.state!=='completed')return {state:'partial',terminal:true,phase:'finished',programState:'not-started',next:'Codex 解除未完成，程序未更新或卸载；保留原入口和文件。'};
+    if(fs.existsSync(registration))throw Error('解除后归属记录仍存在，不继续程序操作');
+  }
+  const parameters={targetRoot:root,currentVersion:current.version,targetVersion:kind==='update'?candidate?.version:current.version};
+  if(kind==='uninstall')parameters.mode='full'; // Owned program/runtime/state only; user data remains protected by the exact plan.
+  if(kind==='update'){
+    if(!candidate||candidate.version===current.version)throw Error('目标版本无效或已经安装；不重复更新');
+    parameters.candidate=candidate;
+    if(before.supportedLifecycleOptions?.update?.includes('cleanupAcquisition'))parameters.cleanupAcquisition=true;
+  }
+  const result=await run('program',kind,parameters);
+  const payload=result.result?.lifecycleResult||result.result||{};
+  onChange({programState:result.state,sessionId:result.sessionId,runtimeHealth:payload.stableLauncherHealth||'unknown',programResult:payload,phase:'runtime-ended'});
+  if(result.state!=='completed')return {state:'partial',terminal:true,phase:'finished',next:'程序操作未完成；保留结果和恢复记录，不自动补做。先核验程序与 Codex 各自状态。'};
+  if(kind==='uninstall'){
+    const file=plainPath(path.join(root,'uninstall-result.json')),receipt=JSON.parse(fs.readFileSync(file));
+    if(!matchesUninstallResult(receipt,payload,current.identity.installId))throw Error('卸载独立回执与本次已安装引擎结果不一致');
+    return {state:'completed',terminal:true,phase:'finished',skillRegistered:false,uninstallReceipt:file,next:'卸载完成；保留项目资料、用户修改文件及卸载回执。缓存清理说明见独立回执，不自动清理其他缓存。'};
+  }
+  const after=call(['manager','inspect','--root',root]).installation?.current;
+  if(after?.identity?.installId!==current.identity.installId||after.version!==candidate.version||after.candidateHash!==candidate.manifestHash||payload.stableLauncherHealth!=='passed')throw Error('更新后的稳定入口身份或健康待核实');
+  if(hadSkill)return followSelectedSkill({operation:{...operation,kind:'update',installationRoot:root,programState:'completed',sessionId:null,previousPlanRef,journeyContext:{id:operation.operationId,skillChoice:'selected'}},env,onChange});
+  return {state:'completed',terminal:true,phase:'finished',skillRegistered:false,next:'更新及稳定入口健康核验完成；未新增 Skill，项目与用户数据按计划保留。'};
+}

package/lib/manager-step.mjs

@@ -0,0 +1,62 @@
+import {spawn,spawnSync} from 'node:child_process';
+import path from 'node:path';
+import {plainPath} from './acquire.mjs';
+
+// A client of the existing installed manager, never a confirmation authority.
+export function installedClient(root,env) {
+  root=plainPath(root);
+  const launcher=plainPath(path.join(root,'bin/foundation-kit'));
+  const call=args=>{
+    const r=spawnSync(launcher,args,{env,encoding:'utf8',timeout:30000,maxBuffer:4*1024*1024});
+    if(r.status!==0){const e=Error('已安装入口检查失败；保留已核实结果，不自动重放');e.code='INSTALLED_COMMAND_FAILED';e.command=args.slice(0,2);e.exitCode=r.status;throw e;}
+    return JSON.parse(r.stdout);
+  };
+  return {root,launcher,call,env};
+}
+
+export async function observePlan(client,requested,onChange) {
+  if(!/^foundation-plan-[a-f0-9]{64}$/.test(requested.planRef))throw Error('计划标识无效');
+  const child=spawn(client.launcher,['manager','open-manager','--plan-ref',requested.planRef],{env:client.env,stdio:['ignore','pipe','pipe']});
+  let pending='',json='',finished=false;
+  return new Promise((resolve,reject)=>{
+    const stop=()=>child.kill('SIGTERM');
+    const finish=(error,value)=>{if(finished)return;finished=true;clearTimeout(timer);process.off('SIGINT',stop);process.off('SIGTERM',stop);
+      if(error||value?.responseFinished===true)child.kill('SIGTERM');
+      else { // Older managers report results before HTTP flush. Leave their
+        // existing bounded page lifetime intact rather than aborting the reply.
+        child.stdout.destroy();child.stderr.destroy();child.unref();
+        onChange({state:value.state,temporaryManager:{pid:child.pid,expiresAt:requested.expiresAt,reason:'old-manager-response-flush-unavailable'}});
+      }
+      error?reject(error):resolve(value);
+    };
+    const timer=setTimeout(()=>finish(Error('确认等待到期；保留同次计划记录')),Math.max(1,Math.min(16*60*1000,requested.expiresAt-Date.now()+1000)));
+    process.once('SIGINT',stop);process.once('SIGTERM',stop);
+    child.once('error',e=>finish(e));
+    child.once('close',()=>{if(!finished)finish(Error('页面进程退出，结果待核实；不自动重放'));});
+    child.stderr.on('data',()=>{});
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data',chunk=>{
+      pending+=chunk;
+      if(pending.length+json.length>4*1024*1024)return finish(Error('状态输出超过限制'));
+      let end;
+      while((end=pending.indexOf('\n'))>=0){
+        const line=pending.slice(0,end);pending=pending.slice(end+1);
+        if(!json&&!line.trim().startsWith('{'))continue;
+        json+=line+'\n';let event;try{event=JSON.parse(json);}catch{continue;}json='';
+        if(event.planRef!==requested.planRef)continue;
+        if(event.status==='AWAITING_FOUNDATION_UI_CONFIRMATION'){
+          const url=new URL(event.url);if(url.protocol!=='http:'||url.hostname!=='127.0.0.1'||url.username||url.password)return finish(Error('确认网址无效'));
+          onChange({state:'pending',confirmationUrl:url.href,sessionId:event.sessionId});
+        }
+        if(event.status==='FOUNDATION_OPERATION_STATE')onChange({state:event.state,sessionId:event.sessionId});
+        if(event.status==='FOUNDATION_OPERATION_RESULT'){
+          // The result comes from this exact installed process/session. Uninstall
+          // may already have removed the launcher, so its external manager receipt
+          // must remain the durable recovery source; do not execute deleted code.
+          if(!event.sessionId)return finish(Error('操作结果缺少会话身份'));
+          finish(null,event);
+        }
+      }
+    });
+  });
+}

package/lib/operation-result.mjs

@@ -7,12 +7,15 @@ export function createOperation() {
 }
 // Observations from the verified runtime, never confirmation or execution authority.
 export function runtimeObservation(event) {
-  if(event.status==='AWAITING_FOUNDATION_DIRECTORY_SELECTION')return {phase:'selecting-directory',selectionId:event.selectionId,installationWrites:'none'};
-  if(['FOUNDATION_SELECTION_BOUND','AWAITING_FOUNDATION_UI_CONFIRMATION'].includes(event.status))return {phase:'awaiting-confirmation',sessionId:event.sessionId,planHash:event.planHash,installationWrites:'none'};
+  let confirmationUrl;
+  if(event.url){const url=new URL(event.url);if(url.protocol==='http:'&&url.hostname==='127.0.0.1'&&!url.username&&!url.password)confirmationUrl=url.href;}
+  if(event.status==='AWAITING_FOUNDATION_DIRECTORY_SELECTION')return {phase:'selecting-directory',selectionId:event.selectionId,journeyContext:event.journeyContext,installationWrites:'none',...(confirmationUrl?{confirmationUrl}:{})};
+  if(['FOUNDATION_SELECTION_BOUND','AWAITING_FOUNDATION_UI_CONFIRMATION'].includes(event.status))return {phase:'awaiting-confirmation',...(event.journeyContext?{journeyContext:event.journeyContext}:{}),sessionId:event.sessionId,planHash:event.planHash,installationWrites:'none',...(confirmationUrl?{confirmationUrl}:{})};
   if(event.status==='FOUNDATION_OPERATION_STATE'&&['executing','consumed'].includes(event.state))return {phase:'executing',sessionId:event.sessionId,installationWrites:'possible'};
   if(event.status==='BOOTSTRAP_OPERATION_ENDED'){
     const state=['completed','failed','cancelled','expired'].includes(event.state)?event.state:'verification-required';
-    return {phase:'runtime-ended',state,terminal:state!=='verification-required',sessionId:event.sessionId,installationRoot:event.installationRoot,installationWrites:state==='completed'?'runtime-reported-installed':'unknown',runtimeHealth:event.result?.executableHealth||'unknown',next:'只读核验稳定 installed launcher 或同次 session 结果，不重放确认'};
+    const selectedPending=state==='completed'&&event.journeyContext?.skillChoice==='selected';
+    return {phase:'runtime-ended',programState:state,state:selectedPending?'awaiting-skill':state,terminal:state!=='verification-required'&&!selectedPending,sessionId:event.sessionId,installationRoot:event.installationRoot,installationWrites:state==='completed'?'runtime-reported-installed':'unknown',runtimeHealth:event.result?.stableLauncherHealth||event.result?.lifecycleResult?.stableLauncherHealth||event.result?.executableHealth||'unknown',journeyContext:event.journeyContext,next:selectedPending?'程序已完成，正在准备所选 Codex 接入的独立确认':'只读核验稳定 installed launcher 或同次 session 结果，不重放确认'};
   }
   if(['cancelled-no-install','expired-no-install','shutdown-no-install'].includes(event.state))return {phase:'directory-selection-ended',state:event.state,terminal:true,installationWrites:'none'};
   return null;

package/lib/progress-page.mjs

@@ -0,0 +1,57 @@
+import http from 'node:http';
+import crypto from 'node:crypto';
+import {journeyView} from './journey-view.mjs';
+
+export function downloadText(download) {
+  if(!download||!Number.isFinite(download.downloadedBytes)||download.downloadedBytes<0)return '';
+  const amount=n=>(n/1048576).toFixed(2)+' MiB';
+  const known=Number.isFinite(download.totalBytes)&&download.totalBytes>0;
+  return '已接收 '+amount(download.downloadedBytes)+(known?' / '+amount(download.totalBytes)+(download.downloadedBytes<=download.totalBytes?' · '+Math.floor(download.downloadedBytes/download.totalBytes*100)+'%':'（长度待核实）'):'（总量未知）');
+}
+
+export function acquisitionProgress(record) {
+  const phases={discovering:'查询正式发行','verifying-trust':'核验发行来源','fetching-and-verifying-catalog':'获取并核验发行清单','fetching-and-verifying-runtime':'下载并核验运行文件','extracting-and-validating':'展开并检查文件','acquired':'获取验证完成','starting-confirmation-service':'准备目录选择与确认页','selecting-directory':'等待你选择目录','awaiting-confirmation':'等待你确认安装',executing:'正在安装','runtime-ended':'读取安装结果',finished:'安装结果已返回'};
+  const terminal=record.terminal;
+  const acquired=['acquired','starting-confirmation-service','selecting-directory','directory-selection-ended','awaiting-confirmation','executing','runtime-ended','finished'].includes(record.phase);
+  const observations={acquire:{state:acquired?'completed':terminal?'failed':'running',evidence:record.resultFile}};
+  if(record.phase==='selecting-directory')observations.select={state:'pending'};
+  if(record.phase==='directory-selection-ended')observations.select={state:record.state==='cancelled-no-install'?'cancelled':record.state==='expired-no-install'?'expired':'verification-required',evidence:record.selectionId};
+  if(['awaiting-confirmation','executing','runtime-ended','finished'].includes(record.phase))observations.select={state:'completed',evidence:record.selectionId};
+  if(record.phase==='awaiting-confirmation')observations.program={state:'pending',evidence:record.sessionId};
+  if(record.phase==='executing')observations.program={state:'running',evidence:record.sessionId};
+  if(['runtime-ended','finished'].includes(record.phase))observations.program={state:record.programState||record.state,evidence:record.sessionId};
+  if(record.runtimeHealth==='passed')observations.health={state:'completed',evidence:record.sessionId};
+  if(record.programState==='completed'){
+    observations.acquire={state:'completed',evidence:record.resultFile};
+    observations.select={state:'completed',evidence:record.selectionId};
+    observations.program={state:'completed',evidence:record.sessionId};
+  }
+  for(const key of ['material','register'])if(record.skillSteps?.[key])observations[key]=record.skillSteps[key];
+  for(const key of ['remove','program'])if(record.maintenanceSteps?.[key])observations[key]=record.maintenanceSteps[key];
+  const kind=record.kind||'install';
+  const journey=journeyView({id:record.operationId,kind,includeAcquisition:kind!=='uninstall',includeSelection:kind==='install',includeHealth:kind!=='uninstall',includeSkillRemoval:Boolean(observations.remove),observations,skillChoice:record.journeyContext?.skillChoice||'undecided'});
+  if(record.terminal&&record.state==='partial'){journey.ended=false;journey.title=record.programState==='completed'?'程序已完成，Codex 接入未完成':'本次操作尚未全部完成';journey.summary=record.next;}
+  const verb=kind==='uninstall'?'卸载':kind==='update'?'更新':'安装';
+  Object.assign(phases,{'awaiting-confirmation':'等待你确认'+verb,executing:'正在'+verb,'runtime-ended':'读取'+verb+'结果',finished:verb+'结果已返回'});
+  if(record.terminal&&record.state==='partial'&&record.programState==='completed'&&kind==='update')journey.title='程序已更新，Skill 尚未更新';
+  return {journey,operationId:record.operationId,title:journey.title,phase:({'skill-confirmation':'等待你确认 Codex 操作','skill-executing':'正在处理 Codex 对话能力'})[record.phase]||phases[record.phase]||'正在核实本次操作',state:record.state,version:record.currentVersion&&kind==='update'?record.currentVersion+' → '+record.version:record.version||record.currentVersion||null,download:record.download||null,program:record.programState==='completed'?'程序'+verb+'已完成；'+(kind==='uninstall'?'结果由独立回执保留':record.runtimeHealth==='passed'?'稳定入口健康已核验':'健康待核实'):record.installationWrites==='none'?'尚未执行程序操作':'程序结果以同次记录为准',skill:kind==='uninstall'?(observations.remove?.state==='completed'?'已解除已归属 Codex 注册；修改和未知文件按计划保留':'本次没有已核实的注册移除结果'):record.skillRegistered===true?'Skill 文件与归属已核验；新对话识别另验':record.journeyContext?.skillChoice==='skipped'?'本次不接入 Codex':record.journeyContext?.skillChoice==='selected'?'已选择接入 Codex；仅在分别确认后执行':'Codex 接入可选，尚未选择',project:'未自动接入项目',installationRoot:record.installationRoot||null,skillDestination:record.skillDestination||null,next:record.next||(record.terminal&&record.state==='completed'&&record.journeyContext?.skillChoice==='skipped'?'本次已跳过 Codex 接入；程序操作已完成，项目另行确认。':journey.summary),nextUrl:record.terminal?(kind!=='uninstall'&&record.workbench?.state==='ready'?record.workbench.url:null):record.confirmationUrl||null,nextLabel:record.terminal?'打开已安装工作台':record.phase?.startsWith('skill-')?'查看 Codex 精确确认':kind==='install'?'继续到目录选择 / 本人确认页':'查看'+verb+'确认',resultFile:record.resultFile||null,terminal,diagnostic:record.diagnostic||null};
+}
+
+// A bounded, read-only loopback view over the existing in-memory operation.
+// No POST, launch endpoint, confirmation authority or downloaded executable.
+export async function startProgressPage(readRecord) {
+  const token=crypto.randomBytes(24).toString('hex'),base=`/${token}`,clients=new Set();
+  const html=`<!doctype html><html lang="zh-CN"><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>Foundation 获取与安装进度</title><style>body{font:16px/1.6 system-ui;max-width:760px;margin:24px auto;padding:0 20px;color:#18181b;background:#fafafa;overflow-wrap:anywhere}section{background:white;border:1px solid #e4e4e7;border-radius:12px;padding:16px;margin:16px 0}h1{font-size:24px}h2{font-size:18px}a{display:inline-block;padding:12px;border:1px solid #71717a;border-radius:8px;color:inherit}pre{white-space:pre-wrap}a:focus-visible,summary:focus-visible{outline:3px solid #2563eb}[hidden]{display:none}.steps{display:flex;flex-wrap:wrap;gap:8px}.steps p{margin:0;background:#f4f4f5;padding:6px 10px;border-radius:6px;font-size:13px}header{font-size:14px;font-weight:600}#continue{background:#18181b;color:white;font-weight:600;text-decoration:none}#target{overflow-wrap:anywhere}@media(max-width:480px){body{padding:0 16px}.steps p{flex:1 1 110px}}</style><body><header>Foundation</header><h1>正在准备 Foundation</h1><section role="status" aria-live="polite"><h2 id="phase">正在读取同次操作</h2><div id="journey-steps" class="steps"></div><p id="journey-summary"></p><p id="version"></p><p id="download"></p><p id="target"></p><p id="program"></p><p id="skill"></p><p id="project"></p><p id="next"></p><a id="continue" hidden>继续到目录选择 / 本人确认页</a><p id="connection"></p></section><p>此页面只读，不批准安装；程序、对话能力与项目分别确认。未知长度不显示百分比。临时服务结束后，可从原对话读取保留的操作结果。</p><details><summary>操作与恢复详情</summary><pre id="raw"></pre></details><script>const downloadText=${downloadText.toString()};let last=null;function show(p){last=p;document.querySelector('h1').textContent=p.journey.title;document.getElementById('journey-summary').textContent=p.journey.summary;const steps=document.getElementById('journey-steps');steps.replaceChildren();for(const step of p.journey.steps){const line=document.createElement('p');line.textContent=step.title+'：'+step.label;steps.append(line);}for(const key of ['phase','program','skill','project','next'])document.getElementById(key).textContent=p[key]||'';document.getElementById('download').textContent=downloadText(p.download);document.getElementById('version').textContent=p.version?'版本：'+p.version:'';document.getElementById('target').textContent=p.installationRoot?'程序目录：'+p.installationRoot:'';const link=document.getElementById('continue');link.hidden=!p.nextUrl;link.textContent=p.nextLabel;if(p.nextUrl)link.href=p.nextUrl;document.getElementById('raw').textContent=JSON.stringify(p,null,2);}const events=new EventSource(location.pathname+'/events');events.onmessage=e=>show(JSON.parse(e.data));events.onerror=()=>{events.close();document.getElementById('connection').textContent=last&&last.terminal?'临时进度服务已结束，上方保留最后收到的结果。':'连接已中断，当前状态待核实；不自动重试安装。'};window.addEventListener('pagehide',()=>events.close(),{once:true});</script></body></html>`;
+  let origin;
+  const current=()=>JSON.stringify(acquisitionProgress(readRecord()));
+  const server=http.createServer((req,res)=>{
+    if(req.method!=='GET'||req.headers.host!==origin||req.headers.origin&&req.headers.origin!==`http://${origin}`){res.writeHead(403).end();return;}
+    const headers={'cache-control':'no-store','x-content-type-options':'nosniff','content-security-policy':"default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"};
+    if(req.url===base){res.writeHead(200,{...headers,'content-type':'text/html; charset=utf-8'}).end(html);}
+    else if(req.url===base+'/events'){res.writeHead(200,{...headers,'content-type':'text/event-stream'});res.write(`data: ${current()}\n\n`);clients.add(res);req.on('close',()=>clients.delete(res));}
+    else{res.writeHead(404).end();}
+  });
+  await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',resolve);});
+  origin=`127.0.0.1:${server.address().port}`;
+  return {url:`http://${origin}${base}`,publish(){for(const res of clients)res.write(`data: ${current()}\n\n`);},close(){for(const res of clients)res.end();clients.clear();return new Promise(resolve=>server.close(resolve));}};
+}

package/lib/resume-handoff.mjs

@@ -0,0 +1,24 @@
+import {readOperation} from './operation-result.mjs';
+import {installedClient} from './manager-step.mjs';
+import {followSelectedSkill} from './skill-handoff.mjs';
+
+// Explicit user-requested recovery, never an automatic replay of approval.
+export async function resumeSkillHandoff({file,env,onChange}) {
+  const previous=readOperation(file);
+  if(previous.pid&&previous.pid!==process.pid){
+    try{process.kill(previous.pid,0);throw Error('原进程仍存在，先在原任务查询；不并发恢复');}
+    catch(e){if(e.code!=='ESRCH')throw e;}
+  }
+  if(previous.programState!=='completed'||previous.journeyContext?.skillChoice!=='selected'||!previous.installationRoot)throw Error('该记录不是程序完成后的 Skill 待续；先只读核实原操作，不重跑程序');
+  const client=installedClient(previous.installationRoot,env),current=client.call(['manager','inspect','--root',previous.installationRoot]).installation?.current;
+  if(!previous.installId||current?.identity?.installId!==previous.installId||previous.installedCandidateHash&&current.candidateHash!==previous.installedCandidateHash)throw Error('恢复记录与当前安装不一致；需重新核实');
+  if(previous.currentPlanRef){
+    const status=client.call(['manager','status','--plan-ref',previous.currentPlanRef]);
+    if(['executing','consumed'].includes(status.state))throw Error('旧计划仅有执行中记录；先核实或按原恢复机制处理，不能自动重试');
+    // Completed material is reused by capability status. Cancelled/expired
+    // confirmation is not reused: followSelectedSkill requests a fresh plan.
+  }
+  const operation={...previous,pid:process.pid,state:'awaiting-skill',terminal:false};
+  onChange(operation);
+  return followSelectedSkill({operation,env,onChange});
+}

package/lib/skill-handoff.mjs

@@ -0,0 +1,53 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import {installedClient,observePlan} from './manager-step.mjs';
+import {plainPath} from './acquire.mjs';
+
+// Coordinates existing exact-plan APIs. It never sends a confirmation request.
+// The installed launcher resolves current on every call; downloaded code is not
+// reused as installed authority. onChange is observation, not authorization.
+export async function followSelectedSkill({operation,env,onChange}) {
+  if(operation.programState!=='completed'||operation.journeyContext?.skillChoice!=='selected')throw Error('Skill 接续需要已完成程序和明确所选意向');
+  const client=installedClient(operation.installationRoot,env),{root,call}=client;
+  const initial=call(['manager','inspect','--root',root]);
+  const identity=initial.installation?.current;
+  if(!identity?.identity?.installId||initial.bridge?.currentVersion!==identity.version)throw Error('当前安装身份无法核实，停止 Skill 接续');
+  if(operation.installId&&operation.installId!==identity.identity.installId)throw Error('恢复记录属于另一安装，停止接续');
+  onChange({installId:identity.identity.installId,installedCandidateHash:identity.candidateHash});
+  const manifestFile=plainPath(path.join(root,identity.appPath,'artifacts/skills/ai-product-foundation-kit/capability.json'));
+  if(!manifestFile.startsWith(root+path.sep))throw Error('Skill 材料必须属于当前安装');
+  if(initial.codexSkill?.state==='files-installed-host-discovery-unverified'){
+    const destination=plainPath(initial.codexSkill.destination);
+    const binding=JSON.parse(fs.readFileSync(plainPath(path.join(destination,'foundation-installation.json'))));
+    if(binding.installId===identity.identity.installId&&binding.installationRoot===root&&fs.readFileSync(plainPath(path.join(destination,'SKILL.md'))).equals(fs.readFileSync(path.join(path.dirname(manifestFile),'SKILL.md'))))return {state:'completed',terminal:true,phase:'finished',skillRegistered:true,skillDestination:destination,hostDiscoveryVerified:false,skillSteps:{material:{state:'completed',evidence:{source:'installed-owned-current-bytes'}},register:{state:'completed',evidence:{source:'installed-owned-current-bytes'}}},next:'当前版本 Skill 文件和归属已核实，无需重复注册；新任务识别另验。'};
+  }
+  const checkIdentity=()=>{
+    const current=call(['manager','inspect','--root',root]);
+    if(current.installation?.current?.identity?.installId!==identity.identity.installId||current.installation.current.candidateHash!==identity.candidateHash)throw Error('接续期间安装发生变化，需重新核实');
+    return current;
+  };
+  let previousPlanRef=operation.previousPlanRef||null;
+  const steps={};
+  const material=call(['capability','status','--root',root,'--manifest',manifestFile]);
+  const reusable=['CAPABILITY_NOT_REGISTERED','CAPABILITY_INACTIVE','PROJECT_NOT_ENABLED','CAPABILITY_READY'].includes(material.code);
+  const ownedUpdate=operation.kind==='update'&&initial.codexSkill?.state==='files-installed-host-discovery-unverified'&&material.code==='CAPABILITY_IDENTITY_MISMATCH';
+  if(!reusable&&material.code!=='CAPABILITY_NOT_INSTALLED'&&!ownedUpdate)throw Error('已有 Skill 材料不兼容或归属待核实；不自动覆盖');
+  if(reusable)steps.material={state:'completed',evidence:{source:'installed-capability-status',code:material.code}};
+  for(const kind of [...(!reusable?['material']:[]),'register']) {
+    checkIdentity();
+    const requested=call(['manager','request-plan','--operation',kind==='material'?'capability-install':'capability-register','--parameters-json',JSON.stringify({installationRoot:root,manifestFile,...(kind==='register'?{connectCodex:true}:{})}),...(previousPlanRef?['--previous-plan-ref',previousPlanRef]:operation.sessionId?['--previous-session-id',operation.sessionId]:[])]);
+    if(!/^foundation-plan-[a-f0-9]{64}$/.test(requested.planRef))throw Error('接续计划标识无效');
+    steps[kind]={state:'pending',evidence:{planRef:requested.planRef}};
+    onChange({state:'awaiting-skill',phase:'skill-confirmation',terminal:false,skillSteps:{...steps},currentPlanRef:requested.planRef,next:kind==='material'?'确认准备对话能力材料；随后继续注册确认':'确认将 Foundation Skill 接入 Codex'});
+const event=await observePlan(client,requested,observation=>onChange({phase:observation.state==='pending'?'skill-confirmation':'skill-executing',...(observation.temporaryManager?{temporaryManager:observation.temporaryManager}:{}),...(observation.confirmationUrl?{confirmationUrl:observation.confirmationUrl}:{}),skillSteps:{...steps,[kind]:{state:observation.state,evidence:{planRef:requested.planRef,sessionId:observation.sessionId}}}}));
+    const result=call(['manager','status','--plan-ref',requested.planRef]);
+    if(result.sessionId!==event.sessionId||result.state!==event.state)throw Error('Skill 记录与事件不一致');
+    steps[kind]={state:result.state,evidence:{planRef:requested.planRef,sessionId:result.sessionId,recordLocation:result.recordLocation}};
+    onChange({skillSteps:{...steps}});
+    if(result.state!=='completed')return {state:'partial',phase:'finished',terminal:true,skillRegistered:false,skillSteps:steps,next:'程序已安装；本次 Skill 未完成。保留同次计划结果，需要时仅继续未完成步骤。'};
+    previousPlanRef=requested.planRef;
+  }
+  const verified=checkIdentity().codexSkill;
+  if(verified?.state!=='files-installed-host-discovery-unverified')throw Error('Skill 注册文件与归属未通过核验；程序成功保留');
+  return {state:'completed',phase:'finished',terminal:true,skillRegistered:true,skillDestination:verified.destination,skillSteps:steps,hostDiscoveryVerified:false,next:'程序与所选 Skill 文件已就位；新开 Codex 对话验证识别，项目接入另行确认。'};
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@josephyulei/summon-foundation",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@josephyulei/summon-foundation",
-      "version": "0.1.3",
+      "version": "0.1.5",
       "license": "MIT",
       "dependencies": {
         "@sigstore/bundle": "4.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyulei/summon-foundation",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Prepare a verified Foundation release for an explicitly confirmed Codex installation",
   "type": "module",
   "bin": {"summon": "bin/summon.mjs"},