@ccmsg/cli 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "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.22.0"
+    "@ccmsg/protocol": "1.23.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.0",

package/src/auth/auth.ts

@@ -488,7 +488,7 @@ export class Auth {
    * Only its issuer can say, because only the issuer holds the secret that
    * signed it — and the six digits are held beside that secret. So the digits
    * travel there unjudged: an instance that decided them itself would let
-   * somebody spread guesses across the cluster without any of them counting
+   * somebody spread guesses across the mesh without any of them counting
    * against the URL (contract, `AuthResolveArgs`). Nothing is spent here.
    *
    * The claims come back from the issuer having been checked and consumed, and

package/src/auth/records.ts

@@ -127,7 +127,7 @@ export class AuthRecords {
     }
   }
 
-  /** Write one record of this instance's own, and tell the cluster.
+  /** Write one record of this instance's own, and tell the mesh.
    *
    * A local write always displaces what the key holds. Last-write-wins settles
    * a disagreement between instances; this is not one — the writer is the

package/src/cli.ts

@@ -434,7 +434,7 @@ const ROOT: Command = {
     {
       name: "dump",
       summary: "セッション (か配下の worker 1 体) の transcript を型ごとの表示で書き出す",
-      usage: "ccmsg dump <sid>[/agent-<id>] [--preset <名前>] [--types <選択>]",
+      usage: "ccmsg dump <sid>[/agent-<id>] [--preset <名前>] [--types <選択>] [--format <形式>]",
       options: [
         ["--preset <名前>", "instance が持つ選択 (ccmsg dump presets で一覧)"],
         ["--types <選択>", "型をカンマ区切りで。prefix 可、-で除外、@名前で preset 展開"],
@@ -444,6 +444,10 @@ const ROOT: Command = {
         ],
         ["--until <at|ago|uuid>", "上限。同上"],
         ["--max-chars <n>", "1 アイテムの本文をこの文字数で切る (既定は切らない)"],
+        [
+          "--format <形式>",
+          "instance に書かせる形式: items (型付き JSON) / records (元の jsonl) / text (markdown)",
+        ],
         ["--json", "markdown ではなく dump file の中身をそのまま出す"],
         ["--out <path>", "標準出力ではなくこの path に書く"],
       ],
@@ -1181,7 +1185,7 @@ function agents(args: readonly string[]): Promise<unknown> {
   });
 }
 
-/** Read the current value of a cluster topic and answer with it.
+/** Read the current value of a mesh topic and answer with it.
  *
  * One entry per instance, carrying the topic's payload exactly as the contract
  * defines it: a whole value per instance is not something to merge into one
@@ -1221,7 +1225,11 @@ async function topic(
  *
  * `--json` hands over the file as it stands, for a reader that is a program. */
 async function dump(args: readonly string[]): Promise<unknown> {
-  const parsed = options(args, ["preset", "types", "since", "until", "out", "max-chars"], ["json"]);
+  const parsed = options(
+    args,
+    ["preset", "types", "since", "until", "out", "max-chars", "format"],
+    ["json"],
+  );
   const subject = parsed.rest[0];
   if (subject === undefined) {
     throw new CommandError(
@@ -1234,6 +1242,11 @@ async function dump(args: readonly string[]): Promise<unknown> {
     ...dumpArgs(subject, parsed.named),
   })) as unknown as SessionDumpWriteResult;
   const body = readFileSync(written.path, "utf8");
+  // A format the instance was asked for is a file it wrote for that purpose,
+  // so it is handed over as it stands: rendering it again here would be this
+  // command deciding what a caller already decided.
+  const format = parsed.named.get("format");
+  if (format !== undefined) return await handed(body, parsed.named.get("out"));
   // What the heading states is where the cut fell, not the words it was asked
   // for in: a dump read next week cannot work out what "10 minutes ago" was.
   const since = spelled(resolved("since", parsed.named.get("since")));
@@ -1269,6 +1282,16 @@ async function dump(args: readonly string[]): Promise<unknown> {
  * two apart so that a sid stays a validated sid, and the joined spelling is
  * the CLI's own convenience — it is how the file the agent's records live in
  * is named, which is what makes the two halves tellable apart by eye. */
+/** Write out what the instance wrote, wherever the caller wanted it. */
+async function handed(body: string, out: string | undefined): Promise<undefined> {
+  if (out === undefined) {
+    process.stdout.write(body.endsWith("\n") ? body : `${body}\n`);
+    return undefined;
+  }
+  await Bun.write(out, body);
+  return undefined;
+}
+
 export function dumpArgs(
   subject: string,
   named: ReadonlyMap<string, string> = new Map(),
@@ -1278,8 +1301,13 @@ export function dumpArgs(
   const agent = at === -1 ? undefined : subject.slice(at + AGENT_MARK.length);
   const types = named.get("types");
   const preset = named.get("preset");
+  const format = named.get("format");
+  if (format !== undefined && format !== "items" && format !== "records" && format !== "text") {
+    throw new CommandError("invalid_args", "--format は items / records / text のどれかです");
+  }
   return {
     sid,
+    ...(format === undefined ? {} : { format }),
     ...(agent === undefined || agent === "" ? {} : { agent_id: agent }),
     ...(preset === undefined ? {} : { preset }),
     ...(types === undefined
@@ -1418,16 +1446,21 @@ function reply(args: readonly string[]): Promise<unknown> {
  * line on the page they are watching, and the machine saying it aloud. Both
  * run whatever the tool itself decided to do with it. */
 export async function notify(args: readonly string[], read?: Read): Promise<unknown> {
-  const parsed = options(args, ["sid", "about"], ["hook"]);
+  const parsed = options(args, ["sid", "about", "reply-to"], ["hook"]);
   if (parsed.flags.has("hook")) return await pushed(await hookEvent(read));
   const [text] = parsed.rest;
   if (text === undefined) {
-    throw new CommandError("invalid_args", "使い方: ccmsg notify <text> [--about <sid>] | --hook");
+    throw new CommandError(
+      "invalid_args",
+      "使い方: ccmsg notify <text> [--about <sid>] [--reply-to <mid>] | --hook",
+    );
   }
   const about = parsed.named.get("about");
+  const answering = parsed.named.get("reply-to");
   return await announce(parsed.named.get("sid"), {
     text,
     ...(about === undefined ? {} : { sid: about }),
+    ...(answering === undefined ? {} : { reply_to: answering as NotifySendArgs["reply_to"] }),
   });
 }
 

package/src/daemon/snapshot.ts

@@ -6,7 +6,7 @@ import { CommandError } from "./link.ts";
  *
  * The pair rather than the payload alone, because two instances state the same
  * topic name: a payload with the name of its author taken off could not be told
- * from the other's, and which instance said it is half of what a cluster read
+ * from the other's, and which instance said it is half of what a mesh read
  * answers. */
 export interface Snapshot {
   readonly instance: InstanceId;
@@ -31,7 +31,7 @@ interface Frame {
   readonly data?: unknown;
 }
 
-/** What a greeting answered, as the two fields a cluster read needs of it. */
+/** What a greeting answered, as the two fields a mesh read needs of it. */
 interface Greeted {
   readonly instance?: unknown;
   readonly instances?: unknown;
@@ -92,7 +92,7 @@ export async function snapshots(
   return [...held].map(([instance, data]) => ({ instance, data }));
 }
 
-/** The instances a greeting named, as the set a read of a cluster topic waits
+/** The instances a greeting named, as the set a read of a mesh topic waits
  * for.
  *
  * `all` is every instance the answering one can currently reach, itself

package/src/dispatch/dispatch.ts

@@ -14,11 +14,11 @@ import { type DispatchResult, failure, OpError, reply } from "./result.ts";
 /** What dispatch needs from the instance around it. */
 export interface DispatchDeps {
   /** This instance's own id, compared with the destination of an
-   * `instance-local` op to decide whether the op is ours to run. */
+   * `owner_instance` op to decide whether the op is ours to run. */
   readonly self: InstanceId;
   /** The capabilities this instance has, as `hello` reports them. */
   readonly capabilities: ReadonlySet<Capability>;
-  /** The instance that owns the subject of an `instance-local` op, or
+  /** The instance that owns the subject of an `owner_instance` op, or
    * `undefined` when no other instance owns it and we answer ourselves.
    * The routing table behind this is the `peers` topic (DESIGN §7.3). */
   readonly resolveInstance: (op: OpName, frame: Record<string, unknown>) => InstanceId | undefined;
@@ -97,7 +97,7 @@ export async function dispatch(
     );
   }
 
-  // 6. an instance-local op whose subject belongs elsewhere goes to mesh.
+  // 6. an owner_instance op whose subject belongs elsewhere goes to mesh.
   //
   // A request that has already been here is dropped before that: a cycle in
   // the routing would otherwise send it round the same instances until every
@@ -108,7 +108,7 @@ export async function dispatch(
   if (Array.isArray(hops) && hops.includes(deps.self)) {
     return failure(requestId, "instance_unreachable", `${op} came back to ${deps.self}`);
   }
-  if (attrs.locality === "instance-local") {
+  if (attrs.locality === "owner_instance") {
     const asked = fields["to_instance"];
     const target = typeof asked === "string" ? asked : deps.resolveInstance(op, fields);
     if (target !== undefined && target !== deps.self) {

package/src/instance/instance.ts

@@ -423,7 +423,7 @@ export class Instance {
           : { terminal_gateway: config.upstream.terminal_gateway }),
       }),
     ]);
-    // The mesh is the rest of the cluster as the topic mechanism sees it: what
+    // The mesh is the rest of the mesh as the topic mechanism sees it: what
     // the peers have stated, and where a local subscription has to travel to
     // (DESIGN §7.4). An instance without one has no other instance to hear from.
     this.#topics = new Topics(this.self, this.#capabilities, this.#mesh);
@@ -561,7 +561,7 @@ export class Instance {
     this.#delivery = new Delivery({
       self: this.self,
       sessions: this.#sessions,
-      ...(this.#mesh === undefined ? {} : { cluster: this.#mesh }),
+      ...(this.#mesh === undefined ? {} : { mesh: this.#mesh }),
       inbox,
       direct: this.#direct,
       publish: (topic, data, instance, to) => this.#topics.publish(topic, data, instance, to),
@@ -604,7 +604,7 @@ export class Instance {
     });
     this.#topics.attach("kv", kv);
 
-    // The credentials, tokens and removals the cluster shares (DR-0001 §2.6).
+    // The credentials, tokens and removals the mesh shares (DR-0001 §2.6).
     // Written down beside the store and for the same reason: none of it is
     // derived from anything else this instance holds (DESIGN §2.5).
     const records = new AuthRecords({
@@ -860,7 +860,7 @@ export class Instance {
 
   /** A link came up or went down. Told to every client when it changes what
    * the instance would answer about the host link, and to nobody when the set
-   * of reachable peers moved without changing that — a five-peer cluster
+   * of reachable peers moved without changing that — a five-peer mesh
    * losing one is not this host going offline. */
   #linkMoved(): void {
     const network = this.network;
@@ -945,11 +945,11 @@ export class Instance {
       : await this.#mesh.forward(decided.to, decided.frame, stated ?? callerOfIdentity(identity));
   }
 
-  /** Which instance owns the subject of an instance-local op.
+  /** Which instance owns the subject of an owner_instance op.
    *
    * The subject is the session an op names, and an op that names none is about
    * this instance and stays here. A session this instance holds is its own
-   * whatever the cluster last said; one it does not hold is looked for in the
+   * whatever the mesh last said; one it does not hold is looked for in the
    * routing table the `peers` topic is (DESIGN §7.3). */
   #owner(fields: Record<string, unknown>): InstanceId | undefined {
     const sid = fields["sid"];

package/src/mesh/instances.ts

@@ -8,16 +8,16 @@ export interface MeshView {
   instances(): InstanceInfo[];
 }
 
-/** The cluster as one instance sees it, itself included.
+/** The mesh as one instance sees it, itself included.
  *
- * An instance with no mesh is a cluster of one and says so: it is reached at
+ * An instance with no mesh is a mesh 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(
+ * mesh would be one instance stating two views of itself. */
+export function meshView(
   self: InstanceId,
   endpoint: Endpoint | undefined,
   mesh: MeshView | undefined,
@@ -56,7 +56,7 @@ export class Instances implements UpstreamResource {
   ) {}
 
   view(): InstanceInfo[] {
-    return clusterView(this.deps.self, this.deps.endpoint, this.deps.mesh);
+    return meshView(this.deps.self, this.deps.endpoint, this.deps.mesh);
   }
 
   /** State the view, which the mesh asks for whenever a link moves. A frame

package/src/mesh/mesh.ts

@@ -18,7 +18,7 @@ import {
   type SettledIdentity,
 } from "../dispatch/index.ts";
 import type { TopicValue } from "../topics/index.ts";
-import { AUTH_TOPIC, isClusterTopic, Relay } from "./relay.ts";
+import { AUTH_TOPIC, isMeshTopic, Relay } from "./relay.ts";
 import {
   ALLOWED_ALGS,
   EphemeralKey,
@@ -388,7 +388,7 @@ export class Mesh {
    * whether it can be reached right now (DESIGN §7.5).
    *
    * A peer no handshake has settled yet is listed without an id. The operator
-   * configured that endpoint, so it is an entry of the cluster whether or not
+   * configured that endpoint, so it is an entry of the mesh whether or not
    * anything has answered there — and leaving it out would hide exactly the
    * peer whose link is down, which is the one a reader is looking for. */
   instances(): InstanceInfo[] {
@@ -408,7 +408,7 @@ export class Mesh {
 
   /** Whether any peer is currently out of reach.
    *
-   * What separates "no instance in the cluster knows this session" from "an
+   * What separates "no instance in the mesh knows this session" from "an
    * instance that might know it cannot be asked" — the one distinction DESIGN §6.6
    * says rests on the mesh's connection state and on nothing else. */
   anyUnreachable(): boolean {
@@ -417,7 +417,7 @@ export class Mesh {
 
   /** Which instance should answer for a session this instance does not hold.
    *
-   * A session the cluster has named belongs to the instance its `peers` row
+   * A session the mesh has named belongs to the instance its `peers` row
    * states. One nobody has named while a peer is out of reach is answered with
    * that peer: forwarding there fails and the caller is told
    * `instance_unreachable`, which is what DESIGN §6.6 asks for in place of deciding
@@ -532,7 +532,7 @@ export class Mesh {
    *
    * The caller the envelope names, on the link it arrived over. A request that
    * names none is dispatched as the link itself, whose role is `instance` —
-   * which the attribute table already answers, since no instance-local op is
+   * which the attribute table already answers, since no owner_instance op is
    * open to an instance. */
   caller(conn: Requester, caller: CallerIdentity | undefined): Requester {
     const link = this.#linkOf.get(conn);
@@ -553,12 +553,12 @@ export class Mesh {
 
   /** The current value of a relayed topic, one entry per instance that has
    * stated one. Handed to a fresh local subscriber beside this instance's own
-   * snapshot, so it opens on the cluster rather than on us. */
+   * snapshot, so it opens on the mesh rather than on us. */
   snapshot(topic: string): readonly TopicValue[] {
     return this.relay.snapshot(topic);
   }
 
-  /** A local subscriber appeared on a cluster topic, or the last one left.
+  /** A local subscriber appeared on a mesh topic, or the last one left.
    *
    * The subscription travels: what a subscriber asks of this instance, this
    * instance asks of every peer, and the frames come back unchanged (DESIGN §7.4).
@@ -567,7 +567,7 @@ export class Mesh {
     // `auth.records` is never given up and never asked for on demand: every
     // instance holds the whole set whether or not anything local is watching
     // it, the way `peers` is also the routing table (DESIGN §7.4, DR-0001 §2.6).
-    if (topic === AUTH_TOPIC || !isClusterTopic(topic)) return;
+    if (topic === AUTH_TOPIC || !isMeshTopic(topic)) return;
     if (wanted) {
       if (this.#demanded.has(topic)) return;
       this.#demanded.add(topic);
@@ -593,7 +593,7 @@ export class Mesh {
       topic,
       // The instance asks on behalf of whoever subscribed to it, and what they
       // have in common is that they are this deployment's people rather than
-      // any one session: a cluster topic is the same value for all of them
+      // any one session: a mesh topic is the same value for all of them
       // (DESIGN §6.2), so there is nothing narrower to name.
       //
       // `auth.records` is the exception, and the one topic no person may hear:
@@ -1090,12 +1090,12 @@ export class Mesh {
     //
     // The far end has no other way to learn this instance is going: it would
     // keep the link, keep answering `reachable`, and keep routing
-    // `instance-local` ops here until its own heartbeat gave up minutes later,
+    // `owner_instance` ops here until its own heartbeat gave up minutes later,
     // where the disconnection of DESIGN §7.5 is supposed to be immediate. Which side
     // dialled a link is decided by the glare rule from a comparison of
     // endpoint strings (mesh-peer-auth §8.1), so which of a peer's links this instance
     // accepted is not something either end chose — leaving those open makes a
-    // clean stop look like a silent one to whichever half of the cluster the
+    // clean stop look like a silent one to whichever half of the mesh the
     // comparison put on this side.
     //
     // An accepted socket is transport's to release (DESIGN §8.5 step 5), and left to

package/src/mesh/relay.ts

@@ -9,7 +9,7 @@ import {
 } from "@ccmsg/protocol";
 import { Elements, type TopicValue } from "../topics/index.ts";
 
-/** The rows of sessions the whole cluster is seen through.
+/** The rows of sessions the whole mesh 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
@@ -19,13 +19,13 @@ import { Elements, type TopicValue } from "../topics/index.ts";
  * 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 topics a subscriber sees the whole mesh on.
  *
  * A per-instance whole is relayable by construction (DESIGN §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[] = [
+export const MESH_TOPICS: readonly string[] = [
   ...PLAIN_TOPICS.filter((topic) => TOPIC_ATTRIBUTES[topic].granularity === "per_instance_whole"),
   ...ROW_TOPICS,
 ];
@@ -37,8 +37,8 @@ export const CLUSTER_TOPICS: readonly string[] = [
  * 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);
+export function isMeshTopic(topic: string): boolean {
+  return MESH_TOPICS.includes(topic);
 }
 
 /** Whether what a frame of this topic carries is rows to be merged rather than
@@ -64,7 +64,7 @@ export interface RelayDeps {
 }
 
 /** What the peers said, held on this instance so that losing a peer does not
- * empty the cluster view (DESIGN §7.5).
+ * empty the mesh view (DESIGN §7.5).
  *
  * Two things live here and nowhere else: the last whole value each instance
  * stated per topic, and whether that instance can be reached right now. The
@@ -99,7 +99,7 @@ export class Relay {
    * unchanged — recomputing it would put the same judgement in two places
    * (DESIGN §7.4). */
   accept(instance: InstanceId, topic: string, data: unknown, snapshot = false): void {
-    if (!isClusterTopic(topic)) return;
+    if (!isMeshTopic(topic)) return;
     this.#sweep();
     const held = this.#held.get(instance) ?? new Map<string, unknown>();
     this.#held.set(instance, held);
@@ -174,7 +174,7 @@ export class Relay {
     return values;
   }
 
-  /** Which instance a session belongs to, read from the cluster values the
+  /** Which instance a session belongs to, read from the mesh values the
    * peers stated (DESIGN §7.3).
    *
    * `peers` names every session an instance holds, connected and lost alike,

package/src/messaging/delivery.ts

@@ -2,6 +2,8 @@ import type {
   CallerIdentity,
   CandidateSession,
   InboxMessage,
+  InboxRemoved,
+  InboxRemovedReason,
   InstanceId,
   MessageSendArgs,
   MessageSendResult,
@@ -21,7 +23,12 @@ import {
   OpError,
   type Requester,
 } from "../dispatch/index.ts";
-import type { PublishOutcome, TopicValue, UpstreamResource } from "../topics/index.ts";
+import {
+  PEOPLE,
+  type PublishOutcome,
+  type TopicValue,
+  type UpstreamResource,
+} from "../topics/index.ts";
 import type { DirectRoute } from "./direct.ts";
 import type { Inbox } from "./inbox.ts";
 
@@ -38,15 +45,15 @@ export interface SessionLookup {
   peerRows(): PeerInfo[];
 }
 
-/** The rest of the cluster, for a message addressed outside this instance.
+/** The rest of the mesh, for a message addressed outside this instance.
  *
- * `message.send` is a `cluster` op — any instance may be asked — but a message
+ * `message.send` is an `any_instance` op — any instance may be asked — but a message
  * reaches a session through the session's own connections, which are held by
  * the instance it greeted. So the op is answered here by carrying it there
- * (DESIGN §2.2 step 6 is about `instance-local` ops; this is the same forwarding for
+ * (DESIGN §2.2 step 6 is about `owner_instance` ops; this is the same forwarding for
  * the one op whose subject is elsewhere while its op is not). */
-export interface Cluster {
-  /** Which instance holds this session, or nothing when the cluster has not
+export interface MeshReach {
+  /** Which instance holds this session, or nothing when the mesh has not
    * named it. */
   ownerOf(sid: Sid): InstanceId | undefined;
   /** Whether an instance that might hold it cannot be asked right now. */
@@ -64,14 +71,19 @@ export interface DeliveryDeps {
   readonly sessions: SessionLookup;
   /** Absent on an instance with no mesh, where every session it can name is
    * its own. */
-  readonly cluster?: Cluster;
+  readonly mesh?: MeshReach;
   readonly inbox: Inbox;
   /** Route (a). Off until it is confirmed against a running harness, which is
    * condition 0 of DESIGN §6.5 and is why this is handed in rather than built here. */
   readonly direct: DirectRoute;
   /** The one way a value reaches subscribers (DESIGN §6.1), narrowed to the session a
    * message is for. */
-  readonly publish: (topic: string, data: unknown, instance: InstanceId, to: Sid) => PublishOutcome;
+  readonly publish: (
+    topic: string,
+    data: unknown,
+    instance: InstanceId,
+    to: Sid | typeof PEOPLE,
+  ) => PublishOutcome;
   /** How many of that session's connections are listening on `inbox`. */
   readonly listeners: (topic: string, to: Sid) => number;
 }
@@ -97,6 +109,14 @@ export class Delivery implements UpstreamResource {
 
   constructor(private readonly deps: DeliveryDeps) {
     this.#counter = deps.inbox.lastCounter(`${deps.self}/`);
+    // Every way out of the inbox is stated to the watchers, and the inbox is
+    // the one that knows about all of them — handed over, timed out, dropped
+    // for a newer message. Read from there rather than published beside each
+    // call that removes something, so a way out nobody thought of here is
+    // still a removal somebody watching sees (DESIGN §6.7).
+    deps.inbox.onRemoved((mid, reason) => {
+      this.#removed([mid], reason);
+    });
   }
 
   /** `message.send`. The op fails only for a sid nobody knows; every other
@@ -123,47 +143,87 @@ export class Delivery implements UpstreamResource {
     if (direct === "refused") {
       // Turned away for now, which is neither delivered nor undeliverable: it
       // waits in the inbox and is offered again (DESIGN §6.8).
-      this.deps.inbox.hold(to, message);
+      this.#hold(to, message);
       return { delivered: false, reason: "throttled" };
     }
 
     if (this.deps.listeners(INBOX, to) > 0) {
       if (this.deps.publish(INBOX, [message], this.deps.self, to) === "ok") {
+        // Route (b) is the topic itself, so the message never waits anywhere:
+        // the watchers are told both halves at once — it arrived, and it is
+        // gone because the session has it — since a view built from frames
+        // alone would otherwise show it waiting for good.
+        this.#watchers(to, [message]);
+        this.#removed([message.mid], "delivered");
         return { delivered: true };
       }
       // The session is listening but is behind on what it has already been
       // offered, which is the same standing as route (a) turning the message
       // away: it waits in the inbox and is offered again (DESIGN §6.8).
-      this.deps.inbox.hold(to, message);
+      this.#hold(to, message);
       return { delivered: false, reason: "throttled" };
     }
 
-    const { evicted } = this.deps.inbox.hold(to, message);
+    const { evicted } = this.#hold(to, message);
     return this.#undelivered(to, evicted ? "inbox_full" : this.#reason(state));
   };
 
+  /** Hold a message the session could not take, and say so to the watchers.
+   *
+   * Stated before it is held, so that a message dropped to make room for it
+   * reads in the order the two happened: a removal of something the watcher
+   * has, rather than of something it is about to be told about. */
+  #hold(to: Sid, message: InboxMessage): { evicted: boolean } {
+    this.#watchers(to, [message]);
+    return this.deps.inbox.hold(to, message);
+  }
+
+  /** What is waiting, as somebody looking at it from outside reads it.
+   *
+   * A person holds every session's inbox in one subscription, so the rows they
+   * are answered with name their recipient; the session's own do not, since
+   * its subscription is already the recipient (contract, `InboxMessage.to`). */
+  #watchers(to: Sid, messages: readonly InboxMessage[]): void {
+    if (messages.length === 0) return;
+    this.deps.publish(
+      INBOX,
+      messages.map((message) => ({ ...message, to })),
+      this.deps.self,
+      PEOPLE,
+    );
+  }
+
+  /** A message has left an inbox, which only a watcher has anything left to do
+   * with: the session it was for either has it or never will, and neither is
+   * something to tell it on the topic it receives messages on. */
+  #removed(mids: readonly Mid[], reason: InboxRemovedReason): void {
+    if (mids.length === 0) return;
+    const gone: InboxRemoved[] = mids.map((mid) => ({ mid, removed: true, reason }));
+    this.deps.publish(INBOX, gone, this.deps.self, PEOPLE);
+  }
+
   /** A session this instance does not hold: carried to the instance that does,
-   * or named as one the cluster cannot answer for right now.
+   * or named as one the mesh cannot answer for right now.
    *
-   * Nothing when the cluster has no such session anywhere and every instance
+   * Nothing when the mesh has no such session anywhere and every instance
    * could be asked — which is the only case `session_not_found` covers (DESIGN §6.6).
    * While an instance is out of reach the sid may well be its, so the sender is
    * told the reason rather than that the session does not exist. The message is
    * not held here either: the inbox that would offer it again is the one on the
    * instance that owns the session (DESIGN §6.7). */
   async #elsewhere(to: Sid, input: HandlerInput): Promise<MessageSendResult | undefined> {
-    const cluster = this.deps.cluster;
-    if (cluster === undefined) return undefined;
-    const owner = cluster.ownerOf(to);
+    const reach = this.deps.mesh;
+    if (reach === undefined) return undefined;
+    const owner = reach.ownerOf(to);
     if (owner === undefined || owner === this.deps.self) {
-      return cluster.anyUnreachable()
+      return reach.anyUnreachable()
         ? { delivered: false, reason: "instance_unreachable" }
         : undefined;
     }
     // The sender, as the owning instance will run the op as: the identity the
     // connection greeted with, which is the same thing `message.send` reads to
     // decide who a message is from (DESIGN §6.5).
-    const answer = await cluster.forward(owner, input.args, callerOf(input));
+    const answer = await reach.forward(owner, input.args, callerOf(input));
     if (answer.kind === "reply") {
       const { ok: _ok, request_id: _id, ...body } = answer.response;
       return body as unknown as MessageSendResult;
@@ -243,11 +303,23 @@ export class Delivery implements UpstreamResource {
    *
    * A message an offer over route (a) has claimed is left out: it is on its way
    * on the other route, and the session subscribing while that runs must not
-   * make it two messages. */
+   * make it two messages.
+   *
+   * **A person's subscription is a view, not a delivery.** They are answered
+   * with everything waiting anywhere on this instance, each row naming its
+   * recipient, and the inbox is left exactly as it was — a person is not who
+   * any of it was addressed to, and a view that consumed what it looked at
+   * would deliver messages to nobody by being opened. Nothing is left out of
+   * it either: a message an offer has claimed is still waiting until that
+   * offer says otherwise, and that is what somebody watching wants to see. */
   snapshot(topic: string, conn: Requester): readonly TopicValue[] {
     const identity = conn.identity;
-    const sid = identity.state === "settled" ? identity.sid : undefined;
-    if (topic !== INBOX || sid === undefined) return [];
+    if (topic !== INBOX || identity.state !== "settled") return [];
+    const sid = identity.sid;
+    // A settled connection that names no session is somebody watching: the
+    // topic table lets nobody but a session and a person subscribe here, so
+    // the sid is the whole of the difference and no role is read for it (M1).
+    if (sid === undefined) return [{ instance: this.deps.self, data: this.#waiting() }];
     const claimed = this.#claimed.get(sid);
     const held = this.deps.inbox
       .undelivered(sid)
@@ -259,6 +331,16 @@ export class Delivery implements UpstreamResource {
     return [{ instance: this.deps.self, data: held }];
   }
 
+  /** Everything still undelivered on this instance, oldest first within each
+   * session, each row naming who it is for. */
+  #waiting(): InboxMessage[] {
+    const rows: InboxMessage[] = [];
+    for (const sid of this.deps.inbox.sids()) {
+      for (const message of this.deps.inbox.undelivered(sid)) rows.push({ ...message, to: sid });
+    }
+    return rows;
+  }
+
   /** The reason a message is waiting, named from the classification alone
    * (DESIGN §6.6). `preparing` is the live session with nowhere to put it: it is there,
    * route (a) did not carry it, and nothing of its is listening yet.

package/src/messaging/inbox.ts

@@ -11,6 +11,7 @@ import {
   INBOX_MAX_PER_SID,
   INBOX_RETENTION_MS,
   type InboxMessage,
+  type InboxRemovedReason,
   type Sid,
   type Timestamp,
 } from "@ccmsg/protocol";
@@ -44,8 +45,21 @@ type Record_ =
 export class Inbox {
   readonly #held = new Map<Sid, InboxMessage[]>();
 
+  /** Told whenever a message leaves, and why. Every way out passes through
+   * here — handed over, timed out, dropped for a newer one — so whoever states
+   * removals on the topic has one place to hear about them rather than a
+   * reading of its own per way (DESIGN §6.7). Absent until somebody asks: a
+   * replay at startup reaches conclusions about a file, with nobody yet
+   * subscribed for them to be news to. */
+  #onRemoved?: (mid: string, reason: InboxRemovedReason) => void;
+
   constructor(private readonly file: string) {}
 
+  /** Hear about messages leaving. */
+  onRemoved(told: (mid: string, reason: InboxRemovedReason) => void): void {
+    this.#onRemoved = told;
+  }
+
   /** Replay the file, drop what has expired, and write back what is left.
    *
    * The rewrite is the only whole-file write, and it happens before anything
@@ -95,7 +109,10 @@ export class Inbox {
     this.#append({ v: "add", sid, message });
     if (held.length <= INBOX_MAX_PER_SID) return { evicted: false };
     const oldest = held.shift();
-    if (oldest !== undefined) this.#append({ v: "dropped", sid, mid: oldest.mid });
+    if (oldest !== undefined) {
+      this.#append({ v: "dropped", sid, mid: oldest.mid });
+      this.#onRemoved?.(oldest.mid, "dropped");
+    }
     return { evicted: true };
   }
 
@@ -108,7 +125,10 @@ export class Inbox {
     const left = held.filter((message) => !gone.has(message.mid));
     if (left.length === 0) this.#held.delete(sid);
     else this.#held.set(sid, left);
-    for (const mid of mids) this.#append({ v: "delivered", sid, mid });
+    for (const mid of mids) {
+      this.#append({ v: "delivered", sid, mid });
+      this.#onRemoved?.(mid, "delivered");
+    }
   }
 
   /** Every session something is waiting for. What reads it is the offer of
@@ -154,8 +174,12 @@ export class Inbox {
       if (only !== undefined && sid !== only) continue;
       const left = held.filter((message) => now - message.sent_at <= INBOX_RETENTION_MS);
       if (left.length === held.length) continue;
+      const gone = new Set(left.map((message) => message.mid));
       if (left.length === 0) this.#held.delete(sid);
       else this.#held.set(sid, left);
+      for (const message of held) {
+        if (!gone.has(message.mid)) this.#onRemoved?.(message.mid, "expired");
+      }
     }
   }
 

package/src/messaging/notify.ts

@@ -1,5 +1,6 @@
 import type {
   InstanceId,
+  Mid,
   Notification,
   NotifySendArgs,
   NotifySendResult,
@@ -48,7 +49,10 @@ export class Notify implements UpstreamResource {
    * caller otherwise, so a session notifying about itself says only the text. */
   send = (input: HandlerInput): NotifySendResult => {
     const args = input.args as unknown as NotifySendArgs;
-    this.#announce(args.sid ?? this.#caller(input), args.text);
+    // What it answers travels with it: a notification is shown while the
+    // session's own account of the same answer is still being written, and the
+    // `mid` is what tells a reader holding both that they are one thing.
+    this.#announce(args.sid ?? this.#caller(input), args.text, Date.now(), args.reply_to);
     return {};
   };
 
@@ -92,11 +96,12 @@ export class Notify implements UpstreamResource {
     return [];
   }
 
-  #announce(sid: Sid, text: string, now: Timestamp = Date.now()): Timestamp {
+  #announce(sid: Sid, text: string, now: Timestamp = Date.now(), reply_to?: Mid): Timestamp {
     const notification: Notification = {
       sid,
       sid_label: this.deps.label(sid),
       text,
+      ...(reply_to === undefined ? {} : { reply_to }),
       sent_at: now,
     };
     // A notification is an occurrence, so nothing folds it away and a watcher

package/src/sessions/dump.ts

@@ -4,13 +4,17 @@ import type {
   DumpPreset,
   InstanceId,
   SessionDumpFile,
+  SessionDumpFormat,
   SessionDumpWriteArgs,
   SessionDumpWriteResult,
+  Timestamp,
 } from "@ccmsg/protocol";
 import { OpError } from "../dispatch/index.ts";
 import {
   bounded,
   classify,
+  document as render,
+  type Item,
   ledger,
   located,
   select,
@@ -81,6 +85,7 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
   );
   const ids = ledger(items);
   const written_at = Date.now();
+  const format = args.format ?? "items";
   // The file repeats what it was asked for. A dump outlives the request that
   // made it and is read by whoever was handed the path, so it has to say on
   // its own what it is a dump of and what was left out — which is why the
@@ -93,12 +98,27 @@ export function dumpWrite(args: SessionDumpWriteArgs, deps: DumpDeps): SessionDu
     items,
     ids,
   };
+  const body =
+    format === "items"
+      ? `${JSON.stringify(document, undefined, 2)}\n`
+      : format === "records"
+        ? sourceLines(text, items)
+        : render(document, {
+            instance: deps.self,
+            ...(args.since_at === undefined ? {} : { since: moment(args.since_at) }),
+            ...(args.until_at === undefined ? {} : { until: moment(args.until_at) }),
+            ...(args.since_uuid === undefined ? {} : { since: args.since_uuid }),
+            ...(args.until_uuid === undefined ? {} : { until: args.until_uuid }),
+          });
   const dir = join(deps.stateDir, DUMPS);
   mkdirSync(dir, { recursive: true });
   const named = args.agent_id === undefined ? args.sid : `${args.sid}-agent-${args.agent_id}`;
-  const path = join(dir, `${named}-${written_at}${DUMP_SUFFIX}`);
-  const body = `${JSON.stringify(document, undefined, 2)}\n`;
+  const path = join(dir, `${named}-${written_at}${suffix(format)}`);
   writeFileSync(path, body);
+  // What is counted is the selection, whatever the file ended up holding: that
+  // is what the caller asked for and what it reads the answer against, and a
+  // count that moved with the rendering would answer a different question each
+  // time (contract, `SessionDumpWriteResult`).
   return { path, instance: deps.self, entries, ids, bytes: Buffer.byteLength(body) };
 }
 
@@ -116,3 +136,43 @@ function presetFor(
   if (found === undefined) throw new OpError("invalid_args", `no preset is configured as ${name}`);
   return found;
 }
+
+/** The records the selected items were read from, as the file holds them.
+ *
+ * Taken out of the bytes by each item's own address rather than re-serialized,
+ * so what a tool reading the harness's format gets is the harness's own lines
+ * — nothing is added around them and nothing inside them is changed. Several
+ * items out of one record share that address, so the record is written once
+ * and the line count is not the item count (contract, `SessionDumpFormat`).
+ *
+ * One dump is one transcript — the session's, or one agent's when the request
+ * names one — so no line here has to say which file it came from. */
+function sourceLines(text: string, items: readonly Item[]): string {
+  const bytes = Buffer.from(text, "utf8");
+  const seen = new Set<number>();
+  const lines: string[] = [];
+  for (const item of items) {
+    const at = item.source.offset;
+    if (seen.has(at)) continue;
+    seen.add(at);
+    lines.push(
+      bytes
+        .subarray(at, at + item.source.bytes)
+        .toString("utf8")
+        .trimEnd(),
+    );
+  }
+  return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+
+/** What a file of this format is called. Whoever is handed the path opens it
+ * in whatever reads that kind of file, and a name saying `.json` for prose
+ * would send them to the wrong one. */
+function suffix(format: SessionDumpFormat): string {
+  return format === "items" ? DUMP_SUFFIX : format === "records" ? ".jsonl" : ".md";
+}
+
+/** A bound as the heading states it. */
+function moment(at: Timestamp): string {
+  return new Date(at).toISOString();
+}

package/src/sessions/registry.ts

@@ -22,7 +22,7 @@ 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 { meshView } from "../mesh/instances.ts";
 import type { TranscriptFacts } from "../transcript/index.ts";
 import { Elements, type TopicValue, type UpstreamResource } from "../topics/index.ts";
 import { classify, type SessionInputs } from "./classify.ts";
@@ -315,8 +315,8 @@ export class Sessions implements UpstreamResource {
       instance: this.deps.self,
       ...(this.deps.endpoint === undefined ? {} : { endpoint: this.deps.endpoint }),
       // 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),
+      // so a greeting and a subscription cannot state two different meshs.
+      instances: meshView(this.deps.self, this.deps.endpoint, this.deps.mesh),
       capabilities: [...this.deps.capabilities],
       version: this.deps.version,
       started_at: this.deps.startedAt,

package/src/topics/egress.ts

@@ -6,9 +6,9 @@ import type { Requester } from "../dispatch/index.ts";
  * list cannot see a change arrive sooner than the display draws it, so frames
  * closer together than a few display frames are spent on nothing, while a wait
  * long enough to be read as lag starts around a quarter of a second. Towards
- * the cluster: a relayed frame waits once per hop, so the delay a subscriber
+ * the mesh: a relayed frame waits once per hop, so the delay a subscriber
  * sees is this value times the hops between it and the instance that produced
- * the value — at 100 ms a two-hop cluster still answers inside the window a
+ * the value — at 100 ms a two-hop mesh still answers inside the window a
  * person reads as immediate, which a longer period would leave.
  *
  * It is not a poll. Nothing is looked at when the period elapses: the timer is