elanous 0.2.15 → 0.2.17

package/src/cli/self-update.ts

@@ -1,10 +1,14 @@
-import { existsSync, readFileSync, realpathSync, readlinkSync, readdirSync, statSync, rmSync, symlinkSync, renameSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, readlinkSync, readdirSync, statSync, rmSync, symlinkSync, renameSync, writeFileSync, lstatSync } from 'node:fs';
 import { resolve, join, basename, dirname } from 'node:path';
 import { homedir, platform, userInfo } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { decideRestartNeeded, type RestartNeededResult } from './nexus-restart-needed.js';
 import { debug } from '../debug/log.js';
 import { envLiteral } from '../platform/env-literal.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { getUserConfig } from '../user-config.js';
+import { planEdgeRail, type EdgeRailInput, type EdgeRailPlan } from './self-update-canary.js';
+import { loadRunLedger } from '../self-implement/run-ledger.js';
 
 export interface SelfUpdateOptions {
   from?: string;
@@ -18,6 +22,18 @@ export interface SelfUpdateOptions {
   skipPwaBuild?: boolean;
   /** 설치된 릴리스에서만 사용한다. 체크아웃 갱신에는 적용하지 않는다. */
   version?: string;
+  /** 판 사이 dev 빌드 설치 — versions/<판>-dev.<sha12> · install.json channel:'dev'. 사람 승인 명령. */
+  dev?: boolean;
+  /** install.json 의 이전 versionDir 로 current 를 되돌린다. 이전이 없으면 거부. */
+  rollback?: boolean;
+  /** Canary rollout action; legacy --auto on|off|status is handled by the CLI scheduler. */
+  auto?: boolean;
+  dryRun?: boolean;
+  seat?: string;
+  quietWindow?: boolean;
+  failureRate?: EdgeRailInput['failureRate'];
+  /** Unique ID of an independently successful canary run; no id means no new run. */
+  canaryRunId?: string;
 }
 
 export interface SelfUpdateDeps {
@@ -26,6 +42,8 @@ export interface SelfUpdateDeps {
   decide?: (opts: { to: string; cwd: string; out: { log: (s: string) => void; error: (s: string) => void } }) => Promise<RestartNeededResult>;
   run?: (command: string, args: string[], cwd: string, options?: { timeout?: number }) => { status: number | null; stderr: string; stdout?: string };
   installedVersion?: () => string;
+  /** 캐너리 시작 «뒤»에 시작해 `completed` 로 끝난 런인가(주입 안 하면 런 원장 `canaryRunSucceededInLedger`). */
+  canaryRunSucceeded?: (runId: string, sinceIso: string) => boolean;
   /** 재시작 뒤 데몬이 이 커밋으로 떴나(주입 안 하면 `/v1/health` 를 최대 90초 폴링). */
   verifyRestart?: (expectedCommit: string) => Promise<VerifyRestartResult>;
   /** 판 목록(이름) — 되돌릴 판 찾기. */
@@ -45,6 +63,22 @@ export interface SelfUpdateDeps {
   out?: { log: (s: string) => void; error: (s: string) => void };
   /** 판올림 성공 알림(주입 안 하면 sendOutbound 'report' · 시험에선 안 보냄). */
   notice?: (text: string) => void;
+  /**
+   * 설치 루트(versions · current · install.json). 주입하지 않으면 ~/.local/share/elanous.
+   * 시험은 임시 루트만 넘긴다 — 실물 심링크·재시작을 만지지 않는다.
+   */
+  installRoot?: string;
+  /** 패키지 버전(package.json). 주입하지 않으면 체크아웃 package.json. */
+  packageVersion?: (checkout: string) => string;
+  /** 재시작을 실제로 호출해도 되는지. NODE_ENV=test · ELANOUS_TEST_HOME 이면 기본 false. */
+  allowLiveRestart?: boolean;
+  /** Automatic edge-rail inputs; injected in tests, never a service registration. */
+  now?: () => Date;
+  stateDir?: string;
+  edgeRailConfig?: () => Pick<EdgeRailInput, 'canaryOkRuns' | 'failureMultiplier' | 'minSamples'>;
+  installEdgeRail?: (options: SelfUpdateOptions, deps: SelfUpdateDeps) => Promise<SelfUpdateResult>;
+  rollbackEdgeRail?: (deps: Pick<SelfUpdateDeps, 'installRoot'>) => ReturnType<typeof rollbackDevInstall>;
+  restartEdgeRail?: () => Promise<boolean>;
 }
 
 export interface SelfUpdateResult {
@@ -63,11 +97,21 @@ export interface SelfUpdateResult {
   prune?: VersionPruneOutcome;
   /** 재시작 뒤 건강 — ok · rolled-back(직전 판으로 되돌려 회복) · rollback-failed · no-rollback-target. */
   health?: 'ok' | 'rolled-back' | 'rollback-failed' | 'no-rollback-target' | 'unmeasured';
+  /** --dev 설치 또는 --rollback 이 옮긴 current 대상(versions/<name>). */
+  current?: string;
+  /** install.json channel. dev 설치면 'dev'. */
+  channel?: string;
+  /** --dev 가 남긴 이전 versionDir. */
+  previous?: string;
   rolledBackTo?: string;
   /** relay(`com.elanous.openai-relay`) 판정 — 넥서스와 «따로» 본다(T5 · 2026-09-24). */
   relay?: RelayUpdateOutcome;
   /** 텔레그램 러너(`com.elanous.telegram` · `elanous-telegram.service`) 판정 — 🆕 2026-09-25. */
   telegramRunner?: RelayUpdateOutcome;
+  edgeRail?: EdgeRailPlan;
+  missingFixes?: string;
+  /** 실패율 측정 원천이 없으면 자동 되돌림이 판단되지 않는다 — 측정 원천은 다음 조각(EDGE-RAIL2 범위 밖). */
+  autoRollback?: 'active' | 'inactive-no-failure-rate';
 }
 
 export interface RelayUpdateOutcome {
@@ -182,6 +226,142 @@ export function rollbackTarget(versions: readonly string[], daemonSha: string, i
 
 const VERSIONS_DIR = () => join(homedir(), '.local/share/elanous/versions');
 
+/** 시험·ELANOUS_TEST_HOME 에서는 실물 재시작을 호출하지 않는다. */
+export function liveRestartBlocked(env: NodeJS.ProcessEnv = process.env): boolean {
+  return env.NODE_ENV === 'test' || Boolean(env.ELANOUS_TEST_HOME?.trim());
+}
+
+export interface InstallRecord {
+  version?: string;
+  versionDir?: string;
+  source?: string;
+  installedAt?: string;
+  commit?: string;
+  channel?: string;
+  previous?: string;
+}
+
+export function defaultInstallRoot(): string {
+  return join(homedir(), '.local/share/elanous');
+}
+
+export function readInstallRecord(root: string): InstallRecord | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(root, 'install.json'), 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    return parsed as InstallRecord;
+  } catch {
+    return null;
+  }
+}
+
+/** install.json 의 version·commit. 못 읽으면 둘 다 «unknown». */
+export function readInstalledIdentity(root: string = defaultInstallRoot()): { installedVersion: string; installedCommit: string } {
+  const record = readInstallRecord(root);
+  const version = typeof record?.version === 'string' && record.version.trim() ? record.version.trim() : '';
+  const commit = typeof record?.commit === 'string' && record.commit.trim() ? record.commit.trim() : '';
+  return { installedVersion: version || 'unknown', installedCommit: commit || 'unknown' };
+}
+
+const VERSION_DIR_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function versionDirName(versionDir: string | undefined): string | null {
+  if (typeof versionDir !== 'string') return null;
+  if (!/^versions\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(versionDir) || versionDir.includes('..')) return null;
+  return basename(versionDir);
+}
+
+/** 판 디렉터리에 실행 진입 파일이 있나(설치기가 실제로 내용을 깔았나). */
+export function installEntryExists(root: string, versionName: string): boolean {
+  return existsSync(join(root, 'versions', versionName, 'node_modules', 'elanous', 'bin', 'elanous.mjs'));
+}
+
+/** 판 이름 «<판>-<커밋12>» · «<판>-dev.<커밋12>» 에서 판·커밋을 읽는다(되돌림 메타 일치용). */
+export function parseVersionDirName(name: string): { version: string; commit: string } | null {
+  const m = /^(.+?)-(?:dev\.)?([0-9a-f]{12})(?:-dirty)?$/.exec(name);
+  return m ? { version: m[1]!, commit: m[2]! } : null;
+}
+
+/** current 심링크를 versions/<name> 으로 원자적으로 옮긴다. 대상 폴더가 없으면 거부. */
+export function relinkInstallCurrent(root: string, versionName: string): void {
+  if (!VERSION_DIR_NAME.test(versionName) || versionName.includes('..')) throw new Error(`잘못된 판 이름: ${versionName}`);
+  if (!existsSync(join(root, 'versions', versionName))) throw new Error(`판 디렉터리 없음: ${versionName}`);
+  // EDGE-RAIL-VERIFY(10-06 05:30 사고): 진입 파일이 없는 판으로는 current 를 옮기지 않는다(빈 판 → 전역 elanous·크론 전부 실패).
+  if (!installEntryExists(root, versionName)) throw new Error(`빈 판(진입 파일 없음): ${versionName} — current 를 옮기지 않는다`);
+  const tmp = join(root, `.current-dev-${process.pid}`);
+  rmSync(tmp, { force: true });
+  symlinkSync(`versions/${versionName}`, tmp);
+  renameSync(tmp, join(root, 'current'));
+}
+
+function checkoutPackageVersion(checkout: string): string {
+  const parsed = JSON.parse(readFileSync(join(checkout, 'package.json'), 'utf8')) as { version?: unknown };
+  if (typeof parsed.version !== 'string' || !parsed.version.trim()) throw new Error('package.json version 없음');
+  return parsed.version.trim();
+}
+
+/**
+ * 판 사이 dev 빌드 — versions/<판>-dev.<sha12> 를 만들고 current 를 옮긴다.
+ * install.json 에 channel:'dev' 와 이전 versionDir(previous) 를 남긴다. 실제 설치기·재시작은 부르지 않는다.
+ */
+export function installDevBuild(checkout: string, commit: string, deps: Pick<SelfUpdateDeps, 'installRoot' | 'packageVersion'> & { runInstaller?: () => { status: number | null; stderr: string } } = {}): { versionName: string; versionDir: string; previous: string; record: InstallRecord } {
+  const sha12 = commit.trim().toLowerCase().slice(0, 12);
+  if (!/^[0-9a-f]{12}$/.test(sha12)) throw new Error(`dev 설치 커밋이 12자가 아님: ${commit}`);
+  const root = deps.installRoot ?? defaultInstallRoot();
+  const prior = readInstallRecord(root);
+  const previous = versionDirName(prior?.versionDir) ? prior!.versionDir! : (typeof prior?.previous === 'string' ? prior.previous : '');
+  // EDGE-RAIL-VERIFY: 빈 디렉터리를 만들고 current 만 옮기던 길(10-06 05:30 사고)을 버리고, 정식 길과 같은 설치기로 내용을 깐다.
+  if (!deps.runInstaller) throw new Error('dev 설치기 없음 — 빈 판을 깔지 않는다');
+  // install.sh 는 current 를 «먼저» 옮기고 뒤에서 실패할 수 있다 — 실패·빈 판 어느 쪽이든 이전 판·install.json 으로 되돌린다.
+  const restore = (why: string, versionName: string | null): never => {
+    const previousName = versionDirName(previous);
+    if (previousName && installEntryExists(root, previousName)) relinkInstallCurrent(root, previousName);
+    if (prior) writeFileSync(join(root, 'install.json'), `${JSON.stringify(prior, null, 2)}\n`);
+    try { debug.log('self-update', 'dev-install-refused', { why, versionName, kept: previousName ?? null }); } catch { /* 관측 실패가 막지 않는다 */ }
+    throw new Error(`${why}: ${versionName ?? '?'} — current 를 이전 판(${previousName ?? '없음'})으로 유지`);
+  };
+  let result: { status: number | null; stderr: string };
+  try { result = deps.runInstaller(); }
+  catch (error) { return restore(`설치기 예외(${String(error).slice(0, 200)})`, null); }
+  const after = readInstallRecord(root);
+  const versionName = versionDirName(after?.versionDir);
+  if (result.status !== 0) return restore(`설치기 실패(rc=${result.status}: ${result.stderr.slice(0, 200)})`, versionName);
+  if (!versionName || !installEntryExists(root, versionName)) return restore('빈 판(진입 파일 없음)', versionName);
+  const versionDir = `versions/${versionName}`;
+  const record: InstallRecord = {
+    ...(after ?? {}),
+    versionDir,
+    channel: 'dev',
+    ...(previous && previous !== versionDir ? { previous } : {}),
+  };
+  writeFileSync(join(root, 'install.json'), `${JSON.stringify(record, null, 2)}\n`);
+  return { versionName, versionDir, previous, record };
+}
+
+/** install.json.previous 의 판으로 current 를 되돌린다. previous 가 없으면 거부(exit 2). */
+export function rollbackDevInstall(deps: Pick<SelfUpdateDeps, 'installRoot'> = {}): { ok: true; versionName: string; record: InstallRecord } | { ok: false; reason: string } {
+  const root = deps.installRoot ?? defaultInstallRoot();
+  const prior = readInstallRecord(root);
+  const previousName = versionDirName(prior?.previous);
+  if (!prior || !previousName) return { ok: false, reason: '이전 판(install.json previous)이 없다 — rollback 거부' };
+  if (!existsSync(join(root, 'versions', previousName))) return { ok: false, reason: `이전 판 디렉터리 없음: ${previousName}` };
+  const currentName = versionDirName(prior.versionDir);
+  relinkInstallCurrent(root, previousName);
+  const parsed = parseVersionDirName(previousName);
+  const record: InstallRecord = {
+    ...prior,
+    ...(parsed ? { version: parsed.version, commit: parsed.commit } : {}),
+    versionDir: `versions/${previousName}`,
+    channel: prior.channel === 'dev' ? undefined : prior.channel,
+    previous: currentName ? `versions/${currentName}` : undefined,
+    installedAt: new Date().toISOString(),
+  };
+  if (!record.channel) delete record.channel;
+  if (!record.previous) delete record.previous;
+  writeFileSync(join(root, 'install.json'), `${JSON.stringify(record, null, 2)}\n`);
+  return { ok: true, versionName: previousName, record };
+}
+
 /** `unmeasured` = 건강을 «잴 수» 없었다(REST 주소를 한 번도 못 얻음) — 「건강하지 않다」와 다르다. 되돌리지 않는다. */
 export interface VerifyRestartResult { ok: boolean; daemonSha?: string; reason?: string; unmeasured?: boolean }
 
@@ -399,9 +579,14 @@ export async function runReleaseUpdate(options: ReleaseUpdateOptions = {}, deps:
   }
   let previous = '';
   let previousBuild = '';
+  let replacedDev: { from: string; to: string } | null = null;
   try {
     const metadata: unknown = JSON.parse(readFileSync(join(prefix, 'install.json'), 'utf8'));
     previousBuild = installedBuild(metadata);
+    if (typeof metadata === 'object' && metadata !== null && (metadata as { channel?: unknown }).channel === 'dev') {
+      const fromDir = typeof (metadata as { versionDir?: unknown }).versionDir === 'string' ? (metadata as { versionDir: string }).versionDir : '';
+      replacedDev = { from: fromDir, to: '' };
+    }
     if (typeof metadata === 'object' && metadata !== null && 'versionDir' in metadata && typeof metadata.versionDir === 'string') {
       const dir = metadata.versionDir;
       if (/^versions\/[a-zA-Z0-9._-]+$/.test(dir) && !dir.includes('..')) previous = basename(dir);
@@ -418,6 +603,12 @@ export async function runReleaseUpdate(options: ReleaseUpdateOptions = {}, deps:
     const installedVersion = typeof metadata === 'object' && metadata !== null && 'version' in metadata && typeof metadata.version === 'string'
       ? metadata.version : null;
     if (!installedVersion) return fail(1, '설치판 확인 실패: install.json version 없음');
+    if (replacedDev) {
+      const toDir = typeof metadata === 'object' && metadata !== null && typeof (metadata as { versionDir?: unknown }).versionDir === 'string'
+        ? (metadata as { versionDir: string }).versionDir : installedVersion;
+      replacedDev = { from: replacedDev.from, to: toDir };
+      try { debug.log('self-update', 'dev-replaced', replacedDev); } catch { /* 관측 실패가 갱신을 막지 않는다 */ }
+    }
     const internalRevision = isTailnet(source) && version?.match(/^(.*)-([0-9a-f]{12})$/);
     if (version && installedVersion !== version && (!internalRevision || installedVersion !== internalRevision[1])) {
       return fail(1, `설치판 버전 불일치: 요청 ${version}, 설치 ${installedVersion}`);
@@ -462,12 +653,186 @@ function readInstallSource(cliRoot: string, exists: (path: string) => boolean, r
   }
 }
 
+/** Output only; never uses a title to decide whether to install. */
+export function missingFixCommitTitles(checkout: string, installed: string, main: string, git: NonNullable<SelfUpdateDeps['git']>): string {
+  if (!/^[a-f0-9]{12,40}$/i.test(installed) || !/^[a-f0-9]{12,40}$/i.test(main)) return 'main 엔 있고 운영엔 없는 수리: 판정 불가';
+  const result = git(checkout, ['log', '--format=%s', '--no-merges', `${installed}..${main}`]);
+  if (result.status !== 0) return 'main 엔 있고 운영엔 없는 수리: 판정 불가';
+  const titles = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => /\bfix(?:es|ed)?\b|(?:^|[(:])fix[:)]/i.test(line))
+    .map((line) => line.replace(/[\r\n\t]+/g, ' ').slice(0, 160)).slice(0, 10);
+  return `main 엔 있고 운영엔 없는 수리: ${titles.length ? titles.join(' · ') : '없음'}`;
+}
+
+interface EdgeRailState { canary: NonNullable<EdgeRailInput['canary']>; mainCommit: string; lastRunId?: string; countedRunIds?: string[]; failureRate?: NonNullable<EdgeRailInput['failureRate']>; promoted?: boolean; rolledBack?: boolean }
+
+function saveEdgeRailState(file: string, state: EdgeRailState): void {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  renameSync(tmp, file);
+}
+
+/** 런 원장에서: `start` 가 캐너리 시작 이후이고 마지막 `run-status` 가 `completed` 인 런만 참. 못 읽으면 거짓. */
+export function canaryRunSucceededInLedger(runId: string, sinceIso: string, dir?: string): boolean {
+  try {
+    const entries = (dir ? loadRunLedger(runId, dir) : loadRunLedger(runId)) ?? [];
+    const started = Date.parse(entries.find((entry) => entry.event === 'start')?.timestamp ?? '');
+    const last = entries.filter((entry) => entry.event === 'run-status').at(-1);
+    return Number.isFinite(started) && started >= Date.parse(sinceIso) && last?.data.runStatus === 'completed';
+  } catch { return false; }
+}
+
+async function restartEdgeRail(deps: SelfUpdateDeps, checkout: string): Promise<boolean> {
+  if (deps.restartEdgeRail) return deps.restartEdgeRail();
+  if (deps.allowLiveRestart === false || (deps.allowLiveRestart !== true && liveRestartBlocked())) return false;
+  const os = deps.os ?? platform();
+  const command = os === 'darwin' ? 'launchctl' : os === 'linux' ? 'systemctl' : null;
+  if (!command) return false;
+  const args = os === 'darwin' ? ['kickstart', '-k', `gui/${deps.uid ?? process.getuid?.() ?? userInfo().uid}/com.elanous.nexus`] : ['--user', 'restart', 'elanous-nexus'];
+  return (deps.run ?? execute)(command, args, checkout).status === 0;
+}
+
+export async function runEdgeRailUpdate(options: SelfUpdateOptions, deps: SelfUpdateDeps = {}): Promise<SelfUpdateResult> {
+  const out = deps.out ?? console;
+  const root = deps.installRoot ?? defaultInstallRoot();
+  const record = readInstallRecord(root);
+  const checkout = resolve(options.from ?? record?.source ?? deps.cliRoot ?? resolve(import.meta.dir, '../..'));
+  const stateFile = join(deps.stateDir ?? elanousStateRoot(), 'self-update-edge-rail.json');
+  const git = deps.git ?? ((cwd: string, args: string[]) => execute('git', args, cwd));
+  const fail = (reason: string): SelfUpdateResult => {
+    const result: SelfUpdateResult = { exitCode: 2, installedVersion: null, decision: null, restarted: false, reason };
+    out.log(options.json ? JSON.stringify(result) : `self-update --auto: hold — ${reason}`);
+    return result;
+  };
+  if (options.dev || options.rollback || options.version || options.restart) return fail('--auto cannot combine with --dev, --rollback, --version or --restart');
+  if (options.seat !== 'OP' && options.seat !== 'TC' && options.seat !== 'MK' && options.seat !== 'UX') return fail('--auto requires a known --seat (OP|TC|MK|UX)');
+  if (!record?.commit) return fail('installed commit unknown');
+  const currentName = versionDirName(record.versionDir);
+  if (!currentName || !installEntryExists(root, currentName)) return fail('installed entry missing');
+  try {
+    if (readlinkSync(join(root, 'current')) !== record.versionDir) return fail('current does not match installed record');
+  } catch { return fail('current is not a version link'); }
+  if (!options.from && (!record.source || /^(?:https?:|file:)/.test(record.source))) return fail('local checkout source unknown — use --from');
+  if (!existsSync(join(checkout, 'scripts', 'install.sh'))) return fail('checkout installer missing');
+  const verifiedRoot = git(checkout, ['rev-parse', '--show-toplevel']);
+  try {
+    if (verifiedRoot.status !== 0 || !verifiedRoot.stdout.trim() || realpathSync(verifiedRoot.stdout.trim()) !== realpathSync(checkout)) return fail('checkout git root mismatch');
+  } catch { return fail('checkout git root mismatch'); }
+  const head = git(checkout, ['rev-parse', '--verify', 'main']);
+  if (head.status !== 0 || !/^[a-f0-9]{12,40}$/i.test(head.stdout.trim())) return fail('main commit unknown');
+  if (!options.dryRun) {
+    const tracked = git(checkout, ['diff', '--quiet', 'HEAD', '--']);
+    const working = git(checkout, ['rev-parse', '--verify', 'HEAD']);
+    if (tracked.status !== 0 || working.status !== 0 || working.stdout.trim() !== head.stdout.trim()) return fail('main is not the clean checkout HEAD');
+    const untracked = git(checkout, ['ls-files', '--others', '--exclude-standard']);
+    if (untracked.status !== 0 || untracked.stdout.trim()) return fail('checkout contains untracked files');
+  }
+  let state: EdgeRailState | null = null;
+  if (existsSync(stateFile)) {
+    try {
+      const value: unknown = JSON.parse(readFileSync(stateFile, 'utf8'));
+      if (value && typeof value === 'object' && 'canary' in value && 'mainCommit' in value) state = value as EdgeRailState;
+      else return fail('invalid edge-rail state');
+    } catch { return fail('invalid edge-rail state'); }
+  }
+  const mainCommit = head.stdout.trim();
+  const config = deps.edgeRailConfig?.() ?? getUserConfig().harness?.edgeRail ?? {};
+  const canary = state?.mainCommit === mainCommit ? state.canary : null;
+  const observed = (deps.now ?? (() => new Date()))();
+  if (!options.dryRun && canary && canary.okRuns < (config.canaryOkRuns ?? 3) && options.seat === 'OP' && (record.commit.startsWith(mainCommit) || mainCommit.startsWith(record.commit))
+    && !options.failureRate && options.canaryRunId?.trim() && options.canaryRunId !== state?.lastRunId
+    // 같은 런을 두 번 세지 않고, 캐너리 시작 뒤 «성공으로 끝난» 런만 센다(임의·과거·실패 id 로 승격을 열지 못하게).
+    && !(state?.countedRunIds ?? []).includes(options.canaryRunId.trim())
+    && (deps.canaryRunSucceeded ?? canaryRunSucceededInLedger)(options.canaryRunId.trim(), canary.startedAt)
+    && Number.isFinite(observed.getTime()) && observed.getTime() >= Date.parse(canary.startedAt)) {
+    const health = await (deps.verifyRestart ?? defaultVerifyRestart)(mainCommit);
+    if (health.ok && health.daemonSha && (health.daemonSha.startsWith(mainCommit) || mainCommit.startsWith(health.daemonSha)) && state) {
+      state = { ...state, canary: { ...canary, okRuns: canary.okRuns + 1 }, lastRunId: options.canaryRunId, countedRunIds: [...(state.countedRunIds ?? []), options.canaryRunId.trim()] };
+      saveEdgeRailState(stateFile, state);
+    }
+  }
+  const input: EdgeRailInput = {
+    // 설정에서는 세 수치만 받는다 — 여분 키가 판단 입력(seat·failureRate·canary…)을 덮지 못하게.
+    ...(config.canaryOkRuns !== undefined ? { canaryOkRuns: config.canaryOkRuns } : {}),
+    ...(config.failureMultiplier !== undefined ? { failureMultiplier: config.failureMultiplier } : {}),
+    ...(config.minSamples !== undefined ? { minSamples: config.minSamples } : {}),
+    now: observed, mainCommit, installed: record.commit, seat: options.seat,
+    canary: state?.mainCommit === mainCommit ? state.canary : null,
+    failureRate: options.failureRate ?? (state?.mainCommit === mainCommit ? state.failureRate : null) ?? null,
+    quietWindow: options.quietWindow === true, promoted: state?.mainCommit === mainCommit ? state.promoted : false,
+  };
+  // 이 main 은 이미 되돌렸다 — 새 main 이 올 때까지 다시 깔거나 승격하지 않는다.
+  const plan = state?.mainCommit === mainCommit && state.rolledBack
+    ? { decision: 'hold' as const, reason: 'this main was rolled back; waiting for a new main' }
+    : planEdgeRail(input);
+  const fixes = missingFixCommitTitles(checkout, record.commit, mainCommit, git);
+  if (!options.dryRun) try { debug.log('self-update.edge-rail', 'plan', { decision: plan.decision, reason: plan.reason, seat: options.seat, mainCommit, installed: record.commit, fixes }); } catch { /* log sink optional */ }
+  const emit = (result: SelfUpdateResult): SelfUpdateResult => {
+    const autoRollback = input.failureRate ? 'active' as const : 'inactive-no-failure-rate' as const;
+    const merged = { ...result, edgeRail: plan, missingFixes: fixes, autoRollback };
+    out.log(options.json ? JSON.stringify(merged) : `self-update --auto: ${plan.decision} — ${plan.reason} · ${fixes}${autoRollback === 'active' ? '' : ' · 자동 되돌림 비활성 — 실패율 측정 원천 없음'}`);
+    return merged;
+  };
+  if (options.dryRun || plan.decision === 'hold' || plan.decision === 'wait-quiet') return emit({ exitCode: 0, installedVersion: null, decision: null, restarted: false, reason: plan.reason });
+  if (plan.decision === 'rollback' && (!record.previous || !versionDirName(record.previous))) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: 'no previous version for rollback' });
+  if (plan.decision === 'rollback' && !deps.restartEdgeRail && liveRestartBlocked()) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: 'live restart blocked' });
+  if (plan.decision === 'rollback') {
+    const rolled = (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps);
+    if (!rolled.ok) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: rolled.reason });
+    // 되돌린 main 은 표시해 둔다 — 캐너리 OK 수가 남아 있어도 다음 실행이 다시 승격하지 못하게.
+    if (state?.mainCommit === mainCommit) saveEdgeRailState(stateFile, { ...state, promoted: false, rolledBack: true });
+    else saveEdgeRailState(stateFile, { mainCommit, canary: { seat: 'OP', okRuns: 0, startedAt: input.now.toISOString() }, rolledBack: true });
+    const restarted = await restartEdgeRail(deps, checkout);
+    const health = restarted ? await (deps.verifyRestart ?? defaultVerifyRestart)(rolled.record.commit ?? '') : null;
+    const confirmed = !!(health?.ok && health.daemonSha && rolled.record.commit
+      && (health.daemonSha.startsWith(rolled.record.commit) || rolled.record.commit.startsWith(health.daemonSha)));
+    return emit({ exitCode: confirmed ? 0 : 1, installedVersion: rolled.versionName, decision: null, restarted, current: `versions/${rolled.versionName}`, reason: confirmed ? plan.reason : `${plan.reason}; rollback health not confirmed` });
+  }
+  if (!deps.restartEdgeRail && liveRestartBlocked()) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: 'live restart blocked' });
+  const installer = deps.installEdgeRail ?? ((next: SelfUpdateOptions, injected: SelfUpdateDeps) => runUpdateForInstallation(next, { cliRoot: injected.cliRoot, checkout: injected }));
+  // The existing --from dev installer checks entry existence and restores current even when install.sh fails after relinking.
+  const installed = await installer({ from: checkout, dev: true, restart: false }, { ...deps, notice: () => {}, out: { log: () => {}, error: () => {} } });
+  if (installed.exitCode !== 0) return emit(installed);
+  const nextRecord = readInstallRecord(root);
+  const nextName = versionDirName(nextRecord?.versionDir);
+  let currentLink = '';
+  try { currentLink = readlinkSync(join(root, 'current')); } catch { /* no valid installed current */ }
+  if (!nextName || !installEntryExists(root, nextName) || nextRecord?.commit !== mainCommit || currentLink !== nextRecord.versionDir) {
+    const rolled = record.versionDir && nextRecord?.previous === record.versionDir ? (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps) : null;
+    return emit({ ...installed, exitCode: 1, reason: `installed entry/commit not confirmed${rolled?.ok ? '; previous build restored' : '; rollback not confirmed'}` });
+  }
+  const restarted = await restartEdgeRail(deps, checkout);
+  // 설치한 판이 재시작·건강에서 실패해 되돌렸으면 같은 main 을 다시 깔지 않게 표시한다.
+  const markRolledBack = (): void => saveEdgeRailState(stateFile, { mainCommit, canary: { seat: 'OP', okRuns: 0, startedAt: input.now.toISOString() }, rolledBack: true });
+  if (!restarted) {
+    const rolled = record.versionDir && readInstallRecord(root)?.previous === record.versionDir
+      ? (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps) : null;
+    if (rolled?.ok) markRolledBack();
+    return emit({ ...installed, exitCode: 1, restarted: false, reason: `${plan.reason}; restart not confirmed${rolled?.ok ? '; previous build restored' : '; rollback not confirmed'}` });
+  }
+  const verified = await (deps.verifyRestart ?? defaultVerifyRestart)(mainCommit);
+  if (!verified.ok || !verified.daemonSha || !(verified.daemonSha.startsWith(mainCommit) || mainCommit.startsWith(verified.daemonSha))) {
+    const rolled = record.versionDir && readInstallRecord(root)?.previous === record.versionDir
+      ? (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps) : null;
+    if (rolled?.ok) { markRolledBack(); await restartEdgeRail(deps, checkout); }
+    return emit({ ...installed, exitCode: 1, restarted: true, reason: `${plan.reason}; restarted build health not confirmed${rolled?.ok ? '; previous build restored' : '; rollback not confirmed'}` });
+  }
+  if (plan.decision === 'canary-install') {
+    const next: EdgeRailState = { mainCommit, canary: { seat: 'OP', okRuns: 0, startedAt: input.now.toISOString() }, ...(options.failureRate ? { failureRate: options.failureRate } : {}) };
+    saveEdgeRailState(stateFile, next);
+  } else if (state?.mainCommit === mainCommit && plan.decision === 'promote-all') {
+    saveEdgeRailState(stateFile, { ...state, promoted: true });
+  }
+  return emit({ ...installed, restarted: true });
+}
+
 /** Route an installed CLI by where it was installed from: a release URL → release installer, a local checkout → git update. */
 export async function runUpdateForInstallation(
   options: SelfUpdateOptions = {},
   deps: { cliRoot?: string; exists?: (path: string) => boolean; readText?: (path: string) => string; release?: ReleaseUpdateDeps; checkout?: SelfUpdateDeps } = {},
 ): Promise<SelfUpdateResult> {
   const cliRoot = resolve(deps.cliRoot ?? resolve(import.meta.dir, '../..'));
+  if (options.auto) return runEdgeRailUpdate(options, { cliRoot, ...deps.checkout });
   const exists = deps.exists ?? existsSync;
   const holder = resolve(cliRoot, '..', '..');
   const parent = resolve(holder, '..');
@@ -491,6 +856,9 @@ export async function runUpdateForInstallation(
     out.log(options.json ? JSON.stringify(result) : `self-update: ${result.reason}`);
     return result;
   }
+  if (options.dev || options.rollback) {
+    return runSelfUpdate(options, { cliRoot, ...deps.checkout });
+  }
   if (options.version !== undefined) {
     const result: SelfUpdateResult = { exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: '--version 은 릴리스 설치본에서만 사용 가능' };
     const out = deps.checkout?.out ?? console;
@@ -537,6 +905,15 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
     return result;
   };
   const reject = (reason: string): SelfUpdateResult => emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason });
+  if (options.rollback) {
+    const rolled = rollbackDevInstall(deps);
+    if (!rolled.ok) return reject(rolled.reason);
+    return emit({
+      exitCode: 0, installedVersion: rolled.versionName, decision: null, restarted: false,
+      current: `versions/${rolled.versionName}`, previous: rolled.record.previous, channel: rolled.record.channel,
+      reason: `rollback: current → ${rolled.versionName}`,
+    });
+  }
   try {
     if (!existsSync(join(checkout, 'scripts/install.sh'))) return reject(`체크아웃 없음 또는 설치기 없음: ${checkout}`);
     const root = git(checkout, ['rev-parse', '--show-toplevel']);
@@ -546,6 +923,24 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
     const dirty = git(checkout, ['diff', '--quiet', 'HEAD', '--']);
     if (dirty.status !== 0) return reject(dirty.status === 1 ? '추적 파일 변경: 체크아웃이 더러움' : `git diff 실패: ${dirty.stderr}`);
 
+    if (options.dev) {
+      try {
+        const installed = installDevBuild(checkout, head.stdout.trim(), { ...deps, runInstaller: () => run('bash', [join(checkout, 'scripts/install.sh'), '--no-modify-path', ...(deps.installRoot ? ['--prefix', deps.installRoot] : [])], checkout) });
+        return emit({
+          exitCode: 0,
+          installedVersion: installed.versionName,
+          decision: null,
+          restarted: false,
+          current: installed.versionDir,
+          channel: 'dev',
+          previous: installed.previous || undefined,
+          reason: `dev 설치: current → ${installed.versionName}`,
+        });
+      } catch (error) {
+        return emit({ exitCode: 1, installedVersion: null, decision: null, restarted: false, reason: `dev 설치 실패: ${error instanceof Error ? error.message : String(error)}` });
+      }
+    }
+
     const silence = { log: (_s: string) => {}, error: (_s: string) => {} };
     let decision: RestartNeededResult;
     try {
@@ -628,6 +1023,9 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
     const os = deps.os ?? platform();
     const command = os === 'darwin' ? 'launchctl' : os === 'linux' ? 'systemctl' : null;
     if (!command) return emit({ exitCode: 1, installedVersion, decision, restarted: false, prune, reason: `지원하지 않는 플랫폼: ${os}` });
+    if (deps.allowLiveRestart === false || (deps.allowLiveRestart !== true && liveRestartBlocked())) {
+      return emit({ exitCode: 0, installedVersion, decision, restarted: false, prune, reason: '테스트 가드: 실물 재시작 0' });
+    }
     const args = os === 'darwin' ? ['kickstart', '-k', `gui/${deps.uid ?? process.getuid?.() ?? userInfo().uid}/com.elanous.nexus`] : ['--user', 'restart', 'elanous-nexus'];
     try {
       const restarted = run(command, args, checkout);

package/src/cli/usage-cli.ts

@@ -10,6 +10,7 @@ import type { Command } from 'commander';
 import { collectUnifiedUsage, formatUnifiedUsage } from '../budget/unified-usage.js';
 import { consumeCodexResetCredits, listCodexResetCredits } from '../budget/codex-reset-credits.js';
 import { rollupRunUsage, type RunUsageInput } from '../budget/run-usage-rollup.js';
+import { formatUsageOutcomes, outcomeTableHasCodexGrokUnknown, queryUsageOutcomes, type UsageOutcomesDeps, type UsageOutcomesReport } from '../budget/usage-outcomes.js';
 import { LogStore, logsDbPath, type LogQuery, type LogStoreRow } from '../mss/logging/log-store.js';
 import { LOGS_SINCE_OPTION, parseSince } from './logs-cli.js';
 import { formatCodexCreditPlan, type CodexCreditPlan } from '../budget/codex-credit-plan.js';
@@ -28,6 +29,9 @@ export interface UsageCliDeps {
   /** 계정 이름 → CODEX_HOME. ⛔ 여기 없는 이름은 «거부»한다(모르는 곳에 쓰지 않는다). */
   readonly homes?: Readonly<Record<string, string>>;
   readonly exit?: (code: number) => never;
+  /** 런 원장 결과 표. 시험은 디렉터리를 주입한다. */
+  readonly outcomes?: (sinceDays: number) => UsageOutcomesReport;
+  readonly outcomeDeps?: UsageOutcomesDeps;
 }
 
 /** 계정 이름 → CODEX_HOME 기본 표.
@@ -134,6 +138,28 @@ export function registerUsageCommand(program: Command, deps: UsageCliDeps = {}):
   //   🩸 그래서 ⑴ `--yes` 없이는 «안 쓴다» ⑵ 쓰기 «전»에 남은 수를 보여 준다
   //      ⑶ 쓴 «뒤»에도 다시 조회해 「줄었나」를 값으로 낸다.
   //   📏 2026-09-24 현황 예: default 100%·team 100%·third 46% ⇒ third 에 쓰면 54% 가 버려진다.
+  const outcomes = deps.outcomes ?? ((sinceDays: number) => queryUsageOutcomes(sinceDays, deps.outcomeDeps));
+  usage
+    .command('outcomes')
+    .description('프로바이더별 무인 착지율 · 라운드 수 · 막힘 사유 분포 (런 원장 childProvider · 미기록은 불명)')
+    .option('--days <n>', '최근 N일', '2')
+    .option('--json', 'JSON 출력')
+    .action((opts: { days?: string; json?: boolean }, command: Command) => {
+      const json = opts.json || command.optsWithGlobals<{ json?: boolean }>().json;
+      const days = Number(opts.days);
+      if (!Number.isFinite(days) || days <= 0) {
+        out.log(`⛔ --days 는 양의 수: '${opts.days}'`);
+        exit(2);
+        return;
+      }
+      const report = outcomes(days);
+      if (json) {
+        out.log(JSON.stringify({ ...report, hasCodexGrokUnknown: outcomeTableHasCodexGrokUnknown(report) }, null, 2));
+        return;
+      }
+      out.log(formatUsageOutcomes(report));
+    });
+
   const list = deps.list ?? listCodexResetCredits;
   const consume = deps.consume ?? consumeCodexResetCredits;
   const homes = deps.homes ?? defaultHomes();

package/src/context-card/index.ts

@@ -0,0 +1,45 @@
+/** A rebuildable view of the ledger and code, never an authoritative record. */
+export interface ContextCard {
+  readonly id: string;
+  readonly kind: 'task' | 'goal' | 'run' | 'pr' | 'cell' | 'doc';
+  readonly conclusion: string;
+  readonly why: string;
+  readonly verdict: string;
+  readonly remaining: readonly string[];
+  readonly pointers: readonly string[];
+  readonly source: string;
+  readonly updatedAt: string;
+  readonly supersedes?: string;
+}
+
+/** Serialized code points, including JSON escaping; callers may supply a smaller screen budget. */
+export const CONTEXT_CARD_SCREEN_CHARS = 1_600;
+const length = (text: string): number => [...text].length;
+
+/** Preserve the decision and provenance; fold only the two expandable lists. Never mutate the card. */
+export function serializeContextCard(card: ContextCard, maxChars = CONTEXT_CARD_SCREEN_CHARS): string {
+  if (!Number.isSafeInteger(maxChars) || maxChars < 1) throw new RangeError('maxChars must be a positive safe integer');
+  if (/[\r\n\u2028\u2029]/u.test(card.conclusion)) throw new Error('conclusion must be one line');
+  const remaining = [...card.remaining];
+  const pointers = [...card.pointers];
+  const render = () => JSON.stringify({
+    id: card.id, kind: card.kind, conclusion: card.conclusion, why: card.why,
+    verdict: card.verdict, remaining: remaining.length < card.remaining.length
+      ? [...remaining, `외 ${card.remaining.length - remaining.length}개`] : remaining,
+    pointers: pointers.length < card.pointers.length
+      ? [...pointers, `외 ${card.pointers.length - pointers.length}개`] : pointers,
+    source: card.source, updatedAt: card.updatedAt,
+    ...(card.supersedes === undefined ? {} : { supersedes: card.supersedes }),
+  });
+  let text = render();
+  while (length(text) > maxChars && (remaining.length || pointers.length)) {
+    // Remove the larger last entry first, then break ties by preferring remaining.
+    const remainingCost = remaining.length ? length(JSON.stringify(remaining.at(-1))) : -1;
+    const pointerCost = pointers.length ? length(JSON.stringify(pointers.at(-1))) : -1;
+    if (remainingCost >= pointerCost) remaining.pop();
+    else pointers.pop();
+    text = render();
+  }
+  if (length(text) > maxChars) throw new RangeError('card core and omission counts exceed maxChars');
+  return text;
+}