@ccmsg/protocol 1.23.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/protocol",
-  "version": "1.23.0",
+  "version": "2.0.0",
   "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
   "license": "MIT",
   "author": "kawaz",

package/src/attributes.ts

@@ -197,7 +197,7 @@ export const OP_ATTRIBUTES = {
     roles: AGENT_AND_USER,
     needs_hello: true,
     locality: "any_instance",
-    errors: ["session_not_found"],
+    errors: ["session_not_found", "session_duplicated"],
   },
   "say.post": {
     plane: "messaging",
@@ -218,7 +218,7 @@ export const OP_ATTRIBUTES = {
     roles: AGENT_AND_USER,
     needs_hello: true,
     locality: "any_instance",
-    errors: ["rate_limited"],
+    errors: ["rate_limited", "session_duplicated"],
   },
 
   // --- control: session observation and operation (10) ---
@@ -227,7 +227,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: ["session_not_found"],
+    errors: ["session_not_found", "ambiguous_run"],
   },
   "session.rename": {
     plane: "control",
@@ -256,7 +256,7 @@ export const OP_ATTRIBUTES = {
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: ["not_found"],
+    errors: ["not_found", "session_duplicated"],
   },
   "dump.presets.read": {
     plane: "control",
@@ -304,7 +304,7 @@ export const OP_ATTRIBUTES = {
     needs_hello: true,
     locality: "owner_instance",
     scope: "role",
-    errors: ["path_forbidden", "not_found"],
+    errors: ["path_forbidden", "not_found", "session_duplicated"],
   },
   "file.read": {
     plane: "control",
@@ -312,49 +312,49 @@ export const OP_ATTRIBUTES = {
     needs_hello: true,
     locality: "owner_instance",
     scope: "role",
-    errors: ["path_forbidden", "not_found"],
+    errors: ["path_forbidden", "not_found", "session_duplicated"],
   },
   "file.write": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: ["path_not_writable", "file_exists"],
+    errors: ["path_not_writable", "file_exists", "session_duplicated"],
   },
   "file.create": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: ["file_exists", "path_forbidden"],
+    errors: ["file_exists", "path_forbidden", "session_duplicated"],
   },
   "file.edit": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: ["file_conflict", "not_a_text_file"],
+    errors: ["file_conflict", "not_a_text_file", "session_duplicated"],
   },
   "file.delete": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: ["path_forbidden", "not_found"],
+    errors: ["path_forbidden", "not_found", "session_duplicated"],
   },
   "file.find": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: ["path_forbidden"],
+    errors: ["path_forbidden", "session_duplicated"],
   },
   "file.stat": {
     plane: "control",
     roles: USER_ONLY,
     needs_hello: true,
     locality: "owner_instance",
-    errors: [],
+    errors: ["session_duplicated"],
   },
   "dir.tree": {
     plane: "control",

package/src/common/hello.ts

@@ -66,6 +66,16 @@ export const HelloSessionArgs = Type.Object({
   ...GREETING_FIELDS,
   /** The session the connection speaks for. */
   sid: Sid,
+  /** The harness process running this session. Where the greeting is carried by
+   * something standing in for the session — a hook, the CLI — it is the parent
+   * harness process's pid and not the helper's: what this names is the run, and
+   * the helper is not one.
+   *
+   * It is what ties this session to a process a launcher started before the
+   * harness had written anything of its own, and what lets two runs of one
+   * session be told apart. Optional: a session that cannot read it is greeted
+   * anyway, and the instance then knows the run by its connection alone. */
+  pid: Type.Optional(Type.Integer({ minimum: 1 })),
   /** What the session says about itself. All optional: a session states what it
    * knows, and the instance derives or leaves unknown what it is not told. The
    * instance repeats these on the `peers` topic, so they are the same fields
@@ -141,11 +151,11 @@ export const HelloResult = Type.Object({
   version: Type.String(),
   started_at: Timestamp,
   /** Where a person opens the terminal a session runs in: the base URL of the
-   * gateway that fronts this instance's terminals. A session's terminal names
-   * itself in `terminal_id` on the `agents` topic, and the gateway's URL for it
-   * is `<terminal_gateway>/sessions/<terminal_id>` — so the base URL carries no
-   * trailing slash, the path below it being the gateway's spelling and not this
-   * contract's.
+   * gateway that fronts this instance's terminals. A run's terminal names
+   * itself in `terminal_id`, and `terminalUrl` below composes the URL from the
+   * two — only for a handle under the `hyoui` scheme, this gateway serving no
+   * other. The base URL carries no trailing slash, the path below it being the
+   * gateway's spelling and not this contract's.
    *
    * Stated by the instance because only it knows which gateway stands in front
    * of the machine its sessions run on; a client has no way to derive one from
@@ -164,6 +174,29 @@ export const HelloResult = Type.Object({
 });
 export type HelloResult = Static<typeof HelloResult>;
 
+/** The terminal scheme the gateway in `terminal_gateway` serves. */
+export const HYOUI_TERMINAL_SCHEME = "hyoui";
+
+/** Where a person opens a run's terminal, or nothing.
+ *
+ * Nothing when the gateway is absent, and nothing when the handle is under
+ * another scheme: a handle names whose terminal it is, and composing this URL
+ * for one the gateway does not serve would hand a person a link to a page that
+ * is not there. A client holding such a handle opens it the way that system
+ * does, or leaves it unopened.
+ *
+ * Composed here rather than once per client, so the one place that knows both
+ * the scheme and the gateway's path is this contract. */
+export function terminalUrl(
+  gateway: string | undefined,
+  terminalId: string | undefined,
+): string | undefined {
+  if (gateway === undefined || terminalId === undefined) return undefined;
+  const prefix = `${HYOUI_TERMINAL_SCHEME}:`;
+  if (!terminalId.startsWith(prefix)) return undefined;
+  return `${gateway}/sessions/${terminalId.slice(prefix.length)}`;
+}
+
 export const HelloSessionRequest = request("hello.session", HelloSessionArgs);
 export const HelloSessionResponse = response("hello.session", HelloResult);
 

package/src/control/agents.ts

@@ -1,19 +1,26 @@
 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 { upstream } from "../upstream.ts";
 
-/** One session as the harness itself reports it, noted with which config home
- * it was found under.
+/** One run of a session — one process — as the harness itself reports it, noted
+ * with which config home it was found under.
  *
  * This is the harness's view rather than the instance's: it covers sessions
  * that never connected here, and it carries what only the process knows — its
  * pid, its terminal, the title the session gave itself. The instance renames
  * the fields as it copies them in; the words inside them stay the harness's,
- * which is why the status-like fields are open sets. */
+ * which is why the status-like fields are open sets.
+ *
+ * A row is one process and is matched by `instance` and `pid`, never by `sid`:
+ * two processes may be running one session, and a launcher's process is here
+ * before it has a session at all. */
 export const AgentInfo = Type.Object(
   {
-    sid: Sid,
+    /** The session this process is running. Absent on a process a launcher
+     * started that the harness has not yet named a session for — it has a
+     * terminal and a start, and nothing to attach them to yet. */
+    sid: Type.Optional(Sid),
     /** The instance that polled it, and whose host the pid belongs to. */
     instance: InstanceId,
     pid: Type.Integer({ minimum: 1 }),
@@ -39,7 +46,7 @@ export const AgentInfo = Type.Object(
      * into. Absent when the process does not name one or its environment could
      * not be read. Read from the running process rather than remembered from
      * when it started, since resuming a session gives it a new process. */
-    terminal_id: Type.Optional(Type.String()),
+    terminal_id: Type.Optional(TerminalId),
     /** Which namespace that terminal lives in. Absent means the process set
      * none, which the multiplexer treats as its default — not the instance's
      * own namespace, which can differ. Typing into the wrong namespace reports a
@@ -50,13 +57,15 @@ export const AgentInfo = Type.Object(
 );
 export type AgentInfo = Static<typeof AgentInfo>;
 
-/** A row that is gone: the harness no longer reports this session, or the
- * instance that polled it stopped. Marked rather than absent, since a frame
- * carries only what changed. */
+/** A row that is gone: the process ended, or the instance that polled it
+ * stopped. Marked rather than absent, since a frame carries only what changed.
+ *
+ * It names the pid and not the session: the session may well still be there,
+ * with another process running it. */
 export const AgentRemoved = Type.Object(
   {
-    sid: Sid,
     instance: InstanceId,
+    pid: Type.Integer({ minimum: 1 }),
     removed: Type.Literal(true),
   },
   { $id: "AgentRemoved" },
@@ -67,7 +76,7 @@ export const AgentElement = Type.Union([AgentInfo, AgentRemoved], { $id: "AgentE
 export type AgentElement = Static<typeof AgentElement>;
 
 /** The `agents` topic. Elements, like `peers`: the rows that changed since the
- * last frame, matched by their `instance` and `sid`.
+ * last frame, matched by their `instance` and `pid`.
  *
  * The instance polls the harness only while somebody is listening here, so the
  * list is as fresh as the subscription is old — and a poll that finds one

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 { 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. */

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.

package/src/errors.ts

@@ -46,6 +46,16 @@ export const ERROR_CODES = [
   "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",

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/topics.ts

@@ -74,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> = {
@@ -90,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,
@@ -102,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",
@@ -115,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",
@@ -125,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 },
     ],
   },
@@ -169,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,
   },
@@ -182,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

@@ -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