@yeaft/webchat-agent 1.0.314 → 1.0.316

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.314",
+  "version": "1.0.316",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/cli-session-runner.js

@@ -128,6 +128,11 @@ export function createCliSessionRunner({
     try {
       for await (const event of engine.query(queryOptions)) {
         if (event.type === 'text_delta') resultText += event.text || '';
+        else if (event.type === 'error' && !failed) {
+          failed = event.error instanceof Error
+            ? event.error
+            : new Error(String(event.error?.message || event.error || 'Unknown Engine error'));
+        }
         await options.onEvent?.({ vpId, event, sessionId, turnId: queryOptions.vpTurnId });
       }
     } catch (error) {

package/yeaft/cli.js

@@ -392,12 +392,28 @@ async function runREPL(config, args) {
     prompt: `yeaft> `,
   });
 
+  let closeRequested = false;
+  let lineQueue = Promise.resolve();
+  let shutdownPromise = null;
+  let acceptedLineSequence = 0;
+  let exitLineSequence = Number.POSITIVE_INFINITY;
+  const isExitLine = line => {
+    const input = line.trim();
+    if (!input.startsWith('/')) return false;
+    const [command] = input.slice(1).split(/\s+/);
+    return command === 'quit' || command === 'exit' || command === 'q';
+  };
+  const promptIfOpen = () => {
+    if (!closeRequested) rl.prompt();
+  };
+
   rl.prompt();
 
-  rl.on('line', async (line) => {
+  const handleLine = async (line, lineSequence) => {
+    if (lineSequence > exitLineSequence) return;
     const input = line.trim();
     if (!input) {
-      rl.prompt();
+      promptIfOpen();
       return;
     }
 
@@ -661,13 +677,14 @@ async function runREPL(config, args) {
         case 'quit':
         case 'exit':
         case 'q':
-          rl.close(); // close handler does shutdown + process.exit()
-          return; // don't call rl.prompt() below
+          closeRequested = true;
+          rl.close();
+          return;
 
         default:
           console.log(`Unknown command: /${cmd}. Type /help for commands.`);
       }
-      rl.prompt();
+      promptIfOpen();
       return;
     }
 
@@ -690,7 +707,7 @@ async function runREPL(config, args) {
         });
         console.log();
         if (outcome.results.some(result => result.error)) process.exitCode = 1;
-        rl.prompt();
+        promptIfOpen();
         return;
       }
 
@@ -733,6 +750,7 @@ async function runREPL(config, args) {
             break;
           case 'error':
             process.stderr.write(`\nError: ${event.error.message}\n`);
+            process.exitCode = 1;
             break;
           case 'turn_start':
             if (session.config.debug && event.turnNumber > 1) {
@@ -751,16 +769,44 @@ async function runREPL(config, args) {
       }
     } catch (err) {
       console.error(`Error: ${err.message}`);
+      process.exitCode = 1;
+    }
+    promptIfOpen();
+  };
+
+  rl.on('line', line => {
+    if (closeRequested) return;
+    const lineSequence = ++acceptedLineSequence;
+    const exitsRepl = isExitLine(line);
+    if (exitsRepl) {
+      exitLineSequence = lineSequence;
+      closeRequested = true;
     }
-    rl.prompt();
+    lineQueue = lineQueue.then(() => handleLine(line, lineSequence)).catch(error => {
+      console.error(`Error: ${error.message}`);
+      process.exitCode = 1;
+    });
+    if (exitsRepl) rl.close();
   });
 
-  rl.on('close', async () => {
-    await sessionRunner?.close();
-    await session.shutdown();
-    console.log('\nBye!');
-    process.exit(0);
+  rl.on('close', () => {
+    closeRequested = true;
+    if (!shutdownPromise) {
+      shutdownPromise = lineQueue.catch(error => {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+      }).then(async () => {
+        await sessionRunner?.close();
+        await session.shutdown();
+        console.log('\nBye!');
+      }).catch(error => {
+        console.error(`Error: ${error.message}`);
+        process.exitCode = 1;
+      });
+    }
   });
+  await new Promise(resolve => rl.once('close', resolve));
+  await shutdownPromise;
 }
 
 // ─── Structured stdio handler ──────────────────────────────────
@@ -843,20 +889,24 @@ async function runStreamJson(config, args) {
       : runStreamTurn({ engine, ...turnOptions });
   };
 
-  let lastResult = null;
+  let hadError = false;
+  const recordResult = (result) => {
+    hadError ||= result?.is_error === true;
+    return result;
+  };
   try {
     if (args.prompt) {
-      lastResult = await runPrompt(args.prompt);
+      recordResult(await runPrompt(args.prompt));
     } else if (input) {
       for (;;) {
         const item = await input.nextPrompt();
         if (!item) break;
-        lastResult = await runPrompt(item.prompt);
+        recordResult(await runPrompt(item.prompt));
       }
     } else {
       let prompt = '';
       for await (const chunk of process.stdin) prompt += chunk;
-      if (prompt.trim()) lastResult = await runPrompt(prompt.trim());
+      if (prompt.trim()) recordResult(await runPrompt(prompt.trim()));
     }
   } finally {
     input?.close();
@@ -866,7 +916,7 @@ async function runStreamJson(config, args) {
     console.info = originalConsole.info;
     console.debug = originalConsole.debug;
   }
-  if (lastResult?.is_error) process.exitCode = 1;
+  if (hadError) process.exitCode = 1;
 }
 
 // ─── One-shot handler ──────────────────────────────────────────
@@ -922,6 +972,7 @@ async function runOnce(config, args) {
       ...(m.toolCalls && { toolCalls: m.toolCalls }),
     }));
 
+    let terminalEngineError = null;
     for await (const event of engine.query({
       prompt: args.prompt,
       messages: priorMessages,
@@ -958,6 +1009,11 @@ async function runOnce(config, args) {
           break;
         case 'error':
           process.stderr.write(`\nError: ${event.error.message}\n`);
+          if (!terminalEngineError) {
+            terminalEngineError = event.error instanceof Error
+              ? event.error
+              : new Error(String(event.error?.message || event.error || 'Engine query failed'));
+          }
           break;
         case 'turn_start':
           if (args.verbose && event.turnNumber > 1) {
@@ -968,6 +1024,7 @@ async function runOnce(config, args) {
     }
     // Final newline after streaming text
     console.log();
+    if (terminalEngineError) process.exitCode = 1;
   } finally {
     await sessionRunner?.close();
     await session.shutdown();

package/yeaft/engine.js

@@ -1630,18 +1630,33 @@ export class Engine {
                 ? `【先前累计摘要】\n${priorSummary}\n\n【新待压缩对话】\n`
                 : `[Previous cumulative summary]\n${priorSummary}\n\n[New conversation to absorb]\n`)
             : '';
-          const result = await adapter.call({
-            model: fastConfig.model,
-            system: summariserSystem,
-            messages: [{ role: 'user', content: `${summariserPromptPrefix}${priorBlock}${toArchive.map(m => `[${m.role}] ${(m.content || '').slice(0, 500)}`).join('\n\n')}` }],
-            // 10k output budget: the running summary is the engine's
-            // long-term memory of cold turns, so it deserves room to
-            // actually preserve detail. We rewrite-in-place each round,
-            // so size stays bounded by maxTokens regardless of how many
-            // compact passes have run.
-            maxTokens: 10240,
+          const maintenanceCtrl = new AbortController();
+          let timeout = null;
+          const timedOut = new Promise((_, reject) => {
+            timeout = setTimeout(() => {
+              maintenanceCtrl.abort('compact_summary_timeout');
+              reject(new LLMAbortError());
+            }, AMS_ADJUST_TIMEOUT_MS);
+            if (timeout && typeof timeout.unref === 'function') timeout.unref();
           });
-          return (result.text || '').trim();
+          try {
+            const request = adapter.call({
+              model: fastConfig.model,
+              system: summariserSystem,
+              messages: [{ role: 'user', content: `${summariserPromptPrefix}${priorBlock}${toArchive.map(m => `[${m.role}] ${(m.content || '').slice(0, 500)}`).join('\n\n')}` }],
+              // 10k output budget: the running summary is the engine's
+              // long-term memory of cold turns, so it deserves room to
+              // actually preserve detail. We rewrite-in-place each round,
+              // so size stays bounded by maxTokens regardless of how many
+              // compact passes have run.
+              maxTokens: 10240,
+              signal: maintenanceCtrl.signal,
+            });
+            const result = await Promise.race([request, timedOut]);
+            return (result.text || '').trim();
+          } finally {
+            if (timeout) clearTimeout(timeout);
+          }
         } catch {
           return '';
         }
@@ -1865,13 +1880,55 @@ export class Engine {
    *   string-prompt shape (no regression for existing callers).
    * @yields {EngineEvent}
    */
-  async *query({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, projectSessionIds = null, projectInstruction = '', sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null } = {}) {
+  async *query(params = {}) {
+    let terminalEmitted = false;
+    let lastTurnNumber = 0;
+    try {
+      for await (const event of this.#queryLifecycle(params)) {
+        if (Number.isFinite(event?.turnNumber)) lastTurnNumber = event.turnNumber;
+        if (event?.type === 'turn_end' && event.terminal === true) terminalEmitted = true;
+        yield event;
+      }
+    } catch (err) {
+      // The internal state machine handles expected provider failures, tool
+      // results, retries and aborts. This outermost boundary catches everything
+      // else, including pre-flow and cleanup faults, so an accepted query never
+      // disappears without a diagnostic terminal event.
+      if (!terminalEmitted) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        yield { type: 'error', error, retryable: false };
+        yield {
+          type: 'turn_end',
+          turnNumber: lastTurnNumber,
+          stopReason: 'error',
+          terminal: true,
+          detail: { message: error.message, errorName: error.name },
+          threadId: params.threadId || MAIN_THREAD_ID,
+        };
+      } else {
+        // Normal end_turn is already durable and visible. A failed maintenance
+        // hook must not retroactively turn the completed answer into an error.
+        console.warn('[Engine] post-turn maintenance failed:', err?.message || err);
+      }
+    }
+  }
+
+  async *#queryLifecycle({ prompt, promptParts = null, messages = [], signal, userEffort = null, scenario = 'chat', vpPersona, router, senderVpId, inboundEnvelope, taskId, taskMembers, sessionId, sessionMembers, projectSessionIds = null, projectInstruction = '', sessionTopics = null, vpPlan, sessionAnnouncement, workCenterInstructions, workDir, userAlreadyPersisted = false, getCurrentTodos = null, setCurrentTodos = null, askUser = null, threadId = MAIN_THREAD_ID, vpTurnId = null, drainPendingUserMessages = null, prepareProviderRequest = null, startProviderRequest = null, finishProviderRequest = null, failProviderRequest = null, closePendingUserInput = null, collabToolPolicy = null } = {}) {
     if (!prompt || typeof prompt !== 'string' || !prompt.trim()) {
+      const error = new Error('prompt is required and must be a non-empty string');
       yield {
         type: 'error',
-        error: new Error('prompt is required and must be a non-empty string'),
+        error,
         retryable: false,
       };
+      yield {
+        type: 'turn_end',
+        turnNumber: 0,
+        stopReason: 'error',
+        terminal: true,
+        detail: { message: error.message, errorName: error.name },
+        threadId,
+      };
       return;
     }
     // promptParts (optional): a content-array form of the user message
@@ -2447,7 +2504,7 @@ export class Engine {
         }
         retryLifecycle.pendingContinuation = null;
         yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
-        yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
+        yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId, terminal: true };
         break;
       }
 
@@ -2932,7 +2989,7 @@ export class Engine {
           });
           endAttemptTrace('aborted');
           yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
-          yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
+          yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId, terminal: true };
           break;
         }
 
@@ -2987,7 +3044,7 @@ export class Engine {
           const slept = await sleepWithAbort(delayMs, signal);
           if (!slept || signal?.aborted) {
             yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
-            yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
+            yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId, terminal: true };
             break;
           }
           yield { type: 'turn_end', turnNumber, stopReason: 'llm_retry', threadId };
@@ -3042,7 +3099,7 @@ export class Engine {
               }
               retryLifecycle.pendingContinuation = null;
               yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
-              yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
+              yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId, terminal: true };
               break;
             }
             yield { type: 'turn_end', turnNumber, stopReason: 'llm_retry', threadId };
@@ -3154,7 +3211,7 @@ export class Engine {
           errorEvent.maxRetries = retryPolicy.maxRetries;
         }
         yield errorEvent;
-        yield { type: 'turn_end', turnNumber, stopReason: 'error', threadId };
+        yield { type: 'turn_end', turnNumber, stopReason: 'error', threadId, terminal: true };
         break;
       }
 
@@ -3399,7 +3456,7 @@ export class Engine {
         };
         if (signal?.aborted) {
           yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
-          yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
+          yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId, terminal: true };
           break;
         }
         if (!signal?.aborted) {
@@ -3863,6 +3920,7 @@ export class Engine {
           stopReason: 'tool_handoff',
           detail: handoffDetail,
           threadId,
+          terminal: true,
         };
         break;
       }
@@ -4000,7 +4058,7 @@ export class Engine {
       // 'aborted' instead of looping back to a new adapter call.
       if (abortedDuringTools || signal?.aborted) {
         yield { type: 'aborted', reason: this.#abortReason || 'external', turnNumber, threadId };
-        yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId };
+        yield { type: 'turn_end', turnNumber, stopReason: 'aborted', threadId, terminal: true };
         break;
       }
 

package/yeaft/linux-process-namespace.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const uid = process.getuid?.();
+const gid = process.getgid?.();
+const separator = process.argv.indexOf('--');
+const command = separator >= 0 ? process.argv[separator + 1] : null;
+const args = separator >= 0 ? process.argv.slice(separator + 2) : [];
+const unsharePath = process.env.YEAFT_UNSHARE_PATH || '/usr/bin/unshare';
+
+if (!Number.isSafeInteger(uid) || !Number.isSafeInteger(gid) || !command) {
+  console.error('linux-process-namespace requires a POSIX uid/gid and a command after --');
+  process.exit(126);
+}
+
+// The child creates user + PID namespaces, then blocks before exec. The parent
+// writes same-uid mappings through /proc while it still owns the new user
+// namespace. A small init process remains PID 1 so the user shell keeps normal
+// signal semantics while namespace teardown remains an unescapable kill boundary.
+const initScript = [
+  'printf ready >&3',
+  'IFS= read -r _ <&4',
+  '"$@" & child=$!',
+  'term() { kill -TERM "$child" 2>/dev/null; }',
+  'trap term TERM INT HUP',
+  'while kill -0 "$child" 2>/dev/null; do wait "$child"; rc=$?; done',
+  'exit "${rc:-1}"',
+].join('; ');
+const child = spawn(unsharePath, [
+  '--user',
+  '--pid',
+  '--fork',
+  '--kill-child=SIGKILL',
+  '--',
+  'sh',
+  '-c',
+  initScript,
+  'yeaft-namespace-init',
+  command,
+  ...args,
+], {
+  stdio: ['ignore', 'inherit', 'inherit', 'pipe', 'pipe'],
+  env: process.env,
+  cwd: process.cwd(),
+});
+
+let started = false;
+const fail = (error) => {
+  if (started) return;
+  started = true;
+  console.error(`Unable to create an isolated process namespace: ${error.message}`);
+  try { child.kill('SIGKILL'); } catch {}
+  process.exitCode = 126;
+};
+
+child.stdio[3].once('data', () => {
+  if (started) return;
+  try {
+    const pid = child.pid;
+    try { writeFileSync(`/proc/${pid}/setgroups`, 'deny\n'); } catch {}
+    writeFileSync(`/proc/${pid}/uid_map`, `${uid} ${uid} 1\n`);
+    writeFileSync(`/proc/${pid}/gid_map`, `${gid} ${gid} 1\n`);
+    const uidMap = readFileSync(`/proc/${pid}/uid_map`, 'utf8');
+    const gidMap = readFileSync(`/proc/${pid}/gid_map`, 'utf8');
+    if (!uidMap.includes(`${uid}`) || !gidMap.includes(`${gid}`)) {
+      throw new Error('uid/gid namespace mapping was not applied');
+    }
+    started = true;
+    child.stdio[4].end('go\n');
+  } catch (error) {
+    fail(error);
+  }
+});
+child.once('error', fail);
+
+const forward = (signal) => {
+  try { child.kill(signal); } catch {}
+};
+process.on('SIGTERM', () => {
+  forward('SIGTERM');
+  setTimeout(() => forward('SIGKILL'), 200);
+});
+process.on('SIGINT', () => forward('SIGINT'));
+process.on('SIGHUP', () => forward('SIGHUP'));
+child.once('close', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exitCode = code ?? 1;
+});

package/yeaft/systemd-scope.js

@@ -8,11 +8,18 @@
  * without polluting the agent service lifecycle.
  */
 
-import { existsSync } from 'fs';
-import { delimiter, isAbsolute, join } from 'path';
+import { spawnSync } from 'child_process';
+import { chmodSync, existsSync, mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
 
 const DEFAULT_SCOPE_PREFIX = 'yeaft-shell';
 const UNIT_MAX_LENGTH = 180;
+const SYSTEMD_SERVICE_RUNNER = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  'systemd-service-runner.js',
+);
 
 function hasPathSeparator(command) {
   return command.includes('/') || command.includes('\\');
@@ -43,6 +50,25 @@ export function shouldUseSystemdUserScope({ runtimePlatform, env = process.env,
   return !!resolvedSystemdRun;
 }
 
+export function canUseSystemdUserManager({ runtimePlatform, env = process.env, systemdRunPath = null } = {}) {
+  if (!runtimePlatform?.isLinux || !env.XDG_RUNTIME_DIR) return false;
+  const systemdRun = systemdRunPath || findExecutableOnPath('systemd-run', env);
+  const systemctlPath = findExecutableOnPath('systemctl', env);
+  if (!systemdRun || !systemctlPath) return false;
+  try {
+    const result = spawnSync(systemctlPath, ['--user', 'show-environment'], {
+      env,
+      encoding: 'utf8',
+      stdio: 'ignore',
+      timeout: 3000,
+      windowsHide: true,
+    });
+    return !result.error && result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
 export function sanitizeSystemdUnitPart(value) {
   const raw = String(value || '').trim() || `${Date.now()}-${process.pid}`;
   return raw
@@ -66,10 +92,11 @@ export function wrapInvocationInSystemdUserScope(invocation, {
   systemdRunPath = null,
 } = {}) {
   if (!shouldUseSystemdUserScope({ runtimePlatform, env, systemdRunPath })) {
-    return { ...invocation, systemdScope: null };
+    return { ...invocation, systemdScope: null, systemdControl: null };
   }
 
   const scopeName = buildSystemdScopeName(scopeId, scopePrefix);
+  const systemctlPath = findExecutableOnPath('systemctl', env);
   return {
     command: systemdRunPath || findExecutableOnPath('systemd-run', env) || 'systemd-run',
     args: [
@@ -83,6 +110,65 @@ export function wrapInvocationInSystemdUserScope(invocation, {
     ],
     family: invocation.family,
     systemdScope: scopeName,
+    systemdControl: systemctlPath
+      ? { unit: scopeName, systemctlPath, env }
+      : null,
+    wrappedCommand: invocation.command,
+  };
+}
+
+export function wrapInvocationInSystemdUserService(invocation, {
+  runtimePlatform,
+  env = process.env,
+  cwd = process.cwd(),
+  unitId = null,
+  unitPrefix = DEFAULT_SCOPE_PREFIX,
+  systemdRunPath = null,
+} = {}) {
+  if (!canUseSystemdUserManager({ runtimePlatform, env, systemdRunPath })) {
+    return { ...invocation, systemdScope: null, systemdControl: null };
+  }
+  const systemdRun = systemdRunPath || findExecutableOnPath('systemd-run', env);
+  const systemctlPath = findExecutableOnPath('systemctl', env);
+  if (!systemctlPath) return { ...invocation, systemdScope: null, systemdControl: null };
+  const safePrefix = sanitizeSystemdUnitPart(unitPrefix).slice(0, 48);
+  const safeId = sanitizeSystemdUnitPart(unitId);
+  const unit = `${safePrefix}-${safeId}`.slice(0, UNIT_MAX_LENGTH) + '.service';
+  const payloadDir = mkdtempSync(join(tmpdir(), 'yeaft-systemd-invocation-'));
+  const payloadPath = join(payloadDir, 'invocation.json');
+  const cleanup = () => rmSync(payloadDir, { recursive: true, force: true });
+  try {
+    chmodSync(payloadDir, 0o700);
+    writeFileSync(payloadPath, JSON.stringify({
+      command: invocation.command,
+      args: invocation.args || [],
+      cwd,
+      env,
+    }), { mode: 0o600 });
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+  return {
+    command: systemdRun,
+    args: [
+      '--user',
+      '--wait',
+      '--pipe',
+      '--quiet',
+      '--collect',
+      '--service-type=exec',
+      '--property=KillMode=control-group',
+      `--unit=${unit}`,
+      '--',
+      process.execPath,
+      SYSTEMD_SERVICE_RUNNER,
+      payloadPath,
+    ],
+    family: invocation.family,
+    systemdScope: unit,
+    systemdControl: { unit, systemctlPath, env },
+    cleanup,
     wrappedCommand: invocation.command,
   };
 }

package/yeaft/systemd-service-runner.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { readFileSync, rmSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const payloadPath = process.argv[2];
+let payload;
+try {
+  if (!payloadPath) throw new Error('missing invocation payload path');
+  payload = JSON.parse(readFileSync(payloadPath, 'utf8'));
+  if (!payload || typeof payload.command !== 'string' || !Array.isArray(payload.args)) {
+    throw new Error('invalid invocation payload');
+  }
+} catch (error) {
+  console.error(`Unable to read systemd service command: ${error.message}`);
+  process.exit(126);
+} finally {
+  if (payloadPath) rmSync(dirname(payloadPath), { recursive: true, force: true });
+}
+
+const child = spawn(payload.command, payload.args, {
+  cwd: payload.cwd || process.cwd(),
+  env: payload.env || process.env,
+  stdio: 'inherit',
+});
+const forward = signal => {
+  try { child.kill(signal); } catch {}
+};
+process.on('SIGTERM', () => forward('SIGTERM'));
+process.on('SIGINT', () => forward('SIGINT'));
+process.on('SIGHUP', () => forward('SIGHUP'));
+child.once('error', error => {
+  console.error(error.message);
+  process.exitCode = 126;
+});
+child.once('close', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exitCode = code ?? 1;
+});