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

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.3`.
 
 Yugoo Design (语构设计系统) is an interactive design plugin for native Agent Hosts.
 It combines domain methods, Design Projects, versioned Design Files and shared
@@ -11,12 +11,16 @@ 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.2 --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
 ```
 

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,7 +11,7 @@ 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'
@@ -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')
@@ -683,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}`)
@@ -701,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
@@ -726,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}
@@ -787,7 +796,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'},
@@ -838,7 +847,7 @@ 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}),
@@ -897,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-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

package/bin/npm-installer-dsh.mjs

@@ -1,8 +1,9 @@
 import { isPathWithin } from './npm-installer-paths.mjs'
+import { assertWindowsPrivate } from './windows-private-storage.mjs'
 import assert from 'node:assert/strict'
 import { execFile } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { lstat, readFile, realpath } from 'node:fs/promises'
+import { createHash, randomUUID } from 'node:crypto'
+import { lstat, readFile, realpath, writeFile } from 'node:fs/promises'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { promisify } from 'node:util'
@@ -14,6 +15,72 @@ const canonical = value => Array.isArray(value) ? value.map(canonical) : value &
   ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value
 const digest = value => sha(JSON.stringify(canonical(value)))
 const beneath = isPathWithin
+export const DSH_INSTALL_MAX_OUTPUT_BYTES = 1024 * 1024
+
+/** Install duration belongs to the native package manager, not a probe timer. */
+export async function executeDshInstall(command, args, options, { run = exec, signal, timeoutMs = 0 } = {}) {
+  assert.ok(Number.isSafeInteger(timeoutMs) && timeoutMs >= 0 && timeoutMs <= 2147483647, 'Invalid install deadline')
+  const started = performance.now(), cancellation = new AbortController()
+  let requested = null, timer, pending, output = {}, failure = null, invoked = false
+  const captured = { stdout: [], stderr: [] }, sizes = { stdout: 0, stderr: 0 }
+  const capture = stream => chunk => {
+    const bytes = Buffer.from(chunk).subarray(0, DSH_INSTALL_MAX_OUTPUT_BYTES - sizes[stream])
+    if (bytes.length) { captured[stream].push(bytes); sizes[stream] += bytes.length }
+  }
+  const stop = reason => {
+    if (requested !== null) return
+    requested = reason
+    cancellation.abort()
+  }
+  const cancel = () => stop('cancelled')
+  signal?.addEventListener('abort', cancel, { once: true })
+  if (signal?.aborted) cancel()
+  if (timeoutMs > 0) timer = setTimeout(() => stop('timed-out'), timeoutMs)
+  try {
+    cancellation.signal.throwIfAborted()
+    invoked = true
+    pending = run(command, args, { ...options, shell: false, timeout: 0,
+      signal: cancellation.signal, maxBuffer: DSH_INSTALL_MAX_OUTPUT_BYTES })
+    for (const stream of ['stdout', 'stderr']) pending.child?.[stream]?.on('data', capture(stream))
+    output = await pending
+  } catch (error) { failure = error; output = error }
+  finally { clearTimeout(timer); signal?.removeEventListener('abort', cancel) }
+  const buffer = value => Buffer.isBuffer(value) ? value : Buffer.from(value ?? '')
+  const stdout = sizes.stdout ? Buffer.concat(captured.stdout) : buffer(output.stdout).subarray(0, DSH_INSTALL_MAX_OUTPUT_BYTES)
+  const stderr = sizes.stderr ? Buffer.concat(captured.stderr) : buffer(output.stderr).subarray(0, DSH_INSTALL_MAX_OUTPUT_BYTES)
+  const overflow = failure?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER'
+    || buffer(output.stdout).length > stdout.length || buffer(output.stderr).length > stderr.length
+  // DOMException.code identifies an API error, never a native process exit.
+  // A pre-cancelled request has not invoked the runner even if its reason has a code.
+  const observedCode = failure ? (invoked && failure.name !== 'AbortError' && !(failure instanceof DOMException)
+    && Number.isInteger(failure.code) ? failure.code : null) : output.exitCode ?? output.status ?? 0
+  const code = observedCode ?? 1
+  const state = requested ?? (overflow ? 'output-limit' : failure?.signal ? 'terminated'
+    : failure ? (failure.code === 'ENOENT' || failure.code === 'EACCES' ? 'launch-failed' : 'failed')
+      : code === 0 ? 'completed' : 'failed')
+  const execution = { state, elapsedMs: Math.round(performance.now() - started), timeoutMs,
+    maxOutputBytesPerStream: DSH_INSTALL_MAX_OUTPUT_BYTES, exitCode: observedCode, pid: pending?.child?.pid ?? null,
+    signal: failure?.signal ?? pending?.child?.signalCode ?? null, killed: pending?.child?.killed ?? failure?.killed ?? null,
+    cancellationRequested: requested !== null, outputComplete: requested === null && !overflow && (!failure || observedCode !== null),
+    // An AbortError or a dead parent CLI cannot establish Windows pnpm tree exit.
+    processTreeState: state === 'completed' ? 'not-asserted' : 'unverified', retrySafe: false,
+    output: { stdout: { bytes: stdout.length, sha256: sha(stdout) }, stderr: { bytes: stderr.length, sha256: sha(stderr) } } }
+  return { execution, stdout, stderr,
+    exitCode: state === 'completed' ? 0 : code || 1,
+    executionError: failure ? String(failure.code ?? failure.name) : state === 'completed' ? null : state }
+}
+
+async function retainCommandOutput(directory, command) {
+  if (directory === undefined) return
+  await safeDirectory(directory)
+  if (process.platform === 'win32') await assertWindowsPrivate(directory, { directory: true })
+  const id = randomUUID()
+  for (const stream of ['stdout', 'stderr']) {
+    const path = join(directory, `${id}.dsh-${stream}.log`)
+    await writeFile(path, command[stream], { flag: 'wx', mode: 0o600 })
+    command.execution.output[stream].path = path
+  }
+}
 
 async function regular(path, optional = false) {
   try { assert.ok((await lstat(path)).isFile(), 'Expected regular file'); return await readFile(path) }
@@ -59,7 +126,7 @@ export async function createDshInstallerAdapter({ scope = 'official-pinned', dsh
   }
   assert.equal(await realpath(loader.path), await realpath(resolve(dirname(loaderManifest.path), boot.main)), 'Loader must be the pinned public entry')
   const api = await import(pathToFileURL(await realpath(loader.path)).href)
-  for (const key of ['resolveProfileDir', 'readProfileManifest', 'resolveBundleDir', 'loadOverlayPatches', 'composeEntries'])
+  for (const key of ['resolveProfileDir', 'readProfileManifest', 'resolveBundleDir', 'bundlePatchPaths', 'loadOverlayPatches', 'composeEntries'])
     assert.equal(typeof api[key], 'function', `Missing official Loader interface: ${key}`)
   const adapter = Object.freeze({ scope, hostVersion, loaderVersion })
   admitted.set(adapter, { pins, api, dshHome, run, identity: { scope, dshHome, hostVersion, loaderVersion, pins } })
@@ -178,11 +245,17 @@ export async function inspectDshInstallation(options) {
     for (const name of manifest.dsh.profile.bundles) {
       const dir = state.api.resolveBundleDir('dsh', name, state.pins.hostManifest.path, current.dir)
       const bundle = state.api.readProfileManifest('dsh', dir), declared = bundle.dsh?.bundle?.patch
-      assert.ok(typeof declared === 'string' && !isAbsolute(declared), 'Bundle patch declaration required')
-      const path = resolve(dir, declared)
-      assert.ok(beneath(resolve(dir), path), 'Bundle patch escapes package')
-      assert.ok(beneath(await realpath(dir), await realpath(path)), 'Bundle patch resolves outside package')
-      layers.push(state.api.loadOverlayPatches('dsh', path))
+      const files = typeof declared === 'string' ? [declared] : declared
+      assert.ok(Array.isArray(files) && files.every(file => typeof file === 'string'
+        && file.length > 0 && !file.includes('\0') && !isAbsolute(file)), 'Relative Bundle patch path or list required')
+      // Keep the official file order and one PatchOptions[] per file. Its
+      // composeEntries flattens these lists once, as loadProfileDirectory does.
+      for (const path of state.api.bundlePatchPaths(dir, bundle.dsh.bundle)) {
+        assert.ok(beneath(resolve(dir), path), 'Bundle patch escapes package')
+        assert.ok(beneath(await realpath(dir), await realpath(path)), 'Bundle patch resolves outside package')
+        await regular(path) // Reject patch symlinks/special files before the Loader reads them.
+        layers.push(state.api.loadOverlayPatches('dsh', path))
+      }
     }
     for (const [path, pin] of Object.entries(current.patches)) if (pin !== null) layers.push(state.api.loadOverlayPatches('dsh', path))
     const warnings = []
@@ -197,19 +270,26 @@ export async function inspectDshInstallation(options) {
 }
 
 /** Runs only the pinned public CLI; retains partial state on failure, never rolls back. */
-export async function applyDshInstallation(plan, { adapter } = {}) {
+export async function applyDshInstallation(plan, { adapter, signal, timeoutMs = 0, logDirectory } = {}) {
   const { planSha256, ...unsigned } = plan
   assert.equal(digest(unsigned), planSha256, 'Plan or profile changed; replan before execution')
   const state = await protocol(adapter)
   const fresh = await planDshInstallation({ ...plan, adapter })
   assert.equal(fresh.planSha256, plan.planSha256, 'Plan or profile changed; replan before execution')
-  let exitCode = 0, executionError = null
+  if (logDirectory !== undefined) {
+    await safeDirectory(logDirectory)
+    for (const root of [state.dshHome, ...Object.values(state.pins).map(pin => dirname(pin.path))])
+      assert.ok(!beneath(root, logDirectory) && !beneath(logDirectory, root), 'Command logs overlap host inputs')
+    if (process.platform === 'win32') await assertWindowsPrivate(logDirectory, { directory: true })
+  }
+  let exitCode = 0, executionError = null, execution = { state: 'not-needed', retrySafe: false }, diagnosticError = null
   if (fresh.action !== 'already-registered') {
-    try {
-      const result = await state.run(fresh.command, fresh.args, { cwd: fresh.before.dir,
-        env: { ...process.env, DSH_HOME: state.dshHome, ...(state.pins.desktopHostManifest ? { ELECTRON_RUN_AS_NODE: '1' } : {}) }, shell: false, timeout: 120000, maxBuffer: 1024 * 1024 })
-      exitCode = result.exitCode ?? result.status ?? 0
-    } catch (error) { exitCode = Number.isInteger(error.code) ? error.code : 1; executionError = String(error.code ?? error.name) }
+    const command = await executeDshInstall(fresh.command, fresh.args, { cwd: fresh.before.dir,
+      env: { ...process.env, DSH_HOME: state.dshHome, ...(state.pins.desktopHostManifest ? { ELECTRON_RUN_AS_NODE: '1' } : {}) } },
+    { run: state.run, signal, timeoutMs })
+    ;({ exitCode, executionError, execution } = command)
+    try { await retainCommandOutput(logDirectory, command) }
+    catch (error) { diagnosticError = String(error.code ?? error.name) }
   }
   let readback = null, readbackError = null, userConfigurationPreserved = false
   try {
@@ -217,9 +297,10 @@ export async function applyDshInstallation(plan, { adapter } = {}) {
     userConfigurationPreserved = readback.foreignSha256 === plan.before.foreignSha256
       && digest(readback.patches) === digest(plan.before.patches) && digest(readback.configPins) === digest(plan.before.configPins)
   } catch (error) { readbackError = error.message }
-  const succeeded = exitCode === 0 && userConfigurationPreserved && readback?.configurationParsed === true
+  const succeeded = exitCode === 0 && diagnosticError === null && userConfigurationPreserved && readback?.configurationParsed === true
   return { scope: adapter.scope, status: succeeded ? 'registered-config-parsed' : 'failed-partial-state-retained',
-    exitCode, executionError, readbackError, readback, userConfigurationPreserved,
+    exitCode, executionError, execution, diagnosticError, readbackError, readback, userConfigurationPreserved,
+    userConfigurationStatus: readback === null ? 'unverified' : userConfigurationPreserved ? 'observed-matching' : 'changed',
     rollbackAttempted: false, partialStateRetained: !succeeded,
     runtimeMounted: false, bundleCycleVerified: false, releaseValidated: false }
 }

package/bin/npm-runtime-check.mjs

@@ -57,6 +57,46 @@ async function packageRoot(name,roots) {
   }
   throw Object.assign(Error(`Missing installed dependency: ${name}`),{code:'ENOENT'})
 }
+const GIT_CHECKS=['init','publish','history','diff','read','agent-read-arguments','project-pin','read-no-publication']
+async function describeGit(root,observation,pins) {
+  const manifest=JSON.parse(await readFile(join(root,'package.json'),'utf8'))
+  const declared=manifest['x-design-release-review']?.nativeGit
+  if(declared===undefined)return {required:false,status:'not-declared'}
+  assert.equal(declared,'shared-core-library','Unknown installed Git runtime declaration')
+  const shared=join(root,'payload/shared'),nativeRoot=join(shared,'git-native'),byPath=new Map(pins.map(pin=>[pin.path,pin]))
+  const pin=path=>{const value=byPath.get(path);assert.ok(value,'Missing installed Git asset: '+path);return value}
+  const recipe=JSON.parse(await readFile(pin(join(nativeRoot,'runtime-manifest.json')).path,'utf8'))
+  const source=JSON.parse(await readFile(pin(join(nativeRoot,'SOURCE.json')).path,'utf8'))
+  assert.equal(recipe.schemaVersion,1);assert.equal(pin(join(nativeRoot,'SOURCE.json')).sha256,recipe.sourceSha256)
+  const pathFor=path=>{assert.ok(typeof path==='string'&&path&&!path.includes('\\')&&!path.split('/').some(p=>!p||p==='.'||p==='..'),'Unsafe Git manifest path');const target=resolve(nativeRoot,path);assert.ok(inside(nativeRoot,target)&&target!==nativeRoot);return target}
+  for(const [path,identity] of Object.entries(recipe.files))assert.equal(pin(pathFor(path)).sha256,identity.sha256,'Installed Git material changed')
+  for(const input of [...source.inputs,...source.artifacts])assert.equal(pin(pathFor(input.path)).sha256,input.sha256,'Installed Git source/prebuild changed')
+  assert.deepEqual(source.artifacts.map(x=>x.path).sort(),['native/yugoo_git.linux-x64.node','native/yugoo_git.win32-x64.node'])
+  assert.ok(['linux','win32'].includes(observation.platform)&&observation.arch==='x64'&&(observation.platform!=='linux'||observation.libc==='glibc'),'Unsupported installed Git platform')
+  const descriptor={required:true,status:'present',backend:'native',
+    worker:pin(join(shared,'scripts/git-native-worker.js')),probe:pin(join(shared,'scripts/git-runtime-check.mjs')),
+    loader:pin(join(nativeRoot,'index.cjs')),materials:pin(join(nativeRoot,'runtime-manifest.json')),
+    native:pin(join(nativeRoot,`native/yugoo_git.${observation.platform}-${observation.arch}.node`))}
+  return {...descriptor,identitySha256:digest(descriptor)}
+}
+/** New packages require Git independently of the optional embedding runtime. */
+export function assertGitRuntimeReceipt(receipt,current) {
+  const expected=current.gitPrerequisites
+  if(!expected?.required)return
+  assert.equal(receipt.scope,'installed-runtime-readonly','Required Git check needs an actual installed-runtime receipt')
+  assert.deepEqual(receipt.gitPrerequisites,expected,'Git static prerequisites mismatch')
+  assert.equal(expected.status,'present','Required Git assets are not present')
+  assert.equal(receipt.git?.required,true,'Required Git receipt missing')
+  assert.equal(receipt.git.status,'passed','Required library Git check did not pass')
+  assert.equal(receipt.git.identitySha256,expected.identitySha256,'Git runtime descriptor drift')
+  for(const key of ['backend','worker','probe','loader','materials','native'])assert.deepEqual(receipt.git[key],expected[key],'Git runtime '+key+' mismatch')
+  const load=receipt.git.load
+  assert.equal(load?.status,'passed');assert.equal(load.code,0);assert.equal(load.signal,null)
+  assert.ok(Number.isInteger(load.childPid)&&load.childPid>0,'Git check child PID missing')
+  assert.equal(load.childAbsent,true,'Git check child exit was not verified')
+  for(const key of ['execPath','node','platform','arch'])assert.equal(load.observation?.[key],current.observation[key],'Git check '+key+' mismatch')
+  assert.equal(load.externalGitCalls,0);assert.deepEqual(load.checks,GIT_CHECKS)
+}
 export async function inspectRuntime({npmRoot,disableEmbedding=false,host}={}) {
   assert.equal(typeof disableEmbedding,'boolean')
   const root=resolve(npmRoot)
@@ -69,10 +109,12 @@ export async function inspectRuntime({npmRoot,disableEmbedding=false,host}={}) {
     semanticKagVerified:false,graVerified:false,licenseObligationsAccepted:false}
   const finalize=()=>{
     result.pins.sort((a,b)=>a.path.localeCompare(b.path))
-    result.identitySha256=digest({npmRoot:root,observation,embedding:result.embedding,pins:result.pins})
+    result.identitySha256=digest({npmRoot:root,observation,embedding:result.embedding,gitPrerequisites:result.gitPrerequisites,pins:result.pins})
     return result
   }
   if(host==='dsh'){result.status='not-applicable';result.reason='DSH package route is not a Companion runtime';return finalize()}
+  try {result.gitPrerequisites=await describeGit(root,observation,result.pins)}
+  catch(e) {result.gitPrerequisites={required:true,status:'failed',reason:e.message};result.status='failed';result.reason=e.message;return finalize()}
   if(disableEmbedding){result.status='disabled';return finalize()}
   try {
     const runtime=join(root,'payload/shared/knowledge/runtime.mjs')
@@ -120,6 +162,38 @@ export async function checkRuntime(options) {
   if(before.sharp)assert.ok(!inside(before.sharp.root,directory),'Receipt directory overlaps sharp')
   await assertRuntimePath(directory)
   const receipt={...before,load:{status:'not-run'},releaseValidated:false,scope:run?'isolated-test-contract':'installed-runtime-readonly'}
+  receipt.git=before.gitPrerequisites??{required:false,status:'not-declared'}
+  if(before.gitPrerequisites?.required) {
+    let childPid=null,diagnostic
+    try {
+      assert.equal(before.gitPrerequisites.status,'present','Required installed Git assets are missing or changed')
+      const entry=before.gitPrerequisites.probe.path
+      await mkdir(directory,{recursive:true})
+      diagnostic=await mkdtemp(join(directory,'library-git-'))
+      for(const name of ['home','tmp','cache'])await mkdir(join(diagnostic,name))
+      const env={PATH:'',HOME:join(diagnostic,'home'),USERPROFILE:join(diagnostic,'home'),TMPDIR:join(diagnostic,'tmp'),TMP:join(diagnostic,'tmp'),TEMP:join(diagnostic,'tmp'),XDG_CACHE_HOME:join(diagnostic,'cache')}
+      if(process.platform==='win32'&&process.env.SystemRoot)env.SystemRoot=process.env.SystemRoot
+      const pending=execute(before.observation.execPath,[entry],{cwd:diagnostic,env,timeout:30000,killSignal:'SIGKILL',maxBuffer:1024*1024,encoding:'utf8'})
+      childPid=pending.child?.pid??null
+      const output=await pending
+      const value=JSON.parse(output.stdout)
+      assert.equal(value.status,'passed');assert.equal(value.backend,'native');assert.equal(value.externalGitCalls,0)
+      assert.deepEqual(value.checks,GIT_CHECKS)
+      assert.ok(Number.isInteger(childPid)&&childPid>0,'Git diagnostic child PID missing')
+      let childAbsent=false
+      try {process.kill(childPid,0)} catch(e) {childAbsent=e.code==='ESRCH'}
+      assert.equal(childAbsent,true,'Git check child is still present')
+      const after=await inspectRuntime(options)
+      assert.equal(after.identitySha256,before.identitySha256,'Runtime prerequisites changed during Git check')
+      receipt.git={...before.gitPrerequisites,status:'passed',load:{...value,code:0,signal:null,childPid,childAbsent,diagnosticDirectory:diagnostic,stderr:output.stderr}}
+      assertGitRuntimeReceipt(receipt,before)
+    } catch(e) {
+      let childAbsent=null
+      if(childPid) {try {process.kill(childPid,0);childAbsent=false} catch(error) {childAbsent=error.code==='ESRCH'}}
+      receipt.git={...before.gitPrerequisites,status:'failed',reason:e.message,load:{status:'failed',code:e.code??null,signal:e.signal??null,killed:e.killed??false,childPid,childAbsent,diagnosticDirectory:diagnostic,stderr:String(e.stderr??'').slice(0,16384)}}
+      receipt.status='failed';return receipt
+    }
+  }
   if(before.status!=='present')return receipt
   await mkdir(directory,{recursive:true})
   const diagnostic=await mkdtemp(join(directory,'native-load-'))