dsh-gitbash-shell 0.39.3 → 0.40.0

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
+      }
+    },
+  }
+}

package/src/native-output.js

@@ -0,0 +1,347 @@
+// Private, operation-local adapter over the public subprocess raw-pipe seam.
+// No peer imports: the host must inject its exported ./output OutputCollector.
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const ENCODINGS = Object.freeze({ utf8: 'utf-8', 'utf-8': 'utf-8', gbk: 'gbk', cp936: 'gbk', utf16le: 'utf-16le', 'utf-16le': 'utf-16le', raw: 'raw' });
+const freeze = value => Object.freeze(value);
+const failure = (error, code) => freeze({ code: String(error?.code ?? code), message: String(error?.message ?? error).slice(0, 400) });
+function integer(value, fallback, name, min = 0) {
+  const result = value ?? fallback;
+  if (!Number.isSafeInteger(result) || result < min) throw new TypeError(`${name} must be a safe integer >= ${min}`);
+  return result;
+}
+function encoding(value = 'utf8') {
+  const label = ENCODINGS[value];
+  if (!label) throw new TypeError(`Unsupported native output encoding: ${value}`);
+  if (label !== 'raw') {
+    // Probe both replacement and fatal support in the actual host, before spawn.
+    new TextDecoder(label, { fatal: false, ignoreBOM: true });
+    new TextDecoder(label, { fatal: true, ignoreBOM: true });
+  }
+  return label;
+}
+function isCollect(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Number.isSafeInteger(value.maxBytes) && value.maxBytes >= 0
+    && Object.keys(value).every(key => key === 'maxBytes' || key === 'spill')
+    && (value.spill === undefined || (value.spill !== null && typeof value.spill === 'object'
+      && Number.isSafeInteger(value.spill.maxBytes) && value.spill.maxBytes >= 0
+      && Object.keys(value.spill).every(key => key === 'maxBytes')));
+}
+function alignedStart(bytes, start) {
+  while (start < bytes.length && (bytes[start] & 0xc0) === 0x80) start++;
+  return start;
+}
+function alignedEnd(bytes, end) {
+  if (end === bytes.length) return end;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+  return end;
+}
+
+/**
+ * Construct one immutable operation's provider facade. Create another facade for
+ * a different encoding/configuration; no ambient per-agent or global settings.
+ *
+ * Only known {maxBytes, spill?} stdout/stderr modes opt in. Pipe, inherit and
+ * future/unknown modes are delegated unchanged. The real provider still owns
+ * execution, abort, termination, range observation, stdin and control.
+ *
+ * artifactDirectory must ALREADY exist and be owned/authorized by the caller.
+ * artifactPolicyValidated is only a misuse guard, NOT a sandbox grant: the
+ * native executor must enforce its actual resolved danger-only policy first.
+ * This adapter never creates directories, chmods, removes files or grants access.
+ * The caller owns artifact retention/removal after all readers have finished.
+ *
+ * maxTotalBytes bounds adapter-owned byte payload reservations + artifact bytes,
+ * not provider/Node pipe buffers, JS object overhead or copies retained by callers.
+ * Memory reservation includes tail backing buffers, snapshot/string copies and
+ * bounded decode scratch (conservative multipliers). No raw in-memory history.
+ * Artifact quotas are SHARED by both streams and by raw + normalized UTF8 files.
+ * Readers use normalized UTF8 byte offsets, never raw/source-byte offsets.
+ */
+export function createNativeOutputAdapter(provider, options = {}) {
+  if (!provider || typeof provider.spawn !== 'function') throw new TypeError('A real subprocess provider is required');
+  if (typeof options.OutputCollector !== 'function') throw new TypeError('Inject the host OutputCollector from its public ./output export');
+  const config = freeze({
+    OutputCollector: options.OutputCollector,
+    stdoutEncoding: encoding(options.stdoutEncoding),
+    stderrEncoding: encoding(options.stderrEncoding),
+    errors: options.errors ?? 'replace',
+    maxSpillBytes: integer(options.maxSpillBytes, 8 * 1024 * 1024, 'maxSpillBytes'),
+    maxTotalBytes: integer(options.maxTotalBytes, 16 * 1024 * 1024, 'maxTotalBytes', 1024),
+    drainTimeoutMs: integer(options.drainTimeoutMs, 250, 'drainTimeoutMs', 1),
+    artifactDirectory: options.artifactDirectory,
+  });
+  if (!['replace', 'strict'].includes(config.errors)) throw new TypeError('errors must be replace or strict');
+  if (config.drainTimeoutMs > 2_147_483_647) throw new TypeError('drainTimeoutMs exceeds Node timer range');
+  if (config.artifactDirectory !== undefined) {
+    if (options.artifactPolicyValidated !== true) throw new Error('Native output artifacts require caller policy validation');
+    if (typeof config.artifactDirectory !== 'string' || !path.isAbsolute(config.artifactDirectory)) throw new TypeError('artifactDirectory must be absolute');
+    if (!fs.statSync(config.artifactDirectory).isDirectory()) throw new TypeError('artifactDirectory must already be a directory');
+  }
+
+  function spawn(spec) {
+    const names = ['stdout', 'stderr'].filter(name => isCollect(spec.stdio?.[name]));
+    if (!names.length) return provider.spawn(spec);
+    // Capture mutable caller dispositions before invoking the real provider.
+    const modes = Object.fromEntries(names.map(name => [name, freeze({ maxBytes: spec.stdio[name].maxBytes, spillMax: spec.stdio[name].spill?.maxBytes })]));
+    const scratchBytes = Math.max(1, Math.min(1024, Math.floor(config.maxTotalBytes / 256)));
+    const baseReservation = scratchBytes * 64 + 256 * names.length;
+    const tailShare = Math.max(0, Math.floor((config.maxTotalBytes - baseReservation) / (16 * names.length)));
+    const caps = Object.fromEntries(names.map(name => [name, Math.min(modes[name].maxBytes, tailShare)]));
+    const reservedMemoryBytes = baseReservation + names.reduce((sum, name) => sum + caps[name] * 16, 0);
+    const budget = { artifactBytes: 0, limit: Math.min(config.maxSpillBytes, config.maxTotalBytes - reservedMemoryBytes) };
+    const owners = names.map(name => makeOwner(name, modes[name], caps[name], config, budget, scratchBytes));
+    const stdio = { ...spec.stdio };
+    for (const name of names) stdio[name] = 'pipe';
+    let real;
+    try { real = provider.spawn({ ...spec, stdio }); }
+    catch (error) { for (const owner of owners) owner.finish('spawn-error'); throw error; }
+    for (const owner of owners) owner.attach(real[owner.name]);
+    let timer;
+    let processSettled = false;
+    const armDrain = reason => {
+      if (timer || owners.every(owner => owner.isSettled())) return;
+      timer = setTimeout(() => { for (const owner of owners) owner.finish(reason); }, config.drainTimeoutMs);
+    };
+    const onAbort = () => {
+      for (const owner of owners) owner.markAborted();
+      armDrain('abort-drain-timeout');
+    };
+    const signal = spec.signal;
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    const outputSettled = Promise.all(owners.map(owner => owner.settled)).then(() => {
+      clearTimeout(timer);
+    });
+    // Observe success AND rejection immediately. Decoding/storage NEVER changes
+    // process outcome or converts a successful side-effecting process into a
+    // provider failure that might invite an unsafe retry.
+    const done = Promise.resolve(real.done).then(async outcome => {
+      processSettled = true;
+      armDrain('exit-drain-timeout');
+      await outputSettled;
+      signal?.removeEventListener('abort', onAbort);
+      return outcome;
+    }, async error => {
+      processSettled = true;
+      armDrain('provider-error-drain-timeout');
+      await outputSettled;
+      signal?.removeEventListener('abort', onAbort);
+      throw error;
+    });
+    const collected = { ...real.collected };
+    for (const owner of owners) collected[owner.name] = owner.reader;
+    const additions = {
+      done, outputSettled, collected: freeze(collected),
+      terminate(...args) {
+        // Direct kill/dispose need not abort spec.signal. Record interruption
+        // before delegating, but never retroactively spoil a completed result
+        // merely because an owner invokes idempotent cleanup after settlement.
+        if (!processSettled || !owners.every(owner => owner.isSettled())) {
+          for (const owner of owners) owner.markAborted();
+          armDrain('terminate-drain-timeout');
+        }
+        return real.terminate(...args);
+      },
+      outputFacts: () => freeze({
+        ...Object.fromEntries(owners.map(owner => [owner.name, owner.facts()])),
+        budget: freeze({ maxTotalBytes: config.maxTotalBytes, reservedMemoryBytes, artifactBytes: budget.artifactBytes, maxArtifactBytes: budget.limit }),
+      }),
+      ...Object.fromEntries(names.map(name => [name, undefined])),
+    };
+    return delegate(real, additions);
+  }
+  return delegate(provider, { spawn, provider, outputConfig: config });
+}
+
+// Bind unknown methods to their REAL receiver (including private-field methods).
+// Do not mutate provider/handle identity or their service registration.
+function delegate(real, additions) {
+  return new Proxy(Object.create(null), {
+    get(_target, key) {
+      if (Object.hasOwn(additions, key)) return additions[key];
+      const value = Reflect.get(real, key, real);
+      return typeof value === 'function' ? value.bind(real) : value;
+    },
+    has: (_target, key) => Object.hasOwn(additions, key) || key in real,
+    set() { return false; },
+  });
+}
+
+function makeOwner(name, mode, cap, config, budget, scratchBytes) {
+  const label = config[`${name}Encoding`];
+  const collector = new config.OutputCollector(cap, `native-${name}`); // no host-private spill fields
+  const decoder = label === 'raw' ? undefined : new TextDecoder(label, { fatal: config.errors === 'strict', ignoreBOM: true });
+  // A fatal validator distinguishes actual invalid bytes from a legitimate U+FFFD.
+  let validator = label === 'raw' || config.errors === 'strict' ? undefined : new TextDecoder(label, { fatal: true, ignoreBOM: true });
+  let rawBytes = 0, decodedUtf8Bytes = 0, decodeError, storageError, streamError;
+  let settled = false, naturalEOF = false, aborted = false, termination, stream, stopText = false;
+  let resolveSettled;
+  const settledPromise = new Promise(resolve => { resolveSettled = resolve; });
+  const artifacts = {};
+  function recordStorage(error) { storageError ??= failure(error, 'NATIVE_OUTPUT_STORAGE'); }
+  function artifact(kind) {
+    if (!config.artifactDirectory) return undefined;
+    return artifacts[kind] ??= { kind, encoding: kind === 'raw' ? label : 'utf-8', bytes: 0, capReached: false, error: undefined, path: undefined, fd: undefined, sealed: false };
+  }
+  function writeArtifact(kind, bytes) {
+    const target = artifact(kind);
+    if (!target || !bytes.length || target.error || target.capReached) return;
+    const streamLimit = kind === 'decoded' ? Math.min(mode.spillMax ?? config.maxSpillBytes, config.maxSpillBytes) : config.maxSpillBytes;
+    let length = Math.min(bytes.length, Math.max(0, budget.limit - budget.artifactBytes), Math.max(0, streamLimit - target.bytes));
+    if (kind === 'decoded') length = alignedEnd(bytes, length);
+    if (length < bytes.length) target.capReached = true;
+    if (!length) return;
+    try {
+      if (target.fd === undefined) {
+        const filename = path.join(config.artifactDirectory, `native-${randomUUID()}-${name}-${kind}.${kind === 'raw' ? 'bin' : 'utf8.log'}`);
+        target.fd = fs.openSync(filename, 'wx', 0o600);
+        target.path = filename;
+      }
+      let offset = 0;
+      while (offset < length) {
+        const written = fs.writeSync(target.fd, bytes, offset, length - offset);
+        if (!Number.isSafeInteger(written) || written <= 0) throw new Error('Native artifact write made no progress');
+        offset += written;
+        target.bytes += written;
+        budget.artifactBytes += written;
+      }
+    } catch (error) { target.error = failure(error, 'NATIVE_OUTPUT_SPILL'); recordStorage(error); }
+  }
+  function publish(text) {
+    if (!text) return;
+    const bytes = Buffer.from(text, 'utf8');
+    decodedUtf8Bytes += bytes.length;
+    writeArtifact('decoded', bytes);
+    if (stopText) return;
+    try {
+      // Bound backing allocations, too: OutputCollector may retain subarray tails.
+      // Every push owns a small copy, never a view of the provider's giant chunk.
+      const step = Math.max(1, Math.min(scratchBytes, cap || 1));
+      for (let offset = 0; offset < bytes.length; offset += step) {
+        const slice = bytes.subarray(offset, offset + step);
+        // Unpooled storage prevents a one-byte retained tail pinning an 8KiB slab.
+        const owned = Buffer.allocUnsafeSlow(slice.length);
+        owned.set(slice);
+        collector.push(owned);
+      }
+    } catch (error) { recordStorage(error); stopText = true; }
+  }
+  function ingest(chunk) {
+    if (settled) return;
+    if (!(chunk instanceof Uint8Array)) {
+      streamError ??= failure(new Error('Raw pipe emitted non-byte data (setEncoding must not be used)'), 'NATIVE_OUTPUT_NOT_BYTES');
+      finish('stream-error');
+      return;
+    }
+    rawBytes += chunk.byteLength;
+    // Never decode a giant incoming chunk in one allocation. Borrow raw slices;
+    // output/string scratch is bounded even after an error or artifact cap.
+    for (let offset = 0; offset < chunk.byteLength; offset += scratchBytes) {
+      const bytes = chunk.subarray(offset, offset + scratchBytes);
+      writeArtifact('raw', bytes);
+      if (!decoder || (decodeError && config.errors === 'strict')) continue;
+      if (validator) {
+        try { validator.decode(bytes, { stream: true }); }
+        catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); validator = undefined; }
+      }
+      try { publish(decoder.decode(bytes, { stream: true })); }
+      catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); }
+    }
+  }
+  function finish(reason) {
+    if (settled) return;
+    settled = true;
+    termination = reason;
+    naturalEOF = reason === 'end';
+    if (validator) {
+      try { validator.decode(); }
+      catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); }
+    }
+    if (decoder && !(decodeError && config.errors === 'strict')) {
+      try { publish(decoder.decode()); }
+      catch (error) { decodeError ??= failure(error, 'NATIVE_OUTPUT_DECODE'); }
+    }
+    try { collector.seal(); } catch (error) { recordStorage(error); }
+    for (const target of Object.values(artifacts)) {
+      if (target.fd !== undefined) {
+        try { fs.closeSync(target.fd); }
+        catch (error) { target.error ??= failure(error, 'NATIVE_OUTPUT_SPILL_CLOSE'); recordStorage(error); }
+        target.fd = undefined;
+      }
+      target.sealed = true;
+    }
+    if (stream) {
+      stream.removeListener('data', ingest);
+      stream.removeListener('end', onEnd);
+      stream.removeListener('close', onClose);
+      // Keep a harmless error sink until close: destroy can schedule a late
+      // error, which must not become an uncaught exception after settlement.
+      if (stream.closed) stream.removeListener('error', onError);
+      else stream.once('close', () => stream.removeListener('error', onError));
+      if (!naturalEOF && !stream.destroyed) stream.destroy();
+    }
+    resolveSettled();
+  }
+  const onEnd = () => finish('end');
+  const onClose = () => finish('close-before-end');
+  const onError = error => { if (!settled) { streamError ??= failure(error, 'NATIVE_OUTPUT_STREAM'); finish('stream-error'); } };
+  function artifactFacts() {
+    return freeze(Object.fromEntries(Object.entries(artifacts).map(([kind, target]) => [kind, freeze({
+      kind, encoding: target.encoding, path: target.path, bytes: target.bytes,
+      complete: target.sealed && naturalEOF && !aborted && !target.error && !target.capReached && (kind === 'raw' || !decodeError),
+      capReached: target.capReached, error: target.error,
+    })])));
+  }
+  const reader = freeze({ readFrom(fromByte) {
+    if (!Number.isSafeInteger(fromByte) || fromByte < 0 || fromByte > decodedUtf8Bytes) throw new RangeError('Expected a normalized UTF8 cursor between zero and decodedUtf8Bytes');
+    let snapshot;
+    try { snapshot = collector.snapshot(); }
+    catch (error) { recordStorage(error); return { text: '', nextOffset: decodedUtf8Bytes, lossy: true }; }
+    const start = snapshot.totalBytes - snapshot.bytes.length;
+    const requested = Math.max(0, fromByte - start);
+    const aligned = alignedStart(snapshot.bytes, requested);
+    const spill = artifactFacts().decoded;
+    return {
+      text: snapshot.bytes.subarray(aligned).toString('utf8'),
+      nextOffset: decodedUtf8Bytes,
+      lossy: label === 'raw' || !!decodeError || !!storageError || fromByte < start || aligned !== requested,
+      // Only finalized COMPLETE normalized text can be called a full-output path.
+      ...(spill?.complete && spill.path ? { spillPath: spill.path } : {}),
+    };
+  } });
+  return {
+    name, reader, settled: settledPromise, finish, isSettled: () => settled,
+    markAborted() { aborted = true; },
+    attach(value) {
+      stream = value;
+      if (!stream || typeof stream.on !== 'function') {
+        stream = undefined;
+        streamError = failure(new Error('Provider did not expose requested raw pipe'), 'NATIVE_OUTPUT_PIPE_MISSING');
+        finish('missing-pipe');
+        return;
+      }
+      stream.on('error', onError);
+      stream.once('end', onEnd);
+      stream.once('close', onClose);
+      stream.on('data', ingest);
+      if (stream.readableEnded) finish('end');
+      else if (stream.destroyed || stream.closed) finish('close-before-end');
+    },
+    facts() {
+      const artifact = artifactFacts();
+      const lossy = reader.readFrom(0).lossy;
+      return freeze({
+        encoding: label, errors: config.errors, rawBytes, decodedUtf8Bytes,
+        rawCursor: rawBytes, decodedCursor: decodedUtf8Bytes,
+        reliableText: label !== 'raw' && !decodeError && !streamError && !storageError,
+        lossy, complete: naturalEOF && !aborted && !streamError && !decodeError && !storageError && (label !== 'raw' || artifact.raw?.complete === true),
+        sourceComplete: naturalEOF, aborted, settled, termination, decodeError, streamError, storageError, artifact,
+        retainedMaxBytes: cap,
+      });
+    },
+  };
+}