elanous 0.2.36 → 0.2.38

package/src/pty-shell/registry.ts

@@ -23,6 +23,8 @@ import { getSessionCwd } from '../session/working-dir.js';
 import { buildPtyEnv } from '../agent/identity-env.js';
 import { getCurrentPtyId } from '../agent/pty-identity.js';
 import { bunNativePtyAvailable, bunSpawnPty } from './bun-native-pty.js';
+import { ptyAvailable } from './availability.js';
+export { ptyAvailable } from './availability.js';
 import { resolvePtyRef, canTransitionAccessMode, ptyIdSeparatorIndex, type PtyAccessMode, type PtyTransitionPolicy } from './pty-ref.js';
 import { resolveWriteDecision, resolveTakeover, type PtyWriteActor } from './pty-write-arbiter.js';
 import { addPtyManifestOutputBytes, upsertPtyManifest, updatePtyManifestSnapshot, updatePtyManifestNickname, markPtyManifestClosed, removePtyManifest, touchLivePtyManifest } from './pty-manifest.js';
@@ -513,7 +515,7 @@ export function startPty(opts: StartOpts): PtyHandle {
     set nickname(v: string | undefined) { nickname = v; },
     setNickname(name: string): void {
       nickname = name.trim() || undefined;
-      if (PTY_MANIFEST_ENABLED) updatePtyManifestNickname(id, nickname, Date.now());
+      if (ptyManifestEnabled()) updatePtyManifestNickname(id, nickname, Date.now());
     },
     get accessMode() { return accessMode; },
     set accessMode(v: PtyAccessMode) { accessMode = v; },
@@ -718,7 +720,7 @@ export function startPty(opts: StartOpts): PtyHandle {
     catch (error) { debug.log('pty.record', 'tap-error', { ptyId: id, error: String(error) }); }
     emitPtyEvent({ type: 'output', id, chunk });
     // ★ 크로스-프로세스 관측(2026-07-23) — throttled 스냅샷을 공유 매니페스트에(데몬 PWA 유니온). getter 라 throttle 통과 시에만 snapshot().
-    if (PTY_MANIFEST_ENABLED) {
+    if (ptyManifestEnabled()) {
       pendingManifestOutputBytes += Buffer.byteLength(chunk, 'utf8');
       const now = Date.now();
       // ⛔⭐ throttle 이 막은 출력도 «반드시» 실린다 — 안 그러면 마지막 버스트 뒤 조용해진 PTY 의
@@ -741,7 +743,7 @@ export function startPty(opts: StartOpts): PtyHandle {
     try { autoStopPtyRecording(id); }
     catch (error) { debug.log('pty.record', 'auto-stop-error', { ptyId: id, error: String(error) }); }
     emitPtyEvent({ type: 'exit', id, exitCode: code, signal });
-    if (PTY_MANIFEST_ENABLED) {
+    if (ptyManifestEnabled()) {
       const now = Date.now();
       // Manifest closure and output durability are separate: a closed row keeps retrying trailing bytes until committed.
       manifestOutputFlush.close(now);
@@ -754,7 +756,7 @@ export function startPty(opts: StartOpts): PtyHandle {
   // ★ 크로스-프로세스 관측 — startPty 를 공유 매니페스트에 등록(다른 프로세스 데몬이 /v1/terminals 로 봄). fail-soft.
   //   ⚠️ 테스트 런(NODE_ENV=test·bun test)은 skip — 테스트가 띄우는 임시 셸(self-implement gate·CI·수동 bun test)이
   //   운영 매니페스트(~/.elanous/pty)로 새어들어 관측소를 오염시키던 근본 차단(격리). 실 세션(NODE_ENV≠test)만 등록.
-  if (PTY_MANIFEST_ENABLED) {
+  if (ptyManifestEnabled()) {
     const childSpaceId = opts.env?.ELANOUS_HARNESS_SPACE_ID;
     const childParentPtyId = opts.env?.ELANOUS_PARENT_PTY_ID ?? getCurrentPtyId();
     const childController = opts.env?.ELANOUS_CONTROLLER?.trim();
@@ -800,8 +802,24 @@ export function startPty(opts: StartOpts): PtyHandle {
   return handle;
 }
 
-/** 공유 PTY 매니페스트 등록 활성 여부 — 테스트 런(bun test=NODE_ENV=test)은 운영 매니페스트 오염 방지 위해 off. */
-const PTY_MANIFEST_ENABLED = process.env.NODE_ENV !== 'test';
+/** 공유 PTY 매니페스트 등록 활성 여부 — 테스트 런(bun test=NODE_ENV=test)은 운영 매니페스트 오염 방지 위해 off.
+ *
+ *  ⭐ 자리(seat) 수명주기는 이 기록자에서만 원장에 실린다 — spawned/exited 사건의 seat·
+ *  누적 outputBytesTotal·exitCode 를 남기는 곳이 `upsertPtyManifest`/`markPtyManifestClosed` 이기
+ *  때문이다. 그런데 NODE_ENV 판정만 있으면 **격리 test 우주에서는 이 경로를 한 번도 지날 수 없어**
+ *  자리 수명주기가 실행 증거를 가질 수 없다(합성 manifest 직접 호출만 남는다 — 완료 경계가 금지).
+ *  ⇒ 판정을 호출 시점 함수로 두고, 격리 우주(전용 `ELANOUS_STATE_DIR`·전용 manifest db)가 **명시적으로**
+ *  켤 수 있는 seam 을 둔다. override 가 없으면 종전과 같은 NODE_ENV 판정이라 운영 동작은 불변이다. */
+let _ptyManifestEnabledOverride: boolean | null = null;
+
+/** 테스트 전용 seam — 격리 우주에서 생산 기록 경로를 그대로 지나기 위해 켠다. null = NODE_ENV 판정 복귀. */
+export function setPtyManifestEnabledForTesting(enabled: boolean | null): void {
+  _ptyManifestEnabledOverride = enabled;
+}
+
+function ptyManifestEnabled(): boolean {
+  return _ptyManifestEnabledOverride ?? process.env.NODE_ENV !== 'test';
+}
 
 // ★ 라이브 PTY 하트비트(2026-07-23) — 소유 프로세스가 자기 라이브 PTY 의 updated_at 을 주기 갱신해
 //   "살아있음"을 증명한다. 데몬의 stale reap 이 하트비트 끊긴 유령만 제거하도록(pid 재활용 견고). unref 로 프로세스 종료 방해 X.
@@ -904,7 +922,7 @@ export function renamePty(id: string, nickname: string): boolean {
   //    별명은 manifest 행에만 산다. 여기서 받지 않으면 IPC rename 이 그 행에 `unknown-pty` 로 진다.
   const target = controlTargets.get(id);
   if (!target || !target.isAlive()) return false;
-  if (PTY_MANIFEST_ENABLED) updatePtyManifestNickname(id, nickname.trim() || undefined, Date.now());
+  if (ptyManifestEnabled()) updatePtyManifestNickname(id, nickname.trim() || undefined, Date.now());
   debug.log('pty.rename', 'control-target-renamed', { ptyId: id, nickname: nickname.trim() });
   return true;
 }
@@ -1012,14 +1030,6 @@ export function killNonDetached(): number {
   return killed;
 }
 
-/** Probe-compatible. Under Bun the native PTY (Bun.spawn terminal) is
- *  used instead of node-pty, so PTY is available even if node-pty can't
- *  resolve. Under node we still require node-pty. */
-export function ptyAvailable(): boolean {
-  if (bunNativePtyAvailable()) return true;
-  try { require.resolve('node-pty'); return true; } catch { return false; }
-}
-
 // ─── Adapter wiring ──────────────────────────────────────────────
 
 let cachedSpawn: ((opts: StartOpts) => PtyAdapter) | null | undefined = undefined;

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

@@ -11,6 +11,7 @@
 //   `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';
@@ -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 {
@@ -326,6 +465,11 @@ export interface TuiRunStateRecorderDeps {
    * 생략 시: 기본 신고기(herdr 미주입)일 때만 실 `process` · 주입 herdr 는 지킴이 0. `null` 이면 안 건다.
    */
   readonly signals?: HerdrSignalTarget | null;
+  /**
+   * H9 자기 재기동(낡은 판 ∧ 유휴 ∧ 사람 입력 없음 ⇒ 새 세션 ⊕ 자리 맥락 재주입).
+   * 생략하면 감시를 안 건다 — 이 축을 켜는 것은 호출자(생산 진입점)의 결정이다.
+   */
+  readonly selfRestart?: TuiSelfRestartDeps;
 }
 
 interface ActiveRecorder {
@@ -336,6 +480,8 @@ interface ActiveRecorder {
   readonly herdr: HerdrAgentReporterLike | null;
   /** manifest 에 실제로 적힌 마지막 턴. 실패면 안 바뀐다(재시도). */
   last?: PtyTurnState;
+  /** idle 로 «바뀐» 시각 — 유휴 경과의 0초. busy 로 가면 다시 모른다. */
+  idleSince?: number;
   /** herdr 에 마지막으로 알린 턴. manifest 성패와 따로 둔다. */
   herdrLast?: PtyTurnState;
 }
@@ -366,6 +512,88 @@ 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 = () => {};
@@ -373,6 +601,7 @@ export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRec
     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;
@@ -389,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/checklist.ts

@@ -37,6 +37,8 @@ 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. */
@@ -67,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;
 }
@@ -405,7 +450,7 @@ 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);
 }
 
@@ -501,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;
@@ -585,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`. */
@@ -616,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;

package/src/release-loop/feature-store.ts

@@ -36,7 +36,7 @@ const walWait = new Int32Array(new SharedArrayBuffer(4));
 const SCHEMA_COLUMNS: Record<string, readonly string[]> = {
   imported_versions: ['json_hash', 'imported_at'],
   events: ['reason', 'generation'],
-  assignments: ['priority', 'predecessors', 'deadline_version', 'ceo_minutes', 'ceo_date', 'accelerator', 'refs', 'dispatch_kind'],
+  assignments: ['priority', 'predecessors', 'deadline_version', 'ceo_minutes', 'ceo_date', 'accelerator', 'refs', 'dispatch_kind', 'known_issue'],
   release_schedules: ['freeze_from', 'freeze_until', 'publish_at'],
 };
 function schemaCurrent(db: Database): boolean {
@@ -81,7 +81,7 @@ function open(root = releaseLedgerRoot()): Database {
       if (!eventColumns.some((column) => column.name === 'generation')) db.exec('ALTER TABLE events ADD COLUMN generation INTEGER');
       db.exec('CREATE TABLE IF NOT EXISTS release_schedules (version TEXT PRIMARY KEY, cut_at TEXT NOT NULL, land_by TEXT, updated_at TEXT NOT NULL, updated_by TEXT NOT NULL)');
       const assignmentColumns = db.query('PRAGMA table_info(assignments)').all() as Array<{ name: string }>;
-      for (const [name, sql] of [['priority', 'TEXT'], ['predecessors', 'TEXT'], ['deadline_version', 'TEXT'], ['ceo_minutes', 'INTEGER'], ['ceo_date', 'TEXT'], ['accelerator', 'INTEGER'], ['refs', 'TEXT'], ['dispatch_kind', 'TEXT']] as const) {
+      for (const [name, sql] of [['priority', 'TEXT'], ['predecessors', 'TEXT'], ['deadline_version', 'TEXT'], ['ceo_minutes', 'INTEGER'], ['ceo_date', 'TEXT'], ['accelerator', 'INTEGER'], ['refs', 'TEXT'], ['dispatch_kind', 'TEXT'], ['known_issue', 'TEXT']] as const) {
         if (!assignmentColumns.some((column) => column.name === name)) db.exec(`ALTER TABLE assignments ADD COLUMN ${name} ${sql}`);
       }
       const scheduleColumns = db.query('PRAGMA table_info(release_schedules)').all() as Array<{ name: string }>;
@@ -178,7 +178,7 @@ function evidenceRefs(db: Database, version: string, id: string): string[] {
   return (db.query('SELECT ref FROM evidence WHERE feature_id = ? AND version = ? ORDER BY rowid').all(id, version) as Array<{ ref: string }>).map((row) => row.ref);
 }
 function items(db: Database, version: string): ChecklistItem[] {
-  const rows = db.query(`SELECT f.id, COALESCE(a.title_override, f.title) AS title, a.owner, a.kind, a.dispatch_kind, a.priority, a.predecessors, a.deadline_version, a.ceo_minutes, a.ceo_date, a.accelerator, a.refs, a.status, a.disposition, a.evidence, a.updated_at, a.updated_by
+  const rows = db.query(`SELECT f.id, COALESCE(a.title_override, f.title) AS title, a.owner, a.kind, a.dispatch_kind, a.priority, a.predecessors, a.deadline_version, a.ceo_minutes, a.ceo_date, a.accelerator, a.refs, a.status, a.disposition, a.evidence, a.known_issue, a.updated_at, a.updated_by
     FROM assignments a JOIN features f ON f.id = a.feature_id WHERE a.version = ? ORDER BY a.rowid`).all(version) as Array<Record<string, string | number | null>>;
   return rows.map((r) => {
     const evidence = [r.evidence, ...evidenceRefs(db, version, r.id as string)].filter((value) => value !== null).join('\n');
@@ -190,7 +190,7 @@ function items(db: Database, version: string): ChecklistItem[] {
       ...(r.ceo_minutes !== null ? { ceoMinutes: r.ceo_minutes as number } : {}), ...(r.ceo_date !== null ? { ceoDate: r.ceo_date as string } : {}),
       ...(r.accelerator === 1 ? { accelerator: true as const } : {}),
       ...(r.refs !== null && r.refs !== undefined ? { refs: JSON.parse(r.refs as string) as string[] } : {}),
-      ...(r.evidence !== null || evidence ? { evidence } : {}), ...(r.disposition !== null ? { disposition: r.disposition as ChecklistItem['disposition'] } : {}),
+      ...(r.evidence !== null || evidence ? { evidence } : {}), ...(r.known_issue !== null ? { knownIssue: r.known_issue as string } : {}), ...(r.disposition !== null ? { disposition: r.disposition as ChecklistItem['disposition'] } : {}),
       updatedAt: r.updated_at as string, updatedBy: r.updated_by as string };
   });
 }
@@ -203,9 +203,9 @@ function putItem(db: Database, version: string, item: ChecklistItem): void {
   if (!feature) db.query('INSERT INTO features (id, title, owner, kind, created_at) VALUES (?, ?, ?, ?, ?)').run(item.id, item.title, item.owner ?? null, item.kind ?? null, item.updatedAt);
   // features.owner/kind follow the latest assignment so details() and the checklist never disagree after a set.
   else if (item.owner !== undefined || item.kind !== undefined) db.query('UPDATE features SET owner = COALESCE(?, owner), kind = COALESCE(?, kind) WHERE id = ?').run(item.owner ?? null, item.kind ?? null, item.id);
-  db.query(`INSERT INTO assignments (feature_id, version, status, disposition, evidence, title_override, owner, kind, dispatch_kind, priority, predecessors, deadline_version, ceo_minutes, ceo_date, accelerator, refs, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(feature_id, version) DO UPDATE SET status=excluded.status, disposition=excluded.disposition, evidence=excluded.evidence, owner=excluded.owner, kind=excluded.kind, dispatch_kind=excluded.dispatch_kind, priority=excluded.priority, predecessors=excluded.predecessors, deadline_version=excluded.deadline_version, ceo_minutes=excluded.ceo_minutes, ceo_date=excluded.ceo_date, accelerator=excluded.accelerator, refs=excluded.refs, updated_at=excluded.updated_at, updated_by=excluded.updated_by`)
-    .run(item.id, version, item.status, item.disposition ?? null, item.evidence ?? null, feature && feature.title !== item.title ? item.title : null, item.owner ?? null, item.kind ?? null, item.dispatchKind ?? null, item.priority ?? null, item.predecessors ? JSON.stringify(item.predecessors) : null, item.deadlineVersion ?? null, item.ceoMinutes ?? null, item.ceoDate ?? null, item.accelerator === true ? 1 : null, item.refs?.length ? JSON.stringify(item.refs) : null, item.updatedAt, item.updatedBy);
+  db.query(`INSERT INTO assignments (feature_id, version, status, disposition, evidence, title_override, owner, kind, dispatch_kind, priority, predecessors, deadline_version, ceo_minutes, ceo_date, accelerator, refs, known_issue, updated_at, updated_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(feature_id, version) DO UPDATE SET status=excluded.status, disposition=excluded.disposition, evidence=excluded.evidence, owner=excluded.owner, kind=excluded.kind, dispatch_kind=excluded.dispatch_kind, priority=excluded.priority, predecessors=excluded.predecessors, deadline_version=excluded.deadline_version, ceo_minutes=excluded.ceo_minutes, ceo_date=excluded.ceo_date, accelerator=excluded.accelerator, refs=excluded.refs, known_issue=excluded.known_issue, updated_at=excluded.updated_at, updated_by=excluded.updated_by`)
+    .run(item.id, version, item.status, item.disposition ?? null, item.evidence ?? null, feature && feature.title !== item.title ? item.title : null, item.owner ?? null, item.kind ?? null, item.dispatchKind ?? null, item.priority ?? null, item.predecessors ? JSON.stringify(item.predecessors) : null, item.deadlineVersion ?? null, item.ceoMinutes ?? null, item.ceoDate ?? null, item.accelerator === true ? 1 : null, item.refs?.length ? JSON.stringify(item.refs) : null, item.knownIssue ?? null, item.updatedAt, item.updatedBy);
 }
 function jsonHash(contents: string | Buffer): string { return createHash('sha256').update(contents).digest('hex'); }
 
@@ -274,7 +274,7 @@ function importOnDb(db: Database, version: string): boolean {
       record(db, version, { at: new Date().toISOString(), by: item.updatedBy, id: item.id, field: 'reimport', from: null, to: item, released: data.released, dev: data.dev });
       continue;
     }
-    const fields = ['title', 'status', 'evidence', 'owner', 'disposition', 'kind', 'dispatchKind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator', 'refs'] as const;
+    const fields = ['title', 'status', 'evidence', 'knownIssue', 'owner', 'disposition', 'kind', 'dispatchKind', 'priority', 'predecessors', 'deadlineVersion', 'ceoMinutes', 'ceoDate', 'accelerator', 'refs'] as const;
     const baseEvidence = (db.query('SELECT evidence FROM assignments WHERE feature_id = ? AND version = ?').get(item.id, version) as { evidence: string | null }).evidence ?? undefined;
     const preserveRefs = item.evidence === baseEvidence || item.evidence === current.evidence;
     const differs = fields.some((field) => field === 'evidence'
@@ -441,7 +441,7 @@ export function set(version: string, id: string, patch: Partial<ChecklistItem>,
   return mutate(version, released, dev, (data) => {
     const item = data.items.find((i) => i.id === id);
     if (!item) throw new CliUserError(`없는 칸: ${id}`, 'list 로 칸 목록을 본다');
-    const fields = (['evidence', 'owner', 'status', 'disposition', 'kind'] as const).filter((field) => patch[field] !== undefined && patch[field] !== item[field]);
+    const fields = (['evidence', 'knownIssue', 'owner', 'status', 'disposition', 'kind'] as const).filter((field) => patch[field] !== undefined && patch[field] !== item[field]);
     if (!fields.length) return false;
     const at = new Date().toISOString();
     for (const field of fields) {

package/src/release-loop/gate-shards.ts

@@ -12,6 +12,12 @@ export type ShardState = typeof SHARD_STATES[number];
 export interface GateShard {
   id: string;
   state: ShardState;
+  /** Kubernetes Job for the current attempt; lets the gate watchdog reconcile a lost completion callback. */
+  job?: string;
+  /** Attempt identity associated with the currently recorded Job/result marker. */
+  attemptId?: string;
+  /** Result JSON for the current attempt; retries replace this so an older marker cannot close a new Job. */
+  resultFile?: string;
   startedAt?: string;
   endedAt?: string;
   /** 설치(install) 단계에 쓴 초. */
@@ -61,8 +67,14 @@ function shardOf(value: unknown): GateShard | null {
   const waitReason = str(raw.waitReason);
   const plannedMin = num(raw.plannedMin);
   const host = str(raw.host, 120);
+  const job = str(raw.job, 120);
+  const attemptId = str(raw.attemptId, 120);
+  const resultFile = str(raw.resultFile, 200);
   return {
     id, state,
+    ...(job ? { job } : {}),
+    ...(attemptId ? { attemptId } : {}),
+    ...(resultFile ? { resultFile } : {}),
     ...(startedAt ? { startedAt } : {}), ...(endedAt ? { endedAt } : {}),
     ...(installSec !== undefined ? { installSec } : {}), ...(rc !== undefined ? { rc } : {}),
     ...(waitReason ? { waitReason } : {}), ...(plannedMin !== undefined ? { plannedMin } : {}),
@@ -70,6 +82,55 @@ function shardOf(value: unknown): GateShard | null {
   };
 }
 
+export type GateJobTerminal = 'complete' | 'failed';
+
+/** Forget the prior child Job before a shard descends into a retry/split attempt. */
+export function beginGateShardAttempt(shard: GateShard, now = new Date()): GateShard {
+  const next: GateShard = { ...shard, state: 'retry', startedAt: now.toISOString() };
+  delete next.endedAt;
+  delete next.waitReason;
+  delete next.host;
+  delete next.job;
+  delete next.resultFile;
+  delete next.attemptId;
+  return next;
+}
+
+/**
+ * Close each stale running row when its result marker or Kubernetes Job has terminal evidence.
+ * A result marker can close a row even when the Kubernetes status read is unavailable.
+ */
+export function finalizeTerminalGateShards(
+  file: GateShardsFile,
+  terminalJobs: ReadonlyMap<string, GateJobTerminal>,
+  results: ReadonlyMap<string, { completed?: boolean; jobName?: string; attemptId?: string; jobFailed?: boolean; rc?: number | null; reason?: 'timeout' | 'stall' }>,
+  now: Date = new Date(),
+  staleAfterMs = 120_000,
+): GateShardsFile {
+  const active = file.shards.filter((shard) => shard.state === 'running' || shard.state === 'retry');
+  if (!active.length) return file;
+  const at = now.getTime();
+  const ready = active.map((shard) => {
+    const result = results.get(shard.id);
+    const resultTerminal = result?.completed === true && result.jobName === shard.job && result.attemptId === shard.attemptId;
+    const k8sTerminal = shard.job ? terminalJobs.get(shard.job) : undefined;
+    const startedAt = shard.startedAt ? Date.parse(shard.startedAt) : Number.NaN;
+    if (!resultTerminal && !k8sTerminal) return undefined;
+    if (!Number.isFinite(startedAt) || at - startedAt < staleAfterMs) return undefined;
+    return { shard, result, state: resultTerminal
+      ? (result!.reason === 'timeout' ? 'timeout' as const : result!.reason === 'stall' || result!.jobFailed === true ? 'failed' as const : 'done' as const)
+      : k8sTerminal === 'failed' ? 'failed' as const : 'done' as const };
+  });
+  const finalized = ready.filter((entry): entry is NonNullable<typeof entry> => entry !== undefined);
+  if (!finalized.length) return file;
+  const byId = new Map(finalized.map(({ shard, result, state }) => {
+    const current = { ...shard };
+    delete current.waitReason;
+    return [shard.id, { ...current, state, endedAt: now.toISOString(), ...(result && typeof result.rc === 'number' ? { rc: result.rc } : {}) } satisfies GateShard];
+  }));
+  return { ...file, updatedAt: now.toISOString(), shards: file.shards.map((shard) => byId.get(shard.id) ?? shard) };
+}
+
 function verdictOf(value: unknown): GateShardsVerdict | undefined {
   if (!value || typeof value !== 'object') return undefined;
   const raw = value as Record<string, unknown>;