elanous 0.2.27 → 0.2.28

package/scripts/browser-observe-cycle.ts

@@ -4,7 +4,15 @@
 // 기본 MCP 전송은 기존 McpClient 의 initialize + Mcp-Session-Id 수명주기를 탄다.
 // 스케줄러 진입점 배선은 다음 조각의 몫이다. 이 파일은 호출 가능한 함수만 내보낸다.
 
-import { McpClient, McpServerError, type McpHttpFetch } from '../src/mcp/client.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  McpClient,
+  McpConnectionError,
+  McpServerError,
+  type McpHttpFetch,
+} from '../src/mcp/client.js';
+import { getElanousConfigDir } from '../src/elanous-config-dir.js';
 import { debug } from '../src/debug/log.js';
 
 export const ELANOUS_PWA_URL = 'http://127.0.0.1:31415/app';
@@ -21,6 +29,10 @@ export const BROWSER_OBSERVE_OK = 'ok';
 export const BROWSER_OBSERVE_WRONG_SCREEN = 'wrong-screen';
 /** 관측하지 못했다 */
 export const BROWSER_OBSERVE_UNOBSERVED = 'unobserved';
+/** `unobserved` 사유 — 루프백 owner 토큰을 못 읽어 Authorization 헤더를 못 붙였다 */
+export const BROWSER_OBSERVE_REASON_AUTH_MISSING = 'auth-missing';
+/** `unobserved` 사유 — 루프백 owner 토큰을 붙였는데 서버가 401 로 거부했다 */
+export const BROWSER_OBSERVE_REASON_AUTH_REJECTED = 'auth-rejected';
 
 export type BrowserObserveStatus =
   | typeof BROWSER_OBSERVE_OK
@@ -50,6 +62,39 @@ export interface BrowserObserveResult extends BrowserObserveClassification {
   request: BrowserObserveMcpRequest;
 }
 
+/** 루프백 owner 토큰을 어디서 읽는지 — `src/cli/mcp-reload.ts` 의 기존 꼴과 같은 자리다. */
+export function browserObserveTokenPath(): string {
+  return join(getElanousConfigDir(), 'acp-token');
+}
+
+/**
+ * 루프백 ACP 토큰을 **읽기 전용**으로 얻는다(실패는 null).
+ * ⛔ `ensureAuthToken`(src/auth/acp-token.ts) 을 쓰지 않는다 — 그것은 «없으면 만든다».
+ * 이 조각은 새 토큰 생성 0: 파일이 없거나 비면 그대로 auth-missing 이다.
+ */
+export function readBrowserObserveToken(): string | null {
+  const tokenPath = browserObserveTokenPath();
+  try {
+    if (!existsSync(tokenPath)) return null;
+    const token = readFileSync(tokenPath, 'utf8').trim();
+    return token.length > 0 ? token : null;
+  } catch {
+    return null;
+  }
+}
+
+/** MCP POST 전부에 `Authorization: Bearer <token>` 을 얹는 전송 래퍼. */
+export function withBrowserObserveAuthorization(
+  fetchImpl: BrowserObserveHttpFetch,
+  token: string,
+): BrowserObserveHttpFetch {
+  return (url, init) =>
+    fetchImpl(url, {
+      ...init,
+      headers: { ...init.headers, authorization: `Bearer ${token}` },
+    });
+}
+
 export type BrowserObserveMcpCall = (request: BrowserObserveMcpRequest) => Promise<unknown>;
 export type BrowserObserveLog = (category: string, event: string, data?: unknown) => void;
 export type BrowserObserveHttpFetch = McpHttpFetch;
@@ -58,6 +103,8 @@ export interface BrowserObserveDeps {
   mcpCall?: BrowserObserveMcpCall;
   fetch?: BrowserObserveHttpFetch;
   log?: BrowserObserveLog;
+  /** 토큰 획득 주입 자리 — 시험이 파일 시스템 없이 결정성을 얻는다. 생략하면 `readBrowserObserveToken` */
+  readToken?: () => string | null;
 }
 
 /**
@@ -328,6 +375,15 @@ function emit(
 }
 
 function unobservedFromCaught(caught: unknown): BrowserObserveClassification {
+  // 루프백 토큰을 붙였는데 서버가 401 로 거부한 경우 — McpClient 가
+  // McpConnectionError('auth-required') 로 던진다. 긴 오류 문자열 대신 이유 한 칸으로 가른다.
+  if (caught instanceof McpConnectionError && caught.reason === 'auth-required') {
+    return {
+      status: BROWSER_OBSERVE_UNOBSERVED,
+      observedUrl: null,
+      reason: BROWSER_OBSERVE_REASON_AUTH_REJECTED,
+    };
+  }
   if (caught instanceof McpServerError) {
     return {
       status: BROWSER_OBSERVE_UNOBSERVED,
@@ -342,14 +398,32 @@ function unobservedFromCaught(caught: unknown): BrowserObserveClassification {
   };
 }
 
+/** 기본 전송(McpClient) 에 루프백 토큰을 얹는다. 토큰이 없으면 null — 401 이 보장된 호출은 아예 안 한다. */
+function defaultAuthorizedMcpCall(deps: BrowserObserveDeps): BrowserObserveMcpCall | null {
+  const token = deps.readToken ? deps.readToken() : readBrowserObserveToken();
+  if (token === null) return null;
+  const base: BrowserObserveHttpFetch = deps.fetch ?? ((url, init) => fetch(url, init));
+  const authorized = withBrowserObserveAuthorization(base, token);
+  return (request) => callAsideReplViaMcpClient(request, authorized);
+}
+
 /** MCP 로 브라우저에서 값을 가져와 공개 분류 함수에 넘긴다. 의존성 주입으로 실 데몬 없이 검증한다. */
 export async function observeBrowserCycle(
   deps: BrowserObserveDeps = {},
 ): Promise<BrowserObserveResult> {
   if (!deps.log) await ensureBrowserObserveLogSink();
   const log = deps.log ?? defaultLog;
-  const mcpCall = deps.mcpCall ?? ((request) => callAsideReplViaMcpClient(request, deps.fetch));
   const request = buildBrowserObserveMcpRequest();
+  const mcpCall = deps.mcpCall ?? defaultAuthorizedMcpCall(deps);
+  if (mcpCall === null) {
+    const classified: BrowserObserveClassification = {
+      status: BROWSER_OBSERVE_UNOBSERVED,
+      observedUrl: null,
+      reason: BROWSER_OBSERVE_REASON_AUTH_MISSING,
+    };
+    emit(log, classified);
+    return { ...classified, request };
+  }
   try {
     const response = await mcpCall(request);
     const rpcError = jsonRpcErrorMessage(response);

package/scripts/ci-typecheck-changed.ts

@@ -759,7 +759,7 @@ export function exportedLiteralUnionMembersInChanges(
   pathsResult: ChangedPathResult = changedPathPairs(base),
   readBase: GitFileReader = readGitFile,
   readHead = (file: string) => readFileSync(file, 'utf8'),
-  sources?: RepositorySources,
+  sources?: RepositorySources | (() => RepositorySources),
 ): LiteralUnionMemberCheck {
   if (pathsResult.failure) return { additions: [], failure: pathsResult.failure };
   const additions: LiteralUnionAddition[] = [];
@@ -780,7 +780,7 @@ export function exportedLiteralUnionMembersInChanges(
   }
   if (removals.length === 0) return { additions };
   try {
-    return { additions, removals: literalUnionReferencesInSource(removals, changed, sources ?? repositoryTypeScriptSources()) };
+    return { additions, removals: literalUnionReferencesInSource(removals, changed, typeof sources === 'function' ? sources() : sources ?? repositoryTypeScriptSources()) };
   } catch (error: unknown) {
     return { additions, failure: `저장소 리터럴 참조 탐색 실패: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -873,6 +873,7 @@ export type GateIo = {
   literalUnionMembers?: (changed: ReadonlySet<string>, base: string) => LiteralUnionMember[] | LiteralUnionMemberCheck;
   readBaselineDiagnostics?: (base: string, command: string) => BaselineDiagnostics;
   runTscCmd: (cmd: string) => TscRun;
+  resolveTscScript?: (cwd: string) => string | undefined;
   /** Landing tree. Git, existsSync, tsc, and the test baseline are measured here — not in process.cwd(). */
   cwd?: string;
   /** Explicit base revision. Same rule as TSC_BASE_REF, without reading the process environment. */
@@ -982,16 +983,30 @@ export function planRootCheck(input: {
   if (roots.length > TSC_GATE_ROOT_LIMIT) return { mode: 'full', fallbackReason: `루트 ${roots.length}개 > 상한 ${TSC_GATE_ROOT_LIMIT}`, roots: roots.length };
   return { mode: 'affected', roots, changedCount: gateChanged.size };
 }
-/**
- * K-OP-039 · 노하우를 «도구 출력»에 싣는 첫 조각(대표 2026-10-12 «어떤 에이전트가 와도 같은 수준»).
- * 승격된 전체 판정은 `apps/pwa/node_modules` 가 없으면 «가짜» PWA 타입 에러만 낸다 —
- * 10-12 하루 TC·UX 두 자리가 같은 가짜 TS2322(ChatMessage.tsx)로 코드를 고치려 했다.
- * 카드(내부 문서 `KNOWHOW` K-OP-039)의 처방 문면을 그대로 도구 출력에 싣는다.
- */
-const PWA_DEPS_MISSING_HINT = '환경: apps/pwa 의존성 없음 — (cd apps/pwa && bun install --frozen-lockfile) 뒤 재실행 · 코드 결함 아님(K-OP-039)';
+/** Target checkout first, then the installed CLI's top-level and nested dependencies. */
+export function resolveTscScript(cwd: string, scriptsDir = import.meta.dir, present: (path: string) => boolean = existsSync): string | undefined {
+  return [
+    join(cwd, 'node_modules/typescript/bin/tsc'),
+    join(scriptsDir, '../../typescript/bin/tsc'),
+    join(scriptsDir, '../node_modules/typescript/bin/tsc'),
+  ].find(present);
+}
+
+/** The installed compiler cannot resolve declarations from a checkout without its own dependencies. */
+export function missingCheckoutTypeDependencies(cwd: string, needsPwa = false, present: (path: string) => boolean = existsSync): string[] {
+  const missing: string[] = [];
+  if (!present(join(cwd, 'node_modules'))) missing.push('node_modules');
+  if (!present(join(cwd, 'node_modules/bun-types'))) missing.push('bun-types');
+  if (needsPwa && !present(join(cwd, 'apps/pwa/node_modules'))) missing.push('apps/pwa/node_modules');
+  return missing;
+}
 
 export function runGate(io: Partial<GateIo> = {}): void {
   const cwd = io.cwd ?? process.cwd();
+  const targetGit: GitRunner = (command, args, options) => execFileSync(command, args, { ...options, cwd, env: gitEnv() });
+  const targetPaths = (base: string) => changedPathPairs(base, targetGit);
+  const targetFile = (ref: string, path: string) => readGitFile(ref, path, targetGit);
+  const targetSource = (file: string) => readFileSync(join(cwd, file), 'utf8');
   const defaultChanged = () => changedTsFiles((cmd) => sh(cmd, cwd), process.env, cwd, io.baseRef);
   const defaultRunTsc = (cmd: string) => runTsc(cmd, ((command, options) => execSync(command, { ...options, cwd, env: tscExecEnv(options?.env) })) as typeof execSync);
   const { changedTsFiles: getChanged = defaultChanged, runTscCmd = defaultRunTsc, log = (message: string) => console.log(message), warn = (message: string) => console.warn(message), error = (message: string) => console.error(message), exit = ((code: number) => process.exit(code)) as GateIo['exit'] } = io;
@@ -999,10 +1014,10 @@ export function runGate(io: Partial<GateIo> = {}): void {
   // Set 주입은 기존 테스트 심이며 기준 revision이 없다. 실제 ChangedTsFiles 경로만 Git 관측을 요구한다.
   const requiredExportFields = io.requiredExportFields ?? ((changed: ReadonlySet<string>, base: string) => base === 'injected test seam'
     ? { fields: [], removedSymbols: [], parameterIncreases: [] }
-    : requiredExportFieldsInChanges(changed, base));
+    : requiredExportFieldsInChanges(changed, base, targetPaths(base), targetFile, targetSource));
   const literalUnionMembers = io.literalUnionMembers ?? ((changed: ReadonlySet<string>, base: string) => base === 'injected test seam'
     ? { additions: [] }
-    : exportedLiteralUnionMembersInChanges(changed, base));
+    : exportedLiteralUnionMembersInChanges(changed, base, targetPaths(base), targetFile, targetSource, () => repositoryTypeScriptSources(cwd)));
   const changedResult = getChanged();
   const { files: changed, base, baseSource, head, diffFiles, warnings = [], failures = [] } = changedResult instanceof Set
     ? { files: changedResult, base: 'injected test seam', baseSource: 'injected test seam', head: 'injected test seam', diffFiles: new Set<string>(), warnings: [], failures: [] }
@@ -1099,15 +1114,33 @@ export function runGate(io: Partial<GateIo> = {}): void {
   }, { level: 'info' });
   log(`[tsc-gate] root 설정 범위 ${rootScope.size}개 관측 (apps/pwa/** 제외).`);
   if (runsPwa) log(`[tsc-gate] PWA 설정 범위 ${pwaScope.size}개 관측.`);
-  // ⛔ K-OP-039: 승격된 전체 판정은 apps/pwa 의존성 없이는 «가짜» PWA 타입 에러만 낸다(환경 문제 · 코드 결함 아님).
-  //    그 오류를 내기 «전에» 이 한 줄로 멈춘다(환경 줄이 곧 마지막 줄 = 판정) — 의존성이 있으면 아래
-  //    판정 규칙·출력 형식은 기존 그대로다. «못 쟀다 ≠ 통과» — PWA 미측정을 통과로 접지 않는다.
-  if (wholeRepository && !existsSync(join(cwd, 'apps/pwa/node_modules'))) {
-    error(`[tsc-gate] ${PWA_DEPS_MISSING_HINT}`);
+  // K-OP-039: PWA checks without app dependencies produce fake type errors.
+  // The target checkout's declarations are required even when a compiler is
+  // supplied by the installed CLI or injected by another gate caller.
+  const missing = missingCheckoutTypeDependencies(cwd, runsPwa || wholeRepository);
+  if (missing.length > 0) {
+    const quotedCwd = `'${cwd.replaceAll("'", "'\\''")}'`;
+    const install = `cd ${quotedCwd} && bun install --frozen-lockfile${missing.includes('apps/pwa/node_modules') ? ' && (cd apps/pwa && bun install --frozen-lockfile)' : ''}`;
+    error(`[tsc-gate] ⛔ 대상 트리 타입 의존성 없음: ${missing.join(', ')} — ${install}`);
+    error('[tsc-gate] FAIL — 대상 의존성을 확인하지 못했다(설치본 tsc 존재 ≠ 대상 타입 검사 가능).');
+    exit(1);
+    return;
+  }
+  // The .bin shim uses `#!/usr/bin/env node`. A LaunchAgent can have Bun but no
+  // node on PATH, so invoke the installed compiler with this process's absolute
+  // runtime instead. A missing dependency must fail the gate, never fetch via npx.
+  // Preserve the target checkout's compiler version when available. The
+  // installed CLI may resolve TypeScript from a sibling top-level node_modules
+  // or its own nested node_modules; verify each path before starting a child.
+  const tscScript = (io.resolveTscScript ?? resolveTscScript)(cwd);
+  if (!tscScript) {
+    error('[tsc-gate] ⛔ TypeScript 실행 파일 없음 — 대상 트리 또는 설치본에 bun install --frozen-lockfile 뒤 재실행하십시오.');
+    error('[tsc-gate] FAIL — tsc 를 실행하지 못했다(의존성 없음 ≠ 진단 0건).');
     exit(1);
     return;
   }
-  const tscBin = existsSync(join(cwd, 'node_modules/.bin/tsc')) ? 'node_modules/.bin/tsc' : 'npx tsc';
+  const shellArg = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+  const tscBin = `${shellArg(process.execPath)} ${shellArg(tscScript)}`;
   const baseline = readTestTypecheckBaseline(cwd);
   const rootCommand = `${tscBin} --noEmit -p ${TYPECHECK_GATE_CONFIG}`;
   const pwaCommand = `${tscBin} --noEmit -p apps/pwa/tsconfig.json`;

package/scripts/detect-test-interference.ts

@@ -26,6 +26,9 @@ export type MeasuredRun = {
   fail: number | null;
   status: 'measured' | 'unmeasurable';
   reason?: string;
+  /** Names observed in Bun's failed-test output. Absent names must not be inferred from the selected files. */
+  failedFiles?: string[];
+  failedTests?: string[];
 };
 
 export type InterferenceReport = {
@@ -61,6 +64,32 @@ export function parseFailureCount(output: string): number | null {
   return Number(failures[0]![1]);
 }
 
+/** Bun prints a file heading before its `(fail) name` lines. Only retain names actually printed by that run. */
+export function parseFailedTestNames(output: string): { files: string[]; tests: string[] } {
+  const files = new Set<string>();
+  const tests = new Set<string>();
+  let currentFile: string | undefined;
+  for (const raw of output.replace(/\x1b\[[0-9;]*m/g, '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (/^(?:\d+\s+(?:pass|fail|skip)|Ran\s+\d+\s+tests?|Bun test v)/i.test(line)) { currentFile = undefined; continue; }
+    const failure = /^\(fail\)\s+(.+?)(?:\s+\[[^\]]+\])?$/.exec(line);
+    if (failure) {
+      tests.add(failure[1]!.trim());
+      if (currentFile) files.add(currentFile);
+      continue;
+    }
+    const heading = /^(.+):$/.exec(line);
+    if (heading) currentFile = /\.(?:test|spec)\.[cm]?[jt]sx?$/.test(heading[1]!) ? heading[1] : undefined;
+  }
+  return { files: [...files], tests: [...tests] };
+}
+
+export function failedNamesFromStreams(result: RunnerResult): { files: string[]; tests: string[] } {
+  const stdout = parseFailedTestNames(result.stdout);
+  const stderr = parseFailedTestNames(result.stderr);
+  return { files: [...new Set([...stdout.files, ...stderr.files])], tests: [...new Set([...stdout.tests, ...stderr.tests])] };
+}
+
 async function measure(files: readonly string[], runner: TestRunner): Promise<MeasuredRun> {
   try {
     const result = await runner(files);
@@ -68,9 +97,10 @@ async function measure(files: readonly string[], runner: TestRunner): Promise<Me
       return { files: [...files], fail: null, status: 'unmeasurable', reason: result.signal ? `runner terminated by ${result.signal}` : 'runner exit code unavailable' };
     }
     const fail = parseFailureCount(`${result.stdout}${result.stderr}`);
+    const names = fail !== null && fail > 0 ? failedNamesFromStreams(result) : undefined;
     return fail === null
       ? { files: [...files], fail: null, status: 'unmeasurable', reason: 'test summary unavailable, ambiguous, or ran zero files' }
-      : { files: [...files], fail, status: 'measured' };
+      : { files: [...files], fail, status: 'measured', ...(names?.files.length ? { failedFiles: names.files } : {}), ...(names?.tests.length ? { failedTests: names.tests } : {}) };
   } catch (error) {
     return { files: [...files], fail: null, status: 'unmeasurable', reason: error instanceof Error ? error.message : String(error) };
   }

package/scripts/release-loop/docs-node.ts

@@ -130,7 +130,11 @@ export function runDocs(
 const SHA = /^[0-9a-f]{40}$/i;
 const PREFETCH_DEADLINE_MS = 15 * 60_000;
 type Cut = { version: string; commit: string; manifestHash: string };
-type PrefetchCache = Cut & { main: string; tree: string; docs: DocsResult; tui: Record<string, unknown> | null };
+// Two separately published cache files: a finished TUI must survive a docs failure or delay,
+// so it never lives inside the same file as the docs result (should-fix ②).
+type TuiCache = Cut & { tui: Record<string, unknown> };
+type DocsCache = Cut & { main: string; tree: string; docs: DocsResult };
+type PrefetchCache = DocsCache & { tui: Record<string, unknown> | null };
 type Runner = (command: string, args: string[], cwd?: string, timeout?: number, env?: NodeJS.ProcessEnv) => string;
 export const commandRunner: Runner = (command, args, cwd, timeout, env) => {
   const output = spawnSync(command, args, { cwd, env: env ?? process.env, timeout: timeout ?? 15 * 60_000, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
@@ -162,11 +166,27 @@ function claimPrefetch(dir: string, owner: 'worker' | 'docs'): boolean {
 function cacheFile(dir: string, cut: Cut): string {
   return join(dir, `${cut.commit}-${cut.manifestHash}.json`);
 }
-function loadCache(dir: string, cut: Cut): PrefetchCache | null {
+function tuiCacheFile(dir: string, cut: Cut): string {
+  return join(dir, `${cut.commit}-${cut.manifestHash}.tui.json`);
+}
+function loadTuiCache(dir: string, cut: Cut): TuiCache | null {
+  try {
+    const value = JSON.parse(readFileSync(tuiCacheFile(dir, cut), 'utf8')) as TuiCache;
+    if (value.version !== cut.version || value.commit !== cut.commit || value.manifestHash !== cut.manifestHash) return null;
+    return value;
+  } catch { return null; }
+}
+/** Publish `data` to `path` atomically (temp + rename), so a reader never sees a partial file. */
+function publish(path: string, data: unknown): void {
+  const staged = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(staged, JSON.stringify(data) + '\n');
+  try { renameSync(staged, path); } catch (error) { rmSync(staged, { force: true }); throw error; }
+}
+function loadCache(dir: string, cut: Cut): DocsCache | null {
   try {
-    const value = JSON.parse(readFileSync(cacheFile(dir, cut), 'utf8')) as PrefetchCache;
+    const value = JSON.parse(readFileSync(cacheFile(dir, cut), 'utf8')) as DocsCache;
     if (value.version !== cut.version || value.commit !== cut.commit || value.manifestHash !== cut.manifestHash
-      || !SHA.test(value.main) || value.tree !== join(dir, 'tree') || !existsSync(value.tree)
+      || !SHA.test(value.main) || dirname(value.tree) !== dir || !/^tree-[0-9a-f-]{36}$/.test(basename(value.tree)) || !existsSync(value.tree)
       || value.docs?.outcome !== 'ok' || value.docs.version !== cut.version
       || value.docs.notes !== join(value.tree, 'release/public/docs/releases', `${cut.version}.md`)
       || value.docs.pages !== join(value.tree, 'website/pages.json')
@@ -191,21 +211,34 @@ export function stagePrefetch(context: GraphContext, env: NodeJS.ProcessEnv = pr
   const cut = cutFor(context, stateRoot);
   mkdirSync(dir, { recursive: true });
   const already = loadCache(dir, cut);
-  if (already) return already;
-  const tree = join(dir, 'tree');
+  if (already) return { ...already, tui: loadTuiCache(dir, cut)?.tui ?? null };
+  // An attempt gets its own path. A failed add can only remove a tree belonging to this attempt,
+  // even when an earlier cut or a concurrent worker has a checkout in the same run directory.
+  const tree = join(dir, `tree-${randomUUID()}`);
   let added = false;
+  // `git worktree add` can fail AFTER creating the tree directory (e.g. a failed checkout): clean up
+  // whenever the add succeeded OR the tree is on disk, so a retry of this run is never blocked (should-fix ①).
+  const removeTree = () => {
+    if (!(added || existsSync(tree))) return;
+    try { runner('git', ['worktree', 'remove', '--force', tree], repo, 60_000); } catch { /* preserve original failure */ }
+    // A remove that failed (or could not unregister the tree) must still leave no blocking directory behind.
+    if (existsSync(tree)) rmSync(tree, { recursive: true, force: true });
+  };
   try {
     const main = run('git', ['rev-parse', '--verify', 'origin/main^{commit}'], repo);
     if (!SHA.test(main)) throw new Error('invalid origin/main commit');
-    // TUI runs against the cut, on its own isolated worktree, before touching the docs checkout.
+    const cachedTui = loadTuiCache(dir, cut);
+    // TUI runs against the cut, on its own isolated session, before touching the docs checkout.
     // tui-sim-node.ts prints the RAW result (no `outcome`); judge it the way node-verdict.ts tui would before reuse.
-    const tuiData = deps.tui ? deps.tui(cut.commit) : (() => {
+    // Publish the reusable TUI in its OWN file the moment it is confirmed — a later docs failure or
+    // delay must not throw away a finished TUI (should-fix ②).
+    const tui = cachedTui ? cachedTui.tui : reusableTui(withTuiOutcome(0, deps.tui ? deps.tui(cut.commit) : (() => {
       const tuiRun = spawnSync('bun', ['scripts/release-loop/tui-sim-node.ts', '--commit', cut.commit, '--json'], {
         cwd: repo, timeout: Math.min(6 * 60_000, left()), encoding: 'utf8', maxBuffer: 16 * 1024 * 1024,
       });
       return tuiRun.status === 0 ? lastResult({ status: tuiRun.status, stdout: tuiRun.stdout ?? '', stderr: tuiRun.stderr ?? '' }) ?? null : null;
-    })();
-    const tui = reusableTui(withTuiOutcome(0, tuiData), cut.commit);
+    })()), cut.commit);
+    if (tui && !cachedTui) publish(tuiCacheFile(dir, cut), { ...cut, tui });
     run('git', ['worktree', 'add', '--detach', tree, main], repo);
     added = true;
     run('bun', ['install', '--frozen-lockfile'], tree);
@@ -220,19 +253,14 @@ export function stagePrefetch(context: GraphContext, env: NodeJS.ProcessEnv = pr
     const finalCut = cutFor(context, stateRoot);
     if (finalCut.manifestHash !== cut.manifestHash) throw new Error('manifest changed during prefetch');
     const result: PrefetchCache = { ...cut, main, tree, docs, tui };
-    const final = cacheFile(dir, cut);
-    const staged = `${final}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(staged, JSON.stringify(result) + '\n');
+    const docsCache: DocsCache = { ...cut, main, tree, docs };
     // Publication handshake: whoever creates `claim` first (O_EXCL) wins. The docs node claims before it reads,
     // so a worker that loses can never publish a cache that a docs attempt would consume.
-    if (!claimPrefetch(dir, 'worker')) {
-      rmSync(staged, { force: true });
-      throw new Error('docs node already ran; late prefetch is discarded');
-    }
-    renameSync(staged, final);
+    if (!claimPrefetch(dir, 'worker')) throw new Error('docs node already ran; late prefetch is discarded');
+    publish(cacheFile(dir, cut), docsCache);
     return result;
   } catch (error) {
-    if (added) { try { runner('git', ['worktree', 'remove', '--force', tree], repo, 60_000); } catch { /* preserve original failure */ } }
+    removeTree();
     throw error;
   }
 }
@@ -247,9 +275,10 @@ export function joinTui(context: GraphContext, env: NodeJS.ProcessEnv, repo: str
   }, stateRoot = effectiveInstanceRoot()): Record<string, unknown> {
   if (context.outputs.upgrade?.outcome !== 'ok') throw new Error('upgrade did not pass');
   // Any failure to key the cache (no manifest, cutoff mismatch, no run dir) is a cache miss → original TUI path.
+  // The TUI cache file is independent of docs (should-fix ②): a docs failure or delay never blocks this read.
   let cut: Cut | null = null;
-  let cached: PrefetchCache | null = null;
-  try { cut = cutFor(context, stateRoot); cached = loadCache(runCacheDir(env), cut); } catch { /* cache miss */ }
+  let cached: TuiCache | null = null;
+  try { cut = cutFor(context, stateRoot); cached = loadTuiCache(runCacheDir(env), cut); } catch { /* cache miss */ }
   const reused = cut && cached?.tui && reusableTui(cached.tui, cut.commit);
   if (reused) return { ...reused, outcome: 'ok', summary: `tui ${reused.verdict}` };
   // Preserve node-verdict.ts's exit convention and last-JSON output on a cache miss.
@@ -287,7 +316,7 @@ export function graphDocs(context: GraphContext, env: NodeJS.ProcessEnv, repo: s
   try {
     // No fetch (nor any write to remote) until every gate is verified.
     for (const node of ['gate', 'prepare', 'upgrade', 'tui']) if (context.outputs[node]?.outcome !== 'ok') throw new Error(`${node} did not pass`);
-    let cached: PrefetchCache | null = null;
+    let cached: DocsCache | null = null;
     // A cache key that cannot be computed is a miss — the original fresh-worktree path runs.
     if (mayConsume && cacheDir) { try { const cut = cutFor(context, stateRoot); cached = loadCache(cacheDir, cut); } catch { cached = null; } }
     const branch = `release-docs/${version}`;

package/scripts/release-loop/gate-node.ts

@@ -117,6 +117,8 @@ export interface GateResult {
 const sha = /^[0-9a-f]{7,40}$/i;
 const versionPattern = /^\d+\.\d+\.\d+(?:-(?:rc|alpha|beta)\.\d+)?$/;
 const failureFile = (root: string, version: string) => join(root, 'release', version, 'gate-failures.json');
+/** Judged identities live beside the machine release ledger; gate-failures.json keeps its raw baseline schema. */
+const verdictFile = (root: string, version: string) => join(root, 'release', version, 'gate-verdict.json');
 const quote = (s: string) => `'${s.replaceAll("'", "'\\''")}'`;
 const defaultRemoteMirror = '~/mirror/elanous-agent.git';
 
@@ -1431,6 +1433,8 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
   };
   const repo = resolve(opts.repo ?? process.cwd());
   const result: GateResult = { outcome: 'error', commit: opts.commit, introduced: [], preexisting: 0, fixed: 0, knownEnv: 0, knownEnvCleared: [], stalledEnv: [], rcNonzeroNoFailures: [], durationMs: 0 };
+  const preexistingIds: string[] = [];
+  let knownEnvIds: string[] = [];
   let work: string | undefined;
   let baseSnapshot = false;
   let cutFailures: SweepFailures | undefined;
@@ -1598,11 +1602,13 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
     const baselineIds = [...baseline.failures, ...baseline.errors];
     const countedCut = splitKnownEnv(cutIds, known);
     const countedBaseline = splitKnownEnv(baselineIds, known);
-    result.knownEnv = countedCut.knownEnv.length;
+    knownEnvIds = countedCut.knownEnv;
+    result.knownEnv = knownEnvIds.length;
     result.knownEnvCleared = [...new Set(cutRun.passedIds ?? [])].filter((id) => known.has(id) && !cutIds.includes(id) && !cutRun.stalledEnv?.some(({ file }) => fileOf(id) === file)).sort();
     const diff = diffFailures(countedCut.counted, countedBaseline.counted);
     result.fixed = result.baselineDeferred ? null : diff.fixed.length;
-    result.preexisting = diff.common.length;
+    preexistingIds.push(...diff.common);
+    result.preexisting = preexistingIds.length;
     // GATE-BASELINE-CACHE — only the files whose new failures reproduce in isolation reach the baseline, and each
     // (commit, file, host) is run at most once across gates: this gate's cut results also seed the next gate's baseline.
     const cacheHost = opts.remote ?? 'local';
@@ -1703,10 +1709,11 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
         debug.log('release-loop.gate', 'isolated-rc-nonzero-no-failures', { file, label: 'cut isolated', rc: rcOnly.rc, pass: rcOnly.pass, baseline });
       }
       for (const id of candidates) {
-        if (oldFailures.has(id)) result.preexisting++;
+        if (oldFailures.has(id)) preexistingIds.push(id);
         else result.introduced.push(id);
       }
     }
+    result.preexisting = preexistingIds.length;
     result.baselineCache = cacheStats;
     debug.log('release.gate', 'baseline-cache', { hits: cacheStats.hits, misses: cacheStats.misses, commit: baseSha });
     result.outcome = result.introduced.length ? 'regression' : 'ok';
@@ -1751,7 +1758,33 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
       result.error = `baseline persistence: ${String(error)}`;
     }
   }
-  if (result.outcome !== 'error') debug.log('release-loop.gate', 'judged', { version: opts.version, commit: opts.commit, introduced: result.introduced.length, preexisting: result.preexisting });
+  if (result.outcome !== 'error') {
+    const ids = {
+      introduced: [...result.introduced].sort(),
+      knownEnv: [...knownEnvIds].sort(),
+      preexisting: [...preexistingIds].sort(),
+      loadFlaky: [...(result.loadFlaky ?? [])].sort(),
+    };
+    try {
+      const path = verdictFile(ledger, opts.version);
+      mkdirSync(dirname(path), { recursive: true });
+      const temp = join(dirname(path), `.gate-verdict-${process.pid}-${randomUUID()}.tmp`);
+      try {
+        writeFileSync(temp, JSON.stringify({ version: opts.version, commit: opts.commit, outcome: result.outcome, ...ids }, null, 2) + '\n', { mode: 0o600 });
+        chmodSync(temp, 0o600);
+        renameSync(temp, path);
+      } finally { if (existsSync(temp)) rmSync(temp); }
+    } catch (error) {
+      result.outcome = 'error';
+      result.error = `verdict persistence: ${String(error)}`;
+    }
+    if (result.outcome !== 'error') debug.log('release-loop.gate', 'judged', {
+      version: opts.version, commit: opts.commit,
+      introduced: result.introduced.length, preexisting: result.preexisting,
+      knownEnv: result.knownEnv, loadFlaky: ids.loadFlaky.length,
+      introducedIds: ids.introduced, knownEnvIds: ids.knownEnv, preexistingIds: ids.preexisting, loadFlakyIds: ids.loadFlaky,
+    });
+  }
   // GATE-LIVE-OBS-RC-WORDING ⓒ — the shards board says «판정 전» until this lands; then «새 실패 N» only (UX · gate-shards.ts).
   // Same ledger as the board's own writes (sweep's shardsFile). A write failure is logged and never changes the verdict.
   if (result.outcome !== 'error' && opts.pod) {

package/scripts/release-loop/node-verdict.ts

@@ -7,6 +7,7 @@ import { debug } from '../../src/debug/log.js';
 export type NodeOutcome = 'ok' | 'fail' | 'error';
 export type NodeVerdict = 'pass' | 'flaky' | 'fail';
 export interface GraphContext {
+  nodeId?: string;
   input: { version: string; previousVersion: string; [key: string]: unknown };
   outputs: Record<string, Record<string, unknown>>;
 }
@@ -20,7 +21,8 @@ export function readGraphContext(env: NodeJS.ProcessEnv = process.env): GraphCon
   const input = context.input as Record<string, unknown> | undefined;
   if (!input || typeof input.version !== 'string' || !isReleaseVersion(input.version)
     || typeof input.previousVersion !== 'string' || !/^\d+\.\d+\.\d+$/.test(input.previousVersion)) throw new Error('version and previousVersion required');
-  return { input: input as GraphContext['input'], outputs: context.outputs && typeof context.outputs === 'object' ? context.outputs as GraphContext['outputs'] : {} };
+  return { ...(typeof context.nodeId === 'string' ? { nodeId: context.nodeId } : {}),
+    input: input as GraphContext['input'], outputs: context.outputs && typeof context.outputs === 'object' ? context.outputs as GraphContext['outputs'] : {} };
 }
 
 export function nodeOutput(context: GraphContext, node: string, key: string): string {

package/scripts/release-loop/publish-node.ts

@@ -48,6 +48,9 @@ export function waitForAssets(run: CommandRunner, repo: string, tag: string, nam
 export function runPublish(run: CommandRunner = runCommand, prodFreezeRoot?: string,
   clock: { now: () => number; sleep: (ms: number) => void } = { now: Date.now, sleep: Bun.sleepSync }) {
   const context = readGraphContext();
+  // A resumed graph once invoked this irreversible node at npm-publish, docs-land, and failed.
+  // The runner's context is the authority: only the publish visit may publish.
+  if (context.nodeId !== 'publish') throw new Error(`publish node context mismatch: expected publish, got ${context.nodeId ?? 'missing'}`);
   const version = context.input.version;
   // A measured automatic decision or the existing human approval must authorize publication.
   const auto = context.outputs['auto-approve'];

package/scripts/release-loop/tui-node-checks.ts

@@ -11,6 +11,9 @@ export interface TuiScreens {
 export interface TuiCheck { id: string; pass: boolean; detail: string }
 
 const ERROR_TEXT = /\b(TypeError|ReferenceError|SyntaxError|Unhandled|panic|Segmentation fault)\b|Error: /;
+// The startup band can say "Commands — /help lists every command" (#26954).
+// Only the modal's title proves that the help overlay itself remains on screen.
+const HELP_MODAL_TITLE = 'Dashboard help';
 
 export function tuiChecks(s: TuiScreens, readyLimitMs = 60_000): TuiCheck[] {
   const all = [s.first, s.help, s.afterEsc].join('\n');
@@ -18,8 +21,8 @@ export function tuiChecks(s: TuiScreens, readyLimitMs = 60_000): TuiCheck[] {
     { id: 'boot', pass: s.readyMs !== null && s.readyMs <= readyLimitMs, detail: s.readyMs === null ? 'never ready' : `ready in ${s.readyMs}ms` },
     { id: 'prompt', pass: s.first.includes('❯'), detail: 'input line (❯) on the first screen' },
     { id: 'status-bar', pass: /│.*ctx \d+/.test(s.first), detail: 'status bar with model and ctx' },
-    { id: 'help-opens', pass: s.help.includes('help') && s.help.includes('Commands') && s.help.includes('/help'), detail: '/help shows the help overlay' },
-    { id: 'help-closes', pass: !s.afterEsc.includes('Commands') && s.afterEsc.includes('❯'), detail: 'Esc closes the overlay' },
+    { id: 'help-opens', pass: s.help.includes(HELP_MODAL_TITLE) && s.help.includes('Commands') && s.help.includes('/help'), detail: '/help shows the help overlay' },
+    { id: 'help-closes', pass: !s.afterEsc.includes(HELP_MODAL_TITLE) && s.afterEsc.includes('❯'), detail: 'Esc closes the overlay' },
     { id: 'no-error-text', pass: !ERROR_TEXT.test(all), detail: 'no error text on any screen' },
   ];
 }

package/scripts/skills/public-check.ts

@@ -17,7 +17,9 @@ export interface PublicCheckReport {
   readonly ok: boolean;
 }
 
-const PERSONAL_OR_INTERNAL = /\/Users\/|~\/source(?:\/|\b)|\b(?:INTERNAL_ONLY|ELANOUS_INTERNAL|PRIVATE_INTERNAL|internal-only)\b|@internal\b|내부\s*전용/iu;
+// 개인 경로(`/Users/`·`~/source`)는 대소문자를 가리고, 내부 표지는 기존처럼 `iu`.
+const PERSONAL_PATH = /\/Users\/|~\/source(?:\/|\b)/u;
+const INTERNAL_MARKER = /\b(?:INTERNAL_ONLY|ELANOUS_INTERNAL|PRIVATE_INTERNAL|internal-only)\b|@internal\b|내부\s*전용/iu;
 const EXECUTABLE = /\.(?:ts|tsx|js|mjs|cjs|py|sh|bash)$/iu;
 const ENTRY_DIR = /^(?:scripts|src|bin)\//u;
 const NON_ENTRY = /(?:\.d\.ts|\.(?:test|spec)\.[^.]+)$/iu;
@@ -165,7 +167,8 @@ export function checkPublicSkills(root: string, boundary: SkillBoundaryReport =
       const bytes = readFileSync(file);
       if (bytes.includes(0)) continue;
       try {
-        if (PERSONAL_OR_INTERNAL.test(new TextDecoder('utf-8', { fatal: true }).decode(bytes))) matches.push(relative(root, file));
+        const decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        if (PERSONAL_PATH.test(decoded) || INTERNAL_MARKER.test(decoded)) matches.push(relative(root, file));
       } catch {
         // Binary assets are not text; extensionless and dotfiles are checked when decodable.
       }