thinkpool-pair 0.7.319 → 0.7.320

package/README.md

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

package/account.mjs

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

package/bridge.mjs

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

package/command-guidance.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.319",
+  "version": "0.7.320",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "bridge.mjs",
+    "command-guidance.mjs",
     "abort-turn-barrier.mjs",
     "host-memory.mjs",
     "sdk-smoke.mjs",

package/provider.mjs

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

package/serve-consent.mjs

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

package/service.mjs

@@ -24,6 +24,7 @@ import path from 'node:path'
 import { execSync } from 'node:child_process'
 import { hostMemoryAdmission } from './host-memory.mjs'
 import { readSupervisorReady, supervisorReadyMatches } from './supervisor-ready.mjs'
+import { pairCli } from './command-guidance.mjs'
 
 // Service identity. Account mode has no room → a single stable id so there's
 // exactly one account service per machine (a second install replaces it).
@@ -499,10 +500,10 @@ export function installService(room, cmdArgs = [], { autoUpdate = false, version
     ? (process.platform === 'win32'
         ? 'auto-update ON: a new thinkpool-pair@latest applies on the next login/restart (Windows has no in-process self-update).'
         : `auto-update ON: checks npm ~every 30 min and restarts to apply a new @latest once sessions are idle (≥${idleSecs}s quiet; they resume in place).`)
-    : `PINNED to ${version} (stable local runtime; restarts do not depend on npx or the network). To update: use "Restart & update the bridge" (or re-run install-service from a newer thinkpool-pair). Pass --auto-update to track @latest instead.`
+    : `PINNED to ${version} (stable local runtime; restarts do not depend on npx or the network). To update: use "Restart & update the bridge" (or run ${pairCli('install-service', room || undefined)}). Pass --auto-update to track @latest instead.`
   const removeArg = room ? ` ${room}` : ''
   const what = room ? `room ${room}` : 'your account (auto-serves every session)'
-  process.stderr.write(`  ◆ ${what}\n  ◆ ${process.platform === 'darwin' ? 'Launchd is completing and verifying the reload independently.' : a.note}\n  ◆ ${updateNote}\n  ◆ logs: ${path.join(a.logDir, `${slug(room)}.log`)}\n  ◆ remove with: thinkpool-pair uninstall-service${removeArg}\n\n`)
+  process.stderr.write(`  ◆ ${what}\n  ◆ ${process.platform === 'darwin' ? 'Launchd is completing and verifying the reload independently.' : a.note}\n  ◆ ${updateNote}\n  ◆ logs: ${path.join(a.logDir, `${slug(room)}.log`)}\n  ◆ remove with: ${pairCli('uninstall-service')}${removeArg}\n\n`)
   return true
 }