dsh-gitbash-shell 0.39.4 → 0.40.1

package/src/inline-tools.js

@@ -101,14 +101,14 @@ export function inlineNeeds(names, { pwshVisible } = {}) {
  * routing. Both hold regardless of the path dialect a delegate sees.
  */
 export const GITBASH_ROUTE_ADDENDUM = [
-  'Prefer this bash tool for ALL commands; use the pwsh tool ONLY when a Windows-native capability (cmdlets, registry, services, WMI) is truly required.',
-  'Fix failed bash commands in bash — never switch shells mid-task, never embed `pwsh -Command` inside a bash command (variable expansion and output encoding break there).',
+  'Prefer this bash tool for shell syntax, scripts, pipelines, redirection, globbing and POSIX utilities; use the pwsh tool ONLY when PowerShell cmdlets, registry, services or WMI are truly required.',
+  'Fix failed bash syntax in bash; never embed `pwsh -Command` inside a bash command as a workaround (variable expansion and output encoding break there). Choose a separately offered native route for its documented purpose before execution, never as a policy-denial retry.',
 ].join('\n')
 
 /** The bash-only routing variant, used while the pwsh switch is off (the default). */
 export const GITBASH_ROUTE_ADDENDUM_NO_PWSH = [
-  'Prefer this bash tool for ALL commands — it is this host\'s shell.',
-  'Fix failed commands in bash; there is no PowerShell tool on this host.',
+  'Prefer this bash tool for shell syntax, scripts, pipelines, redirection, globbing and POSIX utilities — it is this host\'s shell.',
+  'Fix failed bash syntax in bash; no PowerShell tool is offered here. Do not invent a hidden tool or embed another interpreter as a workaround.',
 ].join('\n')
 
 /**
@@ -118,6 +118,38 @@ export const GITBASH_ROUTE_ADDENDUM_NO_PWSH = [
  */
 export const GITBASH_MSYS_ADDENDUM = 'This bash is Git for Windows (MSYS): paths use drive roots (/c/Users/...), and ~, /tmp, /dev/null and /usr/... resolve exactly as Git Bash resolves them.'
 
+const ROUTING_START = '\n[gitbash tool routing]\n'
+const ROUTING_END = '\n[/gitbash tool routing]'
+const ROUTING_SAFETY = 'Choose the execution route before running. A policy/access denial is a stop condition: never switch tools, shells or permissions to bypass it. A decoding/display failure does not mean the command failed to run; preserve its exit facts and never blindly repeat a side-effecting command. Do not guess unknown or mixed encodings.'
+const PTC_ROUTING = 'Inside run_code, call only bindings actually offered by the current SDK with await tools.<name>(...). Select by their descriptions: shell execution for shell syntax/pipelines; an offered typed native-executable binding for exact Windows argv or explicitly known per-stream encodings; an offered complete-path conversion binding before passing an MSYS value to Node fs/path. These are different operations, not substitutes for permissions. Never pass routes, search text or source code to a path converter. Program strings do not perform shell expansion. If a needed binding is absent, report the missing capability; do not invent its name. ' + ROUTING_SAFETY
+
+/** Model guidance names only tools in this assembly, not a switch's intent. */
+export function toolRoutingHintFor(tools, { pwshVisible = false } = {}) {
+  const names = new Set((Array.isArray(tools) ? tools : []).map(tool => tool?.name))
+  if (!names.has('bash')) return ''
+  const lines = [pwshVisible && names.has('pwsh') ? GITBASH_ROUTE_ADDENDUM : GITBASH_ROUTE_ADDENDUM_NO_PWSH]
+  if (names.has('gitbash_native')) lines.push('Use gitbash_native before execution when a Windows .exe needs exact literal argv such as /all or /c without MSYS conversion, or independently declared stdout/stderr encodings. Supply an absolute executable, mark each argument literal or path, and select only a known encoding (raw for unknown/mixed bytes). It does not implement shell pipelines, expansion or .cmd/.bat wrappers; only resolved danger-full-access can execute it.')
+  if (names.has('gitbash_to_native_path')) lines.push('Use gitbash_to_native_path only for a complete caller-declared MSYS filesystem path that a native Node fs/path API needs, especially a runtime-built value. Read native_path from the result. Never convert routes, search strings or shell/program source. Already-native or cwd-relative Node paths need no conversion; ordinary tool path fields already use their own translation. Conversion grants no access.')
+  lines.push(ROUTING_SAFETY)
+  return lines.join('\n')
+}
+
+/** Add a replaceable, idempotent block; a reused assembly follows visibility. */
+export function applyToolRouting(tools, { pwshVisible = false, msys = false } = {}) {
+  if (!Array.isArray(tools)) return
+  for (const tool of tools) {
+    if (!tool || typeof tool.description !== 'string' || !['bash', 'run_code'].includes(tool.name)) continue
+    let description = tool.description
+    const start = description.indexOf(ROUTING_START)
+    const end = start < 0 ? -1 : description.indexOf(ROUTING_END, start)
+    if (end >= 0) description = description.slice(0, start) + description.slice(end + ROUTING_END.length)
+    const hint = tool.name === 'bash'
+      ? toolRoutingHintFor(tools, { pwshVisible }) + (msys ? '\n' + GITBASH_MSYS_ADDENDUM : '')
+      : PTC_ROUTING
+    tool.description = description + ROUTING_START + hint + ROUTING_END
+  }
+}
+
 /** @deprecated composed form kept for tests: route + MSYS sentences. */
 export const GITBASH_BASH_ADDENDUM = GITBASH_ROUTE_ADDENDUM + '\n' + GITBASH_MSYS_ADDENDUM
 
@@ -158,7 +190,12 @@ export async function mountPrivateExecutor(ctx, GitBashSandboxExecutor, createSc
         if (executorScope.fiber) await executorScope.fiber
         const fiber = executorScope.ctx.plugin(GitBashSandboxExecutor)
         await fiber
-        return executorScope.ctx.get('shell')
+        const executor = executorScope.ctx.get('shell')
+        const sandboxModule = await resolveHostModule(executorScope.ctx, '@deepseek-ai/dsh-sandbox')
+        if (typeof sandboxModule?.SandboxUnavailableError === 'function') {
+          executor.unavailableErrorType = sandboxModule.SandboxUnavailableError
+        }
+        return executor
       })(),
       mountTimeout,
     ])
@@ -198,6 +235,7 @@ export function mountInlineTools(ctx, deps) {
   let closed = false
   const isLive = (agent, state) => !closed && tracked.get(agent) === state && !state.controller.signal.aborted
   const newState = () => ({ timer: undefined, scope: undefined, denyPwsh: undefined, pending: undefined, controller: new AbortController() })
+  const experimentalEnabled = () => deps.experimentalEnabled?.() !== false
   // Loader imports cannot be cancelled, but no continuation may outlive its
   // owner. Join our cancelled continuations without waiting on a stuck loader.
   const untilDisposed = async (promise, signal) => {
@@ -247,6 +285,7 @@ export function mountInlineTools(ctx, deps) {
         if (typeof createScope !== 'function') throw new Error('no createScope seam')
         controller.signal.throwIfAborted()
         const mounted = await mountPrivateExecutor(ctx, GitBashSandboxExecutor, createScope)
+        mounted.executor.experimentalEnabled = experimentalEnabled
         executorScope = mounted.executorScope
         controller.signal.throwIfAborted()
         const hostModules = {}
@@ -255,7 +294,33 @@ export function mountInlineTools(ctx, deps) {
         }
         const { createBashToolModule } = await untilDisposed(import('./bash-tool.js'), controller.signal)
         const module = createBashToolModule({ executor: mounted.executor, log, ...hostModules })
-        return { executor: mounted.executor, executorScope, module }
+        const extraModules = []
+        if (typeof deps.translatePath === 'function') {
+          const { createPathToolModule, PATH_TOOL_NAME } = await untilDisposed(import('./path-tool.js'), controller.signal)
+          extraModules.push({ name: PATH_TOOL_NAME, create: scope => createPathToolModule({
+            toolsModule: hostModules.toolsModule, translate: deps.translatePath, experimentalEnabled, log, scope,
+          }) })
+          try {
+            const localBashModule = await untilDisposed(resolveHostModule(ctx, '@deepseek-ai/dsh-bash-local'), controller.signal)
+            const outputModule = await untilDisposed(resolveHostModule(ctx, '@deepseek-ai/dsh-subprocess-local/output'), controller.signal)
+            if (typeof localBashModule?.LocalBashExecutor !== 'function'
+              || typeof outputModule?.OutputCollector !== 'function') {
+              throw new Error('public native executor/OutputCollector capability unavailable')
+            }
+            const { createNativeOutputAdapter } = await untilDisposed(import('./native-output.js'), controller.signal)
+            const { createNativeToolModule } = await untilDisposed(import('./native-tool.js'), controller.signal)
+            extraModules.push({ name: 'gitbash_native', create: scope => createNativeToolModule({
+              toolsModule: hostModules.toolsModule, sandboxModule: hostModules.sandboxModule,
+              localBashModule, createScope, translateMsysPath: deps.translatePath,
+              createNativeOutputAdapter, outputOptions: { OutputCollector: outputModule?.OutputCollector },
+              createArtifactDirectory: deps.createArtifactDirectory, experimentalEnabled, log, scope,
+            }) })
+          } catch (error) {
+            if (controller.signal.aborted) throw error
+            log(`native tool capability unavailable; bash/path tools remain available: ${error?.message ?? error}`)
+          }
+        }
+        return { executor: mounted.executor, executorScope, module, extraModules }
       } catch (error) {
         if (executorScope) await executorScope.dispose()
         throw error
@@ -271,7 +336,7 @@ export function mountInlineTools(ctx, deps) {
     let scope
     let retained = false
     try {
-      const { executor, module } = await untilDisposed(bashOncePromise(), state.controller.signal)
+      const { executor, module, extraModules } = await untilDisposed(bashOncePromise(), state.controller.signal)
       if (!isLive(agent, state)) return
       log(`own bash tool ready (private Git Bash executor at ${executor.bashPath || '(unresolved)'}; official pwsh executor untouched)`)
       scope = createScope(agent.ctx)
@@ -297,6 +362,28 @@ export function mountInlineTools(ctx, deps) {
       if (registeredNames.includes('bash') === false) {
         throw new Error('bash tool did not register for this agent (module fiber INACTIVE — this host lacks an injected service the module requires — or the tools read-back is unavailable); bash is NOT available in this session, please report this with your dsh version (issue #27)')
       }
+      for (const extra of extraModules ?? []) {
+        let extraFiber
+        try {
+          let applied = false
+          const module = extra.create(agent)
+          extraFiber = scope.ctx.plugin({ ...module, async apply(extraCtx, config) {
+            await module.apply(extraCtx, config)
+            applied = true
+          } })
+          await untilDisposed(extraFiber, state.controller.signal)
+          if (!isLive(agent, state)) return
+          if (!applied) {
+            throw new Error(`${extra.name} scope inactive (a required service may be missing)`)
+          }
+          // Registration/stand-down is reported by the shared live registrar.
+          log(`${extra.name} scope ready; registration follows experimentalNative and existing owners`)
+        } catch (error) {
+          if (!isLive(agent, state)) return
+          await extraFiber?.dispose()
+          log(`${extra.name} activation failed; bash remains available: ${error?.message ?? error}`)
+        }
+      }
       retained = true
       log('own bash tool activated for this agent (Git Bash execution; official pwsh tool real but hidden by default)')
     } catch (error) {
@@ -403,7 +490,7 @@ export function mountInlineTools(ctx, deps) {
       log(`agent bash tool cleanup failed: ${error?.message ?? error}`)
     }))
     ctx.on('loader/volatile-update', (paths) => {
-      if (!Array.isArray(paths) || !paths.some((path) => Array.isArray(path) && path[0] === 'pwshTool')) return
+      if (!Array.isArray(paths) || !paths.some((path) => Array.isArray(path) && ['pwshTool', 'experimentalNative'].includes(path[0]))) return
       for (const agent of tracked.keys()) {
         try { reconcile(agent) } catch (error) { log(`pwsh switch update failed: ${error?.message ?? error}`) }
       }

package/src/native-executor.js

@@ -0,0 +1,283 @@
+import path from 'node:path'
+import { resolveSessionCwd } from './session-workdir.js'
+
+// No host peer imports here: the owner supplies modules via its host loader.
+const KEYS = new Set(['description', 'executable', 'argv', 'cwd', 'timeoutMs', 'run_in_background', 'entrypoint', 'stdoutEncoding', 'stderrEncoding', 'errors'])
+const ENCODINGS = new Set(['utf8', 'gbk', 'utf16le', 'raw'])
+// A usability guard for known names, NOT executable attestation or a sandbox:
+// a renamed/custom .exe may implement its own language. Direct argv is not a
+// promise about arbitrary Windows parsers, even after explicit opt-in.
+const INTERPRETERS = /^(?:cmd|powershell|pwsh|bash|sh|dash|zsh|fish|wsl|wscript|cscript|mshta|node|nodejs|pythonw?(?:\d+(?:\.\d+)*)?|pypy(?:\d+)?|py|perl|ruby|php|lua|javaw?|jshell|dotnet|csi|tclsh|wish|rscript|busybox|deno|bun)(?:\.exe)?$/i
+export const NATIVE_TIMEOUT_MS = 120000
+export const NATIVE_MAX_TIMEOUT_MS = 600000
+
+function object(value, label, allowed) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${label}: expected an object`)
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw new TypeError(`${label}: unsupported field ${key}`)
+}
+function string(value, label, empty = false) {
+  if (typeof value !== 'string' || (!empty && value.trim() === '') || value.includes('\0')) throw new TypeError(`${label}: expected ${empty ? 'a' : 'a non-empty'} NUL-free string`)
+  return value
+}
+
+/** Only explicitly typed paths cross the existing mount translator. No argv guessing. */
+export function nativePath(input, translateMsysPath, platform = process.platform, label = 'path') {
+  object(input, label, new Set(['kind', 'value']))
+  if (input.kind !== 'path') throw new TypeError(`${label}: kind must be path`)
+  const value = string(input.value, label)
+  if (/^[~$]|%[^%]+%/.test(value)) throw new TypeError(`${label}: variable and home expansion are not supported; use an absolute path`)
+  if (platform !== 'win32') throw new Error('gitbash_native currently supports only the Windows local execution world')
+  // A rooted Windows path without a drive is not absolute in this contract.
+  const absolute = v => /^[a-z]:[\\/]/i.test(v) || /^\\\\[^\\]+\\[^\\]+/.test(v) || /^\/\/[^/]+\/[^/]+/.test(v)
+  const translated = absolute(value) ? value : typeof translateMsysPath === 'function' ? translateMsysPath(value) : value
+  if (typeof translated !== 'string' || translated.includes('\0') || !absolute(translated)) throw new TypeError(`${label}: unresolved or non-absolute typed path`)
+  return path.win32.normalize(translated)
+}
+
+/** Strict request validation is also applied outside ToolRuntime. */
+export function parseNativeRequest(args, { translateMsysPath, platform = process.platform, sessionCwd } = {}) {
+  object(args, 'gitbash_native', KEYS)
+  const description = string(args.description, 'description')
+  const executable = nativePath(args.executable, translateMsysPath, platform, 'executable')
+  if (!/\.exe$/i.test(executable)) throw new TypeError('executable: only native .exe files are supported; .cmd/.bat and script files are never wrapped')
+  const entrypoint = args.entrypoint ?? 'native'
+  if (!['native', 'interpreter'].includes(entrypoint)) throw new TypeError('entrypoint: expected native or interpreter')
+  if (INTERPRETERS.test(path.win32.basename(executable)) && entrypoint !== 'interpreter') throw new TypeError('executable: a known interpreter requires explicit entrypoint: interpreter; its language and quoting remain your responsibility')
+  if (!Array.isArray(args.argv) || args.argv.length > 4096) throw new TypeError('argv: expected an array of at most 4096 typed arguments')
+  const argv = args.argv.map((arg, index) => {
+    object(arg, `argv[${index}]`, new Set(['kind', 'value']))
+    if (arg.kind === 'literal') return string(arg.value, `argv[${index}].value`, true)
+    if (arg.kind === 'path') return nativePath(arg, translateMsysPath, platform, `argv[${index}]`)
+    throw new TypeError(`argv[${index}]: kind must be literal or path`)
+  })
+  // Conservative bound before the provider's Windows command-line serialization.
+  if ([executable, ...argv].reduce((n, arg) => n + arg.length * 2 + 3, 0) > 30000) throw new TypeError('argv: conservative Windows command-line size limit exceeded')
+  const cwd = nativePath(args.cwd ?? { kind: 'path', value: sessionCwd }, translateMsysPath, platform, 'cwd')
+  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new TypeError('timeoutMs: expected a positive finite number')
+  if (args.run_in_background !== undefined && typeof args.run_in_background !== 'boolean') throw new TypeError('run_in_background: expected boolean')
+  if (args.run_in_background === true && args.timeoutMs !== undefined) throw new TypeError('timeoutMs is not supported with run_in_background; managed jobs have no tool deadline')
+  const stdoutEncoding = args.stdoutEncoding ?? 'utf8'
+  const stderrEncoding = args.stderrEncoding ?? 'utf8'
+  const errors = args.errors ?? 'replace'
+  if (!ENCODINGS.has(stdoutEncoding) || !ENCODINGS.has(stderrEncoding)) throw new TypeError('encoding: expected utf8, gbk, utf16le or raw; auto is not supported')
+  if (!['replace', 'strict'].includes(errors)) throw new TypeError('errors: expected replace or strict')
+  return Object.freeze({ description, executable, argv: Object.freeze(argv), cwd, entrypoint,
+    timeoutMs: Math.min(args.timeoutMs ?? NATIVE_TIMEOUT_MS, NATIVE_MAX_TIMEOUT_MS),
+    run_in_background: args.run_in_background === true,
+    output: Object.freeze({ stdoutEncoding, stderrEncoding, errors }),
+  })
+}
+
+/** Resolve the *call's* standing policy, never the composition default. */
+export function requireNativePolicy(ctx, exec, sandboxModule) {
+  const service = ctx.get('sandboxPolicy')
+  const policy = service?.resolve(exec?.agent === undefined ? {} : { session: exec.agent.session })
+  if (!policy || policy.mode !== 'danger-full-access') {
+    const detail = 'gitbash_native has no confined backend adapter. This entry refuses read-only, workspace-write and missing policy before spawn or artifact creation; do not bypass a denied operation. The user can select danger-full-access in the session access-mode control, or turn off Experimental native execution / fail-closed (experimentalNative) in Settings > Plugins > dsh-gitbash-shell to disable native/path tools and restore explicitly UNCONFINED legacy Bash.'
+    if (typeof sandboxModule?.SandboxUnavailableError === 'function') throw new sandboxModule.SandboxUnavailableError(policy?.mode ?? 'unknown', detail)
+    throw Object.assign(new Error(detail), { code: 'SANDBOX_UNAVAILABLE' })
+  }
+  return policy
+}
+
+function checkedDshEnv(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('shellEnv.collect must return managed environment facts')
+  const seen = new Set()
+  const result = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (!/^DSH_/i.test(key) || key.includes('=') || key.includes('\0') || seen.has(key.toUpperCase())) throw new TypeError('shellEnv: invalid or conflicting managed environment key')
+    result[key] = string(entry, 'shellEnv managed fact', true)
+    seen.add(key.toUpperCase())
+  }
+  return Object.freeze(result)
+}
+
+function preparationTimeout() {
+  return Object.assign(new Error('gitbash_native preparation timed out before spawn; no native producer was started'), { code: 'NATIVE_PREPARATION_TIMEOUT' })
+}
+function cancellation(parent, timeoutMs) {
+  const controller = new AbortController()
+  const forward = () => controller.abort(parent.reason)
+  parent?.addEventListener('abort', forward, { once: true })
+  if (parent?.aborted) forward()
+  let timer
+  if (timeoutMs <= 0) controller.abort(preparationTimeout())
+  else timer = setTimeout(() => controller.abort(preparationTimeout()), timeoutMs)
+  return { controller, signal: controller.signal,
+    stopDeadline() { clearTimeout(timer) },
+    dispose() { clearTimeout(timer); parent?.removeEventListener('abort', forward) },
+  }
+}
+async function whileActive(work, signal) {
+  signal.throwIfAborted()
+  let abort
+  const interrupted = new Promise((_, reject) => {
+    abort = () => reject(signal.reason)
+    signal.addEventListener('abort', abort, { once: true })
+  })
+  try { return await Promise.race([Promise.resolve().then(() => { signal.throwIfAborted(); return work() }), interrupted]) }
+  finally { signal.removeEventListener('abort', abort) }
+}
+
+/**
+ * Per-operation private Core executor. Only this operation's scope and handle are
+ * owned here. In particular, disposing it never disposes the root subprocess.
+ * Prepared requests are private capabilities, not caller-supplied policy DTOs.
+ */
+export function createNativeExecutor(ctx, deps) {
+  const { localBashModule, sandboxModule, createScope, translateMsysPath, createNativeOutputAdapter, outputOptions = {} } = deps
+  const LocalBashExecutor = localBashModule?.LocalBashExecutor
+  if (typeof LocalBashExecutor !== 'function' || typeof createScope !== 'function' || typeof createNativeOutputAdapter !== 'function') throw new Error('gitbash_native: required host executor/output/scope capability is unavailable')
+  const prepared = new WeakMap()
+  const requireEnabled = () => {
+    if (deps.experimentalEnabled?.() === false) throw new Error('gitbash_native is disabled by experimentalNative. Enable Experimental native execution / fail-closed in Settings > Plugins > dsh-gitbash-shell.')
+  }
+  const remaining = request => request.timeoutMs - (Date.now() - prepared.get(request))
+  return {
+    waitBudget: request => Math.max(1, remaining(request)),
+    async prepare(args, exec) {
+      requireEnabled()
+      const policy = requireNativePolicy(ctx, exec, sandboxModule)
+      exec.signal?.throwIfAborted()
+      if (args?.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) throw new TypeError('timeoutMs: expected a positive finite number')
+      const startedAt = Date.now()
+      const timeoutMs = Math.min(args?.timeoutMs ?? NATIVE_TIMEOUT_MS, NATIVE_MAX_TIMEOUT_MS)
+      const preparation = cancellation(exec.signal, timeoutMs)
+      try {
+        const sessionCwd = await whileActive(() => resolveSessionCwd(ctx, { ...exec, signal: preparation.signal }, policy), preparation.signal)
+        requireEnabled()
+        preparation.signal.throwIfAborted()
+        const request = parseNativeRequest(args, { translateMsysPath, sessionCwd, platform: deps.platform ?? process.platform })
+        const value = Object.freeze({ ...request, dshEnv: checkedDshEnv(ctx.shellEnv.collect(exec)) })
+        prepared.set(value, startedAt)
+        return value
+      } finally { preparation.dispose() }
+    },
+    async execute(request, exec, { signal = exec.signal, onExpiry = 'kill' } = {}) {
+      requireEnabled()
+      const policy = requireNativePolicy(ctx, exec, sandboxModule)
+      if (!prepared.has(request)) throw new TypeError('gitbash_native: request must be prepared by this executor')
+      if (!['kill', 'none'].includes(onExpiry)) throw new TypeError('invalid native expiry mode')
+      signal?.throwIfAborted()
+      const provider = ctx.get('subprocess')
+      if (typeof provider?.spawn !== 'function') throw new Error('gitbash_native: subprocess provider unavailable')
+      // Jobs registrations survive the tool fiber. Their operation scopes belong
+      // directly to the agent, not to a disposable tool registration fiber.
+      const owner = exec.agent?.ctx ?? ctx
+      const operation = cancellation(signal, remaining(request))
+      let scope
+      let handle
+      let scopeDisposed = false
+      let producerSettled = false
+      let proc
+      let resultPromise
+      const cancel = reason => {
+        if (producerSettled || operation.signal.aborted) return false
+        operation.controller.abort(Object.assign(new Error(reason), { code: 'NATIVE_OPERATION_CANCELLED' }))
+        return true
+      }
+      // OutputCollector DTOs may contain optional undefined fields. ToolRuntime
+      // requires lossless JSON, so project the adapter's facts at this boundary.
+      // Even a facts projection problem must not erase a producer's real exit.
+      const outputFacts = () => {
+        try { return JSON.parse(JSON.stringify(handle?.outputFacts?.() ?? { unavailable: true })) }
+        catch (error) { return { projectionError: String(error?.message ?? error), reliableText: false } }
+      }
+      const release = async () => {
+        if (scopeDisposed) return
+        scopeDisposed = true
+        try { await scope?.dispose() } finally { operation.dispose() }
+      }
+      try {
+        operation.signal.throwIfAborted()
+        scope = createScope(owner.isolate('shell').isolate('subprocess'))
+        if (scope.fiber) await whileActive(() => scope.fiber, operation.signal)
+        operation.signal.throwIfAborted()
+        // Install ownership cancellation before any further preparation await.
+        scope.ctx.effect(() => async () => {
+          if (!producerSettled) cancel('native execution owner disposed')
+          if (!handle) return
+          handle.terminate()
+          if (typeof handle.waitForExit === 'function') await handle.waitForExit(AbortSignal.timeout(5000))
+        })
+        requireEnabled()
+        requireNativePolicy(ctx, exec, sandboxModule)
+        const outputConfig = { ...outputOptions, ...request.output, artifactPolicyValidated: true }
+        // Capability/encoding validation is pure and precedes directory creation.
+        createNativeOutputAdapter(provider, { ...outputConfig, artifactDirectory: undefined })
+        if (outputConfig.artifactDirectory === undefined) {
+          if (typeof deps.createArtifactDirectory !== 'function') throw new Error('gitbash_native: no trusted artifact directory owner is configured')
+          requireEnabled()
+          requireNativePolicy(ctx, exec, sandboxModule)
+          operation.signal.throwIfAborted()
+          outputConfig.artifactDirectory = await whileActive(async () => {
+            const directory = await deps.createArtifactDirectory(request, { ...exec, signal: operation.signal }, operation.signal)
+            if (operation.signal.aborted) {
+              // The directory owner retains late results under its normal retention
+              // policy. Never spawn from a late callback or delete a path still
+              // potentially owned/referenced by that trusted asynchronous producer.
+              deps.log?.(`gitbash_native: cancelled preparation retained its late artifact directory under owner retention: ${String(directory)}`)
+            }
+            return directory
+          }, operation.signal)
+          if (typeof outputConfig.artifactDirectory !== 'string') throw new Error('gitbash_native: artifact directory owner did not return a path')
+        }
+        requireNativePolicy(ctx, exec, sandboxModule)
+        operation.signal.throwIfAborted()
+        requireEnabled()
+        const adapter = createNativeOutputAdapter(provider, outputConfig)
+        const facade = { spawn(spec) {
+          requireEnabled()
+          requireNativePolicy(ctx, exec, sandboxModule)
+          spec.signal?.throwIfAborted()
+          handle = adapter.spawn(spec)
+          return handle
+        } }
+        scope.ctx.provide('subprocess', facade)
+        const mounted = scope.ctx.plugin(LocalBashExecutor)
+        await whileActive(() => mounted, operation.signal)
+        requireEnabled()
+        operation.signal.throwIfAborted()
+        const executor = scope.ctx.get('shell')
+        if (typeof executor?.executeArgv !== 'function') throw new Error('gitbash_native: host executeArgv contract is unavailable')
+        const budget = remaining(request)
+        if (budget <= 0) throw preparationTimeout()
+        const spec = executor.resolve({ command: request.description, workdir: request.cwd, timeoutMs: onExpiry === 'kill' ? budget : request.timeoutMs,
+          signal: operation.signal, onExpiry, dshEnv: request.dshEnv, sandboxPolicy: policy })
+        // Core owns runtime kill deadlines. For Jobs, onExpiry:none keeps running
+        // after the bounded preparation phase and the caller's promotion deadline.
+        operation.stopDeadline()
+        proc = await executor.executeArgv(spec, [request.executable, ...request.argv])
+        const originalResult = proc.result.bind(proc)
+        const originalDone = proc.done
+        // Keep the original producer exit/status even when decoding/storage fails.
+        const result = () => resultPromise ??= originalResult().then(value => ({ ...value, status: proc.status, timeoutMs: request.timeoutMs,
+          cwd: request.cwd, sandbox: { mode: policy.mode, denied: false },
+          outputFacts: outputFacts(),
+        }))
+        const finished = originalDone.then(async () => {
+          // Normal settlement must not be relabelled as an owner cancellation
+          // merely because its now-finished execution scope is being released.
+          producerSettled = true
+          try { await result() } catch { /* result() preserves provider rejection */ }
+          await release()
+        }, async error => { producerSettled = true; await release(); throw error })
+        // Ensure lifecycle cleanup is observed even before a foreground reader attaches.
+        finished.catch(() => {})
+        return { get status() { return proc.status }, get exitCode() { return proc.exitCode }, get signal() { return proc.signal },
+          observed: proc.observed, readOutput: () => proc.readOutput(), kill: () => {
+            if (proc.status !== 'running') return false
+            cancel('native execution explicitly killed')
+            return proc.kill()
+          },
+          done: finished, result: async () => { await finished; return result() },
+          outputFacts,
+          sandbox: { mode: policy.mode, denied: false },
+        }
+      } catch (error) {
+        await release()
+        throw error
+      }
+    },
+  }
+}