thinkpool-pair 0.7.275 → 0.7.276

package/account.mjs

@@ -21,6 +21,7 @@ import { supervisorServes } from './serve-consent.mjs'
 import { resolveServeDir } from './serve-dir.mjs'
 import { pairKeyFor, pairTopic, CROSSROOM_BUS } from './cross-terminal.mjs'
 import { installedAgentCommands } from './agent-detect.mjs'
+import { hostMemoryAdmission } from './host-memory.mjs'
 
 const VERSION = (() => { try { return JSON.parse(fs.readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version } catch { return null } })()
 
@@ -892,6 +893,16 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
 
       // ── supervisor child_spawn logging (cascade brg-instrument) ─────────────────
       const alreadyHad = children.has(room)
+      const memory = hostMemoryAdmission(`spawn the room bridge for ${room}`)
+      if (!memory.ok) {
+        if (!warned.has(`memory:${room}`)) {
+          warned.add(`memory:${room}`)
+          process.stderr.write(`\n  ◇ ${room}: ${memory.reason}\n`)
+        }
+        refused.set(room, 'host-memory')
+        continue
+      }
+      warned.delete(`memory:${room}`)
       const child = spawn(process.execPath, [BRIDGE, room, '--headless', '--auto=claude'], { cwd: dir, stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })
       console.log(`child_spawn sup=${SUP_ID} room=${room} pid=${child.pid} dir=${dir} had_prior=${alreadyHad}`)
 

package/bridge.mjs

@@ -63,6 +63,7 @@ import { createManagedLaneWorktree, removeManagedLaneWorktree } from './lane-wor
 import { commandOnPath } from './agent-detect.mjs'
 import { requiresSdkAdmission, sdkSmokePassed } from './sdk-admission.mjs'
 import { hermesUserInputResponse } from './question-response.mjs'
+import { hostMemoryAdmission } from './host-memory.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'
@@ -1230,7 +1231,7 @@ async function receiveCrossRoomPost({ fromRoom, fromHost, fromTerminalName, text
   const msg = `[From: room ${fromLabel} — relayed via the ThinkPool cross-room Ensemble, approved by a person in this room]\n${body}`
   const evt = { kind: 'you', text: msg, by: `room ${fromRoom}`, crosspost: true, relaySourceName: String(fromTerminalName || '').trim().slice(0, 80) || undefined }
   stampEvent(evt); pushLog(te, evt); bcast('code-event', { term: targetId, evt })
-  try { te.session.sendTurn(msg) } catch { return { error: `Could not deliver to room ${room} — the lane may have just closed.` } }
+  try { if (te.session.sendTurn(msg) === false) return { error: `Could not deliver to room ${room} — the lane refused the turn (check its visible host-memory/runtime error).` } } catch { return { error: `Could not deliver to room ${room} — the lane may have just closed.` } }
   return { ok: true, ref: String(targetId).slice(0, 8) }
 }
 
@@ -1576,6 +1577,12 @@ function openTerm({ id, cmd, args = [], attached = false, cols, rows }) {
     bcast('term-exit', { id })
     return
   }
+  const memory = hostMemoryAdmission(`start the ${cmd} terminal`)
+  if (!memory.ok) {
+    process.stderr.write(`\n  ⚠ ${memory.reason}\n`)
+    bcast('term-exit', { id, reason: memory.reason })
+    return
+  }
   const ad = attached ? attachedDims() : null
   // This terminal's private mockup outbox — render.sh run inside it writes here,
   // and the watcher attributes every card to THIS id (not a Map-order guess).
@@ -2333,7 +2340,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           stampEvent(evt)
           pushLog(te, evt)
           bcast('code-event', { term: target.id, evt })
-          try { te.session.sendTurn(msg) } catch { return okText(`Could not deliver to terminal ${target.ref} — it may have just closed.`) }
+          try { if (te.session.sendTurn(msg) === false) return okText(`Could not deliver to terminal ${target.ref} — it refused the turn. Check its visible host-memory/runtime error.`) } catch { return okText(`Could not deliver to terminal ${target.ref} — it may have just closed.`) }
           return okText(`Delivered to terminal ${target.ref} (${target.cmd}). It will respond in its own lane; check back with read_terminal.`)
         },
       )] : []),
@@ -2356,6 +2363,8 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           const okText = (t) => ({ content: [{ type: 'text', text: t }] })
           const resolved = resolveAgentOpen(args)
           if (resolved.error) return okText(resolved.error)
+          const memory = hostMemoryAdmission('start another Cascade conductor')
+          if (!memory.ok) return okText(memory.reason)
           const gate = consumeTerminalOpenBudget()
           if (!gate.ok) return okText(gate.reason)
           const newId = randomUUID()
@@ -2382,7 +2391,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
           const msg = `[Task from main terminal ${fromRef}'s agent — opened as an independent MAIN CASCADE CONDUCTOR terminal, not an Ensemble child]\n${String(args.task).trim()}`
           const evt = { kind: 'you', text: msg, by: `main terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
           stampEvent(evt); pushLog(conductor, evt); bcast('code-event', { term: newId, evt })
-          try { conductor.session.sendTurn(msg) }
+          try { if (conductor.session.sendTurn(msg) === false) return okText(`Opened main conductor ${newRef}, but host pressure prevented its runtime from starting. Existing lanes remain connected; free memory and retry the task.`) }
           catch { return okText(`Opened main conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — the initial task could not be delivered.`) }
           return okText(`Opened independent main Cascade conductor ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It is a main terminal, not an Ensemble lane.`)
         },
@@ -2424,6 +2433,8 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
             spawnedBy: s.spawnedBy,
             busy: (s.session?.turnActive ?? false) || (s.pending?.size ?? 0) > 0,
           }))))
+          const memory = hostMemoryAdmission('start another worker lane')
+          if (!memory.ok) return okText(memory.reason)
           const effectiveArgs = {
             ...args,
             runtime: resolved.runtime,
@@ -2499,7 +2510,7 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
             const msg = `[Task from terminal ${fromRef}'s agent — relayed via ThinkPool Ensemble; you are its WORKER SUB-TERMINAL, never a main terminal or Cascade conductor]\n${args.task}${reviewTarget}`
             const evt = { kind: 'you', text: msg, by: `terminal ${fromRef} (agent)`, crosspost: true, relaySourceName: termNames[id] || undefined }
             stampEvent(evt); pushLog(ne, evt); bcast('code-event', { term: newId, evt })
-            try { ne.session.sendTurn(msg) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
+            try { if (ne.session.sendTurn(msg) === false) return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but host pressure prevented its runtime from accepting the task. Existing lanes remain connected; free memory and retry.`) } catch { return okText(`Opened lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}, but it may still be starting — could not hand off the task. Try post_to_terminal shortly.`) }
             return okText(`Opened agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''} and handed it the task. It runs in its own lane — check back with read_terminal, then close_terminal when done.`)
           }
           return okText(`Opened idle agent lane ${newRef}${args?.name ? ` ("${args.name}")` : ''}. Hand it work with post_to_terminal, or a person can type into it.`)
@@ -2698,6 +2709,10 @@ function openStructured({ id, runtime = 'claude', model, models, effort, resume,
     // defer: a restored-idle terminal cold-boots its query only on first use — restore is
     // then instant for display, and only used terminals pay the ~50s MCP boot (Max, 2026-07-02).
     lazy: shouldDeferStructuredRuntime({ runtime, defer, cwd, flowSessionId, flowTaskKey, models: entry.models }),
+    // One shared host-pressure circuit at the actual cold-runtime boundary. An
+    // empty/restored tab remains visible under pressure; its first expensive
+    // agent process is refused with a recoverable room event until memory returns.
+    admitStart: () => hostMemoryAdmission('start this agent runtime'),
     reviewGate,
     // A Flow CONDUCTOR (flowSessionId set, no flowTaskKey) must DECOMPOSE, not explore via
     // a fan-out of Task/Explore subagents, and must not build. Hard-block Task/Bash/Write for
@@ -3478,7 +3493,7 @@ channel
         stampEvent(parentEvent); pushLog(parent, parentEvent); bcast('code-event', { term: sideParent, evt: parentEvent })
         const snapshot = sideSnapshot(parent.log.filter((event) => event.cid !== parentEvent.cid))
         const prompt = snapshot ? `${snapshot}\n\n--- side task ---\n${task}` : task
-        try { child.session.sendTurn(prompt) } catch {
+        try { if (child.session.sendTurn(prompt) === false) throw new Error('runtime refused the turn') } catch {
           bcast('side-open-failed', { id: payload.id, parent: sideParent, message: 'The side agent could not start.' })
           endStructured(payload.id)
           return
@@ -4279,6 +4294,12 @@ flowChannel
     if (!flowRuntime) return
     const flowCatalog = flowRuntime === 'codex' ? (origin?.models || readCodexModels()) : flowRuntime === 'hermes' ? (origin?.models || []) : []
     const conductorModel = flowConductorModelFor({ runtime: flowRuntime, originModel: origin?.model, catalog: flowCatalog })
+    const memory = hostMemoryAdmission('start the Flow conductor')
+    if (!memory.ok) {
+      process.stderr.write(`\n  ${A.yel}◆ flow start held — ${memory.reason}${A.rst}\n`)
+      bcast('flow-host-pressure', { term: 'flow', flowId: payload.flowId, reason: memory.reason }, flowChannel)
+      return
+    }
     const cid = randomUUID()
     termNames[cid] = `Flow · ${String(payload.flowId).slice(0, 6)}`
     saveNames(room, termNames)
@@ -4335,6 +4356,12 @@ flowChannel
       }
       const gate = canDispatch({ mode: dispMode, liveLanes, budget })
       if (!gate.ok) { process.stderr.write(`\n  ${A.yel}◆ flow dispatch held (${gate.reason}, ${liveLanes}/${FLOW_LIMITS.maxConcurrentLanes} lanes) — ${assignments.length} spawned this wave.${A.rst}\n`); break }
+      const memory = hostMemoryAdmission('start another Flow lane')
+      if (!memory.ok) {
+        process.stderr.write(`\n  ${A.yel}◆ flow dispatch held — ${memory.reason}${A.rst}\n`)
+        bcast('flow-host-pressure', { term: 'flow', flowId: payload.flowId, reason: memory.reason }, flowChannel)
+        break
+      }
       try {
         // Step 4 — a `review` slice gets the adversarial reviewer prompt (try-to-break),
         // every other slice gets the builder prompt.

package/claude-session.mjs

@@ -206,7 +206,7 @@ const TP_ROOM_REMINDER = [
   'BUILD WORKFLOW (default, no magic word): right-size within your TERMINAL ROLE — a trivial ask or delegated slice you just do; a conductor-capable role with a genuinely decomposable build FIRST writes a short plan in chat, THEN fans worker slices into visible spawn_terminal lanes and verifies them. Worker/leaf/Side/managed Flow roles do not fan out. A requested separate conductor uses open_main_terminal. Never plan-mode/ExitPlanMode; plans live in chat and lanes in the existing list.',
 ].join(' ')
 
-export function startClaudeSession({ cwd, model, effort: initialEffort = 'high', resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate, didSpawnTarget = null, terminalRolePrompt, rolePrompt, blockSubagents = false, onSubmitPlan = null, onLaneDone = null, onReviewVerdict = null, reviewGate = null, lazy = false, roomContext = null, suggest = true, prepareCwd = null }) {
+export function startClaudeSession({ cwd, model, effort: initialEffort = 'high', resume, env, mode: initialMode = 'default', onEvent, requestPermission, mcpServers, crossPostGate, crossRoomPostGate, didSpawnTarget = null, terminalRolePrompt, rolePrompt, blockSubagents = false, onSubmitPlan = null, onLaneDone = null, onReviewVerdict = null, reviewGate = null, lazy = false, roomContext = null, suggest = true, prepareCwd = null, admitStart = null }) {
   // Per-turn reminder + live ROOM NOW tail. roomContext (bridge-supplied) returns the
   // room's CURRENT state — sibling lanes, active git worktrees — or null. The static
   // rules keep the agent aware of the room's FEATURES; the live tail keeps it aware of
@@ -812,7 +812,15 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
     finally { clearTimeout(t) }
   }
 
-  const runQuery = async () => {
+  const admitColdStart = () => {
+    const gate = typeof admitStart === 'function' ? admitStart() : { ok: true }
+    if (gate?.ok !== false) return true
+    emit({ kind: 'error', message: gate.reason || 'Host memory is critically low. This agent runtime was not started.', recoverable: true })
+    return false
+  }
+
+  const runQuery = async ({ admitted = false } = {}) => {
+    if (!started && !admitted && !admitColdStart()) return false
     if (spawnT0 == null) spawnT0 = Date.now()
     started = true
     // Per-query AbortController (child of the session `ac`): lets a model switch kill
@@ -1164,7 +1172,7 @@ export function startClaudeSession({ cwd, model, effort: initialEffort = 'high',
   return {
     // A lazy (restored-idle) session cold-boots the query on its first turn. input.push
     // is queue-backed, so the pushed turn buffers and runs once the query is ready.
-    sendTurn(text) { if (!closed) { if (!started && prepareCwd) { try { const next = prepareCwd(); if (next) { cwd = next; opts.cwd = next } } catch { /* keep original cwd */ } } if (!started) runQuery(); turnActive = true; sawSuggestion = false; lastTurnText = String(text); if (sugTimer) { clearTimeout(sugTimer); sugTimer = null } lastEvtTs = Date.now(); stalledSent = false; stallRetried = false; forceStopped = false;
+    sendTurn(text) { if (!closed) { if (!started && !admitColdStart()) return false; if (!started && prepareCwd) { try { const next = prepareCwd(); if (next) { cwd = next; opts.cwd = next } } catch { /* keep original cwd */ } } if (!started) runQuery({ admitted: true }); turnActive = true; sawSuggestion = false; lastTurnText = String(text); if (sugTimer) { clearTimeout(sugTimer); sugTimer = null } lastEvtTs = Date.now(); stalledSent = false; stallRetried = false; forceStopped = false;
       const t = String(text)
       const promptIndex = userPromptNo++
       const thisTurnForceFull = forceFullReminder

package/codex-session.mjs

@@ -352,7 +352,7 @@ function appServerItemForMapper(item) {
  * @param {string} [o.providerConfig] optional -c overrides / provider block (M2: from the provider registry)
  * @returns {{ sendTurn(text, options?), abort(), end(), readonly sessionId }}
  */
-export function startCodexSession({ cwd, model, effort: initialEffort = 'high', resume, env, sandbox, mode = 'default', onEvent, providerConfig, terminalRolePrompt, rolePrompt, roomContext, mcpServers, prepareCwd = null, requestPermission, appServerGate = codexAppServerGate, appServerFactory = createCodexAppServer, mcpHttpFactory = startCodexMcpHttp, spawnImpl = spawn }) {
+export function startCodexSession({ cwd, model, effort: initialEffort = 'high', resume, env, sandbox, mode = 'default', onEvent, providerConfig, terminalRolePrompt, rolePrompt, roomContext, mcpServers, prepareCwd = null, requestPermission, appServerGate = codexAppServerGate, appServerFactory = createCodexAppServer, mcpHttpFactory = startCodexMcpHttp, spawnImpl = spawn, admitStart = null }) {
   let activeMode = CODEX_MODE_CONFIG[mode] ? mode : 'default'
   let modeConfig = codexConfigForMode(activeMode)
   sandbox = normalizeCodexSandbox(sandbox || modeConfig.sandbox)
@@ -764,6 +764,17 @@ export function startCodexSession({ cwd, model, effort: initialEffort = 'high',
     get started() { return turnNo > 0 || turnActive },
     sendTurn(text, options = {}) {
       if (ended) return false
+      // App Server stays resident between turns. Only gate when an idle turn
+      // would have to create a new host process (fresh/resumed cold lane or
+      // exec fallback after App Server failure). Steering an existing process
+      // and reading a restored transcript remain available under pressure.
+      if (!turnActive && queue.length === 0 && !appServerThreadReady && !child) {
+        const gate = typeof admitStart === 'function' ? admitStart() : { ok: true }
+        if (gate?.ok === false) {
+          try { onEvent?.({ kind: 'error', message: gate.reason || 'Host memory is critically low. This Codex runtime was not started.', recoverable: true }) } catch { /* noop */ }
+          return false
+        }
+      }
       const promptIndex = userPromptNo++
       const thisTurnForceFull = forceFullReminder
       forceFullReminder = isCodexCompactCommand(text) || /^\s*\/(?:reset|clear)\b/i.test(String(text || ''))

package/hermes-session.mjs

@@ -67,6 +67,7 @@ export function startHermesSession({
   command = HERMES_COMMAND, args = ['acp'], clientFactory = createAcpClient,
   mcpHttpFactory = startCodexMcpHttp, lazy = false, hermesRole = null,
   crossPostGate = null, didSpawnTarget = null, crossRoomPostGate = null, effort = 'high',
+  admitStart = null,
 } = {}) {
   let activeCwd = cwd
   const requestedModel = model || null
@@ -241,6 +242,8 @@ export function startHermesSession({
     if (crashed) throw new Error('Hermes ACP process crashed; this lane must be restarted before sending another turn')
     if (client?.alive && mapper) return
     if (starting) return starting
+    const gate = typeof admitStart === 'function' ? admitStart() : { ok: true }
+    if (gate?.ok === false) throw new Error(gate.reason || 'Host memory is critically low. This Hermes runtime was not started.')
     starting = (async () => {
       if (!started && prepareCwd) {
         try { activeCwd = prepareCwd() || activeCwd } catch { /* retain original cwd */ }
@@ -516,6 +519,13 @@ export function startHermesSession({
     get effort() { return activeEffort },
     sendTurn(text, options = {}) {
       if (ended) return false
+      if (!client?.alive && !starting) {
+        const gate = typeof admitStart === 'function' ? admitStart() : { ok: true }
+        if (gate?.ok === false) {
+          emit({ kind: 'error', message: gate.reason || 'Host memory is critically low. This Hermes runtime was not started.', recoverable: true })
+          return false
+        }
+      }
       const promptIndex = userPromptNo++
       const thisTurnForceFull = forceFullReminder
       forceFullReminder = /^\s*\/(?:compact|reset|clear)\b/i.test(String(text || ''))

package/host-memory.mjs

@@ -0,0 +1,116 @@
+import os from 'node:os'
+import fs from 'node:fs'
+import { execFileSync } from 'node:child_process'
+
+const MIB = 1024 * 1024
+const DEFAULT_BLOCK_PERCENT = 8
+const DEFAULT_RELEASE_PERCENT = 12
+const DEFAULT_BLOCK_BYTES = 512 * MIB
+const DEFAULT_RELEASE_BYTES = 1024 * MIB
+
+function finiteNumber(value, fallback) {
+  const n = Number(value)
+  return Number.isFinite(n) ? n : fallback
+}
+
+export function parseMacMemoryPressure(output) {
+  const match = String(output || '').match(/System-wide memory free percentage:\s*([0-9]+(?:\.[0-9]+)?)%/i)
+  return match ? Number(match[1]) : null
+}
+
+export function parseLinuxMemAvailable(output) {
+  const text = String(output || '')
+  const available = text.match(/^MemAvailable:\s*(\d+)\s*kB\s*$/mi)
+  const total = text.match(/^MemTotal:\s*(\d+)\s*kB\s*$/mi)
+  if (!available || !total) return null
+  return { availableBytes: Number(available[1]) * 1024, totalBytes: Number(total[1]) * 1024, source: 'proc-meminfo' }
+}
+
+export function memoryDecision(snapshot, { blocked = false, env = process.env } = {}) {
+  if (env.TP_MEMORY_GUARD_OFF === '1') return { ok: true, blocked: false, source: 'disabled' }
+  if (!snapshot) return { ok: true, blocked: false, source: 'unavailable' }
+
+  const blockPercent = Math.max(1, finiteNumber(env.TP_MEMORY_BLOCK_PERCENT, DEFAULT_BLOCK_PERCENT))
+  const releasePercent = Math.max(blockPercent + 1, finiteNumber(env.TP_MEMORY_RELEASE_PERCENT, DEFAULT_RELEASE_PERCENT))
+  const blockBytes = Math.max(64 * MIB, finiteNumber(env.TP_MEMORY_BLOCK_MIB, DEFAULT_BLOCK_BYTES / MIB) * MIB)
+  const releaseBytes = Math.max(blockBytes + MIB, finiteNumber(env.TP_MEMORY_RELEASE_MIB, DEFAULT_RELEASE_BYTES / MIB) * MIB)
+  const availableBytes = Number.isFinite(snapshot.availableBytes) ? snapshot.availableBytes : null
+  const totalBytes = Number.isFinite(snapshot.totalBytes) && snapshot.totalBytes > 0 ? snapshot.totalBytes : null
+  const availablePercent = Number.isFinite(snapshot.availablePercent)
+    ? snapshot.availablePercent
+    : (availableBytes != null && totalBytes ? (availableBytes / totalBytes) * 100 : null)
+
+  // macOS' memory_pressure percentage already accounts for reclaimable/compressed
+  // memory. Generic os.freemem() does not, so a healthy Mac can look ~97% full.
+  // Other platforms need BOTH a low ratio and a low absolute reserve to avoid
+  // rejecting large-memory hosts merely because their page cache is busy.
+  const pressureSignal = snapshot.source === 'macos-memory-pressure'
+  const shouldBlock = pressureSignal
+    ? availablePercent != null && availablePercent <= blockPercent
+    : availablePercent != null && availableBytes != null && availablePercent <= blockPercent && availableBytes <= blockBytes
+  const recovered = pressureSignal
+    ? availablePercent != null && availablePercent >= releasePercent
+    : availablePercent != null && availableBytes != null && (availablePercent >= releasePercent || availableBytes >= releaseBytes)
+  const nextBlocked = blocked ? !recovered : shouldBlock
+
+  return {
+    ok: !nextBlocked,
+    blocked: nextBlocked,
+    source: snapshot.source || 'unknown',
+    availablePercent,
+    availableBytes,
+    blockPercent,
+    releasePercent,
+  }
+}
+
+export function createHostMemoryGuard({
+  platform = process.platform,
+  env = process.env,
+  execFile = execFileSync,
+  readFile = fs.readFileSync,
+  freeMemory = os.freemem,
+  totalMemory = os.totalmem,
+  now = Date.now,
+  cacheMs = 5000,
+} = {}) {
+  let cached = null
+  let cachedAt = 0
+  let blocked = false
+
+  const sample = () => {
+    if (platform === 'darwin') {
+      try {
+        const output = execFile('/usr/bin/memory_pressure', ['-Q'], { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] })
+        const availablePercent = parseMacMemoryPressure(output)
+        if (availablePercent != null) return { availablePercent, source: 'macos-memory-pressure' }
+      } catch { /* fall through to a portable snapshot */ }
+    } else if (platform === 'linux') {
+      try {
+        const parsed = parseLinuxMemAvailable(readFile('/proc/meminfo', 'utf8'))
+        if (parsed) return parsed
+      } catch { /* fall through to a portable snapshot */ }
+    }
+    try {
+      return { availableBytes: freeMemory(), totalBytes: totalMemory(), source: 'os-freemem' }
+    } catch { return null }
+  }
+
+  return function admitHostMemory(activity = 'start new work') {
+    const at = now()
+    if (!cached || at - cachedAt >= cacheMs) {
+      const decision = memoryDecision(sample(), { blocked, env })
+      blocked = decision.blocked
+      cached = decision
+      cachedAt = at
+    }
+    if (cached.ok) return cached
+    const pct = cached.availablePercent == null ? 'critically low' : `${Math.round(cached.availablePercent)}% available`
+    return {
+      ...cached,
+      reason: `Host memory is critically low (${pct}). ThinkPool did not ${activity}. Existing lanes stay connected; close a lane or free memory, then retry.`,
+    }
+  }
+}
+
+export const hostMemoryAdmission = createHostMemoryGuard()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.275",
+  "version": "0.7.276",
   "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",
+    "host-memory.mjs",
     "sdk-smoke.mjs",
     "sdk-admission.mjs",
     "sdk-admission.mjs",

package/service.mjs

@@ -22,6 +22,7 @@ import os from 'node:os'
 import fs from 'node:fs'
 import path from 'node:path'
 import { execSync } from 'node:child_process'
+import { hostMemoryAdmission } from './host-memory.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).
@@ -85,11 +86,13 @@ function runtimeVersion(entry) {
   } catch { return null }
 }
 
-export function provisionRuntime(version, { exec = execSync, root = path.join(os.homedir(), '.thinkpool-pair', 'runtimes') } = {}) {
+export function provisionRuntime(version, { exec = execSync, root = path.join(os.homedir(), '.thinkpool-pair', 'runtimes'), admit = hostMemoryAdmission } = {}) {
   if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(String(version))) throw new Error(`invalid runtime version: ${version}`)
   const dir = path.join(root, String(version))
   const entry = path.join(dir, 'node_modules', 'thinkpool-pair', 'bridge.mjs')
   if (fs.existsSync(entry) && runtimeVersion(entry) === String(version)) return entry
+  const memory = admit('stage a bridge runtime update')
+  if (!memory?.ok) throw new Error(memory?.reason || 'host memory is critically low')
 
   // Install beside the target and only swap it into place after BOTH the entrypoint
   // and package version prove the payload. A killed/poisoned npm install must never