elanous 0.2.18 → 0.2.20

package/src/self-dev/pr-preview.ts

@@ -0,0 +1,247 @@
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface PreviewOptions {
+  target: string;
+  repoRoot: string;
+  scenario?: string;
+  /** Main-based combined preview: only existing config paths may be enabled. */
+  flags?: readonly string[];
+  /** PR heads to preview together on main when no feature flags exist. */
+  bundlePrs?: readonly number[];
+  commentPr?: number;
+}
+export interface PreviewResult {
+  target: string;
+  head: string;
+  scenario: string;
+  status: 'passed' | 'friction';
+  report: string;
+  prNumber?: number;
+  commented: boolean;
+}
+export function readPreviewResult(directory: string): PreviewResult | null {
+  try {
+    const value = JSON.parse(readFileSync(join(directory, 'preview-result.json'), 'utf8')) as PreviewResult;
+    return value && (value.status === 'passed' || value.status === 'friction') && typeof value.head === 'string' ? value : null;
+  } catch { return null; }
+}
+
+export interface PreviewDeps {
+  run?: (command: string, args: readonly string[], cwd: string, timeoutMs?: number) => { status: number | null; stdout: string; stderr: string };
+  makeDir?: () => string;
+  dispose?: (directory: string) => void;
+  wait?: (ms: number) => Promise<void>;
+  /** Probe a test-mode daemon without injecting a global HTTP client into the command runner. */
+  probePwa?: (url: string) => Promise<boolean>;
+}
+
+const SCENARIOS: Record<string, { input: string; expected: string; matches: (snapshot: string) => boolean }> = {
+  // GOODHART (#24844 review): a group head (`▸ 시작`) or the echoed `/help` is not the list. The /help modal
+  // (help-from-registry.ts) prints one `/name  description` row per command; the «시작» group alone has six.
+  // Pass only when at least three other start-group commands are listed as rows.
+  S2: { input: '/help', expected: 'help command list (/status, /model, /clear ... rows)', matches: (s) =>
+    ['status', 'model', 'clear', 'new', 'resume'].filter((name) => new RegExp(`(?:^|\\s)/${name}(?: \\([^)]*\\))?\\s{2,}\\S`, 'mu').test(s)).length >= 3 },
+  S3: { input: '/status', expected: 'model and connection', matches: (s) => /모델|model/iu.test(s) && /연결|connection/iu.test(s) },
+  S6: { input: '/now', expected: 'current runs or schedules', matches: (s) => /지금|도는 런|스케줄|running|schedule/iu.test(s) },
+  S7: { input: '/term list', expected: 'terminal/PTY list', matches: (s) => /terminal|pty|터미널/iu.test(s) },
+  S8: { input: '/model', expected: 'model choices', matches: (s) => /빠름|보통|깊음|terra|sol|luna|선택/iu.test(s) },
+  S9: { input: '/harness', expected: 'harness usage or stages', matches: (s) => /usage:.*harness|저작|구현|리뷰|착지/iu.test(s) },
+};
+
+/**
+ * Lines of `after` that were not already on `before`'s screen (multiset by line, trailing spaces ignored).
+ * A prefix check is not enough: the PTY re-renders and scrolls, so the previous scenario's answer can
+ * reappear anywhere on the next screen (#24844 review). A repeated line is conservatively treated as old.
+ */
+export function previewFreshLines(before: string, after: string): string {
+  const seen = new Map<string, number>();
+  for (const line of before.split('\n')) {
+    const key = line.trimEnd();
+    if (key) seen.set(key, (seen.get(key) ?? 0) + 1);
+  }
+  return after.split('\n').filter((line) => {
+    const key = line.trimEnd();
+    if (!key) return false;
+    const left = seen.get(key) ?? 0;
+    if (left > 0) { seen.set(key, left - 1); return false; }
+    return true;
+  }).join('\n');
+}
+
+/** Whether a fresh screen region shows the scenario's expected answer (exported for the preview tests). */
+export function previewScenarioMatches(scenario: string, fresh: string): boolean {
+  const entry = Object.hasOwn(SCENARIOS, scenario) ? SCENARIOS[scenario] : undefined;
+  if (!entry) throw new Error(`TUI-COMFORT §4: unsupported scenario ${scenario}`);
+  return entry.matches(fresh);
+}
+
+export function previewScenarioInput(scenario: string): string {
+  const text = Object.hasOwn(SCENARIOS, scenario) ? SCENARIOS[scenario] : undefined;
+  if (!text) throw new Error(`TUI-COMFORT §4: unsupported scenario ${scenario}; available: ${Object.keys(SCENARIOS).join(', ')}`);
+  return text.input;
+}
+
+const defaultRun: NonNullable<PreviewDeps['run']> = (command, args, cwd, timeoutMs = 120_000) => {
+  const r = spawnSync(command, [...args], { cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 });
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? String(r.error ?? '') };
+};
+
+/** Build and exercise a detached head, never the caller's checkout. The report is posted only after measurement. */
+export async function runPrPreview(options: PreviewOptions, deps: PreviewDeps = {}): Promise<PreviewResult> {
+  const run = deps.run ?? defaultRun;
+  const root = resolve(options.repoRoot);
+  const target = options.target.trim();
+  if (!target || target.startsWith('-') || /[\s\x00-\x1f]/u.test(target)) throw new Error('preview: invalid PR number or branch');
+  const isPr = /^[1-9]\d*$/u.test(target);
+  if (isPr && !Number.isSafeInteger(Number(target))) throw new Error('preview: invalid PR number');
+  if (/^\d+$/u.test(target) && !isPr) throw new Error('preview: invalid PR number');
+  if (options.commentPr !== undefined && (!Number.isSafeInteger(options.commentPr) || options.commentPr <= 0)) throw new Error('preview: invalid --comment-pr');
+  const bundlePrs = options.bundlePrs ?? [];
+  if (bundlePrs.length && (target !== 'main' || (options.flags?.length ?? 0) > 0)) throw new Error('preview: --bundle-pr requires main without feature flags');
+  if (bundlePrs.length && (new Set(bundlePrs).size !== bundlePrs.length || bundlePrs.some((pr) => !Number.isSafeInteger(pr) || pr <= 0))) throw new Error('preview: invalid or duplicate --bundle-pr');
+  if (target === 'main' && options.commentPr === undefined) throw new Error('preview: main ⊕ flags requires --comment-pr <PR number> to publish the result');
+  if (isPr && options.commentPr !== undefined && options.commentPr !== Number(target)) throw new Error('preview: --comment-pr must match the target PR');
+  const flags = options.flags ?? [];
+  if (flags.length && target !== 'main') throw new Error('preview: --flag requires main (main ⊕ feature flags)');
+  if (flags.some((flag) => !/^[a-zA-Z][\w-]*(?:\.[a-zA-Z][\w-]*)+$/u.test(flag))) throw new Error('preview: --flag expects an existing dotted config path');
+  const scenarios = (options.scenario ?? 'S2').split(',').map((id) => id.trim());
+  if (scenarios.length === 0 || new Set(scenarios).size !== scenarios.length) throw new Error('preview: duplicate or empty scenario');
+  for (const id of scenarios) previewScenarioInput(id);
+  const scenario = scenarios.join(',');
+  const check = (command: string, args: readonly string[], cwd: string, timeout?: number): string => {
+    const r = run(command, args, cwd, timeout);
+    if (r.status !== 0) throw new Error(`preview: ${command} ${args.join(' ')} failed: ${(r.stdout + '\n' + r.stderr).slice(-600)}`);
+    return r.stdout.trim();
+  };
+  let prNumber = isPr ? Number(target) : options.commentPr;
+  let branchPrHead: string | undefined;
+  let ref = target;
+  if (isPr) {
+    const pr = JSON.parse(check('gh', ['pr', 'view', target, '--json', 'number,headRefOid'], root)) as { number?: number; headRefOid?: string };
+    if (pr.number !== Number(target) || !/^[0-9a-f]{40}$/iu.test(pr.headRefOid ?? '')) throw new Error('preview: PR head is unavailable');
+    ref = pr.headRefOid!;
+  } else if (target !== 'main') {
+    check('git', ['check-ref-format', '--branch', target], root);
+    if (options.commentPr === undefined) {
+      const matching = JSON.parse(check('gh', ['pr', 'list', '--head', target, '--state', 'open', '--json', 'number,headRefOid'], root)) as Array<{ number?: number; headRefOid?: string }>;
+      if (matching.length !== 1 || !Number.isSafeInteger(matching[0]?.number)) throw new Error('preview: branch has no unique open PR; use --comment-pr <PR number>');
+      prNumber = matching[0]!.number;
+      branchPrHead = matching[0]!.headRefOid;
+    }
+  }
+  if (isPr && run('git', ['cat-file', '-e', `${ref}^{commit}`], root).status !== 0) {
+    check('git', ['fetch', '--no-tags', 'origin', `pull/${target}/head`], root, 120_000);
+    const fetched = check('git', ['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], root);
+    if (fetched !== ref) throw new Error('preview: PR head changed while fetching; retry');
+  }
+  const head = check('git', ['rev-parse', '--verify', `${ref}^{commit}`], root);
+  if (!/^[0-9a-f]{40}$/iu.test(head)) throw new Error('preview: unresolved commit');
+  if (target !== 'main' && !isPr) {
+    const pr = JSON.parse(check('gh', ['pr', 'view', String(prNumber), '--json', 'headRefOid,headRefName'], root)) as { headRefOid?: string; headRefName?: string };
+    if (pr.headRefName !== target || pr.headRefOid !== head || (branchPrHead !== undefined && branchPrHead !== head)) throw new Error('preview: branch does not match the target PR head; use the PR number');
+  }
+  const bundleHeads = bundlePrs.map((number) => {
+    const pr = JSON.parse(check('gh', ['pr', 'view', String(number), '--json', 'number,headRefOid'], root)) as { number?: number; headRefOid?: string };
+    if (pr.number !== number || !/^[0-9a-f]{40}$/iu.test(pr.headRefOid ?? '')) throw new Error(`preview: PR #${number} head is unavailable`);
+    const oid = pr.headRefOid!;
+    if (run('git', ['cat-file', '-e', `${oid}^{commit}`], root).status !== 0) {
+      check('git', ['fetch', '--no-tags', 'origin', `pull/${number}/head`], root, 120_000);
+      if (check('git', ['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], root) !== oid) throw new Error(`preview: PR #${number} head changed while fetching; retry`);
+    }
+    return { number, oid };
+  });
+  const directory = (deps.makeDir ?? (() => {
+    const previews = join(root, '.elanous-test', 'previews');
+    mkdirSync(previews, { recursive: true });
+    return mkdtempSync(join(previews, 'preview-'));
+  }))();
+  const worktree = join(directory, 'checkout');
+  let added = false;
+  let heldPty: string | undefined;
+  let report = '';
+  const wait = deps.wait ?? ((ms: number) => new Promise<void>((done) => setTimeout(done, ms)));
+  try {
+    check('git', ['worktree', 'add', '--detach', worktree, head], root);
+    added = true;
+    for (const { number, oid } of bundleHeads) {
+      const current = JSON.parse(check('gh', ['pr', 'view', String(number), '--json', 'number,headRefOid'], root)) as { number?: number; headRefOid?: string };
+      if (current.number !== number || current.headRefOid !== oid) throw new Error(`preview: PR #${number} head changed while preparing bundle; retry`);
+      check('git', ['-c', 'user.name=elanous-preview', '-c', 'user.email=preview@localhost', 'merge', '--no-ff', '--no-edit', oid], worktree, 120_000);
+    }
+    check('bun', ['install', '--frozen-lockfile'], worktree, 300_000);
+    check('bun', ['install', '--frozen-lockfile'], join(worktree, 'apps/pwa'), 300_000);
+    for (const flag of flags) {
+      const existing = check('bun', ['bin/elanous.mjs', '--test', 'config', 'get', flag], worktree);
+      if (existing !== 'true' && existing !== 'false') throw new Error(`preview: ${flag} is not a boolean feature flag`);
+      check('bun', ['bin/elanous.mjs', '--test', 'config', 'set', flag, 'true'], worktree);
+    }
+    check('bun', ['bin/elanous.mjs', '--test', 'nexus', 'build', '--cwd', join(worktree, 'apps/pwa')], worktree, 300_000);
+    const pwa = check('bun', ['bin/elanous.mjs', '--test', 'nexus', 'run', '--test', '--tool-cwd', worktree], worktree, 120_000);
+    const port = /\bnexus\s+:(314[5-9]\d)\b/u.exec(pwa)?.[1];
+    const endpoint = port ? `http://127.0.0.1:${port}` : undefined;
+    if (!endpoint) throw new Error('preview: P-1 has no local test endpoint');
+    const probeOnce = deps.probePwa ?? (async (url: string) => {
+      try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
+        return response.ok && (await response.text()).includes('<');
+      } catch { return false; }
+    });
+    // `nexus run` detaches and returns before the daemon listens — its exit is not readiness. Poll.
+    let probe = false;
+    for (let attempt = 0; attempt < 60 && !probe; attempt++) {
+      probe = await probeOnce(`${endpoint}/app/`);
+      if (!probe) await wait(1000);
+    }
+    if (!probe) throw new Error('preview: P-1 did not serve the built PWA');
+    const version = check('bun', ['bin/elanous.mjs', '--version'], worktree);
+    if (!version) throw new Error('preview: B-1 version probe returned no output');
+    const held = check('bun', ['bin/elanous.mjs', '--test', 'dev', '--elanous', '--hold', '--cwd', worktree, '--isolated-root', join(directory, 'tui'), '--json'], worktree, 120_000);
+    const last = held.split('\n').reverse().find((line: string) => line.trim().startsWith('{'));
+    const pty = last ? JSON.parse(last) as { held?: boolean; ptyId?: string } : {};
+    if (pty.held !== true || !/^pty_[\w-]+$/u.test(pty.ptyId ?? '')) throw new Error('preview: B-1 held TUI did not return a PTY reference');
+    heldPty = pty.ptyId;
+    const snapshotArgs = ['bin/elanous.mjs', '--test', 'pty', 'snapshot', pty.ptyId!] as const;
+    const rows: string[] = [];
+    const snapshots: string[] = [];
+    for (const id of scenarios) {
+      const { input, expected, matches } = SCENARIOS[id]!;
+      const before = check('bun', snapshotArgs, worktree);
+      check('bun', ['bin/elanous.mjs', '--test', 'pty', 'text', pty.ptyId!, input, '--enter'], worktree);
+      // A constant sleep misses slow frames under load — poll until this scenario's expected response (≤ 20s).
+      let snapshot = '';
+      let matched = false;
+      for (let attempt = 0; attempt < 20; attempt++) {
+        await wait(1000);
+        snapshot = check('bun', snapshotArgs, worktree);
+        const fresh = previewFreshLines(before, snapshot);
+        matched = snapshot !== 'ok' && snapshot !== before && matches(fresh);
+        if (matched) break;
+      }
+      const observed = snapshot && snapshot !== 'ok' && snapshot !== before;
+      rows.push(`| TUI-COMFORT §4 ${id} | \`${input}\` → ${matched ? `expected ${expected} matched` : `friction: expected ${expected} not found${observed ? '' : ' (no response within 20s)'}`} |`);
+      snapshots.push(`<details><summary>Inner PTY snapshot ${id}</summary>\n\n\`\`\`text\n${snapshot.slice(-3000).replaceAll('```', "'''")}\n\`\`\`\n</details>`);
+    }
+    report = `| Check | Observation |\n|---|---|\n| head | \`${head}\` |${bundleHeads.length ? `\n| bundled PR heads | ${bundleHeads.map(({ number, oid }) => `#${number} \`${oid}\``).join(' ⊕ ')} |` : ''}\n| B-1 version | ${version.slice(0, 120)} |\n| P-1 PWA | \`${endpoint}/app/\` served the built PWA |\n${rows.join('\n')}\n\n${snapshots.join('\n\n')}`;
+  } catch (error) {
+    report = `| Check | Friction |\n|---|---|\n| head | \`${head}\` |\n| TUI-COMFORT §4 ${scenario} | ${String(error).replaceAll('|', '\\|').slice(0, 700)} |`;
+  } finally {
+    if (added) {
+      if (heldPty) run('bun', ['bin/elanous.mjs', '--test', 'pty', 'key', heldPty, 'ctrl+c'], worktree, 30_000);
+      run('bun', ['bin/elanous.mjs', '--test', 'nexus', 'run', '--test', '--stop'], worktree, 30_000);
+      const removed = run('git', ['worktree', 'remove', '--force', worktree], root, 30_000);
+      if (removed.status !== 0) throw new Error(`preview: failed to remove isolated worktree: ${removed.stderr}`);
+    }
+    (deps.dispose ?? ((dir) => rmSync(dir, { recursive: true, force: true })))(directory);
+  }
+  const status = report.includes('| Friction |') || report.includes('→ friction:') ? 'friction' : 'passed';
+  const body = `## PR preview — ${target} (${status})\n\n${report}`;
+  if (prNumber === undefined) throw new Error('preview: cannot comment without a PR number');
+  check('gh', ['pr', 'comment', String(prNumber), '--body', body], root);
+  const result: PreviewResult = { target, head, scenario, status, report: body, prNumber, commented: true };
+  const resultDir = join(root, '.elanous-test');
+  mkdirSync(resultDir, { recursive: true });
+  writeFileSync(join(resultDir, 'preview-result.json'), JSON.stringify(result), { mode: 0o600 });
+  return result;
+}

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

@@ -11,6 +11,7 @@ export interface ShardRunResult {
   shards: GateTestShard[];
   attempts: GateShardAttempt[];
   reason?: string;
+  measurementFailures?: number;
 }
 
 export type ShardProcess = (cwd: string, files: readonly string[]) => {
@@ -34,24 +35,39 @@ export function runShardedGateTests(
   if (!Number.isSafeInteger(count) || count < 1) throw new Error('invalid --shards count');
   const rss = new Map<string, number>();
   const seconds = new Map<string, number>();
+  const failedMeasurements: string[] = [];
   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)}` };
+    } catch {
+      failedMeasurements.push(file);
+      continue;
     }
-    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}` };
+    if (![0, 1].includes(sample.exitCode ?? -1) || sample.signal || !sample.junit
+      || !Number.isFinite(sample.rssMb) || sample.rssMb! <= 0
+      || !Number.isFinite(sample.seconds) || sample.seconds! < 0) {
+      failedMeasurements.push(file);
+      continue;
     }
     rss.set(file, sample.rssMb!);
     seconds.set(file, sample.seconds!);
   }
+  if (failedMeasurements.length) {
+    if (!rss.size) return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: 'no valid file measurements', measurementFailures: failedMeasurements.length };
+    const averageRss = [...rss.values()].reduce((sum, value) => sum + value, 0) / rss.size;
+    const averageSeconds = [...seconds.values()].reduce((sum, value) => sum + value, 0) / seconds.size;
+    for (const file of failedMeasurements) {
+      rss.set(file, averageRss);
+      seconds.set(file, averageSeconds);
+    }
+  }
+  const measurementFailures = failedMeasurements.length || undefined;
   let shards: GateTestShard[];
   try {
     shards = planGateTestShards(files, rss, seconds, budgetGiB, count);
   } catch (error) {
-    return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error) };
+    return { aggregate: { status: 'unmeasured', retryShardIds: [] }, shards: [], attempts: [], reason: String(error), ...(measurementFailures ? { measurementFailures } : {}) };
   }
   const attempts: GateShardAttempt[] = [];
   const baseline = baselineWorktree(cwd, baseRef, (dir) => {
@@ -76,8 +92,8 @@ export function runShardedGateTests(
     }
     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 };
+  if ('retryShardIds' in baseline) return { aggregate: baseline, shards, attempts, ...(measurementFailures ? { measurementFailures } : {}) };
+  return { aggregate: { status: 'unmeasured', retryShardIds: shards.map((shard) => shard.id) }, shards, attempts, reason: baseline.log, ...(measurementFailures ? { measurementFailures } : {}) };
 }
 
 export function runBunShard(cwd: string, files: readonly string[]): ReturnType<ShardProcess> {

package/src/self-implement/blocked-draft-policy.ts

@@ -1,6 +1,107 @@
+import type { AbandonedClassification } from './abandoned-classification.js';
+
 /** Environment interruptions have a resumable branch, not a human draft decision. */
 export function blockedDraftDisposition(classification: string | undefined): 'open-draft' | 'preserve-branch' {
   return classification === 'provider-error' || classification === 'quota-exhausted' || classification === 'credential-failure'
     ? 'preserve-branch'
     : 'open-draft';
 }
+
+/**
+ * DRAFT-NOT-ARCHIVE (RFC-draft-pr-accumulation-root-fix R1 · 첫 조각)
+ *
+ * S: 멈춘 런은 산출을 draft PR 로 남겼다 — PR 이 «실패 보관소»가 되어 열린 PR 이 200 을 넘고 겹침 검사가 눈이 멀었다.
+ * C: 닫힌 147건 중 사람이 실제로 봐야 했던 것은 «주인 자리» 47건뿐이었다.
+ * Q: 어느 멈춤이 PR 을 열 자격이 있나?
+ * A: 사람 판단이 필요한 멈춤(needs-owner)만. 나머지(harvestable)는 수확 가지 `salvage/<run>/<leaf>` ⊕ 런 원장의 «사유 · 다음 수»로 남긴다.
+ *    `tools.selfImplement.draftOnStop` = 'always'(기본 · 종전) | 'needs-owner-only'.
+ */
+export type DraftOnStopMode = 'needs-owner-only' | 'always';
+export const DRAFT_ON_STOP_MODES = ['needs-owner-only', 'always'] as const satisfies readonly DraftOnStopMode[];
+export const DEFAULT_DRAFT_ON_STOP: DraftOnStopMode = 'always';
+
+/** landable = 승인된 산출(merge-approved-abandoned) — 다음 수가 `pr land` 이므로 수확 가지로 숨기지 않고 PR 로 남긴다(⛔ needs-owner 라벨은 안 단다). */
+export type StopClass = 'needs-owner' | 'harvestable' | 'landable';
+
+const LANDABLE: ReadonlySet<string> = new Set<AbandonedClassification>(['merge-approved-abandoned']);
+
+/** 사람(주인 자리)이 골·계약·처분을 정해야 풀리는 멈춤. 모르는 분류는 «needs-owner» 쪽으로 기운다(⛔ 산출을 PR 밖으로 숨기지 않는다). */
+const NEEDS_OWNER: ReadonlySet<string> = new Set<AbandonedClassification>([
+  'contract-conflict',
+  'goal-unconvergeable-candidate',
+  'pr-declined',
+]);
+
+const HARVESTABLE: ReadonlySet<string> = new Set<AbandonedClassification>([
+  'implementation-deficit',
+  'report-deficit',
+  'artifact-deficit',
+  'run-deadline-exceeded',
+  'already-satisfied',
+  'quota-exhausted',
+  'provider-error',
+  'credential-failure',
+]);
+
+export function stopClassFor(classification: string | undefined): StopClass {
+  if (classification && NEEDS_OWNER.has(classification)) return 'needs-owner';
+  if (classification && LANDABLE.has(classification)) return 'landable';
+  if (classification && HARVESTABLE.has(classification)) return 'harvestable';
+  return 'needs-owner';
+}
+
+const NEXT_MOVE: Record<string, string> = {
+  'implementation-deficit': '수확 가지에서 같은 골을 이어 돌린다(resume 1회) — 그래도 멈추면 needs-owner',
+  'report-deficit': '수확 가지에서 완료 증거·보고를 보강해 다시 게이트에 올린다',
+  'artifact-deficit': '수확 가지에서 요구 산출물을 채워 다시 돌린다',
+  'run-deadline-exceeded': '수확 가지에서 이어 돌리거나, 산출이 작으면 골을 쪼개 재발사한다',
+  'merge-approved-abandoned': '승인된 산출이다 — 이 PR 을 착지 경로(pr land)로 올린다',
+  'already-satisfied': '고칠 것이 없다 — 재발사하지 말고 카드를 닫는다',
+  'quota-exhausted': '용량 회복 뒤 수확 가지에서 이어 돌린다',
+  'provider-error': 'provider 복구 뒤 수확 가지에서 이어 돌린다',
+  'credential-failure': '인증 복구 뒤 수확 가지에서 이어 돌린다',
+  'contract-conflict': '주인 자리가 골의 상충 기준을 정정한다',
+  'goal-unconvergeable-candidate': '주인 자리가 되풀이된 must-fix 와 골 계약을 대조해 골을 다시 쓰거나 쪼갠다',
+  'pr-declined': '주인 자리가 거절 사유를 반영할지 골을 다시 정할지 정한다',
+};
+
+export function nextMoveFor(classification: string | undefined): string {
+  return (classification && NEXT_MOVE[classification]) ?? '주인 자리가 중단 사유를 읽고 처분을 정한다(분류 못 함)';
+}
+
+export type DraftOnStopDecision =
+  | { action: 'open-draft'; stopClass: StopClass; mode: DraftOnStopMode; ownerLabel?: string }
+  | { action: 'salvage-branch'; stopClass: 'harvestable'; mode: 'needs-owner-only' };
+
+/** 'always' 는 종전 그대로(라벨도 그대로). 'needs-owner-only' 는 harvestable → 수확 가지 · needs-owner·landable → draft ⊕ 주인 자리 라벨.
+ *  ⛔ 자리를 모르면 자리 라벨을 «안 단다»(OP 로 추측해 달면 «안다»고 말하는 셈이다) — `elanous:needs-owner` 만 남는다. */
+export function decideDraftOnStop(input: { mode: DraftOnStopMode; classification: string | undefined; seat?: string }): DraftOnStopDecision {
+  const stopClass = stopClassFor(input.classification);
+  if (input.mode !== 'needs-owner-only') return { action: 'open-draft', stopClass, mode: 'always' };
+  if (stopClass === 'harvestable') return { action: 'salvage-branch', stopClass, mode: 'needs-owner-only' };
+  const ownerLabel = ownerSeatLabel(input.seat);
+  return { action: 'open-draft', stopClass, mode: 'needs-owner-only', ...(ownerLabel ? { ownerLabel } : {}) };
+}
+
+const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
+
+/** 주인 자리 라벨 — `helper-repair` 가 읽는 `elanous:seat-<자리>` 꼴. 아는 자리일 때만 낸다(모르면 undefined). */
+export function ownerSeatLabel(seat: string | undefined): string | undefined {
+  const trimmed = seat?.trim().toUpperCase();
+  return trimmed && (SEATS as readonly string[]).includes(trimmed) ? `elanous:seat-${trimmed}` : undefined;
+}
+
+/** 런 하나의 수확 가지 — `salvage/run-<6hex>/<가지 잎>`. 잎이 `-r<6hex>` 로 끝나면 `selectRunSalvageRefs` 가 그대로 찾는다. */
+export function salvageBranchForRun(runId: string, branch: string): string {
+  // `salvage-branches.ts` `runSuffixKey` 와 같은 규칙 — 그 모듈은 실행 러너를 끌고 와 user-config 가 부를 수 없다.
+  const key = /^(?:run-)?([0-9a-f]{6})/i.exec(runId.trim())?.[1]?.toLowerCase();
+  const runShort = key ? `run-${key}` : (runId.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24) || 'run-unknown');
+  const leaf = branch.replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '').replace(/\.\.+/g, '.').replace(/\.lock$/i, '-lock') || 'branch';
+  return `salvage/${runShort}/${leaf}`;
+}
+
+export function parseDraftOnStopMode(raw: unknown): { mode: DraftOnStopMode; invalid: boolean } {
+  if (raw === undefined) return { mode: DEFAULT_DRAFT_ON_STOP, invalid: false };
+  if (typeof raw === 'string' && (DRAFT_ON_STOP_MODES as readonly string[]).includes(raw)) return { mode: raw as DraftOnStopMode, invalid: false };
+  return { mode: DEFAULT_DRAFT_ON_STOP, invalid: true };
+}

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

@@ -15,6 +15,10 @@ import { appendRunLedgerEntry, type RunLedgerWriter } from './run-ledger.js';
 
 export interface ExecutionClarificationContext {
   runId: string;
+  outsideFiles?: readonly string[];
+  /** Full outside count — when larger than `outsideFiles`, the card says how many names it does not show. */
+  outsideCount?: number;
+  declaredPaths?: readonly string[];
   budget?: ClarificationContext['budget'];
   pendingQuestionCount?: number;
   config?: { hitl?: { executionDeadlineMinutes?: number } };
@@ -71,6 +75,13 @@ export async function askAtExecution(
 
   const request = toAskUserQuestionRequest(decision);
   if (!request) throw new Error('Execution clarification policy approved a question without a valid wire request.');
+  if (candidate.id === 'execution_scope' && ctx.outsideFiles) {
+    const sibling = (file: string) => ctx.declaredPaths === undefined ? 'unknown'
+      : file.endsWith('.test.ts') && ctx.declaredPaths.includes(file.replace(/\.test\.ts$/, '.ts')) ? 'yes' : 'no';
+    const hidden = Math.max(0, (ctx.outsideCount ?? ctx.outsideFiles.length) - ctx.outsideFiles.length);
+    const details = `Run ID: ${ctx.runId}\nOutside files:\n${ctx.outsideFiles.map(file => `- ${file} (declared-path sibling test: ${sibling(file)})`).join('\n')}${hidden > 0 ? `\n- … ${hidden} more outside file(s) not shown — inspect the worktree diff before expanding scope` : ''}`;
+    for (const question of request.questions) question.question += `\n\n${details}`;
+  }
   const configured = ctx.config === undefined
     ? getUserConfig().hitl?.executionDeadlineMinutes
     : ctx.config.hitl?.executionDeadlineMinutes;

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

@@ -26,10 +26,13 @@ import {
 import { listWorktrees } from '../git-fs/worktree.js';
 import { runShardedGateTests } from '../self-dev/shard-run.js';
 
-interface SelfGateCliOptions {
+export interface SelfGateCliOptions {
   base?: string;
   pr?: string;
   shards?: number;
+  /** LIGHT-RC (0.2.19) — repository-relative test paths run on every call, whatever changed. Existing ones join the
+   *  run (deduplicated, same introduced/preexisting baseline as the rest); missing ones go to `alwaysIncludeMissing`. */
+  alwaysInclude?: readonly string[];
 }
 
 interface ProcessResult {
@@ -102,7 +105,7 @@ interface GateOutput {
   error: (message: string) => void;
 }
 
-interface SelfGateCliResult {
+export interface SelfGateCliResult {
   exitCode: number;
   lines: string[];
   changedFiles: string[];
@@ -110,6 +113,11 @@ interface SelfGateCliResult {
   unverified: readonly string[];
   documentPaths: readonly string[];
   documentsWithoutDerivedTests: readonly string[];
+  /** `alwaysInclude` paths that do not exist in the tree (empty when none were given). */
+  alwaysIncludeMissing: readonly string[];
+  /** New vs. already-present failures (unknown/preconditionUnmet = failures it could not classify). Absent = the test
+   *  step did not produce a measurement (e.g. shards unmeasured). */
+  baseline?: { introduced: number; preexisting: number; unknown: number; preconditionUnmet: number };
 }
 
 /** 시험 단계와 독립인 정책 관문 넷. skipTestStep 이든 시험 통과든 같은 함수를 부른다. */
@@ -590,7 +598,12 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   const expose = publicExposureFiles(selection.files).length > 0
     ? runExposeGate(cwd, selection.files, getUserConfig().harness?.exposeGate === 'strict' ? 'strict' : 'warn', deps.runCommand)
     : { passed: true, log: '' };
-  const testFiles = [...(scope.testArgs ?? [])];
+  const alwaysInclude = [...new Set((options.alwaysInclude ?? []).map(normalizeGatePath).filter(Boolean))];
+  const alwaysIncludeMissing = alwaysInclude.filter((path) => !exists(path));
+  const scopedTests = scope.testArgs ?? [];
+  const alwaysIncludeExtra = alwaysInclude.filter((path) => exists(path) && !scopedTests.includes(path));
+  const testFiles = [...scopedTests, ...alwaysIncludeExtra];
+  const skipTestStep = scope.skipTestStep && alwaysIncludeExtra.length === 0;
   const unrunImporterTotal = lookupFailed ? null : (scope.importerTestsNotRun?.total ?? 0);
   const importerLookupFailed = Boolean(lookupFailed);
   const lines = [
@@ -619,6 +632,10 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     ...(routeIndex?.lookupFailures.length ? [`⚠️ caller route base lookup failed — unmeasured: ${routeIndex.lookupFailures.map(({ source, reason }) => `${source} (${reason})`).join(', ')}`] : []),
     ...(scope.callerTestsOverflow.length ? [`⚠️ caller test cap exceeded — not run: ${scope.callerTestsOverflow.map(({ file, reasons }) => `${file} (${reasons.join('+')})`).join(', ')}`] : []),
     changedTestCountNote(cwd, selection.files, selection.baseRef, deps.runCommand, deps.readFile),
+    // Only printed when the caller asked for always-include paths — the plain `self gate` output is unchanged.
+    ...(options.alwaysInclude !== undefined
+      ? [`always include: ${alwaysInclude.length - alwaysIncludeMissing.length}/${alwaysInclude.length} (added ${alwaysIncludeExtra.length}${alwaysIncludeMissing.length ? ` · missing: ${alwaysIncludeMissing.join(', ')}` : ''})`]
+      : []),
   ];
   if (expose.log) lines.push(expose.log);
   if (options.pr) {
@@ -641,17 +658,18 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   const iosPassed = runAdditionalGate('ios-gate', deps.runIosGate ?? runIosUnitTestGate, selection.files, cwd, lines);
   const pwaPassed = runAdditionalGate('pwa-gate', deps.runPwaGate ?? runPwaBuildGate, selection.files, cwd, lines);
 
-  if (scope.skipTestStep) {
+  if (skipTestStep) {
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-    return { exitCode: androidPassed && iosPassed && pwaPassed && policyPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+    return { exitCode: androidPassed && iosPassed && pwaPassed && policyPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
   }
 
   if (options.shards !== undefined) {
     const sharded = (deps.runShards ?? runShardedGateTests)(cwd, testFiles, selection.baseRef, options.shards);
-    lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})`);
+    lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})${sharded.measurementFailures ? ` · 측정 실패 ${sharded.measurementFailures}` : ''}`);
     for (const attempt of sharded.attempts) lines.push(`shard attempt: ${attempt.shardId} #${attempt.attempt}`);
     const { aggregate } = sharded;
+    let shardBaseline: SelfGateCliResult['baseline'];
     if (aggregate.status === 'unmeasured') lines.push(`shards: unmeasured (${aggregate.retryShardIds.join(', ') || sharded.reason || 'no complete JUnit'})`);
     else if (aggregate.report) {
       const report = aggregate.report;
@@ -662,15 +680,18 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
         baselineFiles: report.files, baselineStatus: report.baselineStatus, unrunImporterTotal, lookupFailed: importerLookupFailed,
       });
       lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
+      shardBaseline = { introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown, preconditionUnmet: report.preconditionUnmet };
     } else {
       lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
       logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
+      shardBaseline = { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 };
     }
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     return {
       exitCode: aggregate.status !== 'passed' || !policyPassed || !androidPassed || !iosPassed || !pwaPassed || !expose.passed ? 1 : 0,
       lines, changedFiles: selection.files, testFiles, unverified: scope.unverified,
       documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests,
+      alwaysIncludeMissing, ...(shardBaseline ? { baseline: shardBaseline } : {}),
     };
   }
 
@@ -680,7 +701,7 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
   }
 
   if (worktreeLog.includes('deterministic environment setup failed')) lines.push(worktreeLog);
@@ -702,5 +723,5 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
   const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
   const exitCode = !androidPassed || !iosPassed || !pwaPassed || !policyPassed || !expose.passed || report.introduced > 0 || report.unknown > 0 || report.preconditionUnmet > 0 ? 1 : 0;
-  return { exitCode, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests };
+  return { exitCode, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, baseline: { introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown, preconditionUnmet: report.preconditionUnmet } };
 }