elanous 0.2.22 → 0.2.23

package/src/release-loop/rehearsal.ts

@@ -0,0 +1,317 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { debug } from '../debug/log.js';
+import { sendOutbound } from '../domains/outbound-alert.js';
+import { releaseLedgerRoot } from '../instance/resolve.js';
+import { runLightRc, type LightRcResult } from './light-rc.js';
+import { listSchedules, type ReleaseSchedule } from './release-schedule.js';
+
+export type StepId = 'rc-7h' | 'rc-150m';
+export type RehearsalOutcome = 'ok' | 'regression' | 'unmeasured' | 'error' | 'no-checkout' | 'checkout-dirty' | 'superseded' | 'interrupted';
+export type RehearsalPlan =
+  | { status: 'no-schedule' }
+  | { status: 'not-yet'; version: string; cutAt: string; nextStepAt: string }
+  | { status: 'due'; version: string; cutAt: string; run: StepId | null; supersede: StepId[] }
+  | { status: 'nothing-due'; version: string; cutAt: string };
+
+const steps = [{ id: 'rc-7h', minutes: 420 }, { id: 'rc-150m', minutes: 150 }] as const;
+const minute = 60_000;
+
+/** Only the earliest future cut is eligible. A missed early step is never run back-to-back with the late step. */
+export function planRehearsal(schedules: readonly ReleaseSchedule[], now: Date, stamps: Readonly<Partial<Record<StepId, boolean>>>): RehearsalPlan {
+  const current = now.getTime();
+  if (!Number.isFinite(current)) throw new Error('now must be a valid date');
+  const schedule = schedules.filter(row => Number.isFinite(Date.parse(row.cutAt)) && Date.parse(row.cutAt) > current)
+    .sort((a, b) => Date.parse(a.cutAt) - Date.parse(b.cutAt) || a.version.localeCompare(b.version))[0];
+  if (!schedule) return { status: 'no-schedule' };
+  const { version, cutAt } = schedule;
+  const cut = Date.parse(cutAt);
+  const open = steps.filter(step => !stamps[step.id]);
+  if (!open.length) return { status: 'nothing-due', version, cutAt };
+  if (current >= cut - 45 * minute) return { status: 'due', version, cutAt, run: null, supersede: open.map(step => step.id) };
+  if (current >= cut - 150 * minute) {
+    return { status: 'due', version, cutAt, run: stamps['rc-150m'] ? null : 'rc-150m', supersede: stamps['rc-7h'] ? [] : ['rc-7h'] };
+  }
+  const due = open.filter(step => current >= cut - step.minutes * minute);
+  if (due.length) return { status: 'due', version, cutAt, run: due[0]!.id, supersede: [] };
+  return { status: 'not-yet', version, cutAt, nextStepAt: new Date(cut - open[0]!.minutes * minute).toISOString() };
+}
+
+export interface RehearsalStamp {
+  version: string;
+  step: StepId;
+  cutAt: string;
+  outcome: RehearsalOutcome | 'running';
+  startedAt: string;
+  endedAt?: string;
+  sha?: string;
+  summary?: string;
+  regressionFiles?: string[];
+  result?: LightRcResult;
+  notifiedAt?: string;
+  ownerPid?: number;
+}
+
+export interface RehearsalOptions {
+  apply?: boolean;
+  checkout?: string;
+  ledgerRoot?: string;
+}
+
+export interface RehearsalDeps {
+  now?: () => Date;
+  schedules?: (root: string) => ReleaseSchedule[];
+  lightRc?: (version: string, checkout: string) => Promise<LightRcResult>;
+  notify?: (text: string) => void | boolean | Promise<void | boolean>;
+  git?: (args: string[], cwd: string) => { rc: number | null; stdout: string; stderr?: string };
+}
+
+export type RehearsalTickResult = RehearsalPlan & { applied?: boolean; stamps?: RehearsalStamp[]; notificationFailures?: number };
+
+function stampPath(root: string, version: string, step: StepId): string {
+  if (!/^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/.test(version)) throw new Error(`invalid release version: ${version}`);
+  return join(root, 'release', version, 'rehearsal', `${step}.json`);
+}
+
+const defaultGit: NonNullable<RehearsalDeps['git']> = (args, cwd) => {
+  const run = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return { rc: run.error ? null : run.status, stdout: run.stdout ?? '', stderr: run.error ? String(run.error) : run.stderr ?? '' };
+};
+
+function gitResult(git: NonNullable<RehearsalDeps['git']>, args: string[], checkout: string): string {
+  const result = git(args, checkout);
+  if (result.rc !== 0) throw new Error(`git ${args.join(' ')} rc=${result.rc}: ${result.stderr || result.stdout}`);
+  return result.stdout.trim();
+}
+
+function oneLine(text: string): string { return text.replace(/\s+/g, ' ').trim(); }
+
+function outcomeLine(stamp: RehearsalStamp): string {
+  const head = `${stamp.outcome === 'regression' || stamp.outcome === 'error' || stamp.outcome === 'interrupted' ? '⛔' : '🧪'} 리허설 ${stamp.version} ${stamp.step} · ${stamp.outcome}`;
+  if (stamp.outcome === 'no-checkout') return `${head} · ELANOUS_REHEARSAL_GIT_CWD=<깨끗한 체크아웃> 설정 필요`;
+  if (stamp.outcome === 'checkout-dirty') return `${head} · 체크아웃 변경을 보존했다`;
+  if (!stamp.result) return `${head}${stamp.summary ? ` · ${stamp.summary}` : ''}`;
+  const result = stamp.result;
+  const duration = Math.max(0, Math.round((Date.parse(stamp.endedAt!) - Date.parse(stamp.startedAt)) / minute));
+  return `${head} · 새 회귀 ${result.introduced ?? '못 쟀다'} · 기존 ${result.preexisting ?? '못 쟀다'} · 미분류 ${result.unclassified ?? '못 쟀다'} · ${result.remote ?? 'local'} · ${duration}분${stamp.outcome === 'error' ? ` · gate rc ${result.gateExitCode}${!result.ok ? ' · RC 실패' : ''}` : ''}${stamp.regressionFiles?.length ? ` · 파일 ${stamp.regressionFiles.slice(0, 3).join(', ')}` : ''}`;
+}
+
+function persistStamp(path: string, stamp: RehearsalStamp): void {
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(stamp)}\n`, { mode: 0o600 });
+    renameSync(temp, path);
+  } finally {
+    if (existsSync(temp)) unlinkSync(temp);
+  }
+}
+
+/** A stamp that cannot be parsed (e.g. written by an older build that crashed mid-write) is reported, never re-run. */
+function readStampFile(path: string): RehearsalStamp | null {
+  try { return JSON.parse(readFileSync(path, 'utf8')) as RehearsalStamp; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    debug.log('release.rehearsal', 'stamp-unreadable', { path, error: oneLine(String(error)) });
+    return null;
+  }
+}
+
+function ownerIsDead(pid: number | undefined): boolean {
+  if (!Number.isSafeInteger(pid) || !pid || pid <= 0) return false;
+  try { process.kill(pid, 0); return false; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === 'ESRCH'; }
+}
+
+function aged(startedAt: string, now: number): boolean {
+  const started = Date.parse(startedAt);
+  return Number.isFinite(started) && now - started > 15 * minute;
+}
+
+/**
+ * Exclusive lock without ever removing another process's lock. Generation `<base>`, `<base>.1`, … is created with
+ * wx and carries `{ pid, token }`. A generation whose holder is gone (or an empty/unreadable one older than a
+ * minute — a crash inside the create) is skipped, never unlinked, so two contenders recovering the same dead lock
+ * still race on one wx create. A live, fresh-unreadable holder stops the scan (fail closed; a later tick retries).
+ * There is no generation cap: a dead generation only exists after a crash, so the scan is always finite.
+ * Returns a release function that removes only the acquired generation.
+ */
+function acquireGenerationLock(base: string): { release: () => void } | null {
+  const contents = JSON.stringify({ pid: process.pid, token: randomUUID() });
+  for (let generation = 0; ; generation++) {
+    const path = generation ? `${base}.${generation}` : base;
+    try { writeFileSync(path, contents, { flag: 'wx', mode: 0o600 }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      let holder: { pid?: number } | null = null;
+      try { holder = JSON.parse(readFileSync(path, 'utf8')) as { pid?: number }; } catch { holder = null; }
+      if (holder) { if (ownerIsDead(holder.pid)) continue; return null; }
+      try { if (Date.now() - statSync(path).mtimeMs > minute) continue; }
+      catch (inner) { if ((inner as NodeJS.ErrnoException).code === 'ENOENT') { generation--; continue; } }
+      return null;
+    }
+    return {
+      // Only this process ever writes or removes this generation, so removing it is race-free.
+      release: () => { try { if (readFileSync(path, 'utf8') === contents) unlinkSync(path); } catch (inner) { if ((inner as NodeJS.ErrnoException).code !== 'ENOENT') throw inner; } },
+    };
+  }
+}
+
+/** A notification lock only fences delivery, never the RC claim. A living sender is never evicted for elapsed time alone. */
+async function deliverStamp(path: string, notify: NonNullable<RehearsalDeps['notify']>, now: NonNullable<RehearsalDeps['now']>): Promise<boolean> {
+  const lock = acquireGenerationLock(`${path}.notify.lock`);
+  if (!lock) return false;
+  try {
+    const stamp = JSON.parse(readFileSync(path, 'utf8')) as RehearsalStamp;
+    if (!stamp.endedAt || stamp.notifiedAt) return true;
+    try {
+      if (await notify(outcomeLine(stamp)) === false) {
+        debug.log('release.rehearsal', 'notify-failed', { version: stamp.version, step: stamp.step, outcome: stamp.outcome });
+        return false;
+      }
+      stamp.notifiedAt = now().toISOString();
+      persistStamp(path, stamp);
+      return true;
+    } catch (error) {
+      debug.log('release.rehearsal', 'notify-failed', { version: stamp.version, step: stamp.step, outcome: stamp.outcome, error: oneLine(String(error)) });
+      return false;
+    }
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * The running→interrupted transition is exclusive: only the tick holding the interrupt lock may re-read and rewrite
+ * the stamp, so a loser never writes from its stale read and cannot clobber the winner's `notifiedAt`.
+ */
+function interruptStamp(path: string, saved: RehearsalStamp, now: Date): RehearsalStamp | null {
+  const lock = acquireGenerationLock(`${path}.interrupt.lock`);
+  if (!lock) {
+    debug.log('release.rehearsal', 'step-claimed-elsewhere', { version: saved.version, step: saved.step, outcome: 'interrupted' });
+    return null;
+  }
+  try {
+    const latest = JSON.parse(readFileSync(path, 'utf8')) as RehearsalStamp;
+    if (latest.outcome !== 'running' || latest.endedAt || latest.startedAt !== saved.startedAt || latest.ownerPid !== saved.ownerPid || !ownerIsDead(latest.ownerPid)) return null;
+    latest.outcome = 'interrupted';
+    latest.endedAt = now.toISOString();
+    latest.summary = '실행 프로세스 종료 · RC 재실행 안 함';
+    persistStamp(path, latest);
+    return latest;
+  } finally {
+    lock.release();
+  }
+}
+
+/** wx claim is permanent per version/step; a crashed run is reported as interrupted without running RC twice. */
+export async function runRehearsalTick(opts: RehearsalOptions = {}, deps: RehearsalDeps = {}): Promise<RehearsalTickResult> {
+  const root = opts.ledgerRoot ?? releaseLedgerRoot();
+  const now = (deps.now ?? (() => new Date()))();
+  const schedules = (deps.schedules ?? listSchedules)(root);
+  if (!Number.isFinite(now.getTime())) throw new Error('now must be a valid date');
+  const candidate = planRehearsal(schedules, now, {});
+  const stamps = candidate.status !== 'no-schedule'
+    ? Object.fromEntries(steps.map(step => [step.id, existsSync(stampPath(root, candidate.version, step.id))])) as Partial<Record<StepId, boolean>> : {};
+  const plan = planRehearsal(schedules, now, stamps);
+  debug.log('release.rehearsal', 'tick', { ...plan, apply: !!opts.apply });
+  if (!opts.apply) return plan;
+  const written: RehearsalStamp[] = [];
+  const notify = deps.notify ?? ((text: string) => sendOutbound(text, 'op-report'));
+  const clock = deps.now ?? (() => new Date());
+  let notificationFailures = 0;
+  const releaseDir = join(root, 'release');
+  const versions = existsSync(releaseDir) ? readdirSync(releaseDir, { withFileTypes: true }).filter(entry => entry.isDirectory()).map(entry => entry.name) : [];
+  for (const version of versions) {
+    if (!/^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/.test(version)) continue;
+    for (const step of steps) {
+      const path = stampPath(root, version, step.id);
+      if (!existsSync(path)) continue;
+      const saved = readStampFile(path);
+      if (!saved) continue;
+      if (saved.outcome === 'running' && !saved.endedAt && aged(saved.startedAt, now.getTime()) && ownerIsDead(saved.ownerPid)) {
+        const interrupted = interruptStamp(path, saved, now);
+        if (interrupted) {
+          written.push(interrupted);
+          debug.log('release.rehearsal', 'step-done', { version, step: step.id, outcome: 'interrupted', summary: interrupted.summary });
+        }
+      }
+      const pending = readStampFile(path);
+      if (pending?.endedAt && !pending.notifiedAt && !await deliverStamp(path, notify, clock)) notificationFailures++;
+    }
+  }
+  if (plan.status !== 'due') return { ...plan, ...(written.length ? { stamps: written, applied: true } : {}), notificationFailures };
+  const claim = (step: StepId): { path: string; stamp: RehearsalStamp } | null => {
+    const path = stampPath(root, plan.version, step);
+    mkdirSync(dirname(path), { recursive: true });
+    const stamp: RehearsalStamp = { version: plan.version, cutAt: plan.cutAt, step, outcome: 'running', startedAt: now.toISOString(), ownerPid: process.pid };
+    // Crash-safe exclusive create: the complete JSON is written to a private temp file, then hard-linked into
+    // place. link(2) fails with EEXIST like wx, but the stamp can never be observed empty or half-written.
+    const temp = `${path}.${process.pid}.${randomUUID()}.claim.tmp`;
+    try {
+      writeFileSync(temp, `${JSON.stringify(stamp)}\n`, { mode: 0o600 });
+      linkSync(temp, path);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      debug.log('release.rehearsal', 'step-claimed-elsewhere', { version: plan.version, step, outcome: 'running' });
+      return null;
+    } finally {
+      try { unlinkSync(temp); } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error; }
+    }
+    return { path, stamp };
+  };
+  const finish = async (path: string, stamp: RehearsalStamp): Promise<void> => {
+    stamp.endedAt = (deps.now ?? (() => new Date()))().toISOString();
+    persistStamp(path, stamp);
+    written.push(stamp);
+    debug.log('release.rehearsal', stamp.outcome === 'superseded' ? 'step-superseded' : 'step-done', { version: stamp.version, step: stamp.step, outcome: stamp.outcome, sha: stamp.sha, summary: stamp.summary });
+    if (!await deliverStamp(path, notify, clock)) notificationFailures++;
+  };
+  for (const step of plan.supersede) {
+    const claimed = claim(step);
+    if (claimed) { claimed.stamp.outcome = 'superseded'; await finish(claimed.path, claimed.stamp); }
+  }
+  if (plan.run) {
+    const claimed = claim(plan.run);
+    if (claimed) {
+      const { path, stamp } = claimed;
+      debug.log('release.rehearsal', 'step-start', { version: plan.version, step: plan.run, outcome: 'running' });
+      try {
+        const checkout = opts.checkout?.trim() || process.env.ELANOUS_REHEARSAL_GIT_CWD?.trim();
+        if (!checkout) stamp.outcome = 'no-checkout';
+        else {
+          const git = deps.git ?? defaultGit;
+          const status = gitResult(git, ['status', '--porcelain'], checkout);
+          if (status) stamp.outcome = 'checkout-dirty';
+          else {
+            gitResult(git, ['fetch', '-q', 'origin', 'main'], checkout);
+            gitResult(git, ['checkout', '-q', '--detach', 'origin/main'], checkout);
+            stamp.sha = gitResult(git, ['rev-parse', 'HEAD'], checkout);
+            if (!stamp.sha) throw new Error('git rev-parse HEAD returned no sha');
+            const regressionFiles: string[] = [];
+            const result = await (deps.lightRc ?? ((version, cwd) => runLightRc(version, { ledgerRoot: root, log: (line) => {
+              for (const entry of line.split(/\r?\n/)) {
+                const file = /^- introduced: (.+?)(?: > |$)/.exec(entry)?.[1];
+                if (file && regressionFiles.length < 3) regressionFiles.push(file);
+              }
+              console.error(line);
+            } }, { cwd })))(plan.version, checkout);
+            stamp.result = result;
+            if (regressionFiles.length) stamp.regressionFiles = regressionFiles;
+            stamp.outcome = result.introduced === null || result.unclassified === null ? 'unmeasured'
+              : result.introduced > 0 ? 'regression'
+              : result.unclassified > 0 ? 'unmeasured'
+              : !result.ok || result.gateExitCode !== 0 ? 'error' : 'ok';
+            stamp.summary = oneLine(`introduced ${result.introduced} · preexisting ${result.preexisting ?? 'unmeasured'} · unclassified ${result.unclassified} · ${result.remote ?? 'local'} · gate rc ${result.gateExitCode}${!result.ok ? ' · RC 실패' : ''}`);
+          }
+        }
+      } catch (error) {
+        stamp.outcome = 'error';
+        stamp.summary = oneLine(String(error instanceof Error ? error.message : error).split(/\r?\n/, 1)[0] ?? 'unknown error');
+      }
+      await finish(path, stamp);
+    }
+  }
+  return { ...plan, applied: true, stamps: written, notificationFailures };
+}

package/src/release-loop/release-schedule.ts

@@ -1,9 +1,15 @@
 import { CliUserError } from '../cli/cli-user-error.js';
 import { debug } from '../debug/log.js';
 import { readSchedule, readSchedules, writeSchedule, type ScheduleRow } from './feature-store.js';
+import { checkScheduleCeoLoad } from './placement.js';
 
 export type ReleaseSchedule = ScheduleRow;
 
+/** A release landing and its representative work share the same KST day boundary. */
+export function kstDay(utc: string): string {
+  return new Date(Date.parse(utc) + 9 * 3_600_000).toISOString().slice(0, 10);
+}
+
 function utcIso(input: string): string {
   const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})(?::(\d{2})(?:\.\d{1,3})?)?(Z|([+-])(\d{2}):(\d{2}))$/.exec(input);
   if (!match) throw new CliUserError(`시각에는 ISO 오프셋 필요: ${input}`);
@@ -36,9 +42,15 @@ export function listSchedules(root?: string): ReleaseSchedule[] {
 }
 
 export function setSchedule(version: string, patch: { cutAt?: string; landBy?: string; freezeFrom?: string; freezeUntil?: string; publishAt?: string }, by: string, root?: string): ReleaseSchedule {
+  const landing = patch.landBy !== undefined ? utcIso(patch.landBy) : undefined;
+  if (landing !== undefined) {
+    const previous = readSchedule(version, root);
+    // Check the landing against the same ledger and configuration root that writeSchedule will use.
+    if (!previous?.landBy || kstDay(previous.landBy) !== kstDay(landing)) checkScheduleCeoLoad(version, landing, root);
+  }
   const schedule = writeSchedule(version, {
     ...(patch.cutAt !== undefined ? { cutAt: utcIso(patch.cutAt) } : {}),
-    ...(patch.landBy !== undefined ? { landBy: utcIso(patch.landBy) } : {}),
+    ...(landing !== undefined ? { landBy: landing } : {}),
     ...(patch.freezeFrom !== undefined ? { freezeFrom: utcIso(patch.freezeFrom) } : {}),
     ...(patch.freezeUntil !== undefined ? { freezeUntil: utcIso(patch.freezeUntil) } : {}),
     ...(patch.publishAt !== undefined ? { publishAt: utcIso(patch.publishAt) } : {}),

package/src/release-loop/rubric-types.ts

@@ -0,0 +1 @@
+export type RubricAxis = { key: string; weight: number };

package/src/release-loop/rubric.ts

@@ -4,8 +4,8 @@ import { join } from 'node:path';
 import type { ChecklistItem } from './checklist.js';
 import { debug } from '../debug/log.js';
 import { getUserConfig } from '../user-config.js';
-
-export type RubricAxis = { key: string; weight: number };
+import type { RubricAxis } from './rubric-types.js';
+export type { RubricAxis } from './rubric-types.js';
 
 export const DEFAULT_PROJECT_AXES: readonly RubricAxis[] = [
   { key: 'V', weight: 2 }, { key: 'U', weight: 2 },

package/src/retro/daily.ts

@@ -17,6 +17,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../instance/resolve.js';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { getUserConfig } from '../user-config.js';
 import { debug } from '../debug/log.js';
 
@@ -226,12 +227,12 @@ export function draftActions(insights: readonly Insight[], recurrences: readonly
   });
 }
 
-export function summaryLines(recurrences: readonly Recurrence[], actions: readonly DraftCell[], factCount: number, mode: RetroMode): string[] {
+export function summaryLines(recurrences: readonly Recurrence[], actions: readonly DraftCell[], factCount: number, mode: RetroMode, factsUnmeasurable = factCount === 0): string[] {
   const top = recurrences.filter(r => r.recurring);
   const first = top[0];
   return [
-    first ? `회고 1순위: ${first.title} ${first.count}건${first.reBrokeAfterGreen ? ' · 초록 뒤 재발' : first.recurAfterAction ? ' · 조치 뒤 재발' : first.daysSeen.length ? ` · ${first.daysSeen.length}일째` : ''}` : '회고: 반복 없음',
-    `사실 ${factCount} · 반복 주제 ${top.length}(${top.slice(0, 5).map(r => r.title).join(' · ') || '없음'})`,
+    first ? `회고 1순위: ${first.title} ${first.count}건${first.reBrokeAfterGreen ? ' · 초록 뒤 재발' : first.recurAfterAction ? ' · 조치 뒤 재발' : first.daysSeen.length ? ` · ${first.daysSeen.length}일째` : ''}` : factsUnmeasurable ? '회고: 반복 판정 불가' : '회고: 반복 없음',
+    `사실 ${factsUnmeasurable ? '측정 불가' : factCount} · 반복 주제 ${factsUnmeasurable ? '측정 불가' : top.length}(${factsUnmeasurable ? '판정 불가' : top.slice(0, 5).map(r => r.title).join(' · ') || '없음'})`,
     `조치 초안 ${actions.length}: ${actions.map(a => `${a.id}(${a.owner})`).join(', ') || '없음'} · ${mode}`,
   ];
 }
@@ -249,10 +250,10 @@ export type RetroDeps = { now?: Date; readFacts?: (since: string, root: string)
 
 const repoRoot = resolve(import.meta.dir, '..', '..');
 
-function readFactsViaCli(since: string, root: string, repo = repoRoot): unknown {
-  const args = ['bin/elanous.mjs', ...(root === prodInstanceRoot() ? [] : [`--test=${root}`]), 'retro', 'facts', '--since', since, '--json'];
+function readFactsViaCli(since: string, root: string, configDir: string, repo = repoRoot): unknown {
+  const args = ['bin/elanous.mjs', ...(root === prodInstanceRoot() ? [] : [`--test=${root}`]), 'retro', 'facts', '--since', since, '--json', '--config-dir', resolve(configDir)];
   const result = spawnSync('bun', args, { cwd: repo, encoding: 'utf8', timeout: 570_000, maxBuffer: 64 * 1024 * 1024 });
-  if (result.error || result.status !== 0) throw new Error(`retro facts failed: ${result.error?.message ?? result.stderr?.trim() ?? `exit ${result.status}`}`);
+  if (result.error || result.status !== 0) throw new Error(`retro facts failed: ${result.error?.message || result.stderr?.trim() || `exit ${result.status ?? 'unknown'}`}`);
   return JSON.parse(result.stdout);
 }
 
@@ -294,15 +295,26 @@ export async function runRetroStage(stage: RetroStage, ctx: Ctx, root: string, d
       let raw: unknown;
       if (typeof input.factsFile === 'string') { raw = JSON.parse(readFileSync(input.factsFile, 'utf8')); sources.facts = `file:${input.factsFile}`; }
       else if (Array.isArray(input.facts)) { raw = input.facts; sources.facts = 'input'; }
-      else { raw = (deps.readFacts ?? ((s, r) => readFactsViaCli(s, r, deps.repo)))(since, root); sources.facts = `retro facts --since ${since}`; }
+      else {
+        sources.facts = `retro facts --since ${since}`;
+        try { raw = (deps.readFacts ?? ((s, r) => readFactsViaCli(s, r, getElanousConfigDir(), deps.repo)))(since, root); }
+        catch (error) {
+          raw = { facts: [] };
+          sources.facts = `unreadable: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`;
+        }
+      }
       const { facts, truncated } = normalizeFacts(raw);
+      const unavailable: unknown[] = Array.isArray(record(raw).unavailable) ? record(raw).unavailable as unknown[] : [];
+      const rawFacts = Array.isArray(raw) ? raw : record(raw).facts;
+      const factsUnmeasurable = facts.length === 0 && (sources.facts.startsWith('unreadable:') ||
+        !Array.isArray(rawFacts) || rawFacts.length > 0 || unavailable.length > 0);
+      if (factsUnmeasurable && !sources.facts.startsWith('unreadable:')) sources.facts = `unreadable: ${sources.facts}`;
       let greenCells: GreenCell[] = [];
       if (Array.isArray(input.greenCells)) { greenCells = input.greenCells.map(record).map(c => ({ id: str(c.id), title: str(c.title), status: str(c.status), version: str(c.version) || undefined, greenAt: str(c.greenAt) || undefined })); sources.green = 'input'; }
       else {
         try { greenCells = (deps.readGreenCells ? deps.readGreenCells() : await readGreenCellsFromChecklist()).map(c => ({ ...c, title: (c.title ?? "").slice(0, 120) })); sources.green = 'checklist'; }
         catch (error) { sources.green = `unreadable: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`; }
       }
-      const unavailable = Array.isArray(record(raw).unavailable) ? record(raw).unavailable : [];
       return { outcome: 'ok', day, since, mode: resolveRetroMode(input, deps.readConfig), facts, factCount: facts.length, truncated, unavailable, greenCells, sources };
     }
     case 'cluster': {
@@ -329,7 +341,9 @@ export async function runRetroStage(stage: RetroStage, ctx: Ctx, root: string, d
       const facts = (out.collect?.facts ?? []) as RetroFact[];
       const recurrences = (out.recur?.recurrences ?? []) as Recurrence[];
       const actions = (out.act?.actions ?? []) as DraftCell[];
-      const summary = summaryLines(recurrences, actions, facts.length, mode);
+      const sources = record(out.collect?.sources);
+      const summary = summaryLines(recurrences, actions, facts.length, mode,
+        facts.length === 0 && (!str(sources.facts) || str(sources.facts).startsWith('unreadable:')));
       const themes = recurrences.map(r => ({ theme: r.theme, title: r.title, count: r.count, recurring: r.recurring, reBrokeAfterGreen: r.reBrokeAfterGreen, recurAfterAction: r.recurAfterAction, greenCells: r.greenCells, rank: r.rank }));
       const dayFile = { day, mode, briefing: mode === 'live', generatedAt: now.toISOString(), factCount: facts.length,
         truncated: out.collect?.truncated === true, unavailable: out.collect?.unavailable ?? [], sources: out.collect?.sources ?? {},

package/src/seat-loop/seat-loop.ts

@@ -29,6 +29,7 @@ import { queryRunningRuns } from '../self-implement/running-runs.js';
 import { checklistHistory, listChecklist, type Checklist } from '../release-loop/checklist.js';
 import { readSchedules, releasedVersion } from '../release-loop/feature-store.js';
 import { runOpDecide, type OpDecideCandidate } from './op-decide.js';
+import { readHandedCells, readTrafficSignal, type TrafficSignalRead } from './traffic-signal.js';
 
 // `kind`/`createdAt` are the V3 shadow-compare keys (내부 문서 `METHOD-v3-shadow-compare-2026-10-02` · MK 10-02 18:54).
 export type SeatItem = { source: 'request' | 'checklist' | 'hook' | 'seat-question' | 'idle'; kind?: 'request' | 'cell' | 'hook-task' | 'seat-question'; id: string; title: string; text: string; evidence?: string; status?: string; version?: string; seat?: string; evidenceHash?: string; asOf?: string; queuedAt?: string; createdAt?: string; from?: SeatId; idleRung?: 1 | 2 | 3 | 4 | 5 };
@@ -81,6 +82,9 @@ export type SeatDeps = {
   schedules?: () => Array<{ version: string; cutAt: string; landBy?: string | null }>;
   /** Checklist items of one version — default reads the release ledger DB (checklist.json is only a legacy import source since REL5b). */
   checklistItems?: (version: string) => Array<{ id: string; title: string; status: string; owner?: string | null; disposition?: string; evidence?: string }>;
+  /** Optional injected traffic/handoff snapshots; defaults read the OP files. */
+  trafficSignal?: TrafficSignalRead;
+  handedCells?: ReadonlySet<string>;
   /** Chronological release-ledger events for a checklist id; injected for isolated release fixtures. */
   checklistHistory?: (id: string) => ReturnType<typeof checklistHistory>;
   /** Full checklist snapshot including history, for stall detection. */
@@ -526,11 +530,31 @@ export async function gatherSeatInputs(seat: string, deps: SeatDeps = {}, ledger
   }
   const checklist: SeatItem[] = [];
   const closed: string[] = [];
-  for (const version of open === null ? [] : versions().sort(versionOrder)) {
+  // runSeatLoopOnce → gatherSeatInputs → pickNext: only checklist construction is gated;
+  // requests, hook cards and seat questions above keep their original selection path.
+  const signal = deps.trafficSignal === undefined ? readTrafficSignal() : deps.trafficSignal;
+  // The signal verdict comes first; the handed ledger is read only when the signal would let cells through,
+  // so a handed read failure never masks `signal-not-green` / `signal-seat-paused`.
+  let handed: ReadonlySet<string> = new Set();
+  let handedUnreadable = false;
+  const signalStops = signal !== null && ('unreadable' in signal || signal.global !== 'green' || Boolean(signal.paused?.[seat]));
+  if (signal !== null && !signalStops) {
+    try { handed = deps.handedCells ?? readHandedCells(); }
+    catch { handedUnreadable = true; }
+  }
+  if (signal !== null && 'unreadable' in signal) debug.log('seat.loop', 'signal-unreadable', { seat });
+  else if (signal !== null && signal.global !== 'green') debug.log('seat.loop', 'signal-not-green', { seat });
+  else if (signal !== null && signal.paused?.[seat]) debug.log('seat.loop', 'signal-seat-paused', { seat });
+  else if (handedUnreadable) debug.log('seat.loop', 'signal-unreadable', { seat, source: 'handed' });
+  else for (const version of open === null ? [] : versions().sort(versionOrder)) {
     if (!open!.has(version)) {
       closed.push(version);
       continue;
     }
+    if (signal?.versions && !signal.versions.includes(version)) {
+      debug.log('seat.loop', 'skip-signal-version', { version });
+      continue;
+    }
     let items: ReturnType<typeof itemsOf>;
     try { items = itemsOf(version); } catch (error) {
       debug.log('seat.loop', 'checklist-unreadable', { seat, version, error: String(error).slice(0, 200) });
@@ -543,6 +567,14 @@ export async function gatherSeatInputs(seat: string, deps: SeatDeps = {}, ledger
     }
     for (const item of items) {
       if (item.owner === seat && (item.status === 'yellow' || item.status === 'red')) {
+        if (signal?.hold?.includes(item.id)) {
+          debug.log('seat.loop', 'skip-signal-cell', { id: item.id, why: 'hold' });
+          continue;
+        }
+        if (handed.has(item.id)) {
+          debug.log('seat.loop', 'skip-signal-cell', { id: item.id, why: 'handed' });
+          continue;
+        }
         checklist.push({ source: 'checklist', kind: 'cell', version, seat, asOf, id: item.id, title: item.title, text: item.title, status: item.status,
           ...(item.evidence ? { evidence: item.evidence } : {}), evidenceHash: createHash('sha256').update(item.evidence ?? '').digest('hex') });
       }
@@ -1389,6 +1421,7 @@ export async function runSeatLoopOnce(seat: string, deps: SeatDeps = {}): Promis
   const failedDecisions = new Set<string>();
   let lastDecisionFailure: SeatEntry | undefined;
   while (true) {
+  // The seat turn reads the signal-gated checklist and ungated requests before pickNext.
   const inputs = await gatherSeatInputs(seat, deps, ledger);
   inputs.requests = inputs.requests.filter((candidate) => !failedDecisions.has(itemKey(candidate)));
   inputs.checklist = inputs.checklist.filter((candidate) => !failedDecisions.has(itemKey(candidate)));

package/src/seat-loop/traffic-signal.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export type TrafficSignal = {
+  global: string;
+  versions?: string[];
+  hold?: string[];
+  paused?: Record<string, boolean>;
+};
+export type TrafficSignalRead = TrafficSignal | { unreadable: true } | null;
+
+const defaultPath = (name: string): string => join(homedir(), 'elanous-hq', 'seat-state', 'OP', name);
+const missing = (error: unknown): boolean => (error as NodeJS.ErrnoException).code === 'ENOENT';
+
+/** A missing installation has no signal; an invalid or unreadable one cannot authorize a checklist launch. */
+export function readTrafficSignal(path?: string): TrafficSignalRead {
+  try {
+    const value: unknown = JSON.parse(readFileSync(path ?? process.env.ELANOUS_TRAFFIC_SIGNAL ?? defaultPath('traffic.json'), 'utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value)) return { unreadable: true };
+    const row = value as Record<string, unknown>;
+    if (typeof row.global !== 'string'
+      || (row.versions !== undefined && (!Array.isArray(row.versions) || !row.versions.every((version) => typeof version === 'string')))
+      || (row.hold !== undefined && (!Array.isArray(row.hold) || !row.hold.every((id) => typeof id === 'string')))
+      || (row.paused !== undefined && (!row.paused || typeof row.paused !== 'object' || Array.isArray(row.paused)
+        || !Object.values(row.paused).every((paused) => typeof paused === 'boolean')))) return { unreadable: true };
+    return { global: row.global, ...(row.versions !== undefined ? { versions: row.versions as string[] } : {}),
+      ...(row.hold !== undefined ? { hold: row.hold as string[] } : {}),
+      ...(row.paused !== undefined ? { paused: row.paused as Record<string, boolean> } : {}) };
+  } catch (error) {
+    return missing(error) ? null : { unreadable: true };
+  }
+}
+
+/** A missing handoff ledger has no handed cells; other read errors propagate so selection can fail closed. */
+export function readHandedCells(path?: string): Set<string> {
+  try {
+    return new Set(readFileSync(path ?? process.env.ELANOUS_HANDED_CELLS ?? defaultPath(join('feeder', 'handed.txt')), 'utf8')
+      .split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+  } catch (error) {
+    if (missing(error)) return new Set();
+    throw error;
+  }
+}

package/src/self-dev/ask-launch-flow.ts

@@ -215,7 +215,7 @@ export type AskLaunchFlowResult =
   /** ⓪ 저작 «전»에 막혔다 — 100초를 안 썼다. */
   | { readonly kind: 'stopped-before-authoring'; readonly goalFile?: undefined }
   /** ⑵⑶⑷ 에서 막혔다 — 골은 «있다»(사람이 열어볼 수 있게 돌려준다). */
-  | { readonly kind: 'stopped-by-preflight'; readonly goalFile: string };
+  | { readonly kind: 'stopped-by-preflight'; readonly goalFile: string; readonly blockers: LaunchPreflightResult['blockers'] };
 
 /** 런 식별자가 흐름 뒤에 확정된 호출자는 이 관측으로 입구와 런을 조인한다. */
 export function observeAskLaunchRunIdentity(
@@ -1103,5 +1103,5 @@ export async function runAskLaunchFlow(
   }
   return launchDecision
     ? { kind: 'launch', goalFile: effectiveGoalFile }
-    : { kind: 'stopped-by-preflight', goalFile: effectiveGoalFile };
+    : { kind: 'stopped-by-preflight', goalFile: effectiveGoalFile, blockers: preflight.blockers };
 }