@yugoo-design/companion 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -1,6 +1,6 @@
 # Yugoo Design Companion — beta
 
-Package: `@yugoo-design/companion@0.1.0-beta.1`.
+Package: `@yugoo-design/companion@0.1.0-beta.11`.
 
 Yugoo Design (语构设计系统) is an interactive design plugin for native Agent Hosts.
 It combines domain methods, Design Projects, versioned Design Files and shared
@@ -11,31 +11,129 @@ 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 system Git, Node.js `>=22.19.0 <23` and a durable npm installation directory. 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.1 --registry=https://registry.npmjs.org
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.11 --registry=https://registry.npmjs.org
 npx --no-install design-system --help
 ```
 
-Have the Agent in your intended host follow the installed CLI's parameters and
-that host's setup requirements:
+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
+  protobufjs: true
+  sharp: true
+```
+
+```sh
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip pnpm add --save-exact @yugoo-design/companion@0.1.0-beta.11 --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.11 --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
+unclear, ask only for the missing host choice. Follow this acquired version's
+CLI parameters and host requirements; a newer source guide does not add commands
+to an already published package. Users do not install DSH and Companion separately:
 
 | Host | Native installation route |
 | --- | --- |
-| Codex | `install --host codex`: matching runtime receipt and saved-plan route. |
+| Codex | `install --host codex`: run the existing plan, runtime check and apply transaction, retaining each receipt. |
 | Claude Code | `install --host claude-code`: native user-scope registration. |
 | Qoder CLI | `install --host qoder`: native user-scope registration and independent readback. |
-| QwenWork | `prepare-desktop --target qwenwork`: prepare the expert suite and its MCP configuration; import through the host. |
-| WorkBuddy | `prepare-desktop --target workbuddy`: prepare the stable marketplace and plugin; import or update through the host. |
-| DSH | `install --host dsh`: use the bound aggregate, official CLI/Loader and an explicitly selected existing profile. |
+| QwenWork | `install --host qwenwork`: prepare the expert suite and its MCP configuration; import and enable through the host. |
+| WorkBuddy | `install --host workbuddy`: prepare the stable marketplace and plugin; import or update and enable through the host. |
+| DSH | `install --host dsh`: run the existing plan/apply transaction with the bound aggregate, official CLI/Loader and an explicitly selected existing profile. |
+
+For a fresh WorkBuddy installation, use native suite `0.3.24` with
+`--suite-version 0.3.24`, the verified Node executable and a persistent external
+preparation destination. Import the returned `nativeImport.market` directory and
+enable its `yugoo-design` plugin. The fresh market is also named `yugoo-design`;
+no previous test market or preparation receipt is required. An owned update with
+`--previous-receipt` retains its original market name and directory, including
+historical test markets, rather than migrating a registered installation.
+
+Supply the required host inputs shown by `design-system --help`. Without a host,
+the entry returns `host-selection-required`; missing inputs return
+`inputs-required`, both with exit code 2 and no installation attempted. The
+Agent should obtain supported native facts itself and ask only for missing
+choices. Explicit saved-plan and `prepare-desktop` routes remain available.
+
+The Agent completes executable steps and reports only the required human
+authorization, import, enable, restart or new-session action. Report acquisition,
+registration/import, activation and verified use separately; do not report an
+untested phase as complete. DSH uses its native integration, not a second
+Companion runtime inside the host.
 
 Desktop preparation alone does not register or activate a plugin. Native suite
 versions are separate from npm versions. Preserve unrelated registrations,
 models, credentials and Design Projects; do not overwrite an owned previous
 installation path or automatically repeat an uncertain operation.
+Same-version retries and updates must follow the owning adapter's receipt rules;
+this entry does not introduce a universal replacement or rollback mechanism.
 
 Start the host normally, then invoke Yugoo Design in the intended conversation.
 Confirm the actual loaded skill and tools, open a project, edit and save a Panel,

package/bin/design-system.mjs

@@ -1,9 +1,21 @@
 #!/usr/bin/env node
 import { fileURLToPath } from 'node:url'
 import { installerMain } from './installer.mjs'
+const args=process.argv.slice(2)
+const dshInstall=args[0]==='install'&&args.some((arg,index)=>arg==='--host=dsh'||arg==='--host'&&args[index+1]==='dsh')
+const cancellation=new AbortController()
+const cancel=()=>cancellation.abort()
+if(dshInstall) { process.on('SIGINT',cancel);process.on('SIGTERM',cancel) }
 try {
-  const result=await installerMain(process.argv.slice(2),{npmRoot:fileURLToPath(new URL('../',import.meta.url))})
+  const result=await installerMain(args,{npmRoot:fileURLToPath(new URL('../',import.meta.url)),signal:dshInstall?cancellation.signal:undefined})
   console.log(JSON.stringify(result))
   if(process.argv[2]==='check-runtime'&&!['load-verified','disabled','not-applicable'].includes(result.status))process.exitCode=1
   if(result.status==='failed-partial-state-retained')process.exitCode=1
-} catch(error) { console.error(error.message);process.exitCode=1 }
+  if(['runtime-not-ready','unsupported-host'].includes(result.status))process.exitCode=1
+  if(['host-selection-required','inputs-required'].includes(result.status))process.exitCode=2
+} catch(error) {
+  console.error(error.installation ? JSON.stringify({error:error.message,installation:error.installation}) : error.message)
+  process.exitCode=1
+} finally {
+  if(dshInstall) { process.off('SIGINT',cancel);process.off('SIGTERM',cancel) }
+}

package/bin/installer.mjs

@@ -1,4 +1,5 @@
 import { isPathWithin } from './npm-installer-paths.mjs'
+import { assertWindowsPrivate, ensureWindowsPrivateDirectory } from './windows-private-storage.mjs'
 import assert from 'node:assert/strict'
 import { createHash, randomUUID } from 'node:crypto'
 import { cp, lstat, mkdir, readFile, readdir, realpath, rename, rm, rmdir, unlink, writeFile } from 'node:fs/promises'
@@ -10,10 +11,11 @@ import { parseArgs } from 'node:util'
 import { codexAdapter, assertCodexAdmission, createCodexNativeAdapter } from './npm-installer-codex.mjs'
 import { createClaudeNativeAdapter, planClaudeInstallation, applyClaudeInstallation, recoverClaudeInstallation } from './npm-installer-claude.mjs'
 import { installQoderPlugin } from './npm-installer-qoder.mjs'
-import { checkRuntime, inspectRuntime } from './npm-runtime-check.mjs'
+import { checkRuntime, inspectRuntime, assertGitRuntimeReceipt } from './npm-runtime-check.mjs'
 import { runDesktopDshInstaller } from './npm-installer-dsh-desktop.mjs'
-import { desktopPreparationMain } from './npm-desktop-preparation.mjs'
-import { createDshInstallerAdapter, planDshInstallation, applyDshInstallation } from './npm-installer-dsh.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, validateReleaseHosts } from './npm-installer-dsh.mjs'
 
 export const INSTALL_HOSTS = ['dsh','codex','claude-code','qoder','codex-desktop','qwenwork']
 const PLUGIN = 'yugoo-design'
@@ -240,6 +242,7 @@ function testContract(adapter,userRoot) {
 
 function runtimeGate(plan,receipt,current,receiptSha256) {
   assert.ok(receipt&&typeof receipt==='object'&&!Array.isArray(receipt),'An explicit runtime-check receipt is required')
+  assertGitRuntimeReceipt(receipt,current)
   assert.ok(['installed-runtime-readonly','isolated-test-contract'].includes(receipt.scope),'Unknown runtime receipt scope')
   assert.equal(receipt.npmRoot,plan.npmRoot,'Runtime receipt npmRoot mismatch')
   assert.equal(receipt.identitySha256,current.identitySha256,'Runtime receipt identity drift')
@@ -620,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}
@@ -664,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)
@@ -675,23 +661,30 @@ 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)))
   }
   for(const root of roots)assert.ok(outside(root,output)&&outside(output,root),'DSH output overlaps a package, host or user configuration root')
   for(const file of [configPath,planPath].filter(Boolean))
     assert.ok(outside(output,resolve(file))&&outside(resolve(file),output),'DSH output overlaps config or saved plan')
+  if(process.platform==='win32') {
+    try { await lstat(output) } catch(error) { if(error.code==='ENOENT')return output; throw error }
+    await assertWindowsPrivate(output,{directory:true})
+  }
   return output
 }
 async function writeDshOutput(directory,name,value) {
-  await safePath(directory);await mkdir(directory,{recursive:true});await safePath(directory)
+  await safePath(directory)
+  if(process.platform==='win32')await ensureWindowsPrivateDirectory(directory)
+  else await mkdir(directory,{recursive:true})
+  await safePath(directory)
   const path=join(directory,name)
   // Exclusive create, never overwrite even an unrelated file at a digest name.
   await safePath(path);await writeFile(path,encode(value),{flag:'wx',mode:0o600})
   return path
 }
-async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args}) {
+async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args,signal,dshInstallTimeoutMs}) {
   assert.ok(values['dry-run']===true&&values.apply!==true||values.apply===true&&values['dry-run']!==true,'Choose exactly dry-run or apply')
   for(const key of ['codex-executable','user-root','runtime-receipt','disable-embedding','receipt'])
     assert.ok(!Object.hasOwn(values,key),`DSH install does not accept --${key}`)
@@ -700,7 +693,7 @@ async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args}) {
   const selection=await dshReleaseSelection(values,npmRoot)
   const configPath=values['dsh-config'],config=await dshConfiguration(configPath)
   if (config.desktopHostManifest && !process.versions.electron)
-    return runDesktopDshInstaller({ node:config.node, args, npmRoot })
+    return runDesktopDshInstaller({ node:config.node, args, npmRoot, signal, timeoutMs:dshInstallTimeoutMs })
   const output=await dshOutputDirectory(values['receipt-dir'],{npmRoot,config,configPath})
   const adapter=await dshAdapterFactory({...config,scope:'official-pinned'})
   let aggregateDirectory
@@ -708,9 +701,12 @@ async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args}) {
     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}
   }
@@ -721,14 +717,27 @@ async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args}) {
   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})
-  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. */
@@ -786,18 +795,19 @@ export async function nativePluginDirectory({npmRoot,host}) {
   }
 }
 
-export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=codexAdapter,dshAdapterFactory=createDshInstallerAdapter,claudeAdapterFactory=createClaudeNativeAdapter,qoderInstaller=installQoderPlugin}={}) {
+export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=codexAdapter,dshAdapterFactory=createDshInstallerAdapter,claudeAdapterFactory=createClaudeNativeAdapter,qoderInstaller=installQoderPlugin,agentDispatch=true,signal,dshInstallTimeoutMs}={}) {
   if(args[0]==='prepare-desktop')return desktopPreparationMain(args.slice(1),{npmRoot})
   const {values,positionals}=parseArgs({args,allowPositionals:true,options:{host:{type:'string'},'dry-run':{type:'boolean'},
     help:{type:'boolean',short:'h'},apply:{type:'boolean'},plan:{type:'string'},'receipt-dir':{type:'string'},receipt:{type:'string'},'runtime-receipt':{type:'string'},'codex-executable':{type:'string'},'claude-executable':{type:'string'},'user-root':{type:'string'},'disable-embedding':{type:'boolean'},
     'qoder-executable':{type:'string'},'qoder-config-dir':{type:'string'},
-    'dsh-config':{type:'string'},profile:{type:'string'},'aggregate-selector':{type:'string'},registry:{type:'string'}}})
+    'dsh-config':{type:'string'},profile:{type:'string'},'aggregate-selector':{type:'string'},registry:{type:'string'},
+    ...Object.fromEntries(DESKTOP_INSTALL_OPTIONS.map(key=>[key,{type:key==='separate-mcp'?'boolean':'string'}]))}})
   if(values.help)return {
     schemaVersion:1,kind:'installer-help',status:'not-applicable',
     usage:'design-system <command> [options]',
     commands:{
       'prepare-desktop':'Prepare a small QwenWork suite or stable WorkBuddy market from this exact acquired npm package. Uses --target, --package-name/--package-version, --suite-version, --node-executable and an external --destination; does not register a host. Updates use the previous preparation receipt.',
-      install:'Install persistently through the selected native host. Claude accepts a direct install with executable and receipt directory, or --dry-run / --apply. DSH/Codex use their existing saved-plan routes.',
+      install:'The current Agent selects --host from trusted context or one user choice. Direct install orchestrates the existing DSH/Codex saved-plan routes, native Claude/Qoder registration, or QwenWork/WorkBuddy import preparation. Missing inputs and pending activation are explicit. Existing --dry-run / --apply remain available.',
       'plugin-directory':'Inspect the optional Claude/Qoder session-only --plugin-dir entry; this is not persistent installation.',
       'check-runtime':'Check runtime prerequisites and write an external runtime receipt; does not install.',
       recover:'Recover an owned Codex or Claude installation transaction using --receipt.',
@@ -805,7 +815,7 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
     },
     options:{
       '--help, -h':'Show this JSON usage without reading configuration or registering a host.',
-      '--host <host>':`Explicit host: ${INSTALL_HOSTS.join(', ')}. Names do not imply verified registration.`,
+      '--host <host>':`Current host: ${AGENT_INSTALL_HOSTS.join(', ')}. Omission requests one choice; installed binaries are not active-host identity. Explicit legacy codex-desktop remains plan-only.`,
       '--dry-run':'Prepare an install plan; requires --receipt-dir and writes that plan.',
       '--apply':'Apply a saved plan. Codex and Claude require --runtime-receipt; DSH requires explicit pins and external --receipt-dir.',
       '--plan <file>':'Saved installation plan used by --apply.',
@@ -821,13 +831,29 @@ 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>':'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. Persistent installation uses native host registration. Codex requires an admitted adapter; DSH requires pinned public CLI inputs; unimplemented hosts are plan-only.',
+    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.',
       'DSH failures retain partial state without rollback. Configuration parsing is not actual host runtime or release acceptance.',
       'Uninstall requires a successful owned receipt. Package installation is not Bundle/Panel/GRA/KAG acceptance.'],
   }
   assert.equal(positionals.length,1,'Exactly one installer command required')
+  if(agentDispatch&&positionals[0]==='install'&&!values['dry-run']&&!values.apply) {
+    const context={npmRoot,userRoot,adapter,dshAdapterFactory,claudeAdapterFactory,qoderInstaller,agentDispatch:false,signal,dshInstallTimeoutMs}
+    return agentInstallation(values,{npmRoot,admittedCodexAdapter:adapter!==codexAdapter,
+      invoke:nextArgs=>installerMain(nextArgs,context),
+      desktopPrepare:nextArgs=>desktopPreparationMain(nextArgs,{npmRoot}),
+      desktopReuse:nextArgs=>desktopPreparationReuseMain(nextArgs,{npmRoot})})
+  }
+  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})
@@ -858,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')
@@ -880,7 +906,7 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
     }
     return {...plan,planFile:path}
   }
-  if(values.host==='dsh'&&positionals[0]==='install')return dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args})
+  if(values.host==='dsh'&&positionals[0]==='install')return dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args,signal,dshInstallTimeoutMs})
   if(adapter===codexAdapter&&values['codex-executable']&&positionals[0]!=='check-runtime') {
     assert.equal(values.host,'codex','Native executable is only valid for the Codex host')
     const profile=resolve(values['user-root']??userRoot)

package/bin/npm-agent-installation.mjs

@@ -0,0 +1,141 @@
+/** Agent-facing orchestration of the existing native installers, not a registration authority. */
+import assert from 'node:assert/strict'
+import { randomUUID } from 'node:crypto'
+import { lstat, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+export const AGENT_INSTALL_HOSTS = ['dsh', 'codex', 'claude-code', 'qoder', 'qwenwork', 'workbuddy']
+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', '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'],
+}
+
+function argv(command, values, keys) {
+  const args = [command]
+  for (const key of keys) if (Object.hasOwn(values, key)) {
+    args.push('--' + key)
+    if (typeof values[key] !== 'boolean') args.push(values[key])
+    else assert.equal(values[key], true, 'False CLI flags are not supported')
+  }
+  return args
+}
+function pending(host, status, missing, message) {
+  return { schemaVersion: 1, kind: 'agent-installation', status, host: host ?? null,
+    hostRegistered: false, usable: false, missing,
+    installation: { host: host ?? null, acquisition: 'unverified', registration: 'not-performed',
+      activation: 'not-performed', usability: 'unverified', nextActions: [{ action: 'supply-inputs', automatic: false, message }] } }
+}
+function activationActions(host, result) {
+  const verify = { action: 'verify-native-session', automatic: true,
+    message: 'In the intended native conversation, verify the actually loaded Yugoo Design version and tools; then open a project and verify Panel save/reopen and original-conversation receipt. Registration alone is not usability.' }
+  if (host === 'qwenwork') return [
+    { action: 'import-expert-suite', automatic: false, path: result.nativeImport?.archive,
+      message: 'Import this exact expert-suite ZIP through QwenWork. If bundled MCP is disabled by organization policy, use the emitted connector configuration and retain exactly one Yugoo Design connector.' },
+    { action: 'activate-native-suite', automatic: false,
+      message: 'Enable the imported suite; start a new native conversation if QwenWork requires it. Retain the acquired npm runtime and confirm the actually loaded suite version.' }, verify]
+  if (host === 'workbuddy') return [
+    { action: 'import-or-update-market', automatic: false, path: result.nativeImport?.market,
+      message: 'Import this stable marketplace through WorkBuddy, or refresh the same market and update its existing Yugoo Design plugin. Preparation has not registered or activated it.' },
+    { action: 'activate-native-plugin', automatic: false,
+      message: 'Enable the plugin and start a new native conversation if WorkBuddy requires it; confirm the actually loaded suite version.' }, verify]
+  return [{ action: 'activate-native-session', automatic: false,
+    message: host === 'dsh'
+      ? 'Use the selected existing DSH profile and the host-supported plugin activation/restart flow; verify runtime loading in a new native session.'
+      : host === 'codex'
+        ? 'Start a new Codex conversation normally in the intended workspace and invoke the installed yugoo Skill through the native Skill entry. Retain the registered npm runtime.'
+        : 'Start a new native host conversation normally in the intended workspace and invoke /yugoo-design:yugoo. Retain the registered npm runtime; no --plugin-dir is needed.' }, verify]
+}
+
+/** Project only verified facts from the owning native/preparation receipt. */
+export function installationResult(host, result, packageIdentity) {
+  const failed = result.status === 'failed-partial-state-retained'
+  const desktop = host === 'qwenwork' || host === 'workbuddy'
+  const registered = !desktop && !failed && (result.hostRegistered === true
+    || host === 'dsh' && result.status === 'registered-config-parsed' && result.readback?.bundleRegistered === true)
+  const identity = result.package ?? packageIdentity
+  return { ...result, host, usable: false,
+    installation: { host, package: identity ?? null,
+      acquisition: identity?.name && identity?.version && (host !== 'dsh' || result.readback?.packageInstalled === true) ? 'available' : 'unverified',
+      // This entry consumes an acquired installation; it never verifies a registry download.
+      registryAcquisitionVerified: false,
+      registration: failed ? 'failed-partial-state-retained' : registered ? 'verified' : 'not-performed',
+      activation: failed ? 'not-performed' : 'required', usability: 'unverified',
+      nextActions: failed ? [{ action: 'inspect-retained-state', automatic: false, path: result.receiptFile,
+        message: 'Inspect the owning receipt and retained DSH state before another operation. No automatic rollback or retry was attempted.' }]
+        : activationActions(host, result) } }
+}
+
+export async function agentInstallation(values, { npmRoot, invoke, desktopPrepare, desktopReuse,
+  admittedCodexAdapter = false, platform = process.platform } = {}) {
+  const host = values.host
+  // Installed executables, PATH, host profiles and process names cannot identify this conversation.
+  if (!host) return { ...pending(null, 'host-selection-required', ['host'],
+    'Select the host of this conversation. If trusted native context identifies it, the current Agent should supply --host; otherwise ask one host-selection question.'), hosts: AGENT_INSTALL_HOSTS }
+  if (host === 'codex-desktop') return pending(host, 'unsupported-host', [],
+    'Codex Desktop native registration is not implemented by this entry. Select the actual supported host; do not substitute a CLI or infer usability from a prepared plan.')
+  assert.ok(AGENT_INSTALL_HOSTS.includes(host), 'Explicit supported host required')
+  const desktop = host === 'qwenwork' || host === 'workbuddy'
+  const allowed = desktop ? ['host', ...DESKTOP_INSTALL_OPTIONS] : nativeOptions[host]
+  for (const key of Object.keys(values)) assert.ok(allowed.includes(key), `${host} install accepts only ${allowed.map(k => '--' + k).join(', ')}; unsupported option --${key}`)
+  const required = desktop ? ['destination', 'node-executable', 'suite-version'] : ['receipt-dir']
+  if (host === 'dsh') required.push('dsh-config', 'profile')
+  if (host === 'codex' && !admittedCodexAdapter) required.push('codex-executable')
+  if (host === 'claude-code') required.push('claude-executable')
+  if (host === 'qwenwork') required.push('qwenwork-runtime')
+  if (host === 'workbuddy') for (const key of ['qwenwork-runtime', 'separate-mcp'])
+    assert.ok(!Object.hasOwn(values, key), `WorkBuddy install does not accept --${key}`)
+  if (desktop && platform !== 'win32') required.push('npm-root-windows', 'destination-windows')
+  const missing = required.filter(key => typeof values[key] !== 'string' || !values[key])
+  if (missing.length) return pending(host, 'inputs-required', missing,
+    `The current Agent should obtain verified values for ${missing.map(key => '--' + key).join(', ')}. Ask only for information or host actions it cannot obtain through supported native inspection. No installation was attempted.`)
+
+  let plan
+  try {
+    if (desktop) {
+      const path = join(npmRoot, 'package.json'), info = await lstat(path)
+      assert.ok(info.isFile() && info.size <= 1024 * 1024, 'Expected bounded regular acquired package manifest')
+      const manifest = JSON.parse(await readFile(path, 'utf8'))
+      const args = argv('prepare-desktop', values, DESKTOP_INSTALL_OPTIONS).slice(1)
+      args.push('--target', host, '--package-name', manifest.name, '--package-version', manifest.version)
+      const reused = values['previous-receipt'] && await desktopReuse(args)
+      return installationResult(host, reused || await desktopPrepare(args))
+    }
+    if (host === 'claude-code' || host === 'qoder')
+      return installationResult(host, await invoke(argv('install', values, allowed)))
+    // DSH's exclusive plan files are never overwritten. Each direct operation gets
+    // its own receipt subdirectory; Codex keeps the stable directory needed by upgrades.
+    const nativeValues = host === 'dsh' ? { ...values, 'receipt-dir': join(values['receipt-dir'], randomUUID()) } : values
+    const dryArgs = argv('install', nativeValues, allowed)
+    dryArgs.push('--dry-run')
+    plan = await invoke(dryArgs)
+    assert.ok(plan.planFile, 'The owning installer did not retain an installation plan')
+    if (host === 'codex') {
+      assert.equal(plan.applySupported, true, 'Codex native installation is not admitted by the owning adapter')
+      const runtime = await invoke(argv('check-runtime', values, ['host', 'receipt-dir', 'disable-embedding']))
+      if (!['load-verified', 'disabled'].includes(runtime.status)) return {
+        ...pending(host, 'runtime-not-ready', [], 'Inspect the runtime receipt. No native apply was attempted; repair the reported prerequisites before re-running install.'),
+        runtimeReceipt: runtime, planFile: plan.planFile }
+      assert.ok(runtime.receiptFile, 'The owning runtime checker did not retain its receipt')
+      const applyArgs = argv('install', values, allowed.filter(key => !['receipt-dir', 'disable-embedding'].includes(key)))
+      applyArgs.push('--apply', '--plan', plan.planFile, '--runtime-receipt', runtime.receiptFile)
+      return installationResult(host, await invoke(applyArgs), plan.package)
+    }
+    const applyArgs = argv('install', nativeValues, allowed)
+    applyArgs.push('--apply', '--plan', plan.planFile)
+    return installationResult(host, await invoke(applyArgs), plan.package)
+  } catch (error) {
+    const receipt = error.receiptFile ?? error.receiptPath ?? null
+    error.installation = { host, acquisition: 'unverified', registration: 'failed-or-unconfirmed',
+      activation: 'not-performed', usability: 'unverified', receiptFile: receipt,
+      planFile: plan?.planFile ?? null,
+      nextActions: [{ action: receipt ? 'inspect-owned-receipt' : 'inspect-failure', automatic: false,
+        message: host === 'codex' || host === 'claude-code'
+          ? 'Inspect the failure and matching owned receipt; use the existing recover --host route only when that receipt requires recovery. Do not delete profiles, projects or unrelated plugins.'
+          : 'Inspect retained state before retrying. This host has no general automatic rollback in this entry; use its supported update/recovery flow.' }] }
+    throw error
+  }
+}