elanous 0.2.9 → 0.2.11

package/src/self-dev/shard-aggregate.ts

@@ -0,0 +1,230 @@
+import {
+  allowsBaselineOnlyFailure,
+  buildGateBaselineReport,
+  type GateBaselineReport,
+  type GatePassedTestEvidence,
+} from '../self-implement/gate-baseline.js';
+import type { GateTestShard } from './shard-plan.js';
+
+export interface GateShardAttempt {
+  shardId: string;
+  attempt: number;
+  /** A process death, missing report, or incomplete XML is not a test failure. */
+  currentJUnit?: string;
+  baselineJUnit?: string;
+  currentExitCode: number | null;
+  baselineExitCode: number | null;
+  currentSignal?: string | null;
+  baselineSignal?: string | null;
+}
+
+export interface GateShardAggregate {
+  status: 'passed' | 'failed' | 'unmeasured';
+  /** Only these shard identities need another assignment; completed siblings stay intact. */
+  retryShardIds: string[];
+  report?: GateBaselineReport;
+}
+
+interface JUnitCase { file: string; name: string; failure?: string }
+
+const decode = (text: string): string => text.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos);/gi, (entity, key: string) => {
+  if (key[0] === '#') {
+    const code = key[1]?.toLowerCase() === 'x' ? parseInt(key.slice(2), 16) : parseInt(key.slice(1), 10);
+    return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+  }
+  return ({ amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" } as Record<string, string>)[key.toLowerCase()] ?? entity;
+});
+
+interface XmlElement { name: string; attrs: Record<string, string>; children: XmlElement[]; text: string }
+
+/** Strict, dependency-free XML reader for JUnit reports: the whole document must be well formed
+ *  (one root, balanced tags, nothing but whitespace/comments after the root). CDATA and comments are
+ *  text, never elements — so a `<testcase>` inside a failure message is not a test case, and a report
+ *  followed by a truncated tail is rejected as unmeasured rather than read as complete. */
+function parseXml(xml: string): XmlElement | undefined {
+  const stack: XmlElement[] = [];
+  let root: XmlElement | undefined;
+  let i = xml.charCodeAt(0) === 0xfeff ? 1 : 0;
+  const appendText = (text: string): boolean => {
+    const top = stack.at(-1);
+    if (!top) return text.trim() === '';
+    top.text += text;
+    return true;
+  };
+  while (i < xml.length) {
+    const lt = xml.indexOf('<', i);
+    if (lt === -1) return appendText(xml.slice(i)) && !stack.length && root ? root : undefined;
+    if (lt > i) {
+      const raw = xml.slice(i, lt);
+      if (!appendText(decode(raw))) return undefined;
+      if (/&(?!(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos);)/i.test(raw)) return undefined;
+    }
+    if (xml.startsWith('<!--', lt)) {
+      const close = xml.indexOf('-->', lt + 4);
+      if (close === -1) return undefined;
+      i = close + 3;
+    } else if (xml.startsWith('<![CDATA[', lt)) {
+      const close = xml.indexOf(']]>', lt + 9);
+      if (close === -1 || !stack.length) return undefined;
+      appendText(xml.slice(lt + 9, close));
+      i = close + 3;
+    } else if (xml.startsWith('<?', lt)) {
+      const close = xml.indexOf('?>', lt + 2);
+      if (close === -1 || stack.length || root) return undefined;
+      i = close + 2;
+    } else if (xml.startsWith('<!', lt)) {
+      return undefined;
+    } else {
+      let j = lt + 1;
+      let quote: string | undefined;
+      for (; j < xml.length; j++) {
+        const ch = xml[j]!;
+        if (quote) { if (ch === quote) quote = undefined; else if (ch === '<') return undefined; }
+        else if (ch === '"' || ch === "'") quote = ch;
+        else if (ch === '>') break;
+        else if (ch === '<') return undefined;
+      }
+      if (j >= xml.length) return undefined;
+      const inner = xml.slice(lt + 1, j);
+      i = j + 1;
+      if (inner.startsWith('/')) {
+        const name = inner.slice(1).trim();
+        const open = stack.pop();
+        if (!open || open.name !== name) return undefined;
+        if (!stack.length) root = open;
+        continue;
+      }
+      const selfClosing = inner.endsWith('/');
+      const body = selfClosing ? inner.slice(0, -1) : inner;
+      const head = /^([A-Za-z_][\w.:-]*)/.exec(body);
+      if (!head || (!stack.length && root)) return undefined;
+      const attrs: Record<string, string> = {};
+      let rest = body.slice(head[1]!.length);
+      const attrPattern = /^\s+([A-Za-z_][\w.:-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/;
+      for (let m = attrPattern.exec(rest); m; m = attrPattern.exec(rest)) {
+        if (m[1]! in attrs) return undefined;
+        attrs[m[1]!] = decode(m[2] ?? m[3] ?? '');
+        rest = rest.slice(m[0].length);
+      }
+      if (rest.trim() !== '') return undefined;
+      const element: XmlElement = { name: head[1]!, attrs, children: [], text: '' };
+      stack.at(-1)?.children.push(element);
+      if (selfClosing) { if (!stack.length) root = element; }
+      else stack.push(element);
+    }
+  }
+  return !stack.length && root ? root : undefined;
+}
+
+function textOf(element: XmlElement): string {
+  return element.text + element.children.map(textOf).join('');
+}
+
+function readJUnit(xml: string, files: readonly string[]): JUnitCase[] | undefined {
+  const root = parseXml(xml);
+  if (!root || (root.name !== 'testsuites' && root.name !== 'testsuite')) return undefined;
+  const expected = new Set(files);
+  if (expected.size === 0) return undefined;
+  const cases: JUnitCase[] = [];
+  const counts = new Map<string, number>();
+  const executed = new Set<string>();
+  let failures = 0;
+  let errors = 0;
+  const matchesCount = (value: string | undefined, actual: number) => value === undefined
+    || (/^(0|[1-9]\d*)$/.test(value) && Number(value) === actual);
+  // Each suite's tests attribute covers its descendants too: compare subtree totals.
+  const walkSuite = (suite: XmlElement, parentFile: string | undefined): { tests: number; failures: number; errors: number } | undefined => {
+    const file = suite.attrs.file ?? parentFile;
+    const declared = Number(suite.attrs.tests);
+    if ((file && !expected.has(file)) || !Number.isSafeInteger(declared) || declared < 0) return undefined;
+    const total = { tests: 0, failures: 0, errors: 0 };
+    for (const child of suite.children) {
+      if (child.name === 'testsuite') {
+        const sub = walkSuite(child, file);
+        if (!sub) return undefined;
+        total.tests += sub.tests; total.failures += sub.failures; total.errors += sub.errors;
+      } else if (child.name === 'testcase') {
+        const caseFile = child.attrs.file ?? file;
+        const leaf = child.attrs.name;
+        if (!caseFile || !expected.has(caseFile) || !leaf || (file && file !== caseFile)) return undefined;
+        total.tests++;
+        counts.set(caseFile, (counts.get(caseFile) ?? 0) + 1);
+        if (child.children.some((c) => c.name === 'skipped')) return undefined;
+        const classname = child.attrs.classname;
+        const name = classname && classname !== caseFile ? `${classname} > ${leaf}` : leaf;
+        const identity = `${caseFile}\u0000${name}`;
+        if (executed.has(identity)) return undefined;
+        executed.add(identity);
+        const failure = child.children.find((c) => c.name === 'failure' || c.name === 'error');
+        if (failure?.name === 'failure') { failures++; total.failures++; }
+        else if (failure) { errors++; total.errors++; }
+        const diagnostic = failure ? [failure.attrs.message, textOf(failure).trim()].filter(Boolean).join('\n') : undefined;
+        cases.push({ file: caseFile, name, ...(failure ? { failure: diagnostic || 'JUnit test failed' } : {}) });
+      }
+    }
+    if (total.tests !== declared || !matchesCount(suite.attrs.failures, total.failures) || !matchesCount(suite.attrs.errors, total.errors)) return undefined;
+    return total;
+  };
+  const suites = root.name === 'testsuite' ? [root] : root.children.filter((c) => c.name === 'testsuite');
+  if (suites.length === 0 || (root.name === 'testsuites' && root.children.some((c) => c.name === 'testcase'))) return undefined;
+  let counted = 0;
+  for (const suite of suites) {
+    const total = walkSuite(suite, undefined);
+    if (!total) return undefined;
+    counted += total.tests;
+  }
+  if (root.name === 'testsuites' && (!matchesCount(root.attrs.tests, counted)
+    || !matchesCount(root.attrs.failures, failures) || !matchesCount(root.attrs.errors, errors))) return undefined;
+  if (cases.length === 0 || [...expected].some((file) => !counts.has(file))) return undefined;
+  return cases;
+}
+
+function asGateLog(cases: readonly JUnitCase[]): string {
+  return cases.map(({ file, name, failure }) => `${file}:\n${failure === undefined ? `(pass) ${name}` : `${failure}\n(fail) ${name}`}`).join('\n');
+}
+
+/** Select the latest complete attempt per shard, then classify the union with the existing full-suite gate ruler. */
+export function aggregateGateTestShards(shards: readonly GateTestShard[], attempts: readonly GateShardAttempt[]): GateShardAggregate {
+  const selected = new Map<string, GateShardAttempt>();
+  for (const attempt of attempts) {
+    if (!Number.isSafeInteger(attempt.attempt) || attempt.attempt < 1) throw new Error('invalid shard attempt');
+    if (!shards.some((shard) => shard.id === attempt.shardId)) throw new Error(`unknown shard: ${attempt.shardId}`);
+    const prior = selected.get(attempt.shardId);
+    if (prior?.attempt === attempt.attempt) throw new Error(`duplicate shard attempt: ${attempt.shardId}`);
+    if (!prior || prior.attempt < attempt.attempt) selected.set(attempt.shardId, attempt);
+  }
+  const retryShardIds: string[] = [];
+  const current: JUnitCase[] = [];
+  const baseline: JUnitCase[] = [];
+  for (const shard of shards) {
+    const attempt = selected.get(shard.id);
+    const head = attempt?.currentJUnit === undefined ? undefined : readJUnit(attempt.currentJUnit, shard.files);
+    const base = attempt?.baselineJUnit === undefined ? undefined : readJUnit(attempt.baselineJUnit, shard.files);
+    if (!attempt || attempt.currentExitCode === null || attempt.baselineExitCode === null
+      || attempt.currentSignal || attempt.baselineSignal
+      || ![0, 1].includes(attempt.currentExitCode) || ![0, 1].includes(attempt.baselineExitCode)
+      || !head || !base
+      || (attempt.currentExitCode === 0 && head.some((test) => test.failure !== undefined))
+      || (attempt.baselineExitCode === 0 && base.some((test) => test.failure !== undefined))
+      || (attempt.currentExitCode !== 0 && head.every((test) => test.failure === undefined))
+      || (attempt.baselineExitCode !== 0 && base.every((test) => test.failure === undefined))) {
+      retryShardIds.push(shard.id);
+      continue;
+    }
+    current.push(...head);
+    baseline.push(...base);
+  }
+  if (retryShardIds.length > 0 || shards.length === 0) return { status: 'unmeasured', retryShardIds };
+  if (current.every((test) => test.failure === undefined)) return { status: 'passed', retryShardIds: [] };
+  const passedTestEvidence: GatePassedTestEvidence = {
+    status: 'available',
+    tests: baseline.filter((test) => test.failure === undefined).map(({ file, name }) => ({ file, name: `${file} > ${name}` })),
+  };
+  const report = buildGateBaselineReport(asGateLog(current), {
+    status: baseline.some((test) => test.failure !== undefined) ? 'test-fail' : 'pass',
+    output: asGateLog(baseline),
+    passedTestEvidence,
+    log: 'shard baseline JUnit complete',
+  });
+  return { status: allowsBaselineOnlyFailure(report) ? 'passed' : 'failed', retryShardIds: [], report };
+}

package/src/self-dev/shard-placement.ts

@@ -0,0 +1,60 @@
+import type { PoolLeaseMeasure } from '../task-orchestrator/surfaces/pod-lease.js';
+import type { GateTestShard } from './shard-plan.js';
+
+export interface ShardPlacement {
+  shardId: string;
+  context: string;
+}
+
+/** Assign only to measurable, ready Pod lease members. No remote work is performed here. */
+export function assignGateShardsToPool(
+  shards: readonly GateTestShard[],
+  pool: PoolLeaseMeasure,
+  previous: readonly ShardPlacement[] = [],
+  failedContext?: string,
+): ShardPlacement[] {
+  const ids = new Set(shards.map((shard) => shard.id));
+  if (ids.size !== shards.length) throw new Error('duplicate shard id');
+  if (shards.some((shard) => !Number.isFinite(shard.plannedRssMb) || shard.plannedRssMb <= 0)) throw new Error('invalid shard RSS');
+  const reservationBytes = (shard: GateTestShard) => Math.max(4, Math.ceil(shard.plannedRssMb / 1024)) * 1024 ** 3;
+  if (previous.some((placement) => !ids.has(placement.shardId))) throw new Error('unknown shard placement');
+  const retained = previous.filter((placement) => placement.context !== failedContext);
+  if (new Set(previous.map((placement) => placement.shardId)).size !== previous.length) throw new Error('duplicate shard placement');
+  const members = pool.members.filter((member) => member.context !== failedContext && member.reason === null
+    && member.running !== null && member.pending !== null && member.availableMemoryByNodeBytes !== null
+    && Number.isSafeInteger(member.capacity) && member.capacity > 0
+    && member.availableMemoryByNodeBytes.every((bytes) => Number.isFinite(bytes) && bytes >= 0));
+  if (new Set(members.map((member) => member.context)).size !== members.length) throw new Error('duplicate pool context');
+  const state = members.map((member) => ({
+    context: member.context,
+    slots: Math.max(0, member.capacity - member.running! - member.pending!),
+    nodes: [...member.availableMemoryByNodeBytes!],
+    weight: member.availableMemoryByNodeBytes!.reduce((sum, bytes) => sum + Math.max(0, bytes), 0),
+    assigned: 0,
+  }));
+  for (const placement of retained) {
+    const member = state.find((entry) => entry.context === placement.context);
+    const shard = shards.find((entry) => entry.id === placement.shardId)!;
+    if (!member) throw new Error(`placed shard has no healthy pool member: ${placement.shardId}`);
+    const node = member.nodes.findIndex((bytes) => bytes >= reservationBytes(shard));
+    if (node < 0 || member.slots < 1) throw new Error(`placed shard exceeds pool lease: ${placement.shardId}`);
+    member.nodes[node]! -= reservationBytes(shard);
+    member.slots--;
+    member.assigned++;
+  }
+  const assigned = new Map(retained.map((placement) => [placement.shardId, placement.context]));
+  for (const shard of shards) {
+    if (assigned.has(shard.id)) continue;
+    const bytes = reservationBytes(shard);
+    const eligible = state.filter((member) => member.slots > 0 && member.nodes.some((free) => free >= bytes))
+      .sort((a, b) => a.assigned / a.weight - b.assigned / b.weight || b.weight - a.weight || a.context.localeCompare(b.context));
+    const member = eligible[0];
+    if (!member) throw new Error(`no pool lease memory for shard: ${shard.id}`);
+    const node = member.nodes.findIndex((free) => free >= bytes);
+    member.nodes[node]! -= bytes;
+    member.slots--;
+    member.assigned++;
+    assigned.set(shard.id, member.context);
+  }
+  return shards.map((shard) => ({ shardId: shard.id, context: assigned.get(shard.id)! }));
+}

package/src/self-dev/shard-plan.ts

@@ -0,0 +1,48 @@
+export interface GateTestShard {
+  id: string;
+  files: string[];
+  plannedRssMb: number;
+  plannedSeconds: number;
+}
+
+/** RSS values are the per-file rss_mb observations; the budget is in GiB (1 GiB = 1024 MB here). */
+export function planGateTestShards(
+  files: readonly string[],
+  rssMb: ReadonlyMap<string, number>,
+  seconds: ReadonlyMap<string, number>,
+  budgetGiB: number,
+  shardCount = Number.POSITIVE_INFINITY,
+): GateTestShard[] {
+  if (!Number.isFinite(budgetGiB) || budgetGiB <= 0) throw new Error('invalid shard memory budget');
+  if (shardCount !== Number.POSITIVE_INFINITY && (!Number.isSafeInteger(shardCount) || shardCount < 1)) throw new Error('invalid shard count');
+  const capacity = budgetGiB * 1024;
+  const unique = [...new Set(files)];
+  for (const file of unique) {
+    const rss = rssMb.get(file);
+    const duration = seconds.get(file);
+    if (!file || rss === undefined || !Number.isFinite(rss) || rss <= 0
+      || duration === undefined || !Number.isFinite(duration) || duration < 0) {
+      throw new Error(`missing or invalid RSS/seconds measurement: ${file}`);
+    }
+    if (rss > capacity) throw new Error(`test file exceeds shard memory budget: ${file}`);
+  }
+  const sorted = unique.sort((a, b) =>
+    rssMb.get(b)! - rssMb.get(a)! || seconds.get(b)! - seconds.get(a)! || (a < b ? -1 : a > b ? 1 : 0));
+  const shards: GateTestShard[] = [];
+  for (const file of sorted) {
+    const rss = rssMb.get(file)!;
+    const duration = seconds.get(file)!;
+    const eligible = shards.filter((shard) => shard.plannedRssMb + rss <= capacity)
+      .sort((a, b) => a.plannedSeconds - b.plannedSeconds || a.plannedRssMb - b.plannedRssMb || a.id.localeCompare(b.id));
+    let shard = eligible[0];
+    if ((!shard || (shardCount !== Number.POSITIVE_INFINITY && shards.length < Math.min(shardCount, sorted.length))) && shards.length < shardCount) {
+      shard = { id: `shard-${shards.length + 1}`, files: [], plannedRssMb: 0, plannedSeconds: 0 };
+      shards.push(shard);
+    }
+    if (!shard) throw new Error(`test files exceed ${shardCount} shard memory budgets`);
+    shard.files.push(file);
+    shard.plannedRssMb += rss;
+    shard.plannedSeconds += duration;
+  }
+  return shards;
+}

package/src/self-dev/shard-pod-run.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { runPodCommand } from '../task-orchestrator/surfaces/pod-command-job.js';
+import type { PoolLeaseMeasure } from '../task-orchestrator/surfaces/pod-lease.js';
+import { aggregateGateTestShards, type GateShardAttempt } from './shard-aggregate.js';
+import { assignGateShardsToPool, type ShardPlacement } from './shard-placement.js';
+import type { GateTestShard } from './shard-plan.js';
+import type { ShardRunResult } from './shard-run.js';
+
+type PodShardCommand = typeof runPodCommand;
+
+/** Execute already-measured GT2 bundles through the existing Pod command Job, never through SSH. */
+export async function runGateShardsOnPod(
+  shards: readonly GateTestShard[],
+  pool: PoolLeaseMeasure,
+  poolSpec: string,
+  currentCommit: string,
+  baselineCommit: string,
+  deps: { run?: PodShardCommand; read?: (path: string) => string; measure?: () => PoolLeaseMeasure } = {},
+): Promise<ShardRunResult & { placements: ShardPlacement[] }> {
+  const run = deps.run ?? (await import('../task-orchestrator/surfaces/pod-command-job.js')).runPodCommand;
+  const read = deps.read ?? ((path: string) => readFileSync(path, 'utf8'));
+  const { parsePodPool } = await import('../task-orchestrator/surfaces/pod-pool.js');
+  const poolMembers = parsePodPool(poolSpec);
+  const specs = poolSpec.split(',').map((spec) => spec.trim()).filter(Boolean);
+  const members = new Map(poolMembers.map((member, index) => [member.context, specs[index]!]));
+  const measure = deps.measure ?? (async () => (await import('../task-orchestrator/surfaces/pod-lease.js')).measurePoolLease(poolMembers));
+  for (const commit of [currentCommit, baselineCommit]) {
+    if (!/^[0-9a-f]{40}$/.test(commit)) throw new Error('Pod shard source requires a 40-character commit SHA');
+  }
+  const attempts: GateShardAttempt[] = [];
+  const planned = [...shards];
+  let placements = assignGateShardsToPool(planned, pool);
+  if (placements.some((placement) => !members.has(placement.context))) throw new Error('leased pool member is not in Pod pool spec');
+  let pending = planned;
+  for (let round = 1; round <= 2 && pending.length; round++) {
+    const failed = new Set<string>();
+    for (const shard of pending) {
+      const context = placements.find((entry) => entry.shardId === shard.id)!.context;
+      let current: { exitCode: number | null; junit?: string } = { exitCode: null };
+      let base: { exitCode: number | null; junit?: string } = { exitCode: null };
+      try {
+        // Pin the context by narrowing the existing pool spec; do not send a command over SSH.
+        const member = members.get(context);
+        if (!member) throw new Error(`pool context not in spec: ${context}`);
+        const executeOnMember = async (commit: string) => {
+          const report = `shard-${shard.id}.xml`;
+          const result = await run({ command: ['bash', '-c', 'mkdir -p "$HOME/outbox"; bun install --frozen-lockfile >/dev/null && bun test --reporter=junit --reporter-outfile="$HOME/outbox/$1" "${@:2}"', 'shard', report, ...shard.files],
+            pool: member,
+            clone: true, memoryLimit: `${Math.max(4, Math.ceil(shard.plannedRssMb / 1024))}Gi`,
+            source: { kind: 'commit', sha: commit } });
+          return { exitCode: result.exitCode, junit: read(join(result.artifactsDir, report)) };
+        };
+        current = await executeOnMember(currentCommit);
+        base = await executeOnMember(baselineCommit);
+      } catch {
+        failed.add(context);
+      }
+      attempts.push({ shardId: shard.id, attempt: round, currentExitCode: current.exitCode, baselineExitCode: base.exitCode,
+        ...(current.junit ? { currentJUnit: current.junit } : {}), ...(base.junit ? { baselineJUnit: base.junit } : {}) });
+    }
+    const retry = new Set(aggregateGateTestShards(planned, attempts).retryShardIds);
+    pending = planned.filter((shard) => retry.has(shard.id));
+    if (pending.length && round === 1 && failed.size) {
+      try {
+        const available = await measure();
+        const toMove = new Set(pending.filter((shard) => failed.has(placements.find((entry) => entry.shardId === shard.id)!.context)).map((shard) => shard.id));
+        const reassigned = assignGateShardsToPool(planned.filter((shard) => toMove.has(shard.id)),
+          { members: available.members.filter((member) => !failed.has(member.context) && members.has(member.context)) });
+        placements = placements.map((placement) => reassigned.find((next) => next.shardId === placement.shardId) ?? placement);
+      } catch (error) {
+        return { aggregate: { status: 'unmeasured', retryShardIds: [...retry] }, shards: planned, attempts, placements, reason: String(error) };
+      }
+    }
+  }
+  return { aggregate: aggregateGateTestShards(planned, attempts), shards: planned, attempts, placements };
+}

package/src/self-dev/shard-run.ts

@@ -0,0 +1,105 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { prepareDeterministicChildEnvironment } from '../../scripts/lib/deterministic-env.js';
+import { withBaselineWorktree } from '../self-implement/gate-baseline.js';
+import { aggregateGateTestShards, type GateShardAttempt, type GateShardAggregate } from './shard-aggregate.js';
+import { planGateTestShards, type GateTestShard } from './shard-plan.js';
+
+export interface ShardRunResult {
+  aggregate: GateShardAggregate;
+  shards: GateTestShard[];
+  attempts: GateShardAttempt[];
+  reason?: string;
+}
+
+export type ShardProcess = (cwd: string, files: readonly string[]) => {
+  exitCode: number | null;
+  signal?: string | null;
+  junit?: string;
+  rssMb?: number;
+  seconds?: number;
+};
+
+/** One process per bundle and per revision; a failed runner is retried only for its own bundle. */
+export function runShardedGateTests(
+  cwd: string,
+  files: readonly string[],
+  baseRef: string,
+  count = 2,
+  run: ShardProcess = runBunShard,
+  baselineWorktree: typeof withBaselineWorktree = withBaselineWorktree,
+  budgetGiB = 8,
+): ShardRunResult {
+  if (!Number.isSafeInteger(count) || count < 1) throw new Error('invalid --shards count');
+  const rss = new Map<string, number>();
+  const seconds = new Map<string, number>();
+  for (const file of [...new Set(files)]) {
+    let sample: ReturnType<ShardProcess>;
+    try {
+      sample = run(cwd, [file]);
+    } catch (error) {
+      return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: `measurement failed: ${file}: ${String(error)}` };
+    }
+    if (![0, 1].includes(sample.exitCode ?? -1) || sample.signal || !sample.junit || !Number.isFinite(sample.rssMb) || !Number.isFinite(sample.seconds)) {
+      return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: `measurement unavailable: ${file}` };
+    }
+    rss.set(file, sample.rssMb!);
+    seconds.set(file, sample.seconds!);
+  }
+  let shards: GateTestShard[];
+  try {
+    shards = planGateTestShards(files, rss, seconds, budgetGiB, count);
+  } catch (error) {
+    return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error) };
+  }
+  const attempts: GateShardAttempt[] = [];
+  const baseline = baselineWorktree(cwd, baseRef, (dir) => {
+    let pending = shards;
+    for (let round = 1; round <= 2 && pending.length; round++) {
+      for (const shard of pending) {
+        const runSafely = (location: string): ReturnType<ShardProcess> => {
+          try { return run(location, shard.files); }
+          catch { return { exitCode: null }; }
+        };
+        const current = runSafely(cwd);
+        const base = runSafely(dir);
+        attempts.push({
+          shardId: shard.id, attempt: round,
+          currentJUnit: current.junit, baselineJUnit: base.junit,
+          currentExitCode: current.exitCode, baselineExitCode: base.exitCode,
+          currentSignal: current.signal, baselineSignal: base.signal,
+        });
+      }
+      const retry = new Set(aggregateGateTestShards(shards, attempts).retryShardIds);
+      pending = shards.filter((shard) => retry.has(shard.id));
+    }
+    return aggregateGateTestShards(shards, attempts);
+  });
+  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts };
+  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log };
+}
+
+export function runBunShard(cwd: string, files: readonly string[]): ReturnType<ShardProcess> {
+  const dir = mkdtempSync(join(tmpdir(), 'elanous-shard-junit-'));
+  const report = join(dir, 'result.xml');
+  const isolated = prepareDeterministicChildEnvironment('elanous-shard-test-env-');
+  try {
+    const measured = files.length === 1;
+    const args = ['test', '--reporter=junit', `--reporter-outfile=${report}`, ...files];
+    const started = performance.now();
+    const result = Bun.spawnSync(['bun', ...args], {
+      cwd, env: isolated.env, stdout: 'pipe', stderr: 'pipe', timeout: 300_000,
+    });
+    return {
+      exitCode: result.exitCode,
+      signal: result.signalCode ? String(result.signalCode) : undefined,
+      junit: existsSync(report) ? readFileSync(report, 'utf8') : undefined,
+      rssMb: measured ? result.resourceUsage.maxRSS / (1024 * 1024) : undefined,
+      seconds: measured ? (performance.now() - started) / 1000 : undefined,
+    };
+  } finally {
+    isolated.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/src/self-implement/execution-clarification.ts

@@ -0,0 +1,115 @@
+import { randomUUID } from 'node:crypto';
+
+import { createPendingQuestion, writePendingQuestion } from '../ask-user-question/pending-questions.js';
+import { createFileAskUserQuestionResolver } from '../ask-user-question/tool.js';
+import { debug } from '../debug/log.js';
+import {
+  decideAndObserveClarification,
+  defaultClarificationBudget,
+  toAskUserQuestionRequest,
+  type ClarificationCandidate,
+  type ClarificationContext,
+} from '../hitl/clarification-policy.js';
+import { getUserConfig } from '../user-config.js';
+import { appendRunLedgerEntry, type RunLedgerWriter } from './run-ledger.js';
+
+export interface ExecutionClarificationContext {
+  runId: string;
+  budget?: ClarificationContext['budget'];
+  pendingQuestionCount?: number;
+  config?: { hitl?: { executionDeadlineMinutes?: number } };
+}
+
+export type ExecutionClarificationResult =
+  | { choice: string; by: 'assumed' | 'owner' | 'auto-recommended' }
+  | { deferred: true }
+  | { parked: true; reason: 'critical-unanswered'; questionId: string };
+
+export interface ExecutionClarificationDeps {
+  now?: () => number;
+  createId?: () => string;
+  resolver?: typeof createFileAskUserQuestionResolver;
+  resolverDeps?: Parameters<typeof createFileAskUserQuestionResolver>[1];
+  writeRunLedger?: RunLedgerWriter;
+}
+
+/** A single execution-phase decision; the file resolver owns the pending/answer lifecycle. */
+export async function askAtExecution(
+  candidate: ClarificationCandidate,
+  ctx: ExecutionClarificationContext,
+  deps: ExecutionClarificationDeps = {},
+): Promise<ExecutionClarificationResult> {
+  const recommended = candidate.options.filter(option => option.recommended);
+  if (candidate.options.length < 2 || candidate.options.length > 4 || recommended.length !== 1
+    || new Set(candidate.options.map(option => option.label)).size !== candidate.options.length) {
+    throw new Error('Execution clarification requires 2–4 distinct options and exactly one recommendation.');
+  }
+  const observe = (event: 'assumed' | 'asked' | 'answered' | 'auto-recommended' | 'parked', questionId?: string): void => {
+    try {
+      debug.log('hitl.execution', event, { runId: ctx.runId, questionId, impact: candidate.impact });
+    } catch { /* Logging must not decide the user's choice. */ }
+  };
+  const record = (event: 'assumed' | 'auto-recommended' | 'parked', data: Record<string, unknown>): void => {
+    (deps.writeRunLedger ?? appendRunLedgerEntry)({
+      timestamp: new Date((deps.now ?? Date.now)()).toISOString(),
+      runId: ctx.runId,
+      event,
+      data: { impact: candidate.impact, ...data },
+    });
+  };
+  const decision = decideAndObserveClarification(candidate, {
+    phase: 'execution',
+    budget: ctx.budget ?? defaultClarificationBudget('execution'),
+    pendingQuestionCount: ctx.pendingQuestionCount,
+  }, { consumer: 'self-implement-execution' });
+  if (decision.action === 'defer') return { deferred: true };
+  if (decision.action === 'assume') {
+    record('assumed', { choice: recommended[0]!.label, assumption: decision.assumption });
+    observe('assumed');
+    return { choice: recommended[0]!.label, by: 'assumed' };
+  }
+
+  const request = toAskUserQuestionRequest(decision);
+  if (!request) throw new Error('Execution clarification policy approved a question without a valid wire request.');
+  const configured = ctx.config === undefined
+    ? getUserConfig().hitl?.executionDeadlineMinutes
+    : ctx.config.hitl?.executionDeadlineMinutes;
+  const minutes = configured === undefined ? 30 : configured;
+  if (!Number.isSafeInteger(minutes) || minutes < 1 || minutes > 35_791) {
+    throw new Error('hitl.executionDeadlineMinutes must be a positive integer within the resolver timer limit.');
+  }
+  const questionId = (deps.createId ?? (() => `execution:${ctx.runId}:${randomUUID()}`))();
+  let expired = false;
+  let written = false;
+  const resolver = (deps.resolver ?? createFileAskUserQuestionResolver)(minutes * 60_000, {
+    ...deps.resolverDeps,
+    observe: (state, data) => {
+      if (state === 'answer-missing') expired = true;
+      deps.resolverDeps?.observe?.(state, data);
+    },
+    createId: () => questionId,
+    write: (pending) => {
+      const question = createPendingQuestion(questionId, { ...request, runId: ctx.runId }, undefined,
+        { now: () => new Date((deps.now ?? Date.now)()) },
+        { surface: 'file', delivery: 'file', expiresAt: pending.expiresAt });
+      (deps.resolverDeps?.write ?? writePendingQuestion)(question);
+      written = true;
+      observe('asked', questionId);
+    },
+  });
+  const answer = await resolver({ ...request, runId: ctx.runId });
+  const chosen = answer.answers[candidate.id];
+  if (written && !expired && !answer.cancelled && typeof chosen === 'string' && candidate.options.some(option => option.label === chosen)) {
+    observe('answered', questionId);
+    return { choice: chosen, by: 'owner' };
+  }
+  if (!written || !expired) throw new Error('Execution clarification was cancelled or could not read its answer before expiry.');
+  if (candidate.impact === 'critical') {
+    record('parked', { questionId, reason: 'critical-unanswered' });
+    observe('parked', questionId);
+    return { parked: true, reason: 'critical-unanswered', questionId };
+  }
+  record('auto-recommended', { questionId, choice: recommended[0]!.label, by: 'auto-recommended' });
+  observe('auto-recommended', questionId);
+  return { choice: recommended[0]!.label, by: 'auto-recommended' };
+}

package/src/self-implement/gate-baseline.ts

@@ -764,7 +764,7 @@ export function classifyBaselineProcess(result: ProcessResult, budget?: { timeou
   };
 }
 
-function withBaselineWorktree<T>(cwd: string, baseRef: string, run: (baselineDir: string) => T): T | BaselineProcessResult {
+export function withBaselineWorktree<T>(cwd: string, baseRef: string, run: (baselineDir: string) => T): T | BaselineProcessResult {
   const baselineDir = mkdtempSync(join(tmpdir(), 'elanous-gate-baseline-'));
   let attached = false;
   try {