@pandanpc/mcp-server 0.1.45 → 0.1.47

package/README.md

@@ -70,12 +70,12 @@ Account operations require `note_login` when not already authenticated. Reading
 
 ## Automatic runtime updates
 
-The npm launcher starts the last verified runtime immediately and checks for a newer stable release in a separate background process (at most once every six hours; failed checks back off for 15 minutes). It downloads the platform binary into the user's cache, verifies SHA-256, and runs a bounded startup check before atomically selecting it for the next launch. Current MCP sessions are never restarted or replaced. Offline or failed updates keep the existing runtime usable.
+The npm launcher starts the last verified runtime immediately and checks for a newer stable release in a separate background process (about once an hour with random jitter; failed checks back off exponentially from 15 minutes up to 6 hours). It downloads the platform binary into the user's cache, verifies SHA-256 and runs a bounded startup check, which stages it as a candidate. The launcher stays between the MCP client and the runtime, so a running session switches to the candidate without a restart: it completes a real MCP handshake with the client's own initialize request, waits for in-flight requests to finish (new requests are queued in order), then closes the old runtime. A new runtime becomes the default for future sessions only after it has served a tool call or run for a minute; one that fails to start, times out or crashes before that is skipped with a growing backoff, and a session whose new runtime crashes, before or after that point, goes back to the previous runtime automatically (requests that were in flight get an error and are not replayed). The crashed version is not retried in that session and is skipped with the same backoff; if it had already become the default, later sessions start from the runtime it replaced. If the new version changes the tool list, Claude Code sessions switch and receive `notifications/tools/list_changed`; other clients keep the current runtime and use the new one from their next session. A change to the server instructions always waits for the next session, because clients cannot refresh instructions mid-session; a switch is also postponed while the client is not reading the launcher's output. The launcher always advertises `tools.listChanged` to the client, even when the runtime does not declare it (runtimes 0.1.45 and earlier never do), so a later switch can still refresh the tool list. Offline or failed updates keep the existing runtime usable. Sessions that were started by an older launcher (0.1.45 or earlier) cannot switch in place: after upgrading the npm package, reconnect the MCP server (or restart the session) once; later releases then apply to running sessions automatically.
 
 The cache defaults to `~/.pandanpc-mcp/runtime/<platform>-<arch>` and does not require write access to a global npm installation. Each version uses its own file, including on Windows. Older cached executables are retained because another session may still use them; remove the cache only after closing those sessions if you want to reclaim disk space.
 
 - `pandanpc-mcp --version` shows the selected runtime and npm launcher versions.
-- `pandanpc-mcp --update` checks/downloads now; reconnect afterwards to use the result. Status messages go to stderr, never the MCP protocol stream.
+- `pandanpc-mcp --update` checks/downloads now; running sessions pick up the result within a minute when compatible. Status messages go to stderr, never the MCP protocol stream.
 - Set `PANDANPC_MCP_AUTO_UPDATE=0` in the MCP client's environment to disable checks and pin the runtime bundled with the installed npm version.
 - `PANDANPC_MCP_CACHE_DIR` optionally selects a different user-writable cache directory.
 

package/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
- * bin entry: spawn the platform-specific pandanpc-mcp binary,
- * forwarding all arguments and stdio streams.
+ * bin entry: run the platform-specific pandanpc-mcp binary behind a stdio proxy that can swap in
+ * a newer verified runtime without restarting the MCP session (see proxy.js).
  */
 
 const path = require('path')
@@ -9,36 +9,83 @@ const { spawn } = require('child_process')
 const fs = require('fs')
 const { binaryName } = require('./binary-name')
 const pkg = require('./package.json')
-const { selectRuntime, startBackgroundUpdate, checkForUpdates } = require('./updater')
+const updater = require('./updater')
+const { McpProxy } = require('./proxy')
+const { selectRuntime, startBackgroundUpdate, checkForUpdates } = updater
 
 const binName = binaryName()
 const bundledPath = path.join(__dirname, 'bin', binName)
 const runtime = selectRuntime()
+const autoUpdate = process.env.PANDANPC_MCP_AUTO_UPDATE !== '0'
+const args = process.argv.slice(2)
 let child
 
-if (process.argv[2] === '--version') {
+if (args[0] === '--version') {
   console.log(`pandanpc-mcp ${runtime.version} (launcher ${pkg.version})`)
   process.exit(0)
 }
-if (process.argv[2] === '--update') {
+if (args[0] === '--update') {
   checkForUpdates({ force: true }).then(result => {
     console.error(`[pandanpc-mcp] update: ${result.status}${result.version ? ` ${result.version}` : ''}${result.error ? ` (${result.error})` : ''}`)
     if (result.status === 'manual-update-required') console.error('Update the launcher: npm install -g @pandanpc/mcp-server@latest')
+    if (result.status === 'ready') console.error('Running sessions switch to it automatically when compatible')
     process.exit(result.status === 'failed' ? 1 : 0)
   }).catch(error => { console.error(error.message); process.exit(1) })
-} else {
+} else if (args.includes('--http') || args.some(a => a.startsWith('--engine-agent'))) {
+  // Not an stdio MCP session: nothing to proxy.
   launch(runtime)
+} else {
+  proxy()
   startBackgroundUpdate()
   // Keep long-lived sessions aware of releases without holding the process open.
   setInterval(startBackgroundUpdate, 15 * 60 * 1000).unref()
 }
 
+function proxy() {
+  const bundled = { file: bundledPath, version: pkg.version }
+  let first = runtime, fallback = null
+  const candidate = autoUpdate ? updater.candidateRuntime() : null
+  if (candidate) { first = candidate; fallback = runtime }
+  if (!fs.existsSync(first.file)) {
+    console.error(`[pandanpc-mcp] binary not found at ${first.file}; reinstall @pandanpc/mcp-server`)
+    process.exit(1)
+  }
+  if (!fallback && runtime.file !== bundledPath && fs.existsSync(bundledPath)) fallback = bundled
+  const instance = new McpProxy({
+    input: process.stdin, output: process.stdout, args,
+    log: message => console.error(`[pandanpc-mcp] ${message}`),
+    promote: selected => { try { updater.promoteCandidate(selected) } catch {} },
+    recordFailure: (version, reason) => updater.recordFailure(updater.cacheRoot(), version, reason),
+    onExit: ({ code, signal, error }) => {
+      if (error && !signal) console.error(`[pandanpc-mcp] failed to spawn: ${error.message}`)
+      if (signal) {
+        process.removeAllListeners(signal)
+        process.kill(process.pid, signal)
+      }
+      process.exitCode = code ?? (error ? 1 : 0)
+      process.stdout.write('', () => process.exit(process.exitCode))
+    },
+  })
+  instance.start(first, fallback)
+  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+    try { process.on(signal, () => instance.shutdown(signal)) } catch {}
+  }
+  if (!autoUpdate) return
+  // Pick up a runtime the background updater downloaded while this session is running.
+  setInterval(() => {
+    const version = updater.peekCandidateVersion()
+    if (!version || !instance.ready || instance.attempted.has(version) || version === instance.version) return
+    const next = updater.candidateRuntime()
+    if (next) instance.hotSwap(next)
+  }, 60 * 1000).unref()
+}
+
 function launch(selected) {
   if (!fs.existsSync(selected.file)) {
     console.error(`[pandanpc-mcp] binary not found at ${selected.file}; reinstall @pandanpc/mcp-server`)
     process.exit(1)
   }
-  child = spawn(selected.file, process.argv.slice(2), {
+  child = spawn(selected.file, args, {
     stdio: 'inherit', windowsHide: true,
     env: { ...process.env, PANDANPC_MCP_RUNTIME_VERSION: selected.version },
   })
@@ -55,6 +102,6 @@ function launch(selected) {
       process.exit(1)
     }
   })
+  process.on('SIGINT', () => { if (child) child.kill('SIGINT') })
+  process.on('SIGTERM', () => { if (child) child.kill('SIGTERM') })
 }
-process.on('SIGINT', () => { if (child) child.kill('SIGINT') })
-process.on('SIGTERM', () => { if (child) child.kill('SIGTERM') })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pandanpc/mcp-server",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "PandaNpc MCP Server — PandaNote and Agent connection management for Codex, Claude Code, and other MCP clients",
   "keywords": [
     "mcp",
@@ -20,6 +20,7 @@
     "pandanpc-mcp": "index.js"
   },
   "files": [
+    "proxy.js",
     "binary-name.js",
     "index.js",
     "install.js",

package/proxy.js

@@ -0,0 +1,522 @@
+/**
+ * Long-lived stdio proxy between the MCP client and the Rust runtime.
+ *
+ * It lets a newer verified runtime take over a live session: the candidate is started beside the
+ * current one, handshaken with the client's own initialize request, and only swapped in once the
+ * session is idle and every in-flight request (both directions) has completed. Client traffic that
+ * arrives meanwhile is queued in order. The old runtime is closed through stdin EOF so it releases
+ * its memory sync lease. A new runtime stays on probation until it has served a tool call or run
+ * for a while; only then is it promoted to the default, and if it crashes first the proxy goes
+ * back to the runtime it replaced within the same session.
+ */
+const { spawn, spawnSync } = require('child_process')
+
+const CLAUDE_CODE = /^claude[-_ ]?code/i
+const INTERNAL = 'pandanpc-proxy:'
+
+/** Splits a byte stream into JSON-RPC lines; tolerates split chunks, CRLF and split UTF-8 sequences. */
+class LineReader {
+  constructor(onLine) { this.parts = []; this.onLine = onLine }
+  push(chunk) {
+    let start = 0
+    for (let i = chunk.indexOf(10); i !== -1; i = chunk.indexOf(10, start)) {
+      const piece = chunk.subarray(start, i)
+      const line = this.parts.length ? Buffer.concat([...this.parts, piece]) : piece
+      this.parts = []
+      start = i + 1
+      let end = line.length
+      if (end && line[end - 1] === 13) end--
+      const text = line.toString('utf8', 0, end)
+      if (text.trim()) this.onLine(text)
+    }
+    if (start < chunk.length) this.parts.push(chunk.subarray(start))
+  }
+}
+
+const idKey = id => JSON.stringify(id)
+const isRequest = m => m && typeof m === 'object' && !Array.isArray(m) && typeof m.method === 'string' && m.id !== undefined && m.id !== null
+const isNotification = m => m && typeof m === 'object' && !Array.isArray(m) && typeof m.method === 'string' && m.id === undefined
+const isResponse = m => m && typeof m === 'object' && !Array.isArray(m) && m.method === undefined && m.id !== undefined
+const progressToken = m => m?.params?._meta?.progressToken
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (value && typeof value === 'object') return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`
+  return JSON.stringify(value)
+}
+const toolsFingerprint = tools => canonical([...tools].sort((a, b) => String(a.name).localeCompare(String(b.name))))
+const timeout = (ms, message) => { let timer; const p = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), ms) }); p.catch(() => {}); p.cancel = () => clearTimeout(timer); return p }
+
+function spawnProcess(runtime, args) {
+  return spawn(runtime.file, args, {
+    stdio: ['pipe', 'pipe', 'inherit'], windowsHide: true,
+    env: { ...process.env, PANDANPC_MCP_RUNTIME_VERSION: runtime.version },
+  })
+}
+/**
+ * Force-stops a runtime that ignored stdin EOF. On Windows the npm-cache binary re-launches itself
+ * from a private copy and waits for it, so the server may sit one level below; kill those two
+ * levels only. Engine agent workers are meant to outlive the MCP server and are never killed.
+ */
+function killTree(proc) {
+  if (!proc.pid) return
+  if (process.platform === 'win32') {
+    const query = `Get-CimInstance Win32_Process -Filter "ParentProcessId=${Number(proc.pid)}" | Where-Object { $_.CommandLine -notmatch '--engine-agent-worker' } | ForEach-Object { $_.ProcessId }`
+    const found = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', query], { windowsHide: true, encoding: 'utf8', timeout: 10000 })
+    const pids = String(found.stdout || '').split(/\s+/).filter(p => /^\d+$/.test(p))
+    for (const pid of [proc.pid, ...pids]) spawnSync('taskkill', ['/PID', String(pid), '/F'], { windowsHide: true, stdio: 'ignore', timeout: 10000 })
+  } else {
+    try { proc.kill('SIGKILL') } catch {}
+  }
+}
+
+class McpProxy {
+  constructor(options) {
+    this.input = options.input
+    this.output = options.output
+    this.args = options.args || []
+    this.spawnProcess = options.spawnProcess || spawnProcess
+    this.killTree = options.killTree || killTree
+    this.log = options.log || (() => {})
+    this.onExit = options.onExit || (() => {})
+    this.promote = options.promote || (() => {})
+    this.recordFailure = options.recordFailure || (() => {})
+    this.handshakeTimeoutMs = options.handshakeTimeoutMs ?? 15000
+    this.idleWaitMs = options.idleWaitMs ?? 30000
+    this.drainTimeoutMs = options.drainTimeoutMs ?? 5000
+    this.exitTimeoutMs = options.exitTimeoutMs ?? 10000
+    this.probationMs = options.probationMs ?? 60000
+    this.busyBackoffMs = options.busyBackoffMs ?? 2 * 60 * 1000
+    this.now = options.now || Date.now
+    this.generation = 0
+    this.nextInternal = 0
+    this.clientPending = new Map() // client -> runtime request id -> { rt, method }
+    this.serverPending = new Map() // runtime -> client request id -> { rt }
+    this.progressOwners = new Map() // progress token of a runtime -> client request -> runtime
+    this.queue = []
+    this.frozen = false
+    this.switching = false
+    this.attempted = new Set()
+    this.busyCount = 0
+    this.retryAt = 0
+    this.clientInit = null
+    this.clientInitialized = null
+    this.serverInit = null
+    this.exiting = false
+    this.drainWaiters = []
+    this.closing = new Set()
+  }
+
+  start(runtime, fallback) {
+    this.fallback = fallback || null
+    this.current = this.startRuntime(runtime)
+    this.current.trial = !!fallback
+    this.clientReader = new LineReader(line => this.fromClient(line))
+    this.input.on('data', chunk => this.clientReader.push(chunk))
+    this.input.on('end', () => this.shutdown())
+    this.input.on('error', () => this.shutdown())
+    this.output.on('error', () => this.shutdown())
+  }
+  get version() { return this.current?.runtime.version }
+  get ready() { return !!(this.serverInit && this.clientInitialized && !this.exiting && !this.restarting) }
+  isClaudeCode() { return CLAUDE_CODE.test(String(this.clientInit?.params?.clientInfo?.name || '')) }
+
+  startRuntime(runtime) {
+    const rt = { runtime, generation: ++this.generation, internal: new Map(), closing: false, alive: true, startedAt: this.now() }
+    rt.proc = this.spawnProcess(runtime, this.args)
+    const reader = new LineReader(line => this.fromRuntime(rt, line))
+    rt.proc.stdout.on('data', chunk => reader.push(chunk))
+    rt.proc.stdin.on('error', () => {})
+    rt.exited = new Promise(resolve => {
+      let done = false
+      const finish = (code, signal) => {
+        if (done) return
+        done = true; rt.alive = false; rt.code = code; rt.signal = signal
+        clearTimeout(rt.probationTimer)
+        for (const waiter of rt.internal.values()) waiter.reject(new Error('runtime exited'))
+        rt.internal.clear()
+        resolve()
+        this.runtimeExited(rt)
+      }
+      rt.proc.on('close', finish)
+      rt.proc.on('error', error => { rt.spawnError = error; finish(null, null) })
+    })
+    return rt
+  }
+
+  send(rt, message) {
+    if (!rt.alive) return false
+    try { rt.proc.stdin.write(typeof message === 'string' ? `${message}\n` : `${JSON.stringify(message)}\n`); return true } catch { return false }
+  }
+  reply(message) {
+    try { this.output.write(`${typeof message === 'string' ? message : JSON.stringify(message)}\n`) } catch {}
+  }
+  /** Resolves true once everything already written to the client has been handed to the OS, false on timeout. */
+  outputFlushed(ms = this.drainTimeoutMs) {
+    const limit = timeout(ms, 'output flush timed out')
+    const written = new Promise(resolve => { try { this.output.write('', () => resolve()) } catch { resolve() } })
+    return Promise.race([written, limit]).then(() => true, () => false).finally(() => limit.cancel())
+  }
+  request(rt, method, params, ms = this.handshakeTimeoutMs) {
+    const id = `${INTERNAL}${rt.generation}:${++this.nextInternal}`
+    const limit = timeout(ms, `${method} timed out`)
+    const answer = new Promise((resolve, reject) => {
+      rt.internal.set(id, { resolve, reject })
+      if (!this.send(rt, { jsonrpc: '2.0', id, method, ...(params === undefined ? {} : { params }) })) reject(new Error('runtime is not running'))
+    })
+    return Promise.race([answer, limit]).finally(() => { limit.cancel(); rt.internal.delete(id) })
+  }
+  /** Replays the client's initialize on another runtime; its response never reaches the client. */
+  async handshake(rt) {
+    const exited = rt.exited.then(() => { throw new Error(`exited during startup (${rt.spawnError?.message || rt.signal || rt.code})`) })
+    exited.catch(() => {})
+    return Promise.race([this.request(rt, 'initialize', this.clientInit.params), exited])
+  }
+
+  // ── client -> runtime ─────────────────────────────────────────────────
+  fromClient(line) {
+    let message
+    try { message = JSON.parse(line) } catch { message = undefined }
+    if (isRequest(message) && message.method === 'initialize' && !this.clientInit) {
+      this.clientInit = message
+      this.frozen = true // nothing else goes out until the runtime answers initialize
+      this.initKey = idKey(message.id)
+      this.forwardRequest(this.current, message)
+      if (this.current.trial) this.watchTrial(this.current)
+      return
+    }
+    // Before initialize the runtime only accepts initialize: it exits on anything else. Clients may
+    // probe first (Claude Code sends `server/discover`), so answer such requests here and drop the rest.
+    if (!this.clientInit && this.initKey == null) {
+      if (isRequest(message)) this.reply({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Method not found: ${message.method}` } })
+      return
+    }
+    if (isResponse(message)) return this.routeResponse(message)
+    if (isNotification(message) && message.method === 'notifications/cancelled') return this.routeCancel(message, line)
+    if (isNotification(message) && message.method === 'notifications/progress') {
+      // Client progress only refers to a runtime's own requests: it goes to that runtime or nowhere,
+      // never to a successor.
+      const owner = this.progressOwners.get(idKey(message.params?.progressToken))
+      if (owner?.alive && !owner.closing) this.send(owner, line)
+      return
+    }
+    if (this.frozen) return this.queue.push({ line, message })
+    this.dispatch(line, message)
+  }
+  dispatch(line, message) {
+    if (isNotification(message) && message.method === 'notifications/initialized') this.clientInitialized = message
+    if (isRequest(message)) return this.forwardRequest(this.current, message, line)
+    this.send(this.current, line)
+  }
+  forwardRequest(rt, message, line) {
+    this.clientPending.set(idKey(message.id), { rt, method: message.method })
+    if (!this.send(rt, line || message)) this.failRequest(message.id, 'PandaNpc MCP runtime is not running')
+  }
+  routeResponse(message) {
+    const key = idKey(message.id)
+    const entry = this.serverPending.get(key)
+    this.serverPending.delete(key)
+    if (entry) {
+      if (entry.rt.alive) this.send(entry.rt, message)
+    }
+    this.checkDrained()
+  }
+  routeCancel(message, line) {
+    const key = idKey(message.params?.requestId)
+    const entry = this.clientPending.get(key)
+    if (entry) return void this.send(entry.rt, line)
+    // A cancel for a queued request stays in order behind it; one for a finished or
+    // previous-runtime request has nothing left to cancel.
+    if (this.queue.some(q => isRequest(q.message) && idKey(q.message.id) === key)) this.queue.push({ line, message })
+  }
+  flush() {
+    this.frozen = false
+    const queued = this.queue
+    this.queue = []
+    for (const { line, message } of queued) {
+      if (this.frozen) { this.queue.push({ line, message }); continue }
+      this.dispatch(line, message)
+    }
+  }
+  failRequest(id, text) {
+    this.clientPending.delete(idKey(id))
+    this.reply({ jsonrpc: '2.0', id, error: { code: -32603, message: text } })
+  }
+
+  // ── runtime -> client ─────────────────────────────────────────────────
+  fromRuntime(rt, line) {
+    let message
+    try { message = JSON.parse(line) } catch { message = undefined }
+    if (isResponse(message) && typeof message.id === 'string' && rt.internal.has(message.id)) {
+      const waiter = rt.internal.get(message.id)
+      return message.error ? waiter.reject(new Error(message.error.message || 'request failed')) : waiter.resolve(message.result)
+    }
+    if (rt !== this.current) {
+      // A candidate being handshaken may not talk to the client; answer its requests itself.
+      if (isRequest(message)) this.send(rt, { jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Not available during runtime handover' } })
+      return
+    }
+    if (isResponse(message)) {
+      const key = idKey(message.id)
+      const entry = this.clientPending.get(key)
+      this.clientPending.delete(key)
+      if (key === this.initKey && !this.serverInit) {
+        if (message.result) return this.initialized(rt, message)
+        if (rt.trial) return void this.abandonTrial(rt, 'initialize returned an error')
+        this.clientInit = null // let the client retry initialize
+        this.reply(line)
+        return this.flush()
+      }
+      if (entry?.method === 'tools/call' && message.result && !message.result.isError) this.confirm(rt)
+      this.reply(line)
+      return this.checkDrained()
+    }
+    if (isRequest(message)) {
+      const token = progressToken(message)
+      this.serverPending.set(idKey(message.id), { rt })
+      if (token !== undefined) {
+        // Late progress may follow the response, so owners are kept (bounded) rather than removed.
+        this.progressOwners.set(idKey(token), rt)
+        if (this.progressOwners.size > 1000) this.progressOwners.delete(this.progressOwners.keys().next().value)
+      }
+    }
+    this.reply(line)
+  }
+  initialized(rt, message) {
+    this.serverInit = message.result
+    // Advertise tools.listChanged so the client refreshes after a swap that changed the tool list.
+    const result = { ...message.result, capabilities: { ...message.result.capabilities } }
+    result.capabilities.tools = { ...(result.capabilities.tools || {}), listChanged: true }
+    if (rt.trial) {
+      rt.trial = false
+      rt.cancelTrial?.()
+      this.probation(rt, this.fallback)
+      this.fallback = null
+    } else if (this.fallback) {
+      rt.fallback = this.fallback
+      this.fallback = null
+    }
+    this.reply({ ...message, result })
+    this.flush()
+  }
+  /** A new runtime becomes the default only after it proved itself in this session. */
+  probation(rt, fallback) {
+    rt.fallback = fallback || null
+    rt.probation = true
+    clearTimeout(rt.probationTimer)
+    rt.probationTimer = setTimeout(() => this.confirm(rt), this.probationMs)
+    rt.probationTimer.unref?.()
+  }
+  confirm(rt) {
+    if (!rt.probation || !rt.alive || rt !== this.current) return
+    rt.probation = false
+    clearTimeout(rt.probationTimer)
+    this.promote(rt.runtime)
+  }
+  /** A startup candidate that dies or stalls before answering initialize is replaced by the fallback. */
+  watchTrial(rt) {
+    const limit = timeout(this.handshakeTimeoutMs, 'initialize timed out')
+    limit.catch(() => { if (rt.trial && rt === this.current) this.abandonTrial(rt, 'initialize timed out') })
+    rt.exited.then(() => limit.cancel())
+    rt.cancelTrial = limit.cancel
+  }
+  abandonTrial(rt, reason) {
+    if (!rt.trial || !this.fallback || this.exiting) return false
+    rt.trial = false
+    rt.cancelTrial?.()
+    this.log(`New runtime ${rt.runtime.version} failed to start (${reason}); using ${this.fallback.version}`)
+    this.recordFailure(rt.runtime.version, reason)
+    this.attempted.add(rt.runtime.version)
+    this.closeInBackground(rt)
+    this.clientPending.delete(this.initKey)
+    const next = this.startRuntime(this.fallback)
+    this.fallback = null
+    this.current = next
+    if (this.clientInit) this.forwardRequest(next, this.clientInit)
+    return true
+  }
+
+  // ── lifecycle ─────────────────────────────────────────────────────────
+  runtimeExited(rt) {
+    if (rt.closing || this.exiting) return
+    if (rt !== this.current) return
+    const reason = rt.spawnError ? rt.spawnError.message : `exit ${rt.signal || rt.code}`
+    if (rt.trial && this.abandonTrial(rt, reason)) return
+    // Never replay requests on another runtime: they may not be idempotent.
+    for (const [key, entry] of [...this.clientPending]) {
+      if (entry.rt === rt) this.failRequest(JSON.parse(key), 'PandaNpc MCP runtime exited before responding')
+    }
+    for (const [key, entry] of [...this.serverPending]) {
+      if (entry.rt === rt) this.serverPending.delete(key)
+    }
+    const fallback = rt.fallback && this.serverInit && this.clientInitialized
+    // Going back to the previous runtime always retires the crashed one, even after it was confirmed:
+    // otherwise the watcher would switch to it again and a reproducible crash would loop.
+    if (rt.probation || fallback) {
+      this.attempted.add(rt.runtime.version)
+      this.recordFailure(rt.runtime.version, `${rt.probation ? 'stopped before it was confirmed' : 'stopped after it was confirmed'} (${reason})`)
+    }
+    this.log(`PandaNpc MCP runtime ${rt.runtime.version} stopped (${reason})`)
+    if (fallback) return void this.restart(rt, rt.fallback)
+    this.finish(rt.code, rt.signal, rt.spawnError)
+  }
+  /** Brings back the runtime a crashed one replaced, re-using the cached handshake. */
+  async restart(crashed, runtime) {
+    this.restarting = true
+    this.frozen = true
+    let next
+    try {
+      next = this.startRuntime(runtime)
+      const limit = timeout(this.handshakeTimeoutMs, 'initialize timed out')
+      try { await Promise.race([this.handshake(next), limit]) } finally { limit.cancel() }
+      this.send(next, this.clientInitialized)
+      if (this.exiting) return
+      this.current = next
+      this.log(`PandaNpc MCP went back to ${runtime.version} after ${crashed.runtime.version} stopped`)
+      this.flush()
+      if (this.isClaudeCode()) this.reply({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' })
+    } catch (error) {
+      this.log(`PandaNpc MCP could not restart ${runtime.version} (${error.message})`)
+      if (next) this.closeInBackground(next)
+      this.finish(crashed.code || 1, null)
+    } finally { this.restarting = false }
+  }
+  async closeRuntime(rt, signal) {
+    rt.closing = true
+    clearTimeout(rt.probationTimer)
+    if (!rt.alive) return
+    try { rt.proc.stdin.end() } catch {}
+    if (signal && process.platform !== 'win32') { try { rt.proc.kill(signal) } catch {} }
+    const limit = timeout(this.exitTimeoutMs, 'exit timed out')
+    try { await Promise.race([rt.exited, limit]) } catch {
+      this.log(`PandaNpc MCP runtime ${rt.runtime.version} did not exit; terminating it`)
+      this.killTree(rt.proc)
+      const last = timeout(5000, 'kill timed out')
+      await Promise.race([rt.exited, last]).catch(() => {})
+      last.cancel()
+    } finally { limit.cancel() }
+  }
+  closeInBackground(rt) {
+    const closing = this.closeRuntime(rt).finally(() => this.closing.delete(closing))
+    this.closing.add(closing)
+  }
+  async shutdown(signal) {
+    if (this.exiting) return
+    this.exiting = true
+    const rt = this.current
+    await Promise.all([this.candidate && this.closeRuntime(this.candidate), rt && this.closeRuntime(rt, signal), ...this.closing])
+    this.finish(rt?.code, rt?.signal)
+  }
+  finish(code, signal, error) {
+    if (this.finished) return
+    this.finished = true
+    this.exiting = true
+    this.onExit({ code, signal, error })
+  }
+
+  // ── hot swap ──────────────────────────────────────────────────────────
+  pendingFor(rt) {
+    for (const entry of this.clientPending.values()) if (entry.rt === rt) return true
+    for (const entry of this.serverPending.values()) if (entry.rt === rt) return true
+    return rt.internal.size > 0
+  }
+  checkDrained() {
+    const waiters = this.drainWaiters
+    this.drainWaiters = []
+    for (const w of waiters) { if (!this.pendingFor(w.rt)) w.resolve(true); else this.drainWaiters.push(w) }
+  }
+  /** Resolves true once `rt` has nothing in flight, false after `ms`. */
+  idle(rt, ms) {
+    if (!this.pendingFor(rt)) return Promise.resolve(true)
+    return new Promise(resolve => {
+      const waiter = { rt, resolve: value => { clearTimeout(timer); resolve(value) } }
+      const timer = setTimeout(() => { this.drainWaiters = this.drainWaiters.filter(w => w !== waiter); resolve(false) }, ms)
+      this.drainWaiters.push(waiter)
+    })
+  }
+  async listTools(rt) {
+    const tools = []
+    let cursor
+    for (let page = 0; page < 50; page++) {
+      const result = await this.request(rt, 'tools/list', cursor ? { cursor } : {})
+      tools.push(...(result?.tools || []))
+      cursor = result?.nextCursor
+      if (!cursor) break
+    }
+    return tools
+  }
+  compatible(result) {
+    if (!result || result.protocolVersion !== this.serverInit.protocolVersion) return 'protocol version differs'
+    // tools.listChanged is ignored: the proxy always advertises it to the client (see initialized()),
+    // so a runtime that starts or stops declaring it does not change what the client sees.
+    const strip = caps => { const copy = JSON.parse(JSON.stringify(caps || {})); if (copy.tools) delete copy.tools.listChanged; return canonical(copy) }
+    return strip(result.capabilities) === strip(this.serverInit.capabilities) ? null : 'capabilities differ'
+  }
+  busy() {
+    this.busyCount++
+    this.retryAt = this.now() + Math.min(this.busyBackoffMs * 2 ** Math.min(this.busyCount - 1, 30), 60 * 60 * 1000)
+    return 'busy'
+  }
+  /**
+   * Returns 'switched', 'deferred' (kept for a later session), 'busy' (retry later), 'failed' or
+   * 'skipped'. Never loses or reorders client traffic; the old runtime stays in place on failure.
+   */
+  async hotSwap(runtime) {
+    if (!this.ready || this.switching || this.attempted.has(runtime.version) || runtime.version === this.version) return 'skipped'
+    if (this.now() < this.retryAt) return 'skipped'
+    this.switching = true
+    let next
+    try {
+      next = this.candidate = this.startRuntime(runtime)
+      const start = timeout(this.handshakeTimeoutMs, 'initialize timed out')
+      let init
+      try { init = await Promise.race([this.handshake(next), start]) } finally { start.cancel() }
+      const problem = this.compatible(init)
+      if (problem) {
+        this.attempted.add(runtime.version)
+        this.log(`PandaNpc MCP ${runtime.version} is not compatible with this session (${problem}); it will be used by the next session`)
+        return 'deferred'
+      }
+      this.send(next, this.clientInitialized)
+      const [before, after] = await Promise.all([this.listTools(this.current), this.listTools(next)])
+      const toolsChanged = toolsFingerprint(before) !== toolsFingerprint(after)
+      const instructionsChanged = (init.instructions || '') !== (this.serverInit.instructions || '')
+      if (instructionsChanged) this.log(`PandaNpc MCP ${runtime.version} changes the server instructions`)
+      // No client can refresh instructions mid-session, so an instructions change always waits for the next session.
+      if (instructionsChanged || (toolsChanged && !this.isClaudeCode())) {
+        this.attempted.add(runtime.version)
+        this.log(`PandaNpc MCP ${runtime.version} changes the ${instructionsChanged ? 'instructions' : 'tool list'}; it will be used by the next session`)
+        return 'deferred'
+      }
+      const old = this.current
+      // Freeze only at an idle moment, and only briefly: a busy session is retried later.
+      if (!await this.idle(old, this.idleWaitMs)) return this.busy()
+      this.frozen = true
+      if (!await this.idle(old, this.drainTimeoutMs)) { this.flush(); return this.busy() }
+      // A client that is not reading stdout keeps the old runtime; unfreeze and retry later.
+      if (!await this.outputFlushed()) { this.flush(); return this.busy() }
+      if (!next.alive || this.exiting) throw new Error('new runtime exited before handover')
+      if (old !== this.current) throw new Error('runtime changed during handover')
+      this.current = next
+      this.candidate = null
+      this.serverInit = { ...this.serverInit, ...init }
+      this.probation(next, old.runtime)
+      this.closeInBackground(old) // stdin EOF: the old runtime stops sync and releases its lease
+      this.flush()
+      if (toolsChanged) this.reply({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' })
+      this.busyCount = 0
+      this.log(`PandaNpc MCP switched to ${runtime.version} without restarting the session`)
+      return 'switched'
+    } catch (error) {
+      this.attempted.add(runtime.version)
+      this.recordFailure(runtime.version, error.message)
+      this.log(`PandaNpc MCP ${runtime.version} could not take over (${error.message}); keeping ${this.version}`)
+      if (this.frozen && !this.exiting && this.current.alive && !this.restarting) this.flush()
+      return 'failed'
+    } finally {
+      if (this.candidate) { const c = this.candidate; this.candidate = null; await this.closeRuntime(c) }
+      this.switching = false
+    }
+  }
+}
+
+module.exports = { McpProxy, LineReader, toolsFingerprint, killTree }

package/updater.js

@@ -9,8 +9,13 @@ const { fetchText } = require('./network')
 const pkg = require('./package.json')
 
 const PROTOCOL = 1
-const INTERVAL = 6 * 60 * 60 * 1000
+const INTERVAL = 60 * 60 * 1000
+const JITTER = 10 * 60 * 1000
 const RETRY_INTERVAL = 15 * 60 * 1000
+const MAX_RETRY_INTERVAL = 6 * 60 * 60 * 1000
+// A candidate that fails a real handshake is not retried for 1h, 4h, 16h... capped at a week.
+const FAILURE_BACKOFF = 60 * 60 * 1000
+const MAX_FAILURE_BACKOFF = 7 * 24 * 60 * 60 * 1000
 const REGISTRY = 'https://registry.npmjs.org/@pandanpc%2fmcp-server/latest'
 const quiet = { log() {}, warn() {} }
 
@@ -34,27 +39,82 @@ function writeJson(file, value) {
   try { fs.writeFileSync(temp, JSON.stringify(value), { mode: 0o600 }); fs.renameSync(temp, file) }
   finally { try { fs.unlinkSync(temp) } catch {} }
 }
-function activeRuntime(root, bundledVersion = pkg.version, platform = process.platform) {
+function jitter(random = Math.random) { return Math.floor(random() * JITTER) }
+function successDelay(random) { return INTERVAL + jitter(random) }
+function failureDelay(failures, random) { return Math.min(RETRY_INTERVAL * 2 ** Math.max(0, failures - 1), MAX_RETRY_INTERVAL) + jitter(random) }
+// Launchers re-check the candidate every minute; hash a given file version only once.
+const hashes = new Map()
+function hashOf(file, stat) {
+  const key = `${file}|${stat.mtimeMs}|${stat.size}|${stat.ino}`
+  if (!hashes.has(key)) hashes.set(key, crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'))
+  return hashes.get(key)
+}
+// Verifies a pointer (active.json / candidate.json entry) and returns the runnable runtime or null.
+function verifyEntry(root, entry, bundledVersion, platform) {
   try {
-    const active = readJson(path.join(root, 'active.json'))
+    const active = entry
     if (!active || !versionParts(active.version) || compareVersions(active.version, bundledVersion) <= 0) return null
     if (!/^[a-zA-Z0-9.-]+$/.test(active.directory) || !active.directory.startsWith(active.version + '-')) return null
     if (!/^[a-f0-9]{64}$/.test(active.checksum)) return null
     const file = path.join(root, active.directory, binaryName(platform, active.version))
     const stat = fs.lstatSync(file)
     if (!stat.isFile() || stat.size <= 0 || stat.size > 64 * 1024 * 1024) return null
-    if (crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== active.checksum) return null
+    if (hashOf(file, stat) !== active.checksum) return null
     if (platform !== 'win32') fs.accessSync(file, fs.constants.X_OK)
-    return { file, version: active.version }
+    return { file, version: active.version, directory: active.directory, checksum: active.checksum }
   } catch { return null }
 }
+function failures(root) { return readJson(path.join(root, 'failed.json')) || {} }
+function inBackoff(root, version, now = Date.now()) {
+  const entry = failures(root)[version]
+  return !!entry && Number.isFinite(entry.until) && entry.until > now
+}
+// A downloaded version that failed a real start/handshake; it is skipped until its backoff ends.
+function recordFailure(root, version, reason, now = Date.now()) {
+  try {
+    const all = failures(root)
+    const count = (all[version]?.count || 0) + 1
+    all[version] = { count, until: now + Math.min(FAILURE_BACKOFF * 4 ** (count - 1), MAX_FAILURE_BACKOFF), reason: String(reason || '').slice(0, 200) }
+    writeJson(path.join(root, 'failed.json'), all)
+  } catch {}
+}
+function activeRuntime(root, bundledVersion = pkg.version, platform = process.platform, now = Date.now()) {
+  const active = readJson(path.join(root, 'active.json'))
+  if (!active) return null
+  if (!inBackoff(root, active.version, now)) {
+    const runtime = verifyEntry(root, active, bundledVersion, platform)
+    if (runtime) return runtime
+  }
+  // The promoted version crashed after taking over: fall back to the one it replaced.
+  return active.previous && !inBackoff(root, active.previous.version, now) ? verifyEntry(root, active.previous, bundledVersion, platform) : null
+}
+// Downloaded and probed, but not yet proven by a real MCP handshake.
+function candidateRuntime({ root = cacheRoot(), bundledVersion = pkg.version, platform = process.platform, now = Date.now() } = {}) {
+  const candidate = readJson(path.join(root, 'candidate.json'))
+  if (!candidate || inBackoff(root, candidate.version, now)) return null
+  const current = activeRuntime(root, bundledVersion, platform, now)
+  if (!versionParts(candidate.version) || (current && compareVersions(candidate.version, current.version) <= 0)) return null
+  return verifyEntry(root, candidate, bundledVersion, platform)
+}
+function peekCandidateVersion(root = cacheRoot()) {
+  const candidate = readJson(path.join(root, 'candidate.json'))
+  return candidate && versionParts(candidate.version) ? candidate.version : null
+}
+// Called only after the candidate completed a real initialize handshake.
+function promoteCandidate(runtime, { root = cacheRoot(), bundledVersion = pkg.version, platform = process.platform } = {}) {
+  const current = activeRuntime(root, bundledVersion, platform)
+  if (current && compareVersions(current.version, runtime.version) >= 0) return
+  const previous = current ? { version: current.version, directory: current.directory, checksum: current.checksum } : undefined
+  writeJson(path.join(root, 'active.json'), { version: runtime.version, directory: runtime.directory, checksum: runtime.checksum, ...(previous ? { previous } : {}) })
+  if (readJson(path.join(root, 'candidate.json'))?.version === runtime.version) { try { fs.unlinkSync(path.join(root, 'candidate.json')) } catch {} }
+}
 function selectRuntime({ root = cacheRoot(), bundledVersion = pkg.version, platform = process.platform, disabled = process.env.PANDANPC_MCP_AUTO_UPDATE === '0' } = {}) {
   const bundled = { file: path.join(__dirname, 'bin', binaryName(platform, bundledVersion)), version: bundledVersion }
   return (!disabled && activeRuntime(root, bundledVersion, platform)) || bundled
 }
 function due(root, now = Date.now()) {
   const state = readJson(path.join(root, 'check.json'))
-  return !state || !Number.isFinite(state.nextCheck) || state.nextCheck <= now || state.nextCheck > now + INTERVAL
+  return !state || !Number.isFinite(state.nextCheck) || state.nextCheck <= now || state.nextCheck > now + MAX_RETRY_INTERVAL + JITTER
 }
 function acquireLock(root, now) {
   const file = path.join(root, 'update.lock')
@@ -90,6 +150,7 @@ async function checkForUpdates(options = {}) {
   const platformInfo = options.platformInfo || detectPlatform()
   const fetchTextFn = options.fetchTextFn || fetchText
   const now = (options.now || Date.now)()
+  const random = options.random || Math.random
   fs.mkdirSync(root, { recursive: true, mode: 0o700 })
   if (!options.force && !due(root, now)) return { status: 'throttled' }
   const unlock = acquireLock(root, now)
@@ -97,17 +158,23 @@ async function checkForUpdates(options = {}) {
   let directory
   try {
     if (!options.force && !due(root, now)) return { status: 'throttled' }
-    writeJson(path.join(root, 'check.json'), { nextCheck: now + RETRY_INTERVAL })
+    const failed = (readJson(path.join(root, 'check.json'))?.failures || 0) + 1
+    writeJson(path.join(root, 'check.json'), { nextCheck: now + failureDelay(failed, random), failures: failed })
     const metadata = JSON.parse(await fetchTextFn(REGISTRY))
     if (!versionParts(metadata.version)) throw new Error('Invalid release version')
-    const current = activeRuntime(root, bundledVersion, platform)
-    const currentVersion = current?.version || bundledVersion
+    const current = activeRuntime(root, bundledVersion, platform, now)
+    const pending = candidateRuntime({ root, bundledVersion, platform, now })
+    const currentVersion = pending?.version || current?.version || bundledVersion
     if (compareVersions(metadata.version, currentVersion) <= 0) {
-      writeJson(path.join(root, 'check.json'), { nextCheck: now + INTERVAL })
+      writeJson(path.join(root, 'check.json'), { nextCheck: now + successDelay(random) })
       return { status: 'current', version: currentVersion }
     }
+    if (inBackoff(root, metadata.version, now)) {
+      writeJson(path.join(root, 'check.json'), { nextCheck: now + successDelay(random) })
+      return { status: 'backoff', version: metadata.version }
+    }
     if (metadata.pandanpcUpdaterProtocol !== PROTOCOL) {
-      writeJson(path.join(root, 'check.json'), { nextCheck: now + INTERVAL, manualUpdateRequired: metadata.version })
+      writeJson(path.join(root, 'check.json'), { nextCheck: now + successDelay(random), manualUpdateRequired: metadata.version })
       return { status: 'manual-update-required', version: metadata.version }
     }
     const version = metadata.version
@@ -119,11 +186,12 @@ async function checkForUpdates(options = {}) {
       baseUrl: `https://cos.pandanpc.com/mcp-server/v${version}`, fetchTextFn,
       ...(options.downloadFn ? { downloadFn: options.downloadFn } : {}), logger: quiet })
     await (options.probeFn || probeBinary)(file)
-    const newer = activeRuntime(root, bundledVersion, platform)
+    const newer = candidateRuntime({ root, bundledVersion, platform, now }) || activeRuntime(root, bundledVersion, platform, now)
     if (newer && compareVersions(newer.version, version) >= 0) return { status: 'current', version: newer.version }
-    writeJson(path.join(root, 'active.json'), { version, directory: name, checksum: result.checksum })
+    // Only a candidate: a launcher promotes it to active.json after a real MCP handshake succeeds.
+    writeJson(path.join(root, 'candidate.json'), { version, directory: name, checksum: result.checksum })
     directory = null // published versions may be in use; never delete them automatically
-    writeJson(path.join(root, 'check.json'), { nextCheck: now + INTERVAL })
+    writeJson(path.join(root, 'check.json'), { nextCheck: now + successDelay(random) })
     return { status: 'ready', version }
   } catch (error) {
     return { status: 'failed', error: error.message }
@@ -142,4 +210,4 @@ function startBackgroundUpdate() {
   } catch {} // updates must never prevent an MCP session from starting
 }
 if (require.main === module) checkForUpdates().catch(() => {})
-module.exports = { compareVersions, selectRuntime, checkForUpdates, startBackgroundUpdate }
+module.exports = { compareVersions, selectRuntime, checkForUpdates, startBackgroundUpdate, candidateRuntime, peekCandidateVersion, promoteCandidate, recordFailure, inBackoff, cacheRoot }