elanous 0.2.35 → 0.2.37

package/src/pty-shell/herdr-sequence-lease.ts

@@ -0,0 +1,60 @@
+export interface HerdrSeqStore {
+  read(): number | undefined;
+  write(seq: number): void;
+}
+
+const DEFAULT_SEQ_WINDOW = 65_536;
+
+/** Reserve future sequence values before reporting so a SIGKILL restart can advance past the dead process. */
+export class HerdrSequenceLease {
+  private seq = 0;
+  private end = 0;
+  private stored: number | undefined;
+  private ready = false;
+  private failed = false;
+
+  constructor(
+    private readonly store: HerdrSeqStore,
+    private readonly now: () => number,
+    private readonly onFailure: (error: unknown) => void,
+    private readonly seqWindow = DEFAULT_SEQ_WINDOW,
+  ) {}
+
+  next(): number {
+    this.initialize();
+    const clock = Math.floor(this.now());
+    let next = Number.isFinite(clock) ? Math.max(this.seq + 1, clock) : this.seq + 1;
+    if (this.stored !== undefined) next = Math.max(next, this.stored + 1);
+    if (next > this.end) this.reserve(next);
+    this.seq = next;
+    return next;
+  }
+
+  private initialize(): void {
+    if (this.ready) return;
+    try {
+      const stored = this.store.read();
+      this.stored = typeof stored === 'number' && Number.isSafeInteger(stored) && stored >= 0 ? stored : undefined;
+    } catch (error) { this.fail(error); }
+    const clock = Math.floor(this.now());
+    this.seq = Number.isFinite(clock) ? Math.max(clock + this.seqWindow, this.stored ?? 0) : (this.stored ?? 0);
+    this.reserve(this.seq);
+    this.ready = true;
+  }
+
+  private reserve(from: number): void {
+    const end = from + this.seqWindow;
+    try { this.store.write(end); } catch (error) { this.fail(error); }
+    this.end = end;
+  }
+
+  private fail(error: unknown): void {
+    if (this.failed) return;
+    this.failed = true;
+    this.onFailure(error);
+  }
+}
+
+export function staleHerdrReleaseArgs(paneId: string, source: string, agent: string, seq: number): string[] {
+  return ['pane', 'release-agent', paneId, '--source', source, '--agent', agent, '--seq', String(seq)];
+}

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

@@ -1,13 +1,15 @@
 import { Database } from 'bun:sqlite';
-import { mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { ptyManifestDbPath, getPtyManifest, markPtyControlled } from './pty-manifest.js';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ptyManifestDbPath, getPtyManifest, markPtyControlled, listPtyManifestRows, listPtyManifestRowsAt } from './pty-manifest.js';
 import { getHarnessRunId } from '../harness/harness-space.js';
 import { renamePty, type PtyControlTarget } from './registry.js';
 import { resizePtyWithOutcome, writePtyWithOutcome, writePtyWithOutcomeDetail } from './pty-write-outcome.js';
 import { resetExternalWriteProvenanceForTesting } from './pty-write-provenance.js';
 import { parsePtyWriteActor, resolveRemoteControlActor, type PtyWriteActor } from './pty-write-arbiter.js';
-import { isPtyAccessMode } from './pty-ref.js';
+import { isPtyAccessMode, resolvePtyRef, type PtyRefReason } from './pty-ref.js';
+import { RemotesStore } from '../cli/remotes.js';
+import { bookmarkToElanousRemote } from '../cli/remote-resolve.js';
 import { debug } from '../debug/log.js';
 import { encodeSgrMouse, mouseModeOffReason, type PtyMouseInput } from './pty-mouse.js';
 import { startPtyRecording, stopPtyRecording } from './pty-recording.js';
@@ -48,6 +50,17 @@ 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>;
+  /** 사람 타이핑 세션 — 있으면 재해석·재캡처 없이 이 «고정값»만 쓴다(`beginPtyHumanTypingSession`). */
+  readonly typingSession?: PtyHumanTypingSession;
+  /** 아직 세션이 없을 때 캡처할 북마크 이름(없으면 remotes.json 의 default · 그것도 없으면 로컬). */
+  readonly bookmarkName?: string;
+  /** 호출자가 이미 캡처해 둔 북마크 핀 — 재조회하지 않는다. */
+  readonly typingBookmark?: PtyTypingBookmarkPin;
 }
 
 export interface PtyControlResult {
@@ -144,6 +157,138 @@ 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;
+
+/** 감속 계단의 두 값과 «계측» 훅 — 생산 기본값은 위 상수 ⊕ env override 다. */
+interface ControlCadenceLimits {
+  readonly deepIdleAfterMs: number;
+  readonly deepIdlePollMs: number;
+  /** 큐를 실제로 다시 읽을 때마다 1회 — 감속 계측용(생산 진입점은 넘기지 않는다). */
+  readonly onQueueRead?: () => void;
+}
+
+/** 생산 폴러는 옵션 없이 호출되므로 env override 뒤 상수 기본값만 사용한다. */
+function resolveCadenceMs(envName: string, fallback: number): number {
+  return positiveInteger(Number(process.env[envName])) ?? fallback;
+}
+
+function cadenceLimits(options: PtyControlProcessOptions): ControlCadenceLimits {
+  return {
+    deepIdleAfterMs: resolveCadenceMs('ELANOUS_PTY_CONTROL_DEEP_IDLE_AFTER_MS', PTY_CONTROL_DEEP_IDLE_AFTER_MS),
+    deepIdlePollMs: resolveCadenceMs('ELANOUS_PTY_CONTROL_DEEP_IDLE_POLL_MS', PTY_CONTROL_DEEP_IDLE_POLL_MS),
+    ...(options.onQueueRead ? { onQueueRead: options.onQueueRead } : {}),
+  };
+}
+
+/** 깨어움 표식은 큐와 같은 원장 디렉터리에 둔다 — 요청자와 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, limits: ControlCadenceLimits): 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 >= limits.deepIdleAfterMs;
+  const sinceReadMs = state.lastDbReadAt === null ? Number.POSITIVE_INFINITY : nowMs - state.lastDbReadAt;
+  if (!woke && deepIdle && sinceReadMs < limits.deepIdlePollMs) {
+    observeControlCadence(state, 'deep-idle', idleMs);
+    return false;
+  }
+  state.lastDbReadAt = nowMs;
+  observeControlCadence(state, deepIdle ? 'deep-idle' : 'active', idleMs);
+  limits.onQueueRead?.();
+  return true;
+}
+
 export async function requestRemotePtyControlCapabilities(id: string, options: PtyControlRequestOptions = {}): Promise<PtyControlCapabilitiesResult> {
   const result = await requestRemotePtyControl(id, 'capabilities', undefined, options);
   if (result.status === 'success') {
@@ -156,40 +301,190 @@ export async function requestRemotePtyControlCapabilities(id: string, options: P
   return { status: 'owner-result', result };
 }
 
+// ── PTY-HUMAN-TYPING-REMOTE (0.2.36 · UX 칸) — 사람 타이핑의 ref 해석·bookmark 캡처는 «한 번» ──
+//
+// `--remote --human` 타이핑은 호출자가 준 ref(alias·nickname)를 그대로 원장에 흘리면 안 된다:
+// 타이핑 도중 nickname 이 바뀌면 같은 입력이 다른 PTY 로 풀리고, 북마크(host·token·url)가 갈라지면
+// «어느 원격에 쓰는가» 자체가 흔들린다. ⇒ 첫 글자를 넣기 前에 한 번 해석·캡처하고 그 값을 세션 전체에
+// 고정한다. 해석이 확정되기 前에는 원장 행을 «쓰지 않는다»(fail-closed).
+//
+// ⛔ 여기서 해석기를 새로 만들지 않는다 — 목록은 `pty-manifest`(listPtyManifestRows/…At),
+//    해석은 `pty-ref`(resolvePtyRef), 북마크는 `cli/remotes`(RemotesStore) 가 정본이다.
+
+/** 사람 타이핑 세션이 고정하는 원격 북마크 신원 — 캡처는 세션 시작 때 한 번뿐이다. */
+export interface PtyTypingBookmarkPin {
+  readonly name: string;
+  readonly host: string;
+  readonly url: string;
+  readonly token?: string;
+}
+
+/** 타이핑 세션의 고정값 — 이 객체가 사는 동안 재해석·재조회가 없다. */
+export interface PtyHumanTypingSession {
+  /** 호출자가 준 ref(그대로 보존 — 원장·로그 대조용). */
+  readonly ref: string;
+  /** 해석된 canonical pty id — 이후 모든 요청이 쓰는 유일한 주소. */
+  readonly ptyId: string;
+  /** 어느 단계로 확정됐나(`exact-id`·`nickname-exact`·`kind`·`id-prefix`·`nickname-substr`). */
+  readonly resolvedBy: PtyRefReason;
+  /** 캡처된 원격 북마크(로컬이면 null). */
+  readonly bookmark: PtyTypingBookmarkPin | null;
+  /** 해석에 쓴 매니페스트 뿌리 — 연합 요청이면 그 원장이다. */
+  readonly manifestDbPath?: string;
+}
+
+export interface PtyHumanTypingOptions {
+  /** 해석에 쓸 매니페스트 뿌리 — 없으면 이 프로세스의 원장(`ptyManifestDbPath`). */
+  readonly manifestDbPath?: string;
+  /** 이미 읽어 둔 핀(호출자가 캡처를 마친 경우) — 재조회하지 않는다. */
+  readonly bookmark?: PtyTypingBookmarkPin;
+  /** 캡처할 북마크 이름. 없으면 default 북마크, 그것도 없으면 로컬(null). */
+  readonly bookmarkName?: string;
+  /** remotes.json 저장소 재정의(시험·연합). */
+  readonly remotes?: RemotesStore;
+}
+
+export type PtyHumanTypingResolution =
+  | { readonly ok: true; readonly session: PtyHumanTypingSession }
+  | {
+    readonly ok: false;
+    readonly status: 'ambiguous-ref' | 'unresolved-ref' | 'unknown-bookmark';
+    /** ambiguous 면 후보 canonical id 들(사람이 고를 수 있게). */
+    readonly candidates: readonly string[];
+  };
+
+type BookmarkCapture = { readonly ok: true; readonly pin: PtyTypingBookmarkPin | null } | { readonly ok: false };
+
+function captureTypingBookmark(options: PtyHumanTypingOptions): BookmarkCapture {
+  if (options.bookmark) return { ok: true, pin: options.bookmark };
+  const wanted = options.bookmarkName?.trim() ?? '';
+  try {
+    const store = options.remotes ?? new RemotesStore();
+    const listed = wanted ? undefined : store.listRemotes().find((item) => item.isDefault);
+    const entry = wanted ? store.getRemote(wanted) : listed?.entry;
+    if (!entry) return wanted ? { ok: false } : { ok: true, pin: null };
+    const token = store.readToken(entry);
+    return {
+      ok: true,
+      pin: {
+        name: wanted || listed?.name || entry.host,
+        host: entry.host,
+        url: bookmarkToElanousRemote(entry),
+        ...(token ? { token } : {}),
+      },
+    };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * ★ 사람 타이핑 세션 시작 — ref(alias·nickname·id)를 canonical id 로 **한 번** 해석하고
+ *   bookmark host/token/URL 을 **한 번** 캡처한다. 해석이 확정되지 않으면 세션을 만들지 않는다.
+ *
+ * 목록은 «한 번의 스냅숏»이다(살아 있는 행만) — 해석 도중 목록이 바뀌어도 이 세션은 흔들리지 않는다.
+ */
+export function beginPtyHumanTypingSession(ref: string, options: PtyHumanTypingOptions = {}): PtyHumanTypingResolution {
+  const items = (options.manifestDbPath ? listPtyManifestRowsAt(options.manifestDbPath) : listPtyManifestRows())
+    .filter((row) => row.alive)
+    .map((row) => ({ id: row.id, kind: row.kind, ...(row.nickname ? { nickname: row.nickname } : {}) }));
+  const resolution = resolvePtyRef(ref, items);
+  if (!resolution.match) {
+    const candidates = resolution.candidates.map((item) => item.id);
+    debug.log('pty.control', 'typing-ref-unresolved', { ref, reason: resolution.reason, candidates });
+    return { ok: false, status: resolution.reason === 'ambiguous' ? 'ambiguous-ref' : 'unresolved-ref', candidates };
+  }
+  const captured = captureTypingBookmark(options);
+  if (!captured.ok) {
+    // ⛔ 명시적으로 부른 북마크를 못 읽었으면 fail-closed. (부르지 않은 default 캡처 실패는 로컬로 떨어진다 — 아래)
+    if (options.bookmarkName?.trim()) {
+      debug.log('pty.control', 'typing-bookmark-unavailable', { ref, bookmark: options.bookmarkName.trim() });
+      return { ok: false, status: 'unknown-bookmark', candidates: [] };
+    }
+    debug.log('pty.control', 'typing-bookmark-skipped', { ref, reason: 'default-bookmark-unreadable' });
+  }
+  const session: PtyHumanTypingSession = {
+    ref,
+    ptyId: resolution.match.id,
+    resolvedBy: resolution.reason,
+    bookmark: captured.ok ? captured.pin : null,
+    ...(options.manifestDbPath ? { manifestDbPath: options.manifestDbPath } : {}),
+  };
+  debug.log('pty.control', 'typing-session-pinned', {
+    ref: session.ref,
+    ptyId: session.ptyId,
+    resolvedBy: session.resolvedBy,
+    bookmark: session.bookmark?.name ?? 'local',
+  });
+  return { ok: true, session };
+}
+
 export async function requestRemotePtyControl(id: string, action: PtyControlAction, payloadOrTimeout?: PtyControlPayload | number, timeoutOrOptions: PtyControlRequestOptions | number = {}): Promise<PtyControlResult> {
   const payload = typeof payloadOrTimeout === 'number' ? undefined : payloadOrTimeout;
   const options = typeof timeoutOrOptions === 'number' ? { timeoutMs: timeoutOrOptions } : timeoutOrOptions;
   const timeoutMs = typeof payloadOrTimeout === 'number' ? payloadOrTimeout : options.timeoutMs ?? 2_000;
   const actor: PtyWriteActor = options.actor ?? 'human';
-  const opened = dbAt(options.manifestDbPath);
+  // 요청자 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));
+  // ⭐ 사람 타이핑(input-text/input-key)은 원장에 «쓰기 前» ref 를 canonical id 로 확정한다.
+  //    확정 전에는 행을 안 쓴다(fail-closed) — 미해석·모호한 ref 가 남의 PTY 에 닿지 않게.
+  const typingAction = action === 'input-text' || action === 'input-key';
+  let session = options.typingSession;
+  let targetId = id;
+  if (typingAction) {
+    if (!session) {
+      const started = beginPtyHumanTypingSession(id, {
+        ...(options.manifestDbPath ? { manifestDbPath: options.manifestDbPath } : {}),
+        ...(options.bookmarkName ? { bookmarkName: options.bookmarkName } : {}),
+        ...(options.typingBookmark ? { bookmark: options.typingBookmark } : {}),
+      });
+      if (!started.ok) {
+        return started.status === 'ambiguous-ref'
+          ? { status: 'denied', reason: 'pty-ref-ambiguous' }
+          : started.status === 'unknown-bookmark'
+            ? { status: 'denied', reason: 'typing-bookmark-unavailable' }
+            : { status: 'unknown-pty' };
+      }
+      session = started.session;
+    }
+    targetId = session.ptyId;
+  }
+  // 세션 핀이 연합 원장을 정했으면 그 원장을 쓴다(재해석·재조회 없음).
+  const queuePath = options.manifestDbPath ?? session?.manifestDbPath;
+  const opened = dbAt(queuePath);
   const d = opened.database;
   try {
     cleanupStale(d);
-    const target = options.manifestDbPath
-      ? d.query('SELECT owner_pid, alive FROM pty_manifest WHERE id=?').get(id) as { owner_pid: number; alive: number } | null
-      : getPtyManifest(id);
+    const target = queuePath
+      ? d.query('SELECT owner_pid, alive FROM pty_manifest WHERE id=?').get(targetId) as { owner_pid: number; alive: number } | null
+      : getPtyManifest(targetId);
     if (!target || !target.alive) return { status: 'unknown-pty' };
     const ownerPid = 'owner_pid' in target ? target.owner_pid : target.ownerPid;
     const requestId = crypto.randomUUID();
     const now = Date.now();
     // ⭐ 요청자의 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]);
+    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, targetId, action, payload ? JSON.stringify(payload) : null, actor, getHarnessRunId(process.env), ownerPid, 'pending', now, now]);
+    // ⭐ 깊은 유휴 감속 중인 owner 를 즉시 깨운다 — 행을 넣은 «뒤» 표식을 남기므로 그 재읽기가 이 행을 본다.
+    //    표식은 그 행의 `ownerPid` «별» 파일이다 — 같은 원장을 공유하는 다른 owner 가 가져가지 못한다.
+    signalPtyControlWake(queuePath ?? ptyManifestDbPath(), 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 +540,10 @@ let inFlight: Promise<void> | null = null;
 export interface PtyControlProcessOptions {
   readonly now?: () => number;
   readonly takeoverTtlMs?: number;
+  /** 깊은 유휴 감속 계단 **전용** 시계(기본 `Date.now`). `now` 는 takeover TTL 시계라 섞지 않는다. */
+  readonly pollClock?: () => number;
+  /** 큐를 실제로 다시 읽을 때마다 1회 — 감속 계측용. 생산 진입점은 넘기지 않는다. */
+  readonly onQueueRead?: () => void;
 }
 
 function positiveInteger(value: unknown): number | undefined {
@@ -281,6 +580,11 @@ 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)(), cadenceLimits(options))) return Promise.resolve();
   inFlight = processPtyControlRequestsOnce(getHandle, takeover, options).finally(() => { inFlight = null; });
   return inFlight;
 }
@@ -290,6 +594,8 @@ async function processPtyControlRequestsOnce(getHandle: (id: string) => PtyContr
   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 +740,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/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;