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

package/dist/manager.js

@@ -3,7 +3,7 @@ import { join, resolve, dirname } from 'node:path';
 import { access, mkdir, writeFile, rm } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { AppHostError, requireCondition, SerialQueue, copy } from './errors.js';
-import { validateDefinition, identifier, fingerprint, expand, loopbackOrigin, packageName as validPackageName } from './descriptor.js';
+import { validateDefinition, identifier, fingerprint, expand, workspaceOrigin, packageName as validPackageName } from './descriptor.js';
 import { secureDirectory } from './store.js';
 import { freePort, spawnOwned, waitReady } from './runtime.js';
 import { FixedGateway, ancestorOrigin } from './gateway.js';
@@ -24,19 +24,21 @@ export class AppHost {
   #queue = new SerialQueue(); #definitions = new Map(); #controls = new Map(); #listeners = new Set();
   #packageNames = new Map(); #activityListeners = new Set();
   #logs = new Map(); #state; #initialized = false; #closing = false; #poisoned = false; #timer; #disposing;
-  #credentialResolver = null; #nodeBinary; #runtimeLedgerReader;
+  #credentialResolver = null; #nodeBinary; #nodeBinaryProvider; #runtimeLedgerReader;
   constructor({ store, dataRoot, parentOrigin, frameAncestors = [], leaseTtlMs = 90_000, sweepIntervalMs = 15_000,
-    checkpoint = async () => {}, clock = () => Date.now(), credentialResolver = null, nodeBinary,
-    runtimeLedgerReader = async root => (await import('./provision/index.js')).ledger(root) }) {
+    checkpoint = async () => {}, clock = () => Date.now(), credentialResolver = null, nodeBinary, nodeBinaryProvider,
+    runtimeLedgerReader = async root => (await import('@hanamesh/lib-provision')).ledger(root) }) {
     requireCondition(store && ['init','load','save','close'].every(k => typeof store[k] === 'function'),
       'INVALID_STORE','A durable snapshot store is required.');
     requireCondition(typeof dataRoot === 'string' && resolve(dataRoot) === dataRoot,'INVALID_ROOT','dataRoot must be an absolute canonical path.');
     requireCondition(Number.isSafeInteger(leaseTtlMs) && leaseTtlMs >= 100 && leaseTtlMs <= 3_600_000 &&
       Number.isSafeInteger(sweepIntervalMs) && sweepIntervalMs >= 0 && sweepIntervalMs <= 3_600_000,
       'INVALID_TIMEOUT','Invalid lease or sweep timing.');
-    this.store = store; this.dataRoot = dataRoot; this.parentOrigin = loopbackOrigin(parentOrigin); this.frameAncestors = frameAncestors.map(ancestorOrigin);
+    this.store = store; this.dataRoot = dataRoot; this.parentOrigin = workspaceOrigin(parentOrigin); this.frameAncestors = frameAncestors.map(ancestorOrigin);
     this.leaseTtlMs = leaseTtlMs; this.sweepIntervalMs = sweepIntervalMs; this.checkpoint = checkpoint; this.clock = clock;
     this.#nodeBinary = nodeBinary;
+    requireCondition(nodeBinaryProvider===undefined||typeof nodeBinaryProvider==='function','INVALID_RUNTIME','nodeBinaryProvider must be a function.');
+    this.#nodeBinaryProvider=nodeBinaryProvider;
     requireCondition(typeof runtimeLedgerReader === 'function','INVALID_RUNTIME','runtimeLedgerReader must be a function.');
     this.#runtimeLedgerReader = runtimeLedgerReader;
     this.setCredentialResolver(credentialResolver);
@@ -168,6 +170,7 @@ export class AppHost {
     try { await this.store.save(next); }
     catch (error) { if (error.code === 'COMMIT_UNCERTAIN') this.#poisoned = true; throw error; }
     this.#state = next;
+    for (const control of this.#controls.values()) control.gateway?.revokeInactive();
     for (const event of next.events) if (event.sequence > oldSequence) this.#notify(event);
   }
   #findLease(state,principalId,viewId) { return state.leases.find(l => l.principalId === principalId && l.viewId === viewId); }
@@ -307,7 +310,7 @@ export class AppHost {
     return prepared;
   }
   async #openResult(prepared, input, principalId, requireReady) {
-    return await this.#queue.run(() => {
+    return await this.#queue.run(async () => {
       this.#assertOpen();
       const lease = this.#findLease(this.#state,principalId,input.viewId);
       this.#checkToken(lease,prepared.token);
@@ -317,10 +320,23 @@ export class AppHost {
       if (requireReady) requireCondition(instance.status === 'ready','INSTANCE_NOT_READY','Instance is not ready.');
       return { instance:publicInstance(instance),lease:publicLease(lease),leaseToken:prepared.token,
         uiUrl:instance.status !== 'ready' ? null : (prepared.control.gateway ?
-          prepared.control.gateway.issue(leaseKey(principalId,input.viewId,lease.generation)) : instance.endpoint),
+          await prepared.control.gateway.issueAsync(leaseKey(principalId,input.viewId,lease.generation)) : instance.endpoint),
         originalSessionId:lease.originalSessionId };
     });
   }
+  async authorizeBootstrap(input, principalId='host') {
+    return await this.#queue.run(() => {
+      this.#assertOpen();
+      requireCondition(input && Object.keys(input).every(k=>['viewId','leaseToken','gatewayOrigin','challenge'].includes(k)) &&
+        typeof input.gatewayOrigin === 'string' && typeof input.challenge === 'string' && /^[a-f0-9]{64}$/.test(input.challenge),
+        'INVALID_REQUEST','Expected a bound bootstrap challenge.');
+      const lease=this.#findLease(this.#state,principalId,input.viewId);this.#checkToken(lease,input.leaseToken);
+      requireCondition(active(lease,this.clock()),'LEASE_EXPIRED','Inactive view.',{},403);
+      const control=this.#controls.get(lease.instanceId);
+      requireCondition(control?.gateway,'INSTANCE_NOT_READY','Gateway is not ready.');
+      return control.gateway.authorizeChallenge(leaseKey(principalId,input.viewId,lease.generation),input.gatewayOrigin,input.challenge);
+    });
+  }
   async beginOpen(input,principalId='host') {
     const prepared = await this.#prepareOpen(input,principalId);
     return await this.#openResult(prepared,input,principalId,false);
@@ -385,7 +401,7 @@ export class AppHost {
       XDG_STATE_HOME:join(instance.dataDir,'state'),XDG_DATA_HOME:instance.dataDir,
     };
     control.origin=`http://127.0.0.1:${port}`;
-    control.runner=await spawnOwned({ nodeBinary:this.#nodeBinary,command,args:deployment.args.map(value => expand(value,values)),
+    control.runner=await spawnOwned({ nodeBinary:this.#nodeBinaryProvider?this.#nodeBinaryProvider():this.#nodeBinary,command,args:deployment.args.map(value => expand(value,values)),
       cwd:deployment.cwd ?? instance.dataDir,dataDir:instance.dataDir,port,env,stopGraceMs:deployment.stopGraceMs,secrets:credentials.secrets },{
       onLog:(stream,text) => {
         const records=this.#logs.get(instance.id) ?? [];

package/dist/node-runtime/domain.js

@@ -0,0 +1,6 @@
+import {defineDomain} from '@deepseek-ai/dsh-storage-domain';
+import {z} from 'zod';
+export const nodeRuntimeDomainSpec=defineDomain({name:'hanamesh_node_runtime',version:1,layout:'single',tables:{},global:{
+ schema:z.object({schema:z.literal(1),revision:z.number().int().nonnegative(),settings:z.record(z.string(),z.unknown()).nullable(),active:z.record(z.string(),z.unknown()).nullable()}),
+ initial:{schema:1,revision:0,settings:null,active:null},
+}});

package/dist/node-runtime/releases.json

@@ -0,0 +1,59 @@
+{
+  "keyringCommit": "481637f813e912c4aa3622d7964ab426c97b8e8d",
+  "archives": [
+    {
+      "version": "24.13.1",
+      "platform": "darwin-arm64",
+      "asset": "node-v24.13.1-darwin-arm64.tar.gz",
+      "sha256": "8c039d59f2fec6195e4281ad5b0d02b9a940897b4df7b849c6fb48be6787bba6",
+      "bytes": 51007946,
+      "unpackedBytes": 189519272,
+      "files": 4559,
+      "url": "https://nodejs.org/dist/v24.13.1/node-v24.13.1-darwin-arm64.tar.gz",
+      "licenseSha256": "9ef8d3fa97d90d93543ee9e2b71394de59c09d8057625fd355d45303243527a3",
+      "signatureVerified": true,
+      "keyringCommit": "481637f813e912c4aa3622d7964ab426c97b8e8d"
+    },
+    {
+      "version": "24.13.1",
+      "platform": "darwin-x64",
+      "asset": "node-v24.13.1-darwin-x64.tar.gz",
+      "sha256": "527f0578d9812e7dfa225121bda0b1546a6a0e4b5f556295fc8299c272de5fbf",
+      "bytes": 52182519,
+      "unpackedBytes": 191849205,
+      "files": 4559,
+      "url": "https://nodejs.org/dist/v24.13.1/node-v24.13.1-darwin-x64.tar.gz",
+      "licenseSha256": "9ef8d3fa97d90d93543ee9e2b71394de59c09d8057625fd355d45303243527a3",
+      "signatureVerified": true,
+      "keyringCommit": "481637f813e912c4aa3622d7964ab426c97b8e8d"
+    },
+    {
+      "version": "24.22.0",
+      "platform": "darwin-arm64",
+      "asset": "node-v24.22.0-darwin-arm64.tar.gz",
+      "sha256": "6a9724d9b50a5f22b4816cded441b5a8d9ddae546191a5e5b7efa5a5e2ee26d5",
+      "bytes": 53049576,
+      "unpackedBytes": 197365224,
+      "files": 4797,
+      "url": "https://nodejs.org/dist/v24.22.0/node-v24.22.0-darwin-arm64.tar.gz",
+      "licenseSha256": "5888dbb9a1d2b18f2c3e6c5f6af1b39de658372b402a0577b002777f14c62ace",
+      "signatureVerified": true,
+      "keyringCommit": "481637f813e912c4aa3622d7964ab426c97b8e8d"
+    },
+    {
+      "version": "24.22.0",
+      "platform": "darwin-x64",
+      "asset": "node-v24.22.0-darwin-x64.tar.gz",
+      "sha256": "495e3f273c645f3c4677d438304cdfc701729ea5dec5728f5c8e76a2dece4b91",
+      "bytes": 54356645,
+      "unpackedBytes": 200534581,
+      "files": 4797,
+      "url": "https://nodejs.org/dist/v24.22.0/node-v24.22.0-darwin-x64.tar.gz",
+      "licenseSha256": "5888dbb9a1d2b18f2c3e6c5f6af1b39de658372b402a0577b002777f14c62ace",
+      "signatureVerified": true,
+      "keyringCommit": "481637f813e912c4aa3622d7964ab426c97b8e8d"
+    }
+  ],
+  "verification": "official signed SHASUMS gpgv; SHA match; no runtime execution",
+  "defaultVersion": "24.22.0"
+}

package/dist/node-runtime/service.js

@@ -0,0 +1,101 @@
+/** Plugin-owned standalone runtime. Nothing downloads during activation, planning or settings saves. */
+import {readFile,statfs,lstat,access} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {execFile} from 'node:child_process';
+import {promisify} from 'node:util';
+import {release} from 'node:os';
+import {join,dirname,isAbsolute,resolve} from 'node:path';
+import {randomUUID} from 'node:crypto';
+import * as provisionApi from '@hanamesh/lib-provision';
+import {AppHostError,requireCondition,copy} from '../errors.js';
+import {secureDirectory,FileLock} from '../store.js';
+const run=promisify(execFile);
+const catalog=JSON.parse(await readFile(new URL('./releases.json',import.meta.url),'utf8'));
+export const NODE_SETTING_NAMES=Object.freeze({mode:'安装环境管理方式',version:'独立 Node 固定版本',sourceBase:'Node 下载来源',storageRoot:'独立 Node 存放位置',externalBinary:'已有独立 Node 路径（高级）'});
+const fields=Object.keys(NODE_SETTING_NAMES);
+const plain=x=>x&&typeof x==='object'&&!Array.isArray(x);
+const exact=(input,keys)=>requireCondition(plain(input)&&Object.keys(input).every(k=>keys.includes(k)),'NODE_INPUT_INVALID','安装环境的请求包含不支持的字段。');
+const checkScript="console.log(JSON.stringify({version:process.versions.node,platform:process.platform,arch:process.arch,electron:process.versions.electron??null}))";
+export async function probeStandaloneNode(binary,{platform,version,signal}={}){
+ requireCondition(typeof binary==='string'&&isAbsolute(binary),'NODE_BINARY_INVALID','独立 Node 路径必须是绝对路径。');
+ await access(binary,constants.X_OK);
+ const {stdout}=await run(binary,['-e',checkScript],{env:{PATH:''},maxBuffer:4096,signal});
+ let actual;try{actual=JSON.parse(stdout);}catch{throw new AppHostError('NODE_NOT_STANDALONE','所选文件没有返回独立 Node 的检查结果；Electron 包装脚本不能代替独立 Node。');}
+ requireCondition(actual.electron===null&&/^24\./.test(actual.version)&&(Number(actual.version.split('.')[1])>13||Number(actual.version.split('.')[1])===13&&Number(actual.version.split('.')[2])>=1)&&(!version||actual.version===version)&&`${actual.platform}-${actual.arch}`===platform,'NODE_NOT_STANDALONE','需要当前平台的独立 Node.js 24（24.13.1 或更新）；所选文件的版本、平台或 Electron 检查未通过。');
+ return actual;
+}
+async function safeAncestors(path){
+ let p=path;
+ while(true){try{const info=await lstat(p);requireCondition(info.isDirectory()&&!info.isSymbolicLink(),'NODE_STORAGE_UNSAFE','存放位置不能经过符号链接或普通文件。');}catch(e){if(e.code!=='ENOENT')throw e;}
+  const parent=dirname(p);if(p===parent)break;p=parent;}
+}
+async function diskBytes(path){let p=path;while(true){try{const info=await statfs(p,{bigint:true});return Number(info.bavail*info.bsize);}catch(e){if(e.code!=='ENOENT'||p===dirname(p))throw e;p=dirname(p);}}}
+const causeText=e=>String(e?.message??e).slice(0,1500);
+/** Ports are public lib-provision and storage-domain; test substitutes never enter the normal plugin package. */
+export function createNodeRuntime({domain,dataRoot,config={},initialBinary,platform=`${process.platform}-${process.arch}`,kernelRelease=release(),provisionApi:api=provisionApi,probe=probeStandaloneNode,freeBytes=diskBytes,busy=()=>false,checkpoint=async()=>{},lockFactory=path=>new FileLock(path,{reclaimDead:true})}){
+ const defaultSettings={mode:initialBinary?'external':'managed',version:catalog.defaultVersion,sourceBase:'https://nodejs.org/dist',storageRoot:join(dataRoot,'managed-node'),externalBinary:initialBinary??''};
+ let state,settings,executable,operation=null,plan=null,closed=false,saving=false,pending=Promise.resolve(),controller;
+ const supported=['darwin-arm64','darwin-x64'].includes(platform)&&Number(kernelRelease.split('.')[0])>=22&&(Number(kernelRelease.split('.')[0])>22||Number(kernelRelease.split('.')[1])>=6);
+ const available=()=>{requireCondition(!closed,'NODE_CLOSED','安装环境页面已关闭。');};
+ const idle=()=>{available();requireCondition(!saving&&!controller&&!['preparing','committing'].includes(operation?.state)&&!busy(),'NODE_IN_USE','安装环境正在准备或有插件操作运行，请完成或取消后再修改。');};
+ function validate(next){
+  exact(next,fields);requireCondition(fields.every(k=>typeof next[k]==='string')&&['managed','external'].includes(next.mode),'NODE_SETTINGS_INVALID','请填写完整的安装环境设置。');
+  requireCondition(catalog.archives.some(a=>a.version===next.version),'NODE_VERSION_UNSUPPORTED','请选择已校验的固定 Node 版本，不能填写 latest。');
+  let source;try{source=new URL(next.sourceBase);}catch{}
+  requireCondition(source?.protocol==='https:'&&!source.username&&!source.password&&!source.search&&!source.hash,'NODE_SOURCE_INVALID','下载来源必须是没有账号、密码、查询参数的 HTTPS 地址。');
+  requireCondition(isAbsolute(next.storageRoot)&&resolve(next.storageRoot)===next.storageRoot&&next.storageRoot!=='/'&&!next.storageRoot.includes('\0'),'NODE_STORAGE_INVALID','请选择绝对的专用存放目录。');
+  requireCondition(next.mode!=='external'||isAbsolute(next.externalBinary),'NODE_BINARY_INVALID','已有独立 Node 路径必须是绝对路径。');
+  return {...next,sourceBase:source.href.replace(/\/$/,'')};
+ }
+ const externalCheck=()=>requireCondition(['darwin-arm64','darwin-x64','linux-arm64','linux-x64'].includes(platform),'NODE_PLATFORM_UNSUPPORTED','当前平台尚未完成独立 Node 的进程守护支持；Windows 不支持本安装流程。');
+ const supportedCheck=()=>requireCondition(supported,'NODE_PLATFORM_UNSUPPORTED','一键准备当前仅支持 macOS 13.5 及以上的 arm64 / x64；Windows 安装与进程守护尚未接通。');
+ async function publish(next){const whole={...next,revision:state.revision+1};await domain.global.set(whole);state=whole;}
+ function manifest(p){return {schema:1,sources:[{id:'confirmed-source',kind:'https',base:new URL(`v${p.version}/`,p.sourceBase+'/').href}],items:[{id:'node',version:p.version,kind:'tar.gz',installTo:'runtime',platforms:{[platform]:{asset:p.asset,sha256:p.sha256,size:p.bytes,strip:1}},verify:{exec:'bin/node',args:['-e',checkScript],expect:JSON.stringify({version:p.version,platform:'darwin',arch:platform.slice(7),electron:null})}}]};}
+ async function verifyActive(active,signal,heldLock){
+  requireCondition(active&&active.platform===platform&&catalog.archives.some(a=>a.version===active.version&&a.platform===platform&&a.sha256===active.sha256),'NODE_LEDGER_MISMATCH','运行时记录与已校验的官方发行记录不一致。');
+  await safeAncestors(active.root);const lock=heldLock??lockFactory(join(active.root,'.apphost-node.lock'));if(!heldLock)await lock.acquire();
+  try{const verification=await api.verify({root:active.root}),ledger=await api.ledger(active.root),entry=ledger.items.node;
+   requireCondition(verification.ok&&verification.items.some(i=>i.item==='node'&&['ok','repaired'].includes(i.state))&&entry?.sha256===active.sha256&&entry.version===active.version&&entry.platform===platform&&entry.installTo==='runtime','NODE_LEDGER_MISMATCH','独立 Node 文件、SHA 或管理账本不一致，未启用。');
+   const binary=join(active.root,'runtime/bin/node');await probe(binary,{platform,version:active.version,signal});return binary;
+  }finally{if(!heldLock)await lock.release();}
+ }
+ const service={
+  get executable(){return executable;},
+  async init(){state=await domain.global.get();settings=validate({...defaultSettings,...Object.fromEntries(Object.entries(config).filter(([,v])=>v!==undefined)),...(state.settings??{})});
+   try{if(settings.mode==='external'){externalCheck();await probe(settings.externalBinary,{platform});executable=settings.externalBinary;}
+    else if(state.active){supportedCheck();executable=await verifyActive(state.active);}
+   }catch(e){operation={id:null,state:'failed',phase:'restore',error:{message:'安装环境尚未就绪：'+causeText(e),code:e.code??'NODE_CHECK_FAILED'}};}
+  },
+  status(){return copy({settings,names:NODE_SETTING_NAMES,versions:[...new Set(catalog.archives.map(a=>a.version))],platform,supported,ready:!!executable,executable:executable??null,active:state?.active??null,operation,limitations:'一键准备支持 macOS 13.5+ arm64 / x64；Windows 尚不支持。下载仅在确认后开始；不重试、不切换来源。'});},
+  async save(input){exact(input,['settings']);idle();const next=validate(input.settings);saving=true;plan=null;
+   try{await safeAncestors(next.storageRoot);let external;
+    if(next.mode==='external'){externalCheck();await probe(next.externalBinary,{platform});external=next.externalBinary;}
+    await publish({...state,settings:next,active:next.mode==='external'?null:state.active});settings=next;if(next.mode==='external')executable=external;else if(state.active===null)executable=undefined;
+    operation=null;return service.status();
+   }finally{saving=false;}
+  },
+  async plan(input){exact(input,[]);idle();supportedCheck();requireCondition(settings.mode==='managed','NODE_MANAGED_REQUIRED','请先选择并保存「插件管理」方式。');
+   const revision=state.revision,snapshot=copy(settings),asset=catalog.archives.find(a=>a.version===snapshot.version&&a.platform===platform);
+   await safeAncestors(snapshot.storageRoot);const free=await freeBytes(snapshot.storageRoot),requiredBytes=asset.bytes+2*asset.unpackedBytes;
+   requireCondition(free>=requiredBytes,'NODE_DISK_SPACE',`准备环境需要至少 ${requiredBytes} 字节可用空间，当前只有 ${free} 字节。`);idle();requireCondition(revision===state.revision,'NODE_PLAN_STALE','设置已经改变，请重新查看准备信息。');
+   plan={...asset,sourceBase:snapshot.sourceBase,source:new URL(`v${snapshot.version}/${asset.asset}`,snapshot.sourceBase+'/').href,root:join(snapshot.storageRoot,'apphost-node',snapshot.version,platform),requiredBytes,freeBytes:free,planId:randomUUID(),revision,license:'Node.js MIT；归档内 LICENSE 保留其第三方声明',minimumOS:'macOS 13.5'};return copy(plan);
+  },
+  prepare(input){exact(input,['planId','confirm']);idle();supportedCheck();requireCondition(input.confirm===true,'NODE_CONFIRM_REQUIRED','请先核对来源、平台、版本与体积，再确认下载。');
+   requireCondition(plan&&input.planId===plan.planId&&plan.revision===state.revision,'NODE_PLAN_STALE','这份确认信息已经失效，请重新查看准备信息。');
+   const accepted=plan;plan=null;controller=new AbortController();const signal=controller.signal;operation={id:randomUUID(),state:'preparing',phase:'starting',bytes:0,total:accepted.bytes};
+   pending=(async()=>{let lock;try{
+    requireCondition(await freeBytes(settings.storageRoot)>=accepted.requiredBytes,'NODE_DISK_SPACE','当前磁盘空间不足，尚未开始下载。');
+    await secureDirectory(accepted.root);lock=lockFactory(join(accepted.root,'.apphost-node.lock'));await lock.acquire();signal.throwIfAborted();
+    await api.provision(manifest(accepted),{root:accepted.root,platform,force:true,sourceOrder:['confirmed-source'],signal,onProgress:event=>{operation={...operation,phase:event.phase,...(event.bytes!==undefined?{bytes:event.bytes}:{}),...(event.total!==undefined?{total:event.total}:{})};}});
+    signal.throwIfAborted();
+    const active={root:accepted.root,version:accepted.version,platform,sha256:accepted.sha256},binary=await verifyActive(active,signal,lock);signal.throwIfAborted();
+    await checkpoint('node-verified-before-binding');signal.throwIfAborted();operation={...operation,state:'committing',phase:'bind'};await publish({...state,settings,active});await lock.release();lock=null;executable=binary;operation={...operation,state:'ready',phase:'ready'};
+   }catch(e){operation={...operation,state:signal.aborted?'cancelled':'failed',error:{code:signal.aborted?'NODE_PREPARATION_CANCELLED':e.code??'NODE_PREPARATION_FAILED',message:signal.aborted?'已取消准备；尚未启用新的安装环境。':`准备安装环境未完成（${operation.phase}）：${causeText(e)}`}};
+   }finally{try{if(lock)await lock.release();}catch(e){operation={...operation,state:'failed',error:{code:'NODE_CLEANUP_FAILED',message:(operation.error?.message??'准备安装环境未完成')+'；运行时锁清理失败：'+causeText(e),original:operation.error??null}};}finally{controller=null;}}})() ;return {operation:copy(operation)};
+  },
+  cancel(input){exact(input,['operationId']);available();requireCondition(operation?.state!=='committing','NODE_COMMIT_IN_PROGRESS','已完成校验，正在保存并启用，不能再取消；请查看最终结果。');requireCondition(controller&&operation.state==='preparing'&&input.operationId===operation.id,'NODE_OPERATION_STALE','这项准备操作已经结束或不是当前操作。');controller.abort();return {operation:copy(operation)};},
+  settled:()=>pending,
+  async close(){closed=true;controller?.abort();await pending;},
+ };
+ return service;
+}

package/dist/owned-probe-diagnostic.js

@@ -0,0 +1,53 @@
+import { execFile } from 'node:child_process';
+import { appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// Explicit card-run opt-in. No environment, credentials, argv of other processes,
+// or lsof output is recorded. Writes never join the readiness promise.
+export function probeDiagnosticSink(directory) {
+  return event => { void appendFile(join(directory, 'owned-lsof.jsonl'), JSON.stringify(event)+'\n').catch(()=>{}); };
+}
+export function observeOwnedProbe(child, { port, args, source, emit }) {
+  const start = performance.now();
+  const startedAt = new Date().toISOString();
+  const base = { source, pid: child.pid ?? null, port, address: '127.0.0.1', args, startedAt, timeoutMs: 1000 };
+  let observer, identityObserver, finished = false, pgid = null;
+  const write = event => { try { emit({...base,...event}); } catch {} };
+  write({phase:'start', pgid:null, pgidSource:'pending exact-pid ps'});
+  if (child.pid) {
+    identityObserver = execFile('/bin/ps', ['-p',String(child.pid),'-o','pid=,pgid='],
+      {timeout:150,maxBuffer:4096}, (error,stdout)=>{
+        const fields=stdout.trim().split(/\s+/);
+        pgid = Number(fields[0])===child.pid?Number(fields[1]):null;
+        write({phase:'identity',pgid,
+          pgidSource:'exact-pid ps',observerExit:error?.code??0,observerSignal:error?.signal??null,
+          blindSpot:Number(fields[0])===child.pid?null:'Probe exited or ps could not observe its group.'});
+      });
+  }
+  const timer = setTimeout(()=>{
+    if (finished || child.exitCode !== null || child.signalCode !== null || !child.pid) return;
+    const targetPid = child.pid;
+    // ps selects only the child handle while it is alive. No command/env fields.
+    observer = execFile('/bin/ps', ['-p',String(targetPid),'-o','pid=,pgid=,stat=,wchan='],
+      {timeout:150,maxBuffer:4096}, (error, stdout)=>{
+        const fields = stdout.trim().split(/\s+/);
+        const matched = Number(fields[0]) === targetPid;
+        write({phase:'wait-state',targetPid, observedAt:new Date().toISOString(),
+          pgid:matched?Number(fields[1]):null, state:matched?fields[2]:null, wait:matched?fields.slice(3).join(' '):null,
+          observerExit:error?.code??0, observerSignal:error?.signal??null,
+          observerKilled:error?.killed??false, sourceStage:'slow-window exact-pid ps',
+          blindSpot:'No stack collected: stack sampling may suspend target or outlive the original 1000ms budget; ps wait availability depends on platform permissions.'});
+      });
+  },250);
+  timer.unref();
+  child.once('error', error=>write({phase:'error',errorCode:error.code??null}));
+  child.once('exit',(exit,signal)=>{
+    finished=true; clearTimeout(timer);
+    for (const ownedObserver of [observer,identityObserver]) {
+      if (ownedObserver && ownedObserver.exitCode===null && ownedObserver.signalCode===null) ownedObserver.kill('SIGTERM');
+    }
+    write({phase:'end',endedAt:new Date().toISOString(),elapsedMs:performance.now()-start,
+      pgid,exit,signal,killed:child.killed,sourceStage:'owned execFile exit'});
+  });
+  child.once('close',()=>{clearTimeout(timer);});
+}

package/dist/router/receipts.js

@@ -6,18 +6,15 @@
  *
  *     { appId, providerId, model, hour, count }      hour = UTC `YYYYMMDDHH`, count = forwarded requests in that hour
  *
- * kept in app-host's own storage domain (`hanamesh_router_receipts`, one global snapshot, ONE `global.set` per
- * publication, debounced) and reported through the usage plugin's record seat as the receipt of that hour's `use`
- * event (see usage-evidence.js). No prompt, response, credential or URL is ever recorded — only the provider id,
- * the model name the Router routed, and a count.
+ * kept in app-host's own storage domain (`hanamesh_router_receipts`, one global snapshot,
+ * ONE debounced `global.set` per publication). These are transport diagnostics only;
+ * ready/HTTP/WS counts and restoring old rows never prove presentation or business
+ * success and are never automatically sent to the Usage record service.
  *
- *   inject   Router `credentialResolver` resolved a route for an instance → the instance's route is remembered
- *            (first api-key / provider env entry in declaration order) and the (app, route, hour) row counts one injection.
- *   activity the instance's gateway forwarded an authorized request → the (app, route, hour) row counts one request;
- *            an instance whose route is unknown (recovered / attached, no injection this run) counts against a
- *            route-less row so the hour's `use` is still reported, just without a receipt.
- *   reported once the usage seat accepted (or already had) the hour's `use` event the rows are flagged; later requests in
- *            the same hour keep counting locally but are not re-reported (the seat de-duplicates by key).
+ * `inject` remembers the first resolved route and increments injections; `activity`
+ * counts forwarded requests. Unknown routes remain null. The legacy `reported`
+ * field and explicit markReported() operation stay available for existing ledger
+ * consumers, without asserting Usage acceptance, delivery or business success.
  *
  * Without a storage domain (library use, tests) the ledger is memory-only and behaves identically.
  */

package/dist/router/routes.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { AppHostError, requireCondition } from '../errors.js';
-import { loopbackOrigin } from '../descriptor.js';
+import { controlOrigins } from '../control-origin.js';
 
 export const ROUTER_ROUTES=Object.freeze(['/hanamesh/router/providers','/hanamesh/router/plan','/hanamesh/router/grant',
   '/hanamesh/router/revoke','/hanamesh/router/model','/hanamesh/router/mode','/hanamesh/router/gateway','/hanamesh/router/receipts']);
@@ -14,18 +14,18 @@ function send(res,status,value){res.writeHead(status,{'content-type':'applicatio
 const statusFor=code=>({APP_NOT_FOUND:404,ENTRY_UNKNOWN:404,ROUTER_PROVIDER_ABSENT:404,RISK_NOT_ACKNOWLEDGED:403,
   CONSUMER_MISMATCH:403,ENTRY_NOT_ROUTED:409,GATEWAY_OFF:409,GATEWAY_UNREACHABLE:503}[code]??400);
 
-export function createRouterHttpHandler(router,{parentOrigin,authenticate,authorize}){
-  parentOrigin=loopbackOrigin(parentOrigin);requireCondition(typeof authenticate==='function'&&typeof authorize==='function','AUTH_BINDING_REQUIRED','Router authentication is required.');
+export function createRouterHttpHandler(router,{parentOrigin,transportOrigin,authenticate,authorize}){
+  const origins=controlOrigins(parentOrigin,transportOrigin);parentOrigin=origins.parent;requireCondition(typeof authenticate==='function'&&typeof authorize==='function','AUTH_BINDING_REQUIRED','Router authentication is required.');
   return async(req,res)=>{const traceId=randomUUID();try{
-    requireCondition(req.headers.host===new URL(parentOrigin).host,'HOST_DENIED','Unrecognized request host.',{},403);
+    requireCondition(req.headers.host===new URL(origins.transport).host,'HOST_DENIED','Unrecognized request host.',{},403);
     requireCondition(req.url?.startsWith('/')&&!req.url.startsWith('//')&&!req.url.includes('\\'),'BAD_TARGET','Invalid request target.');
-    const url=new URL(req.url,parentOrigin),path=url.pathname;requireCondition(ROUTER_ROUTES.includes(path),'NOT_FOUND','Unknown router route.',{},404);
+    const url=new URL(req.url,origins.transport),path=url.pathname;requireCondition(ROUTER_ROUTES.includes(path),'NOT_FOUND','Unknown router route.',{},404);
     const readOnly=['/hanamesh/router/providers','/hanamesh/router/plan','/hanamesh/router/receipts'].includes(path);
     requireCondition(req.method===(readOnly?'GET':'POST'),'METHOD_NOT_ALLOWED','State changes require POST.',{},405);
-    requireCondition(!req.headers.origin||req.headers.origin===parentOrigin,'ORIGIN_DENIED','Unapproved browser origin.',{},403);
+    requireCondition(!req.headers.origin||origins.acceptsOrigin(req.headers.origin),'ORIGIN_DENIED','Unapproved browser origin.',{},403);
     requireCondition(req.headers['sec-fetch-dest']!=='iframe'&&req.headers['sec-fetch-site']!=='cross-site','FRAME_CONTROL_DENIED','An application frame cannot control the router.',{},403);
     requireCondition(req.headers['x-hanamesh-client']==='workspace-v1','CSRF_DENIED','Explicit workspace client header is required.',{},403);
-    if(!readOnly)requireCondition(req.headers.origin===parentOrigin,'CSRF_DENIED','Workspace origin is required.',{},403);
+    if(!readOnly)requireCondition(origins.acceptsOrigin(req.headers.origin),'CSRF_DENIED','Workspace origin is required.',{},403);
     const subject=await authenticate(req);requireCondition(subject&&typeof subject.principalId==='string','UNAUTHENTICATED','Host authentication is required.',{},401);
     const input=readOnly?Object.fromEntries(url.searchParams):await body(req);
     if(path==='/hanamesh/router/providers')requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','No provider parameters are accepted.');

package/dist/routes.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { AppHostError, requireCondition } from './errors.js';
-import { loopbackOrigin } from './descriptor.js';
+import { controlOrigins } from './control-origin.js';
 function browserInstance(instance) {
   if(!instance)return null;
   const {id,appId,deploymentId,dataId,mode,status,runtimeId,errorCode}=instance;
@@ -23,24 +23,24 @@ function send(res,status,value) {
   res.end(JSON.stringify(value));
 }
 /** Node request handler. Authentication/authorization MUST come from the host. */
-export function createHttpHandler(host,{parentOrigin,authenticate,authorize}) {
-  parentOrigin=loopbackOrigin(parentOrigin);
+export function createHttpHandler(host,{parentOrigin,transportOrigin,authenticate,authorize}) {
+  const origins=controlOrigins(parentOrigin,transportOrigin);parentOrigin=origins.parent;
   requireCondition(typeof authenticate==='function'&&typeof authorize==='function','AUTH_BINDING_REQUIRED',
     'Host authentication and per-operation authorization callbacks are mandatory.');
   return async(req,res)=>{
     const traceId=randomUUID();
     try{
-      requireCondition(req.headers.host===new URL(parentOrigin).host,'HOST_DENIED','Unrecognized request host.',{},403);
+      requireCondition(req.headers.host===new URL(origins.transport).host,'HOST_DENIED','Unrecognized request host.',{},403);
       requireCondition(req.url?.startsWith('/')&&!req.url.startsWith('//')&&!req.url.includes('\\'),'BAD_TARGET','Invalid request target.');
-      const url=new URL(req.url,parentOrigin),path=url.pathname;
-      const known=['/hanamesh/apps','/apps/open','/apps/resume','/apps/recover','/apps/close','/apps/heartbeat','/apps/stop','/apps/events'];
+      const url=new URL(req.url,origins.transport),path=url.pathname;
+      const known=['/hanamesh/apps','/apps/open','/apps/resume','/apps/recover','/apps/close','/apps/heartbeat','/apps/stop','/apps/events','/apps/bootstrap-authorize'];
       requireCondition(known.includes(path),'NOT_FOUND','Unknown app-host route.',{},404);
       const readOnly=['/hanamesh/apps','/apps/events'].includes(path);
       requireCondition(req.method===(readOnly?'GET':'POST'),'METHOD_NOT_ALLOWED','State changes require POST.',{},405);
-      requireCondition(!req.headers.origin||req.headers.origin===parentOrigin,'ORIGIN_DENIED','Unapproved browser origin.',{},403);
+      requireCondition(!req.headers.origin||origins.acceptsOrigin(req.headers.origin),'ORIGIN_DENIED','Unapproved browser origin.',{},403);
       requireCondition(req.headers['sec-fetch-dest']!=='iframe','FRAME_CONTROL_DENIED','An application frame cannot control the host.',{},403);
       if(!readOnly){
-        requireCondition(req.headers.origin===parentOrigin&&req.headers['x-hanamesh-client']==='workspace-v1',
+        requireCondition(origins.acceptsOrigin(req.headers.origin)&&req.headers['x-hanamesh-client']==='workspace-v1',
           'CSRF_DENIED','Workspace origin and explicit client header are required.',{},403);
       }
       const subject=await authenticate(req);
@@ -50,6 +50,7 @@ export function createHttpHandler(host,{parentOrigin,authenticate,authorize}) {
       let result;
       switch(path){
         case '/hanamesh/apps':requireCondition(!url.search,'UNKNOWN_FIELDS','No list parameters are accepted.');result=host.list(subject.principalId);break;
+        case '/apps/bootstrap-authorize':result=await host.authorizeBootstrap(input,subject.principalId);break;
         case '/apps/open':result=await host.beginOpen(input,subject.principalId);break;
         case '/apps/resume':result=await host.resume(input,subject.principalId,{waitForReady:false});break;
         case '/apps/recover':result=await host.recoverView(input,subject.principalId);break;

package/dist/runtime.js

@@ -7,6 +7,7 @@ import { dirname, isAbsolute, join } from 'node:path';
 import { promisify } from 'node:util';
 import { AppHostError, bounded } from './errors.js';
 const exec = promisify(execFile);
+import { observeOwnedProbe, probeDiagnosticSink } from './owned-probe-diagnostic.js';
 export async function resolveNodeBinary(nodeBinary) {
   let selected = nodeBinary;
   if (selected === undefined || selected === null || selected === '') {
@@ -83,7 +84,16 @@ export async function ownsLoopbackPort(pid, port) {
     }
     if (!binary) throw new AppHostError('PORT_OWNERSHIP_UNAVAILABLE', 'lsof is required to verify socket ownership on macOS.');
     let stdout;
-    try { ({ stdout } = await exec(binary, ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-FpgLn'], { timeout: 1_000 })); }
+    try {
+      // Select the already-required owned group before Darwin inspects file descriptors of unrelated processes.
+      const args = ['-nP', '-a', '-g', String(pid), `-iTCP:${port}`, '-sTCP:LISTEN', '-FpgLn'];
+      const pending = exec(binary, args, { timeout: 1_000 });
+      if (process.env.HANAMESH_APPHOST_RUN_DIR) {
+        try { observeOwnedProbe(pending.child, {port, args, source:'readiness/socket-ownership',
+          emit:probeDiagnosticSink(process.env.HANAMESH_APPHOST_RUN_DIR)}); } catch {}
+      }
+      ({ stdout } = await pending);
+    }
     catch (error) { if (error.code === 1) return false; throw error; }
     const blocks = stdout.split(/(?=^p\d+$)/m);
     return blocks.some(block => block.split('\n').includes(`g${pid}`) && block.includes(`n127.0.0.1:${port}`));

package/dist/usage-evidence.js

@@ -1,117 +1,49 @@
 /**
- * rc.27 — application usage evidence (user decision 2026-09-21, STATUS `P2-USE-EVENTS`); T6 — usage receipts.
- *
- * Applications' `open` / `use` events are reported by app-host through the usage plugin's record seat
- * (`ctx.hanameshUsage.record`). The three HanaMesh plugins never import each other: the seat arrives as an
- * OPTIONAL Cordis service, read duck-typed each time it is needed. Absent or incompatible seat → no events,
- * never a throw, never a blocked launch or proxied request.
- *
- *   open  once per successful app open — the instance reaching `ready` (the served view).
- *         idempotencyKey `open:<appId>:<instanceId>`, occurredAt = the ready time.
- *   use   real activity only — the instance's gateway forwarded an authorized request (bootstrap, denials,
- *         401/403 answers and the host's own readiness probes never count). At most one per app per UTC hour:
- *         idempotencyKey `use:<appId>:<YYYYMMDDHH>`, occurredAt = the first forwarded request of that bucket.
- *         T6: the event carries `targetRef = appId` and, when the Router routed a provider into the app, the
- *         hour's receipt `{providerId, model, count}` from the receipt ledger (router/receipts.js). Because the
- *         count is only final when the hour is over, the `use` event is handed to the seat when the UTC hour
- *         closes (next activity in a later hour, the periodic sweep, plugin shutdown) or as soon as the app's
- *         last live instance ends. Hours that were still open when the host died are reported on the next start
- *         (the ledger is persisted); the seat de-duplicates by key, so nothing is counted twice.
- *
- * `hanaRef` is the app's npm package name (`host.packageName(appId)`: definition `packageName`, else the
- * installed-package scan binding). No package name → no evidence for that app (debug log only).
- * `withheld` (consent off) and `duplicate` (repeat) are normal dispositions and are logged at debug only.
+ * AppHost's runtime/transport observations are Router diagnostics, not original
+ * application presentation or successful-business facts (C-USAGE-LOCAL edition 1).
+ * No verified public source for those facts is connected here. Keep Usage unknown
+ * and leave the application available; never manufacture record input or time.
  */
 import { requireCondition } from './errors.js';
 import { createReceiptLedger, hourBucket } from './router/receipts.js';
 
 export { hourBucket };
 export const SOURCE_PLUGIN = '@hanamesh/dsh-app-host';
-const MAX_KEY = 160;
-/** Duck-type the optional sibling service: anything exposing `record(input)` is used, nothing else is assumed. */
+/** Shape inspection only; presence of a record method does not prove a source fact. */
 export const duckSeat = value => value !== null && typeof value === 'object' && typeof value.record === 'function' ? value : null;
 const TERMINAL = ['instance.stopped','instance.failed','instance.interrupted'];
-const LIVE = ['starting','ready','stopping'];
 
 /**
+ * Preserve the existing adapter lifecycle and independent Router ledger. `seat`
+ * and `sweepIntervalMs` remain accepted for compatibility, but no record call or
+ * hourly reporting timer is created without a verified original fact source.
  * @param {{host:import('./manager.js').AppHost, seat:()=>unknown, receipts?:ReturnType<typeof createReceiptLedger>, logger?:{debug?:Function}, clock?:()=>number, sweepIntervalMs?:number}} options
- *   `seat()` is read on every emission (the service may appear or disappear while the host runs).
- *   `receipts` is the Router's receipt ledger; without one an in-memory ledger gives the same behaviour.
  */
 export function createUsageEvidence({ host, seat, receipts, logger, clock = Date.now, sweepIntervalMs = 60_000 }) {
   requireCondition(host && typeof host.subscribe === 'function' && typeof host.onActivity === 'function' && typeof host.packageName === 'function',
     'INVALID_HOST','createUsageEvidence needs an AppHost with subscribe/onActivity/packageName.');
   requireCondition(typeof seat === 'function','INVALID_SEAT','seat must be a function returning the optional usage service.');
   requireCondition(Number.isSafeInteger(sweepIntervalMs) && sweepIntervalMs >= 0,'INVALID_OPTIONS','sweepIntervalMs must be a non-negative integer.');
-  const debug = (...args) => { try { logger?.debug?.(...args); } catch {} };
   const ledger = receipts ?? createReceiptLedger({ clock });
-  const inflight = new Set();
   let closed = false;
-
-  /** @returns {Promise<{disposition:string, code?:string}|null>} null when nothing was attempted */
-  function emit(action, appId, key, at, extra = {}) {
-    if (closed) return Promise.resolve(null);
-    const api = duckSeat(seat());
-    if (!api) { debug('hanamesh-app-host usage: seat absent, %s not recorded', key); return Promise.resolve(null); }
-    const hanaRef = host.packageName(appId);
-    if (!hanaRef) { debug('hanamesh-app-host usage: no package name for app %s, %s not recorded', appId, key); return Promise.resolve(null); }
-    if (key.length > MAX_KEY) { debug('hanamesh-app-host usage: key too long, %s not recorded', key.slice(0,40)); return Promise.resolve(null); }
-    const input = { hanaRef, action, occurredAt:new Date(at).toISOString(), idempotencyKey:key, sourcePlugin:SOURCE_PLUGIN, ...extra };
-    let task;
-    try { task = Promise.resolve(api.record(input)); }
-    catch (error) { debug('hanamesh-app-host usage: seat threw for %s (%s)', key, error?.code ?? error?.message); return Promise.resolve(null); }
-    const settled = task.then(result => {
-      const disposition = result?.disposition ?? 'unknown';
-      debug('hanamesh-app-host usage: %s %s → %s%s', action, key, disposition, result?.code ? ` (${result.code})` : '');
-      return result && typeof result === 'object' ? result : null;
-    }, error => { debug('hanamesh-app-host usage: seat rejected %s (%s)', key, error?.code ?? error?.message); return null; });
-    inflight.add(settled);
-    settled.finally(() => inflight.delete(settled));
-    return settled;
-  }
-
-  /** Report every closed (or, with includeCurrent, every) unreported hour as one `use` event with its receipt. */
-  function flush({ appId, includeCurrent = false } = {}) {
-    if (closed) return Promise.resolve();
-    const tasks = [];
-    for (const hour of ledger.pending({ appId, includeCurrent, now:clock() })) {
-      const extra = { targetRef:hour.appId, ...(hour.receipt ? { receipt:hour.receipt } : {}) };
-      tasks.push(emit('use', hour.appId, `use:${hour.appId}:${hour.hour}`, hour.occurredAt, extra).then(result => {
-        if (result && (result.disposition === 'recorded' || result.disposition === 'duplicate')) ledger.markReported(hour.appId, hour.hour);
-      }));
-    }
-    return Promise.all(tasks).then(() => {});
-  }
-  const liveInstances = appId => {
-    try { return host.instanceList().filter(i => i.appId === appId && LIVE.includes(i.status)).length; } catch { return 0; }
-  };
+  // One capability diagnostic at registration; no app content, identity, token,
+  // timestamp or service response is logged. Logger failures never block apps.
+  try { logger?.debug?.('USAGE_FACT_UNAVAILABLE: no verified public presentation/success source; runtime readiness, transport and hourly receipts are diagnostics only.'); } catch {}
 
   const unsubscribeEvents = host.subscribe(event => {
-    if (event.type === 'instance.ready') {
-      const instance = host.instance(event.instanceId, event.principalId);
-      if (instance) void emit('open', instance.appId, `open:${instance.appId}:${event.instanceId}`, event.at);
-    } else if (TERMINAL.includes(event.type)) {
-      ledger.forget(event.instanceId);
-      const instance = host.instance(event.instanceId, event.principalId);
-      // The app's last live instance ended: this hour's count is final for now, report it right away.
-      if (instance && liveInstances(instance.appId) === 0) void flush({ appId:instance.appId, includeCurrent:true });
-    }
+    if (TERMINAL.includes(event.type)) ledger.forget(event.instanceId);
   });
   const unsubscribeActivity = host.onActivity(activity => {
     ledger.activity({ appId:activity.appId, instanceId:activity.instanceId, at:activity.at });
-    void flush({ appId:activity.appId });
   });
-  let timer = null;
-  if (sweepIntervalMs > 0) { timer = setInterval(() => { void flush(); }, sweepIntervalMs); timer.unref?.(); }
-  // Hours left open by a previous run (persisted ledger) are reported once the seat is reachable.
-  queueMicrotask(() => { void flush(); });
-
+  // Persist diagnostics only. In particular, do not send or mark pending rows
+  // reported when an hour closes, on startup, stop, flush or disposal.
+  const flush = () => closed ? Promise.resolve() : ledger.persist();
   return Object.freeze({
-    /** Report closed hours now (tests / shutdown); `includeCurrent` also reports the running hour. */
     flush,
-    /** Resolves once every record() call issued so far has settled (tests / orderly shutdown). */
-    settle: async () => { await Promise.allSettled([...inflight]); },
+    /** Settles this ledger's writes; it is not a Usage processing/delivery receipt. */
+    settle: async () => { await ledger.persist(); },
     receipts: ledger,
-    close() { void flush(); closed = true; if (timer !== null) clearInterval(timer); unsubscribeEvents(); unsubscribeActivity(); },
+    close() { if (closed) return; void flush(); closed = true; unsubscribeEvents(); unsubscribeActivity(); },
   });
 }