@ccmsg/cli 0.11.2 → 0.11.4

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.2",
+  "version": "0.11.4",
   "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
@@ -438,8 +438,11 @@ const ROOT: Command = {
       options: [
         ["--preset <名前>", "instance が持つ選択 (ccmsg dump presets で一覧)"],
         ["--types <選択>", "型をカンマ区切りで。prefix 可、-で除外、@名前で preset 展開"],
-        ["--since <at|uuid>", "下限。時刻 (ISO か epoch ミリ秒) か record の uuid"],
-        ["--until <at|uuid>", "上限。同上"],
+        [
+          "--since <at|ago|uuid>",
+          "下限。時刻 (ISO か epoch ミリ秒)、今からの差 (-10m / -2h / -1d / -30s)、record の uuid",
+        ],
+        ["--until <at|ago|uuid>", "上限。同上"],
         ["--max-chars <n>", "1 アイテムの本文をこの文字数で切る (既定は切らない)"],
         ["--json", "markdown ではなく dump file の中身をそのまま出す"],
         ["--out <path>", "標準出力ではなくこの path に書く"],
@@ -641,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)) {
@@ -654,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.
@@ -686,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"]);
@@ -719,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. */
@@ -826,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(
@@ -1242,8 +1245,10 @@ async function dump(args: readonly string[]): Promise<unknown> {
     ...dumpArgs(subject, parsed.named),
   })) as unknown as SessionDumpWriteResult;
   const body = readFileSync(written.path, "utf8");
-  const since = parsed.named.get("since");
-  const until = parsed.named.get("until");
+  // What the heading states is where the cut fell, not the words it was asked
+  // for in: a dump read next week cannot work out what "10 minutes ago" was.
+  const since = spelled(resolved("since", parsed.named.get("since")));
+  const until = spelled(resolved("until", parsed.named.get("until")));
   const limit = parsed.named.get("max-chars");
   const text = parsed.flags.has("json")
     ? body
@@ -1301,23 +1306,73 @@ export function dumpArgs(
   };
 }
 
+/** One bound as the heading writes it: a moment in the spelling everything
+ * else states an instant in, and a record id as it was given. */
+function spelled(bound: number | string | undefined): string | undefined {
+  if (bound === undefined) return undefined;
+  return typeof bound === "number" ? new Date(bound).toISOString() : bound;
+}
+
 const AGENT_MARK = "/agent-";
 
-/** One bound, as whichever of the two kinds it was written in.
+/** One bound, as whichever of the kinds it was written in.
  *
- * A time and a record id cannot be confused for one another — one parses as a
- * moment and the other does not — so the caller writes what they have rather
- * than saying which it is. */
+ * A moment and a record id cannot be confused for one another — one reads as a
+ * time and the other does not — so the caller writes what they have rather than
+ * saying which it is. What reads as neither ends the command: a bound nobody
+ * could act on would otherwise be dropped, and a dump asked for "the last ten
+ * minutes" would come back empty with nothing saying why. */
 function bound(kind: "since" | "until", value: string | undefined): Record<string, unknown> {
-  if (value === undefined || value === "") return {};
-  const at = moment(value);
-  return at === undefined ? { [`${kind}_uuid`]: value } : { [`${kind}_at`]: at };
+  const at = resolved(kind, value);
+  if (at === undefined) return {};
+  return typeof at === "number" ? { [`${kind}_at`]: at } : { [`${kind}_uuid`]: at };
 }
 
-function moment(value: string): number | undefined {
+/** A record id, as the harness writes one: the whole uuid.
+ *
+ * Checked rather than assumed, because "not a time" is what a typo looks like
+ * too — and because the id a heading shows is shortened to its first bytes,
+ * which is what a person copies. The instance matches a bound against the
+ * record's own uuid exactly, so a shortened one would cut nothing and answer
+ * with an empty dump. */
+const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** How far back from now a bound may be written: a count and a unit, with the
+ * sign that says it is in the past.
+ *
+ * Only backwards, because what a person asks a transcript for is a stretch
+ * that has already happened. A bound in the future would name a moment nothing
+ * has reached, which is an empty dump asked for in a roundabout way. */
+const AGO = /^-(\d+)(s|m|h|d)$/;
+
+const SPANS: Readonly<Record<string, number>> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/** What one bound turns out to be: a moment, a record id, or nothing written.
+ *
+ * The clock is read here, at the moment the command is given, so `-10m` is ten
+ * minutes before a person typed it rather than before anything the instance
+ * later does. */
+function resolved(
+  kind: "since" | "until",
+  value: string | undefined,
+  now: number = Date.now(),
+): number | string | undefined {
+  if (value === undefined || value === "") return undefined;
+  const ago = AGO.exec(value);
+  if (ago !== null) return now - Number(ago[1]) * (SPANS[ago[2] as string] as number);
   if (/^\d+$/.test(value)) return Number(value);
   const parsed = Date.parse(value);
-  return Number.isNaN(parsed) ? undefined : parsed;
+  if (!Number.isNaN(parsed)) return parsed;
+  if (RECORD_ID.test(value)) return value;
+  throw new CommandError(
+    "invalid_args",
+    `--${kind} は時刻 (ISO か epoch ミリ秒)、今からの差 (-10m / -2h / -1d / -30s)、または record の uuid (短縮形でなく全体) です: ${value}`,
+  );
 }
 
 function chars(value: string): number {
@@ -1382,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
@@ -1515,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);