@ccmsg/cli 0.11.3 → 0.11.5

package/src/messaging/delivery.ts

@@ -26,13 +26,13 @@ import type { DirectRoute } from "./direct.ts";
 import type { Inbox } from "./inbox.ts";
 
 /** The topic a message reaches its session on, and the only route in use while
- * route (a) waits for confirmation (§4.1). */
+ * route (a) waits for confirmation (DESIGN §6.5). */
 const INBOX = "inbox";
 
 /** What delivery reads about a session. Two questions, both answered by the
- * sessions domain from the inputs of §5.1: where a session stands, and which
+ * sessions domain from the inputs of DESIGN §4.2: where a session stands, and which
  * sessions are around — neither is asked of anything else, which is what keeps
- * the reasons of §4.2 from growing a source per reason. */
+ * the reasons of DESIGN §6.6 from growing a source per reason. */
 export interface SessionLookup {
   classify(sid: Sid): SessionState | undefined;
   peerRows(): PeerInfo[];
@@ -43,7 +43,7 @@ export interface SessionLookup {
  * `message.send` is a `cluster` 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
- * (§3.2 step 6 is about `instance-local` ops; this is the same forwarding for
+ * (DESIGN §2.2 step 6 is about `instance-local` 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
@@ -67,20 +67,20 @@ export interface DeliveryDeps {
   readonly cluster?: Cluster;
   readonly inbox: Inbox;
   /** Route (a). Off until it is confirmed against a running harness, which is
-   * condition 0 of §4.1 and is why this is handed in rather than built here. */
+   * 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 (§6.1), narrowed to the session a
+  /** 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;
   /** How many of that session's connections are listening on `inbox`. */
   readonly listeners: (topic: string, to: Sid) => number;
 }
 
-/** Delivery, and the inbox topic it delivers on (§4).
+/** Delivery, and the inbox topic it delivers on (DESIGN §6.5-6.8).
  *
- * Two things, as §4 splits them: the route a message takes, and what the sender
+ * Two things, as DESIGN §6.5-6.8 splits them: the route a message takes, and what the sender
  * is told when it took none. The second reads the classification and the inbox
- * and nothing else (§4.2) — a reason is a name for a state that was already
+ * and nothing else (DESIGN §6.6) — a reason is a name for a state that was already
  * there, never a state of its own. */
 export class Delivery implements UpstreamResource {
   #counter: number;
@@ -92,7 +92,7 @@ export class Delivery implements UpstreamResource {
   /** The messages an offer has taken responsibility for, per session. They are
    * still in the inbox — an offer that does not reach the end leaves them
    * there — but they are spoken for, so the snapshot below hands them to
-   * nobody: one message goes out on one route (§4.3). */
+   * nobody: one message goes out on one route (DESIGN §6.7). */
   readonly #claimed = new Map<Sid, Set<Mid>>();
 
   constructor(private readonly deps: DeliveryDeps) {
@@ -115,14 +115,14 @@ export class Delivery implements UpstreamResource {
     const direct = await this.deps.direct.send(to, message);
     if (direct === "delivered") {
       // Route (a) reaching this session is the session being able to receive,
-      // which is what the inbox waits for (§4.3). Whatever is still held for it
+      // which is what the inbox waits for (DESIGN §6.7). Whatever is still held for it
       // is offered now, on the route that just worked.
       await this.#offer(to);
       return { delivered: true };
     }
     if (direct === "refused") {
       // Turned away for now, which is neither delivered nor undeliverable: it
-      // waits in the inbox and is offered again (§4.4).
+      // waits in the inbox and is offered again (DESIGN §6.8).
       this.deps.inbox.hold(to, message);
       return { delivered: false, reason: "throttled" };
     }
@@ -133,7 +133,7 @@ export class Delivery implements UpstreamResource {
       }
       // 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 (§4.4).
+      // away: it waits in the inbox and is offered again (DESIGN §6.8).
       this.deps.inbox.hold(to, message);
       return { delivered: false, reason: "throttled" };
     }
@@ -146,11 +146,11 @@ export class Delivery implements UpstreamResource {
    * or named as one the cluster cannot answer for right now.
    *
    * Nothing when the cluster has no such session anywhere and every instance
-   * could be asked — which is the only case `session_not_found` covers (§4.2).
+   * 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 (§4.3). */
+   * 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;
@@ -162,7 +162,7 @@ export class Delivery implements UpstreamResource {
     }
     // 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 (§4.1).
+    // decide who a message is from (DESIGN §6.5).
     const answer = await cluster.forward(owner, input.args, callerOf(input));
     if (answer.kind === "reply") {
       const { ok: _ok, request_id: _id, ...body } = answer.response;
@@ -197,7 +197,7 @@ export class Delivery implements UpstreamResource {
   /** Hand a session what it is owed, oldest first, over route (a).
    *
    * Stops at the first message the route does not carry, whatever it answered:
-   * a refusal means the session is taking nothing more for now (§4.4), and an
+   * a refusal means the session is taking nothing more for now (DESIGN §6.8), and an
    * unavailable route means route (b) is the one that applies — either way the
    * rest stay held, in order, for the next time this session becomes able to
    * receive. */
@@ -223,7 +223,7 @@ export class Delivery implements UpstreamResource {
     }
   }
 
-  // --- UpstreamResource (§6.3)
+  // --- UpstreamResource (DESIGN §6.3)
 
   /** Nothing upstream to run: what is undelivered is already in hand, and the
    * messages that arrive later come through `send`. */
@@ -232,12 +232,12 @@ export class Delivery implements UpstreamResource {
   stop(): void {}
 
   /** The current value of `inbox` for whoever subscribed: everything still
-   * undelivered for that session (§6.2, element granularity — the snapshot is
+   * undelivered for that session (DESIGN §6.2, element granularity — the snapshot is
    * every element, a later frame is one).
    *
    * Subscribing is receiving, so the snapshot empties the inbox: the frame is
    * queued on the connection before this returns, and a message the session has
-   * been handed is not one that is still waiting for it (§4.3). A connection
+   * been handed is not one that is still waiting for it (DESIGN §6.7). A connection
    * with no session — a person watching — is handed nothing, because the topic
    * carries what was said to a session and they are not one.
    *
@@ -260,7 +260,7 @@ export class Delivery implements UpstreamResource {
   }
 
   /** The reason a message is waiting, named from the classification alone
-   * (§4.2). `preparing` is the live session with nowhere to put it: it is there,
+   * (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.
    *
    * `instance_unreachable` is not here: it is the mesh's answer about an
@@ -280,7 +280,7 @@ export class Delivery implements UpstreamResource {
 
   /** The answer for a message that went to the inbox. Candidates ride along
    * when the addressee is gone, since that is when sending somewhere else is
-   * the sender's next move (§4.2). */
+   * the sender's next move (DESIGN §6.6). */
   #undelivered(to: Sid, reason: UndeliveredReason): MessageSendResult {
     if (reason !== "paused" && reason !== "disappeared") return { delivered: false, reason };
     const candidates = this.#candidates(to);
@@ -289,7 +289,7 @@ export class Delivery implements UpstreamResource {
       : { delivered: false, reason, candidates };
   }
 
-  /** Sessions live now in the repository the addressee belongs to (§4.2).
+  /** Sessions live now in the repository the addressee belongs to (DESIGN §6.6).
    *
    * 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
@@ -319,7 +319,7 @@ export class Delivery implements UpstreamResource {
   }
 
   /** Who the message is from: the identity the connection greeted as, never
-   * anything the caller put in the arguments (§4.1).
+   * anything the caller put in the arguments (DESIGN §6.5).
    *
    * A session names itself with its sid. A person greets without one, which is
    * what the sender literal stands for — spelled out so a reader tells "a

package/src/messaging/direct.ts

@@ -5,30 +5,30 @@ import { dirname, join } from "node:path";
 import { type InboxMessage, renderDirectDelivery, type Sid } from "@ccmsg/protocol";
 import { HARNESS, HARNESSES } from "../harness/index.ts";
 
-/** What route (a) answered (§4.1).
+/** What route (a) answered (DESIGN §6.5).
  *
  * `unavailable` is every way the route does not apply — the flag is off, the
  * harness names no messaging socket, the generation is one we do not speak, the
- * key cannot be read, the acknowledgement did not come. §4.1 gives them one
+ * key cannot be read, the acknowledgement did not come. DESIGN §6.5 gives them one
  * outcome on purpose: the route either carried the message or it did not, and
  * route (b) is tried the same way in each case.
  *
  * `refused` is separate because it is not "the route does not apply": the
  * session is there and turned this message away for now, which is the one
- * outcome that reaches the sender as its own reason (§4.4). */
+ * outcome that reaches the sender as its own reason (DESIGN §6.8). */
 export type DirectOutcome = "delivered" | "unavailable" | "refused";
 
 /** Route (a): the harness's own messaging socket. */
 export interface DirectRoute {
   send(sid: Sid, message: InboxMessage): Promise<DirectOutcome>;
   /** Let go of what the route holds open. The status inbox below is a bound
-   * socket with a name on disk, and it leaves when the instance does (§8.5). */
+   * socket with a name on disk, and it leaves when the instance does (DESIGN §8.5). */
   close(): void;
 }
 
-/** Route (a) turned off by config (§4.1 condition 0). Delivery is unchanged by
+/** Route (a) turned off by config (DESIGN §6.5 condition 0). Delivery is unchanged by
  * this: route (b) is the fallback, and a fallback that always runs is still the
- * same semantics (§4.1). */
+ * same semantics (DESIGN §6.5). */
 export class DisabledDirectRoute implements DirectRoute {
   send(): Promise<DirectOutcome> {
     return Promise.resolve("unavailable");
@@ -39,7 +39,7 @@ export class DisabledDirectRoute implements DirectRoute {
 
 /** The `peerProtocol` generation this speaks. One value, because one is what
  * has been read off a running harness (2.1.263); any other generation is a
- * protocol nobody here has seen, which is condition 1 of §4.1. */
+ * protocol nobody here has seen, which is condition 1 of DESIGN §6.5. */
 export const PEER_PROTOCOL = 1;
 
 /** How long one attempt has to reach the point where the harness holds our
@@ -52,7 +52,7 @@ export const PEER_PROTOCOL = 1;
 export const DIRECT_ACK_MS = 2_000;
 
 /** How long the status inbox is watched for word about this message before the
- * send is taken to have landed (§4.1 condition 3).
+ * send is taken to have landed (DESIGN §6.5 condition 3).
  *
  * Provisional. What is known from the harness (2.1.263) is where the receipt
  * is raised, not how long it takes to arrive: the receiving session decides a
@@ -74,11 +74,11 @@ export const DIRECT_STATUS_MS = 250;
  *
  * `held` is among them because a parked message is not delivered yet: it waits
  * on somebody's approval there, which is the same "there, and not taking it
- * now" that §4.4 keeps in our inbox and offers again. */
+ * now" that DESIGN §6.8 keeps in our inbox and offers again. */
 const REFUSING = new Set(["refused", "denied", "dropped", "expired", "held"]);
 
 /** The socket this daemon offers so the receiving session can say what became
- * of a message (§4.1 condition 3).
+ * of a message (DESIGN §6.5 condition 3).
  *
  * It lives in the directory the target's own socket is in, and not in this
  * instance's state directory, because the receiving harness vets the address it
@@ -213,7 +213,7 @@ export interface SocketRouteOptions {
   readonly statusMs?: number;
 }
 
-/** Route (a) against the harness's messaging socket (§4.1).
+/** Route (a) against the harness's messaging socket (DESIGN §6.5).
  *
  * The path is `sessions/<pid>.json` of this instance's own config home, which
  * is also the answer to condition 2: a key beside it that this uid can read is
@@ -222,7 +222,7 @@ export interface SocketRouteOptions {
  * instance cannot see a state file for is simply not reachable this way.
  *
  * The directory is read per send rather than taken from the sessions domain's
- * watch: that watch runs only while a topic is subscribed (§6.3), and route (a)
+ * watch: that watch runs only while a topic is subscribed (DESIGN §6.3), and route (a)
  * exists precisely for the session that subscribes to nothing. */
 export class ClaudeCodeSocketRoute implements DirectRoute {
   readonly #sessionsDir: string;
@@ -243,7 +243,7 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
    *
    * The message is written, and then the receipt channel is watched for word
    * about it. What can arrive is a session saying it did not take the message
-   * (§4.4); what cannot is a session saying it did, because none is sent for
+   * (DESIGN §6.8); what cannot is a session saying it did, because none is sent for
    * the ordinary case. So the outcome is refusal if it says so in time, and
    * delivery if it says nothing — which is the same shape as the acknowledged
    * send it stands in for, decided on a channel that carries the refusals
@@ -281,7 +281,7 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
   }
 
   /** The state file naming this session, if it names a socket of a generation
-   * we speak (§4.1 conditions 1). */
+   * we speak (DESIGN §6.5 conditions 1). */
   async #target(sid: Sid): Promise<HarnessTarget | undefined> {
     let names: string[];
     try {
@@ -303,7 +303,7 @@ export class ClaudeCodeSocketRoute implements DirectRoute {
     return undefined;
   }
 
-  /** The `peerToken` the harness wrote for this session (§4.1 condition 2).
+  /** The `peerToken` the harness wrote for this session (DESIGN §6.5 condition 2).
    *
    * Found by the pid the key is named after rather than by rebuilding the rest
    * of the name: the digest in `<pid>.<digest>.key` is stated to be over the
@@ -341,7 +341,7 @@ type Env = Record<string, string>;
  * Passed through, they would tell the Codex CLI about a config home this
  * instance is not about and a session that is not the one being written to.
  * The home this route means is named explicitly, and the rest is dropped
- * (§3.8). */
+ * (DESIGN §4.1). */
 const DROPPED = HARNESSES.filter((harness) => harness !== "codex").flatMap((harness) => [
   HARNESS[harness].homeEnv,
   ...HARNESS[harness].sessionEnv,
@@ -360,7 +360,7 @@ const DROPPED = HARNESSES.filter((harness) => harness !== "codex").flatMap((harn
  * The budget is here for what is not being predicted: a child that never
  * answers would hold `message.send` open for as long as it lived, and route
  * (b) exists exactly so a route that does not come through costs a message
- * nothing (§4.1). It is generous next to a call that has been measured to
+ * nothing (DESIGN §6.5). It is generous next to a call that has been measured to
  * return at once. */
 export const QUEUE_MS = 10_000;
 
@@ -380,7 +380,7 @@ const runCodex: RunCodex = async (args, env) => {
     });
   } catch {
     // No `codex` on `PATH`, which is the same as the route not applying: the
-    // message goes by route (b) and nothing about it is lost (§4.1).
+    // message goes by route (b) and nothing about it is lost (DESIGN §6.5).
     return { code: 127 };
   }
   // The timer is held so it can be cleared: a send that answered in a
@@ -408,7 +408,7 @@ export interface QueueRouteOptions {
   readonly run?: RunCodex;
 }
 
-/** Route (a) against a Codex thread's queue (§4.1).
+/** Route (a) against a Codex thread's queue (DESIGN §6.5).
  *
  * Codex has no socket a message can be written to: what it has is a queue per
  * thread, held by the app-server the thread belongs to, and `codex queue` is
@@ -460,7 +460,7 @@ export class CodexQueueRoute implements DirectRoute {
  * into a message nobody receives rather than one the wrong session does.
  *
  * `from` is the address of our own status inbox, and is fixed by ccmsg rather
- * than taken from the caller (§4.1). It is what the receiving session answers
+ * than taken from the caller (DESIGN §6.5). It is what the receiving session answers
  * to about this message, and the message's `mid` is what it answers about — so
  * the two travel together, and a route with no inbox to offer sends neither
  * rather than naming an address nothing is listening on. */
@@ -476,7 +476,7 @@ function frames(sid: Sid, token: string, message: InboxMessage, from?: string):
   return `${JSON.stringify(auth)}\n${JSON.stringify(user)}\n`;
 }
 
-/** Connect and write, and answer whether the harness holds our bytes (§4.1
+/** Connect and write, and answer whether the harness holds our bytes (DESIGN §6.5
  * condition 3).
  *
  * That is the whole of what this can decide. The connection carries nothing
@@ -520,7 +520,7 @@ async function write(path: string, payload: string, ackMs: number): Promise<Dire
     });
   } catch {
     // No socket at the path, or nothing listening on it: the session ended and
-    // took its socket with it, or never had one (§4.1 condition 1).
+    // took its socket with it, or never had one (DESIGN §6.5 condition 1).
     return "unavailable";
   }
 
@@ -543,7 +543,7 @@ async function readJson(path: string): Promise<Record<string, unknown> | undefin
     return document as Record<string, unknown>;
   } catch {
     // Missing, unreadable by this uid, or half written — all of them are
-    // "route (a) does not apply here" (§4.1 conditions 1 and 2).
+    // "route (a) does not apply here" (DESIGN §6.5 conditions 1 and 2).
     return undefined;
   }
 }

package/src/messaging/inbox.ts

@@ -33,13 +33,13 @@ type Record_ =
 
 /** What was said to a session and has not reached it.
  *
- * The one thing here that nothing else can reconstruct (§3.6): the sender's
+ * The one thing here that nothing else can reconstruct (DESIGN §2.5): the sender's
  * `message.send` has already been answered, no transcript holds a message that
  * was never handed over, and the text lives nowhere else. Losing this file
  * loses the words.
  *
  * One file rather than one per sid. Both are append-only and both mean the same
- * thing for removal and expiry (§4.3); a single file makes the write path one
+ * thing for removal and expiry (DESIGN §6.7); a single file makes the write path one
  * open handle and makes "what is undelivered right now" one replay. */
 export class Inbox {
   readonly #held = new Map<Sid, InboxMessage[]>();
@@ -100,7 +100,7 @@ export class Inbox {
   }
 
   /** Note that messages reached their session, which is what takes them out of
-   * the inbox (§4.3). */
+   * the inbox (DESIGN §6.7). */
   delivered(sid: Sid, mids: readonly string[]): void {
     const held = this.#held.get(sid);
     if (held === undefined || mids.length === 0) return;
@@ -112,7 +112,7 @@ export class Inbox {
   }
 
   /** Every session something is waiting for. What reads it is the offer of
-   * §4.3: when a session becomes able to receive, what it is owed has to be
+   * DESIGN §6.7: when a session becomes able to receive, what it is owed has to be
    * findable without asking about each sid in turn. */
   sids(): Sid[] {
     return [...this.#held.keys()];
@@ -146,7 +146,7 @@ export class Inbox {
     else this.#held.set(record.sid, left);
   }
 
-  /** Drop what is past the window the contract sets (DV-Q4). Nothing is
+  /** Drop what is past the window the contract sets (DR-0008). Nothing is
    * appended for an expiry: the same clock reaches the same verdict on the next
    * replay, so writing it down would record a conclusion rather than an event. */
   #expire(now: Timestamp, only?: Sid): void {
@@ -185,7 +185,7 @@ export class Inbox {
 }
 
 /** Where the inbox 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 inboxPath(stateDir: string): string {
   return join(stateDir, INBOX_FILE);
 }

package/src/messaging/notify.ts

@@ -21,7 +21,7 @@ export interface NotifyDeps {
   /** How a session is shown. The contract has the issuing instance resolve it,
    * so the label is decided here rather than carried in the arguments. */
   readonly label: (sid: Sid) => string;
-  /** The one way a value reaches subscribers (§6.1). No `to`: a notification is
+  /** The one way a value reaches subscribers (DESIGN §6.1). No `to`: a notification is
    * for whoever is watching, not for one session. */
   readonly publish: (topic: string, data: unknown, instance: InstanceId) => PublishOutcome;
 }
@@ -34,7 +34,7 @@ export interface NotifyDeps {
  * as the same frame, which is what keeps "a notification" from meaning two
  * shapes depending on which op raised it.
  *
- * The topic is `event` granularity (§6.2): nothing is held, so there is no
+ * The topic is `event` granularity (DESIGN §6.2): nothing is held, so there is no
  * snapshot and no suppression — two identical notifications are two things
  * that happened. */
 export class Notify implements UpstreamResource {
@@ -79,7 +79,7 @@ export class Notify implements UpstreamResource {
     return [...this.#unread];
   }
 
-  // --- UpstreamResource (§6.3)
+  // --- UpstreamResource (DESIGN §6.3)
 
   /** Nothing upstream to run: a notification exists because an op raised it. */
   start(): void {}
@@ -87,7 +87,7 @@ export class Notify implements UpstreamResource {
   stop(): void {}
 
   /** An event topic has no current value, so a subscriber starts at the next
-   * thing that happens (§6.2). */
+   * thing that happens (DESIGN §6.2). */
   snapshot(): readonly TopicValue[] {
     return [];
   }
@@ -102,7 +102,7 @@ export class Notify implements UpstreamResource {
     // A notification is an occurrence, so nothing folds it away and a watcher
     // that cannot keep up is what stops it. The caller hears that rather than
     // the notification going nowhere: it is the one that decides whether to
-    // raise another (§6.4).
+    // raise another (DESIGN §6.4).
     if (this.deps.publish(NOTIFY, notification, this.deps.self) === "rate_limited") {
       throw new OpError(
         "rate_limited",

package/src/plugin/codex.ts

@@ -86,7 +86,7 @@ const SKILL_FILE = join("skills", "ccmsg", "SKILL.md");
  * started against the default home has no variable saying so, and a Codex
  * session started from inside a Claude Code session inherits that session's
  * `CLAUDE_CONFIG_DIR` and session id — so a hook that only added its own would
- * still greet the other instance, as the other session (§3.8, measured). What
+ * still greet the other instance, as the other session (DESIGN §4.1, measured). What
  * is dropped is named here rather than left to the shell: the hook has to
  * speak for the session it fired for.
  *

package/src/sessions/classify.ts

@@ -2,23 +2,23 @@ import type { SessionState, Timestamp } from "@ccmsg/protocol";
 
 /** What the harness's own row says, for a session that has one. */
 export interface HarnessPresence {
-  /** Its status is `waiting`, so a dialog is open (§5.1). */
+  /** Its status is `waiting`, so a dialog is open (DESIGN §4.2). */
   waiting: boolean;
   /** The terminal it runs in, when one could be read. Absent means unknown,
    * which is what makes a live session unmanaged. */
   terminal_id?: string;
 }
 
-/** Everything the classification reads, and nothing else (§5.1). */
+/** Everything the classification reads, and nothing else (DESIGN §4.2). */
 export interface SessionInputs {
   /** A connection of this session is open to us right now. */
   connected: boolean;
   /** Present when the harness's `sessions/` has a row for it. */
   harness?: HarnessPresence;
-  /** The last time the gateway saw inference for it (§5.1). Absent on an
+  /** The last time the gateway saw inference for it (DESIGN §4.2). Absent on an
    * instance with no gateway configured, and for a session it has not seen. */
   gateway_active_at?: Timestamp;
-  /** Its transcript's last turn ended on an API error (§5.1, from the fold).
+  /** Its transcript's last turn ended on an API error (DESIGN §4.2, from the fold).
    * Absent for a session whose transcript nothing is following. */
   api_error_stopped?: boolean;
   /** Present when it is in `last_live`. */
@@ -30,12 +30,12 @@ export interface SessionInputs {
 export const GATEWAY_LIVE_WINDOW_MS = 5 * 60 * 1000;
 
 /** The classification is the contract's `SessionState`, derived here rather
- * than by whoever displays it (§5.2): a client combining raw values of its own
+ * than by whoever displays it (DESIGN §4.3): a client combining raw values of its own
  * would read two instances' lists by two rules.
  *
  * Pinned is not one of them. A person pins a row and the instance holds the
  * mark beside the classification, but the mark never decides which state the
- * row is in (§5.2).
+ * row is in (DESIGN §4.3).
  *
  * Busy and idle are not among them either, and not by omission: a live session
  * carries how busy it is as an attribute of its row, so an instance with no

package/src/sessions/dump.ts

@@ -21,7 +21,7 @@ import type { TranscriptFiles } from "../transcript/index.ts";
 
 /** Where dumps land: one directory under this instance's own state, named
  * after the config home it answers for like every other per-instance path
- * (§8.1). The caller never supplies a path, so there is none to contain. */
+ * (DESIGN §8.1). The caller never supplies a path, so there is none to contain. */
 export const DUMPS = "dumps";
 
 /** What a dump file is called. Two extensions rather than one so that a reader

package/src/sessions/handlers.ts

@@ -62,7 +62,7 @@ export interface SessionOpsDeps {
    * instance last saw them. The sessions domain owns the list; this op only
    * asks it to forget a row. */
   readonly forget: (sid: Sid) => boolean;
-  /** The named selections this instance is configured with (§3.6). */
+  /** The named selections this instance is configured with (DESIGN §2.5). */
   readonly presets: readonly DumpPreset[];
 }
 
@@ -138,7 +138,7 @@ export function sessionHandlers(deps: SessionOpsDeps) {
     "transcript.read": (input: HandlerInput): TranscriptReadResult => {
       const args = input.args as unknown as TranscriptReadArgs;
       if (!sees(args.sid, viewer(input))) {
-        // The role sets the visible range, not the permission (§3.2): outside
+        // The role sets the visible range, not the permission (DESIGN §2.2): outside
         // it there is no transcript to speak of, which is the one code this op
         // declares. A refusal that named the session would answer a question
         // the caller was not entitled to ask.

package/src/sessions/harness.ts

@@ -7,7 +7,7 @@ import type { Harness } from "../harness/index.ts";
  * an answer, alongside a `waitingFor` naming what it waits on.
  *
  * Read out of the harness binary (2.1.263): `{status:"waiting",waitingFor:…}`.
- * This is the one thing the raw status decides (§5.1 / DV-Q5) — busy and idle
+ * This is the one thing the raw status decides (DESIGN §4.2 / DR-0009) — busy and idle
  * are the gateway's to say, so no other value of it is read here. */
 const WAITING = "waiting";
 
@@ -16,9 +16,9 @@ const WAITING = "waiting";
  * `fs.watch` is the route; this is not. macOS/Bun delivers FSEvents tens of
  * seconds late under load (measured in the old daemon while many test children
  * ran), and the poll exists so a change the watch is sitting on is picked up
- * before a person notices it is missing (§5.1). Five seconds is the interval
+ * before a person notices it is missing (DESIGN §4.2). Five seconds is the interval
  * the old daemon's `claude agents` poller ran at as its only route, and this
- * one replaces it as a backstop (DV-Q6), so it cannot be the slower of the
+ * one replaces it as a backstop (DR-0009), so it cannot be the slower of the
  * two. */
 export const CONFIRM_POLL_MS = 5_000;
 
@@ -32,11 +32,11 @@ const STATE_FILE = /^\d+\.json$/;
  * states and what the `agents` topic is; Codex says only that a thread has a
  * live writer, which answers "is it there" and nothing else. So `rows` is what
  * can be reported and `present` is what the classification reads, and a harness
- * that reports nothing still has its sessions classified (§5.1). */
+ * that reports nothing still has its sessions classified (DESIGN §4.2). */
 export interface OwnSessions {
   readonly running: boolean;
   /** Begins watching. Called when the first subscriber arrives and not before
-   * (§6.3 / §8.3: no upstream is read until somebody is listening). */
+   * (DESIGN §6.3 / §8.3: no upstream is read until somebody is listening). */
   start(): void;
   stop(): void;
   /** The harness's own rows, as `agents` answers with them. Empty for a
@@ -46,7 +46,7 @@ export interface OwnSessions {
   present(): ReadonlySet<Sid>;
 }
 
-/** The one this config home runs (§3.8). */
+/** The one this config home runs (DESIGN §4.1). */
 export function ownSessions(
   harness: Harness,
   configHome: string,
@@ -117,11 +117,11 @@ class CodexThreads implements OwnSessions {
 /** The sessions the harness itself reports, read from one config home.
  *
  * The directory is the whole input: it says which sessions exist and which is
- * waiting on a dialog (§5.1). Only the config home this instance was given is
+ * waiting on a dialog (DESIGN §4.2). Only the config home this instance was given is
  * ever opened (M6) — the path is handed in, and nothing here searches for
  * another one.
  *
- * Two things live here, and §6.3 separates them. Reading the directory answers
+ * Two things live here, and DESIGN §6.3 separates them. Reading the directory answers
  * a question, and is done whenever one is asked. Watching it says the answer
  * may have changed, which is only worth knowing while somebody is subscribed —
  * so the watch is what the subscription drives, and no answer waits on it. */
@@ -163,7 +163,7 @@ export class HarnessSessions implements OwnSessions {
   /** The directory as it is at this instant.
    *
    * Every answer comes from here rather than from anything the watch left
-   * behind. Which sessions exist is an input to the classification (§5.1), and
+   * behind. Which sessions exist is an input to the classification (DESIGN §4.2), and
    * classifying happens inside `message.send`'s decision and inside the
    * recompute that writes `last_live` — neither of which can hand back a
    * promise without changing what it means, and neither of which may depend on
@@ -209,7 +209,7 @@ export class HarnessSessions implements OwnSessions {
 /** One directory that says what the harness's sessions are, watched while
  * somebody is subscribed and read whenever an answer is wanted.
  *
- * The two things §6.3 separates live here. Reading the directory answers a
+ * The two things DESIGN §6.3 separates live here. Reading the directory answers a
  * question, and is done whenever one is asked. Watching it says the answer may
  * have changed, which is only worth knowing while somebody is listening — so
  * the watch is what the subscription drives, and no answer waits on it. */
@@ -274,7 +274,7 @@ type RowResult =
   | { readonly complete: true; readonly row?: AgentInfo };
 
 /** The conversion of one upstream document into the contract's spelling
- * (§3.5): renamed to snake_case, instants in Unix ms, and nothing carried over
+ * (DESIGN §2.4): renamed to snake_case, instants in Unix ms, and nothing carried over
  * that the contract does not name.
  *
  * A row whose process is gone is dropped: the file outlives a session that did
@@ -316,7 +316,7 @@ function alive(pid: number): boolean {
     return true;
   } catch {
     // EPERM would mean alive but ours to signal — impossible here, since the
-    // daemon and the sessions of its config home run as one uid (§2 A4).
+    // daemon and the sessions of its config home run as one uid (DESIGN §1.4 A4).
     return false;
   }
 }