thinkpool-pair 0.7.238 → 0.7.240

package/bridge.mjs

@@ -50,6 +50,7 @@ import { validateProviderSwitch, providerSwitchPlan, BUILTIN_PROVIDER } from './
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { z } from 'zod'
 import { readCodexDefaultModel, readCodexModels, codexConfigForMode, codexThreadCanResume } from './codex-session.mjs'
+import { withMcpSessionFactory } from './codex-mcp-http.mjs'
 import { startStructuredSession } from './runtime-session.mjs'
 import { defaultStructuredMode, shouldDeferStructuredRuntime, structuredRuntimeForCommand, structuredRuntimeMetadata, structuredRuntimeSupportsMode } from './runtime-registry.mjs'
 import { probeHermesRuntime } from './hermes-probe.mjs'
@@ -2052,7 +2053,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
   // own `id` (excluded) + `entry` (per-turn call counter, reset by the code-turn
   // handler). Auto-allowed by the PreToolUse gate (mcp__thinkpool__ prefix).
   // Spec: docs/specs/2026-06-28-cross-terminal-awareness.md
-  const peekServer = createSdkMcpServer({
+  const createPeekServer = () => createSdkMcpServer({
     name: 'thinkpool',
     version: '1.0.0',
     tools: [
@@ -2420,6 +2421,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
       )] : []),
     ],
   })
+  const peekServer = withMcpSessionFactory(createPeekServer)
   // S5 (slice 1b) — the review-lane write-block, wired into the live PreToolUse path.
   // Null for builder lanes (no reviewSliceRoots) → their toolset is UNCHANGED. For a review
   // lane, deny a mutating tool call if it targets ANY reviewed slice's worktree, allowing the

package/codex-mcp-http.mjs

@@ -6,18 +6,47 @@ import http from 'node:http'
 import { randomUUID } from 'node:crypto'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
 
+export function withMcpSessionFactory(createSessionServer) {
+  if (typeof createSessionServer !== 'function') throw new TypeError('MCP session factory must be a function')
+  return Object.assign(createSessionServer(), { createSessionServer })
+}
+
 export async function startCodexMcpHttp({ sdkServer, host = '127.0.0.1' } = {}) {
-  const instance = sdkServer?.instance
-  if (!instance?.connect) throw new TypeError('Codex MCP requires an SDK MCP server instance')
+  const createSessionServer = sdkServer?.createSessionServer
+  const initialInstance = sdkServer?.instance
+  if (!initialInstance?.connect || typeof createSessionServer !== 'function') {
+    throw new TypeError('Codex MCP requires an SDK MCP server and createSessionServer factory')
+  }
 
   const secretPath = `/mcp/${randomUUID()}`
-  // Stateful sessions (not stateless): a stateless transport (sessionIdGenerator
-  // undefined) 500s on the `notifications/initialized` POST that every MCP client
-  // sends right after initialize — it has no session to attach the notification to.
-  // Each connecting Codex process gets its own session id; the bridge owns one
-  // server per lane, so the in-memory session map is bounded by the live lanes.
-  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() })
-  await instance.connect(transport)
+  // Stateful sessions are required: this SDK's stateless transport rejects the
+  // `notifications/initialized` POST sent by every MCP client. A transport is
+  // single-initialize, though, while Codex App Server -> exec fallback and Hermes
+  // crash recovery both start a new client against the same lane endpoint.
+  // Keep exactly one active child session per lane. A new initialize atomically
+  // retires the old server+transport before receiving its own isolated instance.
+  let active = null
+
+  const retireActive = async () => {
+    const current = active
+    active = null
+    if (!current) return
+    await Promise.allSettled([
+      current.instance.close(),
+      current.transport.close(),
+    ])
+  }
+
+  const beginSession = async () => {
+    await retireActive()
+    const next = createSessionServer()
+    const instance = next?.instance
+    if (!instance?.connect) throw new TypeError('Codex MCP session factory did not return an SDK MCP server instance')
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() })
+    await instance.connect(transport)
+    active = { instance, transport }
+    return active
+  }
 
   const server = http.createServer(async (req, res) => {
     if (req.url !== secretPath) {
@@ -25,7 +54,19 @@ export async function startCodexMcpHttp({ sdkServer, host = '127.0.0.1' } = {})
       return
     }
     try {
-      await transport.handleRequest(req, res)
+      const sessionId = req.headers['mcp-session-id']
+      let target = active
+      if (!sessionId) {
+        if (req.method !== 'POST') {
+          res.writeHead(400).end('missing session')
+          return
+        }
+        target = await beginSession()
+      } else if (!target?.transport?.sessionId || sessionId !== target.transport.sessionId) {
+        res.writeHead(404).end('session not found')
+        return
+      }
+      await target.transport.handleRequest(req, res)
     } catch {
       if (!res.headersSent) res.writeHead(500)
       res.end()
@@ -38,7 +79,7 @@ export async function startCodexMcpHttp({ sdkServer, host = '127.0.0.1' } = {})
       server.listen(0, host, resolve)
     })
   } catch (error) {
-    await transport.close().catch(() => {})
+    await retireActive()
     throw error
   }
   const address = server.address()
@@ -51,7 +92,7 @@ export async function startCodexMcpHttp({ sdkServer, host = '127.0.0.1' } = {})
       if (closed) return
       closed = true
       await Promise.allSettled([
-        transport.close(),
+        retireActive(),
         new Promise((resolve) => server.close(resolve)),
       ])
     },

package/hermes-isolation.mjs

@@ -4,6 +4,7 @@ import path from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'
 import { startHermesSession } from './hermes-session.mjs'
+import { withMcpSessionFactory } from './codex-mcp-http.mjs'
 
 const waitFor = (predicate, timeoutMs = 25_000) => new Promise((resolve, reject) => {
   const started = Date.now()
@@ -36,10 +37,11 @@ export async function verifyHermesMcpIsolation({ rounds = 2, sessionFactory = st
       for (let i = 0; i < 2; i++) {
         const cwd = path.join(root, i === 0 ? 'alpha' : 'beta')
         fs.mkdirSync(cwd)
-        const sdkServer = createSdkMcpServer({
+        const createMarkerServer = () => createSdkMcpServer({
           name: 'thinkpool', version: '1.0.0',
           tools: [tool(markers[i], 'Synthetic ThinkPool lane-isolation marker.', {}, async () => ({ content: [{ type: 'text', text: markers[i] }] }))],
         })
+        const sdkServer = withMcpSessionFactory(createMarkerServer)
         sessions.push(sessionFactory({ cwd, lazy: true, mcpServers: { thinkpool: sdkServer }, onEvent: (event) => events[i].push(event) }))
       }
       sessions.forEach((session) => session.sendTurn('/tools'))

package/launcher.mjs

@@ -16,6 +16,7 @@ import path from 'node:path'
 import { execSync } from 'node:child_process'
 import { detectProvider, fetchModels, ANTHROPIC_COMPATIBLE, gatewayHint } from './byok-detect.mjs'
 import { probeHermesRuntime } from './hermes-probe.mjs'
+import { darwinServiceRunning } from './service.mjs'
 
 const HOME = os.homedir()
 const CFG_DIR = path.join(HOME, '.thinkpool-pair')
@@ -57,13 +58,17 @@ function serviceFile(room) {
   return path.join(startup, `thinkpool-pair-${room || 'account'}.cmd`)
 }
 
-// Ground truth for the header: is the service actually LOADED, not just a plist on disk?
+// Ground truth for the header: is the service actually RUNNING, not just registered?
 // `launchctl load` can silently no-op, leaving a plist that never loads — file-existence
-// would report "installed" while the bridge is off (the 2026-06-26 bug). Query the manager.
+// would report "installed" while the bridge is off (the 2026-06-26 bug). A registered
+// job can also be inactive with no pid, so inspect launchd's live state, not print's exit.
 function serviceLoaded(room) {
   const label = room ? `io.thinkpool.pair.${room.toLowerCase()}` : 'io.thinkpool.pair.account'
   try {
-    if (process.platform === 'darwin') { execSync(`launchctl print gui/$(id -u)/${label}`, { stdio: 'ignore' }); return true }
+    if (process.platform === 'darwin') {
+      const out = execSync(`launchctl print gui/$(id -u)/${label}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      return darwinServiceRunning(out)
+    }
     if (process.platform === 'linux')  { execSync(`systemctl --user is-active --quiet ${label}.service`); return true }
     return fs.existsSync(serviceFile(room)) // Windows: no daemon, file presence is the only proxy
   } catch { return false }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.238",
+  "version": "0.7.240",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {

package/service.mjs

@@ -13,8 +13,9 @@
      • account — `install-service` (no room) → supervises the ACCOUNT
                  supervisor (`npx thinkpool-pair`, bare), which serves
                  every session you're in. Pass room=null for this.
-   Both launch `thinkpool-pair@latest`, so a restart pulls the newest
-   publish; auto-update self-restart lives in bridge.mjs / account.mjs.
+   Pinned services launch an immutable local runtime directly. The optional
+   auto-update tier still resolves `thinkpool-pair@latest`; its self-restart
+   lives in bridge.mjs / account.mjs.
    ───────────────────────────────────────────────────────────── */
 
 import os from 'node:os'
@@ -37,10 +38,16 @@ const label = (room) => {
 const slug = (room) => room || 'account'
 const xml = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
 const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`
-// Stale-proof launch wrapper: wipe any cached thinkpool-pair in the npx store, then exec
-// the pinned package FRESH. Folds update-local-service.sh into the builder — without this a
-// deliberate "Restart & update" (or any KeepAlive restart) can re-serve a stale npx cache,
-// which is what left Max's account bridge stuck on 0.7.75 while @latest was 0.7.78.
+export function sanitizeServicePath(value, platform = process.platform) {
+  const sep = platform === 'win32' ? ';' : ':'
+  return String(value || '').split(sep).filter((part) => part && !part.includes('/.npm/_npx/')).join(sep)
+}
+export function darwinServiceRunning(output) {
+  const text = String(output || '')
+  return /(^|\n)[ \t]*state = running[ \t]*($|\n)/.test(text) && /(^|\n)[ \t]*pid = \d+[ \t]*($|\n)/.test(text)
+}
+// Legacy auto-update services still use npx. Wipe its disposable execution project
+// before resolving the package so an @latest restart cannot re-serve a stale cache.
 // `home` is the platform-correct, runtime-expanded home token ("$HOME" on darwin under
 // /bin/bash; "$$HOME" inside a systemd unit so systemd emits a literal $HOME to bash).
 // npx caches the temporary execution project as a unit. Removing only the package can
@@ -75,15 +82,39 @@ function npmPath(platform = process.platform) {
 // Persistent services never execute through npx. Provision an immutable, versioned
 // runtime from the tarball URL (which bypasses stale npm packument metadata), then point
 // launchd/systemd directly at its bridge.mjs with the current Node binary.
-export function provisionRuntime(version, { exec = execSync } = {}) {
+function runtimeVersion(entry) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(entry), 'package.json'), 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version : null
+  } catch { return null }
+}
+
+export function provisionRuntime(version, { exec = execSync, root = path.join(os.homedir(), '.thinkpool-pair', 'runtimes') } = {}) {
   if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(String(version))) throw new Error(`invalid runtime version: ${version}`)
-  const dir = path.join(os.homedir(), '.thinkpool-pair', 'runtimes', String(version))
+  const dir = path.join(root, String(version))
   const entry = path.join(dir, 'node_modules', 'thinkpool-pair', 'bridge.mjs')
-  if (fs.existsSync(entry)) return entry
-  fs.mkdirSync(dir, { recursive: true })
+  if (fs.existsSync(entry) && runtimeVersion(entry) === String(version)) return entry
+
+  // Install beside the target and only swap it into place after BOTH the entrypoint
+  // and package version prove the payload. A killed/poisoned npm install must never
+  // leave `runtimes/0.7.237` containing 0.7.229 and then pass forever on file existence.
+  const tmp = `${dir}.install-${process.pid}-${Date.now()}`
+  fs.rmSync(tmp, { recursive: true, force: true })
+  fs.mkdirSync(tmp, { recursive: true })
   const tarball = `https://registry.npmjs.org/thinkpool-pair/-/thinkpool-pair-${version}.tgz`
-  exec(`${shq(npmPath())} install --prefix ${shq(dir)} ${shq(tarball)} --prefer-online --no-audit --no-fund`, { stdio: 'inherit', shell: '/bin/bash' })
-  if (!fs.existsSync(entry)) throw new Error(`runtime install completed without ${entry}`)
+  const tmpEntry = path.join(tmp, 'node_modules', 'thinkpool-pair', 'bridge.mjs')
+  try {
+    exec(`${shq(npmPath())} install --prefix ${shq(tmp)} ${shq(tarball)} --prefer-online --no-audit --no-fund`, { stdio: 'inherit', shell: '/bin/bash' })
+    const actual = runtimeVersion(tmpEntry)
+    if (!fs.existsSync(tmpEntry) || actual !== String(version)) {
+      throw new Error(`runtime verification failed: requested ${version}, installed ${actual || 'no valid package'}`)
+    }
+    fs.rmSync(dir, { recursive: true, force: true })
+    fs.renameSync(tmp, dir)
+  } catch (e) {
+    fs.rmSync(tmp, { recursive: true, force: true })
+    throw e
+  }
   return entry
 }
 
@@ -91,10 +122,14 @@ export function provisionRuntime(version, { exec = execSync } = {}) {
 // room falsy → ACCOUNT service (bare `thinkpool-pair`, auto-serves all sessions).
 export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate = false, version = VERSION, staleProof = false, runtimeEntry = null } = {}) {
   const npx = npxPath(platform)
-  const cwd = process.cwd()
+  // Account mode discovers each room's own bound directory, so its supervisor must use
+  // a stable home cwd. Persisting the caller's managed worktree here makes the service
+  // unstartable as soon as that lane is closed and its worktree is removed.
+  const cwd = room ? process.cwd() : os.homedir()
   const id = slug(room)
   const logDir = path.join(os.homedir(), '.thinkpool-pair')
   const log = path.join(logDir, `${id}.log`)
+  const servicePath = sanitizeServicePath(process.env.PATH || '', platform)
   const tail = cmdArgs.length ? ['--', ...cmdArgs] : []
   const desc = room ? `bridge (${room})` : 'account bridge'
   // OS-supervised tiers (launchd KeepAlive / systemd Restart) don't need --supervise.
@@ -116,8 +151,8 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   const autoUpdateEnv = autoUpdate ? { THINKPOOL_PAIR_AUTOUPDATE: '1' } : {}
 
   if (platform === 'darwin') {
-    // launchd KeepAlive supervises. staleProof → wrap in a cache-wiping /bin/bash launch so
-    // every (re)start re-fetches the pinned version fresh (deliberate-update path).
+    // launchd KeepAlive supervises. Stable runtimes execute directly; the legacy npx
+    // shape keeps its cache-wiping wrapper for auto-update compatibility.
     const args = runtimeEntry
       ? [process.execPath, runtimeEntry, ...(room ? [room] : []), ...tail]
       : staleProof
@@ -140,39 +175,12 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   <key>WorkingDirectory</key><string>${xml(cwd)}</string>
   <key>StandardOutPath</key><string>${xml(log)}</string>
   <key>StandardErrorPath</key><string>${xml(log)}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(process.env.PATH || '')}</string>${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}</dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(servicePath)}</string>${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}</dict>
 </dict></plist>\n`
-    // Modern bootstrap/enable, NOT the deprecated `launchctl load`. On current macOS
-    // (Darwin 24/25) `load` silently no-ops for a GUI LaunchAgent — the plist lands on
-    // disk but never loads, so the bridge is "installed" yet off (the 2026-06-26 bug).
-    // Sequence: bootout any existing instance (idempotent reinstall) → WAIT for it to
-    // actually leave the domain (bootout is async; bootstrapping while teardown is in
-    // flight throws "Bootstrap failed: 5: Input/output error") → enable (clears a stale
-    // `disabled` override from a prior bootout / the account-storm cleanup) → bootstrap,
-    // retried on the EIO race → a final `print` so the command's exit code reports the
-    // real loaded state (installService warns if it ends not-loaded).
-    const lbl = label(room), dom = 'gui/$(id -u)'
-    const pr = `launchctl print ${dom}/${lbl} >/dev/null 2>&1`
-    const post = [
-      // Evict any existing instance so the REWRITTEN plist (new pinned version) is what
-      // loads. bootout is async + occasionally sticky: if the old supervised process
-      // won't leave the domain, the follow-up bootstrap throws "Bootstrap failed: 5:
-      // Input/output error" and we'd SILENTLY keep running the OLD pinned version while
-      // reporting success — the 2026-06-30 "Restart & update" stuck-on-0.7.96 bug. So:
-      // bootout, wait for it to actually leave, and if it WON'T, SIGKILL the wedged pid
-      // then bootout again (KeepAlive can't relaunch a job that's booting out).
-      `launchctl bootout ${dom}/${lbl} 2>/dev/null || true`,
-      `for i in $(seq 1 25); do ${pr} || break; sleep 0.2; done`,
-      `if ${pr}; then p=$(launchctl print ${dom}/${lbl} 2>/dev/null | sed -n 's/.*[^a-z]pid = \\([0-9][0-9]*\\).*/\\1/p' | head -1); [ -n "$p" ] && kill -9 "$p" 2>/dev/null || true; launchctl bootout ${dom}/${lbl} 2>/dev/null || true; for i in $(seq 1 25); do ${pr} || break; sleep 0.2; done; fi`,
-      // Clear a stale `disabled` override (from a prior bootout / account-storm cleanup),
-      // then load the rewritten plist from disk, retried on the EIO teardown race.
-      `launchctl enable ${dom}/${lbl} 2>/dev/null || true`,
-      `ok=0; for i in $(seq 1 25); do launchctl bootstrap ${dom} "${file}" 2>/dev/null && { ok=1; break; }; sleep 0.3; done`,
-      // Be HONEST about the outcome: if it never loaded, say so + give the exact manual
-      // recovery — never let a failed reload masquerade as a successful update.
-      `if [ "$ok" != 1 ] && ! ${pr}; then echo "  ⚠ thinkpool-pair: launchd reload FAILED — run by hand: launchctl bootout ${dom}/${lbl} ; launchctl bootstrap ${dom} \\"${file}\\"" >&2; fi`,
-    ].join('; ')
-    return { file, content, logDir, post: [post], note: 'Loaded as a LaunchAgent — starts at login, restarts on crash.' }
+    // The destructive reload is intentionally NOT represented as an inline `post`
+    // command. installService stages this plist and hands the transaction to an
+    // independent one-shot launchd job (buildDarwinReloadHandoff below).
+    return { file, content, logDir, post: [], expectedRuntime: runtimeEntry || verSpec, note: 'Loaded as a LaunchAgent — starts at login, restarts on crash.' }
   }
 
   if (platform === 'linux') {
@@ -202,7 +210,7 @@ RestartSec=2
 # still restarted. Matches the bridge's exit-code contract (stop()=0, restart=non-zero).
 RestartPreventExitStatus=0
 WorkingDirectory=${cwd}
-Environment=PATH=${process.env.PATH || ''}
+Environment=PATH=${servicePath}
 ${autoUpdate ? 'Environment=THINKPOOL_PAIR_AUTOUPDATE=1\n' : ''}StandardOutput=append:${log}
 StandardError=append:${log}
 
@@ -231,9 +239,6 @@ WantedBy=default.target
   throw new Error(`unsupported platform: ${platform}`)
 }
 
-// Blocking sleep (installService runs synchronously from the interactive menu; the
-// user is watching, so we WANT to wait + report the real outcome, not fire-and-forget).
-const sleepMs = (ms) => { try { execSync(`sleep ${(ms / 1000).toFixed(2)}`) } catch { /* noop */ } }
 // Parse both legacy npx commands (`thinkpool-pair@<ver>`) and stable runtime commands
 // (`.../runtimes/<ver>/...`).
 export function parseRunningPairVersions(out) {
@@ -241,35 +246,84 @@ export function parseRunningPairVersions(out) {
   return new Set(versions.map((s) => s.match(/\d+\.\d+\.\d+/)?.[0]).filter(Boolean))
 }
 
-// Which thinkpool-pair versions are running right now. Returns a Set of versions.
-const runningPairVersions = () => {
+// A macOS update can be invoked FROM a ThinkPool Code room hosted by the very account
+// service being replaced. Running `bootout; bootstrap` in that caller is unsafe: bootout
+// tears down the room process tree and can kill the updater before bootstrap. Hand the
+// whole destructive transaction to a separate one-shot launchd job first. It survives
+// the target service's teardown, reloads it, verifies the exact expected runtime in
+// launchd's live definition, and records an atomic result for diagnosis.
+export function buildDarwinReloadHandoff({ targetLabel, targetFile, stagedFile, expectedRuntime, version, nonce = `${process.pid}-${Date.now()}` }) {
+  if (!/^io\.thinkpool\.pair\.[A-Za-z0-9_.-]+$/.test(String(targetLabel))) throw new Error(`invalid service label: ${targetLabel}`)
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(String(version))) throw new Error(`invalid runtime version: ${version}`)
+  const safeNonce = String(nonce).replace(/[^A-Za-z0-9-]/g, '') || String(process.pid)
+  const helperLabel = `io.thinkpool.pair.update.${safeNonce}`
+  const helperFile = path.join(os.homedir(), 'Library', 'LaunchAgents', `${helperLabel}.plist`)
+  const backupFile = `${stagedFile}.previous`
+  const statusFile = path.join(os.homedir(), '.thinkpool-pair', 'update-status.json')
+  const logFile = path.join(os.homedir(), '.thinkpool-pair', 'update.log')
+  const script = [
+    'set -u',
+    'dom="gui/$(id -u)"',
+    `target=${shq(targetLabel)}`,
+    `helper=${shq(helperLabel)}`,
+    `target_file=${shq(targetFile)}`,
+    `staged_file=${shq(stagedFile)}`,
+    `backup_file=${shq(backupFile)}`,
+    `helper_file=${shq(helperFile)}`,
+    `expected=${shq(expectedRuntime)}`,
+    `status=${shq(statusFile)}`,
+    'tmp="$status.tmp.$$"',
+    'ok=0',
+    'had_previous=0',
+    'if [ -f "$target_file" ]; then cp "$target_file" "$backup_file" && had_previous=1; fi',
+    'launchctl bootout "$dom/$target" 2>/dev/null || true',
+    'for i in $(seq 1 40); do launchctl print "$dom/$target" >/dev/null 2>&1 || break; sleep 0.2; done',
+    'cp "$staged_file" "$target_file"',
+    'launchctl enable "$dom/$target" 2>/dev/null || true',
+    'for i in $(seq 1 30); do launchctl bootstrap "$dom" "$target_file" 2>/dev/null && break; sleep 0.3; done',
+    'for i in $(seq 1 60); do if launchctl print "$dom/$target" 2>/dev/null | grep -F -- "$expected" >/dev/null && launchctl print "$dom/$target" 2>/dev/null | grep -F "state = running" >/dev/null; then ok=1; break; fi; sleep 0.5; done',
+    `if [ "$ok" = 1 ]; then printf '%s\\n' '${JSON.stringify({ ok: true, version: String(version) })}' > "$tmp"; else rollback=0; if [ "$had_previous" = 1 ]; then launchctl bootout "$dom/$target" 2>/dev/null || true; for i in $(seq 1 40); do launchctl print "$dom/$target" >/dev/null 2>&1 || break; sleep 0.2; done; cp "$backup_file" "$target_file"; launchctl enable "$dom/$target" 2>/dev/null || true; for i in $(seq 1 30); do if launchctl bootstrap "$dom" "$target_file" 2>/dev/null; then rollback=1; break; fi; sleep 0.3; done; fi; if [ "$rollback" = 1 ]; then printf '%s\\n' '${JSON.stringify({ ok: false, version: String(version), error: 'new runtime not confirmed; previous service restored', rolledBack: true })}' > "$tmp"; else printf '%s\\n' '${JSON.stringify({ ok: false, version: String(version), error: 'new runtime not confirmed and rollback failed', rolledBack: false })}' > "$tmp"; fi; fi`,
+    'mv "$tmp" "$status"',
+    'rm -f "$staged_file" "$backup_file" "$helper_file"',
+    'launchctl bootout "$dom/$helper" >/dev/null 2>&1 || true',
+    'exit "$((1-ok))"',
+  ].join('; ')
+  const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${xml(helperLabel)}</string>
+  <key>ProgramArguments</key><array><string>/bin/bash</string><string>-lc</string><string>${xml(script)}</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>${xml(logFile)}</string>
+  <key>StandardErrorPath</key><string>${xml(logFile)}</string>
+</dict></plist>\n`
+  return { helperLabel, helperFile, backupFile, statusFile, logFile, script, content }
+}
+
+function startDarwinReloadHandoff(a, version) {
+  const stagedFile = path.join(a.logDir, `service-update-${process.pid}-${Date.now()}.plist`)
+  const h = buildDarwinReloadHandoff({ targetLabel: labelFromFile(a.file), targetFile: a.file, stagedFile, expectedRuntime: a.expectedRuntime, version })
+  fs.mkdirSync(path.dirname(h.helperFile), { recursive: true })
+  fs.mkdirSync(path.dirname(h.statusFile), { recursive: true })
+  fs.rmSync(h.statusFile, { force: true })
+  fs.writeFileSync(stagedFile, a.content)
+  fs.writeFileSync(h.helperFile, h.content)
   try {
-    const out = execSync('ps ax -o command= 2>/dev/null', { encoding: 'utf8', shell: '/bin/bash' })
-    return parseRunningPairVersions(out)
-  } catch { return new Set() }
+    execSync(`launchctl bootstrap gui/$(id -u) ${shq(h.helperFile)}`, { stdio: 'inherit', shell: '/bin/bash' })
+    process.stderr.write(`  ◆ update handoff armed outside the bridge process tree — completion is recorded in ${h.statusFile}.\n`)
+    return true
+  } catch (e) {
+    fs.rmSync(stagedFile, { force: true })
+    fs.rmSync(h.helperFile, { force: true })
+    process.stderr.write(`  ⚠ could not arm the launchd update handoff; existing service left running: ${e.message}\n`)
+    return false
+  }
 }
-const darwinSvcLoaded = (lbl) => { try { execSync(`launchctl print gui/$(id -u)/${lbl}`, { stdio: 'ignore' }); return true } catch { return false } }
-// After the reload, CONFIRM the new pinned version is actually running — the shell
-// post can report "loaded" while an ORPHANED old child bridge (that bootout didn't
-// reap) keeps serving the OLD version, which is the "Restart & update never works"
-// bug (Max 2026-07-02). If the new version isn't up, SIGKILL lingering ROOM child
-// bridges (never the no-arg menu process) + re-bootstrap, then report the truth.
-function verifyDarwinReload(lbl, file, version) {
-  const want = String(version)
-  const up = () => darwinSvcLoaded(lbl) && runningPairVersions().has(want)
-  for (let i = 0; i < 25 && !up(); i++) sleepMs(600)            // fresh (cache-wiped) fetch takes a bit
-  if (up()) { process.stderr.write(`  ◆ verified: bridge is now running v${want}.\n`); return true }
-  process.stderr.write(`  ⚠ v${want} not up yet — clearing stale bridges and re-bootstrapping…\n`)
-  try { execSync(`launchctl bootout gui/$(id -u)/${lbl} 2>/dev/null || true`, { stdio: 'ignore' }) } catch { /* noop */ }
-  // Kill orphaned ROOM child bridges (`bridge.mjs <ROOM>`), which bootout may not have
-  // reaped. The uppercase room-code guard never matches the no-arg / `setup` menu.
-  try { execSync(`pkill -9 -f 'thinkpool-pair/bridge.mjs [A-Z0-9]' 2>/dev/null || true`, { stdio: 'ignore', shell: '/bin/bash' }) } catch { /* noop */ }
-  sleepMs(500)
-  try { execSync(`launchctl enable gui/$(id -u)/${lbl} 2>/dev/null || true`, { stdio: 'ignore' }) } catch { /* noop */ }
-  for (let i = 0; i < 25 && !up(); i++) { try { execSync(`launchctl bootstrap gui/$(id -u) "${file}" 2>/dev/null || true`, { stdio: 'ignore' }) } catch { /* noop */ } sleepMs(600) }
-  if (up()) { process.stderr.write(`  ◆ recovered: bridge is now running v${want}.\n`); return true }
-  process.stderr.write(`  ⚠ could NOT confirm v${want} is running. Recover by hand:\n      launchctl bootout gui/$(id -u)/${lbl} ; pkill -9 -f thinkpool-pair ; launchctl bootstrap gui/$(id -u) "${file}"\n`)
-  return false
+
+function labelFromFile(file) {
+  const match = path.basename(file).match(/^(io\.thinkpool\.pair\.[A-Za-z0-9_.-]+)\.plist$/)
+  if (!match) throw new Error(`cannot derive service label from ${file}`)
+  return match[1]
 }
 
 // F4 — every io.thinkpool.pair.* label currently LOADED in the launchd/systemd domain,
@@ -327,12 +381,8 @@ export function sweepExistingServices(keepLabel, platform = process.platform) {
   }
 }
 
-// staleProof defaults ON for every real install: even a FIRST install can be launched from
-// a stale npx cache (the launcher itself is npx-resolved), so without the cache-wiping
-// wrapper a fresh `install-service` could pin a stale build just like the update path did.
-// Pinning still holds (we pin a fixed version number) — staleProof only guarantees that
-// pinned version is fetched fresh on every (re)start. buildArtifact keeps staleProof=false
-// so its unit tests assert the pure pinned shape.
+// staleProof remains for the legacy npx artifact shape. Pinned services normally bypass
+// npx entirely through the verified immutable runtime provisioned below.
 export function installService(room, cmdArgs = [], { autoUpdate = false, version = VERSION, staleProof = true } = {}) {
   // Pinned services get a stable local runtime. The legacy @latest opt-in keeps its
   // existing npx behavior until it resolves a concrete version through updateService.
@@ -343,20 +393,22 @@ export function installService(room, cmdArgs = [], { autoUpdate = false, version
   }
   const a = buildArtifact(process.platform, { room, cmdArgs, autoUpdate, version, staleProof, runtimeEntry })
   // F4: clear every OTHER pre-existing pair service first, so only the one we install remains
-  // (the "two account services live" storm trigger). Our own label is bootout+bootstrapped
-  // by a.post below, so keep it.
+  // (the "two account services live" storm trigger). Our own label is handled by the
+  // launchd handoff (macOS) or the platform post command, so keep it.
   try { sweepExistingServices(label(room), process.platform) } catch { /* best-effort */ }
   fs.mkdirSync(a.logDir, { recursive: true })
   fs.mkdirSync(path.dirname(a.file), { recursive: true })
-  fs.writeFileSync(a.file, a.content)
-  process.stderr.write(`\n  ◆ wrote ${a.file}\n`)
-  for (const cmd of a.post) {
-    try { execSync(cmd, { stdio: 'inherit' }) } catch (e) { process.stderr.write(`  ⚠ "${cmd}" failed: ${e.message}\n`) }
+  if (process.platform === 'darwin') {
+    process.stderr.write(`\n  ◆ staged replacement for ${a.file}\n`)
+    if (!startDarwinReloadHandoff(a, version)) return false
+  } else {
+    fs.writeFileSync(a.file, a.content)
+    process.stderr.write(`\n  ◆ wrote ${a.file}\n`)
+    for (const cmd of a.post) {
+      try { execSync(cmd, { stdio: 'inherit' }) }
+      catch (e) { process.stderr.write(`  ⚠ "${cmd}" failed; service update NOT confirmed: ${e.message}\n`); return false }
+    }
   }
-  // Darwin: confirm the reload actually put the NEW version live, self-heal if not.
-  // Only for a PINNED (re)install where we know the exact version to look for — an
-  // autoUpdate (@latest) install has no fixed version number to verify against.
-  if (process.platform === 'darwin' && !autoUpdate) verifyDarwinReload(label(room), a.file, version)
   // Be honest about the cadence — it is NOT instant. The supervisor polls npm
   // roughly every 30 min (THINKPOOL_PAIR_UPDATE_INTERVAL) and only restarts once
   // every served session is idle, so a just-published version can take a while.
@@ -368,15 +420,13 @@ export function installService(room, cmdArgs = [], { autoUpdate = false, version
     : `PINNED to ${version} (stable local runtime; restarts do not depend on npx or the network). To update: use "Restart & update the bridge" (or re-run install-service from a newer thinkpool-pair). Pass --auto-update to track @latest instead.`
   const removeArg = room ? ` ${room}` : ''
   const what = room ? `room ${room}` : 'your account (auto-serves every session)'
-  process.stderr.write(`  ◆ ${what}\n  ◆ ${a.note}\n  ◆ ${updateNote}\n  ◆ logs: ${path.join(a.logDir, `${slug(room)}.log`)}\n  ◆ remove with: thinkpool-pair uninstall-service${removeArg}\n\n`)
+  process.stderr.write(`  ◆ ${what}\n  ◆ ${process.platform === 'darwin' ? 'Launchd is completing and verifying the reload independently.' : a.note}\n  ◆ ${updateNote}\n  ◆ logs: ${path.join(a.logDir, `${slug(room)}.log`)}\n  ◆ remove with: thinkpool-pair uninstall-service${removeArg}\n\n`)
   return true
 }
 
 // Restart an already-installed boot-persistent service. launchd/systemd relaunch
-// the supervised `npx …`, so any active session resumes in place (the bridge
-// restores from disk). Use it to recover a wedged bridge, re-read provider.json,
-// or — if the service was installed with --auto-update (@latest) — pull a new
-// publish now. A PINNED service (the default) re-runs its same installed version.
+// the stable runtime (or legacy auto-update npx command), so active sessions resume
+// from disk. Use it to recover a wedged bridge or re-read provider.json.
 // room falsy → the ACCOUNT service. Returns true on success.
 export function restartService(room) {
   const plat = process.platform
@@ -430,7 +480,10 @@ export function serviceActive(room) {
   const plat = process.platform
   const id = label(room)
   try {
-    if (plat === 'darwin') { execSync(`launchctl print gui/$(id -u)/${id}`, { stdio: 'ignore' }); return true }
+    if (plat === 'darwin') {
+      const out = execSync(`launchctl print gui/$(id -u)/${id}`, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      return darwinServiceRunning(out)
+    }
     if (plat === 'linux')  { execSync(`systemctl --user is-active --quiet ${id}.service`); return true }
     // Windows has no managed daemon — the Startup-folder script's presence is the only proxy.
     return fs.existsSync(buildArtifact(plat, { room }).file)