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

{agent_switchboard-2.2.2 → agent_switchboard-2.3.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` · 9 item(s), 6 startable
+`hub-boundary` · 10 item(s), 7 startable
 
 `https://github.com/gald33/switchboard/issues/61` · `https://github.com/gald33/switchboard/issues/73` · `docs/model.md` · `docs/encryption.md`
 
@@ -67,6 +67,7 @@ under pressure.
 
 | item | status | priority |
 |---|---|---|
+| `a-drain-that-retries-forever-never-escalates` | ready | now |
 | `ci-workspace-is-public` | ready | now |
 | `stale-resolver-references` | ready | now |
 | `seal-agent-meta` | ready | next |
@@ -79,7 +80,7 @@ under pressure.
 
 ### 🟠 The first ten minutes, for somebody who has not read the docs
 
-`setup-and-first-run` · 19 item(s), 13 startable
+`setup-and-first-run` · 22 item(s), 16 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`
 
@@ -101,9 +102,12 @@ wrong says so.
 
 | item | status | priority |
 |---|---|---|
+| `first-contact-needs-a-key-it-cannot-have` | ready | now |
+| `inbox-consumes-what-it-cannot-open` | ready | now |
 | `automatic-session-checkpoints` | ready | next |
 | `connect-failure-message` | done | next |
 | `cross-key-rendezvous` | ready | next |
+| `discovery-is-uneven-and-delivery-is-unknowable` | ready | next |
 | `init-writes-rooms-file` | ready | next |
 | `known-rooms-address-book` | done | next |
 | `a-lobby-derived-from-the-key` | ready | — |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-switchboard
-Version: 2.2.2
+Version: 2.3.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
@@ -81,6 +81,29 @@ live exactly as long as the work does.
 That's the whole model. Direct messages aren't a fifth concept — a DM to agent
 `bob` is just a message on channel `@bob`.
 
+### A message is half an exchange
+
+Agents are turn-based. They run, they end, and something else starts them
+later. So an agent that sends a message is almost never launching a one-off —
+it sends because it needs something back, and the answer is due after its turn
+is over, into an inbox nothing is watching.
+
+`switchboard listen` is the other half — not a fifth primitive, but the way an
+agent stays reachable across the gap it is not awake for. It parks on the
+inbox and **exits the moment something arrives**, which is the one event a
+runner already reacts to: Claude Code re-invokes a session when a background
+process exits, so the reply *is* the wake — seconds after it lands, rather than
+at whatever check somebody scheduled.
+
+```bash
+switchboard dm reviewer-agent "0142 is mine — does that clash with yours?"
+switchboard listen --until forecast:p50    # as a background process, before the turn ends
+```
+
+`say`, `dm` and `whisper` report where each end stands — whether a listener is
+parked for you, and for the agent you sent to — so "sent" is never mistaken for
+"will be answered into something that is listening".
+
 ### Why leases expire
 
 This is the part worth dwelling on. A conventional "claim" — a row in a table,
@@ -306,12 +329,20 @@ Agents then get these as native tools:
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
 | `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 |
 
 `checkin` is the one that matters most in practice: a single tool call that
 keeps the agent alive, renews everything it holds, and hands back anything
 other agents said since last time.
 
+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`,
+`dm` and `whisper` return a `listener` field saying whether one is parked for
+each end of the message, so an agent finds out before its turn ends rather than
+after.
+
 See [`docs/claude-code.md`](docs/claude-code.md) for the full setup including a
 `SessionStart` hook that registers the agent automatically and a `Stop` hook
 that releases its leases.

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

@@ -43,6 +43,29 @@ live exactly as long as the work does.
 That's the whole model. Direct messages aren't a fifth concept — a DM to agent
 `bob` is just a message on channel `@bob`.
 
+### A message is half an exchange
+
+Agents are turn-based. They run, they end, and something else starts them
+later. So an agent that sends a message is almost never launching a one-off —
+it sends because it needs something back, and the answer is due after its turn
+is over, into an inbox nothing is watching.
+
+`switchboard listen` is the other half — not a fifth primitive, but the way an
+agent stays reachable across the gap it is not awake for. It parks on the
+inbox and **exits the moment something arrives**, which is the one event a
+runner already reacts to: Claude Code re-invokes a session when a background
+process exits, so the reply *is* the wake — seconds after it lands, rather than
+at whatever check somebody scheduled.
+
+```bash
+switchboard dm reviewer-agent "0142 is mine — does that clash with yours?"
+switchboard listen --until forecast:p50    # as a background process, before the turn ends
+```
+
+`say`, `dm` and `whisper` report where each end stands — whether a listener is
+parked for you, and for the agent you sent to — so "sent" is never mistaken for
+"will be answered into something that is listening".
+
 ### Why leases expire
 
 This is the part worth dwelling on. A conventional "claim" — a row in a table,
@@ -268,12 +291,20 @@ Agents then get these as native tools:
 | `say` / `dm` / `inbox` / `history` | channel and direct messaging |
 | `board_set` / `board_get` / `board_list` | shared scratch space |
 | `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 |
 
 `checkin` is the one that matters most in practice: a single tool call that
 keeps the agent alive, renews everything it holds, and hands back anything
 other agents said since last time.
 
+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`,
+`dm` and `whisper` return a `listener` field saying whether one is parked for
+each end of the message, so an agent finds out before its turn ends rather than
+after.
+
 See [`docs/claude-code.md`](docs/claude-code.md) for the full setup including a
 `SessionStart` hook that registers the agent automatically and a `Stop` hook
 that releases its leases.

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

@@ -151,22 +151,28 @@ cloud sessions, and in CI. Switchboard is how you coordinate with them.
   which is worth interrupting for in a way general channel traffic is not.
   On this CLI it is a line after `say` and `whisper` (and a field under
   `--json`), printed only when something is actually waiting.
-- **If you are ending a turn while still waiting on another agent**, read
+- **Before ending a turn in which you sent anything you need an answer to,
+  arm the listener.** A message here is the opening of a conversation, not a
+  one-off: you send because you need something back, and the answer arrives on
+  the other agent's schedule — after this turn has ended, into an inbox no
+  process is watching. Run `switchboard listen --until forecast:p50` as a
+  background process. It parks on your inbox and exits when something arrives,
+  and a runner that re-invokes a session when a background process exits —
+  Claude Code does — wakes you seconds after the message lands rather than at
+  the next scheduled check. `say`, `dm` and `whisper` tell you where you
+  stand: a `listener` field on the MCP results and a line on the CLI, saying
+  whether one is parked for you and for them. `--until` is when to give up and
+  come back empty; without one it parks indefinitely, which is a promise to be
+  reachable that nothing keeps. It peeks rather than drains, so still call
+  `inbox` yourself when you wake, and it exits on the first message, so arm it
+  again if you are still waiting. It takes the flags every command takes, so
+  `-w` or `--invite` parks it in another room for cross-repo work.
+- **If you cannot park one** — no background mechanism your runner tracks, or
+  a wait that outlives this session — read
   `.claude/skills/switchboard-coordinate/SKILL.md` for how to schedule a
-  check-in instead of leaving the wait unbounded — `unread_dms` only helps
+  check-in instead of leaving the wait unbounded. `unread_dms` only helps
   while you are still making tool calls, and nothing else will interrupt an
   idle session.
-- **If the thing you are waiting for is a message**, arm the listener before
-  the turn ends: run `switchboard listen --until forecast:p50` as a background
-  process. It parks on your inbox and exits when something arrives, and a
-  runner that re-invokes a session when a background process exits — Claude
-  Code does — wakes you seconds after the message lands rather than at the
-  next scheduled check. `--until` is when to give up and come back empty;
-  without one it parks indefinitely, which is a promise to be reachable that
-  nothing keeps. It peeks rather than drains, so still call `inbox` yourself
-  when you wake, and it exits on the first message, so arm it again if you are
-  still waiting. It takes the flags every command takes, so `-w` or `--invite`
-  parks it in another room for cross-repo work.
 - **Optionally, when a message precedes a stretch of heads-down work**, pass
   `execution_class` (a short label like "coding") and `effort`
   (`low`/`medium`/`high`) to `say`/`dm`/`checkin`/`inbox`. Your runtime turns
@@ -249,12 +255,19 @@ guarded hook degrades to a no-op.
 The `Stop` hook is a convenience, not a requirement — leases expire on their
 own. Releasing eagerly just frees the resource sooner.
 
-## 6. Optional: be woken by a message
+## 6. Be woken by a message
 
 Everything above assumes the session is awake. A message that lands after the
 turn ends is delivered to nobody: the session only reaches for its inbox when
 it is its turn, and nothing about a hub can make a stopped session run.
 
+That is not an edge case, which is why this section is not optional. An agent
+sends because it needs something back — a review, a verdict, a lease it was
+told to wait for — so most turns that send end mid-wait, and the answer is due
+after the turn is over. The listener is the piece that makes the second half of
+the exchange reachable. `say`, `dm` and `whisper` say where you stand on every
+send: whether a listener is parked for you, and for the agent you sent to.
+
 What *can* is the runner. Claude Code re-invokes a session when a background
 process exits, so a process that parks on the inbox and exits when something
 arrives turns a message into a wake. `init` installs one beside the hooks in
@@ -454,18 +467,87 @@ under exactly one key, because `claude --resume` refuses to choose between
 duplicates. Other direct messages the read consumed come back as `other`
 rather than being lost.
 
-Local → cloud → local is then three commands and no hub change: `session
-handoff` on the laptop, `session receive` in the cloud session followed by
-`claude --resume`, and the same pair back when the cloud side is done. The
-hub saw two sealed values it cannot name — the pointer's discriminator
-travels inside the sealed body and the message type stays `note`, so not
-even the row type says what moved.
+Local → cloud → local is three commands and no hub change: `session handoff`
+on the laptop, `session receive` in the cloud session followed by `claude
+--resume`, and the same pair back when the cloud side is done. The hub saw
+two sealed values it cannot name — the pointer's discriminator travels inside
+the sealed body and the message type stays `note`, so not even the row type
+says what moved.
+
+**One account, though — see below.** Cloud → local has been run end to end.
+The other direction was run and *failed*, for a reason that is not
+Switchboard's and not fixable here.
+
+### A session belongs to the account that made it
+
+A transcript can carry a `bridge-session` record naming the account that
+owned it. Restoring one under a different account installs and resumes
+normally and then comes back **empty**: Claude Code loads the file, sees the
+mismatch, and appends
+
+```json
+{"type": "history-suppression", "cause": "restored_owner_mismatch", "vetoedAgainstAccountUuid": "…"}
+```
+
+instead of replaying the conversation. Observed moving a bridged laptop
+session into a cloud container: 14.7 MB and 36 files arrived with a matching
+sha256, `claude --resume` bound the right id, and the conversation was not
+there.
+
+Nothing in the capsule causes this and nothing in it can prevent it — the
+bytes are carried and verified faithfully, and the refusal happens after
+Claude Code has already read them. `session resume` detects the record and
+says so rather than blaming the transport; re-running does not help, because
+the veto is a property of the transcript and the account.
+
+**Which sessions carry the marker (observed).** Not most of them. Of six
+transcripts compared on one machine — a plain `claude -p` session, a cloud
+session, three sessions Claude Code started itself, and the bridged one — only
+the bridged session had a `bridge-session` record at all. The cloud session
+did not, and it is a remote session with its own `cse_…` id, so this is not
+local versus cloud: the marker rides on the *bridge*, and it names the account
+that owns the session on the other end of it.
+
+So the boundary a handoff cannot cross is an *account*, and only a session
+bridged under one carries the evidence. An ordinary session moves between your
+own environments as the matrix says. A bridged one moves its bytes and not its
+conversation unless the destination is signed in as the same account —
+including where "the same person" is signed into two accounts, which is what
+produced the observation above.
 
 `switchboard session export -o FILE` and `switchboard session import FILE`
 are the two halves with no hub between them: a capsule file, created `0600`
 because it is as private as the transcript it carries, that you move however
 you like.
 
+### Checkpointing, for the session that does not end politely
+
+A handoff saves a session that ends *deliberately*. The first real transfer
+survived only because the cloud agent chose to publish before it finished; a
+container that dies takes its context with it, and an explicit command cannot
+help a session that never got to run one.
+
+So `switchboard init` asks, once, whether a session should checkpoint itself
+when it ends. Say yes and the stop hook publishes the transcript as a handoff
+addressed to nobody: sealed to the room, expiring on its own, collectable by
+anyone holding the key — which in practice means your own other machines.
+Publishing happens after the hook releases this agent's leases, so the capsule
+records an agent that holds nothing, which is true once the session is over,
+and it ends in `|| true` because a session finishing must never fail on an
+unreachable hub.
+
+It is asked rather than assumed because it is real traffic and real storage: a
+transcript can be megabytes and every session end would publish one. The
+default is no, a non-interactive run leaves it off, and the answer is baked
+into the hook script rather than read at run time, since a hook runs as a plain
+shell and never sees `.mcp.json`'s environment.
+
+Collecting stays explicit for now. `switchboard session receive <id>` takes a
+checkpoint by id, and which one a *starting* session should collect
+automatically is an open question — see the `automatic-session-checkpoints`
+roadmap item, which would rather leave it undecided than guess wrong about
+whose conversation lands on your disk.
+
 ### What a handoff cannot reach, and what to send instead
 
 A handoff lands a transcript on a filesystem. That covers every environment

{agent_switchboard-2.2.2 → agent_switchboard-2.3.0}/docs/codex-cli.md

@@ -73,22 +73,28 @@ sessions, and in CI. Switchboard is how you coordinate with them.
   which is worth interrupting for in a way general channel traffic is not.
   On this CLI it is a line after `say` and `whisper` (and a field under
   `--json`), printed only when something is actually waiting.
-- **If you are ending a turn while still waiting on another agent**, read
+- **Before ending a turn in which you sent anything you need an answer to,
+  arm the listener.** A message here is the opening of a conversation, not a
+  one-off: you send because you need something back, and the answer arrives on
+  the other agent's schedule — after this turn has ended, into an inbox no
+  process is watching. Run `switchboard listen --until forecast:p50` as a
+  background process. It parks on your inbox and exits when something arrives,
+  and a runner that re-invokes a session when a background process exits —
+  Claude Code does — wakes you seconds after the message lands rather than at
+  the next scheduled check. `say`, `dm` and `whisper` tell you where you
+  stand: a `listener` field on the MCP results and a line on the CLI, saying
+  whether one is parked for you and for them. `--until` is when to give up and
+  come back empty; without one it parks indefinitely, which is a promise to be
+  reachable that nothing keeps. It peeks rather than drains, so still call
+  `inbox` yourself when you wake, and it exits on the first message, so arm it
+  again if you are still waiting. It takes the flags every command takes, so
+  `-w` or `--invite` parks it in another room for cross-repo work.
+- **If you cannot park one** — no background mechanism your runner tracks, or
+  a wait that outlives this session — read
   `.claude/skills/switchboard-coordinate/SKILL.md` for how to schedule a
-  check-in instead of leaving the wait unbounded — `unread_dms` only helps
+  check-in instead of leaving the wait unbounded. `unread_dms` only helps
   while you are still making tool calls, and nothing else will interrupt an
   idle session.
-- **If the thing you are waiting for is a message**, arm the listener before
-  the turn ends: run `switchboard listen --until forecast:p50` as a background
-  process. It parks on your inbox and exits when something arrives, and a
-  runner that re-invokes a session when a background process exits — Claude
-  Code does — wakes you seconds after the message lands rather than at the
-  next scheduled check. `--until` is when to give up and come back empty;
-  without one it parks indefinitely, which is a promise to be reachable that
-  nothing keeps. It peeks rather than drains, so still call `inbox` yourself
-  when you wake, and it exits on the first message, so arm it again if you are
-  still waiting. It takes the flags every command takes, so `-w` or `--invite`
-  parks it in another room for cross-repo work.
 - **Optionally, when a message precedes a stretch of heads-down work**, pass
   `execution_class` (a short label like "coding") and `effort`
   (`low`/`medium`/`high`) to `say`/`dm`/`checkin`/`inbox`. Your runtime turns

{agent_switchboard-2.2.2 → agent_switchboard-2.3.0}/docs/concepts.md

@@ -123,6 +123,22 @@ Each message carries a monotonically increasing `seq` alongside its cursor
 position, so an agent that wants to defend against acting on the same message
 twice — after a retried call, say — can key on `seq` rather than on content.
 
+### Sending is half of it
+
+Long-polling covers a wait inside a turn. Most waits are not: an agent sends
+because it needs something back, and the answer is due after the sender's turn
+has ended — into a cursor position nothing is advancing.
+
+`switchboard listen` is the half that makes the rest of the exchange reachable.
+It parks on the inbox and exits the moment something arrives, which is the one
+event a runner already reacts to, so the reply itself becomes the wake. It
+peeks rather than drains, so the woken session still reads its `inbox` and the
+cursor stays the session's to advance. While parked it heartbeats a
+`listener/<agent-id>` entry on the blackboard, which is why `say`, `dm` and
+`whisper` can tell each sender whether an answer will reach anybody: parked is
+a live process saying so now, and it expires on its own when that process
+stops. See [claude-code.md](claude-code.md#6-be-woken-by-a-message).
+
 ## Blackboard
 
 A key/value space for things too big to be a message and too transient to be a

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

@@ -19,7 +19,7 @@ switchboard serve --port 8787
 You should see:
 
 ```
-switchboard 2.2.2 → http://127.0.0.1:8787  db=switchboard.db
+switchboard 2.3.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.2.2", "auth": true }
+{ "ok": true, "version": "2.3.0", "auth": true }
 
 $ switchboard register -c build
 registered local-main-yourhost (local) in demo

{agent_switchboard-2.2.2 → agent_switchboard-2.3.0}/extras/session-capsule/README.md

@@ -47,6 +47,24 @@ No transcript was modified. No path translation was needed. The destination
 needs neither the repo path nor the repo contents to *resume the conversation*;
 it needs them only for whatever the conversation does next.
 
+**One boundary this matrix never crossed (observed later, in production).**
+Every case above moved a session owned by one account — between config dirs,
+between directories, between machines, but never between *accounts*. A
+transcript can carry a `bridge-session` record naming its owner, and restoring
+one under a different account installs, resumes under the right id, and comes
+back empty; Claude Code appends
+`{"type":"history-suppression","cause":"restored_owner_mismatch"}` rather than
+replaying it. So "portable as a single opaque file" holds within an account
+and not across one, and the row above that reads "the real, live 537 KB
+session that ran this investigation" passed because it was *our own*.
+
+Comparing six transcripts on one machine afterwards (**observed**): only a
+bridged session carries the record. A plain `claude -p` session, a cloud
+session with its own `cse_…` id, and three sessions Claude Code started itself
+had no owner field anywhere. So the marker is not a property of every session
+and not of cloud sessions — it rides on the bridge, and the account it names
+is the one on the far side.
+
 ## 1. Where Claude Code stores sessions (observed)
 
 ```

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-switchboard"
-version = "2.2.2"
+version = "2.3.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"