@ccmsg/cli 0.11.3 → 0.11.5

package/README.md

@@ -2,19 +2,13 @@
 
 > 🇯🇵 [README-ja.md](./README-ja.md)
 
-The daemon that serves one **instance** (= one config home) as an endpoint of the contract,
-together with its CLI and the plugins it hands to agents.
+The daemon that serves one **instance** (= one config home) as an endpoint of the contract, together with its CLI and the plugins it hands to agents.
 
 - `daemon` — holds sessions, delivery, topics and the mesh, and answers the contract's ops over UDS / WS
 - `cli` — the entry point a session calls its instance through (`ccmsg`)
-- `plugin` — the plugin an agent receives (`ccmsg plugin install claude`). Claude Code is the only
-  agent that has one; a codex plugin is not implemented, and what it would take is tracked in
-  [`docs/issue/2026-09-09-codex-plugin-delivery-via-thread-queue.md`](./docs/issue/2026-09-09-codex-plugin-delivery-via-thread-queue.md)
+- `plugin` — the plugin an agent receives (`ccmsg plugin install claude`). Claude Code is the only agent that has one; a codex plugin is not implemented, and what it would take is tracked in [`docs/issue/2026-09-09-codex-plugin-delivery-via-thread-queue.md`](./docs/issue/2026-09-09-codex-plugin-delivery-via-thread-queue.md)
 
-The wire contract is [`@ccmsg/protocol`](https://github.com/kawaz/ccmsg-protocol), pinned to a
-version here. Who may call what, and what comes back, is decided by the contract's attribute
-table and schemas; the daemon reads them rather than carrying validation or authorization
-branches of its own.
+The wire contract is [`@ccmsg/protocol`](https://github.com/kawaz/ccmsg-protocol), pinned to a version here. Who may call what, and what comes back, is decided by the contract's attribute table and schemas; the daemon reads them rather than carrying validation or authorization branches of its own.
 
 ## What it does not do
 
@@ -23,12 +17,14 @@ branches of its own.
 - Re-derive an upstream judgment (the gateway's severity, Claude Code's permission decisions) or observe another config home
 - Carry validation of its own, or serve v1 alongside — the contract's validator is called, and the new lineage stands as a separate instance
 
-Authenticating a person is not on that list: the daemon answers "who came" itself, with a
-passkey. [docs/DESIGN.md](./docs/DESIGN.md) §9 carries the reason each of these ties back to.
+Authenticating a person is not on that list: the daemon answers "who came" itself, with a passkey. [docs/DESIGN.md](./docs/DESIGN.md) §8.6 carries the reason each of these ties back to.
 
 ## Documentation
 
-- [docs/DESIGN.md](./docs/DESIGN.md) — layers, delivery, the state model, the mesh, and how it is tested
+- [docs/DESIGN.md](./docs/DESIGN.md) — **what it is now**: the purpose and what is not grown, the contract and the layers, authentication, the state model, transcripts and dumps, topics and delivery, the mesh, operation, and how it is tested
+- [docs/decisions/](./docs/decisions/INDEX.md) — **the record of the judgments (DR)**: why something was decided that way, and what was set aside
+- [docs/ROADMAP.md](./docs/ROADMAP.md) — the bundles of work in the order they are taken, pointing at the issues across the three repos
+- [docs/design/](./docs/design/README.md) — the design details that stand on their own (authentication between instances, the item types of a dump)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccmsg/cli",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "The ccmsg daemon, CLI and agent plugins for one instance (= one config home)",
   "license": "MIT",
   "author": "kawaz",

package/src/auth/auth.ts

@@ -44,7 +44,7 @@ import { CborError } from "./cbor.ts";
 
 /** How long an access token is accepted, and how long a refresh token is.
  *
- * Chosen rather than derived, within the DR's "hours" and "days" (§2.4). The
+ * Chosen rather than derived, within the DR's "hours" and "days" (DR-0001 §2.4). The
  * access token's life is also a connection's: a client renews on the
  * connection it already holds, so the period is what bounds a stolen token
  * rather than how often a person is interrupted. The refresh token's life is
@@ -84,7 +84,7 @@ export const CODE_ATTEMPTS = 5;
 /** How many `/auth/*` requests are answered per second, over all callers.
  *
  * The routes are reached before anything is proven, like the mesh's key
- * endpoint (§6), and the work behind them is a signature verification. The cap
+ * endpoint (mesh-peer-auth §6), and the work behind them is a signature verification. The cap
  * is far above what a person at a keyboard produces and far below what would
  * cost this instance anything. */
 export const AUTH_RATE_LIMIT = 30;
@@ -102,7 +102,7 @@ interface Pending {
   attempts: number;
 }
 
-/** One challenge this instance issued, good once (§2.6). */
+/** One challenge this instance issued, good once (DR-0001 §2.6). */
 interface Issued {
   readonly expiresAt: Timestamp;
 }
@@ -194,7 +194,7 @@ export class Auth {
     return (this.deps.now ?? Date.now)();
   }
 
-  // --- issuing a registration URL (§2.2) ---
+  // --- issuing a registration URL (DR-0001 §2.2) ---
 
   /** Make one registration URL and the code that goes with it.
    *
@@ -345,7 +345,7 @@ export class Auth {
     for (const sub of removed) this.disconnect(sub);
   }
 
-  // --- challenges (§2.6) ---
+  // --- challenges (DR-0001 §2.6) ---
 
   challenge(): AuthChallengeResult {
     this.#forget();
@@ -365,7 +365,7 @@ export class Auth {
   }
 
   /** Spend a challenge wherever it was issued: here, or at the instance the
-   * caller says issued it (§2.4, behind a load balancer either may be
+   * caller says issued it (DR-0001 §2.4, behind a load balancer either may be
    * reached). */
   async #spendAnywhere(challenge: AuthChallenge): Promise<void> {
     if (challenge.issuer === this.deps.self) {
@@ -402,13 +402,13 @@ export class Auth {
     return ask(iss, op, args);
   }
 
-  // --- registration (§2.2) ---
+  // --- registration (DR-0001 §2.2) ---
 
   /** Verify a registration and write the credential down.
    *
    * The registration URL is checked where its secret is, which may be another
    * instance; everything else — the WebAuthn verification, the record — is done
-   * here, by whoever the browser reached (§2.6). */
+   * here, by whoever the browser reached (DR-0001 §2.6). */
   async register(
     args: AuthRegisterArgs,
     from: { ip?: string; userAgent?: string; path?: string } = {},
@@ -493,7 +493,7 @@ export class Auth {
    *
    * The claims come back from the issuer having been checked and consumed, and
    * everything after this — the WebAuthn verification, the record — is done by
-   * whichever instance the browser actually reached (§2.6). */
+   * whichever instance the browser actually reached (DR-0001 §2.6). */
   async #claimsOf(args: AuthRegisterArgs): Promise<RegisterClaims> {
     const stated = claimsOf(args.token);
     if (stated.iss === this.deps.self) return this.resolveRegistration(args.token, args.code);
@@ -530,7 +530,7 @@ export class Auth {
     if (code === undefined || !equalStrings(code, held.code)) {
       held.attempts += 1;
       // The URL itself is spent once the tries are gone, so guessing the code
-      // costs the whole registration rather than one attempt (§2.2).
+      // costs the whole registration rather than one attempt (DR-0001 §2.2).
       if (held.attempts >= CODE_ATTEMPTS) {
         this.#pending.delete(stated.jti);
         throw new OpError(
@@ -544,7 +544,7 @@ export class Auth {
     return held.claims;
   }
 
-  // --- assertion (§2.5) ---
+  // --- assertion (DR-0001 §2.5) ---
 
   async assert(
     args: AuthAssertArgs,
@@ -620,7 +620,7 @@ export class Auth {
    *
    * The one the credential was registered under, which the record carries: a
    * passkey only ever answers for the domain it was made under, and the
-   * endpoint being reached says nothing about that (§2.3). Nothing is widened
+   * endpoint being reached says nothing about that (DR-0001 §2.3). Nothing is widened
    * to a suffix, and a record from before the field existed names the host of
    * the endpoint it was registered for. */
   #rpIdFor(record: CredentialRecord): string[] {
@@ -633,9 +633,9 @@ export class Auth {
    *
    * Its own is there because a browser may land here holding a URL another
    * instance issued — the page it runs the exchange from is then this
-   * instance's, and the issuer is only asked to spend the URL (§2.6).
+   * instance's, and the issuer is only asked to spend the URL (DR-0001 §2.6).
    *
-   * Read by the HTTP carrier, which compares them whole (§2.3). Not the relying
+   * Read by the HTTP carrier, which compares them whole (DR-0001 §2.3). Not the relying
    * party: an RP ID is a domain, so a page at any host under it would be let in
    * — and `/auth/refresh` answers a cookie the browser attaches by domain, so a
    * sibling subdomain admitted here would read a person's access token. What
@@ -651,7 +651,7 @@ export class Auth {
     return [...origins];
   }
 
-  // --- tokens (§2.4) ---
+  // --- tokens (DR-0001 §2.4) ---
 
   /** Make a family for this person, minted by this instance. */
   mint(sub: Subject): MintedSession {
@@ -673,7 +673,7 @@ export class Auth {
    * A family is written by its `iss` alone, so a rotation that landed here for
    * a family minted elsewhere is carried there rather than done here — two
    * instances rotating one family in parallel would merge by last write and
-   * read exactly like a stolen token being replayed (§2.4). */
+   * read exactly like a stolen token being replayed (DR-0001 §2.4). */
   async refreshToken(value: Base64Url, from: RefreshFrom = {}): Promise<MintedSession> {
     const held = this.deps.records.byRefresh(value);
     if (held === undefined) {
@@ -783,7 +783,7 @@ export class Auth {
 
   /** A value that is nobody's standing token but was somebody's: the family it
    * belonged to is failed, because a token in use twice is a token that was
-   * taken (§2.4).
+   * taken (DR-0001 §2.4).
    *
    * Recognised three ways: the standing refresh token past its expiry, the one
    * before it past its grace, and any generation this instance rotated away
@@ -813,7 +813,7 @@ export class Auth {
     }
   }
 
-  // --- connections (§2.5) ---
+  // --- connections (DR-0001 §2.5) ---
 
   /** Whether an access token opens a connection, and until when. */
   admits(access: Base64Url): { sub: Subject; expiresAt: Timestamp } | undefined {
@@ -861,7 +861,7 @@ export class Auth {
     return this.#authorized.get(conn)?.expiresAt;
   }
 
-  /** Extend a live connection with a token got from `/auth/refresh` (§2.5). */
+  /** Extend a live connection with a token got from `/auth/refresh` (DR-0001 §2.5). */
   extend(conn: Requester, args: AuthExtendArgs): AuthExtendResult {
     const held = this.#authorized.get(conn);
     if (held === undefined) {
@@ -879,7 +879,7 @@ export class Auth {
     return { auth_expires_at: admitted.expiresAt };
   }
 
-  // --- the rate limit the unauthenticated routes share (§2.4) ---
+  // --- the rate limit the unauthenticated routes share (DR-0001 §2.4) ---
 
   allowRequest(): boolean {
     const now = this.#now();
@@ -929,7 +929,7 @@ export function authHandlers(auth: Auth) {
       }
       // The digits arrive unjudged from wherever the browser landed, and are
       // checked here — this is the instance holding both the secret that signed
-      // the URL and the count of tries against it (§2.2).
+      // the URL and the count of tries against it (DR-0001 §2.2).
       return { kind: "register", claims: auth.resolveRegistration(args.token, args.code) };
     },
     "auth.rotate": (input: HandlerInput): AuthRotateResult => {
@@ -1011,7 +1011,7 @@ function token(): Base64Url {
  * A JWS with HS256, because the value travels in a URL fragment and has to
  * survive being carried there: the shape is the conventional one, and the
  * verifier is the issuer itself, so nothing about it is a key anyone else
- * needs (§2.2). */
+ * needs (DR-0001 §2.2). */
 function sign(claims: RegisterClaims, secret: Buffer): string {
   const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "JWT" })).toString("base64url");
   const body = Buffer.from(JSON.stringify(claims)).toString("base64url");
@@ -1060,7 +1060,7 @@ function challengeIn(clientDataJson: Base64Url): Base64Url {
   return challenge;
 }
 
-/** The host an endpoint names, which is the relying party by default (§2.3). */
+/** The host an endpoint names, which is the relying party by default (DR-0001 §2.3). */
 export function hostOf(endpoint: Endpoint): string {
   return new URL(endpoint).hostname;
 }

package/src/auth/http.ts

@@ -60,7 +60,7 @@ export function endpointPath(pathname: string): string {
 /** The cookie path for a request: everything up to and including its `/auth/`.
  *
  * It narrows what the browser sends where, and nothing more — same-origin
- * script can fetch any path, so this is not an authorization boundary (§2.4).
+ * script can fetch any path, so this is not an authorization boundary (DR-0001 §2.4).
  * What it is for is that two endpoints behind one origin (`/` and `/personal`)
  * get cookies of their own. */
 export function cookiePath(pathname: string): string {
@@ -102,7 +102,7 @@ export interface AuthRoutesDeps {
  *
  * Everything unauthenticated shares one rate limit and one origin check: these
  * routes are reachable before anything is proven, and the work behind them is a
- * signature verification (§2.4). */
+ * signature verification (DR-0001 §2.4). */
 export async function handleAuth(
   request: Request,
   deps: AuthRoutesDeps,
@@ -116,7 +116,7 @@ export async function handleAuth(
   // anything else, including the preflight that would tell it to try. Compared
   // whole rather than by domain: `/auth/refresh` answers with a person's access
   // token, and a browser attaches the cookie it is asked for by domain, so a
-  // sibling subdomain let in here could read that token (§2.3).
+  // sibling subdomain let in here could read that token (DR-0001 §2.3).
   if (origin !== null && !deps.auth.knownOrigins().includes(origin)) {
     return new Response("Forbidden", { status: 403 });
   }

package/src/auth/records.ts

@@ -57,7 +57,7 @@ function covers(tombstone: string, key: string): boolean {
 }
 
 export interface RecordsDeps {
-  /** Where the set is written down (§3.6). */
+  /** Where the set is written down (DESIGN §2.5). */
   readonly dir: string;
   /** This instance's id, which is the one thing that makes a record arriving
    * from a peer refusable on sight: a family this instance minted is written by
@@ -76,7 +76,7 @@ export interface RecordsDeps {
  * write to the keys it covers, so a peer coming back from a partition cannot
  * carry a revoked credential in as news.
  *
- * Written down for the same reason the store is (§3.6): none of it is derived
+ * Written down for the same reason the store is (DESIGN §2.5): none of it is derived
  * from anything else this instance holds. A credential exists nowhere but here
  * and in the authenticator, and losing a family logs its person out. */
 export class AuthRecords {

package/src/auth/webauthn.ts

@@ -245,7 +245,7 @@ export const SUPPORTED_ALGORITHMS: readonly number[] = [ES256, EdDSA, RS256];
  * Done at registration rather than at the first assertion: a key that cannot be
  * imported is a credential that can never be used, and finding that out when
  * the person tries to sign in leaves a record nobody can explain. The imported
- * key itself is thrown away — an assertion imports its own (§2.10). */
+ * key itself is thrown away — an assertion imports its own (DR-0001 §2.10). */
 export async function checkPublicKey(cose: Uint8Array): Promise<void> {
   const key = decodeCborWhole(cose);
   const alg = mapEntry(key, 3);

package/src/cli.ts

@@ -76,7 +76,7 @@ import {
 import { type Run, runCommand, serviceFor } from "./service/index.ts";
 import { VERSION } from "./version.ts";
 
-/** The session this process runs inside, as its environment says (§3.8).
+/** The session this process runs inside, as its environment says (DESIGN §4.1).
  *
  * One reading for every command that speaks as a session: which harness
  * claimed the process settles both who the sender is and which instance it
@@ -644,9 +644,9 @@ async function runInstance(given: string | undefined): Promise<unknown> {
   // The directory is handed over rather than put in the environment: the
   // instance would otherwise read it back through the question "which session
   // is this process inside", and a `daemon run` issued from a session of
-  // another harness would answer for that session's config home (§3.8).
+  // another harness would answer for that session's config home (DESIGN §4.1).
   // With a supervisor up, it is the one that reads the files and writes down
-  // what held (§8.2); this start reads what it applied. With none, this
+  // what held (DESIGN §8.2); this start reads what it applied. With none, this
   // process is the only one there is, so it does both.
   const outcome = await start({ configHome: home, settle: !(await reachable()) });
   if (!isRunning(outcome)) {
@@ -657,7 +657,7 @@ async function runInstance(given: string | undefined): Promise<unknown> {
   }
   const instance = outcome;
   // A signal is a request to leave, and leaving is the ordered shutdown of
-  // §8.5 — the same one `instance.shutdown` runs, so a client sees the same
+  // DESIGN §8.5 — the same one `instance.shutdown` runs, so a client sees the same
   // departure either way. The listeners are removed once it has run, because a
   // signal listener keeps the event loop alive and the process would sit at an
   // empty loop instead of exiting.
@@ -689,7 +689,7 @@ async function supervise(): Promise<unknown> {
  * The file first and the supervisor second, because the file is what survives:
  * a host with no supervisor running still gets the config home added, and the
  * next supervisor starts it. Told rather than left to be discovered, because
- * the supervisor reads the list once (DV-Q8) and would otherwise not know
+ * the supervisor reads the list once (DR-0004) and would otherwise not know
  * until it is restarted. */
 async function added(args: readonly string[]): Promise<unknown> {
   const { named, rest } = options(args, ["harness", "port"]);
@@ -722,11 +722,11 @@ async function added(args: readonly string[]): Promise<unknown> {
  *
  * Its own command rather than one under `daemon`, because what it edits is not
  * one instance's anything: every instance of this host is in the same mesh
- * (§7.1), so the list is the host's. `peers` is what a session list is called,
+ * (DESIGN §7.1), so the list is the host's. `peers` is what a session list is called,
  * which is why this is called what the thing itself is called.
  *
  * An addition takes effect when the instances next start, for the reason
- * nothing else reloads either (DV-Q8). A removal is told to whoever is running
+ * nothing else reloads either (DR-0004). A removal is told to whoever is running
  * as well as written down: an endpoint taken off the list is one this host is
  * not to be talking to, and leaving a live link up until the next restart would
  * be leaving exactly the connection that was just revoked. */
@@ -829,7 +829,7 @@ async function configShow(args: readonly string[]): Promise<unknown> {
   }
   // A dry run: the files are read and the settings functions are called, and
   // nothing is written. They are expected to have no side effects for exactly
-  // this reason (§8.2).
+  // this reason (DESIGN §8.2).
   const read = await evaluate(resolveConfigDir());
   if (read.satisfied === undefined) {
     throw new CommandError(
@@ -1437,7 +1437,7 @@ function notify(args: readonly string[]): Promise<unknown> {
 
 /** `ccmsg stopping`: this session is about to go.
  *
- * What it buys is the difference between Paused and Disappeared (§5.2): the
+ * What it buys is the difference between Paused and Disappeared (DESIGN §4.3): the
  * instance holds the declaration until the connection closes, and the entry it
  * then writes carries the instant it was told. The connection closing is the
  * second half of that, so the command says its piece and leaves — which is
@@ -1570,7 +1570,7 @@ async function plugin(
   // The config home is that agent's own, and not whichever variable happens to
   // be set: a Codex session started from a Claude Code session carries both,
   // and an install that read the wrong one would write Codex's hooks into
-  // Claude Code's config home (§3.8). The marker check is what says the
+  // Claude Code's config home (DESIGN §4.1). The marker check is what says the
   // directory really is that agent's.
   const home = configHome(homeOf(which), which);
   const paths = resolvePathsFor(home);

package/src/daemon/control.ts

@@ -64,7 +64,7 @@ export function greetAsUser(conn: Conn): Promise<Record<string, unknown>> {
  * and everything else.
  *
  * By `request_id` rather than by arrival order, because the two are not the
- * same stream: an instance pushes topic frames of its own accord (§6), and one
+ * same stream: an instance pushes topic frames of its own accord (DESIGN §6), and one
  * of those landing between a request and its reply would otherwise be read as
  * the reply. It is not a rare window — greeting an instance that has mesh peers
  * is enough, since a peer connecting moves a row on `instances`. */

package/src/daemon/registry.ts

@@ -32,7 +32,7 @@ import { CommandError } from "./link.ts";
  *
  * The harness's own settings file is what says the directory is a config home
  * rather than any directory somebody typed, so which file is looked for
- * follows which harness the directory runs (§3.8). Checked where a directory
+ * follows which harness the directory runs (DESIGN §4.1). Checked where a directory
  * is named — `add` and `run` — rather than at every use, so the mistake is
  * caught when it is made. */
 export function configHome(dir: string, harness: Harness = DEFAULT_HARNESS): string {
@@ -49,7 +49,7 @@ export function configHome(dir: string, harness: Harness = DEFAULT_HARNESS): str
 
 /** Which harness a registered config home runs, as its own file says.
  *
- * Read from the same file the instance itself will read (§8.2), so a command
+ * Read from the same file the instance itself will read (DESIGN §8.2), so a command
  * that has to know before anything is running — `run`, and the supervisor's
  * own start — reaches the same answer the instance does. A directory no file
  * names runs whatever the defaults say, which is what an unregistered
@@ -99,7 +99,7 @@ export interface InstanceRow {
    * settings for has none. */
   readonly name?: string;
   readonly dir: string;
-  /** The address it binds, and the one its peers dial (§7.1). */
+  /** The address it binds, and the one its peers dial (DESIGN §7.1). */
   readonly port?: number;
   readonly endpoint?: string;
   readonly running: boolean;
@@ -113,7 +113,7 @@ export interface StatusRow extends InstanceRow {
    * what is written. */
   readonly config_problems?: readonly ConfigProblem[];
   /** What this config home's instance is configured with, after the shared
-   * file's defaults and its own entry are merged (§8.2).
+   * file's defaults and its own entry are merged (DESIGN §8.2).
    *
    * Answered whether or not anything is running, and read from the file rather
    * than asked of the instance: this is what a restart would apply, which is
@@ -249,7 +249,7 @@ export function nameFor(dir: string): string {
  *
  * The marker file is the evidence: Claude Code keeps `settings.json` and Codex
  * keeps `config.toml`, so a directory that holds one of them is that harness's
- * (§3.8). A directory holding both, or neither, is not answered for — the
+ * (DESIGN §4.1). A directory holding both, or neither, is not answered for — the
  * first is two answers and the second is none, and guessing either way writes
  * down a setting the instance will act on for the whole of its life. */
 export function harnessOf(dir: string): Harness {
@@ -333,7 +333,7 @@ export async function add(env: Env, dir: string, options: AddOptions = {}): Prom
   // is keyed by, and a fresh one gets its id here rather than at its first
   // start (DR-0001 §2.1).
   const id = instanceIdentity(targetFor(env, home).paths.instanceIdFile);
-  // Every instance listens, because an instance is an entry of the mesh (§7.1)
+  // Every instance listens, because an instance is an entry of the mesh (DESIGN §7.1)
   // and a mesh is reached over the entry: what `--port` settles is which
   // address, not whether there is one.
   const port =
@@ -353,7 +353,7 @@ export async function add(env: Env, dir: string, options: AddOptions = {}): Prom
   );
   // The loopback address, because that is the one this host is certainly
   // reached at. A proxy in front of it is a deployment fact nothing here can
-  // see, so an operator who has one edits this row (§8.2).
+  // see, so an operator who has one edits this row (DESIGN §8.2).
   saveEndpoints(paths.configDir, [
     ...readEndpointRows(paths.configDir).filter((row) => row.id !== id),
     { id, endpoint: `http://127.0.0.1:${String(port)}/` as EndpointRow["endpoint"] },
@@ -563,7 +563,7 @@ export async function status(target: Target): Promise<StatusRow> {
     config: own?.config ?? DEFAULT_CONFIG,
     // What a person has to be told even though the instance is running: an
     // edit that did not check out is not applied, and the only sign of it
-    // otherwise is a setting that did not take (§8.3).
+    // otherwise is a setting that did not take (DESIGN §8.3).
     ...(read.problems.length === 0 ? {} : { config_problems: read.problems }),
   };
   const conn = await connect(target.paths.socket);
@@ -596,7 +596,7 @@ export async function status(target: Target): Promise<StatusRow> {
  *
  * The contract's op rather than a signal, so the request goes through the same
  * authorization every other op does and the caller is told it was accepted
- * before the process goes down (§8.5). */
+ * before the process goes down (DESIGN §8.5). */
 export async function stop(target: Target): Promise<{ dir: string; stopped: boolean }> {
   const conn = await connect(target.paths.socket);
   if (conn === undefined) {
@@ -639,7 +639,7 @@ export const spawnInstance: SpawnInstance = (dir, env) => {
   // The directory is an argument and not an environment variable: `daemon run`
   // takes it from there and hands it to the instance by value, so which config
   // home the child answers for cannot depend on which session the supervisor
-  // was started from (§3.8).
+  // was started from (DESIGN §4.1).
   const proc = Bun.spawn([process.execPath, ENTRY, "daemon", "run", dir], {
     stdio: ["ignore", "ignore", "ignore"],
     env: { ...env } as Record<string, string>,
@@ -679,7 +679,7 @@ export function awaitSocket(paths: InstancePaths, timeoutMs: number): Promise<vo
 }
 
 /** Wait for the lock to be released, which is the last thing a departing
- * instance does (§8.5). */
+ * instance does (DESIGN §8.5). */
 export function awaitGone(paths: InstancePaths, timeoutMs: number): Promise<void> {
   return awaitEntry(paths, timeoutMs, () => {
     const pid = lockHolder(paths.lockFile);

package/src/daemon/snapshot.ts

@@ -41,7 +41,7 @@ interface Greeted {
  * leave.
  *
  * A subscription opens with one `snapshot: true` frame per instance that has a
- * value (§6.2), so the current value of a topic is read by subscribing and
+ * value (DESIGN §6.2), so the current value of a topic is read by subscribing and
  * stopping at the frames rather than by an op of its own. The local instance's
  * frame is deferred behind the acknowledgement and is therefore already on the
  * wire; the relayed ones are what the budget is for.

package/src/daemon/supervise.ts

@@ -30,7 +30,7 @@ import {
  *   still holds the lock needs only the moment that takes, so the first retry
  *   is short enough to be invisible.
  * - `maxMs` bounds a spin. The failure this is really for is a config the
- *   instance refuses to start with (DV-Q9): it fails in milliseconds and will
+ *   instance refuses to start with (DR-0004): it fails in milliseconds and will
  *   fail again identically until somebody edits the file, so the cap is the
  *   rate at which the supervisor is willing to say so in its log while waiting
  *   for that edit.
@@ -93,7 +93,7 @@ class Supervised {
 /** The foreground supervisor: the instances the shared file lists, kept up, and
  * a socket over which they are asked about.
  *
- * The list is read once, when this starts (DV-Q8). What changes it afterwards
+ * The list is read once, when this starts (DR-0004). What changes it afterwards
  * is a request — `daemon add` and `daemon remove` tell the supervisor as well
  * as the file — rather than the file being re-read, so the supervisor's idea of
  * which instances there are and the file's cannot silently disagree about
@@ -122,7 +122,7 @@ export class Supervisor {
   }
 
   /** Read the edited files, check them, write down what held, and look after
-   * what it names (§8.2).
+   * what it names (DESIGN §8.2).
    *
    * This is the one thing that writes the applied settings: the children read
    * them and write nothing, so nothing races over the file and there is one
@@ -316,7 +316,7 @@ export class Supervisor {
   /** Stop one child, and leave it stopped.
    *
    * Asked over its own socket rather than signalled, so what runs is the
-   * ordered shutdown of §8.5 — the same departure a client sees from an
+   * ordered shutdown of DESIGN §8.5 — the same departure a client sees from an
    * `instance.shutdown`. */
   async stopOne(dir: string): Promise<{ dir: string; stopped: boolean }> {
     const unit = this.#units.get(dir);

package/src/dispatch/caller.ts

@@ -10,7 +10,7 @@ export class CallerError extends Error {}
  * The role is read here because it decides which fields the value has to
  * carry — `sid` is present exactly when the role is `session` — and not
  * whether anything is allowed: what the identity may do is decided afterwards,
- * by dispatch, against the attribute table (§3.2). It is the same question
+ * by dispatch, against the attribute table (DESIGN §2.2). It is the same question
  * `hello` asks of a greeting, whose shape depends on its role in the same way
  * and for the same reason: one schema covers all three roles, so the schema
  * cannot state the rule and the instance does.

package/src/dispatch/dispatch.ts

@@ -20,7 +20,7 @@ export interface DispatchDeps {
   readonly capabilities: ReadonlySet<Capability>;
   /** The instance that owns the subject of an `instance-local` op, or
    * `undefined` when no other instance owns it and we answer ourselves.
-   * The routing table behind this is the `peers` topic (daemon-v2 §7.3). */
+   * The routing table behind this is the `peers` topic (DESIGN §7.3). */
   readonly resolveInstance: (op: OpName, frame: Record<string, unknown>) => InstanceId | undefined;
   readonly handlers: Handlers;
 }
@@ -31,7 +31,7 @@ function isOpName(op: string): op is OpName {
 
 /** Decide one frame.
  *
- * The six steps of daemon-v2 §3.2 are written once, here, and read the op
+ * The six steps of DESIGN §2.2 are written once, here, and read the op
  * attribute table for every op. Adding an op is a row in the table plus a
  * schema and an implementation — never a check in this function (M1). */
 export async function dispatch(
@@ -101,7 +101,7 @@ export async function dispatch(
   //
   // 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
-  // deadline expired (§7.3). It is answered rather than left unanswered,
+  // deadline expired (DESIGN §7.3). It is answered rather than left unanswered,
   // because the caller learns the same thing sooner and the code is the one
   // the contract gives a destination that could not be reached.
   const hops = fields["hops"];
@@ -123,7 +123,7 @@ export async function dispatch(
       args: fields,
       conn,
       identity: identity.state === "settled" ? identity : undefined,
-      // The one route by which a role reaches an implementation (§3.2).
+      // The one route by which a role reaches an implementation (DESIGN §2.2).
       role: attrs.scope === "role" && identity.state === "settled" ? identity.role : undefined,
     });
     return reply(requestId, body);

package/src/dispatch/handler.ts

@@ -5,7 +5,7 @@ import type { ConnIdentity, SettledIdentity } from "./identity.ts";
  *
  * It is the `Conn` transport accepted, narrowed to what an op may do with it:
  * read the identity, push frames, and learn that the connection is gone. A
- * subscription is held by a connection and ends with it (daemon-v2 §6.3), so
+ * subscription is held by a connection and ends with it (DESIGN §6.3), so
  * this is what the topic mechanism keys its subscribers on. Declared here
  * rather than imported from transport because dispatch sits below it. */
 export interface Requester {
@@ -25,12 +25,12 @@ export interface Requester {
 /** What an op implementation receives.
  *
  * The arguments are already validated and the caller is already allowed
- * (daemon-v2 §3.2): a handler starts from "this may be run", so it holds no
+ * (DESIGN §2.2): a handler starts from "this may be run", so it holds no
  * check of its own. */
 export interface HandlerInput {
   readonly op: OpName;
   /** The connection the request arrived on. Ops that hold something for the
-   * length of a connection — the subscriptions of daemon-v2 §6.3 — need it;
+   * length of a connection — the subscriptions of DESIGN §6.3 — need it;
    * ops that only answer ignore it. */
   readonly conn: Requester;
   /** The whole request frame, validated against the op's request schema. */
@@ -40,7 +40,7 @@ export interface HandlerInput {
   /** Set only for ops the attribute table marks `scope: "role"`, where the role
    * changes what the reply may contain rather than whether the call is allowed.
    * This is the only route by which a role reaches an implementation
-   * (daemon-v2 §3.2). */
+   * (DESIGN §2.2). */
   readonly role?: Role;
 }
 

package/src/dispatch/identity.ts

@@ -2,7 +2,7 @@ import type { Role, Sid } from "@ccmsg/protocol";
 
 /** What dispatch knows about the connection a frame arrived on.
  *
- * transport settles this (daemon-v2 §3.1): a connection starts anonymous and
+ * transport settles this (DESIGN §2.1): a connection starts anonymous and
  * becomes `settled` when `hello` binds a role, and a session's `sid`, to it.
  * Nothing else about the connection reaches dispatch — the authorization steps
  * read the op attribute table, not the connection. */

package/src/dispatch/result.ts

@@ -3,7 +3,7 @@ import type { ErrorCode, ErrorResponse, InstanceId } from "@ccmsg/protocol";
 /** What dispatch decided about one frame.
  *
  * `forward` is the only outcome that is not an answer: the op belongs to
- * another instance and mesh has to carry it there (daemon-v2 §3.2 step 6).
+ * another instance and mesh has to carry it there (DESIGN §2.2 step 6).
  * There is no mesh yet, so dispatch names the destination and stops. */
 export type DispatchResult =
   /** The frame was not a request and has no answer. The mesh handshake's own
@@ -32,7 +32,7 @@ export class OpError extends Error {
 }
 
 /** The reply envelope, built here and nowhere else so the wire shape stays in
- * one place (daemon-v2 §11.1). */
+ * one place (DESIGN §9.1). */
 export function reply(
   requestId: string,
   body: unknown,