elanous 0.2.28 → 0.2.31

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

@@ -64,6 +64,8 @@ export interface PtyManifestRow {
   nickname?: string;
   cmd: string;
   workdir?: string;
+  purpose?: string;
+  seat?: string;
   ownerPid: number;
   ptyPid: number;
   livenessSource?: 'pty-pid' | 'owner-pid';
@@ -96,6 +98,22 @@ export interface PtyManifestRow {
   externalToolName?: string;
   closedAt: number;
   codeSha: string;
+  /** TUI 턴 상태 — TUI 가 턴 시작·끝에 스스로 적는다(화면 글자 추정 아님). 없으면 기록 안 하는 행/옛 판. */
+  turnState?: PtyTurnState;
+  turnAt?: number;
+  /** 행 소유 프로세스가 «기동 때» 실은 코드 판 — 트리 HEAD(`codeSha`)와 다른 축이다. */
+  build?: PtyBuildIdentity;
+}
+
+export type PtyTurnState = 'busy' | 'idle';
+export type PtyBuildSource = 'installed' | 'checkout' | 'unknown';
+export interface PtyBuildIdentity {
+  readonly version: string;
+  /** 40자 커밋 — 모르면 ''. */
+  readonly sha: string;
+  readonly source: PtyBuildSource;
+  /** 기동한 코드의 뿌리 — checkout 이면 지금 HEAD 와 비교하는 자리. */
+  readonly codeRoot?: string;
 }
 
 const SNAPSHOT_TAIL_BYTES = 16 * 1024;
@@ -152,6 +170,8 @@ function db(): Database | null {
 
 export function migratePtyManifestSchema(d: Database): void {
   try { d.run('ALTER TABLE pty_manifest ADD COLUMN nickname TEXT'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN purpose TEXT'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN seat TEXT'); } catch { /* already exists */ }
   try { d.run(`ALTER TABLE pty_manifest ADD COLUMN frame TEXT NOT NULL DEFAULT ''`); } catch { /* already exists */ }
   try { d.run('ALTER TABLE pty_manifest ADD COLUMN frame_at INTEGER NOT NULL DEFAULT 0'); } catch { /* already exists */ }
   try { d.run(`ALTER TABLE pty_manifest ADD COLUMN run_id TEXT NOT NULL DEFAULT ''`); } catch { /* already exists */ }
@@ -176,6 +196,12 @@ export function migratePtyManifestSchema(d: Database): void {
   try { d.run('ALTER TABLE pty_manifest ADD COLUMN external_tool_name TEXT'); } catch { /* already exists */ }
   try { d.run('ALTER TABLE pty_manifest ADD COLUMN output_bytes_total INTEGER NOT NULL DEFAULT 0'); } catch { /* already exists */ }
   try { d.run('ALTER TABLE pty_manifest ADD COLUMN last_control_at INTEGER'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN turn_state TEXT'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN turn_at INTEGER'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN build_version TEXT'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN build_sha TEXT'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN build_source TEXT'); } catch { /* already exists */ }
+  try { d.run('ALTER TABLE pty_manifest ADD COLUMN build_code_root TEXT'); } catch { /* already exists */ }
   try { d.run('ALTER TABLE pty_manifest DROP COLUMN chain_depth'); } catch { /* legacy schema has no duplicate column */ }
   try { d.run('UPDATE pty_manifest SET closed_at=updated_at WHERE alive=0 AND closed_at=0'); } catch { /* fail-soft */ }
 }
@@ -236,9 +262,12 @@ export function upsertPtyManifest(row: {
   nickname?: string;
   cmd: string;
   workdir?: string;
+  purpose?: string;
+  seat?: string;
   startedAt: number;
   now: number;
   ptyPid?: number;
+  origin?: { originRoot: string; controller?: string };
   identity?: {
     spaceId?: string;
     parentPtyId?: string;
@@ -258,7 +287,10 @@ export function upsertPtyManifest(row: {
     const chainOrigin = getPtyChainOrigin();
     const registrarNestDepth = process.env.ELANOUS_NEST_DEPTH === undefined ? undefined : getNestDepth();
     const nestDepth = row.identity?.nestDepth ?? registrarNestDepth;
-    const { originRoot, originAgent, originSession, controller } = originObservationFields();
+    const observedOrigin = originObservationFields();
+    const { originRoot, originAgent, originSession, controller } = row.origin
+      ? { originRoot: row.origin.originRoot, originAgent: undefined, originSession: undefined, controller: row.origin.controller }
+      : observedOrigin;
     const terminalOrigin = classifyTerminalOrigin({ originRoot, originAgent, originSession, controller });
     const codeSha = codeShaForWorkdir(row.workdir);
     d.run('BEGIN IMMEDIATE');
@@ -281,15 +313,15 @@ export function upsertPtyManifest(row: {
           : 'process';
       const shouldRecordSpawned = previous === null || previous.alive === 0;
       const values = [
-        row.id, row.kind, row.nickname ?? null, row.cmd, row.workdir ?? null, process.pid, row.ptyPid ?? 0, resolveInstanceName(),
+        row.id, row.kind, row.nickname ?? null, row.cmd, row.workdir ?? null, row.purpose ?? null, row.seat ?? null, process.pid, row.ptyPid ?? 0, resolveInstanceName(),
         runId, runIdSource, spaceId, sessionId, codeSha, parentPtyId, parentPid, parentKind, chainOrigin ?? null, nestDepth ?? null,
         originRoot ?? null, originAgent ?? null, originSession ?? null, manifestController ?? null, terminalOrigin.category, terminalOrigin.reason,
         terminalOrigin.externalToolName ?? null, row.startedAt, 1, null, '', 0, row.now,
       ];
       d.run(
-        `INSERT INTO pty_manifest (id, kind, nickname, cmd, workdir, owner_pid, pty_pid, instance, run_id, run_id_source, space_id, session_id, code_sha, parent_pty_id, parent_pid, parent_kind, chain_origin, nest_depth, origin_root, origin_agent, origin_session, controller, terminal_origin_category, terminal_origin_reason, external_tool_name, started_at, alive, exit_code, snapshot, snapshot_at, updated_at)
+        `INSERT INTO pty_manifest (id, kind, nickname, cmd, workdir, purpose, seat, owner_pid, pty_pid, instance, run_id, run_id_source, space_id, session_id, code_sha, parent_pty_id, parent_pid, parent_kind, chain_origin, nest_depth, origin_root, origin_agent, origin_session, controller, terminal_origin_category, terminal_origin_reason, external_tool_name, started_at, alive, exit_code, snapshot, snapshot_at, updated_at)
          VALUES (${values.map(() => '?').join(', ')})
-         ON CONFLICT(id) DO UPDATE SET kind=excluded.kind, nickname=excluded.nickname, cmd=excluded.cmd, workdir=excluded.workdir,
+         ON CONFLICT(id) DO UPDATE SET kind=excluded.kind, nickname=excluded.nickname, cmd=excluded.cmd, workdir=excluded.workdir, purpose=excluded.purpose, seat=excluded.seat,
            owner_pid=excluded.owner_pid, pty_pid=excluded.pty_pid, instance=excluded.instance,
            run_id=excluded.run_id, run_id_source=excluded.run_id_source, space_id=excluded.space_id, session_id=excluded.session_id, code_sha=excluded.code_sha,
            parent_pty_id=excluded.parent_pty_id, parent_pid=excluded.parent_pid, parent_kind=excluded.parent_kind,
@@ -297,13 +329,16 @@ export function upsertPtyManifest(row: {
            origin_session=excluded.origin_session, controller=excluded.controller, terminal_origin_category=excluded.terminal_origin_category,
            terminal_origin_reason=excluded.terminal_origin_reason, external_tool_name=excluded.external_tool_name,
            started_at=excluded.started_at, alive=1, exit_code=NULL,
-           snapshot='', snapshot_at=0, frame='', frame_at=0, closed_at=0, updated_at=excluded.updated_at`,
+           snapshot='', snapshot_at=0, frame='', frame_at=0, closed_at=0, updated_at=excluded.updated_at,
+           turn_state=NULL, turn_at=NULL, build_version=NULL, build_sha=NULL, build_source=NULL, build_code_root=NULL`,
         values,
       );
       d.run('COMMIT');
       if (shouldRecordSpawned) {
         recordPtyLifecycle('spawned', {
           id: row.id, kind: row.kind, ...(row.nickname ? { nickname: row.nickname } : {}), cmd: row.cmd,
+          ...(row.purpose ? { purpose: row.purpose } : {}),
+          ...(row.seat ? { seat: row.seat } : {}),
           ...(row.workdir ? { workdir: row.workdir } : {}), ownerPid: process.pid, ptyPid: row.ptyPid ?? 0, instance: resolveInstanceName(),
           startedAt: row.startedAt, alive: true, exitCode: null, snapshot: '', snapshotAt: 0, outputBytesTotal: 0, updatedAt: row.now,
           frame: '', frameAt: 0, runId, runIdSource, spaceId, sessionId, parentPtyId, parentPid, parentKind,
@@ -375,6 +410,29 @@ export function updatePtyManifestNickname(id: string, nickname: string | undefin
   } catch { /* fail-soft */ }
 }
 
+/** 턴 상태 기록 — 행이 없거나 db 를 못 열면 false(호출자가 관측을 남긴다). */
+export function updatePtyManifestTurn(id: string, turn: PtyTurnState, at: number): boolean {
+  try {
+    const d = db(); if (!d) return false;
+    return d.run('UPDATE pty_manifest SET turn_state=?, turn_at=? WHERE id=?', [turn, at, id]).changes > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** 기동 판 기록 — 행 등록 직후 한 번. */
+export function updatePtyManifestBuild(id: string, build: PtyBuildIdentity): boolean {
+  try {
+    const d = db(); if (!d) return false;
+    return d.run(
+      'UPDATE pty_manifest SET build_version=?, build_sha=?, build_source=?, build_code_root=? WHERE id=?',
+      [build.version, build.sha, build.source, build.codeRoot ?? null, id],
+    ).changes > 0;
+  } catch {
+    return false;
+  }
+}
+
 export function markPtyControlled(id: string, at: number): void {
   try {
     const d = db(); if (!d) return;
@@ -781,6 +839,8 @@ function mapRow(r: Record<string, unknown>): PtyManifestRow {
     ...(r.nickname ? { nickname: String(r.nickname) } : {}),
     cmd: String(r.cmd),
     ...(r.workdir ? { workdir: String(r.workdir) } : {}),
+    ...(r.purpose ? { purpose: String(r.purpose) } : {}),
+    ...(r.seat ? { seat: String(r.seat) } : {}),
     ownerPid: Number(r.owner_pid),
     ptyPid: Number(r.pty_pid ?? 0),
     ...(r.liveness_source === 'pty-pid' || r.liveness_source === 'owner-pid' ? { livenessSource: r.liveness_source } : {}),
@@ -812,6 +872,18 @@ function mapRow(r: Record<string, unknown>): PtyManifestRow {
     ...(terminalOrigin.externalToolName === undefined ? {} : { externalToolName: terminalOrigin.externalToolName }),
     closedAt: Number(r.closed_at ?? 0),
     codeSha: String(r.code_sha ?? ''),
+    ...(r.turn_state === 'busy' || r.turn_state === 'idle' ? { turnState: r.turn_state, turnAt: Number(r.turn_at ?? 0) } : {}),
+    ...(typeof r.build_sha === 'string' ? { build: mapBuild(r) } : {}),
     updatedAt: Number(r.updated_at),
   };
 }
+
+function mapBuild(r: Record<string, unknown>): PtyBuildIdentity {
+  const source = r.build_source === 'installed' || r.build_source === 'checkout' ? r.build_source : 'unknown';
+  return {
+    version: String(r.build_version ?? ''),
+    sha: String(r.build_sha ?? ''),
+    source,
+    ...(typeof r.build_code_root === 'string' && r.build_code_root ? { codeRoot: r.build_code_root } : {}),
+  };
+}

package/src/pty-shell/registry.ts

@@ -371,6 +371,12 @@ export interface StartOpts {
   kind?: string;
   /** 휴먼 리더블 닉네임 — 고유 id 와 함께 같은 PTY 를 부르는 다른 이름(나중에 goto 로 기억·접근). */
   nickname?: string;
+  /** Explicit origin for a host-owned PTY when the host process has no origin marker. */
+  origin?: { originRoot: string; controller?: string };
+  /** Explicit purpose for a host-owned PTY with no worktree goal. */
+  purpose?: string;
+  /** Seat that owns this PTY; absent for callers without a seat. */
+  seat?: string;
   /** 접근 모드 초기값(관찰 read/인터랙션 write/자율 auto). 기본 'write'(미션 등 헤드리스 자율은 'auto' 지정). */
   accessMode?: PtyAccessMode;
   /** 전환 정책 초기값(전환불가 locked/전환허용 open). 기본 'open'. */
@@ -766,6 +772,9 @@ export function startPty(opts: StartOpts): PtyHandle {
       id, kind: handle.kind, cmd: handle.cmd, ptyPid: adapter.pid,
       ...(handle.nickname ? { nickname: handle.nickname } : {}),
       ...(handle.workdir ? { workdir: handle.workdir } : {}),
+      ...(opts.origin ? { origin: opts.origin } : {}),
+      ...(opts.purpose ? { purpose: opts.purpose } : {}),
+      ...(opts.seat ? { seat: opts.seat } : {}),
       startedAt: handle.startedAt, now: Date.now(),
       identity: {
         ...(childSpaceId === undefined ? {} : { spaceId: childSpaceId }),
@@ -887,8 +896,16 @@ export function listPty(): PtyHandle[] {
 /** 닉네임 부여/변경 — 나중에 goto 로 기억·접근 쉽게. 없는 id 면 false. */
 export function renamePty(id: string, nickname: string): boolean {
   const h = getPty(id);
-  if (!h) return false;
-  h.setNickname(nickname);
+  if (h) {
+    h.setNickname(nickname);
+    return true;
+  }
+  // ⭐ 자식이 아닌 제어 대상(맨 `elanous` TUI 의 `tui:<pid>` 행 등)은 PtyHandle 이 없다 —
+  //    별명은 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());
+  debug.log('pty.rename', 'control-target-renamed', { ptyId: id, nickname: nickname.trim() });
   return true;
 }
 

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

@@ -0,0 +1,253 @@
+// ── TUI 실행 상태 — 턴(busy/idle) ⊕ 기동 판 ⊕ stale 판정 ──
+//
+// 바깥 제어자(`elanous pty state <ref>`)가 «지금 턴 중인가»와 «이 프로세스가 어느 판 코드로 도는가»를
+// 화면 글자 grep 없이 알게 한다(대표 TUI OP 도그푸드 결함 #13).
+//
+// ⛔ 화면 하단 `⌥ HEAD@<sha>` 는 «세션 cwd 트리»의 HEAD 다 — 프로세스가 실은 코드가 아니다.
+//    10-14 실측: 15:19 에 뜬 TUI 가 15:4x 설치 갱신(5c0f98f) 뒤에도 새 판처럼 보였다.
+//    ⇒ 기동 판은 «기동 때 한 번» 잡아 manifest 행에 적고, 비교 대상(설치본 · 체크아웃 HEAD)은 «읽을 때» 잰다.
+//
+// 기록(TUI 쪽): 행 등록 직후 `startTuiRunStateRecorder` 가 판 ⊕ idle 을 적고, 대시보드가 턴 시작·끝에
+//   `reportTuiTurn` 을 부른다. 기록 실패는 `debug.log('pty.tui-state', …)` — 조용히 삼키지 않는다.
+// 판독(CLI 쪽): `describePtyRunState` 가 행 ⊕ 설치본 기록 ⊕ (체크아웃이면) 그 뿌리의 HEAD 로 판정한다.
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { debug } from '../debug/log.js';
+import { runGitCommand } from '../git-fs/runner.js';
+import { codeRevision, packageVersion, readInstallMetadataCommit } from '../version/code-revision.js';
+import { versionedDashboardInstallDir } from '../dashboard/stale-install-check.js';
+import {
+  updatePtyManifestBuild, updatePtyManifestTurn,
+  type PtyBuildIdentity, type PtyManifestRow, type PtyTurnState,
+} from './pty-manifest.js';
+
+const CODE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+// ── 기동 판 ──
+
+export interface RunningBuildDeps {
+  readonly codeRoot?: string;
+  readonly installRoot?: string;
+  readonly versionDirOf?: (codeRoot: string, installRoot?: string) => string | undefined;
+  readonly readInstallCommit?: (metadataPath: string) => string | undefined;
+  /** 체크아웃 HEAD(설치본 판 폴더가 아닐 때만). */
+  readonly revision?: () => string | undefined;
+  readonly version?: () => string;
+}
+
+/** 이 프로세스가 실은 코드의 판. 설치본 판 폴더면 그 폴더의 install.json, 아니면 코드 뿌리의 git HEAD. */
+export function resolveRunningBuild(deps: RunningBuildDeps = {}): PtyBuildIdentity {
+  const codeRoot = deps.codeRoot ?? CODE_ROOT;
+  const version = (deps.version ?? packageVersion)();
+  const versionDir = (deps.versionDirOf ?? versionedDashboardInstallDir)(codeRoot, deps.installRoot);
+  if (versionDir) {
+    // 판 폴더의 install.json 만이 «실은 판»의 증거다 — 못 읽으면 다른 출처로 메우지 않고 모른다로 둔다.
+    const sha = (deps.readInstallCommit ?? readInstallMetadataCommit)(join(versionDir, 'install.json')) ?? '';
+    return { version, sha, source: sha ? 'installed' : 'unknown', codeRoot };
+  }
+  const sha = (deps.revision ?? codeRevision)() ?? '';
+  return { version, sha, source: sha ? 'checkout' : 'unknown', codeRoot };
+}
+
+let bootBuild: PtyBuildIdentity | undefined;
+/** 기동 판 — 처음 부른 순간 한 번 잡고 그대로 둔다(뒤에 트리 HEAD 가 움직여도 «실은 코드»는 그대로다). */
+export function runningBuild(): PtyBuildIdentity {
+  bootBuild ??= resolveRunningBuild();
+  return bootBuild;
+}
+
+// ── 설치본 기록 ──
+
+export interface InstalledRecord {
+  readonly sha?: string;
+  /** install.json `installedAt`(epoch ms) — 못 읽으면 undefined. */
+  readonly installedAt?: number;
+}
+
+export function defaultInstallRoot(): string {
+  return join(homedir(), '.local', 'share', 'elanous');
+}
+
+/** 지금 `current` 가 가리키는 설치본의 commit ⊕ 설치 시각. */
+export function readCurrentInstallRecord(installRoot = defaultInstallRoot()): InstalledRecord {
+  const path = join(installRoot, 'current', 'install.json');
+  const sha = readInstallMetadataCommit(path);
+  let installedAt: number | undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as { installedAt?: unknown };
+    const t = typeof parsed.installedAt === 'string' ? Date.parse(parsed.installedAt) : NaN;
+    if (Number.isFinite(t)) installedAt = t;
+  } catch { /* 설치본 없음 */ }
+  return { ...(sha ? { sha } : {}), ...(installedAt !== undefined ? { installedAt } : {}) };
+}
+
+export function readCheckoutHead(codeRoot: string): string | undefined {
+  try {
+    const r = runGitCommand(codeRoot, ['rev-parse', 'HEAD'], { encoding: 'utf8' });
+    const sha = r.status === 0 ? String(r.stdout).trim() : '';
+    return sha || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ── stale 판정 ──
+
+export type BuildStaleReason =
+  /** 설치본 판으로 떴고 지금 설치본과 같다. */
+  | 'same-as-installed'
+  /** 설치본 판으로 떴는데 그 뒤 설치본이 바뀌었다 — 재기동해야 새 판. */
+  | 'installed-moved'
+  /** 체크아웃에서 떴고 그 뿌리의 HEAD 가 같다. */
+  | 'same-as-checkout'
+  /** 체크아웃에서 떴는데 그 뿌리의 HEAD 가 움직였다. */
+  | 'checkout-moved'
+  /** 판 기록이 없는 옛 행인데 설치본이 그 행보다 늦게 깔렸다(추정 — 설치본으로 떴다면 낡았다). */
+  | 'started-before-install'
+  /** 비교할 값을 못 얻었다 — «안 낡았다»가 아니다. */
+  | 'unknown';
+
+export interface BuildStaleness {
+  /** null = 못 쟀다(⛔ false 로 접지 않는다). */
+  readonly stale: boolean | null;
+  readonly reason: BuildStaleReason;
+}
+
+export function judgeBuildStaleness(input: {
+  readonly build?: PtyBuildIdentity;
+  readonly installed: InstalledRecord;
+  readonly checkoutHead?: string;
+  readonly startedAt?: number;
+}): BuildStaleness {
+  const { build, installed } = input;
+  if (build?.sha && build.source === 'installed') {
+    if (!installed.sha) return { stale: null, reason: 'unknown' };
+    return installed.sha === build.sha ? { stale: false, reason: 'same-as-installed' } : { stale: true, reason: 'installed-moved' };
+  }
+  if (build?.sha && build.source === 'checkout') {
+    if (!input.checkoutHead) return { stale: null, reason: 'unknown' };
+    return input.checkoutHead === build.sha ? { stale: false, reason: 'same-as-checkout' } : { stale: true, reason: 'checkout-moved' };
+  }
+  if (!build && input.startedAt !== undefined && installed.installedAt !== undefined && installed.installedAt > input.startedAt) {
+    return { stale: true, reason: 'started-before-install' };
+  }
+  return { stale: null, reason: 'unknown' };
+}
+
+// ── 판독(CLI) ──
+
+export type PtyTurnView = PtyTurnState | 'unknown';
+
+export interface PtyRunStateView {
+  readonly turn: PtyTurnView;
+  readonly turnAt?: number;
+  readonly build: PtyBuildIdentity | null;
+  readonly installed: string | null;
+  readonly stale: boolean | null;
+  readonly staleReason: BuildStaleReason;
+}
+
+export interface DescribeRunStateDeps {
+  readonly readInstalled?: () => InstalledRecord;
+  readonly readCheckoutHead?: (codeRoot: string) => string | undefined;
+}
+
+/** manifest 행 하나의 턴 ⊕ 판 ⊕ stale. 행이 없거나 죽었으면 턴은 unknown. */
+export function describePtyRunState(
+  row: Pick<PtyManifestRow, 'alive' | 'startedAt' | 'kind' | 'turnState' | 'turnAt' | 'build'> | null,
+  deps: DescribeRunStateDeps = {},
+): PtyRunStateView {
+  let installed: InstalledRecord = {};
+  try { installed = (deps.readInstalled ?? readCurrentInstallRecord)(); } catch { /* unknown */ }
+  const build = row?.build;
+  let checkoutHead: string | undefined;
+  // 판독 예외는 «모른다»(stale=null)로 — 조회 명령 자체를 깨지 않는다.
+  try {
+    if (build?.source === 'checkout' && build.codeRoot) checkoutHead = (deps.readCheckoutHead ?? readCheckoutHead)(build.codeRoot);
+  } catch { checkoutHead = undefined; }
+  // 판 기록 없는 옛 행의 «설치 뒤에 떴나» 추정은 elanous TUI 행에만 건다(셸 PTY 는 판과 무관하다).
+  const staleness = judgeBuildStaleness({
+    ...(build ? { build } : {}),
+    installed,
+    ...(checkoutHead ? { checkoutHead } : {}),
+    ...(row && row.kind === 'tui' ? { startedAt: row.startedAt } : {}),
+  });
+  const turn: PtyTurnView = row?.alive && row.turnState ? row.turnState : 'unknown';
+  return {
+    turn,
+    ...(turn !== 'unknown' && row?.turnAt ? { turnAt: row.turnAt } : {}),
+    build: build ?? null,
+    installed: installed.sha ?? null,
+    stale: staleness.stale,
+    staleReason: staleness.reason,
+  };
+}
+
+export function shortSha(sha: string | null | undefined): string {
+  return sha ? sha.slice(0, 7) : '-';
+}
+
+// ── 기록(TUI) ──
+
+export interface TuiRunStateRecorderDeps {
+  readonly now?: () => number;
+  readonly build?: () => PtyBuildIdentity;
+  readonly writeBuild?: (id: string, build: PtyBuildIdentity) => boolean;
+  readonly writeTurn?: (id: string, turn: PtyTurnState, at: number) => boolean;
+  readonly log?: (event: string, data: Record<string, unknown>) => void;
+}
+
+interface ActiveRecorder {
+  readonly surfaceId: string;
+  readonly now: () => number;
+  readonly writeTurn: (id: string, turn: PtyTurnState, at: number) => boolean;
+  readonly log: (event: string, data: Record<string, unknown>) => void;
+  last?: PtyTurnState;
+}
+
+let active: ActiveRecorder | null = null;
+
+const defaultLog = (event: string, data: Record<string, unknown>): void => { debug.log('pty.tui-state', event, data); };
+
+/** TUI 행 등록 직후 부른다 — 판을 적고 턴을 idle 로 연다. 이후 `reportTuiTurn` 이 이 행에 적는다. */
+export function startTuiRunStateRecorder(surfaceId: string, deps: TuiRunStateRecorderDeps = {}): () => void {
+  const now = deps.now ?? Date.now;
+  const log = deps.log ?? defaultLog;
+  const writeTurn = deps.writeTurn ?? updatePtyManifestTurn;
+  let build: PtyBuildIdentity | undefined;
+  try { build = (deps.build ?? runningBuild)(); } catch (error) {
+    log('build-resolve-failed', { ptyId: surfaceId, error: error instanceof Error ? error.message : String(error) });
+  }
+  if (build) {
+    const ok = (() => { try { return (deps.writeBuild ?? updatePtyManifestBuild)(surfaceId, build); } catch { return false; } })();
+    log(ok ? 'build-recorded' : 'build-write-failed', { ptyId: surfaceId, sha: build.sha, version: build.version, source: build.source });
+  }
+  const recorder: ActiveRecorder = { surfaceId, now, writeTurn, log };
+  active = recorder;
+  writeTurnState(recorder, 'idle');
+  return () => { if (active === recorder) active = null; };
+}
+
+/** 대시보드가 턴 시작(busy)·끝(idle)에 부른다. 녹음기가 없으면(자기보고 꺼짐) 아무것도 안 한다. */
+export function reportTuiTurn(turn: PtyTurnState): void {
+  if (!active || active.last === turn) return;
+  writeTurnState(active, turn);
+}
+
+function writeTurnState(recorder: ActiveRecorder, turn: PtyTurnState): void {
+  const at = recorder.now();
+  let ok = false;
+  try { ok = recorder.writeTurn(recorder.surfaceId, turn, at); } catch { ok = false; }
+  if (ok) recorder.last = turn;
+  // 실패는 관측으로 남긴다 — 바깥 제어자는 그 사이 «unknown/낡은 값»을 본다. 성공은 남기지 않는다(턴마다 두 줄은 소음).
+  else recorder.log('turn-write-failed', { ptyId: recorder.surfaceId, turn, at });
+}
+
+export function resetTuiRunStateForTesting(): void {
+  active = null;
+  bootBuild = undefined;
+}

package/src/release-loop/gate-host-reservation.ts

@@ -0,0 +1,97 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { psProcessStartMs } from '../harness/harness-stop.js';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+
+interface GateHostClaim {
+  token: string;
+  runId: string;
+  hosts: string[];
+  pid: number;
+  pidStartedAt: number | null;
+}
+
+export type GateHostReservation =
+  | { status: 'free' }
+  | { status: 'reserved' | 'unknown'; reason: string; runId?: string };
+
+const hostName = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const claimsDir = (root: string) => join(root, 'release', 'gate-host-reservations');
+
+/** The release graph's pinned child state and the self gate CLI's selected universe resolve through this same entry. */
+export function gateHostReservationRoot(): string { return effectiveInstanceRoot(); }
+
+function claimAlive(claim: GateHostClaim): 'alive' | 'dead' | 'unknown' {
+  try { process.kill(claim.pid, 0); }
+  catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ESRCH' ? 'dead' : 'unknown';
+  }
+  if (claim.pidStartedAt === null) return 'unknown';
+  const current = psProcessStartMs(claim.pid);
+  if (current === null) return 'unknown';
+  return Math.abs(current - claim.pidStartedAt) <= 2_000 ? 'alive' : 'dead';
+}
+
+/** A gate owns its host until its node exits. A crashed owner's claim is removed on the next read. */
+export function reserveReleaseGateHosts(root: string, runId: string, hosts: readonly string[]): () => void {
+  const unique = [...new Set(hosts)];
+  if (!runId || unique.some(host => host !== '*' && !hostName.test(host))) throw new Error('invalid release gate reservation');
+  if (!unique.length) return () => undefined;
+  const dir = claimsDir(root);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const token = randomUUID();
+  const pidStartedAt = psProcessStartMs(process.pid);
+  if (pidStartedAt === null) throw new Error('release gate owner start time unmeasured');
+  const claim: GateHostClaim = { token, runId, hosts: unique, pid: process.pid, pidStartedAt };
+  const path = join(dir, `${token}.json`);
+  const temp = join(dir, `.${token}.tmp`);
+  try {
+    writeFileSync(temp, JSON.stringify(claim) + '\n', { mode: 0o600, flag: 'wx' });
+    renameSync(temp, path);
+  } finally { if (existsSync(temp)) rmSync(temp); }
+  debug.log('release-loop.gate', 'host-reserved', { runId, hosts: unique, pid: process.pid, path });
+  return () => {
+    try {
+      const current = JSON.parse(readFileSync(path, 'utf8')) as Partial<GateHostClaim>;
+      if (current.token === token) rmSync(path);
+      debug.log('release-loop.gate', 'host-released', { runId, hosts: unique, path });
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT')
+        debug.log('release-loop.gate', 'host-release-unmeasured', { runId, path, error: String(error) });
+    }
+  };
+}
+
+/** An unreadable claim is a reservation, never permission to enter a gate host. */
+export function inspectReleaseGateHost(root: string, host: string): GateHostReservation {
+  const dir = claimsDir(root);
+  let names: string[];
+  try { names = readdirSync(dir).filter(name => name.endsWith('.json')); }
+  catch (error) {
+    return { status: 'unknown', reason: `reservation directory unreadable: ${String(error)}` };
+  }
+  for (const name of names) {
+    const path = join(dir, name);
+    let claim: GateHostClaim;
+    try {
+      claim = JSON.parse(readFileSync(path, 'utf8')) as GateHostClaim;
+      if (!claim || !Array.isArray(claim.hosts) || claim.hosts.length === 0
+        || !claim.hosts.every(item => typeof item === 'string' && (item === '*' || hostName.test(item)))
+        || !Number.isSafeInteger(claim.pid) || claim.pid <= 0 || typeof claim.token !== 'string'
+        || typeof claim.runId !== 'string' || !claim.runId
+        || (claim.pidStartedAt !== null && (!Number.isSafeInteger(claim.pidStartedAt)
+          || claim.pidStartedAt <= 0 || claim.pidStartedAt > Date.now()))) throw new Error('invalid claim');
+    } catch (error) { return { status: 'unknown', reason: `reservation unreadable: ${name}: ${String(error)}` }; }
+    const live = claimAlive(claim);
+    if (live === 'dead') {
+      try { rmSync(path); } catch { /* a confirmed dead process cannot still own the host */ }
+      debug.log('release-loop.gate', 'host-claim-reclaimed', { runId: claim.runId, hosts: claim.hosts, path });
+      continue;
+    }
+    if (!claim.hosts.includes(host) && !claim.hosts.includes('*')) continue;
+    return { status: live === 'unknown' ? 'unknown' : 'reserved', reason: `release gate ${claim.runId} holds ${host}`, runId: claim.runId };
+  }
+  return { status: 'free' };
+}

package/src/release-loop/landing-freeze.ts

@@ -36,6 +36,11 @@ export function readLandingFreeze(root = effectiveInstanceRoot(), now = new Date
   return { ...freeze, holdLaunches: freeze.holdLaunches ?? false } as LandingFreeze;
 }
 
+/** Interpret a validated, expiry-aware read without reading the freeze file twice. */
+export function landingFreezeState(freeze: LandingFreeze | null): 'on' | 'off' {
+  return freeze === null ? 'off' : 'on';
+}
+
 export function enableLandingFreeze(opts: { reason?: string; until?: string; by?: string; holdLaunches?: boolean }, root = effectiveInstanceRoot(), now = new Date()): LandingFreeze {
   const until = opts.until === undefined ? null : opts.until;
   if (until !== null && (!/^\d{4}-\d\d-\d\dT\d\d:\d\d(?::\d\d(?:\.\d+)?)?(?:Z|[+-]\d\d:\d\d)$/.test(until) || !Number.isFinite(Date.parse(until)) || Date.parse(until) <= now.getTime())) {