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

package/dist/client.js

@@ -1,8 +1,8 @@
+import { isWorkspaceOrigin } from './workspace-origin.js';
 /** Workspace-side SDK only. Never inject this module into an application iframe. */
 export class WorkspaceAppClient {
   constructor({origin=globalThis.location?.origin,fetch:fetcher=globalThis.fetch,headers=()=>({})}={}) {
-    const parsed=new URL(origin);
-    if(parsed.origin!==origin||parsed.protocol!=='http:'||parsed.hostname!=='127.0.0.1'||!parsed.port)throw new TypeError('Expected exact loopback workspace origin.');
+    if(!isWorkspaceOrigin(origin))throw new TypeError('Expected exact loopback workspace origin.');
     if(typeof fetcher!=='function'||typeof headers!=='function')throw new TypeError('fetch and host headers provider are required.');
     this.origin=origin;this.fetcher=fetcher;this.headers=headers;
   }

package/dist/control-origin.js

@@ -0,0 +1,9 @@
+import {workspaceOrigin, loopbackOrigin} from './descriptor.js';
+import {DESKTOP_ORIGIN} from './workspace-origin.js';
+/** Desktop authenticates and forwards to HTTP after removing Origin; keep both identities. */
+export function controlOrigins(parentOrigin, transportOrigin) {
+  const parent = workspaceOrigin(parentOrigin);
+  const transport = loopbackOrigin(transportOrigin ?? parent);
+  return {parent, transport, forwarded: parent === DESKTOP_ORIGIN,
+    acceptsOrigin: origin => origin === parent || (parent === DESKTOP_ORIGIN && origin === undefined)};
+}

package/dist/descriptor.js

@@ -1,3 +1,4 @@
+import { isWorkspaceOrigin } from './workspace-origin.js';
 import { isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
 import { requireCondition, copy } from './errors.js';
@@ -14,6 +15,11 @@ export function loopbackOrigin(value) {
     'INVALID_ORIGIN', 'Only an explicit http://127.0.0.1:<port> origin is supported by this candidate.');
   return url.origin;
 }
+/** Workspace parent only; application upstream URLs still use loopbackOrigin. */
+export function workspaceOrigin(value) {
+  requireCondition(isWorkspaceOrigin(value), 'INVALID_ORIGIN', 'Expected an exact HTTP loopback or dsh-app://app workspace origin.');
+  return value;
+}
 /** npm package name (optionally scoped), at most 128 characters — the same shape the usage plugin accepts as `hanaRef`. */
 export const packageName = value => typeof value === 'string' && value.length <= 128 && /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
 export function validateDefinition(input) {

package/dist/dsh-compat.js

@@ -0,0 +1,6 @@
+import semver from 'semver';
+
+/** Public host compatibility; exact dependency versions in devDependencies remain reproducible test inputs. */
+export const DSH_RANGE='>=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0';
+/** saveExact entered the public PluginManager contract in 0.2.1-alpha.2. Unknown versions fail closed. */
+export function managerSupportsExactSave(version){return typeof version==='string'&&semver.satisfies(version,'>=0.2.1-alpha.2 <0.3.0-0',{includePrerelease:true});}

package/dist/dsh.d.ts

@@ -1,17 +1,19 @@
+import type {InstallationReaderConfig} from './installation-status.js';
 import type { AppHost, AppDefinition, AuthenticatedSubject, Awaitable, DshStorageBinding } from './index.js';
 export const name: 'hanamesh-app-host';
-export const DSH_TARGET: '0.2.0-rc.2';
+export const DSH_TARGET: '>=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0';
 export const inject: readonly ['webServer', 'storageDomain', 'connection'];
 export const BROWSER_PRINCIPAL: 'dsh-browser';
 export const ROUTES: readonly string[];
 export const Config: unknown;
 export const appHostDomainSpec: { readonly name: 'hanamesh_app_host'; readonly version: 1; readonly layout: 'single' };
 export interface DshPluginConfig {
-  dataRoot?: string; parentOrigin?: string; nodeBinary?: string; router?:{codingOauth?:{mode?:'http'|'file'}};
+  nodeRuntime?:{mode?:'managed'|'external';version?:string;sourceBase?:string;storageRoot?:string;externalBinary?:string};
+  dataRoot?: string; parentOrigin?: string; frameAncestors?: string[]; nodeBinary?: string; router?:{codingOauth?:{mode?:'http'|'file'}};
   /** `sources` undefined → the HanaMesh catalog source; explicit `[]` → none. `profileDir`/`profileName`/`dshBin` (and
-   *  `nodeBinary`) are inferred on plain DSH when undefined — see docs/CONTRACT.md 「应用库配置」; explicit values win. */
+   *  `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;allowPrerelease?:boolean};
+  library?:{fixture?:string;sources?:Array<{manifestUrl:string;enabled?:boolean}>;profileDir?:string;profileName?:string;dshBin?:string;registry?:string;allowPrerelease?:boolean;eventRetention?:number;installationReaders?:Partial<Record<'claude'|'codex',InstallationReaderConfig>>};
   applications?: AppDefinition[]; leaseTtlMs?: number; sweepIntervalMs?: number;
 }
 /** Adapt an open `ctx.storageDomain` handle (single layout, global snapshot) to the store binding. */
@@ -23,3 +25,18 @@ export function browserAuthentication(connection: { requestRejection(request: {
 };
 /** Cordis plugin entry; activates once webServer, storageDomain and connection are provided. */
 export function apply(ctx: unknown, config: DshPluginConfig): Promise<void>;
+
+/** AppHost-owned HTTP settings on GET/POST /hanamesh/library/suite-source. Catalog sources stay independent. */
+export type SuiteSourceMode='configured'|'core';
+/** Public Core protocol-1 observation; no provider revision, generation or watch is supplied. */
+export interface CoreSuiteSourceState {
+  readonly protocolVersion:'1';readonly status:'disabled'|'ready'|'failed'|'disposed';
+  readonly selection:'configured'|'custom'|'disabled';readonly registry:string|null;
+  readonly archiveCount:number;readonly lastError:string|null;
+}
+export interface SuiteSourceSettings {
+  readonly mode:SuiteSourceMode;readonly configuredRegistry:string;
+  readonly observation:{readonly observable:true;readonly state:CoreSuiteSourceState}|{readonly observable:false;readonly code:string};
+}
+/** POST accepts exactly this shape; saving selects a source and does not authorize installation. */
+export interface SuiteSourceSettingsInput {mode:SuiteSourceMode;}

package/dist/dsh.js

@@ -1,6 +1,7 @@
+import { createInstallationStatusReader } from './library/installation-status.js';
 /**
- * DSH plugin entry for @hanamesh/dsh-app-host, bound to the PINNED public APIs
- * of the official DSH 0.2.0-rc.2 release:
+ * 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:
  *
  *   ctx.storageDomain.open(spec)      @deepseek-ai/dsh-storage-domain  — `single` layout, one
  *                                     global snapshot; `global.set()` is one whole-image publish
@@ -23,7 +24,7 @@ import { defineDomain } from '@deepseek-ai/dsh-storage-domain';
 import { AppHost } from './manager.js';
 import { DshDomainSnapshotStore, emptySnapshot } from './store.js';
 import { createHttpHandler } from './routes.js';
-import { requireCondition } from './errors.js';
+import { requireCondition,SerialQueue } from './errors.js';
 import { routerDomainSpec } from './router/domain.js';
 import { createProviderSources } from './router/sources.js';
 import { createRouter } from './router/broker.js';
@@ -31,40 +32,55 @@ import { createRouterHttpHandler, ROUTER_ROUTES } from './router/routes.js';
 import { libraryDomainSpec } from './library/domain.js';
 import { createLibraryService } from './library/service.js';
 import { createLibraryInstaller } from './library/install.js';
-import { resolveLibraryLocations } from './library/locate.js';
+import { inferDesktopLayout, resolveLibraryLocations } from './library/locate.js';
 import { createLibraryHttpHandler, LIBRARY_ROUTES } from './library/routes.js';
+import { createHandoffQueue, createHandoffHandler, createHandoffListener } from './library/handoff.js';
+import { detectClient } from './library/client-identity.js';
 import { createUsageEvidence } from './usage-evidence.js';
 import { createReceiptLedger } from './router/receipts.js';
 import { receiptsDomainSpec } from './router/receipts-domain.js';
+import {createNodeRuntime} from './node-runtime/service.js';
+import {nodeRuntimeDomainSpec} from './node-runtime/domain.js';
+import {nodeBinding,nodeStatusBinding} from './library/node-binding.js';
+import {DSH_RANGE} from './dsh-compat.js';
 
 export const name = 'hanamesh-app-host';
-export const DSH_TARGET = '0.2.0-rc.2';
+export const DSH_TARGET = DSH_RANGE;
 export const inject = ['webServer', 'storageDomain', 'connection'];
 /** One authenticated local browser session per profile; DSH web has no per-user principals. */
 export const BROWSER_PRINCIPAL = 'dsh-browser';
 /** Every route the HTTP handler answers; registered individually so nothing else is shadowed. */
 export const ROUTES = Object.freeze(['/hanamesh/apps', '/apps/open', '/apps/resume', '/apps/recover',
-  '/apps/close', '/apps/heartbeat', '/apps/stop', '/apps/events']);
+  '/apps/close', '/apps/heartbeat', '/apps/stop', '/apps/events', '/apps/bootstrap-authorize']);
 
 export const Config = z.object({
   /** Absolute canonical directory that owns every instance data root (secureDirectory refuses symlinks). */
   dataRoot: z.string().default(join(process.env.DSH_HOME ?? process.env.HOME ?? '.', 'data', 'hanamesh-apps')),
-  /** Exact loopback workspace origin; defaults to the running web server's own origin. */
+  /** Exact workspace origin; inferred Desktop uses dsh-app://app, plain DSH uses HTTP loopback. */
   parentOrigin: z.string(),
   /** Extra origins allowed as frame ancestors of app views — the desktop shell's own webview origin
    *  (e.g. `tauri://localhost`) when the DSH workspace itself runs inside the shell's iframe. */
-  frameAncestors: z.array(z.string()),
+  frameAncestors: z.union([z.array(z.string()),z.const(undefined)]),
   /** Standalone Node executable used for guardian/launcher processes; required under Electron. */
   nodeBinary: z.string(),
+  nodeRuntime:z.object({mode:z.string(),version:z.string(),sourceBase:z.string(),storageRoot:z.string(),externalBinary:z.string()}),
   router: z.object({ codingOauth: z.object({ mode:z.string() }) }),
   library: z.object({
     fixture:z.string(),
     /** Undefined (not configured) → the HanaMesh catalog source; an explicit `[]` → no source. schemastery would
      *  coerce a missing array to `[]`, so the union keeps "unset" distinguishable from "deliberately empty". */
     sources:z.union([z.array(z.any()),z.const(undefined)]),
-    /** All four are set by the desktop shell overlay; on plain DSH they are inferred (see library/locate.js). */
+    /** 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(),allowPrerelease:z.boolean(),
+    /** Publicly named event history capacity; a lost cursor reports resetRequired. */
+    eventRetention:z.number().default(512),
+    /** Explicit official CLI readers; unset means unknown, never inferred from PATH or private files. */
+    installationReaders:z.union([z.any(),z.const(undefined)]),
+    /** Website → client handoff listener (library/handoff.js). Unset fields use the defaults shown in the library
+     *  settings page, where they can also be changed (saved values win over this config). */
+    handoff:z.object({enabled:z.boolean(),ports:z.union([z.array(z.number()),z.const(undefined)]),
+      allowedOrigins:z.union([z.array(z.string()),z.const(undefined)]),ttlMs:z.number(),pollMs:z.number()}),
   }),
   applications: z.array(z.any()).default([]),
   leaseTtlMs: z.number(),
@@ -115,80 +131,155 @@ 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 parentOrigin = config.parentOrigin ?? `http://127.0.0.1:${webServer.port}`;
-  const domain = await facility.open(appHostDomainSpec);
-  let routerDomain,receiptsDomain,receipts,libraryDomain,library;
-  const store = new DshDomainSnapshotStore(domainBinding(domain));
-  const host = new AppHost({ store, dataRoot, parentOrigin, frameAncestors: config.frameAncestors ?? [],
-    ...(config.nodeBinary === undefined ? {} : { nodeBinary: config.nodeBinary }),
-    ...(config.leaseTtlMs === undefined ? {} : { leaseTtlMs: config.leaseTtlMs }),
-    ...(config.sweepIntervalMs === undefined ? {} : { sweepIntervalMs: config.sweepIntervalMs }) });
+  const desktop = await inferDesktopLayout();
+  const transportOrigin = `http://127.0.0.1:${webServer.port}`;
+  const parentOrigin = config.parentOrigin ?? desktop?.parentOrigin ?? transportOrigin;
+  const frameAncestors = config.frameAncestors ?? desktop?.frameAncestors ?? [];
+  const locations = await resolveLibraryLocations(config.library??{}, {nodeBinary:config.nodeBinary, desktop});
+  // Pair each acquisition immediately, including partial route registration.
+  // The same once-only release belongs to both failed startup and Cordis unload.
+  const acquired = [];
+  let closing = false, cleanupTail = Promise.resolve();
+  const drain = () => {
+    closing = true;
+    const pending = cleanupTail.then(async () => {
+      const failed = [];
+      while (acquired.length) {
+        const { label, release } = acquired.pop();
+        try { await release(); }
+        catch {
+          failed.push(label);
+          try { ctx.logger?.warn?.('APPHOST_CLEANUP_FAILED %s', label); } catch {}
+        }
+      }
+      requireCondition(failed.length === 0, 'APPHOST_CLEANUP_FAILED',
+        'AppHost resource cleanup failed.', { resources:failed });
+    });
+    cleanupTail = pending.catch(() => {});
+    return pending;
+  };
+  // Cordis unloads separate effects concurrently. One drain preserves resource
+  // dependencies, including ledger persistence and stopping before domain close.
+  ctx.effect(() => drain, 'hanameshApps.dispose');
+  const own = (label, action) => {
+    let pending;
+    const release = () => pending ??= (async () => { await action(); })();
+    acquired.push({ label, release });
+    // If an awaited acquisition completed after unload began, catch drains its
+    // newly acquired resource too; no further activation can publish a seat.
+    requireCondition(!closing, 'HOST_CLOSED', 'AppHost activation is being disposed.');
+    return release;
+  };
+  const optional = (name, receive) => {
+    const listener = ctx.inject([name], injected => {
+      receive(injected.get(name)); return () => receive(undefined);
+    });
+    own(`listener:${name}`, () => listener.dispose());
+  };
+  let host, store, nodeRuntime, library;
   let initialized = false;
   try {
+    const nodeDomain=await facility.open(nodeRuntimeDomainSpec);
+    own('node-runtime-domain',()=>nodeDomain.close());
+    nodeRuntime=createNodeRuntime({domain:nodeDomain,dataRoot,config:config.nodeRuntime,initialBinary:locations.nodeBinary,
+      busy:()=>Boolean(library?.events().operations.length)||Boolean(host?.instanceList(BROWSER_PRINCIPAL).some(i=>!['stopped','failed','interrupted'].includes(i.status)))});
+    own('node-runtime',()=>nodeRuntime.close());await nodeRuntime.init();
+    const domain = await facility.open(appHostDomainSpec);
+    const closeDomain = own('app-domain', () => domain.close());
+    store = new DshDomainSnapshotStore(domainBinding({ global:domain.global, close:closeDomain }));
+    host = new AppHost({ store, dataRoot, parentOrigin, frameAncestors,
+      nodeBinaryProvider:()=>nodeRuntime.executable,
+      ...(config.leaseTtlMs === undefined ? {} : { leaseTtlMs: config.leaseTtlMs }),
+      ...(config.sweepIntervalMs === undefined ? {} : { sweepIntervalMs: config.sweepIntervalMs }) });
+    own('host', () => initialized ? host.dispose() : store.close());
     for (const definition of config.applications ?? []) host.register(definition);
     await host.init(); initialized = true;
-    const auth = { parentOrigin, ...browserAuthentication(connection) };
+    const auth = { parentOrigin, transportOrigin, ...browserAuthentication(connection) };
     const handler = createHttpHandler(host, auth);
-    const disposers = ROUTES.map(path => webServer.register({ kind: 'exact', path, handler }));
-    let credentialService, llmService, oauthService, usageService;
-    ctx.inject(['credentials'], injected => { credentialService=injected.get('credentials');return()=>{credentialService=undefined;}; });
-    // rc.27: usage evidence goes through the usage plugin's record seat when (and only when) that plugin is loaded.
-    ctx.inject(['hanameshUsage'], injected => { usageService=injected.get('hanameshUsage');return()=>{usageService=undefined;}; });
-    // T6: hourly usage receipts live in app-host's own domain; the usage `use` event carries the hour's receipt.
-    receiptsDomain = await facility.open(receiptsDomainSpec);
-    receipts = createReceiptLedger({ domain:receiptsDomain });
+    for (const path of ROUTES) own(`route:${path}`, webServer.register({ kind:'exact', path, handler }));
+    let credentialService, llmService, oauthService, usageService, coreService, suiteSourceService;
+    optional('credentials', service => { credentialService=service; });
+    // Optional Usage service presence does not provide original application success facts.
+    optional('hanameshUsage', service => { usageService=service; });
+    optional('hanameshCore', service => { coreService=service; });
+    optional('hanameshSuiteSource', service => { suiteSourceService=service; });
+    // Router hourly counts remain local diagnostics, never synthesized Usage open/use facts.
+    const receiptsDomain = await facility.open(receiptsDomainSpec);
+    own('receipts-domain', () => receiptsDomain.close());
+    const receipts = createReceiptLedger({ domain:receiptsDomain });
+    own('receipts', () => receipts.close());
     const evidence = createUsageEvidence({ host, seat:()=>usageService, receipts, logger:ctx.logger });
-    ctx.effect(() => async () => { evidence.close(); await evidence.settle(); await receipts.close(); await receiptsDomain.close(); }, 'hanameshApps.usage');
-    ctx.inject(['llm'], injected => { llmService=injected.get('llm');return()=>{llmService=undefined;}; });
-    ctx.inject(['hanameshOAuth'], injected => { oauthService=injected.get('hanameshOAuth');return()=>{oauthService=undefined;}; });
+    own('usage', async () => { evidence.close(); await evidence.settle(); });
+    optional('llm', service => { llmService=service; });
+    optional('hanameshOAuth', service => { oauthService=service; });
     const credentials = {
       describe: async ref => credentialService ? await credentialService.describe(ref) : { configured:false,writable:false },
       resolve: async ref => credentialService ? await credentialService.resolve(ref) : undefined,
       describeRecord: async key => credentialService ? await credentialService.describeRecord(key) : { configured:false,writable:false },
     };
-    routerDomain = await facility.open(routerDomainSpec);
+    const routerDomain = await facility.open(routerDomainSpec);
+    own('router-domain', () => routerDomain.close());
     const sources = createProviderSources({ credentials, apps:host, llm:()=>llmService,
       webOrigin:`http://127.0.0.1:${webServer.port}`, codingOauth:config.router?.codingOauth });
     const router = createRouter({ credentials, domain:routerDomain, apps:host, sources, oauth:()=>oauthService, receiptLedger:receipts,
       onInject:({ appId, instanceId, routes }) => { receipts.inject({ appId, instanceId, routes }); } });
-    const detachResolver=host.setCredentialResolver(router.credentialResolver),detachObserver=host.subscribe(router.observe);
+    own('resolver', host.setCredentialResolver(router.credentialResolver));
+    own('router-observer', host.subscribe(router.observe));
     const routerHandler=createRouterHttpHandler(router,auth);
-    const routerDisposers=ROUTER_ROUTES.map(path=>webServer.register({kind:'exact',path,handler:routerHandler}));
-    libraryDomain=await facility.open(libraryDomainSpec);
-    // Explicit config wins; on plain DSH (no shell overlay) the profile, DSH bin and Node are inferred from this process.
-    const locations=await resolveLibraryLocations(config.library??{},{nodeBinary:config.nodeBinary});
+    for (const path of ROUTER_ROUTES) own(`route:${path}`, webServer.register({kind:'exact',path,handler:routerHandler}));
+    const libraryDomain=await facility.open(libraryDomainSpec);
+    const closeLibraryDomain=own('library-domain', () => libraryDomain.close());
+    // Explicit config wins; infer only proven process/profile locations.
     const libraryConfig={...(config.library??{}),sources:locations.sources,profileDir:locations.profileDir,profileName:locations.profileName};
     if(locations.inferred.length&&typeof ctx.logger?.info==='function')ctx.logger.info('hanamesh-app-host library: inferred %s',JSON.stringify(Object.fromEntries(
       locations.inferred.map(key=>[key,key==='sources'?locations.sources.map(source=>source.manifestUrl):locations[key]]))));
-    let provisionApi,installer;
-    if(locations.profileDir&&locations.profileName&&locations.nodeBinary){
-      let dshBin=locations.dshBin;
-      if(!dshBin)try{dshBin=createRequire(join(locations.profileDir,'package.json')).resolve('@deepseek-ai/dsh/lib/bin.js');}catch{dshBin=undefined;}
-      if(dshBin){
-        provisionApi=await import('./provision/index.js');
-        installer=createLibraryInstaller({profileDir:locations.profileDir,profileName:locations.profileName,dataRoot,nodeBinary:locations.nodeBinary,
-          dshBin,registry:libraryConfig.registry,allowPrerelease:libraryConfig.allowPrerelease,provision:provisionApi.provision,remove:provisionApi.remove,
-          emit:event=>library?.emit(event)});
-      }
+    // Exact-save capability comes from the host's public package metadata. Older managers use the public CLI
+    // for installs and preserve restart-required; applications and compensation also use that CLI.
+    let pluginManager;
+    optional('pluginManager', service => { pluginManager=service; });
+    let dshBin=locations.dshBin;
+    if(!dshBin&&locations.profileDir&&!desktop)try{dshBin=createRequire(join(locations.profileDir,'package.json')).resolve('@deepseek-ai/dsh/lib/bin.js');}catch{dshBin=undefined;}
+    const cliUsable=Boolean(locations.desktopLauncher||dshBin&&(!desktop||locations.desktopCli||config.library?.dshBin));
+    let provisionApi,installer;const profileWriter=new SerialQueue();
+    if(locations.profileDir&&locations.profileName){
+      provisionApi=await import('@hanamesh/lib-provision');
+      installer=nodeBinding(()=>nodeRuntime.executable,nodeBinary=>createLibraryInstaller({profileDir:locations.profileDir,profileName:locations.profileName,dataRoot,
+        ...(cliUsable?{nodeBinary,dshBin,desktopCli:locations.desktopCli,desktopLauncher:locations.desktopLauncher}:{}),pluginManagerVersion:locations.pluginManagerVersion,profileWriter,
+        registry:libraryConfig.registry,allowPrerelease:libraryConfig.allowPrerelease,provision:provisionApi.provision,remove:provisionApi.remove,ledger:provisionApi.ledger,
+        coreService:()=>coreService,suiteSourceService:()=>suiteSourceService,suiteSourceMode:()=>library?.suiteSourceSettings().mode??'configured',pluginManager:()=>pluginManager,emit:event=>library?.emit(event)}));
     }
-    library=createLibraryService({domain:libraryDomain,host,config:libraryConfig,dataRoot,ledgerReader:provisionApi?.ledger??(async()=>({schema:1,items:{}})),installer});
+    /** What a person must do so the library can install, in their words (C-MARKET probe `error.need`). */
+    const unavailable=()=>{
+      if(!locations.profileDir)return[{need:'找不到这个 DSH profile 的目录',how:'用 dsh plugin --profile <名字> add 安装 HanaMesh 应用库，或在插件设置 library.profileDir 里填 profile 目录'}];
+      if(installer?.ready)return[];
+      if(!nodeRuntime.executable)return[{need:'安装环境尚未准备',how:'打开 AppHost「安装环境」，点击「准备安装环境」，核对来源、版本与体积后确认；完成后自动可用，无需重启或填写路径。'}];
+      if(installer?.unavailable?.length)return installer.unavailable;
+      const rows=[];
+      if(!locations.nodeBinary)rows.push({need:'找不到能运行 DSH 命令行的 Node',how:'在 AppHost 插件配置中，将 nodeBinary 填为独立 Node.js 24 的绝对路径（24.13.1 或更新的 24.x）；完全退出后重开。'});
+      if(!dshBin||(desktop&&!locations.desktopCli&&!config.library?.dshBin))rows.push({need:'找不到可在受控进程中运行的 DSH 命令行',how:'恢复客户端随附的公开 dsh 命令启动器，或在插件设置 library.dshBin 里填 dsh 的 lib/bin.js'});
+      return rows;
+    };
+    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,readers:libraryConfig.installationReaders})),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
     // which appId, and that package name is the usage-evidence `hanaRef`. Scan failure only costs evidence, never startup.
-    try { for (const row of await library.installed()) if (row.appId && row.packageName) { try { host.bindPackageName(row.appId,row.packageName); } catch {} } }
+    try { for (const row of await library.installed()) if (row.appId && row.packageName) { try { host.bindPackageName(row.appId,row.packageName); } catch (error) { ctx.logger?.warn?.('hanamesh-app-host usage: %s not bound to %s (%s)', row.appId, row.packageName, error?.code ?? error?.message); } } }
     catch (error) { if (typeof ctx.logger?.debug === 'function') ctx.logger.debug('hanamesh-app-host usage: installed scan unavailable (%s)', error?.code ?? error?.message); }
-    const libraryHandler=createLibraryHttpHandler(library,auth);
-    const libraryDisposers=LIBRARY_ROUTES.map(path=>webServer.register({kind:'exact',path,handler:libraryHandler}));
-    ctx.effect(() => () => { for (const dispose of disposers.splice(0)) dispose(); }, 'hanameshApps.routes');
-    ctx.effect(() => async () => { for(const dispose of routerDisposers.splice(0))dispose();detachResolver();detachObserver();await routerDomain.close(); }, 'hanameshApps.router');
-    ctx.effect(() => async () => { for(const dispose of libraryDisposers.splice(0))dispose();await library.close(); }, 'hanameshApps.library');
-    ctx.provide('hanameshApps', host);
+    const queue=createHandoffQueue({ttlMs:()=>library.handoffSettings().ttlMs,onError:(message,error)=>ctx.logger?.warn?.('%s: %s',message,error?.message??error)});
+    own('handoff-observer', library.observe(event=>queue.observe(event)));
+    const listener=createHandoffListener({settings:()=>library.handoffSettings(),logger:ctx.logger,
+      handlerFor:port=>createHandoffHandler({library,queue,settings:()=>library.handoffSettings(),port})});
+    own('handoff-listener', () => listener.stop());
+    await listener.start();
+    const libraryHandler=createLibraryHttpHandler(library,{...auth,nodeRuntime,handoff:{queue,listener,restart:()=>listener.start()}});
+    for (const path of LIBRARY_ROUTES) own(`route:${path}`, webServer.register({kind:'exact',path,handler:libraryHandler}));
+    own('seat', ctx.provide('hanameshApps', host));
   } catch (error) {
-    await library?.close().catch(()=>{});await libraryDomain?.close().catch(()=>{});await routerDomain?.close().catch(()=>{});await receipts?.close().catch(()=>{});await receiptsDomain?.close().catch(()=>{});
-    if (initialized) await host.dispose().catch(() => {}); else await store.close().catch(() => {});
+    // Cleanup names failures without replacing the original activation error.
+    await drain().catch(() => {});
     throw error;
   }
-  // Disposal order: routes go first (registered later, disposed earlier by Cordis), then the host
-  // stops every owned instance and closes the domain. An attached instance is never signalled.
-  ctx.effect(() => async () => { await host.dispose(); }, 'hanameshApps.dispose');
 }