elanous 0.2.0 → 0.2.5

package/src/cli/self-update.ts

@@ -4,6 +4,7 @@ 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';
 
 export interface SelfUpdateOptions {
   from?: string;
@@ -13,6 +14,8 @@ export interface SelfUpdateOptions {
   keep?: number;
   /** 실패(exit≠0)를 알림으로도 보낸다 — 무인(크론) 실행용. 🩸 없으면 pilot 이 더럽거나 설치가 실패해도 조용히 며칠씩 멈춘다. */
   alert?: boolean;
+  /** 명시적으로 요청한 경우에만 체크아웃 설치 전 PWA 빌드를 건너뛴다. */
+  skipPwaBuild?: boolean;
   /** 설치된 릴리스에서만 사용한다. 체크아웃 갱신에는 적용하지 않는다. */
   version?: string;
 }
@@ -21,7 +24,7 @@ export interface SelfUpdateDeps {
   cliRoot?: string;
   git?: (cwd: string, args: string[]) => { status: number | null; stdout: string; stderr: string };
   decide?: (opts: { to: string; cwd: string; out: { log: (s: string) => void; error: (s: string) => void } }) => Promise<RestartNeededResult>;
-  run?: (command: string, args: string[], cwd: string) => { status: number | null; stderr: string };
+  run?: (command: string, args: string[], cwd: string, options?: { timeout?: number }) => { status: number | null; stderr: string; stdout?: string };
   installedVersion?: () => string;
   /** 재시작 뒤 데몬이 이 커밋으로 떴나(주입 안 하면 `/v1/health` 를 최대 90초 폴링). */
   verifyRestart?: (expectedCommit: string) => Promise<VerifyRestartResult>;
@@ -40,6 +43,8 @@ export interface SelfUpdateDeps {
   /** 텔레그램 러너 서비스(`elanous telegram service --install`)가 깔려 있나 — 주입 안 하면 서비스 파일 존재로 본다. */
   telegramRunnerInstalled?: () => boolean;
   out?: { log: (s: string) => void; error: (s: string) => void };
+  /** 판올림 성공 알림(주입 안 하면 sendOutbound 'report' · 시험에선 안 보냄). */
+  notice?: (text: string) => void;
 }
 
 export interface SelfUpdateResult {
@@ -48,6 +53,12 @@ export interface SelfUpdateResult {
   decision: RestartNeededResult | null;
   restarted: boolean;
   reason: string;
+  /** 체크아웃에서 PWA 빌드가 성공한 HEAD 커밋(12자)과 빌드 시각. */
+  pwaBuiltCommit?: string;
+  pwaBuiltAt?: string;
+  /** 릴리스 갱신에 사용한 기준 URL 및 결정 출처. */
+  releaseBase?: string;
+  releaseBaseSource?: 'option' | 'env' | 'install-source' | 'default';
   /** 설치 뒤 옛 판 정리 결과. 정리를 건너뛰었으면 `skipped` 에 이유. */
   prune?: VersionPruneOutcome;
   /** 재시작 뒤 건강 — ok · rolled-back(직전 판으로 되돌려 회복) · rollback-failed · no-rollback-target. */
@@ -209,8 +220,26 @@ function defaultRelinkCurrent(versionName: string): void {
   renameSync(tmp, join(root, 'current'));
 }
 
+/** 판올림 성공 알림 한 줄(대표 09-28 «수정·배포 과정이 매끄럽지 않다») — 사람이 «무엇을 해야 새 판을 보나»를 바로 안다. */
+export function formatUpdateNotice(result: Pick<SelfUpdateResult, 'installedVersion' | 'restarted' | 'decision' | 'pwaBuiltCommit'>): string | null {
+  if (!result.installedVersion) return null;
+  const restartLine = result.restarted
+    ? '넥서스 재시작함 — 열린 PWA 탭의 터미널·채팅 연결이 끊겼다 → **새로고침** 하면 다시 붙는다'
+    : '넥서스 재시작 안 함(화면·스크립트만 바뀜)';
+  const pwaLine = result.pwaBuiltCommit || result.restarted
+    ? 'PWA 새 화면: 열린 탭은 **새로고침** 해야 보인다'
+    : 'PWA 변경 없음';
+  return [`🔄 **운영 판올림** \`${result.installedVersion}\``, `  • ${restartLine}`, `  • ${pwaLine}`].join('\n');
+}
+
+function defaultNotice(text: string): void {
+  // 시험에선 텔레그램으로 나가지 않는다.
+  if (process.env.NODE_ENV === 'test') return;
+  import('../domains/outbound-alert.js').then((m) => { m.sendOutbound(text, 'ops-report'); }).catch(() => {});
+}
+
 function defaultAlert(text: string): void {
-  import('../domains/outbound-alert.js').then((m) => { m.sendOutbound(text, 'alert'); }).catch(() => {});
+  import('../domains/outbound-alert.js').then((m) => { m.sendOutbound(text, 'ops-alert'); }).catch(() => {});
 }
 
 export interface VersionPruneOutcome {
@@ -267,8 +296,11 @@ export function childPath(env: NodeJS.ProcessEnv = process.env, execPath: string
   return current.split(':').includes(bunDir) ? current : [bunDir, current].filter(Boolean).join(':');
 }
 
-const execute = (command: string, args: string[], cwd: string) => {
-  const result = spawnSync(command, args, { cwd, encoding: 'utf8', env: { ...process.env, PATH: childPath() } });
+// bun 1.4 는 maxBuffer(기본 1MiB)를 넘는 출력을 자르고 자식을 죽인다 — 설치·빌드 로그는 그보다 클 수 있다.
+const SPAWN_MAX_BUFFER = 64 * 1024 * 1024;
+
+const execute = (command: string, args: string[], cwd: string, options?: { timeout?: number }) => {
+  const result = spawnSync(command, args, { cwd, encoding: 'utf8', timeout: options?.timeout, maxBuffer: SPAWN_MAX_BUFFER, env: { ...process.env, PATH: childPath() } });
   return { status: result.status, stdout: result.stdout ?? '', stderr: result.error?.message ?? result.stderr ?? '' };
 };
 
@@ -290,7 +322,7 @@ export interface ReleaseUpdateDeps {
   out?: { log: (text: string) => void; error: (text: string) => void };
   alert?: (text: string) => void;
   pruneVersions?: (plan: { current: string; previous: string; keep: number; prefix: string }) => VersionPruneOutcome;
-  /** 릴리스 기준 URL 주입(시험) — 없으면 `ELANOUS_RELEASE_BASE` → 공개 저장소. */
+  /** 릴리스 기준 URL 주입 — 환경변수와 설치 출처보다 우선한다. */
   releaseBase?: string;
 }
 
@@ -314,7 +346,9 @@ function pruneReleaseVersions(plan: { current: string; previous: string; keep: n
 /** A release update never packs the checkout: the downloaded installer verifies its own release tarball. */
 export async function runReleaseUpdate(options: ReleaseUpdateOptions = {}, deps: ReleaseUpdateDeps = {}): Promise<SelfUpdateResult> {
   const out = deps.out ?? console;
+  let selection: Pick<SelfUpdateResult, 'releaseBase' | 'releaseBaseSource'> = {};
   const finish = (result: SelfUpdateResult): SelfUpdateResult => {
+    result = { ...result, ...selection };
     if (options.alert && result.exitCode !== 0) (deps.alert ?? defaultAlert)(`⛔ elanous self-update 실패(exit ${result.exitCode}): ${result.reason}`);
     if (options.json) out.log(JSON.stringify(result));
     else out.log(`release-update: installed=${result.installedVersion ?? 'none'} restarted=${result.restarted} reason=${result.reason}`);
@@ -334,8 +368,15 @@ export async function runReleaseUpdate(options: ReleaseUpdateOptions = {}, deps:
   if (options.version !== undefined && (!version || !/^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/.test(version))) {
     return fail(2, `잘못된 릴리스 버전: ${options.version}`);
   }
-  // ⭐ 설치기와 같은 기준(`ELANOUS_RELEASE_BASE` · 없으면 공개 저장소 릴리스) — 사설 미러·시험 픽스처(file://)도 같은 길로 간다.
-  const base = (deps.releaseBase ?? process.env.ELANOUS_RELEASE_BASE ?? 'https://github.com/ElanvitalAI/elanous/releases').replace(/\/+$/, '');
+  const source = readInstallSource(packageRoot, exists);
+  const inferred = source?.match(/^(https?:\/\/[^?#]+|file:\/\/[^?#]+)\/(?:latest\/download|download\/v[^/]+)\/elanous\.tgz$/)?.[1];
+  const base = (deps.releaseBase ?? process.env.ELANOUS_RELEASE_BASE ?? inferred ?? 'https://github.com/ElanvitalAI/elanous/releases').replace(/\/+$/, '');
+  selection = { releaseBase: base, releaseBaseSource: deps.releaseBase !== undefined ? 'option' : process.env.ELANOUS_RELEASE_BASE !== undefined ? 'env' : inferred ? 'install-source' : 'default' };
+  const isTailnet = (value: string | null): boolean => {
+    try { return value !== null && new URL(value).hostname.toLowerCase().endsWith('.ts.net'); }
+    catch { return false; }
+  };
+  if (isTailnet(source) && !isTailnet(base)) return fail(2, '내부 설치본을 공개 기준으로 바꾸지 않는다');
   const url = `${base}/${version ? `download/v${version}` : 'latest/download'}/install.sh`;
   let installer: string;
   try {
@@ -357,17 +398,20 @@ export async function runReleaseUpdate(options: ReleaseUpdateOptions = {}, deps:
     }
   } catch { previous = ''; }
   const run = deps.run ?? ((command: string, args: string[], cwd: string, input?: string, env?: NodeJS.ProcessEnv) => {
-    const result = spawnSync(command, args, { cwd, encoding: 'utf8', input, env: { ...process.env, ...env, PATH: childPath() } });
+    const result = spawnSync(command, args, { cwd, encoding: 'utf8', input, maxBuffer: SPAWN_MAX_BUFFER, env: { ...process.env, ...env, PATH: childPath() } });
     return { status: result.status, stderr: result.error?.message ?? result.stderr ?? '' };
   });
   try {
-    const install = run('bash', ['-s', '--', '--no-modify-path', '--prefix', prefix], prefix, installer, { ELANOUS_VERSION: version ?? '', ELANOUS_INSTALL_SOURCE: '' });
+    const install = run('bash', ['-s', '--', '--no-modify-path', '--prefix', prefix], prefix, installer, envLiteral({ ELANOUS_VERSION: version ?? '', ELANOUS_INSTALL_SOURCE: '', ELANOUS_RELEASE_BASE: base }));
     if (install.status !== 0) return fail(1, `설치 실패: ${install.stderr.trim() || install.status}`);
     const metadata: unknown = JSON.parse(readFileSync(join(prefix, 'install.json'), 'utf8'));
     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 (version && installedVersion !== version) return fail(1, `설치판 버전 불일치: 요청 ${version}, 설치 ${installedVersion}`);
+    const internalRevision = isTailnet(source) && version?.match(/^(.*)-([0-9a-f]{12})$/);
+    if (version && installedVersion !== version && (!internalRevision || installedVersion !== internalRevision[1])) {
+      return fail(1, `설치판 버전 불일치: 요청 ${version}, 설치 ${installedVersion}`);
+    }
     let prune: VersionPruneOutcome;
     try {
       const current = typeof metadata === 'object' && metadata !== null && 'versionDir' in metadata && typeof metadata.versionDir === 'string'
@@ -452,8 +496,10 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
   const alertOnce = (text: string): void => { alerted = true; sendAlert(text); };
   let relayOutcome: RelayUpdateOutcome | undefined;
   let runnerOutcome: RelayUpdateOutcome | undefined;
+  let pwaBuild: Pick<SelfUpdateResult, 'pwaBuiltCommit' | 'pwaBuiltAt'> | undefined;
   const emit = (raw: SelfUpdateResult): SelfUpdateResult => {
-    const withRelay: SelfUpdateResult = relayOutcome && !raw.relay ? { ...raw, relay: relayOutcome } : raw;
+    const withBuild: SelfUpdateResult = pwaBuild ? { ...raw, ...pwaBuild } : raw;
+    const withRelay: SelfUpdateResult = relayOutcome && !withBuild.relay ? { ...withBuild, relay: relayOutcome } : withBuild;
     const result: SelfUpdateResult = runnerOutcome && !withRelay.telegramRunner ? { ...withRelay, telegramRunner: runnerOutcome } : withRelay;
     // ⭐ 셀프힐(되돌림) 로직이라 관측을 logs.db 에 남긴다 — /tmp 로그 한 줄로는 `elanous logs` 가 못 본다.
     //   조회: elanous logs --category self-update --event finished
@@ -468,6 +514,10 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
       });
     } catch { /* 관측 실패가 갱신을 막지 않는다 */ }
     if (options.alert && result.exitCode !== 0 && !alerted) alertOnce(`⛔ elanous self-update 실패(exit ${result.exitCode}): ${result.reason}`);
+    if (result.exitCode === 0) {
+      const notice = formatUpdateNotice(result);
+      if (notice) (deps.notice ?? defaultNotice)(notice);
+    }
     if (options.json) out.log(JSON.stringify(result));
     else out.log(`self-update: installed=${result.installedVersion ?? 'none'} decision=${result.decision?.verdict ?? 'unknown'} restarted=${result.restarted} pruned=${result.prune ? (result.prune.skipped ? `skip(${result.prune.skipped})` : result.prune.removed.length) : 'n/a'} reason=${result.reason}`);
     return result;
@@ -489,6 +539,42 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
     } catch (error) {
       decision = { exitCode: 2, reason: `판정 실패: ${String(error)}` };
     }
+    const depsDirs = options.skipPwaBuild ? [checkout] : [checkout, join(checkout, 'apps/pwa')];
+    for (const dir of depsDirs) {
+      const started = Date.now();
+      let ok = false;
+      let tail = '';
+      try {
+        const installed = run('bun', ['install', '--frozen-lockfile'], dir, { timeout: 15 * 60_000 });
+        ok = installed.status === 0;
+        tail = (installed.stderr?.trim() || installed.stdout?.trim() || '').split(/\r?\n/).filter((line) => line.trim()).at(-1)?.trim().slice(0, 500) ?? '';
+      } catch (error) {
+        tail = String(error).split(/\r?\n/).at(-1)?.trim().slice(0, 500) ?? '';
+      }
+      try { debug.log('self-update', 'deps-install', { dir, ok, ms: Date.now() - started }); }
+      catch { /* 관측 실패가 갱신을 막지 않는다 */ }
+      if (!ok) return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `의존 설치 실패: ${tail || '출력 없음'}` });
+    }
+    if (!options.skipPwaBuild) {
+      const commit = head.stdout.trim().slice(0, 12);
+      const started = Date.now();
+      let ok = false;
+      let tail = '';
+      try {
+        const build = run('bun', ['bin/elanous.mjs', 'nexus', 'build'], checkout, { timeout: 15 * 60_000 });
+        ok = build.status === 0;
+        tail = (build.stderr?.trim() || build.stdout?.trim() || '').split(/\r?\n/).filter((line) => line.trim()).at(-1)?.trim().slice(0, 500) ?? '';
+      } catch (error) {
+        tail = String(error).split(/\r?\n/).at(-1)?.trim().slice(0, 500) ?? '';
+      }
+      const ms = Date.now() - started;
+      try {
+        debug.log('self-update', 'pwa-build', { ok, commit, ms });
+        debug.log('self-update', 'pwa-build-tail', { commit, tail: tail || '출력 없음' });
+      } catch { /* 관측 실패가 갱신을 막지 않는다 */ }
+      if (!ok) return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `PWA 빌드 실패: ${tail || '출력 없음'}` });
+      pwaBuild = { pwaBuiltCommit: commit, pwaBuiltAt: new Date().toISOString() };
+    }
     let install: ReturnType<NonNullable<SelfUpdateDeps['run']>>;
     try {
       install = run('bash', [join(checkout, 'scripts/install.sh'), '--no-modify-path'], checkout);
@@ -516,7 +602,12 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
     runnerOutcome = updateTelegramRunner(decision, options.restart === true, deps, run, checkout);
     try { debug.log('self-update', 'telegram-runner', { ...runnerOutcome, installedVersion }); } catch { /* */ }
     if (runnerOutcome.verdict === 'failed' && options.alert) alertOnce(`⚠️ elanous self-update: 텔레그램 러너 재시작 실패 — ${runnerOutcome.reason}`);
-    if (decision.verdict !== 'restart' || decision.exitCode !== 11) {
+    // ⛔ `build`(PWA 만 바뀜)도 재시작한다 — 이 길은 새 판을 `versions/<새 판>` 에 깔고 `current` 를 옮긴다.
+    //    도는 넥서스는 «부팅 때의» 판 디렉터리에서 정적 파일을 서빙하므로, 재시작 없이는 새 PWA 가 영영 안 보인다
+    //    (2026-09-28 실측: decision=build · restarted=false 뒤에도 운영이 옛 빌드 id 를 서빙 → kickstart 뒤에야 새 id).
+    //    `build = 재빌드만` 은 체크아웃에서 도는 데몬(같은 apps/pwa/out 을 읽는다)의 전제였다.
+    const needsRestart = (decision.verdict === 'restart' && decision.exitCode === 11) || (decision.verdict === 'build' && decision.exitCode === 10);
+    if (!needsRestart) {
       return emit({ exitCode: 0, installedVersion, decision, restarted: false, prune, relay, reason: decision.exitCode === 2 ? `판정 모름: ${decision.reason ?? '이유 없음'}` : `판정 ${decision.verdict ?? 'unknown'}: 재시작 불필요` });
     }
     if (!options.restart) return emit({ exitCode: 0, installedVersion, decision, restarted: false, prune, reason: '--restart 없음: 재시작하지 않음' });

package/src/cli/setup-cli.ts

@@ -3,6 +3,8 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import type { Command } from 'commander';
 import { formatDoctorReport, runDoctor, type DoctorOptions, type DoctorReport } from './doctor-cli.js';
+import { applyClaudePluginSetup, planClaudePluginSetup } from './claude-plugin-setup.js';
+import { debug } from '../debug/log.js';
 import { getUserConfig, saveUserConfig, type UserConfig } from '../user-config.js';
 
 const ELANOUS_LOGIN_COMMAND = 'elanous login openai-codex';
@@ -23,7 +25,9 @@ export interface SetupCliDeps extends DoctorOptions {
   homeDir?: () => string;
   getUserConfig?: () => UserConfig;
   saveUserConfig?: (config: UserConfig) => void;
-	  prompt?: (message: string) => Promise<string | undefined>;
+  planClaudePluginSetup?: typeof planClaudePluginSetup;
+  applyClaudePluginSetup?: typeof applyClaudePluginSetup;
+  prompt?: (message: string) => Promise<string | undefined>;
   isStdinTty?: () => boolean;
   out?: { log: (value: string) => void; error?: (value: string) => void };
   setExitCode?: (code: number) => void;
@@ -104,6 +108,12 @@ function missingRequiredCommands(doctor: DoctorReport): boolean {
   return doctor.externalCommands.some((command) => command.status === 'missing' && command.tier === 'required');
 }
 
+function displayCommand(command: string[]): string {
+  return command.map((arg) => /^[A-Za-z0-9_@%+=:,./-]+$/.test(arg)
+    ? arg
+    : `'${arg.replace(/'/g, "'\\''")}'`).join(' ');
+}
+
 export function formatSetupReport(doctor: DoctorReport, steps: SetupStep[], nonInteractive: boolean): string {
   const elanousLogin = steps[0]!.complete;
   const provider = steps[1]!.complete;
@@ -141,7 +151,7 @@ export function registerSetupCommand(program: Command, deps: SetupCliDeps = {}):
     try { return await rl.question(message); } finally { rl.close(); }
   });
 
-  program.command('setup')
+  const setup = program.command('setup')
     .description('Check OpenAI Codex setup and guide each missing credential step')
     .option('--non-interactive', 'Report setup state without prompts or writes')
     .action(async (opts: { nonInteractive?: boolean }) => {
@@ -171,4 +181,56 @@ export function registerSetupCommand(program: Command, deps: SetupCliDeps = {}):
       out.log(formatSetupReport(doctor, steps, false));
       setExitCode(0);
     });
+
+  setup.command('claude-code')
+    .description('Plan or install the elanous Claude Code plugin')
+    .option('--apply', 'Install missing steps and verify the MCP connection')
+    .option('--source <URL|경로|owner/repo>', 'Claude plugin marketplace source')
+    .option('--json', 'Print the plan or result as one JSON line')
+    .action(async (opts: { apply?: boolean; source?: string; json?: boolean }) => {
+      let ready: boolean | undefined;
+      let needed: number | undefined;
+      let executed: number | undefined;
+      let mcpVerified: boolean | undefined;
+      try {
+        const plan = await (deps.planClaudePluginSetup ?? planClaudePluginSetup)({ source: opts.source });
+        ready = plan.ready;
+        needed = plan.steps.filter((step) => step.needed).length;
+        debug.log('setup.claude-code', 'planned', { ready, needed, executed, mcpVerified });
+        if (opts.apply) {
+          const result = await (deps.applyClaudePluginSetup ?? applyClaudePluginSetup)(plan);
+          executed = result.executed.length;
+          mcpVerified = result.mcpVerified;
+          ready = result.verification.ready;
+          if (opts.json) out.log(JSON.stringify(result));
+          else {
+            for (const command of result.executed) out.log(`✓ 실행: ${displayCommand(command)}`);
+            out.log(`MCP 확인: ${mcpVerified ? '✓ 완료' : '✗ 실패'}`);
+          }
+          debug.log('setup.claude-code', result.ok ? 'applied' : 'failed', { ready, needed, executed, mcpVerified });
+          setExitCode(result.ok ? 0 : 1);
+          return;
+        }
+        if (opts.json) out.log(JSON.stringify(plan));
+        else {
+          for (const binary of [
+            { available: plan.claudeCode, name: 'claude', reason: 'Claude Code is not installed' },
+            { available: plan.node, name: 'node', reason: 'node is not on PATH' },
+            { available: plan.elanous, name: 'elanous', reason: 'elanous is not on PATH' },
+          ]) {
+            out.log(binary.available ? `✓ 완료: ${binary.name}` : `✗ 막힘: ${binary.reason}`);
+          }
+          for (const step of plan.steps) {
+            out.log(step.needed ? `→ 할 일: ${displayCommand(step.command)}` : `✓ 완료: ${displayCommand(step.command)}`);
+          }
+          out.log(plan.ready ? '준비됨' : '--apply 로 실행');
+        }
+        setExitCode(0);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        debug.log('setup.claude-code', 'failed', { ready, needed, executed, mcpVerified });
+        (out.error ?? out.log)(message.replace(/\r?\n/g, ' '));
+        setExitCode(1);
+      }
+    });
 }

package/src/cli/shadow-cli.ts

@@ -0,0 +1,188 @@
+// `elanous shadow` — git 을 거절한 폴더의 이력을 폴더 «밖» 그림자 저장소에 남긴다.
+import { statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import type { Command } from 'commander';
+
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import {
+  diffShadow,
+  listShadow,
+  restoreShadow,
+  shadowPaths,
+  snapshotShadow,
+  targetIsGitRepo,
+  type ShadowContext,
+  type ShadowGit,
+} from '../self-implement/shadow-repo.js';
+
+export const GIT_REPO_REFUSAL = '이 폴더는 git 저장소입니다 — git 을 쓰세요';
+
+export interface ShadowCliIo {
+  log: (message: string) => void;
+  error: (message: string) => void;
+}
+
+export interface ShadowCliDeps {
+  cwd?: () => string;
+  instanceRoot?: () => string;
+  git?: ShadowGit;
+  now?: () => Date;
+  out?: ShadowCliIo;
+  setExitCode?: (code: number) => void;
+}
+
+interface ShadowFlags {
+  message?: string;
+  json?: boolean;
+  yes?: boolean;
+}
+
+function depsOf(overrides: ShadowCliDeps): Required<Pick<ShadowCliDeps, 'cwd' | 'instanceRoot' | 'out' | 'setExitCode'>> & ShadowCliDeps {
+  return {
+    cwd: () => process.cwd(),
+    instanceRoot: () => effectiveInstanceRoot(),
+    out: { log: (message) => console.log(message), error: (message) => console.error(message) },
+    setExitCode: (code) => { process.exitCode = code; },
+    ...overrides,
+  };
+}
+
+function contextFor(dir: string | undefined, deps: ReturnType<typeof depsOf>): ShadowContext & { target: string } {
+  const target = resolve(dir ?? deps.cwd());
+  return {
+    target,
+    instanceRoot: deps.instanceRoot(),
+    git: deps.git,
+    now: deps.now,
+  };
+}
+
+/** 대상이 git 저장소면 한 줄만 내고 2. 그림자에는 아무것도 쓰지 않는다. */
+function refuseGitRepo(ctx: ShadowContext, deps: ReturnType<typeof depsOf>): boolean {
+  // A missing folder must not become a shadow repository keyed by a path that does not exist
+  // (2026-09-28: `restore <dir> <commit>` in the wrong order created one and then crashed in git add).
+  let isDirectory = false;
+  try { isDirectory = statSync(ctx.target).isDirectory(); } catch { /* missing */ }
+  if (!isDirectory) {
+    deps.out.error(`폴더가 아닙니다: ${ctx.target}${/^[0-9a-f]{7,40}$/i.test(basename(ctx.target)) ? ' — 커밋처럼 보인다. restore 는 `shadow restore <커밋> [폴더]` 순서다' : ''}`);
+    deps.setExitCode(2);
+    return true;
+  }
+  if (!targetIsGitRepo(ctx.target, deps.git)) return false;
+  deps.out.error(GIT_REPO_REFUSAL);
+  deps.setExitCode(2);
+  return true;
+}
+
+function runSnapshot(dir: string | undefined, flags: ShadowFlags, overrides: ShadowCliDeps): void {
+  const deps = depsOf(overrides);
+  const ctx = contextFor(dir, deps);
+  if (refuseGitRepo(ctx, deps)) return;
+  const message = flags.message?.trim() || 'shadow snapshot';
+  const result = snapshotShadow({ ...ctx, message });
+  deps.out.log(`${result.mode} ${result.commit} changed=${result.changed}`);
+}
+
+function runLog(dir: string | undefined, flags: ShadowFlags, overrides: ShadowCliDeps): void {
+  const deps = depsOf(overrides);
+  const ctx = contextFor(dir, deps);
+  if (refuseGitRepo(ctx, deps)) return;
+  const rows = listShadow(ctx);
+  if (flags.json) {
+    deps.out.log(JSON.stringify(rows, null, 2));
+    return;
+  }
+  if (rows.length === 0) {
+    deps.out.log('(그림자 이력 없음)');
+    return;
+  }
+  for (const row of rows) {
+    deps.out.log(`${row.commit} ${row.at} changed=${row.changed} ${row.message}`);
+  }
+}
+
+function runDiff(dir: string | undefined, from: string | undefined, to: string | undefined, overrides: ShadowCliDeps): void {
+  const deps = depsOf(overrides);
+  const ctx = contextFor(dir, deps);
+  if (refuseGitRepo(ctx, deps)) return;
+  const rows = listShadow(ctx);
+  const base = from ?? rows[0]?.commit;
+  if (!base) {
+    deps.out.error('비교할 그림자 커밋이 없습니다');
+    deps.setExitCode(1);
+    return;
+  }
+  deps.out.log(diffShadow({ ...ctx, from: base, to }));
+}
+
+/** `--yes` 없이 restore 가 보여줄 바뀔 파일 목록. 쓰기는 하지 않는다. */
+function previewRestore(ctx: ShadowContext & { commit: string }): string {
+  return diffShadow({ ...ctx, from: 'HEAD', to: ctx.commit });
+}
+
+function runRestore(dir: string | undefined, commit: string | undefined, flags: ShadowFlags, overrides: ShadowCliDeps): void {
+  const deps = depsOf(overrides);
+  const ctx = contextFor(dir, deps);
+  if (refuseGitRepo(ctx, deps)) return;
+  if (!commit) {
+    deps.out.error('restore 에는 커밋이 필요합니다');
+    deps.setExitCode(1);
+    return;
+  }
+  if (!flags.yes) {
+    const text = previewRestore({ ...ctx, commit });
+    const files = text.split('\n').filter((line) => line.startsWith('diff --git ')).map((line) => line.slice('diff --git '.length));
+    if (files.length === 0) deps.out.log('(바뀔 파일 없음)');
+    else for (const file of files) deps.out.log(file);
+    deps.out.log('반영하려면 --yes');
+    return;
+  }
+  const result = restoreShadow({ ...ctx, commit });
+  deps.out.log(`restored ${commit} ${result.commit} changed=${result.changed}`);
+}
+
+/** One line and exit 1 instead of a stack trace. */
+function guarded(overrides: ShadowCliDeps, run: () => void): void {
+  try { run(); }
+  catch (error) {
+    const deps = depsOf(overrides);
+    deps.out.error(`shadow: ${error instanceof Error ? error.message : String(error)}`);
+    deps.setExitCode(1);
+  }
+}
+
+export function registerShadowCommand(program: Command, overrides: ShadowCliDeps = {}): void {
+  const shadow = program.command('shadow').description('git 아닌 폴더의 이력을 인스턴스 밖 그림자 저장소에 남긴다');
+
+  shadow.command('snapshot')
+    .description('현재 폴더(또는 [dir])의 그림자 스냅숏')
+    .argument('[dir]', '대상 폴더 (기본: 현재 폴더)')
+    .option('-m, --message <message>', '스냅숏 메시지')
+    .action((dir: string | undefined, flags: ShadowFlags) => guarded(overrides, () => runSnapshot(dir, flags, overrides)));
+
+  shadow.command('log')
+    .description('그림자 커밋 목록 (최신 먼저)')
+    .argument('[dir]', '대상 폴더 (기본: 현재 폴더)')
+    .option('--json', 'JSON 출력')
+    .action((dir: string | undefined, flags: ShadowFlags) => guarded(overrides, () => runLog(dir, flags, overrides)));
+
+  shadow.command('diff')
+    .description('그림자 커밋과 작업 트리(또는 다른 커밋)의 unified diff')
+    .argument('[dir]', '대상 폴더 (기본: 현재 폴더)')
+    .argument('[from]', '기준 커밋 (생략 시 최신)')
+    .argument('[to]', '비교 커밋 (생략 시 WORKTREE)')
+    .action((dir: string | undefined, from: string | undefined, to: string | undefined) => {
+      guarded(overrides, () => runDiff(dir, from, to, overrides));
+    });
+
+  shadow.command('restore')
+    .description('그림자 커밋으로 되돌린다 (--yes 없으면 바뀔 파일만 보여 주고 멈춘다)')
+    .argument('<commit>', '되돌릴 커밋')
+    .argument('[dir]', '대상 폴더 (기본: 현재 폴더)')
+    .option('--yes', '실제로 대상 파일을 되돌린다')
+    .action((commit: string, dir: string | undefined, flags: ShadowFlags) => {
+      guarded(overrides, () => runRestore(dir, commit, flags, overrides));
+    });
+}
+
+

package/src/cli/share-auto-mount.ts

@@ -29,7 +29,7 @@
 //     3. macOS NOPASSWD entry for `tailscale serve` (long-term daemon
 //        operators)
 
-import { defaultServe } from '../nexus/onboarding/pwa-share-prompt.js';
+import { autoServe } from '../nexus/onboarding/pwa-share-prompt.js';
 import { probeTailscale, type TailscaleProbe } from '../nexus/onboarding/tailscale-probe.js';
 import { readSwitchValue, readUserConfig } from '../nexus/config/user-config.js';
 import { debug } from '../debug/log.js';
@@ -59,7 +59,7 @@ export interface MountShareOpts {
   // ─── Test seams ─────────────────────────────────────────────────
   readShareSwitchFn?: () => ShareTailnetValue;
   shareProbeFn?: () => Promise<TailscaleProbe>;
-  shareServeFn?: (binary: string, port: number) => Promise<{ exitCode: number }>;
+  shareServeFn?: (binary: string, port: number) => Promise<{ exitCode: number; ladderExhausted?: boolean }>;
 }
 
 /** Read `global.nexus.pwa.shareTailnet` switch (default 'ask' when unset). */
@@ -106,17 +106,21 @@ export async function mountShareIfEnabled(opts: MountShareOpts): Promise<ShareMo
     return { outcome: 'skipped', reason: 'tailscale-down' };
   }
 
-  const serveFn = opts.shareServeFn ?? defaultServe;
+  const serveFn = opts.shareServeFn ?? autoServe;
   const serve = await serveFn(probe.binary ?? 'tailscale', opts.httpPort);
   if (serve.exitCode !== 0) {
-    // Most common cause in fork+detach: `sudo -n` cache empty → exit
-    // 1. Tag the trace so the recovery paths (see module doc above)
-    //    are obvious from the log alone.
+    // Only a caller that actually saw the ladder fail through sudo
+    // (`ladderExhausted === true`) may claim the cache was empty.
+    // Unknown or false leaves the hint off.
     trace('failed', {
       reason: 'serve-error',
       serveExitCode: serve.exitCode,
-      likelyCause: 'sudo-cache-empty-in-fork-detach',
-      recoveryHint: 'run `sudo -v` once in a TTY then restart, or `elanous nexus pwa share enable`',
+      ...(serve.ladderExhausted === true
+        ? {
+            likelyCause: 'sudo-cache-empty-in-fork-detach',
+            recoveryHint: 'run `sudo -v` once in a TTY then restart, or `elanous nexus pwa share enable`',
+          }
+        : {}),
     });
     return { outcome: 'failed', reason: 'serve-error', serveExitCode: serve.exitCode };
   }