@brutalsystems/muster 0.8.3 → 0.9.1

package/CANONICAL_ID.md

@@ -1,6 +1,6 @@
 # Tin Can — Address Format
 
-> **Normative for `@brutalsystems/tincan` 0.1.0.**
+> **Normative for `@brutalsystems/tincan` 1.6.0.**
 >
 > This describes what Tin Can does today, precisely enough for another tool to
 > produce addresses Tin Can will resolve. It is a write-down of shipped
@@ -11,22 +11,56 @@
 > asserted by `test/canonical-id.test.ts`. Copy that fixture rather than
 > reimplementing from prose.
 >
+> Its `tincan_version` field records the release the expectations were verified
+> against, and is bumped every release. **A version difference alone is not
+> drift** — compare the file's contents, or its hash, to tell whether the format
+> actually moved.
+>
 > **The implementation is authoritative.** If this document and Tin Can
 > disagree, Tin Can is right and this document has a bug. The fixture is the
 > regression net that keeps them together.
 
 ## The pieces
 
-An address is built from two inputs:
+An address is built from three inputs, one of which is usually absent:
 
 | Runtime | Name source | Id source |
 |---|---|---|
 | `codex` | thread title, or absent | `thread_id` |
 | `claude-code` | session name from the registry | `session_id` |
+| `opencode` | session slug | `session_id` |
 
 Neither name is guaranteed unique, and neither is stable: **a name belongs to a
 process and dies with it.** Key durable records on the id, never on the address.
 
+`peers` exposes that id on every peer — `thread_id` for Codex, `session_id` for
+Claude Code and for opencode — so a caller never has to derive it from an
+address.
+
+The third input is the **machine**, and it is absent for every peer on this
+one. See [Machine](#machine).
+
+## Machine
+
+A peer on another machine carries `@<machine>` at the end of its address. A
+peer on this machine carries nothing.
+
+    auth-refactor            a session here
+    auth-refactor@m4pro      a session on another computer
+
+Absent rather than a literal like `localhost`, for two reasons. Every address
+anyone types today keeps working and keeps meaning exactly what it meant. And
+it makes the dangerous direction the explicit one: reaching another computer
+requires saying so.
+
+**A bare address never resolves to a remote peer.** Resolution filters by
+whether the input contains `@` before matching anything, so an address with no
+machine can only match a local session — including during prefix matching,
+which is where it would otherwise slip through. A message meant for a local
+peer must not leave the machine because a local session happened to exit.
+
+The machine name is slugified by the same rule as a peer name.
+
 ## Slugify
 
 Applied to the runtime-supplied name.
@@ -59,21 +93,47 @@ is a timestamp, so every thread live on a machine at the same time shares its
 first characters. A leading suffix disambiguates nothing. This has been
 specified wrongly before — verify against the fixture.
 
+The same holds for opencode, for the same reason by a different route. An
+opencode session id is `ses_` followed by roughly twelve hex characters of
+descending timestamp, then roughly fourteen base62 (`[0-9a-zA-Z]`) random
+characters. Stripping to `[0-9a-f]` and taking the last three lands in that
+random tail, not the timestamp — exactly as it does for a Codex UUIDv7 or a
+Claude Code UUIDv4. `suffixOf('ses_f41a2b3c4ffeExampleSess01Z')` → `'e01'`.
+
 - `01a0b9b4-a33e-7ab1-80a0-bb715504a0fb` → `0fb`
 - `5af69d42-2214-41d9-b13f-9c3177eb60ce` → `0ce`
+- `ses_f41a2b3c4ffeExampleSess01Z` → `e01`
 - Uppercase hex is kept, then lowered: `...ABC` → `abc`
 - Fewer than three hex characters yields a shorter suffix: `z-9` → `9`
 - No hex at all yields an empty suffix: `zzzz` → `""`
 
+Two caveats specific to opencode's id shape:
+
+- **The random tail is base62, not hex, so filtering it down to `[0-9a-f]`
+  skews the alphabet.** `a`–`f` are reachable from two source characters each
+  (upper- and lower-case), while `0`–`9` are reachable from only one, so the
+  surviving hex digits are not uniform. Collision odds for the suffix
+  therefore sit slightly above the nominal 1 in 4096 for a uniform 3-hex-digit
+  space. Worth stating; not worth changing — see
+  [Changing this format](#changing-this-format).
+- **An opencode id can never produce the empty-suffix defect.** The fixed
+  `ses_` + hex-timestamp prefix guarantees at least three hex characters are
+  always present, so unlike an adversarial or degenerate id (`zzzz` above),
+  `suffixOf` never returns `""` for a real opencode session id.
+
 ## Forms
 
 Three forms exist. Two are emitted; all three are accepted as input.
 
 | Form | Shape | Emitted |
 |---|---|---|
-| **Display** | `auth-refactor` | by `peers`, when the slug does not collide |
-| **Qualified** | `auth-refactor.7f3` | by `peers`, only on collision |
-| **Canonical** | `codex:auth-refactor.7f3` | as `canonical_id`, always |
+| **Display** | `auth-refactor`, `auth-refactor@m4pro` | by `peers`, when the slug does not collide |
+| **Qualified** | `auth-refactor.7f3`, `auth-refactor.7f3@m4pro` | by `peers`, only on collision |
+| **Canonical** | `codex:auth-refactor.01a0b9b4-a33e-7ab1-80a0-bb715504a0fb` | as `canonical_id`, always |
+
+**The canonical form carries the whole durable id**, not the three-character
+suffix. That is what makes it unique — see [Known defects](#known-defects),
+where its non-uniqueness used to be recorded as a defect preserved on purpose.
 
 The separator is `.` so that an address needs no shell quoting.
 
@@ -84,31 +144,82 @@ It is the form to record in logs and to pass between tools.
 
 A peer is suffixed in its **display** form when either:
 
-- another peer in the same listing has the same slug, or
+- another peer in the same listing has the same slug **on the same machine**, or
 - the peer has no name (`rawName === null`), which is always suffixed.
 
+Collisions are counted per machine. The same slug on two computers is already
+two different addresses, so suffixing both would add noise to distinguish
+things that were never confusable.
+
 Otherwise the display form is the bare slug. Only colliding peers are suffixed;
 peers that do not collide keep their bare names in the same listing.
 
+**Adding a runtime can change an existing peer's display.** `assignNames`
+computes collisions across the *whole* returned list, regardless of runtime.
+So a peer that displayed as a bare slug before opencode support existed can
+start displaying suffixed the moment an opencode peer (or any peer) slugging
+to the same string appears in the same listing — a Codex peer `foo` and an
+opencode session slugging to `foo` both flip from bare `foo` to qualified
+`foo.<suffix>` (see the fixture's "cross-runtime collision" case). This is
+inherent to the existing rule, not new behaviour introduced by opencode
+support, and it is correct: the two peers are genuinely indistinguishable by
+slug. It is called out here because Muster consumes `display`, and this
+should be an expected consequence of adding a runtime, not something its
+maintainer discovers by surprise.
+
 ## Resolution
 
-Input is trimmed and lowercased, then matched in two passes.
+Input is trimmed and lowercased, then matched in two passes against the peer
+listing, with one host-local check between them.
 
 **Pass 1 — exact.** Matches if the input equals the peer's display form, its
 qualified form, or its canonical id. One match resolves. More than one is
 refused as ambiguous.
 
-**Pass 2 — prefix**, only if pass 1 found nothing. Matches if the peer's slug or
-its qualified form *starts with* the input. One match resolves. More than one is
-refused as ambiguous.
-
-If neither pass matches, the result is refused as unknown.
+**Self check**, only if pass 1 found nothing. If the input names the session
+Tin Can is itself running in, the result is refused as `self`. See
+[Self is not a peer](#self-is-not-a-peer) — this pass is **not** part of the
+fixture contract and a second implementation is not expected to reproduce it.
+
+**Pass 2 — prefix**, only if pass 1 and the self check found nothing. Matches
+if the peer's slug or its qualified form *starts with* the input. One match
+resolves. More than one is refused as ambiguous.
+
+If nothing matches, the result is refused as unknown.
+
+### Self is not a peer
+
+A host never lists the session it is running in, so an address naming that
+session reaches pass 2 with nothing to match — or, worse, matches *something
+else*. The check sits between the passes rather than before them, and the
+order is load-bearing in both directions:
+
+- **Below pass 1**, so an exact peer name still wins. A peer genuinely called
+  `review` receives `review` even when the host is called `review-tools`,
+  which the self check matches by prefix.
+- **Above pass 2**, because that pass resolves on a *single* match. A host
+  that can only recognise itself by name — a Claude Code host carries no
+  session id of its own and falls back to its working directory's basename —
+  whose fallback name prefixed exactly one peer would otherwise resolve to
+  that peer and deliver. Where the listing spans config dirs, that peer
+  belongs to a different account: a note addressed to yourself, delivered to
+  a stranger, reported as sent.
+
+**This is deliberately outside the fixture.** Every case in
+`test/fixtures/canonical-id.json` resolves with no host identity supplied, and
+all ten behave identically with and without this pass. "Self" is a property of
+the process doing the resolving, not of the address or the listing, so a tool
+that consumes addresses — Muster launches sessions and hands back peer records
+for Tin Can to resolve — has no self to check and nothing to implement. The
+address format is unchanged; what changed is what one particular resolver does
+with its own name.
 
 - **Case-insensitive** throughout. `AUTH-REFACTOR.7F3` resolves.
 - **Input is trimmed.** Surrounding whitespace is ignored.
 - **There is no minimum prefix length.** A one-character prefix resolves if it
-  is unambiguous. The empty string is a prefix of everything — see
-  [known defects](#known-defects).
+  is unambiguous. The empty string is a prefix of everything, and a complete
+  name can be a prefix of a longer complete name — see
+  [known defects](#known-defects), 3 and 4.
 - **No tie-breaking.** Ambiguity is always refused, never guessed.
 
 ### Refusal shape
@@ -117,26 +228,32 @@ If neither pass matches, the result is refused as unknown.
 |---|---|
 | `ambiguous` | every matching peer, in **qualified** form |
 | `unknown` | every peer in the listing, in **display** form |
+| `self` | every peer the address *also* prefixed, in **qualified** form — so the caller is told which full name to type instead of guessing one exists |
 
 ## Known defects
 
-Preserved in 0.1.0 by decision, not by oversight. They are in the fixture so
+Preserved by decision, not by oversight. They are in the fixture so
 that a second implementation matches Tin Can exactly, including where Tin Can is
 wrong. **Do not "correct" them independently** — that produces addresses that
 resolve in one tool and fail silently in the other.
 
-**1. `canonical_id` is not unique.** Two peers whose slugs match *and* whose ids
-share their last three hex characters produce the same `canonical_id`. Tin Can
-then refuses to resolve either, listing two identical candidates — a refusal
-that tells the caller to disambiguate using a string that does not
-disambiguate. The peers are unaddressable until one exits.
+**1. `canonical_id` is not unique. — FIXED in 1.0.0.**
+
+It used to carry the three-character suffix, so two peers whose slugs matched
+*and* whose ids shared their last three hex characters produced the same
+`canonical_id`. Tin Can then refused to resolve either, listing two identical
+candidates — a refusal that told the caller to disambiguate using a string that
+did not disambiguate. Both peers were unaddressable until one exited. Roughly 1
+in 4096 given a slug collision, and slug collisions are not rare: Codex titles
+threads from their first prompt.
 
-Probability is roughly 1 in 4096 *given* a slug collision, and slug collisions
-are not rare: Codex titles threads from their first prompt, so two sessions
-started from similar prompts collide readily.
+The canonical form now carries the whole durable id, which makes a collision
+impossible rather than merely unlikely. Both peers stay addressable.
 
-**Consumers must therefore treat `canonical_id` as a display and correlation
-aid, not a primary key.** Key on `thread_id` / `session_id`.
+**The short forms still collide**, and still should: `display` and `qualified`
+are for humans, and two sessions genuinely sharing a name are genuinely
+ambiguous. The difference is that there is now an unambiguous form to fall back
+to. `canonical_id` is a usable key.
 
 **2. A name that slugifies to empty is inconsistent with an unnamed peer.**
 Alone in a listing, a peer named `???` displays as `thread` with no suffix,
@@ -149,6 +266,45 @@ string is a prefix of every slug, `resolve("")` against a single-peer listing
 returns that peer rather than refusing. With two or more peers it is refused as
 ambiguous, as expected.
 
+**4. A full name that is a prefix of a longer full name resolves to the longer
+one once the exactly-named session is gone.** While a session named `muster` is
+listed, `muster` is an exact hit and pass 2 is never reached. The moment it
+exits, `muster` is nobody's name and becomes merely a prefix of its neighbour
+`muster-b1` — the only match, so it resolves, and the message is delivered to a
+session the caller did not mean and reported as sent. Observed live between two
+sessions; the send was a reply, so `reply_misrouted` caught it, but a new
+message would have gone through.
+
+This is not an exotic collision. It happens whenever a short name and a longer
+one built on it coexist — `muster` / `muster-b1`, `ferry` / `ferry-9b`.
+
+**It is kept because it cannot be fixed from the listing alone.** The hazard is
+indistinguishable from the behaviour directly above it in this document: `auth`
+→ `auth-refactor` and `muster` → `muster-b1` are the same shape, the same single
+match, and in both cases the input is nobody's current name. The only fact that
+separates them is that a session named exactly `muster` *existed and has gone*,
+and a peer listing cannot carry that fact, because the session's absence is the
+whole premise. Any rule that refuses the second refuses the first: removing the
+prefix pass is verifiable in one edit, and it fails
+`resolve > unambiguous prefix resolves` alongside the defect's own case.
+
+**The form that cannot misroute is `canonical_id`.** Pass 2 matches against the
+slug and the qualified form, never against `canonicalId`, so a canonical id can
+never prefix-match a stranger — it resolves to the session it names or refuses
+as unknown:
+
+```
+muster gone , resolve("muster")                        -> OK, muster-b1
+muster gone , resolve("claude-code:muster.18ddaa21-…") -> REFUSED unknown
+```
+
+A loud refusal is the outcome a caller wants here. **When you hold a session's
+durable id, address it by `canonical_id` rather than by its bare name** — a
+short name is for a human typing, not for a program that already knows exactly
+which session it means. `expect_id` does not substitute: it is compared after
+resolution and only ever rejects, so it guards the send without selecting the
+recipient.
+
 ## Changing this format
 
 The address format is a contract between Tin Can and tools built against it. A
@@ -156,6 +312,14 @@ change to slugify, suffix derivation, collision handling, or resolution produces
 addresses that resolve in one tool and fail silently in the other — no error,
 just a message delivered nowhere.
 
+**Who is built against this today:**
+[Muster](https://github.com/BrutalSystems/muster) launches agent sessions and
+returns a peer record Tin Can must resolve. It does not import Tin Can — the two
+agree on this document and on `test/fixtures/canonical-id.json`, which Muster
+copies verbatim. So a change here is not local to this repo, and the person
+making it is responsible for coordinating the release, not for discovering
+afterwards that the other tool disagreed.
+
 So:
 
 - **A change to any behaviour described here is a breaking change**, and ships

package/CONTRACT_PROVENANCE.md

@@ -299,3 +299,74 @@ same-runtime exclusion, or Tin Can state. Its count assertion applies only to
 the matching canonical ID in the isolated test environment. Naming hashes do
 not cover listing membership, self-exclusion, or state semantics. A future
 upgrade must test these behaviors separately where relied upon.
+
+## Re-sync to Tin Can 1.5.1 — 2026-09-24
+
+Both contract copies were replaced wholesale from Tin Can at tag `v1.5.1`,
+commit `b62ca6a719131dbd1b43875fa47604c1c17cd9fb`. This ends the 0.1.0-vintage
+freeze described above: Muster had never been verified against any Tin Can 1.x,
+and the contract suite passed only because `RELEASING.md` pinned it to 0.6.4.
+
+| File | SHA-256 |
+| --- | --- |
+| `CANONICAL_ID.md` | `7ec8857238262ff49277488a515f830078df25451cff11dad69c0b6aa820dfa5` |
+| `test/fixtures/canonical-id.json` | `dde6ce24bf259fc0a44685f08fc724232968cd9ec3c839802cd2b37de702a85a` |
+
+The fixture carries `tincan_version: 1.5.1` and 39 cases: 8 slugify, 7 suffix,
+12 assignment, 12 resolution. These hashes are the same numbers asserted by
+`test/naming.test.ts` ("contract copies remain frozen"); the two sites must
+always agree, and the earlier divergence between this document's recorded
+fixture hash and the test's is what #48 reports.
+
+**Why the tag and not HEAD.** Tin Can's HEAD was one commit past `v1.5.1` when
+this was copied, and the three contract-relevant files were byte-identical
+between the two — confirmed from both sides. HEAD has since gained a 40th
+resolve case, but the fixture's `tincan_version` still reads 1.5.1 because
+those version sites only move on a cut. Copying HEAD and recording it as 1.5.1
+would manufacture exactly the provenance confusion this document exists to
+prevent, so the tag is the acquisition point and the 40th case is a follow-up.
+
+**What the 40th case is, and why it matters here.** It freezes a known defect
+Muster reported upstream and Tin Can confirmed as
+[tincan#39](https://github.com/BrutalSystems/tincan/issues/39): a full name
+that is a prefix of a longer full name resolves to the longer one once the
+exactly-named session has gone — `muster` lands on `muster-b1`. Tin Can chose
+to document it rather than change resolution, because no rule can separate it
+from fixture case [4] (`auth` resolving to `auth-refactor`) using anything a
+peer listing carries; an implementation of the stricter rule failed both the
+new case and the existing one. Muster reimplements resolution, so it inherits
+the defect by construction. Adopt the frozen case when it is cut; do not
+special-case it locally, because a local rule is drift by another name.
+
+`canonical_id` is the form that cannot misroute — resolution matches it
+exactly and never by prefix. Prefer it over a bare name wherever a durable id
+is already in hand.
+
+## Superseded same day: re-sync to Tin Can 1.6.0 — 2026-09-24
+
+The 1.5.1 acquisition above **never shipped**. Its release, 0.9.0, failed in CI
+before publishing (see below), and Tin Can cut 1.6.0 while that was being
+fixed. The copies are now from tag `v1.6.0`, commit
+`3d66ceaa718a098bb9e962282d901aff03dd47ff`.
+
+| File | SHA-256 |
+| --- | --- |
+| `CANONICAL_ID.md` | `06dd8afe83fa641183fb44b2625dbc684c2bed13c9ac5c8f51a6c1206a00da3e` |
+| `test/fixtures/canonical-id.json` | `a574fe291a515d920aab07f29629100caadb4fc8d8e8130a0851559bf2384aac` |
+
+`tincan_version: 1.6.0`, 40 cases: 8 slugify, 7 suffix, 12 assignment, 13
+resolution. This removes the compromise the 1.5.1 section describes — the
+fixture is now labelled for the release that contains it, so the acquisition
+point and the version metadata agree, and no follow-up is outstanding.
+
+The 40th case freezes the prefix-resolution defect
+([tincan#39](https://github.com/BrutalSystems/tincan/issues/39)) that Muster
+reported. `naming.ts`, written against the 39-case fixture, passes it
+unchanged — no expected value moved, so this is not an address-format change.
+
+**The case was verified to have teeth rather than assumed to.** A case that has
+never failed has not been shown to test anything. Implementing the stricter
+rule it documents — refuse a prefix that ends at a segment boundary — fails the
+new case *and* `resolve: unambiguous prefix resolves` together, in this copy.
+That pair failing together is the argument for Tin Can's decision to document
+the defect rather than change resolution, and it reproduces here.

package/dist/naming.js

@@ -19,32 +19,52 @@ export function suffixOf(uuid) {
         .slice(-3)
         .toLowerCase();
 }
+/** `@machine`, or nothing at all for a peer on this machine. */
+function at(machine) {
+    return machine === undefined || machine === "" ? "" : `@${slugify(machine)}`;
+}
 export function assignNames(peers) {
     const slugs = peers.map((peer) => {
         const s = peer.rawName ? slugify(peer.rawName) : "";
         return s.length > 0 ? s : "thread";
     });
+    // Collisions are counted per machine. The same slug on two computers is two
+    // different addresses already, so suffixing both would add noise to
+    // distinguish things that were never confusable.
     const counts = new Map();
-    for (const s of slugs)
-        counts.set(s, (counts.get(s) ?? 0) + 1);
+    for (const [i, s] of slugs.entries()) {
+        const key = `${s}${at(peers[i].machine)}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
     return peers.map((peer, i) => {
         const slug = slugs[i];
         const suffix = suffixOf(peer.uuid);
-        const qualified = `${slug}.${suffix}`;
+        const host = at(peer.machine);
+        const qualified = `${slug}.${suffix}${host}`;
         // An unnamed thread has no name to stand on, so it always carries its suffix.
-        const collides = (counts.get(slug) ?? 0) > 1 || peer.rawName === null;
+        const collides = (counts.get(`${slug}${host}`) ?? 0) > 1 || peer.rawName === null;
         return {
             ...peer,
             slug,
             suffix,
-            canonicalId: `${peer.runtime}:${qualified}`,
-            display: collides ? qualified : slug,
+            canonicalId: `${peer.runtime}:${slug}.${peer.uuid}${host}`,
+            display: collides ? qualified : `${slug}${host}`,
         };
     });
 }
 export function resolvePeer(peers, input) {
     const q = input.trim().toLowerCase();
-    const qualified = (p) => `${p.slug}.${p.suffix}`;
+    const qualified = (p) => `${p.slug}.${p.suffix}${at(p.machine)}`;
+    // A bare address names a peer on THIS machine. Prefix matching is what makes
+    // that matter: without this gate an address with no `@` could fall through
+    // and resolve to a session on another computer, so a message meant for a
+    // peer at this desk would leave the machine and be reported as sent. The
+    // dangerous direction has to be the explicit one.
+    const wantsMachine = q.includes("@");
+    peers = peers.filter((p) => {
+        const remote = p.machine !== undefined && p.machine !== "";
+        return wantsMachine ? remote : !remote;
+    });
     const exact = peers.filter((p) => p.display.toLowerCase() === q ||
         qualified(p) === q ||
         p.canonicalId.toLowerCase() === q);

package/dist/run.js

@@ -26,7 +26,7 @@ import { codexPolicyArgs } from "./codex-policy.js";
 import { CodexRpc } from "./codex-rpc.js";
 import { allocateLoopbackPort, OpenCodeHttp } from "./opencode-http.js";
 import { assertOpenCodeVersion, openCodeMcpNames, openCodeSessionLaunch, openCodeTaskLaunch, } from "./opencode-policy.js";
-import { assignNames, resolvePeer, runtimeName, } from "./naming.js";
+import { assignNames, resolvePeer, runtimeName, suffixOf, } from "./naming.js";
 import { selectMcp, prepareMcp, mcpEnvironment } from "./mcp.js";
 import { pollInterval } from "./reap.js";
 import { selectPlugins } from "./plugins.js";
@@ -783,7 +783,12 @@ export class Muster {
             slug: String(e.peer.canonical_id)
                 .split(":")[1]
                 .replace(/\.[^.]*$/, ""),
-            suffix: String(e.peer.canonical_id).split(".").at(-1),
+            // From the durable id, not from the canonical id's last dot-segment.
+            // That segment used to BE the three-hex suffix; since Tin Can 1.0.0 the
+            // canonical form carries the whole uuid, so the old surgery yielded the
+            // entire id and every qualified `slug.suffix` address stopped resolving.
+            // It failed quietly, as "unknown", which is why it needed a test.
+            suffix: suffixOf(e.id),
             canonicalId: String(e.peer.canonical_id),
             display: String(e.peer.name),
         }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {

package/test/fixtures/canonical-id.json

@@ -1,161 +1,590 @@
 {
   "$comment": "FROZEN. Describes @brutalsystems/tincan address behaviour as shipped. Adding cases is fine; changing an expected value means the address format changed - see CANONICAL_ID.md, 'Changing this format'.",
-  "tincan_version": "0.1.0",
+  "tincan_version": "1.6.0",
   "spec": "CANONICAL_ID.md",
-
   "slugify": [
-    { "case": "spaces and case are folded", "input": "Auth Refactor", "output": "auth-refactor" },
-    { "case": "runs of punctuation collapse to one dash", "input": "auth/refactor (v2)", "output": "auth-refactor-v2" },
-    { "case": "leading and trailing separators are stripped", "input": "  --Auth--  ", "output": "auth" },
-    { "case": "non-ascii is not transliterated, it is a separator", "input": "café ☕ time", "output": "caf-time" },
-    { "case": "digits survive", "input": "123", "output": "123" },
-    { "case": "all-caps folds", "input": "ALLCAPS", "output": "allcaps" },
-    { "case": "a name of only punctuation slugifies to empty", "input": "???", "output": "" },
-    { "case": "empty in, empty out", "input": "", "output": "" }
+    {
+      "case": "spaces and case are folded",
+      "input": "Auth Refactor",
+      "output": "auth-refactor"
+    },
+    {
+      "case": "runs of punctuation collapse to one dash",
+      "input": "auth/refactor (v2)",
+      "output": "auth-refactor-v2"
+    },
+    {
+      "case": "leading and trailing separators are stripped",
+      "input": "  --Auth--  ",
+      "output": "auth"
+    },
+    {
+      "case": "non-ascii is not transliterated, it is a separator",
+      "input": "café ☕ time",
+      "output": "caf-time"
+    },
+    {
+      "case": "digits survive",
+      "input": "123",
+      "output": "123"
+    },
+    {
+      "case": "all-caps folds",
+      "input": "ALLCAPS",
+      "output": "allcaps"
+    },
+    {
+      "case": "a name of only punctuation slugifies to empty",
+      "input": "???",
+      "output": ""
+    },
+    {
+      "case": "empty in, empty out",
+      "input": "",
+      "output": ""
+    }
   ],
-
   "suffix": [
-    { "case": "codex thread id (uuidv7): last three hex", "input": "01a0b9b4-a33e-7ab1-80a0-bb715504a0fb", "output": "0fb" },
-    { "case": "claude session id (uuidv4): last three hex", "input": "5af69d42-2214-41d9-b13f-9c3177eb60ce", "output": "0ce" },
-    { "case": "uppercase hex is lowercased", "input": "...ABC", "output": "abc" },
-    { "case": "non-hex characters are stripped before slicing", "input": "z-9", "output": "9" },
-    { "case": "no hex at all yields an empty suffix", "input": "zzzz", "output": "" },
-    { "case": "empty in, empty out", "input": "", "output": "" }
+    {
+      "case": "codex thread id (uuidv7): last three hex",
+      "input": "01a0b9b4-a33e-7ab1-80a0-bb715504a0fb",
+      "output": "0fb"
+    },
+    {
+      "case": "claude session id (uuidv4): last three hex",
+      "input": "5af69d42-2214-41d9-b13f-9c3177eb60ce",
+      "output": "0ce"
+    },
+    {
+      "case": "opencode session id (ses_ + hex timestamp + base62 random tail): last three hex",
+      "input": "ses_f41a2b3c4ffeExampleSess01Z",
+      "output": "e01"
+    },
+    {
+      "case": "uppercase hex is lowercased",
+      "input": "...ABC",
+      "output": "abc"
+    },
+    {
+      "case": "non-hex characters are stripped before slicing",
+      "input": "z-9",
+      "output": "9"
+    },
+    {
+      "case": "no hex at all yields an empty suffix",
+      "input": "zzzz",
+      "output": ""
+    },
+    {
+      "case": "empty in, empty out",
+      "input": "",
+      "output": ""
+    }
   ],
-
   "assign": [
     {
       "case": "no collision: display is the bare slug, canonical id is always qualified",
-      "peers": [ { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" } ],
-      "expect": [ { "display": "auth-refactor", "canonicalId": "codex:auth-refactor.7f3" } ]
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        }
+      ],
+      "expect": [
+        {
+          "display": "auth-refactor",
+          "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+        }
+      ]
     },
     {
       "case": "claude peers are qualified with their runtime",
-      "peers": [ { "runtime": "claude-code", "rawName": "billing-api", "uuid": "5af69d42-2214-41d9-b13f-9c3177eb60ce" } ],
-      "expect": [ { "display": "billing-api", "canonicalId": "claude-code:billing-api.0ce" } ]
+      "peers": [
+        {
+          "runtime": "claude-code",
+          "rawName": "billing-api",
+          "uuid": "5af69d42-2214-41d9-b13f-9c3177eb60ce"
+        }
+      ],
+      "expect": [
+        {
+          "display": "billing-api",
+          "canonicalId": "claude-code:billing-api.5af69d42-2214-41d9-b13f-9c3177eb60ce"
+        }
+      ]
+    },
+    {
+      "case": "opencode peer, no collision: display is the bare slug",
+      "peers": [
+        {
+          "runtime": "opencode",
+          "rawName": "nimble-wizard",
+          "uuid": "ses_7f6e5d4c3b2aNimbleWizardQ7"
+        }
+      ],
+      "expect": [
+        {
+          "display": "nimble-wizard",
+          "canonicalId": "opencode:nimble-wizard.ses_7f6e5d4c3b2aNimbleWizardQ7"
+        }
+      ]
+    },
+    {
+      "case": "collision between two opencode sessions with the same slug: both suffixed",
+      "peers": [
+        {
+          "runtime": "opencode",
+          "rawName": "swift-otter",
+          "uuid": "ses_8e7d6c5b4a39SwiftOtterAlpha"
+        },
+        {
+          "runtime": "opencode",
+          "rawName": "swift-otter",
+          "uuid": "ses_8e7d6c5b4a39SwiftOtterBeta7"
+        }
+      ],
+      "expect": [
+        {
+          "display": "swift-otter.eaa",
+          "canonicalId": "opencode:swift-otter.ses_8e7d6c5b4a39SwiftOtterAlpha"
+        },
+        {
+          "display": "swift-otter.ea7",
+          "canonicalId": "opencode:swift-otter.ses_8e7d6c5b4a39SwiftOtterBeta7"
+        }
+      ]
+    },
+    {
+      "case": "cross-runtime collision: an opencode peer and a codex peer sharing a slug both flip to suffixed",
+      "peers": [
+        {
+          "runtime": "opencode",
+          "rawName": "auth-refactor",
+          "uuid": "ses_9f8e7d6c5b4aAuthRefactorX9"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "01b1c2d3-e4f5-7a6b-90c1-d2e3f4a5b6c7"
+        }
+      ],
+      "expect": [
+        {
+          "display": "auth-refactor.ac9",
+          "canonicalId": "opencode:auth-refactor.ses_9f8e7d6c5b4aAuthRefactorX9"
+        },
+        {
+          "display": "auth-refactor.6c7",
+          "canonicalId": "codex:auth-refactor.01b1c2d3-e4f5-7a6b-90c1-d2e3f4a5b6c7"
+        }
+      ]
     },
     {
       "case": "collision: every colliding peer is suffixed, and only those",
       "peers": [
-        { "runtime": "codex", "rawName": "Review phase 1 handoff", "uuid": "00000000-0000-0000-0000-000000000aaa" },
-        { "runtime": "codex", "rawName": "Review phase-1 handoff", "uuid": "00000000-0000-0000-0000-000000000bbb" },
-        { "runtime": "codex", "rawName": "Something else", "uuid": "00000000-0000-0000-0000-000000000ccc" }
+        {
+          "runtime": "codex",
+          "rawName": "Review phase 1 handoff",
+          "uuid": "00000000-0000-0000-0000-000000000aaa"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Review phase-1 handoff",
+          "uuid": "00000000-0000-0000-0000-000000000bbb"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Something else",
+          "uuid": "00000000-0000-0000-0000-000000000ccc"
+        }
       ],
       "expect": [
-        { "display": "review-phase-1-handoff.aaa", "canonicalId": "codex:review-phase-1-handoff.aaa" },
-        { "display": "review-phase-1-handoff.bbb", "canonicalId": "codex:review-phase-1-handoff.bbb" },
-        { "display": "something-else", "canonicalId": "codex:something-else.ccc" }
+        {
+          "display": "review-phase-1-handoff.aaa",
+          "canonicalId": "codex:review-phase-1-handoff.00000000-0000-0000-0000-000000000aaa"
+        },
+        {
+          "display": "review-phase-1-handoff.bbb",
+          "canonicalId": "codex:review-phase-1-handoff.00000000-0000-0000-0000-000000000bbb"
+        },
+        {
+          "display": "something-else",
+          "canonicalId": "codex:something-else.00000000-0000-0000-0000-000000000ccc"
+        }
       ]
     },
     {
       "case": "an unnamed thread always carries its suffix, even alone",
-      "peers": [ { "runtime": "codex", "rawName": null, "uuid": "00000000-0000-0000-0000-0000000007f3" } ],
-      "expect": [ { "display": "thread.7f3", "canonicalId": "codex:thread.7f3" } ]
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": null,
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        }
+      ],
+      "expect": [
+        {
+          "display": "thread.7f3",
+          "canonicalId": "codex:thread.00000000-0000-0000-0000-0000000007f3"
+        }
+      ]
     },
     {
       "case": "KNOWN DEFECT: a name that slugifies to empty displays bare, unlike an unnamed thread",
-      "peers": [ { "runtime": "codex", "rawName": "???", "uuid": "00000000-0000-0000-0000-000000000def" } ],
-      "expect": [ { "display": "thread", "canonicalId": "codex:thread.def" } ]
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "???",
+          "uuid": "00000000-0000-0000-0000-000000000def"
+        }
+      ],
+      "expect": [
+        {
+          "display": "thread",
+          "canonicalId": "codex:thread.00000000-0000-0000-0000-000000000def"
+        }
+      ]
     },
     {
       "case": "unnamed and slugifies-to-empty collide on 'thread', so both are suffixed",
       "peers": [
-        { "runtime": "codex", "rawName": null, "uuid": "00000000-0000-0000-0000-000000000aaa" },
-        { "runtime": "codex", "rawName": "???", "uuid": "00000000-0000-0000-0000-000000000bbb" }
+        {
+          "runtime": "codex",
+          "rawName": null,
+          "uuid": "00000000-0000-0000-0000-000000000aaa"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "???",
+          "uuid": "00000000-0000-0000-0000-000000000bbb"
+        }
       ],
       "expect": [
-        { "display": "thread.aaa", "canonicalId": "codex:thread.aaa" },
-        { "display": "thread.bbb", "canonicalId": "codex:thread.bbb" }
+        {
+          "display": "thread.aaa",
+          "canonicalId": "codex:thread.00000000-0000-0000-0000-000000000aaa"
+        },
+        {
+          "display": "thread.bbb",
+          "canonicalId": "codex:thread.00000000-0000-0000-0000-000000000bbb"
+        }
       ]
     },
     {
       "case": "KNOWN DEFECT: canonical_id is not unique when slug and suffix both collide",
       "peers": [
-        { "runtime": "codex", "rawName": "Auth refactor", "uuid": "11111111-0000-0000-0000-000000000abc" },
-        { "runtime": "codex", "rawName": "auth-refactor", "uuid": "22222222-0000-0000-0000-000000000abc" }
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "11111111-0000-0000-0000-000000000abc"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "auth-refactor",
+          "uuid": "22222222-0000-0000-0000-000000000abc"
+        }
+      ],
+      "expect": [
+        {
+          "display": "auth-refactor.abc",
+          "canonicalId": "codex:auth-refactor.11111111-0000-0000-0000-000000000abc"
+        },
+        {
+          "display": "auth-refactor.abc",
+          "canonicalId": "codex:auth-refactor.22222222-0000-0000-0000-000000000abc"
+        }
+      ]
+    },
+    {
+      "case": "a peer on another machine carries @machine in both forms",
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3",
+          "machine": "m4pro"
+        }
+      ],
+      "expect": [
+        {
+          "display": "auth-refactor@m4pro",
+          "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3@m4pro"
+        }
+      ]
+    },
+    {
+      "case": "the same slug on two machines does not collide",
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3",
+          "machine": "m4pro"
+        }
       ],
       "expect": [
-        { "display": "auth-refactor.abc", "canonicalId": "codex:auth-refactor.abc" },
-        { "display": "auth-refactor.abc", "canonicalId": "codex:auth-refactor.abc" }
+        {
+          "display": "auth-refactor",
+          "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+        },
+        {
+          "display": "auth-refactor@m4pro",
+          "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3@m4pro"
+        }
       ]
     }
   ],
-
   "resolve": [
     {
       "case": "exact display name",
-      "peers": [ { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" } ],
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        }
+      ],
       "input": "auth-refactor",
-      "expect": { "ok": true, "canonicalId": "codex:auth-refactor.7f3" }
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+      }
     },
     {
       "case": "qualified form, accepted even with no collision",
-      "peers": [ { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" } ],
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        }
+      ],
       "input": "auth-refactor.7f3",
-      "expect": { "ok": true, "canonicalId": "codex:auth-refactor.7f3" }
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+      }
     },
     {
       "case": "fully qualified canonical id is accepted as input",
-      "peers": [ { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" } ],
-      "input": "codex:auth-refactor.7f3",
-      "expect": { "ok": true, "canonicalId": "codex:auth-refactor.7f3" }
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        }
+      ],
+      "input": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3",
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+      }
     },
     {
       "case": "case-insensitive, and input is trimmed",
-      "peers": [ { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" } ],
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        }
+      ],
       "input": "  AUTH-REFACTOR.7F3  ",
-      "expect": { "ok": true, "canonicalId": "codex:auth-refactor.7f3" }
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+      }
     },
     {
       "case": "unambiguous prefix resolves",
       "peers": [
-        { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" },
-        { "runtime": "codex", "rawName": "Billing sync", "uuid": "00000000-0000-0000-0000-000000000b12" }
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Billing sync",
+          "uuid": "00000000-0000-0000-0000-000000000b12"
+        }
       ],
       "input": "auth",
-      "expect": { "ok": true, "canonicalId": "codex:auth-refactor.7f3" }
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+      }
     },
     {
       "case": "ambiguous prefix is refused, listing every candidate in qualified form",
       "peers": [
-        { "runtime": "codex", "rawName": "Billing sync", "uuid": "00000000-0000-0000-0000-000000000b12" },
-        { "runtime": "codex", "rawName": "Billing report", "uuid": "00000000-0000-0000-0000-000000000b34" }
+        {
+          "runtime": "codex",
+          "rawName": "Billing sync",
+          "uuid": "00000000-0000-0000-0000-000000000b12"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Billing report",
+          "uuid": "00000000-0000-0000-0000-000000000b34"
+        }
       ],
       "input": "billing",
-      "expect": { "ok": false, "reason": "ambiguous", "candidates": ["billing-report.b34", "billing-sync.b12"] }
+      "expect": {
+        "ok": false,
+        "reason": "ambiguous",
+        "candidates": [
+          "billing-sync.b12",
+          "billing-report.b34"
+        ]
+      }
     },
     {
       "case": "unknown name is refused, and candidates list every peer in display form",
       "peers": [
-        { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" },
-        { "runtime": "codex", "rawName": "Billing sync", "uuid": "00000000-0000-0000-0000-000000000b12" }
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Billing sync",
+          "uuid": "00000000-0000-0000-0000-000000000b12"
+        }
       ],
       "input": "zzz",
-      "expect": { "ok": false, "reason": "unknown", "candidates": ["auth-refactor", "billing-sync"] }
+      "expect": {
+        "ok": false,
+        "reason": "unknown",
+        "candidates": [
+          "auth-refactor",
+          "billing-sync"
+        ]
+      }
     },
     {
-      "case": "KNOWN DEFECT: colliding canonical ids refuse with two identical candidates",
+      "case": "two peers whose slug AND short suffix collide are each still addressable by canonical id",
       "peers": [
-        { "runtime": "codex", "rawName": "Auth refactor", "uuid": "11111111-0000-0000-0000-000000000abc" },
-        { "runtime": "codex", "rawName": "auth-refactor", "uuid": "22222222-0000-0000-0000-000000000abc" }
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "11111111-0000-0000-0000-000000000abc"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "auth-refactor",
+          "uuid": "22222222-0000-0000-0000-000000000abc"
+        }
       ],
-      "input": "codex:auth-refactor.abc",
-      "expect": { "ok": false, "reason": "ambiguous", "candidates": ["auth-refactor.abc", "auth-refactor.abc"] }
+      "input": "codex:auth-refactor.11111111-0000-0000-0000-000000000abc",
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.11111111-0000-0000-0000-000000000abc"
+      }
     },
     {
       "case": "empty input is a prefix of everything: ambiguous when more than one peer",
       "peers": [
-        { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" },
-        { "runtime": "codex", "rawName": "Billing sync", "uuid": "00000000-0000-0000-0000-000000000b12" }
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Billing sync",
+          "uuid": "00000000-0000-0000-0000-000000000b12"
+        }
       ],
       "input": "",
-      "expect": { "ok": false, "reason": "ambiguous", "candidates": ["auth-refactor.7f3", "billing-sync.b12"] }
+      "expect": {
+        "ok": false,
+        "reason": "ambiguous",
+        "candidates": [
+          "auth-refactor.7f3",
+          "billing-sync.b12"
+        ]
+      }
     },
     {
       "case": "KNOWN DEFECT: empty input resolves to the only peer when there is exactly one",
-      "peers": [ { "runtime": "codex", "rawName": "Auth refactor", "uuid": "00000000-0000-0000-0000-0000000007f3" } ],
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        }
+      ],
       "input": "",
-      "expect": { "ok": true, "canonicalId": "codex:auth-refactor.7f3" }
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3"
+      }
+    },
+    {
+      "case": "a remote peer resolves by its @machine address",
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3"
+        },
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3",
+          "machine": "m4pro"
+        }
+      ],
+      "input": "auth-refactor@m4pro",
+      "expect": {
+        "ok": true,
+        "canonicalId": "codex:auth-refactor.00000000-0000-0000-0000-0000000007f3@m4pro"
+      }
+    },
+    {
+      "case": "a bare address never reaches another machine",
+      "peers": [
+        {
+          "runtime": "codex",
+          "rawName": "Auth refactor",
+          "uuid": "00000000-0000-0000-0000-0000000007f3",
+          "machine": "m4pro"
+        }
+      ],
+      "input": "auth-refactor",
+      "expect": {
+        "ok": false,
+        "reason": "unknown",
+        "candidates": []
+      }
+    },
+    {
+      "case": "KNOWN DEFECT: a full name that is a prefix of a longer full name resolves to the longer one once the exactly-named session is gone",
+      "peers": [
+        {
+          "runtime": "claude-code",
+          "rawName": "muster-b1",
+          "uuid": "22222222-2222-4222-8222-222222222222"
+        },
+        {
+          "runtime": "claude-code",
+          "rawName": "cxx-be",
+          "uuid": "33333333-3333-4333-8333-333333333333"
+        }
+      ],
+      "input": "muster",
+      "expect": {
+        "ok": true,
+        "canonicalId": "claude-code:muster-b1.22222222-2222-4222-8222-222222222222"
+      }
     }
   ]
 }