@yugoo-design/companion 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -1,6 +1,6 @@
 # Yugoo Design Companion — beta
 
-Package: `@yugoo-design/companion@0.1.0-beta.3`.
+Package: `@yugoo-design/companion@0.1.0-beta.5`.
 
 Yugoo Design (语构设计系统) is an interactive design plugin for native Agent Hosts.
 It combines domain methods, Design Projects, versioned Design Files and shared
@@ -11,19 +11,86 @@ This beta is experimental. Native installation, tools, Panel saving, KAG and GRA
 must be verified for the actual host version and platform. A successful package
 installation or runtime-load check does not establish all of those capabilities.
 
-Use Node.js `>=22.19.0 <23` and a durable npm installation directory. This source
-candidate uses the packaged native Git library for runtime versioning; system Git
-is needed only for the explicit CLI diagnostic backend and development fixtures.
-The installed native binding must support the actual operating system and CPU;
-missing support is reported rather than silently spawning system Git. Resolve the
+Use Node.js `>=22.19.0 <23` and a durable npm or pnpm installation directory. The current
+release uses the packaged native Git library for normal Design versioning without
+system Git. It bundles Windows x64 MSVC and Linux x64 GNU runtimes; other platforms
+are unsupported. System Git is separate and needed only for the explicit CLI
+diagnostic backend and development fixtures. Missing native support is reported
+rather than silently spawning system Git. Resolve the
 selected beta to the exact version and integrity before acquisition; keep the
 previous installed version available during updates. Do not substitute `latest`.
 
 ```sh
-npm install --ignore-scripts --save-exact @yugoo-design/companion@0.1.0-beta.3 --registry=https://registry.npmjs.org
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.5 --registry=https://registry.npmjs.org
 npx --no-install design-system --help
 ```
 
+Alternatively, use an existing pnpm 11 installation (npm remains supported).
+In the dedicated, empty version directory, create `pnpm-workspace.yaml` with
+these local settings before acquisition:
+
+```yaml
+nodeLinker: hoisted
+allowBuilds:
+  onnxruntime-node: true
+  sharp: true
+```
+
+```sh
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip pnpm add --save-exact @yugoo-design/companion@0.1.0-beta.5 --registry=https://registry.npmjs.org
+pnpm exec design-system --help
+```
+
+Run either acquisition in its own retained version directory, not the Design
+Project or host profile. Do not mix npm and pnpm lockfiles in that directory.
+The hoisted layout is the compatibility route for Companion's current native
+dependency inspection; other pnpm layouts are not certified for every host.
+pnpm's explicit build permissions above allow the current native dependencies'
+installation scripts; do not disable all scripts or enable all future dependency
+builds. Review any newly reported build requirement before allowing it. Retain
+the complete pnpm installation layout; do not copy just a linked
+package directory or invoke Node with `--preserve-symlinks` flags.
+
+An explicitly selected HTTPS npm mirror is supported, for example
+`--registry=https://registry.npmmirror.com`. Use it both when acquiring this
+package and when invoking `design-system install --host dsh --registry=<url>`
+with the required host inputs. The latter controls the official DSH CLI's
+package download registry; it does not replace that CLI with npm or pnpm.
+The exact aggregate version still comes from `release-hosts.json`, whose registry
+remains the canonical release origin/default. The plan and receipt separately
+record the effective mirror and bind it through apply and owned updates. There
+is no automatic registry fallback or global registry edit. Verify the exact
+mirror version and integrity against the selected release before installation;
+missing or stale mirror packages are not permission to change version or source.
+Registry selection does not redirect separate embedding-model or upstream
+installation-script downloads to that mirror.
+
+First-release local embedding runs on CPU. Set the supported
+`ONNXRUNTIME_NODE_INSTALL_CUDA=skip` environment before acquisition to skip ONNX
+Runtime's extra CUDA download while retaining normal dependency lifecycle
+scripts. Preserve the upstream packages and other environment values. The
+installed package cannot configure its acquiring parent npm/npx process; a bare
+npm/npx acquisition does not apply this policy automatically. Keep the same
+policy on later host-installation children that acquire dependencies. The
+maintained DSH adapter passes it to the official CLI in Web and Desktop; older
+installed adapters may need the caller to supply it. This does not establish
+installation success or remove the separate embedding-model download/cache step.
+The default product does not provision GPU runtimes; optional GPU support and
+configurable or user-local model selection are future work.
+
+In Windows PowerShell, scope the setting to acquisition and restore its previous
+process value:
+
+```powershell
+$previousOrtCuda = [Environment]::GetEnvironmentVariable('ONNXRUNTIME_NODE_INSTALL_CUDA', 'Process')
+try {
+  $env:ONNXRUNTIME_NODE_INSTALL_CUDA = 'skip'
+  npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.5 --registry=https://registry.npmjs.org
+} finally {
+  [Environment]::SetEnvironmentVariable('ONNXRUNTIME_NODE_INSTALL_CUDA', $previousOrtCuda, 'Process')
+}
+```
+
 Ask the Agent in your current host to install or update Yugoo Design as one
 product. It should identify the host from its actual execution context or your
 explicit choice, not from which CLIs happen to be installed. If identity is

package/bin/installer.mjs

@@ -15,7 +15,7 @@ import { checkRuntime, inspectRuntime, assertGitRuntimeReceipt } from './npm-run
 import { runDesktopDshInstaller } from './npm-installer-dsh-desktop.mjs'
 import { desktopPreparationMain, desktopPreparationReuseMain } from './npm-desktop-preparation.mjs'
 import { agentInstallation, AGENT_INSTALL_HOSTS, DESKTOP_INSTALL_OPTIONS } from './npm-agent-installation.mjs'
-import { createDshInstallerAdapter, planDshInstallation, applyDshInstallation } from './npm-installer-dsh.mjs'
+import { createDshInstallerAdapter, planDshInstallation, applyDshInstallation, validateReleaseHosts } from './npm-installer-dsh.mjs'
 
 export const INSTALL_HOSTS = ['dsh','codex','claude-code','qoder','codex-desktop','qwenwork']
 const PLUGIN = 'yugoo-design'
@@ -623,32 +623,15 @@ async function recoverOwnedInstallation(receipt,{adapter,ownRecovery,uninstall=f
 }
 
 const DSH_FLAGS = ['dsh-config','profile','aggregate-selector','registry']
-// Only DSH consumes this local product mapping. Older candidates retain their
-// explicit selector/registry route; preparation values never imply a release.
-export function validateReleaseHosts(config) {
-  assert.ok(config && typeof config==='object' && !Array.isArray(config),'Release hosts object required')
-  assert.deepEqual(Object.keys(config).sort(),['hosts','schemaVersion'],'Unknown release hosts fields')
-  assert.equal(config.schemaVersion,1,'Unsupported release hosts schema')
-  assert.ok(config.hosts && typeof config.hosts==='object' && !Array.isArray(config.hosts),'Release hosts map required')
-  assert.deepEqual(Object.keys(config.hosts),['dsh'],'Release mapping currently supports DSH only')
-  const dsh=config.hosts.dsh
-  assert.ok(dsh && typeof dsh==='object' && !Array.isArray(dsh),'DSH release mapping required')
-  assert.deepEqual(Object.keys(dsh).sort(),['aggregatePackage','aggregateVersion','registry'],'Unknown DSH release fields')
-  assert.match(dsh.aggregatePackage ?? '',/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u,'Exact aggregate package name required')
-  if(dsh.aggregateVersion===null && dsh.registry===null)return null
-  assert.match(dsh.aggregateVersion ?? '',/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u,'Exact aggregate version required')
-  assert.equal(typeof dsh.registry,'string','Bound HTTPS registry required')
-  const url=new URL(dsh.registry)
-  assert.ok(url.protocol==='https:' && !url.username && !url.password && !url.search && !url.hash,'Credential-free HTTPS registry required')
-  return {aggregateSelector:`${dsh.aggregatePackage}@${dsh.aggregateVersion}`,registry:url.href}
-}
+export { validateReleaseHosts }
 async function dshReleaseSelection(values,npmRoot) {
   const bytes=await optional(join(npmRoot,'release-hosts.json'))
   const mapped=bytes===null?null:validateReleaseHosts(JSON.parse(bytes))
   if(mapped) {
     if(Object.hasOwn(values,'aggregate-selector'))assert.equal(values['aggregate-selector'],mapped.aggregateSelector,'Aggregate override differs from product release')
-    if(Object.hasOwn(values,'registry'))assert.equal(new URL(values.registry).href,mapped.registry,'Registry override differs from product release')
-    return mapped
+    // The release binds the package/version and default origin, not the user's
+    // explicit download mirror. The owning planner validates and pins transport.
+    return {...mapped,registry:values.registry ?? mapped.registry}
   }
   for(const key of ['aggregate-selector','registry'])assert.ok(typeof values[key]==='string' && values[key],`DSH release mapping is unbound or missing; explicit --${key} required for compatibility installation`)
   return {aggregateSelector:values['aggregate-selector'],registry:values.registry}
@@ -667,7 +650,7 @@ async function dshConfiguration(path) {
   }
   return config
 }
-async function dshOutputDirectory(path,{npmRoot,config,configPath,planPath}) {
+async function dshOutputDirectory(path,{npmRoot,config,configPath,planPath,previousProductRoot}) {
   assert.ok(typeof path==='string'&&isAbsolute(path),'Explicit absolute external receipt directory required')
   const output=resolve(path)
   await safePath(output)
@@ -678,7 +661,7 @@ async function dshOutputDirectory(path,{npmRoot,config,configPath,planPath}) {
     try { assert.equal(await realpath(ancestor),ancestor,'Output ancestor realpath mismatch'); break }
     catch(error){if(error.code!=='ENOENT')throw error;ancestor=dirname(ancestor)}
   }
-  const roots=[resolve(npmRoot),resolve(config.dshHome)]
+  const roots=[resolve(npmRoot),resolve(config.dshHome),...previousProductRoot ? [resolve(previousProductRoot)] : []]
   for(const key of ['node','cli','hostManifest','loader','loaderManifest', ...config.desktopHostManifest ? ['desktopHostManifest'] : []]) {
     roots.push(dirname(resolve(config[key].path)),dirname(await realpath(config[key].path)))
   }
@@ -718,9 +701,12 @@ async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args,signal,d
     const name=selection.aggregateSelector.slice(0,selection.aggregateSelector.lastIndexOf('@'))
     aggregateDirectory=dirname(await realpath(createRequire(join(npmRoot,'package.json')).resolve(name+'/package.json')))
   } catch(error) { if(error.code!=='MODULE_NOT_FOUND')throw error }
-  const options={adapter,profile:values.profile,...selection,...aggregateDirectory ? {aggregateDirectory} : {}}
+  const options={adapter,profile:values.profile,...selection,productRoot:await realpath(resolve(npmRoot)),
+    ...values['previous-receipt'] ? {previousReceipt:values['previous-receipt']} : {},
+    ...aggregateDirectory ? {aggregateDirectory} : {}}
   if(values['dry-run']) {
     const plan=await planDshInstallation(options)
+    if(plan.previous)await dshOutputDirectory(output,{npmRoot,config,configPath,previousProductRoot:plan.previous.product.npmRoot})
     const planFile=await writeDshOutput(output,plan.planSha256+'.dsh-plan.json',plan)
     return {...plan,planFile}
   }
@@ -731,14 +717,27 @@ async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args,signal,d
   assert.equal(plan.profile,options.profile,'Saved DSH profile mismatch')
   assert.equal(plan.aggregateSelector,options.aggregateSelector,'Saved aggregate selector mismatch')
   assert.equal(plan.registry,new URL(options.registry).href,'Saved registry mismatch')
+  assert.equal(plan.previousReceipt,options.previousReceipt,'Saved previous ownership reference mismatch')
   assert.equal(plan.protocol.scope,adapter.scope,'Saved adapter scope mismatch')
   const fresh=await planDshInstallation(options)
+  if(fresh.previous)await dshOutputDirectory(output,{npmRoot,config,configPath,previousProductRoot:fresh.previous.product.npmRoot})
   assert.deepEqual(plan.protocol,fresh.protocol,'Saved official pins/home/version mismatch')
   assert.equal(plan.planSha256,fresh.planSha256,'Saved DSH plan or profile drifted')
-  const result=await applyDshInstallation(plan,{adapter,signal,timeoutMs:dshInstallTimeoutMs,logDirectory:output})
-  const receipt={...result,host:'dsh',route:'official-dsh-bundle',planSha256:plan.planSha256}
-  const receiptFile=await writeDshOutput(output,randomUUID()+'.dsh-result.json',receipt)
-  return {...receipt,receiptFile}
+  const id=randomUUID(),receiptPath=join(output,id+'.dsh-result.json')
+  const preparedRecordFile=await writeDshOutput(output,id+'.dsh-prepared.json',{
+    schemaVersion:2,kind:'dsh-installation-prepared',id,planSha256:plan.planSha256,planSnapshot:plan,
+    receiptPath,ownershipEstablished:false,phase:'prepared',retrySafe:false})
+  try {
+    const result=await applyDshInstallation(plan,{adapter,signal,timeoutMs:dshInstallTimeoutMs,logDirectory:output})
+    const body={...result,id,receiptPath,preparedRecordFile}
+    const receipt={...body,receiptSha256:digest(body)}
+    const receiptFile=await writeDshOutput(output,id+'.dsh-result.json',receipt)
+    return {...receipt,receiptFile}
+  } catch(error) {
+    // The native command may already have changed the profile. Keep the exact
+    // prepared record discoverable without fabricating a successful terminal receipt.
+    throw Object.assign(error,{receiptPath:preparedRecordFile,preparedRecordFile,planFile:values.plan})
+  }
 }
 
 /** Reuse native session plugin loading. No registration, copying, or host launch. */
@@ -832,13 +831,13 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
       '--dsh-config <file>':'DSH install only: absolute JSON with dshHome, official node/CLI/Loader file pins and host/Loader versions; desktopHostManifest selects the official Electron Desktop CLI. No scope or runner override.',
       '--profile <name>':'DSH install only: explicitly selected existing profile; never initialized implicitly.',
       '--aggregate-selector <name@version>':'DSH install only: optional exact aggregate override matching the product release mapping; required for old or unbound candidates.',
-      '--registry <https-url>':'DSH install only: optional credential-free HTTPS registry override matching the product mapping; required for old or unbound candidates.',
+      '--registry <https-url>':'DSH install only: explicit credential-free HTTPS download registry or mirror; defaults to the product mapping. Preserves the exact mapped aggregate and binds the saved plan/receipt; no automatic fallback. Required for old or unbound candidates.',
       '--destination <directory>':'QwenWork/WorkBuddy direct install: exclusive external preparation directory, or the same owned directory with --previous-receipt.',
       '--suite-version <version>':'QwenWork/WorkBuddy: exact native suite version, separate from the acquired npm version.',
       '--node-executable <path>':'QwenWork/WorkBuddy: absolute Windows Node path used by the imported suite.',
       '--qwenwork-runtime <file>':'QwenWork: verified native executable/worker/Node paths and byte pins. Agent obtains these through supported native inspection; no credentials.',
       '--separate-mcp':'QwenWork: emit one external connector instead of bundling it when organization policy requires this.',
-      '--previous-receipt <file>':'Desktop: verify and reuse this owned preparation for a same-version repeat, or prepare a strictly newer native suite/npm version using its update boundary.',
+      '--previous-receipt <file>':'DSH: successful source-bound installation receipt for an owned update or repeat; sparse/manual receipts cannot be adopted. Desktop: reuse an owned preparation or prepare a newer native suite/npm version.',
       '--npm-root-windows, --destination-windows':'Desktop: explicit Windows path mappings required when preparing from another platform; native Windows paths must match actual roots.',
     },
     limitations:['plugin-directory is an optional session-only diagnostic, not installation. Codex requires an admitted adapter; DSH requires pinned public CLI inputs. Desktop preparation needs native import and activation. Exit 2 means host selection or inputs are required; exit 0 does not establish a usable native session.',
@@ -853,7 +852,8 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
       desktopPrepare:nextArgs=>desktopPreparationMain(nextArgs,{npmRoot}),
       desktopReuse:nextArgs=>desktopPreparationReuseMain(nextArgs,{npmRoot})})
   }
-  for(const key of DESKTOP_INSTALL_OPTIONS)assert.ok(!Object.hasOwn(values,key),`--${key} is only valid for direct desktop install`)
+  for(const key of DESKTOP_INSTALL_OPTIONS)if(!(key==='previous-receipt'&&values.host==='dsh'&&positionals[0]==='install'))
+    assert.ok(!Object.hasOwn(values,key),`--${key} is only valid for direct desktop install`)
   if(positionals[0]==='plugin-directory'&&['claude-code','qoder'].includes(values.host)) {
     assert.deepEqual(Object.keys(values),['host'],'Native directory entry accepts only --host; transaction/runtime options must not be silently ignored')
     return nativePluginDirectory({npmRoot,host:values.host})
@@ -884,7 +884,7 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
       if(values.apply)assert.ok(values.plan&&values['runtime-receipt']&&!values['receipt-dir']&&!values['disable-embedding'],'Claude apply requires saved plan and runtime receipt only')
       else assert.ok(values['receipt-dir']&&!values.plan&&!values['runtime-receipt'],'Claude dry-run requires external receipt directory only')
     } else assert.ok(values.receipt&&!values.apply&&!values['dry-run']&&!values.plan&&!values['receipt-dir']&&!values['runtime-receipt']&&!values['disable-embedding'],'Claude recovery/uninstall requires only persisted receipt')
-    const native=await claudeAdapterFactory({executable:values['claude-executable'],userRoot:profile,scope:values['dry-run']?'plan-only':'production'})
+    const native=await claudeAdapterFactory({executable:values['claude-executable'],userRoot:profile,nativeCwd:resolve(npmRoot),scope:values['dry-run']?'plan-only':'production'})
     if(command==='recover'||command==='uninstall') {
       const receipt=JSON.parse(await optional(resolve(values.receipt)))
       assert.equal(receipt.npmRoot,resolve(npmRoot),'Claude receipt npm root mismatch');assert.equal(receipt.userRoot,profile,'Claude receipt profile mismatch')

package/bin/npm-agent-installation.mjs

@@ -8,7 +8,7 @@ export const AGENT_INSTALL_HOSTS = ['dsh', 'codex', 'claude-code', 'qoder', 'qwe
 export const DESKTOP_INSTALL_OPTIONS = ['destination', 'node-executable', 'suite-version', 'npm-root-windows',
   'destination-windows', 'qwenwork-runtime', 'separate-mcp', 'previous-receipt']
 const nativeOptions = {
-  dsh: ['host', 'receipt-dir', 'dsh-config', 'profile', 'aggregate-selector', 'registry'],
+  dsh: ['host', 'receipt-dir', 'dsh-config', 'profile', 'aggregate-selector', 'registry', 'previous-receipt'],
   codex: ['host', 'receipt-dir', 'codex-executable', 'user-root', 'disable-embedding'],
   'claude-code': ['host', 'receipt-dir', 'claude-executable', 'user-root', 'disable-embedding'],
   qoder: ['host', 'receipt-dir', 'qoder-executable', 'qoder-config-dir'],

package/bin/npm-installer-claude.mjs

@@ -57,34 +57,54 @@ async function executableFence(s) {
   assert.ok((await lstat(exe)).isFile(),'Claude executable must remain regular')
   assert.equal(sha(await readFile(exe)),s.identity.sha256,'Claude executable changed')
 }
+async function nativeCwdFence(s) {
+  const cwd=s.identity.nativeCwd
+  await assertRuntimePath(cwd)
+  assert.equal(await realpath(cwd),cwd,'Claude canonical native working directory changed')
+  const info=await lstat(cwd)
+  assert.ok(info.isDirectory(),'Claude native working directory must be a directory')
+  assert.deepEqual({dev:info.dev,ino:info.ino},s.nativeCwdIdentity,'Claude native working directory replaced')
+  assert.notEqual(cwd,s.userRoot,'Claude native working directory must differ from HOME')
+  for(const name of ['settings.json','settings.local.json']) {
+    const file=join(cwd,'.claude',name)
+    await assertRuntimePath(file)
+    try { await lstat(file);assert.fail('Claude native working directory contains direct .claude configuration') }
+    catch(error) { if(error.code!=='ENOENT')throw error }
+  }
+}
 function protocolIdentity(s) { const {scope,...identity}=s.identity;return identity }
 async function state(adapter) {
   const s=adapters.get(adapter);assert.ok(s,'Unrecognized Claude adapter')
-  await executableFence(s);return s
+  await executableFence(s);await nativeCwdFence(s);return s
 }
 async function call(s,args) {
-  await executableFence(s)
+  await executableFence(s);await nativeCwdFence(s)
   let result
-  try { result=await s.run(s.identity.executable,args,{cwd:s.userRoot,env:s.env,timeout:30000,maxBuffer:1048576}) }
-  finally { await executableFence(s) }
+  try { result=await s.run(s.identity.executable,args,{cwd:s.identity.nativeCwd,env:s.env,timeout:30000,maxBuffer:1048576}) }
+  finally { await executableFence(s);await nativeCwdFence(s) }
   assert.ok(result.code===undefined||result.code===0,'Claude command failed')
   assert.ok(!result.signal,'Claude command signalled');return result.stdout??''
 }
 /** Read-only factory. Injected runners are confined to explicitly isolated profiles. */
-export async function createClaudeNativeAdapter({executable,userRoot,scope='plan-only',run=execute}) {
+export async function createClaudeNativeAdapter({executable,userRoot,nativeCwd,scope='plan-only',run=execute}) {
   assert.ok(['plan-only','isolated-acceptance','isolated-test-contract','production'].includes(scope),'Unknown Claude scope')
   assert.ok(isAbsolute(executable??'')&&isAbsolute(userRoot??''),'Explicit Claude executable/profile required')
+  assert.ok(isAbsolute(nativeCwd??''),'Explicit Claude native working directory required')
+  assert.equal(resolve(nativeCwd),nativeCwd,'Explicit canonical Claude native working directory required')
   const exe=await realpath(executable),home=resolve(userRoot)
   await assertRuntimePath(exe);await assertRuntimePath(home)
   assert.equal(await realpath(home),home);assert.ok((await lstat(home)).isDirectory())
+  await assertRuntimePath(nativeCwd);assert.equal(await realpath(nativeCwd),nativeCwd,'Claude canonical native working directory changed')
+  const cwdInfo=await lstat(nativeCwd)
+  assert.ok(cwdInfo.isDirectory(),'Claude native working directory must be a directory')
   if(scope.startsWith('isolated-'))assert.notEqual(home,resolve(homedir()),'Isolated Claude cannot use actual profile')
   else { assert.equal(run,execute,'Real profile cannot use injected transport');assert.equal(home,resolve(homedir()),'Real profile identity required') }
-  const identity={executable:exe,sha256:sha(await readFile(exe)),userRoot:home,configDir:locations(home).config,platform:process.platform,arch:process.arch,scope}
+  const identity={executable:exe,sha256:sha(await readFile(exe)),userRoot:home,configDir:locations(home).config,nativeCwd,platform:process.platform,arch:process.arch,scope}
   const config=identity.configDir
   const env={HOME:home,CLAUDE_CONFIG_DIR:config,PATH:dirname(process.execPath)+':/usr/bin:/bin',
     XDG_CONFIG_HOME:join(home,'.config'),XDG_CACHE_HOME:join(home,'.cache'),XDG_DATA_HOME:join(home,'.local/share'),
     TMPDIR:join(config,'tmp'),LANG:'C.UTF-8',LC_ALL:'C.UTF-8',DISABLE_AUTOUPDATER:'1',NODE_OPTIONS:'',NODE_PATH:''}
-  const s={identity,userRoot:home,run,env}
+  const s={identity,userRoot:home,run,env,nativeCwdIdentity:{dev:cwdInfo.dev,ino:cwdInfo.ino}}
   const version=(await call(s,['--version'])).trim().match(/^(\d+\.\d+\.\d+(?:[-+][\w.-]+)?) \(Claude Code\)$/)
   assert.ok(version,'Expected Claude Code native executable');identity.version=version[1]
   // Check the native interface we actually use, not one developer's binary hash.
@@ -169,6 +189,7 @@ async function lock(directory,id,fn,recovery=false) {
 }
 function validatePlan(plan) {
   const {planSha256,...body}=plan;assert.equal(digest(body),planSha256,'Claude plan body digest mismatch')
+  assert.ok(typeof plan.protocol?.nativeCwd==='string','Claude protocol missing nativeCwd; use the retained installed implementation for its existing receipts')
   assert.equal(plan.host,'claude-code');assert.equal(plan.scope,'user');pluginName(plan.selector)
   for(const key of ['npmRoot','userRoot','receiptDirectory'])assert.ok(isAbsolute(plan[key])&&resolve(plan[key])===plan[key],'Noncanonical Claude plan path')
   assert.ok(!beneath(plan.npmRoot,plan.receiptDirectory)&&!beneath(plan.paths.target,plan.receiptDirectory),'Receipt overlaps owned inputs')

package/bin/npm-installer-dsh.mjs

@@ -98,6 +98,170 @@ async function checkPin(pin) {
   assert.equal(sha(await regular(await realpath(pin.path))), pin.sha256, 'Official file pin changed')
 }
 
+// Only DSH consumes this local product mapping. Older candidates retain their
+// explicit selector/registry route; preparation values never imply a release.
+export function validateReleaseHosts(config) {
+  assert.ok(config && typeof config==='object' && !Array.isArray(config),'Release hosts object required')
+  assert.deepEqual(Object.keys(config).sort(),['hosts','schemaVersion'],'Unknown release hosts fields')
+  assert.equal(config.schemaVersion,1,'Unsupported release hosts schema')
+  assert.ok(config.hosts && typeof config.hosts==='object' && !Array.isArray(config.hosts),'Release hosts map required')
+  assert.deepEqual(Object.keys(config.hosts),['dsh'],'Release mapping currently supports DSH only')
+  const dsh=config.hosts.dsh
+  assert.ok(dsh && typeof dsh==='object' && !Array.isArray(dsh),'DSH release mapping required')
+  assert.deepEqual(Object.keys(dsh).sort(),['aggregatePackage','aggregateVersion','registry'],'Unknown DSH release fields')
+  assert.match(dsh.aggregatePackage ?? '',/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u,'Exact aggregate package name required')
+  if(dsh.aggregateVersion===null && dsh.registry===null)return null
+  assert.match(dsh.aggregateVersion ?? '',/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u,'Exact aggregate version required')
+  assert.equal(typeof dsh.registry,'string','Bound HTTPS registry required')
+  const url=new URL(dsh.registry)
+  assert.ok(url.protocol==='https:' && !url.username && !url.password && !url.search && !url.hash,'Credential-free HTTPS registry required')
+  return {aggregateSelector:`${dsh.aggregatePackage}@${dsh.aggregateVersion}`,registry:url.href}
+}
+
+async function boundedFile(path) {
+  assert.ok(isAbsolute(path), 'Explicit absolute ownership file required')
+  await safeDirectory(dirname(path))
+  const info = await lstat(path)
+  assert.ok(info.isFile() && info.size <= 1024 * 1024, 'Bounded regular ownership file required')
+  return regular(path)
+}
+
+/** Pin the acquired product, not an aggregate that a registry operation has yet to acquire. */
+async function productIdentity(root) {
+  if (root === undefined) return null
+  assert.ok(isAbsolute(root), 'Explicit absolute acquired product required')
+  await safeDirectory(root)
+  const manifestBytes = await boundedFile(join(root, 'package.json')), manifest = JSON.parse(manifestBytes)
+  assert.equal(typeof manifest.name, 'string'); assert.equal(typeof manifest.version, 'string')
+  let releaseMap = null
+  try { releaseMap = await boundedFile(join(root, 'release-hosts.json')) }
+  catch (error) { if (error.code !== 'ENOENT') throw error }
+  const entries = {}
+  for (const file of ['design-system.mjs', 'installer.mjs', 'npm-installer-dsh.mjs', 'npm-agent-installation.mjs'])
+    entries[file] = sha(await boundedFile(join(root, 'bin', file)))
+  return { npmRoot: root, name: manifest.name, version: manifest.version, manifestSha256: sha(manifestBytes),
+    releaseMapSha256: releaseMap === null ? null : sha(releaseMap),
+    releaseSelection: releaseMap === null ? null : validateReleaseHosts(JSON.parse(releaseMap)), entries }
+}
+
+function expectedSource(input) {
+  return { kind: input.aggregateDirectory ? 'retained-link' : 'registry-selector',
+    aggregateSelector: input.aggregateSelector, registry: input.registry,
+    ...(input.aggregateDirectory ? { aggregateDirectory: input.aggregateDirectory,
+      aggregateManifestSha256: input.aggregateManifestSha256, aggregatePatchSha256: input.aggregatePatchSha256 } : {}) }
+}
+function ownedState(current) {
+  return { dependency: current.dependency, installed: current.installed, registered: current.registered }
+}
+
+function ownerReference(record) {
+  return { receiptFile: record.path, receiptSha256: sha(record.bytes), planSha256: record.plan.planSha256,
+    product: record.plan.product, owned: record.receipt.source.observed }
+}
+function assertOwnerReference(reference) {
+  assert.ok(reference && typeof reference === 'object', 'Actual native owner reference required')
+  assert.ok(typeof reference.receiptFile === 'string' && isAbsolute(reference.receiptFile), 'Actual native owner file required')
+  for (const key of ['receiptSha256', 'planSha256']) assert.match(reference[key] ?? '', /^[a-f0-9]{64}$/u, 'Native owner hash required')
+  assert.ok(reference.product && reference.owned?.installed && reference.owned.registered, 'Native owner identity required')
+}
+
+// This validates a saved fact without reading historical product directories or
+// following its earlier owner. Only the selected current product is reread below.
+async function readOwnedReceipt(path, state, profile, currentProduct) {
+  assert.ok(typeof path === 'string' && isAbsolute(path), 'Explicit absolute previous receipt required')
+  for (const root of [state.dshHome, currentProduct.npmRoot, ...Object.values(state.pins).map(pin => dirname(pin.path))])
+    assert.ok(!beneath(root, path), 'Previous receipt overlaps host or product inputs')
+  if (process.platform === 'win32') await assertWindowsPrivate(dirname(path), { directory: true })
+  const bytes = await boundedFile(path), receipt = JSON.parse(bytes)
+  const { receiptSha256, ...body } = receipt
+  assert.equal(receipt.schemaVersion, 2, 'Ownership proof required; sparse or manual receipts cannot be adopted')
+  assert.equal(digest(body), receiptSha256, 'Previous receipt digest mismatch')
+  assert.equal(receipt.kind, 'dsh-installation'); assert.equal(receipt.host, 'dsh')
+  assert.equal(receipt.route, 'official-dsh-bundle'); assert.equal(receipt.scope, state.identity.scope)
+  assert.match(receipt.id ?? '', /^[0-9a-f-]{36}$/u)
+  assert.equal(receipt.receiptPath, path)
+  assert.equal(join(dirname(path), receipt.id + '.dsh-result.json'), path)
+  assert.equal(receipt.status, 'registered-config-parsed', 'Successful owned installation required')
+  assert.equal(receipt.ownershipEstablished, true, 'Previous installation ownership was not established')
+  assert.equal(receipt.exitCode, 0); assert.equal(receipt.partialStateRetained, false)
+  assert.equal(receipt.userConfigurationPreserved, true)
+  const old = receipt.planSnapshot, { planSha256, ...unsigned } = old ?? {}
+  assert.equal(planSha256, receipt.planSha256); assert.equal(digest(unsigned), planSha256, 'Previous plan digest mismatch')
+  assert.deepEqual(old.protocol, state.identity, 'Previous official profile or protocol differs')
+  assert.equal(old.profile, profile, 'Previous profile differs')
+  assert.deepEqual(receipt.product, old.product, 'Previous product identity mismatch')
+  assert.ok(old.product?.releaseSelection, 'Previous product was not release-bound')
+  assert.ok(!beneath(old.product.npmRoot, path), 'Previous receipt overlaps its acquired product')
+  const selected = await selectorInput({ profile: old.profile, aggregateSelector: old.aggregateSelector, registry: old.registry })
+  assert.deepEqual(old.package, selected.package, 'Previous selected package differs')
+  // A receipt pins both the canonical release origin and the effective download
+  // registry. They may differ for an explicitly selected mirror, never in version.
+  assert.deepEqual(old.product.releaseSelection, validateReleaseHosts({ schemaVersion: 1, hosts: { dsh: {
+    aggregatePackage: selected.package.name, aggregateVersion: selected.package.version,
+    registry: old.product.releaseSelection.registry } } }), 'Previous product selection mismatch')
+  assert.deepEqual(receipt.source?.expected, expectedSource(old), 'Previous selected source differs')
+  assert.deepEqual(receipt.source?.observed, ownedState(receipt.readback), 'Previous installed source differs')
+  assert.equal(receipt.readback?.configurationParsed, true)
+  assert.equal(receipt.readback?.packageInstalled, true); assert.equal(receipt.readback?.bundleRegistered, true)
+  assert.equal(receipt.readback.installed?.name, selected.package.name)
+  assert.equal(receipt.readback.installed?.version, selected.package.version)
+  assert.equal(receipt.readback.registered, true)
+  if (old.aggregateDirectory) {
+    assert.equal(receipt.readback.installed.realPackageDir, old.aggregateDirectory)
+    assert.ok(receipt.readback.dependency.startsWith('link:'))
+  } else assert.equal(receipt.readback.dependency, selected.package.version)
+  return { path, bytes, receipt, plan: old }
+}
+function assertNativeOwner(record) {
+  const { receipt, plan } = record
+  assert.equal(receipt.execution?.state, 'completed', 'Owner must be an actual completed native operation')
+  assert.equal(receipt.execution.exitCode, 0, 'Native owner must have exited successfully')
+  if (plan.action === 'install') {
+    assert.ok(!plan.before.installed && !plan.before.registered && plan.before.dependency === null,
+      'Native install owner must start with an absent aggregate')
+  } else {
+    assert.equal(plan.action, 'update', 'A no-command observation is not a native owner')
+    assertOwnerReference(plan.previous)
+    assert.deepEqual(ownedState(plan.before), plan.previous.owned, 'Native update before-state differs from its owner')
+    assert.notEqual(plan.before.installed.version, receipt.readback.installed.version)
+    assert.notEqual(plan.previous.product.version, plan.product.version)
+    assert.equal(plan.previous.product.name, plan.product.name)
+  }
+}
+
+async function previousOwnership(path, state, input, product) {
+  assert.ok(product?.releaseSelection, 'Owned update requires a release-bound acquired product')
+  const selected = await readOwnedReceipt(path, state, input.profile, product)
+  let anchor = selected
+  if (selected.plan.action !== 'install') {
+    const reference = selected.plan.previous
+    assertOwnerReference(reference)
+    // Read exactly one native anchor. Never follow its own earlier reference.
+    const native = await readOwnedReceipt(reference.receiptFile, state, input.profile, product)
+    assert.deepEqual(ownerReference(native), reference, 'Native owner reference changed')
+    assertNativeOwner(native)
+    assert.deepEqual(ownedState(selected.plan.before), reference.owned, 'Previous before-state differs from its native owner')
+    if (selected.plan.action === 'already-registered') {
+      assert.equal(selected.receipt.execution?.state, 'not-needed')
+      assert.deepEqual(selected.plan.product, native.plan.product, 'Observation product differs from its native owner')
+      assert.deepEqual(selected.receipt.source, native.receipt.source, 'Observation source differs from its native owner')
+      anchor = native
+    } else assertNativeOwner(selected)
+  } else assertNativeOwner(selected)
+  assert.deepEqual(await productIdentity(selected.plan.product.npmRoot), selected.plan.product, 'Previous acquired product changed')
+  assert.equal(selected.plan.product.name, product.name, 'Previous product name differs')
+  const oldInput = await selectorInput(selected.plan)
+  assert.equal(oldInput.package.name, input.package.name, 'Previous aggregate name differs')
+  assert.equal(selected.plan.product.releaseSelection.registry, product.releaseSelection.registry,
+    'Release registry migration requires a separate route')
+  assert.equal(oldInput.registry, input.registry, 'Registry migration requires a separate route')
+  assert.equal(Boolean(oldInput.aggregateDirectory), Boolean(input.aggregateDirectory), 'Source-kind migration requires a separate route')
+  if (oldInput.package.version === input.package.version)
+    assert.deepEqual(product, selected.plan.product, 'Same-version relocation is not an owned update')
+  else assert.notEqual(product.version, selected.plan.product.version, 'An update requires a new exact product version')
+  return { input: oldInput, inputSha256: sha(selected.bytes), reference: ownerReference(anchor) }
+}
+
 /** Pins are caller-selected release inputs, not host discovery or publication proof. */
 export async function createDshInstallerAdapter({ scope = 'official-pinned', dshHome,
   node, cli, hostManifest, loader, loaderManifest, desktopHostManifest, hostVersion, loaderVersion,
@@ -204,6 +368,8 @@ async function snapshot(state, input) {
   }
   let installed = null
   if (packageDir !== null) {
+    const realPackageDir = await realpath(packageDir)
+    assert.equal(await realpath(join(dir, 'node_modules', name)), realPackageDir, 'Official resolution is not the direct profile package')
     if (input.aggregateDirectory) assert.equal(await realpath(packageDir), input.aggregateDirectory, 'Resolved aggregate differs from retained installation')
     const bytes = await regular(join(packageDir, 'package.json')), value = JSON.parse(bytes)
     assert.equal(value.name, name, 'Resolved package identity conflict')
@@ -214,22 +380,35 @@ async function snapshot(state, input) {
     const patchPath = resolve(packageDir, patch)
     assert.ok(beneath(resolve(packageDir), patchPath), 'Aggregate patch escapes package')
     assert.ok(beneath(await realpath(packageDir), await realpath(patchPath)), 'Aggregate patch resolves outside package')
-    installed = { name, version: value.version, packageDir, manifestSha256: sha(bytes), patchPath, patchSha256: sha(await regular(patchPath)) }
+    installed = { name, version: value.version, packageDir, realPackageDir, manifestSha256: sha(bytes), patchPath, patchSha256: sha(await regular(patchPath)) }
   } else assert.equal(dependency, undefined, 'Existing aggregate dependency is unresolved; repair separately')
+  const lock = await regular(join(dir, 'pnpm-lock.yaml'), true)
   return { dir, manifestSha256: sha(manifestBytes), foreignSha256: digest(foreignManifest(manifest, name)),
-    patches, configPins, installed, registered: bundles.includes(name) }
+    patches, configPins, installed, dependency: dependency ?? null, bundles: [...bundles],
+    lockfileSha256: lock === null ? null : sha(lock), registered: bundles.includes(name) }
 }
 
 /** Read-only plan. Does not initialize profiles, install packages or write configuration. */
 export async function planDshInstallation(options) {
   const state = await protocol(options.adapter), input = await selectorInput(options)
   if (state.pins.desktopHostManifest) assert.equal(input.profile, 'desktop', 'Desktop registration requires its reserved profile')
-  const before = await snapshot(state, input)
-  const plan = { schemaVersion: 1, host: 'dsh', route: 'official-dsh-bundle', ...input,
+  const product = await productIdentity(options.productRoot ?? options.product?.npmRoot)
+  if (product?.releaseSelection) {
+    assert.equal(input.aggregateSelector, product.releaseSelection.aggregateSelector, 'Selected aggregate differs from product release')
+    // selectorInput already admits only credential-free HTTPS transport. Keep
+    // this choice separate from the immutable release origin in product identity.
+  }
+  const previous = options.previousReceipt === undefined ? null
+    : await previousOwnership(options.previousReceipt, state, input, product)
+  const before = await snapshot(state, previous?.input ?? input)
+  if (previous) assert.deepEqual(ownedState(before), previous.reference.owned, 'Owned A installation changed')
+  const plan = { schemaVersion: 2, host: 'dsh', route: 'official-dsh-bundle', ...input, product,
+    ...(previous ? { previousReceipt: options.previousReceipt, previousInputSha256: previous.inputSha256, previous: previous.reference } : {}),
     protocol: structuredClone(state.identity), before, command: state.pins.node.path,
     // Official profiles contain pnpm-workspace.yaml; explicitly target their root.
     args: [...state.pins.desktopHostManifest ? ['--expose-internals'] : [], state.pins.cli.path, 'plugin', '--profile', input.profile, 'add', '--workspace-root', '--save-exact', input.aggregateDirectory ? 'link:' + input.aggregateDirectory : input.aggregateSelector, '--registry', input.registry],
-    action: before.installed && before.registered ? 'already-registered' : 'install',
+    action: previous && previous.input.package.version !== input.package.version ? 'update'
+      : before.installed && before.registered ? 'already-registered' : 'install',
     runtimeMounted: false, bundleCycleVerified: false, releaseValidated: false }
   return { ...plan, planSha256: digest(plan) }
 }
@@ -271,6 +450,7 @@ export async function inspectDshInstallation(options) {
 
 /** Runs only the pinned public CLI; retains partial state on failure, never rolls back. */
 export async function applyDshInstallation(plan, { adapter, signal, timeoutMs = 0, logDirectory } = {}) {
+  plan = structuredClone(plan)
   const { planSha256, ...unsigned } = plan
   assert.equal(digest(unsigned), planSha256, 'Plan or profile changed; replan before execution')
   const state = await protocol(adapter)
@@ -278,14 +458,17 @@ export async function applyDshInstallation(plan, { adapter, signal, timeoutMs =
   assert.equal(fresh.planSha256, plan.planSha256, 'Plan or profile changed; replan before execution')
   if (logDirectory !== undefined) {
     await safeDirectory(logDirectory)
-    for (const root of [state.dshHome, ...Object.values(state.pins).map(pin => dirname(pin.path))])
+    for (const root of [state.dshHome, plan.product?.npmRoot, plan.previous?.product.npmRoot,
+      ...Object.values(state.pins).map(pin => dirname(pin.path))].filter(Boolean))
       assert.ok(!beneath(root, logDirectory) && !beneath(logDirectory, root), 'Command logs overlap host inputs')
     if (process.platform === 'win32') await assertWindowsPrivate(logDirectory, { directory: true })
   }
   let exitCode = 0, executionError = null, execution = { state: 'not-needed', retrySafe: false }, diagnosticError = null
   if (fresh.action !== 'already-registered') {
     const command = await executeDshInstall(fresh.command, fresh.args, { cwd: fresh.before.dir,
-      env: { ...process.env, DSH_HOME: state.dshHome, ...(state.pins.desktopHostManifest ? { ELECTRON_RUN_AS_NODE: '1' } : {}) } },
+      // ORT's supported policy skips its extra CUDA download, not dependency lifecycle scripts.
+      env: { ...process.env, ONNXRUNTIME_NODE_INSTALL_CUDA: 'skip', DSH_HOME: state.dshHome,
+        ...(state.pins.desktopHostManifest ? { ELECTRON_RUN_AS_NODE: '1' } : {}) } },
     { run: state.run, signal, timeoutMs })
     ;({ exitCode, executionError, execution } = command)
     try { await retainCommandOutput(logDirectory, command) }
@@ -296,11 +479,17 @@ export async function applyDshInstallation(plan, { adapter, signal, timeoutMs =
     readback = await inspectDshInstallation({ ...plan, adapter })
     userConfigurationPreserved = readback.foreignSha256 === plan.before.foreignSha256
       && digest(readback.patches) === digest(plan.before.patches) && digest(readback.configPins) === digest(plan.before.configPins)
+      && (plan.action !== 'update' || digest(readback.bundles) === digest(plan.before.bundles))
   } catch (error) { readbackError = error.message }
   const succeeded = exitCode === 0 && diagnosticError === null && userConfigurationPreserved && readback?.configurationParsed === true
-  return { scope: adapter.scope, status: succeeded ? 'registered-config-parsed' : 'failed-partial-state-retained',
+  const ownershipEstablished = Boolean(succeeded && plan.product?.releaseSelection && (plan.previous
+    || plan.action === 'install' && !plan.before.installed && !plan.before.registered && execution.state === 'completed'))
+  return { schemaVersion: 2, kind: 'dsh-installation', host: 'dsh', route: 'official-dsh-bundle',
+    product: plan.product, planSnapshot: plan, planSha256: plan.planSha256, operation: plan.action,
+    ownershipEstablished, source: { expected: expectedSource(plan), observed: readback === null ? null : ownedState(readback) },
+    registryAcquisitionVerified: false, scope: adapter.scope, status: succeeded ? 'registered-config-parsed' : 'failed-partial-state-retained',
     exitCode, executionError, execution, diagnosticError, readbackError, readback, userConfigurationPreserved,
     userConfigurationStatus: readback === null ? 'unverified' : userConfigurationPreserved ? 'observed-matching' : 'changed',
-    rollbackAttempted: false, partialStateRetained: !succeeded,
+    rollbackAttempted: false, rollbackScope: 'adapter-only; official CLI may perform limited compatibility restoration', partialStateRetained: !succeeded,
     runtimeMounted: false, bundleCycleVerified: false, releaseValidated: false }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugoo-design/companion",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Yugoo Design Companion beta: interactive Design Projects and Panels in supported native Agent Hosts.",
   "license": "Apache-2.0",
   "type": "module",

package/payload/overlays/claude-code/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "yugoo-design",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.5",
   "description": "Yugoo Design: interactive Design Panels with Claude Code native agents and background design reviews."
 }