elanous 0.2.37 → 0.2.40

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

@@ -9,6 +9,7 @@ export { SUPERVISOR_STOP_REASONS } from './run-types.js';
 import { recordSelfDevRunSupervisorStop, selfDevRunsDir } from './run-store.js';
 import { debug } from '../debug/log.js';
 import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
+import { selectKnowhowPack } from '../self-implement/knowhow-pack.js';
 import { routeSupervisorVerdict } from './supervisor-verdict-edges.js';
 import type { TaskAgentShadowInput } from '../task-agent/shadow.js';
 import { cardPrNumber, taskAgentStatePath } from '../task-agent/task-hand.js';
@@ -101,6 +102,10 @@ export interface SupervisorDecision {
   action: 'relaunch' | 'add-repair-task' | 'stop';
   stopReason?: SupervisorStopReason;
   why: string;
+  /** Repository lessons pulled at this decision, never appended to a child's goal. */
+  knowhowPackSliceIds?: string[];
+  /** Bounded reference for the supervisor handoff. It is evidence, not an executable child instruction. */
+  knowhowPackReference?: string;
   round: number;
   rerunnable: string[];
   reworkable: string[];
@@ -374,6 +379,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 +458,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 +624,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 +753,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 +766,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}`,
   };
 }
 
@@ -1012,6 +1032,8 @@ export function patternMineSignaturesFromDecision(decision: SupervisorDecision):
 
 export interface SuperviseRunOptions {
   initial: readonly SupervisorJobResult[];
+  /** Stable repository source for decision-time knowhow; falls back to a result worktree if omitted. */
+  knowhowRepo?: string;
   rerun: (previous: readonly SupervisorJobResult[], invocation: { relaunch: true; repairGoals?: Record<string, string> }) => Promise<readonly SupervisorJobResult[]>;
   limits?: SupervisorLimits;
   enrich?: (results: readonly SupervisorJobResult[]) => readonly SupervisorJobResult[];
@@ -1132,6 +1154,18 @@ export async function superviseRun(opts: SuperviseRunOptions): Promise<Superviso
       } : {}),
     });
 
+    // The supervisor consumes knowhow when it judges a failed piece. Keep the child prompt untouched.
+    const failedPiece = results.find((result) => result.status === 'failed' && result.feature.trim());
+    if (failedPiece) {
+      const repo = opts.knowhowRepo ?? failedPiece.worktreePath;
+      if (repo) {
+        const pulled = selectKnowhowPack(repo, failedPiece.feature);
+        try { opts.observe?.('knowhow-pack-decision', { taskId: failedPiece.taskId, ids: pulled.ids, reason: pulled.reason, action: decision.action }); } catch { /* fail-soft */ }
+        if (pulled.ids.length) decision = { ...decision, knowhowPackSliceIds: pulled.ids, knowhowPackReference: pulled.text,
+          why: `${decision.why} · 판단 참고 노하우 ${pulled.ids.join(',')}` };
+      }
+    }
+
     const runId = opts.runStore?.runId ?? results.find((result) => result.runId?.trim())?.runId ?? null;
 
     let decomposePromotion: DecomposePromotionObservation = decision.decomposable.length === 0

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,9 +59,11 @@ 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 {
@@ -73,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 {
@@ -104,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;
 
@@ -113,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[] {
@@ -321,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);
@@ -381,6 +579,65 @@ export function runBunShardWithSpawn(cwd: string, files: readonly string[], spaw
   }
 }
 
+/** 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 {

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;
+}

package/src/self-implement/device-first.ts

@@ -72,6 +72,12 @@ export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], r
   const evidenceCommand = /완료\s*경계\s*증거\s*명령\s*[:：]\s*([^\r\n]+)/u.exec(goal)?.[1] ?? '';
   const goalFeatureTest = [evidenceCommand, goal].flatMap((text) => [...text.matchAll(/(?:src|test)\/[\w./-]+\.test\.[cm]?[jt]sx?/gu)]
     .map((match) => match[0])).find((path) => path !== test && !path.startsWith('src/ux-sim/'));
+  // ⭐ TDD 를 로직으로(S4) — 문면이 아니라 로직 판정에 필요한 RED→GREEN 기록 필드를 조각 계획에 실어
+  //   넘긴다. 오케스트레이터가 [tdd-red]/[tdd-green] 기록의 태그·같은 명령·결과를 판정한다(문면 유지).
+  const tddRecordFields = 'TDD 기록 필드: 첫 조각 커밋에 피처 시험을 먼저 쓰고 구현 전 실행 RED 기록을 남긴다'
+    + " — 'EVIDENCE: [tdd-red] <무엇을 확인했나> || <증거 명령>' 다음 줄 'RESULT: <실패 요약 한 줄>'"
+    + " · 구현 뒤 같은 명령의 GREEN 기록을 남긴다 — 'EVIDENCE: [tdd-green] <무엇을 확인했나> || <같은 증거 명령>' 다음 줄 'RESULT: <통과 요약 한 줄>'"
+    + ' · 오케스트레이터가 두 기록의 태그·같은 명령·결과를 로직으로 판정하고 없으면 수리 라운드를 돌린다';
   const completeFeatureStage = (stage: string, index: number): string => {
     const withPredecessor = stage.includes(predecessor) ? stage : `${stage}\n${predecessor}`;
     const declaredGoalTest = index === 0 ? goalFeatureTest : undefined;
@@ -87,10 +93,10 @@ export function ensureDeviceFirstSteps(goal: string, steps: readonly string[], r
       ? stageSource.replace(/\.ts$/u, '.test.ts') : undefined;
     const featureTest = declaredGoalTest ?? stageTest
       ?? (existingSiblingTest && existsSync(join(root!, existingSiblingTest)) ? existingSiblingTest : undefined);
-    if (!featureTest) return `${withoutWrongPlan}\n검증 계획(TDD): 시험 경로 미확정(${stageSource ? `${stageSource}의 시험 확장자 미정` : '조각 대상 경로 없음'}) · 이 조각에서 시험 경로를 먼저 정하고 RED 실패 뒤 같은 명령으로 GREEN을 확인한다.`;
+    if (!featureTest) return `${withoutWrongPlan}\n검증 계획(TDD): 시험 경로 미확정(${stageSource ? `${stageSource}의 시험 확장자 미정` : '조각 대상 경로 없음'}) · 이 조각에서 시험 경로를 먼저 정하고 RED 실패 뒤 같은 명령으로 GREEN을 확인한다. ${tddRecordFields}`;
     const inventory = root === undefined ? '시험 재고 미측정(대상 루트 미상)'
       : existsSync(join(root, featureTest)) ? '기존 시험' : '신규 시험(이 조각에서 먼저 신설)';
-    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다.`;
+    return `${withoutWrongPlan}\n검증 계획(TDD): ${inventory} ${featureTest} · 피처 시험 bun test ${featureTest}를 구현 전에 RED로 확인하고 생산 경로를 구현한 뒤 같은 명령으로 GREEN을 확인한다. ${tddRecordFields}`;
   };
   const targetPaths = [decision.device, test].filter((path) => root !== undefined && existsSync(join(root, path)));
   const newPaths = [decision.device, test].filter((path) => !targetPaths.includes(path));