@cleocode/core 2026.9.8 → 2026.9.9

package/dist/resources/spawn-wrapper.js

@@ -65,7 +65,12 @@
  * @task T11993
  */
 import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { z } from 'zod';
+import { registerTeardownAbort } from '../teardown-signal.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -99,39 +104,101 @@ const OOM_AVOID_CLASSES = new Set(['daemon', 'db']);
 // Internal helpers
 // ---------------------------------------------------------------------------
 /**
- * Is `systemd-run` available on this host? Probed once and cached.
+ * Is `systemd-run` available for this manager context? Probed and cached per connection.
  * Mirrors the probe in `packages/core/src/check/pr-gate.ts`.
  */
-let _systemdRunAvailable;
+let _forcedSystemdRunAvailable;
+const systemdProbeCache = new Map();
+/** Construct a manager environment without mutating the caller or global state. */
+function managerEnvironment(context, original) {
+    if (!context)
+        return original;
+    if (!isAbsolute(context.runtimeDirectory))
+        throw new TypeError('Systemd manager runtime directory must be absolute');
+    const address = context.busAddress ?? `unix:path=${join(context.runtimeDirectory, 'bus')}`;
+    if (!address.startsWith('unix:'))
+        throw new TypeError('Systemd manager bus must use a local Unix address');
+    return {
+        ...original,
+        XDG_RUNTIME_DIR: context.runtimeDirectory,
+        DBUS_SESSION_BUS_ADDRESS: address,
+    };
+}
+/** Check the original launch boundary without claiming preemption of synchronous calls. */
+function launchRemaining(execution) {
+    execution?.signal?.throwIfAborted();
+    if (!execution)
+        return 1000;
+    if (!Number.isSafeInteger(execution.deadlineAt))
+        throw new RangeError('Process deadline must be an absolute integer timestamp');
+    const remaining = execution.deadlineAt - Date.now();
+    if (remaining <= 0)
+        throw new Error('E_PROCESS_DEADLINE: original process launch deadline expired');
+    return remaining;
+}
 /**
- * Check whether `systemd-run --user` is usable on this host.
- *
- * Returns `false` on non-Linux, when systemd-run is not on PATH, or when
- * DBUS_SESSION_BUS_ADDRESS / XDG_RUNTIME_DIR are absent (CI containers,
- * ssh sessions without a user bus).
+ * Check whether the selected local user manager can launch transient scopes.
+ * @param context - Explicit manager context; omitted callers retain ambient discovery.
+ * @param execution - Original deadline/cancellation; each synchronous probe uses its remaining budget.
+ * @returns Whether systemd binaries and the selected user bus answered the bounded probes.
+ * @remarks Availability does not prove that a later scope or resource bound was established.
+ * Probe results are keyed by platform, executable search path and manager connection,
+ * so an unavailable ambient context cannot poison a later explicit context.
+ * @example
+ * ```typescript
+ * const available = hasSystemdRun({ runtimeDirectory: '/run/user/1000' });
+ * ```
  */
-export function hasSystemdRun() {
-    if (_systemdRunAvailable !== undefined)
-        return _systemdRunAvailable;
-    if (process.platform !== 'linux') {
-        _systemdRunAvailable = false;
-        return false;
+export function hasSystemdRun(context, execution) {
+    launchRemaining(execution);
+    const env = managerEnvironment(context, process.env);
+    if (_forcedSystemdRunAvailable !== undefined)
+        return _forcedSystemdRunAvailable;
+    const key = JSON.stringify([
+        process.platform,
+        env['PATH'],
+        env['DBUS_SESSION_BUS_ADDRESS'],
+        env['XDG_RUNTIME_DIR'],
+    ]);
+    const cached = systemdProbeCache.get(key);
+    if (cached !== undefined)
+        return cached;
+    let available = false;
+    if (process.platform === 'linux' && (env['DBUS_SESSION_BUS_ADDRESS'] || env['XDG_RUNTIME_DIR'])) {
+        const probe = spawnSync('systemd-run', ['--version'], {
+            env,
+            stdio: 'ignore',
+            timeout: Math.min(1000, launchRemaining(execution)),
+        });
+        launchRemaining(execution);
+        const bus = probe.status === 0
+            ? spawnSync('systemctl', ['--user', 'show-environment'], {
+                env,
+                stdio: 'ignore',
+                timeout: Math.min(1000, launchRemaining(execution)),
+            })
+            : null;
+        launchRemaining(execution);
+        available = probe.status === 0 && bus?.status === 0;
     }
-    // Quick binary availability check — does NOT test user-bus connectivity.
-    const probe = spawnSync('systemd-run', ['--version'], { stdio: 'ignore' });
-    _systemdRunAvailable = probe.status === 0;
-    return _systemdRunAvailable;
+    // Bound contexts retained by long-lived callers with many synthetic workspaces.
+    if (systemdProbeCache.size >= 64)
+        systemdProbeCache.clear();
+    systemdProbeCache.set(key, available);
+    return available;
 }
 /**
- * Force-override the cached systemd-run availability.
- *
- * Exposed for unit tests that need to exercise the pgid-fallback or
- * systemd paths without the real binary.
- *
- * @param available - `true` = force systemd path, `false` = force pgid path.
+ * Override availability for deterministic tests, or clear the override and cached probes.
+ * @param available - Forced availability; undefined restores real context-specific probing.
+ * @remarks Test overrides do not establish actual manager availability or containment.
+ * @example
+ * ```typescript
+ * _forceSystemdRunAvailable(undefined);
+ * ```
  */
 export function _forceSystemdRunAvailable(available) {
-    _systemdRunAvailable = available;
+    _forcedSystemdRunAvailable = available;
+    systemdProbeCache.clear();
 }
 /** Whether we have already emitted the pgid-demotion log line for this process. */
 let _pgidDemotionLogged = false;
@@ -205,10 +272,15 @@ let _scopeCounter = 0;
  * @param args - Arguments to pass to the executable.
  * @param opts - Wrapper options (scope class, resources, etc.).
  * @returns Build result with final command, args, mode, and unit name.
+ * @remarks This only constructs launch arguments; it does not establish or inspect a scope.
+ * @example
+ * ```typescript
+ * const launch = buildSpawnArgs('node', ['--version']);
+ * ```
  */
 export function buildSpawnArgs(command, args, opts = {}) {
     const { scopeClass = 'agent', scopeId, resources = {}, noCoreFile = true } = opts;
-    if (!hasSystemdRun()) {
+    if (!hasSystemdRun(opts.systemdControl, opts.execution)) {
         if (!_pgidDemotionLogged) {
             _pgidDemotionLogged = true;
             process.stderr.write('[cleo:spawn-wrapper] systemd-run unavailable — falling back to plain pgid spawn ' +
@@ -246,6 +318,11 @@ export function buildSpawnArgs(command, args, opts = {}) {
         '-p',
         'MemorySwapMax=0',
     ];
+    if (resources.tasksMax !== undefined) {
+        if (!Number.isSafeInteger(resources.tasksMax) || resources.tasksMax < 1)
+            throw new RangeError('Scope task limit must be a positive safe integer');
+        wrapArgs.push('-p', `TasksMax=${resources.tasksMax}`);
+    }
     // MemoryHigh: only emit the directive when it is a real limit (not infinity).
     if (highStr !== 'infinity') {
         wrapArgs.push('-p', `MemoryHigh=${highStr}`);
@@ -290,10 +367,41 @@ export function buildSpawnArgs(command, args, opts = {}) {
  * @param spawnOpts - Options forwarded to `child_process.spawn`.
  * @param wrapOpts - Wrapper options (scope class, resources, etc.).
  * @returns Wrapped spawn result.
+ * @remarks An explicit manager context applies only to the launcher. Child manager variables
+ * are restored before execution, while all other child environment values remain in env.
+ * Scope membership, limits and cleanup require independent observation.
+ * @example
+ * ```typescript
+ * const launched = spawnWrapped('node', ['--version'], { env: process.env });
+ * ```
  */
 export function spawnWrapped(command, args, spawnOpts = {}, wrapOpts = {}) {
-    const built = buildSpawnArgs(command, args, wrapOpts);
-    const child = spawn(built.command, built.args, spawnOpts);
+    const execution = wrapOpts.execution ? { ...wrapOpts.execution } : undefined;
+    const options = {
+        ...wrapOpts,
+        execution,
+        systemdControl: wrapOpts.systemdControl ? { ...wrapOpts.systemdControl } : undefined,
+    };
+    launchRemaining(execution);
+    const control = options.systemdControl;
+    const childEnvironment = spawnOpts?.env ?? process.env;
+    const controlled = control !== undefined && hasSystemdRun(control, execution);
+    // Only non-secret manager path/address values enter the env shim's argv.
+    // Arbitrary child environment (including credentials) stays in the environment.
+    const restored = [];
+    if (controlled) {
+        for (const key of ['XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS']) {
+            restored.push(`--unset=${key}`);
+        }
+        for (const key of ['XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS']) {
+            const value = childEnvironment[key];
+            if (value !== undefined)
+                restored.push(`${key}=${value}`);
+        }
+    }
+    const built = buildSpawnArgs(controlled ? 'env' : command, controlled ? [...restored, command, ...args] : args, options);
+    launchRemaining(execution);
+    const child = spawn(built.command, built.args, controlled ? { ...spawnOpts, env: managerEnvironment(control, childEnvironment) } : spawnOpts);
     return {
         child,
         pid: child.pid,
@@ -301,4 +409,454 @@ export function spawnWrapped(command, args, spawnOpts = {}, wrapOpts = {}) {
         unitName: built.unitName,
     };
 }
+/** Transport reports target events separately from the enclosing scope wrapper. */
+const CAPTURE_TRANSPORT = String.raw `
+(() => {
+const { spawn } = require('node:child_process');
+const send = (event) => process.stdout.write(JSON.stringify(event) + '\n');
+const [limitsJson, command, ...args] = process.argv.slice(1);
+const limits = JSON.parse(limitsJson);
+if (limits.memoryMaxBytes !== undefined || limits.tasksMax !== undefined) {
+  try {
+    const { readFileSync } = require('node:fs');
+    const { join } = require('node:path');
+    const entries = readFileSync('/proc/self/cgroup', 'utf8').trim().split('\n');
+    const unified = entries.find((entry) => entry.startsWith('0::'));
+    if (!unified) throw new Error('Unified cgroup membership unavailable');
+    const cgroup = unified.slice(3);
+    if (!cgroup.startsWith('/') || cgroup.split('/').includes('..') || !cgroup.split('/').includes(limits.unitName))
+      throw new Error('Transport is not inside the requested owned scope');
+    const readLimit = (name) => {
+      const value = readFileSync(join('/sys/fs/cgroup', cgroup, name), 'utf8').trim();
+      if (value === 'max') return null;
+      const limit = Number(value);
+      if (!Number.isSafeInteger(limit) || limit < 1) throw new Error('Invalid kernel limit: ' + name);
+      return limit;
+    };
+    const memoryMaxBytes = readLimit('memory.max');
+    const tasksMax = readLimit('pids.max');
+    if (limits.memoryMaxBytes !== undefined && (memoryMaxBytes === null || memoryMaxBytes > limits.memoryMaxBytes))
+      throw new Error('Requested memory ceiling was not observed');
+    if (limits.tasksMax !== undefined && (tasksMax === null || tasksMax > limits.tasksMax))
+      throw new Error('Requested task ceiling was not observed');
+    send({ type: 'resources', cgroup, memoryMaxBytes, tasksMax });
+  } catch (error) {
+    send({ type: 'resource-error', message: String(error.message) });
+    process.exitCode = 125;
+    return;
+  }
+}
+const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+child.once('spawn', () => send({ type: 'started', pid: child.pid }));
+child.once('error', (error) => send({ type: 'error', message: String(error.code || '') + ': ' + error.message }));
+for (const stream of ['stdout', 'stderr']) {
+  child[stream].on('data', (chunk) => {
+    for (let offset = 0; offset < chunk.length; offset += 16384)
+      send({ type: 'data', stream, bytes: chunk.subarray(offset, offset + 16384).toString('base64') });
+  });
+}
+child.once('close', (code, signal) => send({ type: 'closed', code, signal }));
+})();
+`;
+/** Internal framing is validated before it can supply a target verdict. */
+const captureFrameSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('resource-error'), message: z.string() }).strict(),
+    z
+        .object({
+        type: z.literal('resources'),
+        cgroup: z.string(),
+        memoryMaxBytes: z.number().int().positive().safe().nullable(),
+        tasksMax: z.number().int().positive().safe().nullable(),
+    })
+        .strict(),
+    z.object({ type: z.literal('started'), pid: z.number().int().positive() }).strict(),
+    z.object({ type: z.literal('error'), message: z.string() }).strict(),
+    z
+        .object({ type: z.literal('data'), stream: z.enum(['stdout', 'stderr']), bytes: z.string() })
+        .strict(),
+    z
+        .object({
+        type: z.literal('closed'),
+        code: z.number().int().nullable(),
+        signal: z.string().nullable(),
+    })
+        .strict(),
+]);
+/**
+ * Capture an owned process with a shared deadline, cancellation and bounded output.
+ * @param command - Exact executable; never interpreted as a shell expression.
+ * @param args - Exact target arguments; no environment values are added to argv.
+ * @param options - Explicit captured routing, environment and original execution budget.
+ * @returns Target events and independent transport, stop and cleanup diagnostics.
+ * @throws When admission inputs are invalid, the original context has ended, or the platform cannot provide process-group cleanup.
+ * @remarks A fixed Node transport distinguishes the requested process from systemd/sh
+ * launchers. Cleanup has a bounded additional manager timeout and can exceed the
+ * execution deadline. POSIX process groups cannot contain deliberately escaped
+ * descendants; Windows capture is refused. Requested hard memory/task limits require
+ * observation inside the exact owned cgroup before the target is launched. Calls without
+ * requests retain unverified memory limits. This is a transport, not a job scheduler.
+ * @example
+ * ```typescript
+ * const result = await captureWrapped('node', ['check.mjs'], {
+ *   cwd: projectRoot, env: {}, execution: { deadlineAt: Date.now() + 2000 },
+ * });
+ * if (result.started && !result.stopped && result.exitCode === 0) inspect(result);
+ * ```
+ */
+export async function captureWrapped(command, args, options) {
+    if (process.platform === 'win32')
+        throw new Error('E_PROCESS_CONTAINMENT: bounded process-group capture is unavailable on Windows');
+    if (!isAbsolute(options.cwd))
+        throw new TypeError('Captured process cwd must be absolute');
+    const maxOutputBytes = options.maxOutputBytes ?? 1_048_576;
+    if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1)
+        throw new RangeError('Capture byte limit must be a positive safe integer');
+    const memoryMaxMb = options.memoryMaxMb;
+    const tasksMax = options.tasksMax;
+    for (const [name, value] of [
+        ['memoryMaxMb', memoryMaxMb],
+        ['tasksMax', tasksMax],
+    ]) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+            throw new RangeError(`${name} must be a positive safe integer`);
+    }
+    const memoryMaxBytes = memoryMaxMb === undefined ? undefined : memoryMaxMb * 1024 * 1024;
+    if (memoryMaxBytes !== undefined && !Number.isSafeInteger(memoryMaxBytes))
+        throw new RangeError('Requested memory ceiling exceeds exact byte representation');
+    const scopeId = `${process.pid}-${randomUUID()}`;
+    const requestedLimits = { memoryMaxBytes, tasksMax, unitName: `cleo-tool-${scopeId}.scope` };
+    const requiresLimits = memoryMaxMb !== undefined || tasksMax !== undefined;
+    const execution = { ...options.execution };
+    const env = { ...options.env };
+    const systemdControl = options.systemdControl ? { ...options.systemdControl } : undefined;
+    const startedAt = Date.now();
+    launchRemaining(execution);
+    const controller = new AbortController();
+    const deregister = registerTeardownAbort(controller);
+    let owned;
+    try {
+        controller.signal.throwIfAborted();
+        owned = spawnWrapped(process.execPath, ['-e', CAPTURE_TRANSPORT, JSON.stringify(requestedLimits), command, ...args], {
+            cwd: options.cwd,
+            env,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }, {
+            scopeClass: 'tool',
+            scopeId,
+            resources: {
+                ...(memoryMaxMb === undefined ? {} : { memoryMax: `${memoryMaxMb}M` }),
+                tasksMax,
+            },
+            execution,
+            systemdControl,
+            noCoreFile: false,
+        });
+    }
+    catch (error) {
+        deregister();
+        throw error;
+    }
+    return new Promise((resolve) => {
+        const { child } = owned;
+        let resourceLimits;
+        let started = false;
+        let targetPid = null;
+        let exitCode = null;
+        let signal = null;
+        let error = null;
+        let stopped = null;
+        let closedFrame = false;
+        let pending = '';
+        let outputBytes = 0;
+        let outputTruncated = false;
+        let wrapperError = '';
+        const stdout = [];
+        const stderr = [];
+        const cleanupErrors = [];
+        let cleanupObservation = 'unverified';
+        let terminated = false;
+        const terminate = () => {
+            if (terminated)
+                return;
+            terminated = true;
+            if (child.pid) {
+                try {
+                    if (process.platform === 'win32')
+                        child.kill('SIGKILL');
+                    else {
+                        process.kill(-child.pid, 'SIGKILL');
+                        cleanupObservation = 'process-group-signalled';
+                    }
+                }
+                catch (cause) {
+                    if (cause instanceof Error && 'code' in cause && cause.code === 'ESRCH')
+                        cleanupObservation = 'process-group-absent';
+                    else
+                        cleanupErrors.push(String(cause));
+                }
+            }
+            if (owned.unitName) {
+                const cleanup = spawnSync('systemctl', ['--user', 'kill', '--kill-whom=all', '--signal=SIGKILL', owned.unitName], {
+                    env: managerEnvironment(systemdControl, env),
+                    timeout: 1000,
+                    maxBuffer: 4096,
+                    encoding: 'utf8',
+                });
+                const observation = spawnSync('systemctl', ['--user', 'show', owned.unitName, '--property=LoadState', '--property=ActiveState'], {
+                    env: managerEnvironment(systemdControl, env),
+                    timeout: 1000,
+                    maxBuffer: 4096,
+                    encoding: 'utf8',
+                });
+                const inactive = observation.stdout
+                    ?.split('\n')
+                    .some((line) => line === 'LoadState=not-found' ||
+                    line === 'ActiveState=inactive' ||
+                    line === 'ActiveState=failed');
+                if (!observation.error && inactive)
+                    cleanupObservation = 'scope-terminal';
+                if (observation.error || !inactive)
+                    cleanupErrors.push(`Scope cleanup unverified: ${observation.error?.message ??
+                        observation.stderr?.trim() ??
+                        cleanup.error?.message ??
+                        cleanup.stderr?.trim() ??
+                        'scope remains active'}`);
+            }
+        };
+        const stop = (reason, diagnostic) => {
+            stopped ??= reason;
+            if (diagnostic)
+                error ??= diagnostic;
+            terminate();
+        };
+        const cancelled = () => stop(Date.now() >= execution.deadlineAt ? 'deadline' : 'cancelled');
+        const teardown = () => stop('teardown');
+        let timer;
+        const deadline = () => {
+            const remaining = execution.deadlineAt - Date.now();
+            if (remaining <= 0)
+                stop('deadline');
+            else
+                timer = setTimeout(deadline, Math.min(2_147_483_647, remaining));
+        };
+        deadline();
+        execution.signal?.addEventListener('abort', cancelled, { once: true });
+        controller.signal.addEventListener('abort', teardown, { once: true });
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            pending += chunk;
+            for (;;) {
+                const end = pending.indexOf('\n');
+                if (end < 0)
+                    break;
+                const line = pending.slice(0, end);
+                pending = pending.slice(end + 1);
+                if (line.length > 32768) {
+                    stop('transport-error', 'Capture frame exceeds byte bound');
+                    break;
+                }
+                try {
+                    const frame = captureFrameSchema.parse(JSON.parse(line));
+                    if (closedFrame)
+                        throw new Error('Capture frame received after target close');
+                    switch (frame.type) {
+                        case 'resource-error':
+                            stop('resource-limit', `E_PROCESS_RESOURCE_LIMIT: ${frame.message}`);
+                            break;
+                        case 'resources':
+                            if (!requiresLimits ||
+                                resourceLimits ||
+                                started ||
+                                owned.mode !== 'systemd' ||
+                                !frame.cgroup.split('/').includes(requestedLimits.unitName) ||
+                                (memoryMaxBytes !== undefined &&
+                                    (frame.memoryMaxBytes === null || frame.memoryMaxBytes > memoryMaxBytes)) ||
+                                (tasksMax !== undefined && (frame.tasksMax === null || frame.tasksMax > tasksMax)))
+                                throw new Error('Invalid or insufficient resource observation');
+                            resourceLimits = {
+                                cgroup: frame.cgroup,
+                                memoryMaxBytes: frame.memoryMaxBytes,
+                                tasksMax: frame.tasksMax,
+                            };
+                            break;
+                        case 'started':
+                            if (requiresLimits && !resourceLimits)
+                                throw new Error('Target started without required resource observation');
+                            if (started || error)
+                                throw new Error('Duplicate or contradictory target start');
+                            started = true;
+                            targetPid = frame.pid;
+                            break;
+                        case 'error':
+                            error = frame.message;
+                            break;
+                        case 'closed':
+                            closedFrame = true;
+                            if (started) {
+                                exitCode = frame.code;
+                                signal = frame.signal;
+                            }
+                            break;
+                        case 'data': {
+                            if (!started)
+                                throw new Error('Output before target spawn');
+                            const bytes = Buffer.from(frame.bytes, 'base64');
+                            if (bytes.toString('base64') !== frame.bytes)
+                                throw new Error('Malformed output encoding');
+                            const allowed = Math.max(0, maxOutputBytes - outputBytes);
+                            (frame.stream === 'stdout' ? stdout : stderr).push(bytes.subarray(0, allowed));
+                            outputBytes += bytes.length;
+                            if (outputBytes > maxOutputBytes) {
+                                outputTruncated = true;
+                                stop('output-limit');
+                            }
+                            break;
+                        }
+                    }
+                }
+                catch (cause) {
+                    stop('transport-error', `Invalid capture transport: ${String(cause)}`);
+                }
+            }
+            if (pending.length > 32768)
+                stop('transport-error', 'Unterminated capture frame exceeds bound');
+        });
+        child.stderr?.on('data', (chunk) => {
+            wrapperError = Buffer.concat([Buffer.from(wrapperError), chunk])
+                .subarray(0, 4096)
+                .toString('utf8');
+        });
+        child.once('error', (cause) => {
+            error = `Capture launcher failed: ${cause.message}`;
+        });
+        child.once('close', (wrapperCode, wrapperSignal) => {
+            clearTimeout(timer);
+            execution.signal?.removeEventListener('abort', cancelled);
+            controller.signal.removeEventListener('abort', teardown);
+            deregister();
+            if (!stopped &&
+                (!closedFrame ||
+                    (!started && !error) ||
+                    pending.length ||
+                    wrapperCode !== 0 ||
+                    wrapperSignal)) {
+                stopped = 'transport-error';
+                error ??= `Capture transport incomplete (wrapper code ${wrapperCode}, signal ${wrapperSignal}): ${wrapperError}`;
+            }
+            terminate();
+            if (Buffer.byteLength(Buffer.concat(stdout).toString('utf8')) +
+                Buffer.byteLength(Buffer.concat(stderr).toString('utf8')) >
+                maxOutputBytes) {
+                outputTruncated = true;
+                stopped ??= 'output-limit';
+            }
+            const decodedStdout = new StringDecoder('utf8').write(Buffer.from(Buffer.concat(stdout).toString('utf8')).subarray(0, maxOutputBytes));
+            const decodedStderr = new StringDecoder('utf8').write(Buffer.from(Buffer.concat(stderr).toString('utf8')).subarray(0, maxOutputBytes - Buffer.byteLength(decodedStdout)));
+            resolve({
+                started,
+                targetPid,
+                exitCode,
+                signal,
+                error,
+                stopped,
+                stdout: decodedStdout,
+                stderr: decodedStderr,
+                outputTruncated,
+                durationMs: Date.now() - startedAt,
+                mode: owned.mode,
+                ...(owned.unitName ? { unitName: owned.unitName } : {}),
+                nativeMemory: resourceLimits?.memoryMaxBytes ? 'observed-cgroup' : 'unverified',
+                ...(resourceLimits ? { resourceLimits } : {}),
+                cleanupScope: 'process-group',
+                transportClosed: true,
+                targetCloseObserved: closedFrame,
+                cleanupObservation,
+                cleanupErrors,
+            });
+        });
+        if (execution.signal?.aborted)
+            cancelled();
+        if (controller.signal.aborted)
+            teardown();
+    });
+}
+/**
+ * Create the parser's process-execution port using the canonical spawn service.
+ * @returns A launcher with per-process V8 limits and teardown cancellation.
+ * @remarks Explicit Node argv overrides inherited NODE_OPTIONS heap flags while
+ * preserving loader guards. Configured cgroup memory is not claimed as observed
+ * native-memory containment. The parser verifies its actual V8 limit at startup.
+ * @example
+ * ```ts
+ * const parserExecution = createParserExecutionPort();
+ * ```
+ */
+export function createParserExecutionPort() {
+    return {
+        spawn(scriptPath, limits) {
+            const heapMb = limits.workerHeapMb ?? 128;
+            if (!Number.isSafeInteger(heapMb) || heapMb < 8 || heapMb > 512) {
+                throw new RangeError('Parser worker heap must be an integer from 8 to 512 MiB');
+            }
+            limits.signal?.throwIfAborted();
+            const controller = new AbortController();
+            const deregister = registerTeardownAbort(controller);
+            if (controller.signal.aborted) {
+                deregister();
+                controller.signal.throwIfAborted();
+            }
+            let owned;
+            try {
+                owned = spawnWrapped(process.execPath, [`--max-old-space-size=${heapMb}`, '--max-semi-space-size=8', scriptPath], {
+                    stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+                    detached: process.platform !== 'win32',
+                    env: process.env,
+                }, { scopeClass: 'tool', resources: { memoryMax: `${Math.max(256, heapMb * 2)}M` } });
+            }
+            catch (error) {
+                deregister();
+                throw error;
+            }
+            const { child } = owned;
+            // Drain diagnostics to avoid blocking a child on a full stderr pipe.
+            child.stderr?.on('data', () => undefined);
+            let exited = false;
+            const closed = new Promise((resolve) => {
+                child.once('close', () => {
+                    exited = true;
+                    resolve();
+                });
+            });
+            const stop = async () => {
+                if (!exited && child.pid) {
+                    try {
+                        if (process.platform === 'win32')
+                            child.kill('SIGKILL');
+                        else
+                            process.kill(-child.pid, 'SIGKILL');
+                    }
+                    catch (error) {
+                        if (!(error instanceof Error) || !('code' in error) || error.code !== 'ESRCH')
+                            throw error;
+                    }
+                }
+                await closed;
+            };
+            const abort = () => {
+                void stop().catch(() => undefined);
+            };
+            limits.signal?.addEventListener('abort', abort, { once: true });
+            controller.signal.addEventListener('abort', abort, { once: true });
+            child.once('close', () => {
+                limits.signal?.removeEventListener('abort', abort);
+                controller.signal.removeEventListener('abort', abort);
+                deregister();
+            });
+            if (limits.signal?.aborted || controller.signal.aborted)
+                abort();
+            return { child, heapMb, nativeMemory: 'unverified', stop };
+        },
+    };
+}
 //# sourceMappingURL=spawn-wrapper.js.map