@bakapiano/ccsm 0.16.0 → 0.17.2

package/scripts/upgrade-helper.js

@@ -3,33 +3,39 @@
 
 // In-app upgrade helper · spawned detached by /api/upgrade.
 //
-// The previous implementation kicked off `npm i -g` directly from the
-// running server. On Windows that fails with EBUSY: npm tries to rename
-// the package directory but the server has files open inside it.
-//
-// This script breaks the cycle:
+// Why this exists: running `npm i -g` from inside the live server hits
+// EBUSY on Windows (npm tries to rename the package directory while the
+// server has files open inside it). We can't do the install in-process.
 //
+// What this script does:
 //   1. Server validates the upgrade request, spawns this helper detached
-//      with [target, port, pid] argv, sends 200 OK, then gracefulShutdowns.
-//   2. Helper waits for the old port to free up + the old pid to die.
-//   3. Helper runs `npm i -g @bakapiano/ccsm@<target>` synchronously.
-//   4. On success it spawns `ccsm` detached (which spins up the new
-//      backend on the same port) and exits.
-//
-// Logs everything to ~/.ccsm/upgrade.log so a failed upgrade is
-// debuggable without the user needing to re-run the command manually.
+//      with the target version + caller's port/pid, sends 200 OK back to
+//      the frontend, then gracefulShutdowns.
+//   2. Helper writes ~/.ccsm/.upgrade.lock (so a stray ccsm:// wake on
+//      ccsm.cmd doesn't try to start a new server while we're installing).
+//   3. Helper starts a tiny HTTP server on port 7779 that serves a
+//      progress UI: inline HTML at /, JSON status at /api/upgrade/status,
+//      SSE stream of npm output at /api/upgrade/stream. The original
+//      frontend navigates to http://localhost:7779/ when it gets the
+//      upgrade response, so the user watches install progress live.
+//   4. Helper waits for the old port + pid to be gone (up to 30s).
+//   5. Helper runs `npm i -g @bakapiano/ccsm@<target>`, captures stdout +
+//      stderr line by line, pushes each line into the SSE stream.
+//   6. On success: spawn ccsm.cmd (which boots the new server on 7777),
+//      push a `done` SSE event with redirectTo=7777 so the UI navigates
+//      back. Keep the helper server alive for ~30s for late clients,
+//      then exit + release the lock.
+//   7. On failure: keep the helper server alive indefinitely so the user
+//      can read the error + copy the log. Exits when the user clicks
+//      Close in the UI (POST /api/upgrade/dismiss) OR after 10 min.
 //
 // Argv: node upgrade-helper.js <target> <port> <pid> [installPrefix] [respawn=1|0]
-// - installPrefix: when set, runs `npm i -g --prefix=<this>` so the
-//   global install can be redirected to a sandbox dir for testing
-//   against a live prod install without disturbing it. Respawn then
-//   uses <prefix>/ccsm.cmd (Windows) or <prefix>/bin/ccsm (posix).
-// - respawn: '0' skips the final ccsm respawn (also useful for tests).
 
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const net = require('node:net');
+const http = require('node:http');
 const { spawn, spawnSync } = require('node:child_process');
 
 const target = process.argv[2] || 'latest';
@@ -37,19 +43,25 @@ const oldPort = Number(process.argv[3] || 7777);
 const oldPid = Number(process.argv[4] || 0);
 const installPrefix = process.argv[5] || '';
 const doRespawn = process.argv[6] !== '0';
+// redirectTo: where the updater UI sends the browser after success.
+// Server passes the FRONTEND_URL it computed (GH Pages router in
+// prod, local apiUrl in dev). Fallback to localhost:oldPort/ so old
+// callers that don't pass anything still work.
+const redirectTo = process.argv[7] || `http://localhost:${oldPort}/`;
 
+const HELPER_PORT = 7779;
 const HOME = process.env.CCSM_HOME || path.join(os.homedir(), '.ccsm');
 const LOG = path.join(HOME, 'upgrade.log');
+const LOCK = path.join(HOME, '.upgrade.lock');
 try { fs.mkdirSync(HOME, { recursive: true }); } catch {}
 
-function log(msg) {
+function fileLog(msg) {
   const line = `[${new Date().toISOString()}] ${msg}\n`;
   try { fs.appendFileSync(LOG, line); } catch {}
 }
 
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
-// Returns true once nothing answers on host:port within timeoutMs.
 function portFree(port, timeoutMs = 800) {
   return new Promise((resolve) => {
     const s = new net.Socket();
@@ -69,11 +81,450 @@ function pidAlive(pid) {
   catch (e) { return e.code === 'EPERM'; }
 }
 
+// ── Lockfile so bin/ccsm.js refuses to spawn a new server mid-upgrade.
+// bin reads .upgrade.lock at startup; if it exists with a live pid and
+// startedAt < 10min ago it exits early. Stale locks are auto-cleared.
+let phaseValue = 'starting';
+function writeLock() {
+  try {
+    fs.writeFileSync(LOCK, JSON.stringify({
+      pid: process.pid,
+      startedAt: Date.now(),
+      target,
+      phase: phaseValue,
+      helperPort: HELPER_PORT,
+    }, null, 2));
+  } catch {}
+}
+function removeLock() {
+  try { fs.unlinkSync(LOCK); } catch {}
+}
+writeLock();
+process.on('exit', removeLock);
+process.on('SIGINT', () => { removeLock(); process.exit(0); });
+process.on('SIGTERM', () => { removeLock(); process.exit(0); });
+process.on('uncaughtException', (e) => { fileLog(`uncaught: ${e.stack || e.message}`); removeLock(); process.exit(1); });
+
+// ── Progress state shared with the HTTP server. ─────────────────────
+const startedAt = Date.now();
+const linesBuffer = [];       // ring of {ts, stream, text}
+const LINES_CAP = 2000;
+const sseClients = new Set(); // res objects we push events to
+let errorMsg = null;
+let finishedAt = null;
+
+function pushLine(stream, text) {
+  if (!text) return;
+  const entry = { ts: Date.now(), stream, text };
+  linesBuffer.push(entry);
+  if (linesBuffer.length > LINES_CAP) linesBuffer.shift();
+  const payload = JSON.stringify(entry);
+  for (const res of sseClients) {
+    try { res.write(`data: ${payload}\n\n`); } catch {}
+  }
+  fileLog(`[${stream}] ${text}`);
+}
+
+function setPhase(p) {
+  phaseValue = p;
+  writeLock();
+  const payload = JSON.stringify({ phase: p, ts: Date.now() });
+  for (const res of sseClients) {
+    try { res.write(`event: phase\ndata: ${payload}\n\n`); } catch {}
+  }
+  fileLog(`[phase] ${p}`);
+}
+
+function notifyDone(redirectTo) {
+  finishedAt = Date.now();
+  const payload = JSON.stringify({ redirectTo, ts: Date.now() });
+  for (const res of sseClients) {
+    try { res.write(`event: done\ndata: ${payload}\n\n`); } catch {}
+  }
+}
+
+function notifyFailed() {
+  finishedAt = Date.now();
+  const payload = JSON.stringify({ error: errorMsg, ts: Date.now() });
+  for (const res of sseClients) {
+    try { res.write(`event: failed\ndata: ${payload}\n\n`); } catch {}
+  }
+}
+
+// ── Inline updater UI ────────────────────────────────────────────────
+const UI_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>ccsm · upgrade</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" />
+<style>
+:root {
+  --bg: #faf9f5;
+  --bg-elev: #ffffff;
+  --ink: #1a1815;
+  --ink-mid: #6b665d;
+  --ink-muted: #9a9489;
+  --border: #e8e3d5;
+  --accent: #4a73a5;
+  --green: #4a8a4a;
+  --red: #b73f3f;
+  --warn: #c79544;
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: var(--bg);
+  color: var(--ink);
+  font-family: 'Geist', -apple-system, BlinkMacSystemFont, sans-serif;
+  font-size: 14px;
+  display: flex;
+  align-items: flex-start;
+  justify-content: center;
+  padding: 40px 20px;
+}
+.card {
+  width: 100%;
+  max-width: 720px;
+  background: var(--bg-elev);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 24px 28px;
+  box-shadow: 0 1px 2px rgba(0,0,0,0.04);
+}
+h1 {
+  margin: 0 0 6px;
+  font-size: 18px;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+}
+.subtitle {
+  color: var(--ink-mid);
+  margin: 0 0 20px;
+  font-size: 13px;
+}
+.subtitle .mono { font-family: 'JetBrains Mono', monospace; font-size: 12.5px; }
+.phase-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 0;
+  border-bottom: 1px dashed var(--border);
+}
+.phase-row:last-of-type { border-bottom: 0; }
+.phase-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--border);
+  flex-shrink: 0;
+}
+.phase-row.active .phase-dot {
+  background: var(--accent);
+  animation: pulse 1.4s ease-in-out infinite;
+}
+.phase-row.done .phase-dot { background: var(--green); }
+.phase-row.failed .phase-dot { background: var(--red); }
+.phase-row.pending .phase-dot { background: var(--border); }
+.phase-label {
+  flex: 1;
+  font-size: 13px;
+  color: var(--ink);
+}
+.phase-row.pending .phase-label { color: var(--ink-muted); }
+.phase-row.done .phase-label { color: var(--ink-mid); }
+.phase-meta {
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 11.5px;
+  color: var(--ink-muted);
+}
+@keyframes pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50%      { opacity: 0.4; transform: scale(1.3); }
+}
+.log {
+  margin-top: 16px;
+  background: #1a1815;
+  color: #e8e3d5;
+  border-radius: 6px;
+  padding: 12px 14px;
+  font-family: 'JetBrains Mono', monospace;
+  font-size: 11.5px;
+  line-height: 1.5;
+  max-height: 320px;
+  overflow-y: auto;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+.log .line.err { color: #e07b6e; }
+.log .line.info { color: #9bb8d8; }
+.log .ts { color: #534e44; margin-right: 8px; }
+.banner {
+  margin-top: 16px;
+  padding: 10px 14px;
+  border-radius: 6px;
+  font-size: 13px;
+}
+.banner.success {
+  background: rgba(74, 138, 74, 0.08);
+  color: var(--green);
+  border: 1px solid rgba(74, 138, 74, 0.3);
+}
+.banner.error {
+  background: rgba(183, 63, 63, 0.08);
+  color: var(--red);
+  border: 1px solid rgba(183, 63, 63, 0.3);
+}
+.actions {
+  margin-top: 16px;
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}
+.btn {
+  appearance: none;
+  border: 1px solid var(--border);
+  background: var(--bg-elev);
+  color: var(--ink);
+  padding: 7px 14px;
+  border-radius: 6px;
+  cursor: pointer;
+  font: inherit;
+  font-size: 13px;
+}
+.btn.primary {
+  background: var(--ink);
+  color: var(--bg-elev);
+  border-color: var(--ink);
+}
+.btn:hover { background: rgba(0,0,0,0.04); }
+.btn.primary:hover { background: #000; }
+</style>
+</head>
+<body>
+<div class="card">
+  <h1>Upgrading ccsm</h1>
+  <p class="subtitle">target: <span class="mono">@bakapiano/ccsm@<span id="target"></span></span></p>
+
+  <div id="phases">
+    <div class="phase-row pending" data-phase="waiting-port">
+      <span class="phase-dot"></span>
+      <span class="phase-label">Wait for old backend to exit</span>
+      <span class="phase-meta" data-meta-for="waiting-port"></span>
+    </div>
+    <div class="phase-row pending" data-phase="installing">
+      <span class="phase-dot"></span>
+      <span class="phase-label">Run <span class="phase-meta">npm i -g</span></span>
+      <span class="phase-meta" data-meta-for="installing"></span>
+    </div>
+    <div class="phase-row pending" data-phase="spawning">
+      <span class="phase-dot"></span>
+      <span class="phase-label">Start new backend</span>
+      <span class="phase-meta" data-meta-for="spawning"></span>
+    </div>
+  </div>
+
+  <div id="banner"></div>
+  <div class="log" id="log"></div>
+
+  <div class="actions">
+    <button class="btn" id="copyLog">Copy log</button>
+    <button class="btn primary" id="close" style="display:none">Close</button>
+  </div>
+</div>
+
+<script>
+(function () {
+  const targetEl = document.getElementById('target');
+  const logEl = document.getElementById('log');
+  const bannerEl = document.getElementById('banner');
+  const closeBtn = document.getElementById('close');
+  const copyBtn = document.getElementById('copyLog');
+
+  const PHASE_ORDER = ['waiting-port', 'installing', 'spawning', 'done'];
+  let lastPhaseTs = Date.now();
+
+  function setPhase(phase) {
+    const idx = PHASE_ORDER.indexOf(phase);
+    document.querySelectorAll('.phase-row').forEach((row) => {
+      const p = row.getAttribute('data-phase');
+      const pi = PHASE_ORDER.indexOf(p);
+      row.classList.remove('pending', 'active', 'done', 'failed');
+      if (phase === 'failed') {
+        if (pi < idx || (pi === idx - 1)) row.classList.add('done');
+        else if (pi === idx) row.classList.add('failed');
+        else row.classList.add('pending');
+      } else if (pi < idx) row.classList.add('done');
+      else if (pi === idx) row.classList.add('active');
+      else row.classList.add('pending');
+    });
+  }
+
+  function appendLine(entry) {
+    const div = document.createElement('div');
+    div.className = 'line ' + (entry.stream === 'stderr' ? 'err' : entry.stream === 'info' ? 'info' : '');
+    const t = new Date(entry.ts).toLocaleTimeString();
+    div.innerHTML = '<span class="ts">' + t + '</span>' + escapeHtml(entry.text);
+    logEl.appendChild(div);
+    logEl.scrollTop = logEl.scrollHeight;
+  }
+
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, (c) => ({
+      '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'
+    })[c]);
+  }
+
+  copyBtn.addEventListener('click', () => {
+    const text = Array.from(logEl.children).map((d) => d.innerText).join('\\n');
+    navigator.clipboard.writeText(text).then(() => {
+      copyBtn.innerText = 'Copied';
+      setTimeout(() => { copyBtn.innerText = 'Copy log'; }, 1500);
+    });
+  });
+
+  closeBtn.addEventListener('click', () => {
+    fetch('/api/upgrade/dismiss', { method: 'POST' }).catch(() => {});
+    window.close();
+  });
+
+  // SSE stream — server replays the buffer first then streams new
+  // events. EventSource auto-reconnects.
+  const es = new EventSource('/api/upgrade/stream');
+
+  // Status fetch up-front to fill target + initial phase quickly even
+  // if SSE is slow to push.
+  fetch('/api/upgrade/status').then((r) => r.json()).then((s) => {
+    targetEl.innerText = s.target || '';
+    if (s.phase) setPhase(s.phase);
+    if (s.errorMsg) showFailed(s.errorMsg);
+    if (s.lines) s.lines.forEach(appendLine);
+  }).catch(() => {});
+
+  es.addEventListener('message', (ev) => {
+    try {
+      const entry = JSON.parse(ev.data);
+      if (entry.stream && entry.text != null) appendLine(entry);
+    } catch {}
+  });
+  es.addEventListener('phase', (ev) => {
+    try {
+      const data = JSON.parse(ev.data);
+      if (data.phase) setPhase(data.phase);
+    } catch {}
+  });
+  es.addEventListener('done', (ev) => {
+    try {
+      const data = JSON.parse(ev.data);
+      setPhase('done');
+      document.querySelectorAll('.phase-row').forEach((r) => r.classList.add('done'));
+      bannerEl.className = 'banner success';
+      bannerEl.innerText = 'Upgrade complete. Redirecting to the new backend…';
+      closeBtn.style.display = '';
+      // Give the new backend a moment to bind 7777 before redirecting.
+      setTimeout(() => {
+        location.href = data.redirectTo || 'http://localhost:7777/';
+      }, 1500);
+    } catch {}
+  });
+  es.addEventListener('failed', (ev) => {
+    try {
+      const data = JSON.parse(ev.data);
+      showFailed(data.error);
+    } catch {}
+  });
+
+  function showFailed(msg) {
+    setPhase('failed');
+    bannerEl.className = 'banner error';
+    bannerEl.innerText = 'Upgrade failed: ' + (msg || 'unknown error');
+    closeBtn.style.display = '';
+    closeBtn.innerText = 'Close';
+  }
+})();
+</script>
+</body>
+</html>`;
+
+// ── HTTP server ──────────────────────────────────────────────────────
+function buildStatus() {
+  return {
+    target,
+    phase: phaseValue,
+    startedAt,
+    finishedAt,
+    errorMsg,
+    redirectTo,
+    helperPort: HELPER_PORT,
+    lines: linesBuffer.slice(-500),
+  };
+}
+
+const httpServer = http.createServer((req, res) => {
+  // Permissive CORS — only listens on localhost anyway.
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  if (req.method === 'OPTIONS') return res.end();
+
+  if (req.url === '/' || req.url === '/index.html') {
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    return res.end(UI_HTML);
+  }
+  if (req.url === '/api/upgrade/status') {
+    res.setHeader('Content-Type', 'application/json');
+    return res.end(JSON.stringify(buildStatus()));
+  }
+  if (req.url === '/api/upgrade/stream') {
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    res.flushHeaders();
+    res.write(': connected\n\n');
+    // Replay buffered lines so a late client catches up.
+    for (const entry of linesBuffer) {
+      res.write(`data: ${JSON.stringify(entry)}\n\n`);
+    }
+    res.write(`event: phase\ndata: ${JSON.stringify({ phase: phaseValue, ts: Date.now() })}\n\n`);
+    if (finishedAt && errorMsg) {
+      res.write(`event: failed\ndata: ${JSON.stringify({ error: errorMsg })}\n\n`);
+    } else if (finishedAt) {
+      res.write(`event: done\ndata: ${JSON.stringify({ redirectTo })}\n\n`);
+    }
+    sseClients.add(res);
+    const hb = setInterval(() => { try { res.write(': ping\n\n'); } catch {} }, 25_000);
+    req.on('close', () => { clearInterval(hb); sseClients.delete(res); });
+    return;
+  }
+  if (req.url === '/api/upgrade/dismiss' && req.method === 'POST') {
+    res.end('{"ok":true}');
+    // Schedule self-exit so the user closing the window also wraps up
+    // the helper. Give SSE a chance to flush.
+    setTimeout(() => {
+      removeLock();
+      process.exit(0);
+    }, 300);
+    return;
+  }
+  res.statusCode = 404;
+  res.end('not found');
+});
+httpServer.on('error', (e) => {
+  fileLog(`http server error: ${e.message}`);
+});
+httpServer.listen(HELPER_PORT, '127.0.0.1', () => {
+  fileLog(`updater UI at http://localhost:${HELPER_PORT}/`);
+  pushLine('info', `Helper UI listening on http://localhost:${HELPER_PORT}/`);
+});
+
+// ── Main upgrade flow ────────────────────────────────────────────────
 (async () => {
-  log(`start · target=${target} oldPort=${oldPort} oldPid=${oldPid}${installPrefix ? ` prefix=${installPrefix}` : ''}${!doRespawn ? ' (no respawn)' : ''}`);
+  fileLog(`start · target=${target} oldPort=${oldPort} oldPid=${oldPid}${installPrefix ? ` prefix=${installPrefix}` : ''}${!doRespawn ? ' (no respawn)' : ''}`);
+  pushLine('info', `Upgrading ccsm to ${target}`);
 
-  // Wait up to 30s for the old server to be gone. Both port-free AND
-  // pid-dead so we don't fight npm's rename for a stale file handle.
+  setPhase('waiting-port');
   const deadline = Date.now() + 30_000;
   while (Date.now() < deadline) {
     const free = await portFree(oldPort);
@@ -81,11 +532,11 @@ function pidAlive(pid) {
     if (free && dead) break;
     await sleep(250);
   }
-  log(`old server gone (or 30s elapsed) · running npm install`);
+  pushLine('info', `Old backend gone (port ${oldPort} free, pid ${oldPid} dead).`);
+
+  setPhase('installing');
+  pushLine('info', `Running: npm i -g @bakapiano/ccsm@${target}${installPrefix ? ` --prefix=${installPrefix}` : ''}`);
 
-  // npm.cmd is a batch wrapper on Windows; spawn it via cmd.exe /c so
-  // we don't need shell:true (which would mean argv quoting). target
-  // has already been regex-validated server-side so this is safe.
   const isWin = process.platform === 'win32';
   const arg = `@bakapiano/ccsm@${target}`;
   const npmArgs = ['i', '-g'];
@@ -94,54 +545,77 @@ function pidAlive(pid) {
     npmArgs.push(`--prefix=${installPrefix}`);
   }
   npmArgs.push(arg);
-  let r;
+
+  let exe, exeArgs;
   if (isWin) {
-    r = spawnSync(process.env.ComSpec || 'cmd.exe',
-      ['/d', '/s', '/c', 'npm', ...npmArgs],
-      { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    exe = process.env.ComSpec || 'cmd.exe';
+    exeArgs = ['/d', '/s', '/c', 'npm', ...npmArgs];
   } else {
-    r = spawnSync('npm', npmArgs,
-      { stdio: ['ignore', 'pipe', 'pipe'] });
+    exe = 'npm';
+    exeArgs = npmArgs;
   }
-  const stdout = r.stdout?.toString().trim();
-  const stderr = r.stderr?.toString().trim();
-  log(`npm exit=${r.status}${stdout ? `\nSTDOUT:\n${stdout}` : ''}${stderr ? `\nSTDERR:\n${stderr}` : ''}`);
-  if (r.status !== 0) {
-    log(`upgrade failed · not respawning`);
-    process.exit(1);
+
+  const npmExit = await new Promise((resolve) => {
+    const child = spawn(exe, exeArgs, { windowsHide: true });
+    const pipe = (stream, label) => {
+      let leftover = '';
+      stream.on('data', (chunk) => {
+        const text = leftover + chunk.toString();
+        const lines = text.split(/\r?\n/);
+        leftover = lines.pop() || '';
+        for (const line of lines) if (line) pushLine(label, line);
+      });
+      stream.on('end', () => { if (leftover) pushLine(label, leftover); });
+    };
+    pipe(child.stdout, 'stdout');
+    pipe(child.stderr, 'stderr');
+    child.on('error', (e) => {
+      pushLine('stderr', `spawn error: ${e.message}`);
+      resolve(-1);
+    });
+    child.on('exit', (code) => resolve(code));
+  });
+
+  if (npmExit !== 0) {
+    errorMsg = `npm exited with code ${npmExit}`;
+    pushLine('stderr', errorMsg);
+    notifyFailed();
+    // Stay alive 10min so user can copy log + read error.
+    setTimeout(() => { removeLock(); process.exit(1); }, 10 * 60_000);
+    return;
   }
+  pushLine('info', `npm install completed (exit ${npmExit}).`);
 
   if (!doRespawn) {
-    log(`respawn skipped (respawn=0)`);
+    pushLine('info', 'respawn skipped (respawn=0).');
+    setPhase('done');
+    notifyDone(redirectTo);
+    setTimeout(() => { removeLock(); process.exit(0); }, 30_000);
     return;
   }
 
-  // Respawn ccsm. With installPrefix the binary lives there; otherwise
-  // it's on PATH from the global npm install. The launcher handles
-  // detect-or-spawn-server and detaches.
-  //
-  // On Windows, CreateProcess refuses to spawn .cmd / .bat directly —
-  // they're cmd.exe scripts, not native exes. Route through cmd.exe /c
-  // so it loads the wrapper.
+  setPhase('spawning');
+  pushLine('info', 'Starting new backend…');
+
   const ccsmCmd = installPrefix
     ? (isWin ? path.join(installPrefix, 'ccsm.cmd') : path.join(installPrefix, 'bin', 'ccsm'))
     : (isWin ? 'ccsm.cmd' : 'ccsm');
-  // Drop CCSM_NO_BROWSER so the post-upgrade server pops a fresh window
-  // — the frontend that triggered the upgrade window.close()'d in
-  // parallel, and the new window takes its place. Skips the
-  // OfflineBanner gap that used to bridge the upgrade.
   const childEnv = { ...process.env };
   delete childEnv.CCSM_NO_BROWSER;
-  let exe, exeArgs;
+  // Hint the new ccsm that it was spawned by the updater so it can
+  // skip auto-opening a browser window — the user is already looking
+  // at the updater UI which will redirect to the new server.
+  childEnv.CCSM_FROM_UPGRADE = '1';
+  let respawnExe, respawnArgs;
   if (isWin) {
-    exe = process.env.ComSpec || 'cmd.exe';
-    exeArgs = ['/d', '/s', '/c', ccsmCmd];
+    respawnExe = process.env.ComSpec || 'cmd.exe';
+    respawnArgs = ['/d', '/s', '/c', ccsmCmd];
   } else {
-    exe = ccsmCmd;
-    exeArgs = [];
+    respawnExe = ccsmCmd;
+    respawnArgs = [];
   }
   try {
-    const child = spawn(exe, exeArgs, {
+    const child = spawn(respawnExe, respawnArgs, {
       detached: true,
       stdio: 'ignore',
       windowsHide: true,
@@ -149,12 +623,27 @@ function pidAlive(pid) {
       env: childEnv,
     });
     child.unref();
-    log(`respawned ${ccsmCmd} (via ${path.basename(exe)})`);
+    pushLine('info', `Spawned ${ccsmCmd} (via ${path.basename(respawnExe)}).`);
   } catch (e) {
-    log(`respawn failed: ${e.message}`);
-    process.exit(1);
+    errorMsg = `respawn failed: ${e.message}`;
+    pushLine('stderr', errorMsg);
+    notifyFailed();
+    setTimeout(() => { removeLock(); process.exit(1); }, 10 * 60_000);
+    return;
   }
+
+  setPhase('done');
+  notifyDone(redirectTo);
+  pushLine('info', 'Done. Redirecting frontend to the new backend.');
+
+  // Stay alive briefly so late-arriving SSE clients still see the
+  // success state. After that the helper exits and releases the lock;
+  // the new ccsm at port 7777 takes over.
+  setTimeout(() => { removeLock(); process.exit(0); }, 30_000);
 })().catch((e) => {
-  log(`fatal: ${e.message}`);
-  process.exit(1);
+  errorMsg = e?.message || String(e);
+  fileLog(`fatal: ${errorMsg}`);
+  pushLine('stderr', `fatal: ${errorMsg}`);
+  notifyFailed();
+  setTimeout(() => { removeLock(); process.exit(1); }, 10 * 60_000);
 });