elanous 0.2.36 → 0.2.38

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

@@ -374,6 +374,21 @@ export function decideNextRun(input: {
   const deployFindings = input.deployFindings === undefined ? undefined
     : new Map([...input.deployFindings].filter(([taskId]) => !handedOffIds.has(taskId)));
   const t = triageRun(activeResults, deployFindings, observation === 'failed', undefined, mainSyncRelaunchSpent(history));
+  const revisionUnobserved = activeResults.filter((result) => result.harvestable === true && !!result.branch
+    && result.goalPlanRevision?.status !== 'read');
+  const revisionUnobservedIds = new Set(revisionUnobserved.map((result) => result.taskId));
+  for (const classification of t.classifications) {
+    if (classification.kind !== 'main-sync-blocked' || classification.action !== 'relaunch-on-main'
+      || !revisionUnobservedIds.has(classification.taskId)) continue;
+    // Keep history's «already spent» predicate separate from this independent safety block.
+    classification.action = 'needs-human';
+    t.relaunchOnMain = t.relaunchOnMain.filter((taskId) => taskId !== classification.taskId);
+    if (!t.needsHuman.includes(classification.taskId)) t.needsHuman.push(classification.taskId);
+  }
+  t.actionable = countActionable(t) > 0;
+  const revisionHoldNote = revisionUnobserved.length > 0
+    ? ` · 골 개정 관측 미확인 — 같은 골 재발사 보류(${revisionUnobserved.map((result) => result.taskId).join(', ')})`
+    : '';
   const relaunchGoals: Record<string, string> = Object.fromEntries(activeResults.flatMap((result) =>
     t.relaunchOnMain.includes(result.taskId) && result.branch
       ? [[result.taskId, mainSyncRelaunchGoal(result.feature, result.branch)]] : []));
@@ -438,7 +453,7 @@ export function decideNextRun(input: {
       ...base,
       action: 'stop',
       stopReason: 'harvestable-awaiting-human',
-      why: withGoalPlanRevisionObservation(`구현 완료 · 수확 대기 — ${harvestable.map((result) => result.branch).join(' · ')}`),
+      why: `${withGoalPlanRevisionObservation(`구현 완료 · 수확 대기 — ${harvestable.map((result) => result.branch).join(' · ')}`)}${revisionHoldNote}`,
     };
   }
 
@@ -604,7 +619,7 @@ export function decideNextRun(input: {
         ...base,
         action: 'stop',
         stopReason: 'no-progress',
-        why: withNoProgressGoalPlanRevisionObservation(`${stallRounds}라운드 연속 제자리 — base=${completionBase ?? 'main'} 기준 완료 ${baseCompleted} · 착지 ${landed} · 남은 조각도 안 줄었다(${actionable}). 골·불변식을 의심할 자리`),
+        why: `${withNoProgressGoalPlanRevisionObservation(`${stallRounds}라운드 연속 제자리 — base=${completionBase ?? 'main'} 기준 완료 ${baseCompleted} · 착지 ${landed} · 남은 조각도 안 줄었다(${actionable}). 골·불변식을 의심할 자리`)}${revisionHoldNote}`,
       };
     }
   }
@@ -733,10 +748,10 @@ export function decideNextRun(input: {
         ...(action === 'add-repair-task' && held.length ? { heldTaskIds: held } : {}) },
       pendingDecision: 'attempt-care-escalation',
       why: fresh.length === 0
-        ? `리뷰 진동 반복 — ${signatureOf(oscillating)} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}`
+        ? `리뷰 진동 반복 — ${signatureOf(oscillating)} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}${revisionHoldNote}`
         : cannotRepair
-          ? `리뷰 진동 — ${signatureOf(oscillating)} · ${input.repairGoalExecution === false ? '이 감독 경로가 수리 골 실행을 선언하지 않았다(미선언 또는 불가)' : '수리 원문/PR 관측 불가'} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}`
-          : `리뷰 진동 — ${signatureOf(fresh)} · review-oscillation 수리 조각을 한 번 붙인다${input.repairGoalExecution === true ? '' : '(실행 배선 미선언 — 결정 칸만)'}${repairedHeld.length ? ` · 이미 수리한 조각 ${repairedHeld.join(', ')} 은 사람 결정 대기` : ''}${classHeld.length ? ` · 분류로 보류한 조각 ${classHeld.join(', ')}` : ''}${heldReasonSuffix}`,
+          ? `리뷰 진동 — ${signatureOf(oscillating)} · ${input.repairGoalExecution === false ? '이 감독 경로가 수리 골 실행을 선언하지 않았다(미선언 또는 불가)' : '수리 원문/PR 관측 불가'} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}${revisionHoldNote}`
+          : `리뷰 진동 — ${signatureOf(fresh)} · review-oscillation 수리 조각을 한 번 붙인다${input.repairGoalExecution === true ? '' : '(실행 배선 미선언 — 결정 칸만)'}${repairedHeld.length ? ` · 이미 수리한 조각 ${repairedHeld.join(', ')} 은 사람 결정 대기` : ''}${classHeld.length ? ` · 분류로 보류한 조각 ${classHeld.join(', ')}` : ''}${heldReasonSuffix}${revisionHoldNote}`,
     };
   }
 
@@ -746,14 +761,14 @@ export function decideNextRun(input: {
     return {
       ...base,
       action: 'add-repair-task',
-      why: `수리 조각을 붙인다 — 수리 ${t.repairable.length} · 그대로 재실행 ${t.rerunnable.length} · 재작업 ${t.reworkable.length} · 분해 ${t.decomposable.length} · 라운드 ${round + 1}/${maxRounds}`,
+      why: `수리 조각을 붙인다 — 수리 ${t.repairable.length} · 그대로 재실행 ${t.rerunnable.length} · 재작업 ${t.reworkable.length} · 분해 ${t.decomposable.length} · 라운드 ${round + 1}/${maxRounds}${revisionHoldNote}`,
     };
   }
 
   return {
     ...base,
     action: 'relaunch',
-    why: `다시 건다 — 그대로 재실행 ${t.rerunnable.length} · 재작업 ${t.reworkable.length} · 분해 ${t.decomposable.length} · 수리 ${t.repairable.length}${t.relaunchOnMain.length > 0 ? ` · main 위 재발사 ${t.relaunchOnMain.length}` : ''} · 라운드 ${round + 1}/${maxRounds}`,
+    why: `다시 건다 — 그대로 재실행 ${t.rerunnable.length} · 재작업 ${t.reworkable.length} · 분해 ${t.decomposable.length} · 수리 ${t.repairable.length}${t.relaunchOnMain.length > 0 ? ` · main 위 재발사 ${t.relaunchOnMain.length}` : ''} · 라운드 ${round + 1}/${maxRounds}${revisionHoldNote}`,
   };
 }
 

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

@@ -105,3 +105,51 @@ export function planFixedGateTestShards(files: readonly string[], shardCount: nu
   }
   return groups.map((group, index) => ({ id: `shard-${index + 1}`, files: group, plannedRssMb: 0, plannedSeconds: 0 }));
 }
+
+/** GATE-REMOTE-SHARD-PLAN — one remote shard carrying its orchestration identity; introducedFiles are this shard's own
+ *  files, so introduced attribution stays file-level (a shard never inherits another shard's introduced files). */
+export interface GateRemoteShard {
+  orchestrationId: string;
+  shardId: string;
+  totalShards: number;
+  position: number;
+  files: string[];
+  introducedFiles: string[];
+}
+
+/** Deterministic orchestration id for a changed-file list: same files in any order produce the same id, so re-plans stay joinable. */
+export function shardPlanOrchestrationId(files: readonly string[]): string {
+  const sorted = [...new Set(files)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  let hash = 0x811c9dc5;
+  for (const file of sorted) {
+    for (let index = 0; index < file.length; index += 1) {
+      hash ^= file.charCodeAt(index);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+  }
+  return `gate-${sorted.length}-${hash.toString(16).padStart(8, '0')}`;
+}
+
+/** Split a changed-file list (e.g. 183 files) into identity-carrying shards; every file is introduced by its own shard.
+ *  Contiguous slices keep each shard's files in input order, so concatenating shards reproduces the input list. */
+export function planGateRemoteShards(files: readonly string[], shardCount: number, orchestrationId: string): GateRemoteShard[] {
+  if (!Number.isSafeInteger(shardCount) || shardCount < 1) throw new Error('invalid shard count');
+  const sorted = [...new Set(files)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+  if (!sorted.length) throw new Error('no files to shard');
+  if (shardCount > sorted.length) throw new Error(`shard count ${shardCount} exceeds file count ${sorted.length}`);
+  const base = Math.floor(sorted.length / shardCount);
+  const extra = sorted.length % shardCount;
+  return Array.from({ length: shardCount }, (_, index) => {
+    const start = index * base + Math.min(index, extra);
+    const size = base + (index < extra ? 1 : 0);
+    const shardFiles = sorted.slice(start, start + size);
+    return {
+      orchestrationId,
+      shardId: `${orchestrationId}/shard-${index + 1}`,
+      totalShards: shardCount,
+      position: index + 1,
+      files: shardFiles,
+      introducedFiles: [...shardFiles],
+    };
+  });
+}

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

@@ -1,10 +1,10 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statfsSync, statSync, writeFileSync } from 'node:fs';
-import { availableParallelism, freemem, tmpdir } from 'node:os';
+import { availableParallelism, freemem, loadavg, tmpdir, totalmem } from 'node:os';
 import { join } from 'node:path';
 import { debug, redactSecretText } from '../debug/log.js';
 import { prepareDeterministicChildEnvironment } from '../../scripts/lib/deterministic-env.js';
 import { withGateTestEnv } from '../../scripts/lib/gate-test-env.js';
-import { withBaselineWorktree } from '../self-implement/gate-baseline.js';
+import { withBaselineWorktree, withBaselineWorktreeAsync } from '../self-implement/gate-baseline.js';
 import { aggregateGateTestShards, type GateShardAttempt, type GateShardAggregate } from './shard-aggregate.js';
 import { GateShardCapacityError, planFixedGateTestShards, planSelfGateSpawnSeparatedShards, type GateTestShard } from './shard-plan.js';
 import { isGateSpawnLaneFile } from './spawn-lane-files.js';
@@ -27,6 +27,15 @@ export interface ShardRunResult {
   unmeasuredByShard?: Record<string, string>;
   /** git stderr tail (redacted · ≤2KB · one line) when the baseline worktree could not be added. */
   baselineStderrTail?: string;
+  /** Effective live pool width and its host-load/memory decision, for gate artifacts and diagnosis. */
+  concurrency?: number;
+  concurrencyReason?: string;
+  /** Wall time spent in singleton RSS samples and current+baseline bundles, respectively. */
+  measurementMs?: number;
+  bundleMs?: number;
+  /** Sum of process wall times across bundles (overlaps under concurrency). */
+  currentProcessMs?: number;
+  baselineProcessMs?: number;
 }
 
 /** What a failed shard process leaves behind so «test failure vs runner error» can be told apart after the fact. */
@@ -50,7 +59,19 @@ export interface ShardRunMode {
   /** OP FU — sorted round-robin into `count` shards, zero pre-measurement runs. Default off: the measured planner. */
   fixedDistribution?: boolean;
   /** Measured on the executing host; override only for deterministic planning tests. */
-  hostResources?: { cores: number; freeMemoryGiB: number; freeTmpGiB: number };
+  hostResources?: { cores: number; freeMemoryGiB: number; freeTmpGiB: number; load1?: number };
+  /** Observation after each bundle's first current+baseline attempt; never controls retries or verdict. */
+  onShardComplete?: (progress: ShardRunProgress) => void;
+  /** Maximum concurrently active shard bundles. The default is three, bounded to one through four. */
+  concurrency?: number;
+}
+
+export interface ShardRunProgress {
+  shardId: string;
+  completedShards: number;
+  totalShards: number;
+  completedFiles: number;
+  totalFiles: number;
 }
 
 function hostResources(): ShardRunMode['hostResources'] | undefined {
@@ -63,14 +84,37 @@ function hostResources(): ShardRunMode['hostResources'] | undefined {
       const availableKiB = /^MemAvailable:\s+(\d+)\s+kB/m.exec(readFileSync('/proc/meminfo', 'utf8'))?.[1];
       if (availableKiB) freeMemoryGiB = Number(availableKiB) / (1024 ** 2);
     }
+    if (process.platform === 'darwin') {
+      // macOS freemem excludes reclaimable cache; node-b reported 5 GiB free of 512 GiB while
+      // memory_pressure reported 91% available. A freemem cap would silently serialize the gate.
+      const pressure = Bun.spawnSync(['memory_pressure', '-Q'], { stdout: 'pipe', stderr: 'ignore', timeout: 2_000 });
+      const percent = /System-wide memory free percentage:\s*(\d+(?:\.\d+)?)%/.exec(Buffer.from(pressure.stdout).toString('utf8'))?.[1];
+      if (pressure.exitCode === 0 && percent !== undefined && Number(percent) >= 0 && Number(percent) <= 100) {
+        freeMemoryGiB = totalmem() / (1024 ** 3) * Number(percent) / 100;
+      }
+    }
     return {
       cores: availableParallelism(),
       freeMemoryGiB,
       freeTmpGiB: Number(tmp.bavail) * Number(tmp.bsize) / (1024 ** 3),
+      load1: loadavg()[0],
     };
   } catch { return undefined; }
 }
 
+/** A conservative snapshot taken before sampling. Explicit 1 preserves the old serial child order. */
+export function resolveShardConcurrency(configured: number | undefined, resources: ShardRunMode['hostResources'], budgetGiB: number): { count: number; reason: string } {
+  if (!resources || !Number.isFinite(resources.cores) || resources.cores < 1) return { count: Math.max(1, Math.min(4, configured ?? 3)), reason: configured === undefined ? 'default; host load unavailable' : 'configured; host load unavailable' };
+  const loadRatio = Number.isFinite(resources.load1) ? resources.load1! / resources.cores : null;
+  const target = configured ?? (loadRatio !== null && loadRatio >= 0.8 ? 2
+    : loadRatio !== null && loadRatio <= 0.35 && resources.cores >= 8 ? 4 : 3);
+  const cpuCap = Math.max(1, Math.floor(resources.cores));
+  const memoryCap = Number.isFinite(resources.freeMemoryGiB) && Number.isFinite(budgetGiB) && budgetGiB > 0
+    ? Math.max(1, Math.floor(resources.freeMemoryGiB / budgetGiB)) : 4;
+  const count = Math.max(1, Math.min(4, target, cpuCap, memoryCap));
+  return { count, reason: `${configured === undefined ? 'adaptive' : `configured ${configured}`} · host load/cores ${loadRatio === null ? '?' : loadRatio.toFixed(2)} · free ${resources.freeMemoryGiB.toFixed(1)} GiB · shard budget ${budgetGiB} GiB` };
+}
+
 /** One expansion slot needs one CPU, one shard memory budget, and 1 GiB of free tmp space.
  *  Explicitly requested shards remain the caller's choice; this only limits automatic growth. */
 export function maxAutomaticShardCount(requested: number, budgetGiB: number, resources: ShardRunMode['hostResources']): number {
@@ -94,6 +138,7 @@ export type ShardProcess = (cwd: string, files: readonly string[]) => {
   /** Present only when the process failed (exit≠0 · signal · no JUnit) — observation only, never part of the verdict. */
   failure?: ShardFailureOutput;
 };
+export type AsyncShardProcess = (cwd: string, files: readonly string[]) => Promise<ReturnType<ShardProcess>>;
 
 export const SHARD_FAILURE_TAIL_BYTES = 64 * 1024;
 
@@ -103,6 +148,29 @@ function outputTail(bytes: Uint8Array | undefined): string {
   return redactSecretText(Buffer.from(tail).toString('utf8'));
 }
 
+/** Drain a child pipe without retaining its entire output. Diagnostics need the opening context and failure tail. */
+async function boundedChildOutput(stream: ReadableStream<Uint8Array>, abort: AbortSignal): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const cancel = () => { void reader.cancel('child output drain timed out').catch(() => {}); };
+  abort.addEventListener('abort', cancel, { once: true });
+  const headLimit = 1024;
+  let head = new Uint8Array(0);
+  let tail = new Uint8Array(0);
+  let total = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (head.byteLength < headLimit) head = Buffer.concat([head, value.subarray(0, headLimit - head.byteLength)]);
+      tail = value.byteLength >= SHARD_FAILURE_TAIL_BYTES
+        ? value.slice(-SHARD_FAILURE_TAIL_BYTES)
+        : Buffer.concat([tail, value]).subarray(-SHARD_FAILURE_TAIL_BYTES);
+    }
+  } finally { abort.removeEventListener('abort', cancel); reader.releaseLock(); }
+  return total <= SHARD_FAILURE_TAIL_BYTES ? tail : Buffer.concat([head, tail]);
+}
+
 /** `<shardId>.failure.json` per failed shard (shard ids are already `shard-<n>`). Top level = the latest current-side
  *  failure (else the latest baseline one); `failures` keeps every failed side/attempt. Returns the written paths. */
 export function writeShardFailureEvidence(dir: string, evidence: readonly ShardFailureEvidence[]): string[] {
@@ -162,7 +230,7 @@ export function runShardedGateTests(
     try { fixed = planFixedGateTestShards(files, count); }
     catch (error) { return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), distribution: 'fixed' }; }
     debug.log('self-dev.shard', 'fixed-distribution', { shards: fixed.length, files: fixed.reduce((sum, shard) => sum + shard.files.length, 0) });
-    return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree), distribution: 'fixed' };
+    return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree, mode.onShardComplete), distribution: 'fixed' };
   }
   const rss = new Map<string, number>();
   const seconds = new Map<string, number>();
@@ -199,7 +267,7 @@ export function runShardedGateTests(
       const fixed = planFixedGateTestShards(files, maxCount);
       debug.log('self-dev.shard', 'host-cap-fixed-fallback', { requested: count, cap: maxCount,
         files: new Set(files).size, reason, measurementFailures: measurementFailures ?? 0 });
-      return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree), distribution: 'fixed-cap-fallback',
+      return { ...runPlannedShards(cwd, fixed, baseRef, run, baselineWorktree, mode.onShardComplete), distribution: 'fixed-cap-fallback',
         fallbackReason: reason, ...(measurementFailures ? { measurementFailures } : {}) };
     } catch (error) {
       return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [],
@@ -232,7 +300,7 @@ export function runShardedGateTests(
     requested: count, planned: shards.length, files: new Set(files).size, budgetGiB,
     measurementFailures: measurementFailures ?? 0,
   });
-  return { ...runPlannedShards(cwd, shards, baseRef, run, baselineWorktree), ...(plannedCount > count ? { expandedFrom: count } : {}), ...(measurementFailures ? { measurementFailures } : {}) };
+  return { ...runPlannedShards(cwd, shards, baseRef, run, baselineWorktree, mode.onShardComplete), ...(plannedCount > count ? { expandedFrom: count } : {}), ...(measurementFailures ? { measurementFailures } : {}) };
 }
 
 /** Shared by the measured and the fixed planner: current + baseline per shard, one retry round, one aggregate. */
@@ -242,6 +310,7 @@ function runPlannedShards(
   baseRef: string,
   run: ShardProcess,
   baselineWorktree: typeof withBaselineWorktree,
+  onShardComplete?: ShardRunMode['onShardComplete'],
 ): ShardRunResult {
   const attempts: GateShardAttempt[] = [];
   const failureEvidence: ShardFailureEvidence[] = [];
@@ -256,6 +325,8 @@ function runPlannedShards(
     const treeReadable = (() => { try { return statSync(dir).isDirectory(); } catch { return false; } })();
     const atBase = (shard: GateTestShard) => treeReadable ? shard.files.filter((file) => !absentAtBaseline(join(dir, file))) : [...shard.files];
     let pending = shards;
+    let completedFiles = 0;
+    const totalFiles = new Set(shards.flatMap((shard) => shard.files)).size;
     for (let round = 1; round <= 2 && pending.length; round++) {
       for (const shard of pending) {
         const runSafely = (location: string, selected: readonly string[]): ReturnType<ShardProcess> => {
@@ -279,6 +350,13 @@ function runPlannedShards(
           baselineFiles,
           currentRoot: cwd, baselineRoot: dir,
         });
+        if (round === 1 && onShardComplete) {
+          completedFiles += shard.files.length;
+          try {
+            onShardComplete({ shardId: shard.id, completedShards: attempts.length,
+              totalShards: shards.length, completedFiles, totalFiles });
+          } catch { /* progress is observation only */ }
+        }
       }
       const retry = new Set(aggregateGateTestShards(shards, attempts).retryShardIds);
       pending = shards.filter((shard) => retry.has(shard.id));
@@ -301,6 +379,146 @@ function runPlannedShards(
   };
 }
 
+/** Runs planned bundles concurrently while retaining plan order in attempts and aggregate evidence. */
+export async function runShardedGateTestsAsync(
+  cwd: string,
+  files: readonly string[],
+  baseRef: string,
+  count = 2,
+  run: AsyncShardProcess = runBunShardAsync,
+  baselineWorktree: typeof withBaselineWorktreeAsync = withBaselineWorktreeAsync,
+  budgetGiB = 8,
+  mode: ShardRunMode = {},
+  measure: AsyncShardProcess = run,
+): Promise<ShardRunResult> {
+  if (mode.concurrency !== undefined && (!Number.isSafeInteger(mode.concurrency) || mode.concurrency < 1 || mode.concurrency > 4)) throw new Error('invalid shard concurrency (expected 1–4)');
+  const resources = mode.hostResources ?? hostResources();
+  const selectedConcurrency = resolveShardConcurrency(mode.concurrency, resources, budgetGiB);
+  const concurrency = selectedConcurrency.count;
+  debug.log('self-dev.shard', 'concurrency', { concurrency, reason: selectedConcurrency.reason });
+  const measurementStartedAt = performance.now();
+  const samples = new Map<string, ReturnType<ShardProcess>>();
+  if (!mode.fixedDistribution) {
+    const unique = [...new Set(files)];
+    let nextSample = 0;
+    const sampleWorker = async () => {
+      for (;;) {
+        const index = nextSample++;
+        if (index >= unique.length) return;
+        const file = unique[index]!;
+        try { samples.set(file, await measure(cwd, [file])); }
+        catch (error) {
+          debug.log('self-dev.shard', 'rss-measurement-failed', { file, error: redactSecretText(String(error)).slice(0, 500) });
+          samples.set(file, { exitCode: null });
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, unique.length) }, () => sampleWorker()));
+  }
+  const measurementMs = Math.round(performance.now() - measurementStartedAt);
+  // Reuse the established measured/fixed planner and its host-cap fallback. The callback supplies a
+  // planning-only aggregate, so this phase never launches a shard or creates a baseline worktree.
+  const planningOnlyBaseline = (() => ({ status: 'passed' as const, retryShardIds: [] })) as unknown as typeof withBaselineWorktree;
+  const planned = runShardedGateTests(cwd, files, baseRef, count, (_cwd, selected) => samples.get(selected[0]!) ?? { exitCode: null },
+    planningOnlyBaseline, budgetGiB, { ...mode, ...(resources ? { hostResources: resources } : {}) });
+  if (planned.reason) return { ...planned, concurrency, concurrencyReason: selectedConcurrency.reason, measurementMs, bundleMs: 0 };
+  const shards = planned.shards;
+  const attempts: GateShardAttempt[] = [];
+  const failureEvidence: ShardFailureEvidence[] = [];
+  const bundlesStartedAt = performance.now();
+  let currentProcessMs = 0;
+  let baselineProcessMs = 0;
+  const baseline = await baselineWorktree(cwd, baseRef, async (dir) => {
+    const treeReadable = (() => { try { return statSync(dir).isDirectory(); } catch { return false; } })();
+    // Baseline membership is invariant for both rounds. Cache it before launching children.
+    const atBase = new Map(shards.map((shard) => [shard.id,
+      treeReadable ? shard.files.filter((file) => !absentAtBaseline(join(dir, file))) : [...shard.files]]));
+    const baselinePassCache = new Map<string, ReturnType<ShardProcess>>();
+    const totalFiles = new Set(shards.flatMap((shard) => shard.files)).size;
+    let completedShards = 0;
+    let completedFiles = 0;
+    let pending = shards;
+    for (let round = 1; round <= 2 && pending.length; round++) {
+      const roundAttempts = new Array<GateShardAttempt>(pending.length);
+      const roundEvidence = new Array<ShardFailureEvidence[]>(pending.length);
+      let next = 0;
+      const runSafely = async (location: string, selected: readonly string[]): Promise<ReturnType<ShardProcess>> => {
+        try { return await run(location, selected); }
+        catch (error) {
+          debug.log('self-dev.shard', 'bundle-runner-failed', { location, files: selected,
+            error: redactSecretText(String(error)).slice(0, 500) });
+          return { exitCode: null };
+        }
+      };
+      const worker = async () => {
+        for (;;) {
+          const index = next++;
+          if (index >= pending.length) return;
+          const shard = pending[index]!;
+          const baselineFiles = atBase.get(shard.id)!;
+          if (baselineFiles.length < shard.files.length) {
+            debug.log('self-dev.shard', 'baseline-files-absent', { shardId: shard.id, round,
+              absent: shard.files.filter((file) => !baselineFiles.includes(file)) });
+          }
+          const currentStartedAt = performance.now();
+          const current = await runSafely(cwd, shard.files);
+          currentProcessMs += performance.now() - currentStartedAt;
+          const cached = concurrency > 1 && round > 1 ? baselinePassCache.get(shard.id) : undefined;
+          if (cached) debug.log('self-dev.shard', 'baseline-cache-hit', { shardId: shard.id, round });
+          const baselineStartedAt = performance.now();
+          const base = cached ?? (baselineFiles.length ? await runSafely(dir, baselineFiles) : { exitCode: 0 });
+          baselineProcessMs += performance.now() - baselineStartedAt;
+          if (concurrency > 1 && baselineFiles.length && base.exitCode === 0 && !base.signal && base.junit) baselinePassCache.set(shard.id, base);
+          roundAttempts[index] = {
+            shardId: shard.id, attempt: round, currentJUnit: current.junit, baselineJUnit: base.junit,
+            currentExitCode: current.exitCode, baselineExitCode: base.exitCode,
+            currentSignal: current.signal, baselineSignal: base.signal,
+            currentDiagnostic: current.diagnostic, baselineDiagnostic: base.diagnostic,
+            baselineFiles, currentRoot: cwd, baselineRoot: dir,
+          };
+          roundEvidence[index] = [];
+          for (const [side, result, selected] of [
+            ['current', current, shard.files], ['baseline', base, baselineFiles],
+          ] as const) {
+            if (result.failure) roundEvidence[index]!.push({ shardId: shard.id, side, attempt: round,
+              files: [...selected], exitCode: result.exitCode, signal: result.signal ?? null, ...result.failure });
+          }
+          if (round === 1 && mode.onShardComplete) {
+            completedShards++;
+            completedFiles += shard.files.length;
+            try { mode.onShardComplete({ shardId: shard.id, completedShards, totalShards: shards.length,
+              completedFiles, totalFiles }); } catch { /* observation only */ }
+          }
+        }
+      };
+      await Promise.all(Array.from({ length: Math.min(concurrency, pending.length) }, () => worker()));
+      attempts.push(...roundAttempts);
+      for (const evidence of roundEvidence) failureEvidence.push(...evidence);
+      const retry = new Set(aggregateGateTestShards(shards, attempts).retryShardIds);
+      pending = shards.filter((shard) => retry.has(shard.id));
+    }
+    return aggregateGateTestShards(shards, attempts);
+  });
+  const evidence = failureEvidence.length ? { failureEvidence } : {};
+  const bundleMs = Math.round(performance.now() - bundlesStartedAt);
+  if ('retryShardIds' in baseline) return {
+    ...planned, aggregate: baseline, attempts, ...evidence, concurrency, concurrencyReason: selectedConcurrency.reason, measurementMs, bundleMs,
+    currentProcessMs: Math.round(currentProcessMs), baselineProcessMs: Math.round(baselineProcessMs),
+    ...(baseline.retryShardIds.length ? { unmeasuredByShard: incompleteShardReasons(baseline.retryShardIds, attempts) } : {}),
+  };
+  const retryShardIds = shards.map((shard) => shard.id);
+  const stderrTail = baseline.gitStderrTail;
+  const stderrPart = stderrTail ? ` · git stderr: ${stderrTail}` : '';
+  return {
+    ...planned, aggregate: { status: 'unmeasured', retryShardIds }, attempts, concurrency, concurrencyReason: selectedConcurrency.reason, measurementMs, bundleMs,
+    currentProcessMs: Math.round(currentProcessMs), baselineProcessMs: Math.round(baselineProcessMs),
+    reason: baseline.log, ...evidence,
+    unmeasuredByShard: Object.fromEntries(retryShardIds.map((id) => [id,
+      `baseline worktree: ${redactSecretText(baseline.log).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500)}${stderrPart}`])),
+    ...(stderrTail ? { baselineStderrTail: stderrTail } : {}),
+  };
+}
+
 function incompleteShardReasons(shardIds: readonly string[], attempts: readonly GateShardAttempt[]): Record<string, string> {
   return Object.fromEntries(shardIds.map((id) => {
     const latest = attempts.filter((attempt) => attempt.shardId === id).at(-1);
@@ -360,3 +578,89 @@ export function runBunShardWithSpawn(cwd: string, files: readonly string[], spaw
     rmSync(dir, { recursive: true, force: true });
   }
 }
+
+/** Nonblocking child runner; each bundle still owns its own deterministic environment and JUnit path. */
+export async function runBunShardAsync(cwd: string, files: readonly string[], drainTimeoutMs = 5_000): Promise<ReturnType<ShardProcess>> {
+  const timeout = selfGateShardTimeoutMs(files);
+  const spawnLane = timeout === 120_000;
+  const dir = mkdtempSync(join(tmpdir(), 'elanous-shard-junit-'));
+  const report = join(dir, 'result.xml');
+  const isolated = prepareDeterministicChildEnvironment('elanous-shard-test-env-', { env: withGateTestEnv(process.env) });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let drainTimer: ReturnType<typeof setTimeout> | undefined;
+  const drainAbort = new AbortController();
+  try {
+    const args = ['test', ...(spawnLane ? ['--timeout=120000'] : []), '--reporter=junit', `--reporter-outfile=${report}`, ...files];
+    const started = performance.now();
+    const child = Bun.spawn(['bun', ...args], { cwd, env: isolated.env, stdout: 'pipe', stderr: 'pipe' });
+    let timedOut = false;
+    let drainTimedOut = false;
+    timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeout);
+    const stdoutOutput = boundedChildOutput(child.stdout, drainAbort.signal);
+    const stderrOutput = boundedChildOutput(child.stderr, drainAbort.signal);
+    const exited = child.exited.then((code) => {
+      // Pipe draining can continue after process exit; a late timer must not relabel a clean exit as SIGKILL.
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+      drainTimer = setTimeout(() => {
+        drainTimedOut = true;
+        debug.log('self-dev.shard', 'output-drain-timeout', { cwd, files, drainTimeoutMs });
+        drainAbort.abort();
+      }, drainTimeoutMs);
+      return code;
+    });
+    const [exitCode, stdoutBuffer, stderrBuffer] = await Promise.all([
+      exited,
+      stdoutOutput,
+      stderrOutput,
+    ]);
+    if (drainTimer) clearTimeout(drainTimer);
+    drainTimer = undefined;
+    const stdout = stdoutBuffer;
+    const stderr = stderrBuffer;
+    const durationMs = performance.now() - started;
+    const usage = child.resourceUsage();
+    const junit = existsSync(report) ? readFileSync(report, 'utf8') : undefined;
+    const signal = drainTimedOut ? 'DRAIN_TIMEOUT' : timedOut ? 'SIGKILL' : child.signalCode ? String(child.signalCode) : undefined;
+    const failed = exitCode !== 0 || !!signal || junit === undefined;
+    return {
+      exitCode, signal, junit,
+      ...(files.length === 1 ? { rssMb: usage ? usage.maxRSS / (1024 * 1024) : undefined, seconds: durationMs / 1000 } : {}),
+      ...(junit === undefined && (exitCode !== 0 || signal) ? { diagnostic: boundedDiagnostic(stdout, stderr) } : {}),
+      ...(failed ? { failure: { durationMs: Math.round(durationMs), stdoutTail: outputTail(stdout), stderrTail: outputTail(stderr) } } : {}),
+    };
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (drainTimer) clearTimeout(drainTimer);
+    drainAbort.abort();
+    isolated.cleanup();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** GATE-REMOTE-SHARD-PLAN — identity of one remote shard. files/introducedFiles are optional: a caller that only relays
+ *  identity (CLI wiring) passes none, while a planner-produced shard carries its file-level attribution. */
+export interface RemoteShardSpec {
+  orchestrationId: string;
+  shardId: string;
+  totalShards: number;
+  position: number;
+  files?: readonly string[];
+  introducedFiles?: readonly string[];
+}
+
+/** The identity slice that rides a remote gate command line — validated so a dropped flag fails loudly, not silently. */
+export function remoteShardArgArgs(shard: RemoteShardSpec, options?: { planFile?: string }): string[] {
+  if (!shard.orchestrationId.trim()) throw new Error('orchestration id must be non-empty');
+  if (!shard.shardId.trim()) throw new Error('shard id must be non-empty');
+  if (!Number.isSafeInteger(shard.totalShards) || shard.totalShards < 1) throw new Error('shard total must be a positive integer');
+  if (!Number.isSafeInteger(shard.position) || shard.position < 1) throw new Error('shard position must be a positive integer');
+  const args = ['--orchestration-id', shard.orchestrationId, '--shard-id', shard.shardId, '--shard-position', String(shard.position)];
+  if (options?.planFile !== undefined && options.planFile !== '') args.push('--shard-plan', options.planFile);
+  return args;
+}
+
+/** Full remote command for one shard — the exact argv a remote host (e.g. an node-b pod shard) would run. */
+export function remoteShardArgv(shard: RemoteShardSpec, options?: { planFile?: string }): string[] {
+  return ['bun', 'bin/elanous.mjs', '--test', 'self', 'gate', '--changed', '--shards', String(shard.totalShards), ...remoteShardArgArgs(shard, options)];
+}

package/src/self-implement/comment-only-source.ts

@@ -0,0 +1,54 @@
+import ts from 'typescript';
+
+/** Exclude importer expansion only when non-comment bytes and comment boundaries
+ * are identical. The TypeScript parser finds comments within JSDoc that a bare
+ * scanner can misread because their prose contains backticks. */
+export function isCommentOnlySourceChange(before: string, after: string, path: string): boolean {
+  if (before === after || !/\.(?:[cm]?[jt]sx?)$/.test(path)) return false;
+  const kind = /\.(?:[cm]?[jt]sx)$/.test(path) ? ts.ScriptKind.TSX
+    : /\.(?:[cm]?js)$/.test(path) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
+  const collect = (source: string): { masked: string; comments: string[] } | null => {
+    const file = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, kind);
+    if (file.parseDiagnostics.length) return null;
+    const ranges = new Map<number, ts.CommentRange>();
+    const add = (found: ts.CommentRange[] | undefined) => {
+      for (const range of found ?? []) ranges.set(range.pos, range);
+    };
+    const visit = (node: ts.Node) => {
+      add(ts.getLeadingCommentRanges(source, node.getFullStart()));
+      add(ts.getTrailingCommentRanges(source, node.getEnd()));
+      ts.forEachChild(node, visit);
+    };
+    visit(file);
+    const comments: string[] = [];
+    let masked = '';
+    let end = 0;
+    for (const range of [...ranges.values()].sort((left, right) => left.pos - right.pos)) {
+      if (range.pos < end) return null;
+      const comment = source.slice(range.pos, range.end);
+      comments.push(comment);
+      masked += source.slice(end, range.pos) + `\u0000C${range.kind}:${comment.match(/\r\n|\r|\n/g)?.join('') ?? ''}\u0000`;
+      end = range.end;
+    }
+    return { masked: masked + source.slice(end), comments };
+  };
+  const old = collect(before);
+  const current = collect(after);
+  if (!old || !current || old.masked !== current.masked || old.comments.length !== current.comments.length) return false;
+  const directive = /^(?:\/\/\/|\/\/[#@])|@|(?:eslint|istanbul|coverage|#__PURE__|__NO_SIDE_EFFECTS__)/i;
+  // Any unquoted @ may be a TypeScript/JSDoc tag, including newly introduced ones.
+  // A backticked example username such as `@example_bot` is prose, not a tag.
+  const semanticText = (comment: string) => comment.trim().replace(/`[^`\r\n]*`/g, '');
+  let changed = false;
+  for (let index = 0; index < old.comments.length; index++) {
+    const prior = old.comments[index]!;
+    const next = current.comments[index]!;
+    if (prior === next) continue;
+    changed = true;
+    // Ordinary inline block comments and line comments stay in the importer set.
+    // This exemption is intentionally limited to JSDoc prose edits.
+    if (!prior.startsWith('/**') || !next.startsWith('/**')) return false;
+    if (directive.test(semanticText(prior)) || directive.test(semanticText(next))) return false;
+  }
+  return changed;
+}