@hanamesh/dsh-app-host 0.2.0-rc.2 → 0.6.12

package/dist/library/install.js

@@ -1,17 +1,21 @@
 import { readFile, lstat, unlink, rmdir } from 'node:fs/promises';
-import { join, resolve, dirname, sep } from 'node:path';
-import { spawn as nodeSpawn } from 'node:child_process';
-import { AppHostError, requireCondition } from '../errors.js';
+import { join, resolve, dirname, sep, delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {safeGitEnv,guardNodeBinary,spawnGitSafe} from '../git-process.js';
+import { randomUUID } from 'node:crypto';
+import { AppHostError, requireCondition, SerialQueue } from '../errors.js';
 import { validateDefinition } from '../descriptor.js';
 import { itemKind } from './catalog.js';
+import { profileSnapshot, runtimeSnapshot, profileChecks, runtimeChecks, packageRestoreArgs, keepOriginals } from './recovery.js';
+import {prepareSuiteUpgrade,readSuiteStatus,createCoreSuiteAdapter,SUITE_INSTALL_COMMAND} from './suite.js';
 
 /** The HanaMesh suite itself (real names + the historical scoped spellings) is never installed or removed through the market. */
-export const PROTECTED_PACKAGES=Object.freeze(['@hanamesh/dsh-app-host','hanamesh-core','hanamesh-usage','@hanamesh/dsh-core','@hanamesh/dsh-usage']);
+export const PROTECTED_PACKAGES=Object.freeze(['@hanamesh/dsh-app-host','hanamesh-core','hanamesh-usage','hanamesh-brand','@hanamesh/dsh-core','@hanamesh/dsh-usage']);
 const blocked=new Set(PROTECTED_PACKAGES);
 const packageName=value=>typeof value==='string'&&/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
 const versionText=value=>typeof value==='string'&&/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(value);
 async function json(path){return JSON.parse(await readFile(path,'utf8'));}
-function defaultSpawn(command,args,options){return new Promise((resolvePromise,reject)=>{const child=nodeSpawn(command,args,{...options,env:{HOME:process.env.HOME,DSH_HOME:process.env.DSH_HOME,LANG:process.env.LANG??'C.UTF-8',PATH:`${command.slice(0,command.lastIndexOf('/'))}:/usr/bin:/bin`},stdio:['ignore','pipe','pipe']});let stdout='',stderr='';child.stdout.on('data',chunk=>stdout+=chunk);child.stderr.on('data',chunk=>stderr+=chunk);child.on('error',reject);child.on('exit',(code,signal)=>resolvePromise({code,signal,stdout,stderr}));});}
+const defaultSpawn=spawnGitSafe;
 
 async function defaults(){return await import('../provision/index.js');}
 
@@ -37,17 +41,32 @@ async function clearGeneratedRuntimeCache(result,runtimeRoot){
   requireCondition(remaining.length===0&&residue===null,'RUNTIME_RESIDUE','Runtime has unowned files that require manual review.',{count:remaining.length},409);
 }
 
-export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBinary,dshBin,registry='https://registry.npmjs.org',allowPrerelease=false,
-  fetchImpl=globalThis.fetch,spawn=defaultSpawn,provision,remove,emit=()=>{}}){
+/** Package mutations use the public CLI in an owned monitored process; upstream's in-process manager has no scoped env/monitor port. */
+export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBinary,dshBin,desktopCli,desktopLauncher,pluginManagerVersion,registry='https://registry.npmjs.org',allowPrerelease=false,
+  fetchImpl=globalThis.fetch,spawn=defaultSpawn,provision,remove,ledger,coreSuitePlan,coreService=()=>undefined,suiteSourceMode=()=>'configured',suiteSourceService=()=>undefined,pluginManager=()=>undefined,emit=()=>{},profileWriter=new SerialQueue()}){
   requireCondition(typeof profileDir==='string'&&resolve(profileDir)===profileDir,'PROFILE_DIR_REQUIRED','library.profileDir must be an absolute path.');
   requireCondition(typeof dataRoot==='string'&&resolve(dataRoot)===dataRoot,'INVALID_ROOT','dataRoot must be absolute.');
-  requireCondition(typeof nodeBinary==='string'&&resolve(nodeBinary)===nodeBinary,'NODE_RUNTIME_REQUIRED','An absolute nodeBinary is required for library operations.');
-  requireCondition(typeof dshBin==='string'&&resolve(dshBin)===dshBin,'DSH_BIN_REQUIRED','An absolute DSH bin.js path is required.');
+  const launcherAvailable=typeof desktopLauncher?.command==='string'&&resolve(desktopLauncher.command)===desktopLauncher.command&&typeof desktopLauncher.home==='string'&&join(desktopLauncher.home,'profiles',profileName)===profileDir;
+  const supervisorNode=guardNodeBinary({workerNode:nodeBinary});
+  const cliAvailable=Boolean(supervisorNode)&&(launcherAvailable||(typeof nodeBinary==='string'&&resolve(nodeBinary)===nodeBinary&&typeof dshBin==='string'&&resolve(dshBin)===dshBin));
+  requireCondition(nodeBinary===undefined||(typeof nodeBinary==='string'&&resolve(nodeBinary)===nodeBinary),'NODE_RUNTIME_REQUIRED','nodeBinary must be an absolute path.');
+  requireCondition(dshBin===undefined||(typeof dshBin==='string'&&resolve(dshBin)===dshBin),'DSH_BIN_REQUIRED','dshBin must be an absolute DSH bin.js path.');
   requireCondition(typeof profileName==='string'&&/^[A-Za-z0-9_.-]+$/.test(profileName),'PROFILE_NAME_REQUIRED','library.profileName is required.');
+  const unavailable=()=>!supervisorNode?[{need:'找不到能运行安装监测的独立 Node，不能用 Electron 宿主代替',how:'在 AppHost 插件配置中，将 nodeBinary 填为独立 Node.js 24 的绝对路径（24.13.1 或更新的 24.x）；完全退出后重开。Electron 的 Node 包装脚本不能代替独立 Node。'}]:cliAvailable?[]:[{need:'缺少能固定精确版本、隔离 Git 凭据并监测钥匙串调用的公开 DSH 命令行',how:'恢复客户端随附的公开 dsh 命令启动器后重试。'}];
   const runtimeRoot=appId=>join(dataRoot,'runtimes',appId);
   const permitted=name=>requireCondition(packageName(name)&&!blocked.has(name),'PACKAGE_DENIED','Package name is not permitted.',{packageName:name});
+  /** rc.10: one profile writer at a time inside this host; `dsh plugin` itself serialises against other writers per command. */
+  requireCondition(profileWriter&&typeof profileWriter.run==='function','INVALID_PROFILE_WRITER','A shared profile writer queue is required.');
+  const injected={provision,remove,ledger};
+  /** Injected runtime functions (tests, suites) or the vendored lib-provision export of the same name. */
+  const runtimeApi=async name=>injected[name]??(await defaults())[name];
   async function installed(packageNameValue){const root=join(profileDir,'node_modules',...packageNameValue.split('/')),pkg=await json(join(root,'package.json'));const appFile=typeof pkg.hanamesh?.app==='string'?pkg.hanamesh.app:'app.json';return{pkg,definition:validateDefinition(await json(join(root,appFile)))};}
-  async function run(args){const result=await spawn(nodeBinary,[dshBin,'plugin','--profile',profileName,...args],{cwd:profileDir});requireCondition(result.code===0,'DSH_PLUGIN_FAILED','DSH plugin operation failed.',{code:result.code,signal:result.signal,stderr:String(result.stderr??'').slice(-2000)},502);return result;}
+  const commandPath=command=>[dirname(command),...(process.platform==='win32'?(process.env.PATH??process.env.Path??'').split(delimiter):['/opt/homebrew/bin','/usr/local/bin','/usr/bin','/bin'])].join(delimiter);
+  async function run(args){requireCondition(cliAvailable,'DSH_CLI_UNAVAILABLE','The official dsh plugin CLI is unavailable in this host.',{need:['nodeBinary','dshBin']},503);
+    const options={cwd:profileDir,workerNode:supervisorNode,env:safeGitEnv({HOME:process.env.HOME,DSH_HOME:process.env.DSH_HOME,LANG:process.env.LANG??'C.UTF-8',PATH:commandPath(nodeBinary??desktopLauncher.command)})},tail=['plugin','--profile',profileName,...args];
+    if(launcherAvailable)options.env=safeGitEnv({...options.env,DSH_HOME:desktopLauncher.home,PATH:commandPath(desktopLauncher.command)});
+    const result=await spawn(launcherAvailable?desktopLauncher.command:nodeBinary,launcherAvailable?tail:[...(desktopCli?['--expose-internals',fileURLToPath(new URL('./desktop-cli.js',import.meta.url)),desktopCli.entry,desktopCli.runtimeDir,desktopCli.supportDir]:[dshBin]),...tail],options);
+    requireCondition(result.code===0,'DSH_PLUGIN_FAILED','DSH plugin operation failed.',{code:result.code,signal:result.signal,stderr:String(result.stderr??'').slice(-2000)},502);return result;}
   /** The exact version `dsh plugin add` will pin: the registry's `latest` dist-tag, re-checked here (the catalog's `latestVersion` is a hint only). */
   async function latest(name){
     const base=new URL(registry);requireCondition(['https:','http:'].includes(base.protocol),'REGISTRY_DENIED','Registry URL is invalid.');
@@ -56,32 +75,119 @@ export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBina
     requireCondition(versionText(version)&&(allowPrerelease||!version.includes('-')),'UNSTABLE_VERSION','Registry latest must be an exact stable version.');
     return version;
   }
-  /** Same path for applications and plugins: `dsh plugin add --save-exact <name>@<version>` (also the upgrade path: a newer exact version replaces the installed one). */
-  async function add(name){const version=await latest(name);await run(['add','--save-exact',`${name}@${version}`]);return version;}
+  /**
+   * rc.10 compensation after a failed install: the package goes back to its baseline spec through the official CLI, runtime
+   * items this operation newly claimed are removed by ownership, a replaced baseline item is provisioned again from the
+   * restored definition, and then every item is read back. `restored`/`not-needed` only when every row matches the baseline.
+   */
+  async function recover({name,stage,base,runtime,operationId}){
+    const report={status:'failed',mode:base?.spec===null?'new-install':'upgrade',stage,previousVersion:base?.module??null,actions:[],checks:[],residue:[]};
+    if(!base){report.mode='unknown';report.status='not-needed';return report;}
+    const fail=error=>{report.error??={code:error.code??'INSTALL_RECOVERY_FAILED',message:String(error.message??error)};};
+    try{
+      let now=await profileSnapshot(profileDir,name);const args=packageRestoreArgs(base,now,name);
+      if(args){report.actions.push(['dsh','plugin',...args].join(' '));try{await run(args);}catch(error){fail(error);}now=await profileSnapshot(profileDir,name);}
+      report.checks.push(...profileChecks(base,now,name));
+    }catch(error){fail(error);report.residue.push({item:'profile',reason:'NOT_VERIFIED'});}
+    if(runtime)try{
+      const readLedger=await runtimeApi('ledger');let current=await runtimeSnapshot(readLedger,runtime.root);
+      for(const id of Object.keys(current).filter(id=>!(id in runtime.base))){
+        report.actions.push('provision remove '+id);
+        try{const removed=await (await runtimeApi('remove'))(id,{root:runtime.root});if(removed?.kept?.length)report.residue.push({item:'runtime:'+id,reason:'UNOWNED_FILES_KEPT',count:removed.kept.length});}catch(error){fail(error);}
+      }
+      const replaced=Object.keys(runtime.base).filter(id=>JSON.stringify(runtime.base[id])!==JSON.stringify(current[id]));
+      if(replaced.length&&base.spec!==null&&report.checks.every(row=>row.ok))try{
+        const record=await installed(name);
+        for(const id of replaced){const declared=record.definition.deployments.map(deployment=>deployment.runtime).find(value=>value?.item===id);if(!declared)continue;
+          report.actions.push('provision '+id);await (await runtimeApi('provision'))(declared.manifest,{root:runtime.root,only:[id],onProgress:event=>emit({type:'library.provision-progress',appId:record.definition.id,...event})});}
+      }catch(error){fail(error);}
+      current=await runtimeSnapshot(readLedger,runtime.root);report.checks.push(...runtimeChecks(runtime.base,current));
+    }catch(error){fail(error);report.residue.push({item:'runtime',reason:'NOT_VERIFIED'});}
+    for(const row of report.checks)if(!row.ok)report.residue.push({item:row.item,expected:row.expected,actual:row.actual,reason:row.reason??'NOT_RESTORED',...(row.concurrent?{concurrent:row.concurrent}:{})});
+    report.status=report.error||report.residue.length?'failed':report.actions.length?'restored':'not-needed';
+    if(report.status==='failed'){try{report.originals=await keepOriginals(join(dataRoot,'library-recovery',operationId),base,runtime?.base);}catch(error){report.originals={error:{code:error.code??'ORIGINALS_NOT_KEPT',message:String(error.message??error)}};}}
+    return report;
+  }
+  /**
+   * Same path for applications and plugins: baseline → `dsh plugin add --save-exact <name>@<version>` (also the upgrade
+   * path) → profile readback → application definition → runtime provision. Any failure after the baseline is compensated
+   * and reported with the original error; nothing is retried.
+   */
+  async function transaction(item,kind,context){
+    requireCondition(cliAvailable,'DSH_EXACT_INSTALL_UNAVAILABLE','The host cannot install a package with an exact saved version.',{need:unavailable()},503);
+    const name=item.package.name,operationId=/^[A-Za-z0-9-]{1,64}$/.test(context?.operationId??'')?context.operationId:randomUUID();let stage='baseline',base,runtime;
+    try{
+      base=await profileSnapshot(profileDir,name);
+      stage='before-add';const version=await latest(name);
+      const status='restart-required';
+      stage='add';await run(['add','--save-exact',`${name}@${version}`]);
+      stage='readback';const added=await profileSnapshot(profileDir,name);
+      requireCondition(added.spec===version&&added.module===version,'INSTALL_READBACK_MISMATCH','The profile does not resolve the exact version that was added.',{expected:version,spec:added.spec,module:added.module},502);
+      if(kind==='plugin')return{status,kind,packageName:name,version};
+      stage='definition';const record=await installed(name);const declared=record.definition.deployments.map(deployment=>deployment.runtime).find(Boolean);
+      if(declared){stage='provision';const root=runtimeRoot(record.definition.id);runtime={root,base:await runtimeSnapshot(await runtimeApi('ledger'),root)};
+        await (await runtimeApi('provision'))(declared.manifest,{root,only:[declared.item],onProgress:event=>emit({type:'library.provision-progress',appId:record.definition.id,...event})});}
+      return{status:'restart-required',kind,appId:record.definition.id,packageName:name,version};
+    }catch(error){error.recovery=await recover({name,stage,base,runtime,operationId});throw error;}
+  }
+  async function installAs(item,kind,context){
+    permitted(item.package.name);const name=item.package.name;
+    emit({type:'library.install-started',...(item.id?{itemId:item.id}:{}),packageName:name,kind});
+    try{const result=await profileWriter.run(()=>transaction(item,kind,context));emit({type:'library.install-done',...result});return result;}
+    catch(error){emit({type:'library.install-failed',...(item.id?{itemId:item.id}:{}),packageName:name,kind,code:error.code??'INSTALL_FAILED',...(error.recovery?{recovery:error.recovery}:{})});throw error;}
+  }
+  let suitePlan;
+  const suiteProvider=coreSuitePlan??createCoreSuiteAdapter({core:coreService,registry,suiteSourceMode,suiteSourceService});
+  async function previewSuite(){
+    const next=await prepareSuiteUpgrade({coreSuitePlan:suiteProvider});
+    suitePlan={...next,planId:randomUUID()};return structuredClone(suitePlan);
+  }
   return{
-    async install(item){
-      const kind=itemKind(item);
-      requireCondition(kind!=='listing','NOT_INSTALLABLE','Catalog item has no npm package to install.');const name=item.package.name;
-      permitted(name);
-      emit({type:'library.install-started',itemId:item.id,packageName:name,kind});
+    get suiteUpgradeUnavailable(){return suiteProvider.unavailable??null;},
+    async suiteFacts(){
+      if(!suiteProvider.readFacts)return await readSuiteStatus(profileDir);
+      try{return await suiteProvider.readFacts();}catch(error){return{...await readSuiteStatus(profileDir),status:'unknown',completeness:'unknown',blocked:[{code:error.code??'CORE_SUITE_DECLARATION_UNAVAILABLE'}],suiteUpgradeUnavailable:error.code==='CORE_SUITE_DECLARATION_MISSING'?suiteProvider.unavailable:'Core 套件声明读取失败（'+(error.code??'CORE_SUITE_DECLARATION_UNAVAILABLE')+'）'};}
+    },
+    prepareSuiteUpgrade:previewSuite,
+    async upgradeSuite({planId}={}){return await profileWriter.run(async()=>{
+      requireCondition(suitePlan?.planId===planId,'SUITE_PLAN_CHANGED','升级确认已变化，请重新查看并确认。',{},409);
+      const confirmed=suitePlan;suitePlan=undefined;
+      const fresh=await prepareSuiteUpgrade({coreSuitePlan:suiteProvider});
+      const identity=plan=>JSON.stringify({sourceBinding:plan.sourceBinding,components:plan.components,declarationId:plan.declarationId,registry:plan.registry,selectedUpgrade:plan.selectedUpgrade,physicalBaseline:plan.physicalBaseline});
+      requireCondition(identity(fresh)===identity(confirmed),'SUITE_PLAN_CHANGED','套件声明或版本已变化，请重新查看并确认。',{},409);
+      requireCondition(fresh.available,'SUITE_NO_UPDATE','当前没有兼容新版。',{},409);
+      const before=await readSuiteStatus(profileDir);
+      requireCondition(before.status==='installed'&&fresh.components.every((c,i)=>before.components[i]?.version===c.from),'SUITE_PLAN_CHANGED','已装版本或启用状态已变化，请重新查看并确认。',{},409);
+      requireCondition(cliAvailable,'DSH_CLI_UNAVAILABLE','套件升级需客户端随附的官方 CLI；请恢复后重试。',{},503);
+      const executing=await prepareSuiteUpgrade({coreSuitePlan:suiteProvider});
+      requireCondition(identity(executing)===identity(confirmed),'SUITE_PLAN_CHANGED','执行前套件安装包来源或声明已变化，请重新查看并确认。',{},409);
+      emit({type:'library.install-started',itemId:'hanamesh:suite-upgrade',packageName:'hanamesh-core',kind:'suite-upgrade'});
       try{
-        const version=await add(name);
-        if(kind==='plugin'){const result={status:'restart-required',kind,packageName:name,version};emit({type:'library.install-done',...result});return result;}
-        const record=await installed(name);const runtime=record.definition.deployments.map(deployment=>deployment.runtime).find(Boolean);
-        if(runtime){const api=provision?{provision}:{...(await defaults())};await api.provision(runtime.manifest,{root:runtimeRoot(record.definition.id),only:[runtime.item],onProgress:event=>emit({type:'library.provision-progress',appId:record.definition.id,...event})});}
-        const result={status:'restart-required',kind,appId:record.definition.id,packageName:name,version};emit({type:'library.install-done',...result});return result;
-      }catch(error){emit({type:'library.install-failed',itemId:item.id,packageName:name,kind,code:error.code??'INSTALL_FAILED'});throw error;}
+        await run(['add','--save-exact','--strict-peer-dependencies',`--registry=${fresh.registry??registry}`,...fresh.components.map(c=>`${c.name}@${c.to}`)]);
+        const actual=await readSuiteStatus(profileDir);
+        const saved=await json(join(profileDir,'package.json'));
+        requireCondition(actual.status==='installed'&&fresh.components.every((c,i)=>actual.components[i]?.version===c.to&&saved.dependencies?.[c.name]===c.to),'INSTALL_READBACK_MISMATCH','套件升级后的版本或启用状态不符，请完全退出后按补齐命令修复。',{},502);
+        return{status:'restart-required',kind:'suite-upgrade',packageName:'hanamesh-core',components:fresh.components,version:actual.version};
+      }catch(error){
+        error.details={...error.details,stage:'suite-upgrade',actual:await readSuiteStatus(profileDir),command:SUITE_INSTALL_COMMAND};
+        emit({type:'library.install-failed',packageName:'hanamesh-core',code:error.code??'SUITE_UPGRADE_FAILED'});throw error;
+      }
+    });},
+    async install(item,context){
+      const kind=itemKind(item);
+      requireCondition(kind!=='listing','NOT_INSTALLABLE','Catalog item has no npm package to install.');
+      return await installAs(item,kind,context);
     },
     /** rc.28: install a plugin by package name (already verified against the catalog by the service). */
-    async installPlugin({packageName:name}){
-      permitted(name);
-      emit({type:'library.install-started',packageName:name,kind:'plugin'});
-      try{const version=await add(name);const result={status:'restart-required',kind:'plugin',packageName:name,version};emit({type:'library.install-done',...result});return result;}
-      catch(error){emit({type:'library.install-failed',packageName:name,kind:'plugin',code:error.code??'INSTALL_FAILED'});throw error;}
-    },
-    async provisionRuntime({appId,packageName:installedName,runtimeItem}){const record=await installed(installedName);requireCondition(record.definition.id===appId,'APP_ID_MISMATCH','Installed package app id does not match.');const runtime=record.definition.deployments.map(deployment=>deployment.runtime).find(value=>value?.item===runtimeItem);requireCondition(runtime,'RUNTIME_NOT_DECLARED','Runtime item is not declared.');const api=provision?{provision}:{...(await defaults())};const result=await api.provision(runtime.manifest,{root:runtimeRoot(appId),only:[runtime.item],onProgress:event=>emit({type:'library.provision-progress',appId,...event})});return{status:'restart-required',appId,packageName:installedName,result};},
-    async uninstall({packageName:installedName,appId,runtimeItem,running}){permitted(installedName);requireCondition(!running,'INSTANCE_IN_USE','Stop all application instances before uninstalling.',{},409);await run(['remove',installedName]);if(runtimeItem){const api=remove?{remove}:{...(await defaults())};const result=await api.remove(runtimeItem,{root:runtimeRoot(appId)});await clearGeneratedRuntimeCache(result,runtimeRoot(appId));}return{status:'restart-required',kind:'application',appId,packageName:installedName,dataPreserved:true};},
+    async installPlugin({packageName:name},context){return await installAs({package:{registry:'npm',name}},'plugin',context);},
+    async provisionRuntime({appId,packageName:installedName,runtimeItem}){return await profileWriter.run(async()=>{const record=await installed(installedName);requireCondition(record.definition.id===appId,'APP_ID_MISMATCH','Installed package app id does not match.');const runtime=record.definition.deployments.map(deployment=>deployment.runtime).find(value=>value?.item===runtimeItem);requireCondition(runtime,'RUNTIME_NOT_DECLARED','Runtime item is not declared.');const result=await (await runtimeApi('provision'))(runtime.manifest,{root:runtimeRoot(appId),only:[runtime.item],onProgress:event=>emit({type:'library.provision-progress',appId,...event})});return{status:'restart-required',appId,packageName:installedName,result};});},
+    async uninstall({packageName:installedName,appId,runtimeItem,running}){permitted(installedName);requireCondition(!running,'INSTANCE_IN_USE','Stop all application instances before uninstalling.',{},409);return await profileWriter.run(async()=>{await run(['remove',installedName]);if(runtimeItem){const result=await (await runtimeApi('remove'))(runtimeItem,{root:runtimeRoot(appId)});await clearGeneratedRuntimeCache(result,runtimeRoot(appId));}return{status:'restart-required',kind:'application',appId,packageName:installedName,dataPreserved:true};});},
     /** rc.28: `dsh plugin remove <name>`; the suite itself (PROTECTED_PACKAGES) is refused with PACKAGE_DENIED. */
-    async uninstallPlugin({packageName:installedName}){permitted(installedName);await run(['remove',installedName]);return{status:'restart-required',kind:'plugin',packageName:installedName};},
+    async uninstallPlugin({packageName:installedName}){permitted(installedName);return await profileWriter.run(async()=>{      await run(['remove',installedName]);return{status:'restart-required',kind:'plugin',packageName:installedName};});},
+    /** Guarded public CLI mutations require a restart. */
+    get live(){return false;},
+    /** Installation requires a public CLI that can run inside the owned monitor. */
+    get ready(){return cliAvailable;},
+    get unavailable(){return unavailable();},
   };
 }

package/dist/library/installation-cli.js

@@ -0,0 +1,48 @@
+/** Fixed official read-only CLI calls. No browser-controlled argv, environment or profile path. */
+import {fork} from 'node:child_process';
+import {guardNodeBinary} from '../git-process.js';
+import {stat,realpath,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {dirname,isAbsolute,delimiter} from 'node:path';
+import {AppHostError} from '../errors.js';
+const fail=code=>{throw new AppHostError(code,'The configured official installation reader could not complete.',{},503)};
+export const SUPPORTED_READER_VERSIONS=Object.freeze({claude:'2.1.301 (Claude Code)',codex:'codex-cli 0.162.1'});
+export function validReader(value){
+ if(!value||typeof value!=='object'||Array.isArray(value))return false;
+ const keys=['executable','home','configDir','pluginName','marketplace','marketplaceUrl','timeoutMs','maxOutputBytes'];
+ if(Object.keys(value).some(key=>!keys.includes(key))||!['executable','home','configDir'].every(key=>typeof value[key]==='string'&&isAbsolute(value[key])&&!/[\x00-\x1f]/.test(value[key])))return false;
+ if(!['pluginName','marketplace'].every(key=>typeof value[key]==='string'&&/^[a-z0-9][a-z0-9._-]{0,127}$/.test(value[key])))return false;
+ try{const url=new URL(value.marketplaceUrl);if(url.protocol!=='https:'||url.username||url.password||url.hash||url.search||url.href!==value.marketplaceUrl)return false}catch{return false}
+ return Number.isSafeInteger(value.timeoutMs)&&value.timeoutMs>0&&value.timeoutMs<=2_147_483_647&&Number.isSafeInteger(value.maxOutputBytes)&&value.maxOutputBytes>0;
+}
+export async function runOfficialInstallationCommand({channel,reader,args,signal,workerNode}){
+ if(signal?.aborted)fail('INSTALLATION_STATUS_CANCELLED');
+ if(process.platform==='win32')fail('AGENT_READER_PLATFORM_UNSUPPORTED');
+ if(!validReader(reader))fail('AGENT_READER_CONFIG_INVALID');
+ const nodeRuntime=guardNodeBinary({workerNode});if(!nodeRuntime)fail('AGENT_READER_NODE_REQUIRED');
+ for(const path of [reader.home,reader.configDir]){let value;try{value=await stat(path)}catch{fail('AGENT_PROFILE_UNAVAILABLE')}if(!value.isDirectory())fail('AGENT_PROFILE_UNAVAILABLE')}
+ const temporaryRoot=await realpath(tmpdir());let cwd;
+ // An exact configuration directory is explicit. Inherited model/API tokens, proxy, shell startup and askpass are absent.
+ const env={PATH:[dirname(nodeRuntime),'/usr/bin','/bin','/usr/local/bin'].join(delimiter),HOME:reader.home,USERPROFILE:reader.home,
+  ...(channel==='claude'?{CLAUDE_CONFIG_DIR:reader.configDir,CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC:'1',DISABLE_AUTOUPDATER:'1'}:{CODEX_HOME:reader.configDir}),
+  GIT_TERMINAL_PROMPT:'0',GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null',GIT_CONFIG_COUNT:'1',GIT_CONFIG_KEY_0:'credential.helper',GIT_CONFIG_VALUE_0:''};
+ try{return await new Promise((resolve,reject)=>{
+  if(signal?.aborted){reject(new AppHostError('INSTALLATION_STATUS_CANCELLED','Installation read was cancelled.',{},499));return}
+  const child=fork(new URL('./installation-worker.js',import.meta.url),[],{cwd:temporaryRoot,env,execPath:nodeRuntime,execArgv:[],detached:true,stdio:['ignore','pipe','pipe','ipc']});
+  const chunks=[];let total=0,stderr=false,fault,exited=false,message;
+  const kill=code=>{fault??=code;if(!exited&&child.pid){child.kill('SIGTERM')}};
+  const abort=()=>kill('INSTALLATION_STATUS_CANCELLED');signal?.addEventListener('abort',abort,{once:true});
+  const timer=setTimeout(()=>kill('AGENT_READER_TIMEOUT'),reader.timeoutMs);
+  child.stdout.on('data',chunk=>{total+=chunk.length;if(total>reader.maxOutputBytes)kill('AGENT_READER_OUTPUT_LIMIT');else chunks.push(chunk)});
+  child.stderr.on('data',chunk=>{stderr=true;total+=chunk.length;if(total>reader.maxOutputBytes)kill('AGENT_READER_OUTPUT_LIMIT')});
+  child.on('message',value=>{if(typeof value.directory==='string')cwd=value.directory;else message=value});
+  child.once('exit',()=>{exited=true});
+  child.once('error',error=>{fault??=error.code==='EACCES'?'AGENT_READER_PERMISSION_DENIED':'AGENT_READER_UNAVAILABLE'});
+  child.once('close',code=>{exited=true;clearTimeout(timer);signal?.removeEventListener('abort',abort);
+   if(fault||message?.error||message?.result!==0||stderr)reject(new AppHostError(fault??message?.error??(stderr?'AGENT_READER_DIAGNOSTIC':'AGENT_READER_FAILED'),'The configured official reader did not return a complete clean result.',{},503));
+   else resolve(Buffer.concat(chunks).toString('utf8'));
+  });
+  if(child.connected)child.send({executable:reader.executable,args,temporaryRoot,env},()=>{});
+  if(signal?.aborted)abort();
+ })}finally{if(cwd)await rm(cwd,{recursive:true,force:true})}
+}

package/dist/library/installation-command-worker.js

@@ -0,0 +1,27 @@
+/** Live command-group anchor. Its separate reaper removes the cwd only after this group has ended. */
+import {spawn} from 'node:child_process';
+let started=false,reported=false;
+const stopOwnedGroup=()=>process.kill(-process.pid,'SIGKILL');
+function report(payload){
+ if(reported)return;reported=true;
+ if(process.connected){try{process.send(payload,error=>{if(error)stopOwnedGroup()})}catch{stopOwnedGroup()}}else stopOwnedGroup();
+ // Remain the live group owner until the reaper terminates us; never release a reusable PGID early.
+}
+process.once('disconnect',stopOwnedGroup);
+process.once('SIGTERM',stopOwnedGroup);process.once('SIGINT',stopOwnedGroup);
+process.once('uncaughtException',()=>report({error:'AGENT_READER_FAILED'}));
+process.once('unhandledRejection',()=>report({error:'AGENT_READER_FAILED'}));
+if(!process.connected)process.exit(1);
+process.on('message',request=>{
+ if(started)return;started=true;
+ try{
+  const child=spawn(request.executable,request.args,{cwd:process.cwd(),env:process.env,detached:false,shell:false,stdio:['ignore','pipe','pipe']});
+  child.stdout.pipe(process.stdout,{end:false});child.stderr.pipe(process.stderr,{end:false});
+  child.once('error',error=>report({error:error.code==='EACCES'?'AGENT_READER_PERMISSION_DENIED':'AGENT_READER_UNAVAILABLE'}));
+  // An exited leader may leave descendants holding its pipes. Keep ownership until EOF or reaper cancellation.
+  child.once('close',code=>{
+   let flushed=0;const complete=()=>{if(++flushed===2)report({result:code})};
+   process.stdout.write('',complete);process.stderr.write('',complete);
+  });
+ }catch{report({error:'AGENT_READER_UNAVAILABLE'})}
+});

package/dist/library/installation-status-http.js

@@ -0,0 +1,26 @@
+import {AppHostError,requireCondition} from '../errors.js';
+export function installationStatusCors(req,allowedOrigins){
+ const origin=req.headers.origin;
+ requireCondition(typeof origin==='string'&&allowedOrigins.includes(origin),'ORIGIN_DENIED','This origin is not allowed to read installation status.',{},403);
+ return{'access-control-allow-origin':origin,vary:'Origin','access-control-allow-private-network':'true'};
+}
+/** Called only after the owning listener's exact loopback Host and Origin checks. */
+export async function serveInstallationStatus(req,res,{read,maxBodyBytes,traceId,cors,send}){
+ requireCondition(req.url?.startsWith('/')&&!req.url.startsWith('//')&&!req.url.includes('\\'),'BAD_TARGET','Invalid request target.');
+ requireCondition(req.headers['sec-fetch-dest']!=='iframe','FRAME_CONTROL_DENIED','An application frame cannot inspect the host.',{},403);
+ requireCondition(req.headers.cookie===undefined&&req.headers.authorization===undefined,'CREDENTIALS_NOT_ACCEPTED','Installation reads require credentials: omit.',{},403);
+ requireCondition(!new URL(req.url,'http://127.0.0.1').search,'UNKNOWN_FIELDS','Installation status takes no query.');
+ if(req.method==='OPTIONS'){send(res,204,undefined,{...cors,'access-control-allow-methods':'POST','access-control-allow-headers':'content-type'});return;}
+ requireCondition(req.method==='POST','METHOD_NOT_ALLOWED','Installation status requires POST.',{},405);
+ requireCondition(req.headers['content-type']?.split(';')[0].trim()==='application/json','CONTENT_TYPE_REQUIRED','Expected application/json.',{},415);
+ let total=0;const chunks=[];
+ for await(const chunk of req){total+=chunk.length;requireCondition(total<=maxBodyBytes,'BODY_TOO_LARGE','Installation status body is too large.',{},413);chunks.push(chunk)}
+ let body;try{body=JSON.parse(Buffer.concat(chunks).toString('utf8'))}catch{throw new AppHostError('INVALID_JSON','Malformed JSON.',{},400)}
+ requireCondition(body&&typeof body==='object'&&!Array.isArray(body)&&Object.keys(body).every(key=>['contractVersion','consent'].includes(key)),'UNKNOWN_FIELDS','Only contractVersion and consent are accepted.');
+ requireCondition(body.contractVersion===undefined||body.contractVersion==='1','INSTALLATION_STATUS_CONTRACT_UNSUPPORTED','Installation status contractVersion 1 is required.');
+ requireCondition(Object.keys(body).length===2&&body.contractVersion==='1'&&body.consent==='read-installations','INSTALLATION_STATUS_CONSENT_REQUIRED','Explicit one-request read-installations consent is required.',{},403);
+ requireCondition(typeof read==='function','INSTALLATION_STATUS_UNAVAILABLE','The read-only installation bridge is not supplied.',{},503);
+ const controller=new AbortController();const abort=()=>{if(!res.writableEnded)controller.abort()};req.once('aborted',abort);res.once('close',abort);
+ try{if(req.aborted||res.destroyed)controller.abort();const value=await read({signal:controller.signal});if(!controller.signal.aborted)send(res,200,{...value,traceId},cors)}
+ finally{req.off('aborted',abort);res.off('close',abort)}
+}

package/dist/library/installation-status.js

@@ -0,0 +1,91 @@
+/** Read fresh public installation facts. No compatibility calculation, persistence or polling. */
+import semver from 'semver';
+import {AppHostError} from '../errors.js';
+import {createCoreSuiteAdapter,SUITE_PACKAGES} from './suite.js';
+import {SUPPORTED_READER_VERSIONS,validReader,runOfficialInstallationCommand} from './installation-cli.js';
+const object=x=>x!==null&&typeof x==='object'&&!Array.isArray(x);
+const exact=x=>typeof x==='string'&&semver.valid(x)===x?x:null;
+const reason=(code,message,action)=>({code,message,action});
+const interrupted=()=>new AppHostError('INSTALLATION_STATUS_CANCELLED','Installation read was cancelled.',{},499);
+function abortable(work,signal){
+ if(signal.aborted)return Promise.reject(interrupted());
+ return new Promise((resolve,reject)=>{const abort=()=>reject(interrupted());signal.addEventListener('abort',abort,{once:true});Promise.resolve(work).then(resolve,reject).finally(()=>signal.removeEventListener('abort',abort))});
+}
+const base=(channel,id,kind,label)=>({channel,scope:{id,kind,label},status:'unknown',version:null,versionKind:['dsh','hanamesh'].includes(channel)?'core':'agent-distribution',components:[],identity:null,reason:null});
+const unknown=(row,code,message,action)=>({...row,status:'unknown',version:null,reason:reason(code,message,action)});
+const agentBase=channel=>base(channel,'agent-cli','official-user-profile',channel==='claude'?'Claude Code 用户级插件（不覆盖项目或其他隔离资料）':'Codex CLI 本地市场用户资料（不代表桌面 App、项目或其他隔离资料）');
+const inventoryError=()=>{throw new AppHostError('AGENT_INVENTORY_INVALID','Official inventory shape is unsupported.',{},503)};
+const qualified=x=>typeof x==='string'&&/^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9._-]*$/.test(x)&&x.length<=257;
+function parseInventory(channel,plugins,marketplaces,target){
+ let rows,markets;
+ if(channel==='claude'){
+  if(!Array.isArray(plugins)||!Array.isArray(marketplaces))inventoryError();rows=plugins;markets=marketplaces;
+  if(!rows.every(r=>object(r)&&qualified(r.id)&&['user','project','local','managed','session','synced'].includes(r.scope)&&typeof r.enabled==='boolean'&&typeof r.version==='string'&&typeof r.installPath==='string'&&(r.errors===undefined||Array.isArray(r.errors))&&(r.notes===undefined||Array.isArray(r.notes))))inventoryError();
+ }else{
+  if(!object(plugins)||!Array.isArray(plugins.installed)||!Array.isArray(plugins.available)||!object(marketplaces)||!Array.isArray(marketplaces.marketplaces))inventoryError();rows=plugins.installed;markets=marketplaces.marketplaces;
+  if(!rows.every(r=>object(r)&&qualified(r.pluginId)&&r.pluginId===`${r.name}@${r.marketplaceName}`&&typeof r.installed==='boolean'&&typeof r.enabled==='boolean'))inventoryError();
+ }
+ if(!markets.every(r=>object(r)&&typeof r.name==='string'&&r.name.length>0&&r.name.length<=128))inventoryError();
+ const sourceRows=markets.filter(r=>r.name===target.marketplace);
+ if(sourceRows.length>1)throw new AppHostError('AGENT_INVENTORY_CONFLICT','Conflicting marketplace identities.',{},503);
+ if(sourceRows.length){const m=sourceRows[0],url=channel==='claude'?(['url','git'].includes(m.source)?m.url:null):(['git','url'].includes(m.marketplaceSource?.sourceType)?m.marketplaceSource.source:null);
+  if(url!==target.marketplaceUrl)throw new AppHostError('AGENT_MARKETPLACE_SOURCE_MISMATCH','The configured marketplace source is not the registered target.',{},503);
+ }
+ const id=`${target.pluginName}@${target.marketplace}`;
+ const matches=rows.filter(r=>(channel==='claude'?r.id:r.pluginId)===id);
+ const scoped=channel==='claude'?matches.filter(r=>r.scope==='user'):matches;
+ if(matches.length&&!scoped.length)throw new AppHostError('AGENT_SCOPE_UNOBSERVABLE','The target is outside the configured user scope.',{},503);
+ if(scoped.length>1)throw new AppHostError('AGENT_INVENTORY_CONFLICT','Conflicting target installations.',{},503);
+ if(!scoped.length)return{status:'not-installed',version:null,components:[],reason:null};
+ if(!sourceRows.length)throw new AppHostError('AGENT_MARKETPLACE_SOURCE_UNAVAILABLE','The target marketplace source is not observable.',{},503);
+ const installedSource=scoped[0].marketplaceSource;
+ if(channel==='codex'){
+  if(!installedSource||!['git','url'].includes(installedSource.sourceType)||typeof installedSource.source!=='string')throw new AppHostError('AGENT_MARKETPLACE_SOURCE_UNAVAILABLE','Installed marketplace source is not observable.',{},503);
+  if(installedSource.source!==target.marketplaceUrl)throw new AppHostError('AGENT_MARKETPLACE_SOURCE_MISMATCH','Installed marketplace source conflicts with the registered target.',{},503);
+ }
+ const row=scoped[0],version=exact(channel==='claude'&&row.readFromFolder!==undefined?row.folderVersion:row.version);
+ const failed=channel==='claude'?Boolean(row.errors?.length||row.notes?.length):!row.installed;
+ return{status:failed?'incomplete':'installed',version,components:[{name:target.pluginName,version,active:row.enabled}],
+  reason:failed?reason(channel==='claude'?'AGENT_PLUGIN_LOAD_FAILED':'AGENT_PLUGIN_PAYLOAD_MISSING','官方清单报告插件负载或加载问题。','在该官方客户端的插件详情中检查并修复。'):version===null?reason('AGENT_VERSION_UNAVAILABLE','已确认该作用域的安装记录，但实际版本未知。','在该官方客户端插件详情中核对实际版本。'):null};
+}
+const failureCodes=new Set(['AGENT_READER_UNAVAILABLE','AGENT_READER_PERMISSION_DENIED','AGENT_READER_PLATFORM_UNSUPPORTED','AGENT_READER_NODE_REQUIRED','AGENT_PROFILE_UNAVAILABLE','AGENT_READER_TIMEOUT','AGENT_READER_OUTPUT_LIMIT','AGENT_READER_CLEANUP_FAILED','AGENT_READER_DIAGNOSTIC','AGENT_READER_FAILED','AGENT_INVENTORY_INVALID','AGENT_INVENTORY_CONFLICT','AGENT_MARKETPLACE_SOURCE_MISMATCH','AGENT_MARKETPLACE_SOURCE_UNAVAILABLE','AGENT_SCOPE_UNOBSERVABLE']);
+/** Trusted static configuration only; `core` is the optional public protocol-1 Cordis service accessor. */
+export function createInstallationStatusReader({client='dsh',core=()=>undefined,readers={},workerNode,runCommand=runOfficialInstallationCommand}={}){
+ if(!['dsh','hanamesh'].includes(client))throw new TypeError('client must be dsh or hanamesh');
+ const settings=structuredClone(readers??{}),active=new Set();let closed=false;
+ const suite=createCoreSuiteAdapter({core});
+ async function runtime(signal){
+  const row=base(client,'current-runtime','responding-runtime',client==='dsh'?'当前响应的 DSH runtime':'当前响应的 HanaMesh 客户端 runtime');
+  try{const value=await abortable(suite.readFacts(),signal);
+   const components=value.components.map(c=>({name:c.name,version:exact(c.version),...(['satisfied','missing','incompatible','damaged','unreadable','inactive','failed','ambiguous'].includes(c.status)?{status:c.status}:{}),...(typeof c.active==='boolean'?{active:c.active}:{})}));
+   const blocked=value.blocked.map(r=>({code:/^CORE_[A-Z0-9_]{1,75}$/.test(r.code)?r.code:'CORE_SUITE_BLOCKED',...(SUITE_PACKAGES.some(c=>c.name===r.moduleName)?{moduleName:r.moduleName}:{})}));
+   return{...row,status:value.status,version:value.status==='unknown'?null:exact(value.version),components,blocked,
+    reason:value.status==='unknown'?reason('CORE_SUITE_DECLARATION_UNKNOWN','Core 尚不能确认本 runtime 的套件完整性。','查看 Core 设置中的具名阻断原因，补齐其公开事实后重新检测。'):value.status==='incomplete'?reason('CORE_SUITE_CURRENT_INCOMPLETE','Core 报告本 runtime 的套件不完整。','在本客户端按 Core 组件说明修复后重新检测。'):null};
+  }catch(error){if(signal.aborted)throw interrupted();const code=['CORE_SUITE_DECLARATION_MISSING','CORE_SUITE_DECLARATION_INVALID'].includes(error.code)?error.code:'CORE_SUITE_READ_FAILED';return unknown(row,code,code==='CORE_SUITE_DECLARATION_MISSING'?'本 runtime 未提供 Core 套件声明方法。':'本次 Core 套件声明读取失败。','启用支持 protocol 1 getSuiteDeclaration 的 Core，查看其设置并重新检测。')}
+ }
+ async function agent(channel,signal){
+  const initial=agentBase(channel),config=settings[channel];
+  if(config===undefined)return unknown(initial,'AGENT_READER_NOT_CONFIGURED','尚未配置该渠道的官方只读清单读取器。','在 AppHost library.installationReaders 中配置官方命令、用户资料、登记目标与读取预算后重新检测。');
+  if(!validReader(config))return unknown(initial,'AGENT_READER_CONFIG_INVALID','官方读取器缺少有效的显式配置。','核对 library.installationReaders 的绝对路径、登记插件名/市场来源和必填读取预算。');
+  const row={...initial,identity:{pluginName:config.pluginName,marketplace:config.marketplace}};
+  const invoke=args=>abortable(runCommand({channel,reader:config,args,signal,workerNode}),signal);
+  try{
+   const version=(await invoke(['--version'])).trim();
+   if(version!==SUPPORTED_READER_VERSIONS[channel])return unknown(row,'AGENT_READER_VERSION_UNSUPPORTED','该官方 CLI 版本尚未验证此读取协议。','使用提供方正文列明的支持版本，或先核实新版本官方清单协议。');
+   const suffix=channel==='codex'?['--disable','remote_plugin']:[];
+   const text=await invoke(['plugin','list','--json',...suffix]);
+   const sourceText=await invoke(['plugin','marketplace','list','--json',...suffix]);
+   let plugins,marketplaces;try{plugins=JSON.parse(text);marketplaces=JSON.parse(sourceText)}catch{inventoryError()}
+   return{...row,...parseInventory(channel,plugins,marketplaces,config)};
+  }catch(error){if(signal.aborted||error.code==='INSTALLATION_STATUS_CANCELLED')throw interrupted();const code=failureCodes.has(error.code)?error.code:'AGENT_READER_FAILED';return unknown(row,code,'本次官方清单读取未能提供完整且一致的安装事实。','在对应官方 CLI 的已配置用户资料中检查插件与市场清单、权限或诊断，修复后显式重检。')}
+ }
+ const read=async({signal}={})=>{
+  if(closed||signal?.aborted)throw interrupted();const controller=new AbortController();active.add(controller);const combined=signal?AbortSignal.any([signal,controller.signal]):controller.signal;
+  try{const current=await runtime(combined);const agents=await Promise.all(['claude','codex'].map(channel=>agent(channel,combined)));if(combined.aborted)throw interrupted();
+   return{schemaVersion:1,client,checkedAt:new Date().toISOString(),observations:[current,
+    unknown(base(client==='dsh'?'hanamesh':'dsh','other-runtime','unobserved-runtime','另一客户端 runtime（须由其自身监听回答）'),'OTHER_RUNTIME_NOT_OBSERVED','本监听未读取另一客户端的 runtime。','启动该客户端，并向其已广告的状态入口显式检测。'),...agents,
+    unknown(base('codex','desktop-app','desktop-app','Codex / ChatGPT 桌面 App（独立作用域）'),'CODEX_DESKTOP_SCOPE_UNOBSERVABLE','Codex CLI 清单不能证明桌面 App 的安装。','在桌面 App 的插件目录核对；需官方公开桌面状态协议后才可接入。')]};
+  }finally{active.delete(controller)}
+ };
+ read.close=()=>{closed=true;for(const controller of active)controller.abort();active.clear()};return read;
+}

package/dist/library/installation-worker.js

@@ -0,0 +1,44 @@
+/** Detached reaper: it outlives the caller and owns the neutral directory, outside the command group. */
+import {fork} from 'node:child_process';
+import {mkdtempSync,realpathSync,rmSync} from 'node:fs';
+import {join} from 'node:path';
+let started=false,finishing=false,finalized=false,directory,anchor,anchorExited=false,payload;
+function finalize(){
+ if(finalized)return;finalized=true;
+ // Normal owned shutdown reaches here after the live group was killed and its anchor closed.
+ // An external SIGKILL/native crash of an internal supervisor is outside automatic recovery.
+ if(directory){try{rmSync(directory,{recursive:true,force:true})}catch{payload={error:'AGENT_READER_CLEANUP_FAILED'}}}
+ let flushed=0;const complete=()=>{if(++flushed!==2)return;const exit=()=>process.exit(0);
+  if(process.connected){try{process.send(payload,exit)}catch{exit()}}else exit();
+ };
+ process.stdout.write('',complete);process.stderr.write('',complete);
+}
+function finish(value){
+ if(finishing)return;finishing=true;payload=value;
+ if(anchor&&!anchorExited){
+  // The IPC anchor deliberately stays alive after command completion. Kill only its still-owned group.
+  try{process.kill(-anchor.pid,'SIGKILL')}catch{payload={error:'AGENT_READER_FAILED'}}
+ }else if(!anchor)finalize();
+}
+process.once('disconnect',()=>finish({error:'INSTALLATION_STATUS_CANCELLED'}));
+process.once('SIGTERM',()=>finish({error:'INSTALLATION_STATUS_CANCELLED'}));
+process.once('SIGINT',()=>finish({error:'INSTALLATION_STATUS_CANCELLED'}));
+process.once('uncaughtException',()=>finish({error:'AGENT_READER_FAILED'}));
+process.once('unhandledRejection',()=>finish({error:'AGENT_READER_FAILED'}));
+if(!process.connected)process.exit(1);
+process.on('message',request=>{
+ if(started)return;started=true;
+ try{
+  if(!process.connected){finish({error:'INSTALLATION_STATUS_CANCELLED'});return}
+  directory=mkdtempSync(join(realpathSync(request.temporaryRoot),'hanamesh-installation-read-'));
+  process.send({directory},error=>{if(error)finish({error:'INSTALLATION_STATUS_CANCELLED'})});
+  const env={...request.env,XDG_CONFIG_HOME:join(directory,'config'),XDG_CACHE_HOME:join(directory,'cache'),XDG_STATE_HOME:join(directory,'state'),TMPDIR:directory,TMP:directory,TEMP:directory};
+  anchor=fork(new URL('./installation-command-worker.js',import.meta.url),[],{cwd:directory,env,execArgv:[],detached:true,stdio:['ignore','pipe','pipe','ipc']});
+  anchor.stdout.pipe(process.stdout,{end:false});anchor.stderr.pipe(process.stderr,{end:false});
+  anchor.on('message',value=>finish(value));
+  anchor.once('exit',()=>{anchorExited=true});
+  anchor.once('error',()=>{if(!finishing){finishing=true;payload={error:'AGENT_READER_UNAVAILABLE'}}});
+  anchor.once('close',()=>{if(!finishing){finishing=true;payload={error:'AGENT_READER_FAILED'}}finalize()});
+  anchor.send({executable:request.executable,args:request.args},error=>{if(error)finish({error:'AGENT_READER_UNAVAILABLE'})});
+ }catch{finish({error:'AGENT_READER_UNAVAILABLE'})}
+});

package/dist/library/locate.js

@@ -2,22 +2,31 @@
  * Library locations on plain DSH (PRD §A.8 official-distribution path, rc.26).
  *
  * The pinned kernel exposes neither the profile directory nor the profile name to a plugin, and the
- * desktop shell fills `library.profileDir/profileName/dshBin` and `nodeBinary` through its overlay.
+ * Historical desktop shell fills `library.profileDir/profileName/dshBin` and `nodeBinary` through its overlay.
  * A `dsh plugin add` user has no overlay, so without these the installed-app scan returned `[]` and
  * every install/uninstall answered `LIBRARY_INSTALL_UNAVAILABLE`. Each value below is inferred ONLY
  * when the explicit config leaves it undefined, and only from facts this process can prove about
  * itself: where its own package really lives, which script started it, and which Node runs it.
  */
-import { readFile, realpath } from 'node:fs/promises';
+import { readFile, realpath, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createRequire } from 'node:module';
 import { basename, dirname, isAbsolute, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 export const PACKAGE_NAME='@hanamesh/dsh-app-host';
 /** Used when `library.sources` is undefined (not configured). An explicit `[]` means "no source". */
-export const DEFAULT_CATALOG_SOURCES=Object.freeze([Object.freeze({manifestUrl:'https://market.hanamesh.com/catalog-source.json',enabled:true})]);
+export const DEFAULT_CATALOG_SOURCES=Object.freeze([Object.freeze({manifestUrl:'https://market.hanamesh.com/catalog-source.json?view=hanamesh',enabled:true})]);
 const DSH_BIN_SUFFIX='/@deepseek-ai/dsh/lib/bin.js';
 
 async function json(path){try{return JSON.parse(await readFile(path,'utf8'));}catch{return undefined;}}
+/** The public package manifest resolved by the host's installation/profile anchor. No service flags are inferred. */
+export async function inferPluginManagerVersion(anchor){
+  if(typeof anchor!=='string'||!isAbsolute(anchor))return undefined;
+  try{const pkg=await json(createRequire(anchor).resolve('@deepseek-ai/dsh-plugin-manager/package.json'));return pkg?.name==='@deepseek-ai/dsh-plugin-manager'?pkg.version:undefined;}catch{return undefined;}
+}
 /** A DSH profile manifest that carries HanaMesh: `dsh.profile` (written by `dsh plugin`) or a hanamesh dependency. */
 export function isHanameshProfileManifest(manifest){
   if(!manifest||typeof manifest!=='object'||Array.isArray(manifest))return false;
@@ -51,6 +60,56 @@ export async function inferProfileDir(moduleUrl){
   }
 }
 
+/** Proven upstream Desktop launch layout, from desktop/src/host-process.ts and desktop-host/src/index.ts.
+ * The shell passes runtimeDir and profileDir to its named entry; prove the entry and this package's
+ * profile link before using them. Never infer from cwd, HOME, a port, or a supply overlay.
+ */
+export async function inferDesktopLayout({moduleUrl=import.meta.url,argv=process.argv}={}) {
+  const [entry,runtimeDir,profileDir]=[argv?.[1],argv?.[2],argv?.[3]];
+  if (![entry,runtimeDir,profileDir].every(value=>typeof value==='string'&&isAbsolute(value))) return undefined;
+  const hostRoot=join(runtimeDir,'node_modules/@deepseek-ai/dsh-desktop-host'),hostManifest=await json(join(hostRoot,'package.json'));
+  if (entry!==join(hostRoot,'lib/index.js') || hostManifest?.name!=='@deepseek-ai/dsh-desktop-host') return undefined;
+  const root=await packageRoot(moduleUrl);
+  const linked=await realpath(join(profileDir,'node_modules',...PACKAGE_NAME.split('/'))).catch(()=>undefined);
+  if (!root || root!==linked || basename(profileDir)!=='desktop' || !isHanameshProfileManifest(await json(join(profileDir,'package.json')))) return undefined;
+  const dshRoot=join(runtimeDir,'node_modules/@deepseek-ai/dsh');
+  const dshManifest=await json(join(dshRoot,'package.json'));
+  if (dshManifest?.name!=='@deepseek-ai/dsh') return undefined;
+  const dshBin=await realpath(join(dshRoot,'lib/bin.js')).catch(()=>undefined);
+  if (!dshBin || !await realpath(entry).catch(()=>undefined)) return undefined;
+  const payload=argv[4]??join(dirname(runtimeDir),'runtime/primary-runtime');
+  const cli=join(hostRoot,'lib/cli.js');
+  const payloadNamed=typeof payload==='string'&&isAbsolute(payload)&&basename(payload)==='primary-runtime';
+  const desktopCli=payloadNamed&&!runtimeDir.split(sep).some(segment=>segment.endsWith('.asar'))&&await realpath(cli).catch(()=>undefined)
+    ? {entry:cli,runtimeDir,supportDir:dirname(payload)} : undefined;
+  let nodeBinary;
+  const metadata=payloadNamed?await json(join(payload,'runtime.json')):undefined;
+  const matchingRuntime=typeof hostManifest.version==='string'&&metadata?.platform===process.platform&&metadata?.arch===process.arch&&metadata.desktopVersion===hostManifest.version&&hostManifest.version===dshManifest.version;
+  // Packaged Desktop supplies a public launcher outside ASAR. Invoke that launcher unchanged;
+  // standalone Node cannot import the archived CLI, and the launcher owns Electron's boot details.
+  let desktopLauncher;
+  const resources=dirname(dirname(runtimeDir));
+  if(matchingRuntime&&runtimeDir===join(resources,'app.asar','dsh')&&payload===join(resources,'runtime','primary-runtime')&&basename(dirname(profileDir))==='profiles'){
+    // Upstream ships a POSIX launcher on macOS. Windows' .cmd needs a separately verified carrier;
+    // Linux has no official packaged Desktop launcher. Both stay explicitly unavailable here.
+    if(process.platform==='darwin')try{const command=join(resources,'runtime','cli','bin','dsh');await access(command,constants.X_OK);desktopLauncher={command:await realpath(command),home:await realpath(dirname(dirname(profileDir)))};}catch{}
+  }
+  const managerManifest=await json(join(runtimeDir,'node_modules/@deepseek-ai/dsh-plugin-manager/package.json'));
+  const pluginManagerVersion=managerManifest?.name==='@deepseek-ai/dsh-plugin-manager'&&managerManifest.version===hostManifest.version?managerManifest.version:undefined;
+  // Current canonical runtime manifest only. No legacy descriptor inference or PATH search.
+  if(metadata?.platform===process.platform&&metadata?.arch===process.arch&&
+    metadata.desktopVersion===(await json(join(hostRoot,'package.json')))?.version&&/^24\.\d+\.\d+$/.test(metadata.node??'')) {
+    const node=join(payload,'dependencies/node/bin',process.platform==='win32'?'node.exe':'node');
+    try {
+      await access(node,constants.X_OK);
+      const {stdout}=await promisify(execFile)(node,['-p','JSON.stringify({node:process.versions.node,electron:process.versions.electron})'],{timeout:1000,env:{},maxBuffer:1024});
+      const actual=JSON.parse(stdout);
+      if(actual.node===metadata.node&&actual.electron===undefined)nodeBinary=await realpath(node);
+    } catch { /* Unavailable/unproven payload Node stays unavailable; never use Electron. */ }
+  }
+  return {profileDir:await realpath(profileDir),profileName:'desktop',dshBin,parentOrigin:'dsh-app://app',frameAncestors:[],desktopCli,desktopLauncher,pluginManagerVersion,nodeBinary,runtimeDir};
+}
+
 /** The DSH CLI that started this process — `argv[1]` only when it IS `@deepseek-ai/dsh/lib/bin.js`. */
 export function inferDshBin(argv=process.argv){
   const candidate=argv?.[1];
@@ -68,12 +127,14 @@ export function inferNodeBinary({execPath=process.execPath,versions=process.vers
  * Explicit config always wins; every inferred key is named in `inferred` so the caller can log it.
  * `sources`: undefined → DEFAULT_CATALOG_SOURCES; an explicit array (including `[]`) is kept as is.
  */
-export async function resolveLibraryLocations(config={},{moduleUrl=import.meta.url,argv=process.argv,execPath=process.execPath,versions=process.versions,nodeBinary}={}){
+export async function resolveLibraryLocations(config={},{moduleUrl=import.meta.url,argv=process.argv,execPath=process.execPath,versions=process.versions,nodeBinary,desktop}={}){
+  desktop ??= await inferDesktopLayout({moduleUrl,argv});
   const inferred=[];
-  let profileDir=config.profileDir;if(profileDir===undefined){profileDir=await inferProfileDir(moduleUrl);if(profileDir)inferred.push('profileDir');}
-  let profileName=config.profileName;if(profileName===undefined&&profileDir){profileName=basename(profileDir);inferred.push('profileName');}
-  let dshBin=config.dshBin;if(dshBin===undefined){dshBin=inferDshBin(argv);if(dshBin)inferred.push('dshBin');}
-  let node=nodeBinary;if(node===undefined){node=inferNodeBinary({execPath,versions});if(node)inferred.push('nodeBinary');}
+  let profileDir=config.profileDir;if(profileDir===undefined){profileDir=desktop?.profileDir??await inferProfileDir(moduleUrl);if(profileDir)inferred.push('profileDir');}
+  let profileName=config.profileName;if(profileName===undefined&&profileDir){profileName=desktop?.profileDir===profileDir?desktop.profileName:basename(profileDir);inferred.push('profileName');}
+  let dshBin=config.dshBin;if(dshBin===undefined){dshBin=desktop?.dshBin??inferDshBin(argv);if(dshBin)inferred.push('dshBin');}
+  let node=nodeBinary;if(node===undefined){node=desktop?.nodeBinary??inferNodeBinary({execPath,versions});if(node)inferred.push('nodeBinary');}
   let sources=config.sources;if(sources===undefined){sources=structuredClone(DEFAULT_CATALOG_SOURCES);inferred.push('sources');}
-  return{profileDir,profileName,dshBin,nodeBinary:node,sources,inferred};
+  const pluginManagerVersion=desktop?desktop.pluginManagerVersion:await inferPluginManagerVersion(inferDshBin(argv)??(profileDir?join(profileDir,'package.json'):undefined));
+  return{profileDir,profileName,dshBin,nodeBinary:node,sources,inferred,...(pluginManagerVersion?{pluginManagerVersion}:{}),...(desktop&&desktop.profileDir===profileDir&&config.dshBin===undefined?{desktopCli:desktop.desktopCli,desktopLauncher:desktop.desktopLauncher}:{})};
 }