thinkpool-pair 0.7.335 → 0.7.337

package/README.md

@@ -17,6 +17,11 @@ not require an inbound port, tunnel, or public IP.
   - Hermes
 - The provider login or API credentials required by that runtime
 
+**The bridge does not include a coding agent.** Claude Code, Codex, or Hermes
+must already be installed and runnable on the bridge machine. BYOK only supplies
+model-provider credentials to an installed runtime; a provider key does not
+install or replace the agent itself.
+
 ## Start the bridge
 
 Run the launcher from the project directory the agents should use:
@@ -60,6 +65,35 @@ when that trade-off is intentional:
 npx thinkpool-pair@latest install-service --auto-update
 ```
 
+### Optional: keep the bridge computer awake
+
+The launcher’s **Settings → Keep computer awake** option prevents system sleep
+while the bridge is running. The same choice is available from the CLI:
+
+```bash
+# Foreground, for this run only
+npx thinkpool-pair@latest --keep-awake
+
+# Persist the choice and install the background service
+npx thinkpool-pair@latest install-service --keep-awake
+
+# Persistently turn it back off while reinstalling/updating the service
+npx thinkpool-pair@latest install-service --no-keep-awake
+```
+
+**Important:** keep-awake can substantially increase battery use. It prevents
+the computer from sleeping; it does **not** keep the display illuminated.
+Display dimming, screen locking, and display sleep continue normally. Closing a
+laptop lid may still put it to sleep depending on the operating system and its
+power settings. On some Linux systems the sleep inhibitor can also block an
+explicit suspend request while the bridge runs.
+
+The implementation is process-bound and releases automatically when the bridge
+stops: macOS uses `caffeinate -i`, Linux uses `systemd-inhibit --what=sleep`,
+and Windows uses a system-only power request without `ES_DISPLAY_REQUIRED`.
+If the platform helper is unavailable, the bridge warns and continues without
+keep-awake rather than failing startup.
+
 Service implementation by platform:
 
 - macOS: LaunchAgent
@@ -231,9 +265,10 @@ log before reinstalling; repeated installation can hide the original failure.
 
 ### No runtimes are available
 
-Install/sign in to Claude, Codex, or Hermes on the host, then restart the
-launcher. Runtime availability is detected from the host; the web room cannot
-install a missing CLI for you.
+Install and configure Claude Code, Codex, or Hermes on the host, then restart
+the launcher. Runtime availability is detected from the host; the web room
+cannot install a missing CLI. BYOK configures provider credentials only and
+does not replace the local agent runtime.
 
 ### A custom model fails immediately
 

package/account.mjs

@@ -526,6 +526,11 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   // never impersonate a completed restart.
   const BRIDGE_ID = randomUUID()
   let restarting = false   // set by the "restart" broadcast → stop() exits non-zero so a supervisor respawns us
+  // Account-control handlers are registered before the discovery loop is
+  // initialized. Route early requests through a harmless placeholder, then
+  // replace it once `tick` exists; this avoids a temporal-dead-zone crash during
+  // supervisor bootstrap while still letting a live web room request discovery.
+  let requestDiscoveryTick = () => {}
   // Web "attach this session" card → bind an unbound/new room to a local dir (and
   // optionally set it as the account default) so it serves WITHOUT a terminal command.
   // Rides the private, owner-gated control topic; the dir must exist on THIS machine.
@@ -538,7 +543,17 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     bindDir(code, dir)
     if (payload?.setDefault) { saveDefaultDir(dir); process.stderr.write(`\n  ◆ default project dir set → ${dir}\n`) }
     process.stderr.write(`\n  ◆ ${code} bound → ${dir} (from the web). Serving…\n`)
-    try { tick() } catch { /* the periodic tick will serve it next cycle */ }
+    requestDiscoveryTick()
+  })
+  // A newly-created web room already knows its owner and has an authenticated,
+  // owner-private account-control channel. Nudge discovery immediately instead
+  // of waiting for the supervisor's 15-second reconciliation interval. `tick`
+  // still re-queries owner-owned active rooms, so the browser cannot make this
+  // host serve an arbitrary code.
+  acctControl.on('broadcast', { event: 'serve-room' }, ({ payload }) => {
+    const code = String(payload?.code || '').toUpperCase().trim()
+    if (!/^[A-Z0-9]{4,12}$/.test(code)) return
+    requestDiscoveryTick()
   })
   // Dashboard "Disconnect" → broadcast shutdown → clean exit (presence leaves, bar flips live).
   // If we're the auto-restarting background service (launchd KeepAlive / systemd
@@ -906,6 +921,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
     tickingSince = now
     try { await tickBody() } finally { if (tickingSince === now) tickingSince = 0 }
   }
+  requestDiscoveryTick = () => { void tick().catch(() => {}) }
   // Expose for the watchdog to force-unwedge the guard after a reconnect.
   const clearTickGuard = () => { tickingSince = 0 }
   const tickBody = async () => {

package/bridge.mjs

@@ -68,6 +68,7 @@ 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'
+import { explicitKeepAwakeChoice, keepAwakeEnabled, saveKeepAwakePreference, startKeepAwake } from './keep-awake.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'
@@ -130,6 +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 { loadHermesModelCache, saveHermesModelCache } from './hermes-model-cache.mjs'
 import { makeThrottledTrack, recoveryBackoffMs } from './presence.mjs'
 import { MockupDeliveryQueue, completeMockupManifest, isMockupDeliveryBoundary } from './mockup-delivery.mjs'
 import { resolveAnonKey, DEFAULT_SUPABASE_URL } from './supabase-key.mjs'
@@ -140,6 +142,10 @@ import { buildTerminalRolePrompt, HERMES_VISIBLE_WORKER_FALLBACK_RULE, THINKPOOL
 const SUPABASE_URL  = process.env.TP_SUPABASE_URL  || DEFAULT_SUPABASE_URL
 const WEB_BASE      = process.env.TP_WEB_BASE      || 'https://thinkpool.io'
 const IMAGE_QUEUE_CONFIG = imageQueueConfig()
+// Shared by every Hermes lane in this room child and persisted across room
+// children. Without this, each new room must boot ACP (up to 30s) merely to
+// discover the same public model list before its first real turn.
+let hostHermesModels = loadHermesModelCache()
 
 // The anon key is RESOLVED, not baked. It used to be a string literal here, and
 // that literal now sits in 224 published tarballs on 224 users' laptops: disable
@@ -231,6 +237,17 @@ const pickAgent = (installed) => new Promise((resolve) => {
 
 const argv = process.argv.slice(2)
 
+// CLI service flags also set the durable machine preference. Service updates read
+// the same preference, so a later pinned-runtime update cannot silently turn the
+// requested power behavior off. Foreground `--keep-awake` remains a one-run override.
+if (argv[0] === 'install-service' || argv[0] === 'restart-service') {
+  const choice = explicitKeepAwakeChoice(argv)
+  if (choice !== null && !saveKeepAwakePreference(choice)) {
+    process.stderr.write('  ⚠ could not save the keep-awake setting; service left unchanged.\n')
+    process.exit(1)
+  }
+}
+
 if (argv[0] === 'privacy-report') {
   const { runPrivacyReport } = await import('./privacy-report.mjs')
   runPrivacyReport()
@@ -357,7 +374,10 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
       const child = spawn(process.execPath, args, { stdio: 'inherit' })
       child.on('exit', (code) => process.exit(code == null ? 0 : code))
     }),
-    serveAccountForeground: async () => { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) },
+    serveAccountForeground: async () => {
+      startKeepAwake({ enabled: keepAwakeEnabled([]) })
+      const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON)
+    },
     // 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.
@@ -402,6 +422,17 @@ if ((!argv[0] || argv[0] === 'setup') && process.stdin.isTTY) {
         : ['anthropic']
       await runProvider(args)
     },
+    setKeepAwake: async ({ enabled }) => {
+      if (!saveKeepAwakePreference(enabled)) {
+        io.print('\n  ⚠ could not save the keep-awake setting; nothing was changed.')
+        return false
+      }
+      // A managed Unix service must restart to acquire/release its process-bound
+      // inhibitor. Windows' Startup entry has no daemon control; restartService
+      // prints the honest close-and-relaunch instruction instead.
+      if (svc.isServiceInstalled(null)) svc.restartService(null)
+      return true
+    },
     setupHermes: async ({ mode }) => {
       const { setupHermesRuntime } = await import('./hermes-setup.mjs')
       const result = setupHermesRuntime({ mode })
@@ -456,7 +487,10 @@ function checkSdkCompat() {
   }
 }
 
-if (!argv[0] || argv[0].startsWith('-')) { const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON) }
+if (!argv[0] || argv[0].startsWith('-')) {
+  startKeepAwake({ enabled: keepAwakeEnabled(argv) })
+  const { runAccount } = await import('./account.mjs'); await runAccount(SUPABASE_URL, SUPABASE_ANON)
+}
 
 const room = (argv[0] || '').toUpperCase().trim()
 if (!room) { console.error(`usage: ${pairCli('<ROOM>', '[--headless]', '[--continue|--fresh]', '[-- <command…>]')}   |   ${PAIR_CLI}  (account mode)`); process.exit(1) }
@@ -528,6 +562,11 @@ if (_superOwn.includes('--supervise') || _superOwn.includes('--keep-alive')) {
   if (shouldHoldMachineLock(process.env)) process.on('exit', () => { try { releaseMachineLock() } catch { /* noop */ } })
 }
 
+// Direct single-room mode owns one inhibitor in its actual serving process. Account
+// supervisor children deliberately skip this (the account parent already owns it),
+// and the --supervise wrapper above never reaches this line—only its child does.
+startKeepAwake({ enabled: keepAwakeEnabled(argv) })
+
 const headless = argv.includes('--headless')
 // Account-mode children pass --auto=<agent> so a served session opens a live
 // terminal automatically (headless, no TTY/picker) instead of an empty room.
@@ -2139,7 +2178,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     ? spawnDepth
     : (sideParent || (spawnedBy && !String(spawnedBy).startsWith('flow:')) ? 1 : 0)
   const initialHop = Number.isInteger(hop) && hop >= 0 ? hop : structuralDepth
-  const entry = { cmd: runtime, runtime, kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: commandCatalogForRuntime(runtime, commands), mode, effort, models: runtime === 'codex' ? codexModels : runtime === 'hermes' && Array.isArray(models) ? models : undefined,
+  const entry = { cmd: runtime, runtime, kind: 'structured', log: Array.isArray(log) ? log.slice(-STRUCTURED_LOG_MAX) : [], pending: new Map(), session: null, recovered: false, commands: commandCatalogForRuntime(runtime, commands), mode, effort, models: runtime === 'codex' ? codexModels : runtime === 'hermes' ? (Array.isArray(models) && models.length ? models : hostHermesModels) : undefined,
     // model: truthful active-model label — now the SAME `laneModel` the SDK is given, so the
     // chip cannot disagree with the wire. When this lane runs on a custom (non-anthropic)
     // registered provider the SDK id is impersonated (see the onEvent guard below), so
@@ -3311,7 +3350,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
         // A custom Anthropic-compatible endpoint may expose its own catalog through the
         // same SDK method. Never publish that as the ROOM's Claude catalog: its models
         // already render in the provider group and otherwise leak under ANTHROPIC.
-        if (entry.runtime === 'hermes' && evt.kind === 'models' && Array.isArray(evt.models) && evt.models.length) { entry.models = evt.models; announce() }
+        if (entry.runtime === 'hermes' && evt.kind === 'models' && Array.isArray(evt.models) && evt.models.length) { entry.models = saveHermesModelCache(evt.models); hostHermesModels = entry.models; announce() }
         else if (onBuiltin && evt.kind === 'models' && Array.isArray(evt.models) && evt.models.length) { roomModels = evt.models; announce() } }
       // Hermes model changes are asynchronous ACP requests. Keep the previous model
       // authoritative until Hermes acknowledges session/set_model; then settle the

package/hermes-model-cache.mjs

@@ -0,0 +1,54 @@
+// Hermes exposes its model catalog only after `session/new`, which may take up
+// to 30 seconds while the ACP process boots. The catalog is public metadata and
+// identical for every room served by this Hermes profile, so keep the last
+// validated copy at the host level. A live Hermes session always replaces it.
+
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const MAX_MODELS = 1000
+const MAX_BYTES = 512 * 1024
+const MAX_FIELD = 512
+
+const cachePath = () => process.env.TP_HERMES_MODEL_CACHE
+  || path.join(process.env.TP_PAIR_ROOT || path.join(os.homedir(), '.thinkpool-pair'), 'hermes-models.json')
+
+export function normalizeHermesModelCache(models) {
+  if (!Array.isArray(models)) return []
+  const seen = new Set()
+  const normalized = []
+  for (const raw of models.slice(0, MAX_MODELS)) {
+    const value = String(raw?.value || '').trim().slice(0, MAX_FIELD)
+    if (!value || seen.has(value)) continue
+    seen.add(value)
+    normalized.push({
+      value,
+      displayName: String(raw?.displayName || value).trim().slice(0, MAX_FIELD) || value,
+      description: String(raw?.description || '').trim().slice(0, MAX_FIELD),
+    })
+  }
+  return normalized
+}
+
+export function loadHermesModelCache() {
+  try {
+    const file = cachePath()
+    if ((Number(fs.statSync(file).size) || 0) > MAX_BYTES) return []
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+    return normalizeHermesModelCache(parsed?.models)
+  } catch { return [] }
+}
+
+export function saveHermesModelCache(models) {
+  const normalized = normalizeHermesModelCache(models)
+  if (!normalized.length) return []
+  try {
+    const file = cachePath()
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    const temp = `${file}.${process.pid}.${Date.now()}.tmp`
+    fs.writeFileSync(temp, JSON.stringify({ savedAt: Date.now(), models: normalized }), { mode: 0o600 })
+    fs.renameSync(temp, file)
+  } catch { /* cache is opportunistic; live discovery remains the fallback */ }
+  return normalized
+}

package/keep-awake.mjs

@@ -0,0 +1,148 @@
+/* keep-awake.mjs — one explicit, machine-wide bridge preference with a
+   platform-native implementation. The assertion is SYSTEM-only: it never asks
+   any platform to keep the display lit, so normal dimming, display sleep, and
+   screen locking remain available.
+
+   The helper is deliberately tied to the bridge PID. A crash, Ctrl-C, update,
+   or service-manager replacement therefore releases the assertion without a
+   sticky machine-level power-policy change. */
+
+import os from 'node:os'
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const SETTINGS_FILE = 'settings.json'
+
+function settingsPath(home = os.homedir()) {
+  return path.join(home, '.thinkpool-pair', SETTINGS_FILE)
+}
+
+export function loadKeepAwakePreference({ home = os.homedir(), fsImpl = fs } = {}) {
+  try { return JSON.parse(fsImpl.readFileSync(settingsPath(home), 'utf8')).keepAwake === true }
+  catch { return false }
+}
+
+export function saveKeepAwakePreference(enabled, { home = os.homedir(), fsImpl = fs } = {}) {
+  const file = settingsPath(home)
+  const dir = path.dirname(file)
+  let current = {}
+  try { current = JSON.parse(fsImpl.readFileSync(file, 'utf8')) || {} } catch { /* first setting */ }
+  const next = { ...current, keepAwake: enabled === true }
+  const tmp = `${file}.tmp.${process.pid}.${Date.now()}`
+  try {
+    fsImpl.mkdirSync(dir, { recursive: true })
+    fsImpl.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 })
+    fsImpl.renameSync(tmp, file)
+    return true
+  } catch {
+    try { fsImpl.rmSync(tmp, { force: true }) } catch { /* noop */ }
+    return false
+  }
+}
+
+export function explicitKeepAwakeChoice(argv = []) {
+  const dash = argv.indexOf('--')
+  const own = dash >= 0 ? argv.slice(0, dash) : argv
+  if (own.includes('--no-keep-awake')) return false
+  if (own.includes('--keep-awake')) return true
+  return null
+}
+
+export function keepAwakeEnabled(argv = [], { env = process.env, loadPreference = loadKeepAwakePreference } = {}) {
+  const explicit = explicitKeepAwakeChoice(argv)
+  if (explicit !== null) return explicit
+  if (env.THINKPOOL_PAIR_KEEP_AWAKE === '1') return true
+  if (env.THINKPOOL_PAIR_KEEP_AWAKE === '0') return false
+  return loadPreference() === true
+}
+
+const WINDOWS_HELPER = (parentPid) => [
+  '$ErrorActionPreference = "Stop"',
+  'Add-Type -TypeDefinition \'using System; using System.Runtime.InteropServices; public static class ThinkpoolPower { [DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint flags); }\'',
+  // ES_CONTINUOUS | ES_SYSTEM_REQUIRED. ES_DISPLAY_REQUIRED (0x2) is intentionally absent.
+  '[ThinkpoolPower]::SetThreadExecutionState([uint32]0x80000001) | Out-Null',
+  `try { while (Get-Process -Id ${parentPid} -ErrorAction SilentlyContinue) { Start-Sleep -Seconds 5 } }`,
+  'finally { [ThinkpoolPower]::SetThreadExecutionState([uint32]0x80000000) | Out-Null }',
+].join('; ')
+
+// Pure command construction keeps the display-sleep contract testable on any host.
+export function keepAwakeCommand(platform, parentPid, { node = process.execPath, modulePath = fileURLToPath(import.meta.url) } = {}) {
+  if (!Number.isInteger(parentPid) || parentPid <= 0) throw new Error('keep-awake requires a live bridge pid')
+  if (platform === 'darwin') {
+    // -i is the idle SYSTEM-sleep assertion. Do not add -d (display).
+    // -w makes caffeinate release automatically when the bridge PID exits.
+    return { command: '/usr/bin/caffeinate', args: ['-i', '-w', String(parentPid)], adapter: 'caffeinate' }
+  }
+  if (platform === 'linux') {
+    // Inhibit the sleep operation, not desktop "idle" handling: an idle inhibitor
+    // can also suppress screen blanking in some desktop environments. The tiny Node
+    // waiter exits with the parent, releasing systemd-logind's inhibitor lock.
+    return {
+      command: 'systemd-inhibit',
+      args: ['--what=sleep', '--mode=block', '--who=Thinkpool', '--why=Keep the Thinkpool bridge reachable', '--', node, modulePath, '--wait-for', String(parentPid)],
+      adapter: 'systemd-inhibit',
+    }
+  }
+  if (platform === 'win32') {
+    return {
+      command: 'powershell.exe',
+      args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-Command', WINDOWS_HELPER(parentPid)],
+      adapter: 'Windows power request',
+    }
+  }
+  return null
+}
+
+export function startKeepAwake({
+  enabled,
+  platform = process.platform,
+  parentPid = process.pid,
+  spawnImpl = spawn,
+  stderr = process.stderr,
+  accountChild = process.env.THINKPOOL_PAIR_ACCOUNT_CHILD === '1',
+} = {}) {
+  if (!enabled || accountChild) return null
+  let spec
+  try { spec = keepAwakeCommand(platform, parentPid) }
+  catch (error) { stderr.write(`  ⚠ keep-awake unavailable: ${error?.message || error}\n`); return null }
+  if (!spec) {
+    stderr.write(`  ⚠ keep-awake is not supported on ${platform}; bridge startup will continue normally.\n`)
+    return null
+  }
+
+  let child
+  const startedAt = Date.now()
+  try {
+    child = spawnImpl(spec.command, spec.args, { stdio: 'ignore', windowsHide: true })
+    child.once?.('spawn', () => {
+      stderr.write(`  ◆ keep-awake ON via ${spec.adapter}: system sleep is inhibited while this bridge runs.\n    Your screen can still dim, lock, and turn off normally.\n`)
+    })
+    child.once?.('error', (error) => {
+      stderr.write(`  ⚠ keep-awake could not start (${spec.adapter}: ${error?.message || error}); bridge startup will continue normally.\n`)
+    })
+    child.once?.('exit', (code) => {
+      if (code && Date.now() - startedAt < 30_000) stderr.write(`  ⚠ keep-awake helper exited early (${spec.adapter}, code ${code}); the computer may sleep normally.\n`)
+    })
+    child.unref?.()
+    return child
+  } catch (error) {
+    stderr.write(`  ⚠ keep-awake could not start (${spec.adapter}: ${error?.message || error}); bridge startup will continue normally.\n`)
+    return null
+  }
+}
+
+async function waitForProcess(pid) {
+  for (;;) {
+    try { process.kill(pid, 0) } catch { return }
+    await new Promise((resolve) => setTimeout(resolve, 5_000))
+  }
+}
+
+// Linux systemd-inhibit owns this helper as its COMMAND. It holds no power
+// assertion itself; its lifetime simply matches the bridge process.
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === '--wait-for') {
+  const pid = Number(process.argv[3])
+  if (Number.isInteger(pid) && pid > 0) await waitForProcess(pid)
+}

package/launcher.mjs

@@ -17,6 +17,7 @@ import { execSync } from 'node:child_process'
 import { detectProvider, fetchModels, ANTHROPIC_COMPATIBLE, gatewayHint } from './byok-detect.mjs'
 import { probeHermesRuntime } from './hermes-probe.mjs'
 import { darwinServiceRunning, serviceRuntimeVersion } from './service.mjs'
+import { loadKeepAwakePreference } from './keep-awake.mjs'
 
 const HOME = os.homedir()
 const CFG_DIR = path.join(HOME, '.thinkpool-pair')
@@ -86,6 +87,7 @@ export function detectState() {
     hermesInstalled,
     hermesReady,
     accountSvc,
+    keepAwake: loadKeepAwakePreference(),
     serviceVersion: accountSvc ? serviceRuntimeVersion(null) : null,
     platform: process.platform,
     cwd: process.cwd(),
@@ -110,6 +112,7 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
     loggedIn: !!next?.loggedIn,
     reconnectRequired: !!next?.reconnectRequired,
     accountSvc: !!next?.accountSvc,
+    keepAwake: next?.keepAwake === true,
     serviceVersion: typeof next?.serviceVersion === 'string' && next.serviceVersion ? next.serviceVersion : null,
     platform: next?.platform || process.platform,
     provider: next?.provider || 'Anthropic (default)',
@@ -134,7 +137,7 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
     io.print('  ' + C.dim('┌ ') + C.bold('thinkpool-pair') + C.dim(' ' + '─'.repeat(40)))
     io.print(`  ${C.dim('│ launcher ')} ${state.version ? `v${state.version}` : 'version unavailable'}`)
     io.print(`  ${C.dim('│ account  ')} ${state.reconnectRequired ? C.yellow('reconnect required') : state.loggedIn ? C.green((state.email || 'linked') + ' ✓') : C.yellow('not linked')}`)
-    io.print(`  ${C.dim('│ agents   ')} ${state.agents.length ? state.agents.map(a => a.label).join(', ') : C.yellow('none ready')}`)
+    io.print(`  ${C.dim('│ agents   ')} ${state.agents.length ? state.agents.map(a => a.label).join(', ') : C.yellow('none ready: install Claude Code, Codex, or Hermes')}`)
     io.print(`  ${C.dim('│ directory')} ${C.dim(state.cwd)}`)
     const bridgeStatus = !state.accountSvc
       ? 'not installed'
@@ -142,6 +145,7 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
         ? C.green('startup entry installed')
         : C.green(`running${state.serviceVersion ? ` v${state.serviceVersion}` : ' (version unavailable)'}`)
     io.print(`  ${C.dim('│ bridge   ')} ${bridgeStatus}`)
+    io.print(`  ${C.dim('│ keep awake')} ${state.keepAwake ? C.green('on') + C.dim(', display may still dim') : 'off'}`)
     io.print('  ' + C.dim('└' + '─'.repeat(54)) + '\n')
   }
 
@@ -176,8 +180,25 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
     return true
   }
 
+  // A provider key is credentials, not an executable agent. Stop new installs
+  // before they create an apparently healthy but unusable background bridge.
+  const ensureAgentReady = async () => {
+    if (state.agents.length) return true
+    io.print('\n  ' + C.yellow('No coding agent is ready on this computer'))
+    io.print('  Thinkpool connects an agent already installed on this machine. It does not')
+    io.print('  include one. Install and configure at least one of:')
+    io.print(`\n    ${C.cyan('Claude Code')}   command: claude`)
+    io.print(`    ${C.cyan('Codex')}         command: codex`)
+    io.print(`    ${C.cyan('Hermes')}        command: hermes, then set up its Thinkpool profile here`)
+    io.print('\n  ' + C.bold('BYOK does not replace the agent. It only gives an installed agent'))
+    io.print('  credentials for a model provider.')
+    io.print('\n  Install one, then reopen this launcher.')
+    return false
+  }
+
   const providerMenu = async () => {
     const cur = state.provider + (state.providerModel ? `, model ${state.providerModel}` : '')
+    io.print('\n  ' + C.dim('Provider settings supply model credentials. Claude Code, Codex, or Hermes must still be installed locally.'))
     const p = await askChoice('\n  provider', [
       { label: 'Anthropic (default)', hint: 'regular Claude login' },
       { label: 'Paste a key, pick a model', hint: 'auto-detects the provider · OpenRouter = any model' },
@@ -236,6 +257,7 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
       const options = [
         { key: 'provider', label: 'Provider', hint: `current: ${state.provider}` },
         { key: 'account', label: 'Account', hint: state.reconnectRequired ? 'reconnect required' : state.loggedIn ? `linked: ${state.email || 'yes'}` : 'not linked' },
+        { key: 'awake', label: 'Keep computer awake', hint: `${state.keepAwake ? 'ON' : 'off'} · the screen can still dim, lock, and turn off` },
       ]
       if (state.hermesInstalled) options.push({ key: 'hermes', label: state.hermesReady ? 'Hermes profile' : 'Set up Hermes', hint: state.hermesReady ? 'isolated profile ready' : 'set up isolated profile + delegation guard' })
       options.push({ key: 'back', label: 'Back to main menu', hint: '' })
@@ -243,6 +265,30 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
       if (picked.key === 'back') return
       if (picked.key === 'provider') await providerMenu()
       else if (picked.key === 'account') { await actions.login(); resync(); return }
+      else if (picked.key === 'awake') {
+        if (state.keepAwake) {
+          const changed = await actions.setKeepAwake({ enabled: false })
+          if (changed === false) continue
+          state = { ...state, keepAwake: false }
+          resync()
+          io.print('\n  ' + C.green('✓ keep-awake is off. The computer may sleep normally.'))
+        } else {
+          io.print('\n  ' + C.yellow('Important: keep-awake changes this computer’s power behavior'))
+          io.print('  While the bridge runs, Thinkpool will prevent the computer itself from')
+          io.print('  automatically sleeping. This can use substantially more battery and may')
+          io.print('  also block suspend requests on some Linux systems.')
+          io.print('\n  ' + C.green('It does NOT keep the screen on. Display dimming, screen locking, and'))
+          io.print('  display sleep continue to work normally. Closing a laptop lid may still')
+          io.print('  sleep it, depending on the operating system and power settings.')
+          if (await askYesNo('\n  Enable keep-awake while the Thinkpool bridge runs?', false)) {
+            const changed = await actions.setKeepAwake({ enabled: true })
+            if (changed === false) continue
+            state = { ...state, keepAwake: true }
+            resync()
+            io.print('\n  ' + C.green('✓ keep-awake is on. Your screen is still free to dim and turn off.'))
+          } else io.print('\n  ' + C.yellow('unchanged: keep-awake remains off.'))
+        }
+      }
       else if (picked.key === 'hermes') {
         const setup = await askChoice('\n  Hermes profile', [
           { label: 'Clone active profile', hint: 'copies provider/config explicitly; fresh ThinkPool session history' },
@@ -277,13 +323,13 @@ export async function runLauncher({ actions, io, state = detectState(), refresh
           { key: 'serve',   label: 'Serve all my sessions', hint: 'runs here, Ctrl-C stops it' },
           { key: 'service', label: 'Always-on background service', hint: 'recommended — survives reboot, restarts on crash' },
         ]
-    items.push({ key: 'settings', label: 'Settings', hint: `provider · account${state.hermesInstalled ? ' · Hermes profile' : ''}` })
+    items.push({ key: 'settings', label: 'Settings', hint: `provider · account · keep-awake ${state.keepAwake ? 'ON' : 'off'}${state.hermesInstalled ? ' · Hermes profile' : ''}` })
     items.push({ key: 'quit', label: 'Quit', hint: '' })
     const pick = items[await askChoice('choose', items)]
     if (pick.key === 'quit') return
-    if (pick.key === 'serve') { if (await ensureLoggedIn()) await actions.serveAccountForeground() }
+    if (pick.key === 'serve') { if (await ensureAgentReady() && await ensureLoggedIn()) await actions.serveAccountForeground() }
     else if (pick.key === 'service') {
-      if (await ensureLoggedIn()) {
+      if (await ensureAgentReady() && await ensureLoggedIn()) {
         const installed = await actions.installService({ room: null })
         if (installed === true) {
           if (!actions.relaunchLauncher || await actions.relaunchLauncher()) return

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.335",
-  "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
+  "version": "0.7.337",
+  "description": "Connect Claude Code, Codex, or Hermes on your computer to a Thinkpool Code room.",
   "type": "module",
   "bin": {
     "thinkpool-pair": "bridge.mjs"
@@ -12,6 +12,7 @@
     "command-guidance.mjs",
     "abort-turn-barrier.mjs",
     "host-memory.mjs",
+    "keep-awake.mjs",
     "sdk-smoke.mjs",
     "sdk-admission.mjs",
     "sdk-admission.mjs",
@@ -36,6 +37,7 @@
     "codex-commands.mjs",
     "acp-client.mjs",
     "hermes-session.mjs",
+    "hermes-model-cache.mjs",
     "hermes-policy.mjs",
     "hermes-acp-bootstrap.py",
     "hermes-event-mapper.mjs",

package/service.mjs

@@ -25,6 +25,7 @@ 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'
+import { loadKeepAwakePreference } from './keep-awake.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).
@@ -591,7 +592,11 @@ 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 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: ${pairCli('uninstall-service')}${removeArg}\n\n`)
+  const awakeNote = loadKeepAwakePreference()
+    ? '  ◆ Keep-awake on: system sleep is inhibited while the bridge runs (higher battery use); the display may still dim, lock, and turn off.\n'
+    : ''
+  const runtimeNote = '  ◆ Prerequisite: Claude Code, Codex, or Hermes must be installed on this machine. BYOK supplies model credentials; it does not install an agent.\n'
+  process.stderr.write(`  ◆ ${what}\n  ◆ ${process.platform === 'darwin' ? 'Launchd is completing and verifying the reload independently.' : a.note}\n${runtimeNote}${awakeNote}  ◆ ${updateNote}\n  ◆ logs: ${path.join(a.logDir, `${slug(room)}.log`)}\n  ◆ remove with: ${pairCli('uninstall-service')}${removeArg}\n\n`)
   return true
 }