@ccmsg/cli 0.11.3 → 0.11.5

package/src/sessions/last-live.ts

@@ -46,7 +46,7 @@ const VERSION = 1;
 
 /** The sessions that were running when this instance last saw them.
  *
- * One of the three things written to disk (§3.6): losing it loses the Paused
+ * One of the three things written to disk (DESIGN §2.5): losing it loses the Paused
  * and Disappeared rows of the list entirely, and nothing else on the host
  * remembers that a session used to be here. Only observations are stored — the
  * classification is derived from them at read time, never written (M4). */
@@ -62,7 +62,7 @@ export class LastLiveStore {
     private readonly id: InstanceId,
   ) {}
 
-  /** Read at startup (§8.3 step 4), before anything can ask for the list. A
+  /** Read at startup (DESIGN §8.3 step 4), before anything can ask for the list. A
    * file that is missing or unreadable starts an empty list: the daemon has no
    * way to recover it and refusing to start would cost more than the rows. */
   load(now: Timestamp = Date.now()): void {
@@ -95,7 +95,7 @@ export class LastLiveStore {
   /** Note a session as no longer live. A `stopped_at` already recorded for it
    * survives, since the session being gone is what that stop led to; the entry
    * carries one when the session declared it was going, which is what makes it
-   * Paused rather than Disappeared (§5.2). */
+   * Paused rather than Disappeared (DESIGN §4.3). */
   record(entry: StoredEntry): void {
     const stopped = this.#entries.get(entry.sid)?.stopped_at ?? entry.stopped_at;
     this.#entries.set(entry.sid, {
@@ -136,7 +136,7 @@ export class LastLiveStore {
 }
 
 /** Where the list lives for an instance whose state directory is `stateDir`
- * (§8.1: every per-instance path is derived from its config home). */
+ * (DESIGN §8.1: every per-instance path is derived from its config home). */
 export function lastLivePath(stateDir: string): string {
   return join(stateDir, LAST_LIVE_FILE);
 }

package/src/sessions/registry.ts

@@ -32,7 +32,7 @@ import { stoppedOn } from "./status.ts";
 import { TerminalCache, type TerminalReader } from "./terminals.ts";
 
 /** What the harness says at one instant: the rows it reports, and which
- * sessions it says are there (§3.8).
+ * sessions it says are there (DESIGN §4.1).
  *
  * Two readings of one moment, passed together so a caller answering several
  * questions about that moment reads once. They are the same set for a harness
@@ -45,7 +45,7 @@ interface Own {
 
 /** What the sessions domain needs from the instance around it. */
 export interface SessionsDeps {
-  /** Which harness this config home runs (§3.8). It decides what says a
+  /** Which harness this config home runs (DESIGN §4.1). It decides what says a
    * session is there and, through that, what `agents` can report. */
   readonly harness: Harness;
   readonly self: InstanceId;
@@ -58,30 +58,30 @@ export interface SessionsDeps {
    * opened (DR-0001 §2.5). Absent on the unix socket, where reaching the
    * instance is itself the permission, and on a mesh link. */
   readonly authExpiresAt?: (conn: Requester) => Timestamp | undefined;
-  /** The one config home this instance answers for (§8.2). Its `sessions/` is
+  /** The one config home this instance answers for (DESIGN §8.2). Its `sessions/` is
    * the only directory read, and no other config home is ever looked for (M6). */
   readonly configHome: string;
   /** Where `last_live` is written. Derived from the config home by the caller,
-   * which is where every per-instance path is decided (§8.1). */
+   * which is where every per-instance path is decided (DESIGN §8.1). */
   readonly stateDir: string;
   readonly capabilities: readonly Capability[];
   /** The daemon build, reported by `hello` for display. */
   readonly version: string;
   readonly startedAt: Timestamp;
-  /** The one way a value reaches subscribers (§6.1). */
+  /** The one way a value reaches subscribers (DESIGN §6.1). */
   readonly publish: (topic: string, data: unknown) => void;
-  /** What the transcript fold says about a session (§5.1). Absent while
+  /** What the transcript fold says about a session (DESIGN §4.2). Absent while
    * nothing folds transcripts, in which case the two values it settles are
    * simply unknown and every rule that reads them behaves as it does for a
    * session whose transcript has said nothing. */
   readonly transcript?: TranscriptSource;
-  /** What the gateway has seen of a session (§5.1). Absent on an instance with
+  /** What the gateway has seen of a session (DESIGN §4.2). Absent on an instance with
    * no gateway configured, which costs the classification one of its five
    * inputs and none of its states. */
   readonly gateway?: GatewaySource;
   /** The sessions this instance speaks about, or what the fold says about one,
    * has changed. What rests on either — the topics whose value is derived from
-   * the same fold, and the tails they keep running (§6.3) — is told to catch
+   * the same fold, and the tails they keep running (DESIGN §6.3) — is told to catch
    * up. Absent when nothing does. */
   readonly onChanged?: () => void;
   /** How often the confirmation poll runs, for a test that cannot wait. */
@@ -99,7 +99,7 @@ export interface SessionsDeps {
   readonly terminals?: TerminalReader;
   /** The mesh, on an instance that has one. It answers the one greeting this
    * domain cannot judge: a peer's, whose claim is settled by an exchange of its
-   * own rather than by anything a session says (§7.2). */
+   * own rather than by anything a session says (DESIGN §7.2). */
   readonly mesh?: MeshSource;
   /** Where a person opens the terminal a session runs in, which `hello` states
    * as `terminal_gateway`. The same value that gates the `terminal` capability
@@ -110,7 +110,7 @@ export interface SessionsDeps {
 }
 
 /** What `hello` needs of the mesh: verify the greeting of a peer, and say which
- * instances there are and which of them can be reached (§7.5). */
+ * instances there are and which of them can be reached (DESIGN §7.5). */
 export interface MeshSource {
   greet(conn: Requester, claim: MeshClaim): Promise<void>;
   instances(): InstanceInfo[];
@@ -121,13 +121,13 @@ type MeshClaim = HelloInstanceArgs["mesh"];
 
 /** The fold, as the sessions domain reads it: two values about one session,
  * asked for when a payload is built rather than copied here when they change
- * (§3.3 — the current value lives with whoever owns it). */
+ * (DESIGN §2.3 — the current value lives with whoever owns it). */
 export interface TranscriptSource {
   facts(sid: Sid): TranscriptFacts;
 }
 
 /** The gateway, as the sessions domain reads it: when it last saw inference
- * for one session, asked for when a payload is built (§3.3). */
+ * for one session, asked for when a payload is built (DESIGN §2.3). */
 export interface GatewaySource {
   activeAt(sid: Sid): Timestamp | undefined;
 }
@@ -164,7 +164,7 @@ interface Connected {
   readonly meta: SessionMeta;
   /** The most recent request on any of its connections. Distinct from when a
    * person last spoke to it, which is folded out of the transcript and is the
-   * one an attention-ordered list wants (§5.3). */
+   * one an attention-ordered list wants (DESIGN §4.4). */
   last_activity_at: Timestamp;
   /** More than one client process of a session may hold a connection. */
   conns: number;
@@ -173,10 +173,10 @@ interface Connected {
 /** The sessions this instance can speak about, and the two topics that carry
  * them.
  *
- * The current value lives here rather than in the topic mechanism (§3.3): what
+ * The current value lives here rather than in the topic mechanism (DESIGN §2.3): what
  * is connected is held in memory and dies with the process, what the harness
  * reports is re-read from `sessions/`, and only `last_live` survives a restart.
- * The classification of §5.2 is derived from those three whenever a payload is
+ * The classification of DESIGN §4.3 is derived from those three whenever a payload is
  * built, and never stored (M4). */
 export class Sessions implements UpstreamResource {
   readonly #connected = new Map<Sid, Connected>();
@@ -187,7 +187,7 @@ export class Sessions implements UpstreamResource {
    * being live is what writes its `last_live` entry. */
   #live = new Map<Sid, StoredEntry>();
   /** The topic names currently subscribed. Both topics rest on the same
-   * directory watch, so it runs while either has a listener (§6.3). */
+   * directory watch, so it runs while either has a listener (DESIGN §6.3). */
   readonly #wanted = new Set<string>();
   /** What a session said about itself when it last greeted, kept for as long
    * as the harness still names the session.
@@ -277,7 +277,7 @@ export class Sessions implements UpstreamResource {
   /** `hello.instance`. A peer's greeting is answered only once the connection
    * has been proven to be the endpoint it names. The verification rejects when
    * it is not, and the connection stays anonymous because nothing settles an
-   * identity but a reply (mesh-peer-auth §5, daemon-v2 §3.2 step 7). This is
+   * identity but a reply (mesh-peer-auth §5, DESIGN §2.2 step 7). This is
    * the one greeting that has to wait for something, which is why it is the one
    * that answers with a promise. */
   helloInstance = (input: HandlerInput): Promise<HelloResult> => {
@@ -327,7 +327,7 @@ export class Sessions implements UpstreamResource {
     };
   }
 
-  /** Where a session stands (§5.2). Undefined for a sid this instance has
+  /** Where a session stands (DESIGN §4.3). Undefined for a sid this instance has
    * never seen live and does not hold in `last_live`. */
   classify(
     sid: Sid,
@@ -371,7 +371,7 @@ export class Sessions implements UpstreamResource {
    *
    * The harness's rows are read here rather than taken from the watch. Which
    * sessions the harness has is a fact about this config home, true whether or
-   * not anybody subscribed to hear about it (§5.1) — the watch of §6.3 exists
+   * not anybody subscribed to hear about it (DESIGN §4.2) — the watch of DESIGN §6.3 exists
    * to push a change to subscribers, and reading its cache instead would make
    * "a session exists" mean "somebody is listening", which is how a live
    * session becomes `session_not_found` to a sender and how a session that is
@@ -417,7 +417,7 @@ export class Sessions implements UpstreamResource {
     if (held !== undefined) held.last_activity_at = at;
   }
 
-  /** Where a session's transcript is, as it announced it (§5.1). Whoever
+  /** Where a session's transcript is, as it announced it (DESIGN §4.2). Whoever
    * follows one needs the path, and the greeting is the only thing that
    * states it. */
   transcriptPath(sid: Sid): string | undefined {
@@ -431,7 +431,7 @@ export class Sessions implements UpstreamResource {
     const meta = this.#connected.get(sid)?.meta;
     const cwd = meta?.cwd ?? this.#own().rows.get(sid)?.cwd;
     // The container when the session named one, the working directory
-    // otherwise — the same order `repo_root` is meant in (§4.2).
+    // otherwise — the same order `repo_root` is meant in (DESIGN §6.6).
     const root = meta?.repo_root ?? cwd;
     return {
       ...(root === undefined || root === "" ? {} : { root }),
@@ -441,7 +441,7 @@ export class Sessions implements UpstreamResource {
 
   /** The harness's sessions as they are right now, read rather than taken
    * from the watch's cache. What acts on a session's process resolves its pid
-   * through this: the watch runs only while somebody is subscribed (§6.3), and
+   * through this: the watch runs only while somebody is subscribed (DESIGN §6.3), and
    * a pid from a poll that has not run is a number belonging to nobody. */
   rowsNow(): ReadonlyMap<Sid, AgentInfo> {
     return this.#own().rows;
@@ -463,7 +463,7 @@ export class Sessions implements UpstreamResource {
   }
 
   /** `session.stopping`: a session saying it is about to go, which is what
-   * makes it Paused rather than Disappeared once it is gone (§5.2).
+   * makes it Paused rather than Disappeared once it is gone (DESIGN §4.3).
    *
    * Nothing is recorded now and nothing is published: the session is still
    * here, and the list this changes is the one it is not on yet. What the
@@ -481,7 +481,7 @@ export class Sessions implements UpstreamResource {
     return { stopped_at: at };
   };
 
-  // --- UpstreamResource (§6.3): the directory is read while, and only while,
+  // --- UpstreamResource (DESIGN §6.3): the directory is read while, and only while,
   // somebody is subscribed to a topic that rests on it.
 
   start(topic: string): void {
@@ -524,7 +524,7 @@ export class Sessions implements UpstreamResource {
    * 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 is not the same as connected (DESIGN §4.3). A session the harness names is
    * live whether or not it ever greeted us, and it has to be on this list for
    * the same reason it is classified at all: a restart forgets every greeting,
    * and a list that showed only what had greeted this daemon would show a host
@@ -573,7 +573,7 @@ export class Sessions implements UpstreamResource {
     };
   }
 
-  /** The gateway saw inference for one session again (§5.1).
+  /** The gateway saw inference for one session again (DESIGN §4.2).
    *
    * 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
@@ -718,12 +718,12 @@ export class Sessions implements UpstreamResource {
   }
 
   #peer(session: Connected, now: Timestamp, own: Own): PeerInfo {
-    // The two "last activity" values are different questions (§5.3): the one
+    // The two "last activity" values are different questions (DESIGN §4.4): the one
     // above moves on every request the session makes, this one only when a
     // person speaks, and the fold is the only place that knows the second.
     const userInput = this.deps.transcript?.facts(session.sid).last_user_input_at;
     // What the gateway last saw run for this session: an attribute of the row
-    // beside the classification, not folded into it (§5.1). Absent from an
+    // beside the classification, not folded into it (DESIGN §4.2). Absent from an
     // instance with no gateway, where nothing observes inference at all.
     const gatewayActiveAt = this.#gatewayActiveAt(session.sid, own.present.has(session.sid));
     return {
@@ -741,11 +741,11 @@ export class Sessions implements UpstreamResource {
     };
   }
 
-  /** A session the harness names that holds no connection here (§5.1).
+  /** A session the harness names that holds no connection here (DESIGN §4.2).
    *
    * It is on the same list as the connected ones because it is live in the same
    * sense: the classification is what separates them, and a client groups on
-   * that field alone (§5.2). What it cannot carry is everything a greeting
+   * that field alone (DESIGN §4.3). What it cannot carry is everything a greeting
    * states — the session never said where it works, so the working directory
    * comes from the harness's own row and the display names it does not know are
    * simply absent.
@@ -772,7 +772,7 @@ export class Sessions implements UpstreamResource {
   }
 
   /** When the gateway last saw inference for a session, for a session this
-   * instance knows (§5.1).
+   * instance knows (DESIGN §4.2).
    *
    * The gateway sits above every config home and its events name only a session
    * id, so what it reports is not by itself evidence about *this* instance's
@@ -807,7 +807,7 @@ export class Sessions implements UpstreamResource {
    * `repo` and `ws` have no fallback: they are display names for a layout this
    * instance has no stated way to read out of a path, so a session that does
    * not name them is shown without them rather than with a guess. The same
-   * goes for `repo_root`, which §4.2 says to derive from `cwd` when it is not
+   * goes for `repo_root`, which DESIGN §6.6 says to derive from `cwd` when it is not
    * given — no primary source states that derivation, so it is left unstated
    * until one does. */
   #where(

package/src/sessions/status.ts

@@ -13,10 +13,10 @@ import { workspaceFolders } from "./workspace.ts";
 
 /** What the fold says stopped a session, read in one place.
  *
- * Three values rest on it: whether a live session is Waiting (§5.2), what
+ * Three values rest on it: whether a live session is Waiting (DESIGN §4.3), what
  * `session.errors` lists, and the `api_error` of `session.status:<sid>`. They
  * ask this rather than each reading the fold's field, so the three cannot come
- * to different answers about the same session (§7.4, M5). */
+ * to different answers about the same session (DESIGN §7.4, M5). */
 export function stoppedOn(facts: TranscriptFacts): SessionApiError | undefined {
   return facts.api_error;
 }
@@ -60,7 +60,7 @@ export function sessionStatusOf(
   };
 }
 
-/** Where a session works, as it greeted (§5.1). The same two values the file
+/** Where a session works, as it greeted (DESIGN §4.2). The same two values the file
  * surfaces are decided against, asked for here so that what `session.status`
  * says and what a read is admitted by come from one answer. */
 export interface SessionWhere {
@@ -72,7 +72,7 @@ export interface SessionStatusDeps {
   readonly self: InstanceId;
   /** The sessions this instance can follow a transcript of: the ones that
    * greeted, since a greeting is the only thing that names a transcript path
-   * (§5.1). A session it cannot follow has no error to fold. */
+   * (DESIGN §4.2). A session it cannot follow has no error to fold. */
   readonly sessions: () => readonly Sid[];
   readonly facts: (sid: Sid) => TranscriptFacts;
   /** Where each session works, for the two fields the transcript does not
@@ -81,12 +81,12 @@ export interface SessionStatusDeps {
   /** The tail behind a session's fold, asked for and let go by name. */
   readonly hold: (sid: Sid) => void;
   readonly release: (sid: Sid) => void;
-  /** The one way a value reaches subscribers (§6.1). */
+  /** The one way a value reaches subscribers (DESIGN §6.1). */
   readonly publish: (topic: string, data: unknown) => void;
 }
 
 /** The two topics the fold's error state feeds, and the tails they keep
- * running (§6.3).
+ * running (DESIGN §6.3).
  *
  * `session.errors` is one list for the instance and `session.status:<sid>` is
  * one session, so what they hold differs: the first wants every session's fold
@@ -108,7 +108,7 @@ export class SessionStatus implements UpstreamResource {
 
   constructor(private readonly deps: SessionStatusDeps) {}
 
-  // --- UpstreamResource (§6.3)
+  // --- UpstreamResource (DESIGN §6.3)
 
   start(topic: string): void {
     this.#wanted.add(topic);

package/src/sessions/terminals.ts

@@ -9,7 +9,7 @@ export type TerminalReader = (pid: number) => Promise<Terminal | undefined>;
  *
  * `agents` states a session's terminal and the classification reads it: a live
  * session that neither holds a connection here nor names a terminal is the one
- * nothing can reach (§5.2, `live_unmanaged`). Both want the value on every
+ * nothing can reach (DESIGN §4.3, `live_unmanaged`). Both want the value on every
  * row, and neither may pay for it on every read — the harness's directory is
  * scanned whenever any question is asked of it, and reading every session's
  * environment there would spawn a child per session per question.

package/src/transcript/files.ts

@@ -13,7 +13,7 @@ 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).
+ * there says which session it belongs to (DESIGN §4.1).
  *
  * Two facts, because the two harnesses file the same thing differently. Claude
  * Code keeps one directory per working directory and names the file after the
@@ -76,9 +76,9 @@ const TEAMMATE = /^[A-Za-z0-9_-]{1,64}$/;
  * (M6) — nothing searches for another one. */
 export interface TranscriptFilesDeps {
   readonly configHome: string;
-  /** Which harness's tree is under it (§3.8). */
+  /** Which harness's tree is under it (DESIGN §4.1). */
   readonly harness: Harness;
-  /** Where a connected session said its transcript is (§5.1). A session that
+  /** Where a connected session said its transcript is (DESIGN §4.2). A session that
    * never greeted has none, and the walk below answers for it. */
   readonly announced: (sid: Sid) => string | undefined;
 }
@@ -133,7 +133,7 @@ export class TranscriptFiles {
   }
 
   /** Which standing a transcript was written from, which every item read out
-   * of it states (§3.6).
+   * of it states (DESIGN §2.5).
    *
    * 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

package/src/transcript/fold.ts

@@ -11,7 +11,7 @@ import type {
   Timestamp,
 } from "@ccmsg/protocol";
 
-/** Everything one session's transcript is folded into (§3.3).
+/** Everything one session's transcript is folded into (DESIGN §2.3).
  *
  * One fold, not one per consumer: the same line settles whether the session is
  * stopped, when a person last spoke to it, which files it named and what is
@@ -23,9 +23,9 @@ import type {
 export interface TranscriptFacts {
   /** The error the latest turn ended on. Present only while it stands: a real
    * turn after it clears it, so this is the session's current state and not
-   * every error it ever hit. One of the two things §5.2 calls Waiting. */
+   * every error it ever hit. One of the two things DESIGN §4.3 calls Waiting. */
   readonly api_error?: SessionApiError;
-  /** When a person last put something into the session (§5.3). */
+  /** When a person last put something into the session (DESIGN §4.4). */
   readonly last_user_input_at?: Timestamp;
   /** What answered on the latest turn, and how hard it was asked to think.
    *
@@ -66,7 +66,7 @@ export const NO_FACTS: TranscriptFacts = {
  * Nothing outside this module parses a transcript record. A line arrives, the
  * fold updates what it can from it, and the values the domain states are read
  * off the result — so a value can never be derived by two different readings
- * of the same file (§3.3, M5).
+ * of the same file (DESIGN §2.3, M5).
  *
  * Feeding lines is order-dependent by design: the api error is the state of
  * the latest turn, so a later line undoing an earlier one is the point.
@@ -135,7 +135,7 @@ export class TranscriptFold {
     if (!isRecord(row)) return false;
     // A Codex rollout line settles one of these facts and none of the others,
     // so it is folded on its own rather than run past readers of records it
-    // does not have (§3.8).
+    // does not have (DESIGN §4.1).
     const rollout = rolloutRecord(row, str(row["type"]));
     if (rollout !== undefined) return this.#foldRollout(rollout);
     // Every value this fold derives, derived from the one parse (M5).
@@ -155,7 +155,7 @@ export class TranscriptFold {
    * The harness writes its own failures as assistant messages carrying
    * `isApiErrorMessage: true` ("Prompt is too long", "API Error: 500 …",
    * "Please run /login"): the turn stopped and the session sits idle until a
-   * person intervenes, which is why it counts as Waiting (§5.2). A row the
+   * person intervenes, which is why it counts as Waiting (DESIGN §4.3). A row the
    * model actually produced clears it — a row the harness wrote itself carries
    * `model: "<synthetic>"` and does not, so the harness's own "No response
    * requested." cannot pass for the agent answering again. A user row is not a
@@ -729,7 +729,7 @@ function merge(before: readonly string[] | undefined, added: unknown): string[]
  * read one that has stopped growing. Both are the same act of interpretation,
  * so both live here: nothing outside this module turns a transcript line into
  * meaning, and the harness's own spellings — its record types, its block
- * kinds, its ISO instants — stop at this boundary (§3.5). */
+ * kinds, its ISO instants — stop at this boundary (DESIGN §2.4). */
 export interface TranscriptRecord {
   /** The record id a dump's bounds cut at. */
   readonly uuid?: string;
@@ -787,7 +787,7 @@ export function readRecord(line: string): TranscriptRecord | undefined {
  * uses appear in no Claude Code transcript — so the two formats are told apart
  * by the line rather than by anything the reader was told beforehand.
  *
- * What is read is what §5 asks a transcript for and a rollout answers: when a
+ * What is read is what DESIGN §4 asks a transcript for and a rollout answers: when a
  * person last spoke, and where the session runs. The rest of the fold's facts —
  * a session's todos, its teammates, the files it named — are Claude Code's own
  * records, and a Codex session simply declares none of them.
@@ -887,7 +887,7 @@ function isHuman(text: string): boolean {
 }
 
 /** A transcript instant, in the contract's spelling. The harness writes ISO
- * strings; the contract's `Timestamp` is Unix ms (§3.5). */
+ * strings; the contract's `Timestamp` is Unix ms (DESIGN §2.4). */
 function instant(value: unknown): Timestamp | undefined {
   const text = str(value);
   if (text === undefined) return undefined;

package/src/transcript/items/classify.ts

@@ -1,4 +1,10 @@
-import type { TranscriptSubject } from "@ccmsg/protocol";
+import {
+  DIRECT_DELIVERY_TAG,
+  type DirectDelivery,
+  parseDirectDelivery,
+  type TranscriptSubject,
+  USER_SENDER,
+} from "@ccmsg/protocol";
 import type { Item } from "./item.ts";
 import {
   count,
@@ -20,7 +26,7 @@ import { genericResult, resultFields, useFields } from "./tools.ts";
  *
  * The contract writes down the type names and what an item of each type
  * carries, and says nothing about the file: the file is the harness's own, it
- * changes without asking, and reading it is this instance's work (§3.8). So
+ * changes without asking, and reading it is this instance's work (DESIGN §4.1). So
  * everything that knows what a line looks like is here, and what leaves is
  * only ever an item.
  *
@@ -126,7 +132,7 @@ export class Classification {
    *
    * 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).
+   * it beside the file, and whoever opened the file has already read that (DESIGN §2.5).
    *
    * 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
@@ -490,11 +496,7 @@ export class Classification {
       return;
     }
     if (said.includes("<cross-session-message")) {
-      make("message.session.in", {
-        text: said,
-        ...optional("from", attribute(said, "from")),
-        ...optional("msg_id", attribute(said, "mid")),
-      });
+      delivered(said, make);
       return;
     }
     if (said.includes("<teammate-message")) {
@@ -590,6 +592,52 @@ function envelope(said: string): Record<string, unknown> {
   };
 }
 
+/** What arrived in the envelope another session's message comes in.
+ *
+ * The harness writes prose around it — a line saying where it came from, and
+ * after it a standing reminder about messages from elsewhere — and both are
+ * the same on every one of these. What a person reads a transcript for is what
+ * was said, so the item carries the body alone and the envelope's own
+ * attributes say who said it.
+ *
+ * Who that is settles the type. A message this instance delivered on somebody's
+ * behalf names them: `user` is a person typing at a page, and their words are
+ * the same thing as words typed at the terminal (`message.user.in`). A sid is
+ * another session, which is a correspondent rather than the subject's own
+ * person (`message.session.in`). An envelope from somewhere else entirely —
+ * another harness's own cross-session traffic, which carries none of this
+ * protocol's attributes — is a session's message and is kept whole, since
+ * nothing here knows which part of it is the body. */
+function delivered(said: string, make: Make): void {
+  const parsed = envelopeOf(said);
+  if (parsed === undefined) {
+    make("message.session.in", {
+      text: said,
+      ...optional("from", attribute(said, "from")),
+      ...optional("msg_id", attribute(said, "mid")),
+    });
+    return;
+  }
+  make(parsed.from === USER_SENDER ? "message.user.in" : "message.session.in", {
+    text: parsed.text,
+    from: parsed.from,
+    msg_id: parsed.mid,
+  });
+}
+
+/** The envelope out of whatever the harness wrapped around it.
+ *
+ * The contract reads one that starts where the text does, so the text is cut
+ * to it first: the tag opens it and the last closing tag ends it, which is the
+ * same rule the contract uses to let a body contain one. */
+function envelopeOf(said: string): DirectDelivery | undefined {
+  const open = said.indexOf(`<${DIRECT_DELIVERY_TAG}`);
+  if (open < 0) return undefined;
+  const close = said.lastIndexOf(`</${DIRECT_DELIVERY_TAG}>`);
+  if (close < open) return undefined;
+  return parseDirectDelivery(said.slice(open, close + `</${DIRECT_DELIVERY_TAG}>`.length));
+}
+
 /** The type an agent's answer arrives under, which is the other half of
  * whatever asked for it: a teammate's run ending answers the call that started
  * it, an errand's answer is the errand's result. */

package/src/transcript/read.ts

@@ -13,7 +13,7 @@ export const READ_LIMIT = 512 * 1024;
 
 /** A slice of a transcript, read backwards from an offset.
  *
- * Paging is by byte offset aligned to line boundaries (§3.3): the end of the
+ * Paging is by byte offset aligned to line boundaries (DESIGN §2.3): the end of the
  * file is read first, and each further page asks for what began before the
  * slice just read. Nothing is scanned whole and no index is built, which is
  * what lets a transcript of any size be read from its end.

package/src/transcript/tail.ts

@@ -9,7 +9,7 @@ import { CONFIRM_POLL_MS } from "../sessions/harness.ts";
  * is the recent end of the file, not its history. A megabyte is a few hundred
  * records at the sizes the harness writes, which reaches back past the current
  * turn by a wide margin while costing one read of fixed size however large the
- * file has grown (§3.3: a transcript of any size is read from its end).
+ * file has grown (DESIGN §2.3: a transcript of any size is read from its end).
  *
  * A person who has not spoken within it is reported as having no known input
  * rather than as having spoken long ago, which is what the contract's absent
@@ -42,10 +42,10 @@ export interface TailDeps {
   readonly pollMs?: number;
 }
 
-/** One transcript file, followed while somebody wants it (§6.3).
+/** One transcript file, followed while somebody wants it (DESIGN §6.3).
  *
  * Watch plus a low-rate confirmation poll, for the reason and at the interval
- * the sessions directory uses (§5.1): the watch is the route and the poll is
+ * the sessions directory uses (DESIGN §4.2): the watch is the route and the poll is
  * the backstop for what a delayed FSEvents queue is still sitting on. The
  * interval is shared rather than chosen again, so the two watches cannot
  * drift into two different answers to the same question. */

package/src/transcript/transcripts.ts

@@ -23,14 +23,14 @@ function isItems(topic: string): boolean {
 export interface TranscriptsDeps {
   readonly self: InstanceId;
   /** Where a session's transcript is: what it announced when it greeted
-   * (§5.1), or the `<sid>.jsonl` under this instance's `projects/` that
+   * (DESIGN §4.2), or the `<sid>.jsonl` under this instance's `projects/` that
    * carries its name. A sid neither names nor is named by a file there has
    * none, and nothing is guessed for it. */
   readonly pathOf: (sid: Sid) => string | undefined;
-  /** The one way a value reaches subscribers (§6.1). */
+  /** The one way a value reaches subscribers (DESIGN §6.1). */
   readonly publish: (topic: string, data: unknown) => void;
   /** The fold now says something different about this session. What the fold
-   * settles is an input to the sessions domain (§5.1), so the domain that
+   * settles is an input to the sessions domain (DESIGN §4.2), so the domain that
    * states those values is told to state them again. */
   readonly onFacts: (sid: Sid) => void;
   /** Overrides the confirmation poll, for a test that cannot wait. */
@@ -38,14 +38,14 @@ export interface TranscriptsDeps {
 }
 
 /** One tail and one fold per session, and the `transcript:<sid>` topic they
- * feed (§3.3).
+ * feed (DESIGN §2.3).
  *
  * The fold is one per session, not one per consumer: a line is read once and
  * every value it settles is settled from that read, so the api error, the last
  * human input and the appended bytes are three uses of one pass rather than
  * three passes (M5).
  *
- * A tail runs while something wants it and stops when nothing does (§6.3).
+ * A tail runs while something wants it and stops when nothing does (DESIGN §6.3).
  * Subscription is one such want; a `hold` is the other, for the values the
  * sessions domain states about a session nobody is watching the transcript of.
  * They are counted together, so the last one to go is what stops the tail. */
@@ -54,7 +54,7 @@ export class Transcripts implements UpstreamResource {
 
   constructor(private readonly deps: TranscriptsDeps) {}
 
-  // --- UpstreamResource (§6.3)
+  // --- UpstreamResource (DESIGN §6.3)
 
   start(topic: string): void {
     const sid = topicParam(topic);
@@ -68,7 +68,7 @@ export class Transcripts implements UpstreamResource {
 
   /** Where the transcript ends as the subscription begins. What follows starts
    * there, which is the whole of the snapshot for a topic whose frames are an
-   * append rather than a value (§6.2). A session whose transcript this
+   * append rather than a value (DESIGN §6.2). A session whose transcript this
    * instance cannot find has nothing to state, and the subscriber begins at
    * the first thing appended after one appears. */
   snapshot(topic: string): readonly TopicValue[] {

package/src/translate/helper.ts

@@ -17,10 +17,10 @@ export interface HelperChannel {
   kill(): void;
 }
 
-/** Read the helper the config names (§8.2).
+/** Read the helper the config names (DESIGN §8.2).
  *
  * A helper that is named and cannot be run ends the start rather than leaving
- * translation silently off (DV-Q9): an instance without the capability looks
+ * translation silently off (DR-0004): an instance without the capability looks
  * exactly like one nobody configured, and the operator who named a program
  * meant to have it. */
 export function translateSetup(config: UpstreamConfig, file: string): string | undefined {