elanous 0.2.34 → 0.2.36

package/src/pty-shell/pty-control-ipc.ts

@@ -1,6 +1,6 @@
 import { Database } from 'bun:sqlite';
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { ptyManifestDbPath, getPtyManifest, markPtyControlled } from './pty-manifest.js';
 import { getHarnessRunId } from '../harness/harness-space.js';
 import { renamePty, type PtyControlTarget } from './registry.js';
@@ -48,6 +48,11 @@ export interface PtyControlRequestOptions {
   readonly timeoutMs?: number;
   /** 대상 PTY를 발견한 매니페스트 뿌리. 연합 조회는 이 DB에 제어 요청을 남겨 그 행의 owner가 처리하게 한다. */
   readonly manifestDbPath?: string;
+  /** 요청자 poll 루프의 시계(기본 `Date.now`) — deadline·grace 경계를 재는 유일한 시계다.
+   *  ⛔ 원장 시각(`created_at`/`updated_at`)은 여전히 `Date.now()` 다 — 원장 형식은 이 옵션에 안 흔들린다. */
+  readonly now?: () => number;
+  /** 요청자 poll 루프의 대기(기본 `Bun.sleep`) — 기본값에서 25ms cadence 계약은 그대로다. */
+  readonly sleep?: (ms: number) => Promise<void>;
 }
 
 export interface PtyControlResult {
@@ -144,6 +149,116 @@ function cleanupStale(d: Database): void {
   d.run("DELETE FROM pty_control_requests WHERE created_at < ? AND status = 'processing'", [now - PTY_CONTROL_PROCESSING_STALE_MS]);
 }
 
+// ── TUI-IDLE-PTY-DEEP-IDLE-FU (#29694) — owner 큐 재읽기의 깊은 유휴 감속 ⊕ 첫 요청 즉시 깨움 ──
+//
+// owner 프로세스는 `registry.startPtyControlPoller` 가 **25ms 마다** 부르는 `processPtyControlRequests` 로
+// 제어 큐(같은 SQLite 원장)를 다시 읽는다. 사람이 자리를 비운 채 TUI 가 몇 시간 떠 있으면 그 재읽기가
+// 시간당 14만 번씩 DB 를 두드린다 — 제어가 **10분 넘게** 없었으면 재읽기 간격을 1.5s 로 늦춘다.
+// ⛔ 감속만 넣으면 첫 원격 요청이 최대 1.5s 뒤에야 처리돼 25ms 응답 계약이 깨진다. 그래서 요청자는
+//    큐와 «별도»인 깨어움 표식을 남기고(`signalPtyControlWake`), owner 는 tick 마다 그 파일의 존재만
+//    싸게 확인한다(`consumePtyControlWake`). DB 재읽기보다 훨씬 싸고, 그 tick 안에서 즉시 깬다.
+interface ControlCadenceState {
+  /** 마지막 **제어 요청 처리** 시각 — `markPtyControlled` 와 같은 사건을 앵커로 쓴다. */
+  lastControlAt: number | null;
+  /** 마지막으로 큐를 실제로 **다시 읽은** 시각 — 감속 간격의 기준점. */
+  lastDbReadAt: number | null;
+  /** 이 상태를 마지막으로 관측한 시계 값 — 시계가 뒤로 가면 앵커를 버린다(시계 교체 감지). */
+  lastSeenAt: number | null;
+  observed: 'active' | 'deep-idle' | null;
+}
+
+/** 큐 원장 경로마다 따로 센다 — 원장 경로가 바뀌면(시험용 `setPtyManifestDbPathForTesting`) 이전
+ *  경로의 유휴 앵커가 새 원장에 얹히지 않는다. ⛔ 열쇠는 **읽는 원장과 같은 경로**여야 한다
+ *  (`processPtyControlRequestsOnce` 가 여는 `db()` 와 동일: `ptyManifestDbPath()`). */
+const controlCadence = new Map<string, ControlCadenceState>();
+
+function cadenceState(dbPath: string): ControlCadenceState {
+  const known = controlCadence.get(dbPath);
+  if (known) return known;
+  const fresh: ControlCadenceState = { lastControlAt: null, lastDbReadAt: null, lastSeenAt: null, observed: null };
+  controlCadence.set(dbPath, fresh);
+  return fresh;
+}
+
+/** 재읽기를 늦추기 시작하는 유휴 길이. 「10분+ 유휴 뒤 1.5s」의 앞 절반. */
+const PTY_CONTROL_DEEP_IDLE_AFTER_MS = 10 * 60_000;
+/** 깊은 유휴에서의 재읽기 간격. 요청 wake 는 이 간격을 «기다리지 않는다». */
+const PTY_CONTROL_DEEP_IDLE_POLL_MS = 1_500;
+
+/** 깨어움 표식은 큐와 같은 원장 디렉터리에 둔다 — 요청자와 owner 가 같은 원장(`ptyManifestDbPath`)을
+ *  볼 때 owner 의 tick 이 곧바로 그 자리를 본다. 연합 큐(`manifestDbPath`)로 남의 원장에 요청하면
+ *  표식은 그 원장 자리에 남고 그 owner 는 감속 간격만큼만 늦다(요청 timeout 안쪽 · fail-soft).
+ *  ⭐ 표식은 **owner 별** 파일이다(`control-wake-<ownerPid>`) — 요청자는 이미 `ownerPid` 를 알고,
+ *  같은 `ELANOUS_STATE_DIR` 원장을 공유하는 여러 프로세스의 `startPtyControlPoller` 가 각자 돌아도
+ *  비대상 owner 가 대상 owner 의 표식을 가져가 즉시 깨움(25ms)을 훔치지 못하게 한다. */
+function wakeSignalPath(dbPath: string, ownerPid: number): string {
+  return join(dirname(dbPath), `control-wake-${ownerPid}`);
+}
+
+/** 구형 요청자가 남기던 공유 표식 — 읽기 «호환 경로»로만 유지한다(새 경로는 owner 별 파일만 쓴다). */
+function legacyWakeSignalPath(dbPath: string): string {
+  return join(dirname(dbPath), 'control-wake');
+}
+
+/** 요청자가 대상 owner 의 깨움 표식을 남긴다 — owner «별» 파일(`control-wake-<ownerPid>`). */
+export function signalPtyControlWake(dbPath: string, ownerPid: number): void {
+  try {
+    mkdirSync(dirname(dbPath), { recursive: true });
+    writeFileSync(wakeSignalPath(dbPath, ownerPid), '');
+  } catch { /* fail-soft — 표식이 없으면 감속 간격만큼만 늦다(timeout 안쪽) */ }
+}
+
+/** «자기» `ownerPid` 의 표식이 있으면 지우고 `true` — 요청자는 행을 «넣은 뒤» 그 행의 owner
+ *  표식을 남기므로, 그 owner 의 이 tick 재읽기는 그 행을 반드시 본다. 남의 owner 표식과 구형
+ *  공유 표식은 잔존 호환으로 «읽기만» 한다(비대상 owner 가 이 표식을 지울 수는 없다). */
+function consumePtyControlWake(dbPath: string): boolean {
+  const own = wakeSignalPath(dbPath, process.pid);
+  let woke = false;
+  if (existsSync(own)) {
+    woke = true;
+    try { rmSync(own, { force: true }); } catch { /* 다음 tick 이 다시 지운다 */ }
+  }
+  const legacy = legacyWakeSignalPath(dbPath);
+  if (existsSync(legacy)) {
+    woke = true;
+    try { rmSync(legacy, { force: true }); } catch { /* 다음 tick 이 다시 지운다 */ }
+  }
+  return woke;
+}
+
+function observeControlCadence(state: ControlCadenceState, mode: 'active' | 'deep-idle', idleMs: number): void {
+  if (state.observed === mode) return;
+  state.observed = mode;
+  debug.log('pty.control', 'poll-cadence', { mode, idleMs });
+}
+
+/** 깊은 유휴 감속 gate — `false` 면 이번 tick 은 큐를 **다시 읽지 않는다**.
+ *  ⛔ 첫 tick 은 언제나 읽는다(기동 직후 도착한 요청을 감속 뒤에 두지 않는다).
+ *  ⛔ 감속 시계는 `pollClock`(기본 `Date.now`) 뿐이다 — `now`(takeover TTL 시계)를 섞으면 시험이
+ *     주입한 값이 실제 tick 을 감속시키는 회귀가 난다. */
+function shouldReadControlQueue(dbPath: string, nowMs: number): boolean {
+  const state = cadenceState(dbPath);
+  // 시계가 뒤로 갔다 = 이전 관측과 다른 시계다. 그 앵커로는 유휴를 못 재므로 버리고 다시 센다.
+  if (state.lastSeenAt !== null && nowMs < state.lastSeenAt) {
+    state.lastControlAt = null;
+    state.lastDbReadAt = null;
+    state.observed = null;
+  }
+  state.lastSeenAt = nowMs;
+  const woke = consumePtyControlWake(dbPath);
+  if (state.lastControlAt === null || woke) state.lastControlAt = nowMs;
+  const idleMs = nowMs - state.lastControlAt;
+  const deepIdle = idleMs >= PTY_CONTROL_DEEP_IDLE_AFTER_MS;
+  const sinceReadMs = state.lastDbReadAt === null ? Number.POSITIVE_INFINITY : nowMs - state.lastDbReadAt;
+  if (!woke && deepIdle && sinceReadMs < PTY_CONTROL_DEEP_IDLE_POLL_MS) {
+    observeControlCadence(state, 'deep-idle', idleMs);
+    return false;
+  }
+  state.lastDbReadAt = nowMs;
+  observeControlCadence(state, deepIdle ? 'deep-idle' : 'active', idleMs);
+  return true;
+}
+
 export async function requestRemotePtyControlCapabilities(id: string, options: PtyControlRequestOptions = {}): Promise<PtyControlCapabilitiesResult> {
   const result = await requestRemotePtyControl(id, 'capabilities', undefined, options);
   if (result.status === 'success') {
@@ -161,6 +276,10 @@ export async function requestRemotePtyControl(id: string, action: PtyControlActi
   const options = typeof timeoutOrOptions === 'number' ? { timeoutMs: timeoutOrOptions } : timeoutOrOptions;
   const timeoutMs = typeof payloadOrTimeout === 'number' ? payloadOrTimeout : options.timeoutMs ?? 2_000;
   const actor: PtyWriteActor = options.actor ?? 'human';
+  // 요청자 poll 루프의 시계·대기 — 기본값이면 종전 그대로(`Date.now` ⊕ 25ms `Bun.sleep`)이고,
+  // 시험만 가상 시각으로 deadline·grace 경계와 cadence 를 결정론적으로 민다(벽시계 판별 없음).
+  const pollNow = options.now ?? Date.now;
+  const pollWait = options.sleep ?? ((ms: number): Promise<void> => Bun.sleep(ms));
   const opened = dbAt(options.manifestDbPath);
   const d = opened.database;
   try {
@@ -175,21 +294,24 @@ export async function requestRemotePtyControl(id: string, action: PtyControlActi
     // ⭐ 요청자의 run anchor 를 요청에 실어 보낸다 — 인가는 **owner 가** 자기 PTY 의 run 과 대조해 내린다
     //    (요청자 자기 신고를 그대로 믿지 않는다는 뜻이 아니라, 판정 지점이 자원 소유자라는 뜻).
     d.run(`INSERT INTO pty_control_requests (request_id, pty_id, action, payload_json, actor, requester_run_id, owner_pid, status, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [requestId, id, action, payload ? JSON.stringify(payload) : null, actor, getHarnessRunId(process.env), ownerPid, 'pending', now, now]);
+    // ⭐ 깊은 유휴 감속 중인 owner 를 즉시 깨운다 — 행을 넣은 «뒤» 표식을 남기므로 그 재읽기가 이 행을 본다.
+    //    표식은 그 행의 `ownerPid` «별» 파일이다 — 같은 원장을 공유하는 다른 owner 가 가져가지 못한다.
+    signalPtyControlWake(requestQueuePath(options), ownerPid);
     const readback = (): ControlRow | null => d.query(SELECT_ROW).get(requestId) as ControlRow | null;
     const del = (): void => { d.run('DELETE FROM pty_control_requests WHERE request_id=?', [requestId]); };
-    const deadline = now + timeoutMs;
-    while (Date.now() < deadline) {
+    const deadline = pollNow() + timeoutMs;
+    while (pollNow() < deadline) {
       const row = readback();
       if (row && settled(row.status)) { del(); return resultFrom(row); }
-      await Bun.sleep(25);
+      await pollWait(25);
     }
     if (d.run("DELETE FROM pty_control_requests WHERE request_id=? AND status='pending'", [requestId]).changes > 0) return { status: 'owner-unreachable' };
-    const graceDeadline = Date.now() + 500;
-    while (Date.now() < graceDeadline) {
+    const graceDeadline = pollNow() + 500;
+    while (pollNow() < graceDeadline) {
       const row = readback();
       if (!row) return { status: 'owner-unreachable' };
       if (settled(row.status)) { del(); return resultFrom(row); }
-      await Bun.sleep(25);
+      await pollWait(25);
     }
     const final = readback();
     if (final && settled(final.status)) { del(); return resultFrom(final); }
@@ -245,6 +367,8 @@ let inFlight: Promise<void> | null = null;
 export interface PtyControlProcessOptions {
   readonly now?: () => number;
   readonly takeoverTtlMs?: number;
+  /** 깊은 유휴 감속 계단 **전용** 시계(기본 `Date.now`). `now` 는 takeover TTL 시계라 섞지 않는다. */
+  readonly pollClock?: () => number;
 }
 
 function positiveInteger(value: unknown): number | undefined {
@@ -281,15 +405,28 @@ function reapExpiredTakeovers(d: Database, getHandle: (id: string) => PtyControl
 
 export function processPtyControlRequests(getHandle: (id: string) => PtyControlTarget | undefined, takeover: (id: string, actor: 'human') => boolean, options: PtyControlProcessOptions = {}): Promise<void> {
   if (inFlight) return inFlight;
+  // 깊은 유휴 감속(#29694) — 이 함수는 `pty-shell/registry.ts:startPtyControlPoller` 가 25ms 마다 부른다.
+  //   감속 구간에서는 여기서 «큐를 다시 읽지 않는» 것으로 끝나고, 첫 원격 요청의 표식이 오면 즉시 통과한다.
+  //   ⛔ 감속 열쇠는 아래 `processPtyControlRequestsOnce` 가 실제로 여는 원장(`db()` = `ptyManifestDbPath()`)과
+  //      같은 경로다 — 상태는 한 큐, 읽기는 다른 큐로 갈라지지 않는다.
+  if (!shouldReadControlQueue(ptyManifestDbPath(), (options.pollClock ?? Date.now)())) return Promise.resolve();
   inFlight = processPtyControlRequestsOnce(getHandle, takeover, options).finally(() => { inFlight = null; });
   return inFlight;
 }
 
+/** 요청이 실제로 들어간 원장 — 깨어움 표식은 «그 원장의 owner» 가 보는 자리에 남겨야 한다.
+ *  연합 요청(`manifestDbPath`)이면 그 원장 디렉터리, 내 요청이면 내 원장. */
+function requestQueuePath(options: { readonly manifestDbPath?: string }): string {
+  return options.manifestDbPath ?? ptyManifestDbPath();
+}
+
 async function processPtyControlRequestsOnce(getHandle: (id: string) => PtyControlTarget | undefined, takeover: (id: string, actor: 'human') => boolean, options: PtyControlProcessOptions): Promise<void> {
   const d = db();
   const now = options.now ?? Date.now;
   reapExpiredTakeovers(d, getHandle, now(), resolveTakeoverTtlMs(options));
   const rows = d.query(`SELECT ${ROW_COLUMNS} FROM pty_control_requests WHERE owner_pid=? AND status='pending' ORDER BY created_at ASC`).all(process.pid) as ControlRow[];
+  // 제어를 «처리했다» = 유휴 앵커를 지금으로 되감는다(`markPtyControlled` 와 같은 사건).
+  if (rows.length > 0) cadenceState(ptyManifestDbPath()).lastControlAt = (options.pollClock ?? Date.now)();
   for (const row of rows) {
     if (d.run("UPDATE pty_control_requests SET status='processing', updated_at=? WHERE request_id=? AND status='pending'", [Date.now(), row.request_id]).changes === 0) continue;
     let requested: PtyWriteActor | null = null;
@@ -434,6 +571,12 @@ async function processPtyControlRequestsOnce(getHandle: (id: string) => PtyContr
 
 export function resetPtyControlIpcForTesting(): void {
   database?.close(); database = null;
+  // 깊은 유휴 감속 상태(#29694)도 «같이» 비운다 — 남으면 다음 시험/기동이 감속 구간에서 시작한다.
+  controlCadence.clear();
+  try {
+    rmSync(wakeSignalPath(ptyManifestDbPath(), process.pid), { force: true });
+    rmSync(legacyWakeSignalPath(ptyManifestDbPath()), { force: true });
+  } catch { /* 표식이 없으면 그만 */ }
   // ⛔⭐ 쓰기 출처 맵도 «같이» 비운다 — 별도 export 로만 두면 아무도 안 부르고 테스트 사이에 샌다
   //   (오늘 `index.ts:65 readStdinLine` 이 정확히 그 형태로 죽어 있었다).
   resetExternalWriteProvenanceForTesting();

package/src/pty-shell/pty-manifest.ts

@@ -251,6 +251,13 @@ function recordPtyLifecycle(event: PtyLifecycleEvent, row: PtyManifestRow, now:
       exitCode: row.exitCode,
       startedAt: row.startedAt,
       closedAt: row.closedAt,
+      // 시작·종료·오류·산출을 같은 seatId 한 흐름으로 대조할 수 있게
+      // 매니페스트 행의 자리 정체성과 산출 총량을 원장 이벤트에도 싣는다.
+      ...(row.seat ? { seat: row.seat } : {}),
+      ...(row.purpose ? { purpose: row.purpose } : {}),
+      outputBytesTotal: row.outputBytesTotal,
+      ...(row.lastControlAt === undefined ? {} : { lastControlAt: row.lastControlAt }),
+      ...(row.turnState ? { turnState: row.turnState, turnAt: row.turnAt } : {}),
     },
   });
   if (seq === 0) debug.log('pty.manifest', 'ledger-write-failed', { ptyId: row.id, event });

package/src/pty-shell/pty-special-keys.ts

@@ -30,18 +30,58 @@ function resolveControlKey(normalized: string): string | undefined {
 type PtySpecialKey = keyof typeof PTY_SPECIAL_KEYS;
 type PtySpecialKeyAlias = keyof typeof PTY_SPECIAL_KEY_ALIASES;
 
-export function resolvePtySpecialKey(name: string): string {
+// ── 조합 키 (PTY-KEY-MODIFIERS · 0.2.36 · 2026-10-22) ──────────────────────────────────────
+// `shift+enter` · `alt+enter` · `ctrl+enter` · `ctrl+shift+tab` · `alt+up` … 를 TUI 가 켜 두는 두 프로토콜 중
+// 하나로 보낸다 — 기본 xterm modifyOtherKeys `CSI 27;<mod>;<code>~` · `--kitty` 면 kitty `CSI <code>;<mod>u`.
+// 화살표·home/end 는 `CSI 1;<mod><F>` · delete/pageup/pagedown 은 `CSI <n>;<mod>~`(두 프로토콜 공통).
+// mod = 1 + shift(1) + alt(2) + ctrl(4) — src/tui.ts decodeModifier 와 같은 규약(받는 쪽이 이 값을 그대로 푼다).
+// 수식자 없는 키·`ctrl+<글자>` 는 예전 바이트 그대로(호환).
+export type PtyKeyEncoding = 'xterm' | 'kitty';
+const MODIFIER_BITS: Record<string, number> = { shift: 1, alt: 2, option: 2, ctrl: 4, control: 4 };
+const KEYCODES: Record<string, number> = { enter: 13, tab: 9, esc: 27, escape: 27, space: 32, backspace: 127 };
+const CSI_FINAL: Record<string, string> = { up: 'A', down: 'B', right: 'C', left: 'D', home: 'H', end: 'F' };
+const CSI_TILDE: Record<string, number> = { delete: 3, pageup: 5, pagedown: 6 };
+
+function resolveModifiedKey(normalized: string, encoding: PtyKeyEncoding): string | undefined {
+  if (!normalized.includes('+') || /^(?:ctrl|control)\+[a-z]$/.test(normalized)) return undefined;
+  const parts = normalized.split('+').map((p) => p.trim());
+  // 조합은 «이름 있는 키» 에만 — 한 글자(ctrl+1 · meta+c)·빈 칸(ctrl++c)·모르는 이름은 예전처럼 거부한다.
+  //   표 조회는 자기 속성만(Object.hasOwn) — «constructor+enter» 같은 프로토타입 이름이 새지 않게(r1 must-fix).
+  const key = parts.at(-1) ?? '';
+  const mods = parts.slice(0, -1);
+  if (!key || mods.length === 0 || mods.some((m) => !m || !Object.hasOwn(MODIFIER_BITS, m))) {
+    throw new Error(`unknown PTY special key: ${normalized}; modifiers: shift, alt, ctrl + a named key (enter, tab, esc, space, backspace, up, down, left, right, home, end, delete, pageup, pagedown)`);
+  }
+  let bits = 0;
+  for (const m of mods) bits |= MODIFIER_BITS[m]!;
+  const mod = 1 + bits;
+  if (Object.hasOwn(CSI_FINAL, key)) return `\x1b[1;${mod}${CSI_FINAL[key]}`;
+  if (Object.hasOwn(CSI_TILDE, key)) return `\x1b[${CSI_TILDE[key]};${mod}~`;
+  if (Object.hasOwn(KEYCODES, key)) {
+    const code = KEYCODES[key]!;
+    return encoding === 'kitty' ? `\x1b[${code};${mod}u` : `\x1b[27;${mod};${code}~`;
+  }
+  throw new Error(`unknown PTY special key: ${normalized}; modifiers apply to named keys only (enter, tab, esc, space, backspace, up, down, left, right, home, end, delete, pageup, pagedown)`);
+}
+
+export function resolvePtySpecialKey(name: string, opts: { encoding?: PtyKeyEncoding } = {}): string {
   const normalized = name.trim().toLowerCase();
+  const encoding = opts.encoding ?? 'xterm';
   const controlBytes = resolveControlKey(normalized);
   if (controlBytes) {
     debug.log('pty.special-key', 'resolved', { inputName: name, resolvedName: normalized, control: true });
     return controlBytes;
   }
+  const modified = resolveModifiedKey(normalized, encoding);
+  if (modified !== undefined) {
+    debug.log('pty.special-key', 'resolved', { inputName: name, resolvedName: normalized, modified: true, encoding });
+    return modified;
+  }
   const alias = PTY_SPECIAL_KEY_ALIASES[normalized as PtySpecialKeyAlias];
   const resolvedName = alias ?? normalized;
   const bytes = PTY_SPECIAL_KEYS[resolvedName as PtySpecialKey];
   if (!bytes) {
-    throw new Error(`unknown PTY special key: ${name}; available names: ${[...Object.keys(PTY_SPECIAL_KEYS), ...Object.keys(PTY_SPECIAL_KEY_ALIASES), 'ctrl+a..ctrl+z'].join(', ')}`);
+    throw new Error(`unknown PTY special key: ${name}; available names: ${[...Object.keys(PTY_SPECIAL_KEYS), ...Object.keys(PTY_SPECIAL_KEY_ALIASES), 'ctrl+a..ctrl+z', 'shift|alt|ctrl+<key> (e.g. shift+enter)'].join(', ')}`);
   }
   debug.log('pty.special-key', 'resolved', { inputName: name, resolvedName, alias: alias !== undefined });
   return bytes;

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

@@ -17,14 +17,14 @@ 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,
@@ -321,6 +321,11 @@ export interface TuiRunStateRecorderDeps {
    * `null` 이면 신고하지 않는다.
    */
   readonly herdr?: HerdrAgentReporterLike | null;
+  /**
+   * SIGINT·SIGTERM 기본 죽음에도 herdr 를 반납하는 신호 지킴이의 대상(TUI-HERDR-EXIT-RACE).
+   * 생략 시: 기본 신고기(herdr 미주입)일 때만 실 `process` · 주입 herdr 는 지킴이 0. `null` 이면 안 건다.
+   */
+  readonly signals?: HerdrSignalTarget | null;
 }
 
 interface ActiveRecorder {
@@ -361,7 +366,14 @@ export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRec
   active = recorder;
   writeTurnState(recorder, 'idle');
   if (herdr) { try { herdr.start(); } catch { /* 신고 실패가 녹음기를 깨지 않는다 */ } }
+  // 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 { unguard(); } catch { /* 종료 경로를 깨지 않는다 */ }
     if (herdr) { try { herdr.release(); } catch { /* 종료 경로를 깨지 않는다 */ } }
     if (active === recorder) active = null;
   };

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 } : {}) };
 }