elanous 0.2.35 → 0.2.36

package/src/pty-shell/herdr-prompt.ts

@@ -0,0 +1,266 @@
+// `eln herdr prompt <대상> "<문장>" [--wait] [--timeout MS]` — herdr pane 의 elanous TUI 를 밖에서 깨운다.
+//
+// 왜 herdr `agent prompt` 가 아닌가(10-22 실측 · herdr 소스 v0.9.1·v0.9.5·main 5bd900d 동일):
+//   `src/app/api/agents.rs` 의 prompt·send-keys 는 `terminal.effective_known_agent()`(내장 kind 라벨)와
+//   `runtime_hosts_agent`(전경 프로세스가 그 kind)를 요구한다. «Add Herdr support to your agent» 계약대로
+//   자기 이름(`elanous`)으로 신고한 agent 는 list·get·wait·read·알림은 되지만 prompt 는
+//   `agent_not_ready: … is not an active named agent` 로 늘 거부된다.
+// 그래서 같은 의미를 여기서 낸다:
+//   ① `herdr agent get` — 신고 라벨이 elanous 이고 idle/done 인지(blocked/working/unknown 은 입력 0 으로 거부)
+//   ② `herdr pane run <pane> <문장>` — agent prompt 와 «같은 바이트»: herdr 의 `pane run` 은 pane 의 bracketed-paste
+//      모드를 따라 `ESC[200~문장ESC[201~` ⊕ Enter 를 한 번에 쓴다(격리 세션 실측 · `pane send-text` 는 날 바이트라 쓰지 않는다)
+//   ③ --wait — 제출 뒤 활동 창(5000ms) 안에 working/blocked 를 관측해야 하고(아니면 agent_prompt_stalled),
+//      그 뒤 idle/done/blocked 정착까지 기다린다. 호출자 timeout 이 먼저 끝나면 timeout. herdr agent prompt --wait 의미 그대로.
+// 관측: debug.log('pty.herdr', 'prompt', { target, paneId, accepted, reason, status, ms }) 한 줄.
+// 호출자 둘: CLI `eln herdr prompt`(라벨 elanous 만) ⊕ 우편 깨움 `src/loops/msg-wake.ts`(anyAgent · beforeSubmit 으로 재해석·opt-in·마감 관문).
+// 신고 계약(herdr-agent-report.ts)은 건드리지 않는다 — 이 명령은 그 신고(working/idle)를 «읽기만» 한다.
+
+import { spawn } from 'node:child_process';
+
+import { debug } from '../debug/log.js';
+
+export const HERDR_PROMPT_ACTIVITY_WINDOW_MS = 5000;
+const HERDR_PROMPT_AGENT = 'elanous';
+const CALL_TIMEOUT_MS = 5000;
+const KILL_GRACE_MS = 1500;
+const OUTPUT_CAP = 64 * 1024;
+
+export interface HerdrCliResult {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** herdr CLI 한 번. timeoutMs 가 Infinity 면 끝없이 기다린다. */
+export type HerdrCliRunner = (argv: readonly string[], timeoutMs: number) => Promise<HerdrCliResult>;
+
+export interface HerdrPromptOpts {
+  readonly target: string;
+  readonly text: string;
+  readonly wait?: boolean;
+  /** 호출자 timeout(제출 포함) — 없으면 정착 대기는 끝이 없다(herdr 와 같다). */
+  readonly timeoutMs?: number;
+  /**
+   * 라벨 확인을 끈다 — 호출자가 대상을 이미 정했을 때(우편 깨움: 자리 폴더 `herdr.pane`). 상태 확인(idle/done 만)과
+   * 제출(`pane run`)은 그대로다. CLI(`eln herdr prompt`)는 켜지 않는다 — herdr 내장 kind 는 herdr agent prompt 몫.
+   */
+  readonly anyAgent?: boolean;
+  /** `agent get` 이 agent_not_found 면 `pane get` 의 agent_status 로 떨어진다(우편 깨움 · #30261 전 경로와 같은 관문).
+   *  10-22 cct 아래 Claude 자리가 agent get 에서 간헐적으로 안 잡혀 깨움 18건이 failed 됐다. */
+  readonly paneFallback?: boolean;
+}
+
+/** 상태 확인을 통과한 대상 — `beforeSubmit` 이 본다. */
+export interface HerdrPromptView {
+  readonly agent: string;
+  readonly status: string;
+  readonly paneId: string;
+}
+
+export interface HerdrPromptDeps {
+  readonly run?: HerdrCliRunner;
+  readonly now?: () => number;
+  readonly log?: (event: string, data: Record<string, unknown>) => void;
+  /** 시험용 — 제출 뒤 활동 관측 창. 기본 5000ms(herdr 의미). */
+  readonly activityWindowMs?: number;
+  readonly env?: NodeJS.ProcessEnv;
+  /**
+   * 상태 확인 «뒤»·제출 «바로 앞» 호출자 관문 — 이유 문자열을 돌려주면 입력 0 으로 그 이유로 끝난다(accepted:false).
+   * 우편 깨움이 대상 재해석·opt-in 재확인·마감을 여기서 본다(조회 사이 바뀐 것에 넣지 않는다).
+   */
+  readonly beforeSubmit?: (view: HerdrPromptView) => string | undefined;
+}
+
+export type HerdrPromptReason =
+  | 'submitted' | 'settled'
+  | 'empty_agent_prompt' | 'not_elanous' | 'agent_blocked' | 'agent_working' | 'agent_unknown'
+  | 'agent_prompt_stalled' | 'timeout'
+  | string; // herdr 오류 코드 그대로(agent_not_found · pane_not_found …)
+
+export interface HerdrPromptResult {
+  readonly ok: boolean;
+  /** 문장이 pane 에 들어갔나(실패여도 true 일 수 있다 — 재제출 전에 화면을 읽어라). */
+  readonly accepted: boolean;
+  readonly reason: HerdrPromptReason;
+  readonly target: string;
+  readonly paneId?: string;
+  readonly agent?: string;
+  readonly status?: string;
+  readonly message?: string;
+  readonly ms: number;
+}
+
+interface AgentView {
+  readonly agent: string;
+  readonly status: string;
+  readonly paneId: string;
+  readonly seq: number;
+}
+
+/** herdr 오류 봉투(stderr 또는 stdout JSON `{"error":{code,message}}`). 없으면 undefined. */
+function herdrError(r: HerdrCliResult): { code: string; message: string } | undefined {
+  for (const text of [r.stderr, r.stdout]) {
+    const t = text.trim();
+    if (!t.startsWith('{')) continue;
+    try {
+      const e = (JSON.parse(t) as { error?: { code?: unknown; message?: unknown } }).error;
+      if (e && typeof e === 'object') {
+        return { code: typeof e.code === 'string' ? e.code : 'herdr_error', message: typeof e.message === 'string' ? e.message : '' };
+      }
+    } catch { /* not an envelope */ }
+  }
+  if (r.code === 0) return undefined;
+  return { code: r.code === null ? 'herdr_killed' : `herdr_rc_${r.code}`, message: r.stderr.trim().slice(0, 240) };
+}
+
+function agentOf(r: HerdrCliResult): AgentView | undefined {
+  try {
+    const a = (JSON.parse(r.stdout.trim()) as { result?: { agent?: Record<string, unknown> } }).result?.agent;
+    if (!a || typeof a.pane_id !== 'string') return undefined;
+    return {
+      agent: typeof a.agent === 'string' ? a.agent : '',
+      status: typeof a.agent_status === 'string' ? a.agent_status : 'unknown',
+      paneId: a.pane_id,
+      seq: typeof a.state_change_seq === 'number' ? a.state_change_seq : 0,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** `pane get` 봉투에서 agent·agent_status — paneFallback 전용(agent get 이 못 찾을 때). seq 는 없다(0). */
+function paneViewOf(r: HerdrCliResult): AgentView | undefined {
+  if (herdrError(r)) return undefined;
+  try {
+    const p = (JSON.parse(r.stdout.trim()) as { result?: { pane?: Record<string, unknown> } }).result?.pane;
+    if (!p || typeof p.pane_id !== 'string' || typeof p.agent_status !== 'string') return undefined;
+    return { agent: typeof p.agent === 'string' ? p.agent : '', status: p.agent_status, paneId: p.pane_id, seq: 0 };
+  } catch {
+    return undefined;
+  }
+}
+
+/** 기본 러너 — HERDR_BIN_PATH(없으면 PATH 의 herdr). HERDR_SOCKET_PATH 등 env 는 그대로 넘긴다. */
+export function defaultHerdrCliRunner(env: NodeJS.ProcessEnv = process.env): HerdrCliRunner {
+  const bin = env.HERDR_BIN_PATH?.trim() || 'herdr';
+  return (argv, timeoutMs) => new Promise<HerdrCliResult>((resolve) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(bin, [...argv], { env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    } catch (error) {
+      resolve({ code: null, stdout: '', stderr: error instanceof Error ? error.message : String(error) });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (r: HerdrCliResult): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve(r);
+    };
+    const timer = Number.isFinite(timeoutMs)
+      ? setTimeout(() => {
+        try { child.kill(); } catch { /* gone */ }
+        finish({ code: null, stdout, stderr: stderr || 'herdr call timed out' });
+      }, Math.max(1, timeoutMs))
+      : undefined;
+    child.stdout?.on('data', (c: Buffer | string) => { if (stdout.length < OUTPUT_CAP) stdout += String(c); });
+    child.stderr?.on('data', (c: Buffer | string) => { if (stderr.length < OUTPUT_CAP) stderr += String(c); });
+    child.on('error', (error) => finish({ code: null, stdout, stderr: error.message }));
+    child.on('close', (code) => finish({ code, stdout, stderr }));
+  });
+}
+
+export async function herdrPrompt(opts: HerdrPromptOpts, deps: HerdrPromptDeps = {}): Promise<HerdrPromptResult> {
+  const now = deps.now ?? Date.now;
+  const run = deps.run ?? defaultHerdrCliRunner(deps.env);
+  const log = deps.log ?? ((event: string, data: Record<string, unknown>) => debug.log('pty.herdr', event, data));
+  const windowMs = deps.activityWindowMs ?? HERDR_PROMPT_ACTIVITY_WINDOW_MS;
+  const start = now();
+  const deadline = opts.timeoutMs !== undefined ? start + opts.timeoutMs : undefined;
+  const remaining = (): number => (deadline === undefined ? Number.POSITIVE_INFINITY : Math.max(0, deadline - now()));
+  const callCap = (): number => Math.min(CALL_TIMEOUT_MS, Math.max(1, remaining()));
+
+  let view: AgentView | undefined;
+  const done = (ok: boolean, accepted: boolean, reason: HerdrPromptReason, message?: string): HerdrPromptResult => {
+    const result: HerdrPromptResult = {
+      ok, accepted, reason, target: opts.target,
+      ...(view ? { paneId: view.paneId, agent: view.agent, status: view.status } : {}),
+      ...(message ? { message } : {}),
+      ms: Math.max(0, Math.round(now() - start)),
+    };
+    log('prompt', { target: opts.target, paneId: view?.paneId, accepted, reason, status: view?.status, ms: result.ms });
+    return result;
+  };
+
+  if (opts.text.length === 0) return done(false, false, 'empty_agent_prompt', 'prompt text must not be empty');
+
+  // ① 대상 확인
+  const got = await run(['agent', 'get', opts.target], callCap());
+  const getErr = herdrError(got);
+  if (getErr) {
+    if (!(opts.paneFallback && getErr.code === 'agent_not_found')) return done(false, false, getErr.code, getErr.message);
+    const pane = paneViewOf(await run(['pane', 'get', opts.target], callCap()));
+    if (!pane) return done(false, false, getErr.code, getErr.message);
+    log('prompt-pane-fallback', { target: opts.target, paneId: pane.paneId, agent: pane.agent, status: pane.status });
+    view = pane;
+  } else view = agentOf(got);
+  if (!view) return done(false, false, 'unparseable_agent_get');
+  if (!opts.anyAgent && view.agent !== HERDR_PROMPT_AGENT) {
+    return done(false, false, 'not_elanous', `agent label ${view.agent || '(none)'} — use herdr agent prompt for herdr-supported agents`);
+  }
+  if (view.status === 'blocked') return done(false, false, 'agent_blocked', 'agent is blocked and requires interactive input');
+  if (view.status === 'working') return done(false, false, 'agent_working', 'agent is working — wait for idle first');
+  if (view.status !== 'idle' && view.status !== 'done') return done(false, false, 'agent_unknown', `agent status ${view.status}`);
+  const seq0 = view.seq;
+  const paneId = view.paneId;
+  const veto = deps.beforeSubmit?.({ agent: view.agent, status: view.status, paneId });
+  if (veto !== undefined) return done(false, false, veto);
+
+  // ② 제출 — agent prompt 와 같은 bracketed text ⊕ Enter 한 번
+  const sent = await run(['pane', 'run', paneId, opts.text], callCap());
+  const sendErr = herdrError(sent);
+  if (sendErr) return done(false, false, sendErr.code, sendErr.message);
+  if (!opts.wait) return done(true, true, 'submitted');
+
+  const refresh = async (): Promise<AgentView | undefined> => {
+    const r = await run(['agent', 'get', paneId], CALL_TIMEOUT_MS);
+    const v = herdrError(r) ? undefined : agentOf(r);
+    if (v) view = v;
+    return v;
+  };
+  const settledStatus = (s: string): boolean => s === 'idle' || s === 'done' || s === 'blocked';
+
+  // ③ 활동 관측(working/blocked) — 창 안에 없으면 stalled, 호출자 timeout 이 먼저면 timeout
+  const win = Math.min(windowMs, remaining());
+  const activity = await run(['agent', 'wait', paneId, '--until', 'working', '--until', 'blocked', '--timeout', String(Math.max(1, Math.floor(win)))], win + KILL_GRACE_MS);
+  const actErr = herdrError(activity);
+  if (actErr) {
+    const v = await refresh();
+    // wait 를 걸기 전에 턴이 이미 돌고 끝났다 — seq 가 움직였고 정착 상태면 성공이다.
+    if (v && v.seq > seq0 && settledStatus(v.status)) return done(true, true, 'settled');
+    if (!(v && v.seq > seq0 && v.status === 'working')) {
+      if (actErr.code !== 'timeout') return done(false, true, actErr.code, actErr.message);
+      return done(false, true, remaining() <= 0 ? 'timeout' : 'agent_prompt_stalled', 'no working/blocked activity observed after submission');
+    }
+  } else {
+    const v = agentOf(activity);
+    if (v) view = v;
+    if (v?.status === 'blocked') return done(true, true, 'settled');
+  }
+
+  // ④ 정착(idle/done/blocked)까지
+  const rem = remaining();
+  const settleArgs = ['agent', 'wait', paneId, ...(Number.isFinite(rem) ? ['--timeout', String(Math.max(1, Math.floor(rem)))] : [])];
+  const settled = await run(settleArgs, Number.isFinite(rem) ? rem + KILL_GRACE_MS : Number.POSITIVE_INFINITY);
+  const setErr = herdrError(settled);
+  if (setErr) {
+    await refresh();
+    return done(false, true, setErr.code, setErr.message);
+  }
+  const v = agentOf(settled);
+  if (v) view = v;
+  return done(true, true, 'settled');
+}

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-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'));
+}