thinkpool-pair 0.7.319 → 0.7.321

package/README.md

@@ -31,14 +31,14 @@ The bridge self-heals at three levels — all cross-platform (macOS / Linux / Wi
   backoff). Zero-dependency. Combined with session restore (below), a crash is
   invisible — the room reconnects and the Claude session resumes where it left off.
   ```bash
-  npx thinkpool-pair <ROOM> --supervise -- claude
+  npx thinkpool-pair@latest <ROOM> --supervise -- claude
   ```
 - **Boot-persistent service** — survive reboot/logout too. Installs the right
   native service for your OS (launchd on macOS, systemd `--user` on Linux, a
   Startup-folder script on Windows):
   ```bash
-  npx thinkpool-pair install-service <ROOM> -- claude   # set and forget
-  npx thinkpool-pair uninstall-service <ROOM>           # remove it
+  npx thinkpool-pair@latest install-service <ROOM> -- claude   # set and forget
+  npx thinkpool-pair@latest uninstall-service <ROOM>           # remove it
   ```
   The service runs `npx thinkpool-pair@latest`, so it **auto-updates** — new
   versions apply on the next restart, no re-install. (Linux: run
@@ -186,7 +186,7 @@ that format:
 > not OpenRouter's Anthropic endpoint.
 
 ```bash
-npx thinkpool-pair provider custom --base <url> --token <key> [--model <name>]
+npx thinkpool-pair@latest provider custom --base <url> --token <key> [--model <name>]
 ```
 
 Common base urls (the agent appends `/v1/messages`):
@@ -203,11 +203,11 @@ Common base urls (the agent appends `/v1/messages`):
 > gateway is for. Avoid LiteLLM 1.82.7 / 1.82.8 (compromised releases); use a
 > current version.
 
-Show the current provider (`npx thinkpool-pair provider`), or reset back to your
+Show the current provider (`npx thinkpool-pair@latest provider`), or reset back to your
 regular Claude login:
 
 ```bash
-npx thinkpool-pair provider anthropic
+npx thinkpool-pair@latest provider anthropic
 ```
 
 Provider config is stored in `~/.thinkpool-pair/provider.json` (mode 0600) and

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'
@@ -24,6 +24,7 @@ import { installedAgentCommands } from './agent-detect.mjs'
 import { hostMemoryAdmission } from './host-memory.mjs'
 import { createPairBusBroker, mergePairRoomRoster, pairBusStatusFromRealtime, PAIR_BUS_STATUS } from './pair-bus.mjs'
 import { clearSupervisorReady, supervisorPresenceEchoed, writeSupervisorReady } from './supervisor-ready.mjs'
+import { PAIR_CLI, pairCli } from './command-guidance.mjs'
 
 const VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version } catch { return null } })()
 
@@ -121,7 +122,7 @@ export async function runLogin(SUPABASE_URL, SUPABASE_ANON, WEB_BASE) {
   process.stderr.write(`\n  ◆ Link this device to your ThinkPool account.\n    Open (signed in) and approve:\n\n    ${url}\n\n    code:  ${user_code}\n\n  Waiting…\n`)
   const started = Date.now()
   const poll = async () => {
-    if (Date.now() - started > 5 * 60 * 1000) { process.stderr.write('\n  ◇ link timed out — run `npx thinkpool-pair login` again.\n'); process.exit(1) }
+    if (Date.now() - started > 5 * 60 * 1000) { process.stderr.write(`\n  ◇ link timed out — run \`${pairCli('login')}\` again.\n`); process.exit(1) }
     try {
       // A discarded `error` costs one tick — the loop retries in a second, and a
       // permanent failure still lands on the "link timed out" branch above rather than
@@ -130,10 +131,10 @@ export async function runLogin(SUPABASE_URL, SUPABASE_ANON, WEB_BASE) {
       const { data: r } = await sb.rpc('claim_device_code', { p_device_code: device_code })
       if (r?.status === 'approved' && r.session?.refresh_token) {
         saveAuth(r.session)
-        process.stderr.write(`\n  ◆ linked as ${r.session.email || 'your account'}. You can close the browser tab.\n    Now run:  npx thinkpool-pair\n`)
+        process.stderr.write(`\n  ◆ linked as ${r.session.email || 'your account'}. You can close the browser tab.\n    Now run:  ${PAIR_CLI}\n`)
         process.exit(0)
       }
-      if (r?.status === 'expired' || r?.status === 'not_found') { process.stderr.write('\n  ◇ link expired — run `npx thinkpool-pair login` again.\n'); process.exit(1) }
+      if (r?.status === 'expired' || r?.status === 'not_found') { process.stderr.write(`\n  ◇ link expired — run \`${pairCli('login')}\` again.\n`); process.exit(1) }
     } catch { /* transient — keep polling */ }
     setTimeout(poll, 3000)
   }
@@ -397,18 +398,18 @@ export function scheduleTokenRefresh({ sb, session, onRefreshed, onReconnectRequ
 
 export function runBind(room, dir) {
   const r = (room || '').toUpperCase().trim()
-  if (!r) { console.error('usage: npx thinkpool-pair bind <ROOM> <directory>'); process.exit(1) }
+  if (!r) { console.error(`usage: ${pairCli('bind', '<ROOM>', '<directory>')}`); process.exit(1) }
   const abs = path.resolve(dir || '.')
   if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) { console.error(`✗ not a directory: ${abs}`); process.exit(1) }
   bindDir(r, abs)
-  console.error(`✓ bound ${r} → ${abs}\n  Run \`npx thinkpool-pair\` (or restart it) to serve this session.`)
+  console.error(`✓ bound ${r} → ${abs}\n  Run \`${PAIR_CLI}\` (or restart it) to serve this session.`)
   process.exit(0)
 }
 
 // ── account supervisor: a headless child bridge per bound room, in its dir ──
 export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   if (!acquireSingleton()) {
-    console.error('\n  ◇ An account bridge is already running on this machine\n    (~/.thinkpool-pair/account.lock). Not starting a second — two would race\n    your saved login. Stop the other one first, or share a single room with\n    `npx thinkpool-pair <ROOM>`.\n')
+    console.error(`\n  ◇ An account bridge is already running on this machine\n    (~/.thinkpool-pair/account.lock). Not starting a second — two would race\n    your saved login. Stop the other one first, or share a single room with\n    \`${pairCli('<ROOM>')}\`.\n`)
     process.exit(0)
   }
   // We own account.lock now, so any previous readiness receipt is stale. A fresh
@@ -430,7 +431,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     // Reached ONLY when there is no saved login at all (not linked). Stand down CLEANLY
     // with exit 0: launchd KeepAlive has SuccessfulExit=false, so exit 0 is NOT respawned
     // — no crash storm for the "never logged in" case. The user links with `login`.
-    console.error('\n  ◇ Not linked to a ThinkPool account on this machine.\n    Link it:  npx thinkpool-pair login\n')
+    console.error(`\n  ◇ Not linked to a ThinkPool account on this machine.\n    Link it:  ${pairCli('login')}\n`)
     process.exit(0)
   }
   if (auth.reconnectRequired) {
@@ -470,9 +471,9 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     ? '    (auto-updating background service — survives reboot, tracks @latest)\n'
     : isManagedService
       ? '    (background service — survives reboot, restarts on crash, pinned to this version)\n'
-      : '    (run hands-off + auto-updating: npx thinkpool-pair install-service)\n'
+      : `    (run hands-off + auto-updating: ${pairCli('install-service')})\n`
   const _effDefault = loadDefaultDir() || claudeRecentProjectDir() || DEFAULT_DIR
-  process.stderr.write(`\n  ◆ thinkpool-pair — account mode · ${email}\n    New sessions auto-serve from ${_effDefault}${loadDefaultDir() ? ' (your default)' : (claudeRecentProjectDir() ? ' (your most-recent Claude Code project)' : '')}\n    (change it: npx thinkpool-pair set-default-dir <dir>  ·  one room: npx thinkpool-pair bind <code> <dir>)\n${svcHint}`)
+  process.stderr.write(`\n  ◆ thinkpool-pair — account mode · ${email}\n    New sessions auto-serve from ${_effDefault}${loadDefaultDir() ? ' (your default)' : (claudeRecentProjectDir() ? ' (your most-recent Claude Code project)' : '')}\n    (change it: ${pairCli('set-default-dir', '<dir>')}  ·  one room: ${pairCli('bind', '<code>', '<dir>')})\n${svcHint}`)
 
   const children = new Map()   // room -> child process
   const childIdle = new Map()    // room -> bool (last idle report: in the quiet window)
@@ -564,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
@@ -698,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
@@ -714,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
@@ -955,7 +975,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
           const why = choice.reason === 'home'
             ? `no project directory set — refusing to serve it from your home folder (${choice.dir}); the agent would lose its session context and the room would show "${path.basename(choice.dir)}" as the repo.`
             : 'no directory to serve it from.'
-          process.stderr.write(`\n  ◇ ${room}: ${why}\n    Bind it to its repo:  npx thinkpool-pair bind ${room} <repo-dir>\n`)
+          process.stderr.write(`\n  ◇ ${room}: ${why}\n    Bind it to its repo:  ${pairCli('bind', room, '<repo-dir>')}\n`)
         }
         continue
       }
@@ -1158,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

@@ -68,6 +68,7 @@ import { requiresSdkAdmission, sdkSmokePassed } from './sdk-admission.mjs'
 import { hermesUserInputResponse } from './question-response.mjs'
 import { hostMemoryAdmission } from './host-memory.mjs'
 import { queueAbortBarrier, waitForAbortBarrier } from './abort-turn-barrier.mjs'
+import { PAIR_CLI, pairCli } from './command-guidance.mjs'
 
 const STRUCTURED_MODES = new Set(['default', 'acceptEdits', 'plan', 'review', 'bypassPermissions'])
 import { FLOW_CONDUCTOR_PROMPT, FLOW_LANE_PROMPT, FLOW_CODEX_CONDUCTOR_PROMPT, FLOW_CODEX_LANE_PROMPT, buildConductorEnv, assembleCrossWaveContext, buildLanePrompt } from './flow-conductor.mjs'
@@ -121,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'
@@ -130,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'
@@ -292,7 +293,7 @@ if (argv[0] === 'bind')  { const { runBind }  = await import('./account.mjs'); r
 if (argv[0] === 'set-default-dir') {
   const { saveDefaultDir } = await import('./auth-store.mjs')
   let d = (argv[1] || '').trim(); if (d.startsWith('~')) d = d.replace(/^~/, os.homedir())
-  if (!d) { console.error('  usage: npx thinkpool-pair set-default-dir <dir>'); process.exit(1) }
+  if (!d) { console.error(`  usage: ${pairCli('set-default-dir', '<dir>')}`); process.exit(1) }
   saveDefaultDir(d)
   console.log(`  ◆ default project dir set → ${d}\n    New/unbound sessions auto-serve from here — no per-session bind. Takes effect next serve tick.`)
   process.exit(0)
@@ -358,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) },
@@ -369,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
@@ -437,7 +460,7 @@ function checkSdkCompat() {
 if (!argv[0] || argv[0].startsWith('-')) { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) }
 
 const room = (argv[0] || '').toUpperCase().trim()
-if (!room) { console.error('usage: npx thinkpool-pair <ROOM> [--headless] [--continue|--fresh] [-- <command…>]   |   npx thinkpool-pair  (account mode)'); process.exit(1) }
+if (!room) { console.error(`usage: ${pairCli('<ROOM>', '[--headless]', '[--continue|--fresh]', '[-- <command…>]')}   |   ${PAIR_CLI}  (account mode)`); process.exit(1) }
 // Security (audit 2026-07-02): `room` becomes a filesystem path segment under
 // ~/.thinkpool-pair (session-store) AND is interpolated into launchctl/systemd
 // service labels. sessions.id is unconstrained TEXT, so refuse path-unsafe / shell-
@@ -549,7 +572,7 @@ if (dashIdx >= 0) {
   }
 } else if (!headless) {
   if (installedAgents.length === 0) {
-    console.error(`\n  No known coding-agent CLI found on your PATH.\n  Install one (claude / codex / gemini / aider / cursor-agent / opencode …)\n  or share a specific command:  npx thinkpool-pair ${room} -- <your-command>\n`)
+    console.error(`\n  No known coding-agent CLI found on your PATH.\n  Install one (claude / codex / gemini / aider / cursor-agent / opencode …)\n  or share a specific command:  ${pairCli(room, '--', '<your-command>')}\n`)
     process.exit(1)
   }
   attachedCmd = await pickAgent(installedAgents)
@@ -831,7 +854,7 @@ let myServeUid = null        // this bridge's authed uid (null = anon)
     // 401 must NEVER serve, or the gate is bypassed (DEFECT 1). gateFailAction classifies.
     if (gateFailAction(e) === 'refuse') {
       process.stderr.write(refusalMessage({ room, name: null, reason: 'no-identity' }))
-      process.stderr.write(`\n  ◇ (serve-consent: auth rejected at the gate — ${e.message}; the stored login is expired or revoked. Re-run: npx thinkpool-pair login)\n`)
+      process.stderr.write(`\n  ◇ (serve-consent: auth rejected at the gate — ${e.message}; the stored login is expired or revoked. Re-run: ${pairCli('login')})\n`)
       process.exit(0)
     }
     // Availability failure → fail OPEN (spec: never strand a user on a flaky fetch).
@@ -1402,7 +1425,7 @@ let standalonePairChannel = null // standalone owner bridge's direct paired-sess
 // standalone bridge (no supervisor) or a disabled/timed-out request returns { error }.
 function pairRequest(type, payload = {}, timeoutMs = 4000) {
   if (process.env.TP_CROSSROOM_OFF === '1') return Promise.resolve({ error: 'Cross-session reach is turned off in this room.' })
-  if (!IS_ACCOUNT_CHILD) return Promise.resolve({ error: 'Cross-session reach needs the ThinkPool account bridge running your sessions (npx thinkpool-pair). This room is running standalone, so it can only see its own terminals — use read_terminal.' })
+  if (!IS_ACCOUNT_CHILD) return Promise.resolve({ error: `Cross-session reach needs the ThinkPool account bridge running your sessions (${PAIR_CLI}). This room is running standalone, so it can only see its own terminals — use read_terminal.` })
   const reqId = randomUUID()
   return new Promise((resolve) => {
     const timer = setTimeout(() => { pairWaiters.delete(reqId); resolve({ error: 'The other session did not respond in time.' }) }, timeoutMs)
@@ -5181,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/command-guidance.mjs

@@ -0,0 +1,8 @@
+// Canonical, cache-busting invocation for every command printed to people.
+export const PAIR_CLI = 'npx thinkpool-pair@latest'
+
+export function pairCli(...args) {
+  return [PAIR_CLI, ...args.filter((arg) => arg !== undefined && arg !== null && String(arg).length > 0)]
+    .map(String)
+    .join(' ')
+}

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.319",
+  "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": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bridge.mjs",
+    "command-guidance.mjs",
     "abort-turn-barrier.mjs",
     "host-memory.mjs",
     "sdk-smoke.mjs",

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/provider.mjs

@@ -31,6 +31,7 @@
 import os from 'node:os'
 import fs from 'node:fs'
 import path from 'node:path'
+import { pairCli } from './command-guidance.mjs'
 
 const DIR = path.join(os.homedir(), '.thinkpool-pair')
 const FILE = path.join(DIR, 'provider.json')
@@ -68,7 +69,7 @@ export function applyProviderEnv() {
   const authToken = process.env.TP_ANTHROPIC_AUTH_TOKEN || cfg.authToken
   const model     = process.env.TP_ANTHROPIC_MODEL      || cfg.model
   if (!baseUrl || !authToken) {
-    process.stderr.write(`\n  ◇ provider "${provider}" is set but is missing baseUrl/authToken.\n    Finish setup:  npx thinkpool-pair provider custom --base <url> --token <key>\n    Falling back to regular Claude for now.\n`)
+    process.stderr.write(`\n  ◇ provider "${provider}" is set but is missing baseUrl/authToken.\n    Finish setup:  ${pairCli('provider', 'custom', '--base', '<url>', '--token', '<key>')}\n    Falling back to regular Claude for now.\n`)
     return { provider: 'anthropic', source: 'incomplete' }
   }
   process.env.ANTHROPIC_BASE_URL = baseUrl
@@ -121,9 +122,9 @@ export async function runProvider(args) {
 
   console.error(
     '\n  usage:\n' +
-    '    npx thinkpool-pair provider                                            # show current\n' +
-    '    npx thinkpool-pair provider custom --base <url> --token <key> [--model <m>]   # any Anthropic-compatible endpoint\n' +
-    '    npx thinkpool-pair provider anthropic                                  # reset to Claude\n\n' +
+    `    ${pairCli('provider')}                                            # show current\n` +
+    `    ${pairCli('provider', 'custom', '--base', '<url>', '--token', '<key>', '[--model <m>]')}   # any Anthropic-compatible endpoint\n` +
+    `    ${pairCli('provider', 'anthropic')}                                  # reset to Claude\n\n` +
     '  common base urls (SDK appends /v1/messages):\n' +
     '    Z.ai GLM    → https://api.z.ai/api/anthropic\n' +
     '    OpenRouter  → https://openrouter.ai/api\n'

package/serve-consent.mjs

@@ -18,6 +18,8 @@
 // so even an old bridge can no longer READ a grant (the column is gone) and will refuse
 // as a non-owner. That closes the bypass.
 
+import { pairCli } from './command-guidance.mjs'
+
 // serveDecision — may THIS bridge serve THIS room?
 //   ownerId : code_sessions.owner_id (uuid | null)
 //   myUid    : this bridge's authed user id (uuid | null)   — null when the bridge is anon
@@ -109,7 +111,7 @@ export function refusalMessage ({ room, name, reason }) {
   const label = name ? `"${name}"` : '(unnamed)'
   if (reason === 'no-identity') {
     return `\n  ◇ Refusing to serve room ${room} — this bridge is not signed in.\n` +
-      `    A room is served only by its owner's bridge. Sign in first:  npx thinkpool-pair login\n`
+      `    A room is served only by its owner's bridge. Sign in first:  ${pairCli('login')}\n`
   }
   return `\n  ◇ Refusing to serve room ${room} ${label} — it is owned by another person; only their bridge serves it.\n` +
     `    Pairing gives you a read-only view across the pair, not hosting rights. There is no override.\n`

package/service.mjs

@@ -24,6 +24,7 @@ import path from 'node:path'
 import { execSync } from 'node:child_process'
 import { hostMemoryAdmission } from './host-memory.mjs'
 import { readSupervisorReady, supervisorReadyMatches } from './supervisor-ready.mjs'
+import { pairCli } from './command-guidance.mjs'
 
 // Service identity. Account mode has no room → a single stable id so there's
 // exactly one account service per machine (a second install replaces it).
@@ -294,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)"',
@@ -304,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=""',
@@ -313,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',
@@ -335,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' }
@@ -402,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]
 }
@@ -483,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`)
@@ -499,10 +573,10 @@ export function installService(room, cmdArgs = [], { autoUpdate = false, version
     ? (process.platform === 'win32'
         ? 'auto-update ON: a new thinkpool-pair@latest applies on the next login/restart (Windows has no in-process self-update).'
         : `auto-update ON: checks npm ~every 30 min and restarts to apply a new @latest once sessions are idle (≥${idleSecs}s quiet; they resume in place).`)
-    : `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.`
+    : `PINNED to ${version} (stable local runtime; restarts do not depend on npx or the network). To update: use "Restart & update the bridge" (or run ${pairCli('install-service', room || undefined)}). 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  ◆ ${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`)
+  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: ${pairCli('uninstall-service')}${removeArg}\n\n`)
   return true
 }
 
@@ -524,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,
 } = {}) {
@@ -540,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
@@ -548,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)
@@ -676,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,
 } = {}) {
@@ -699,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 }
@@ -712,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'
+}