@0xgeorgemathew/zcode 0.3.2 → 0.4.1

package/lib/appserver.js

@@ -50,10 +50,14 @@ class AppServerClient {
   }
 
   start() {
+    // Own process group, so kill() takes the engine's tool subprocesses and
+    // stdio MCP servers with it (a runaway shell command must not keep
+    // writing to the workspace after cancel/timeout).
     this.child = spawn(this.nodeBin, [this.enginePath, 'app-server', '--stdio'], {
       env: this.env,
       cwd: this.cwd,
       stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
     });
     this.child.stderr.on('data', (d) => {
       this.engineStderr += d;
@@ -61,13 +65,30 @@ class AppServerClient {
         this.engineStderr = this.engineStderr.slice(-20000);
       }
     });
+    // EPIPE on a dying engine and spawn failures (bad ZAI_CODE_NODE) must
+    // surface as a failed request, never as an uncaught 'error' event.
+    this.child.stdin.on('error', () => {});
+    this.child.on('error', (err) => {
+      if (this.dead) return;
+      this.dead = true;
+      const wrapped = new Error(`engine app-server failed to start: ${err.message}`);
+      for (const { reject, timer } of this.pending.values()) {
+        clearTimeout(timer);
+        reject(wrapped);
+      }
+      this.pending.clear();
+      if (this.onExit) this.onExit(wrapped);
+    });
     this.child.on('exit', (code, signal) => {
       this.dead = true;
       const err = new Error(
         `engine app-server exited (code=${code} signal=${signal})` +
           (this.engineStderr ? `\nengine stderr tail: ${this.engineStderr.split('\n').slice(-8).join('\n')}` : '')
       );
-      for (const { reject } of this.pending.values()) reject(err);
+      for (const { reject, timer } of this.pending.values()) {
+        clearTimeout(timer);
+        reject(err);
+      }
       this.pending.clear();
       if (this.onExit) this.onExit(err);
     });
@@ -139,8 +160,14 @@ class AppServerClient {
   request(method, params, { timeoutMs = 30000 } = {}) {
     if (this.dead) return Promise.reject(new Error('engine app-server is dead'));
     const id = this.nextId++;
-    this.child.stdin.write(JSON.stringify({ id, method, params }) + '\n');
     return new Promise((resolve, reject) => {
+      this.child.stdin.write(JSON.stringify({ id, method, params }) + '\n', (err) => {
+        if (err && this.pending.has(id)) {
+          clearTimeout(this.pending.get(id).timer);
+          this.pending.delete(id);
+          reject(new Error(`engine stdin closed while sending ${method}`));
+        }
+      });
       const timer = setTimeout(() => {
         this.pending.delete(id);
         reject(new Error(`timeout (${timeoutMs}ms) waiting for ${method}`));
@@ -149,12 +176,29 @@ class AppServerClient {
     });
   }
 
+  // Asks the engine to abort the active prompt (session/stop). Best-effort
+  // and bounded: a wedged engine must not block cancellation.
+  async stopSession(sessionId, { timeoutMs = 3000 } = {}) {
+    if (this.dead || !sessionId) return false;
+    try {
+      await this.request('session/stop', { sessionId }, { timeoutMs });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   kill() {
-    if (this.child && !this.dead) {
-      try {
-        this.child.kill('SIGKILL');
-      } catch {
-        /* already gone */
+    if (!this.child || !this.child.pid) return;
+    try {
+      process.kill(-this.child.pid, 'SIGKILL'); // the whole engine group
+    } catch {
+      if (!this.dead) {
+        try {
+          this.child.kill('SIGKILL');
+        } catch {
+          /* already gone */
+        }
       }
     }
   }
@@ -220,26 +264,81 @@ async function waitForMcp(client, { workspacePath, required, timeoutMs = 20000,
   }
 }
 
-// Runs one full turn: create (+setMode ladder) or resume → subscribe → send
-// → wait for terminal. Resolves a turn result object; rejects with TurnError
-// on failure. `resumeSessionId` continues a persisted session (the engine
-// stores sessions in SQLite under the scratch HOME, so a new engine process
-// picks up where the previous CLI invocation stopped).
-async function executeTurn(client, {
+// Opens the engine session for an invocation: create (+setMode ladder) or
+// resume a persisted one, subscribe, and wait for explicit MCP servers.
+// Everything here is side-effect free on the workspace, so a failure in
+// this phase is safe to retry with a fresh engine.
+async function openSession(client, {
   workspacePath,
   modelId,
   effort,
-  prompt,
-  timeoutMs,
   resumeSessionId = null,
   requiredMcp = [],
   onEvent = () => {},
+}) {
+  const session = { sessionId: null, resumed: false, mode: null };
+  if (resumeSessionId) {
+    const resumed = await client.request(
+      'session/resume',
+      { sessionId: resumeSessionId, thoughtLevel: effort },
+      { timeoutMs: 30000 }
+    );
+    const s = resumed.session || resumed.value || {};
+    session.sessionId = s.sessionId || resumeSessionId;
+    session.resumed = true;
+    session.mode = s.mode || null;
+    await client.request('session/setMode', { sessionId: session.sessionId, mode: 'yolo' }, { timeoutMs: 15000 });
+    session.mode = 'yolo';
+  } else {
+    const created = await client.request(
+      'session/create',
+      {
+        workspace: { workspacePath, workspaceKey: workspaceKeyFor(workspacePath) },
+        mode: 'yolo',
+        model: { providerId: 'zai-api', modelId, options: { reasoningLevel: effort } },
+        thoughtLevel: effort,
+        // Persist the session row NOW: the default (deferred) loses it to
+        // our SIGKILL on exit, and resume then 404s (-32004).
+        persistence: 'immediate',
+      },
+      { timeoutMs: 30000 }
+    );
+    const s = created.session || created.value || {};
+    session.sessionId = s.sessionId;
+    session.mode = s.mode || null;
+    if (!session.sessionId) throw new TurnError('session/create returned no session.sessionId');
+    // §9.1 mode ladder: create's mode param is not honored (live-probed).
+    if (s.mode !== 'yolo') {
+      await client.request('session/setMode', { sessionId: session.sessionId, mode: 'yolo' }, { timeoutMs: 15000 });
+      session.mode = 'yolo';
+    }
+  }
+  await client.request(
+    'session/subscribe',
+    { sessionId: session.sessionId, deliveryKind: 'desktop-continuous' },
+    { timeoutMs: 15000 }
+  );
+  await waitForMcp(client, { workspacePath, required: requiredMcp, onEvent });
+  return session;
+}
+
+// Sends one prompt into an open session and waits for its terminal event.
+// Resolves the turn facts; rejects with TurnError (kind: timeout |
+// cancelled | user_input | terminal_failed | result_type | no_completion).
+// On timeout or abort the engine is told to stop the active prompt
+// (session/stop) before we give up on it, so no tool keeps running behind
+// our back while the caller tears the engine down.
+async function runTurn(client, session, {
+  modelId,
+  effort,
+  prompt,
+  deadline,
+  signal = null,
+  keepReasoning = false,
+  onEvent = () => {},
 }) {
   const started = Date.now();
   const turn = {
-    sessionId: null,
-    resumed: false,
-    mode: null,
     response: '',
     usage: null,
     engineModel: null,
@@ -247,25 +346,30 @@ async function executeTurn(client, {
     engineReasoningLevel: null,
     terminalStatus: null,
     streamingEvents: 0,
+    reasoningChars: 0,
     reasoningText: '',
     toolCallCount: null,
     toolEvents: 0,
-    userInputFailure: null,
+    userInput: null,
+    durationMs: 0,
   };
 
-  const deadline = started + timeoutMs;
-  let completed = null; // {payload} from turn.completed
+  let completed = null;
   let failed = null;
   let completer = null;
   const completion = new Promise((resolve) => { completer = resolve; });
+  const fail = (err) => {
+    if (!failed && !completed) failed = err;
+    completer();
+  };
 
   client.onUserInputRequest = (frame) => {
-    turn.userInputFailure = frame;
-    failed = new TurnError(
-      'headless run requested user input: ' + client.scrub(JSON.stringify(frame.params || {}).slice(0, 800)),
-      { kind: 'user_input' }
+    const params = frame.params || {};
+    const question = client.scrub(
+      String(params.message || params.prompt || params.question || JSON.stringify(params)).slice(0, 800)
     );
-    completer();
+    turn.userInput = question;
+    fail(new TurnError(`headless run requested user input: ${question}`, { kind: 'user_input' }));
   };
 
   client.onFrame = (frame) => {
@@ -273,158 +377,109 @@ async function executeTurn(client, {
     const params = frame.params || {};
     if (method === 'session/event') {
       const type = params.type;
-      if (type === 'model.streaming' && params.payload) {
+      const payload = params.payload;
+      if (type === 'model.streaming' && payload) {
         turn.streamingEvents++;
-        if (params.payload.kind === 'reasoning_delta' && typeof params.payload.delta === 'string') {
-          turn.reasoningText += params.payload.delta;
+        if (payload.kind === 'reasoning_delta' && typeof payload.delta === 'string') {
+          turn.reasoningChars += payload.delta.length;
+          if (keepReasoning) turn.reasoningText += payload.delta;
         }
-        onEvent({ type: 'stream', kind: params.payload.kind, delta: params.payload.delta });
-      } else if (type === 'tool.updated' && params.payload) {
+        onEvent({ type: 'stream', kind: payload.kind, delta: payload.delta });
+      } else if (type === 'tool.updated' && payload) {
         // Engine tool lifecycle: scheduled|started|progress|result|error|…
         turn.toolEvents++;
         onEvent({
           type: 'tool',
-          phase: params.payload.kind ?? null,
-          name: params.payload.toolName ?? null,
-          id: params.payload.toolCallId ?? null,
+          phase: payload.kind ?? null,
+          name: payload.toolName ?? null,
+          id: payload.toolCallId ?? null,
         });
-      } else if (type === 'turn.completed' && params.payload) {
-        completed = params.payload;
-        turn.response = typeof params.payload.response === 'string' ? params.payload.response : turn.response;
-        turn.usage = params.payload.usage || turn.usage;
-        if (typeof params.payload.toolCallCount === 'number') {
-          turn.toolCallCount = params.payload.toolCallCount;
-        }
+      } else if (type === 'turn.completed' && payload) {
+        completed = payload;
+        turn.response = typeof payload.response === 'string' ? payload.response : turn.response;
+        turn.usage = payload.usage || turn.usage;
+        if (typeof payload.toolCallCount === 'number') turn.toolCallCount = payload.toolCallCount;
         completer();
       } else if (type === 'turn.started') {
         onEvent({ type: 'turn', phase: 'started', turnId: params.turnId });
-      } else if (type === 'session.updated' && params.payload && params.payload.type === 'model_request_started') {
-        turn.engineProvider = params.payload.providerId ?? turn.engineProvider;
-        turn.engineModel = params.payload.modelId ?? turn.engineModel;
-        turn.engineReasoningLevel =
-          params.payload.modelCall?.reasoning?.requestedLevel ?? turn.engineReasoningLevel;
+      } else if (type === 'session.updated' && payload && payload.type === 'model_request_started') {
+        turn.engineProvider = payload.providerId ?? turn.engineProvider;
+        turn.engineModel = payload.modelId ?? turn.engineModel;
+        turn.engineReasoningLevel = payload.modelCall?.reasoning?.requestedLevel ?? turn.engineReasoningLevel;
         onEvent({
           type: 'model_request_started',
-          providerId: params.payload.providerId,
-          modelId: params.payload.modelId,
-          reasoningLevel: params.payload.modelCall?.reasoning?.requestedLevel ?? null,
+          providerId: payload.providerId,
+          modelId: payload.modelId,
+          reasoningLevel: payload.modelCall?.reasoning?.requestedLevel ?? null,
         });
       }
     } else if (method === 'state.updated') {
       const patch = params.patch || {};
-      if (patch.mode && patch.mode.current) {
-        turn.mode = patch.mode.current;
-        onEvent({ type: 'state', mode: patch.mode.current });
-      }
+      if (patch.mode && patch.mode.current) onEvent({ type: 'state', mode: patch.mode.current });
     } else if (method === 'v4/telemetry/event' && params.kind === 'turn.terminal') {
       turn.terminalStatus = params.status ?? turn.terminalStatus;
       if (params.status === 'failed') {
-        failed = new TurnError(
+        fail(new TurnError(
           `turn.terminal failed: ${client.scrub(JSON.stringify(params.result || params).slice(0, 800))}`,
           { kind: 'terminal_failed' }
-        );
-        completer();
+        ));
       }
     }
   };
+  const prevOnExit = client.onExit;
+  client.onExit = (err) => fail(new TurnError(client.scrub(err.message), { kind: 'engine_exit' }));
+
+  const remaining = Math.max(0, deadline - Date.now());
+  const timer = setTimeout(
+    () => fail(new TurnError('run exceeded --timeout-ms', { kind: 'timeout' })),
+    remaining
+  );
+  const onAbort = () => fail(new TurnError('cancelled', { kind: 'cancelled' }));
+  if (signal) {
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
 
   try {
-    if (resumeSessionId) {
-      // Continue a persisted session from a previous CLI invocation.
-      const resumed = await client.request(
-        'session/resume',
-        { sessionId: resumeSessionId, thoughtLevel: effort },
-        { timeoutMs: 30000 }
-      );
-      const session = resumed.session || resumed.value || {};
-      turn.sessionId = session.sessionId || resumeSessionId;
-      turn.resumed = true;
-      turn.mode = session.mode || null;
-      await client.request(
-        'session/setMode',
-        { sessionId: turn.sessionId, mode: 'yolo' },
-        { timeoutMs: 15000 }
-      );
-      turn.mode = 'yolo';
-    } else {
-      const created = await client.request(
-        'session/create',
-        {
-          workspace: { workspacePath, workspaceKey: workspaceKeyFor(workspacePath) },
-          mode: 'yolo',
-          model: {
-            providerId: 'zai-api',
-            modelId,
-            options: { reasoningLevel: effort },
+    if (!failed) {
+      await Promise.race([
+        client.request(
+          'session/send',
+          {
+            sessionId: session.sessionId,
+            content: prompt,
+            modelSelection: { providerId: 'zai-api', modelId, options: { reasoningLevel: effort } },
           },
-          thoughtLevel: effort,
-          // Persist the session row NOW: the default (deferred) loses it to
-          // our SIGKILL on exit, and --session resume then 404s (-32004).
-          persistence: 'immediate',
-        },
-        { timeoutMs: 30000 }
-      );
-      const session = created.session || created.value || {};
-      turn.sessionId = session.sessionId;
-      turn.mode = session.mode || null;
-      if (!turn.sessionId) throw new TurnError('session/create returned no session.sessionId');
-
-      // §9.1 mode ladder: create's mode param is not honored (live-probed);
-      // force yolo and record it.
-      if (session.mode !== 'yolo') {
-        await client.request('session/setMode', { sessionId: turn.sessionId, mode: 'yolo' }, { timeoutMs: 15000 });
-        turn.mode = 'yolo';
-      }
+          { timeoutMs: 30000 }
+        ),
+        completion,
+      ]);
     }
-
-    await client.request(
-      'session/subscribe',
-      { sessionId: turn.sessionId, deliveryKind: 'desktop-continuous' },
-      { timeoutMs: 15000 }
-    );
-    await waitForMcp(client, { workspacePath, required: requiredMcp, onEvent });
-    await client.request(
-      'session/send',
-      {
-        sessionId: turn.sessionId,
-        content: prompt,
-        modelSelection: {
-          providerId: 'zai-api',
-          modelId,
-          options: { reasoningLevel: effort },
-        },
-      },
-      { timeoutMs: 30000 }
-    );
-
-    const wait = setInterval(() => {
-      if (Date.now() > deadline && !completed && !failed) {
-        failed = new TurnError(`run exceeded --timeout-ms ${timeoutMs}`, { kind: 'timeout' });
-        completer();
+    await completion;
+    if (failed) {
+      if (['timeout', 'cancelled', 'user_input'].includes(failed.kind)) {
+        await client.stopSession(session.sessionId);
       }
-    }, 500);
-    try {
-      await completion;
-    } finally {
-      clearInterval(wait);
+      throw failed;
     }
-
-    if (failed) throw failed;
-    if (!completed) throw new TurnError('turn ended without a completion event', { kind: 'no_completion' });
     if (completed.resultType && completed.resultType !== 'success') {
       throw new TurnError(`turn completed with resultType "${completed.resultType}"`, { kind: 'result_type' });
     }
     turn.durationMs = Date.now() - started;
     return turn;
   } finally {
+    clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
     client.onFrame = null;
     client.onUserInputRequest = null;
+    client.onExit = prevOnExit;
   }
 }
 
 module.exports = {
   AppServerClient,
-  executeTurn,
+  openSession,
+  runTurn,
   TurnError,
   workspaceKeyFor,
   waitForMcp,

package/lib/bootstrap.js

@@ -1,7 +1,8 @@
 'use strict';
-// Shared bootstrap for turn commands (run/agent): resolves key, engine,
-// builtin config and the scratch HOME, then builds an AppServerClient.
-// Exits with the documented codes (3 no key, 4 no engine/builtin config).
+// Resolves everything an engine spawn needs — key, engine bundle, builtin
+// provider config, node binary — and builds engine clients. Throws
+// ConfigError carrying the documented exit code (3 no key, 4 no engine /
+// builtin config) instead of exiting, so callers decide how to report.
 const { resolveKey, NoKeyError } = require('./key.js');
 const {
   resolveEngine,
@@ -9,81 +10,59 @@ const {
   EngineNotFoundError,
   BuiltinConfigNotFoundError,
 } = require('./engine.js');
-const { ensureIsolation, engineEnv } = require('./isolation.js');
-const { applyMcpOverlay, applySkillsOverlay } = require('./overlay.js');
+const { engineEnv } = require('./isolation.js');
 const { AppServerClient } = require('./appserver.js');
 
-// Returns a function that replaces the API key with *** in any text that is
-// about to be printed or dumped (defense in depth — the engine never echoes
-// the key, but exit-5 dumps raw frames).
+class ConfigError extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+// Replaces the API key with *** in any text that is about to be printed or
+// stored (defense in depth — the engine never echoes the key, but error
+// paths dump raw frames).
 function makeScrub(key) {
-  return (text) => String(text).split(key).join('***');
+  return (text) => (key ? String(text).split(key).join('***') : String(text));
 }
 
-function bootstrap({
-  fresh = false,
-  mcpSpecs = [],
-  mcpInherit = false,
-  skillsDirs = [],
-  noSkills = false,
-} = {}) {
+function resolveRuntime(env = process.env) {
   let key;
   try {
-    key = resolveKey(process.env);
+    key = resolveKey(env);
   } catch (err) {
-    if (err instanceof NoKeyError) {
-      process.stderr.write(`zcode: ${err.message}\n`);
-      process.exit(3);
-    }
+    if (err instanceof NoKeyError) throw new ConfigError(err.message, 3);
     throw err;
   }
-  const scrub = makeScrub(key);
-
   let enginePath;
-  try {
-    enginePath = resolveEngine(process.env);
-  } catch (err) {
-    if (err instanceof EngineNotFoundError) {
-      process.stderr.write(`zcode: ${err.message}\n`);
-      process.exit(4);
-    }
-    throw err;
-  }
   let builtinConfig;
   try {
-    builtinConfig = resolveBuiltinProviderConfig(enginePath, process.env);
+    enginePath = resolveEngine(env);
+    builtinConfig = resolveBuiltinProviderConfig(enginePath, env);
   } catch (err) {
-    if (err instanceof BuiltinConfigNotFoundError) {
-      process.stderr.write(`zcode: ${err.message}\n`);
-      process.exit(4);
+    if (err instanceof EngineNotFoundError || err instanceof BuiltinConfigNotFoundError) {
+      throw new ConfigError(err.message, 4);
     }
     throw err;
   }
-
-  const isolation = ensureIsolation(key, { fresh, env: process.env });
-  // Per-run overlays: recomputed from read-only live sources + flags, so
-  // runs never inherit a previous run's additions (DESIGN §6 extension).
-  const mcp = applyMcpOverlay({ home: isolation.home, inherit: mcpInherit, mcpSpecs });
-  const skills = applySkillsOverlay({
-    rootDir: isolation.root,
-    home: isolation.home,
-    skillsDirs,
-    noSkills,
-  });
-  const overlay = { mcp, skills };
-  const nodeBin = process.env.ZAI_CODE_NODE || process.execPath;
-  const childEnv = engineEnv({
-    home: isolation.home,
-    builtinProviderConfig: builtinConfig,
-  });
-  const client = new AppServerClient({
-    nodeBin,
+  return {
+    key,
+    scrub: makeScrub(key),
     enginePath,
-    env: childEnv,
-    cwd: process.cwd(),
-    scrub,
+    builtinConfig,
+    nodeBin: env.ZAI_CODE_NODE || process.execPath,
+  };
+}
+
+function makeClient(runtime, { home, cwd }) {
+  return new AppServerClient({
+    nodeBin: runtime.nodeBin,
+    enginePath: runtime.enginePath,
+    env: engineEnv({ home, builtinProviderConfig: runtime.builtinConfig }),
+    cwd,
+    scrub: runtime.scrub,
   });
-  return { key, scrub, enginePath, builtinConfig, isolation, overlay, nodeBin, childEnv, client };
 }
 
-module.exports = { bootstrap, makeScrub };
+module.exports = { resolveRuntime, makeClient, makeScrub, ConfigError };

package/lib/checks.js

@@ -0,0 +1,103 @@
+'use strict';
+// Acceptance checks: shell commands from the task contract that zcode runs
+// ITSELF after the model's turn — the model's own claims are never the
+// verification evidence. Each check runs in its own process group (so a
+// timeout or cancel kills the whole tree), with a per-check timeout and a
+// bounded output tail. CI=1 is set when unset so test runners do not enter
+// watch/interactive mode.
+const { spawn } = require('node:child_process');
+
+const OUTPUT_TAIL = 4000;
+
+function killGroup(child) {
+  try {
+    process.kill(-child.pid, 'SIGKILL');
+  } catch {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* gone */
+    }
+  }
+}
+
+function runCheck(command, { cwd, timeoutMs = 300000, signal, env = process.env } = {}) {
+  const started = Date.now();
+  return new Promise((resolve) => {
+    let output = '';
+    let timedOut = false;
+    let cancelled = false;
+    const keep = (chunk) => {
+      output += chunk;
+      if (output.length > OUTPUT_TAIL * 2) output = output.slice(-OUTPUT_TAIL);
+    };
+    let child;
+    try {
+      child = spawn('/bin/sh', ['-c', command], {
+        cwd,
+        env: { ...env, CI: env.CI ?? '1' },
+        stdio: ['ignore', 'pipe', 'pipe'],
+        detached: true,
+      });
+    } catch (err) {
+      resolve({ command, ok: false, exitCode: null, timedOut: false, durationMs: 0, output: String(err.message) });
+      return;
+    }
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup(child);
+    }, timeoutMs);
+    const onAbort = () => {
+      cancelled = true;
+      killGroup(child);
+    };
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener('abort', onAbort, { once: true });
+    }
+    const finish = (exitCode, errText) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      const tail = (output + (errText ? `\n${errText}` : '')).slice(-OUTPUT_TAIL);
+      resolve({
+        command,
+        ok: exitCode === 0 && !timedOut && !cancelled,
+        exitCode,
+        timedOut,
+        cancelled,
+        durationMs: Date.now() - started,
+        output: tail,
+      });
+    };
+    child.on('error', (err) => finish(null, err.message));
+    child.on('close', (code) => finish(code));
+  });
+}
+
+// Runs every check in order (later checks still run when an earlier one
+// fails, so the handback carries complete evidence); stops on cancel.
+async function runChecks(commands, { cwd, timeoutMs, signal, onEvent = () => {} } = {}) {
+  const results = [];
+  for (const command of commands) {
+    if (signal && signal.aborted) break;
+    onEvent({ type: 'check', phase: 'started', command });
+    const r = await runCheck(command, { cwd, timeoutMs, signal });
+    results.push(r);
+    onEvent({
+      type: 'check',
+      phase: 'finished',
+      command,
+      ok: r.ok,
+      exitCode: r.exitCode,
+      timedOut: r.timedOut,
+      durationMs: r.durationMs,
+    });
+  }
+  return results;
+}
+
+module.exports = { runCheck, runChecks, OUTPUT_TAIL };