@yugoo-design/companion 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -1,6 +1,6 @@
 # Yugoo Design Companion — beta
 
-Package: `@yugoo-design/companion@0.1.0-beta.2`.
+Package: `@yugoo-design/companion@0.1.0-beta.4`.
 
 Yugoo Design (语构设计系统) is an interactive design plugin for native Agent Hosts.
 It combines domain methods, Design Projects, versioned Design Files and shared
@@ -11,15 +11,46 @@ 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. 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.2 --registry=https://registry.npmjs.org
+ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --ignore-scripts=false --save-exact @yugoo-design/companion@0.1.0-beta.4 --registry=https://registry.npmjs.org
 npx --no-install design-system --help
 ```
 
+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.4 --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/design-system.mjs

@@ -1,8 +1,13 @@
 #!/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
@@ -11,4 +16,6 @@ try {
 } 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,11 +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, 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'
@@ -241,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')
@@ -621,25 +623,7 @@ 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))
@@ -665,7 +649,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)
@@ -676,23 +660,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}`)
@@ -701,7 +692,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
@@ -709,9 +700,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}
   }
@@ -722,14 +716,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. */
@@ -787,7 +794,7 @@ export async function nativePluginDirectory({npmRoot,host}) {
   }
 }
 
-export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=codexAdapter,dshAdapterFactory=createDshInstallerAdapter,claudeAdapterFactory=createClaudeNativeAdapter,qoderInstaller=installQoderPlugin,agentDispatch=true}={}) {
+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'},
@@ -829,7 +836,7 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
       '--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.',
@@ -838,13 +845,14 @@ export async function installerMain(args,{npmRoot,userRoot=homedir(),adapter=cod
   }
   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}
+    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`)
+  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})
@@ -875,7 +883,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')
@@ -897,7 +905,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

@@ -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

@@ -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'
@@ -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')
@@ -216,6 +237,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