elanous 0.2.36 → 0.2.37

package/src/pty-shell/herdr-agent-report.ts

@@ -9,11 +9,10 @@
 // 마지막 턴 상태를 잠시 뒤 다시 신고하고(새 seq · 더 새 턴이 오면 그만) 이후 턴 신고도 그대로 보낸다.
 //
 // herdr 는 같은 pane·source 에서 «직전보다 큰 seq» 만 받는다(작으면 rc0 인데 무시).
-// 같은 pane 에서 TUI 를 다시 띄워도 신고가 살도록 seq 는 max(직전+1 · 시각 · pane 기록+1) 이다.
-// pane 기록 = 그 pane 에서 마지막으로 낸 seq(기본 tmpdir 파일) — 같은 ms 재기동·시계 역행에도 뒤 프로세스가 앞 프로세스보다 크다.
-// ⛔ 턴 경로는 파일을 안 만진다: 기록은 start 때 한 번 읽고, release(원래 동기인 종료 경로)에서만 쓴다.
+// 같은 pane 에서 TUI 를 다시 띄워도 신고가 살도록 seq 는 max(직전+1 · 시각 · 예약 high-watermark+1) 이다.
+// pane 기록 = 예약한 seq 범위의 high-watermark(기본 tmpdir 파일) — 정상·비정상 재기동에서 뒤 범위를 쓴다.
+// ⛔ 턴 경로는 보통 파일을 안 만진다: 범위가 소진되면 next()가 새 범위를 파일에 예약한다.
 // 기록을 못 읽고 못 쓰면(관측 `seq-store-failed` 한 번) 시각·직전+1 로만 간다.
-// 한계: release 없이 죽은 프로세스의 마지막 seq 는 기록되지 않는다 — 그때 뒤 프로세스는 시각에 기댄다.
 //
 // 실패로 꺼지는 것은 «이후 turn» 뿐이다. release(권한 반납)는 start 실패가 «확인»됐을 때만 건너뛴다.
 // start 의 비동기 신고가 아직 안 끝났으면(결과 모름) 반납을 미루지 않고 바로 동기로 시도한다(관측 `release-start-pending`) —
@@ -27,6 +26,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { debug } from '../debug/log.js';
+import { pruneStaleHerdrAgent } from './herdr-prune-stale.js';
+import { HerdrSequenceLease, type HerdrSeqStore } from './herdr-sequence-lease.js';
+export type { HerdrSeqStore } from './herdr-sequence-lease.js';
 
 /** 턴 값 — tui-run-state 의 PtyTurnState 와 같은 낱말이지만 순환 import 를 피하려 여기 둔다. */
 export type HerdrTurn = 'busy' | 'idle';
@@ -55,10 +57,12 @@ export interface HerdrAgentReporterDeps {
   readonly sessionId?: string;
   /** seq 시작값의 시계(ms). 기본 Date.now. */
   readonly now?: () => number;
-  /** pane 별 마지막 seq 기록. 기본 = tmpdir 파일(`createFileSeqStore`). */
+  /** pane 별 예약 범위 끝 기록. 기본 = tmpdir 파일(`createFileSeqStore`). */
   readonly seqStore?: HerdrSeqStore;
   /** 재신고 타이머 — 기본 setTimeout(unref). 시험이 가짜 시계를 준다. */
   readonly schedule?: (fn: () => void, ms: number) => void;
+  /** Injected runners skip production startup cleanup unless explicitly enabled. */
+  readonly pruneStaleOnStart?: boolean;
 }
 
 const defaultSchedule = (fn: () => void, ms: number): void => {
@@ -66,12 +70,6 @@ const defaultSchedule = (fn: () => void, ms: number): void => {
   (t as unknown as { unref?: () => void }).unref?.();
 };
 
-/** 같은 pane 에서 마지막으로 낸 seq — 프로세스 사이 단조를 잇는다. 실패는 던져도 된다(신고기가 삼킨다). */
-export interface HerdrSeqStore {
-  read(): number | undefined;
-  write(seq: number): void;
-}
-
 export function defaultHerdrSeqDir(): string {
   return join(tmpdir(), 'elanous-herdr-seq');
 }
@@ -277,13 +275,17 @@ export function createHerdrAgentReporter(deps: HerdrAgentReporterDeps = {}): Her
   }
   const run = deps.run ?? defaultHerdrRunner(env);
   const sessionId = deps.sessionId ?? '';
-  return new Reporter(paneId, sessionId, run, log, deps.now ?? Date.now, deps.seqStore ?? createFileSeqStore(paneId), deps.schedule ?? defaultSchedule);
+  return new Reporter(
+    paneId, sessionId, run, log, deps.now ?? Date.now,
+    deps.seqStore ?? createFileSeqStore(paneId), deps.schedule ?? defaultSchedule,
+    deps.pruneStaleOnStart ?? deps.run === undefined,
+  );
 }
 
 type IssueResult = boolean | Promise<boolean>;
 
 class Reporter implements HerdrAgentReporterLike {
-  private seq = 0;
+  private readonly sequence: HerdrSequenceLease;
   private disabled = false;
   /**
    * idle 신고(에이전트 등록)의 상태: none → (pending →) ok | failed.
@@ -291,8 +293,6 @@ class Reporter implements HerdrAgentReporterLike {
    */
   private startState: 'none' | 'pending' | 'ok' | 'failed' = 'none';
   private released = false;
-  /** start 때 한 번 읽은 pane 기록(턴 경로는 파일을 안 만진다). */
-  private storedSeq: number | undefined;
   /** idle 신고(비동기 포함)가 실패했다 — 등록된 적이 없으니 반납할 것이 없다. */
   private idleFailed = false;
   private seqStoreFailed = false;
@@ -313,9 +313,12 @@ class Reporter implements HerdrAgentReporterLike {
     private readonly run: HerdrRunner,
     private readonly log: (event: string, data: Record<string, unknown>) => void,
     private readonly now: () => number,
-    private readonly seqStore: HerdrSeqStore,
+    seqStore: HerdrSeqStore,
     private readonly schedule: (fn: () => void, ms: number) => void,
-  ) {}
+    private readonly pruneStaleOnStart: boolean,
+  ) {
+    this.sequence = new HerdrSequenceLease(seqStore, now, (error) => this.seqStoreFail(error));
+  }
 
   /** 마지막으로 요청된 턴 상태와 그 세대 — 재신고는 세대가 그대로일 때만(더 새 턴이 오면 그만). */
   private lastTurn: HerdrTurn | null = null;
@@ -324,7 +327,17 @@ class Reporter implements HerdrAgentReporterLike {
 
   start(): void {
     if (this.startState !== 'none') return;
-    try { this.storedSeq = this.seqStore.read(); } catch (error) { this.seqStoreFail(error); }
+    if (this.pruneStaleOnStart) {
+      const pruneSeq = this.nextSeq();
+      try {
+        const pruned = pruneStaleHerdrAgent(this.paneId, pruneSeq, this.run);
+        this.log(pruned.ok ? 'startup-prune-complete' : 'startup-prune-failed', {
+          seq: pruneSeq, ...(pruned.stderr ? { stderrHead: stderrHead(pruned.stderr) } : {}),
+        });
+      } catch (error) {
+        this.log('startup-prune-failed', { seq: pruneSeq, stderrHead: stderrHead(error instanceof Error ? error.message : String(error)) });
+      }
+    }
     const idleOk = this.issue([
       'pane', 'report-agent',
       '--source', HERDR_SOURCE, '--agent', HERDR_AGENT,
@@ -365,8 +378,6 @@ class Reporter implements HerdrAgentReporterLike {
     this.releasedWhilePending = false;
     this.log('release-resend-after-late-start', {});
     const seq = this.nextSeq();
-    // 재반납 seq 도 pane 기록에 남긴다 — 같은 ms 재기동의 첫 seq 가 이 값보다 커야 한다(r7 리뷰 mf).
-    try { this.seqStore.write(this.seq); } catch (error) { this.seqStoreFail(error); }
     void this.runAndJudge([
       'pane', 'release-agent',
       this.paneId,
@@ -418,8 +429,6 @@ class Reporter implements HerdrAgentReporterLike {
       ], true, 'release');
     }
     const seq = this.nextSeq();
-    // pane 기록 쓰기는 여기(동기 종료 경로)뿐이다.
-    try { this.seqStore.write(this.seq); } catch (error) { this.seqStoreFail(error); }
     // ⛔ herdr 0.9.1 `release-agent` 는 PANE_ID 를 옵션 «앞»에 둬야 받는다 — 뒤에 두면
     //   «unknown option: custom:elanous» rc2 로 반납이 영영 안 됐다(10-18 라이브 실측 · report-agent 는 뒤도 받음).
     this.issue([
@@ -457,20 +466,16 @@ class Reporter implements HerdrAgentReporterLike {
     this.log('seq-store-failed', { error: error instanceof Error ? error.message : String(error) });
   }
 
-  /** max(직전+1 · 시각 ms · pane 기록+1) — 같은 ms 재기동에도 뒤 프로세스의 첫 seq 가 앞 프로세스의 마지막보다 크다. */
+  /** Reserved sequence lease advances monotonically across same-millisecond restarts. */
   private nextSeq(): string {
-    const clock = Math.floor(this.now());
-    let next = Number.isFinite(clock) ? Math.max(this.seq + 1, clock) : this.seq + 1;
-    if (this.storedSeq !== undefined) next = Math.max(next, this.storedSeq + 1);
-    this.seq = next;
-    return String(this.seq);
+    return String(this.sequence.next());
   }
 
   /**
    * release 는 꺼진 뒤에도 보낸다(권한 반납 · start 성공 조건은 release() 가 본다).
    * @returns false = 동기 실패(신고기 꺼짐) · true = 동기 성공 · Promise = 비동기 결과(성공이면 true).
    */
-  private issue(argv: string[], sync: boolean, phase: 'start' | 'session' | 'turn' | 'release'): IssueResult {
+  private issue(argv: string[], sync: boolean, phase: 'start' | 'session' | 'turn' | 'release' | 'stale-cleanup'): IssueResult {
     if (this.disabled && phase !== 'release') return false;
     const opts: HerdrRunOpts = { sync, timeoutMs: sync ? SYNC_TIMEOUT_MS : ASYNC_TIMEOUT_MS };
     if (!sync && this.pending) {
@@ -520,7 +525,7 @@ class Reporter implements HerdrAgentReporterLike {
   }
 
   /** 줄 선 비동기 한 건 — 러너 결과(동기·비동기 모두)를 성패로 접는다. */
-  private async runAndJudge(argv: string[], opts: HerdrRunOpts, phase: 'start' | 'session' | 'turn' | 'release'): Promise<boolean> {
+  private async runAndJudge(argv: string[], opts: HerdrRunOpts, phase: 'start' | 'session' | 'turn' | 'release' | 'stale-cleanup'): Promise<boolean> {
     try {
       const r = await this.run(argv, opts);
       if (r.ok) return true;
@@ -532,7 +537,7 @@ class Reporter implements HerdrAgentReporterLike {
     }
   }
 
-  private fail(argv: string[], phase: 'start' | 'session' | 'turn' | 'release', stderr: string | undefined, timedOut = false): void {
+  private fail(argv: string[], phase: 'start' | 'session' | 'turn' | 'release' | 'stale-cleanup', stderr: string | undefined, timedOut = false): void {
     if (phase === 'turn' && timedOut && !this.disabled) {
       this.retryTurnAfterTimeout(argv, stderr);
       return;
@@ -543,6 +548,10 @@ class Reporter implements HerdrAgentReporterLike {
       this.log('release-failed', { stderrHead: stderrHead(stderr) });
       return;
     }
+    if (phase === 'stale-cleanup') {
+      this.log('stale-agent-cleanup-failed', { stderrHead: stderrHead(stderr) });
+      return;
+    }
     if (this.disabled) return;
     this.disabled = true;
     const cmd = argv[1] ?? '';

package/src/pty-shell/herdr-prune-stale.ts

@@ -0,0 +1,17 @@
+import type { HerdrRunResult, HerdrRunner } from './herdr-agent-report.js';
+
+const PRUNE_TIMEOUT_MS = 300;
+
+/** Best-effort removal of a prior custom agent left behind in this pane. */
+export function pruneStaleHerdrAgent(
+  paneId: string,
+  seq: string,
+  run: HerdrRunner,
+): HerdrRunResult {
+  const result = run([
+    'pane', 'release-agent', paneId,
+    '--source', 'custom:elanous', '--agent', 'elanous', '--seq', seq,
+  ], { sync: true, timeoutMs: PRUNE_TIMEOUT_MS });
+  if (result instanceof Promise) throw new Error('startup prune requires a synchronous herdr runner');
+  return result;
+}

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 { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { ptyManifestDbPath, getPtyManifest, markPtyControlled } from './pty-manifest.js';
+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';
@@ -53,6 +55,12 @@ export interface PtyControlRequestOptions {
   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 {
@@ -185,6 +193,27 @@ 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).
@@ -236,7 +265,7 @@ function observeControlCadence(state: ControlCadenceState, mode: 'active' | 'dee
  *  ⛔ 첫 tick 은 언제나 읽는다(기동 직후 도착한 요청을 감속 뒤에 두지 않는다).
  *  ⛔ 감속 시계는 `pollClock`(기본 `Date.now`) 뿐이다 — `now`(takeover TTL 시계)를 섞으면 시험이
  *     주입한 값이 실제 tick 을 감속시키는 회귀가 난다. */
-function shouldReadControlQueue(dbPath: string, nowMs: number): boolean {
+function shouldReadControlQueue(dbPath: string, nowMs: number, limits: ControlCadenceLimits): boolean {
   const state = cadenceState(dbPath);
   // 시계가 뒤로 갔다 = 이전 관측과 다른 시계다. 그 앵커로는 유휴를 못 재므로 버리고 다시 센다.
   if (state.lastSeenAt !== null && nowMs < state.lastSeenAt) {
@@ -248,14 +277,15 @@ function shouldReadControlQueue(dbPath: string, nowMs: number): boolean {
   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 deepIdle = idleMs >= limits.deepIdleAfterMs;
   const sinceReadMs = state.lastDbReadAt === null ? Number.POSITIVE_INFINITY : nowMs - state.lastDbReadAt;
-  if (!woke && deepIdle && sinceReadMs < PTY_CONTROL_DEEP_IDLE_POLL_MS) {
+  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;
 }
 
@@ -271,6 +301,124 @@ 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;
@@ -280,23 +428,48 @@ export async function requestRemotePtyControl(id: string, action: PtyControlActi
   // 시험만 가상 시각으로 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);
+  // ⭐ 사람 타이핑(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(requestQueuePath(options), ownerPid);
+    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 = pollNow() + timeoutMs;
@@ -369,6 +542,8 @@ export interface PtyControlProcessOptions {
   readonly takeoverTtlMs?: number;
   /** 깊은 유휴 감속 계단 **전용** 시계(기본 `Date.now`). `now` 는 takeover TTL 시계라 섞지 않는다. */
   readonly pollClock?: () => number;
+  /** 큐를 실제로 다시 읽을 때마다 1회 — 감속 계측용. 생산 진입점은 넘기지 않는다. */
+  readonly onQueueRead?: () => void;
 }
 
 function positiveInteger(value: unknown): number | undefined {
@@ -409,17 +584,11 @@ export function processPtyControlRequests(getHandle: (id: string) => PtyControlT
   //   감속 구간에서는 여기서 «큐를 다시 읽지 않는» 것으로 끝나고, 첫 원격 요청의 표식이 오면 즉시 통과한다.
   //   ⛔ 감속 열쇠는 아래 `processPtyControlRequestsOnce` 가 실제로 여는 원장(`db()` = `ptyManifestDbPath()`)과
   //      같은 경로다 — 상태는 한 큐, 읽기는 다른 큐로 갈라지지 않는다.
-  if (!shouldReadControlQueue(ptyManifestDbPath(), (options.pollClock ?? Date.now)())) return Promise.resolve();
+  if (!shouldReadControlQueue(ptyManifestDbPath(), (options.pollClock ?? Date.now)(), cadenceLimits(options))) 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;

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;