@wastedtokens/agent-switchboard 1.2.1 → 1.4.0

package/README.md

@@ -8,11 +8,23 @@ and pushes peer messages straight into your live session as `<channel>` tags.
 ## Install
 
 Mint an API key at [switchboard.wastedtokens.io/keys](https://switchboard.wastedtokens.io/keys)
-(sign in with your wastedtokens account; the preview is invite-only), then:
+(sign in with your wastedtokens account; the preview is invite-only). Export it in your shell
+profile so the key itself never lands in a repo:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+export SWITCHBOARD_API_KEY=wtsb_...
+```
+
+Then add switchboard at **user scope** — one install covers every project on the machine,
+and the key stays in your profile, out of any project's git. Your identity defaults to your
+**key's label**: name the key well (e.g. `moshe-macbook`) and every session on the machine
+gets that stable directory identity with zero further config (`AGENT_NAME` still overrides;
+an unlabeled or oddly-labeled key falls back to an anonymous `anon-<host>-<pid>` name):
 
 ```bash
 claude mcp add -s user switchboard \
-  -e SWITCHBOARD_API_KEY=wtsb_... \
+  -e SWITCHBOARD_API_KEY="$SWITCHBOARD_API_KEY" \
   -- npx -y @wastedtokens/agent-switchboard@latest
 ```
 
@@ -22,34 +34,115 @@ Channels are a Claude Code research preview, so launch sessions with:
 claude --dangerously-load-development-channels server:switchboard
 ```
 
-For a stable agent identity (a named project agent rather than an ephemeral one), and
-**instant presence** so the session is reachable the moment it connects (see below):
-
-```bash
-claude mcp add -s project switchboard \
-  -e SWITCHBOARD_API_KEY=wtsb_... \
-  -e AGENT_NAME=my-project-agent -e AGENT_PROJECT="$PWD" \
-  -e SWITCHBOARD_AUTO_ANNOUNCE=1 \
-  -- npx -y @wastedtokens/agent-switchboard@latest
+### Stable per-project identity (committed `.mcp.json`)
+
+A project that wants a **named** agent (rather than an anonymous one) can commit an `.mcp.json`
+so every session in that repo shares the identity — but **a minted key never belongs in version
+control.** Reference it by env-var indirection instead: Claude Code expands `${VAR}` in
+`.mcp.json` from your shell, so commit the *reference*, not the secret (keep the `export` from
+above in your profile):
+
+```jsonc
+// .mcp.json — safe to commit; the key lives in your shell profile, never here
+{
+  "mcpServers": {
+    "switchboard": {
+      "command": "npx",
+      "args": ["-y", "@wastedtokens/agent-switchboard@latest"],
+      "env": {
+        "SWITCHBOARD_API_KEY": "${SWITCHBOARD_API_KEY}",
+        "AGENT_NAME": "my-project-agent",
+        "AGENT_PROJECT": "${PWD}",
+        "SWITCHBOARD_AUTO_ANNOUNCE": "1"
+      }
+    }
+  }
+}
 ```
 
+Keep the server key **`switchboard`** (never a variant) — a user-scope and a project-scope
+entry under the same name dedupe to one client via Claude Code's scope precedence, which is
+what keeps a session to a single identity. Set `AGENT_NAME` so the project agent is legible in
+the directory.
+
+> **Never commit a raw `wtsb_…` key.** A checked-in `.mcp.json` with an inline key is a leaked
+> secret. Always use `${SWITCHBOARD_API_KEY}` indirection and export the value from your shell
+> profile.
+
 ## Use
 
 In-session: `announce` once, `who_is_online`, `send_message(to, body)`, and answer pushed
 `<channel source="switchboard" from="X" thread="Y">` messages with
 `reply(to="X", thread="Y", body=...)`. `message_status(id)` returns the delivery receipt
-(`queued | leased | delivered | expired`) for a message you sent. `logoff` when done.
+(`queued | leased | delivered | expired`) plus `delivered_to` — which identity actually
+consumed the message. `thread_history(thread)` reads a thread's prior messages when you join
+mid-conversation (see *Taking over a thread* below). `logoff` when done.
+
+### Shared mailboxes (work queues)
+
+A **shared mailbox** (created on the dashboard or via `POST /api/v1/mailboxes`) is a durable
+queue any of your sessions can serve — the "support@" pattern. Sending to it works like any
+send; consuming is per-message:
+
+- `announce(mailboxes: ["support"])` attaches mailboxes for the announce **reconcile block** —
+  real queued counts for your own mailbox, each attached shared mailbox, and threads you're
+  the sticky consumer for (pull-for-truth after a gap). Set `AGENT_MAILBOXES=support,triage`
+  instead to pin the attachment in config — **the env wins over the tool argument**.
+- `claim_next(mailbox)` claims the oldest unclaimed message: it's pushed into your session,
+  acked under **your** identity (the receipt's `delivered_to` names you, not the mailbox),
+  and any open task on its thread moves to `working`, claimed by you. An empty result means
+  the queue is drained.
+- `task_update(id, state)` reports work-truth: `working` | `input-required` (escalated,
+  waiting on the requester) | `completed` | `failed`. Tasks auto-create as `submitted` when a
+  message lands in a shared mailbox; closed tasks stay closed.
+
+Against an older relay (pre-1.6) these tools degrade to a clear error ("does not support
+shared mailboxes/tasks yet") instead of failing cryptically; the reconcile block is simply
+omitted.
+
+### Taking over a thread (`thread_history`)
+
+When you `claim_next` a message, you land mid-conversation: the relay hands you exactly one
+message row, but that thread may have a long history — the previous consumer went offline,
+their stickiness lapsed, and the requester's next message fell back to the pool for you to
+pick up. `thread_history(thread)` reads the prior messages so you can catch up before you
+reply. It's a **read-only observation** — it never claims or consumes, and it's tenant-scoped
+(you can read any of *your* threads).
+
+- Every claimed (and pushed) message carries its `thread`; a claimed message also carries
+  `task_id`/`task_state` so you can drive the task with `task_update`.
+- `thread_history(thread)` returns the thread's messages oldest→newest, plus `has_more`,
+  `next_before`, and `control_omitted` (relay lifecycle frames are filtered out of the
+  conversation by default and only counted). The `task` and `affinity` blocks tell you the
+  thread's open work and its sticky consumer.
+- **Paging:** the newest page comes back first (default 100, max 200 messages). When
+  `has_more` is `true`, call again with `before: <next_before>` to walk older messages until
+  `has_more` is `false`.
+
+A typical takeover:
+
+```
+claim_next(mailbox: "support")          # → { messages: [{ thread, task_id, task_state, … }] }
+thread_history(thread: "<that thread>") # → catch up on the conversation so far
+# … page older with before: next_before while has_more …
+reply(to: "<requester>", thread: "<that thread>", body: "…")   # answer in-context
+task_update(id: "<task_id>", state: "completed")               # close the loop
+```
+
+Against a relay older than **1.8.0** (no thread-read route) `thread_history` returns a clear
+"relay too old — upgrade to ≥1.8.0" error rather than failing cryptically.
 
 ### Instant presence + clean shutdown
 
 By default the channel is idle until the agent calls `announce`. Set
 `SWITCHBOARD_AUTO_ANNOUNCE=1` and it instead registers and opens its push stream the moment it
-connects — no manual `announce` needed; the session is reachable from the start. Add it as one
-more `-e` flag (as in the named-agent install above):
+connects — no manual `announce` needed; the session is reachable from the start. It's already in
+the committed-`.mcp.json` example above; for a user-scope install add it as one more `-e` flag
+(key by env-var indirection, never inline):
 
 ```bash
-claude mcp add -s project switchboard \
-  -e SWITCHBOARD_API_KEY=wtsb_... -e AGENT_NAME=my-project-agent \
+claude mcp add -s user switchboard \
+  -e SWITCHBOARD_API_KEY="$SWITCHBOARD_API_KEY" -e AGENT_NAME=my-agent \
   -e SWITCHBOARD_AUTO_ANNOUNCE=1 \
   -- npx -y @wastedtokens/agent-switchboard@latest
 ```
@@ -69,6 +162,14 @@ the same name doesn't fight for the mailbox — it takes a suffixed **ephemeral*
 (`my-agent-2`, `-3`, …) that prunes automatically after 24h. Cross-machine name collisions
 resolve the same way (the relay returns 409, the client re-suffixes and retries).
 
+**Same-session self-defense.** Two switchboard clients under the *same Claude Code session*
+(e.g. a mid-session config change that adds a second MCP entry) would otherwise split your
+inbound and outbound traffic across two identities. The client detects this from its lock
+files and keeps exactly one live: the newer/explicitly-named client wins, the other goes
+**inert** (serves no tools, opens no stream) and logs one line naming the survivor and the fix
+— remove the duplicate MCP config entry. An already-running client demotes itself in place if a
+same-session peer supersedes it. Set `SWITCHBOARD_ALLOW_SAME_SESSION=1` to disable the check.
+
 ### Prove the relay round-trip
 
 ```bash
@@ -86,9 +187,11 @@ path end-to-end before wiring the channel into a session. (Pass the key inline
 |---|---|
 | `SWITCHBOARD_API_KEY` | **required** — your per-user key (`wtsb_…`) |
 | `SWITCHBOARD_URL` | relay base URL (default `https://switchboard.wastedtokens.io`) |
-| `AGENT_NAME` | stable directory identity; omit for an ephemeral anonymous name. A concurrent second process with the same name auto-suffixes (`-2`, `-3`, …) |
+| `AGENT_NAME` | stable directory identity; omit to derive one from your **key's label** (`whoami.key_name`), falling back to an anonymous `anon-<host>-<pid>` name. A concurrent second process with the same name auto-suffixes (`-2`, `-3`, …) |
+| `AGENT_MAILBOXES` | comma list of shared mailboxes to attach at announce (reconcile counts); **wins over** the `announce` tool's `mailboxes` argument |
 | `AGENT_PROJECT` / `AGENT_MACHINE` / `AGENT_CAPABILITIES` | directory metadata |
 | `SWITCHBOARD_AUTO_ANNOUNCE` | `1` ⇒ register + open the push stream on connect (instant presence, no manual `announce`) |
+| `SWITCHBOARD_ALLOW_SAME_SESSION` | `1` ⇒ disable same-session duplicate detection (tests / exotic setups) |
 
 Delivery is at-least-once (the relay redelivers on unacked streams); the client dedupes by
 message id, so your session sees each message once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wastedtokens/agent-switchboard",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "type": "module",
   "description": "Claude Code channel client for the hosted Switchboard relay (switchboard.wastedtokens.io) — pushes peer-agent messages into a live session, no polling.",
   "license": "UNLICENSED",

package/switchboard-channel.mjs

@@ -18,12 +18,14 @@
  * tools until you opt in.
  *
  * Env: SWITCHBOARD_API_KEY (required), SWITCHBOARD_URL, AGENT_NAME, AGENT_PROJECT,
- *      AGENT_MACHINE, AGENT_CAPABILITIES (comma list)
+ *      AGENT_MACHINE, AGENT_CAPABILITIES (comma list), AGENT_MAILBOXES (comma list —
+ *      shared mailboxes to attach at announce; env wins over the tool argument),
+ *      SWITCHBOARD_ALLOW_SAME_SESSION, SWITCHBOARD_AUTO_ANNOUNCE
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js'
-import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs'
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync, readdirSync } from 'node:fs'
 import { homedir, hostname } from 'node:os'
 import { join } from 'node:path'
 import { randomBytes } from 'node:crypto'
@@ -38,10 +40,45 @@ if (!KEY) {
   )
   process.exit(1)
 }
-const NAME = process.env.AGENT_NAME || `anon-${hostname()}-${process.pid}`
 const PROJECT = process.env.AGENT_PROJECT || process.cwd()
 const MACHINE = process.env.AGENT_MACHINE || hostname()
 const CAPS = (process.env.AGENT_CAPABILITIES || '').split(',').filter(Boolean)
+// §2e shared-mailbox attachment (comma list). When both the env and the announce tool
+// argument are present, the ENV WINS — headless/config-managed setups must not be
+// overridable by a tool call. Attachment is per-announce, never persisted relay-side.
+const AGENT_MAILBOXES = (process.env.AGENT_MAILBOXES || '').split(',').map((s) => s.trim()).filter(Boolean)
+
+// §2a naming precedence: AGENT_NAME env → whoami.key_name → anon-<host>-<pid>. A well-named
+// key gives a stable fleet-wide identity with zero per-machine config. The whoami call happens
+// once at startup; a pre-§2a relay (404 on /whoami), an unreachable relay, or a key label that
+// is not a valid agent name (relay's own name regex — labels may contain spaces) all fall
+// through to the anon default: never crash, never try to register an unregistrable name.
+// Key-derived names are stable but NOT explicit — the lock's `explicit` field stays
+// "AGENT_NAME was set in the env", exactly as §1c defines it.
+const ANON_NAME = `anon-${hostname()}-${process.pid}`
+const AGENT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/
+async function deriveKeyName() {
+  try {
+    // Bounded (5s): startup must never stall the MCP connect on a hanging relay — a slow
+    // whoami degrades to the anon name, exactly like a 404 from a pre-§2a relay.
+    const res = await fetch(`${API}/whoami`, { headers: authHeaders(), signal: AbortSignal.timeout(5000) })
+    if (!res.ok) return null
+    const data = await res.json().catch(() => ({}))
+    const kn = typeof data.key_name === 'string' ? data.key_name.trim() : ''
+    if (AGENT_NAME_RE.test(kn)) return kn
+  } catch {}
+  return null
+}
+const NAME = process.env.AGENT_NAME || (await deriveKeyName()) || ANON_NAME
+
+// Same-session identity (routing-v2 §1c). `session` is the ownership signal for
+// duplicate-in-session detection; `explicit` records whether the OPERATOR chose this
+// name (AGENT_NAME set) — NOT whether the name is unsuffixed. The default anon-<host>-<pid>
+// name takes the base lock unsuffixed yet is never explicit. `SWITCHBOARD_ALLOW_SAME_SESSION=1`
+// disables the scan entirely (tests, exotic setups; CI has no session env so it no-ops anyway).
+const SESSION = process.env.CLAUDE_CODE_SESSION_ID || null
+const EXPLICIT = 'AGENT_NAME' in process.env && !!process.env.AGENT_NAME
+const ALLOW_SAME_SESSION = process.env.SWITCHBOARD_ALLOW_SAME_SESSION === '1'
 
 const SB_DIR = join(homedir(), '.switchboard')
 const idCachePath = (name) => join(SB_DIR, `${name}.id`)
@@ -53,6 +90,32 @@ const pidAlive = (pid) => {
 
 const MAX_SUFFIX_HOPS = 8
 
+// Lock-file body (routing-v2 §1c): JSON `{pid,session,name,explicit}`. Written on every
+// lock acquisition so a same-session sibling can read our metadata and both sides compute
+// the same winner from lock files alone (no signaling). Legacy ≤1.2.x clients wrote a bare
+// pid string — `parseLock` still honors those (staleness by pid; session null; explicit
+// false), so a mixed fleet during rollout stays safe.
+function lockBody(name) {
+  return JSON.stringify({ pid: process.pid, session: SESSION, name, explicit: EXPLICIT })
+}
+function parseLock(raw) {
+  const s = (raw || '').trim()
+  if (!s) return null
+  try {
+    const o = JSON.parse(s)
+    if (o && typeof o === 'object' && Number.isFinite(Number(o.pid))) {
+      return { pid: Number(o.pid), session: o.session ?? null, name: o.name ?? null, explicit: o.explicit === true }
+    }
+  } catch {}
+  // Legacy bare-pid lock from a ≤1.2.x client.
+  const pid = Number(s)
+  if (Number.isFinite(pid)) return { pid, session: null, name: null, explicit: false }
+  return null
+}
+function readLock(name) {
+  try { return parseLock(readFileSync(lockPath(name), 'utf8')) } catch { return null }
+}
+
 // Take the lock for one name, atomically. Creation is ALWAYS `wx` (exclusive) — a stale
 // (dead-pid) lock is unlinked and creation re-attempted, so when two crash successors
 // race the takeover, exactly one wx-create wins and the loser moves to the next suffix.
@@ -61,15 +124,15 @@ const MAX_SUFFIX_HOPS = 8
 function tryLock(name) {
   for (let attempt = 0; attempt < 2; attempt++) {
     try {
-      writeFileSync(lockPath(name), String(process.pid), { flag: 'wx' })
+      writeFileSync(lockPath(name), lockBody(name), { flag: 'wx' })
     } catch {
-      let holder = NaN
-      try { holder = Number(readFileSync(lockPath(name), 'utf8').trim()) } catch {}
-      if (pidAlive(holder)) return false
+      const holder = readLock(name)
+      if (holder && pidAlive(holder.pid)) return false
       try { unlinkSync(lockPath(name)) } catch {}
       continue // stale lock removed — re-attempt the exclusive create (one winner)
     }
-    try { if (readFileSync(lockPath(name), 'utf8').trim() === String(process.pid)) return true } catch {}
+    const back = readLock(name)
+    if (back && back.pid === process.pid) return true
     return false
   }
   return false
@@ -90,12 +153,102 @@ function acquireIdentity() {
 
 function releaseIdentity(identity) {
   try {
-    if (readFileSync(lockPath(identity.name), 'utf8').trim() === String(process.pid))
-      unlinkSync(lockPath(identity.name))
+    const held = readLock(identity.name)
+    if (held && held.pid === process.pid) unlinkSync(lockPath(identity.name))
   } catch {}
 }
 
-const state = { id: null, subscribing: false, running: true, identity: acquireIdentity(), sseCtl: null }
+// --- same-session duplicate detection (routing-v2 §1c) ----------------------
+// The incident: a second switchboard client under the SAME Claude Code session mints a
+// second identity and both serve, splitting inbound/outbound. Defense: after we hold our
+// own lock, scan every *.lock for another LIVE lock with our session id; if one beats us
+// under the deterministic metadata tiebreak, WE lose and go inert. Both sides read each
+// other's lock files and compute the same winner — no signaling protocol.
+//
+// Tiebreak (on recorded lock metadata, symmetric): explicit:true beats explicit:false;
+// still tied → lower pid wins. Raw pid is NOT the primary key — the incident's stale anon
+// client is the OLDER (lower-pid) process and must lose to the newer explicit-named one.
+// Returns true iff `other` beats `self`.
+function otherWins(self, other) {
+  if (self.explicit !== other.explicit) return other.explicit === true
+  return other.pid < self.pid
+}
+
+// Scan for a live same-session lock that beats US. `self` is our own {pid,session,explicit}.
+// Returns the winning peer's parsed lock (naming its identity) or null. Idle-cheap: a stat +
+// small read per lock file, only the handful in ~/.switchboard. Never matches a null session
+// (legacy/anon-no-session locks can't collide) so the escape hatch and CI both no-op.
+function findSameSessionWinner(self) {
+  if (ALLOW_SAME_SESSION || !self.session) return null
+  let files
+  try { files = readdirSync(SB_DIR) } catch { return null }
+  for (const f of files) {
+    if (!f.endsWith('.lock')) continue
+    const other = readLock(f.slice(0, -'.lock'.length))
+    if (!other) continue
+    if (other.pid === self.pid) continue // our own lock
+    if (!other.session || other.session !== self.session) continue // different session (or session-less)
+    if (!pidAlive(other.pid)) continue // dead pid → stale, ignore (staleness stays pid-based)
+    if (otherWins(self, other)) return other
+  }
+  return null
+}
+
+const state = {
+  id: null, subscribing: false, running: true, identity: acquireIdentity(), sseCtl: null, inert: false,
+  // §2e attached shared mailboxes for register/reconcile. Seeded from AGENT_MAILBOXES; an
+  // announce `mailboxes` argument can set it ONLY when the env list is empty (env wins).
+  mailboxes: AGENT_MAILBOXES,
+}
+
+function selfLock() {
+  return { pid: process.pid, session: SESSION, explicit: EXPLICIT }
+}
+
+// One loud stderr line + the message every inert tool call returns. Names the surviving
+// identity and the operator fix.
+function inertMessage(winnerName) {
+  return `another switchboard client in this session already owns '${winnerName}' — remove the duplicate MCP config entry`
+}
+
+// Loser path: stop serving, drop everything, log once. Used both at startup (before we ever
+// registered) and for active convergence (demote in place while running). Idempotent.
+async function goInert(winnerName) {
+  if (state.inert) return
+  state.inert = true
+  state.running = false
+  state.inertMsg = inertMessage(winnerName)
+  try { state.sseCtl?.abort() } catch {}
+  releaseIdentity(state.identity)
+  if (state.id) { await relay('POST', '/logoff', { id: state.id }).catch(() => {}) ; state.id = null }
+  console.error(`@wastedtokens/agent-switchboard: ${state.inertMsg}`)
+}
+
+// Active convergence check (routing-v2 §1c): run before serving each tool call, at the top
+// of each subscribeLoop reconnect, and on a 60s timer. If a live same-session lock now beats
+// us, demote in place. Returns true iff we (are/became) inert.
+async function convergeInert() {
+  if (state.inert) return true
+  const winner = findSameSessionWinner(selfLock())
+  if (winner) { await goInert(winner.name); return true }
+  return false
+}
+
+// Startup arbitration (routing-v2 §1c "lock first, then scan"): acquireIdentity() already
+// took our lock above; now check for a live same-session lock that beats us. If found we
+// release and go inert BEFORE registering or opening any stream. Nothing to log off (no id
+// yet), so this stays synchronous. Two same-session clients spawning concurrently both run
+// lock→scan→tiebreak and converge on one survivor.
+{
+  const winner = ALLOW_SAME_SESSION ? null : findSameSessionWinner(selfLock())
+  if (winner) {
+    state.inert = true
+    state.running = false
+    state.inertMsg = inertMessage(winner.name)
+    releaseIdentity(state.identity)
+    console.error(`@wastedtokens/agent-switchboard: ${state.inertMsg}`)
+  }
+}
 
 function authHeaders(extra = {}) {
   return { 'Content-Type': 'application/json', Authorization: `Bearer ${KEY}`, ...extra }
@@ -113,6 +266,12 @@ async function relay(method, path, body) {
   return { status: res.status, retryAfter: Number(res.headers.get('retry-after')) || 0, data }
 }
 
+// Degradation probe (routing-v2 Rollout): a relay that predates a route 404s it with a
+// non-JSON (HTML) or empty body — relay() surfaces that as `http 404` or `{}`. A JSON 404
+// from the route itself ("no such mailbox: X", "no such task") carries its own error string
+// and passes through untouched. Same pattern as the pre-#12 receipt fallback in selftest.
+const preRoutingV2 = (r) => r.status === 404 && (!r.data.error || r.data.error === 'http 404')
+
 // CLI selftest (issue #12): a full round-trip through the CONFIGURED relay — register ->
 // subscribe (SSE) -> send -> receive the push -> ack -> receipt — so an operator can prove
 // the edge/proxy path end-to-end before wiring it into a session. Exits 0 (pass) / 1 (fail).
@@ -201,7 +360,22 @@ async function register() {
   const r = await relay('POST', '/register', {
     id: state.id || cached, name: ident.name, project: PROJECT,
     machine: MACHINE, capabilities: CAPS, presence: 'live', ephemeral: ident.ephemeral,
+    // §2e: attach shared mailboxes per-announce; the response's reconcile block reports
+    // queued counts for them. Old relays ignore unknown body fields — wire-compatible.
+    ...(state.mailboxes.length ? { mailboxes: state.mailboxes } : {}),
   })
+  // Cancellation boundary (codex round 1, high): a same-session winner can appear WHILE this
+  // /register is in flight, so goInert() may have run with state.id still null (no /logoff). If
+  // we've since gone inert, do NOT mutate active state or hop a new suffix — undo instead:
+  // best-effort /logoff any id the relay just handed us, drop our lock, and report failure so no
+  // caller subscribes or sends. Without this a demoted loser could resurrect a live relay
+  // identity from the resuming register response.
+  if (state.inert || !state.running) {
+    if (r.data.id) relay('POST', '/logoff', { id: r.data.id }).catch(() => {})
+    releaseIdentity(state.identity)
+    state.id = null
+    return { status: r.status, retryAfter: r.retryAfter, data: { error: 'inert' } }
+  }
   if (r.status === 409) {
     // name owned by another LIVE process (other machine, or a lock we couldn't see):
     // take the next suffix as an ephemeral identity and let the caller retry.
@@ -221,8 +395,10 @@ async function register() {
 // 30s-backoff path — a buggy or hostile relay can never spin this client hot.
 async function registerWithSuffixRetry() {
   let r = await register()
-  for (let hop = 0; hop < MAX_SUFFIX_HOPS && r.status === 409; hop++) r = await register()
-  if (r.status === 409)
+  // Stop hopping the moment we've gone inert (register() already undid its side effects and
+  // returned {error:'inert'}); never keep 409-suffixing on a demoted client.
+  for (let hop = 0; hop < MAX_SUFFIX_HOPS && r.status === 409 && !state.inert; hop++) r = await register()
+  if (r.status === 409 && !state.inert)
     console.error('@wastedtokens/agent-switchboard: relay refused every suffixed name (409) — giving up this attempt')
   return r
 }
@@ -265,12 +441,16 @@ async function pushChannel(server, m) {
 }
 
 async function subscribeLoop(server) {
-  if (state.subscribing) return
+  if (state.subscribing || state.inert) return
   state.subscribing = true
   while (state.running) {
+    // Active convergence (routing-v2 §1c): a same-session client may have won since we last
+    // looked — demote in place before (re)attaching the stream. goInert aborts sseCtl + logs off.
+    if (await convergeInert()) break
     try {
       if (!state.id) {
         const r = await registerWithSuffixRetry()
+        if (state.inert) break // demoted during the in-flight register — never subscribe
         if (!state.id) {
           // Registration REJECTED (bad name, agent cap, rate limit, exhausted 409
           // cascade...): back off — never hit /subscribe without an id, never
@@ -324,7 +504,7 @@ const fail = (obj) => ({ isError: true, content: [{ type: 'text', text: JSON.str
 
 // --- MCP server + tools -----------------------------------------------------
 const server = new Server(
-  { name: 'switchboard', version: '1.2.0' },
+  { name: 'switchboard', version: '1.4.0' },
   {
     capabilities: { experimental: { 'claude/channel': {} }, tools: {} },
     instructions:
@@ -334,13 +514,34 @@ const server = new Server(
       'and the SAME thread. Start with `announce` so peers can find you and so messages start ' +
       'flowing; use `who_is_online` to see peers; `send_message` to start a new conversation; ' +
       '`logoff` when done. A message with a non-empty control attribute is a lifecycle signal, ' +
-      'not conversation.',
+      'not conversation. Shared work queues: `claim_next` pulls the oldest unclaimed message ' +
+      'from a shared mailbox (claiming also moves its open task to working under you); ' +
+      '`task_update` reports task progress (input-required / completed / failed). When a claim ' +
+      'or a wake lands you in an unfamiliar thread, `thread_history` reads the prior messages so ' +
+      'you can catch up before replying.',
   },
 )
 
 const TOOLS = [
-  { name: 'announce', description: 'Register/refresh this agent on the switchboard, begin receiving pushed peer messages, and return the live directory. Call once at session start.',
-    inputSchema: { type: 'object', properties: {} } },
+  { name: 'announce', description: 'Register/refresh this agent on the switchboard, begin receiving pushed peer messages, and return the live directory plus a reconcile block (queued counts for your mailbox, attached shared mailboxes, and your sticky threads — pull-for-truth on attach; older relays omit it).',
+    inputSchema: { type: 'object', properties: {
+      mailboxes: { type: 'array', items: { type: 'string' }, description: 'shared mailboxes to attach for reconcile counts (ignored when AGENT_MAILBOXES is set — env wins)' },
+    } } },
+  { name: 'claim_next', description: 'Claim the oldest unclaimed message from a shared mailbox (work queue). The claimed message is delivered to this session and acked under YOUR identity; any open task on its thread moves to working, claimed by you. Each claimed message carries its thread plus task_id/task_state (null when the thread has no open task) — drive the task with task_update. Landed mid-conversation? Call thread_history with that thread to read what came before. Empty result = nothing queued.',
+    inputSchema: { type: 'object', properties: {
+      mailbox: { type: 'string', description: 'shared mailbox name (kind=mailbox) to claim from' },
+    }, required: ['mailbox'] } },
+  { name: 'thread_history', description: 'Read the prior messages of a thread for takeover context — a tenant-scoped, read-only observation that never claims or consumes. Pull it after claim_next lands you in an unfamiliar thread, or after a wake, to reconstruct the conversation before you joined. Returns messages oldest→newest plus has_more, next_before, and control_omitted; when has_more is true, call again with before: next_before to page older messages. The task and affinity blocks describe the thread\'s open work and its sticky consumer.',
+    inputSchema: { type: 'object', properties: {
+      thread: { type: 'string', description: 'thread id to read (the thread of a claimed/pushed message)' },
+      limit: { type: 'number', description: 'max messages this page (default 100, max 200)' },
+      before: { type: 'string', description: 'pagination cursor — pass the previous response\'s next_before to page older' },
+    }, required: ['thread'] } },
+  { name: 'task_update', description: 'Update a task\'s state: working | input-required (escalated, waiting on the requester) | completed | failed. Tasks are created automatically when a message lands in a shared mailbox; claiming moves them to working. Closed tasks stay closed.',
+    inputSchema: { type: 'object', properties: {
+      id: { type: 'string', description: 'task id (task_…)' },
+      state: { type: 'string', enum: ['working', 'input-required', 'completed', 'failed'] },
+    }, required: ['id', 'state'] } },
   { name: 'who_is_online', description: 'List your agents on the switchboard with presence (live/offline), project, machine, and queued counts.',
     inputSchema: { type: 'object', properties: {} } },
   { name: 'send_message', description: 'Send a message to another of your agents by name or id. Queued for delivery if the recipient is offline.',
@@ -355,7 +556,7 @@ const TOOLS = [
       to: { type: 'string' }, thread: { type: 'string' }, body: { type: 'string' },
       in_reply_to: { type: 'string', description: 'optional msg_id being answered' },
     }, required: ['to', 'thread', 'body'] } },
-  { name: 'message_status', description: 'Delivery receipt for a message you sent: queued | leased | delivered | expired.',
+  { name: 'message_status', description: 'Delivery receipt for a message you sent: queued | leased | delivered | expired. Includes delivered_to — which identity is consuming the addressed mailbox (rename-safe; older relays may omit it).',
     inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'message id from send_message' } }, required: ['id'] } },
   { name: 'logoff', description: 'Go offline now and stop receiving pushes.',
     inputSchema: { type: 'object', properties: {} } },
@@ -363,27 +564,163 @@ const TOOLS = [
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 
+// --- argument validation (issue #36 nit 2) ----------------------------------
+// Reject a call with a missing/mistyped required arg or an unknown arg BEFORE any relay
+// hit — a bare `message_status` used to send GET /messages/undefined (encodeURIComponent of
+// undefined is the literal "undefined"), silently querying a nonexistent id. The check is
+// driven off each tool's own inputSchema so every handler is covered uniformly. Required
+// strings must be present and non-empty (they land in URL paths); optional strings may be
+// empty; numbers accept a numeric value or numeric string (the relay parses either).
+function typeError(k, v, spec, requireNonEmpty) {
+  const t = spec.type
+  if (t === 'string') {
+    if (typeof v !== 'string') return `parameter '${k}' must be a string`
+    if (requireNonEmpty && v.trim() === '') return `parameter '${k}' must not be empty`
+  } else if (t === 'number' || t === 'integer') {
+    const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : NaN
+    if (!Number.isFinite(n)) return `parameter '${k}' must be a number`
+  } else if (t === 'array') {
+    if (!Array.isArray(v)) return `parameter '${k}' must be an array`
+  }
+  return null
+}
+function validateArgs(name, args) {
+  const tool = TOOLS.find((t) => t.name === name)
+  if (!tool) return null // unknown tool name — let the switch default throw its own error
+  const props = tool.inputSchema?.properties || {}
+  const required = tool.inputSchema?.required || []
+  for (const k of Object.keys(args)) {
+    if (!(k in props))
+      return `unknown parameter '${k}' for ${name} (allowed: ${Object.keys(props).join(', ') || 'none'})`
+  }
+  for (const k of required) {
+    const v = args[k]
+    if (v === undefined || v === null) return `missing required parameter '${k}' for ${name}`
+    const err = typeError(k, v, props[k] || {}, true)
+    if (err) return err
+  }
+  for (const k of Object.keys(props)) {
+    if (required.includes(k)) continue
+    const v = args[k]
+    if (v === undefined || v === null) continue // optional + absent is fine
+    const err = typeError(k, v, props[k] || {}, false)
+    if (err) return err
+  }
+  return null
+}
+
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const a = req.params.arguments || {}
+  // Param validation runs first so a malformed call fails clearly (and cheaply) before we
+  // touch identity/convergence or the relay — no GET /messages/undefined (issue #36 nit 2).
+  const paramErr = validateArgs(req.params.name, a)
+  if (paramErr) return fail({ error: paramErr })
+  // logoff must stay functional even when inert (a demoted client still cleans up on exit).
+  // Every other tool re-runs the same-session scan first (active convergence, routing-v2 §1c):
+  // an already-running client demotes the instant a live same-session peer beats it, and an
+  // inert client refuses every call with the one loud message.
+  if (req.params.name !== 'logoff') {
+    await convergeInert()
+    if (state.inert) return fail({ error: state.inertMsg })
+  }
   switch (req.params.name) {
     case 'announce': {
+      // §2e mailbox attachment — a pure function of (env, argument) on EVERY announce:
+      // AGENT_MAILBOXES wins when set (config-managed setups can't be re-pointed by a tool
+      // call); otherwise the argument, and an absent argument means NO attachment. Nothing
+      // persists relay-side; reconnect re-registers just re-send this announce's attachment.
+      state.mailboxes = AGENT_MAILBOXES.length
+        ? AGENT_MAILBOXES
+        : Array.isArray(a.mailboxes)
+          ? a.mailboxes.filter((m) => typeof m === 'string' && m.trim()).map((m) => m.trim()).slice(0, 16)
+          : []
       const r = await registerWithSuffixRetry()
+      // A same-session winner may have appeared during that in-flight register (codex round 1):
+      // register() already undid its state, so recheck before opening the push stream.
+      if (state.inert) return fail({ error: state.inertMsg })
       if (!state.id) return fail({ error: `registration failed: ${r.data.error || `http ${r.status}`}` })
       subscribeLoop(server) // fire-and-forget background push loop
-      return ok((await relay('GET', '/directory')).data)
+      const dir = (await relay('GET', '/directory')).data
+      // §2e pull-for-truth on attach: surface the register response's reconcile block (queued
+      // counts for own mailbox / attached shared mailboxes / sticky threads). A pre-1.6 relay
+      // returns no reconcile — omit it rather than fabricate one.
+      return ok(r.data.reconcile !== undefined ? { ...dir, reconcile: r.data.reconcile } : dir)
     }
     case 'who_is_online':
       return ok((await relay('GET', '/directory')).data)
     case 'message_status':
       return ok((await relay('GET', `/messages/${encodeURIComponent(a.id)}`)).data)
+    case 'thread_history': {
+      // Takeover context (spec §3): read-only passthrough of GET /api/v1/threads/{thread}.
+      // The pagination surface (has_more / next_before / control_omitted) and the task/affinity
+      // blocks are returned UNCHANGED so the consumer can page and reason about them directly.
+      const q = new URLSearchParams()
+      if (a.limit !== undefined && a.limit !== null) q.set('limit', String(a.limit))
+      if (a.before) q.set('before', String(a.before))
+      const qs = q.toString()
+      const r = await relay('GET', `/threads/${encodeURIComponent(a.thread)}${qs ? `?${qs}` : ''}`)
+      // Graceful degrade on a pre-1.8 relay: the route 404s with a non-JSON body (preRoutingV2),
+      // distinct from the route's own JSON 404 "no such thread" — same pattern as the receipt
+      // fallback. Wire errors (404 no such thread / 400 bad cursor) pass straight through.
+      if (preRoutingV2(r)) return fail({ error: 'relay too old for thread history — upgrade the relay to ≥1.8.0' })
+      return r.status === 200 ? ok(r.data) : fail(r.data)
+    }
+    case 'claim_next': {
+      // §2e: per-message claim from a shared work queue. Needs a registered consumer identity
+      // (the relay refuses mailbox/unknown consumers); lazy-register like send_message does.
+      if (!state.id) await registerWithSuffixRetry()
+      if (state.inert) return fail({ error: state.inertMsg }) // demoted during the lazy register
+      if (!state.id) return fail({ error: 'registration failed — cannot claim without a consumer identity' })
+      // Pin the consumer id: the ack and any hand-back must use the id the claim was leased
+      // under, never mutable state.id (subscribeLoop can re-register concurrently).
+      const consumerId = state.id
+      // The relay may lease rows server-side even when WE never see the response (network
+      // drop, body read failure) — never let a throw bypass the cancellation check below
+      // (codex k2 round 2, medium).
+      let r = null
+      try { r = await relay('POST', '/claim', { mailbox: a.mailbox, agent_id: consumerId, max: 1 }) } catch {}
+      // Cancellation boundary (codex k2 round 1, high): same-session demotion can land WHILE
+      // /claim is in flight — goInert logs off and nulls state.id, but the resumed tool would
+      // still inject the claimed work into a session that must be inert, and its lease would
+      // dangle until expiry. Re-check before touching any message: on demotion, hand the rows
+      // back UNCONDITIONALLY (a failed/errored response may still have leased server-side;
+      // /logoff is idempotent and requeues consumerId's leased rows — goInert's own logoff may
+      // have run BEFORE the relay processed the claim, so this second, awaited-bounded one is
+      // what releases the late lease) and refuse with the inert error. Nothing pushed or acked.
+      if (state.inert || !state.running || state.id !== consumerId) {
+        await Promise.race([relay('POST', '/logoff', { id: consumerId }), sleep(2000)]).catch(() => {})
+        return fail({ error: state.inertMsg || 'consumer identity changed during the claim — retry claim_next' })
+      }
+      // Live client, lost response: any server-side lease returns to the pool via lease expiry
+      // (bounded, the existing at-least-once design) — logoff here would kill a healthy stream.
+      if (!r) return fail({ error: 'claim request failed (network) — retry claim_next' })
+      if (preRoutingV2(r)) return fail({ error: 'this relay does not support shared mailboxes yet (pre-1.6 server)' })
+      if (r.status !== 200) return fail(r.data) // 404 no such mailbox / 409 not a mailbox|is a mailbox — wire error passthrough
+      // Deliver exactly like the inbox drain: push into the session, then ack ONLY what was
+      // pushed (a failed push stays leased and returns to the pool on lease expiry). The ack
+      // runs under the pinned consumer id — the §2b ownership predicate finalizes claimed rows
+      // under the consumer, so the receipt's delivered_to reports this identity, not the mailbox.
+      const msgs = r.data.messages || []
+      const acks = []
+      for (const m of msgs) { const acked = await pushChannel(server, m); if (acked) acks.push(acked) }
+      if (acks.length) await relay('POST', '/ack', { agent_id: consumerId, ids: acks }).catch(() => {})
+      return ok({ claimed: msgs.length, messages: msgs })
+    }
+    case 'task_update': {
+      const r = await relay('POST', `/tasks/${encodeURIComponent(a.id)}`, { state: a.state })
+      if (preRoutingV2(r)) return fail({ error: 'this relay does not support tasks yet (pre-1.6 server)' })
+      return r.status === 200 ? ok(r.data) : fail(r.data) // 400 invalid state / 404 no such task / 409 task closed
+    }
     case 'send_message':
       if (!state.id) await registerWithSuffixRetry()
+      if (state.inert) return fail({ error: state.inertMsg }) // demoted during the lazy register
       return ok((await relay('POST', '/send', {
         from: state.identity.name, to: a.to, body: a.body, subject: a.subject || '',
         thread: a.thread || null,
       })).data)
     case 'reply':
       if (!state.id) await registerWithSuffixRetry()
+      if (state.inert) return fail({ error: state.inertMsg }) // demoted during the lazy register
       return ok((await relay('POST', '/send', {
         from: state.identity.name, to: a.to, body: a.body, thread: a.thread, in_reply_to: a.in_reply_to || null,
       })).data)
@@ -419,8 +756,23 @@ for (const sig of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(sig, shutdown)
 
 await server.connect(new StdioServerTransport())
 
+// Active-convergence timer (routing-v2 §1c, axis iii): a purely-idle client whose SSE stream
+// is healthy never re-checks via the loop or a tool call, so a 60s timer catches it. Idle-cheap
+// (stat + small read of a handful of lock files). `unref`'d so it never keeps the process alive;
+// self-clears once inert (demotion is one-way). Skipped entirely when the scan is disabled.
+if (!ALLOW_SAME_SESSION && SESSION) {
+  // 60s default; SWITCHBOARD_CONVERGE_MS lets integration tests tick fast (the incident-shape
+  // test can't wait a real minute for an idle incumbent to demote). Clamped to ≥250ms.
+  const everyMs = Math.max(250, Number(process.env.SWITCHBOARD_CONVERGE_MS) || 60_000)
+  const timer = setInterval(() => {
+    if (state.inert) { clearInterval(timer); return }
+    convergeInert().catch(() => {})
+  }, everyMs)
+  timer.unref?.()
+}
+
 // Auto-announce (issue #12): opt-in instant presence — register + open the push stream on
 // connect, so a session is reachable without the operator remembering to call `announce`.
-if (process.env.SWITCHBOARD_AUTO_ANNOUNCE === '1') {
+if (process.env.SWITCHBOARD_AUTO_ANNOUNCE === '1' && !state.inert) {
   registerWithSuffixRetry().then(() => { if (state.id) subscribeLoop(server) }).catch(() => {})
 }