@hanamesh/dsh-app-host 0.6.25 → 0.6.27

package/README.md

@@ -1,3 +1,13 @@
+0.6.27 候选：客户端随附独立 Node 的启动识别上限由 1 秒改为 30 秒（`PAYLOAD_NODE_PROBE_TIMEOUT_MS`）。owner Mac 实测冷启动 4.07 s / 2.81 s（CPU 0.09 s），已安装应用 0.26 s，30 秒留出 7 倍以上余量；旧 1 秒上限会让整次会话没有 Node，Claude Code/Codex 只读检测恒为 `AGENT_READER_NODE_REQUIRED`、安装环境显示未准备。到上限或插件卸载时立即 SIGKILL 该子进程，Node 仍按原规则记为不可用。身份与版本校验不变。
+
+R168：后台套件版本查询与显式安装确认分离，展示读取不替换已打开的默认/历史确认计划；来源、精确组合与物理基线的执行复读保护保持。见 [查询与确认边界](docs/LIBRARY.md#r168-后台套件查询与确认计划)。
+
+R162：预装 `@hanamesh/brand` 的前后端保护身份统一；目录和已装事实先显示，版本信息按项异步补充，受控并发/短期复用并随页面取消。完整预算与边界见 [R162首屏与保护](docs/LIBRARY.md#r162-首屏与保护边界)。
+
+应用库版本管理：卡片和详情显示已装与最新兼容版本；可升级或选择历史 npm 版本，逐次确认后交给正式 DSH CLI 精确安装。失败保留原诊断与逐项恢复结果；需要完全退出并重开。版本查询失败显示错误，不冒充已是最新。详见 [版本管理](docs/LIBRARY.md#vr1-市场版本管理)。
+
+0.6.26 候选：Codex 官方 GitHub 市场 URL 的 `.git` 后缀按精确仓库身份归一；市场映射与每项安装来源独立校验，不同仓库、凭据、查询、fragment 仍拒绝。CD2 扩大只读覆盖：ChatGPT 桌面 App 内置 Codex CLI、SemVer 预发布版本（仍须不低于最低版本）；官方用户资料目录不存在即判未安装；HanaMesh 客户端从磁盘读取 DSH 桌面版 profile（`~/.dsh/profiles/desktop`）给出 DSH 渠道已安装/未安装。检测不执行安装或配置写入，见[安装状态](docs/INSTALLATION_STATUS.md)。
+
 0.6.25 候选：本机 HTTPS 目录允许回环端口及 *.localhost，修复彩排种子初始化阻断检测监听；公网 HTTPS 非标准端口仍拒绝。Claude 官方 GitHub 市场清单按 repo 身份核对，保留不同来源拒绝。安装物回归命令见[安装状态](docs/INSTALLATION_STATUS.md)，不以页面打开代替检测通过。
 
 PX3 跨平台候选：Windows 可以运行插件/公开服务、attach 应用、受控只读 CLI 与普通包安装；`owned` 应用仍在创建进程、数据目录及请求凭据之前明确拒绝 `PLATFORM_UNSUPPORTED`。Windows 单测保留真实 attach 的 HTTP/租约/网关断言，并验证 owned 的持久失败、无进程/文件写入及不消费凭据；这些断言不构成 Windows owned 运行支持。独立 Node 可用不扩大 owned 支持；受管 Node 准备仍遵守原平台限制。Windows 本地快照采用文件 flush 加同目录 rename，不承诺断电后目录项持久；Coding OAuth Gateway 文件源因缺私有 ACL 证明继续拒绝，HTTP 提供方不变。各平台实际结果以本分支 GitHub Actions 矩阵收据为准。
@@ -22,7 +32,7 @@ PK1 兼容候选：开发输入更新为 DSH 0.2.2-rc.1 / Cordis 4.1.0 / Schemas
 
 > I51 R1 返修（待复审）：供应商指引跟随宿主中英菜单，默认正文只写用途和结果；实现解释、交接固定规则及具名设置默认值保留在技术详情。交接的保存操作与套件来源选择前置，自有字段按单列排列；设置值、默认值、权限、读写协议均不变。
 
-0.6.13 候选只消费新 npm 三包身份；插件 id、服务与存储不变。新旧 Core/Usage/Brand 均受保护，Recommender 不属于套件。0.6.12 原件保持原行为。
+0.6.13 候选只消费新 npm 三包身份；插件 id、服务与存储不变。Core、Usage、AppHost、总包与当前 Brand 受保护，Recommender 不属于套件。0.6.12 原件保持原行为。
 >
 > 已知限制 / Known limitations：官方 DSH rc.2 设置页在 390 CSS px 下仍保留固定侧栏，插件内容可用宽度受宿主挤压；本插件不改变客户端或全局 CSS，不能保证该宿主窄屏下标题、原生下拉选项及输入值完整可见。完整设置操作建议使用宽窗口。At 390 CSS px, the official DSH rc.2 settings sidebar leaves limited room for plugin content; titles, native select options and input values may remain constrained. Use a wider window for full settings operations. AppHost only controls its own content and does not modify the client or global CSS. 此限制按编排本次裁定披露，不报告整页390通过。Brand M01既有错误可见性限制仍开；静态profile peers check红流不改写为通过。
 
@@ -52,7 +62,7 @@ CLI-8：未配置来源的新用户默认请求 HanaMesh 视图（`https://marke
 
 0.6.5 历史交付：Git 依赖安装先清除继承的凭据 helper，再只使用 gh；安装与测试入口监测到 osxkeychain 即失败。套件能力沿用 0.6.4：套件只显示一张官方卡，读回实际组件版本；兼容升级展示三个固定组件的版本变化并需本人确认，升级后完全退出并重开。原有DSH 本地 `install-target` 与网站交接监听共用允许网站名单，未获准网站不能读客户端能力；`library.handoff.pollMs` 保存后在真实存储重启中保留，旧记录缺字段仍用默认值。
 
-> 2026-10-15 · 0.6.1（核查修正）：①探测只回答「允许交接的网站」，别的网站拿不到客户端、就绪、缺什么；②交接出错不再被吞：过期分成「客户端没来取 / 确认框打不开 / 弹出后没回复」，确认框打不开报 `HANDOFF_OPEN_FAILED` 带原因，上报失败、读取失败在应用库里提示并写日志；免重启装完读回 profile 失败会照实提示；③轮询间隔成为设置 `library.handoff.pollMs`（默认 1500 毫秒）；去掉端口数、网站数、过期上下限、预检缓存、读包标识超时这些写死的限值，剩下的固定规则在设置页逐条列出并说明原因；④品牌插件 `hanamesh-brand` 进保护名单，不可从市场卸载；⑤测试临时目录全部在进程退出时删除（失败也删），有守卫测试。
+> 2026-10-15 · 0.6.1（核查修正）：①探测只回答「允许交接的网站」，别的网站拿不到客户端、就绪、缺什么；②交接出错不再被吞：过期分成「客户端没来取 / 确认框打不开 / 弹出后没回复」，确认框打不开报 `HANDOFF_OPEN_FAILED` 带原因，上报失败、读取失败在应用库里提示并写日志；免重启装完读回 profile 失败会照实提示；③轮询间隔成为设置 `library.handoff.pollMs`（默认 1500 毫秒）；去掉端口数、网站数、过期上下限、预检缓存、读包标识超时这些写死的限值，剩下的固定规则在设置页逐条列出并说明原因；④品牌插件 `@hanamesh/brand` 在保护名单，不可从市场卸载；⑤测试临时目录全部在进程退出时删除（失败也删），有守卫测试。
 > 2026-10-15 · 0.6.0（第 2 段 Session E）：①网站交接——应用库在 127.0.0.1 上另起交接监听（默认端口 39317/39318/39319），网站探测、交接、轮询状态，客户端窗口弹出原有确认，用户确认才安装（C-MARKET 2026-10-15 追加）；②宿主有公开 `pluginManager` 时插件安装/卸载改由它完成，装完即加载、无需重启（结果 `applied`）；③探测返回真实客户端 `dsh`/`hanamesh` 和「还不能安装」的具体原因；④设置页新增「网站安装交接」，端口、允许的网站、过期时间都可见可改。
 
 > D-230 / 0.5.9 candidate: each acquired AppHost route, optional-service listener, observer, resolver, domain and host now registers its release immediately. Failed activation drains the acquired resources and preserves the original error; cleanup failures produce only a named APPHOST_CLEANUP_FAILED diagnostic. Normal unload uses the same once-only releases. Ordinary-app admission, original presentation/success facts, native isolation and final-package U2 remain separate gates.

package/dist/client-ui.js

@@ -5,6 +5,14 @@ window.__ModuleLoader__.load({id:'@hanamesh/dsh-app-host',factory:function(requi
   // Owned dictionaries; host locale remains the only language preference.
   const COPY={
   "zh": {
+    "versionLatest":"最新兼容版本：",
+    "versionHistory":"选择历史版本",
+    "versionLabel":"插件版本",
+    "versionApply":"安装所选版本",
+    "versionLoading":"正在读取版本…",
+    "versionFailure":"版本查询失败：",
+    "versionUnavailable":"暂无可确认的兼容版本",
+    "versionIncompatible":"不兼容",
     "copy0": "自动",
     "copy1": "手动指定",
     "copy2": "无可用供应商",
@@ -221,7 +229,7 @@ window.__ModuleLoader__.load({id:'@hanamesh/dsh-app-host',factory:function(requi
     "copy213": "插件名",
     "copy216": "测试目录（fixture）",
     "copy217": "当前市场目录",
-    "copy218": "确认后升级 HanaMesh 总包及其锁定组件；需要完全退出并重新打开客户端。",
+    "copy218": "确认后安装 HanaMesh 总包及其兼容组件；需要完全退出并重新打开客户端。",
     "copy219": "确认安装",
     "copy220": "取消",
     "copy221": "正在查询市场目录…",
@@ -306,6 +314,14 @@ window.__ModuleLoader__.load({id:'@hanamesh/dsh-app-host',factory:function(requi
     "copy301": "支持 macOS 13.5+（Apple Silicon / Intel）。Windows 的安装、守护与取消验证尚未接通，本流程不声称支持 Windows。"
   },
   "en": {
+    "versionLatest":"Latest compatible version: ",
+    "versionHistory":"Choose a previous version",
+    "versionLabel":"Plugin version",
+    "versionApply":"Install selected version",
+    "versionLoading":"Reading versions…",
+    "versionFailure":"Version lookup failed: ",
+    "versionUnavailable":"No confirmed compatible version",
+    "versionIncompatible":"Incompatible",
     "copy0": "Automatic",
     "copy1": "Manually assigned",
     "copy2": "No available provider",
@@ -522,7 +538,7 @@ window.__ModuleLoader__.load({id:'@hanamesh/dsh-app-host',factory:function(requi
     "copy213": "Plugin name",
     "copy216": "Test catalog (fixture)",
     "copy217": "Current market catalog",
-    "copy218": "Confirmation upgrades the HanaMesh bundle and its locked components. Fully quit and reopen the client afterwards.",
+    "copy218": "Confirmation installs the HanaMesh bundle and its compatible components. Fully quit and reopen the client afterwards.",
     "copy219": "Confirm installation",
     "copy220": "Cancel",
     "copy221": "Reading market catalog…",
@@ -654,6 +670,21 @@ window.__ModuleLoader__.load({id:'@hanamesh/dsh-app-host',factory:function(requi
     const response=await globalThis.fetch.bind(globalThis)(path,{...init,headers:{'x-hanamesh-client':'workspace-v1',...(init.body?{'content-type':'application/json'}:{}),...init.headers}});
     const value=await response.json();if(!response.ok){const error=new Error(value?.error?.code??`HTTP_${response.status}`);error.response=value;throw error;}return value;
   };
+  /** Per-view display metadata only; exact installation preview always re-reads its own target. */
+  function createVersionQueries({concurrency,cacheMs,read,notify}){
+    if(!Number.isSafeInteger(concurrency)||concurrency<1||concurrency>16||!Number.isSafeInteger(cacheMs)||cacheMs<=0)throw new Error('PLUGIN_VERSION_QUERY_CONFIG_INVALID');
+    const entries=new Map(),queue=[];let active=0,closed=false;
+    const publish=(entry,value)=>{if(!closed&&!entry.cancelled&&entries.get(entry.id)===entry)notify(entry.id,{key:entry.key,...value});};
+    const cancel=entry=>{if(entry.cancelled)return;entry.cancelled=true;if(entries.get(entry.id)===entry)entries.delete(entry.id);entry.controller.abort();entry.reject(new Error('PLUGIN_VERSION_QUERY_CANCELLED'));};
+    const pump=()=>{while(!closed&&active<concurrency&&queue.length){const entry=queue.shift();if(entry.cancelled)continue;active++;
+      Promise.resolve().then(()=>read(entry.id,entry.controller.signal)).then(result=>{if(entry.cancelled)return;entry.finishedAt=Date.now();entry.state='ready';publish(entry,{...result,loading:false,error:null});entry.resolve(result);},error=>{if(entry.cancelled)return;entry.finishedAt=Date.now();entry.state='failed';publish(entry,{loading:false,error:String(error.code??error.message??error),latestVersion:null,upgradeAvailable:false});entry.reject(error);}).finally(()=>{active--;pump();});
+    }};
+    const ensure=descriptor=>{const prior=entries.get(descriptor.id);if(prior?.key===descriptor.key&&(prior.state==='loading'||Date.now()-prior.finishedAt<cacheMs))return prior.promise;
+      if(prior)cancel(prior);if(closed)return Promise.reject(new Error('PLUGIN_VERSION_QUERY_CANCELLED'));
+      const entry={...descriptor,controller:new AbortController(),state:'loading',cancelled:false};entry.promise=new Promise((resolve,reject)=>{entry.resolve=resolve;entry.reject=reject;});entry.promise.catch(()=>{});entries.set(entry.id,entry);queue.push(entry);publish(entry,{loading:true,error:null});pump();return entry.promise;
+    };
+    return{read:ensure,reconcile(descriptors){const wanted=new Map(descriptors.map(row=>[row.id,row.key]));for(const entry of entries.values())if(wanted.get(entry.id)!==entry.key)cancel(entry);for(const row of descriptors)if(row.automatic)void ensure(row);},close(){if(closed)return;closed=true;for(const entry of entries.values())cancel(entry);queue.length=0;}};
+  }
   const entryId=entry=>entry.projection==='file'?`file:${entry.base??'home'}:${entry.path}`:`env:${entry.env}`;
   function ProvidersSection(){useLocale();
     const[providers,setProviders]=React.useState([]),[apps,setApps]=React.useState([]),[plans,setPlans]=React.useState({}),[error,setError]=React.useState('');
@@ -697,18 +728,18 @@ window.__ModuleLoader__.load({id:'@hanamesh/dsh-app-host',factory:function(requi
   const setTarget=value=>{targetSelection=value;for(const listener of targetListeners)listener(value);};
   const setPending=update=>{pendingOperations=typeof update==='function'?update(pendingOperations):update;for(const listener of pendingListeners)listener(pendingOperations);};
   /** Public client entry: identifiers only; the market fetches its own catalog and owns confirmation. */
-  async function openInstallTarget(input,{handoffId}={}){
+  async function openInstallTarget(input,{handoffId,versionSelection=false}={}){
     const sequence=++targetSequence;if(entryVisible)showLibrary();
     try{
       if(!input||typeof input!=='object'||Array.isArray(input))throw new Error('INVALID_INPUT');
       // rc.8: optional contract declaration; absent keeps v1 semantics, an unsupported version is refused before any request.
       if(input.contractVersion!==undefined&&input.contractVersion!==INSTALL_TARGET_CONTRACT_VERSION)throw new Error('CONTRACT_VERSION_UNSUPPORTED');
-      if(Object.keys(input).some(key=>!['itemId','packageName','contractVersion','installTarget'].includes(key))||(!input.itemId&&!input.packageName)||
+      if(Object.keys(input).some(key=>!['itemId','packageName','contractVersion','installTarget'].includes(key)&&!(versionSelection&&key==='version'))||(!input.itemId&&!input.packageName)||
         (input.installTarget!==undefined&&(!input.itemId||!input.installTarget||typeof input.installTarget!=='object'||Array.isArray(input.installTarget)))||
         (input.itemId!==undefined&&(typeof input.itemId!=='string'||!input.itemId.length||input.itemId.length>160||/[\u0000-\u001f\u007f]/.test(input.itemId)))||
         (input.packageName!==undefined&&(typeof input.packageName!=='string'||input.packageName.length>214||!/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(input.packageName))))throw new Error('INVALID_INPUT');
       setTarget({status:'resolving',input:{...input}});
-      const query=targetQuery(input),resolved=await request('/hanamesh/library/target?'+query);
+      const query=targetQuery(input),resolved=await request((versionSelection?'/hanamesh/library/version-target?':'/hanamesh/library/target?')+query);
       if(sequence!==targetSequence)return{status:'superseded'};
       const item=resolved.item,op=pendingOperations[item.id];
       const status=op?.busy?'installing':['registered','installed','installed-not-loaded'].includes(item.installed?.state)&&!item.upgradeAvailable?'already-installed':'confirmation-required';
@@ -894,7 +925,7 @@ h('div',{className:'hm-source-add'},h('input',{value:draft,placeholder:'https://
   const KIND_TEXT={application:t('应用'),plugin:t('插件'),listing:t('仅收录')};
   const STATE_TEXT={registered:t('已安装'),installed:t('已安装'),'installed-not-loaded':t('需重启'),'uninstalled-not-unloaded':t('已卸载 · 需重启'),'runtime-missing':t('缺运行时'),invalid:t('包无效')};
   // Mirrors PROTECTED_PACKAGES on the host: the suite is never offered an uninstall button (the host answers 403 anyway).
-  const PROTECTED=new Set(['@hanamesh/hanamesh','@hanamesh/core','@hanamesh/usage','@hanamesh/dsh-app-host','hanamesh-brand']);
+  const PROTECTED=new Set(['@hanamesh/hanamesh','@hanamesh/core','@hanamesh/usage','@hanamesh/dsh-app-host','@hanamesh/brand']);
   function RestartNotice({reason}){useLocale();
     return h('p',{role:'status',className:'hm-restart-notice','data-hanamesh-restart':'required'},h('strong',null,t('需重新打开客户端')),' ',reason??t('插件更改需要重新打开客户端后生效。'),' ',h('span',{className:'hm-restart-hint'},t('请完全退出 HanaMesh 客户端或 DSH 后重新打开；关闭窗口不等于退出。')));
   }
@@ -941,6 +972,8 @@ h('div',{className:'hm-source-add'},h('input',{value:draft,placeholder:'https://
   Object.assign(COPY.en,{cl1Detail:'HanaMesh / Application details',cred0:'Not available',cred1:'No data available',cred2:'Public statistics',cred3:'DSH installs / 30 days',cred4:'Users / 30 days',cred5:'Signals updated: ',cred6:'Users updated: '});
   function LibraryOverlay({embedded,mainPage=false,preferredSubsectionId,verification=false}={}){useLocale();
     const[visible,setVisible]=React.useState(embedded?true:libraryVisible),[snapshot,setSnapshot]=React.useState(null),[error,setError]=React.useState(''),[receipt,setReceipt]=React.useState(null),[query,setQuery]=React.useState(''),[filter,setFilter]=React.useState(''),[extra,setExtra]=React.useState([]),[pending,updatePending]=React.useState(pendingOperations),[seenCategories,setSeenCategories]=React.useState([]),[changed,setChanged]=React.useState(false),[openingAppId,setOpeningAppId]=React.useState(null),[closing,setClosing]=React.useState(false);
+    const[versionLists,setVersionLists]=React.useState({});
+    const versionQueries=React.useRef(null);
     const[detailId,setDetailId]=React.useState(null),[acceptedTarget,setAcceptedTarget]=React.useState(null),[libraryTab,setLibraryTab]=React.useState('all'),[credibility,setCredibility]=React.useState(null);
     React.useEffect(()=>{let live=true;setCredibility(null);if(detailId&&visible)void readCredibility(snapshot?.source,{id:detailId}).then(value=>{if(live)setCredibility(value);});return()=>{live=false;};},[detailId,visible,snapshot?.source?.manifestUrl]);
     const[target,updateTarget]=React.useState(targetSelection),[targetItemId,setTargetItemId]=React.useState(''),[targetPackageName,setTargetPackageName]=React.useState('');
@@ -1010,6 +1043,16 @@ h('div',{className:'hm-source-add'},h('input',{value:draft,placeholder:'https://
     const load=React.useCallback(async()=>{try{setError('');setExtra([]);const page=await request('/hanamesh/library'+params());setSnapshot(page);remember(page);}catch(e){setError(e);}},[params]);
     const more=async()=>{try{const cursor=(extra.at(-1)??snapshot)?.page?.nextCursor;if(!cursor)return;const next=await request('/hanamesh/library'+params(cursor));setExtra(list=>[...list,next]);remember(next);}catch(e){if(String(e.message??e)==='CATALOG_CHANGED'){setSnapshot(null);setExtra([]);}setError(e);}};
     React.useEffect(()=>{if(visible)void load();},[visible,load]);
+    const versionDescriptor=item=>({id:item.id,key:JSON.stringify([snapshot?.source,snapshot?.versionQueries?.scope,item.package?.name,item.installed?.version??item.suite?.version??null]),automatic:item.kind==='suite'||Boolean(item.installed&&item.installTarget?.source==='npm')});
+    React.useEffect(()=>()=>{versionQueries.current?.close();versionQueries.current=null;},[]);
+    React.useEffect(()=>{
+      if(!visible||!snapshot?.versionQueries){if(versionQueries.current){versionQueries.current.close();versionQueries.current=null;if(!visible){setSnapshot(null);setExtra([]);setVersionLists({});}}return;}
+      const settings=snapshot.versionQueries,signature=JSON.stringify([settings.concurrency,settings.cacheMs]);
+      if(versionQueries.current?.signature!==signature){versionQueries.current?.close();versionQueries.current={...createVersionQueries({...settings,read:(id,signal)=>request('/hanamesh/library/versions?'+new URLSearchParams({itemId:id}),{signal}),notify:(id,value)=>setVersionLists(previous=>{const prior=previous[id]?.key===value.key?previous[id]:{};return{...previous,[id]:{...prior,...value,...(value.versions?{selected:prior.selected??value.versions.find(row=>row.compatible&&row.version!==value.installedVersion)?.version??''}:{})}};})}),signature};}
+      const all=[snapshot,...extra].flatMap(page=>page?.items??[]),shown=filter==='plugin'?all.filter(item=>item.kind==='plugin'||item.kind==='suite'):all;
+      versionQueries.current.reconcile(shown.map(versionDescriptor));
+    },[visible,snapshot,extra,filter]);
+
     React.useEffect(()=>{if(visible&&['installed','installed-live'].includes(target?.status))void load();},[visible,load,target?.status]);
     // rc.18: install/provision/uninstall are 202 + events. Track the operation per card so the user sees
     // 「安装中…」 and, on failure, the code with a readable reason (user 2026-09-20: clicked install, nothing happened).
@@ -1023,15 +1066,15 @@ h('div',{className:'hm-source-add'},h('input',{value:draft,placeholder:'https://
       const selected=targetSelection;if(selected?.status!=='confirmation-required'||acceptedTarget!==selected||pendingOperations[selected.item.id]?.busy)return;
       setTarget({...selected,status:'installing'});
       const suite=selected.item.kind==='suite-upgrade';
-      const reviewed={itemId:selected.item.id,packageName:selected.item.package.name,...(selected.item.installTarget?{installTarget:selected.item.installTarget}:{})};
-      const outcome=await operate(suite?'/hanamesh/library/suite/upgrade':'/hanamesh/library/install',suite?{planId:selected.item.suiteUpgrade.planId}:reviewed,selected.item.id,suite?t('升级套件'):t('安装'),true);
+      const reviewed={itemId:selected.item.id,packageName:selected.item.package.name,...(selected.item.installTarget?{installTarget:selected.item.installTarget}:{}),...(selected.item.selectedVersion?{version:selected.item.selectedVersion}:{})};
+      const outcome=await operate(suite?'/hanamesh/library/suite/upgrade':selected.item.selectedVersion?'/hanamesh/library/version/install':'/hanamesh/library/install',suite?{planId:selected.item.suiteUpgrade.planId}:reviewed,selected.item.id,suite?t('升级套件'):t('安装'),true);
       if(outcome){
         if(!outcome.ok){if(targetSelection?.item?.id===selected.item.id)setTarget({...targetSelection,status:outcome.unknown?'result-unavailable':suite?'suite-upgrade-failed':'failed',error:outcome.code,details:outcome.details});return;}
         if(suite){
-          try{const snapshot=await request('/hanamesh/library/installedPlugins');if(!outcome.result.components.every(c=>snapshot.plugins.some(p=>p.packageName===c.name&&p.version===c.to&&p.active)))throw new Error('INSTALL_READBACK_MISMATCH');setPending(p=>({...p,[selected.item.id]:{label:t("升级套件"),text:()=>(t('套件升级已读回，请完全退出并重新打开客户端。'))}}));setChanged(true);setTarget({...selected,status:'installed'});}
+          try{const snapshot=await request('/hanamesh/library/suite/status');if(snapshot.status!=='installed'||snapshot.version!==outcome.result.version||!outcome.result.components.every(c=>snapshot.components.some(p=>p.name===c.name&&p.version===c.to&&p.active)))throw new Error('INSTALL_READBACK_MISMATCH');setPending(p=>({...p,[selected.item.id]:{label:t("升级套件"),text:()=>(t('套件升级已读回，请完全退出并重新打开客户端。'))}}));setChanged(true);setTarget({...selected,status:'installed'});}
           catch(error){setPending(p=>({...p,[selected.item.id]:{label:t("升级套件"),text:()=>(t('套件版本读回失败，请检查三个组件。')),failed:true}}));setTarget({...selected,status:'readback-failed',error:String(error.message??error)});}return;
         }
-        try{const fresh=await request('/hanamesh/library/target?'+targetQuery(reviewed));
+        try{const fresh=await request((selected.item.selectedVersion?'/hanamesh/library/version-target?':'/hanamesh/library/target?')+targetQuery(reviewed));
           const row=fresh.item?.installed;
           if(row?.packageName!==selected.item.package.name||!['registered','installed','installed-not-loaded'].includes(row.state)||(outcome.result?.version&&row.version!==outcome.result.version))throw new Error('INSTALL_READBACK_MISMATCH');
           const live=outcome.result?.status==='applied';setPending(p=>({...p,[selected.item.id]:{label:t("安装"),text:()=>(live?t('安装完成，已加载，可以直接使用（已按精确版本读回）')+baselineText(outcome.result):t('安装完成，已按精确版本读回'))}}));if(!live)setChanged(true);
@@ -1078,15 +1121,33 @@ h('div',{className:'hm-source-add'},h('input',{value:draft,placeholder:'https://
     };
     const close=async()=>{if(closing)return;setClosing(true);try{await heldView.current?.close();setReceipt(null);setError('');}catch(e){setError(e);}finally{if(mounted.current)setClosing(false);}};
     if(!visible)return null;
-    const pages=[snapshot,...extra].filter(Boolean),all=pages.flatMap(page=>page.items??[]),items=filter==='plugin'?all.filter(item=>item.kind==='plugin'||item.kind==='suite'):all,installed=snapshot?.installed??[],plugins=snapshot?.plugins??[],nextCursor=(extra.at(-1)??snapshot)?.page?.nextCursor??null;
+    const pages=[snapshot,...extra].filter(Boolean),all=pages.flatMap(page=>page.items??[]),items=(filter==='plugin'?all.filter(item=>item.kind==='plugin'||item.kind==='suite'):all).map(item=>{const state=versionLists[item.id];return state&&(!state.key||state.key===versionDescriptor(item).key)?{...item,...(Object.hasOwn(state,'latestVersion')?{latestVersion:state.latestVersion,upgradeAvailable:state.upgradeAvailable??item.upgradeAvailable}:{}),versionError:state.error??item.versionError}:item;}),installed=snapshot?.installed??[],plugins=snapshot?.plugins??[],nextCursor=(extra.at(-1)??snapshot)?.page?.nextCursor??null;
     const restartRequired=changed||Boolean(snapshot?.restartRequired);
     const filters=[...BASE_FILTERS,...seenCategories.filter(c=>c!=='hanamesh-app').map(c=>[c,c])];
     const openButton=row=>h('button',{type:'button',disabled:Boolean(openingAppId),onClick:()=>void open(row)},openingAppId===row.appId?t('打开中…'):t('打开'));
+    const reviewVersion=(item,version)=>openInstallTarget({itemId:item.kind==='suite'?'hanamesh:suite-upgrade':item.id,version},{versionSelection:true}).catch(()=>{});
+    const versionControls=item=>{
+      if(item.kind!=='suite'&&item.installTarget?.source!=='npm')return null;
+      const saved=versionLists[item.id],state=saved?.key&&saved.key!==versionDescriptor(item).key?undefined:saved;
+      const read=async()=>{
+        const descriptor=versionDescriptor(item);
+        setVersionLists(previous=>({...previous,[item.id]:{...(previous[item.id]?.key===descriptor.key?previous[item.id]:{}),key:descriptor.key,expanded:true}}));
+        if(versionQueries.current){void versionQueries.current.read(descriptor).catch(()=>{});return;}
+        setVersionLists(previous=>({...previous,[item.id]:{...previous[item.id],loading:true}}));
+        try{const result=await request('/hanamesh/library/versions?'+new URLSearchParams({itemId:item.id}));setVersionLists(previous=>({...previous,[item.id]:{...result,expanded:true,selected:result.versions.find(row=>row.compatible&&row.version!==item.installed?.version)?.version??''}}));}
+        catch(error){setVersionLists(previous=>({...previous,[item.id]:{expanded:true,error:String(error.message??error)}}));}
+      };
+      return h('div',{className:'hm-plugin-versions'},
+        item.latestVersion?h('p',{'data-hanamesh-latest-version':item.latestVersion},t('最新兼容版本：')+item.latestVersion):item.versionError?h('p',{role:'alert'},t('版本查询失败：')+item.versionError):null,
+        h('button',{type:'button',disabled:state?.loading,onClick:()=>void read()},t(state?.loading?'正在读取版本…':'选择历史版本')),
+        state?.error&&state.error!==item.versionError?h('p',{role:'alert'},t('版本查询失败：')+state.error):null,
+        state?.expanded&&state?.versions?h('div',null,h('select',{'aria-label':t('插件版本'),value:state.selected,onChange:event=>setVersionLists(previous=>({...previous,[item.id]:{...previous[item.id],selected:event.target.value}}))},h('option',{value:'',disabled:true},t('插件版本')),...state.versions.map(row=>h('option',{key:row.version,value:row.version,disabled:!row.compatible||row.version===item.installed?.version},row.version+(row.compatible?'':' · '+t('不兼容'))))),h('button',{type:'button',disabled:!state.selected,onClick:()=>void reviewVersion(item,state.selected)},t('安装所选版本'))):null);
+    };
     const card=(item,detail=false)=>{const row=item.installed,op=pending[item.id],busy=op?.busy;const installBody={itemId:item.id,...(item.package?.name?{packageName:item.package.name}:{}),...(item.installTarget?{installTarget:item.installTarget}:{})};
-      const reviewOrInstall=label=>item.installTarget?openInstallTarget(installBody).catch(()=>{}):operate('/hanamesh/library/install',installBody,item.id,label);
+      const reviewOrInstall=label=>row&&item.latestVersion?reviewVersion(item,item.latestVersion):item.installTarget?openInstallTarget(installBody).catch(()=>{}):operate('/hanamesh/library/install',installBody,item.id,label);
       let action=h('span',null,t('仅收录，不可安装')),state=null;
       if(row)state=h('span',{className:'hm-market-state','data-hanamesh-state':row.state},(t(STATE_TEXT[row.state]??row.state))+(row.version?' '+row.version:''));
-      if(item.kind==='suite')return h('article',{key:item.id,'data-hanamesh-library-item':item.id,'data-hanamesh-kind':'suite'},h('h3',null,t('HanaMesh 套件')),h('p',null,item.summary),h('p',null,item.suite?.status==='installed'?t('已安装 · HanaMesh ')+item.suite.version:item.suite?.status==='incomplete'?t('套件不完整，请查看组件状态'):t('套件状态未知，请查看 Core 声明与阻断原因')),item.suite?.completeness?h('p',null,t('Core 完整性：')+item.suite.completeness):null,...(item.suite?.components??[]).map(c=>h('p',{key:c.name},c.requiredRange?c.label+t(' · 要求 ')+c.requiredRange+t(' · 实际 ')+(c.actualVersion??t('检测不到'))+' · '+c.status:c.label+' · '+(c.version??t('检测不到'))+(c.active?'':t(' · 未启用')))),...(item.suite?.blocked??[]).map((row,i)=>h('p',{key:'blocked-'+i,role:'status'},row.code+(row.moduleName?' · '+row.moduleName:'')+(row.bundleVersion?' · HanaMesh '+row.bundleVersion:''))),item.suiteUpgradeUnavailable?h('p',{role:'status'},item.suiteUpgradeUnavailable):null,h('button',{type:'button',disabled:Boolean(item.suiteUpgradeUnavailable),onClick:()=>void openInstallTarget({itemId:'hanamesh:suite-upgrade'}).catch(()=>{})},t('检查兼容升级')));
+      if(item.kind==='suite')return h('article',{key:item.id,'data-hanamesh-library-item':item.id,'data-hanamesh-kind':'suite'},h('h3',null,t('HanaMesh 套件')),h('p',null,item.summary),h('p',null,item.suite?.status==='installed'?t('已安装 · HanaMesh ')+item.suite.version:item.suite?.status==='incomplete'?t('套件不完整，请查看组件状态'):t('套件状态未知，请查看 Core 声明与阻断原因')),item.suite?.completeness?h('p',null,t('Core 完整性：')+item.suite.completeness):null,...(item.suite?.components??[]).map(c=>h('p',{key:c.name},c.requiredRange?c.label+t(' · 要求 ')+c.requiredRange+t(' · 实际 ')+(c.actualVersion??t('检测不到'))+' · '+c.status:c.label+' · '+(c.version??t('检测不到'))+(c.active?'':t(' · 未启用')))),...(item.suite?.blocked??[]).map((row,i)=>h('p',{key:'blocked-'+i,role:'status'},row.code+(row.moduleName?' · '+row.moduleName:'')+(row.bundleVersion?' · HanaMesh '+row.bundleVersion:''))),item.suiteUpgradeUnavailable?h('p',{role:'status'},item.suiteUpgradeUnavailable):null,versionControls(item),h('button',{type:'button',disabled:busy||Boolean(item.suiteUpgradeUnavailable),onClick:()=>void (item.latestVersion&&item.upgradeAvailable?reviewVersion(item,item.latestVersion):openInstallTarget({itemId:'hanamesh:suite-upgrade'})).catch(()=>{})},t(item.upgradeAvailable?'升级':'检查兼容升级')),!detail?h('button',{type:'button',onClick:()=>setDetailId(item.id)},t('详情')):null,op?operationNotice(op):null);
       if(busy)action=h('button',{type:'button',disabled:true},t(op.text));
       else if(item.kind!=='listing'&&!row)action=h('button',{type:'button',onClick:()=>void reviewOrInstall(t('安装'))},op?.failed?t('重试安装'):t('安装'));
       else if(row&&item.upgradeAvailable)action=h('span',{className:'hm-market-actions'},h('button',{type:'button',onClick:()=>void reviewOrInstall(t('升级'))},item.installTarget?.source==='github'?t('查看安装目标'):t('升级')),row.state==='registered'?openButton(row):null);
@@ -1098,7 +1159,7 @@ h('div',{className:'hm-source-add'},h('input',{value:draft,placeholder:'https://
       return h('article',{key:item.id,'data-hanamesh-library-item':item.id,'data-hanamesh-kind':item.kind,className:detail?'hm-app-detail':'hm-app-card'},detail&&mainPage?null:h('h3',null,item.displayName),detail&&mainPage?null:h('p',null,item.summary),
         detail?h('div',{className:'hm-app-detail-content'},h('h4',null,t('关于这个应用')),h('p',null,item.description||item.summary),h('h4',null,t('可信度')),h('div',{className:'hm-credibility'},...credibilityFacts(credibility?.itemId===item.id?credibility:null).map(row=>h('div',{key:row.id},h('span',null,t(row.label)),h('strong',{'data-hanamesh-credibility':row.id},row.value===null?t('暂无'):row.value.toLocaleString()),h('small',null,row.value===null?t('当前暂无数据'):t('公开统计'))))),h('p',{className:'hm-market-state'},t('可信度数据缺失不代表 0；本机安装状态与平台采用度分别显示。')),credibility?.checkedAt?h('small',null,t('信号更新：')+credibility.checkedAt):null,credibility?.asOf?h('small',null,t('使用人数更新：')+credibility.asOf):null,h('h4',null,t('来源与安装目标')),h('p',null,item.package?.name??t('仅收录，不可安装')),item.installTarget?h('code',null,item.installTarget.source==='github'?'https://github.com/'+item.installTarget.repo+' @ '+item.installTarget.ref:item.installTarget.name+' @ '+item.installTarget.version):null,...(item.source?.sourceLinks??[]).map((link,index)=>h('p',{key:index},h('a',{href:link.sourceUrl,target:'_blank',rel:'noopener noreferrer'},link.sourceId+' · '+link.sourceRef))),catalogWebsiteLink(snapshot?.source,item)?h('a',{href:catalogWebsiteLink(snapshot?.source,item),target:'_blank',rel:'noopener noreferrer',className:'hm-website-link'},t('在网站查看')):null):null,
         h('small',null,t(KIND_TEXT[item.kind])+' · '+(item.publisher?.name??t('未知发布者'))+((item.categories??[]).length?' · '+item.categories.join('、'):'')),
-        state,h('div',{className:'hm-market-actions'},action,!detail?h('button',{type:'button',onClick:()=>setDetailId(item.id)},t('详情')):null),op&&!busy?operationNotice(op):null);};
+        state,versionControls(item),h('div',{className:'hm-market-actions'},action,!detail?h('button',{type:'button',onClick:()=>setDetailId(item.id)},t('详情')):null),op&&!busy?operationNotice(op):null);};
     const detailItem=items.find(item=>item.id===detailId);
     const catalogSection=receipt?h('div',{className:'hm-app-frame'},h('div',null,h('strong',null,receipt.instance.appId),h('button',{type:'button',disabled:closing,onClick:()=>void close()},closing?t('关闭中…'):t('关闭视图'))),h('iframe',{ref:frame,src:receipt.uiUrl,title:receipt.instance.appId,sandbox:'allow-forms allow-modals allow-popups allow-same-origin allow-scripts'})):
       detailItem?h('div',{key:'detail'},h('button',{type:'button',onClick:()=>setDetailId(null)},t('返回应用库')),card(detailItem,true)):h('div',{className:'hm-library-grid',key:'catalog'},...items.map(item=>card(item)),snapshot&&items.length===0?h('p',{role:'status'},t('没有找到符合条件的应用。')):null);
@@ -1126,7 +1187,8 @@ h('div',{className:'hm-source-add'},h('input',{value:draft,placeholder:'https://
           target.item?.installTarget?.source==='npm'?h('dl',{'data-npm-confirmation':true},h('dt',null,t('精确版本')),h('dd',null,target.item.installTarget.version)):null,
           target.item?.installTarget?.source==='github'?h('dl',{'data-github-confirmation':true},h('dt',null,t('来源仓库')),h('dd',null,'https://github.com/'+target.item.installTarget.repo),h('dt',null,t('固定 commit')),h('dd',null,target.item.installTarget.ref),...(target.item.installTarget.path?[h('dt',null,t('仓库子目录')),h('dd',null,target.item.installTarget.path)]:[])):null,
           target.item?.installTarget?(target.item.installTarget.allowBuild.length?h('div',{role:'alert','data-build-warning':true},h('strong',null,t('会在本机执行构建脚本')),h('p',null,target.item.installTarget.allowBuild.join(', ')),h('p',null,t('确认后将按名单允许构建；pnpm 会把许可保存到当前 profile。'))):h('p',null,t('未授予构建脚本许可'))):null,
-          target.item?.suiteUpgrade?h('ul',null,...target.item.suiteUpgrade.components.map(c=>h('li',{key:c.name},c.label+'：'+c.from+' → '+c.to)),h('li',null,t('确认后升级 HanaMesh 总包及其锁定组件；需要完全退出并重新打开客户端。'))):null,
+          target.item?.suiteUpgrade?h('dl',{'data-suite-confirmation':true},h('dt',null,t('精确版本')),h('dd',null,target.item.suiteUpgrade.bundle.from+' → '+target.item.suiteUpgrade.bundle.to)):null,
+          target.item?.suiteUpgrade?h('ul',null,...target.item.suiteUpgrade.components.map(c=>h('li',{key:c.name},c.label+'：'+c.from+' → '+c.to)),h('li',null,t('确认后安装 HanaMesh 总包及其兼容组件；需要完全退出并重新打开客户端。'))):null,
           target.item?.suiteUpgrade?.registry?h('p',null,'Registry：'+target.item.suiteUpgrade.registry):null,
           ...(target.item?.suiteUpgrade?.blocked??target.details?.blocked??[]).map((row,i)=>h('p',{key:'suite-blocked-'+i,role:'status'},row.code+(row.moduleName?' · '+row.moduleName:'')+(row.bundleVersion?' · HanaMesh '+row.bundleVersion:''))),
           target.status==='confirmation-required'?h('div',null,h('label',{className:'hm-install-ack'},h('input',{type:'checkbox','aria-label':t('我已核对来源与安装目标'),checked:acceptedTarget===target,onChange:event=>setAcceptedTarget(event.currentTarget.checked?target:null)}),t('我已核对来源与安装目标')),h('button',{type:'button',disabled:acceptedTarget!==target,onClick:()=>void confirmTarget()},t('确认安装')),h('button',{type:'button',onClick:()=>{targetSequence++;void reportHandoff(targetSelection?.handoffId,'cancelled');setTarget({...targetSelection,status:'cancelled'});}},t('取消'))):

package/dist/dsh.d.ts

@@ -12,7 +12,7 @@ export interface DshPluginConfig {
   /** `sources` undefined → the HanaMesh catalog source; explicit `[]` → none. `profileDir`/`profileName`/`dshBin` (and
    *  `nodeBinary`) are inferred from the proven Desktop layout or plain DSH when undefined — see docs/CONTRACT.md 「应用库配置」; explicit values win. */
   /** rc.28: the same keys serve the HanaMesh market (plugins + applications; routes `/hanamesh/library*`, see docs/CONTRACT.md「市场」). */
-  library?:{fixture?:string;sources?:Array<{manifestUrl:string;enabled?:boolean}>;profileDir?:string;profileName?:string;dshBin?:string;registry?:string;eventRetention?:number};
+  library?:{fixture?:string;sources?:Array<{manifestUrl:string;enabled?:boolean}>;profileDir?:string;profileName?:string;dshBin?:string;registry?:string;versionLookupTimeoutMs?:number;versionLookupMaxBytes?:number;versionLookupConcurrency?:number;versionLookupCacheMs?:number;eventRetention?:number};
   applications?: AppDefinition[]; leaseTtlMs?: number; sweepIntervalMs?: number;
 }
 /** Adapt an open `ctx.storageDomain` handle (single layout, global snapshot) to the store binding. */

package/dist/dsh.js

@@ -1,5 +1,5 @@
 import {pathToFileURL} from 'node:url';
-import { createInstallationStatusReader } from './library/installation-status.js';
+import { createInstallationStatusReader,officialDshDesktopProfile } from './library/installation-status.js';
 /**
  * DSH plugin entry for @hanamesh/dsh-app-host, using the public APIs audited in
  * official DSH 0.2.0-rc.2 and 0.2.1-alpha.2:
@@ -31,6 +31,7 @@ import { createProviderSources } from './router/sources.js';
 import { createRouter } from './router/broker.js';
 import { createRouterHttpHandler, ROUTER_ROUTES } from './router/routes.js';
 import { libraryDomainSpec } from './library/domain.js';
+import {createNpmVersionCatalog,hostVersionReader} from './library/versions.js';
 import { createLibraryService } from './library/service.js';
 import { createLibraryInstaller } from './library/install.js';
 import { inferDesktopLayout, resolveLibraryLocations } from './library/locate.js';
@@ -74,6 +75,10 @@ export const Config = z.object({
     /** Locations are inferred from the verified Desktop argv/profile or plain DSH (see library/locate.js). */
     profileDir:z.string(),profileName:z.string(),dshBin:z.string(),
     registry:z.string(),
+    versionLookupConcurrency:z.number().min(1).max(16).default(4),
+    versionLookupCacheMs:z.number().min(1).max(2147483647).default(30000),
+    versionLookupTimeoutMs:z.number().min(1).max(2147483647).default(30000),
+    versionLookupMaxBytes:z.number().min(1).default(16777216),
     /** Publicly named event history capacity; a lost cursor reports resetRequired. */
     eventRetention:z.number().default(512),
     /** Website → client handoff listener (library/handoff.js). Unset fields use the defaults shown in the library
@@ -130,7 +135,13 @@ export async function apply(ctx, config) {
   config ??= {};
   const dataRoot = config.dataRoot ?? join(process.env.DSH_HOME ?? process.env.HOME ?? '.', 'data', 'hanamesh-apps');
   requireCondition(typeof dataRoot === 'string', 'INVALID_ROOT', 'dataRoot is required.');
-  const desktop = await inferDesktopLayout();
+  // The payload Node probe may wait for a cold OS start; unloading the plugin kills it instead of waiting.
+  // Cordis runs effect cleanups only after apply() returns, so the cancel listens for this fiber's disposal
+  // (Cordis emits internal/plugin with uid cleared as soon as dispose() starts).
+  const layoutProbe = new AbortController();
+  ctx.on('internal/plugin', fiber => { if (fiber === ctx.fiber && fiber.uid === null) layoutProbe.abort(); });
+  const desktop = await inferDesktopLayout({ signal: layoutProbe.signal });
+  if (layoutProbe.signal.aborted) return; // unloaded during the probe: acquire nothing
   const transportOrigin = `http://127.0.0.1:${webServer.port}`;
   const parentOrigin = config.parentOrigin ?? desktop?.parentOrigin ?? transportOrigin;
   const frameAncestors = config.frameAncestors ?? desktop?.frameAncestors ?? [];
@@ -258,7 +269,9 @@ export async function apply(ctx, config) {
     };
     const identity=await detectClient({desktop});
     if(typeof ctx.logger?.info==='function')ctx.logger.info('hanamesh-app-host library: client %s (%s)',identity.client,identity.evidence);
-    library=createLibraryService({domain:{global:libraryDomain.global,close:closeLibraryDomain},host,config:libraryConfig,dataRoot,ledgerReader:provisionApi?.ledger??(async()=>({schema:1,items:{}})),installer,client:identity.client,unavailable,suiteSourceService:()=>suiteSourceService,installationStatus:nodeStatusBinding(()=>nodeRuntime.executable,workerNode=>createInstallationStatusReader({client:identity.client,core:()=>coreService,workerNode})),logger:ctx.logger});
+    const versionAnchor=desktop?.runtimeDir?join(desktop.runtimeDir,'package.json'):dshBin;
+    const versionCatalog=versionAnchor?createNpmVersionCatalog({registry:libraryConfig.registry||undefined,anchor:versionAnchor,peerVersion:hostVersionReader(versionAnchor),timeoutMs:libraryConfig.versionLookupTimeoutMs,maxBytes:libraryConfig.versionLookupMaxBytes}):undefined;
+    library=createLibraryService({versionCatalog,domain:{global:libraryDomain.global,close:closeLibraryDomain},host,config:libraryConfig,dataRoot,ledgerReader:provisionApi?.ledger??(async()=>({schema:1,items:{}})),installer,client:identity.client,unavailable,suiteSourceService:()=>suiteSourceService,installationStatus:nodeStatusBinding(()=>nodeRuntime.executable,workerNode=>createInstallationStatusReader({client:identity.client,core:()=>coreService,workerNode,otherProfileDir:identity.client==='hanamesh'?()=>officialDshDesktopProfile(locations.profileDir):null})),logger:ctx.logger});
     own('library', () => library.close());
     await library.init();
     // rc.27: app bundles register plain `app.json` (no package name); the installed scan knows which npm package ships

package/dist/installation-status.d.ts

@@ -3,7 +3,7 @@ export const INSTALLATION_STATUS_CAPABILITY:Readonly<{contract:'hanamesh.install
 export interface InstallationStatusRequest {contractVersion:'1';consent:'read-installations'}
 export interface InstallationObservation {
  channel:'hanamesh'|'dsh'|'claude'|'codex';
- scope:{id:'current-runtime'|'other-runtime'|'agent-cli'|'desktop-app';kind:'responding-runtime'|'unobserved-runtime'|'official-user-profile'|'desktop-app';label:string};
+ scope:{id:'current-runtime'|'other-runtime'|'agent-cli'|'desktop-app';kind:'responding-runtime'|'other-client'|'official-user-profile'|'desktop-app';label:string};
  status:'installed'|'not-installed'|'incomplete'|'unknown';version:string|null;versionKind:'suite-bundle'|'agent-distribution';
  components:readonly {name:string;version:string|null;active?:boolean;status?:string}[];
  identity:{pluginName:string;marketplace:string}|null;

package/dist/library/install.js

@@ -1,5 +1,5 @@
 import { readFile, lstat, unlink, rmdir } from 'node:fs/promises';
-import { join, resolve, dirname, sep, delimiter } from 'node:path';
+import { join, resolve, dirname, sep, delimiter, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {safeGitEnv,guardNodeBinary,spawnGitSafe} from '../git-process.js';
 import { randomUUID } from 'node:crypto';
@@ -14,7 +14,7 @@ import {SUITE_BUNDLE,prepareSuiteUpgrade,readSuiteStatus,createCoreSuiteAdapter}
 import {packageInstallTarget,installTargetName,pinnedGithubSpec} from './github-target.js';
 
 /** Suite packages are changed only by the confirmed suite upgrade command. */
-export const PROTECTED_PACKAGES=Object.freeze([SUITE_BUNDLE,'@hanamesh/core','@hanamesh/usage','@hanamesh/dsh-app-host','hanamesh-brand']);
+export const PROTECTED_PACKAGES=Object.freeze([SUITE_BUNDLE,'@hanamesh/core','@hanamesh/usage','@hanamesh/dsh-app-host','@hanamesh/brand']);
 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);
 async function json(path){return JSON.parse(await readFile(path,'utf8'));}
@@ -67,7 +67,9 @@ export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBina
   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);
   const run=args=>runCli(['plugin','--profile',profileName,...args]);
   async function runCli(tail){try{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)})};
+    const dataHome=process.env.XDG_DATA_HOME;
+    const dataEnv=typeof dataHome==='string'&&isAbsolute(dataHome)&&!/[\x00-\x1f]/.test(dataHome)?{XDG_DATA_HOME:dataHome}:{};
+    const options={cwd:profileDir,workerNode:supervisorNode,env:safeGitEnv({...dataEnv,HOME:process.env.HOME,DSH_HOME:process.env.DSH_HOME,LANG:process.env.LANG??'C.UTF-8',PATH:commandPath(nodeBinary??desktopLauncher.command)})};
     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);
     const clean=text=>redact(stripVTControlCharacters(String(text??''))).replace(/(https?:\/\/)[^/\s@]+@/g,'$1[REDACTED]@').slice(-2000);
@@ -118,10 +120,10 @@ export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBina
     try{
       base=await profileSnapshot(profileDir,name);
       stage='before-add';let version;const target=item.installTarget,github=target?.source==='github';
-      if(target.source==='npm'){version=target.version;installRegistry=registry??null;}
+      if(target.source==='npm'){version=target.version;installRegistry=context?.registry??registry??null;}
       const spec=github?pinnedGithubSpec(target.repo,target.ref,target.path):`${name}@${version}`;
       const status='restart-required';
-      stage='add';await run(['add','--save-exact',...(installRegistry===null?[]:[`--registry=${installRegistry}`]),...(target?.allowBuild??[]).map(entry=>`--allow-build=${entry}`),spec]);
+      stage='add';if(context?.installation)await runCli(context.installation.args);else await run(['add','--save-exact',...(installRegistry===null?[]:[`--registry=${installRegistry}`]),...(target?.allowBuild??[]).map(entry=>`--allow-build=${entry}`),spec]);
       stage='readback';const added=await profileSnapshot(profileDir,name);
       if(github){
         const actual=await json(join(profileDir,'node_modules',...name.split('/'),'package.json'));
@@ -129,6 +131,7 @@ export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBina
           'INSTALL_READBACK_MISMATCH','The profile does not resolve and enable the reviewed GitHub package.',{expected:spec,spec:added.spec,packageName:actual.name,active:added.bundles.includes(name)},502);
         version=actual.version;
       }else 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(context?.verify)await context.verify();
       if(kind==='plugin')return{status,kind,packageName:name,version,...(target?{installTarget:target}:{}),...(github?{commit:target.ref}:{})};
       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)};
@@ -144,9 +147,11 @@ export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBina
   }
   let suitePlan;
   const suiteProvider=coreSuitePlan??createCoreSuiteAdapter({core:coreService,registry,profileName,suiteSourceMode,suiteSourceService});
-  async function previewSuite(){
-    const next=await prepareSuiteUpgrade({coreSuitePlan:suiteProvider});
-    suitePlan={...next,planId:randomUUID()};return structuredClone(suitePlan);
+  // Display reads validate the same Core composition without registering an execution confirmation.
+  const readSuite=({bundleVersion}={})=>prepareSuiteUpgrade({coreSuitePlan:suiteProvider,...(bundleVersion===undefined?{}:{bundleVersion})});
+  async function previewSuite({bundleVersion}={}){
+    const next=await readSuite({bundleVersion});
+    suitePlan={...next,requestedVersion:bundleVersion??null,planId:randomUUID()};return structuredClone(suitePlan);
   }
   return{
     get suiteUpgradeUnavailable(){return suiteProvider.unavailable??null;},
@@ -154,22 +159,23 @@ export function createLibraryInstaller({profileDir,profileName,dataRoot,nodeBina
       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')+'）'};}
     },
+    readSuiteUpgrade:readSuite,
     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 fresh=await prepareSuiteUpgrade({coreSuitePlan:suiteProvider,...(confirmed.requestedVersion===null?{}:{bundleVersion:confirmed.requestedVersion})});
       const identity=plan=>JSON.stringify({installation:plan.installation,sourceBinding:plan.sourceBinding,bundle:plan.bundle,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'&&before.version===fresh.bundle.from&&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});
+      const executing=await prepareSuiteUpgrade({coreSuitePlan:suiteProvider,...(confirmed.requestedVersion===null?{}:{bundleVersion:confirmed.requestedVersion})});
       requireCondition(identity(executing)===identity(confirmed),'SUITE_PLAN_CHANGED','执行前套件安装包来源或声明已变化，请重新查看并确认。',{},409);
       emit({type:'library.install-started',itemId:'hanamesh:suite-upgrade',packageName:SUITE_BUNDLE,kind:'suite-upgrade'});
       try{
-        await runCli(fresh.installation.args);
+        await transaction({id:'hanamesh:suite-upgrade',package:{name:SUITE_BUNDLE},installTarget:{source:'npm',name:SUITE_BUNDLE,version:fresh.bundle.to,allowBuild:[]}},'plugin',{registry:fresh.registry,installation:fresh.installation,verify:async()=>{const actual=await readSuiteStatus(profileDir);requireCondition(actual.status==='installed'&&actual.version===fresh.bundle.to&&fresh.components.every((c,i)=>actual.components[i]?.version===c.to),'INSTALL_READBACK_MISMATCH','Suite component readback differs from the confirmed versions.',{},502);}});
         const actual=await readSuiteStatus(profileDir);
         const saved=await json(join(profileDir,'package.json'));
         requireCondition(actual.status==='installed'&&actual.version===fresh.bundle.to&&saved.dependencies?.[SUITE_BUNDLE]===fresh.bundle.to&&fresh.components.every((c,i)=>actual.components[i]?.version===c.to),'INSTALL_READBACK_MISMATCH','套件升级后的版本或启用状态不符，请完全退出后按补齐命令修复。',{},502);

package/dist/library/installation-cli.js

@@ -22,7 +22,8 @@ export function installationEnvironment(source,platform=process.platform){
 const fail=code=>{throw new AppHostError(code,'The automatically discovered official installation reader could not complete.',{},503)};
 export const MINIMUM_READER_VERSIONS=Object.freeze({claude:'2.1.301',codex:'0.162.1'});
 export function readerVersionFailure(channel,output){
- const pattern=channel==='claude'?/^(\d+\.\d+\.\d+) \(Claude Code\)$/:/^codex-cli (\d+\.\d+\.\d+)$/;
+ // SemVer prerelease is allowed: desktop apps bundle prerelease CLIs (ChatGPT.app: codex-cli 0.167.0-alpha.3.2).
+ const pattern=channel==='claude'?/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?) \(Claude Code\)$/:/^codex-cli (\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/;
  const version=pattern.exec(output.trim())?.[1];
  if(!version||semver.valid(version)!==version)return 'AGENT_READER_VERSION_INVALID';
  return semver.gte(version,MINIMUM_READER_VERSIONS[channel])?null:'AGENT_READER_VERSION_UNSUPPORTED';

package/dist/library/installation-discovery.js

@@ -36,15 +36,26 @@ export async function readLoginEnvironment({home=homedir(),env=process.env,signa
  if(!value||typeof value!=='object'||Array.isArray(value)||typeof value.PATH!=='string'||!Object.entries(value).every(([key,path])=>INSTALLATION_ENV_KEYS.includes(key)&&typeof path==='string'&&!/[\x00-\x1f]/.test(path)))throw failure('AGENT_SHELL_ENV_UNAVAILABLE');
  return installationEnvironment(value);
 }
-export async function readLoginPath(options){return(await readLoginEnvironment(options)).PATH}
 
 /** Select once: inherited PATH, login PATH, then documented layouts; never try another CLI after execution. */
-export async function discoverOfficialReader({channel,home=process.env.HOME??process.env.USERPROFILE??homedir(),env=process.env,platform=process.platform,
- systemBinDirs=platform==='win32'?[]:['/opt/homebrew/bin','/usr/local/bin','/home/linuxbrew/.linuxbrew/bin','/usr/bin','/bin'],loginPath,signal,workerNode}={}){
+/** The official user profile directory each CLI reads (CLAUDE_CONFIG_DIR / CODEX_HOME, else ~/.claude / ~/.codex). */
+export function agentProfileDir({channel,home=process.env.HOME??process.env.USERPROFILE??homedir(),env=process.env}={}){
  if(!['claude','codex'].includes(channel)||!absolute(home))throw failure('AGENT_PROFILE_UNAVAILABLE');
- signal?.throwIfAborted();
  const configDir=env[channel==='claude'?'CLAUDE_CONFIG_DIR':'CODEX_HOME']??join(home,channel==='claude'?'.claude':'.codex');
  if(!absolute(configDir))throw failure('AGENT_PROFILE_UNAVAILABLE');
+ return configDir;
+}
+/** Read-only existence check: an absent profile directory holds no user-scope plugin; unreadable is not absence. */
+export async function agentProfileState({channel,home,env}={}){
+ const dir=agentProfileDir({channel,...(home===undefined?{}:{home}),...(env===undefined?{}:{env})});
+ try{if(!(await stat(dir)).isDirectory())throw failure('AGENT_PROFILE_UNAVAILABLE');return 'present'}
+ catch(error){if(['ENOENT','ENOTDIR'].includes(error.code))return 'absent';throw error.code==='AGENT_PROFILE_UNAVAILABLE'?error:failure('AGENT_PROFILE_UNAVAILABLE')}
+}
+export async function discoverOfficialReader({channel,home=process.env.HOME??process.env.USERPROFILE??homedir(),env=process.env,platform=process.platform,
+ systemBinDirs=platform==='win32'?[]:['/opt/homebrew/bin','/usr/local/bin','/home/linuxbrew/.linuxbrew/bin','/usr/bin','/bin'],
+ applicationDirs=platform==='darwin'?['/Applications',join(home,'Applications')]:[],loginPath,signal,workerNode}={}){
+ const configDir=agentProfileDir({channel,home,env});
+ signal?.throwIfAborted();
  const appData=env.APPDATA??join(home,'AppData','Roaming'),local=env.LOCALAPPDATA??join(home,'AppData','Local');
  const runtimeEnv=installationEnvironment(env,platform);
  const reader={home,configDir,...AGENT_INSTALLATION_TARGET,...INSTALLATION_READ_BUDGET,runtimeEnv};
@@ -81,7 +92,9 @@ export async function discoverOfficialReader({channel,home=process.env.HOME??pro
   ...[env.npm_config_prefix,env.NPM_CONFIG_PREFIX,join(home,'.npm-global'),join(home,'.npm')].filter(absolute).map(root=>platform==='win32'?root:join(root,'bin')),
   env.PNPM_HOME,...(absolute(env.PNPM_HOME)?[join(env.PNPM_HOME,'bin')]:[]),join(home,'.local','share','pnpm'),join(home,'.local','share','pnpm','bin'),join(home,'Library','pnpm'),join(home,'Library','pnpm','bin'),join(home,'.yarn','bin'),join(home,'.config','yarn','global','node_modules','.bin'),
   join(env.VOLTA_HOME??join(home,'.volta'),'bin'),join(asdf,'shims'),join(mise,'shims'),
-  ...(platform==='win32'?[join(appData,'npm'),join(local,'pnpm'),join(local,'Yarn','bin'),join(local,'Programs','OpenAI','Codex','bin'),join(local,'Microsoft','WinGet','Links'),join(local,'Volta','bin'),...(absolute(env.ProgramFiles)?[join(env.ProgramFiles,'nodejs')]:[])]:[]),...systemBinDirs];
+  ...(platform==='win32'?[join(appData,'npm'),join(local,'pnpm'),join(local,'Yarn','bin'),join(local,'Programs','OpenAI','Codex','bin'),join(local,'Microsoft','WinGet','Links'),join(local,'Volta','bin'),...(absolute(env.ProgramFiles)?[join(env.ProgramFiles,'nodejs')]:[])]:[]),...systemBinDirs,
+  // Desktop app bundles last, so a standalone CLI the user installed wins: ChatGPT.app ships the Codex CLI.
+  ...(channel==='codex'?applicationDirs.map(root=>join(root,'ChatGPT.app','Contents','Resources','codex-cli','bin')):[])];
  selected=await find(fixed);if(selected)return selected;
  const managed=[];
  for(const [root,suffix]of [[join(nvm,'versions','node'),['bin']],[env.NVM_HOME,[]],[join(fnm,'node-versions'),['installation',...(platform==='win32'?[]:['bin'])]],

package/dist/library/installation-status.js

@@ -1,9 +1,13 @@
 /** Read fresh public installation facts. No compatibility calculation, persistence or polling. */
 import semver from 'semver';
 import {AppHostError} from '../errors.js';
-import {SUITE_BUNDLE,createCoreSuiteAdapter,SUITE_PACKAGES} from './suite.js';
+import {readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {realpathSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {SUITE_BUNDLE,createCoreSuiteAdapter,SUITE_PACKAGES,readSuiteStatus} from './suite.js';
 import {readerVersionFailure,validReader,runOfficialInstallationCommand} from './installation-cli.js';
-import {discoverOfficialReader} from './installation-discovery.js';
+import {discoverOfficialReader,agentProfileState,AGENT_INSTALLATION_TARGET} from './installation-discovery.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});
@@ -17,10 +21,12 @@ const unknown=(row,code,message,action)=>({...row,status:'unknown',version:null,
 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 githubGitUrl(url){return typeof url==='string'&&/^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\.git$/.test(url)?url.slice(0,-4):url;}
+function codexMarketplaceUrl(source){return source?.sourceType==='git'?githubGitUrl(source.source):source?.sourceType==='url'?source.source:null;}
 function claudeMarketplaceUrl(value){
  if(value.source==='github'&&typeof value.repo==='string'&&/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value.repo))return `https://github.com/${value.repo}`;
  const url=['url','git'].includes(value.source)?value.url:null;
- return value.source==='git'&&typeof url==='string'&&/^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\.git$/.test(url)?url.slice(0,-4):url;
+ return value.source==='git'?githubGitUrl(url):url;
 }
 function parseInventory(channel,plugins,marketplaces,target){
  let rows,markets;
@@ -34,7 +40,7 @@ function parseInventory(channel,plugins,marketplaces,target){
  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'?claudeMarketplaceUrl(m):(['git','url'].includes(m.marketplaceSource?.sourceType)?m.marketplaceSource.source:null);
+ if(sourceRows.length){const m=sourceRows[0],url=channel==='claude'?claudeMarketplaceUrl(m):codexMarketplaceUrl(m.marketplaceSource);
   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}`;
@@ -47,7 +53,7 @@ function parseInventory(channel,plugins,marketplaces,target){
  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);
+  if(codexMarketplaceUrl(installedSource)!==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;
@@ -55,8 +61,27 @@ function parseInventory(channel,plugins,marketplaces,target){
   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_SHELL_ENV_UNAVAILABLE','AGENT_READER_DISCOVERY_INVALID','AGENT_READER_ENTRYPOINT_UNAVAILABLE','AGENT_READER_UNAVAILABLE','AGENT_READER_PERMISSION_DENIED','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']);
-/** Automatic current-user discovery only; `core` is the optional public protocol-1 Cordis service accessor. */
-export function createInstallationStatusReader({client='dsh',core=()=>undefined,workerNode,runCommand=runOfficialInstallationCommand,discoverReader=discoverOfficialReader}={}){
+/** Physical on-disk DSH profile inventory: no @hanamesh/hanamesh dependency (or no profile) is authoritative absence. */
+async function profileSuite(row,profileDir){
+ let profile;try{profile=JSON.parse(await readFile(join(profileDir,'package.json'),'utf8'))}
+ catch(error){if(['ENOENT','ENOTDIR'].includes(error.code))return{...row,status:'not-installed'};return unknown(row,'DSH_PROFILE_UNREADABLE','DSH 桌面版 profile 清单无法读取。','打开 DSH 确认其插件页可用后重新检测。')}
+ if(!object(profile)||!object(profile.dependencies))return unknown(row,'DSH_PROFILE_UNREADABLE','DSH 桌面版 profile 清单无法读取。','打开 DSH 确认其插件页可用后重新检测。');
+ if(!Object.hasOwn(profile.dependencies,SUITE_BUNDLE))return{...row,status:'not-installed'};
+ const value=await readSuiteStatus(profileDir);
+ const components=value.components.map(c=>({name:c.name,version:c.version,active:c.active}));
+ if(value.status==='installed'&&value.version)return{...row,status:'installed',version:value.version,components};
+ if(value.status==='unknown')return unknown(row,'DSH_PROFILE_UNREADABLE','DSH 桌面版 profile 清单无法读取。','打开 DSH 确认其插件页可用后重新检测。');
+ return{...row,status:'incomplete',version:value.version,components,reason:reason('DSH_PROFILE_SUITE_INCOMPLETE','DSH 桌面版 profile 中的 HanaMesh 套件缺组件或未启用。','在 DSH 插件页启用 HanaMesh，或按 DSH 安装说明重新安装总包后重启 DSH。')};
+}
+/** Official DSH desktop profile; only distinct, resolvable physical profiles may answer for another client. */
+export function officialDshDesktopProfile(ownProfileDir,home=homedir()){
+ const dir=join(home,'.dsh','profiles','desktop');
+ if(typeof ownProfileDir!=='string'||!ownProfileDir)return null;
+ try{return realpathSync(ownProfileDir)===realpathSync(dir)?null:dir}catch{return null}
+}
+/** Automatic current-user discovery only; `core` is the optional public protocol-1 Cordis service accessor.
+ * `otherProfileDir`: a fresh selector of the official DSH desktop profile (HanaMesh client only); trusted fixtures may supply a path. */
+export function createInstallationStatusReader({client='dsh',core=()=>undefined,workerNode,runCommand=runOfficialInstallationCommand,discoverReader=discoverOfficialReader,profileState=agentProfileState,otherProfileDir=null}={}){
  if(!['dsh','hanamesh'].includes(client))throw new TypeError('client must be dsh or hanamesh');
  const active=new Set();let closed=false;
  const suite=createCoreSuiteAdapter({core});
@@ -72,6 +97,7 @@ export function createInstallationStatusReader({client='dsh',core=()=>undefined,
  async function agent(channel,signal){
   const initial=agentBase(channel);let row=initial;
   try{
+   if(await abortable(profileState({channel}),signal)==='absent')return{...initial,status:'not-installed',identity:{pluginName:AGENT_INSTALLATION_TARGET.pluginName,marketplace:AGENT_INSTALLATION_TARGET.marketplace}};
    const config=await abortable(discoverReader({channel,signal,workerNode}),signal);
    if(!validReader(config))throw new AppHostError('AGENT_READER_DISCOVERY_INVALID','Invalid automatic reader.',{},503);
    row={...initial,identity:{pluginName:config.pluginName,marketplace:config.marketplace}};
@@ -85,11 +111,16 @@ export function createInstallationStatusReader({client='dsh',core=()=>undefined,
    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';const messages={AGENT_READER_UNAVAILABLE:'未在当前用户的 PATH 或常见安装位置找到官方 CLI。',AGENT_SHELL_ENV_UNAVAILABLE:'登录 shell 的 PATH 未能读取。',AGENT_PROFILE_UNAVAILABLE:'当前用户的官方资料目录不存在或不可访问。',AGENT_READER_TIMEOUT:'本次官方只读检测超时。',AGENT_INVENTORY_INVALID:'官方清单 JSON 不符合受支持的格式。',AGENT_READER_DISCOVERY_INVALID:'自动发现的官方 CLI 信息无效。',AGENT_READER_ENTRYPOINT_UNAVAILABLE:'已发现 Windows 命令入口，但官方 npm 程序文件缺失。'};return unknown(row,code,messages[code]??'本次官方清单读取未能提供完整且一致的安装事实。','在终端确认官方 CLI 可运行，并在其用户级插件页面检查清单、权限和市场来源后重新检测。')}
  }
+ async function other(signal){
+  const profileDir=client==='hanamesh'?(typeof otherProfileDir==='function'?otherProfileDir():otherProfileDir):null;
+  if(profileDir)return abortable(profileSuite(base('dsh','other-runtime','other-client','DSH 桌面版 profile（磁盘只读清单；运行中的 DSH 由其自身监听回答）'),profileDir),signal);
+  return unknown(base(client==='dsh'?'hanamesh':'dsh','other-runtime','other-client','另一客户端 runtime（须由其自身监听回答）'),'OTHER_RUNTIME_NOT_OBSERVED','本监听未读取另一客户端的 runtime。','启动该客户端，并向其已广告的状态入口显式检测。');
+ }
  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,
+    await other(combined),...agents,
     unknown(base('codex','desktop-app','desktop-app','Codex / ChatGPT 桌面 App（独立作用域）'),'CODEX_DESKTOP_SCOPE_UNOBSERVABLE','Codex CLI 清单不能证明桌面 App 的安装。','在桌面 App 的插件目录核对；需官方公开桌面状态协议后才可接入。')]};
   }finally{active.delete(controller)}
  };

package/dist/library/locate.js

@@ -69,7 +69,15 @@ export async function inferProfileDir(moduleUrl){
  * 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}={}) {
+/**
+ * Upper bound for the one startup probe of the Desktop payload Node. Its first execution waits for the OS, not for
+ * Node: measured 4.07 s and 2.81 s (0.09 s CPU) on the owner Mac when the client ran from its DMG volume, against
+ * 0.26 s for the installed app. 30 s keeps more than 7x headroom over the slowest measured cold start; the former
+ * 1 s cap made the whole session run without Node. A probe that never answers is killed at this bound or when the
+ * plugin is disposed (`signal`), and the payload Node then stays unavailable as before.
+ */
+export const PAYLOAD_NODE_PROBE_TIMEOUT_MS=30_000;
+export async function inferDesktopLayout({moduleUrl=import.meta.url,argv=process.argv,signal,probeTimeoutMs=PAYLOAD_NODE_PROBE_TIMEOUT_MS}={}) {
   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'));
@@ -107,7 +115,7 @@ export async function inferDesktopLayout({moduleUrl=import.meta.url,argv=process
     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 {stdout}=await promisify(execFile)(node,['-p','JSON.stringify({node:process.versions.node,electron:process.versions.electron})'],{env:{},maxBuffer:1024,timeout:probeTimeoutMs,killSignal:'SIGKILL',...(signal?{signal}:{})});
       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. */ }

package/dist/library/routes.js

@@ -8,8 +8,8 @@ import { HANDOFF_DEFAULTS, HANDOFF_RULES, HANDOFF_SETTING_NAMES, HANDOFF_BODY_MA
 // Keep older route order; dsh.js registers each exact path on the public host API.
 export const LIBRARY_ROUTES=['/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/install','/hanamesh/library/provision','/hanamesh/library/uninstall','/hanamesh/library/events','/hanamesh/library/installedPlugins','/hanamesh/library/plugins/install','/hanamesh/library/plugins/uninstall','/hanamesh/library/target','/hanamesh/library/install-target','/hanamesh/library/handoffs','/hanamesh/library/handoffs/state','/hanamesh/library/handoff-settings','/hanamesh/library/suite/upgrade','/hanamesh/library/installation-status'];
 export const NODE_RUNTIME_ROUTES=['/hanamesh/library/node-runtime','/hanamesh/library/node-runtime/settings','/hanamesh/library/node-runtime/plan','/hanamesh/library/node-runtime/prepare','/hanamesh/library/node-runtime/cancel'];
-LIBRARY_ROUTES.push(...NODE_RUNTIME_ROUTES,'/hanamesh/library/suite-source');
-const READ_ROUTES=new Set(['/hanamesh/library/suite-source','/hanamesh/library/node-runtime','/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/events','/hanamesh/library/installedPlugins','/hanamesh/library/target','/hanamesh/library/handoffs','/hanamesh/library/handoff-settings']);
+LIBRARY_ROUTES.push('/hanamesh/library/version-target','/hanamesh/library/version/install','/hanamesh/library/suite/status','/hanamesh/library/versions',...NODE_RUNTIME_ROUTES,'/hanamesh/library/suite-source');
+const READ_ROUTES=new Set(['/hanamesh/library/version-target','/hanamesh/library/suite/status','/hanamesh/library/versions','/hanamesh/library/suite-source','/hanamesh/library/node-runtime','/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/events','/hanamesh/library/installedPlugins','/hanamesh/library/target','/hanamesh/library/handoffs','/hanamesh/library/handoff-settings']);
 async function jsonBody(req){
   requireCondition(req.headers['content-type']?.split(';')[0].trim()==='application/json','CONTENT_TYPE_REQUIRED','Expected application/json.',{},415);
   const chunks=[];let total=0;for await(const chunk of req){total+=chunk.length;requireCondition(total<=65_536,'BODY_TOO_LARGE','Request body is too large.',{},413);chunks.push(chunk);}
@@ -44,7 +44,7 @@ export function createLibraryHttpHandler(library,{parentOrigin,transportOrigin,a
     requireCondition(subject&&typeof subject.principalId==='string','UNAUTHENTICATED','Host authentication is required.',{},401);
     if(readOnly)requireCondition(new Set(url.searchParams.keys()).size===[...url.searchParams.keys()].length,'INVALID_INPUT','Duplicate query fields are not accepted.');
     const input=readOnly?Object.fromEntries(url.searchParams):await jsonBody(req);
-    if(readOnly&&path==='/hanamesh/library/target'&&input.installTarget!==undefined){try{input.installTarget=JSON.parse(input.installTarget);}catch{throw new AppHostError('INVALID_INPUT','installTarget must contain a structured catalog target.');}}
+    if(readOnly&&['/hanamesh/library/target','/hanamesh/library/version-target'].includes(path)&&input.installTarget!==undefined){try{input.installTarget=JSON.parse(input.installTarget);}catch{throw new AppHostError('INVALID_INPUT','installTarget must contain a structured catalog target.');}}
     requireCondition(await authorize(subject,path,input)===true,'FORBIDDEN','Operation is not authorized.',{},403);
     let result;
     if(NODE_RUNTIME_ROUTES.includes(path)){
@@ -70,6 +70,16 @@ export function createLibraryHttpHandler(library,{parentOrigin,transportOrigin,a
     else if(path==='/hanamesh/library/handoffs/state'){send(res,200,{...handoff.queue.report(input),traceId});return;}
     else if(path==='/hanamesh/library/handoff-settings'&&readOnly){requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','handoff-settings takes no parameters.');result={settings:library.handoffSettings(),defaults:HANDOFF_DEFAULTS,names:HANDOFF_SETTING_NAMES,rules:HANDOFF_RULES,listener:handoff.listener.state()};}
     else if(path==='/hanamesh/library/handoff-settings'){const settings=await library.replaceHandoffSettings(input);send(res,200,{settings,defaults:HANDOFF_DEFAULTS,names:HANDOFF_SETTING_NAMES,rules:HANDOFF_RULES,listener:await handoff.restart(),traceId});return;}
+    else if(path==='/hanamesh/library/suite/status'){requireCondition(Object.keys(input).length===0,'INVALID_INPUT','Suite status takes no parameters.');result=await library.suiteStatus();}
+    else if(path==='/hanamesh/library/version-target')result=await library.resolveVersionTarget(input);
+    else if(path==='/hanamesh/library/version/install')result=await library.installVersion(input);
+    else if(path==='/hanamesh/library/versions'){
+      // Same transport lifetime as the existing read-only installation-status route.
+      const controller=new AbortController(),abort=()=>{if(!res.writableEnded)controller.abort();};req.once('aborted',abort);res.once('close',abort);
+      try{if(req.aborted||res.destroyed)controller.abort();result=await library.versions(input,{signal:controller.signal});if(controller.signal.aborted)return;}
+      catch(error){if(controller.signal.aborted)return;throw error;}
+      finally{req.off('aborted',abort);res.off('close',abort);}
+    }
     else if(path==='/hanamesh/library/target')result=await library.resolveTarget(input);
     else if(path==='/hanamesh/library'&&readOnly){requireCondition(Object.keys(input).every(key=>['q','category','cursor'].includes(key)),'UNKNOWN_FIELDS','Unknown library parameters.');result=await library.list(input);}
     else if(path==='/hanamesh/library/sources'&&readOnly)result=library.sources();

package/dist/library/service.js

@@ -1,3 +1,4 @@
+import semver from 'semver';
 import { randomUUID } from 'node:crypto';
 import { AppHostError, requireCondition, SerialQueue } from '../errors.js';
 import { loadCatalog, isApplication, itemKind, upgradeAvailable, validateManifestUrl } from './catalog.js';
@@ -22,13 +23,16 @@ const npmUpgradeAvailable=(target,row)=>Boolean(target?.source==='npm'&&row?.ver
  * `client`: which client this host is ('dsh' | 'hanamesh', see client-identity.js). `unavailable`: when there is no
  * installer, the facts that are missing, in words a person can act on (`[{need, how}]`); probes and 503s carry them.
  */
-export function createLibraryService({domain,host,config={},dataRoot,ledgerReader,installer,client='dsh',unavailable=()=>[],installationStatus,suiteSourceService=()=>undefined,logger}){
+export function createLibraryService({domain,host,config={},dataRoot,ledgerReader,installer,client='dsh',unavailable=()=>[],installationStatus,versionCatalog,suiteSourceService=()=>undefined,logger}){
   const warn=(message,...args)=>{if(typeof logger?.warn==='function')logger.warn(message,...args);else console.warn(message,...args);};
   const ready=()=>typeof installer?.install==='function'&&installer.ready!==false;
   let suiteStatus={status:'unknown',version:null,components:[]};
   const suiteFacts=async()=>installer?.suiteFacts?await installer.suiteFacts():{...await readSuiteStatus(config.profileDir),status:'unknown',completeness:'unknown',blocked:[{code:'CORE_SUITE_DECLARATION_MISSING'}],suiteUpgradeUnavailable:CORE_SUITE_DECLARATION_MISSING};
   const events=[];let sequence=0;let state;const running=new Map(),installing=new Map();let bootDependencies;
   const eventRetention=config.eventRetention??512;
+  const versionLookupConcurrency=config.versionLookupConcurrency??4,versionLookupCacheMs=config.versionLookupCacheMs??30000;
+  requireCondition(Number.isSafeInteger(versionLookupConcurrency)&&versionLookupConcurrency>=1&&versionLookupConcurrency<=16,'INVALID_INPUT','library.versionLookupConcurrency must be an integer from 1 to 16.');
+  requireCondition(Number.isSafeInteger(versionLookupCacheMs)&&versionLookupCacheMs>0&&versionLookupCacheMs<=2147483647,'INVALID_INPUT','library.versionLookupCacheMs must be a positive timer budget.');
   requireCondition(Number.isSafeInteger(eventRetention)&&eventRetention>0,'INVALID_INPUT','library.eventRetention must be a positive safe integer.');
   const observers=new Set();
   const emit=event=>{const value={sequence:++sequence,at:Date.now(),...event};events.push(value);if(events.length>eventRetention)events.shift();for(const observer of observers){try{observer(value);}catch(error){warn('hanamesh-app-host library: event observer failed (%s): %s',value.type,error?.message??error);}}return value;};
@@ -37,6 +41,13 @@ export function createLibraryService({domain,host,config={},dataRoot,ledgerReade
   const catalog=({q='',category='hanamesh-app',cursor}={})=>loadCatalog({fixture:config.fixture,sources:state.sources,fetchImpl:config.fetchImpl,query:q,category,cursor});
   async function installed(){return config.profileDir?await scanInstalled({profileDir:config.profileDir,host,ledgerReader,dataRoot}):[];}
   async function installedPlugins(){return config.profileDir?await scanInstalledPlugins({profileDir:config.profileDir,bootDependencies}):[];}
+  function suiteVersionCatalog(){
+    if(state.suiteSource?.mode!=='core')return versionCatalog;
+    const source=readSuiteSourceState(suiteSourceService());
+    requireCondition(source.status==='ready'&&source.registry,'CORE_SUITE_SOURCE_NOT_READY','The selected suite registry is not ready.',{},409);
+    requireCondition(versionCatalog?.forRegistry,'PLUGIN_VERSIONS_UNAVAILABLE','The selected suite registry cannot be queried.',{},503);
+    return versionCatalog.forRegistry(source.registry);
+  }
   const settingsWriter=new SerialQueue();
   function persist(update){return settingsWriter.run(async()=>{const next={...update(state),revision:state.revision+1};await domain.global.set(next);state=next;});}
   async function operation(type,task){const operationId=randomUUID();emit({type:`library.${type}-started`,operationId});const work=Promise.resolve().then(()=>task(operationId)).then(result=>{emit({type:`library.${type}-done`,operationId,result});return result;},error=>{
@@ -62,18 +73,19 @@ export function createLibraryService({domain,host,config={},dataRoot,ledgerReade
     if(now[result.packageName])bootDependencies[result.packageName]=now[result.packageName];else delete bootDependencies[result.packageName];
     return{...result,restartBaseline:{updated:true}};
   }
-  async function resolveTarget(input){
+  async function resolveTarget(input,versionSelection=false){
     requireCondition(input&&typeof input==='object'&&!Array.isArray(input),'INVALID_INPUT','Only itemId and packageName are accepted.');
     // rc.8: optional install-target contract declaration. Absent keeps the v1 semantics; anything but '1' is refused explicitly, before field checks.
     requireCondition(input.contractVersion===undefined||input.contractVersion===INSTALL_TARGET_CONTRACT_VERSION,'CONTRACT_VERSION_UNSUPPORTED','This market does not implement the requested install-target contract version.',{supported:[INSTALL_TARGET_CONTRACT_VERSION]});
-    requireCondition(Object.keys(input).every(key=>['itemId','packageName','contractVersion','installTarget'].includes(key)),'INVALID_INPUT','Only catalog identity and package installation target are accepted.');
+    requireCondition(Object.keys(input).every(key=>['itemId','packageName','contractVersion','installTarget'].includes(key)||versionSelection&&key==='version'),'INVALID_INPUT','Only catalog identity and package installation target are accepted.');
     const{itemId,packageName}=input;
+    requireCondition(input.version===undefined||typeof input.version==='string'&&semver.valid(input.version)===input.version,'INVALID_INPUT','Select an exact published version.');
     const expected=input.installTarget===undefined?undefined:packageInstallTarget(input.installTarget);
     requireCondition(!expected||itemId!==undefined,'INVALID_INPUT','A structured installation target requires itemId.');
     if(itemId===SUITE_TARGET){
       requireCondition(packageName===undefined&&!expected,'INVALID_INPUT','套件升级不接受包名或任意替换参数。');
       requireCondition(typeof installer?.prepareSuiteUpgrade==='function','SUITE_UPGRADE_UNAVAILABLE','当前客户端还不支持安全套件升级，请使用补齐命令。',{},503);
-      const plan=await installer.prepareSuiteUpgrade();
+      const plan=await installer.prepareSuiteUpgrade(input.version===undefined?undefined:{bundleVersion:input.version});
       return{contractVersion:'1',source:{kind:'suite',manifestUrl:'https://github.com/yzsnstotz'},item:{id:SUITE_TARGET,displayName:'HanaMesh 套件',kind:'suite-upgrade',package:{registry:'npm',name:SUITE_BUNDLE},installed:{state:'installed',version:suiteStatus.version},upgradeAvailable:plan.available,suiteUpgrade:plan}};
     }
     requireCondition(itemId!==undefined||packageName!==undefined,'INVALID_INPUT','itemId or packageName is required.');
@@ -81,18 +93,19 @@ export function createLibraryService({domain,host,config={},dataRoot,ledgerReade
     requireCondition(packageName===undefined||(text(packageName,214)&&PACKAGE_NAME.test(packageName)),'INVALID_INPUT','packageName is invalid.');
     async function resolved(found,source){
       requireCondition(found.oneClickInstall?.allowed===true,'NOT_INSTALLABLE','The catalog has not approved one-click installation.',{reason:found.oneClickInstall?.reason??'fixed-install-target-required'});
-      const targets=catalogPackageTargets(found),selected=targets.find(target=>expected?sameInstallTarget(target,expected):packageName===undefined||installTargetName(target)===packageName);
+      const targets=catalogPackageTargets(found);let selected=targets.find(target=>expected?sameInstallTarget(input.version&&target.source==='npm'?{...target,version:input.version}:target,expected):packageName===undefined||installTargetName(target)===packageName);
       requireCondition(!expected||selected,'CATALOG_CHANGED','The reviewed installation source or build permission changed. Review the current target again.',{},409);
       requireCondition(selected,'NOT_INSTALLABLE','This catalog entry has no fixed package installation target for the requested package.',{reason:'fixed-install-target-required'});
       const name=installTargetName(selected);
+      if(input.version!==undefined){requireCondition(selected.source==='npm'&&versionCatalog,'PLUGIN_VERSIONS_UNAVAILABLE','Version selection is unavailable for this source.',{},503);await versionCatalog.select(name,input.version);selected={...selected,version:input.version};}
       requireCondition(!protectedPackage(name),'PACKAGE_DENIED','The HanaMesh suite is not managed through the market.',{},403);
       const rows=[...await installedPlugins(),...await installed()],row=rows.find(value=>value.packageName===name)??null;
-      let upgrade=npmUpgradeAvailable(selected,row);
+      let upgrade=input.version!==undefined?row?.version!==input.version:npmUpgradeAvailable(selected,row);
       if(selected?.source==='github'&&row){
         const saved=await readProfileManifest(config.profileDir);
         upgrade=saved.dependencies[name]!==pinnedGithubSpec(selected.repo,selected.ref,selected.path)||row.active===false;
       }
-      const item={...found,package:{registry:selected.source,name},installTarget:selected,installed:row,upgradeAvailable:upgrade};
+      const item={...found,...(input.version?{selectedVersion:input.version}:{}),package:{registry:selected.source,name},installTarget:selected,installed:row,upgradeAvailable:upgrade};
       return{contractVersion:INSTALL_TARGET_CONTRACT_VERSION,source,item:{...item,kind:itemKind(item)}};
     }
     const packageMatches=row=>row.package?.name===packageName||(row.installMethods??[]).some(method=>method.target&&(method.target.packageName??method.target.name)===packageName);
@@ -139,8 +152,26 @@ export function createLibraryService({domain,host,config={},dataRoot,ledgerReade
       let items=page.items.map(item=>{const selected=catalogPackageTargets(item)[0];return selected?{...item,installTarget:selected,package:{registry:selected.source,name:installTargetName(selected)}}:item;}).filter(item=>!protectedPackage(item.package?.name)).map(item=>{const row=byPackage.get(item.package?.name)??null;const kind=itemKind(item);
         return{...item,kind,application:isApplication(item),installed:row,upgradeAvailable:npmUpgradeAvailable(item.installTarget,row)};});
       if(config.profileDir&&!cursor&&(!category||category==='plugin')&&(!q||'hanamesh 套件'.includes(q.toLowerCase())))items.unshift({id:'hanamesh:suite',displayName:'HanaMesh 套件',summary:'官方 · 不计分。Core、使用记录与应用库一次装齐。',kind:'suite',official:true,installed:suiteStatus.status==='installed'?{state:'installed',version:suiteStatus.version}:null,suite:suiteStatus,...((installer?.suiteUpgradeUnavailable??suiteStatus.suiteUpgradeUnavailable)?{suiteUpgradeUnavailable:installer?.suiteUpgradeUnavailable??suiteStatus.suiteUpgradeUnavailable}:{})});
+      // Version discovery is optional and starts only through the per-item read route after this list paints.
+      let coreSource;
+      if(state.suiteSource?.mode==='core')try{coreSource=readSuiteSourceState(suiteSourceService());}catch(error){coreSource={code:error.code??'CORE_SUITE_SOURCE_INVALID'};}
+      const versionQueries=versionCatalog?{concurrency:versionLookupConcurrency,cacheMs:versionLookupCacheMs,scope:JSON.stringify([state.revision,config.registry??'https://registry.npmjs.org/',state.suiteSource??null,coreSource??null])}:null;
       const categories=[...new Set(page.items.flatMap(item=>item.categories??[]))].sort();
-      return{source:page.source,items,categories,installed:installedRows,plugins:pluginRows,restartRequired:[...pluginRows,...installedRows].some(row=>RESTART_STATES.has(row.state)),...(bootSnapshotError?{restartBaseline:{known:false,code:bootSnapshotError}}:{}),page:page.page};},
+      return{source:page.source,items,categories,...(versionQueries?{versionQueries}:{}),installed:installedRows,plugins:pluginRows,restartRequired:[...pluginRows,...installedRows].some(row=>RESTART_STATES.has(row.state)),...(bootSnapshotError?{restartBaseline:{known:false,code:bootSnapshotError}}:{}),page:page.page};},
+    async versions(input,{signal}={}){
+      requireCondition(input&&Object.keys(input).length===1&&typeof input.itemId==='string','INVALID_INPUT','Only itemId is accepted.');
+      requireCondition(versionCatalog,'PLUGIN_VERSIONS_UNAVAILABLE','Version discovery is unavailable.',{},503);
+      signal?.throwIfAborted();
+      if(input.itemId==='hanamesh:suite'){
+        const releases=await suiteVersionCatalog().read(SUITE_BUNDLE,{signal}),installedVersion=(await suiteFacts()).version;
+        signal?.throwIfAborted();let latestVersion=releases.latestVersion;
+        if(latestVersion&&installedVersion&&semver.gt(latestVersion,installedVersion)){const plan=await installer.readSuiteUpgrade();signal?.throwIfAborted();latestVersion=plan.bundle.to;}
+        return{...releases,latestVersion,installedVersion,upgradeAvailable:Boolean(latestVersion&&installedVersion&&semver.gt(latestVersion,installedVersion))};
+      }
+      const {item}=await resolveTarget(input);requireCondition(item.installTarget.source==='npm','NOT_INSTALLABLE','Version selection requires an npm source.');
+      const releases=await versionCatalog.read(item.package.name,{signal}),installedVersion=item.installed?.version??null;signal?.throwIfAborted();
+      return{...releases,installedVersion,upgradeAvailable:Boolean(releases.latestVersion&&installedVersion&&semver.gt(releases.latestVersion,installedVersion))};
+    },
     sources(){return{sources:structuredClone(state.sources),revision:state.revision};},
     /** Suite package registry selection is independent of catalog manifest sources. */
     suiteSourceSettings(){
@@ -160,6 +191,9 @@ export function createLibraryService({domain,host,config={},dataRoot,ledgerReade
     async replaceSources(input){requireCondition(Array.isArray(input?.sources)&&input.sources.length<=16,'INVALID_SOURCES','sources must be an array of at most 16 entries.');const sources=input.sources.map(source=>({manifestUrl:validateManifestUrl(source.manifestUrl).href,enabled:source.enabled===true}));requireCondition(sources.length===0||sources.filter(source=>source.enabled).length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');await persist(current=>({...current,sources}));return this.sources();},
     /** `{itemId, packageName?}`: applications and plugins take the same path (`dsh plugin add --save-exact`); also the upgrade path. */
     resolveTarget,
+    resolveVersionTarget:input=>{requireCondition(typeof input?.version==='string','INVALID_INPUT','Select an exact version.');return resolveTarget(input,true);},
+    suiteStatus:()=>readSuiteStatus(config.profileDir),
+    async installVersion(input){requireInstaller('Version installation is unavailable.');requireCondition(typeof input?.version==='string'&&input.itemId!==SUITE_TARGET,'INVALID_INPUT','Select an exact catalog plugin version.');const {item}=await resolveTarget(input,true);if(present(item.installed)&&!item.upgradeAvailable)return{status:'already-installed',itemId:item.id,packageName:item.package.name};return installItem(item);},
     /** Public discovery is metadata only: no profile, authentication or installed rows. */
     installationStatus,
     installTarget(){const need=ready()?[]:unavailable();return{client,ready:ready(),...(typeof installationStatus==='function'?{installationStatus:INSTALLATION_STATUS_CAPABILITY}:{}),...((suiteStatus.status!=='unknown'||suiteStatus.restartRequired)&&!installer?.suiteUpgradeUnavailable?{suite:structuredClone(suiteStatus)}:{}),installTarget:{contract:'hanamesh.install-target',contractVersion:INSTALL_TARGET_CONTRACT_VERSION,supported:[INSTALL_TARGET_CONTRACT_VERSION],fragmentPrefix:'#hanamesh-install?'},

package/dist/library/suite.js

@@ -29,7 +29,7 @@ export async function readSuiteStatus(profileDir){
       return{name,label,version:pkg?.name===name&&semver.valid(pkg.version)?pkg.version:null,active:selected};
     }));
     const version=bundle?.name===SUITE_BUNDLE&&semver.valid(bundle.version)?bundle.version:null;
-    return{status:version&&selected&&components.every(c=>c.version&&bundle.dependencies?.[c.name]===c.version)?'installed':'incomplete',version,components};
+    return{status:version&&selected&&components.every(c=>c.version&&typeof bundle.dependencies?.[c.name]==='string'&&semver.validRange(bundle.dependencies[c.name])&&semver.satisfies(c.version,bundle.dependencies[c.name]))?'installed':'incomplete',version,components};
   }catch{return{status:'unknown',version:null,components:[]};}
 }
 export const CORE_SUITE_DECLARATION_MISSING='Core 未提供套件声明';
@@ -98,9 +98,9 @@ export function createCoreSuiteAdapter({core=()=>undefined,registry,suiteSourceM
     requireCondition(current()===service,'CORE_SUITE_DECLARATION_MISSING',CORE_SUITE_DECLARATION_MISSING,{},503);
     return validateDeclaration(result);
   }
-  const get=async()=>{
+  const get=async({bundleVersion}={})=>{
     const binding=sourceBinding();
-    const declaration=await read({...(binding.registry===undefined?{}:{registry:binding.registry}),...(profileName===undefined?{}:{profile:profileName})});
+    const declaration=await read({...(binding.registry===undefined?{}:{registry:binding.registry}),...(profileName===undefined?{}:{profile:profileName}),...(bundleVersion===undefined?{}:{bundleVersion})});
     requireCondition(JSON.stringify(sourceBinding())===JSON.stringify(binding),'SUITE_PLAN_CHANGED','套件安装包来源已变化，请重新查看并确认。',{},409);
     requireCondition(declaration.completeness==='complete','CORE_SUITE_CURRENT_INCOMPLETE','Core 套件完整性：'+declaration.completeness,{completeness:declaration.completeness,blocked:declaration.blocked},409);
     let expected;try{const url=new URL(binding.registry);url.pathname=url.pathname.replace(/\/$/,'')+'/';expected=url.href;}catch{}
@@ -126,9 +126,9 @@ export function createCoreSuiteAdapter({core=()=>undefined,registry,suiteSourceM
  * Core owns candidate selection, completeness, ranges and compatibility; this module only checks
  * that an exact execution plan is well formed and confined to our three protected packages.
  */
-export async function prepareSuiteUpgrade({coreSuitePlan}={}){
+export async function prepareSuiteUpgrade({coreSuitePlan,bundleVersion}={}){
   requireCondition(typeof coreSuitePlan==='function','CORE_SUITE_DECLARATION_MISSING',CORE_SUITE_DECLARATION_MISSING,{},503);
-  const plan=await coreSuitePlan();
+  const plan=await coreSuitePlan(bundleVersion===undefined?undefined:{bundleVersion});
   requireCondition(plan!==undefined&&plan!==null,'CORE_SUITE_DECLARATION_MISSING',CORE_SUITE_DECLARATION_MISSING,{},503);
   const invalid=()=>requireCondition(false,'CORE_SUITE_DECLARATION_INVALID','Core 套件声明无法用于精确安装。',{},503);
   if(typeof plan!=='object'||Array.isArray(plan)||typeof plan.available!=='boolean'||!object(plan.bundle)||plan.bundle.name!==SUITE_BUNDLE||!exact(plan.bundle.from)||!exact(plan.bundle.to)||!nullableText(plan.installCommand)||!validInstallation(plan.installation,plan.bundle.to)||!Array.isArray(plan.components)||plan.components.length!==SUITE_PACKAGES.length)invalid();

package/dist/library/versions.js

@@ -0,0 +1,70 @@
+/** npm release discovery for the market; mutations still use the official DSH plugin CLI. */
+import semver from 'semver';
+import {createRequire} from 'node:module';
+import {readFile} from 'node:fs/promises';
+import {dirname,join} from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {AppHostError,requireCondition} from '../errors.js';
+const packageName=value=>typeof value==='string'&&value.length<=214&&/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+
+/** Resolve public host metadata from the running installation, never the plugin's development dependencies. */
+export function hostVersionReader(anchor){
+ const resolver=createRequire(anchor);
+ return async name=>{
+  try{return JSON.parse(await readFile(resolver.resolve(name+'/package.json'),'utf8')).version;}catch{
+   try{let directory=dirname(resolver.resolve(name));for(;;){try{const value=JSON.parse(await readFile(join(directory,'package.json'),'utf8'));if(value.name===name)return value.version;}catch{}const parent=dirname(directory);if(parent===directory)break;directory=parent;}}catch{}
+   return null;
+  }
+ };
+}
+
+/** List published releases and select an exact compatible release; network failures never become 'up to date'. */
+export function createNpmVersionCatalog({registry='https://registry.npmjs.org/',fetchImpl=fetch,peerVersion=async()=>null,nodeVersion=process.versions.node,anchor,timeoutMs=30000,maxBytes=16777216}={}){
+ const url=new URL(registry);
+ requireCondition((url.protocol==='https:'||url.protocol==='http:'&&['127.0.0.1','localhost','[::1]'].includes(url.hostname))&&!url.username&&!url.password&&!url.search&&!url.hash,'INVALID_INPUT','Plugin registry must be a credential-free HTTPS or loopback URL.');
+ url.pathname=url.pathname.replace(/\/$/,'')+'/';
+ async function reason(record,peer){
+  if(!record?.dsh?.bundle?.patch)return 'PLUGIN_BUNDLE_MISSING';
+  if(record.engines?.node&&(!semver.validRange(record.engines.node)||!semver.satisfies(nodeVersion,record.engines.node)))return 'PLUGIN_NODE_INCOMPATIBLE';
+  if(record.engines!==undefined&&(!record.engines||typeof record.engines!=='object'||Array.isArray(record.engines)))return 'PLUGIN_METADATA_INVALID';
+  if(record.peerDependencies!==undefined&&(!record.peerDependencies||typeof record.peerDependencies!=='object'||Array.isArray(record.peerDependencies)))return 'PLUGIN_METADATA_INVALID';
+  const dshPeer=name=>name==='@deepseek-ai/dsh'||name.startsWith('@deepseek-ai/dsh-');
+  if(record.engines?.dsh!==undefined||Object.keys(record.peerDependencies??{}).some(dshPeer)){
+   const actual=await peer('@deepseek-ai/dsh');if(!anchor||!actual||!semver.valid(actual))return 'PLUGIN_PEER_UNKNOWN';
+   try{const resolver=createRequire(anchor),sdk=await import(pathToFileURL(resolver.resolve('@deepseek-ai/dsh-app-boot')).href);if(sdk.evaluatePluginCompatibility(record,{},actual))return 'PLUGIN_PEER_INCOMPATIBLE';}catch{return 'PLUGIN_PEER_UNKNOWN';}
+  }
+  for(const [name,range]of Object.entries(record.peerDependencies??{})){
+   if(dshPeer(name))continue;
+   const actual=await peer(name);
+   if(actual===null&&record.peerDependenciesMeta?.[name]?.optional===true)continue;
+   if(!actual||!semver.valid(actual))return 'PLUGIN_PEER_UNKNOWN';
+   if(typeof range!=='string'||!semver.validRange(range)||!semver.satisfies(actual,range))return 'PLUGIN_PEER_INCOMPATIBLE';
+  }
+  return null;
+ }
+ async function read(name,{signal}={}){
+  requireCondition(packageName(name),'INVALID_INPUT','A valid npm package name is required.');
+  const budget=AbortSignal.timeout(timeoutMs),readSignal=signal?AbortSignal.any([signal,budget]):budget;
+  try{
+   readSignal.throwIfAborted();
+   const response=await fetchImpl(new URL(encodeURIComponent(name),url).href,{method:'GET',credentials:'omit',redirect:'error',headers:{accept:'application/json'},signal:readSignal});
+   requireCondition(response.ok,'PLUGIN_VERSIONS_UNAVAILABLE','Could not read published plugin versions.',{status:response.status},502);
+   const chunks=[];let bytes=0;
+   for await(const chunk of response.body){bytes+=chunk.length;requireCondition(bytes<=maxBytes,'PLUGIN_VERSIONS_UNAVAILABLE','Plugin version metadata exceeds the configured limit.',{},502);chunks.push(chunk);}
+   const data=JSON.parse(Buffer.concat(chunks).toString('utf8'));
+   requireCondition(data.name===name&&data.versions&&typeof data.versions==='object'&&!Array.isArray(data.versions),'PLUGIN_VERSIONS_UNAVAILABLE','The registry returned invalid plugin metadata.',{},502);
+   const versions=[],peers=new Map();const peer=name=>{if(!peers.has(name))peers.set(name,Promise.resolve().then(()=>peerVersion(name)));return peers.get(name);};
+   for(const version of Object.keys(data.versions).filter(v=>semver.valid(v)===v).sort(semver.rcompare)){
+    readSignal.throwIfAborted();
+    const record=data.versions[version];if(record?.name!==name||record.version!==version)continue;
+    const failure=record.deprecated?'PLUGIN_VERSION_DEPRECATED':await reason(record,peer);
+    versions.push({version,compatible:failure===null,...(failure?{reason:failure}:{})});
+   }
+   // Prereleases remain selectable; the default follows latest's stable/prerelease channel.
+   const latest=data['dist-tags']?.latest,prerelease=typeof latest==='string'&&semver.valid(latest)&&semver.prerelease(latest)!==null;
+   const latestVersion=versions.find(row=>row.compatible&&(prerelease||semver.prerelease(row.version)===null))?.version??null;
+   readSignal.throwIfAborted();return{packageName:name,registry:url.href,latestVersion,versions};
+  }catch(error){if(error instanceof AppHostError)throw error;throw new AppHostError('PLUGIN_VERSIONS_UNAVAILABLE','Could not read published plugin versions.',{cause:String(error.message??error)},502);}
+ }
+ return{read,forRegistry:value=>createNpmVersionCatalog({registry:value,fetchImpl,peerVersion,nodeVersion,anchor,timeoutMs,maxBytes}),async select(name,version){requireCondition(typeof version==='string'&&semver.valid(version)===version,'INVALID_INPUT','Select an exact published version.');const result=await read(name),row=result.versions.find(row=>row.version===version);requireCondition(row?.compatible,'PLUGIN_VERSION_INCOMPATIBLE','The selected version is unavailable or incompatible with this client.',{version,reason:row?.reason??'PLUGIN_VERSION_MISSING'},409);return row;}};
+}

package/docs/CONTRACT.md

@@ -1,3 +1,7 @@
+0.6.27：Desktop payload 独立 Node 的启动识别上限为 30 s（实测最慢冷启动 4.07 s 的 7 倍以上余量），超时或插件卸载即终止该子进程；版本、平台与非 Electron 校验不变。
+
+0.6.26：Codex 官方 GitHub `git` 来源的精确 `.git` 后缀在市场映射与每项安装来源分别归一；只读覆盖扩大到 ChatGPT.app 内置 Codex CLI、预发布 CLI 版本、不存在的官方资料目录（未安装）和 HanaMesh 客户端读取的 DSH 桌面版磁盘 profile；`other-runtime` 的 kind 改名为 `other-client`。只读命令与来源冲突拒绝不变，见 INSTALLATION_STATUS.md。
+
 0.6.7 adds the explicitly consented public installation-status capability on both existing library listeners. Full request/response, strict refusals, automatic official-reader discovery and minimum-version support and scope/lifecycle are defined in [INSTALLATION_STATUS.md](INSTALLATION_STATUS.md); it does not authorize installation or alter recording consent.
 
 # 公开契约 v1（候选，0.1.0-rc.41；rc.41 卸载 runtime 时清理生成的 Python 字节码缓存、未知残留仍 fail-closed；rc.40 市场只读查询待启动实例，ready 后一次 resume；前台即时 heartbeat 与失效帧显式清理；rc.39 Market seat 内打开应用时将原有应用帧固定铺满原生窗口并覆盖 Settings，同一回执/租约/关闭动作；rc.38 投射时仅提升 shell.overlay 层级以盖过原生 Settings；rc.35 市场开关按钮即时反馈、owned 应用已退出时提前结束 TERM 等待并确认精确进程组终止；rc.34 内置市场消费 heartbeat/视图清理；rc.33 owned 回收与启动握手分阶段限时；rc.32 客户端 `market` 席位与 dshmarket 互斥、壳内重启改走 postMessage 桥（见「市场席位」）；rc.28 HanaMesh 市场：插件与应用同路径装卸、已装含插件、可升级/需重启、`installedPlugins` 与 `plugins/*` 路由、`LIB-PROVISION-INPUT` 400（见「市场」）；rc.27 应用使用证据经 usage 插件 record 座位上报（见「应用使用证据」）；rc.26 应用库默认目录源 + 纯 DSH 位置推断（见「应用库配置」）；rc.15 目录条目校验补 updatedAt；rc.16 应用库默认 category=hanamesh-app、q/cursor 透传；rc.13/rc.14 与 rc.12 契约相同：rc.13 补许可证/repository/精确 peer，rc.14 去掉客户端对 hanameshCore 的读取）
@@ -157,7 +161,7 @@ DSH 绑定必须提供同一个 `single` domain 的一次完整镜像 publish
 | `/hanamesh/library/provision` | POST | `{appId, packageName, runtimeItem}` 三者必填 | 202；缺字段/非法 → 400 `INVALID_INPUT`（`LIB-PROVISION-INPUT`） |
 | `/hanamesh/library/uninstall` | POST | `{appId, packageName, runtimeItem?}` | 202；缺字段/非法 → 400 `INVALID_INPUT` |
 
-事件流 `library.install-*` 增加 `kind`；`install-done.result` 对插件为 `{status:'restart-required', kind:'plugin', packageName, version}`。受保护包（`@hanamesh/core`、`@hanamesh/usage`、`@hanamesh/brand`、`hanamesh-brand`、`hanamesh-core`、`hanamesh-usage`、`@hanamesh/dsh-app-host` 及旧写法 `@hanamesh/dsh-core`、`@hanamesh/dsh-usage`）任何路径都 `PACKAGE_DENIED`：`plugins/*` 在启动操作前同步答 403，目录条目路径在操作内以 `-failed` 事件给出。「需重启」判定只来自本进程启动时的 profile 依赖快照（钉版本内核不暴露已加载插件集合）；快照不可读时一切已装计为已加载。客户端在壳内（`window.self !== window.top`）给 `hanamesh://restart` 深链，官方 DSH 直开时只提示文字；本包不重启 DSH。
+事件流 `library.install-*` 增加 `kind`；`install-done.result` 对插件为 `{status:'restart-required', kind:'plugin', packageName, version}`。受保护包（`@hanamesh/hanamesh`、`@hanamesh/core`、`@hanamesh/usage`、`@hanamesh/dsh-app-host`、`@hanamesh/brand`）任何路径都 `PACKAGE_DENIED`：`plugins/*` 在启动操作前同步答 403，目录条目路径在操作内以 `-failed` 事件给出。「需重启」判定只来自本进程启动时的 profile 依赖快照（钉版本内核不暴露已加载插件集合）；快照不可读时一切已装计为已加载。客户端提示完全退出并重新打开；本包不重启 DSH。
 
 0.6.13 候选：套件 npm 身份为 `@hanamesh/core`、`@hanamesh/usage`、`@hanamesh/dsh-app-host`；Core 声明的 `core.name`、`moduleName`、升级目标和返回的 `packageName` 按这些新名精确比较，旧名声明不当作新三包。插件 id、`hanameshMarket` 服务、路由与存储键保持；普通 Recommender 不受保护、不加入套件。首装/补齐精确命令见 LIBRARY.md；已发布 0.6.12 原件不包含该适配。
 
@@ -290,3 +294,10 @@ for the reviewed `/catalog-source.json?view=hanamesh` provider. Other catalog
 providers and unavailable/CORS-denied public reads retain “暂无”. The source's
 browser access rules are respected; there is no proxy/CORS bypass. Closing or
 switching details ignores stale replies.
+
+## VR1 版本切换（2026-11-10）
+
+新增市场本机版本路由、兼容检查、确认与恢复义务见 [LIBRARY.md 的 VR1 章节](LIBRARY.md#vr1-市场版本管理)。此能力不扩大 install-target v1/网站交接输入；普通安装协议仍不接受外部版本覆盖。总包依赖可为兼容范围，物理完整性按范围判断；Core 是总包兼容组合的唯一提供方，AppHost 只执行并读回。明确选择的旧总包版本在相同校验下可切换，默认操作仍只升级。
+
+
+R168：后台套件版本展示使用不登记确认的 Core 只读组合查询，只有显式目标预览登记执行计划。后台完成或在Core读取期间取消，不替换已打开的默认/历史确认；planId、来源、tuple、物理baseline复读与单次确认保护保留。见 [后台查询与确认计划](LIBRARY.md#r168-后台套件查询与确认计划)。

package/docs/INSTALLATION_STATUS.md

@@ -37,7 +37,7 @@ interface InstallationStatus {
 interface InstallationObservation {
   channel:'hanamesh'|'dsh'|'claude'|'codex';
   scope:{id:'current-runtime'|'other-runtime'|'agent-cli'|'desktop-app';
-    kind:'responding-runtime'|'unobserved-runtime'|'official-user-profile'|'desktop-app';label:string};
+    kind:'responding-runtime'|'other-client'|'official-user-profile'|'desktop-app';label:string};
   status:'installed'|'not-installed'|'incomplete'|'unknown';
   version:string|null;
   versionKind:'suite-bundle'|'agent-distribution';
@@ -69,6 +69,7 @@ Selection is deterministic: the first executable in the inherited absolute PATH
 | Homebrew / system | `/opt/homebrew/bin`, `/usr/local/bin`, `/home/linuxbrew/.linuxbrew/bin`, `/usr/bin`, `/bin`. [Homebrew prefixes](https://docs.brew.sh/Installation); [Claude Homebrew setup](https://code.claude.com/docs/en/setup), [Codex distribution](https://learn.chatgpt.com/docs/cli). Brew-linked native binaries use the same discovery path. |
 | nvm / fnm / installed manager versions | `NVM_BIN`, `NVM_SYMLINK`; `NVM_DIR/versions/node/*/bin` or `~/.nvm/versions/node/*/bin`; Windows `NVM_HOME/*`; `FNM_MULTISHELL_PATH`; `FNM_DIR/node-versions/*/installation[/bin]`, `~/.local/share/fnm/node-versions/*/installation/bin`, `~/Library/Application Support/fnm/node-versions/*/installation/bin`, `%APPDATA%/fnm/node-versions/*/installation`; asdf `installs/nodejs/*/bin`, mise `installs/node/*/bin`. Only SemVer directory names are scanned. [nvm](https://github.com/nvm-sh/nvm), [fnm](https://github.com/Schniz/fnm/blob/master/docs/commands.md), [asdf](https://asdf-vm.com/manage/configuration.html), [mise](https://mise.jdx.dev/directories.html). |
 | Windows native links / npm shims | `%LOCALAPPDATA%/Microsoft/WinGet/Links` ([Claude WinGet](https://code.claude.com/docs/en/setup)). `.exe` precedes `.cmd` per directory. A `.cmd` is never sent to a shell: resolve only the adjacent official npm `node_modules/@anthropic-ai/claude-code/cli.js` or `node_modules/@openai/codex/bin/codex.js`, run it with the verified standalone Node. Missing JS is a named failure, not a guessed shell command. |
+| Desktop app bundle (macOS, Codex only, searched last) | `/Applications` and `~/Applications` `ChatGPT.app/Contents/Resources/codex-cli/bin/codex` (the ChatGPT desktop app ships the Codex CLI; it reads the same `CODEX_HOME` / `~/.codex`). A standalone CLI in any earlier layout wins. |
 
 HOME is the host user's HOME/USERPROFILE. Honor existing `CLAUDE_CONFIG_DIR` / `CODEX_HOME` environment paths, otherwise use `~/.claude` / `~/.codex`. These directories must already exist; discovery never creates them, reads their contents, or reads credentials, sessions or private configuration files. Only official read commands observe plugin inventory. The named profile scope is not a machine-wide inventory. Electron hosts retain the existing verified standalone Node requirement.
 
@@ -78,12 +79,12 @@ Minimum CLI version and fixed syntax (no new upper bound):
 
 | Channel | Minimum version / accepted `--version` syntax | Fixed subsequent read argv |
 |---|---|---|
-| Claude Code | `>=2.1.301`, `MAJOR.MINOR.PATCH (Claude Code)` | `plugin list --json`; `plugin marketplace list --json` |
-| Codex CLI | `>=0.162.1`, `codex-cli MAJOR.MINOR.PATCH` | `plugin list --json --disable remote_plugin`; `plugin marketplace list --json --disable remote_plugin` |
+| Claude Code | `>=2.1.301`, `MAJOR.MINOR.PATCH[-prerelease] (Claude Code)` | `plugin list --json`; `plugin marketplace list --json` |
+| Codex CLI | `>=0.162.1`, `codex-cli MAJOR.MINOR.PATCH[-prerelease]` (desktop bundles report e.g. `0.167.0-alpha.3.2`; SemVer ordering applies, so `0.162.1-alpha.1` is below the minimum) | `plugin list --json --disable remote_plugin`; `plugin marketplace list --json --disable remote_plugin` |
 
 Malformed version output is `AGENT_READER_VERSION_INVALID`; below-minimum versions are `AGENT_READER_VERSION_UNSUPPORTED`; JSON parse/shape failure is `AGENT_INVENTORY_INVALID`. New versions such as 2.1.319 / 0.167.0 must pass exactly the existing inventory validation.
 
-The Codex flag was checked through this exact CLI's public `features list`; it excludes remote directory reads. Passing the version floor is necessary but not sufficient: both JSON shapes must validate. Claude uses the official installed array's `id`, user `scope`, enabled/version and load diagnostics. Other project-only target rows are unknown for this reader. Codex uses the official `installed` array and its qualified identity, installed/enabled/version. The exact target marketplace must match the registered HTTPS source in marketplace list; Codex's per-install `marketplaceSource` must also be present, supported and consistent. A local/different/unreadable source, duplicate/conflicting target or malformed/truncated/empty raw output is unknown. Only a complete valid clean inventory with no target in the observed user scope is not-installed. A known install may have version null; consumers must show version unknown. Official load/payload issues produce incomplete, not successful readiness. No plugin MCP/hook definitions, unrelated inventory or CLI raw diagnostics are returned.
+The Codex flag was checked through this exact CLI's public `features list`; it excludes remote directory reads. Passing the version floor is necessary but not sufficient: both JSON shapes must validate. Claude uses the official installed array's `id`, user `scope`, enabled/version and load diagnostics. Other project-only target rows are unknown for this reader. Codex uses the official `installed` array and its qualified identity, installed/enabled/version. The exact target marketplace must match the registered HTTPS source in marketplace list; Codex's per-install `marketplaceSource` must also be present, supported and consistent. For official GitHub `sourceType:'git'` records, the exact credential/query/fragment-free `https://github.com/owner/repository.git` spelling identifies the same repository as the registered suffix-free URL. Normalize both the marketplace mapping and the per-install source independently; no other URL rewrite, repository substitution or source fallback is accepted. A local/different/unreadable source, duplicate/conflicting target or malformed/truncated/empty raw output is unknown. Only a complete valid clean inventory with no target in the observed user scope is not-installed. A known install may have version null; consumers must show version unknown. Official load/payload issues produce incomplete, not successful readiness. No plugin MCP/hook definitions, unrelated inventory or CLI raw diagnostics are returned.
 
 Commands run with an empty stdin in a disposable neutral cwd, only named HOME/config/platform paths, only the selected inherited/recovered absolute PATH plus allowlisted manager and standard XDG directory variables, no inherited model/API keys, proxy/auth/askpass/Node preload, and disabled Git credential helpers. The verified Node and selected executable directories prefix the selected PATH; retain its manager binary directories, so an official asdf shim can resolve `asdf`. Preserve existing XDG_CONFIG_HOME/CACHE_HOME/DATA_HOME/STATE_HOME/RUNTIME_DIR and CONFIG_DIRS/DATA_DIRS; absent variables stay absent and retain manager OS defaults. The supervisor never overwrites XDG paths with empty temporary directories. Only TMPDIR/TMP/TEMP and cwd use the owned disposable directory. Manager paths additionally include ASDF_CONFIG_FILE, MISE_CONFIG_DIR/GLOBAL_CONFIG_FILE/CACHE_DIR/STATE_DIR alongside the earlier manager-home keys; credentials, proxy, Node preloads and askpass remain excluded. Recovered shell manager/XDG paths follow the same allowlist; there is no fallback to a different installation. No model/install/upgrade/marketplace refresh command runs. On POSIX, a detached IPC reaper owns the neutral cwd outside a separate live command-group anchor. The anchor remains alive until output closes; abort, budget exhaustion, overflow, provider disposal or parent IPC disconnect makes the surviving reaper terminate only that live anchor's group. The reaper waits for group close before removing the cwd, so active writers cannot race deletion, including after caller death. No released PID/PGID or arbitrary process name is used. The caller also performs exact-path cleanup when alive. On Windows the same live anchor/reaper ownership uses the OS taskkill tree operation for its precise owned anchor; no process-name match or command-shell execution. Windows/Linux runtime evidence is separate from macOS fixture execution. There is no retry or stale-result cache. Automatic recovery after an internal reaper/anchor itself is externally SIGKILLed or suffers a native crash is outside this lifecycle guarantee; an external intervention can leave command processes or temporary files and is never reported as an installed/absent inventory.
 
@@ -94,7 +95,11 @@ HTTP refusals: `HOST_DENIED`, `ORIGIN_DENIED`, `FRAME_CONTROL_DENIED`, `CREDENTI
 Per-scope unknown reasons always include a safe code/message/action:
 
 - `CORE_SUITE_DECLARATION_MISSING`, `CORE_SUITE_DECLARATION_INVALID`, `CORE_SUITE_READ_FAILED`, `CORE_SUITE_DECLARATION_UNKNOWN`; incomplete: `CORE_SUITE_CURRENT_INCOMPLETE`, plus Core blocked codes.
-- `OTHER_RUNTIME_NOT_OBSERVED`, `CODEX_DESKTOP_SCOPE_UNOBSERVABLE`.
+- `OTHER_RUNTIME_NOT_OBSERVED`, `CODEX_DESKTOP_SCOPE_UNOBSERVABLE`, `DSH_PROFILE_UNREADABLE`; incomplete: `DSH_PROFILE_SUITE_INCOMPLETE`.
+
+Authoritative absence (read-only, no CLI execution): an official user profile directory (`CLAUDE_CONFIG_DIR` / `CODEX_HOME`, else `~/.claude` / `~/.codex`) that does not exist holds no user-scope plugin, so that channel is `not-installed` with the registered identity, whether or not the CLI is installed. An existing but inaccessible directory stays `AGENT_PROFILE_UNAVAILABLE`; an existing profile without a readable CLI stays `AGENT_READER_UNAVAILABLE`.
+
+The HanaMesh client's `other-runtime` row (`kind:'other-client'`) reads the official DSH desktop profile on disk at the upstream default home (`~/.dsh/profiles/desktop`, `@deepseek-ai/dsh-home-paths` `.dsh`): after distinct physical profile identities have been established, a missing profile manifest or no `@hanamesh/hanamesh` dependency is `not-installed`; the bundle and all three members resolved at the bundle's exact versions and selected in `dsh.profile.bundles` is `installed` with the bundle version (a physical inventory, not that runtime's Core completeness); otherwise `incomplete`; unreadable JSON is unknown. Before every explicit read, resolve both the current profile and the target with `realpath`; the reused reader retains a selector, never a cached identity decision. The same physical directory (including symlink aliases), a missing current profile identity, or any identity-resolution failure keeps the row `unknown / OTHER_RUNTIME_NOT_OBSERVED`; no target inventory is read. A missing target directory also fails this identity check conservatively. A DSH listener never reports the HanaMesh client: that row is always `OTHER_RUNTIME_NOT_OBSERVED`.
 - `AGENT_READER_VERSION_INVALID`, `AGENT_READER_VERSION_UNSUPPORTED`, `AGENT_READER_NODE_REQUIRED`, `AGENT_SHELL_ENV_UNAVAILABLE`, `AGENT_READER_ENTRYPOINT_UNAVAILABLE`, `AGENT_READER_DISCOVERY_INVALID`.
 - `AGENT_PROFILE_UNAVAILABLE`, `AGENT_READER_UNAVAILABLE`, `AGENT_READER_PERMISSION_DENIED`, `AGENT_READER_TIMEOUT`, `AGENT_READER_OUTPUT_LIMIT`, `AGENT_READER_DIAGNOSTIC`, `AGENT_READER_CLEANUP_FAILED`, `AGENT_READER_FAILED`.
 - `AGENT_INVENTORY_INVALID`, `AGENT_INVENTORY_CONFLICT`, `AGENT_SCOPE_UNOBSERVABLE`, `AGENT_MARKETPLACE_SOURCE_UNAVAILABLE`, `AGENT_MARKETPLACE_SOURCE_MISMATCH`.

package/docs/LIBRARY.md

@@ -85,3 +85,33 @@ D1: DSH suite installation and upgrades use only @hanamesh/hanamesh. Core owns t
 
 
 A2 0.6.22：普通插件必须有 Indexer 已审核的 installMethods 和 oneClickInstall.allowed:true；仅执行其 npm 精确版本或完整 GitHub SHA。缺目标具名拒绝，不根据包名查可变版本标签。CLI 使用显式 library.registry（若有），否则保留宿主原生 registry 配置。删除普通插件按包名内部直装方法、元数据查询及其专用设置/规则加载。套件仅透传 Core installCommand。安装失败保留脱敏 CLI/读回诊断及补偿结果；精确版本发布后即可原生验收。
+
+## VR1 市场版本管理
+
+应用库/应用详情显示已装版本与最新兼容版本，一键升级默认选择该精确版本；“选择历史版本”列出发布版本，不兼容版本禁用。npm 发布元数据只用于发现，版本选择再次验证 Node、可观察 peer 和公开 DSH `evaluatePluginCompatibility`，缺失事实不会启用安装。总包继续由 Core 的 `getSuiteDeclaration({registry,profile,bundleVersion})` 决定三个业务组件的兼容组合。Theme 为总包分发依赖，不增加业务成员。
+
+新增插件自有的认证同源路由：GET `/hanamesh/library/versions?itemId=...`、GET `/hanamesh/library/version-target?itemId=...&version=...`、POST `/hanamesh/library/version/install`。后者只接受当前目录身份、精确版本及复读的安装目标，不接受 URL、命令或浏览器提供的 registry。已确认的总包仍 POST `/hanamesh/library/suite/upgrade`，GET `/hanamesh/library/suite/status` 返回从总包解析的物理组件读回。原 install-target v1 的 `/target` 与 `/install` 继续拒绝任意 version 字段；网站交接不改变。
+
+普通插件安装/升级/历史切换均复用 `dsh plugin --profile <实际profile> add --save-exact <name>@<version>`。总包执行 Core 提供的精确 argv；执行前按相同的显式版本请求复读来源、声明与物理 baseline。命令运行、精确读回或组件验证失败，先通过同一正式 CLI 补偿，再逐项比较依赖、包、选择与锁；原失败和恢复失败都可见，未核实不报告恢复成功。不会自动重试，不直接写 DSH 的 profile/lock，不全局放宽成熟期。安装后提示完全退出并重开；读回使用总包内部解析的真实子包，而非要求子包成为 profile 直接依赖。
+
+版本查询使用与安装一致的配置 registry；总包选择 Core 来源时从其公开 source state 读取并拒绝未就绪状态。`library.versionLookupTimeoutMs`（默认 30000）与 `library.versionLookupMaxBytes`（默认 16777216）限制每次匿名、拒绝重定向的读取。查询仅发生于页面上已装 npm 项和主动展开版本，不遍历整个市场；失败显示错误。
+
+参考：dsh-market `f76b5f58ec553aba91b964f009a8561eea175011` 的 `src/updates.ts`、`src/routes.ts`、`src/official-desktop.ts`；DSH 0.2.2-rc.1 `dsh-plugin-manager` README 的 `listVersions`/`updateBundle`、`dsh-client-ui-plugin-manager` 版本确认 UI。DSH 的版本接口只列新版，`updateBundle` 拒绝旧版；本市场的完整历史切换沿用已有受监测正式 CLI，不移除旧包后再装，也不修改 DSH 本体。
+
+原生验收补充：总包确认页单独显示精确总包的已装→目标版本，即使三个业务成员未变。正式安装 CLI 保留宿主经绝对路径校验的 XDG_DATA_HOME，使 pnpm 沿用该 profile 首次安装的数据根；不转发任意环境、API token 或 proxy，不改 store、不重装依赖以掩盖 store 冲突。
+
+
+## R162 首屏与保护边界
+
+当前预装Brand包名为 `@hanamesh/brand`，与总包、Core、Usage、AppHost同属普通市场保护名单；已装事实可以读到它，但不提供卸载入口，服务与安装器都在执行正式CLI之前拒绝装卸。退休Brand包名不保留保护别名；普通第三方插件仍可卸载。
+
+目录与磁盘已装事实先返回，首屏不等待npm版本查询。客户端随后逐项调用现有 `/hanamesh/library/versions`；同一页面以 `library.versionLookupConcurrency`（默认4，整数1–16）限制在途查询，按项显示最新兼容版本或具名错误。`library.versionLookupCacheMs`（默认30000ms）仅复用同来源、同已装版本的展示结果和在途请求；过期后下一次明确加载才查询，不定时自动重试。历史下拉复用当前新鲜结果；来源或已装版本变化会失效，离开页面/卸载组件取消在途及排队项，旧响应不回写新来源。
+
+浏览器取消经既有HTTP断连生命周期传给registry fetch；原单次timeout、响应预算、匿名和拒绝重定向规则仍生效。展示缓存不进入安装授权：确认和安装仍重新读取精确目标、Core组合与物理baseline。借用dsh-market同一调研SHA的 `MarketSection.tsx` 分离installed/updates读取与展示缓存思路；HTTP取消复用本仓 `installation-status-http.js` 的res close/req aborted模式，不引入上游没有的DSH API。
+
+
+## R168 后台套件查询与确认计划
+
+后台 `/hanamesh/library/versions` 通过安装器内部只读组合入口读取同一 Core 兼容声明，不登记 planId，不写入或替换用户确认计划。只有用户显式打开默认或历史目标确认时才登记新的执行计划；展示查询完成、失败或在 Core 读取期间取消，都不得使已打开的确认失效。Core 公开协议没有传入取消信号的接口；取消后丢弃展示结果，不虚构该接口，也不依赖撤销已登记计划。
+
+执行仍验证本人 planId，并重新核对来源、Core声明/精确tuple与物理baseline；确认只可使用一次。该分离不缓存执行权限，也不删除 `SUITE_PLAN_CHANGED` 保护。回归 `tests/suite-query-race.test.mjs` 将真实 service、installer 与公开Core适配器连接起来，挂起后台metadata/Core读取后分别确认默认/历史目标，并验证取消后原确认仍执行原精确版本。

package/docs/LICENSES.json

@@ -1,7 +1,7 @@
 {
   "package": {
     "name": "@hanamesh/dsh-app-host",
-    "version": "0.6.25",
+    "version": "0.6.27",
     "license": "SEE LICENSE IN LICENSE",
     "source": "git+https://github.com/yzsnstotz/hanamesh-plugin-app-host.git",
     "purpose": "Application ownership, view leases, Router forwarding, and application library for official DSH"
@@ -352,12 +352,13 @@
       "version": "0.2.2-rc.1",
       "license": "MIT",
       "source": "https://registry.npmjs.org/@deepseek-ai/dsh-app-boot/-/dsh-app-boot-0.2.2-rc.1.tgz",
-      "purpose": "Declared public host type/build prerequisite",
+      "purpose": "Public host SDK for DSH compatibility evaluation; exact development input.",
       "usedAs": [
         "devDependencies"
       ],
       "specs": {
-        "devDependencies": "0.2.2-rc.1"
+        "devDependencies": "0.2.2-rc.1",
+        "peerDependencies": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0 || >=0.2.2-0 <0.3.0-0"
       }
     },
     "@deepseek-ai/dsh-client-ui-primitives": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanamesh/dsh-app-host",
-  "version": "0.6.25",
+  "version": "0.6.27",
   "description": "HanaMesh application ownership, durable view leases, and application library for official DSH 0.2.x",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -120,7 +120,8 @@
     "@deepseek-ai/dsh-client-ui-renderer": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0 || >=0.2.2-0 <0.3.0-0",
     "@deepseek-ai/dsh-client-ui-settings": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0 || >=0.2.2-0 <0.3.0-0",
     "@deepseek-ai/dsh-client-locale": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0 || >=0.2.2-0 <0.3.0-0",
-    "react": "^18.3.1"
+    "react": "^18.3.1",
+    "@deepseek-ai/dsh-app-boot": ">=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0 || >=0.2.2-0 <0.3.0-0"
   },
   "hanamesh": {
     "module": "app-host",