@ccmsg/protocol 1.22.1 → 2.0.0

package/src/control/dump.ts

@@ -576,7 +576,28 @@ export type DumpIdEntry = Static<typeof DumpIdEntry>;
 export const DumpIds = Type.Array(DumpIdEntry, { $id: "DumpIds" });
 export type DumpIds = Static<typeof DumpIds>;
 
-/** The file a dump is written to.
+/** How the selected items are written out.
+ *
+ * The selection is one thing and its rendering another: which items a dump is
+ * of follows from the range and the `types`, and a format decides only what the
+ * file then says about them. So all three are dumps of the same items, and the
+ * reply describes that selection whichever was asked for.
+ *
+ * `items` is this contract's own vocabulary, the typed items as
+ * `SessionDumpFile`. `records` writes the transcript records those items were
+ * read from, unchanged, one JSON document per line — for a tool that already
+ * reads the harness's file and wants the classifying alone, which is why
+ * nothing of ours is added around them. An item names its record, so several
+ * items out of one record are one record here and the line count is not the
+ * item count. `text` renders the items for a person to read. */
+export const SessionDumpFormat = Type.Union(
+  [Type.Literal("items"), Type.Literal("records"), Type.Literal("text")],
+  { $id: "SessionDumpFormat" },
+);
+export type SessionDumpFormat = Static<typeof SessionDumpFormat>;
+
+/** The file an `items` dump is written to. The other two formats are not this
+ * shape: `records` is the harness's own lines and `text` is prose.
  *
  * The reply to a dump names a path rather than carrying the items, so the file
  * is where they actually travel — which makes its shape as much a part of the

package/src/control/peers.ts

@@ -1,34 +1,60 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { topicFrame } from "../envelope.ts";
-import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
+import { InstanceId, Sid, TerminalId, Timestamp } from "../identifiers.ts";
 import { SessionMetaFields } from "../session-meta.ts";
 
-/** How a session stands, as the instance holding it derives it.
+/** How recently the gateway must have seen inference for a session for that
+ * alone to say the session is alive. A session whose processes are all gone but
+ * whose inference is still running is alive: the request outlives the terminal
+ * it was typed in. */
+export const GATEWAY_LIVE_WINDOW_MS = 5 * 60 * 1000;
+
+/** One process running a session.
  *
- * The instance states the classification rather than the raw inputs it read,
- * so every client shows the same session the same way. The first three appear
- * on connected sessions, the last two on sessions the instance has lost; a
- * client that groups its list groups on this field alone.
+ * A session and a run of it are two things: the session is the transcript and
+ * the folded state, and lives whether nothing or two processes are running it.
+ * This is the process — what a signal reaches, what a terminal shows, what a
+ * connection speaks over. */
+export const SessionRun = Type.Object(
+  {
+    /** The harness process. Present when the harness's state file names one or
+     * a launcher started it; a run known only by its connection has none, and
+     * nothing in this contract can signal such a run. */
+    pid: Type.Optional(Type.Integer({ minimum: 1 })),
+    /** When that process started, which is what tells a pid the OS has handed
+     * to something else from the run it was read for. Stated wherever `pid`
+     * is. */
+    started_at: Type.Optional(Timestamp),
+    terminal_id: Type.Optional(TerminalId),
+    /** Whether a connection of this run is open to the instance right now. */
+    connected: Type.Boolean(),
+  },
+  { $id: "SessionRun" },
+);
+export type SessionRun = Static<typeof SessionRun>;
+
+/** What the `session.status` fold for this session is worth.
  *
- * Being pinned is not one of these: a person pins a session, and the mark
- * travels beside the classification rather than replacing it. */
-export const SessionState = Type.Union(
+ * A client reads this before it reads the fold: the values below say whether
+ * there is a transcript at all, whether the instance has caught up with it, and
+ * whether anything it says can still be trusted. */
+export const SessionStatusStanding = Type.Union(
   [
-    /** Stopped at something a person has to answer: a dialog it opened, or a
-     * turn that ended in an upstream error. */
-    Type.Literal("waiting"),
-    Type.Literal("live"),
-    /** Alive, but reachable through neither a client connection nor a
-     * terminal, so nothing here can act on it. */
-    Type.Literal("live_unmanaged"),
-    /** Gone, having said it was stopping. */
-    Type.Literal("paused"),
-    /** Gone without saying so. */
-    Type.Literal("disappeared"),
+    /** No transcript, so there is nothing to fold. A session that has just
+     * started stands here until the harness writes its first record. */
+    Type.Literal("absent"),
+    /** The transcript is being read from the top; what the fold says so far is
+     * incomplete. */
+    Type.Literal("folding"),
+    Type.Literal("ready"),
+    /** Two or more runs are writing the same transcript, so the instance stops
+     * updating the fold and stops carrying the transcript's additions. What it
+     * states is the last value it could trust. */
+    Type.Literal("frozen"),
   ],
-  { $id: "SessionState" },
+  { $id: "SessionStatusStanding" },
 );
-export type SessionState = Static<typeof SessionState>;
+export type SessionStatusStanding = Static<typeof SessionStatusStanding>;
 
 /** How long a lost session's row is kept after it was last seen, before the
  * instance forgets it and the row leaves as a removal. The same window the inbox
@@ -68,9 +94,9 @@ export type StaleClientInfo = Static<typeof StaleClientInfo>;
  * Connected and lost sessions are one kind of row rather than two lists: a
  * session registering or going quiet moves it between the two, and a row that
  * changed lists while keeping its identity is an update of that row. Which it
- * is now is the `state` below, and the fields that only a lost session has
- * (`last_seen_at`, `stopped_at`, and what it must resume as) are stated
- * alongside the connection fields it kept. */
+ * is now is read off `runs` and `stopped_at` by `liveness` below, and the
+ * fields that only a lost session has (`last_seen_at`, `stopped_at`, and what
+ * it must resume as) are stated alongside the connection fields it kept. */
 export const PeerInfo = Type.Object(
   {
     sid: Sid,
@@ -90,11 +116,19 @@ export const PeerInfo = Type.Object(
      * notification's `sid_label` — so the material for those is on the row that
      * every client already holds. */
     title: Type.Optional(SessionMetaFields.title),
-    /** How this session stands, which is also what separates a connected row
-     * from one its instance has lost. Absent from an instance that states no
-     * classification, and a client then shows the session without grouping it
-     * rather than guessing one. */
-    state: Type.Optional(SessionState),
+    /** Every process the instance can see running this session, which is also
+     * what separates a connected row from one its instance has lost. Empty
+     * means none is running, which is a row a person can still resume; two or
+     * more mean the harness let the same session be resumed while it was
+     * running, and nothing here picks one of them.
+     *
+     * The observation itself rather than a count or a verdict: which process,
+     * where it can be opened, and whether it is connected are each what a
+     * person decides on, and a session role holds this row without ever seeing
+     * the `agents` topic. */
+    runs: Type.Array(SessionRun),
+    /** What this session's `session.status` fold is worth just now. */
+    session_status: SessionStatusStanding,
     /** Set while a person has pinned this session. Absent means not pinned. */
     pinned: Type.Optional(Type.Boolean()),
     /** When this session first registered with the instance. Stable across its
@@ -112,9 +146,10 @@ export const PeerInfo = Type.Object(
     /** When inference last ran for this session, as the gateway saw it.
      *
      * How busy a session is, carried as an attribute of the row rather than
-     * folded into `state`: a session is busy while it stands in any of the
-     * connected classifications, so the two answer different questions and
-     * collapsing them would lose one. It is an instant rather than a flag
+     * folded into how it stands: a session is busy whether one process or none
+     * is running it, so the two answer different questions and collapsing them
+     * would lose one. It is also what says a session with no run left is still
+     * alive, the request outliving the process. It is an instant rather than a flag
      * because there is no moment a request stops being in flight that anything
      * observes — a client reads recency and decides its own threshold.
      *
@@ -144,7 +179,9 @@ export const PeerInfo = Type.Object(
     last_seen_at: Type.Optional(Timestamp),
     /** When the session said it was stopping. Its presence is what makes a lost
      * session a pause rather than a disappearance: one that goes without a word
-     * leaves nothing to stamp here. */
+     * leaves nothing to stamp here. It says something only while `runs` is
+     * empty — a session that declared it was stopping and is running again has
+     * a stamp older than the run. */
     stopped_at: Type.Optional(Timestamp),
     /** What its last turn ran as, in the transcript's own spelling, read back
      * from the transcript rather than copied from the connection: what a lost
@@ -177,6 +214,59 @@ export type PeerRemoved = Static<typeof PeerRemoved>;
 export const PeerElement = Type.Union([PeerInfo, PeerRemoved], { $id: "PeerElement" });
 export type PeerElement = Static<typeof PeerElement>;
 
+/** Where a session stands as a thing that is or is not running.
+ *
+ * `duplicated` is not a degree of aliveness but the answer to a different
+ * question — how many processes — which is why it wins over the rest: a session
+ * two processes are writing is one nothing should be read from, however alive
+ * it looks. */
+export type Liveness = "alive" | "duplicated" | "paused" | "disappeared";
+
+/** How a session stands, read off the row.
+ *
+ * Derived here rather than stated on the wire, and here rather than once per
+ * side: an instance and a client that each wrote this arithmetic would show the
+ * same row two ways. */
+export function liveness(
+  row: {
+    runs: readonly { connected: boolean }[];
+    stopped_at?: number;
+    gateway_active_at?: number;
+  },
+  now: number,
+): Liveness {
+  if (row.runs.length >= 2) return "duplicated";
+  const running =
+    (row.runs.length > 0 && row.stopped_at === undefined) ||
+    (row.gateway_active_at !== undefined && now - row.gateway_active_at <= GATEWAY_LIVE_WINDOW_MS);
+  if (running) return "alive";
+  return row.stopped_at === undefined ? "disappeared" : "paused";
+}
+
+/** Whether anything here can act on the session: some run of it is connected or
+ * names a terminal. A session alive with neither is one nothing can be handed
+ * to and nothing can be typed into. */
+export function reachable(row: {
+  runs: readonly { connected: boolean; terminal_id?: string }[];
+}): boolean {
+  return row.runs.some((run) => run.connected || run.terminal_id !== undefined);
+}
+
+/** Whether something is out that a person has to answer: a dialog the harness
+ * is holding open, or a turn that ended on an upstream error.
+ *
+ * Both materials belong to the `user` role — the `agents` row and the status
+ * fold — which is why this takes them rather than a `peers` row: a session role
+ * asking how another session stands has `runs` and `stopped_at` and no way to
+ * see this one. Either argument may be missing, which says only that its
+ * material was not there to read. */
+export function waiting(
+  agentsRow: { waiting_for?: string } | undefined,
+  status: { api_error?: unknown } | undefined,
+): boolean {
+  return agentsRow?.waiting_for !== undefined || status?.api_error !== undefined;
+}
+
 /** The `peers` topic.
  *
  * Elements: each frame carries the rows that changed, matched by their

package/src/control/session.ts

@@ -1,15 +1,22 @@
 import { type Static, Type } from "@sinclair/typebox";
 import { request, response } from "../envelope.ts";
-import { InstanceId, Sid, Timestamp } from "../identifiers.ts";
-import { DumpIds, TranscriptItemSelector, TranscriptItemType } from "./dump.ts";
+import { InstanceId, Sid, TerminalId, Timestamp } from "../identifiers.ts";
+import { DumpIds, SessionDumpFormat, TranscriptItemSelector, TranscriptItemType } from "./dump.ts";
 
 /** Ends the OS process behind a session.
  *
- * The request names a session, never a pid: the instance resolves sid to pid
- * itself at the moment it signals, and a pid the caller asserted would be a
- * weaker basis for killing something than that. */
+ * A session with one run is named by its sid alone: the instance resolves it to
+ * a pid at the moment it signals, which is a better basis than anything a
+ * caller asserts. A session with two is not resolvable that way, and a kill
+ * that named only the sid is refused with `ambiguous_run` — the caller picks a
+ * run from `peers.runs` and names it below. */
 export const SessionKillArgs = Type.Object({
   sid: Sid,
+  /** Which run to end, where the session has more than one. The instance
+   * signals it only after finding it in the session's own runs, pid and start
+   * together, so a pid the caller got wrong ends nothing rather than ending
+   * whatever the OS has since given that number to. */
+  pid: Type.Optional(Type.Integer({ minimum: 1 })),
   /** Escalate to an unconditional kill. The instance never chooses this on its
    * own, because it forfeits the session's chance to flush its transcript; a
    * caller asks for it after watching a graceful attempt go unconfirmed. */
@@ -55,7 +62,7 @@ export type SessionRenameArgs = Static<typeof SessionRenameArgs>;
 export const SessionRenameResult = Type.Object({
   /** The terminal handle the keystrokes went to. A host-local handle, so it
    * travels with the instance that owns it. */
-  terminal_id: Type.String(),
+  terminal_id: TerminalId,
   instance: InstanceId,
   /** The trimmed title actually typed, which is what a caller should report
    * rather than the draft it sent. */
@@ -203,6 +210,8 @@ export const SessionDumpWriteArgs = Type.Object({
   /** Leave out the machinery of in-process agents, which
    * `["-message.sub", "-tool.Agent"]` also says. */
   no_agent: Type.Optional(Type.Boolean()),
+  /** What the file says about the items selected. Absent is `items`. */
+  format: Type.Optional(SessionDumpFormat),
 });
 export type SessionDumpWriteArgs = Static<typeof SessionDumpWriteArgs>;
 
@@ -210,12 +219,18 @@ export const SessionDumpWriteResult = Type.Object({
   /** Absolute path on the writing instance's host. */
   path: Type.String(),
   instance: InstanceId,
-  /** How many items of each type were written, keyed by type name. A single
+  /** How many items of each type were selected, keyed by type name. A single
    * total leaves the caller unable to tell a dump that kept what it asked for
-   * from one whose selection matched almost nothing. */
+   * from one whose selection matched almost nothing.
+   *
+   * It counts items and not what the file holds, whatever the `format`: the
+   * selection is what a caller asked for and what it reads this against, and a
+   * count that moved with the rendering would answer a different question each
+   * time. */
   entries: Type.Record(TranscriptItemType, Type.Integer({ minimum: 0 })),
   /** The ids those items carried, so the next dump — of an agent named here —
-   * can be asked for without opening the file. */
+   * can be asked for without opening the file. Read off the selection like
+   * `entries`, whatever the `format`. */
   ids: DumpIds,
   bytes: Type.Integer({ minimum: 0 }),
 });

package/src/envelope.ts

@@ -6,7 +6,7 @@ import { InstanceId, Role, Sid } from "./identifiers.ts";
  * fields and whole new ops may be added; a removal or a change of meaning
  * raises it. Peers announcing another generation are refused, on client
  * connections and on mesh links alike. */
-export const PROTOCOL_VERSION = 3;
+export const PROTOCOL_VERSION = 4;
 
 /** The largest a single frame — one newline-delimited line, request, reply or
  * topic frame alike — may be, in bytes.
@@ -62,7 +62,7 @@ export const RequestEnvelope = Type.Object(
      *
      * A forwarded request that names none is dispatched as the `instance` role
      * it arrived on, which the attribute table already answers: an
-     * instance-local op called by an instance is `forbidden`. */
+     * an `owner_instance` op called by an instance is `forbidden`. */
     caller: Type.Optional(CallerIdentity),
   },
   { $id: "RequestEnvelope" },

package/src/errors.ts

@@ -35,17 +35,27 @@ export const ERROR_CODES = [
   "invalid_args",
   /** The op declares a `capability` this instance does not have. */
   "capability_unavailable",
-  /** An `instance-local` op could not be forwarded to the instance that owns
+  /** An `owner_instance` op could not be forwarded to the instance that owns
    * the subject. */
   "instance_unreachable",
   // --- subscription ---
   /** The topic name is not one this protocol generation defines. */
   "topic_unknown",
   // --- subject lookup ---
-  /** The `sid` names no session anywhere in the cluster. */
+  /** The `sid` names no session anywhere in the mesh. */
   "session_not_found",
   /** The path, transcript, or record named by the arguments does not exist. */
   "not_found",
+  // --- a session two processes are running ---
+  /** Two or more processes are running the session the call names, so what it
+   * would act on cannot be settled and what the transcript says cannot be
+   * trusted. Nothing is held back for later: what was to be sent is still with
+   * the caller, and a person decides which run to end before anything here
+   * resumes. */
+  "session_duplicated",
+  /** The session has more than one run and the call named none. The caller
+   * picks one from `peers.runs` and asks again naming its pid. */
+  "ambiguous_run",
   // --- file access ---
   "path_forbidden",
   "path_not_writable",
@@ -66,7 +76,7 @@ export const ERROR_CODES = [
    * and `msg` says no more than the instance's own log would want. */
   "auth_invalid",
   /** The instance that issued the challenge or registration, and alone can
-   * spend it, is not one this cluster knows or could reach just now. The client
+   * spend it, is not one this mesh knows or could reach just now. The client
    * asks for a fresh one, which the instance it is talking to can issue. */
   "auth_unknown_issuer",
   // --- translate ---

package/src/fixtures/common.ts

@@ -41,8 +41,9 @@ const { sid, instance, other_instance, endpoint, other_endpoint, request_id } =
 export const HELLO_SESSION_REQUEST: Static<typeof HelloSessionRequest> = {
   request_id,
   op: "hello.session",
-  protocol_version: 3,
+  protocol_version: 4,
   sid,
+  pid: 4821,
   client_version: "0.1.0",
   repo: "ccmsg-protocol",
   ws: "main",
@@ -59,7 +60,7 @@ export const HELLO_SESSION_REQUEST: Static<typeof HelloSessionRequest> = {
 export const HELLO_USER_REQUEST: Static<typeof HelloUserRequest> = {
   request_id,
   op: "hello.user",
-  protocol_version: 3,
+  protocol_version: 4,
   client_version: "0.1.0",
 };
 
@@ -68,7 +69,7 @@ export const HELLO_USER_REQUEST: Static<typeof HelloUserRequest> = {
 export const HELLO_INSTANCE_REQUEST: Static<typeof HelloInstanceRequest> = {
   request_id,
   op: "hello.instance",
-  protocol_version: 3,
+  protocol_version: 4,
   mesh: {
     ver: 1,
     iss: other_endpoint,
@@ -83,7 +84,7 @@ export const HELLO_INSTANCE_REQUEST: Static<typeof HelloInstanceRequest> = {
 export const HELLO_RESPONSE: Static<typeof HelloSessionResponse> = {
   ok: true,
   request_id,
-  protocol_version: 3,
+  protocol_version: 4,
   instance,
   endpoint,
   auth_expires_at: FIXTURE_NOW + 10_000_000,

package/src/fixtures/control.ts

@@ -105,7 +105,7 @@ export const SESSION_RENAME_REQUEST: Static<typeof SessionRenameRequest> = {
 export const SESSION_RENAME_RESPONSE: Static<typeof SessionRenameResponse> = {
   ok: true,
   request_id,
-  terminal_id: "%17",
+  terminal_id: "hyoui:%17",
   instance,
   title: "contract fixtures",
 };

package/src/fixtures/messaging.ts

@@ -75,6 +75,7 @@ export const NOTIFY_SEND_REQUEST: Static<typeof NotifySendRequest> = {
   op: "notify.send",
   sid,
   text: "確認して",
+  reply_to: mid,
 };
 
 export const NOTIFY_SEND_RESPONSE: Static<typeof NotifySendResponse> = {

package/src/fixtures/topics.ts

@@ -29,6 +29,7 @@ export const INBOX_FRAME: Static<typeof InboxFrame> = {
       from_label: "contract-fixtures",
       text: "fixture を export した",
       sent_at: FIXTURE_NOW,
+      to: sid,
     },
     {
       mid: `${instance}/1842`,
@@ -37,15 +38,34 @@ export const INBOX_FRAME: Static<typeof InboxFrame> = {
       text: "確認する",
       reply_to: mid,
       sent_at: FIXTURE_NOW + 1_000,
+      to: sid,
     },
   ],
 };
 
+/** A later frame, where one message has been handed over and another was never
+ * taken. */
+export const INBOX_REMOVED_FRAME: Static<typeof InboxFrame> = {
+  ev: "topic",
+  topic: "inbox",
+  instance,
+  data: [
+    { mid, removed: true, reason: "delivered" },
+    { mid: `${instance}/1842`, removed: true, reason: "expired" },
+  ],
+};
+
 export const NOTIFY_FRAME: Static<typeof NotifyFrame> = {
   ev: "topic",
   topic: "notify",
   instance,
-  data: { sid, sid_label: "contract-fixtures", text: "確認して", sent_at: FIXTURE_NOW },
+  data: {
+    sid,
+    sid_label: "contract-fixtures",
+    text: "確認して",
+    reply_to: mid,
+    sent_at: FIXTURE_NOW,
+  },
 };
 
 const PEER = {
@@ -54,7 +74,7 @@ const PEER = {
   repo: "ccmsg-protocol",
   ws: "main",
   cwd: WORKSPACE,
-  protocol_version: 3,
+  protocol_version: 4,
 };
 
 export const PEERS_FRAME: Static<typeof PeersFrame> = {
@@ -70,7 +90,15 @@ export const PEERS_FRAME: Static<typeof PeersFrame> = {
         repo_root: "/repos/kawaz/ccmsg-protocol",
         branch: "main",
         title: "contract fixtures",
-        state: "live",
+        runs: [
+          {
+            pid: 4821,
+            started_at: FIXTURE_NOW - 600_000,
+            terminal_id: "hyoui:%17",
+            connected: true,
+          },
+        ],
+        session_status: "ready",
         pinned: true,
         connected_at: FIXTURE_NOW - 600_000,
         last_activity_at: FIXTURE_NOW,
@@ -82,7 +110,8 @@ export const PEERS_FRAME: Static<typeof PeersFrame> = {
       {
         ...PEER,
         sid: other_sid,
-        state: "live_unmanaged",
+        runs: [{ pid: 7314, started_at: FIXTURE_NOW - 120_000, connected: false }],
+        session_status: "folding",
         stale_client: {
           last_seen_at: FIXTURE_NOW - 300_000,
           version: "0.0.9",
@@ -95,7 +124,8 @@ export const PEERS_FRAME: Static<typeof PeersFrame> = {
         repo: "ccmsg",
         ws: "daemon-v2",
         cwd: "/repos/kawaz/ccmsg/daemon-v2",
-        state: "paused",
+        runs: [],
+        session_status: "ready",
         last_seen_at: FIXTURE_NOW - 1_200_000,
         stopped_at: FIXTURE_NOW - 1_000_000,
         model: "claude-opus-5",
@@ -105,14 +135,33 @@ export const PEERS_FRAME: Static<typeof PeersFrame> = {
   },
 };
 
-/** A later frame: one row moved on, and one the instance forgot. */
+/** A later frame: one row is being run by two processes at once, and one the
+ * instance forgot. */
 export const PEERS_CHANGE_FRAME: Static<typeof PeersFrame> = {
   ev: "topic",
   topic: "peers",
   instance,
   data: {
     peers: [
-      { ...PEER, state: "live", gateway_active_at: FIXTURE_NOW + 1_000 },
+      {
+        ...PEER,
+        runs: [
+          {
+            pid: 4821,
+            started_at: FIXTURE_NOW - 600_000,
+            terminal_id: "hyoui:%17",
+            connected: true,
+          },
+          {
+            pid: 9022,
+            started_at: FIXTURE_NOW - 30_000,
+            terminal_id: "hyoui:%23",
+            connected: true,
+          },
+        ],
+        session_status: "frozen",
+        gateway_active_at: FIXTURE_NOW + 1_000,
+      },
       { sid: "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", instance, removed: true },
     ],
   },
@@ -149,9 +198,18 @@ export const AGENTS_FRAME: Static<typeof AgentsFrame> = {
         status: "working",
         state: "busy",
         config_dir: "/config/claude-personal",
-        terminal_id: "%17",
+        terminal_id: "hyoui:%17",
         terminal_namespace: "personal",
       },
+      {
+        instance,
+        pid: 9022,
+        cwd: WORKSPACE,
+        kind: "claude",
+        started_at: FIXTURE_NOW - 30_000,
+        config_dir: "/config/claude-personal",
+        terminal_id: "hyoui:%23",
+      },
     ],
     polled_at: FIXTURE_NOW,
   },
@@ -162,7 +220,7 @@ export const AGENTS_CHANGE_FRAME: Static<typeof AgentsFrame> = {
   ev: "topic",
   topic: "agents",
   instance,
-  data: { agents: [{ sid: other_sid, instance, removed: true }], polled_at: FIXTURE_NOW + 5_000 },
+  data: { agents: [{ instance, pid: 7314, removed: true }], polled_at: FIXTURE_NOW + 5_000 },
 };
 
 export const SESSION_STATUS_FRAME: Static<typeof SessionStatusFrame> = {

package/src/identifiers.ts

@@ -1,7 +1,7 @@
 import { type Static, Type } from "@sinclair/typebox";
 
 /** A session id: the uuid Claude Code gives its own session. Globally unique,
- * so it names a session across the whole cluster without an instance prefix. */
+ * so it names a session across the whole mesh without an instance prefix. */
 export const Sid = Type.String({
   $id: "Sid",
   pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
@@ -81,6 +81,21 @@ export const Mid = Type.String({
 });
 export type Mid = Static<typeof Mid>;
 
+/** A terminal a run lives in: `<scheme>:<id>`, where the scheme says whose
+ * handle the id is and the id is that system's own spelling.
+ *
+ * The scheme is what lets a client tell a handle it can open from one it
+ * cannot: `hyoui:<id>` is a terminal the gateway named in `terminal_gateway`
+ * serves, and `terminalUrl` composes the URL for it. A handle under any other
+ * scheme travels unchanged and is opened only by a client that knows that
+ * system — which is the point of naming the scheme rather than leaving a bare
+ * id every reader would have to guess the owner of. */
+export const TerminalId = Type.String({
+  $id: "TerminalId",
+  pattern: "^[a-z][a-z0-9_-]*:[^\\s]+$",
+});
+export type TerminalId = Static<typeof TerminalId>;
+
 /** Who a connection speaks as. Settled once by the greeting that opened it —
  * `hello.session`, `hello.user` or `hello.instance`, the op being what says
  * which — and fixed for the connection's life; the op attribute table's