@ccmsg/cli 0.7.0 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",
@@ -20,7 +20,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ccmsg/protocol": "1.18.0"
+    "@ccmsg/protocol": "1.20.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/instance/instance.ts

@@ -62,7 +62,7 @@ import {
   Transport,
   type UpgradeDecision,
 } from "../transport/index.ts";
-import { Mesh, MESH_PROTOCOL } from "../mesh/index.ts";
+import { Instances, Mesh, MESH_PROTOCOL } from "../mesh/index.ts";
 import {
   Gateway,
   gatewayCapabilities,
@@ -317,6 +317,7 @@ export class Instance {
   readonly #transport = new Transport();
   readonly #topics: Topics;
   readonly #sessions: Sessions;
+  readonly #instances: Instances;
   readonly #status: SessionStatus;
   readonly #transcripts: Transcripts;
   readonly #gateway: Gateway;
@@ -401,10 +402,10 @@ export class Instance {
         const stated = (data as { records?: AuthRecord[] } | undefined)?.records;
         if (Array.isArray(stated)) this.#auth.merge(stated);
       },
-      // What `peers` says about the instances is this instance's own view, so
-      // it is restated when that view moves (§7.5).
+      // The mesh view is this instance's own, so the topic that carries it is
+      // restated when that view moves (§7.5).
       changed: () => {
-        this.#sessions.refresh();
+        this.#instances.refresh();
         this.#linkMoved();
       },
     });
@@ -420,6 +421,9 @@ export class Instance {
       onActivity: () => {
         this.#sessions.refresh();
       },
+      onMoved: (sid) => {
+        this.#sessions.gatewayMoved(sid);
+      },
       log: (msg, fields) => {
         this.log.write(msg, fields);
       },
@@ -532,6 +536,15 @@ export class Instance {
       publish: (topic, data, instance) => this.#topics.publish(topic, data, instance),
     });
 
+    this.#instances = new Instances({
+      self: this.self,
+      ...(this.#mesh === undefined ? {} : { endpoint: this.#mesh.self, mesh: this.#mesh }),
+      publish: (topic, data) => {
+        this.#topics.publish(topic, data);
+      },
+    });
+
+    this.#topics.attach("instances", this.#instances);
     this.#topics.attach("peers", this.#sessions);
     this.#topics.attach("agents", this.#sessions);
     this.#topics.attach("inbox", this.#delivery);

package/src/mesh/index.ts

@@ -1,3 +1,4 @@
+export * from "./instances.ts";
 export * from "./keys.ts";
 export * from "./mesh.ts";
 export * from "./probe.ts";

package/src/mesh/instances.ts

@@ -0,0 +1,76 @@
+import { hostname } from "node:os";
+import type { Endpoint, InstanceId, InstanceInfo } from "@ccmsg/protocol";
+import type { TopicValue, UpstreamResource } from "../topics/index.ts";
+
+/** What the `instances` topic reads: the mesh as this instance sees it, which
+ * is the same view `hello` answers with. */
+export interface MeshView {
+  instances(): InstanceInfo[];
+}
+
+/** The cluster as one instance sees it, itself included.
+ *
+ * An instance with no mesh is a cluster of one and says so: it is reached at
+ * whatever it serves, which is a row without an endpoint when that is the unix
+ * socket alone rather than no row at all (contract, `InstanceInfo`).
+ *
+ * The same answer feeds `hello` and the topic, from here rather than from two
+ * places: a greeting and a subscription that disagreed about who is in the
+ * cluster would be one instance stating two views of itself. */
+export function clusterView(
+  self: InstanceId,
+  endpoint: Endpoint | undefined,
+  mesh: MeshView | undefined,
+): InstanceInfo[] {
+  return (
+    mesh?.instances() ?? [
+      {
+        id: self,
+        ...(endpoint === undefined ? {} : { endpoint }),
+        host: hostname(),
+        reachable: true,
+      },
+    ]
+  );
+}
+
+/** The `instances` topic (§7.5).
+ *
+ * A link going down reaches a subscriber where it is already listening, rather
+ * than only on its next greeting. The value is whole per instance: `reachable`
+ * is one instance's reading of every link it has, taken together, and two
+ * instances may legitimately disagree about the same link — so a frame states
+ * one sender's view entire and leaves every other sender's alone.
+ *
+ * Nothing is started or stopped by a subscription. The view exists because the
+ * mesh exists, and reading it costs a walk over the configured peers (§6.3:
+ * what subscription drives is a watch, and there is none here). */
+export class Instances implements UpstreamResource {
+  constructor(
+    private readonly deps: {
+      readonly self: InstanceId;
+      readonly endpoint?: Endpoint;
+      readonly mesh?: MeshView;
+      readonly publish: (topic: string, data: unknown) => void;
+    },
+  ) {}
+
+  view(): InstanceInfo[] {
+    return clusterView(this.deps.self, this.deps.endpoint, this.deps.mesh);
+  }
+
+  /** State the view, which the mesh asks for whenever a link moves. A frame
+   * equal to the last one goes no further than the suppression every topic
+   * shares (M5), so restating it costs nothing when nothing moved. */
+  refresh(): void {
+    this.deps.publish("instances", { instances: this.view() });
+  }
+
+  start(): void {}
+
+  stop(): void {}
+
+  snapshot(): readonly TopicValue[] {
+    return [{ instance: this.deps.self, data: { instances: this.view() } }];
+  }
+}

package/src/mesh/mesh.ts

@@ -763,7 +763,7 @@ export class Mesh {
       this.#host?.element(topic, instance as InstanceId, fields["data"]);
       return true;
     }
-    this.relay.accept(instance as InstanceId, topic, fields["data"]);
+    this.relay.accept(instance as InstanceId, topic, fields["data"], fields["snapshot"] === true);
     return true;
   }
 

package/src/mesh/relay.ts

@@ -1,40 +1,59 @@
+import type { SessionRow } from "../topics/index.ts";
 import {
-  type AgentInfo,
   type InstanceId,
   LAST_LIVE_RETENTION_MS,
-  type LastLiveSession,
-  type PeerInfo,
   PLAIN_TOPICS,
   type Sid,
   TOPIC_ATTRIBUTES,
   type Timestamp,
 } from "@ccmsg/protocol";
-import type { TopicValue } from "../topics/index.ts";
+import { Elements, type TopicValue } from "../topics/index.ts";
+
+/** The rows of sessions the whole cluster is seen through.
+ *
+ * They are `element`-granular, and an element topic is relayable only when its
+ * elements say whose they are: a row here names the instance that holds the
+ * session, so two instances' rows stand side by side under one topic name the
+ * way a whole value per instance does. `inbox` and `kv:<ns>` are elements of
+ * the same granularity and are not relayed, because their elements carry no
+ * such name — an `inbox` frame belongs to a session, not to an instance. */
+const ROW_TOPICS: readonly string[] = ["peers", "agents"];
 
 /** The topics a subscriber sees the whole cluster on.
  *
- * The per-instance whole is what makes a cluster view possible at all (§6.2):
- * a frame replaces its own instance's entries and leaves every other
- * instance's alone, so several instances can state the same topic name without
- * colliding. A topic of any other granularity has no such rule and is not
- * relayed — an `element` topic like `inbox` names one instance's topic while
- * its value belongs to a session, and a frame of it carries no way to say
- * whose it is. */
-export const CLUSTER_TOPICS: readonly string[] = PLAIN_TOPICS.filter(
-  (topic) => TOPIC_ATTRIBUTES[topic].granularity === "per_instance_whole",
-);
+ * A per-instance whole is relayable by construction (§6.2): a frame replaces
+ * its own instance's entries and leaves every other instance's alone, so
+ * several instances can state the same topic name without colliding. The rows
+ * above are relayable for the same reason read one element at a time. */
+export const CLUSTER_TOPICS: readonly string[] = [
+  ...PLAIN_TOPICS.filter((topic) => TOPIC_ATTRIBUTES[topic].granularity === "per_instance_whole"),
+  ...ROW_TOPICS,
+];
 
 /** The one topic the mesh carries that the relay does not.
  *
- * It is `element`-granular, so what travels is the entries that changed and the
- * receiver merges them by key; and it is the instances' own, so it is asked for
- * as the instance rather than on a person's behalf (DR-0001 §2.6). */
+ * It is `element`-granular and its elements are the instances' own, so it is
+ * asked for as the instance rather than on a person's behalf, and folded into
+ * the set this instance holds rather than held here (DR-0001 §2.6). */
 export const AUTH_TOPIC = "auth_records";
 
 export function isClusterTopic(topic: string): boolean {
   return CLUSTER_TOPICS.includes(topic);
 }
 
+/** Whether what a frame of this topic carries is rows to be merged rather than
+ * a value to be replaced. */
+function carriesRows(topic: string): boolean {
+  return ROW_TOPICS.includes(topic);
+}
+
+/** The rows of one frame, under the field each topic names them in. A frame
+ * that carries none is one there is nothing to merge from. */
+function rowsOf(topic: string, data: unknown): readonly SessionRow[] {
+  const field = (data as Record<string, unknown> | undefined)?.[topic];
+  return Array.isArray(field) ? (field as SessionRow[]) : [];
+}
+
 export interface RelayDeps {
   /** Hand a relayed frame to this instance's own subscribers, under the
    * instance that produced it (§7.4). */
@@ -70,19 +89,47 @@ export class Relay {
   }
 
   /** A frame a peer pushed on a topic this instance relays.
+   *
+   * `snapshot` marks the opening frame of a subscription, which carries the
+   * whole of what its instance holds rather than what changed.
    *
    * `instance` is the one that produced the value, which is not always the
    * peer it arrived from: a mesh of three relays transitively, and the frame
    * names its origin the whole way. Held under that origin, and passed on
    * unchanged — recomputing it would put the same judgement in two places
    * (§7.4). */
-  accept(instance: InstanceId, topic: string, data: unknown): void {
+  accept(instance: InstanceId, topic: string, data: unknown, snapshot = false): void {
     if (!isClusterTopic(topic)) return;
     this.#sweep();
     const held = this.#held.get(instance) ?? new Map<string, unknown>();
     this.#held.set(instance, held);
-    held.set(topic, data);
-    this.deps.publish(topic, data, instance);
+    if (!carriesRows(topic)) {
+      held.set(topic, data);
+      this.deps.publish(topic, data, instance);
+      return;
+    }
+    // A frame of rows says what changed, so what is held is the rows merged
+    // and what travels on is the part of it that said something. The same
+    // comparison the mechanism makes of a whole value, made of one element
+    // (M5) — and a frame left with no rows is not passed on at all, which is
+    // what stops a peer's restatement from becoming a frame for every local
+    // subscriber.
+    // An opening frame is the whole of what its instance holds, so it is taken
+    // as the list restated rather than as changes folded in: a row the peer no
+    // longer has is gone from it and from nowhere else, and merging would leave
+    // it here forever. What comes of that is the same kind of answer either
+    // way — the rows that told this instance something, removals included.
+    const rows = this.#rows(held, topic);
+    const stated = rowsOf(topic, data);
+    const news = snapshot ? rows.diff(stated) : rows.merge(stated);
+    if (news.length > 0) this.deps.publish(topic, { [topic]: news }, instance);
+  }
+
+  /** The rows one instance has stated on a topic, made the first time it does. */
+  #rows(held: Map<string, unknown>, topic: string): Elements {
+    const rows = (held.get(topic) as Elements | undefined) ?? new Elements();
+    held.set(topic, rows);
+    return rows;
   }
 
   /** The link to this instance is gone. What it said is kept and marked,
@@ -113,7 +160,16 @@ export class Relay {
     const values: TopicValue[] = [];
     for (const [instance, held] of this.#held) {
       const data = held.get(topic);
-      if (data !== undefined) values.push({ instance, data });
+      if (data === undefined) continue;
+      // A topic of rows is held merged, and the opening frame of a topic is
+      // its whole value — so what a fresh subscriber is handed is every row
+      // that instance has stated, in one frame of the same shape as the ones
+      // that follow it.
+      values.push(
+        carriesRows(topic)
+          ? { instance, data: { [topic]: (data as Elements).rows() } }
+          : { instance, data },
+      );
     }
     return values;
   }
@@ -121,29 +177,21 @@ export class Relay {
   /** Which instance a session belongs to, read from the cluster values the
    * peers stated (§7.3).
    *
-   * `peers` names every session an instance currently holds — connected or in
-   * `last_live` — and is checked first. A session hello has not reached yet
-   * has no row there but the harness may already know of it, so `agents` is
-   * checked next; `last_live` is the last resort for one whose instance has
-   * not stated `agents` at all. Every row names its own instance rather than
-   * the one that relayed it, so a value that travelled through a third
-   * instance still points at the session's own. */
+   * `peers` names every session an instance holds, connected and lost alike,
+   * and is checked first. A session whose greeting has not reached its
+   * instance yet has no row there while the harness may already know of it, so
+   * `agents` is checked next. Every row names its own instance rather than the
+   * one that relayed it, so a row that travelled through a third instance
+   * still points at the session's own. */
   owner(sid: Sid): InstanceId | undefined {
     this.#sweep();
-    for (const held of this.#held.values()) {
-      const value = held.get("peers") as { peers?: PeerInfo[] } | undefined;
-      const row = value?.peers?.find((peer) => peer.sid === sid);
-      if (row !== undefined) return row.instance;
-    }
-    for (const held of this.#held.values()) {
-      const value = held.get("agents") as { agents?: AgentInfo[] } | undefined;
-      const row = value?.agents?.find((agent) => agent.sid === sid);
-      if (row !== undefined) return row.instance;
-    }
-    for (const held of this.#held.values()) {
-      const value = held.get("peers") as { last_live?: LastLiveSession[] } | undefined;
-      const row = value?.last_live?.find((session) => session.sid === sid);
-      if (row !== undefined) return row.instance;
+    for (const topic of ROW_TOPICS) {
+      for (const held of this.#held.values()) {
+        const row = (held.get(topic) as Elements | undefined)
+          ?.rows()
+          .find((held) => held.sid === sid);
+        if (row !== undefined) return row.instance;
+      }
     }
     return undefined;
   }

package/src/messaging/delivery.ts

@@ -3,7 +3,6 @@ import type {
   CandidateSession,
   InboxMessage,
   InstanceId,
-  LastLiveSession,
   MessageSendArgs,
   MessageSendResult,
   Mid,
@@ -15,6 +14,7 @@ import type {
   UndeliveredReason,
 } from "@ccmsg/protocol";
 import { USER_SENDER } from "@ccmsg/protocol";
+import { isLive } from "../sessions/classify.ts";
 import {
   type DispatchResult,
   type HandlerInput,
@@ -35,7 +35,7 @@ const INBOX = "inbox";
  * the reasons of §4.2 from growing a source per reason. */
 export interface SessionLookup {
   classify(sid: Sid): SessionState | undefined;
-  peers(): { peers: PeerInfo[]; last_live: LastLiveSession[] };
+  peerRows(): PeerInfo[];
 }
 
 /** The rest of the cluster, for a message addressed outside this instance.
@@ -290,17 +290,27 @@ export class Delivery implements UpstreamResource {
   }
 
   /** Sessions live now in the repository the addressee belongs to (§4.2).
+   *
+   * The rows are one list of sessions, connected and lost alike, so which of
+   * them can be written to is the classification — asked of the domain, the
+   * same way the addressee's own reason was, rather than read off a field of
+   * the row (M1).
    *
    * The repository is `repo_root` as the session named it. A session that named
    * none is left out rather than matched on something derived from its `cwd`:
    * no primary source states that derivation, and the sessions domain does not
    * make one up either. */
   #candidates(to: Sid): CandidateSession[] {
-    const { peers, last_live } = this.deps.sessions.peers();
-    const root = [...peers, ...last_live].find((row) => row.sid === to)?.repo_root;
+    const rows = this.deps.sessions.peerRows();
+    const root = rows.find((row) => row.sid === to)?.repo_root;
     if (root === undefined) return [];
-    return peers
-      .filter((peer) => peer.sid !== to && peer.repo_root === root)
+    return rows
+      .filter(
+        (peer) =>
+          peer.sid !== to &&
+          peer.repo_root === root &&
+          isLive({ state: this.deps.sessions.classify(peer.sid) }),
+      )
       .map((peer) => ({
         sid: peer.sid,
         ...(peer.ws === "" ? {} : { ws: peer.ws }),
@@ -374,7 +384,7 @@ function callerOf(input: HandlerInput): CallerIdentity | undefined {
  * notification's subject are the same session seen from two ops, and a session
  * shown one way there and another way here would read as two. */
 export function sessionLabel(sessions: SessionLookup, sid: Sid): string {
-  const peer = sessions.peers().peers.find((row) => row.sid === sid);
+  const peer = sessions.peerRows().find((row) => row.sid === sid);
   if (peer === undefined) return sid;
   const where = [peer.repo, peer.ws].filter((part) => part !== "").join("/");
   return where === "" ? sid : where;

package/src/sessions/classify.ts

@@ -64,3 +64,15 @@ export function classify(
   if (inputs.last_live === undefined) return undefined;
   return inputs.last_live.stopped_at === undefined ? "disappeared" : "paused";
 }
+
+/** Whether a classification is one of the connected ones, which is what a row
+ * has to be for anything here to reach it.
+ *
+ * Read off the classification rather than restated: the two sections the
+ * vocabulary is divided into are the contract's own, and a second list of
+ * which words mean "still there" would be a second place for the rule to drift
+ * in (M1). A row that states none is one no section holds, which is not a
+ * session anything can be handed to. */
+export function isLive(row: { readonly state?: SessionState }): boolean {
+  return row.state !== undefined && row.state !== "paused" && row.state !== "disappeared";
+}

package/src/sessions/dump.ts

@@ -75,7 +75,10 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
     },
     deps.presets,
   );
-  const { items, entries } = select(within(classify(located(text)), args), keep);
+  const { items, entries } = select(
+    within(classify(located(text), deps.files.subjectOf(file)), args),
+    keep,
+  );
   const ids = ledger(items);
   const written_at = Date.now();
   // The file repeats what it was asked for. A dump outlives the request that

package/src/sessions/items.ts

@@ -68,7 +68,7 @@ export function itemsRead(
     throw new OpError("not_found", `the transcript of ${args.sid} could not be read`);
   }
   const keep = selection(args.types === undefined ? {} : { types: args.types }, deps.presets);
-  const { items } = select(within(classify(located(text)), args), keep);
+  const { items } = select(within(classify(located(text), deps.files.subjectOf(file)), args), keep);
   const page = paged(items, args.limit, backwards(args));
   return {
     items: page.items,

package/src/sessions/last-live.ts

@@ -3,22 +3,39 @@ import { dirname, join } from "node:path";
 import {
   LAST_LIVE_RETENTION_MS,
   type InstanceId,
-  type LastLiveSession,
+  type PeerInfo,
   type Sid,
   type Timestamp,
 } from "@ccmsg/protocol";
 
 export const LAST_LIVE_FILE = "last-live.json";
 
-/** What is stored per session: the contract's entry, minus the one field that
- * is derived rather than observed.
+/** What is stored per session: the observations a lost session's row is built
+ * from, and nothing the row derives or a connection supplies.
  *
  * `state` is left out on purpose (M4). It follows from `stopped_at` and from
  * whether the session is live again, both of which are known when the list is
  * read, so storing it would be storing a conclusion that can go stale on disk.
  * `pinned` is left out because no pin is held anywhere yet; when one is, it
- * belongs to the session rather than to this list. */
-export type StoredEntry = Omit<LastLiveSession, "state" | "pinned">;
+ * belongs to the session rather than to this list. The connection fields go
+ * with the connection there is none of.
+ *
+ * `last_seen_at` is required here while the row states it optionally: a row
+ * this store holds is by definition one this instance has lost, and when it
+ * last saw it is what the retention window is measured from. */
+export type StoredEntry = Omit<
+  PeerInfo,
+  | "state"
+  | "pinned"
+  | "last_activity_at"
+  | "last_user_input_at"
+  | "gateway_active_at"
+  | "send_message"
+  | "client_version"
+  | "protocol_version"
+  | "stale_client"
+  | "last_seen_at"
+> & { last_seen_at: Timestamp };
 
 interface Document {
   version: number;

package/src/sessions/registry.ts

@@ -1,5 +1,4 @@
 import { realpathSync, statSync } from "node:fs";
-import { hostname } from "node:os";
 import { basename, dirname, isAbsolute, join } from "node:path";
 import {
   type AgentInfo,
@@ -7,9 +6,10 @@ import {
   type HelloArgs,
   type HelloResult,
   type Endpoint,
+  type AgentElement,
   type InstanceId,
   type InstanceInfo,
-  type LastLiveSession,
+  type PeerElement,
   type PeerInfo,
   PROTOCOL_VERSION,
   type SessionState,
@@ -20,8 +20,9 @@ import {
 import { type HandlerInput, OpError, type Requester } from "../dispatch/index.ts";
 import { within } from "../files/index.ts";
 import { HARNESS, type Harness } from "../harness/index.ts";
+import { clusterView } from "../mesh/instances.ts";
 import type { TranscriptFacts } from "../transcript/index.ts";
-import type { TopicValue, UpstreamResource } from "../topics/index.ts";
+import { Elements, type TopicValue, type UpstreamResource } from "../topics/index.ts";
 import { classify, type SessionInputs } from "./classify.ts";
 import { isWaiting, type OwnSessions, ownSessions } from "./harness.ts";
 import { LastLiveStore, type StoredEntry } from "./last-live.ts";
@@ -211,6 +212,16 @@ export class Sessions implements UpstreamResource {
    * then carries on stays connected and keeps its declaration, which is spent
    * whenever it does leave. */
   readonly #stopping = new Map<Sid, Timestamp>();
+  /** What the last frame of each topic left every subscriber holding, kept
+   * whether or not anybody is subscribed.
+   *
+   * A frame carries a difference, and the difference is taken against what was
+   * sent — not against what the last listener happened to see. Which is also
+   * what makes it right for a subscriber that arrives after a spell of nobody
+   * listening: it is handed every row as a snapshot, and every frame after it
+   * says what changed since the last one went out. */
+  readonly #sentPeers = new Elements();
+  readonly #sentAgents = new Elements();
 
   constructor(private readonly deps: SessionsDeps) {
     this.#harness = ownSessions(
@@ -294,18 +305,9 @@ export class Sessions implements UpstreamResource {
       protocol_version: PROTOCOL_VERSION,
       instance: this.deps.self,
       ...(this.deps.endpoint === undefined ? {} : { endpoint: this.deps.endpoint }),
-      // Without a mesh the cluster is this instance alone, and it says so:
-      // an instance serving the unix socket alone has no URL to be dialed at,
-      // which is a row without an endpoint rather than no row (contract,
-      // `InstanceInfo`).
-      instances: this.deps.mesh?.instances() ?? [
-        {
-          id: this.deps.self,
-          ...(this.deps.endpoint === undefined ? {} : { endpoint: this.deps.endpoint }),
-          host: hostname(),
-          reachable: true,
-        },
-      ],
+      // The same view the `instances` topic carries, worked out in one place
+      // so a greeting and a subscription cannot state two different clusters.
+      instances: clusterView(this.deps.self, this.deps.endpoint, this.deps.mesh),
       capabilities: [...this.deps.capabilities],
       version: this.deps.version,
       started_at: this.deps.startedAt,
@@ -483,9 +485,21 @@ export class Sessions implements UpstreamResource {
     if (this.#wanted.size === 0) this.#harness.stop();
   }
 
+  /** What a fresh subscriber is handed: every row, connected and lost alike.
+   *
+   * A frame of either topic carries the rows that changed, so the opening one
+   * has to carry all of them — it is the only frame that states the rows a
+   * subscriber was not there for. Stating them is also what the difference
+   * after it is taken against: these rows are what the subscriber now holds,
+   * and they are the same rows every earlier subscriber was brought up to by
+   * the frames it has had. */
   snapshot(topic: string): readonly TopicValue[] {
+    const now = Date.now();
     const own = this.#own();
-    const data = topic === "agents" ? this.agents(own) : this.peers(Date.now(), own);
+    const data =
+      topic === "agents"
+        ? { agents: this.#sentAgents.stated(this.agentRows(own)), polled_at: now }
+        : { peers: this.#sentPeers.stated(this.peerRows(now, own)) };
     return [{ instance: this.deps.self, data }];
   }
 
@@ -495,9 +509,11 @@ export class Sessions implements UpstreamResource {
     return this.#harness.running;
   }
 
-  /** The `peers` payload: what is live now, and what was live when this
-   * instance last saw it. Both travel together because coming back is exactly
-   * what moves a session from the second list to the first.
+  /** Every row `peers` states: what is live now, and what was live when this
+   * instance last saw it. One kind of row rather than two lists, because
+   * coming back and going quiet are the same row changing its `state` — a
+   * client that held two lists would have to move an entry between them to
+   * follow one field.
    *
    * Live is not the same as connected (§5.2). A session the harness names is
    * live whether or not it ever greeted us, and it has to be on this list for
@@ -510,41 +526,65 @@ export class Sessions implements UpstreamResource {
    * — this instance is one that classifies, so it says so on every row rather
    * than on the rows it happens to have an answer for.
    *
-   * `instances` is the same view `hello` answers with, restated here so that a
-   * link going down reaches a subscriber on the topic it is already on rather
-   * than only on its next greeting (§7.5). It is this instance's view: what a
-   * peer relayed here carries the peer's own, and neither is folded into the
-   * other. An instance with no mesh states none, which is a different thing
-   * from stating that nothing is reachable. */
-  peers(
-    now: Timestamp = Date.now(),
-    own: Own = this.#own(),
-  ): { peers: PeerInfo[]; last_live: LastLiveSession[]; instances?: InstanceInfo[] } {
-    const instances = this.deps.mesh?.instances();
+   * A lost session is a row here rather than a list of its own: its entry in
+   * the store holds what was observed, and the two fields a row derives —
+   * where it stands now, and whether it is pinned — are worked out at read
+   * time (M4). */
+  peerRows(now: Timestamp = Date.now(), own: Own = this.#own()): PeerInfo[] {
+    return [
+      ...[...this.#connected.values()].map((session) => this.#peer(session, now, own)),
+      ...[...own.present]
+        .filter((sid) => !this.#connected.has(sid))
+        .map((sid) => this.#unconnected(sid, now, own)),
+      ...this.#lastLive.entries(now).map((entry) => this.#lost(entry, now, own)),
+    ];
+  }
+
+  /** One row of `peers`, for a producer that knows which session moved.
+   *
+   * The same three sources the list is built from, asked about one sid: a
+   * connection here, a session the harness names, an entry among the sessions
+   * this instance has lost. A sid none of them holds is one this instance has
+   * no row for, and it says so rather than inventing one. */
+  #peerRow(sid: Sid, now: Timestamp, own: Own): PeerInfo | undefined {
+    const held = this.#connected.get(sid);
+    if (held !== undefined) return this.#peer(held, now, own);
+    if (own.present.has(sid)) return this.#unconnected(sid, now, own);
+    const entry = this.#lastLive.get(sid);
+    return entry === undefined ? undefined : this.#lost(entry, now, own);
+  }
+
+  /** A session this instance has lost, as a row: what was observed of it,
+   * with the two fields a row derives worked out at read time (M4). */
+  #lost(entry: StoredEntry, now: Timestamp, own: Own): PeerInfo {
     return {
-      peers: [
-        ...[...this.#connected.values()].map((session) => this.#peer(session, now, own)),
-        ...[...own.present]
-          .filter((sid) => !this.#connected.has(sid))
-          .map((sid) => this.#unconnected(sid, now, own)),
-      ],
-      last_live: this.#lastLive.entries(now).map((entry) => ({
-        ...entry,
-        state: this.classify(entry.sid, now, own) ?? "disappeared",
-        pinned: this.#pinned(entry.sid),
-      })),
-      ...(instances === undefined ? {} : { instances }),
+      ...entry,
+      state: this.classify(entry.sid, now, own) ?? "disappeared",
+      pinned: this.#pinned(entry.sid),
     };
   }
 
-  /** The `agents` payload: the harness's own view, as it stated it.
+  /** The gateway saw inference for one session again (§5.1).
+   *
+   * What moved is one attribute of one row, so that row is what goes out. The
+   * sessions domain is not recomputed for it: which sessions there are has not
+   * changed, and the whole of that work would be spent to restate a clock.
    *
-   * `polled_at` is left out. Stating when the read behind the list ran would
-   * make every confirmation poll a value the list did not have before, so the
-   * one suppression every topic shares (M5) would let a five-second heartbeat
-   * through for a directory that had not changed. */
-  agents(own: Own = this.#own()): { agents: AgentInfo[] } {
-    return { agents: [...own.rows.values()] };
+   * A sid this instance has no row for publishes nothing. The gateway sits
+   * above every config home and its events name only a session id, so one
+   * belonging to another config home must not become a row here — the same
+   * narrowing the row's own reading of the gateway makes. */
+  gatewayMoved(sid: Sid): void {
+    const now = Date.now();
+    const row = this.#peerRow(sid, now, this.#own());
+    if (row === undefined) return;
+    const peers = this.#sentPeers.diffRow(row) as PeerElement[];
+    if (peers.length > 0) this.deps.publish("peers", { peers });
+  }
+
+  /** Every row `agents` states: the harness's own view, as it stated it. */
+  agentRows(own: Own = this.#own()): AgentInfo[] {
+    return [...own.rows.values()];
   }
 
   /** Bind a session to this instance, and take what it says about itself. Its
@@ -596,11 +636,16 @@ export class Sessions implements UpstreamResource {
     this.changed();
   }
 
-  /** Recompute, record what stopped being live, and state both topics.
+  /** Recompute, record what stopped being live, and state what moved on both
+   * topics.
    *
-   * Publishing is unconditional here because suppression belongs to the topic
-   * mechanism and is written once for every topic (M5) — a payload equal to
-   * the last one goes no further than that. */
+   * Both carry the rows that changed, so what is published is the difference
+   * against what was last published rather than the whole list: a session
+   * whose inference just ran is one row, and restating every row to say so
+   * would send a list to report one field. A recompute that found nothing
+   * different publishes nothing — the suppression every topic shares (M5) is
+   * whole-value and cannot drop a frame of elements, so the diff is where a
+   * repeat stops here. */
   private changed(now: Timestamp = Date.now()): void {
     const own = this.#own();
     const live = this.#liveNow(now, own);
@@ -622,8 +667,10 @@ export class Sessions implements UpstreamResource {
     }
     this.#reclaim(live);
     this.#live = live;
-    this.deps.publish("peers", this.peers(now, own));
-    this.deps.publish("agents", this.agents(own));
+    const peers = this.#sentPeers.diff(this.peerRows(now, own)) as PeerElement[];
+    if (peers.length > 0) this.deps.publish("peers", { peers });
+    const agents = this.#sentAgents.diff(this.agentRows(own)) as AgentElement[];
+    if (agents.length > 0) this.deps.publish("agents", { agents, polled_at: now });
     this.deps.onChanged?.();
   }
 

package/src/topics/index.ts

@@ -1,3 +1,4 @@
+export * from "./elements.ts";
 export * from "./egress.ts";
 export * from "./handlers.ts";
 export * from "./topics.ts";

package/src/transcript/files.ts

@@ -1,11 +1,17 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import type { Sid } from "@ccmsg/protocol";
+import type { Sid, TranscriptSubject } from "@ccmsg/protocol";
 import { type Harness, HARNESS } from "../harness/index.ts";
 import { OpError } from "../dispatch/index.ts";
 
 const SUFFIX = ".jsonl";
 
+/** What the harness names an agent's transcript with, and what it calls the
+ * kind of task a teammate is. Both are its own words, read where they are
+ * written rather than mirrored anywhere. */
+const AGENT_PREFIX = "agent-";
+const TEAMMATE_TASK = "in_process_teammate";
+
 /** Where one harness keeps transcripts under its config home, and how a file
  * there says which session it belongs to (§3.8).
  *
@@ -126,6 +132,37 @@ export class TranscriptFiles {
     return this.teammate(under, name(names.teammate ?? "", TEAMMATE, "teammate"));
   }
 
+  /** Which standing a transcript was written from, which every item read out
+   * of it states (§3.6).
+   *
+   * The file itself does not say whether an agent was a teammate or an errand:
+   * both are marked as sidechains and both are briefed the same way. What says
+   * so is the harness's own note beside the file — the same note a teammate is
+   * found by name in — and `taskKind` on it is the harness stating which kind
+   * of task it started. An envelope in the opening brief looks like the same
+   * answer and is not one: it is text somebody wrote, and an errand handed a
+   * quoted message carries it too.
+   *
+   * A note that is missing or unreadable leaves the question unanswered, and
+   * the answer then is `sub`: an errand is the standing that claims the least —
+   * nothing goes on standing, nobody is addressed by name — so a teammate read
+   * as one loses a name it might have been drawn under, where the reverse would
+   * have a reader write back to something that is already gone. */
+  subjectOf(file: string): TranscriptSubject {
+    const name = basename(file);
+    if (!name.startsWith(AGENT_PREFIX) || !name.endsWith(SUFFIX)) return "main";
+    let note: unknown;
+    try {
+      note = JSON.parse(
+        readFileSync(join(dirname(file), `${name.slice(0, -SUFFIX.length)}.meta.json`), "utf8"),
+      );
+    } catch {
+      return "sub";
+    }
+    const kind = (note as { taskKind?: unknown } | null)?.taskKind;
+    return kind === TEAMMATE_TASK ? "team" : "sub";
+  }
+
   /** A teammate's transcript, found by the name it is addressed by.
    *
    * The name a teammate carries in conversation is not its filename, so the

package/src/transcript/items/classify.ts

@@ -1,3 +1,4 @@
+import type { TranscriptSubject } from "@ccmsg/protocol";
 import type { Item } from "./item.ts";
 import {
   count,
@@ -84,6 +85,7 @@ const OUTSTANDING_CALLS = 4096;
 type Draft = Record<string, unknown> & {
   id: string;
   uuid: string;
+  subject: TranscriptSubject;
   source: { offset: number; bytes: number };
   type: string;
   at: number;
@@ -96,8 +98,8 @@ type Draft = Record<string, unknown> & {
  * apart the harness wrote them. Reading the whole file before any range is
  * applied is what makes `parent_item` answerable: a result inside the range
  * whose call fell before it still names the call. */
-export function classify(records: Iterable<Located>): Item[] {
-  const state = new Classification();
+export function classify(records: Iterable<Located>, subject: TranscriptSubject = "main"): Item[] {
+  const state = new Classification(subject);
   return state.readAll(records);
 }
 
@@ -117,17 +119,24 @@ export class Classification {
   #turn = 0;
   /** The last slash command invoked, which is what its output belongs to. */
   #slash: string | undefined;
-  /** Whose file this is, which decides who is at the other end of a plain
-   * line. A session's own transcript has a person there; a file written for an
-   * agent has whoever started it, and calling that `user` would have a reader
-   * take a machine for a person.
+  /** Whose file this is, which every item states and which decides who is at
+   * the other end of a plain line. A session's own transcript has a person
+   * there; a file written for an agent has whoever started it, and calling that
+   * `user` would have a reader take a machine for a person.
    *
-   * The file says so itself — every record of an agent's transcript is marked
-   * as one — so nothing has to be passed in beside it. It is remembered once
-   * seen rather than read per record: a file is one subject's throughout, and a
-   * record that omitted the mark would otherwise change who the subject is
-   * mid-read. */
-  #subject: "session" | "agent" = "session";
+   * It is told rather than read out of the records, because what tells a
+   * teammate from an errand is not in the transcript at all: the harness states
+   * it beside the file, and whoever opened the file has already read that (§3.6).
+   *
+   * A record marked as a sidechain inside a file opened as a session's own says
+   * the file is an agent's after all, and the reading moves to `sub` — the
+   * standing that claims the least. It only ever narrows: a reading told which
+   * agent's file it has is not talked out of it by the records. */
+  #subject: TranscriptSubject;
+
+  constructor(subject: TranscriptSubject = "main") {
+    this.#subject = subject;
+  }
 
   /** The records of one chunk as the items they were read as, oldest first.
    *
@@ -158,7 +167,7 @@ export class Classification {
   read(record: Row, source: { offset: number; bytes: number }): void {
     const type = str(record["type"]);
     if (type === undefined || NOT_ITEMS.has(type)) return;
-    if (record["isSidechain"] === true) this.#subject = "agent";
+    if (record["isSidechain"] === true && this.#subject === "main") this.#subject = "sub";
     // A record the harness wrote without an id of its own still happened, and
     // an item is pointed at by the record it came from — so where the record
     // stands in the file stands in for the id it lacks. The `@` says which of
@@ -174,6 +183,7 @@ export class Classification {
       const draft: Draft = {
         id: `${uuid}:${String(index)}`,
         uuid,
+        subject: this.#subject,
         source,
         type: kind,
         at,
@@ -255,7 +265,7 @@ export class Classification {
         // them is the answer it was started for, and the ones before are what
         // it hands back mid-flight. No call carries them, which is why
         // `parent:out` is prose as well as a call.
-        const kind = this.#subject === "agent" ? "message:parent:out" : "message:user:out";
+        const kind = this.#subject === "main" ? "message:user:out" : "message:parent:out";
         if (said !== undefined && said !== "") make(kind, { text: said });
         continue;
       }
@@ -473,9 +483,9 @@ export class Classification {
     // stands, being told what to do is not the same as being written to.
     if (record["parentUuid"] === null) {
       this.#turn += 1;
-      make(this.#subject === "agent" ? "message:parent:in" : "message:user:in", {
+      make(this.#subject === "main" ? "message:user:in" : "message:parent:in", {
         text: said,
-        ...(this.#subject === "agent" ? envelope(said) : {}),
+        ...(this.#subject === "main" ? {} : envelope(said)),
       });
       return;
     }

package/src/upstream/gateway.ts

@@ -114,6 +114,9 @@ export interface GatewayDeps {
   /** The gateway saw something happen for a session, which is an input of the
    * sessions domain (§5.1) rather than of either topic. */
   readonly onActivity?: () => void;
+  /** A session already known to be running was seen again: its clock moved,
+   * and the row that carries it is what says so. */
+  readonly onMoved?: (sid: Sid) => void;
   readonly log?: (msg: string, fields?: Record<string, unknown>) => void;
   /** Replaces the outward read in tests. */
   readonly fetch?: typeof fetch;
@@ -139,6 +142,7 @@ export class Gateway {
       self: deps.self,
       publish: deps.publish,
       ...(deps.onActivity === undefined ? {} : { onActivity: deps.onActivity }),
+      ...(deps.onMoved === undefined ? {} : { onMoved: deps.onMoved }),
     });
     this.status =
       deps.setup.statusUrl === undefined

package/src/upstream/requests.ts

@@ -14,10 +14,25 @@ export interface LlmRequestsDeps {
   /** The one way a value reaches subscribers (§6.1). */
   readonly publish: (topic: string, data: unknown) => void;
   /** An event moved when a session was last seen running inference, which is
-   * an input of the sessions domain (§5.1) and not of this topic. */
+   * an input of the sessions domain (§5.1) and not of this topic. Told when
+   * the window opened, which is the moment the classification can change. */
   readonly onActivity?: () => void;
+  /** The same session seen again inside a window already open: one attribute
+   * of one row moved. Told apart from the above because what it asks for is
+   * that row restated rather than the whole domain recomputed. */
+  readonly onMoved?: (sid: Sid) => void;
 }
 
+/** Which of a session's gateway facts moved.
+ *
+ * `live` is the moment the classification of §5.1 can change, because the
+ * window either opened or closed, and the sessions domain recomputes for it.
+ * `clock` is the same session seen again inside a window that was already open
+ * — the value of an attribute, not a section anything is in — so what it asks
+ * for is that one row restated. Both reach a subscriber; they differ in how
+ * much work is done to say so. */
+type GatewayMove = "live" | "clock" | "none";
+
 /** Series remembered at once. The prune below already holds this near the
  * number active in the last cache window; the cap is what bounds a gateway
  * whose clock runs ahead, whose events would otherwise never expire. */
@@ -69,7 +84,7 @@ export class LlmRequests implements UpstreamResource {
    * near-ordered in practice, but a redelivery can put an older one after a
    * newer, and a countdown must not walk backwards. */
   record(info: LlmRequestObservation): void {
-    this.active(info.sid, info.received_at);
+    this.moved(info.sid, this.active(info.sid, info.received_at));
     const key = seriesKey(info.sid, info.prefix);
     const held = this.#series.get(key);
     if (held !== undefined && held.info.received_at >= info.received_at) return;
@@ -91,7 +106,13 @@ export class LlmRequests implements UpstreamResource {
    * the window belongs to the request that opened it — and only says the
    * session was still running inference at that instant. */
   note(sid: Sid, at: Timestamp): void {
-    if (this.active(sid, at)) this.deps.onActivity?.();
+    this.moved(sid, this.active(sid, at));
+  }
+
+  /** Tell whoever holds the row what this event moved for that session. */
+  private moved(sid: Sid, move: GatewayMove): void {
+    if (move === "live") this.deps.onActivity?.();
+    else if (move === "clock") this.deps.onMoved?.(sid);
   }
 
   /** When the gateway last saw inference for a session (§5.1). Undefined once
@@ -136,21 +157,31 @@ export class LlmRequests implements UpstreamResource {
 
   private publish(): void {
     this.deps.publish("llm_requests", this.entries());
-    this.deps.onActivity?.();
   }
 
-  /** Note the session was seen, and say whether that moved it forward. */
-  private active(sid: Sid, at: Timestamp): boolean {
+  /** Note the session was seen, and say what that moved.
+   *
+   * A session already inside its window moves its clock and nothing else, so
+   * the row it lands on is restated on its own: inference is observed several
+   * times a second, and recomputing the domain for each would spend the whole
+   * of that work on one attribute of one row (§5.2). */
+  private active(sid: Sid, at: Timestamp): GatewayMove {
     const held = this.#activeAt.get(sid);
-    if (held !== undefined && held >= at) return false;
+    if (held !== undefined && held >= at) return "none";
+    const wasLive = held !== undefined && at - held <= GATEWAY_LIVE_WINDOW_MS;
     this.#activeAt.set(sid, at);
     // Sessions the gateway has not seen for longer than the window go: what is
     // left is what any of this can still say something about.
-    const floor = at - GATEWAY_LIVE_WINDOW_MS;
+    this.prune(at);
+    return wasLive ? "clock" : "live";
+  }
+
+  /** Drop the sessions whose window has closed. */
+  private prune(now: Timestamp): void {
+    const floor = now - GATEWAY_LIVE_WINDOW_MS;
     for (const [seen, when] of this.#activeAt) {
       if (when < floor) this.#activeAt.delete(seen);
     }
-    return true;
   }
 
   private notePrefix(info: LlmRequestObservation): void {