elanous 0.2.35 → 0.2.37

package/src/pty-shell/stale-install-check.ts

@@ -0,0 +1,99 @@
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { readInstallMetadataCommit } from '../version/code-revision.js';
+
+export type StaleInstallResult = {
+  state: 'same' | 'changed' | 'unknown' | 'not-installed';
+  bootCommit: string | undefined;
+  installedCommit: string | undefined;
+};
+
+export const STALE_INSTALL_CHECK_INTERVAL_MS = 60_000;
+
+/**
+ * Builds the command that relaunches the TUI on the same daemon session: `elanous --resume <id>` boots the dashboard,
+ * loads that session (ACP session/load) and replays its turns (src/index.ts resumeSessionId · dashboard acp-boot).
+ * The user-facing hint and its key binding land with the dashboard wiring slice (`r` is the render toggle today).
+ * Intentional wiring boundary: the dashboard owns the key binding and executes this command;
+ * this scoped helper only constructs it and does not spawn a child process.
+ */
+export function buildStaleInstallRelaunchCommand(sessionId: string): string {
+  return `elanous --resume ${JSON.stringify(sessionId)}`;
+}
+
+export function formatStaleInstallNotice(result: StaleInstallResult, notifiedCount: number): string {
+  const message = `새 판이 깔렸습니다 (부팅 판 ${result.bootCommit!.slice(0, 7)} → 지금 ${result.installedCommit!.slice(0, 7)}) · TUI 를 다시 띄우면 새 판으로 돕니다`;
+  return notifiedCount >= 2 ? `${message} · 이 TUI 가 뜬 뒤 ${notifiedCount}번째 새 판` : message;
+}
+
+/** Identify the immutable installed version containing this module, never the session cwd. */
+export function versionedDashboardInstallDir(
+  codeRoot: string,
+  installRoot = join(homedir(), '.local', 'share', 'elanous'),
+): string | undefined {
+  try {
+    const packageRoot = realpathSync(codeRoot);
+    if (basename(packageRoot) !== 'elanous' || basename(dirname(packageRoot)) !== 'node_modules') return undefined;
+    const versionDir = dirname(dirname(packageRoot));
+    let canonicalInstallRoot: string;
+    try { canonicalInstallRoot = realpathSync(installRoot); }
+    catch { canonicalInstallRoot = resolve(installRoot); }
+    if (dirname(versionDir) !== join(canonicalInstallRoot, 'versions')) return undefined;
+    const requestedVersionDir = dirname(dirname(resolve(codeRoot)));
+    return dirname(requestedVersionDir) === resolve(installRoot, 'versions')
+      && realpathSync(requestedVersionDir) === versionDir
+      ? requestedVersionDir : versionDir;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createStaleInstallCheck(input: {
+  bootCommit: string | undefined;
+  readInstalledCommit: () => string | undefined;
+  now: () => number;
+  codeRoot?: string;
+  installRoot?: string;
+}) {
+  const installed = input.codeRoot === undefined
+    || versionedDashboardInstallDir(input.codeRoot, input.installRoot) !== undefined;
+  const notifiedCommits = new Set<string>();
+  let lastReadAt = -Infinity;
+  let lastResult: StaleInstallResult | undefined;
+  const check = (): StaleInstallResult => {
+    if (!installed) return { state: 'not-installed', bootCommit: input.bootCommit, installedCommit: undefined };
+    const time = input.now();
+    if (lastResult && time - lastReadAt < STALE_INSTALL_CHECK_INTERVAL_MS) return lastResult;
+    lastReadAt = time;
+    let installedCommit: string | undefined;
+    try { installedCommit = input.readInstalledCommit(); } catch { /* unreadable metadata */ }
+    const result: StaleInstallResult = {
+      state: !input.bootCommit || !installedCommit
+        ? 'unknown'
+        : input.bootCommit === installedCommit ? 'same' : 'changed',
+      bootCommit: input.bootCommit,
+      installedCommit,
+    };
+    lastResult = result;
+    return result;
+  };
+  return {
+    check,
+    shouldNotify(result: StaleInstallResult): boolean {
+      if (result.state !== 'changed' || !result.installedCommit || notifiedCommits.has(result.installedCommit)) return false;
+      notifiedCommits.add(result.installedCommit);
+      return true;
+    },
+  };
+}
+
+/** Only the current pointer is polled; boot metadata is read once from the immutable version. */
+export function readDashboardBootCommit(versionDir: string): string | undefined {
+  return readInstallMetadataCommit(join(versionDir, 'install.json'));
+}
+
+export function readCurrentInstalledCommit(installRoot = join(homedir(), '.local', 'share', 'elanous')): string | undefined {
+  return readInstallMetadataCommit(join(installRoot, 'current', 'install.json'));
+}

package/src/pty-shell/tui-run-state.ts

@@ -11,20 +11,21 @@
 //   `reportTuiTurn` 을 부른다. 기록 실패는 `debug.log('pty.tui-state', …)` — 조용히 삼키지 않는다.
 // 판독(CLI 쪽): `describePtyRunState` 가 행 ⊕ 설치본 기록 ⊕ (체크아웃이면) 그 뿌리의 HEAD 로 판정한다.
 
+import { spawn } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { debug } from '../debug/log.js';
-import { createHerdrAgentReporter, type HerdrAgentReporterLike } from './herdr-agent-report.js';
+import { createHerdrAgentReporter, guardHerdrReleaseOnSignal, type HerdrAgentReporterLike, type HerdrSignalTarget } from './herdr-agent-report.js';
 import { runGitCommand } from '../git-fs/runner.js';
 import { codeRevision, packageVersion, readInstallMetadataCommit } from '../version/code-revision.js';
 import {
   buildStaleInstallRelaunchCommand,
   formatStaleInstallNotice,
   versionedDashboardInstallDir,
-} from '../dashboard/stale-install-check.js';
+} from './stale-install-check.js';
 import {
   updatePtyManifestBuild, updatePtyManifestTurn,
   type PtyBuildIdentity, type PtyManifestRow, type PtyTurnState,
@@ -307,6 +308,144 @@ export function formatTurnCell(cell: PtyTurnCell): string {
   return `${cell.state},${cell.sinceSec === null ? '?' : cell.sinceSec}s`;
 }
 
+// ── H9 자기 재기동 — «재기동 필요» ∧ 유휴 ∧ 사람 입력 없음 ⇒ 스스로 재기동 ──
+//
+// 정본: seat-state/OPC/TUI-HOMEOSTASIS-SLICES-2026-10-16.md (TUI-H9-IDLE-SELF-RESTART).
+// 판정(`decideSelfRestart`)은 순수 함수 — 실제 «새 세션 ⊕ 자리 맥락 재주입» 은 주입된 수행자(`restart`)가 한다.
+// 낡음 판정은 기존 `BuildStaleness` 를 그대로 재사용한다(판정·문면을 두벌로 만들지 않는다).
+// 사람 입력 대기 신호는 입력 축(대시보드)이 준다 — 이 모듈은 입력 큐를 소유하지 않는다.
+
+/** 유휴 유예: 이만큼 조용했을 때만 재기동한다 — 턴 사이 «쉼»에서 세션을 새로 띄우지 않는다. */
+export const DEFAULT_SELF_RESTART_IDLE_MS = 90_000;
+
+export type SelfRestartReason =
+  | 'stale-idle-no-input'
+  | 'not-stale'
+  | 'staleness-unknown'
+  | 'turn-busy'
+  | 'turn-unknown'
+  | 'still-warm'
+  | 'human-input-pending';
+
+export interface SelfRestartDecisionDeps {
+  /** 재기동 필요인가 — 미지(null)면 재기동하지 않는다. */
+  readonly stale: boolean | null;
+  readonly staleReason?: BuildStaleReason;
+  readonly turn: PtyTurnView;
+  /** 지금 턴 상태에 머문 시간(ms) — 모르면 null. */
+  readonly idleMs: number | null;
+  readonly humanInputPending: boolean;
+  readonly minIdleMs?: number;
+}
+
+export interface SelfRestartDecision {
+  readonly restart: boolean;
+  readonly reason: SelfRestartReason;
+}
+
+/** 판정선: 세 조건(재기동 필요 · 유휴 · 사람 입력 없음)이 모두 참일 때만 참. 거짓인 첫 조건을 이유로 낸다. */
+export function decideSelfRestart(deps: SelfRestartDecisionDeps): SelfRestartDecision {
+  if (deps.stale === null) return { restart: false, reason: 'staleness-unknown' };
+  if (!deps.stale) return { restart: false, reason: 'not-stale' };
+  if (deps.turn === 'busy') return { restart: false, reason: 'turn-busy' };
+  if (deps.turn === 'unknown') return { restart: false, reason: 'turn-unknown' };
+  const minIdleMs = deps.minIdleMs ?? DEFAULT_SELF_RESTART_IDLE_MS;
+  if (deps.idleMs === null || deps.idleMs < minIdleMs) return { restart: false, reason: 'still-warm' };
+  if (deps.humanInputPending) return { restart: false, reason: 'human-input-pending' };
+  return { restart: true, reason: 'stale-idle-no-input' };
+}
+
+/** 재기동 계획 — 새 세션 ⊕ 자리 맥락 재주입 명령까지. 세션 id 를 모르면 명령은 null(판정 근거는 남긴다). */
+export interface TuiSelfRestartPlan {
+  readonly surfaceId: string;
+  readonly staleReason: BuildStaleReason;
+  readonly idleMs: number;
+  readonly relaunchCommand: string | null;
+}
+
+export interface TuiSelfRestartDeps {
+  /** 낡음 판정 재료 — 생략하면 이 프로세스의 기동 판 ⊕ 설치본 ⊕ 체크아웃 HEAD 로 잰다. */
+  readonly staleness?: () => BuildStaleness;
+  /** 사람이 지금 입력 중인가 — 생략하면 «모름» 으로 보고 재기동하지 않는다(조용한 세션을 뺏지 않는다). */
+  readonly humanInputPending?: () => boolean;
+  readonly sessionId?: string;
+  /**
+   * 지금 이 TUI 가 «소유한» 세션 — 틱마다 다시 읽어 `sessionId` 보다 우선한다.
+   * 대화가 갈아 끼워지는 TUI 는 기동 시점 값을 고정할 수 없어 이 칸을 쓴다(읽기 실패 → null → 재기동 안 함).
+   */
+  readonly readSessionId?: () => string | null;
+  readonly minIdleMs?: number;
+  readonly intervalMs?: number;
+  /** 실제 재기동 수행자(새 세션 ⊕ 자리 맥락 재주입). 생략 시 설치본 `elanous --resume <세션>`. */
+  readonly restart?: (plan: TuiSelfRestartPlan) => void;
+  /**
+   * 낡은 TUI 가 좌석을 «놓는» 동작 — 새 세션을 띄우기 직전에 부른다.
+   * 생략해도 이 녹음기는 그 좌석 행 쓰기를 스스로 놓는다(두 TUI 가 한 좌석을 겹쳐 쓰지 않게).
+   */
+  readonly yieldSeat?: (plan: TuiSelfRestartPlan) => void;
+  /** 유휴 감시 등록 — 틱을 받아 해제 함수를 준다. 생략 시 unref 된 setInterval. */
+  readonly watch?: (tick: () => void) => () => void;
+}
+
+const stalenessFromRunningBuild = (): BuildStaleness => {
+  const build = runningBuild();
+  const installed = readCurrentInstallRecord();
+  let checkoutHead: string | undefined;
+  if (build.source === 'checkout' && build.codeRoot) checkoutHead = readCheckoutHead(build.codeRoot);
+  return judgeBuildStaleness({ build, installed, ...(checkoutHead ? { checkoutHead } : {}) });
+};
+
+const defaultWatch = (tick: () => void, intervalMs: number): (() => void) => {
+  const timer = setInterval(tick, intervalMs);
+  (timer as unknown as { unref?: () => void }).unref?.();
+  return () => { clearInterval(timer); };
+};
+
+/** 재기동 인자: 새 세션은 `--resume <세션>` 으로 그 좌석의 자리 맥락을 다시 받는다. */
+export const TUI_RELAUNCH_FLAG = '--resume';
+
+export interface TuiRelaunchChild {
+  on(event: 'error', listener: (error: Error) => void): unknown;
+  on(event: 'spawn', listener: () => void): unknown;
+  unref(): void;
+}
+
+/** 프로세스 띄우기 seam — 무대는 여기만 가짜로 바꿔 «생산 argv·옵션» 을 그대로 지난다. */
+export type TuiRelaunchSpawn = (
+  command: string,
+  args: readonly string[],
+  options: { detached: boolean; stdio: 'ignore' },
+) => TuiRelaunchChild;
+
+const defaultRelaunchSpawn: TuiRelaunchSpawn = (command, args, options) =>
+  spawn(command, args, options) as unknown as TuiRelaunchChild;
+
+let relaunchSpawn: TuiRelaunchSpawn = defaultRelaunchSpawn;
+
+/** 무대용 spawn 교체 — 인자 없이 부르면 생산 기본값(spawn)으로 되돌린다. */
+export function setTuiRelaunchSpawnForTesting(next?: TuiRelaunchSpawn): void {
+  relaunchSpawn = next ?? defaultRelaunchSpawn;
+}
+
+/** 기본 재기동 수행자: 설치본 `elanous --resume <세션>` — 새 세션이 그 좌석의 자리 맥락으로 다시 뜬다. */
+export const spawnTuiRelaunch = (sessionId: string): Promise<void> => {
+  return new Promise<void>((resolve, reject) => {
+    const child = relaunchSpawn(process.env.ELANOUS_BIN || 'elanous', [TUI_RELAUNCH_FLAG, sessionId], { detached: true, stdio: 'ignore' });
+    let settled = false;
+    child.on('error', (error: Error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    });
+    child.on('spawn', () => {
+      if (settled) return;
+      settled = true;
+      child.unref();
+      resolve();
+    });
+  });
+};
+
 // ── 기록(TUI) ──
 
 export interface TuiRunStateRecorderDeps {
@@ -321,6 +460,16 @@ export interface TuiRunStateRecorderDeps {
    * `null` 이면 신고하지 않는다.
    */
   readonly herdr?: HerdrAgentReporterLike | null;
+  /**
+   * SIGINT·SIGTERM 기본 죽음에도 herdr 를 반납하는 신호 지킴이의 대상(TUI-HERDR-EXIT-RACE).
+   * 생략 시: 기본 신고기(herdr 미주입)일 때만 실 `process` · 주입 herdr 는 지킴이 0. `null` 이면 안 건다.
+   */
+  readonly signals?: HerdrSignalTarget | null;
+  /**
+   * H9 자기 재기동(낡은 판 ∧ 유휴 ∧ 사람 입력 없음 ⇒ 새 세션 ⊕ 자리 맥락 재주입).
+   * 생략하면 감시를 안 건다 — 이 축을 켜는 것은 호출자(생산 진입점)의 결정이다.
+   */
+  readonly selfRestart?: TuiSelfRestartDeps;
 }
 
 interface ActiveRecorder {
@@ -331,6 +480,8 @@ interface ActiveRecorder {
   readonly herdr: HerdrAgentReporterLike | null;
   /** manifest 에 실제로 적힌 마지막 턴. 실패면 안 바뀐다(재시도). */
   last?: PtyTurnState;
+  /** idle 로 «바뀐» 시각 — 유휴 경과의 0초. busy 로 가면 다시 모른다. */
+  idleSince?: number;
   /** herdr 에 마지막으로 알린 턴. manifest 성패와 따로 둔다. */
   herdrLast?: PtyTurnState;
 }
@@ -361,7 +512,97 @@ export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRec
   active = recorder;
   writeTurnState(recorder, 'idle');
   if (herdr) { try { herdr.start(); } catch { /* 신고 실패가 녹음기를 깨지 않는다 */ } }
+  // H9 유휴 감시: 판·턴·사람 입력을 매 틱 다시 재고, 재기동 성공 뒤에만 좌석을 양도한다.
+  const selfRestart = deps.selfRestart;
+  let unwatch: () => void = () => {};
+  if (selfRestart) {
+    const minIdleMs = selfRestart.minIdleMs ?? DEFAULT_SELF_RESTART_IDLE_MS;
+    const restartedFor = new Set<BuildStaleReason>();
+    let restartInFlight = false;
+    const tick = (): void => {
+      if (active !== recorder) return;
+      let staleness: BuildStaleness;
+      try { staleness = (selfRestart.staleness ?? stalenessFromRunningBuild)(); } catch (error) {
+        log('self-restart-staleness-failed', { ptyId: surfaceId, error: error instanceof Error ? error.message : String(error) });
+        return;
+      }
+      // 사람 입력 신호가 없거나 읽을 수 없으면 모름으로 닫는다 — 명시적 false만 «사람 입력 없음»이다.
+      let humanInputPending = true;
+      if (selfRestart.humanInputPending) {
+        try { humanInputPending = selfRestart.humanInputPending() !== false; } catch { humanInputPending = true; }
+      }
+      // 재기동은 «지금 이 TUI 가 보여 주는 대화» 로만 잇는다 — 읽기 실패는 null(대체 세션을 지어내지 않는다).
+      let sessionId: string | null = selfRestart.sessionId ?? null;
+      if (selfRestart.readSessionId) {
+        try { sessionId = selfRestart.readSessionId(); } catch { sessionId = null; }
+      }
+      const idleMs = recorder.idleSince === undefined ? null : Math.max(0, now() - recorder.idleSince);
+      const decision = decideSelfRestart({
+        stale: staleness.stale,
+        staleReason: staleness.reason,
+        turn: recorder.last ?? 'unknown',
+        idleMs,
+        humanInputPending,
+        minIdleMs,
+      });
+      if (!decision.restart || restartedFor.has(staleness.reason) || restartInFlight) return;
+      if (!sessionId) {
+        log('self-restart-no-session', { ptyId: surfaceId, staleReason: staleness.reason });
+        return;
+      }
+      const plan: TuiSelfRestartPlan = {
+        surfaceId,
+        staleReason: staleness.reason,
+        idleMs: idleMs ?? 0,
+        relaunchCommand: sessionId ? buildStaleInstallRelaunchCommand(sessionId) : null,
+      };
+      log('self-restart', { ptyId: surfaceId, reason: decision.reason, staleReason: plan.staleReason, idleMs: plan.idleMs, relaunchCommand: plan.relaunchCommand });
+      restartInFlight = true;
+      const handoff = (): void => {
+        // 새 세션이 실제로 생성된 뒤에만 낡은 TUI 가 좌석 행 쓰기를 놓는다.
+        if (selfRestart.yieldSeat) {
+          try {
+            selfRestart.yieldSeat(plan);
+          } catch (error) {
+            log('self-restart-yield-failed', { ptyId: surfaceId, error: error instanceof Error ? error.message : String(error) });
+          }
+        }
+        if (active === recorder) active = null;
+        restartedFor.add(staleness.reason);
+        restartInFlight = false;
+        log('self-restart-handover', { ptyId: surfaceId, staleReason: plan.staleReason, relaunchCommand: plan.relaunchCommand });
+      };
+      const failed = (error: unknown): void => {
+        restartInFlight = false;
+        log('self-restart-failed', { ptyId: surfaceId, error: error instanceof Error ? error.message : String(error) });
+      };
+      try {
+        if (selfRestart.restart) {
+          selfRestart.restart(plan);
+          handoff();
+        } else {
+          void spawnTuiRelaunch(sessionId).then(handoff, failed);
+        }
+      } catch (error) {
+        failed(error);
+      }
+    };
+    try {
+      const watch = selfRestart.watch ?? ((fn: () => void) => defaultWatch(fn, selfRestart.intervalMs ?? Math.max(5_000, Math.round(minIdleMs / 3))));
+      unwatch = watch(tick);
+    } catch (error) {
+      log('self-restart-watch-failed', { ptyId: surfaceId, error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  // raw 모드 전 ctrl+c(SIGINT 기본 죽음)는 'exit' 훅을 안 돌린다 — 신호에서도 반납한다.
+  const signals = deps.signals !== undefined ? deps.signals : (deps.herdr === undefined ? process : null);
+  let unguard: () => void = () => {};
+  if (herdr && signals) {
+    try { unguard = guardHerdrReleaseOnSignal(() => herdr.release(), signals); } catch { /* 지킴이 실패가 녹음기를 깨지 않는다 */ }
+  }
   return () => {
+    try { unwatch(); } catch { /* 종료 경로를 깨지 않는다 */ }
+    try { unguard(); } catch { /* 종료 경로를 깨지 않는다 */ }
     if (herdr) { try { herdr.release(); } catch { /* 종료 경로를 깨지 않는다 */ } }
     if (active === recorder) active = null;
   };
@@ -377,7 +618,12 @@ function writeTurnState(recorder: ActiveRecorder, turn: PtyTurnState): void {
   const at = recorder.now();
   let ok = false;
   try { ok = recorder.writeTurn(recorder.surfaceId, turn, at); } catch { ok = false; }
-  if (ok) recorder.last = turn;
+  if (ok) {
+    recorder.last = turn;
+    // 유휴 경과의 0초는 «idle 로 바뀐 시각» — busy 로 가면 다시 모른다.
+    if (turn === 'idle') recorder.idleSince = at;
+    else recorder.idleSince = undefined;
+  }
   // 실패는 관측으로 남긴다 — 바깥 제어자는 그 사이 «unknown/낡은 값»을 본다. 성공은 남기지 않는다(턴마다 두 줄은 소음).
   else recorder.log('turn-write-failed', { ptyId: recorder.surfaceId, turn, at });
   // herdr 는 manifest 쓰기 성패와 무관하게, 값이 바뀔 때 알린다(같은 값 재시도는 한 번만).

package/src/release-loop/auto-start.ts

@@ -21,9 +21,13 @@ export type AutoStartDeferral = { deferred: true; reason: Exclude<ReleaseReadine
 export type AutoStartResult =
   | { status: 'no-cut' }
   | { status: 'planned'; version: string; cutAt: string }
-  | { status: 'skipped'; version: string; reason: AutoStartDeferral['reason'] }
+  | { status: 'skipped'; version: string; reason: Exclude<AutoStartDeferral['reason'], 'already-running'> }
+  /** A live run of the selected version is a refusal (rc1), not a quiet deferral — the reason names that run. */
+  | { status: 'already-running'; version: string; runId: string; pid: number; startedAt: string }
   | { status: 'started'; version: string; cutAt: string; publishAt?: string };
 
+export interface AutoStartActiveRun { runId: string; pid: number; startedAt: string }
+
 export interface AutoStartOptions {
   windowMinutes: number;
   apply?: boolean;
@@ -31,6 +35,8 @@ export interface AutoStartOptions {
   ledgerRoot?: string;
   schedules?: (root: string) => ReleaseSchedule[];
   readiness?: (version: string, ledgerRoot: string, now: Date) => ReleaseReadiness;
+  /** The live run of `version` (graph-run ledger · force marker · run.lock), asked before readiness on `--apply`. */
+  activeRun?: (version: string, ledgerRoot: string) => AutoStartActiveRun | undefined;
   launch?: (version: string, launchOptions?: { publishAt?: string }) => void | AutoStartDeferral | Promise<void | AutoStartDeferral>;
 }
 
@@ -43,11 +49,23 @@ export async function autoStartScheduledRelease(options: AutoStartOptions): Prom
   if (!schedule) return { status: 'no-cut' };
   const { version, cutAt, publishAt } = schedule;
   if (!options.apply) return { status: 'planned', version, cutAt };
+  const refuse = (run: AutoStartActiveRun): AutoStartResult => {
+    debug.log('release.schedule', 'auto-start-already-running', { version, cutAt, ...run });
+    return { status: 'already-running', version, ...run };
+  };
+  const active = options.activeRun?.(version, root);
+  if (active) return refuse(active);
   const readiness = (options.readiness ?? ((v, ledgerRoot, at) => releaseReadiness(v, { ledgerRoot, now: () => at })))(version, root, now);
+  // A live run.lock without a resolvable run identity still refuses; its pid is the readiness detail.
+  if (!readiness.ready && readiness.reason === 'already-running') return refuse({ runId: 'pending', pid: Number(readiness.details), startedAt: 'unknown' });
   if (!readiness.ready) return { status: 'skipped', version, reason: readiness.reason };
   if (!options.launch) throw new Error('auto-start apply requires a launch callback');
   const launched = await options.launch(version, publishAt != null ? { publishAt: publishAt } : {});
-  if (launched?.deferred) return { status: 'skipped', version, reason: launched.reason };
+  if (launched?.deferred) {
+    const { reason } = launched;
+    if (reason === 'already-running') return refuse(options.activeRun?.(version, root) ?? { runId: 'pending', pid: 0, startedAt: 'unknown' });
+    return { status: 'skipped', version, reason };
+  }
   debug.log('release.schedule', 'auto-start', { version, cutAt, publishAt: publishAt ?? null });
   return { status: 'started', version, cutAt, ...(publishAt != null ? { publishAt: publishAt } : {}) };
 }

package/src/release-loop/checklist.ts

@@ -13,6 +13,15 @@ export type ChecklistKind = 'screen' | 'postpub';
 const CHECKLIST_KINDS: readonly ChecklistKind[] = ['screen', 'postpub'];
 export type ChecklistDispatchKind = 'code' | 'ops' | 'measure' | 'decision' | 'umbrella';
 const CHECKLIST_DISPATCH_KINDS: readonly ChecklistDispatchKind[] = ['code', 'ops', 'measure', 'decision', 'umbrella'];
+/** MUST 지정 — 이 칸이 지켜야 하는 조건과 그 효과. 원장에는 `must` 이벤트(전체 값)로만 실린다. */
+export interface ChecklistMust {
+  version: string;
+  reason: string;
+  setBy: string;
+  setAt: string;
+  effect: string;
+}
+const MUST_FIELDS = ['version', 'reason', 'setBy', 'setAt', 'effect'] as const;
 export interface ChecklistItem {
   id: string;
   title: string;
@@ -28,10 +37,14 @@ export interface ChecklistItem {
   /** 이 칸이 근거로 삼는 문서(저장소 상대 경로, 선택적으로 `#절`). 없으면 칸에 실리지 않는다. */
   refs?: string[];
   evidence?: string;
+  /** Public known-issue wording, independent from the internal checklist title. */
+  knownIssue?: string;
   disposition?: ChecklistDisposition;
   kind?: ChecklistKind;
   /** Whether the seat dispatcher should launch a coding task. Missing in old rows means code. */
   dispatchKind?: ChecklistDispatchKind;
+  /** MUST 지정(있으면 이 칸은 MUST 다). 원장 스키마에 must 컬럼이 없어 `must` 이벤트에서 복원한다. */
+  must?: ChecklistMust;
   updatedAt: string;
   updatedBy: string;
 }
@@ -56,6 +69,49 @@ export interface Checklist {
   history: ChecklistHistory[];
 }
 
+export type ChecklistEvidenceState = 'observed' | 'missing' | 'unmeasurable';
+export type ChecklistEvidenceStageId = 'E1' | 'E3' | 'E4' | 'E5';
+export interface ChecklistEvidenceStage {
+  id: ChecklistEvidenceStageId;
+  state: ChecklistEvidenceState;
+  source: string | null;
+  measuredAt: string | null;
+  reason: string;
+  verificationCommand?: string | null;
+}
+export interface ChecklistEvidenceChain {
+  id: string;
+  version: string;
+  stages: ChecklistEvidenceStage[];
+  greenEligible: boolean;
+  reason: string | null;
+}
+
+/** Build a read-only, fail-closed evidence verdict. Claims are observed only when a source adapter verifies them. */
+export function checklistEvidenceChain(input: {
+  item: ChecklistItem;
+  version: string;
+  stages: readonly ChecklistEvidenceStage[];
+}): ChecklistEvidenceChain {
+  const required: ChecklistEvidenceStageId[] = ['E1', 'E3', 'E4', 'E5'];
+  const byId = new Map(input.stages.map((stage) => [stage.id, stage]));
+  const stages = required.map((id) => {
+    const stage = byId.get(id);
+    if (!stage) return { id, state: 'unmeasurable' as const, source: null, measuredAt: null, reason: '출처 어댑터 결과가 없다' };
+    if (stage.state === 'observed' && (!stage.source?.trim() || !stage.measuredAt || !Number.isFinite(Date.parse(stage.measuredAt))))
+      return { ...stage, state: 'unmeasurable' as const, reason: 'observed 판정에 유효한 출처와 측정 시각이 없다' };
+    return stage;
+  });
+  const unresolved = stages.filter((stage) => stage.state !== 'observed');
+  return {
+    id: input.item.id,
+    version: input.version,
+    stages,
+    greenEligible: unresolved.length === 0,
+    reason: unresolved.length ? `${unresolved.map((stage) => `${stage.id}=${stage.state}: ${stage.reason}`).join('; ')}` : null,
+  };
+}
+
 export function devVersion(): string {
   return (JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as { version: string }).version;
 }
@@ -92,13 +148,51 @@ function decodeClaimHistory(data: Checklist): Checklist {
   return { ...data, history: data.history.map(decodeClaimHistoryEntry) };
 }
 
+/** A `must` event carries the whole MUST value in `to`; anything that is not five strings is not a MUST. */
+function mustValue(value: unknown): ChecklistMust | null {
+  if (!value || typeof value !== 'object') return null;
+  const record = value as Record<string, unknown>;
+  if (!MUST_FIELDS.every((field) => typeof record[field] === 'string')) return null;
+  return { version: record.version as string, reason: record.reason as string, setBy: record.setBy as string, setAt: record.setAt as string, effect: record.effect as string };
+}
+
+function decodeMustEntry<T extends ChecklistHistory>(entry: T): T {
+  if (entry.field !== 'must') return entry;
+  const must = mustValue(entry.to);
+  return must ? { ...entry, to: must } as T : entry;
+}
+
+/** The ledger event schema has no must column either; the last `must` event is this cell's MUST. */
+function decodeMustHistory(data: Checklist): Checklist {
+  const latest = new Map<string, ChecklistMust>();
+  for (const entry of data.history) {
+    if (entry.field !== 'must') continue;
+    const must = mustValue(entry.to);
+    if (must) latest.set(entry.id, must);
+  }
+  if (!latest.size) return data;
+  return { ...data, items: data.items.map((item) => {
+    const must = latest.get(item.id);
+    return must ? { ...item, must } : item;
+  }) };
+}
+
+function latestMust(history: readonly ChecklistHistory[], id: string): ChecklistMust | null {
+  for (let index = history.length - 1; index >= 0; index--) {
+    const entry = history[index]!;
+    if (entry.id !== id || entry.field !== 'must') continue;
+    return mustValue(entry.to);
+  }
+  return null;
+}
+
 export function listChecklist(v: string, root?: string): Checklist {
-  return decodeClaimHistory(root === undefined ? store.list(v) : store.list(v, undefined, undefined, root));
+  return decodeMustHistory(decodeClaimHistory(root === undefined ? store.list(v) : store.list(v, undefined, undefined, root)));
 }
 
 /** Events for this id across every release, ordered by event time (then ledger sequence). */
 export function checklistHistory(id: string): Array<ChecklistHistory & { version: string; seq: number }> {
-  return store.history(id).map(decodeClaimHistoryEntry);
+  return store.history(id).map((entry) => decodeMustEntry(decodeClaimHistoryEntry(entry)));
 }
 
 /** Status events in the requested window; other ledger fields never become status changes. */
@@ -116,8 +210,8 @@ function assertPredecessorsExist(predecessors: readonly string[] | undefined, da
 }
 
 function mutate(v: string, apply: (data: Checklist, otherItems: (id: string) => store.ChecklistCollision[]) => boolean): Checklist {
-  // addItem/setItem/claimItem/removeItem/seedFromRoadmap reach the generation-fenced ledger write here.
-  return decodeClaimHistory(store.mutate(v, store.releasedVersion(), devVersion(), apply));
+  // addItem/setItem/claimItem/removeItem/seedFromRoadmap/setMust reach the generation-fenced ledger write here.
+  return decodeMustHistory(decodeClaimHistory(store.mutate(v, store.releasedVersion(), devVersion(), apply)));
 }
 
 function change(data: Checklist, id: string, field: string, from: unknown, to: unknown, by: string, at: string): void {
@@ -356,10 +450,33 @@ export function addItem(v: string, input: { id: string; title: string; refs?: st
   });
 }
 
-export function setItem(v: string, id: string, patch: { status?: ChecklistStatus; evidence?: string; refs?: string[]; owner?: string; disposition?: ChecklistDisposition; kind?: ChecklistKind; dispatchKind?: ChecklistDispatchKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean | null }, by: string): Checklist {
+export function setItem(v: string, id: string, patch: { status?: ChecklistStatus; evidence?: string; knownIssue?: string | null; refs?: string[]; owner?: string; disposition?: ChecklistDisposition; kind?: ChecklistKind; dispatchKind?: ChecklistDispatchKind; priority?: ChecklistItem['priority']; predecessors?: string[]; deadlineVersion?: string; ceoMinutes?: number; ceoDate?: string; accelerator?: boolean | null }, by: string): Checklist {
   return setItemGuarded(v, id, patch, by);
 }
 
+/** 효과 없는 MUST 는 게이트가 판단할 근거가 없다 — 거부한다. */
+function validateMust(must: ChecklistMust): ChecklistMust {
+  if (!must.effect.trim()) throw new CliUserError('MUST 효과가 비었다', "release checklist must <id> --effect '<게이트에 미치는 효과>'");
+  return must;
+}
+
+/** 이 칸의 MUST 를 세운다. 저장은 `must` 이벤트(from = 이전 전체 값, to = 새 전체 값)로만 하고, 다른 칸 행은 건드리지 않는다. */
+export function setMust(v: string, id: string, input: { version: string; reason: string; effect: string }, by: string): Checklist {
+  if (!by.trim()) throw new CliUserError('MUST 기록 주체가 비었다');
+  const at = new Date().toISOString();
+  const must = validateMust({ version: input.version, reason: input.reason, setBy: by, setAt: at, effect: input.effect });
+  return mutate(v, (data) => {
+    const item = data.items.find((entry) => entry.id === id);
+    if (!item) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
+    const previous = latestMust(data.history, id);
+    if (previous && JSON.stringify(previous) === JSON.stringify(must)) return false;
+    item.updatedAt = at;
+    item.updatedBy = by;
+    change(data, id, 'must', previous, must, by, at);
+    return true;
+  });
+}
+
 /** Remove only the exact machine-authored line; preserve all other evidence bytes and blank lines. */
 export function withoutDispatchSkipLine(evidence: string, line: string | null): string {
   if (!line) return evidence;
@@ -429,13 +546,13 @@ function setItemGuarded(v: string, id: string, patch: Parameters<typeof setItem>
         throw new CliUserError(`지금 주인: ${item.owner} — --force 로만 바꾼다`, 'release checklist claim <id> --by <자리> --force');
       }
     }
-    const fields = (['evidence', 'owner', 'status', 'disposition', 'kind', 'dispatchKind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator', 'refs'] as const).filter((field) => patch[field] !== undefined && JSON.stringify(patch[field]) !== JSON.stringify(item[field] ?? null));
+    const fields = (['evidence', 'knownIssue', 'owner', 'status', 'disposition', 'kind', 'dispatchKind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator', 'refs'] as const).filter((field) => patch[field] !== undefined && JSON.stringify(patch[field]) !== JSON.stringify(item[field] ?? null));
     if (fields.length === 0) return false;
     const at = new Date().toISOString();
     for (const field of fields) {
       const from = item[field];
       const to = patch[field]!;
-      if (field === 'accelerator' && to === null) delete item.accelerator;
+      if ((field === 'accelerator' || field === 'knownIssue') && to === null) delete (item as unknown as Record<string, unknown>)[field];
       else (item as unknown as Record<string, unknown>)[field] = to;
       item.updatedAt = at;
       item.updatedBy = by;
@@ -513,7 +630,7 @@ export interface ChecklistGate {
   undecided: string[];
   blocked: string[];
   moved: string[];
-  knownIssues: Array<{ id: string; title: string; evidence: string }>;
+  knownIssues: Array<{ id: string; title: string; evidence: string; knownIssue?: string }>;
   /** Post-publication cells excluded from the pre-publication judgement. */
   postpub?: string[];
   /** Screen cells whose `짝:` line is missing or has an untracked ⏳ — a warning; it never changes `ok`. */
@@ -544,7 +661,7 @@ export function checklistGate(v: string): ChecklistGate {
     if (item.status !== 'yellow') continue;
     if (item.disposition === 'block') result.blocked.push(item.id);
     else if (item.disposition === 'move') result.moved.push(item.id);
-    else if (item.disposition === 'known-issue') result.knownIssues.push({ id: item.id, title: item.title, evidence: item.evidence ?? '' });
+    else if (item.disposition === 'known-issue') result.knownIssues.push({ id: item.id, title: item.title, evidence: item.evidence ?? '', ...(item.knownIssue?.trim() ? { knownIssue: item.knownIssue.trim() } : {}) });
     else result.undecided.push(item.id);
   }
   result.ok = result.red.length === 0 && result.undecided.length === 0 && result.blocked.length === 0;