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

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.3`.
 
 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,53 @@ 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 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
 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
+npm install --ignore-scripts --save-exact @yugoo-design/companion@0.1.0-beta.3 --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:
+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. |
+
+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,9 +11,10 @@ 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 { 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'
 
 export const INSTALL_HOSTS = ['dsh','codex','claude-code','qoder','codex-desktop','qwenwork']
@@ -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')
@@ -682,16 +685,23 @@ async function dshOutputDirectory(path,{npmRoot,config,configPath,planPath}) {
   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 +710,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
@@ -725,7 +735,7 @@ async function dshInstallerEntry(values,{npmRoot,dshAdapterFactory,args}) {
   const fresh=await planDshInstallation(options)
   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 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}
@@ -786,18 +796,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 +816,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.',
@@ -822,12 +833,27 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
       '--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.',
+      '--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.',
+      '--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)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})
@@ -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'],
+  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
+  }
+}

package/bin/npm-desktop-preparation.mjs

@@ -201,11 +201,61 @@ export async function prepareDesktopPackage({ npmRoot, packageName, packageVersi
   }
 }
 
-export async function desktopPreparationMain(args, { npmRoot } = {}) {
+function preparationArguments(args) {
   const { values, positionals } = parseArgs({ args, options: { help: { type: 'boolean', short: 'h' }, target: { type: 'string' }, 'package-name': { type: 'string' }, 'package-version': { type: 'string' },
     destination: { type: 'string' }, 'node-executable': { type: 'string' }, 'suite-version': { type: 'string' }, 'npm-root-windows': { type: 'string' }, 'destination-windows': { type: 'string' },
     'qwenwork-runtime': { type: 'string' }, 'separate-mcp': { type: 'boolean' }, 'previous-receipt': { type: 'string' } }, allowPositionals: true })
   assert.equal(positionals.length, 0, 'No positional preparation arguments allowed')
+  return values
+}
+
+/** Same-version reuse under the owning preparation lease; no artifact or receipt rewrite. */
+export async function desktopPreparationReuseMain(args, { npmRoot } = {}) {
+  const values = preparationArguments(args)
+  if (!values['previous-receipt']) return null
+  const output = resolve(values.destination), root = resolve(npmRoot)
+  await safe(root); await safe(output)
+  assert.equal(await realpath(root), root)
+  assert.ok(output !== root && !confined(root, output) && !confined(output, root), 'Preparation must be outside npm package')
+  assert.ok(outsideHostProfile(output), 'Do not prepare inside native host profiles')
+  const prior = await priorReceipt(resolve(values['previous-receipt'])), body = prior.body
+  const manifestBytes = await file(join(npmRoot, 'package.json')), manifest = JSON.parse(manifestBytes)
+  if (manifest.version !== body.package.version) return null // The existing preparer owns new-version updates.
+  assert.equal(manifest.name, values['package-name']); assert.equal(manifest.version, values['package-version'])
+  assert.equal(manifest['x-design-release-review']?.fixture, false, 'Fixture packages cannot reuse desktop imports')
+  assert.equal(body.package.npmRoot, resolve(npmRoot), 'Same-version reuse requires the same retained npm directory')
+  assert.equal(body.package.manifestSha256, sha(manifestBytes), 'Same-version acquired manifest changed')
+  assert.equal(body.target, values.target); assert.equal(body.destination, resolve(values.destination))
+  assert.equal(body.suiteVersion, values['suite-version'], 'Same npm version cannot change the native suite version')
+  const windowsNpm = windowsPath(values['npm-root-windows'] ?? (process.platform === 'win32' ? npmRoot : undefined))
+  const windowsOutput = windowsPath(values['destination-windows'] ?? (process.platform === 'win32' ? body.destination : undefined))
+  assert.ok(outsideHostProfile(windowsOutput), 'Do not prepare inside native host profiles')
+  if (process.platform === 'win32') { assert.equal(windowsNpm.toLowerCase(), win32.normalize(root).toLowerCase()); assert.equal(windowsOutput.toLowerCase(), win32.normalize(output).toLowerCase()) }
+  assert.equal(body.windows.npmRoot, windowsNpm); assert.equal(body.windows.destination, windowsOutput)
+  assert.equal(body.windows.nodeExecutable, windowsPath(values['node-executable']), 'Same-version Node path changed')
+  if (body.target === 'qwenwork') {
+    assert.equal(body.nativeImport.includeMcp, !values['separate-mcp'], 'Same-version connector policy changed')
+    const nativePins = JSON.parse(await file(resolve(values['qwenwork-runtime'])))
+    assert.deepEqual(nativePins, JSON.parse(await file(join(dirname(body.nativeImport.suite), 'runtime-pins.json'))), 'Same-version native pins changed')
+    if (process.platform === 'win32') for (const [path, expected] of [[nativePins.executable, nativePins.executableSha256], [nativePins.worker, nativePins.workerSha256]])
+      assert.equal(await streamHash(path), expected, 'QwenWork native bytes do not match provided pins')
+  }
+  const lock = join(output, '.preparation.lock'), owner = randomUUID()
+  // The inventory excludes this transient file, so bytes alone cannot admit a
+  // repeat while another preparation is active or interrupted. Reuse its exact
+  // exclusive boundary and recheck the snapshot under our own reservation.
+  await writeFile(lock, owner, { flag: 'wx', mode: 0o600 })
+  try {
+    assert.deepEqual(await priorReceipt(resolve(values['previous-receipt'])), prior, 'Preparation changed while acquiring its reuse lock')
+    return { ...body, receiptFile: resolve(values['previous-receipt']), receiptSha256: prior.sha256, idempotent: true }
+  } finally {
+    assert.equal((await file(lock)).toString(), owner, 'Preparation reuse lock ownership changed; retained for inspection')
+    await unlink(lock)
+  }
+}
+
+export async function desktopPreparationMain(args, { npmRoot } = {}) {
+  const values = preparationArguments(args)
   if (values.help) return { kind: 'desktop-preparation-help', status: 'not-applicable', usage: 'design-system prepare-desktop --target qwenwork|workbuddy --package-name EXACT_SCOPED_NAME --package-version EXACT_NPM_VERSION --suite-version NATIVE_RELEASE_VERSION --destination EXTERNAL_DIRECTORY --node-executable ABSOLUTE_WINDOWS_NODE',
     options: { '--qwenwork-runtime': 'Explicit JSON with existing QwenWork executable/worker/Node paths and exact executable/worker hashes.', '--separate-mcp': 'QwenWork only: omit the suite connector and emit one external connector JSON for organization policy.', '--previous-receipt': 'Verified successful preparation receipt for an owned new-version update; preserves the same WorkBuddy market.', '--npm-root-windows, --destination-windows': 'Explicit target path mapping required for cross-platform preparation; native Windows paths must match actual roots.' },
     limits: ['Preparation does not acquire from registry, register a host, grant native admission, verify loaded versions or alter a host profile.', 'Acquire the exact npm release first; retain its durable installation and old version until the native update is verified.'] }

package/bin/npm-installer-claude.mjs

@@ -7,7 +7,7 @@ import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
-import { assertRuntimePath, inspectRuntime } from './npm-runtime-check.mjs'
+import { assertRuntimePath, inspectRuntime, assertGitRuntimeReceipt } from './npm-runtime-check.mjs'
 
 const execute = promisify(execFile), adapters = new WeakMap(), activeLocks = new Set()
 const PLUGIN = 'yugoo-design', LEGACY = 'design-system'
@@ -216,6 +216,7 @@ export async function planClaudeInstallation({npmRoot,userRoot,receiptDirectory,
 }
 function runtimeGate(plan,receipt,current,s) {
   assert.ok(receipt&&typeof receipt==='object'&&!Array.isArray(receipt),'Explicit Claude runtime receipt required')
+  assertGitRuntimeReceipt(receipt,current)
   assert.ok(['installed-runtime-readonly','isolated-test-contract'].includes(receipt.scope),'Unknown runtime receipt scope')
   if(!s.identity.scope.startsWith('isolated-'))assert.equal(receipt.scope,'installed-runtime-readonly','Production requires actual runtime receipt')
   assert.equal(receipt.npmRoot,plan.npmRoot);assert.equal(receipt.identitySha256,current.identitySha256,'Runtime receipt identity drift')

package/bin/npm-installer-dsh-desktop.mjs

@@ -8,7 +8,7 @@ import { promisify } from 'node:util'
 
 // Electron owns ASAR resolution. Keep the existing installer and official
 // Loader together in its Node runtime instead of extracting the desktop tree.
-export async function runDesktopDshInstaller({ node, args, npmRoot }) {
+export async function runDesktopDshInstaller({ node, args, npmRoot, signal, timeoutMs = 0 }) {
   assert.ok(node && isAbsolute(node.path), 'Explicit Desktop executable required')
   assert.match(node.sha256 ?? '', /^[a-f0-9]{64}$/u)
   assert.ok((await lstat(await realpath(node.path))).isFile(), 'Desktop executable must be a regular file')
@@ -16,13 +16,22 @@ export async function runDesktopDshInstaller({ node, args, npmRoot }) {
   assert.equal(hash, node.sha256, 'Desktop executable pin changed')
   assert.ok(Array.isArray(args) && args.every(arg => typeof arg === 'string' && !arg.includes('\0')), 'Installer argv required')
   assert.ok(typeof npmRoot === 'string' && isAbsolute(npmRoot), 'Retained npm installation must be absolute')
-  const request = Buffer.from(JSON.stringify({ args, npmRoot })).toString('base64url')
-  const { stdout } = await promisify(execFile)(node.path,
+  assert.ok(Number.isSafeInteger(timeoutMs) && timeoutMs >= 0 && timeoutMs <= 2147483647, 'Invalid install deadline')
+  signal?.throwIfAborted()
+  const request = Buffer.from(JSON.stringify({ args, npmRoot, timeoutMs })).toString('base64url')
+  const pending = promisify(execFile)(node.path,
     ['--expose-internals', fileURLToPath(import.meta.url), request], {
       env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
       windowsHide: true, shell: false, maxBuffer: 1024 * 1024,
     })
-  return JSON.parse(stdout)
+  // Use the pipe on Windows as well: killing the bridge would lose its partial
+  // state receipt and says nothing about the official pnpm descendants.
+  const cancel = () => { if (pending.child.stdin?.writable) pending.child.stdin.write('cancel\n') }
+  pending.child.stdin?.on('error', () => {}) // A closed bridge cannot accept a late cancellation.
+  signal?.addEventListener('abort', cancel, { once: true })
+  if (signal?.aborted) cancel()
+  try { return JSON.parse((await pending).stdout) }
+  finally { signal?.removeEventListener('abort', cancel); pending.child.stdin?.destroy() }
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
@@ -32,15 +41,36 @@ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.ur
       assert.ok(process.versions.electron, 'Desktop bridge requires Electron Node mode')
       assert.equal(process.argv.length, 3, 'One installer request required')
       const request = JSON.parse(Buffer.from(process.argv[2], 'base64url').toString('utf8'))
-      assert.deepEqual(Object.keys(request).sort(), ['args', 'npmRoot'])
+      assert.deepEqual(Object.keys(request).sort(), ['args', 'npmRoot', 'timeoutMs'])
       assert.ok(Array.isArray(request.args) && request.args.every(arg => typeof arg === 'string' && !arg.includes('\0')), 'Installer argv required')
       assert.ok(typeof request.npmRoot === 'string' && isAbsolute(request.npmRoot), 'Retained npm installation must be absolute')
-      const { installerMain } = await import('./npm-installer.mjs').catch(error => {
-        if (error.code !== 'ERR_MODULE_NOT_FOUND' || !error.url?.endsWith('/npm-installer.mjs')) throw error
-        // The published bin directory names the same module installer.mjs.
-        return import('./installer.mjs')
+      assert.ok(Number.isSafeInteger(request.timeoutMs) && request.timeoutMs >= 0 && request.timeoutMs <= 2147483647, 'Invalid install deadline')
+      const cancellation = new AbortController()
+      const cancel = () => cancellation.abort()
+      // Terminal Ctrl-C can reach the bridge as well as the outer entry.
+      process.on('SIGINT', cancel)
+      process.on('SIGTERM', cancel)
+      // A partial or malformed control frame cannot authorize any installation.
+      let control = ''
+      process.stdin.setEncoding('utf8')
+      process.stdin.on('data', chunk => {
+        control = (control + chunk).slice(-64)
+        if (control.includes('cancel\n')) cancellation.abort()
       })
-      process.stdout.write(JSON.stringify(await installerMain(request.args, { npmRoot: request.npmRoot })) + '\n')
+      try {
+        const { installerMain } = await import('./npm-installer.mjs').catch(error => {
+          if (error.code !== 'ERR_MODULE_NOT_FOUND' || !error.url?.endsWith('/npm-installer.mjs')) throw error
+          // The published bin directory names the same module installer.mjs.
+          return import('./installer.mjs')
+        })
+        process.stdout.write(JSON.stringify(await installerMain(request.args, {
+          npmRoot: request.npmRoot, signal: cancellation.signal, dshInstallTimeoutMs: request.timeoutMs,
+        })) + '\n')
+      } finally {
+        process.off('SIGINT', cancel)
+        process.off('SIGTERM', cancel)
+        process.stdin.destroy()
+      }
     } catch (error) {
       process.stderr.write(String(error.message) + '\n')
       process.exitCode = 1