mixdog 1.2.2 → 1.2.3

package/src/runtime/computer-bridge/action-schema.mjs

@@ -1,6 +1,7 @@
 import { splitBridgeToolArgs } from '../shared/bridge-tool-args.mjs';
 import { hasOwn } from '../shared/object.mjs';
 import { schemaValueError } from '../shared/schema-value-error.mjs';
+import { advertiseActionInputUnion } from '../agent/orchestrator/providers/lib/action-input-contract.mjs';
 import {
   COMPUTER_CORE_ACTION_SCHEMA,
   COMPUTER_DEFAULT_DELIVERY,
@@ -149,25 +150,11 @@ const captureProperties = {
   },
 };
 
-export const COMPUTER_INPUT_SCHEMA = {
-  type: 'object',
-  description:
-    'One compact Computer Use operation. Use act.actions to execute 1-6 simple actions and receive one fresh observation.',
-  properties: {
-    action: {
-      type: 'string',
-      enum: ACTIONS,
-      description:
-        'Use capture to observe, act for simple input actions, and the remaining operations only for their named advanced capability.',
-    },
-    input: {
-      type: 'object',
-      description: 'Fields for the selected action.',
-    },
-  },
-  required: ['action'],
-  additionalProperties: false,
-  oneOf: [
+// The strict per-action contract: which `input` each action accepts. The host
+// validates every call against it (validateComputerToolArgs), and the model-facing
+// schema below derives its `input` from it. It is not part of the advertised
+// root: provider tool schemas must be an object root without anyOf/oneOf/allOf.
+export const COMPUTER_ACTION_CONTRACTS = [
     branch(
       'wait_for_user',
       input({
@@ -360,11 +347,47 @@ export const COMPUTER_INPUT_SCHEMA = {
         ['app']
       )
     ),
-  ],
+];
+
+// A JSON Schema 2020-12 object root with no root combinator (Anthropic
+// input_schema rule) whose `input` offers each action's own input as an anyOf
+// alternative titled with that action. The tool advertises its flat projection
+// (flattenActionInputUnion); only provider paths verified to accept the nested
+// alternatives (first-party Anthropic, Claude via Antigravity) send this form
+// (actionInputUnionFor). validateComputerToolArgs enforces the strict
+// per-action contract.
+const COMPUTER_ACTION_INPUT_UNION = {
+  type: 'object',
+  description:
+    'One compact Computer Use operation. Use act.actions to execute 1-6 simple actions and receive one fresh observation.',
+  properties: {
+    action: {
+      type: 'string',
+      enum: ACTIONS,
+      description:
+        'Use capture to observe, act for simple input actions, and the remaining operations only for their named advanced capability.',
+    },
+    input: {
+      type: 'object',
+      description: 'Fields for the selected action.',
+      anyOf: COMPUTER_ACTION_CONTRACTS.map(({ properties }) => {
+        const [action] = properties.action.enum;
+        return {
+          title: action,
+          description: `Input when action="${action}".`,
+          ...structuredClone(properties.input),
+        };
+      }),
+    },
+  },
+  required: ['action'],
+  additionalProperties: false,
 };
 
+export const COMPUTER_INPUT_SCHEMA = advertiseActionInputUnion(COMPUTER_ACTION_INPUT_UNION);
+
 const COMPUTER_ACTION_BRANCHES = new Map();
-for (const actionBranch of COMPUTER_INPUT_SCHEMA.oneOf) {
+for (const actionBranch of COMPUTER_ACTION_CONTRACTS) {
   for (const action of actionBranch.properties?.action?.enum || []) {
     COMPUTER_ACTION_BRANCHES.set(action, actionBranch);
   }

package/src/runtime/github/tool.mjs

@@ -61,6 +61,96 @@ function reduceGithubData(value, key, parentKey) {
   return reduced;
 }
 
+const EXCERPT_MAX = 140;
+const day = (value) => (typeof value === 'string' ? value.slice(0, 10) : undefined);
+const login = (value) => userLogin(value) ?? (typeof value === 'string' ? value : undefined);
+
+function excerpt(body) {
+  if (typeof body !== 'string') return undefined;
+  const text = body.replace(/\s+/g, ' ').trim();
+  if (!text) return undefined;
+  return text.length > EXCERPT_MAX ? `${text.slice(0, EXCERPT_MAX - 1)}…` : text;
+}
+
+function labelNames(labels) {
+  const names = (Array.isArray(labels) ? labels : [])
+    .map((label) => (typeof label === 'string' ? label : label?.name))
+    .filter(Boolean);
+  return names.length ? names : undefined;
+}
+
+// Compact per-row projections for *.list actions: only what picks the next item
+// to open. Undefined fields are dropped by JSON.stringify.
+const LIST_PROJECTORS = {
+  'issue.list': (item) => ({
+    number: item.number,
+    title: item.title,
+    state: item.state,
+    author: login(item.user),
+    updated: day(item.updated_at),
+    labels: labelNames(item.labels),
+    comments: item.comments || undefined,
+    excerpt: excerpt(item.body),
+  }),
+  'pr.list': (item) => ({
+    number: item.number,
+    title: item.title,
+    state: item.merged_at ? 'merged' : item.state,
+    draft: item.draft || undefined,
+    author: login(item.user),
+    updated: day(item.updated_at),
+    head: item.head?.ref,
+    base: item.base?.ref,
+    labels: labelNames(item.labels),
+    excerpt: excerpt(item.body),
+  }),
+  'repo.list': (item) => ({
+    name: item.full_name,
+    description: excerpt(item.description),
+    visibility: item.visibility || (item.private ? 'private' : 'public'),
+    language: item.language || undefined,
+    fork: item.fork || undefined,
+    archived: item.archived || undefined,
+    updated: day(item.pushed_at || item.updated_at),
+  }),
+  'run.list': (item) => ({
+    id: item.id,
+    name: item.display_title || item.name,
+    workflow: item.name,
+    status: item.status,
+    conclusion: item.conclusion || undefined,
+    branch: item.head_branch,
+    event: item.event,
+    actor: login(item.actor),
+    updated: day(item.updated_at),
+  }),
+  'release.list': (item) => ({
+    id: item.id,
+    tag: item.tag_name,
+    name: item.name || undefined,
+    draft: item.draft || undefined,
+    prerelease: item.prerelease || undefined,
+    author: login(item.author),
+    published: day(item.published_at || item.created_at),
+  }),
+  'notification.list': (item) => ({
+    id: item.id,
+    unread: item.unread,
+    reason: item.reason,
+    type: item.subject?.type,
+    title: item.subject?.title,
+    number: Number(/\/(?:issues|pulls)\/(\d+)$/.exec(item.subject?.url || '')?.[1]) || undefined,
+    repo: typeof item.repository === 'string' ? item.repository : item.repository?.full_name,
+    updated: day(item.updated_at),
+  }),
+  'workflow.list': (item) => ({ id: item.id, name: item.name, path: item.path, state: item.state }),
+};
+
+function projectList(action, data) {
+  const project = LIST_PROJECTORS[action];
+  return project && Array.isArray(data) ? data.map(project) : undefined;
+}
+
 const fits = (text) => Buffer.byteLength(text, 'utf8') <= GITHUB_OUTPUT_MAX_BYTES;
 
 function clampStrings(value, max) {
@@ -213,7 +303,7 @@ export const GITHUB_TOOL_DEF = {
   },
   trigger: 'GitHub repos, issues, PRs, Actions, releases; not local Git history, diffs or staging (git).',
   description:
-    'GitHub repositories, issues, PRs and reviews, Actions/logs, releases, and notifications through the signed-in GitHub CLI. Local Git history/diffs/staging belong to git. One action per call; writes are serialized and never retried. Obtain user approval before writes; workflow runs and published releases may deploy. repo is owner/name; omit to resolve the current Project. Lists use page/limit. Review/merge requires the current PR head sha. Install/connect in Extensions → Plugin → Git & GitHub. Results omit API-only URLs and node ids and name users/repos by login/full_name; `raw` is a readable file with the full response, and long results state what is shown.',
+    'GitHub repositories, issues, PRs and reviews, Actions/logs, releases, and notifications through the signed-in GitHub CLI. Local Git history/diffs/staging belong to git. One action per call; writes are serialized and never retried. Obtain user approval before writes; workflow runs and published releases may deploy. repo is owner/name; omit to resolve the current Project. Lists use page/limit and return compact rows (issues/PRs: number, title, state, author, updated, labels, 140-char excerpt; other lists: ids and status fields); open a row with its *.view action for bodies and details. Review/merge requires the current PR head sha. Install/connect in Extensions → Plugin → Git & GitHub. Results omit API-only URLs and node ids and name users/repos by login/full_name; `raw` is a readable file with the full response, and long results state what is shown.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -267,7 +357,7 @@ export const GITHUB_TOOL_DEF = {
 export async function executeGithubTool(args, cwd, options = {}) {
   try {
     const result = await executeGithubRequest(args, cwd, options);
-    const reduced = { ...result, data: reduceGithubData(result.data) };
+    const reduced = { ...result, data: projectList(args.action, result.data) ?? reduceGithubData(result.data) };
     const text = JSON.stringify(reduced);
     if (text === JSON.stringify(result) && fits(text)) return text;
     const raw = persistToolResultArtifactSync({

package/src/runtime/memory/index.mjs

@@ -532,6 +532,7 @@ const _httpRouter = createHttpRouter({
     _traceDb = v;
   },
   ingestTranscriptFile,
+  forgetTranscripts: _transcriptIngest.forgetTranscripts,
   getTranscriptOffset: (fp) => _transcriptIngest.getOffset(fp),
   parseTsToMs,
   refreshCoreMemoryFile: refreshCoreMemorySnapshot,

package/src/runtime/memory/lib/http-router/ingest-routes.mjs

@@ -15,7 +15,14 @@ const INSERT_ENTRY = `
             RETURNING id
           `;
 
-export function createIngestHandler({ getDb, log, ingestTranscriptFile, getTranscriptOffset, parseTsToMs }) {
+export function createIngestHandler({
+  getDb,
+  log,
+  ingestTranscriptFile,
+  forgetTranscripts,
+  getTranscriptOffset,
+  parseTsToMs,
+}) {
   const entry = async (body, res) => {
     const db = getDb();
     const role = String(body.role ?? 'user');
@@ -89,9 +96,23 @@ export function createIngestHandler({ getDb, log, ingestTranscriptFile, getTrans
     }
   };
 
+  const forgetTranscript = async (body, res) => {
+    const filePaths = body.filePaths;
+    if (!Array.isArray(filePaths) || filePaths.some((filePath) => typeof filePath !== 'string' || !filePath)) {
+      sendJson(res, { error: 'filePaths required' }, 400);
+      return;
+    }
+    try {
+      sendJson(res, { ok: true, removed: await forgetTranscripts(filePaths) });
+    } catch (e) {
+      sendJson(res, { error: e.message }, 500);
+    }
+  };
+
   const routes = {
     '/entry': entry,
     '/ingest-transcript': ingestTranscript,
+    '/transcript/forget': forgetTranscript,
     '/transcript/ingest-sync': ingestSync,
   };
 

package/src/runtime/memory/lib/ingest/transcript-offsets.mjs

@@ -47,6 +47,8 @@ export function createTranscriptOffsets({ loadMeta, persistMeta, log }) {
     set: (transcriptPath, position) => {
       offsets.set(transcriptPath, position);
     },
+    /** Drop one file's read position; true when an entry existed. */
+    forget: (transcriptPath) => offsets.delete(transcriptPath),
     reset: () => {
       offsets = new Map();
     },

package/src/runtime/memory/lib/pg/adapter.mjs

@@ -90,7 +90,9 @@ function installPoolErrorHandler(pool, label, { onConnectionLoss } = {}) {
 //   db.transaction(async tx => …)  → auto BEGIN/COMMIT, ROLLBACK on throw
 
 import { resolve } from 'node:path';
-import { ensurePgInstance as supervisorEnsure } from './supervisor.mjs';
+import { ensurePgInstance as supervisorEnsure, stopOwnedPgForShutdown } from './supervisor.mjs';
+
+export { installOwnedPgExitStop, pgClusterExists } from './supervisor.mjs';
 
 // ---------------------------------------------------------------------------
 // One-shot bootstrap guard — keyed by resolved dataDir (cluster-level, not schema)
@@ -164,6 +166,52 @@ export async function checkedConnect(pgPool, schema) {
   return client;
 }
 
+// ---------------------------------------------------------------------------
+// Durable-operation tracking — a shutdown lets these settle before PG stops
+// ---------------------------------------------------------------------------
+
+/** Schemas holding only data rebuilt from another source of truth: the
+ *  session-search copy (re-ingested from the session files by its backfill)
+ *  and trace diagnostics. Every other schema (scheduler, webhooks, memory)
+ *  holds the only copy, so its in-flight operations are drained first. */
+const DERIVED_SCHEMAS = new Set(['session_search', 'trace']);
+const _durableInFlight = new Set();
+
+function trackDurable(schema, run) {
+  if (DERIVED_SCHEMAS.has(schema)) return run();
+  const op = run();
+  _durableInFlight.add(op);
+  const settle = () => _durableInFlight.delete(op);
+  op.then(settle, settle);
+  return op;
+}
+
+/** In-flight operations on durable schemas right now. */
+export function pendingDurablePgOps() {
+  return _durableInFlight.size;
+}
+
+/**
+ * Wait, bounded, until no durable-schema operation is in flight (including
+ * ones issued while waiting). Resolves true when drained, false at the bound.
+ */
+export async function drainDurablePgOps({ timeoutMs = 0 } = {}) {
+  const deadline = Date.now() + Math.max(0, Number(timeoutMs) || 0);
+  while (_durableInFlight.size > 0) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+    let timer = null;
+    await Promise.race([
+      Promise.allSettled([..._durableInFlight]),
+      new Promise((resolveBound) => {
+        timer = setTimeout(resolveBound, remaining);
+      }),
+    ]);
+    clearTimeout(timer);
+  }
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // native PG db shim
 // ---------------------------------------------------------------------------
@@ -253,6 +301,12 @@ function makeCompatDb(pgPool, schema, dataDir) {
       return currentPool();
     },
   };
+  // Every statement entry point is tracked, so a shutdown can let durable
+  // writes settle before it stops the cluster.
+  const { query, exec, transaction } = db;
+  db.query = (sql, params) => trackDurable(schema, () => query(sql, params));
+  db.exec = (sql) => trackDurable(schema, () => exec(sql));
+  db.transaction = (fn) => trackDurable(schema, () => transaction(fn));
   return db;
 }
 
@@ -522,3 +576,46 @@ export async function closePgInstance(dataDir, opts = {}) {
   } catch {}
   instances.delete(key);
 }
+
+// ---------------------------------------------------------------------------
+// shutdownOwnedPg — process exit: every pool, then the cluster this process owns
+// ---------------------------------------------------------------------------
+
+export const POOL_CLOSE_BOUND_MS = 500;
+
+/**
+ * For a host whose stores start PostgreSQL (the daemon's schedules/webhooks/
+ * session-search): stop the cluster it ensured (supervisor
+ * stopOwnedPgForShutdown, `pg_ctl stop -m fast`) while every pool this process
+ * opened ends alongside — a pool waiting on a checked-out client never holds
+ * the stop back. The stop latches the supervisor first (synchronously), so a
+ * pooled client that sees fast shutdown terminate its backend cannot restart
+ * PG through connection-loss recovery; the pools are dropped from the cache,
+ * and their close is waited on only for a short bound after the stop.
+ */
+export async function shutdownOwnedPg({ timeoutMs, drainMs = 0 } = {}) {
+  // Durable writes still in flight (schedule/webhook state) commit first,
+  // bounded by `drainMs`; derived writes (session search, trace) are not
+  // waited on — their sources rebuild them.
+  if (!(await drainDurablePgOps({ timeoutMs: drainMs }))) {
+    __mixdogMemoryLog(
+      `[pg-adapter] stopping PG with ${_durableInFlight.size} durable operation(s) still in flight after ${drainMs}ms\n`
+    );
+  }
+  const pools = [...instances.values()].map((inst) => inst.pool);
+  instances.clear();
+  const stopping = stopOwnedPgForShutdown({ timeoutMs });
+  const closing = Promise.allSettled(pools.map((pool) => pool.end()));
+  try {
+    return await stopping;
+  } finally {
+    let timer = null;
+    await Promise.race([
+      closing,
+      new Promise((resolveBound) => {
+        timer = setTimeout(resolveBound, POOL_CLOSE_BOUND_MS);
+      }),
+    ]);
+    clearTimeout(timer);
+  }
+}

package/src/runtime/memory/lib/pg/process.mjs

@@ -5,8 +5,11 @@ import { sleep as delay } from '../../../shared/sleep.mjs';
 //
 // Public API:
 //   startPg({ runtimeDir, pgdataDir, port?, logPath? }) → { pid, port }
-//   stopPg({ runtimeDir, pgdataDir })                   → void
+//   stopPg({ runtimeDir, pgdataDir, timeoutMs? })       → void
 //   healthcheckPg({ port, host? })                      → boolean
+//
+// Every child on the start/stop path (initdb, pg_ctl start/reload/status/stop)
+// runs async; only stopPgSync — a process 'exit' hook — may block.
 
 import {
   existsSync,
@@ -24,6 +27,7 @@ import { join } from 'node:path';
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import { createConnection, createServer } from 'node:net';
 import { isPidAlive } from '../../../shared/pid-liveness.mjs';
+import { runChild } from './run-child.mjs';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -201,14 +205,12 @@ function ensureConfV2(pgdataDir) {
 // callers route through this rather than re-implementing the conf/reload pair.
 // Reload-compatible settings apply immediately; postmaster settings such as
 // max_connections apply on the next normal PG start (never restart live work).
-export function reconcileConfV2(runtimeDir, pgdataDir) {
+export async function reconcileConfV2(runtimeDir, pgdataDir) {
   const applied = ensureConfV2(pgdataDir);
   if (!applied) return { applied: false, reloaded: false };
-  const reload = spawnSync(pgBin(runtimeDir, 'pg_ctl'), ['reload', '-D', pgdataDir], {
+  const reload = await runChild(pgBin(runtimeDir, 'pg_ctl'), ['reload', '-D', pgdataDir], {
     env: libEnv(runtimeDir),
-    stdio: 'pipe',
-    timeout: 5_000,
-    windowsHide: true,
+    timeoutMs: 5_000,
   });
   const reloaded = reload.status === 0;
   if (reloaded) {
@@ -238,7 +240,7 @@ async function attachExistingPostmaster({ runtimeDir, pgdataDir, existingWaitMs,
     __mixdogMemoryLog(`[pg-process] attaching to existing PG pid=${existing.pid} port=${existing.port}\n`);
     // Route through the single reconcile entry point so v1 → v2 conf
     // upgrades land on already-running instances without restart.
-    if (v2Applied) reconcileConfV2(runtimeDir, pgdataDir);
+    if (v2Applied) await reconcileConfV2(runtimeDir, pgdataDir);
     return { pid: existing.pid, port: existing.port, attached: true };
   }
   if (existing.state === 'alive-not-ready') {
@@ -259,6 +261,10 @@ async function attachExistingPostmaster({ runtimeDir, pgdataDir, existingWaitMs,
 // default_transaction_isolation: native PG default is read committed.
 // Native PG does not default to serializable; set isolation level explicitly
 // so behaviour is unambiguous across PG major versions.
+// Carries every versioned block ensureConfV2 checks for, so a fresh cluster
+// already holds what later boots expect: none of them rewrites the conf and
+// pg_ctl-reloads it (a postmaster-only setting such as shared_buffers cannot
+// change by reload, and every such reload logged an error).
 function freshClusterConfAppend() {
   return (
     [
@@ -279,7 +285,8 @@ function freshClusterConfAppend() {
     ].join('\n') +
     '\n' +
     buildV2Block() +
-    buildV3Block()
+    buildV3Block() +
+    buildV4Block()
   );
 }
 
@@ -290,14 +297,14 @@ function freshClusterConfAppend() {
  * user profile). Such a share dir is passed through an ASCII junction under
  * %ProgramData% that is removed afterwards.
  */
-export function withInitdbShareDir(runtimeDir, run) {
+export async function withInitdbShareDir(runtimeDir, run) {
   const shareDir = join(runtimeDir, 'share');
   if (process.platform !== 'win32' || /^[\x20-\x7e]*$/.test(shareDir)) return run(null);
   const linkRoot = mkdtempSync(join(process.env.ProgramData, 'mixdog-initdb-'));
   const link = join(linkRoot, 'share');
   try {
     symlinkSync(shareDir, link, 'junction');
-    return run(link);
+    return await run(link);
   } finally {
     // Cleanup must not replace initdb's own result or error. Both removals are
     // non-recursive, so the junction target (the runtime share) is never touched.
@@ -312,11 +319,11 @@ export function withInitdbShareDir(runtimeDir, run) {
 }
 
 /** initdb if pgdata is not yet initialised (no PG_VERSION file). */
-function initClusterIfNeeded({ runtimeDir, pgdataDir, env }) {
+async function initClusterIfNeeded({ runtimeDir, pgdataDir, env }) {
   if (existsSync(join(pgdataDir, 'PG_VERSION'))) return;
   __mixdogMemoryLog(`[pg-process] initdb → ${pgdataDir}\n`);
-  const r = withInitdbShareDir(runtimeDir, (shareDir) =>
-    spawnSync(
+  const r = await withInitdbShareDir(runtimeDir, (shareDir) =>
+    runChild(
       pgBin(runtimeDir, 'initdb'),
       [
         '-D',
@@ -329,7 +336,7 @@ function initClusterIfNeeded({ runtimeDir, pgdataDir, env }) {
         '-U',
         'postgres',
       ],
-      { env, stdio: 'pipe', windowsHide: true }
+      { env }
     )
   );
   if (r.status !== 0) {
@@ -435,12 +442,7 @@ async function startAndWaitReady({ pgctl, startArgs, env, pgdataDir, port }) {
  */
 async function attachRaceWinner({ pgdataDir, pgctl, env, existingWaitMs }) {
   __mixdogMemoryLog(`[pg-process] pg_ctl start: "another server might be running" — probing status\n`);
-  const statusR = spawnSync(pgctl, ['status', '-D', pgdataDir], {
-    env,
-    stdio: 'pipe',
-    timeout: 3_000,
-    windowsHide: true,
-  });
+  const statusR = await runChild(pgctl, ['status', '-D', pgdataDir], { env, timeoutMs: 3_000 });
   __mixdogMemoryLog(
     `[pg-process] pg_ctl status: ${statusR.stdout?.toString() || statusR.stderr?.toString() || 'no output'}\n`
   );
@@ -480,7 +482,7 @@ export async function startPg({
   if (attached) return attached;
 
   const pgctl = pgBin(runtimeDir, 'pg_ctl');
-  initClusterIfNeeded({ runtimeDir, pgdataDir, env });
+  await initClusterIfNeeded({ runtimeDir, pgdataDir, env });
   // PostgreSQL requires a completely empty target on first init. Creating the
   // Spotlight marker before initdb makes every fresh macOS cluster fail with
   // "directory exists but is not empty"; add it only after initialization.
@@ -511,15 +513,18 @@ export async function startPg({
 // stopPg
 // ---------------------------------------------------------------------------
 
-export async function stopPg({ runtimeDir, pgdataDir }) {
+// Bounded graceful stop. `-m fast` rolls back open transactions and
+// disconnects clients; pg_ctl's own wait (-t, whole seconds) and the child
+// timeout share `timeoutMs`, so a wedged stop rejects instead of holding a
+// shutdown sequence open.
+export async function stopPg({ runtimeDir, pgdataDir, timeoutMs = 15_000 }) {
   const pgctl = pgBin(runtimeDir, 'pg_ctl');
   const env = libEnv(runtimeDir);
+  const waitSeconds = Math.max(1, Math.ceil(timeoutMs / 1000));
 
-  const r = spawnSync(pgctl, ['stop', '-m', 'fast', '-w', '-D', pgdataDir], {
+  const r = await runChild(pgctl, ['stop', '-m', 'fast', '-w', '-t', String(waitSeconds), '-D', pgdataDir], {
     env,
-    stdio: 'pipe',
-    timeout: 15_000,
-    windowsHide: true,
+    timeoutMs: waitSeconds * 1000 + 1_000,
   });
 
   if (r.status !== 0) {

package/src/runtime/memory/lib/pg/run-child.mjs

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Async child run with spawnSync's result shape ({ status, signal, stdout,
+ * stderr, error }) so the PG runtime's tar / initdb / pg_ctl steps never block
+ * the event loop of the process hosting them (the daemon serves every client
+ * from one loop). `timeoutMs` > 0 kills the child and reports ETIMEDOUT, like
+ * spawnSync's `timeout`. Never rejects.
+ */
+export function runChild(file, args, { timeoutMs = 0, ...options } = {}) {
+  return new Promise((resolve) => {
+    const stdout = [];
+    const stderr = [];
+    let settled = false;
+    let timer = null;
+    let error = null;
+    const finish = (status, signal) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({ status, signal, stdout: Buffer.concat(stdout), stderr: Buffer.concat(stderr), error });
+    };
+    let child;
+    try {
+      child = spawn(file, args, { windowsHide: true, ...options, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (spawnError) {
+      error = spawnError;
+      finish(null, null);
+      return;
+    }
+    child.stdout?.on('data', (chunk) => stdout.push(chunk));
+    child.stderr?.on('data', (chunk) => stderr.push(chunk));
+    child.once('error', (childError) => {
+      error ??= childError;
+      finish(null, null);
+    });
+    // 'close' (not 'exit'): stdio is flushed, so captured output is complete.
+    child.once('close', (status, signal) => finish(status, signal));
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        error = Object.assign(new Error(`${file} timed out after ${timeoutMs}ms`), { code: 'ETIMEDOUT' });
+        try {
+          child.kill();
+        } catch {}
+        finish(null, 'SIGTERM');
+      }, timeoutMs);
+    }
+  });
+}