elanous 0.2.28 → 0.2.29

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/light-rc.ts

@@ -11,6 +11,7 @@ import { runSelfGateCli, type SelfGateCliOptions, type SelfGateCliResult } from
 import { dispatchHeavyCheck, isValidGateHost, type DispatchDeps, type DispatchOptions } from '../self-implement/gate-remote.js';
 import { latestPublishedPreviousVersion } from '../../scripts/release-loop/unattended-release.js';
 import { baseVersion, isReleaseVersion } from '../../scripts/release-loop/release-version.js';
+import { executeTuiNodeCheck, type ExecutedTuiCheck } from '../../scripts/release-loop/tui-node-checks.js';
 
 export const LIGHT_RC_ALWAYS_FILE = 'release/light-rc-always.txt';
 export const LIGHT_RC_DEFAULT_SHARDS = 4;
@@ -31,6 +32,8 @@ export interface LightRcOptions {
   /** Release ledger root for the previous-version lookup (release run's deps.ledgerRoot). */
   ledgerRoot?: string;
   log?: (line: string) => void;
+  /** Rehearsal-only TUI screen check; other light-rc callers keep their current defaults. */
+  rehearsalTui?: boolean;
 }
 
 export interface LightRcResult {
@@ -57,6 +60,7 @@ export interface LightRcResult {
   /** LIGHT-RC-MEASURE ③ — why the gate produced no measurement (e.g. `shard-2`); null = it measured. Carried in the
    *  JSON so the reason reaches the caller even when the remote child's human lines (stderr) do not. */
   unmeasured: string | null;
+  rehearsalTui?: ExecutedTuiCheck;
 }
 
 export interface LightRcDeps {
@@ -68,6 +72,7 @@ export interface LightRcDeps {
   dispatch?: (opts: DispatchOptions, deps?: DispatchDeps) => Promise<number>;
   /** Extra dispatch deps (runner · settings) — tests drive the real dispatch with a fake host. */
   dispatchDeps?: Omit<DispatchDeps, 'write'>;
+  tuiCheck?: typeof executeTuiNodeCheck;
   /** Detached checkout of `sha` for a local run whose tree is not at the measured commit (default: git worktree add
    *  --detach in a temp dir ⊕ bun install); `cleanup` removes it. */
   checkout?: (sha: string, repo: string, log: (line: string) => void) => { dir: string; cleanup: () => void };
@@ -180,13 +185,21 @@ export async function runLightRc(version: string, opts: LightRcOptions = {}, dep
   let alwaysInclude = readList(cwd);
 
   let local: SelfGateCliResult | undefined;
-  const runLocal = () => {
+  let localTui: ExecutedTuiCheck | undefined;
+  const runLocal = async () => {
     // ① The gate scopes by its tree's HEAD — so a tree that is not at the measured commit runs in a detached checkout of it.
     const checkout = worktreeHead === measuredCommit ? undefined : (deps.checkout ?? defaultCheckout)(measuredCommit, cwd, log);
     try {
       const dir = checkout?.dir ?? cwd;
       if (checkout) alwaysInclude = readList(dir);
       local = (deps.runGate ?? runSelfGateCli)(dir, { base, shards, alwaysInclude, includeImporterTests: true });
+      if (opts.rehearsalTui) {
+        const command = async (cmd: string, args: string[], tree: string, limitMs?: number) => {
+          const run = spawnSync(cmd, args, { cwd: tree, encoding: 'utf8', timeout: limitMs });
+          return { rc: run.status ?? 2, output: `${run.stdout ?? ''}\n${run.stderr ?? ''}` };
+        };
+        localTui = await (deps.tuiCheck ?? executeTuiNodeCheck)(measuredCommit, dir, command);
+      }
     } finally { checkout?.cleanup(); }
     for (const line of local.lines) log(line);
     return local.exitCode;
@@ -195,7 +208,7 @@ export async function runLightRc(version: string, opts: LightRcOptions = {}, dep
   const rc = await (deps.dispatch ?? dispatchHeavyCheck)({
     tool: 'self-gate', repo: cwd, installPwa: true, refs: [base], json: true, commit: measuredCommit,
     // The host re-runs this command with --local (and ELANOUS_GATE_REMOTE_CHILD=1), so it never recurses.
-    remoteArgv: (sha) => ['bun', 'bin/elanous.mjs', 'release', 'light-rc', '--version', version, '--base', sha(base), '--head', measuredCommit, '--shards', String(shards), '--local', '--json'],
+    remoteArgv: (sha) => ['bun', 'bin/elanous.mjs', 'release', 'light-rc', '--version', version, '--base', sha(base), '--head', measuredCommit, '--shards', String(shards), '--local', '--json', ...(opts.rehearsalTui ? ['--rehearsal-tui'] : [])],
     flags: { remote: opts.local ? undefined : opts.remote ?? true, local: !!opts.local },
     runLocal,
   }, {
@@ -236,11 +249,22 @@ export async function runLightRc(version: string, opts: LightRcOptions = {}, dep
       unmeasured: typeof remote.unmeasured === 'string' && remote.unmeasured
         ? remote.unmeasured
         : typeof remote.introduced === 'number' ? null : LIGHT_RC_REASON_NOT_REPORTED,
+      ...(remote.rehearsalTui ? { rehearsalTui: remote.rehearsalTui } : {}),
     };
   }
   // Unmeasured (null) or unclassified failures are never green; policy-gate findings in the gate output are reported
   // (gate rc), not a regression.
-  result.ok = result.introduced === 0 && result.unclassified === 0;
+  if (opts.rehearsalTui) {
+    if (local) {
+      result.rehearsalTui = localTui ?? { outcome: 'unmeasured', detail: 'local TUI screen result missing' };
+    } else {
+      const tui = result.rehearsalTui;
+      result.rehearsalTui = tui && ['ok', 'fail', 'unmeasured'].includes(tui.outcome) && typeof tui.detail === 'string' && tui.detail.length > 0
+        ? tui : { outcome: 'unmeasured', detail: 'remote TUI screen result missing' };
+    }
+  }
+  result.ok = result.introduced === 0 && result.unclassified === 0 && result.unmeasured === null
+    && (!opts.rehearsalTui || result.rehearsalTui?.outcome === 'ok');
   debug.log('release.light-rc', 'done', { version, base, measuredCommit, worktreeHead, importerTests: result.importerTests, introduced: result.introduced, preexisting: result.preexisting, unclassified: result.unclassified, shards, remote: result.remote, unmeasured: result.unmeasured });
   return result;
 }
@@ -250,5 +274,6 @@ export function formatLightRc(result: LightRcResult): string[] {
     `${result.ok ? '✅' : '⛔'} light-rc ${result.version} · base ${result.base.slice(0, 12)} · measured ${result.measuredCommit.slice(0, 12)} · ${result.remote ? `host ${result.remote}` : 'local'} · shards ${result.shards}`,
     `  introduced ${result.introduced ?? '못 쟀다'} · preexisting ${result.preexisting ?? '못 쟀다'} · unclassified ${result.unclassified ?? '못 쟀다'} · importer tests ${result.importerTests ?? '못 쟀다'} · always-include ${result.alwaysInclude}${result.alwaysIncludeMissing.length ? ` (missing: ${result.alwaysIncludeMissing.join(', ')})` : ''} · gate rc ${result.gateExitCode}`,
     ...(result.unmeasured !== null ? [`  shards: unmeasured (${result.unmeasured})`] : []),
+    ...(result.rehearsalTui ? [`  TUI screens: ${result.rehearsalTui.outcome} (${result.rehearsalTui.detail})`] : []),
   ];
 }

package/src/release-loop/rehearsal.ts

@@ -290,7 +290,7 @@ export async function runRehearsalTick(opts: RehearsalOptions = {}, deps: Rehear
             stamp.sha = gitResult(git, ['rev-parse', 'HEAD'], checkout);
             if (!stamp.sha) throw new Error('git rev-parse HEAD returned no sha');
             const regressionFiles: string[] = [];
-            const result = await (deps.lightRc ?? ((version, cwd) => runLightRc(version, { ledgerRoot: root, head: stamp.sha, log: (line) => {
+            const result = await (deps.lightRc ?? ((version, cwd) => runLightRc(version, { ledgerRoot: root, head: stamp.sha, rehearsalTui: true, log: (line) => {
               for (const entry of line.split(/\r?\n/)) {
                 const file = /^- introduced: (.+?)(?: > |$)/.exec(entry)?.[1];
                 if (file && regressionFiles.length < 3) regressionFiles.push(file);

package/src/render.ts

@@ -572,6 +572,10 @@ function parseAndRenderTable(lines: string[]): string {
  * Render a tool call header like Claude Code:
  * ⏺ ToolName(description)
  */
+export function singleLineToolHeaderText(text: string): string {
+  return text.replace(/[ \t]*(?:\r\n|\r|\n|\u2028|\u2029)[ \t]*/g, ' ↵ ');
+}
+
 export function toolHeader(
   toolName: string,
   description: string,
@@ -585,7 +589,7 @@ export function toolHeader(
     case 'error':   icon = applyColor(circle, 'error'); break;
   }
   const name = chalk.bold(toolName);
-  const desc = description ? chalk.dim(`(${description})`) : '';
+  const desc = description ? chalk.dim(`(${singleLineToolHeaderText(description)})`) : '';
   return `${icon} ${name}${desc}`;
 }
 

package/src/seat-loop/seat-report.ts

@@ -8,6 +8,7 @@ import { effectiveInstanceRoot } from '../instance/resolve.js';
 import { getUserConfig, type SeatLoopConfig } from '../user-config.js';
 import { collectDraftMetrics, collectOverlapMetrics, countSalvagedToday, type DraftMetrics, type OverlapMetrics } from '../self-dev/draft-sweep.js';
 import { queryRunningRuns } from '../self-implement/running-runs.js';
+import { loadRunLedger } from '../self-implement/run-ledger.js';
 import { readTaskAgentCover } from '../cli/tasks-cli.js';
 import { formatTaskAgentCover } from '../task-agent/cover.js';
 import type { TasksCliDeps } from '../cli/tasks-cli.js';
@@ -27,6 +28,10 @@ export type SeatReportDeps = {
   /** DRAFT-NOT-ARCHIVE salvage branches since the KST day start; null = unreadable. */
   salvagedToday?: (dayStart: Date, now: Date) => Promise<number | null>;
   runningRuns?: (runIds: readonly string[]) => { running: number; unknown: number } | null;
+  /** Launched-run 착지 집계; null 이나 예외는 «착지 못 잼»으로 나온다. */
+  landedRuns?: (runIds: readonly string[]) => { landed: number; unread: number } | null;
+  /** 기본 집계의 runId별 읽기 경로를 시험할 때만 교체한다. */
+  loadLedger?: typeof loadRunLedger;
 };
 export type SeatReportResult = { seat: string; date: string; body: string; posted: boolean };
 const repoRoot = resolve(import.meta.dir, '../..');
@@ -173,10 +178,45 @@ export async function seatReport(seat: string, deps: SeatReportDeps = {}): Promi
         : ` · 도는 런 ${counts.running}(불확실 ${counts.unknown})`;
     } catch { runningDetail = ' · 도는 런 못 잼'; }
   }
-  const body = `**[${seat}]** {{TS}} → 보고 ${date}: ${detail.join(' · ') || (classified.length ? 'OP 그림자 판단' : '원장 기록 없음')}${opDetail}${draftDetail}${runningDetail}`;
+  // ⭐ 사다리 ① (#25210 «도는 런» 옆): 발사된 runId 각각의 run 원장을 읽어 착지 수를 센다.
+  //   'merged' 사건이 있으면 착지 · 원장이 null(로컬에 없음 — Pod 런 등)이면 «원장 없음»으로 따로 센다.
+  let landedDetail = '';
+  let landed: number | null = 0;
+  let landedUnread: number | null = 0;
+  if (runIds.length) {
+    try {
+      const counts = (deps.landedRuns ?? ((ids: readonly string[]) => {
+        let landedCount = 0;
+        let unreadCount = 0;
+        let unreadable = false;
+        for (const runId of ids) {
+          try {
+            const ledger = (deps.loadLedger ?? loadRunLedger)(runId);
+            if (ledger === null) unreadCount += 1;
+            else if (ledger.some((entry) => entry.event === 'merged')) landedCount += 1;
+          } catch { unreadable = true; }
+        }
+        return unreadable ? null : { landed: landedCount, unread: unreadCount };
+      }))(runIds);
+      if (counts === null) {
+        landed = null;
+        landedUnread = null;
+        landedDetail = ' · 착지 못 잼';
+      } else {
+        landed = counts.landed;
+        landedUnread = counts.unread;
+        landedDetail = ` · 착지 ${counts.landed}(원장 없음 ${counts.unread})`;
+      }
+    } catch {
+      landed = null;
+      landedUnread = null;
+      landedDetail = ' · 착지 못 잼';
+    }
+  }
+  const body = `**[${seat}]** {{TS}} → 보고 ${date}: ${detail.join(' · ') || (classified.length ? 'OP 그림자 판단' : '원장 기록 없음')}${opDetail}${draftDetail}${runningDetail}${landedDetail}`;
   const pr = (deps.config ?? getUserConfig().loops?.seat)?.reportPr;
   const posted = deps.post === true && pr !== undefined;
   if (posted) await (deps.send ?? ((text, id, number) => defaultSend(text, id, number, deps.repo ?? repoRoot)))(body, seat, pr);
-  try { debug.log('seat.loop', 'reported', { seat, date, entries: entries.length, posted }); } catch { /* observation is fail-soft */ }
+  try { debug.log('seat.loop', 'reported', { seat, date, entries: entries.length, posted, landed, landedUnread }); } catch { /* observation is fail-soft */ }
   return { seat, date, body, posted };
 }

package/src/self-dev/run-supervisor.ts

@@ -11,6 +11,7 @@ import { sweepFrozenMerges } from '../self-implement/frozen-merges.js';
 import { routeSupervisorVerdict } from './supervisor-verdict-edges.js';
 import { recordTaskAgentShadowMove, runCardFor, type TaskAgentShadowInput } from '../task-agent/shadow.js';
 import { cardPrNumber, taskAgentStatePath } from '../task-agent/task-hand.js';
+import { classifyMustFixRound, inferMustFixEvidence, type MustFixRoundClassification, type MustFixRoundObservation } from '../self-implement/review-mustfix-class.js';
 
 export interface SupervisorRound {
   round: number;
@@ -46,6 +47,8 @@ export interface SupervisorRound {
    * streak pairs rounds by this key. Omitted on older history — the guard then pairs by taskId as before.
    */
   noPrFeatureKeys?: string[];
+  /** REVIEW-MUSTFIX-CLASSIFY — that round's observed must-fix items; pairs the next round's classification. */
+  mustFix?: MustFixRoundObservation;
 }
 
 /** Failed without a PR — a result that carries either a PR number or a PR URL has one (fixtures and older producers set only one). */
@@ -116,6 +119,10 @@ export interface SupervisorDecision {
   deliverableUnmeasured: boolean;
   deliverableMergeCompleteness: 'unmeasured' | 'complete' | 'incomplete';
   reviewMustFixTrend: ReviewRework['trend'];
+  /** REVIEW-MUSTFIX-CLASSIFY — this round's leading must-fix class (② › ③ observed › ①); omitted when unmeasured (지금 동작 그대로). */
+  mustFix?: MustFixRoundClassification;
+  /** REVIEW-MUSTFIX-CLASSIFY — every oscillating task's measured class, so a mixed round keeps each task's decision. */
+  mustFixByTask?: Record<string, MustFixRoundClassification>;
   oscillation?: { taskIds: string[]; helper: 'review-oscillation'; signature: string; repairGoals?: Record<string, string>; heldTaskIds?: string[] };
   pendingDecision?: 'attempt-care-escalation';
 }
@@ -234,6 +241,41 @@ export function aggregateReviewTrend(results: readonly SelfDevJobResult[]): Revi
   return severity[Math.max(...trends.map((trend) => severity.indexOf(trend)))];
 }
 
+/**
+ * REVIEW-MUSTFIX-CLASSIFY — this round's must-fix observation from the results' verbatim `reviewMustFix`.
+ * Each item carries its `taskId` so the next round pairs per task (one task's recurrence never holds another).
+ */
+function mustFixFromResults(results: readonly SupervisorJobResult[]): MustFixRoundObservation {
+  const items = results.flatMap((result) => (result.reviewMustFix ?? []).map((text) => {
+    const evidence = inferMustFixEvidence(text);
+    return { text, taskId: result.taskId, ...(evidence === undefined ? {} : { evidence }) };
+  }));
+  return items.length > 0 ? { items } : {};
+}
+
+/**
+ * REVIEW-MUSTFIX-CLASSIFY — per-task class. `prev` is the preceding round's items of the same task or its repair
+ * lineage (`oscillationRepairOf`), and only when that preceding round authored a repair for it — «수리 뒤 같은 지적»
+ * means a repair ran between the last observation and this one, not «repaired at any time». Lineage items are
+ * re-scoped to this task so the pure pairing accepts them; unrelated tasks never pair.
+ */
+function classifyTaskMustFix(result: SupervisorJobResult, preceding: SupervisorRound | undefined): MustFixRoundClassification {
+  const pairIds = new Set([result.taskId, ...(result.oscillationRepairOf ? [result.oscillationRepairOf] : [])]);
+  const repairedSincePrev = (preceding?.oscillationRepairTaskIds ?? []).some((id) => pairIds.has(id));
+  const prevItems = repairedSincePrev
+    ? (preceding?.mustFix?.items ?? []).filter((item) => item.taskId !== undefined && pairIds.has(item.taskId))
+      .map((item) => ({ ...item, taskId: result.taskId }))
+    : [];
+  return classifyMustFixRound(prevItems.length > 0 ? { items: prevItems } : undefined, mustFixFromResults([result]));
+}
+
+/**
+ * Classes that hold a task out of this round's same-run repair. Only ② acts in this slice; ③ recurring is
+ * observed (decision `mustFix`/`mustFixByTask` · crossReview suggestion) but behaves as ① — acting on it is a
+ * follow-up cell (REVIEW-MUSTFIX-CLASSIFY partial landing).
+ */
+const MUST_FIX_HELD = new Set<MustFixRoundClassification['class']>(['post-land-evidence']);
+
 export function decideNextRun(input: {
   results: readonly SupervisorJobResult[];
   history?: readonly SupervisorRound[];
@@ -520,8 +562,27 @@ export function decideNextRun(input: {
         || (entry.oscillationRepairFeatures?.[index] !== undefined && entry.oscillationRepairFeatures[index] === result.feature
           && Object.values(entry.oscillationRepairGoals ?? {}).includes(result.feature))));
     // Per task: a task that already got its one oscillation repair is held for a human; a fresh one may get it.
-    const fresh = oscillating.filter((result) => !isRepaired(result));
-    const held = [...new Set(oscillating.filter(isRepaired).map((result) => result.taskId))];
+    // REVIEW-MUSTFIX-CLASSIFY — 슈퍼바이저는 추이 대신 회차 분류를 먼저 본다(대표 10-12 «노하우가 아니라 로직으로» · 임의 임계 없음).
+    //   ① new-defect — 그대로 수렴(진동 수리 유지).
+    //   ② post-land-evidence — 증거는 착지 뒤에만 난다 ⇒ 같은 런 재수리 0, «그림자 착지 → 관측 → live» 쪼개기 결정.
+    //   ③ recurring — 수리 뒤 같은 지적 ⇒ 이 조각에선 관측만(교차 리뷰 제안을 결정에 싣고 동작은 ① 그대로 · 후속 칸).
+    //   unmeasured — 분류 불가 ⇒ 지금 동작 그대로. 분류는 조각마다 — 한 조각의 분류가 다른 조각의 수리를 끊지 않는다.
+    const taskClasses = new Map(oscillating.map((result) => [result.taskId, classifyTaskMustFix(result, preceding)]));
+    const fresh = oscillating.filter((result) => !isRepaired(result) && !MUST_FIX_HELD.has(taskClasses.get(result.taskId)!.class));
+    const classes = [...taskClasses.values()];
+    // Decision-level class: ② (the only acting class) first, then observed ③, else ①.
+    const mustFixClass = classes.find((c) => c.class === 'post-land-evidence') ?? classes.find((c) => c.class === 'recurring')
+      ?? classes.find((c) => c.class === 'new-defect');
+    // Held = already repaired once, or classified ② — either way it never rides this round's rerun.
+    const classHeld = [...new Set(oscillating.filter((result) => !isRepaired(result)
+      && MUST_FIX_HELD.has(taskClasses.get(result.taskId)!.class)).map((result) => result.taskId))];
+    const held = [...new Set([...oscillating.filter(isRepaired).map((result) => result.taskId), ...classHeld])];
+    const repairedHeld = held.filter((id) => !classHeld.includes(id));
+    // Every task's measured class survives in the decision — a mixed round keeps ② split and the observed ③ cross-review suggestion both.
+    const mustFixByTask: Record<string, MustFixRoundClassification> = Object.fromEntries(
+      [...taskClasses].filter(([, c]) => c.class !== 'unmeasured'));
+    const heldReasons = [...new Set(classes.filter((c) => MUST_FIX_HELD.has(c.class)).map((c) => c.reason))];
+    const heldReasonSuffix = heldReasons.length ? ` · ${heldReasons.join(' · ')}` : '';
     const repairGoals: Record<string, string> = Object.fromEntries(fresh.flatMap((result) => {
       const goal = result.prNumber && result.reviewMustFix?.length
         ? authorRepairGoal({ pr: result.prNumber, category: 'review-oscillation', originalRequest: result.feature,
@@ -551,14 +612,16 @@ export function decideNextRun(input: {
       } : {}),
       action,
       ...(action === 'stop' ? { stopReason: 'review-oscillating' as const } : {}),
+      ...(mustFixClass ? { mustFix: mustFixClass } : {}),
+      ...(Object.keys(mustFixByTask).length ? { mustFixByTask } : {}),
       oscillation: { taskIds, helper: 'review-oscillation', signature, ...(Object.keys(repairGoals).length ? { repairGoals } : {}),
         ...(action === 'add-repair-task' && held.length ? { heldTaskIds: held } : {}) },
       pendingDecision: 'attempt-care-escalation',
       why: fresh.length === 0
-        ? `리뷰 진동 반복 — ${signatureOf(oscillating)} · 사람 결정 필요(같은 전략 재발사 금지)`
+        ? `리뷰 진동 반복 — ${signatureOf(oscillating)} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}`
         : cannotRepair
-          ? `리뷰 진동 — ${signatureOf(oscillating)} · ${input.repairGoalExecution === false ? '이 감독 경로가 수리 골 실행을 선언하지 않았다(미선언 또는 불가)' : '수리 원문/PR 관측 불가'} · 사람 결정 필요(같은 전략 재발사 금지)`
-          : `리뷰 진동 — ${signatureOf(fresh)} · review-oscillation 수리 조각을 한 번 붙인다${input.repairGoalExecution === true ? '' : '(실행 배선 미선언 — 결정 칸만)'}${held.length ? ` · 이미 수리한 조각 ${held.join(', ')} 은 사람 결정 대기` : ''}`,
+          ? `리뷰 진동 — ${signatureOf(oscillating)} · ${input.repairGoalExecution === false ? '이 감독 경로가 수리 골 실행을 선언하지 않았다(미선언 또는 불가)' : '수리 원문/PR 관측 불가'} · 사람 결정 필요(같은 전략 재발사 금지)${heldReasonSuffix}`
+          : `리뷰 진동 — ${signatureOf(fresh)} · review-oscillation 수리 조각을 한 번 붙인다${input.repairGoalExecution === true ? '' : '(실행 배선 미선언 — 결정 칸만)'}${repairedHeld.length ? ` · 이미 수리한 조각 ${repairedHeld.join(', ')} 은 사람 결정 대기` : ''}${classHeld.length ? ` · 분류로 보류한 조각 ${classHeld.join(', ')}` : ''}${heldReasonSuffix}`,
     };
   }
 
@@ -588,6 +651,8 @@ export function appendRound(
   const t = triageRun(results.filter((result) => result.salvage !== 'launched'), undefined, false, undefined, mainSyncRelaunchSpent(history));
   const baseCompleted = countBaseCompleted(results);
   const base = roundBase(results);
+  // REVIEW-MUSTFIX-CLASSIFY — 회차 원장에 관측을 실어 다음 회차 짝으로 쓴다(관측 없는 옛 원장은 그대로).
+  const mustFix = mustFixFromResults(results.filter((result) => result.salvage !== 'launched'));
   const noPrResults = results.filter(failedWithoutPr);
   const noPrTaskIds = noPrResults.map((result) => result.taskId);
   const noPrFeatureKeys = noPrResults.map((result) => noPrStreakKey(result.feature));
@@ -597,6 +662,7 @@ export function appendRound(
     ...(baseCompleted > 0 || base !== undefined ? { baseCompleted, ...(base === undefined ? {} : { base }) } : {}),
     actionable: countActionable(t),
     ...(reviewMustFixTrend === undefined ? {} : { reviewMustFixTrend }),
+    ...((mustFix.items ?? []).length > 0 ? { mustFix } : {}),
     ...(results.some((result) => result.rework?.signature)
       ? { signatures: Object.fromEntries(results.filter((result) => result.rework?.signature).map((result) => [result.taskId, result.rework!.signature])) } : {}),
     ...(decision && decision.action !== 'stop' && decision.relaunchOnMain.length > 0 ? {

package/src/self-dev/shard-aggregate.ts

@@ -16,6 +16,8 @@ export interface GateShardAttempt {
   baselineExitCode: number | null;
   currentSignal?: string | null;
   baselineSignal?: string | null;
+  currentDiagnostic?: string;
+  baselineDiagnostic?: string;
   /** LIGHT-RC-MEASURE — the shard files that exist in the baseline tree, i.e. what the baseline side actually ran.
    *  Absent = every shard file (the old shape). Empty = the baseline side was not run and contributes zero cases. */
   baselineFiles?: readonly string[];