agent-switchboard 2.3.0__tar.gz → 2.4.0__tar.gz

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/.github/workflows/ci.yml

@@ -143,13 +143,19 @@ jobs:
   # success is the failure being fixed.
   browser:
     runs-on: ubuntu-latest
-    # The only job here that installs system packages, and the only one that
-    # has hung. On #138 `playwright install --with-deps` sat in apt for 71
-    # minutes; GitHub's default job timeout is six HOURS, so nothing would have
-    # said so until the afternoon was gone, and the PR reads as `unstable` —
-    # not red, not green — the whole time. Ten minutes is roughly five times
-    # the step's normal cost, so it bounds the hang without failing a slow
-    # mirror.
+    # This job used to install system packages, and it was the only one that
+    # ever hung or failed on something outside the repo. On #138
+    # `playwright install --with-deps` sat in apt for 71 minutes; on #251 the
+    # same step failed twice with a Hash Sum mismatch fetching Google's Chrome
+    # index, because `--with-deps` adds apt — and therefore dl.google.com — to
+    # the critical path of a job that only needs a browser binary.
+    #
+    # ubuntu-latest already ships the shared libraries Chromium links against,
+    # so the deps step is gone. If that ever stops being true, Chromium fails
+    # to launch and the tests below go red — loudly, and without a skip, which
+    # the last step enforces.
+    #
+    # The timeout stays: it bounded the hang before and costs nothing.
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
@@ -157,7 +163,7 @@ jobs:
         with:
           python-version: "3.12"
       - run: pip install -e '.[dev]' playwright
-      - run: playwright install --with-deps chromium
+      - run: playwright install chromium
       - name: the page, in a browser — and nothing may skip
         # `-p no:randomly` keeps the summary line stable to grep. The skip
         # check is the whole point of the job: if the browser fixture ever
@@ -170,6 +176,27 @@ jobs:
             exit 1
           fi
 
+  # The landing page quotes real terminal output. Until #277 the largest of
+  # those blocks was generated from site/demo.cast, so it could not drift;
+  # that generator is gone and the quotes are now placed by hand, which means
+  # a change to the CLI's output can leave the page showing a line no run
+  # prints any more. site/PRINCIPLES.md principle 4 is the whole reason this
+  # page is worth anything, so it is checked rather than trusted.
+  #
+  # Offline on purpose: it reads only files in this repository. The island
+  # boards are quoted from another host and are checked by hand with
+  # `python3 site/check-quotes.py --online`, because a CI run should not go
+  # red over somebody else's uptime. Stdlib only, so there is nothing to
+  # install.
+  site-quotes:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python3 site/check-quotes.py
+
   docker:
     runs-on: ubuntu-latest
     steps:
@@ -184,48 +211,86 @@ jobs:
           curl -sf http://127.0.0.1:8787/health | grep -q '"ok":true'
           docker rm -f swb
 
-  # Dogfooding: this CI run announces itself on the same hub the rest of
-  # this project coordinates over, same as local/cloud agents do via the
-  # SessionStart hook `init` installs (see cli.py's _SESSION_START_CMD).
-  # It announces into its own workspace rather than the interactive one, so a
-  # CI run never shows up in the middle of a human session's peers.
+  # A smoke test against the real hub, not a notice board.
+  #
+  # This used to announce into a fixed room so a CI run appeared beside the
+  # human sessions. That room's identifier sat in this file in plain text, and
+  # since #73 the hub does no authorization — reaching a room IS knowing its
+  # identifier — so it was the one published room in a repository whose own
+  # .gitignore refuses to commit .mcp.json for the same reason.
   #
-  # The token is read from MANAGED_HUB_TOKEN in the checkout, the same way
-  # deploy.yml reads the value it starts the hub with. That is the whole point:
-  # a private second copy in `secrets.SWITCHBOARD_TOKEN` drifted from the hub's
-  # own token and locked this job out for a day without failing a build (#96).
-  # Since #76 a token admits a caller to the hub and scopes nothing, so there
-  # is nothing for a secret copy to protect that the published one does not.
+  # The fix is not a secret. Nobody was reading what CI announced, so the room
+  # does not need to persist: the job mints its own, uses it, and drops it. No
+  # identifier to leak, no key to rotate, no secret withheld from a fork's pull
+  # request — and the job now behaves identically for a contributor as it does
+  # on main.
   #
-  # Never gates the rest of CI, and never fails silently either: the announce
-  # cannot break a build, but a failure is reported as a warning on the run
-  # instead of one line of stderr in a green job.
+  # What it buys beyond safety: the old job could not fail. It warned and
+  # exited green, so a client that could not reach the hub at all still showed
+  # a passing check. This one mints, announces, and reads the roster back,
+  # asserting the agent it just created is there. That is the whole client
+  # path — keygen, seal, POST, GET, decrypt — against the live hub on every
+  # run, and it goes red when any of it breaks.
+  #
+  # The token still comes from MANAGED_HUB_TOKEN in the checkout rather than a
+  # secret: a private copy drifted from the hub's own token and locked this job
+  # out for a day without failing a build (#96). Since #76 a token admits a
+  # caller and scopes nothing, so a secret copy protects nothing the published
+  # one does not.
   register-switchboard:
+    # Never on a pull request. This is the one job that talks to a server
+    # somebody has to keep up, and a hub reboot must not turn a contributor's
+    # PR red for a reason that has nothing to do with their change — red for
+    # no reason is how people learn to ignore red.
+    #
+    # On main it gates, which is the point: a check that cannot fail is not a
+    # check, and the old one warned and exited green even when the client
+    # could not reach the hub at all.
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
       - run: pip install -e .
-      - name: Announce this CI run to the hub
+      - name: Mint a room, announce into it, and read it back
         env:
           SWITCHBOARD_URL: https://switchboard.lucille-ai.com
-          SWITCHBOARD_WORKSPACE: w_gAbpTxVh-Jl0pjx0Hnqupw
+          SWITCHBOARD_AGENT_ID: ci-${{ github.run_id }}-${{ github.run_attempt }}
         run: |
+          set -euo pipefail
+
           SWITCHBOARD_TOKEN="$(sed -n 's/^MANAGED_HUB_TOKEN = "\([^"]*\)".*/\1/p' \
             src/switchboard/config.py | head -1)"
-          export SWITCHBOARD_TOKEN
           if [ -z "$SWITCHBOARD_TOKEN" ]; then
-            echo "::warning title=switchboard::MANAGED_HUB_TOKEN not found in" \
-              "src/switchboard/config.py — this CI run was not announced"
-            exit 0
+            echo "::error title=switchboard::MANAGED_HUB_TOKEN not found in" \
+              "src/switchboard/config.py"
+            exit 1
           fi
-          if ! out="$(switchboard -q register --kind ci -c build \
-              --task "${{ github.event_name }} ${{ github.ref_name }}@${{ github.sha }}" 2>&1)"; then
-            # Last line only: an auth failure is one line, but a connection
-            # failure is a whole httpx traceback (#88), and a warning is a
-            # one-line surface. The last line is the diagnosis in both cases.
-            echo "::warning title=switchboard::announce failed:" \
-              "$(printf '%s' "${out:-no output}" | tail -n 1)"
+          export SWITCHBOARD_TOKEN
+
+          # A room of its own, thrown away when the job ends. Everything in it
+          # expires on its own anyway — presence in two minutes.
+          eval "$(switchboard keygen --no-input | sed 's/^/export /')"
+
+          MARK="${{ github.event_name }} ${{ github.ref_name }}@${{ github.sha }}"
+          switchboard -q announce --kind ci -c build --task "$MARK"
+
+          # The assertion, and it is deliberately on the task rather than on
+          # the agent id. Ids are scrambled before they reach the hub, so the
+          # one in SWITCHBOARD_AGENT_ID never appears in a roster — an
+          # assertion against it fails every time, which is how this was
+          # written the first time and caught by rehearsing it.
+          #
+          # The task is sealed on the way out and opened on the way back, so
+          # finding it here proves the whole path: mint, seal, POST, GET,
+          # decrypt. Announcing alone would only prove a write was accepted.
+          if ! switchboard --json agents | grep -qF "$MARK"; then
+            echo "::error title=switchboard::announced \"$MARK\" but it did" \
+              "not come back from the roster"
+            switchboard --json agents
+            exit 1
           fi
+          echo "hub round trip ok — announced and read back: $MARK"

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/.gitignore

@@ -30,3 +30,9 @@ uv.lock
 
 # repoctx: generated index + feedback state, per-machine.
 .repoctx/
+
+# Seeded design canvas — regenerated from site/design/*.dc.html by the design skill
+site/design/agentswitchboard-landing.html
+
+# macOS Finder metadata
+.DS_Store

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/ARCS.md

@@ -41,7 +41,7 @@ issue — read off a line in the README rather than reported by anyone.
 
 ### 🟠 What protects a room once the hub stops authorizing anyone
 
-`hub-boundary` · 10 item(s), 7 startable
+`hub-boundary` · 10 item(s), 6 startable
 
 `https://github.com/gald33/switchboard/issues/61` · `https://github.com/gald33/switchboard/issues/73` · `docs/model.md` · `docs/encryption.md`
 
@@ -68,7 +68,7 @@ under pressure.
 | item | status | priority |
 |---|---|---|
 | `a-drain-that-retries-forever-never-escalates` | ready | now |
-| `ci-workspace-is-public` | ready | now |
+| `ci-workspace-is-public` | done | now |
 | `stale-resolver-references` | ready | now |
 | `seal-agent-meta` | ready | next |
 | `abuse-control-after-authorization` | deferred | — |
@@ -80,7 +80,7 @@ under pressure.
 
 ### 🟠 The first ten minutes, for somebody who has not read the docs
 
-`setup-and-first-run` · 22 item(s), 16 startable
+`setup-and-first-run` · 23 item(s), 14 startable
 
 `https://github.com/gald33/switchboard/issues/86` · `https://github.com/gald33/switchboard/issues/88` · `https://github.com/gald33/switchboard/issues/89` · `docs/environments.md`
 
@@ -102,8 +102,8 @@ wrong says so.
 
 | item | status | priority |
 |---|---|---|
-| `first-contact-needs-a-key-it-cannot-have` | ready | now |
-| `inbox-consumes-what-it-cannot-open` | ready | now |
+| `first-contact-needs-a-key-it-cannot-have` | done | now |
+| `inbox-consumes-what-it-cannot-open` | done | now |
 | `automatic-session-checkpoints` | ready | next |
 | `connect-failure-message` | done | next |
 | `cross-key-rendezvous` | ready | next |
@@ -124,6 +124,7 @@ wrong says so.
 | `unread-dms-not-shown-outside-mcp` | ready | — |
 | `write-parity-across-surfaces` | ready | — |
 | `hooks-warning-false-positive` | done | later |
+| `rootless-warning-false-positive` | done | later |
 
 ### 🟠 Ceilings that are honest about themselves
 

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-switchboard
-Version: 2.3.0
+Version: 2.4.0
 Summary: An ephemeral orchestration hub for AI coding agents: presence, leases, messaging and a shared blackboard, all with TTLs.
 Project-URL: Homepage, https://github.com/gald33/switchboard
 Project-URL: Issues, https://github.com/gald33/switchboard/issues
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
 
 **An ephemeral orchestration hub for AI coding agents.**
 
-*Early release — pre-1.0, the shape is still settling. Two minutes in:
+*Early release — the shape is still settling. Two minutes in:
 [watch two agents coordinate](demo/README.md) before installing anything.*
 
 When several coding agents work the same repo — one on your laptop, one in a
@@ -123,22 +123,21 @@ heartbeat — 15 minutes by default — with nobody having to remember anything.
 ## Install
 
 ```bash
-# Agent side: client + CLI only (one dependency, httpx)
+# Agents, the CLI and the MCP bridge — everything except running a hub
 pip install agent-switchboard
 
-# Hub side: also the server
+# Also the hub, if you are running one yourself
 pip install "agent-switchboard[server]"
-
-# With end-to-end encryption
-pip install "agent-switchboard[crypto]"
-
-# With the MCP bridge for Claude Code / any MCP client
-pip install "agent-switchboard[all]"
 ```
 
+Encryption is not an extra: `cryptography` is a base dependency, because a
+build that cannot encrypt is not a working install. `[crypto]` still resolves
+— released docs and images ask for it — but it is now a no-op, and `[all]` is
+`[server]` plus that no-op. Nothing but `switchboard serve` needs either.
+
 To track `main` instead of a release — for unreleased fixes, or to
 contribute — install from GitHub instead:
-`pip install "agent-switchboard[all] @ git+https://github.com/gald33/switchboard.git"`,
+`pip install "agent-switchboard[server] @ git+https://github.com/gald33/switchboard.git"`,
 or pin a commit or tag by appending it to the URL:
 `git+https://github.com/gald33/switchboard.git@v0.7.2`.
 
@@ -328,6 +327,7 @@ Agents then get these as native tools:
 | `claim` / `release` / `claims` | take, drop and inspect leases |
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
+| `rendezvous` | meet an agent you have never exchanged a message with |
 | `checkin` | heartbeat + renew leases + drain inbox, in one call |
 | *(CLI only)* `switchboard listen` | park until a reply arrives, then exit so the runner wakes the session |
 | `session_handoff` / `session_import` / `session_resume` | move a whole Claude Code session to another environment |
@@ -336,6 +336,24 @@ Agents then get these as native tools:
 keeps the agent alive, renews everything it holds, and hands back anything
 other agents said since last time.
 
+`rendezvous` is the one for agents who have not met. Every other timing signal
+here is built *from* contact, so none of it helps before the first exchange —
+this leaves a note that outlives your presence by a day and hands both sides a
+shared slot derived from the workspace and the hub's clock. Two agents who
+cannot even agree a topic use the reserved `open` one and say which side they
+are on: `offer` (I have capacity) matches `want` (I have a task) and never
+another offer, so a room of idle helpers does not report itself as a meeting.
+On the CLI those are `--offer` and `--want`.
+
+`--show` (MCP: `show`) is what you *read*, which is a different question from
+who can answer you: `matches` by default, `all` for the topic as it stands,
+`wants` or `offers` for one side. Matching does not move with it — a note you
+asked to see but cannot answer comes back marked `matches: false` rather than
+as a peer — and whatever the filter removed is counted under `hidden`, so an
+empty list never has to be read as an empty room. That distinction is the
+whole point: the cost of getting it wrong is not a missed meeting but a
+stranger handed a task it never offered to take.
+
 The listener has no MCP tool on purpose: parking is a *process* that outlives
 the tool call, so it is the CLI run in the background — with the mechanism the
 runner itself tracks, not `&` or `nohup`, which park and wake nobody. `say`,

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/README.md

@@ -2,7 +2,7 @@
 
 **An ephemeral orchestration hub for AI coding agents.**
 
-*Early release — pre-1.0, the shape is still settling. Two minutes in:
+*Early release — the shape is still settling. Two minutes in:
 [watch two agents coordinate](demo/README.md) before installing anything.*
 
 When several coding agents work the same repo — one on your laptop, one in a
@@ -85,22 +85,21 @@ heartbeat — 15 minutes by default — with nobody having to remember anything.
 ## Install
 
 ```bash
-# Agent side: client + CLI only (one dependency, httpx)
+# Agents, the CLI and the MCP bridge — everything except running a hub
 pip install agent-switchboard
 
-# Hub side: also the server
+# Also the hub, if you are running one yourself
 pip install "agent-switchboard[server]"
-
-# With end-to-end encryption
-pip install "agent-switchboard[crypto]"
-
-# With the MCP bridge for Claude Code / any MCP client
-pip install "agent-switchboard[all]"
 ```
 
+Encryption is not an extra: `cryptography` is a base dependency, because a
+build that cannot encrypt is not a working install. `[crypto]` still resolves
+— released docs and images ask for it — but it is now a no-op, and `[all]` is
+`[server]` plus that no-op. Nothing but `switchboard serve` needs either.
+
 To track `main` instead of a release — for unreleased fixes, or to
 contribute — install from GitHub instead:
-`pip install "agent-switchboard[all] @ git+https://github.com/gald33/switchboard.git"`,
+`pip install "agent-switchboard[server] @ git+https://github.com/gald33/switchboard.git"`,
 or pin a commit or tag by appending it to the URL:
 `git+https://github.com/gald33/switchboard.git@v0.7.2`.
 
@@ -290,6 +289,7 @@ Agents then get these as native tools:
 | `claim` / `release` / `claims` | take, drop and inspect leases |
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
+| `rendezvous` | meet an agent you have never exchanged a message with |
 | `checkin` | heartbeat + renew leases + drain inbox, in one call |
 | *(CLI only)* `switchboard listen` | park until a reply arrives, then exit so the runner wakes the session |
 | `session_handoff` / `session_import` / `session_resume` | move a whole Claude Code session to another environment |
@@ -298,6 +298,24 @@ Agents then get these as native tools:
 keeps the agent alive, renews everything it holds, and hands back anything
 other agents said since last time.
 
+`rendezvous` is the one for agents who have not met. Every other timing signal
+here is built *from* contact, so none of it helps before the first exchange —
+this leaves a note that outlives your presence by a day and hands both sides a
+shared slot derived from the workspace and the hub's clock. Two agents who
+cannot even agree a topic use the reserved `open` one and say which side they
+are on: `offer` (I have capacity) matches `want` (I have a task) and never
+another offer, so a room of idle helpers does not report itself as a meeting.
+On the CLI those are `--offer` and `--want`.
+
+`--show` (MCP: `show`) is what you *read*, which is a different question from
+who can answer you: `matches` by default, `all` for the topic as it stands,
+`wants` or `offers` for one side. Matching does not move with it — a note you
+asked to see but cannot answer comes back marked `matches: false` rather than
+as a peer — and whatever the filter removed is counted under `hidden`, so an
+empty list never has to be read as an empty room. That distinction is the
+whole point: the cost of getting it wrong is not a missed meeting but a
+stranger handed a task it never offered to take.
+
 The listener has no MCP tool on purpose: parking is a *process* that outlives
 the tool call, so it is the CLI run in the background — with the mechanism the
 runner itself tracks, not `&` or `nohup`, which park and wake nobody. `say`,

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/demo/chess.sh

@@ -128,12 +128,12 @@ done
 banner "TWO AGENTS, BOTH LIVE — chess channel"
 
 export SWITCHBOARD_AGENT_ID=tal
-step 'switchboard register --kind local -c chess --name tal --task "playing chess as Mikhail Tal"' \
-  switchboard register --kind local -c chess --name tal --task "playing chess as Mikhail Tal"
+step 'switchboard announce --kind local -c chess --name tal --task "playing chess as Mikhail Tal"' \
+  switchboard announce --kind local -c chess --name tal --task "playing chess as Mikhail Tal"
 
 export SWITCHBOARD_AGENT_ID=petrosian
-step 'switchboard register --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"' \
-  switchboard register --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"
+step 'switchboard announce --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"' \
+  switchboard announce --kind local -c chess --name petrosian --task "playing chess as Tigran Petrosian"
 
 step 'switchboard agents' \
   switchboard agents

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/demo/run.sh

@@ -100,8 +100,8 @@ banner "SESSION 1 — alice, local laptop"
 # alice as present when beta checks the roster a few seconds from now in
 # this recording. Shortening it here compresses that into a demo-friendly
 # few seconds without changing anything about how the protocol behaves.
-step 'switchboard register --kind local -c build --ttl 5' \
-  switchboard register --kind local -c build --ttl 5
+step 'switchboard announce --kind local -c build --ttl 5' \
+  switchboard announce --kind local -c build --ttl 5
 
 step 'switchboard board list --prefix coord/' \
   switchboard board list --prefix coord/
@@ -122,8 +122,8 @@ banner "2 HOURS LATER — new session, new machine"
 
 # --- session 2: beta, cloud session, no memory of alice ---------------------
 export SWITCHBOARD_AGENT_ID=beta
-step 'switchboard register --kind cloud -c build' \
-  switchboard register --kind cloud -c build
+step 'switchboard announce --kind cloud -c build' \
+  switchboard announce --kind cloud -c build
 
 step 'switchboard agents' \
   switchboard agents

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/docs/claude-code.md

@@ -328,7 +328,9 @@ Two things use it, and they are different questions:
   — and reports per room who is there and who has a listener parked.
   `switchboard find <name or branch>` is the same sweep with a peer in mind.
   `--here` keeps `rendezvous` to this room. `switchboard --room <label>
-  <command>` then runs one command in the room the sweep pointed at.
+  <command>` then runs one command in the room the sweep pointed at. (Which
+  *notes* you read within a room is a separate control, `--show` — see
+  [Somebody you have never messaged](#somebody-you-have-never-messaged).)
 - **Expecting someone.** `listen` parks in this room, the lobby, and every
   room this machine joined, was invited into or minted in the last hour —
   without being told. `--in <label>` adds a known room; `--only <label>`
@@ -728,12 +730,74 @@ the case to log.
 | `inbox` | Collect messages (set `wait` to block for them) |
 | `history` | Catch up on a channel you just joined |
 | `board_set` / `board_get` / `board_list` | Hand off structured context |
+| `rendezvous` | Meeting an agent you have never exchanged a message with — see below |
 | `keygen` | Starting a private side-conversation with specific peers — see below |
 | `join_room` | Enter a room somebody sent an invite for — see below |
 | `session_handoff` | Move this whole session to another agent, or with no `to` checkpoint it on the board for anyone holding the key — see section 7 |
 | `session_import` | Collect a session handed to you (or one capsule by id) into this machine's Claude config dir; installs, never resumes |
 | `session_resume` | Start `claude --bg --resume` for an installed session and get the `claude attach` line back. Local; never touches the hub |
 
+### Somebody you have never messaged
+
+Every other timing signal here is built *from* contact — a forecast comes from
+your own history with a peer and rides on a message — so none of it helps
+before the first exchange, which is exactly where two agents most reliably
+miss each other: one looks for five minutes and leaves, the other arrives at
+minute six, and both were right that the room was empty.
+
+`rendezvous` (CLI: `switchboard rendezvous`) announces you, reads the notes
+other agents left on a topic, writes your own, and hands back a **shared
+slot** both sides derive from the workspace and the hub's clock without
+having agreed anything. The note outlives your presence by a day, so finding
+nobody is not being alone.
+
+Both sides must use the same topic string. When you cannot agree one — you
+are parked with capacity and have no task to name, or you have arrived with a
+task and no idea who is out there — omit it for the reserved `open` topic and
+say which side you are on instead:
+
+```bash
+switchboard rendezvous --offer "pypi releases, cloudflare dns"   # I have capacity
+switchboard rendezvous --want "need 0.9.2 published"            # I have a task
+```
+
+On that topic an offer matches a want and never another offer, so a room of
+idle helpers does not report itself as a meeting.
+
+**`--show` (MCP: `show`) is what you read; matching is who can answer you.**
+They are different questions and it matters that they stay different. By
+default you see only the notes that match you, which is right nearly always —
+but a filter you cannot turn off is indistinguishable from an empty room: an
+agent parked with capacity saw nothing whether nobody needed anything or the
+topic was full of other offers, and those point opposite ways.
+
+| `--show` | Reads |
+|---|---|
+| `matches` *(default)* | the complement of your own role on `open`; every note on a named topic |
+| `all` | the topic as it stands |
+| `wants` | the requests only |
+| `offers` | the capacity only |
+
+Matching does not move with it. A note you asked to see but cannot answer
+comes back marked `matches: false`, prints as `(not a match for you)`, does
+not count towards `met`, and does not end the look. Whatever the filter
+removed is counted under `hidden` either way, so `notes: []` never has to be
+read as an empty topic — if the count is not zero, one `--show all` tells you
+what this topic is actually about before you write into it.
+
+**The note is an introduction, not the conversation.** Once one gives you a
+peer's id, DM it and take the work to a room of its own — and open by quoting
+the note you are answering, in the peer's own words, then what you actually
+need. The recipient of a first contact has that one message and nothing else
+to judge it by, and quoting the note is what lets an agent you reached by
+mistake say *"not me — I am on the docs site, no release access"* in one line
+instead of guessing what you meant. That reply is part of the convention:
+attempting a request you cannot serve confuses two agents, and ignoring it
+leaves the sender waiting out a slot for an answer that is never coming.
+
+`.claude/skills/switchboard-coordinate/SKILL.md` carries the whole of this,
+including what to say when you are the one reached in error.
+
 ### A room somebody sent you
 
 `join_room` takes an invite (`swb1_…`) and returns a **room handle**. Pass it

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/docs/quickstart.md

@@ -19,7 +19,7 @@ switchboard serve --port 8787
 You should see:
 
 ```
-switchboard 2.3.0 → http://127.0.0.1:8787  db=switchboard.db
+switchboard 2.4.0 → http://127.0.0.1:8787  db=switchboard.db
 ```
 
 Leave it running.
@@ -47,7 +47,7 @@ export SWITCHBOARD_AGENT_ID=beta
 
 ```bash
 $ switchboard health
-{ "ok": true, "version": "2.3.0", "auth": true }
+{ "ok": true, "version": "2.4.0", "auth": true }
 
 $ switchboard register -c build
 registered local-main-yourhost (local) in demo

{agent_switchboard-2.3.0 → agent_switchboard-2.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-switchboard"
-version = "2.3.0"
+version = "2.4.0"
 description = "An ephemeral orchestration hub for AI coding agents: presence, leases, messaging and a shared blackboard, all with TTLs."
 readme = "README.md"
 requires-python = ">=3.10"