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

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/ARCS.md

@@ -79,7 +79,7 @@ under pressure.
 
 ### 🟠 The first ten minutes, for somebody who has not read the docs
 
-`setup-and-first-run` · 18 item(s), 12 startable
+`setup-and-first-run` · 19 item(s), 13 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,6 +101,7 @@ wrong says so.
 
 | item | status | priority |
 |---|---|---|
+| `automatic-session-checkpoints` | ready | next |
 | `connect-failure-message` | done | next |
 | `cross-key-rendezvous` | ready | next |
 | `init-writes-rooms-file` | ready | next |

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-switchboard
-Version: 2.2.0
+Version: 2.2.2
 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

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/docs/adaptive-timing.md

@@ -48,7 +48,7 @@ is never a commitment, and no agent is required to obey another's forecast.
   machines. It is shared by every repo on that machine, but every read and
   write is keyed by `(agent_id, workspace)` — and `workspace` defaults to
   the git remote's org/repo — so history never bleeds from one repo into
-  another's forecasts. `agent_id` derives from kind/branch/hostname, so the
+  another's forecasts. `agent_id` derives from kind/hostname/session, so the
   same person on two laptops builds two independent histories that converge
   separately. All of that is deliberate: the premise is that timing is
   local and personal, and a shared or committed history would be neither.

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

@@ -466,6 +466,103 @@ 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.
 
+### What a handoff cannot reach, and what to send instead
+
+A handoff lands a transcript on a filesystem. That covers every environment
+where a session can run a shell — your laptop, another machine, a cloud
+container — because the receiving side collects the capsule and
+`claude --resume` finds it. The first real handoff went cloud-container to
+laptop that way.
+
+It does not reach a session running in Claude's own cloud, and it is worth
+saying why rather than leaving somebody to discover it. Checked against CLI
+2.1.259 on 2026-09-05: `--cloud <session_id>` **attaches** to a cloud session
+that already exists, `--environment ccpool_…` creates a **new** one on a
+self-hosted pool, and neither takes a transcript. The `/move-to-cloud` and
+`/teleport` commands exist in the binary but are registered only for an
+interactive terminal, and the teleport path seeds a fresh session with a
+written summary rather than the conversation. There is no endpoint anywhere
+that accepts a transcript, so a conversation cannot be uploaded to become a
+cloud session, and nothing in this repo pretends otherwise.
+
+Two things do work in that direction, and between them they cover most of
+what people want from it.
+
+**Consult it.** A cloud container can run `session receive` like anything
+else. The transcript lands on its disk and the session *reads* it — greps for
+the decision it needs, opens the twenty records that matter — instead of
+resuming it. This is not a workaround for the missing upload: a 4.5 MB
+transcript could not be injected into a context window even if an endpoint
+existed, and consulting on demand is the only shape that scales.
+
+**Send the shape of it.** `switchboard session brief <id>` prints what a
+session was for, read off the record rather than retold by a model: what the
+human asked, which files were touched, how it worked. On the first real
+handoff that is 960 bytes out of 4.5 MB, and it fits in a message you can
+paste anywhere — including a cloud session in a browser that no capsule can
+reach. The filtering is the substance: Claude Code writes tool results, hook
+output and notifications as `user` records too, so 285 user turns there
+contain 14 things a human actually typed.
+
+### If you work in the desktop app
+
+Installing the transcript is the whole job for a CLI user and half of one for
+everybody else. The desktop app keeps its own list of sessions beside the
+transcripts, so a conversation whose transcript is installed but whose record
+is not exists on disk and is invisible in the app — which is exactly what
+happened the first time a session was handed from a cloud agent to a laptop:
+it resumed perfectly on the command line and could not be found in the app the
+recipient actually used.
+
+So `switchboard init` asks, once, on a machine that runs the app: should a
+session handed to you also appear in its sidebar? Say yes and `receive` writes
+the record too. The question is asked at setup rather than per handoff for two
+reasons — it writes into another program's store, which is a thing to agree to
+deliberately, and the account and project the row is filed under are ids that
+app assigns, discoverable only where it runs. A cloud runner has neither, so
+the step is silently skipped there.
+
+`switchboard session register <id>` does it for a session already installed,
+and `session unregister <id>` is the undo. Prefer that over deleting the row
+inside the app: in-app delete and archive both write a release marker next to
+the transcript which the CLI acts on, while unregister removes only the record.
+
+Two things worth knowing. The app reads its store at launch, so a registered
+session appears after the next restart rather than immediately. And this is an
+undocumented format belonging to another program: `switchboard.desktop` says
+which app version it was verified against, keeps every detail in that one
+module, and answers "not here" rather than guessing when the shape is not what
+it expects.
+
+### What travels, and what a reader can take out
+
+The subagent transcripts in the `<id>/` sidecar travel by default, and that
+is the trade worth naming because it is not the obvious one. They are most
+of a capsule's bytes — three quarters of it is normal — and none of its
+resume: `claude --resume` reads the main transcript alone, so the sidecar
+costs the receiver no context at cold start. What it buys is retrievability.
+A subagent's transcript is finished work, often millions of tokens of it,
+that the receiving session can go and read *if it needs to* rather than
+re-derive at model prices. Bytes on a board with a ten-minute TTL are the
+cheap side of that trade, so the default is on.
+
+`--no-subagents` (`no_subagents` on `session_handoff`) drops them, for a slow
+link or a receiver that only needs the conversation continued. The capsule
+records that it did, as `omitted_subagent_files`, because a session that
+never spawned a subagent and one whose subagents were left behind both
+arrive as a single file, and a receiver deciding whether to ask again needs
+to tell those apart.
+
+A capsule can also be collected with no Switchboard on the machine at all.
+The [viewer](../extras/viewer/) already holds the plaintext — it fetched the
+board entry and opened it with the room key, which is why a sealed value is
+legible there — so a board entry it could open offers a **save** button that
+writes the value out as a file. Feed that file to `switchboard session
+import FILE` wherever the tooling *is* installed. It asks the hub for
+nothing extra, and it is the one path to a handoff for a human with a
+browser and no checkout. Where the page could not open a value it offers
+nothing: a file of envelope bytes would look like the value and is not.
+
 ### What is trusted, and what is not
 
 A transcript is instructions. Whoever resumes it runs a conversation

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

@@ -43,20 +43,23 @@ An agent registers itself (id, name, kind, branch, current task) and then
 heartbeats. If it stops heartbeating, it disappears from the roster within its
 TTL — two minutes by default.
 
-The agent id is inferred from `kind`, git branch and hostname, so a session
-that restarts on the same branch reclaims its own identity rather than
-appearing as a stranger. Override it with `SWITCHBOARD_AGENT_ID` when you want
-something specific.
+The agent id is inferred from `kind`, hostname and a hash of the session id,
+so a session that resumes reclaims its own identity — its leases, its read
+cursor — rather than appearing as a stranger. Two sessions on one machine get
+different ids, because the session is part of the derivation. Override it with
+`SWITCHBOARD_AGENT_ID` when you want something specific.
 
 `kind` is auto-detected as `ci` (in GitHub Actions), `cloud` (in a remote
 Claude Code session or a Codespace) or `local`.
 
-Because the inferred id has no process or session component, two sessions
-that share `kind`, branch and hostname — two terminals on the same checkout,
-say — collide on the same agent id. They are indistinguishable to the hub:
-same presence row, same lease ownership, same message cursor. If you run
-more than one session against the same branch and host, set
-`SWITCHBOARD_AGENT_ID` explicitly for at least one of them.
+**The branch is deliberately not part of the id.** It is registered as its own
+field, which is what `dm` resolves a typed branch name against — so it says
+where an agent is *now* and follows it across a checkout, while the id stays
+put. An id has to outlive the session's whole life: it is what the signer
+socket is keyed on, what the roster stores a public key against, what holds a
+lease and what owns a read cursor. Folding the branch in meant that checking
+one out — the most ordinary thing an agent does — minted a second identity and
+orphaned all four.
 
 ## Leases
 

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

@@ -19,7 +19,7 @@ switchboard serve --port 8787
 You should see:
 
 ```
-switchboard 2.2.0 → http://127.0.0.1:8787  db=switchboard.db
+switchboard 2.2.2 → http://127.0.0.1:8787  db=switchboard.db
 ```
 
 Leave it running.
@@ -35,7 +35,7 @@ export SWITCHBOARD_WORKSPACE=demo
 ```
 
 In the second terminal, give the agent a distinct identity so you can tell them
-apart (normally this is inferred from branch and hostname):
+apart (normally this is inferred from your host and session):
 
 ```bash
 export SWITCHBOARD_AGENT_ID=beta
@@ -47,7 +47,7 @@ export SWITCHBOARD_AGENT_ID=beta
 
 ```bash
 $ switchboard health
-{ "ok": true, "version": "2.2.0", "auth": true }
+{ "ok": true, "version": "2.2.2", "auth": true }
 
 $ switchboard register -c build
 registered local-main-yourhost (local) in demo

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/docs/upgrading.md

@@ -3,6 +3,62 @@
 What changes for you between releases that are not backwards compatible, in
 the order you will hit them. Everything not listed here kept its behaviour.
 
+## 2.2.0 → 2.2.1
+
+**Your agent ids change once.** An id was `kind-branch-host-session`; the
+branch is gone from it, so it is now `kind-host-session`. The branch was in
+there from when it was the only thing telling two sessions apart — the
+session suffix took that job and left the branch behind as decoration, and
+decoration with teeth: an id is what the signer socket is keyed on, what the
+roster stores a public key against, what holds a lease and what owns a read
+cursor. Checking out a branch, the most ordinary thing an agent does, minted
+a second identity and orphaned all four.
+
+Nothing to do about it. On first announce after upgrading, an agent appears
+under its new id; the row under the old one stops being refreshed and lapses
+on the presence TTL like any other. **Leases and read cursors held by the old
+id are not transferred** — a lease expires on its own TTL (15 minutes by
+default) and a cursor's cost is one repeated read. If you cannot wait for a
+lease to lapse, release it before upgrading, or pin `SWITCHBOARD_AGENT_ID`
+across the upgrade to keep the id you had.
+
+Branch-based lookup is unaffected: `dm` and the other recipient resolvers
+match the roster's own `branch` field, registered on every announce, which
+follows an agent across a checkout in a way an id baked at startup never
+did. A name still says the branch if you registered it that way.
+
+`client.identity_drift_warning` is now `client.rootless_warning`, and warns
+about a different thing. It existed for this bug's directory half — outside a
+checkout the branch read as `detached` and the id moved — which no longer
+happens. What still drifts outside a checkout is the *workspace*, derived
+from the directory when there is no remote to read, which puts the agent in a
+different room entirely; that is what the renamed function now says.
+
+Also fixed: an option value beginning with `-` no longer has to be escaped
+by hand. `switchboard session receive --from <agent-id>` and `board list
+--prefix <key>` died on "expected one argument" for about one id in
+sixty-six, because ids and board keys are base64url and argparse will not
+read a dash-leading token as an option's value. Both now work as typed —
+the same repair `dm -yLAoQ63…` already had for positionals, extended to the
+other half of the problem.
+
+Additive in the same release: `--no-subagents` on `session export`,
+`handoff` and `publish` (`no_subagents` on `session_handoff`) leaves the
+subagent transcripts out of a capsule, and the viewer can save an opened
+board value to a file. Neither changes an existing default.
+
+## 2.2.1 → 2.2.2
+
+Additive. `switchboard session brief <id>` prints what a session was for —
+the human's instructions, the files touched, the tools used — read off the
+transcript rather than retold by a model. It exists for the place a capsule
+cannot reach: a session running in Claude's own cloud, which accepts no
+transcript through any endpoint. On a 4.5 MB transcript the brief is under a
+kilobyte, so it fits in a message you can paste anywhere.
+
+`docs/claude-code.md` now states plainly what a handoff can and cannot reach,
+checked against Claude Code 2.1.259. Nothing that worked in 2.2.1 changed.
+
 ## 2.1.0 → 2.2.0
 
 Additive. A whole Claude Code session can be moved between environments

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/docs/viewer.md

@@ -104,6 +104,16 @@ the rest: the whole key, who wrote it and when, and a value that keeps its own
 line breaks instead of being folded to fit. The sidebar itself now widens with
 the screen rather than staying 340px on every one.
 
+An opened entry also offers **save**, which writes the value out as a file
+named after its key. The page is already holding the plaintext — it fetched
+the entry and opened it with the room key, which is the whole reason a sealed
+value is legible here — so this asks the hub for nothing and needs no CLI. It
+is how a person with a browser and no checkout collects a
+[session capsule](claude-code.md#7-hand-a-whole-session-to-another-environment)
+and feeds it to `switchboard session import` somewhere else. A value this page
+could not open offers no button: a file of envelope bytes would look like the
+value and is not.
+
 Each of the three side panels says how much is inside it and folds away, and
 what you fold stays folded. On a window too narrow for two columns they stop
 being a stack under the conversation — where, the talking being long and never

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/extras/viewer/pyproject.toml

@@ -19,7 +19,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "switchboard-viewer"
-version = "0.10.0"
+version = "0.11.0"
 description = "A read-only page showing your Switchboard rooms to a human: who is awake, what is claimed, and the conversation as it happens."
 readme = "README.md"
 requires-python = ">=3.10"

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/extras/viewer/switchboard_viewer/web/index.html

@@ -139,6 +139,13 @@
   .detail .meta { color: var(--dim); font-size: 12px; margin: 4px 0 14px;
                   display: flex; flex-wrap: wrap; gap: 4px 12px; }
   .detail .body, .detail pre { font-size: 13px; }
+  /* Quiet until wanted: a board value is usually read, not taken, and a
+     download button competing with the value would say otherwise. */
+  .detail .meta .save { border: 1px solid var(--line); border-radius: 6px;
+                        background: transparent; color: var(--dim); font: inherit;
+                        font-size: 12px; padding: 0 8px; cursor: pointer; }
+  .detail .meta .save:hover, .detail .meta .save:focus-visible {
+                        color: var(--accent); border-color: var(--accent); }
   .detail .nothing { color: var(--dim); font-size: 13px; }
   /* A key is the row's own text, so it reads as text — and as something that
      does something only where it does something. */

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/extras/viewer/switchboard_viewer/web/render.js

@@ -513,6 +513,8 @@ function drawDetail(s) {
       <span>${who(entry.updated_by)}</span>
       <span>${stamp(entry.updated_at)}</span>
       <span>expires in ${countdown(entry.expires_in, s.generated_at)}</span>
+      ${readable(entry) ? `<button class="save" type="button"
+        data-save="${esc(entry.key)}">save</button>` : ""}
     </div>
     ${bodyHtml(entry.value)}`;
   if (pane.dataset.html !== html) {
@@ -521,6 +523,49 @@ function drawDetail(s) {
   }
 }
 
+/** Whether this page holds the entry's plaintext at all.
+ *
+ *  A value that could not be opened arrives as `null` — the builder drops the
+ *  envelope rather than let ciphertext render as content — and that is the
+ *  condition to check, not `sealed`, which only says whether the *key* stayed
+ *  a blinded token. Without a room key nothing is unblinded, so `sealed` is
+ *  false for every entry in a room this page cannot read: exactly the rooms
+ *  where offering to save one would write out a file that is not the value.
+ */
+function readable(entry) {
+  return Boolean(entry) && entry.value !== null && entry.value !== undefined;
+}
+
+/** Hand the reader the value they are already looking at, as a file.
+ *
+ *  The page has the plaintext: it fetched the entry and opened it with the
+ *  room key, which is the whole reason a sealed value is legible here at all.
+ *  Writing it out asks the hub for nothing and needs no checkout, no CLI and
+ *  no agent — which is the point. A session capsule saved from here goes
+ *  straight into `switchboard session import`, so a human with a browser can
+ *  collect a handoff that no tooling on their machine could.
+ *
+ *  Named after the key so the file says what it is, and `.json` when the
+ *  value is structured, because everything worth saving from a board is.
+ */
+function saveEntry(key) {
+  const entry = (last?.board || []).find((e) => e.key === key);
+  if (!readable(entry)) return;
+  const structured = typeof entry.value !== "string";
+  const text = structured ? JSON.stringify(entry.value, null, 2) : entry.value;
+  const name = `${key.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "")
+                 || "board-entry"}${structured ? ".json" : ".txt"}`;
+  const url = URL.createObjectURL(
+    new Blob([text], { type: structured ? "application/json" : "text/plain" }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = name;
+  a.click();
+  // Same turn would race the click on some browsers; the next one is safe and
+  // still prompt enough that nothing accumulates.
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
 export function render(s, { onRoom, onClose } = {}) {
   last = s;
   if (onRoom || onClose) handlers = { onRoom, onClose };
@@ -784,6 +829,11 @@ export function render(s, { onRoom, onClose } = {}) {
         scopeChanged();
         return;
       }
+      const save = e.target.closest("[data-save]");
+      if (save) {
+        saveEntry(save.dataset.save);
+        return;
+      }
       const entry = e.target.closest("[data-board]");
       if (entry) {
         opened = entry.dataset.board;

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

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

{agent_switchboard-2.2.0 → agent_switchboard-2.2.2}/roadmap/ROADMAP.md

@@ -17,8 +17,12 @@ Claim before starting: `roadmap claim <key>`
   - ↔ related: **`init-writes-rooms-file`** — Both decide where a room identifier is allowed to live. This one is about an identifier that should not have been committed; that one proposes that `init` start committing a rooms record carrying a workspace token by default. Settle the rule here first, or `init` ships the same mistake as the default for every adopter.
   - ↔ related: **`read-only-rooms`** — Half of that item — anyone who can read the repo can post as CI — is closed by minting the CI room write-protected: the identifier can stay committed, since knowing it no longer lets anyone write into it. The other half, sealing what CI announces, is unchanged.
 - `now` **`stale-resolver-references`** — Delete the comments describing auth machinery that no longer exists
+- `next` **`automatic-session-checkpoints`** — A session that ends anywhere is collectable everywhere, without anyone running a command
+  - ↔ related: **`cross-key-rendezvous`** — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
+  - ↔ related: **`selective-wake-for-the-listener`** — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
 - `next` **`cross-key-rendezvous`** — Two agents that share no key have no room to meet in, and a human had to carry the coordinates
   - ↔ related: **`a-lobby-derived-from-the-key`** — That one made the lobby unguessable by deriving it from the key, deliberately rejecting a well-known room. This is the cost of that decision, observed: holders of different keys have no lobby in common. Read it first; the fix here keeps its rejection and works around it, rather than reopening it.
+  - ↔ related: **`automatic-session-checkpoints`** — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
   - ↔ related: **`known-rooms-address-book`** — That one gives a project a room strangers can find. This is what an agent does with rooms once it knows them: a published meeting room, an invite it was handed, a side room it minted, its repo rooms — one list, swept when searching, chosen from when parking. Do that one first; this consumes what it publishes.
   - ↔ related: **`selective-wake-for-the-listener`** — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
 - `next` **`init-writes-rooms-file`** — Make init produce the rooms record the model says is authoritative
@@ -60,6 +64,7 @@ Claim before starting: `roadmap claim <key>`
   - ↔ related: **`every-silent-failure-looks-like-a-quiet-room`** — The symptom when this fires is a 401 on the published credential, which two agents spent a day mis-attributing — first to a stale client, then to a perimeter that had moved. Read that item for why a wrong credential is hard to tell from a quiet room.
 - **`selective-wake-for-the-listener`** — Wake the listener on what matters, and on the time it promised, not on every message
   - ↔ related: **`a-lobby-derived-from-the-key`** — What makes a lobby worth having rather than merely tidy: an agent parked with `listen` is visible on a roster, so a lobby is a place peers can actually be found waiting rather than a room that is empty whenever nobody is mid-turn.
+  - ↔ related: **`automatic-session-checkpoints`** — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
   - ↔ related: **`cross-key-rendezvous`** — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
   - ↔ related: **`every-silent-failure-looks-like-a-quiet-room`** — Cause 8 below is a defect in what that item builds on — a parked listener watches the inbox of the id it started under, and a `git checkout` re-derives that id without telling either side. The fix belongs in `listen`, not here.
   - ↔ related: **`known-rooms-address-book`** — Same primitive, other axis. That one is about which *messages* wake a parked listener; this is about which *rooms* it is parked in, and why it need not be all of them.
@@ -110,6 +115,7 @@ _Nothing blocked._
 graph TD
   a_lobby_derived_from_the_key["Give every key a lobby, so agents that share one can find each other without naming a room"]
   abuse_control_after_authorization["Replace the abuse control that per-token authorization used to provide"]
+  automatic_session_checkpoints["A session that ends anywhere is collectable everywhere, without anyone running a command"]
   board_ttl_ceiling["Decide whether a board value has earned seven times a lease's lifetime"]
   ci_workspace_is_public["Stop publishing the one room identifier that was never meant to be guessable"]
   clients_that_cannot_post["Decide what a client that cannot hold a secret or issue arbitrary HTTP gets"]
@@ -144,6 +150,8 @@ graph TD
   a_lobby_derived_from_the_key -.- one_resolved_context_across_surfaces
   a_lobby_derived_from_the_key -.- selective_wake_for_the_listener
   abuse_control_after_authorization -.- ci_workspace_is_public
+  automatic_session_checkpoints -.- cross_key_rendezvous
+  automatic_session_checkpoints -.- selective_wake_for_the_listener
   board_ttl_ceiling -.- ttl_clamped_silently
   ci_workspace_is_public -.- init_writes_rooms_file
   ci_workspace_is_public -.- read_only_rooms
@@ -282,6 +290,95 @@ graph TD
 
 </details>
 
+### `automatic-session-checkpoints`
+
+- **title:** A session that ends anywhere is collectable everywhere, without anyone running a command
+- **status:** ready
+- **arc:** setup-and-first-run
+- **priority:** next
+- **related to** (not a dependency — both are startable):
+  - `cross-key-rendezvous` — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
+  - `selective-wake-for-the-listener` — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
+- **refs:**
+  - `src/switchboard/handoff.py`
+  - `src/switchboard/claude_session.py`
+  - `docs/claude-code.md`
+  - `https://github.com/gald33/switchboard/pull/229`
+
+<details><summary>evidence</summary>
+
+> **Inferred from a design conversation on 2026-09-05, after the first real
+> handoff the night before.** Nothing is broken; the mechanism works. What this
+> item records is what the working mechanism still asks of a human, and one
+> fragility that only shows up when something goes wrong.
+>
+> **The question that started it: how does Cursor move sessions between cloud
+> and local so smoothly, and can we?** Reading Cursor's own store on a machine
+> that runs it answers the first half. Its `conversations` table tags each row
+> with a `source` — 496 `local` against 47 `cloud-cache` on the machine
+> inspected — the cloud ones carry a server-side `scope` hash the local ones
+> lack, the table has `root_fingerprint` and `cache_fingerprint` columns, and a
+> `conversation_search_reconciliation` table holds a sync `cursor`. That is a
+> client cache over a server-authoritative store. Cursor does not move a
+> session between cloud and local; both ends are clients of one record its
+> servers hold, so there is nothing to move.
+>
+> **That is exactly the trade Switchboard must not make.** Copying it means the
+> hub storing transcripts it currently cannot read, which is the single
+> property the whole design exists to protect (`docs/model.md`). The local-first
+> choice is what let a session cross from a cloud container to a laptop on
+> 2026-09-04 between two agents sharing no account, sealed with a key the hub
+> never saw. A cache-and-sync design cannot do that, because the server has to
+> hold the conversation in order to synchronise it.
+>
+> **So the achievable version of "seamless" is not shared storage — it is that
+> nobody types a command.** A Cursor user does not experience syncing; they
+> experience "it was there". That experience needs the handoff to happen at the
+> boundaries automatically, and every part is already built:
+>
+> - `session publish` with no recipient is already a **checkpoint** — the
+>   capsule goes up sealed, addressed to nobody, collectable by anyone holding
+>   the room's key, which in practice is your own other machines
+>   (`handoff.py`).
+> - `init` already installs `SessionStart` and `Stop` hooks
+>   (`cli.py`, `_session_start_cmd` / `_stop_cmd`).
+> - `session receive` already takes `--wait`.
+>
+> Wiring them is the work: checkpoint on `Stop` and on going idle, collect on
+> `SessionStart`.
+>
+> **And it closes a fragility, which is the stronger half of the case.** A
+> handoff is explicit today, so a session that dies unexpectedly leaves nothing
+> behind — the 2026-09-04 transfer survived only because the cloud agent chose
+> to publish before it finished. Cursor survives that case because the server
+> already holds the conversation. Periodic self-checkpointing is how a
+> local-first design gets the same durability without giving anything away: the
+> last checkpoint is always collectable and expires on its own, so nothing
+> accumulates on the hub.
+>
+> **The open question, and the reason this is an item rather than a patch.**
+> Addressing. When several sessions have checkpointed, a starting session must
+> not collect all of them, and "the newest" is not obviously right either.
+> `--from` and sender verification are the raw material; the rule is not
+> decided. Most likely: the most recent checkpoint for **this repo** from **this
+> account**, with everything else needing to be asked for by id. Settle it
+> together with `cross-key-rendezvous`, which has the same shape of question.
+>
+> **What this must not promise, and the docs should say so rather than let
+> somebody find out.** Two live sessions cannot edit one conversation: without
+> an authority to reconcile against, a handoff is a baton and not a mirror.
+> Continuity is only as good as the checkpoint interval. And a transcript is
+> large — the first real one was 19.8 MB across 175 files — so checkpointing
+> every turn is not free, which argues for idle and end-of-session rather than
+> continuous.
+>
+> **Done when** a session that ends on one machine is collectable on another
+> with nobody running `handoff` or `receive`, when a session killed without
+> warning still leaves a collectable checkpoint, and when the addressing rule is
+> written down and tested rather than left to whoever calls `receive` first.
+
+</details>
+
 ### `board-ttl-ceiling`
 
 - **title:** Decide whether a board value has earned seven times a lease's lifetime
@@ -484,6 +581,7 @@ graph TD
 - **priority:** next
 - **related to** (not a dependency — both are startable):
   - `a-lobby-derived-from-the-key` — That one made the lobby unguessable by deriving it from the key, deliberately rejecting a well-known room. This is the cost of that decision, observed: holders of different keys have no lobby in common. Read it first; the fix here keeps its rejection and works around it, rather than reopening it.
+  - `automatic-session-checkpoints` — Shares the addressing problem from the other end. That one asks how a stranger finds you; this one asks which of several checkpoints is the one you meant. Both resolve to "the tool decides, the agent does not choose", so settle the rule in one place rather than twice.
   - `known-rooms-address-book` — That one gives a project a room strangers can find. This is what an agent does with rooms once it knows them: a published meeting room, an invite it was handed, a side room it minted, its repo rooms — one list, swept when searching, chosen from when parking. Do that one first; this consumes what it publishes.
   - `selective-wake-for-the-listener` — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
 - **refs:**
@@ -1744,6 +1842,7 @@ graph TD
 - **arc:** setup-and-first-run
 - **related to** (not a dependency — both are startable):
   - `a-lobby-derived-from-the-key` — What makes a lobby worth having rather than merely tidy: an agent parked with `listen` is visible on a roster, so a lobby is a place peers can actually be found waiting rather than a room that is empty whenever nobody is mid-turn.
+  - `automatic-session-checkpoints` — Both are about a session being reachable across a gap the agent is not awake for. That one wakes a parked session when a message lands; this one makes sure the session's own context survives the gap at all. Read that one first for the hook and background-process conventions this must follow.
   - `cross-key-rendezvous` — The other half of the same evening: a turn-based session that cannot park a listener returns on shared slots instead, which worked. Meeting failed one layer up — there was no shared room for the slots to be in.
   - `every-silent-failure-looks-like-a-quiet-room` — Cause 8 below is a defect in what that item builds on — a parked listener watches the inbox of the id it started under, and a `git checkout` re-derives that id without telling either side. The fix belongs in `listen`, not here.
   - `known-rooms-address-book` — Same primitive, other axis. That one is about which *messages* wake a parked listener; this is about which *rooms* it is parked in, and why it need not be all of them.

agent_switchboard-2.2.2/roadmap/items/automatic-session-checkpoints.yaml

@@ -0,0 +1,92 @@
+id: automatic-session-checkpoints
+title: A session that ends anywhere is collectable everywhere, without anyone running a command
+status: ready
+arc: setup-and-first-run
+priority: next
+blocked_on: []
+related_to:
+- key: selective-wake-for-the-listener
+  note: 'Both are about a session being reachable across a gap the agent is not awake
+    for. That one wakes a parked session when a message lands; this one makes sure the
+    session''s own context survives the gap at all. Read that one first for the hook
+    and background-process conventions this must follow.'
+- key: cross-key-rendezvous
+  note: 'Shares the addressing problem from the other end. That one asks how a stranger
+    finds you; this one asks which of several checkpoints is the one you meant. Both
+    resolve to "the tool decides, the agent does not choose", so settle the rule in
+    one place rather than twice.'
+refs:
+- 'src/switchboard/handoff.py'
+- 'src/switchboard/claude_session.py'
+- 'docs/claude-code.md'
+- 'https://github.com/gald33/switchboard/pull/229'
+evidence: |
+  **Inferred from a design conversation on 2026-09-05, after the first real
+  handoff the night before.** Nothing is broken; the mechanism works. What this
+  item records is what the working mechanism still asks of a human, and one
+  fragility that only shows up when something goes wrong.
+
+  **The question that started it: how does Cursor move sessions between cloud
+  and local so smoothly, and can we?** Reading Cursor's own store on a machine
+  that runs it answers the first half. Its `conversations` table tags each row
+  with a `source` — 496 `local` against 47 `cloud-cache` on the machine
+  inspected — the cloud ones carry a server-side `scope` hash the local ones
+  lack, the table has `root_fingerprint` and `cache_fingerprint` columns, and a
+  `conversation_search_reconciliation` table holds a sync `cursor`. That is a
+  client cache over a server-authoritative store. Cursor does not move a
+  session between cloud and local; both ends are clients of one record its
+  servers hold, so there is nothing to move.
+
+  **That is exactly the trade Switchboard must not make.** Copying it means the
+  hub storing transcripts it currently cannot read, which is the single
+  property the whole design exists to protect (`docs/model.md`). The local-first
+  choice is what let a session cross from a cloud container to a laptop on
+  2026-09-04 between two agents sharing no account, sealed with a key the hub
+  never saw. A cache-and-sync design cannot do that, because the server has to
+  hold the conversation in order to synchronise it.
+
+  **So the achievable version of "seamless" is not shared storage — it is that
+  nobody types a command.** A Cursor user does not experience syncing; they
+  experience "it was there". That experience needs the handoff to happen at the
+  boundaries automatically, and every part is already built:
+
+  - `session publish` with no recipient is already a **checkpoint** — the
+    capsule goes up sealed, addressed to nobody, collectable by anyone holding
+    the room's key, which in practice is your own other machines
+    (`handoff.py`).
+  - `init` already installs `SessionStart` and `Stop` hooks
+    (`cli.py`, `_session_start_cmd` / `_stop_cmd`).
+  - `session receive` already takes `--wait`.
+
+  Wiring them is the work: checkpoint on `Stop` and on going idle, collect on
+  `SessionStart`.
+
+  **And it closes a fragility, which is the stronger half of the case.** A
+  handoff is explicit today, so a session that dies unexpectedly leaves nothing
+  behind — the 2026-09-04 transfer survived only because the cloud agent chose
+  to publish before it finished. Cursor survives that case because the server
+  already holds the conversation. Periodic self-checkpointing is how a
+  local-first design gets the same durability without giving anything away: the
+  last checkpoint is always collectable and expires on its own, so nothing
+  accumulates on the hub.
+
+  **The open question, and the reason this is an item rather than a patch.**
+  Addressing. When several sessions have checkpointed, a starting session must
+  not collect all of them, and "the newest" is not obviously right either.
+  `--from` and sender verification are the raw material; the rule is not
+  decided. Most likely: the most recent checkpoint for **this repo** from **this
+  account**, with everything else needing to be asked for by id. Settle it
+  together with `cross-key-rendezvous`, which has the same shape of question.
+
+  **What this must not promise, and the docs should say so rather than let
+  somebody find out.** Two live sessions cannot edit one conversation: without
+  an authority to reconcile against, a handoff is a baton and not a mirror.
+  Continuity is only as good as the checkpoint interval. And a transcript is
+  large — the first real one was 19.8 MB across 175 files — so checkpointing
+  every turn is not free, which argues for idle and end-of-session rather than
+  continuous.
+
+  **Done when** a session that ends on one machine is collectable on another
+  with nobody running `handoff` or `receive`, when a session killed without
+  warning still leaves a collectable checkpoint, and when the addressing rule is
+  written down and tested rather than left to whoever calls `receive` first.