thinkpool-pair 0.7.320 → 0.7.321

package/account.mjs

@@ -15,7 +15,7 @@ import { createClient } from '@supabase/supabase-js'
 import os from 'node:os'
 import { saveAuth, loadAuth, markAuthReconnectRequired, loadDirs, bindDir, loadServed, rememberServed, loadDefaultDir, saveDefaultDir, claudeRecentProjectDir } from './auth-store.mjs'
 import { isSafeToRestart } from './update-gate.mjs'
-import { makeThrottledTrack, presenceRecoveryEligible, presenceSelfEchoObservation, reducePresenceChannelEvidence } from './presence.mjs'
+import { makeThrottledTrack, presenceRecoveryEligible, presenceSelfEchoObservation, recoveryBackoffMs, reducePresenceChannelEvidence, subscribeWithoutStartupDeadlock } from './presence.mjs'
 import { publicKeyB64, announceProviders, listProviders, addProvider, addProviderModel, removeProvider, unseal } from './providers.mjs'
 import { supervisorServes, supervisorRoomsToStop } from './serve-consent.mjs'
 import { resolveServeDir } from './serve-dir.mjs'
@@ -565,27 +565,43 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   // just stops — restart is meaningful for the always-on bridge. Old bridges (pre-0.7.60)
   // don't subscribe to this event, so the dashboard button is a harmless no-op there.
   let restartPreparationRunning = false
-  acct.on('broadcast', { event: 'restart' }, ({ payload } = {}) => {
+  acct.on('broadcast', { event: 'restart' }, async ({ payload } = {}) => {
+    const nonce = payload?.nonce
+    const reply = async (ok, error) => {
+      try { await acct.send({ type: 'broadcast', event: 'restart-status', payload: { nonce, ok, error } }) } catch { /* channel down */ }
+    }
+    if (!(await isOwner(payload?.jwt))) {
+      await reply(false, 'unauthorized')
+      return
+    }
     // A dashboard restart is an EXPLICIT apply request, but it is not permission
     // to interrupt a live turn or a pending human decision. Stage the immutable
     // runtime while work continues; applyIfIdle() owns the only destructive edge.
-    applyRequested = true
-    if (restartPreparationRunning || applyingUpdate) return
+    if (restartPreparationRunning || applyingUpdate) {
+      await reply(false, 'a bridge update is already being prepared')
+      return
+    }
     restartPreparationRunning = true
-    ;(async () => {
-      try {
-        const svc = await import('./service.mjs')
-        const staged = svc.serviceActive(null) ? svc.stageServiceUpdate(null) : null
-        // The dashboard's advertised version is only a fallback marker. The host
-        // independently resolves and verifies npm above before applying a service.
-        pendingUpdate = staged || (typeof payload?.version === 'string' ? payload.version : VERSION) || 'restart'
-      } catch {
-        pendingUpdate = (typeof payload?.version === 'string' ? payload.version : VERSION) || 'restart'
-      } finally {
-        restartPreparationRunning = false
+    try {
+      const svc = await import('./service.mjs')
+      const managed = svc.serviceActive(null)
+      const staged = managed ? svc.stageServiceUpdate(null) : null
+      if (managed && !staged) {
+        await reply(false, 'the published runtime could not be staged; the existing bridge was left running')
+        return
       }
-      void applyIfIdle()
-    })()
+      // The dashboard's advertised version is only a fallback marker for a
+      // foreground supervisor. Managed hosts independently resolve and verify npm.
+      pendingUpdate = staged || (typeof payload?.version === 'string' ? payload.version : VERSION) || 'restart'
+      applyRequested = true
+      await reply(true)
+    } catch (error) {
+      await reply(false, `restart preparation failed: ${error?.message || error}`)
+      return
+    } finally {
+      restartPreparationRunning = false
+    }
+    void applyIfIdle()
   })
   // Throttled so a realtime reconnect storm can't machine-gun track() into the
   // per-client presence rate limit (ClientPresenceRateLimitReached → channel closed
@@ -699,10 +715,10 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   // Re-track on EVERY (re)subscribe, not just the first: a realtime reconnect
   // (network blip, or a token swap mid-flight) rejoins the channel and must
   // re-announce, or the dashboard would read "no bridge" until the next restart.
-  await new Promise((res) => acct.subscribe((st) => {
+  const initialAccountRealtime = await subscribeWithoutStartupDeadlock(acct, (st) => {
     if (st === 'SUBSCRIBED') {
       presenceEvidence = reducePresenceChannelEvidence(presenceEvidence, st)
-      pushPresence(); res()
+      pushPresence()
     }
     else if (st === 'CLOSED' || st === 'CHANNEL_ERROR' || st === 'TIMED_OUT') {
       // Invalidate the old generation before inspecting presenceState again. The
@@ -715,7 +731,10 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
       // The callback stays wired for the channel's life, so later rejoins re-fire it.
       try { sb.realtime?.connect?.() } catch { /* noop */ }
     }
-  }))
+  })
+  if (!initialAccountRealtime.connected) {
+    process.stderr.write(`\n  ◇ account realtime not ready at startup (${initialAccountRealtime.status}) — staying alive and recovering in process.\n`)
+  }
 
   // Keep the account JWT fresh so the presence socket never gets deauthed at
   // expiry (the 2026-06-17 "No bridge connected while sessions run" bug). On each
@@ -1159,13 +1178,26 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   // wedged tick can't starve it: when the claim has been quiet ≥2 ticks it nudges realtime
   // to reconnect, force-clears the re-entrancy guard, and re-issues the heartbeat directly
   // (claim_bridge is a plain HTTP RPC — it recovers even while the socket is still flapping).
+  let claimRecoveryAttempt = 0
+  let claimRecoveryNextAt = 0
+  let claimRecoveryInFlight = false
   const heartbeatWatch = setInterval(async () => {
     if (stopping) return
-    if (!claimLoopWedged({ lastClaimOkAt, now: Date.now() })) return
-    console.log(`claim_watchdog sup=${SUP_ID} quiet_ms=${Date.now() - lastClaimOkAt} — reconnecting realtime + re-claiming`)
+    const now = Date.now()
+    if (!claimLoopWedged({ lastClaimOkAt, now })) {
+      claimRecoveryAttempt = 0; claimRecoveryNextAt = 0
+      return
+    }
+    if (claimRecoveryInFlight || now < claimRecoveryNextAt) return
+    claimRecoveryInFlight = true
+    const waitMs = recoveryBackoffMs(claimRecoveryAttempt)
+    claimRecoveryNextAt = now + waitMs
+    claimRecoveryAttempt += 1
+    console.log(`claim_watchdog sup=${SUP_ID} quiet_ms=${now - lastClaimOkAt} attempt=${claimRecoveryAttempt} next_ms=${waitMs} — reconnecting realtime + re-claiming`)
     try { sb.realtime?.connect?.() } catch { /* noop */ }
     clearTickGuard()   // unwedge the guard so the next scheduled tick can run
-    try { await refreshClaim(); pushPresence() } catch { /* the next tick retries */ }
+    try { await refreshClaim(); pushPresence() } catch { /* the backed-off attempt retries */ }
+    finally { claimRecoveryInFlight = false }
   }, 20_000)
   heartbeatWatch.unref?.()
 

package/bridge.mjs

@@ -122,7 +122,7 @@ import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSP
 import { createStandalonePairResponder, standalonePairIdentity } from './direct-pair-room.mjs'
 import { dispatchPendingRecap, recoverInterruptedTurn, recoverMissingResumeOnce, sendInterruptedContinue, shouldAttemptNativeResume, supersedeInterruptedResume } from './interrupted-resume.mjs'
 import { supersedeDispatchLease } from './dispatch-lease.mjs'
-import { turnInFlight } from './update-gate.mjs'
+import { realtimeRecoveryDecision, turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq, hasDurableArchive, servesHistoryPage } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, ImageEventQueue, imageQueueConfig, uploadCodeImage as uploadCodeImageRequest, usageReportLine, codexUsageReportLine, buildRecapFromLog, RECAP_CAP, trimmedBeforeSeq, firstSeq } from './event-id.mjs'
 import { createLatestReplayPump, requestedReplayIds } from './replay-transport.mjs'
@@ -131,7 +131,7 @@ import { fetchPairControlDeliveryAuthority } from './pair-control-authority.mjs'
 import { SIDE_HANDOFF_PROMPT, SIDE_ROLE_PROMPT, appendSideContext, assistantTextSince, dispatchSideContexts, sideContextBlock, sideSnapshot } from './side-lane.mjs'
 import { planMeterLine } from './plan-meters.mjs'
 import { priceForModel } from './model-prices.mjs'
-import { makeThrottledTrack } from './presence.mjs'
+import { makeThrottledTrack, recoveryBackoffMs } from './presence.mjs'
 import { MockupDeliveryQueue, completeMockupManifest, isMockupDeliveryBoundary } from './mockup-delivery.mjs'
 import { resolveAnonKey, DEFAULT_SUPABASE_URL } from './supabase-key.mjs'
 import { buildTerminalRolePrompt, HERMES_VISIBLE_WORKER_FALLBACK_RULE, THINKPOOL_PROMPT_BUNDLE } from './thinkpool-room-prompt.mjs'
@@ -359,8 +359,9 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
       child.on('exit', (code) => process.exit(code == null ? 0 : code))
     }),
     serveAccountForeground: async () => { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) },
-    // Confirmed installs/updates close the launcher: the service is independently
-    // running and another menu cycle can only race it. Failures return to the menu.
+    // Confirmed installs/updates continue in the exact runtime just proven live. This
+    // keeps the person inside the npx menu without letting the stale installer claim
+    // its in-memory VERSION matches the newly installed managed service.
     installService: ({ room = null, agentCmd } = {}) => svc.installAndConfirmService(room, agentCmd ? [agentCmd] : []),
     uninstallService: ({ room = null } = {}) => { svc.uninstallService(room) },
     restartService: ({ room = null } = {}) => { svc.restartService(room) },
@@ -370,6 +371,27 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
     restartUpdateService: async ({ room = null } = {}) => process.platform === 'win32'
       ? svc.updateService(room)
       : svc.updateAndConfirmService(room),
+    relaunchLauncher: async () => {
+      const installedVersion = svc.serviceRuntimeVersion(null)
+      if (!installedVersion) {
+        io.print('\n  ⚠ the managed runtime was confirmed earlier but could not be resolved for launcher handoff; staying in this launcher.')
+        return false
+      }
+      let entry = ''
+      try { entry = svc.provisionRuntime(installedVersion) }
+      catch (error) {
+        io.print(`\n  ⚠ could not open the verified v${installedVersion} launcher: ${error?.message || error}`)
+        return false
+      }
+      return new Promise((resolve) => {
+        const child = spawn(process.execPath, [entry], { stdio: 'inherit', cwd: process.cwd(), env: process.env })
+        child.once('error', (error) => {
+          io.print(`\n  ⚠ launcher handoff failed: ${error?.message || error}`)
+          resolve(false)
+        })
+        child.once('exit', () => resolve(true))
+      })
+    },
     login: async () => { const { runLogin } = await import('./account.mjs'); await runLogin(SUPABASE_URL, SUPABASE_ANON, WEB_BASE) },
     // Provider config is NOT terminal — it writes provider.json and returns to the
     // menu so you can pick a model, switch back, or do something else. (It used to
@@ -5182,15 +5204,46 @@ designChannel
     if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT' || status === 'CLOSED') process.stderr.write(`\n  ⚠ design realtime ${status} (tpdesign:${room}).\n`)
   })
 
-// Watchdog — if the realtime channel is stuck (never connected, or dropped and
-// not recovered) for >60s, exit non-zero so a supervisor/launchd restarts a
-// clean process. Healthy long-lived connections never trip this (brokenSince=0).
-setInterval(() => {
-  if (!realtimeHealthy && brokenSince && Date.now() - brokenSince > 60000) {
-    process.stderr.write('\n  ⚠ realtime wedged >60s — exiting for a clean restart.\n')
+// Watchdog — restart only for a Realtime-only wedge. A total network/Supabase
+// outage cannot be repaired by killing the room process; doing so destroys local
+// agent runtimes and leaves the supervisor unable to rediscover the room until HTTP
+// returns. Probe the public health endpoint with capped backoff, preserve agents while
+// offline or mid-turn, and cross the destructive edge only when HTTP proves healthy.
+let realtimeRecoveryInFlight = false
+let realtimeRecoveryAttempt = 0
+let realtimeRecoveryNextAt = 0
+const probeSupabaseHttp = async () => {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), 5000)
+  try {
+    const response = await fetch(`${SUPABASE_URL}/auth/v1/health`, { headers: { apikey: SUPABASE_ANON }, signal: controller.signal })
+    return response.ok
+  } catch { return false }
+  finally { clearTimeout(timer) }
+}
+setInterval(async () => {
+  if (realtimeHealthy || !brokenSince) {
+    realtimeRecoveryAttempt = 0; realtimeRecoveryNextAt = 0
+    return
+  }
+  const now = Date.now()
+  if (now - brokenSince < 60_000 || realtimeRecoveryInFlight || now < realtimeRecoveryNextAt) return
+  realtimeRecoveryInFlight = true
+  const httpHealthy = await probeSupabaseHttp()
+  const decision = realtimeRecoveryDecision({ brokenSince, now: Date.now(), httpHealthy, activeTurn: turnInFlight(sessions) })
+  if (decision === 'restart') {
+    process.stderr.write('\n  ⚠ realtime wedged while HTTP is healthy — exiting for a clean restart.\n')
     shutdown(1)   // reap PTYs + attempt presence-leave (was a raw exit → orphaned children)
+    return
   }
-}, 15000).unref()
+  const waitMs = recoveryBackoffMs(realtimeRecoveryAttempt)
+  realtimeRecoveryAttempt += 1
+  realtimeRecoveryNextAt = Date.now() + waitMs
+  process.stderr.write(`\n  ◇ realtime unavailable (${decision}) — preserving local agents; retrying in ${Math.round(waitMs / 1000)}s.\n`)
+  try { supabase.realtime?.disconnect?.() } catch { /* noop */ }
+  try { supabase.realtime?.connect?.() } catch { /* noop */ }
+  realtimeRecoveryInFlight = false
+}, 15_000).unref()
 
 // ── auto-update (OS-service tier only) ─────────────────────────────────
 // launchd (KeepAlive) and systemd (Restart=always) re-run

package/launcher.mjs

@@ -285,18 +285,20 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
     else if (pick.key === 'service') {
       if (await ensureLoggedIn()) {
         const installed = await actions.installService({ room: null })
-        if (installed === true) return
+        if (installed === true) {
+          if (!actions.relaunchLauncher || await actions.relaunchLauncher()) return
+        }
         resync()
       }
     }
     else if (pick.key === 'restart') {
       const updated = await actions.restartUpdateService({ room: null })
-      // The launcher process cannot update its own in-memory VERSION. Returning to
-      // the menu after a successful service update therefore showed the old launcher
-      // version beside the new managed-service version and ended on a misleading
-      // "press Enter" pause. The service is already independently running, so close
-      // this stale installer process once the OS-level update is confirmed.
-      if (updated === true) return
+      // Keep the person inside the launcher. A confirmed service update may have
+      // installed a newer package than this process has in memory, so hand the same
+      // TTY to the exact verified runtime instead of dumping back to the shell.
+      if (updated === true) {
+        if (!actions.relaunchLauncher || await actions.relaunchLauncher()) return
+      }
       resync()
     }
     else if (pick.key === 'uninstall') { await actions.uninstallService({ room: null }); resync() }

package/package.json

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

package/presence.mjs

@@ -57,6 +57,37 @@ export function makeThrottledTrack(channel, { minMs = 5000, onStatus = null } =
   }
 }
 
+// A service process must not wedge its entire startup behind the first Realtime
+// SUBSCRIBED callback. Settle the startup gate on success, a terminal channel state,
+// or a bounded timeout while leaving the callback attached for later auto-rejoins.
+export function subscribeWithoutStartupDeadlock(channel, onStatus, {
+  timeoutMs = 15_000,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout,
+} = {}) {
+  if (!channel?.subscribe || typeof onStatus !== 'function') return Promise.resolve({ connected: false, status: 'unavailable' })
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (connected, status) => {
+      if (settled) return
+      settled = true
+      clearTimer(timer)
+      resolve({ connected, status })
+    }
+    const timer = setTimer(() => finish(false, 'STARTUP_TIMEOUT'), Math.max(1, Number(timeoutMs) || 1))
+    channel.subscribe((status) => {
+      onStatus(status)
+      if (status === 'SUBSCRIBED') finish(true, status)
+      else if (status === 'CLOSED' || status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') finish(false, status)
+    })
+  })
+}
+
+export function recoveryBackoffMs(attempt, { baseMs = 20_000, capMs = 300_000 } = {}) {
+  const n = Math.max(0, Math.floor(Number(attempt) || 0))
+  return Math.min(Math.max(1, Number(capMs) || 1), Math.max(1, Number(baseMs) || 1) * (2 ** Math.min(n, 10)))
+}
+
 // A RealtimeChannel keeps its last presenceState() locally. After CHANNEL_ERROR /
 // CLOSED that cache can still contain our own key even though the server (and every
 // dashboard subscriber) has already removed it. Treat every subscribe/error edge as

package/service.mjs

@@ -295,6 +295,8 @@ export function buildDarwinReloadHandoff({ targetLabel, targetFile, stagedFile,
   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 readyFile = path.join(os.homedir(), '.thinkpool-pair', 'account-ready.json')
+  const requiresReady = targetLabel === label(null)
   const script = [
     'set -u',
     'dom="gui/$(id -u)"',
@@ -305,7 +307,10 @@ export function buildDarwinReloadHandoff({ targetLabel, targetFile, stagedFile,
     `backup_file=${shq(backupFile)}`,
     `helper_file=${shq(helperFile)}`,
     `expected=${shq(expectedRuntime)}`,
+    `version=${shq(version)}`,
     `status=${shq(statusFile)}`,
+    `ready=${shq(readyFile)}`,
+    `requires_ready=${requiresReady ? '1' : '0'}`,
     'tmp="$status.tmp.$$"',
     'ok=0',
     'live_pid=""',
@@ -314,11 +319,12 @@ export function buildDarwinReloadHandoff({ targetLabel, targetFile, stagedFile,
     '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',
+    'if [ "$requires_ready" = 1 ]; then rm -f "$ready"; fi',
     '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 snapshot="$(launchctl print "$dom/$target" 2>/dev/null || true)"; pid="$(printf "%s\\n" "$snapshot" | sed -n "s/^[[:space:]]*pid = \\([0-9][0-9]*\\)[[:space:]]*$/\\1/p" | head -1)"; if [ -n "$pid" ] && printf "%s\\n" "$snapshot" | grep -F -- "$expected" >/dev/null && printf "%s\\n" "$snapshot" | grep -F "state = running" >/dev/null; then if [ "$pid" = "$live_pid" ]; then stable=$((stable+1)); else live_pid="$pid"; stable=1; fi; if [ "$stable" -ge 5 ]; then ok=1; break; fi; else live_pid=""; stable=0; fi; sleep 0.5; done',
-    `if [ "$ok" = 1 ]; then printf '%s\\n' '${JSON.stringify({ ok: true, version: String(version), target: String(targetLabel) })}' > "$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), target: String(targetLabel), error: 'new runtime not confirmed; previous service restored', rolledBack: true })}' > "$tmp"; else printf '%s\\n' '${JSON.stringify({ ok: false, version: String(version), target: String(targetLabel), error: 'new runtime not confirmed and rollback failed', rolledBack: false })}' > "$tmp"; fi; fi`,
+    'for i in $(seq 1 60); do snapshot="$(launchctl print "$dom/$target" 2>/dev/null || true)"; pid="$(printf "%s\\n" "$snapshot" | sed -n "s/^[[:space:]]*pid = \\([0-9][0-9]*\\)[[:space:]]*$/\\1/p" | head -1)"; ready_ok=1; if [ "$requires_ready" = 1 ]; then ready_ok=0; [ -f "$ready" ] && grep -F "\\"pid\\":$pid" "$ready" >/dev/null 2>&1 && grep -F "\\"version\\":\\"$version\\"" "$ready" >/dev/null 2>&1 && ready_ok=1; fi; if [ -n "$pid" ] && [ "$ready_ok" = 1 ] && printf "%s\\n" "$snapshot" | grep -F -- "$expected" >/dev/null && printf "%s\\n" "$snapshot" | grep -F "state = running" >/dev/null; then if [ "$pid" = "$live_pid" ]; then stable=$((stable+1)); else live_pid="$pid"; stable=1; fi; if [ "$stable" -ge 5 ]; then ok=1; break; fi; else live_pid=""; stable=0; fi; sleep 0.5; done',
+    `if [ "$ok" = 1 ]; then printf '%s\\n' '${JSON.stringify({ ok: true, version: String(version), target: String(targetLabel) })}' > "$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; if [ "$requires_ready" = 1 ]; then rm -f "$ready"; fi; cp "$backup_file" "$target_file"; launchctl enable "$dom/$target" 2>/dev/null || true; bootstrapped=0; for i in $(seq 1 30); do if launchctl bootstrap "$dom" "$target_file" 2>/dev/null; then bootstrapped=1; break; fi; sleep 0.3; done; if [ "$bootstrapped" = 1 ]; then rollback_pid=""; rollback_stable=0; for i in $(seq 1 60); do snapshot="$(launchctl print "$dom/$target" 2>/dev/null || true)"; pid="$(printf "%s\\n" "$snapshot" | sed -n "s/^[[:space:]]*pid = \\([0-9][0-9]*\\)[[:space:]]*$/\\1/p" | head -1)"; ready_ok=1; if [ "$requires_ready" = 1 ]; then ready_ok=0; [ -f "$ready" ] && grep -F "\\"pid\\":$pid" "$ready" >/dev/null 2>&1 && ready_ok=1; fi; if [ -n "$pid" ] && [ "$ready_ok" = 1 ] && printf "%s\\n" "$snapshot" | grep -F "state = running" >/dev/null; then if [ "$pid" = "$rollback_pid" ]; then rollback_stable=$((rollback_stable+1)); else rollback_pid="$pid"; rollback_stable=1; fi; if [ "$rollback_stable" -ge 5 ]; then rollback=1; break; fi; else rollback_pid=""; rollback_stable=0; fi; sleep 0.5; done; fi; else launchctl bootout "$dom/$target" 2>/dev/null || true; rm -f "$target_file"; fi; if [ "$rollback" = 1 ]; then printf '%s\\n' '${JSON.stringify({ ok: false, version: String(version), target: String(targetLabel), error: 'new runtime not confirmed; previous service restored and ready', rolledBack: true })}' > "$tmp"; else printf '%s\\n' '${JSON.stringify({ ok: false, version: String(version), target: String(targetLabel), error: 'new runtime not confirmed and ready 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',
@@ -336,6 +342,53 @@ export function buildDarwinReloadHandoff({ targetLabel, targetFile, stagedFile,
   return { helperLabel, helperFile, backupFile, statusFile, logFile, script, content }
 }
 
+// Linux has the same self-replacement hazard as launchd: `systemctl restart` issued
+// from inside the account service can terminate the caller before it observes the new
+// process. Run the destructive transaction in a separate transient user unit, and use
+// the same process-bound account readiness receipt as macOS before committing success.
+export function buildLinuxReloadHandoff({ 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 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 readyFile = path.join(os.homedir(), '.thinkpool-pair', 'account-ready.json')
+  const requiresReady = targetLabel === label(null)
+  const script = [
+    'set -u',
+    `target=${shq(targetLabel)}`,
+    'unit="$target.service"',
+    `target_file=${shq(targetFile)}`,
+    `staged_file=${shq(stagedFile)}`,
+    `backup_file=${shq(backupFile)}`,
+    `expected=${shq(expectedRuntime)}`,
+    `version=${shq(version)}`,
+    `status=${shq(statusFile)}`,
+    `ready=${shq(readyFile)}`,
+    `requires_ready=${requiresReady ? '1' : '0'}`,
+    'tmp="$status.tmp.$$"',
+    'ok=0',
+    'had_previous=0',
+    'if [ -f "$target_file" ]; then cp "$target_file" "$backup_file" && had_previous=1; fi',
+    'systemctl --user stop "$unit" 2>/dev/null || true',
+    'if [ "$requires_ready" = 1 ]; then rm -f "$ready"; fi',
+    'cp "$staged_file" "$target_file"',
+    'systemctl --user daemon-reload',
+    'systemctl --user enable "$unit" >/dev/null 2>&1 || true',
+    'systemctl --user restart "$unit" >/dev/null 2>&1 || true',
+    'live_pid=""',
+    'stable=0',
+    'for i in $(seq 1 60); do snapshot="$(systemctl --user show "$unit" --property=ActiveState --property=MainPID --property=ExecStart 2>/dev/null || true)"; pid="$(printf "%s\\n" "$snapshot" | sed -n "s/^MainPID=\\([1-9][0-9]*\\)$/\\1/p" | head -1)"; ready_ok=1; if [ "$requires_ready" = 1 ]; then ready_ok=0; [ -f "$ready" ] && grep -F "\\"pid\\":$pid" "$ready" >/dev/null 2>&1 && grep -F "\\"version\\":\\"$version\\"" "$ready" >/dev/null 2>&1 && ready_ok=1; fi; if [ -n "$pid" ] && [ "$ready_ok" = 1 ] && printf "%s\\n" "$snapshot" | grep -F "ActiveState=active" >/dev/null && printf "%s\\n" "$snapshot" | grep -F -- "$expected" >/dev/null; then if [ "$pid" = "$live_pid" ]; then stable=$((stable+1)); else live_pid="$pid"; stable=1; fi; if [ "$stable" -ge 5 ]; then ok=1; break; fi; else live_pid=""; stable=0; fi; sleep 0.5; done',
+    `if [ "$ok" = 1 ]; then printf '%s\\n' '${JSON.stringify({ ok: true, version: String(version), target: String(targetLabel) })}' > "$tmp"; else rollback=0; if [ "$had_previous" = 1 ]; then systemctl --user stop "$unit" 2>/dev/null || true; if [ "$requires_ready" = 1 ]; then rm -f "$ready"; fi; cp "$backup_file" "$target_file"; systemctl --user daemon-reload; systemctl --user enable "$unit" >/dev/null 2>&1 || true; systemctl --user restart "$unit" >/dev/null 2>&1 || true; rollback_pid=""; rollback_stable=0; for i in $(seq 1 60); do snapshot="$(systemctl --user show "$unit" --property=ActiveState --property=MainPID 2>/dev/null || true)"; pid="$(printf "%s\\n" "$snapshot" | sed -n "s/^MainPID=\\([1-9][0-9]*\\)$/\\1/p" | head -1)"; ready_ok=1; if [ "$requires_ready" = 1 ]; then ready_ok=0; [ -f "$ready" ] && grep -F "\\"pid\\":$pid" "$ready" >/dev/null 2>&1 && ready_ok=1; fi; if [ -n "$pid" ] && [ "$ready_ok" = 1 ] && printf "%s\\n" "$snapshot" | grep -F "ActiveState=active" >/dev/null; then if [ "$pid" = "$rollback_pid" ]; then rollback_stable=$((rollback_stable+1)); else rollback_pid="$pid"; rollback_stable=1; fi; if [ "$rollback_stable" -ge 5 ]; then rollback=1; break; fi; else rollback_pid=""; rollback_stable=0; fi; sleep 0.5; done; else systemctl --user stop "$unit" 2>/dev/null || true; rm -f "$target_file"; systemctl --user daemon-reload; fi; if [ "$rollback" = 1 ]; then printf '%s\\n' '${JSON.stringify({ ok: false, version: String(version), target: String(targetLabel), error: 'new runtime not confirmed; previous service restored and ready', rolledBack: true })}' > "$tmp"; else printf '%s\\n' '${JSON.stringify({ ok: false, version: String(version), target: String(targetLabel), error: 'new runtime not confirmed and ready rollback failed', rolledBack: false })}' > "$tmp"; fi; fi`,
+    'mv "$tmp" "$status"',
+    'rm -f "$staged_file" "$backup_file"',
+    'exit "$((1-ok))"',
+  ].join('; ')
+  return { helperLabel, backupFile, statusFile, logFile, script }
+}
+
 const accountLockFile = () => path.join(os.homedir(), '.thinkpool-pair', 'account.lock')
 const processAlive = (pid) => {
   try { process.kill(pid, 0); return true } catch (error) { return error?.code === 'EPERM' }
@@ -403,8 +456,25 @@ function startDarwinReloadHandoff(a, version) {
   }
 }
 
+function startLinuxReloadHandoff(a, version) {
+  const stagedFile = path.join(a.logDir, `service-update-${process.pid}-${Date.now()}.service`)
+  const h = buildLinuxReloadHandoff({ targetLabel: labelFromFile(a.file), targetFile: a.file, stagedFile, expectedRuntime: a.expectedRuntime, version })
+  fs.mkdirSync(path.dirname(h.statusFile), { recursive: true })
+  fs.rmSync(h.statusFile, { force: true })
+  fs.writeFileSync(stagedFile, a.content)
+  try {
+    execSync(`systemd-run --user --unit=${shq(h.helperLabel)} --collect --property=StandardOutput=append:${shq(h.logFile)} --property=StandardError=append:${shq(h.logFile)} /bin/bash -lc ${shq(h.script)}`, { stdio: 'inherit', shell: '/bin/bash' })
+    process.stderr.write(`  ◆ update handoff armed outside the bridge service cgroup — completion is recorded in ${h.statusFile}.\n`)
+    return true
+  } catch (e) {
+    fs.rmSync(stagedFile, { force: true })
+    process.stderr.write(`  ⚠ could not arm the systemd update handoff; existing service left running: ${e.message}\n`)
+    return false
+  }
+}
+
 function labelFromFile(file) {
-  const match = path.basename(file).match(/^(io\.thinkpool\.pair\.[A-Za-z0-9_.-]+)\.plist$/)
+  const match = path.basename(file).match(/^(io\.thinkpool\.pair\.[A-Za-z0-9_.-]+)\.(?:plist|service)$/)
   if (!match) throw new Error(`cannot derive service label from ${file}`)
   return match[1]
 }
@@ -484,6 +554,9 @@ export function installService(room, cmdArgs = [], { autoUpdate = false, version
   if (process.platform === 'darwin') {
     process.stderr.write(`\n  ◆ staged replacement for ${a.file}\n`)
     if (!startDarwinReloadHandoff(a, version)) return false
+  } else if (process.platform === 'linux') {
+    process.stderr.write(`\n  ◆ staged replacement for ${a.file}\n`)
+    if (!startLinuxReloadHandoff(a, version)) return false
   } else {
     fs.writeFileSync(a.file, a.content)
     process.stderr.write(`\n  ◆ wrote ${a.file}\n`)
@@ -525,7 +598,7 @@ export async function installAndConfirmService(room, cmdArgs = [], {
   },
   now = Date.now,
   sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-  timeoutMs = 55000,
+  timeoutMs = 85000,
   pollMs = 250,
   stderr = process.stderr,
 } = {}) {
@@ -541,7 +614,7 @@ export async function installAndConfirmService(room, cmdArgs = [], {
 
   const confirmation = () => {
     const live = snapshot(room, { platform, exec })
-    const ready = !!room || platform !== 'darwin' || supervisorReadyMatches(readReady(), live, version, { notBefore: confirmationStartedAt })
+    const ready = !!room || platform === 'win32' || supervisorReadyMatches(readReady(), live, version, { notBefore: confirmationStartedAt })
     if (live?.version === version && ready) {
       stderr.write(`  ✓ bridge install confirmed — running v${version}.\n`)
       return true
@@ -549,14 +622,10 @@ export async function installAndConfirmService(room, cmdArgs = [], {
     return false
   }
 
-  // systemd's restart is synchronous. Windows cannot prove a live Startup process,
-  // so this exact-runtime confirmation is used only where a service manager exists.
-  if (platform !== 'darwin') {
-    if (platform === 'win32') return true
-    const confirmed = confirmation()
-    if (!confirmed) stderr.write(`  ⚠ install v${version} was not confirmed: the service manager cannot prove that runtime is running.\n`)
-    return confirmed
-  }
+  // Windows has no service-manager process identity. macOS and Linux both cross an
+  // asynchronous external-helper boundary and must wait for its receipt plus account
+  // readiness; a live PID alone is not a connected bridge.
+  if (platform === 'win32') return true
 
   const deadline = now() + Math.max(0, Number(timeoutMs) || 0)
   const expectedTarget = label(room)
@@ -677,7 +746,7 @@ export async function updateAndConfirmService(room, {
   },
   now = Date.now,
   sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-  timeoutMs = 55000,
+  timeoutMs = 85000,
   pollMs = 250,
   stderr = process.stderr,
 } = {}) {
@@ -700,7 +769,7 @@ export async function updateAndConfirmService(room, {
     const live = snapshot(room, { platform, exec })
     const versionChanged = !!before && before.version !== target
     const processChanged = !!before?.pid && !!live?.pid && before.pid !== live.pid
-    const ready = !!room || platform !== 'darwin' || supervisorReadyMatches(readReady(), live, target, { notBefore: confirmationStartedAt })
+    const ready = !!room || platform === 'win32' || supervisorReadyMatches(readReady(), live, target, { notBefore: confirmationStartedAt })
     if (live?.version === target && (versionChanged || processChanged) && ready) {
       stderr.write(`  ✓ bridge restart confirmed — running v${target}.\n`)
       return { ok: true, live }
@@ -713,14 +782,10 @@ export async function updateAndConfirmService(room, {
     else stderr.write(`  ⚠ update v${target} was not confirmed: the service manager cannot prove the new runtime is running.\n`)
   }
 
-  // systemd's restart is synchronous. The Windows Startup-folder tier has no
-  // authoritative live-service identity, so callers use updateService directly
-  // and label it as a next-launch update rather than a completed restart.
-  if (platform !== 'darwin') {
-    const proof = confirmation()
-    if (!proof.ok) printUnconfirmed(proof)
-    return proof.ok
-  }
+  // The Windows Startup-folder tier has no authoritative live-service identity, so
+  // callers use updateService directly and label it as a next-launch update. Both
+  // managed Unix tiers are asynchronous external handoffs and share the receipt loop.
+  if (platform === 'win32') return true
 
   const deadline = now() + Math.max(0, Number(timeoutMs) || 0)
   const expectedTarget = label(room)

package/update-gate.mjs

@@ -40,3 +40,14 @@ export function turnInFlight(sessions) {
   }
   return false
 }
+
+// Restarting a room process helps only when the HTTP control plane is reachable and
+// Realtime alone is wedged. During a total network outage it destroys healthy local
+// agent processes and cannot improve connectivity; a live turn or permission decision
+// is likewise a hard hold even when HTTP is healthy.
+export function realtimeRecoveryDecision({ brokenSince, now, httpHealthy, activeTurn, graceMs = 60_000 }) {
+  if (!brokenSince || now - brokenSince < graceMs) return 'wait'
+  if (!httpHealthy) return 'hold-offline'
+  if (activeTurn) return 'hold-active'
+  return 'restart'
+}