thinkpool-pair 0.7.274 → 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 } })()
 
@@ -501,12 +502,11 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
   acct.on('broadcast', { event: 'restart' }, () => {
     restarting = true
     // The dashboard "Restart bridge" button ALSO updates to the newest published version
-    // (Max, 2026-07-03). If an OS service manages this bridge, spawn a DETACHED updater
-    // that re-pins the service to @latest and reloads it (install-service resolves the
-    // newest version → rewrites the plist/unit → bootout+bootstrap). Detached → its own
-    // session, so it SURVIVES this process being booted out (the reload kills us); it
-    // inherits our env, whose PATH carries nvm's bin, so npx/node resolve — a bare launchd
-    // PATH would NOT (the 2026-07-03 gotcha that made a manual updater silently no-op).
+    // (Max, 2026-07-03). Use service.mjs's authoritative registry → immutable runtime →
+    // one-shot reload transaction directly. Spawning `npx install-service` here used a
+    // disposable cache that legacy services could delete underneath the updater. The
+    // service primitive arms an independent launchd handoff before this process is booted
+    // out, so the reload survives us without a second package execution tree.
     // The reload IS the bounce; sessions resume from disk on the new version. Best-effort:
     // if there's no service or npm is unreachable, we fall through to the plain bounce, so
     // the button is never dead — and even a failed update degrades to today's behaviour.
@@ -525,8 +525,7 @@ export async function runAccount(SUPABASE_URL, SUPABASE_ANON) {
       try {
         const svc = await import('./service.mjs')
         if (svc.serviceActive(null)) {
-          spawn('npx', ['-y', 'thinkpool-pair@latest', 'install-service'], { detached: true, stdio: 'ignore', env: process.env }).unref()
-          updating = true
+          updating = svc.updateService(null) !== false
         }
       } catch { /* no service / spawn failed → plain bounce below */ }
       process.stderr.write(updating
@@ -894,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.274",
+  "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).
@@ -46,16 +47,12 @@ export function darwinServiceRunning(output) {
   const text = String(output || '')
   return /(^|\n)[ \t]*state = running[ \t]*($|\n)/.test(text) && /(^|\n)[ \t]*pid = \d+[ \t]*($|\n)/.test(text)
 }
-// Legacy auto-update services still use npx. Wipe its disposable execution project
-// before resolving the package so an @latest restart cannot re-serve a stale cache.
-// `home` is the platform-correct, runtime-expanded home token ("$HOME" on darwin under
-// /bin/bash; "$$HOME" inside a systemd unit so systemd emits a literal $HOME to bash).
-// npx caches the temporary execution project as a unit. Removing only the package can
-// leave its generated .bin/package-lock metadata behind, producing the contradictory
-// state where `npm view` sees a version but `npx` reports ETARGET or no executable.
-// The whole _npx directory is disposable; clear its children so the next launch is a
-// genuinely clean install.
-const cacheWipe = (home) => `rm -rf ${home}/.npm/_npx/* 2>/dev/null`
+// Legacy auto-update services still use npx. They MUST use a bridge-owned cache:
+// deleting ~/.npm/_npx corrupts unrelated interactive `npx thinkpool-pair` processes
+// (0.7.274 removed account.mjs underneath a live launcher). The service cache is
+// disposable and isolated, so clearing it cannot mutate a person's npm execution tree.
+const serviceNpmCache = () => path.join(os.homedir(), '.thinkpool-pair', 'npm-cache')
+const cacheWipe = (cacheRoot) => `rm -rf ${shq(path.join(cacheRoot, '_npx'))}/* 2>/dev/null`
 
 // The version installing the service. By DEFAULT the service is pinned to this exact
 // version (not @latest) so a future bad npm publish can't auto-roll to every machine's
@@ -89,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
@@ -130,6 +129,7 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   const logDir = path.join(os.homedir(), '.thinkpool-pair')
   const log = path.join(logDir, `${id}.log`)
   const servicePath = sanitizeServicePath(process.env.PATH || '', platform)
+  const npmCache = serviceNpmCache()
   const tail = cmdArgs.length ? ['--', ...cmdArgs] : []
   const desc = room ? `bridge (${room})` : 'account bridge'
   // OS-supervised tiers (launchd KeepAlive / systemd Restart) don't need --supervise.
@@ -156,7 +156,7 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
     const args = runtimeEntry
       ? [process.execPath, runtimeEntry, ...(room ? [room] : []), ...tail]
       : staleProof
-      ? ['/bin/bash', '-lc', `${cacheWipe('"$HOME"')}; exec ${[npx, ...pkgArgs, ...tail].map(shq).join(' ')}`]
+      ? ['/bin/bash', '-lc', `${cacheWipe(npmCache)}; export NPM_CONFIG_CACHE=${shq(npmCache)}; exec ${[npx, ...pkgArgs, ...tail].map(shq).join(' ')}`]
       : [npx, ...pkgArgs, ...tail]
     const file = path.join(os.homedir(), 'Library', 'LaunchAgents', `${label(room)}.plist`)
     const content = `<?xml version="1.0" encoding="UTF-8"?>
@@ -175,7 +175,7 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
   <key>WorkingDirectory</key><string>${xml(cwd)}</string>
   <key>StandardOutPath</key><string>${xml(log)}</string>
   <key>StandardErrorPath</key><string>${xml(log)}</string>
-  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(servicePath)}</string>${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}</dict>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>${xml(servicePath)}</string>${runtimeEntry ? '' : `<key>NPM_CONFIG_CACHE</key><string>${xml(npmCache)}</string>`}${autoUpdate ? '<key>THINKPOOL_PAIR_AUTOUPDATE</key><string>1</string>' : ''}</dict>
 </dict></plist>\n`
     // The destructive reload is intentionally NOT represented as an inline `post`
     // command. installService stages this plist and hands the transaction to an
@@ -193,7 +193,7 @@ export function buildArtifact(platform, { room = null, cmdArgs = [], autoUpdate
     const execStart = runtimeEntry
       ? args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')
       : staleProof
-      ? `/bin/bash -lc "${cacheWipe('$$HOME')}; exec ${[npx, ...pkgArgs, ...tail].join(' ')}"`
+      ? `/bin/bash -lc "${cacheWipe(npmCache)}; export NPM_CONFIG_CACHE=${shq(npmCache)}; exec ${[npx, ...pkgArgs, ...tail].join(' ')}"`
       : args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')
     const content = `[Unit]
 Description=ThinkPool Code ${desc}
@@ -211,7 +211,7 @@ RestartSec=2
 RestartPreventExitStatus=0
 WorkingDirectory=${cwd}
 Environment=PATH=${servicePath}
-${autoUpdate ? 'Environment=THINKPOOL_PAIR_AUTOUPDATE=1\n' : ''}StandardOutput=append:${log}
+${runtimeEntry ? '' : `Environment=NPM_CONFIG_CACHE=${npmCache}\n`}${autoUpdate ? 'Environment=THINKPOOL_PAIR_AUTOUPDATE=1\n' : ''}StandardOutput=append:${log}
 StandardError=append:${log}
 
 [Install]
@@ -232,7 +232,7 @@ WantedBy=default.target
       : room
       ? ['npx', '-y', ...onlineFlag, verSpec, room, '--supervise', ...tail].join(' ')
       : ['npx', '-y', ...onlineFlag, verSpec].join(' ')
-    const content = `@echo off\r\ntitle thinkpool-pair ${id}\r\n${inner}\r\n`
+    const content = `@echo off\r\ntitle thinkpool-pair ${id}\r\n${runtimeEntry ? '' : `set "NPM_CONFIG_CACHE=${npmCache}"\r\n`}${inner}\r\n`
     return { file, content, logDir, post: [], note: 'Installed to the Startup folder — runs at login' + (room ? ' with --supervise (auto-restart on crash).' : ' (account mode).') + ' Start it now without rebooting by double-clicking the .cmd, or run it from a terminal.' }
   }