elanous 0.2.28 → 0.2.31

package/src/nexus/daemon-thin-inventory.md

@@ -0,0 +1,37 @@
+## stay
+http | src/nexus/api/http-server.ts:startNexusHttpServer | HTTP
+pwa | src/nexus/pwa-registration.ts:createPwaRegistration | PWA
+workflow-dispatch | src/workflow-runtime/daemon.ts:dispatchWebhook | 발송/dispatch
+outbound | src/notifications/outbound-boot.ts:buildOutboundSubstrate | 발송/dispatch
+sse-bus | src/nexus/api/event-bus.ts:NexusEventBus | SSE
+sse-events | src/nexus/api/events.ts:handleSseEvents | SSE
+sse-heartbeat | src/nexus/api/sse-heartbeat.ts:SSE_HEARTBEAT_MS | SSE
+task-cards | src/nexus/api/task-cards-api.ts:handleTaskCardsGet | cards
+decision-cards | src/decisions/decision-cards.ts:DecisionCardService | cards
+hitl-pending | src/nexus/api/hitl-runtime.ts:createHitlPendingCallbacks | cards
+
+## leave
+executor | src/workflow-runtime/executor.ts:runWorkflowToCompletion | judgment/executor; daemon emit awaits this in-process — ops rail must consume a short-lived run instead (process extraction is remaining work, out of stage 1)
+harness | src/boot/daemon-tools/self-implement.ts:dispatchSelfImplement | harness/self-implement wired into TOX externalExec on this boot — already process-shaped; must leave the daemon
+agent-loop | src/telegram-agent.ts:makeTelegramAgentRunTurn | agent loop started on this boot (telegram Q&A; discord makeDiscordAgentRunTurn and ACP createAgentTurnRunner siblings). AutopilotLoopDriver in src/autopilot/agent-loop.ts is not started here
+tox | src/task-orchestrator/boot.ts:wireTox | TOX TaskFeedbackLoop + startToxLoop long-lived dispatcher started on this boot
+continuation | src/dispatch/continuation-scheduler.ts:ContinuationScheduler.start | idle-continuation scheduler constructed on this boot (starts when dispatch.enabled)
+workflow-schedule | src/workflow-runtime/daemon.ts:start | scheduleSource.start is a long-lived trigger scheduler; dispatch methods stay
+intent-prediction | src/intent-prediction/index.ts:createIntentPredictionService | long-lived ranker tick / judgment scheduler
+patcher | src/background-reasoning/patcher-boot.ts:buildPatcherSubstrate | self-improving patcher loop started on this boot
+daily-reflection | src/notes/daily-reflection-scheduler.ts:startDailyReflectionScheduler | daily reflection scheduler
+discovery-cron | src/registry/discovery/cron.ts:startDiscoveryCron | discovery cron scheduler
+watch-default | src/domains/watch-default-scheduler.ts:startWatchDefaultScheduler | watch default scheduler
+
+## removalOrder
+executor
+harness
+agent-loop
+tox
+continuation
+workflow-schedule
+intent-prediction
+patcher
+daily-reflection
+discovery-cron
+watch-default

package/src/nexus/index.ts

@@ -88,6 +88,7 @@ import type { McpReloadOutcome, McpReloadServerResult } from './api/admin-mcp-re
 import { loadOrCreateSigningKey, NonceStore } from './api/edit-in-pwa-core.js';
 import { subscribeErrorSnapshotWriter } from './supervisor/error-snapshot.js';
 import { NexusEventBus } from './api/event-bus.js';
+import { startTaRepairEventCollector } from '../steward/ta-repair-event-collect.js';
 import type { SessionSurface } from '../session/index.js';
 import { wireWorkflowApprovalEvents } from './api/workflow-event-bridge.js';
 import { wireAgentStatusEvents } from './api/agent-status-event-bridge.js';
@@ -275,6 +276,73 @@ import { packageVersion } from '../version/code-revision.js';
 export const NEXUS_VERSION = packageVersion();
 export const NEXUS_PHASE = 'N-5 PR χ (graceful exit + restart pending)';
 
+// DAEMON-THIN stage 1 — inventory only (RFC-universe-by-house §4).
+// Intentional wiring boundary: do not call daemonThinStage1 from runNexus.
+// A runtime caller would change process composition, which stage 1 forbids.
+export const DAEMON_THIN_STAY_ALLOWLIST = ['HTTP', 'PWA', '발송/dispatch', 'SSE', 'cards'] as const;
+export type DaemonThinStayAllowlistClass = (typeof DAEMON_THIN_STAY_ALLOWLIST)[number];
+
+export interface DaemonThinStayEntry {
+  id: string;
+  fileFunction: string;
+  allowlistClass: DaemonThinStayAllowlistClass;
+}
+
+export interface DaemonThinLeaveEntry {
+  id: string;
+  fileFunction: string;
+  why: string;
+}
+
+export interface DaemonThinStage1 {
+  stay: readonly DaemonThinStayEntry[];
+  leave: readonly DaemonThinLeaveEntry[];
+  removalOrder: readonly string[];
+}
+
+export function daemonThinStage1(): DaemonThinStage1 {
+  return {
+    stay: [
+      { id: 'http', fileFunction: 'src/nexus/api/http-server.ts:startNexusHttpServer', allowlistClass: 'HTTP' },
+      { id: 'pwa', fileFunction: 'src/nexus/pwa-registration.ts:createPwaRegistration', allowlistClass: 'PWA' },
+      { id: 'workflow-dispatch', fileFunction: 'src/workflow-runtime/daemon.ts:dispatchWebhook', allowlistClass: '발송/dispatch' },
+      { id: 'outbound', fileFunction: 'src/notifications/outbound-boot.ts:buildOutboundSubstrate', allowlistClass: '발송/dispatch' },
+      { id: 'sse-bus', fileFunction: 'src/nexus/api/event-bus.ts:NexusEventBus', allowlistClass: 'SSE' },
+      { id: 'sse-events', fileFunction: 'src/nexus/api/events.ts:handleSseEvents', allowlistClass: 'SSE' },
+      { id: 'sse-heartbeat', fileFunction: 'src/nexus/api/sse-heartbeat.ts:SSE_HEARTBEAT_MS', allowlistClass: 'SSE' },
+      { id: 'task-cards', fileFunction: 'src/nexus/api/task-cards-api.ts:handleTaskCardsGet', allowlistClass: 'cards' },
+      { id: 'decision-cards', fileFunction: 'src/decisions/decision-cards.ts:DecisionCardService', allowlistClass: 'cards' },
+      { id: 'hitl-pending', fileFunction: 'src/nexus/api/hitl-runtime.ts:createHitlPendingCallbacks', allowlistClass: 'cards' },
+    ],
+    leave: [
+      { id: 'executor', fileFunction: 'src/workflow-runtime/executor.ts:runWorkflowToCompletion', why: 'judgment/executor; daemon emit awaits this in-process — ops rail must consume a short-lived run instead (process extraction is remaining work, out of stage 1)' },
+      { id: 'harness', fileFunction: 'src/boot/daemon-tools/self-implement.ts:dispatchSelfImplement', why: 'harness/self-implement wired into TOX externalExec on this boot — already process-shaped; must leave the daemon' },
+      { id: 'agent-loop', fileFunction: 'src/telegram-agent.ts:makeTelegramAgentRunTurn', why: 'agent loop started on this boot (telegram Q&A; discord makeDiscordAgentRunTurn and ACP createAgentTurnRunner siblings). AutopilotLoopDriver in src/autopilot/agent-loop.ts is not started here' },
+      { id: 'tox', fileFunction: 'src/task-orchestrator/boot.ts:wireTox', why: 'TOX TaskFeedbackLoop + startToxLoop long-lived dispatcher started on this boot' },
+      { id: 'continuation', fileFunction: 'src/dispatch/continuation-scheduler.ts:ContinuationScheduler.start', why: 'idle-continuation scheduler constructed on this boot (starts when dispatch.enabled)' },
+      { id: 'workflow-schedule', fileFunction: 'src/workflow-runtime/daemon.ts:start', why: 'scheduleSource.start is a long-lived trigger scheduler; dispatch methods stay' },
+      { id: 'intent-prediction', fileFunction: 'src/intent-prediction/index.ts:createIntentPredictionService', why: 'long-lived ranker tick / judgment scheduler' },
+      { id: 'patcher', fileFunction: 'src/background-reasoning/patcher-boot.ts:buildPatcherSubstrate', why: 'self-improving patcher loop started on this boot' },
+      { id: 'daily-reflection', fileFunction: 'src/notes/daily-reflection-scheduler.ts:startDailyReflectionScheduler', why: 'daily reflection scheduler' },
+      { id: 'discovery-cron', fileFunction: 'src/registry/discovery/cron.ts:startDiscoveryCron', why: 'discovery cron scheduler' },
+      { id: 'watch-default', fileFunction: 'src/domains/watch-default-scheduler.ts:startWatchDefaultScheduler', why: 'watch default scheduler' },
+    ],
+    removalOrder: [
+      'executor',
+      'harness',
+      'agent-loop',
+      'tox',
+      'continuation',
+      'workflow-schedule',
+      'intent-prediction',
+      'patcher',
+      'daily-reflection',
+      'discovery-cron',
+      'watch-default',
+    ],
+  };
+}
+
 type TelegramAgentRunTurnFactory = typeof import('../telegram-agent.js').makeTelegramAgentRunTurn;
 type TelegramChannelResolver = typeof import('../domains/telegram-channels.js').resolveTelegramChannels;
 type TelegramInteractivePollerSelector = typeof import('../domains/telegram-channels.js').interactivePollerTokens;
@@ -1067,6 +1135,7 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
   }
 
   const eventBus = new NexusEventBus();
+  const stopTaRepairEventCollector = startTaRepairEventCollector(eventBus);
   const state = createNexusState({ nexusVersion: NEXUS_VERSION, phase: NEXUS_PHASE });
   state.bus = eventBus;
   // BACKLOG #9 — fan workflow approval lifecycle into `/v1/events` SSE
@@ -3315,6 +3384,7 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
     pushEvent(state, { kind: 'nexus.shutdown' });
     pwaRegistration.unregister();
     try { unsubscribeWebtermTabLifecycle(); } catch { /* swallow */ }
+    try { stopTaRepairEventCollector(); } catch { /* swallow */ }
     try { unsubscribeErrorSnapshots(); } catch { /* swallow */ }
     if (supervisor) {
       void supervisor.shutdown({ graceMs: 0 });

package/src/nexus/onboarding/first-boot-wizard.ts

@@ -1,6 +1,7 @@
 import type { WizardIO } from '../../onboarding.js';
 import type { SetupCheckResult } from '../setup-status.js';
 import type { TailscaleProbe } from './tailscale-probe.js';
+import { createManagementStarterContract } from '../../persona/presets.js';
 
 export interface FirstBootWizardDeps {
   io: WizardIO;
@@ -18,14 +19,32 @@ export interface FirstBootWizardDeps {
   pwaBuilt?: boolean;
   /** Tailscale probe 결과 (alive 시 magicDNS / IP 도 banner 에 노출). */
   tailscale?: TailscaleProbe;
+  /** 0.2.29 PERSONA-STARTER — «경영» 스타터 계약을 쓸 persona 저장소 경로.
+   *  생략하면 기본 상태 저장소(resolveStatePersonaDir) — 운영 첫 실행 경로. */
+  starterContractDir?: string;
 }
 
 export type FirstBootStep = 'llm' | 'tailscale';
 
+/** 0.2.29 PERSONA-STARTER — 직업 질문에서 «경영»을 골랐을 때 만들어진 스타터 계약 한 장. */
+export interface StarterContractSummary {
+  personaId: string;
+  displayName: string;
+  path: string;
+}
+
 export type FirstBootResult =
-  | { action: 'completed'; stepsRun: FirstBootStep[] }
+  | { action: 'completed'; stepsRun: FirstBootStep[]; starterContract?: StarterContractSummary }
   | { action: 'skipped'; reason: 'no-tty' | 'all-set-up' };
 
+/** 직업 질문 답의 정규화 — «1»·«경영»·«management» 는 경영,
+ *  나머지(빈 답 포함)는 일반(현재 첫 실행 동작 유지). */
+export function normalizeOccupationChoice(input: string): 'management' | 'general' {
+  const v = input.trim().toLowerCase();
+  if (v === '1' || v === '경영' || v === 'management') return 'management';
+  return 'general';
+}
+
 function isTty(force?: boolean): boolean {
   if (force === true) return true;
   if (force === false) return false;
@@ -89,6 +108,39 @@ function printPwaSetupBanner(deps: FirstBootWizardDeps): void {
   deps.io.print('');
 }
 
+/** 0.2.29 PERSONA-STARTER — 직업 질문. «경영»이면 경영 스타터 계약 한 장을
+ *  만들고, 일반이면 계약 없이 현재 흐름 그대로. 계약 생성이 실패해도
+ *  wizard 결과는 completed 로 유지한다(fail-soft). */
+async function askOccupationAndCreateStarter(
+  deps: FirstBootWizardDeps,
+  out: { log: (s: string) => void; error: (s: string) => void },
+): Promise<StarterContractSummary | undefined> {
+  const io = deps.io;
+  if (io.nonInteractive) return undefined;
+  io.print('');
+  io.print('  어떤 일을 하세요? 고르면 스타터 계약 한 장을 만듭니다.');
+  io.print('    1) 경영 — 방향·판단·운영을 함께 세우는 경영 스타터');
+  io.print('    2) 일반 — 지금처럼 계속 (스타터 계약 없이)');
+  let answer: string;
+  try {
+    answer = await io.ask('  선택 (1/2 · Enter=일반): ');
+  } catch (err) {
+    out.error(`first-boot wizard: occupation question failed: ${(err as Error).message}`);
+    return undefined;
+  }
+  if (normalizeOccupationChoice(answer) !== 'management') return undefined;
+  try {
+    const written = createManagementStarterContract(
+      deps.starterContractDir ? { dir: deps.starterContractDir } : {},
+    );
+    io.print(`  ✓ 경영 스타터 계약이 만들어졌습니다: ${written.path}`);
+    return { personaId: written.personaId, displayName: written.displayName, path: written.path };
+  } catch (err) {
+    out.error(`first-boot wizard: starter contract failed: ${(err as Error).message}`);
+    return undefined;
+  }
+}
+
 export async function runFirstBootWizard(
   deps: FirstBootWizardDeps,
 ): Promise<FirstBootResult> {
@@ -127,5 +179,7 @@ export async function runFirstBootWizard(
     }
   }
 
-  return { action: 'completed', stepsRun };
+  const starterContract = await askOccupationAndCreateStarter(deps, out);
+
+  return { action: 'completed', stepsRun, ...(starterContract ? { starterContract } : {}) };
 }

package/src/nexus/state/state.ts

@@ -104,6 +104,7 @@ export interface NexusEvent {
     // FeedbackEnvelope so `<StatusChip>` hydrates wherever chat is
     // rendered (PWA tab · iOS native · future Telegram bot).
     | 'agent.status'
+    | 'ta.repair.completed'
     // PLAN-chat-hud-multi-surface-port-2026-05-13 §4 M2 — HudStore
     // (process-wide HUD segment map) lifecycle. The bridge in
     // `hud-event-bridge.ts` subscribes to the store and publishes one

package/src/oauth/codex-account-store.ts

@@ -17,6 +17,7 @@ import {
 import { authStorePath, defaultCodexHome, isUnderTestRunner, listProviders, loadTokens, saveTokens } from './store.js';
 import { readFreshAvailabilityState, quotaSignalDir, readQuotaSignal, readQuotaSignalCredits, readQuotaSignalUsedPercent, readQuotaSignalObservedAt, readQuotaSignalObservedAtRaw } from '../budget/codex-reset-credit-state.js';
 import { creditPaceStatus } from '../budget/codex-credit-pace.js';
+import { noteCodexBillingDecision, type CodexCreditSpendReason } from './codex-billing-route.js';
 import { loadLlmPolicy } from '../policy/llm-policy.js';
 import { getUserConfig } from '../user-config.js';
 import {
@@ -204,6 +205,8 @@ interface RunPin {
   readonly resolution: CodexAccountResolution;
   /** ⛔ 핀이 «갇혔는지»를 싸게 재려면 그 계정의 홈이 필요하다. 모르면 재지 못하므로 그대로 둔다. */
   readonly home: string | undefined;
+  /** 핀을 박은 판정이 크레딧 소진이었나 — 핀으로 돌려줄 때도 과금 경로를 같이 남긴다. */
+  readonly creditReason?: CodexCreditSpendReason;
 }
 const pinnedByRun = new Map<string, RunPin>();
 /** ⛔ 상한 — 장수 프로세스에서 runId 수만큼 «영구히» 자라면 안 된다(리뷰 should-fix).
@@ -213,6 +216,8 @@ const PIN_MAX = 256;
 /** ⛔ 테스트 심 — 고정을 푼다. 프로덕션에서는 부르지 않는다. */
 export function _resetCodexRotationPinForTesting(): void {
   pinnedByRun.clear();
+  // 판정이 남긴 과금 경로도 같이 푼다 — 안 풀면 다음 시험 파일의 codex usage 가 credit 으로 읽힌다.
+  noteCodexBillingDecision(undefined);
 }
 
 /** ⛔⭐⭐ 후보 조립은 «한 자»여야 한다 — 실행 경로와 조회(dry-run)가 다른 자를 쓰면
@@ -728,7 +733,7 @@ export function resolveCodexAccountForRun(
   const explicit = Boolean(env.ELANOUS_CODEX_ACCOUNT?.trim());
   // ⛔⭐ 사람이 «명시»했으면 고정보다 «먼저» 이긴다(결정 ③) — 고정을 읽지도 쓰지도 않는다.
   //   고정이 앞서면, 앞선 호출이 만든 회전 결과가 「명시한 계정」을 덮는다.
-  if (explicit) { observeRotation({ reason: 'explicit' }, current.name); return current; }
+  if (explicit) { observeRotation({ reason: 'explicit' }, current.name); noteCodexBillingDecision(undefined); return current; }
   // ⛔⭐⭐⭐ 설정 판정이 «핀보다 먼저»다(리뷰 must-fix).
   //   핀을 먼저 보면, 같은 런에서 이미 회전·핀된 뒤 설정이 false 로 바뀌어도
   //   ***계속 회전 계정을 돌려준다*** — 「config false 로만 꺼진다」가 핀 경유로 깨진다.
@@ -736,6 +741,7 @@ export function resolveCodexAccountForRun(
   const enabled = rotationConfig.enabled;
   if (!enabled) {
     observeRotation({ reason: 'disabled', disabledProvenance: rotationConfig.state }, current.name);
+    noteCodexBillingDecision(undefined);
     return current;
   }
   // ⛔⭐⭐⭐ 고정은 «런 신원이 있을 때만» 한다.
@@ -763,7 +769,7 @@ export function resolveCodexAccountForRun(
       //   🔑 전환은 «소진당 한 번»으로 갇히고, 그 뒤 다시 핀이 박힌다.
       const pinnedHome = pinned.home;
       const exhausted = pinnedHome !== undefined && pinnedAccountExhausted(pinnedHome, pinned.resolution.name);
-      if (!exhausted) return pinned.resolution;
+      if (!exhausted) { noteCodexBillingDecision(pinned.creditReason); return pinned.resolution; }
       pinnedByRun.delete(runKey);
       debug.log('oauth.codex-account', 'pin-released',
         { account: pinned.resolution.name, why: 'threshold-reached' }, { level: 'warn' });
@@ -806,6 +812,8 @@ export function resolveCodexAccountForRun(
   // CREDIT-SPEND-ORDER(10-12) — «다른 계정의 선불 크레딧으로 옮김»(`rotated` ⊕ creditEntry)도 크레딧 진입이다.
   const creditSpendReason = decision.reason === 'credits-allowed' || decision.reason === 'credit-pace' ? decision.reason
     : decision.reason === 'rotated' && decision.creditEntry ? 'credits-rotated' as const : undefined;
+  // CREDIT-BILLING-LABEL(10-14) — 이 판정으로 나가는 호출의 `llm.usage` 가 `billing='credit'` 이 되게 남긴다.
+  noteCodexBillingDecision(creditSpendReason);
   if (creditSpendReason && !deps.counterPath && isUnderTestRunner(process.env)) {
     // 시험 러너 가드(autoConsume 의 test-runtime-guard 와 같은 관용구) — 카운터를 주입 안 한 시험이 실제 카운터·송신기에 닿지 않는다.
     debug.log('oauth.codex-account', 'credit-spend-alert-skipped', { account: decision.to?.name ?? current.name, reason: 'test-runtime-guard' });
@@ -833,7 +841,11 @@ export function resolveCodexAccountForRun(
       const oldest = pinnedByRun.keys().next().value;
       if (oldest !== undefined) pinnedByRun.delete(oldest);
     }
-    pinnedByRun.set(runKey, { resolution: resolved, home: effectiveCodexHome(resolved, loadTokens(resolved.storeKey, path), env).home });
+    pinnedByRun.set(runKey, {
+      resolution: resolved,
+      home: effectiveCodexHome(resolved, loadTokens(resolved.storeKey, path), env).home,
+      ...(creditSpendReason ? { creditReason: creditSpendReason } : {}),
+    });
   }
   return resolved;
 }

package/src/oauth/codex-billing-route.ts

@@ -0,0 +1,31 @@
+/**
+ * codex 호출의 «과금 경로» 기억 — 회전 판정이 크레딧 소진을 정했으면 그 호출의 `llm.usage` 가 `billing='credit'` 이다.
+ *
+ * 🩸 10-14 운영 실측: 세 계정이 주간 100% 라 회전이 `credits-allowed` 로 default 계정 크레딧을 쓰는데,
+ *   같은 턴의 `llm.usage` 는 `billing=subscription` · `cost.kind=included($0)` 였다 — 원장·토큰 경보가 크레딧 지출을 $0 로 봤다.
+ *   자격 종류(oauth)만으로 과금 경로를 정하면 «구독 한도를 넘어 크레딧으로 나간 호출»을 구분 못 한다.
+ *
+ * 경로: `loadFreshCodexAuthState` → `resolveCodexAccountForRun`(요청마다 · 판정·핀) → 여기 기록
+ *   → 응답 끝 `logAgentTurnUsage` → `billingRouteForProvider('openai-codex')` 가 여기를 읽는다.
+ * ⚠️ 프로세스 단위 «마지막 판정»이다 — 같은 프로세스에서 다른 런이 동시에 다른 판정을 내리면 섞일 수 있다
+ *   (판정은 같은 스토어·설정을 읽으므로 보통 같은 답이다).
+ */
+
+export type CodexCreditSpendReason = 'credits-allowed' | 'credit-pace' | 'credits-rotated';
+
+let lastCreditReason: CodexCreditSpendReason | undefined;
+
+/** 계정 해석이 끝날 때마다 부른다 — 크레딧 소진이 아니면 `undefined` 로 지운다(앞 판정이 남지 않게). */
+export function noteCodexBillingDecision(reason: CodexCreditSpendReason | undefined): void {
+  lastCreditReason = reason;
+}
+
+/** 마지막 codex 계정 해석이 크레딧 소진이었으면 그 이유. */
+export function codexCreditSpendReason(): CodexCreditSpendReason | undefined {
+  return lastCreditReason;
+}
+
+/** ⛔ 테스트 심 — 프로덕션에서는 부르지 않는다. */
+export function _resetCodexBillingDecisionForTesting(): void {
+  lastCreditReason = undefined;
+}

package/src/oauth/store.ts

@@ -27,10 +27,10 @@
 
 import {
   existsSync, readFileSync, writeFileSync, mkdirSync, renameSync,
-  chmodSync, realpathSync,
+  chmodSync, lstatSync, readlinkSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, dirname, basename, resolve } from 'node:path';
+import { join, dirname, parse, resolve, sep } from 'node:path';
 import { extractChatGPTClaims, decodeJWTPayload, type ChatGPTClaims } from './jwt.js';
 import { debug } from '../debug/log.js';
 import { isCodexStoreKey } from './codex-account.js';
@@ -347,12 +347,37 @@ export function listProviders(path: string = authStorePath()): string[] {
 /** 두 경로가 «실체로» 같은 파일인가. ⛔ 문자열 비교로는 심볼릭 링크가 가드를 통과한다
  *  (`CODEX_HOME` 이 `~/.codex` 로 가는 링크면 resolve() 결과가 다르다 · 리뷰 must-fix).
  *  ⚠️ 파일이 아직 없을 수 있으므로 «부모까지» 실체화하고 이름을 붙인다. */
+export function resolveMirrorGuardPath(path: string): string {
+  let candidate = resolve(path);
+  const visited = new Set<string>();
+  for (let hop = 0; hop < 40; hop++) {
+    if (visited.has(candidate)) throw new Error('mirror path symlink cycle');
+    visited.add(candidate);
+    const root = parse(candidate).root;
+    const parts = candidate.slice(root.length).split(sep).filter(Boolean);
+    let prefix = root;
+    let expanded = false;
+    for (const [index, part] of parts.entries()) {
+      const next = join(prefix, part);
+      let link = false;
+      try { link = lstatSync(next).isSymbolicLink(); }
+      catch (error) {
+        if (!['ENOENT', 'ENOTDIR'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+      }
+      if (link) {
+        candidate = resolve(dirname(next), readlinkSync(next), ...parts.slice(index + 1));
+        expanded = true;
+        break;
+      }
+      prefix = next;
+    }
+    if (!expanded) return candidate;
+  }
+  throw new Error('mirror path symlink depth exceeded');
+}
+
 function sameRealFile(a: string, b: string): boolean {
-  const norm = (p: string): string => {
-    try { return realpathSync(p); } catch { /* 아직 없다 — 부모로 내려간다 */ }
-    try { return join(realpathSync(dirname(p)), basename(p)); } catch { return resolve(p); }
-  };
-  return norm(a) === norm(b);
+  return resolveMirrorGuardPath(a) === resolveMirrorGuardPath(b);
 }
 
 /** ⛔ 테스트 러너 판정 — 이 값이 «거짓»이면 가드는 영영 안 도는 장식이 된다.

package/src/onboarding/first-run.ts

@@ -27,13 +27,38 @@ export function orderProviderChoices(detected: readonly LLMProviderName[] = []):
   return [...detected, ...CHOICE_BASE.filter((name) => !detected.includes(name))];
 }
 
-async function chooseProvider(detected: readonly LLMProviderName[] = []): Promise<LLMProviderName | null> {
+export type MenuAnswer =
+  | { kind: 'chosen'; provider: LLMProviderName }
+  | { kind: 'cancel' }
+  | { kind: 'miss' };
+
+// FIRST10-FIX: 첫 화면의 오타 한 번이 first-run 전체를 취소하던 마찰 — 빈 입력(취소 의사)과 달리
+// 선택지를 가리키지 못하는 입력(오타·범위 밖·전각 숫자)은 취소가 아니라 다시 묻는다.
+export function parseMenuAnswer(answer: string, choices: readonly LLMProviderName[]): MenuAnswer {
+  const trimmed = answer.trim();
+  if (trimmed === '') return { kind: 'cancel' };
+  const index = Number(trimmed) - 1;
+  const provider = Number.isInteger(index) && index >= 0 ? choices[index] : undefined;
+  return provider !== undefined ? { kind: 'chosen', provider } : { kind: 'miss' };
+}
+
+export async function promptProviderMenu(
+  ask: (prompt: string) => Promise<string>,
+  detected: readonly LLMProviderName[] = [],
+): Promise<LLMProviderName | null> {
   const choices = orderProviderChoices(detected);
   const menu = choices.map((name, i) => `${i + 1} ${CHOICE_LABEL[name] ?? name}`).join(', ');
+  for (;;) {
+    const parsed = parseMenuAnswer(await ask(`Choose LLM (${menu}; Enter to cancel): `), choices);
+    if (parsed.kind === 'chosen') return parsed.provider;
+    if (parsed.kind === 'cancel') return null;
+  }
+}
+
+async function chooseProvider(detected: readonly LLMProviderName[] = []): Promise<LLMProviderName | null> {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   try {
-    const answer = (await rl.question(`Choose LLM (${menu}; Enter to cancel): `)).trim();
-    return choices[Number(answer) - 1] ?? null;
+    return await promptProviderMenu((prompt) => rl.question(prompt), detected);
   } finally {
     rl.close();
   }

package/src/ops/overview-cache.ts

@@ -106,10 +106,10 @@ export function createOverviewCache(deps: {
     podTimer = schedule(() => { void refreshPods(); }, POD_MS);
     podTimer.unref();
   };
-  const present = (entry: Entry): OverviewData => {
-    const at = now();
+  /** Response-time Pod occupancy overlay — shared by /v1/ops/overview and /v1/ops/resources. */
+  const overlayPods = (snapshot: OverviewSnapshot, at: number): PodMemberRow[] => {
     const byContext = new Map(podRows.map((row) => [row.context, row]));
-    const pods: PodMemberRow[] = entry.snapshot.machines.pods.map((pod) => {
+    return snapshot.machines.pods.map((pod) => {
       const row = byContext.get(pod.context);
       const stale = row && at - row.observedAt >= POD_STALE_MS;
       const occupied = !podFailure && row && !stale && row.occupied !== null
@@ -117,11 +117,23 @@ export function createOverviewCache(deps: {
         : unmeasured<number>('pod pool background measure', podFailure ?? (stale ? '낡음(120초)' : row?.reason ?? '측정 대기'), row ? new Date(row.observedAt).toISOString() : null);
       return { ...pod, occupied };
     });
+  };
+  const present = (entry: Entry): OverviewData => {
+    const at = now();
+    const pods = overlayPods(entry.snapshot, at);
     const full = { ...entry.snapshot, machines: { ...entry.snapshot.machines, pods } };
     return { ...full, ...computeVerdict(full), durationMs: entry.durationMs,
       sources: [full.release.run.source, full.tasks.launchable.source, full.tasks.capacity.source],
       cacheAgeMs: Math.max(0, at - entry.at), refreshFailed: entry.failure ?? null };
   };
+  /** Read-only view of the freshest memo entry (RES-FLOOR-API) — never collects, never measures, never waits. */
+  const peek = (): { snapshot: OverviewSnapshot; pods: PodMemberRow[]; at: number } | null => {
+    let freshest: Entry | null = null;
+    for (const entry of memo.values()) if (!freshest || entry.at > freshest.at) freshest = entry;
+    if (!freshest) return null;
+    const at = now();
+    return { snapshot: freshest.snapshot, pods: overlayPods(freshest.snapshot, at), at };
+  };
   const get = async (options: Pick<CollectOptions, 'version' | 'owner'> & { sinceMs?: number; sinceLabel?: string } = {}): Promise<OverviewData> => {
     start();
     const key = JSON.stringify([options.version ?? null, options.owner ?? null, options.sinceMs ?? 3_600_000]);
@@ -171,5 +183,5 @@ export function createOverviewCache(deps: {
     }
     return present(memo.get(key)!);
   };
-  return { get, memoSize: () => memo.size, stop: () => { if (podTimer) clearInterval(podTimer); podTimer = null; memo.clear(); } };
+  return { get, peek, memoSize: () => memo.size, stop: () => { if (podTimer) clearInterval(podTimer); podTimer = null; memo.clear(); } };
 }

package/src/ops/overview-collect.ts

@@ -10,7 +10,8 @@ import { effectiveInstanceRoot } from '../instance/resolve.js';
 import type { Checklist, ChecklistItem } from '../release-loop/checklist.js';
 import type { ReleaseSchedule } from '../release-loop/release-schedule.js';
 import type { ResourceView } from '../control-plane/ledger.js';
-import type { TaskCard } from '../task-agent/task-hand.js';
+import { cardPrNumber, type TaskCard } from '../task-agent/task-hand.js';
+import { measureLandingThroughput, type LandingThroughput } from '../task-agent/cover.js';
 import {
   okCell, unmeasured, type Cell, type CapacityInfo, type ChecklistCounts, type LaunchableInfo, type LoopRow, type MachineRow,
   type OverviewSnapshot, type OwnerTaskRow, type ParentsInfo, type PodMemberRow, type ReleaseRunInfo, type ScheduleInfo,
@@ -269,6 +270,22 @@ export async function collectOverview(opts: CollectOptions, injected: CollectDep
   const byOwner: Cell<Record<string, OwnerTaskRow>> = cards instanceof Error
     ? unmeasured('task-agent ledger', errText(cards))
     : okCell(ownerRows(cards, kstMidnight, opts.owner), `task-agent ledger(오늘 KST · owner=seat 키)`, iso(now));
+  const launchedCards = cards instanceof Error ? [] : cards.filter((card) => card.createdAt >= kstMidnight && card.status === 'launched');
+  const throughput = cards instanceof Error
+    ? unmeasured<LandingThroughput>('task-agent ledger', errText(cards))
+    : okCell(measureLandingThroughput({
+      launched: launchedCards.length,
+      cardPrs: launchedCards.filter((card) => cardPrNumber(card) !== undefined).length,
+      taskAgentActions: launchedCards.flatMap((card) => (card.landAttempts ?? [])
+        .filter((attempt) => attempt.at >= kstMidnight)
+        .map((attempt) => ({
+          kind: 'land' as const,
+          result: attempt.ok === true ? 'done' : attempt.ok === false ? 'failed' : 'pending',
+          reason: attempt.reason ?? attempt.detail,
+        }))),
+      allLands: null,
+      pendingLandingAgeSeconds: null,
+    }), 'task-agent ledger(오늘 KST · landAttempts)', iso(now));
   const done = unmeasured<number>('task-agent ledger', '착지 판정은 PR 조회가 필요 — owner 모델(OVW-OWNER)·card-evidence 연결 전');
 
   // 발사 가능 — 열린 판(앞으로의 컷) 전부.
@@ -334,7 +351,7 @@ export async function collectOverview(opts: CollectOptions, injected: CollectDep
       beat: okCell({ lastAt: b.lastAt, ageSeconds: b.ageSeconds, alive: b.alive }, `${SEAT_ERA_SOURCE} dispatcher-${b.seat}.pid`, b.lastAt) });
   }
 
-  return { generatedAt: iso(now), instanceRoot: root, since: opts.sinceLabel, release, tasks, machines, landings, loops };
+  return { generatedAt: iso(now), instanceRoot: root, since: opts.sinceLabel, release, tasks, machines, landings, throughput, loops };
 }
 
 export function parseSince(raw: string | undefined): { ms: number; label: string } {

package/src/ops/resources.ts

@@ -0,0 +1,82 @@
+/**
+ * RES-FLOOR-API — «자원 지도» 접기(순수 층). I/O 0 · kubectl/ssh 0 · 새 수집 0.
+ * 이미 도는 overview 캐시의 메모 스냅숏과 응답 때 얹는 Pod 점유를 PWA 자원 지도 꼴로 접는다.
+ * 설계: 칸 RES-FLOOR-API(0.2.28) — 호스트별 load·mem · Pod 슬롯 · 칸마다 observedAt · 빠진 칸은 missing 사유.
+ */
+import type { Cell, MachineLoad, OverviewSnapshot, PodMemberRow } from './overview.js';
+
+export interface ResourceCell<T> {
+  value: T | null;
+  observedAt: string | null;
+  /** value 가 없는 칸의 사유 — 측정됐으면 null */
+  missing: string | null;
+}
+
+export interface HostResourcesRow {
+  name: string;
+  load1: ResourceCell<number>;
+  load5: ResourceCell<number>;
+  load15: ResourceCell<number>;
+  cpuCount: ResourceCell<number>;
+  memFreeGb: ResourceCell<number>;
+  memTotalGb: ResourceCell<number>;
+}
+
+export interface PodSlotRow {
+  context: string;
+  capacity: number;
+  occupied: ResourceCell<number>;
+}
+
+export interface ResourcesMap {
+  /** 접은 스냅숏의 시각(overview generatedAt) */
+  generatedAt: string;
+  /** 이 읽기 시각 */
+  readAt: string;
+  hosts: HostResourcesRow[];
+  pods: PodSlotRow[];
+  /** 구조적으로 통째로 빈 칸의 사유(호스트 원장 비어 있음 · 풀 설정 없음) */
+  missing: string[];
+}
+
+const NO_REASON = '사유 없음';
+
+function fold<T>(source: Cell<T>): ResourceCell<T> {
+  const measured = source.status !== 'unmeasured' && source.value !== null;
+  return { value: measured ? source.value : null, observedAt: source.observedAt, missing: measured ? null : source.reason ?? NO_REASON };
+}
+
+/** 호스트의 모든 숫자 칸은 같은 하트비트 cell 에서 나오니 observedAt·missing 도 함께 접힌다. */
+function hostRow(host: OverviewSnapshot['machines']['hosts'][number]): HostResourcesRow {
+  const load = fold(host.load);
+  const num = (pick: (l: MachineLoad) => number): ResourceCell<number> => load.value !== null
+    ? { value: pick(load.value), observedAt: load.observedAt, missing: null }
+    : { value: null, observedAt: load.observedAt, missing: load.missing };
+  return {
+    name: host.name,
+    load1: num((l) => l.load1),
+    load5: num((l) => l.load5),
+    load15: num((l) => l.load15),
+    cpuCount: num((l) => l.cpuCount),
+    memFreeGb: num((l) => l.freeGb),
+    memTotalGb: num((l) => l.totalGb),
+  };
+}
+
+export function resourcesFromOverview(snapshot: OverviewSnapshot, pods: readonly PodMemberRow[], now: number): ResourcesMap {
+  const byContext = new Map(pods.map((pod) => [pod.context, pod]));
+  const missing: string[] = [];
+  if (snapshot.machines.hosts.length === 0) missing.push('hosts: 하트비트 원장 비어 있음');
+  if (snapshot.machines.pods.length === 0) missing.push('pods: 풀 설정 없음');
+  return {
+    generatedAt: snapshot.generatedAt,
+    readAt: new Date(now).toISOString(),
+    hosts: snapshot.machines.hosts.map(hostRow),
+    pods: snapshot.machines.pods.map((pod): PodSlotRow => ({
+      context: pod.context,
+      capacity: pod.capacity,
+      occupied: fold((byContext.get(pod.context) ?? pod).occupied),
+    })),
+    missing,
+  };
+}