centralu 0.1.0-beta.2 → 0.1.0-beta.21

package/bin/centralu.mjs

@@ -1,22 +1,61 @@
 #!/usr/bin/env node
 /**
- * Centralu 실행기.
+ * The Centralu launcher.
  *
- * **왜 npm으로 주는가:** macOS는 앱을 검사해서 위험하다고 판정하는 게 아니라,
- * 파일에 붙은 `com.apple.quarantine` 딱지를 보고 개발자 신원을 따진다. 그 딱지는
- * **받아온 프로그램이** 붙인다 — 브라우저는 붙이고 npm은 안 붙인다. 그래서 npm으로
- * 설치하면 서명이 애드혹이어도 경고 없이 그냥 열린다 (docs/plans/beta-release-checklist.md §2).
+ * **Why this ships through npm:** macOS does not inspect the app and decide it is dangerous —
+ * it looks at the `com.apple.quarantine` flag attached to the file and checks the developer's
+ * identity from that. That flag is attached **by the program that downloaded it** — a browser
+ * attaches it, npm does not. So an npm install just opens with no warning even with an ad hoc
+ * signature (docs/plans/beta-release-checklist.md §2).
  *
- * 앱 본체는 아키텍처별 패키지(`centralu-darwin-arm64`)에 들어 있다. 이 패키지는
- * 그것을 찾아 띄우는 얇은 껍데기다 — esbuild·swc가 쓰는 것과 같은 구조.
+ * The app itself lives inside an architecture-specific package (`@centralu/darwin-arm64`). This
+ * package is a thin shell that finds it and launches it — the same structure esbuild and swc
+ * use.
  *
  * Linux is served from the same shim (issue #14). The two platforms disagree about what
  * "the app" even is — macOS hands a `.app` directory to LaunchServices, Linux runs a
  * self-contained AppImage itself — so that difference lives in one table (`TARGETS`)
  * instead of being rediscovered in every function.
+ *
+ * Windows joined in W3 of #14. Its decisions — the exe inside the folder, a detached start,
+ * where `install` copies to, the WebView2 check — live in `platform.mjs` as functions of the
+ * platform, so they are tested on macOS CI (tooling/launcher-platform.test.ts) instead of
+ * being first exercised on someone's laptop.
  */
 import { execFileSync, spawn } from 'node:child_process'
-import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { copyDiffers, isNewer } from './semver.mjs'
+import {
+  asideCopies,
+  busyMessage,
+  earlyExitMessage,
+  executableIn,
+  findHostEntry,
+  installedPaths,
+  isBusyError,
+  launchPlan,
+  npmCommand,
+  regExe,
+  shortcutCommand,
+  targetFor,
+  TARGETS,
+  webview2MissingMessage,
+  webview2Status,
+  windowsInstall,
+} from './platform.mjs'
+import {
+  decodeChildSpec,
+  parseServeArgs,
+  printConnection,
+  rotateToken,
+  runAutostart,
+  runDetach,
+  runDetachedChild,
+  runServe,
+  runStop,
+  SERVE_HELP,
+} from './serve.mjs'
+import { swapInto } from './swap.mjs'
+import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -28,68 +67,95 @@ const APP_NAME = 'Centralu'
 const BUNDLE = `${APP_NAME}.app`
 const INSTALLED = `/Applications/${BUNDLE}`
 
+const PLATFORM = process.platform
+const HOME = homedir()
+
 /** Where a menu entry for the app goes on freedesktop desktops */
-const DESKTOP_ENTRY = join(homedir(), '.local/share/applications/centralu.desktop')
+const DESKTOP_ENTRY = join(HOME, '.local/share/applications/centralu.desktop')
 
-/**
- * The arch package for this machine, and what the app is called inside it.
- *
- * `artifact` must match `scripts/release-npm.mts` exactly — that script renames what
- * Tauri produced (`Centralu_0.1.0-beta.2_amd64.AppImage`) to a fixed name precisely so
- * this file does not have to know version or architecture. If the two ever disagree the
- * symptom is "installed fine, does nothing", so keep them in one place mentally.
- *
- * Only combinations that are actually published belong here. Listing a package that was
- * never released would turn "not supported yet" into "your install is broken", which
- * sends the user off to reinstall something that can never appear.
- */
-const TARGETS = {
-  'darwin-arm64': { pkg: 'centralu-darwin-arm64', artifact: BUNDLE },
-  'linux-x64': { pkg: 'centralu-linux-x64', artifact: `${APP_NAME}.AppImage` },
-}
+/** Where `centralu install` copies the app on Windows (see `windowsInstall`) */
+const WIN = PLATFORM === 'win32' ? windowsInstall(process.env, HOME) : null
 
-const TARGET = TARGETS[`${process.platform}-${process.arch}`]
+/** The arch package for this machine (the table lives in platform.mjs) */
+const TARGET = targetFor(PLATFORM, process.arch)
 
-/** 아키텍처별 패키지 안의 앱. 못 찾으면 null */
+/** The app inside the architecture-specific package. null if it cannot be found. */
 function bundledApp() {
   if (!TARGET) return null
   let root
   try {
     root = dirname(require.resolve(`${TARGET.pkg}/package.json`))
   } catch {
-    return null // 이 아키텍처용 패키지가 안 깔린 것 — 아래에서 이유를 말한다
+    return null // The package for this architecture is not installed — the reason is explained below.
   }
   const app = join(root, TARGET.artifact)
-  return existsSync(app) ? app : null
+  return existsSync(executableIn(PLATFORM, app)) ? app : null
 }
 
 /**
- * 지금 이 기계에서 왜 못 쓰는지를 **구체적으로** 말한다.
- * "설치가 안 됐습니다"만 뜨면 사용자가 할 수 있는 일이 없다.
+ * States **specifically** why this machine cannot run it right now.
+ * If all that shows is "not installed", there is nothing the person can act on.
  */
 function explainMissing() {
   if (!TARGET) {
     // Kept as its own case: "not published for your machine" and "not published for
     // Intel Macs, and here is the reason" send the user to different places.
-    if (process.platform === 'darwin') {
+    if (PLATFORM === 'darwin') {
       return (
-        `${APP_NAME}는 아직 Apple Silicon 전용입니다 (지금 아키텍처: ${process.arch}).\n` +
-        'Intel 맥 지원은 네이티브 애드온까지 함께 묶어야 해서 별도 작업으로 잡혀 있습니다.'
+        `${APP_NAME} is Apple Silicon only for now (current architecture: ${process.arch}).\n` +
+        'Intel Mac support needs native addons bundled in as well, and is tracked as separate work.'
       )
     }
     const supported = Object.keys(TARGETS).join(', ')
     return (
-      `${APP_NAME}는 아직 ${process.platform}/${process.arch}를 지원하지 않습니다.\n` +
-      `지금 지원하는 조합: ${supported}\n` +
-      'https://github.com/ijun17/centralu/issues/14 에 진행 상황이 있습니다.'
+      `${APP_NAME} does not support ${PLATFORM}/${process.arch} yet.\n` +
+      `Currently supported combinations: ${supported}\n` +
+      'Progress is tracked at https://github.com/ijun17/centralu/issues/14.'
     )
   }
   return (
-    `앱 본체 패키지(${TARGET.pkg})를 찾지 못했습니다.\n` +
-    '설치가 중간에 끊겼을 수 있습니다 — `npm i -g centralu`로 다시 설치해 주세요.'
+    `Could not find the app package (${TARGET.pkg}).\n` +
+    'The install may have been interrupted — please reinstall with `npm i -g centralu`.'
   )
 }
 
+/**
+ * The bundled host's entry (`resources/host/main.mjs`) for `centralu serve`, or exit with why not:
+ * from the platform package, or from the host-only package where a hub installed this (`findHostEntry`).
+ *
+ * `CENTRALU_HOST_ENTRY` points it at another host instead: a source checkout's
+ * `packages/agent-host/src/main.ts` while developing, or a freshly bundled `resources/host/main.mjs`.
+ * The tests start `serve` that way (tooling/launcher-serve.test.ts).
+ */
+function requireHostEntry() {
+  if (process.env.CENTRALU_HOST_ENTRY) return process.env.CENTRALU_HOST_ENTRY
+  if (!TARGET) {
+    console.error(explainMissing())
+    process.exit(1)
+  }
+  // The platform package of an npm install, else the host-only package a hub installed (platform.mjs)
+  const found = findHostEntry(PLATFORM, process.arch, {
+    resolveRoot: (name) => {
+      try {
+        return dirname(require.resolve(`${name}/package.json`))
+      } catch {
+        return null
+      }
+    },
+    exists: existsSync,
+  })
+  if (found.entry) return found.entry
+  if (found.missingHost) {
+    console.error(
+      `The host is missing from ${found.missingHost.pkg} (looked for ${found.missingHost.entry}).\n` +
+        'Linux packages published before `centralu serve` existed do not carry it. Update with `npm i -g centralu`.',
+    )
+    process.exit(1)
+  }
+  console.error(explainMissing())
+  process.exit(1)
+}
+
 function requireApp() {
   const app = bundledApp()
   if (!app) {
@@ -100,20 +166,27 @@ function requireApp() {
 }
 
 /**
- * 앱을 띄운다. `/Applications`에 설치돼 있으면 그쪽을 먼저 쓴다.
+ * Launches the app. If it is installed in `/Applications` (macOS) or
+ * `%LOCALAPPDATA%\Programs\Centralu` (Windows), that copy is used first.
  *
- * That preference is macOS-only, and not for lack of an equivalent: `centralu install`
+ * Linux has no such preference, and not for lack of an equivalent: `centralu install`
  * on Linux writes a launcher that points back at this same package, so there is never a
  * second copy to prefer.
+ *
+ * Resolves once the launcher has nothing more to wait for. Only Windows waits at all —
+ * briefly, to report an exe that dies on start (see runWindows).
  */
-function run(args) {
-  if (process.platform === 'darwin') {
+async function run(args) {
+  if (PLATFORM === 'darwin') {
     const app = existsSync(INSTALLED) ? INSTALLED : requireApp()
-    // `open`은 LaunchServices를 거친다 — Dock 아이콘·단일 인스턴스가 그래야 제대로 산다
-    const r = spawn('open', ['-a', app, ...(args.length ? ['--args', ...args] : [])], { stdio: 'inherit' })
+    // `open` goes through LaunchServices — the dock icon and single-instance behavior only
+    // work correctly that way.
+    const plan = launchPlan(PLATFORM, app, args, HOME)
+    const r = spawn(plan.command, plan.args, plan.options)
     r.on('exit', (code) => process.exit(code ?? 0))
     return
   }
+  if (PLATFORM === 'win32') return runWindows(args)
   // Linux has no LaunchServices — the AppImage is its own launcher, so run it directly.
   //
   // Staying attached to the terminal is on purpose. The two usual first failures on
@@ -122,34 +195,101 @@ function run(args) {
   // missing system library from the loader. Detaching would hand back the shell prompt
   // and throw away the one line that says what to do.
   const app = requireApp()
-  const r = spawn(app, args, { stdio: 'inherit' })
+  const plan = launchPlan(PLATFORM, app, args, HOME)
+  const r = spawn(plan.command, plan.args, plan.options)
   r.on('error', (e) => {
-    console.error(`${app}를 실행하지 못했습니다: ${e.message}`)
+    console.error(`Failed to run ${app}: ${e.message}`)
     // EACCES here means the executable bit did not survive the trip through npm, which
     // is invisible from the message alone.
-    if (e.code === 'EACCES') console.error(`실행 권한이 없습니다 — \`chmod +x "${app}"\` 뒤에 다시 시도해 주세요.`)
+    if (e.code === 'EACCES') console.error(`No execute permission — run \`chmod +x "${app}"\` then try again.`)
     process.exit(1)
   })
   r.on('exit', (code) => process.exit(code ?? 0))
 }
 
+/** How long to watch a freshly started exe for an immediate exit */
+const EARLY_EXIT_MS = 3000
+
 /**
- * 앱을 시스템 메뉴에 등록한다.
+ * Windows: check WebView2, start `centralu.exe` detached, and watch it for a few seconds.
  *
- * **postinstall로 몰래 하지 않는다.** 남의 `/Applications`에 조용히 쓰는 것은 신뢰를 깎고,
- * pnpm은 postinstall을 기본 차단한다. 사용자가 원할 때 명시적으로 부르게 한다.
+ * The app is a GUI program, so a failure to start has nowhere to print. Without WebView2
+ * the exe ends before it has a window, and the person sees nothing happen at all — the
+ * registry check turns that into a message with the download link before anything starts.
+ * The short watch afterwards catches whatever the registry cannot see (a broken runtime, a
+ * blocked exe), then lets go so the app outlives this launcher.
+ */
+async function runWindows(args) {
+  const webview = webview2Status(process.env, queryRegistry)
+  if (webview.state === 'missing') {
+    console.error(webview2MissingMessage())
+    process.exit(1)
+  }
+  const app = existsSync(WIN.exe) ? WIN.dir : requireApp()
+  const plan = launchPlan(PLATFORM, app, args, HOME)
+  const child = spawn(plan.command, plan.args, plan.options)
+  await new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer)
+      child.removeAllListeners()
+      child.unref()
+      resolve()
+    }
+    const timer = setTimeout(done, EARLY_EXIT_MS)
+    child.on('error', (e) => {
+      console.error(`Failed to start ${plan.command}: ${e.message}`)
+      process.exitCode = 1
+      done()
+    })
+    child.on('exit', (code) => {
+      // 0 is a normal answer this early: a second start hands over to the window that is
+      // already open and leaves.
+      if (code !== 0 && code !== null) {
+        console.error(earlyExitMessage(code, HOME))
+        process.exitCode = 1
+      }
+      done()
+    })
+  })
+}
+
+/**
+ * `reg query <key> /v pv`: stdout, null when the key or value does not exist (reg exits 1),
+ * undefined when reg itself could not run.
+ */
+function queryRegistry(key) {
+  try {
+    return execFileSync(regExe(process.env), ['query', key, '/v', 'pv'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    })
+  } catch (e) {
+    return typeof e?.status === 'number' ? null : undefined
+  }
+}
+
+/**
+ * Registers the app in the system menu.
+ *
+ * **Never done quietly through postinstall.** Writing silently into someone's `/Applications`
+ * erodes trust, and pnpm blocks postinstall by default anyway. This is only run when the
+ * person explicitly asks for it.
  */
 function install() {
   const app = requireApp()
-  if (process.platform !== 'darwin') return installDesktopEntry(app)
-  if (existsSync(INSTALLED)) {
-    console.log(`기존 ${INSTALLED}를 새 버전으로 교체합니다.`)
-    rmSync(INSTALLED, { recursive: true, force: true })
-  }
-  // cp가 아니라 ditto — 번들의 권한·확장속성을 그대로 옮긴다 (서명이 깨지지 않게)
-  execFileSync('/usr/bin/ditto', [app, INSTALLED], { stdio: 'inherit' })
-  console.log(`설치했습니다: ${INSTALLED}`)
-  console.log('이제 Launchpad·Spotlight에서도 찾을 수 있습니다.')
+  if (PLATFORM === 'win32') return installWindows(app)
+  if (PLATFORM !== 'darwin') return installDesktopEntry(app)
+  if (existsSync(INSTALLED)) console.log(`Replacing the existing ${INSTALLED} with the new version.`)
+  // Copied beside the old one and swapped in by rename (swap.mjs): a copy that fails leaves the
+  // old app in place rather than none. ditto, not cp — carries over the bundle's permissions and
+  // extended attributes unchanged (so the signature does not break).
+  const { leftAt } = swapInto(INSTALLED, (staging) => {
+    execFileSync('/usr/bin/ditto', [app, staging], { stdio: 'inherit' })
+  })
+  if (leftAt) console.log(`The previous copy could not be removed and was left at ${leftAt}. Delete it yourself.`)
+  console.log(`Installed: ${INSTALLED}`)
+  console.log('It can now be found in Launchpad and Spotlight too.')
 }
 
 /**
@@ -182,27 +322,117 @@ function installDesktopEntry(app) {
   mkdirSync(dirname(DESKTOP_ENTRY), { recursive: true })
   writeFileSync(DESKTOP_ENTRY, entry)
   chmodSync(DESKTOP_ENTRY, 0o755)
-  console.log(`등록했습니다: ${DESKTOP_ENTRY}`)
-  console.log('이제 앱 목록에서도 찾을 수 있습니다 (데스크톱에 따라 다시 로그인해야 보일 수 있습니다).')
+  console.log(`Registered: ${DESKTOP_ENTRY}`)
+  console.log('It can now be found in the app list too (some desktops require logging back in before it shows up).')
+}
+
+/**
+ * The Windows answer to "copy it into /Applications": copy the folder into
+ * `%LOCALAPPDATA%\Programs\Centralu` and put a shortcut in the Start menu.
+ *
+ * A copy rather than a shortcut into the npm package (the Linux shape), because Windows
+ * will not replace a running program's files: with the app running from the package,
+ * `npm i -g centralu@newer` fails. Running from the copy leaves the package free to update.
+ *
+ * The old copy is never deleted before the new one is complete. The new folder is
+ * assembled beside it, the old one is renamed aside, and only then is the new one moved in
+ * — so a copy that fails halfway, or an app that is still running, leaves the working
+ * install untouched rather than a folder with half its files.
+ */
+function installWindows(app) {
+  const staging = `${WIN.dir}.new`
+  const aside = `${WIN.dir}.old-${Date.now()}`
+  sweepAsideCopies()
+  rmSync(staging, { recursive: true, force: true })
+  mkdirSync(dirname(WIN.dir), { recursive: true })
+  cpSync(app, staging, { recursive: true })
+  writeFileSync(join(staging, 'centralu-version.txt'), `${pkg.version}\n`)
+  if (existsSync(WIN.dir)) {
+    console.log(`Replacing the existing ${WIN.dir} with the new version.`)
+    try {
+      renameSync(WIN.dir, aside)
+    } catch (e) {
+      rmSync(staging, { recursive: true, force: true })
+      if (!isBusyError(e)) throw e
+      console.error(busyMessage(WIN.dir))
+      process.exit(1)
+    }
+  }
+  renameSync(staging, WIN.dir)
+  try {
+    rmSync(aside, { recursive: true, force: true })
+  } catch {
+    // A rename can succeed while the old copy is running; its files then stay locked until
+    // it quits. Harmless — it is no longer the one anything starts — but worth a line.
+    console.log(`The previous copy is still in use and was left at ${aside}. Delete it after quitting ${APP_NAME}.`)
+  }
+  const sc = shortcutCommand(process.env, { shortcut: WIN.shortcut, target: WIN.exe, workdir: HOME })
+  try {
+    execFileSync(sc.command, sc.args, { env: sc.env, stdio: ['ignore', 'ignore', 'inherit'], windowsHide: true })
+  } catch (e) {
+    console.log(`Installed: ${WIN.dir}`)
+    console.error(`Could not create the Start menu shortcut (${e.message}). Start ${WIN.exe} directly, or run \`centralu\`.`)
+    process.exit(1)
+  }
+  console.log(`Installed: ${WIN.dir}`)
+  console.log(`Start menu: ${WIN.shortcut}`)
+  console.log('It can now be found in Start and Windows search, and `centralu` starts this copy too.')
+}
+
+/**
+ * Removes the copies earlier installs renamed aside (`Centralu.old-<time>`), whichever can go.
+ *
+ * An update from inside the app renames the running copy aside, and Windows will not delete a
+ * running exe, so that copy stays until the app quits. Nothing else would ever remove it, and
+ * each in-app update would leave one more (about 70 files each, measured 2026-10-08). One still
+ * in use is left for the next install; deleting what can be deleted from it does not disturb the
+ * app running from it, which reaches its files by the folder's original path, now the new copy.
+ */
+function sweepAsideCopies() {
+  const parent = dirname(WIN.dir)
+  let names
+  try {
+    names = readdirSync(parent)
+  } catch {
+    return
+  }
+  for (const name of asideCopies(names)) {
+    try {
+      rmSync(join(parent, name), { recursive: true, force: true })
+    } catch {
+      // Still in use: the next install tries again
+    }
+  }
 }
 
 function uninstall() {
-  const installed = process.platform === 'darwin' ? INSTALLED : DESKTOP_ENTRY
-  if (!existsSync(installed)) {
-    console.log(`${installed}가 없습니다 — 지울 것이 없습니다.`)
+  const paths = installedPaths(PLATFORM, process.env, HOME)
+  const present = paths.filter((p) => existsSync(p))
+  if (present.length === 0) {
+    console.log(`${paths[0]} does not exist — nothing to remove.`)
     return
   }
-  rmSync(installed, { recursive: true, force: true })
-  console.log(`지웠습니다: ${installed}`)
-  console.log('패키지 자체를 지우려면: npm uninstall -g centralu')
-  console.log(`대화 기록은 그대로 남아 있습니다 (~/.centralu). 지우려면 직접 지우세요.`)
+  for (const installed of present) {
+    try {
+      rmSync(installed, { recursive: true, force: true })
+    } catch (e) {
+      if (PLATFORM !== 'win32' || !isBusyError(e)) throw e
+      console.error(busyMessage(installed))
+      process.exit(1)
+    }
+    console.log(`Removed: ${installed}`)
+  }
+  console.log('To remove the package itself: npm uninstall -g centralu')
+  const data = PLATFORM === 'win32' ? '%USERPROFILE%\\.centralu' : '~/.centralu'
+  console.log(`Conversation history is left in place (${data}). Remove it yourself if you want to.`)
 }
 
 /**
- * npm 레지스트리가 곧 업데이트 채널이다 — 서버도 서명 키도 따로 필요 없다.
+ * The npm registry itself is the update channel — no separate server or signing key needed.
  *
- * 실패를 뭉뚱그리지 않는다. 못 닿은 것(네트워크)과 없는 것(404)은 **사용자가 할 일이 다르다** —
- * 앞은 연결을 보라는 말이고, 뒤는 봐도 소용없다는 말이다.
+ * Failures are not lumped together. Being unreachable (network) and not existing (404) call
+ * for **different actions from the person** — the first says to check the connection, the
+ * second says checking will not help.
  */
 async function latestVersion(timeoutMs = 2000) {
   try {
@@ -215,71 +445,130 @@ async function latestVersion(timeoutMs = 2000) {
     const version = body?.version
     return typeof version === 'string' ? { ok: true, version } : { ok: false, reason: 'bad-response' }
   } catch {
-    return { ok: false, reason: 'network' } // 네트워크가 없어도 앱은 떠야 한다
+    return { ok: false, reason: 'network' } // The app has to launch even with no network.
   }
 }
 
-/** `1.2.10` > `1.2.9` — 문자열 비교로는 틀린다 */
-function isNewer(a, b) {
-  const pa = String(a).split('.').map(Number)
-  const pb = String(b).split('.').map(Number)
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const x = pa[i] ?? 0
-    const y = pb[i] ?? 0
-    if (x !== y) return x > y
-  }
-  return false
-}
 
 async function update() {
   const res = await latestVersion(8000)
   if (!res.ok) {
     if (res.reason === 'missing') {
-      console.error(`레지스트리에 ${pkg.name}가 없습니다. 이름이 바뀌었거나 아직 발행 전입니다.`)
-      console.error('https://github.com/ijun17/centralu/releases 를 확인해 주세요.')
+      console.error(`${pkg.name} is not on the registry. The name may have changed, or it has not been published yet.`)
+      console.error('Please check https://github.com/ijun17/centralu/releases.')
     } else if (res.reason === 'network') {
-      console.error('레지스트리에 닿지 못했습니다. 네트워크를 확인하고 다시 시도해 주세요.')
+      console.error('Could not reach the registry. Please check your network and try again.')
     } else {
-      console.error(`레지스트리가 예상 밖의 응답을 했습니다 (${res.reason}).`)
+      console.error(`The registry gave an unexpected response (${res.reason}).`)
     }
     process.exit(1)
   }
   const latest = res.version
   if (!isNewer(latest, pkg.version)) {
-    console.log(`이미 최신입니다 (${pkg.version}).`)
+    console.log(`Already up to date (${pkg.version}).`)
+    // The package can be up to date while the copy is not — that is exactly the state of
+    // someone who upgraded with `npm i -g`.
+    notifyIfCopyStale()
     return
   }
-  console.log(`${pkg.version} → ${latest} 로 올립니다.`)
-  execFileSync('npm', ['i', '-g', `${pkg.name}@${latest}`], { stdio: 'inherit' })
-  // /Applications에 넣어둔 사람은 그쪽도 함께 갱신해야 옛 버전이 남지 않는다.
+  console.log(`Upgrading ${pkg.version} → ${latest}.`)
+  const npm = npmCommand(PLATFORM, ['i', '-g', `${pkg.name}@${latest}`])
+  try {
+    execFileSync(npm.command, npm.args, npm.options)
+  } catch (e) {
+    // On Windows the usual cause is the app running from inside the package: its files are
+    // locked, and npm cannot replace them. npm's own output (above) has the details.
+    if (PLATFORM === 'win32') console.error(`\n${busyMessage('the npm package')}`)
+    process.exit(typeof e?.status === 'number' ? e.status : 1)
+  }
+  // Someone with a copy in /Applications (or %LOCALAPPDATA%\Programs) needs that updated
+  // too, or the old version stays behind.
   // On Linux the menu entry points at the package instead of a copy, so rewriting it is
   // cheap — but it is still worth doing, because the Exec path is what would go stale.
-  const installed = process.platform === 'darwin' ? INSTALLED : DESKTOP_ENTRY
+  //
+  // The *new* launcher does the refresh: this file has just been replaced on disk. It is
+  // run through `node` rather than as a script, because Windows cannot execute a `.mjs`.
+  const installed = installedPaths(PLATFORM, process.env, HOME)[0]
   if (existsSync(installed)) {
-    console.log(`${installed}도 갱신합니다.`)
-    execFileSync(process.argv[1], ['install'], { stdio: 'inherit' })
+    console.log(`Updating ${installed} too.`)
+    execFileSync(process.execPath, [process.argv[1], 'install'], { stdio: 'inherit' })
   }
-  console.log('끝났습니다. 앱이 떠 있다면 다시 시작해 주세요.')
+  console.log('Done. If the app is open, please restart it.')
 }
 
-/** 앱을 띄운 뒤에만 알린다 — 업데이트 확인 때문에 실행이 늦어지면 안 된다 */
+/**
+ * The version of the copy placed in /Applications. null if there is nothing to compare.
+ *
+ * `defaults` is used because there is no guarantee Info.plist stays XML — Tauri just happens
+ * to write it as XML today, and if it ever switches to a binary plist, anything reading it
+ * with a regex would silently stop working. `defaults` is always present on a Mac and reads
+ * both formats.
+ *
+ * On Windows it is the file `centralu install` wrote beside the copy (see `windowsInstall`
+ * for why not the exe's own version).
+ */
+function installedCopyVersion() {
+  if (PLATFORM === 'win32') {
+    try {
+      return readFileSync(WIN.versionFile, 'utf8').trim()
+    } catch {
+      return null
+    }
+  }
+  if (PLATFORM !== 'darwin' || !existsSync(INSTALLED)) return null
+  try {
+    const out = execFileSync('/usr/bin/defaults', ['read', join(INSTALLED, 'Contents/Info.plist'), 'CFBundleShortVersionString'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return out.trim()
+  } catch {
+    // Failing to read this is not worth mentioning — the app has already launched, and there
+    // is nothing useful to say here.
+    return null
+  }
+}
+
+/**
+ * One line, if the package and the /Applications copy have drifted apart.
+ *
+ * `npm i -g centralu` only changes the package. So a state quietly forms where the launcher is
+ * new but the app that opens from Spotlight is old — this actually happened (beta.1 stayed in
+ * /Applications while only the package moved to beta.3), and nothing on screen said so.
+ *
+ * **Says it, does not do it.** The same rule as the in-app update line. Overwriting someone's
+ * /Applications without asking is the exact reason this package keeps `install` as a separate
+ * step.
+ */
+function notifyIfCopyStale() {
+  const version = installedCopyVersion()
+  if (!copyDiffers(pkg.version, version)) return
+  const where = PLATFORM === 'win32' ? WIN.dir : '/Applications'
+  console.log(`\nThe ${where} copy is ${version} (this package is ${pkg.version}).\n  centralu install`)
+}
+
+/** Only announced after the app has launched — checking for updates must never delay startup. */
 async function notifyIfOutdated() {
-  // 여기서는 실패를 **전부 삼킨다.** 앱을 띄우러 온 사람에게 레지스트리 사정을 말할 이유가 없다
+  // Every failure here is **swallowed entirely.** Someone who came here to launch the app has
+  // no reason to be told about registry troubles.
   const res = await latestVersion()
   if (res.ok && isNewer(res.version, pkg.version)) {
-    console.log(`\n새 버전이 있습니다: ${pkg.version} → ${res.version}\n  centralu update`)
+    console.log(`\nA new version is available: ${pkg.version} → ${res.version}\n  centralu update`)
   }
 }
 
 const HELP = `${APP_NAME} ${pkg.version}
 
-  centralu              앱을 실행합니다
-  centralu install      앱 목록에 등록합니다 (macOS는 /Applications, Linux는 메뉴 항목)
-  centralu uninstall    그 등록을 지웁니다 (대화 기록은 남습니다)
-  centralu update       새 버전이 있으면 올립니다
-  centralu --version    버전을 출력합니다
+  centralu              Launches the app
+  centralu install      Registers it in the app list (macOS: /Applications, Linux: a menu entry,
+                        Windows: %LOCALAPPDATA%\\Programs\\Centralu and a Start menu shortcut)
+  centralu uninstall    Removes that registration (conversation history is kept)
+  centralu update       Upgrades if a new version is available
+  centralu serve        Runs the host alone on this machine, for the app on another computer
+                        to reach over SSH (\`centralu serve --help\`)
+  centralu --version    Prints the version
 
-필요한 것: Node 22+, 그리고 claude 또는 codex CLI (앱 첫 화면이 상태를 알려줍니다)`
+Requires: Node 22+, and the claude or codex CLI (the app's first screen reports the status)`
 
 const [cmd, ...rest] = process.argv.slice(2)
 switch (cmd) {
@@ -292,6 +581,46 @@ switch (cmd) {
   case 'update':
     await update()
     break
+  case 'serve': {
+    // No update notice here: `--connection`'s stdout is read by a program, and a foreground
+    // server's terminal is a log.
+    const args = parseServeArgs(rest)
+    if (args.error) {
+      console.error(args.error)
+      process.exit(2)
+    }
+    if (args.mode === 'help') {
+      console.log(SERVE_HELP)
+      break
+    }
+    try {
+      if (args.mode === 'rotate') {
+        process.exitCode = rotateToken({ env: process.env, home: HOME })
+        break
+      }
+      // A launcher `--detach` started: what it carried (the data folder, a host entry) applies before
+      // anything below reads the environment
+      const spec = args.child !== undefined ? decodeChildSpec(args.child) : null
+      if (args.child !== undefined && !spec) {
+        console.error('centralu serve: --detached-child is how --detach starts serve; this one could not be read')
+        process.exit(2)
+      }
+      if (spec) Object.assign(process.env, spec.env)
+      // realpath: npm's bin is a symlink to this file, and the launcher must not depend on the link
+      const opts = { env: process.env, home: HOME, entry: requireHostEntry(), version: pkg.version, cliPath: realpathSync(process.argv[1]) }
+      if (args.mode === 'connection') process.exitCode = await printConnection(opts)
+      else if (args.mode === 'detach') process.exitCode = await runDetach({ ...opts, port: args.port })
+      else if (args.mode === 'stop') process.exitCode = await runStop(opts)
+      else if (args.mode === 'autostart') process.exitCode = await runAutostart({ ...opts, action: args.autostart })
+      else if (spec) process.exitCode = await runDetachedChild({ ...opts, spec, port: args.port })
+      else process.exitCode = await runServe({ ...opts, port: args.port })
+    } catch (e) {
+      // A state file that cannot be read or written: one sentence, not a stack, and nothing on stdout
+      console.error(`centralu serve: ${e?.message ?? e}`)
+      process.exitCode = 1
+    }
+    break
+  }
   case '--version':
   case '-v':
     console.log(pkg.version)
@@ -301,7 +630,10 @@ switch (cmd) {
   case 'help':
     console.log(HELP)
     break
-  default:
-    run(cmd ? [cmd, ...rest] : [])
-    await notifyIfOutdated()
+  default: {
+    // Started before the update check, never after it: the check must not delay startup.
+    const launched = run(cmd ? [cmd, ...rest] : [])
+    notifyIfCopyStale()
+    await Promise.all([launched, notifyIfOutdated()])
+  }
 }