@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/sync/run.mjs

@@ -0,0 +1,531 @@
+// estate-sync — orchestrator.
+//
+// The single git writer per host for ESTATE-NATIVE content only. Designed
+// for a 30-minute cron: quiet on success, loud on failure, exit-code
+// accurate for monitoring.
+//
+// Flow (commit-first; see note below):
+//   1. acquire the process lock (PID file; stale after 10m)
+//   2. git fetch origin — refresh remote refs FIRST so ahead/behind is
+//      accurate (without this, a clean tree short-circuits to noop using
+//      a stale origin/main pointer and never discovers remote commits)
+//   3. discover working-tree state — clean? ahead/behind upstream?
+//   4. if nothing to do (clean tree + ahead == 0 + behind == 0) -> noop
+//      audit + exit 0
+//   5. compose a commit body from the cron tools' runs.jsonl files, plus
+//      the registry-scoped commit-scope decision (see registry-scope.mjs)
+//   6. if dirty: compute the commit scope — when
+//      <repoRoot>/operator/registry/{devices.json,repos.json} exist,
+//      resolve this device and exclude every entitled mount's `to`
+//      subtree (+ .vault/** unconditionally), then stage ONLY the
+//      in-scope dirty paths via explicit pathspecs (`git add -- <paths>`)
+//      — NEVER a bare `git add -A`. No registry present -> previous
+//      (pre-rewrite) behaviour: unscoped `git add -A`, but loud about it
+//      (stderr + commit body). Then
+//      `git commit -m "estate-sync <ISO ts>" -m "<body>"`.
+//      (this happens BEFORE the pull — git pull --rebase refuses to run
+//      with uncommitted changes in the index or working tree)
+//   7. git pull --rebase origin <branch> (fetch already done in step 2)
+//      on rebase conflict: git rebase --abort + fail-rebase audit + exit 2
+//   8. git push. on rejection: fetch + pull --rebase + push retry. one
+//      retry only.
+//   9. append success audit to logs/runs.jsonl
+//
+// Why commit-first (Option A): `git pull --rebase` refuses to run when
+// the index or working tree contains uncommitted changes. The original
+// "add -> pull --rebase -> commit -> push" ordering is therefore
+// impossible — sync would abort with "cannot pull with rebase: Your
+// index contains uncommitted changes". Committing first means the
+// rebase replays one clean local commit on top of origin's history;
+// this is the same shape a human follows when integrating with origin.
+// Failure modes are also cleaner: a conflicting rebase can be safely
+// aborted (the commit stays local, next tick reconciles), whereas a
+// stash-pop-conflict would leave the tree in a half-merged state with
+// no good automated recovery.
+//
+// Audit-record contract: every non-dry-run exit path writes exactly one
+// record. Status vocabulary (§15 of the tooling standard):
+//   ok                   commit + push (or pull-only) succeeded
+//   noop-nothing-to-do   working tree clean and no commits ahead of origin
+//   noop-locked          another sync process is running — try again
+//   fail-rebase          pull --rebase conflicted; rebase aborted
+//   fail-push            push rejected even after rebase retry
+//   fail-git             any other git command failed
+//
+// Exit codes (§6 of the tooling standard):
+//   0  ok (including noop)
+//   1  usage (handled in cli.mjs)
+//   2  logical / operational failure (rebase, push reject, dirty rebase)
+//   3  transport / IO failure (git command itself errored, not the result)
+
+import { appendFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import {
+  addAll,
+  addPaths,
+  aheadBehind,
+  checkoutOursDuringRebase,
+  commit,
+  currentBranch,
+  fetchOrigin,
+  hasStagedChanges,
+  listConflictedPaths,
+  pullRebase,
+  push,
+  rebaseAbort,
+  rebaseContinue,
+  statusPorcelain,
+} from './git.mjs';
+import { acquire } from './lock.mjs';
+import {
+  classifyConflicts,
+  loadRegeneratedArtifacts,
+} from './regenerated-artifacts.mjs';
+import { computeCommitScope, filterInScopePaths, renderScopeSection } from './registry-scope.mjs';
+import { composeBody } from './runs-digest.mjs';
+
+function log(line, { stderr = process.stderr } = {}) {
+  stderr.write(`[estate-sync] ${line}\n`);
+}
+
+async function writeAudit(runsLog, record, stderr) {
+  try {
+    await appendFile(runsLog, JSON.stringify(record) + '\n');
+  } catch (err) {
+    log(`warning: failed to append audit record to ${runsLog}: ${err.message}`, { stderr });
+  }
+}
+
+export async function runSync({
+  repoRoot,
+  logDir,
+  runsLog,
+  lockPath,
+  dryRun = false,
+  runner,
+  stderr = process.stderr,
+  lockOptions = {},
+  // Test-only injection seam: overrides os.hostname() inside
+  // computeCommitScope's device resolution. Production callers never pass
+  // this — computeCommitScope defaults to the real os.hostname().
+  hostnameFn,
+} = {}) {
+  if (!runner) throw new Error('runSync: runner is required');
+  if (!repoRoot) throw new Error('runSync: repoRoot is required');
+  if (!runsLog) throw new Error('runSync: runsLog is required');
+  if (!lockPath) throw new Error('runSync: lockPath is required');
+
+  const tsIso = runner.tsIso();
+  const startedAtMs = Date.now();
+
+  if (dryRun) {
+    log('DRY RUN — would:', { stderr });
+  }
+
+  // Step 1 — lock.
+  const lock = await acquire(lockPath, lockOptions);
+  if (!lock.acquired) {
+    log(`another sync is running: ${lock.reason} — exiting noop`, { stderr });
+    if (!dryRun) {
+      await writeAudit(runsLog, {
+        ts: tsIso,
+        status: 'noop-locked',
+        exitCode: 0,
+        durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+        reason: `lock contention: ${lock.reason}`,
+      }, stderr);
+    }
+    return 0;
+  }
+
+  try {
+    // Step 2 — fetch upstream FIRST so ahead/behind reflects what origin
+    // actually has. Without this, a clean tree with no local commits
+    // short-circuits to the step-4 noop using whatever origin/<branch>
+    // pointed at on the last fetch — which on a long-idle clone is
+    // arbitrarily stale. Fetch failures (network, auth) are logged but
+    // not blocking: we'd rather proceed on stale refs for one cycle than
+    // miss a chance to commit local work. The next tick will retry.
+    //
+    // Skip in dry-run mode — even though fetch only updates remote-
+    // tracking refs (no local branch / working tree mutation), the
+    // dry-run contract is "no git commands spawned." Dry-run's
+    // ahead/behind reporting may therefore be stale by up to one cron
+    // tick; that's an acceptable cost for the cleaner contract.
+    let upfrontFetch = { code: 0 };
+    if (!dryRun) {
+      upfrontFetch = await fetchOrigin(runner, { cwd: repoRoot });
+      if (upfrontFetch.code !== 0) {
+        log(`git fetch (up-front) failed — proceeding with stale upstream refs: ${upfrontFetch.stderr.trim()}`, { stderr });
+      }
+    }
+
+    // Step 3 — examine working tree and upstream relation.
+    const status = await statusPorcelain(runner, { cwd: repoRoot });
+    if (status.code !== 0) {
+      log(`git status failed: ${status.stderr.trim()}`, { stderr });
+      if (!dryRun) {
+        await writeAudit(runsLog, {
+          ts: tsIso,
+          status: 'fail-git',
+          exitCode: 3,
+          durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+          reason: `git status failed: ${status.stderr.trim()}`,
+        }, stderr);
+      }
+      return 3;
+    }
+    const dirty = status.stdout.trim().length > 0;
+    const { ahead, behind } = await aheadBehind(runner, { cwd: repoRoot });
+    const aheadCount = Number.isFinite(ahead) ? ahead : 0;
+    const behindCount = Number.isFinite(behind) ? behind : 0;
+    log(`tree dirty=${dirty}, ahead=${aheadCount}, behind=${behindCount}`, { stderr });
+
+    const branch = await currentBranch(runner, { cwd: repoRoot });
+
+    // Step 4 — noop short-circuit.
+    if (!dirty && aheadCount === 0 && behindCount === 0) {
+      log('nothing to do — tree clean, no local commits ahead, up-to-date', { stderr });
+      if (!dryRun) {
+        await writeAudit(runsLog, {
+          ts: tsIso,
+          status: 'noop-nothing-to-do',
+          exitCode: 0,
+          durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+          dirty,
+          ahead: aheadCount,
+          behind: behindCount,
+          branch,
+        }, stderr);
+      }
+      return 0;
+    }
+
+    // Step 5 — compose body (cheap; pure file read) + registry-scoped
+    // commit-scope decision (also cheap; two small JSON reads at most).
+    const digestBody = await composeBody({ repoRoot });
+    const scope = computeCommitScope(hostnameFn ? { repoRoot, hostnameFn } : { repoRoot });
+
+    if (dryRun) {
+      log(`  branch:           ${branch}`, { stderr });
+      log(`  dirty:            ${dirty}`, { stderr });
+      log(`  ahead/behind:     ${aheadCount}/${behindCount}`, { stderr });
+      log(`  commit title:     estate-sync ${tsIso}`, { stderr });
+      log('  commit body (preview):', { stderr });
+      for (const line of digestBody.split('\n')) {
+        log(`    ${line}`, { stderr });
+      }
+      log('  would: git fetch origin (real run does this BEFORE the noop check; dry-run skipped to keep this side-effect-free)', { stderr });
+      if (dirty) {
+        if (scope.registryPresent) {
+          const { inScope, excludedCount } = filterInScopePaths(status.stdout, scope.excludeDirs);
+          log(`  would: git add -- <${inScope.length} in-scope path(s), device=${scope.deviceId}, ${excludedCount} excluded by registry scope>`, { stderr });
+        } else {
+          log('  would: git add -A (no registry found — unscoped commit)', { stderr });
+        }
+        log(`  would: git commit -m "estate-sync ${tsIso}" -m "<body above>"`, { stderr });
+      }
+      log(`  would: git pull --rebase origin ${branch}`, { stderr });
+      log('  would: git push (with one rebase-and-retry on rejection)', { stderr });
+      return 0;
+    }
+
+    // Step 6 — stage + commit (commit-first ordering).
+    //
+    // We commit BEFORE pulling because `git pull --rebase` refuses to
+    // run when the index or working tree has uncommitted changes — it
+    // aborts with "cannot pull with rebase: Your index contains
+    // uncommitted changes". By committing first, the subsequent rebase
+    // replays a clean local commit on top of origin's history. This is
+    // the same shape a human follows when integrating: stage, commit,
+    // then rebase onto upstream.
+    let didCommit = false;
+    if (dirty) {
+      let addRes;
+      let stagedCount = 0;
+      let excludedPathCount = 0;
+      if (scope.registryPresent) {
+        // Registry-scoped staging: explicit pathspecs of in-scope dirty
+        // paths only — NEVER a bare `git add -A`. Untracked files inside
+        // an excluded subtree are simply never passed to `git add`, so
+        // they can never be staged (pathspec approach handles this by
+        // construction, not by a follow-up filter).
+        const { inScope, excludedCount } = filterInScopePaths(status.stdout, scope.excludeDirs);
+        stagedCount = inScope.length;
+        excludedPathCount = excludedCount;
+        if (inScope.length > 0) {
+          addRes = await addPaths(runner, { cwd: repoRoot, paths: inScope });
+        } else {
+          addRes = { code: 0, stdout: '', stderr: '' };
+          log('all dirty paths are excluded by registry scope — nothing to stage this tick', { stderr });
+        }
+      } else {
+        // No registry present at this repo root — previous (pre-rewrite)
+        // behaviour: unscoped `git add -A`, but LOUD about it, both in
+        // the run's own log output and in the commit body (below).
+        const reason = scope.warnings.length > 0 ? ` (${scope.warnings.join('; ')})` : '';
+        log(`estate-sync: no registry found, unscoped commit${reason}`, { stderr });
+        addRes = await addAll(runner, { cwd: repoRoot });
+      }
+      const scopeSection = renderScopeSection(scope, { staged: stagedCount, excludedPaths: excludedPathCount });
+      const body = `${scopeSection}\n\n${digestBody}`;
+
+      if (addRes.code !== 0) {
+        log(`git add failed: ${addRes.stderr.trim()}`, { stderr });
+        await writeAudit(runsLog, {
+          ts: tsIso,
+          status: 'fail-git',
+          exitCode: 3,
+          durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+          reason: `git add failed: ${addRes.stderr.trim()}`,
+        }, stderr);
+        return 3;
+      }
+      // Belt-and-braces: if add somehow produced no staged content (e.g.
+      // every dirty path was ignored), skip the commit and continue.
+      const haveStaged = await hasStagedChanges(runner, { cwd: repoRoot });
+      if (haveStaged) {
+        const title = `estate-sync ${tsIso}`;
+        const c = await commit(runner, { cwd: repoRoot, title, body });
+        if (c.code !== 0) {
+          log(`git commit failed: ${c.stderr.trim()}`, { stderr });
+          await writeAudit(runsLog, {
+            ts: tsIso,
+            status: 'fail-git',
+            exitCode: 3,
+            durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+            reason: `git commit failed: ${c.stderr.trim()}`,
+          }, stderr);
+          return 3;
+        }
+        didCommit = true;
+        log('committed', { stderr });
+      } else {
+        log('nothing staged after add — skipping commit', { stderr });
+      }
+    }
+
+    // Step 7 — rebase. Fetch already done in step 2. Rebase failures
+    // are operational, not transport. Now safe to rebase because the
+    // tree is clean (either we committed in step 6, or it was clean to
+    // begin with — behind-only). If rebase conflicts on a path our
+    // fresh commit touches, we abort and surface; the commit stays
+    // local and the next tick will retry.
+    //
+    // We only attempt pull --rebase if the up-front fetch succeeded.
+    // If fetch failed earlier, we'd be rebasing onto stale refs which
+    // either no-ops (if local refs already match) or fails spuriously.
+    let autoResolvedPaths = [];
+    if (upfrontFetch.code === 0) {
+      const prRes = await pullRebase(runner, { cwd: repoRoot, branch });
+      if (prRes.code !== 0) {
+        log(`git pull --rebase failed: ${prRes.stderr.trim()}`, { stderr });
+        // Before aborting, see if the conflict is limited to files that
+        // distillation regenerates on every host. Those files are
+        // byte-different but semantically equivalent across hosts; a
+        // conflict just means two hosts pushed regenerations in the same
+        // window. Auto-resolve by preferring origin's version (see the
+        // rebase-inversion note on `checkoutOursDuringRebase`) and
+        // continue. If ANY conflict is outside the allowlist, we still
+        // abort and surface fail-rebase — real conflicts need a human.
+        const resolved = await tryAutoResolveRebase({
+          runner,
+          repoRoot,
+          stderr,
+        });
+        if (resolved.ok) {
+          autoResolvedPaths = resolved.paths;
+          log(
+            `auto-resolved rebase conflict on ${resolved.paths.length} regenerated artifact(s): ${resolved.paths.join(', ')}`,
+            { stderr },
+          );
+        } else {
+          log(`aborting rebase: ${resolved.reason}`, { stderr });
+          // Defensive abort. If no rebase is in progress (auto-resolve
+          // already ended it, or nothing was in progress), abort exits
+          // non-zero — we ignore that case.
+          await rebaseAbort(runner, { cwd: repoRoot });
+          await writeAudit(runsLog, {
+            ts: tsIso,
+            status: 'fail-rebase',
+            exitCode: 2,
+            durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+            reason: `git pull --rebase failed — rebase aborted; ${resolved.reason}`,
+            committed: didCommit,
+            ...(resolved.disallowed ? { conflictedPaths: resolved.disallowed } : {}),
+          }, stderr);
+          return 2;
+        }
+      }
+    }
+
+    // Step 7 — push (only if we have something to push). Note: after a
+    // pull --rebase that fast-forwarded, we may have new local refs
+    // pointing at remote refs (nothing to push). If we committed, we have
+    // at least one local-only commit. If we were just behind, pull
+    // brought us up to date — nothing to push.
+    const autoResolveFields = autoResolvedPaths.length > 0
+      ? { autoResolved: autoResolvedPaths.length, autoResolvedPaths }
+      : {};
+
+    const { ahead: aheadAfter } = await aheadBehind(runner, { cwd: repoRoot });
+    const needsPush = Number.isFinite(aheadAfter) && aheadAfter > 0;
+    if (!needsPush) {
+      log('nothing to push (up-to-date with origin)', { stderr });
+      await writeAudit(runsLog, {
+        ts: tsIso,
+        status: 'ok',
+        exitCode: 0,
+        durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+        committed: didCommit,
+        pushed: false,
+        branch,
+        ...autoResolveFields,
+      }, stderr);
+      return 0;
+    }
+
+    const p1 = await push(runner, { cwd: repoRoot });
+    if (p1.code === 0) {
+      log('pushed', { stderr });
+      await writeAudit(runsLog, {
+        ts: tsIso,
+        status: 'ok',
+        exitCode: 0,
+        durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+        committed: didCommit,
+        pushed: true,
+        branch,
+        ...autoResolveFields,
+      }, stderr);
+      return 0;
+    }
+
+    log(`git push rejected — fetching and rebasing for one retry: ${p1.stderr.trim()}`, { stderr });
+    const f2 = await fetchOrigin(runner, { cwd: repoRoot });
+    if (f2.code !== 0) {
+      log(`git fetch (for push-retry) failed: ${f2.stderr.trim()}`, { stderr });
+      await writeAudit(runsLog, {
+        ts: tsIso,
+        status: 'fail-push',
+        exitCode: 2,
+        durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+        reason: 'push rejected and follow-up fetch failed; commit is local-only',
+      }, stderr);
+      return 2;
+    }
+    const pr2 = await pullRebase(runner, { cwd: repoRoot, branch });
+    if (pr2.code !== 0) {
+      log(`git pull --rebase (for push-retry) failed: ${pr2.stderr.trim()}`, { stderr });
+      // Symmetric with step 7: if the push-retry rebase conflicts only
+      // on regenerated artifacts, auto-resolve and continue. Otherwise
+      // abort as before.
+      const resolved2 = await tryAutoResolveRebase({
+        runner,
+        repoRoot,
+        stderr,
+      });
+      if (resolved2.ok) {
+        autoResolvedPaths = [...autoResolvedPaths, ...resolved2.paths];
+        log(
+          `auto-resolved push-retry rebase on ${resolved2.paths.length} regenerated artifact(s): ${resolved2.paths.join(', ')}`,
+          { stderr },
+        );
+      } else {
+        log(`aborting push-retry rebase: ${resolved2.reason}`, { stderr });
+        await rebaseAbort(runner, { cwd: repoRoot });
+        await writeAudit(runsLog, {
+          ts: tsIso,
+          status: 'fail-rebase',
+          exitCode: 2,
+          durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+          reason: `push rejected; follow-up rebase aborted; ${resolved2.reason}`,
+          ...(resolved2.disallowed ? { conflictedPaths: resolved2.disallowed } : {}),
+        }, stderr);
+        return 2;
+      }
+    }
+    const p2 = await push(runner, { cwd: repoRoot });
+    if (p2.code !== 0) {
+      log(`git push (retry) failed: ${p2.stderr.trim()}`, { stderr });
+      await writeAudit(runsLog, {
+        ts: tsIso,
+        status: 'fail-push',
+        exitCode: 2,
+        durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+        reason: 'push rejected even after rebase-retry; commit is local-only',
+      }, stderr);
+      return 2;
+    }
+    log('pushed after rebase', { stderr });
+    // Recompute so any auto-resolve during the push-retry is captured.
+    const autoResolveFieldsFinal = autoResolvedPaths.length > 0
+      ? { autoResolved: autoResolvedPaths.length, autoResolvedPaths }
+      : {};
+    await writeAudit(runsLog, {
+      ts: tsIso,
+      status: 'ok',
+      exitCode: 0,
+      durationSec: Math.round((Date.now() - startedAtMs) / 1000),
+      committed: didCommit,
+      pushed: true,
+      retriedAfterRebase: true,
+      branch,
+      ...autoResolveFieldsFinal,
+    }, stderr);
+    return 0;
+  } finally {
+    await lock.release();
+  }
+}
+
+// Attempt to auto-resolve an in-progress rebase whose conflicts are all
+// on regenerated knowledge artifacts (see `regenerated-artifacts.mjs`).
+// Preferring origin's version is safe here because the next distillation
+// cycle will regenerate again with combined inputs — nothing is lost.
+//
+// Returns:
+//   { ok: true,  paths: [...] }                  — resolved, rebase continued
+//   { ok: false, reason: '<short>', disallowed?: [...] } — do NOT continue
+async function tryAutoResolveRebase({ runner, repoRoot, stderr }) {
+  const conflicts = await listConflictedPaths(runner, { cwd: repoRoot });
+  if (conflicts.code !== 0) {
+    return { ok: false, reason: `git status (post-rebase) failed: ${conflicts.stderr.trim()}` };
+  }
+  if (conflicts.paths.length === 0) {
+    // pull --rebase failed but no unmerged entries — not a content
+    // conflict. Could be untracked-would-be-overwritten, empty commit,
+    // etc. Nothing safe to auto-resolve.
+    return { ok: false, reason: 'no unmerged paths detected — not a content conflict' };
+  }
+
+  const cfg = await loadRegeneratedArtifacts({ repoRoot });
+  if (cfg.warning) {
+    log(`.sync-config.json warning: ${cfg.warning} — falling back to defaults`, { stderr });
+  }
+  const { allowed, disallowed } = classifyConflicts(conflicts.paths, cfg.patterns);
+  if (disallowed.length > 0) {
+    return {
+      ok: false,
+      reason: `conflict on ${disallowed.length} path(s) outside the regenerated-artifacts allowlist (${disallowed.join(', ')}); manual reconciliation required`,
+      disallowed,
+    };
+  }
+
+  // All conflicts are allowlisted. Prefer origin's version, stage, and
+  // continue the rebase.
+  const co = await checkoutOursDuringRebase(runner, { cwd: repoRoot, paths: allowed });
+  if (co.code !== 0) {
+    return { ok: false, reason: `git checkout --ours failed: ${co.stderr.trim()}` };
+  }
+  const add = await addPaths(runner, { cwd: repoRoot, paths: allowed });
+  if (add.code !== 0) {
+    return { ok: false, reason: `git add (post-resolve) failed: ${add.stderr.trim()}` };
+  }
+  const cont = await rebaseContinue(runner, { cwd: repoRoot });
+  if (cont.code !== 0) {
+    return { ok: false, reason: `git rebase --continue failed: ${cont.stderr.trim()}` };
+  }
+  return { ok: true, paths: allowed };
+}

package/dist/engineering-pa-cli/src/sync/runner.mjs

@@ -0,0 +1,62 @@
+// sync — chokepoint for external effects.
+//
+// Every process spawn and clock read funnels through here. This module is
+// the ONLY place that touches the outside world at runtime. Tests inject a
+// fake `spawner` to assert on argv without spawning real processes.
+//
+// Contract (mirrors distill/src/runner.mjs):
+//   - spawn(cmd, args, { cwd?, env?, capture? }) -> { code, stdout, stderr }
+//     * No shell interpolation. Arguments are passed as an array with
+//       shell:false. User-supplied data (paths) flows through untouched.
+//     * capture:true (default) collects stdout/stderr into strings.
+//   - now() -> Date — single source of wall-clock time, for testing.
+//   - tsIso() -> strict RFC-3339 / ISO-8601 UTC timestamp `YYYY-MM-DDTHH:MM:SSZ`
+//     (second precision). Safe to round-trip via `new Date()`.
+
+import { spawn as realSpawn } from 'node:child_process';
+
+export function createRunner({ spawner = realSpawn, clock = () => new Date() } = {}) {
+  return {
+    async spawn(cmd, args, { cwd, env, capture = true } = {}) {
+      return new Promise((resolve, reject) => {
+        const child = spawner(cmd, args, {
+          shell: false,
+          cwd,
+          env: env ?? process.env,
+          stdio: capture ? ['pipe', 'pipe', 'pipe'] : ['pipe', 'inherit', 'inherit'],
+        });
+
+        let stdout = '';
+        let stderr = '';
+
+        if (capture) {
+          child.stdout.on('data', (d) => {
+            stdout += d.toString('utf8');
+          });
+          child.stderr.on('data', (d) => {
+            stderr += d.toString('utf8');
+          });
+        }
+
+        child.on('error', (err) => reject(err));
+        child.on('close', (code) => resolve({ code: code ?? 0, stdout, stderr }));
+        child.stdin.end();
+      });
+    },
+
+    now() {
+      return clock();
+    },
+
+    tsIso() {
+      const d = clock();
+      const pad = (n) => String(n).padStart(2, '0');
+      return (
+        `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}` +
+        `T${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}:${pad(d.getUTCSeconds())}Z`
+      );
+    },
+  };
+}
+
+export const defaultRunner = createRunner();