@intentic/sandbox-contract 1.222.0 → 1.224.0

package/src/history-state.ts

@@ -1,14 +1,14 @@
 import type { StateFile } from "./state-portability.js";
 
-/* WHAT LIVES ON /history — the second half of the daemon's state, and the half nothing declared until an
+/* WHAT LIVES ON /history, the second half of the daemon's state, and the half nothing declared until an
  * export had to reason about it.
  *
  * `WORKSPACE_STATE_FILES` covers `<workspace>/.intentic/`, which is where the manifests live. It is not where
- * the machinery lives. Every repo's REAL git dir is here (a repo's in-tree `.git` is a pointer file — see
+ * the machinery lives. Every repo's REAL git dir is here (a repo's in-tree `.git` is a pointer file, see
  * git/repo-git-dirs.ts for the invariant that forces it), and so are the fleet registry, the turn journal, the
  * ledgers, the checkpoint scopes and the isolated agents' checkouts. A "workspace export" that took `/work`
- * alone would carry a tree of repos with dangling gitdir pointers — every git command in the restored sandbox
- * answering `fatal: not a git repository` — and an empty agent board.
+ * alone would carry a tree of repos with dangling gitdir pointers, every git command in the restored sandbox
+ * answering `fatal: not a git repository`, and an empty agent board.
  *
  * The two tables stay separate rather than becoming one keyed by volume, because they answer different
  * questions. A `.intentic` entry also declares which browser QUERY it makes stale, since the file watcher
@@ -17,7 +17,7 @@ import type { StateFile } from "./state-portability.js";
  * imported rather than duplicated.
  *
  * `history-state-coverage.test.ts` fails when a daemon store builds a `/history` path this list doesn't carry, in both
- * directions — the same shape-recognizing guard that covers the workspace table.
+ * directions, the same shape-recognizing guard that covers the workspace table.
  */
 
 // Paths are historyRoot-relative, forward-slash, matched by PREFIX; a directory entry keeps its trailing slash
@@ -27,7 +27,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
 
     /* THE ONE THAT MAKES A BUNDLE A WORKSPACE. Every repo's real git dir, including the /work root's own
      * ("root"), keyed by URI-encoded repo id. Carrying the working tree without this hands the target files
-     * whose `.git` points at a path that does not exist there — which is not a degraded repo but a broken one,
+     * whose `.git` points at a path that does not exist there, which is not a degraded repo but a broken one,
      * and it takes the Changes review, the diff, land and every agent branch with it. The agent BRANCHES live
      * in here too, which is what lets the checkouts below be left out. */
     { path: "gits/", portability: "carry" },
@@ -38,7 +38,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: "agents.json", portability: "carry" },
     { path: "turns/", portability: "carry" },
     { path: "transcripts/", portability: "carry" },
-    // What each message can be put back to — a workspace checkpoint, or an isolated conversation's own commits.
+    // What each message can be put back to, a workspace checkpoint, or an isolated conversation's own commits.
     // Carried WITH the transcripts and the scopes above, because it is the join between them: without it a
     // restored conversation reads back whole and offers no way back into it, even though both the messages and
     // the states they name travelled.
@@ -48,7 +48,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
      * Carried, and it is the entry with the most to say for itself: the PAGES live in the workspace's outbox
      * (`public/`), so they travel with `/work` whatever this says. Leaving the index behind would restore a
      * sandbox that is still serving somebody's conversation on the internet with nothing in the app that knows
-     * it — no row, no link, and no way to stop sharing short of deleting files by hand. The index is what makes
+     * it, no row, no link, and no way to stop sharing short of deleting files by hand. The index is what makes
      * a published page withdrawable, so it goes wherever the pages go. */
     { path: "shares.json", portability: "carry" },
     { path: "activity.jsonl", portability: "carry" },
@@ -58,7 +58,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     // Explicit first-time dependency setup requests. Carrying the worklist preserves the owner's decision when
     // an export interrupts the queue before its terminal starts; fulfilled entries remove themselves.
     { path: "dependency-requests.json", portability: "carry" },
-    // The deploy engine's own ledgers — a run's events and the check results the Pipelines view reads back.
+    // The deploy engine's own ledgers, a run's events and the check results the Pipelines view reads back.
     { path: "apply-events.ndjson", portability: "carry" },
     { path: "check-events/", portability: "carry" },
 
@@ -68,7 +68,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
      *
      * A conversation's worktree is a full checkout of the monorepo per agent (plus its overlay upper dir), and
      * there can be a hundred of them. None of it is unique: the branch it holds is in `gits/` above, and the
-     * registry entry naming it travels in agents.json — so an imported conversation arrives in exactly the
+     * registry entry naming it travels in agents.json, so an imported conversation arrives in exactly the
      * shape the system already has a name for. `attached()` reports its checkout as absent, the board renders
      * it, and the next turn's `ensure()` re-creates it from the recorded composition, which is the same path an
      * archived agent takes when it runs again. The boot sweep's `git worktree prune` clears the stale admin
@@ -84,7 +84,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     { path: ".isolation-probe", portability: "derived" },
     /* The finished bundles themselves. `derived` is doing real work here rather than describing leftovers: an
      * export that carried the export directory would pack every previous bundle into the new one, and the next
-     * export would pack THAT — each one a multiple of the last. Living on this volume is the other half of the
+     * export would pack THAT, each one a multiple of the last. Living on this volume is the other half of the
      * same guard; under `/work` the file would also be watched, indexed by iq, and snapshotted into history. */
     { path: "exports/", portability: "derived" },
 
@@ -107,7 +107,7 @@ export const HISTORY_STATE_FILES: readonly StateFile[] = [
     /* ---- identity: what binds this sandbox to its owner, its browsers and its host ---- */
 
     /* Signs every browser session cookie. Carrying it would let a bundle's holder mint sessions against the
-     * target — an export becomes a credential — and the target minting its own costs exactly one sign-in. */
+     * target, an export becomes a credential, and the target minting its own costs exactly one sign-in. */
     { path: "session-secret", portability: "identity", note: "Sign in again — the target signs its own sessions." },
     {
         path: "browser-access-disabled",

package/src/host-protocol.ts

@@ -1,36 +1,36 @@
 import { z } from "zod";
 
-/* The handshake on /system/hosts/connect — the ONE message that is not oRPC.
+/* The handshake on /system/hosts/connect, the ONE message that is not oRPC.
  *
  * Everything a connected computer is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
  * this socket by oRPC's websocket adapter: the machine hosts the server, the daemon holds the client. But a
  * socket has to prove whose it is before it can be given a typed client, and that proof cannot itself be an
- * oRPC call — the daemon has nothing to call yet, and would be attaching a link to a stranger.
+ * oRPC call, the daemon has nothing to call yet, and would be attaching a link to a stranger.
  *
  * So the machine's first act is this frame, in plain JSON. The daemon verifies the token, learns which
  * capability the socket belongs to, and only then attaches the link; from that message on, every byte on the
  * wire is oRPC. Anything arriving before the link exists is either this frame or a closed socket. */
 
 // The MCP protocol revision the machine's tool server implements. Shared because the daemon answers the
-// handshake ITSELF when the machine is asleep (hosts/host.routes.ts) — two spellings of this would mean an
+// handshake ITSELF when the machine is asleep (hosts/host.routes.ts), two spellings of this would mean an
 // offline machine negotiating a different protocol than the same machine awake.
 export const MCP_PROTOCOL_VERSION = "2025-06-18";
 
 export const HostHelloSchema = z.object({
     type: z.literal("hello"),
-    /* The machine's enrollment token — in the FIRST FRAME, never in the URL. A WebSocket has no headers to put
+    /* The machine's enrollment token, in the FIRST FRAME, never in the URL. A WebSocket has no headers to put
      * it in, and the obvious `?token=` would write a durable key to somebody's laptop into Cloudflare's edge
      * logs, the connector's logs and every proxy in between (the reasoning that moved the browser's upgrades
-     * onto one-shot tickets — auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
+     * onto one-shot tickets, auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
      * arrives the socket is anonymous and short-lived: the daemon closes it in seconds if it never does. */
     token: z.string(),
-    // The @intentic/host build the machine is running — surfaced per machine so an old binary is visible rather
+    // The @intentic/host build the machine is running, surfaced per machine so an old binary is visible rather
     // than mysteriously missing a tool. What the machine IS (`describe`) is not here: it is pulled over the
     // typed link a moment later, so there is one definition of those facts rather than two.
     version: z.string(),
 });
 export type HostHello = z.infer<typeof HostHelloSchema>;
 
-// The URL the machine's agent dials, given the sandbox's public URL. Carries no credential — the token rides
+// The URL the machine's agent dials, given the sandbox's public URL. Carries no credential, the token rides
 // the hello frame. One place builds it, so the agent and the daemon route can't disagree about where it lives.
 export const hostConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/hosts/connect`;

package/src/hostnames.ts

@@ -1,6 +1,6 @@
 // The single source for the tunnel/preview hostname + ingress scheme, shared by the CLI, platform API, daemon,
 // AND the browser. Pure string builders/parsers with NO node imports (unlike ./tunnel-ids, which needs
-// node:crypto for the digest) — so the web bundle can import them and derive identical names. The caller supplies
+// node:crypto for the digest), so the web bundle can import them and derive identical names. The caller supplies
 // the 12-hex id (sandboxIdFromToken/hostSshIdFromToken in node; WebCrypto in the browser).
 //
 // All four apps MUST agree on these strings: a divergence resolves to NXDOMAIN that resolvers negative-cache for
@@ -18,7 +18,7 @@ export const sshHostname = (id: string, zone: string): string => `ssh-${id}.${zo
  *
  * A public DNS name for a private address looks odd until you ask what the alternative is. A browser on the
  * same machine as the sandbox can reach its daemon in microseconds instead of crossing to a Cloudflare edge
- * and back — but only over HTTPS, because Safari refuses http://127.0.0.1 from an HTTPS page as mixed content
+ * and back, but only over HTTPS, because Safari refuses http://127.0.0.1 from an HTTPS page as mixed content
  * (WebKit 171934, open since 2017), and HTTPS needs a name a public CA will certify. An IP literal cannot have
  * one; this can. The daemon holds the key and gets the certificate by proving control of the zone over
  * DNS-01 (there is nothing on the public internet for a CA to connect to).
@@ -36,36 +36,36 @@ export const hostSshTunnelName = (id: string): string => `host-ssh-${id}`;
 // The proxied-CNAME target every tunnel points its DNS record at.
 export const cfargotunnelCname = (tunnelId: string): string => `${tunnelId}.cfargotunnel.com`;
 
-// The cloudflared ingress catch-all — must be the LAST rule.
+// The cloudflared ingress catch-all, must be the LAST rule.
 export const CATCH_ALL = { service: "http_status:404" } as const;
 
-// Preview scheme: `preview-<panel>-<sandboxId>.<zone>` — one DNS label (the free Universal SSL `*.<zone>` cert
+// Preview scheme: `preview-<panel>-<sandboxId>.<zone>`, one DNS label (the free Universal SSL `*.<zone>` cert
 // covers exactly one level), where <panel> is `<repo>` or `<repo>--<app>` and <sandboxId> pins the hostname to
 // this sandbox (the shared intentic zone hosts many sandboxes; without the id two users' panels would collide).
-// Port-forward scheme: `port-<slot>-<sandboxId>.<zone>` — the same shape with a `port-` prefix, where <slot>
+// Port-forward scheme: `port-<slot>-<sandboxId>.<zone>`, the same shape with a `port-` prefix, where <slot>
 // is one of the sandbox's forward slots (portSlotsFromToken in ./tunnel-ids), not the port number itself:
 // slots keep the intentic-provided path's minted routes bounded and warm while dev servers churn ephemeral
 // ports. The slot labels are salted with the connect token rather than being the letters a…h, so a forwarded
-// port's hostname is not derivable from the (public) sandbox id alone — see tunnel-ids for why that matters.
+// port's hostname is not derivable from the (public) sandbox id alone, see tunnel-ids for why that matters.
 //
-// Outbox scheme: `public-<slot>-<sandboxId>.<zone>` — the same shape again, serving the workspace's `public/`
+// Outbox scheme: `public-<slot>-<sandboxId>.<zone>`, the same shape again, serving the workspace's `public/`
 // directory as static files. <slot> is publicSlotFromToken (./tunnel-ids), salted for the same reason the port
 // slots are, and one record per sandbox rather than a pool: there is one outbox, and its link has to stay good
 // for as long as the file does.
 //
 // A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>` /
-// `public-<slot>`) — the unit the platform's /sandbox/preview-route mints, so one endpoint serves all three.
+// `public-<slot>`), the unit the platform's /sandbox/preview-route mints, so one endpoint serves all three.
 export const previewLabel = (panel: string): string => `preview-${panel}`;
 export const portLabel = (slot: string): string => `port-${slot}`;
 export const publicLabel = (slot: string): string => `public-${slot}`;
 
-// The hostname a label resolves to — what the platform's /sandbox/preview-route mints from the label alone.
+// The hostname a label resolves to, what the platform's /sandbox/preview-route mints from the label alone.
 export const labelHostname = (label: string, id: string, zone: string): string => `${label}-${id}.${zone}`;
 export const previewHostname = (panel: string, id: string, zone: string): string => labelHostname(previewLabel(panel), id, zone);
 export const portHostname = (slot: string, id: string, zone: string): string => labelHostname(portLabel(slot), id, zone);
 export const publicHostname = (slot: string, id: string, zone: string): string => labelHostname(publicLabel(slot), id, zone);
 
-// A label's public URL — undefined unless the sandbox has both a zone and an id (headless/loopback sandboxes
+// A label's public URL, undefined unless the sandbox has both a zone and an id (headless/loopback sandboxes
 // have neither and advertise nothing). One builder, three vocabularies: a panel's preview, a forwarded port's,
 // and the outbox's.
 const labelUrl = (label: string, zone: string | undefined, sandboxId: string | undefined): string | undefined =>
@@ -79,7 +79,7 @@ export const publicUrl = (slot: string, zone: string | undefined, sandboxId: str
 
 // The key after `<prefix>` from a request's Host header. The first DNS label must carry the prefix (the
 // own-Cloudflare wildcard also catches stray subdomains → undefined → the caller's 404) and, when the sandbox
-// has an id, the exact `-<sandboxId>` suffix — a fixed-length match, so keys containing `-` stay unambiguous.
+// has an id, the exact `-<sandboxId>` suffix, a fixed-length match, so keys containing `-` stay unambiguous.
 // Without an id the bare label is the key (loopback tests and provider-deployed workspaces, which front the
 // proxy themselves).
 const keyFromHost = (prefix: string, hostHeader: string | undefined, sandboxId: string | undefined): string | undefined => {
@@ -103,7 +103,7 @@ export const publicSlotFromHost = (hostHeader: string | undefined, sandboxId: st
     keyFromHost("public-", hostHeader, sandboxId);
 
 // The sandbox's identity AS THE USER SEES IT: the leading DNS label of its public URL, minus the `sandbox-`
-// prefix — `https://sandbox-0f310c3c4db4.intentic.dev` → `0f310c3c4db4`, i.e. sandboxIdFromToken's digest read
+// prefix, `https://sandbox-0f310c3c4db4.intentic.dev` → `0f310c3c4db4`, i.e. sandboxIdFromToken's digest read
 // back off the wire by anyone holding only the URL. On the own-Cloudflare path the label is whatever subdomain
 // the owner chose, so that is the id there. undefined until the sandbox has a URL at all.
 export const sandboxIdFromUrl = (url: string | undefined): string | undefined => {
@@ -124,8 +124,8 @@ export const sandboxIdFromUrl = (url: string | undefined): string | undefined =>
 };
 
 // The LOCAL folder desktop sync mirrors /work into: `~/intentic/<sandbox name>-<sandboxIdFromUrl>`. Both halves
-// are strings the user already has in front of them — the name in the sandbox switcher, the id in the address
-// bar — so the folder on disk and the sandbox it mirrors read as ONE identity: `~/intentic/shop-0f310c3c4db4`
+// are strings the user already has in front of them, the name in the sandbox switcher, the id in the address
+// bar, so the folder on disk and the sandbox it mirrors read as ONE identity: `~/intentic/shop-0f310c3c4db4`
 // belongs to `https://sandbox-0f310c3c4db4.intentic.dev` and nothing else. Keyed on the URL rather than the
 // name alone for the same reason the hostname is: a torn-down sandbox recreated under the same name gets a new
 // id, hence its own fresh folder instead of reusing the dead one's (which cleanup never deletes) and colliding
@@ -142,7 +142,7 @@ export const syncFolder = (name: string, url: string | undefined): string => {
 
 // The Cloudflare zone from a sandbox public URL (https://sandbox-<id>.<zone> → <zone>): the hostname minus its
 // first DNS label. undefined when the URL is unparsable OR the hostname has fewer than three labels (no zone
-// suffix to strip — e.g. a 2-label host would otherwise yield a bare TLD). Accepts scheme-less input too, so it
+// suffix to strip, e.g. a 2-label host would otherwise yield a bare TLD). Accepts scheme-less input too, so it
 // works whether the caller passes `https://…` (daemon/CLI) or a bare host. This is the single reconciled
 // implementation of what used to be the daemon's `zoneFromPublicUrl` and the web's `zoneFromDaemonUrl`.
 export const zoneFromUrl = (url: string | undefined): string | undefined => {

package/src/index.ts

@@ -53,7 +53,7 @@ export { gitContract } from "./contracts/git.contract.js";
 export { grokContract } from "./contracts/grok.contract.js";
 export { historyContract } from "./contracts/history.contract.js";
 /* Deliberately NOT part of `sandboxContract` below: that map is the daemon's own HTTP surface, and this one is
- * spoken the other way round — over a connected computer's WebSocket, with the MACHINE implementing it. */
+ * spoken the other way round, over a connected computer's WebSocket, with the MACHINE implementing it. */
 export { hostContract } from "./contracts/host.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
@@ -82,13 +82,13 @@ export * from "./routes.js";
 /* THE CONTAINER'S FIXED DIRECTORY LAYOUT, re-exported so extensions can reach it.
  *
  * The names are defined once in @intentic/constants, which sits at the bottom of the dependency graph. An
- * EXTENSION may not import that package — the boundary rule (.oxlintrc.json, _extensions/README.md) allows
+ * EXTENSION may not import that package, the boundary rule (.oxlintrc.json, _extensions/README.md) allows
  * only the SDK halves and this contract, so that an extension cannot couple itself to app or engine internals.
  * That rule is right, and it left extensions with no way to name the workspace root except by spelling it.
  *
  * Re-exporting here is what closes that gap without widening the boundary: the layout is exactly the kind of
- * thing this package already carries — shared vocabulary both sides of the wire must agree on, alongside the
- * state-file table below — and there is still one definition, in one place, that everything resolves to. */
+ * thing this package already carries, shared vocabulary both sides of the wire must agree on, alongside the
+ * state-file table below, and there is still one definition, in one place, that everything resolves to. */
 export { HISTORY_ROOT, HOST_STATE_ROOT, STATE_DIR, WORKSPACE_ROOT } from "@intentic/constants";
 export * from "./workspace-state.js";
 export * from "./runtime-state.js";
@@ -114,7 +114,7 @@ export * from "./title.js";
 export * from "./versions.js";
 export * from "./workflow-faults.js";
 
-// The aggregated contract — implemented on the server by the per-domain route factories and consumed by the
+// The aggregated contract, implemented on the server by the per-domain route factories and consumed by the
 // browser's typed oRPC client (ContractRouterClient<typeof sandboxContract>). The wire paths it declares are
 // mounted at the sandbox root, so /health and /workspace/raw (plain Hono routes) sit alongside it.
 export const sandboxContract = {
@@ -157,14 +157,14 @@ export const sandboxContract = {
 };
 
 // Every route in THIS build of the contract, and the names the daemon advertises on its hello frame. Bound here
-// rather than in routes.ts so that module stays a pure function of whatever contract it is handed — importing
+// rather than in routes.ts so that module stays a pure function of whatever contract it is handed, importing
 // `sandboxContract` from there would close a load-time cycle back through this file. See routes.ts for why a
 // daemon advertises its route surface at all.
 export const SANDBOX_ROUTES: readonly ContractRoute[] = contractRoutes(sandboxContract);
 export const SANDBOX_ROUTE_NAMES: readonly string[] = SANDBOX_ROUTES.map((route) => route.name);
 
 /* And the SHAPE of each of those routes, advertised beside the names for the failure the names cannot describe:
- * a route both builds have, answering a payload only one of them expects. Computed once at module load — it
+ * a route both builds have, answering a payload only one of them expects. Computed once at module load, it
  * walks every contract schema through `z.toJSONSchema`, which is far too much work to repeat per connection and
  * exactly the kind of thing that never changes for the life of a process. See routes.ts. */
 export const SANDBOX_ROUTE_SHAPES: Readonly<Record<string, string>> = routeShapes(sandboxContract);
@@ -174,7 +174,7 @@ export const sandboxRouteName = (method: string, pathWithQuery: string): string
     routeNameForRequest(SANDBOX_ROUTES, method, pathWithQuery);
 
 // The method and concrete path a TYPED call is about to put on the wire, bound to this build's route table.
-// Undefined when the procedure is not one this contract declares, which a typed caller cannot reach — the host
+// Undefined when the procedure is not one this contract declares, which a typed caller cannot reach, the host
 // gate treats it as a refusal rather than assuming it is harmless.
 export const sandboxRequestFor = (procedure: readonly string[], input: unknown): { method: string; path: string } | undefined => {
     const route = routeForProcedure(SANDBOX_ROUTES, procedure);

package/src/listener-protocol.ts

@@ -3,14 +3,14 @@ import { ActivityStatusSchema } from "./schemas.js";
 
 /* The wire between the daemon and an extension's realtime-listener GATEWAY process (ext-discord, ext-slack,
  * ext-telegram, ext-whatsapp, ext-imap): the four provider-scoped routes app.ts mounts under
- * /listeners/:provider — state, dispatch, failure, status. These shapes used to live daemon-side only, with
+ * /listeners/:provider, state, dispatch, failure, status. These shapes used to live daemon-side only, with
  * every gateway hand-writing its own copy of the payloads as untyped literals; a field rename broke five
- * producers silently. They live in the contract now so BOTH ends compile against one declaration — the daemon
+ * producers silently. They live in the contract now so BOTH ends compile against one declaration, the daemon
  * parses with the schemas, the gateways (via @intentic/connector-runtime) type against the inferred types. */
 
-// One normalized inbound event — serialized as a JSON line in the automation's payload, and the JSON body a
+// One normalized inbound event, serialized as a JSON line in the automation's payload, and the JSON body a
 // realtime source POSTs to /listeners/<provider>/dispatch. A zod schema (not a bare interface) because it's
-// parsed from an extension gateway's request; `provider` and `type` are open strings — the source is
+// parsed from an extension gateway's request; `provider` and `type` are open strings, the source is
 // extension-declared (contributes.listener), not a core enum.
 export const ListenerMessageSchema = z.object({
     provider: z.string().min(1),
@@ -22,7 +22,7 @@ export const ListenerMessageSchema = z.object({
     // Discord message: it @mentions one of our bots or replies to a bot's message. Voice events never set it.
     mentioned: z.boolean().optional(),
     // CI pipeline event: the ref it ran on. Top-level rather than inside `extra` for the same reason
-    // `mentioned` is — the dispatcher MATCHES on it, and a narrowing axis the trigger can name has to be
+    // `mentioned` is, the dispatcher MATCHES on it, and a narrowing axis the trigger can name has to be
     // a field of the message rather than a key in a provider's opaque bag.
     branch: z.string().optional(),
     // Prior channel messages (chronological) fetched when a bot is tagged, so the agent can reason about why.
@@ -45,13 +45,13 @@ export const ListenerMessageSchema = z.object({
 });
 export type ListenerMessage = z.infer<typeof ListenerMessageSchema>;
 
-// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response — a text delta for one automation's
+// One ndjson frame of a /listeners/<provider>/dispatch?stream=1 response, a text delta for one automation's
 // reply, the provider's own failure sentence, or that automation's terminal marker. A type, not a schema: the
 // DAEMON produces these (listener.routes.ts), so nothing parses them from untrusted input.
 export interface ListenerDispatchFrame {
     readonly automationId: string;
     readonly delta?: string;
-    // The turn refused or broke, in the provider's own words — forwarded verbatim because a gateway delivers
+    // The turn refused or broke, in the provider's own words, forwarded verbatim because a gateway delivers
     // into the owner's own channel, where the actual sentence is the useful thing.
     readonly failed?: string;
     readonly end?: boolean;
@@ -61,16 +61,16 @@ export interface ListenerDispatchFrame {
  *
  * A CODE IS NOT THE ONLY THING WORTH SAYING, and publishing only codes is what made a phone that had never
  * linked read as connected: the seconds before the first code, a gateway that just restarted, and a number
- * WhatsApp refused all looked identical from the daemon's side — an absent code — so the card fell through to
+ * WhatsApp refused all looked identical from the daemon's side, an absent code, so the card fell through to
  * "ready" and the owner was sent away from the one screen that could have shown them the step. Each of those is
  * its own state here, and every one of them means NOT PAIRED YET.
  *
  * `since` stamps the CURRENT code. WhatsApp closes an unpaired socket after a minute or so and each reopen mints
- * a fresh code, so a code is a thing with an age — the card says how old the one on screen is rather than
+ * a fresh code, so a code is a thing with an age, the card says how old the one on screen is rather than
  * leaving the owner to type a dead one twice. */
 export const ListenerPairingSchema = z.object({
     // waiting: a socket is up and the code hasn't arrived (or the last one died with its socket).
-    // code: `code` is live — type it on the phone. failed: `detail` says what WhatsApp refused.
+    // code: `code` is live, type it on the phone. failed: `detail` says what WhatsApp refused.
     state: z.enum(["waiting", "code", "failed"]),
     code: z.string().optional(),
     detail: z.string().optional(),
@@ -79,11 +79,11 @@ export const ListenerPairingSchema = z.object({
 export type ListenerPairing = z.infer<typeof ListenerPairingSchema>;
 
 // Push-based listener status: a gateway process POSTs its live connection/voice snapshot to
-// /listeners/<provider>/status, and the activity route reads it from there — the daemon holds no provider
+// /listeners/<provider>/status, and the activity route reads it from there, the daemon holds no provider
 // connection of its own to probe. The body IS the ActivityStatus the /activity/status probe used to build from
 // in-process discord singletons, plus the per-gateway extras that ride the same channel: whether whisper is
 // present (discord's voice-pending signal) and each unpaired capability's ceremony by id (whatsapp's
-// link-a-device flow — the capability card renders it as the step the owner is standing in front of).
+// link-a-device flow, the capability card renders it as the step the owner is standing in front of).
 export const ListenerStatusSchema = ActivityStatusSchema.extend({
     whisperReady: z.boolean().optional(),
     pairing: z.record(z.string(), ListenerPairingSchema).optional(),

package/src/model-order.ts

@@ -1,35 +1,35 @@
-/* HOW A MODEL CATALOG IS ORDERED — one rule for every provider, because only one provider publishes an order
+/* HOW A MODEL CATALOG IS ORDERED, one rule for every provider, because only one provider publishes an order
  * worth keeping.
  *
  * Anthropic's REST /v1/models answers newest-first: that IS a provider opinion, and Claude's catalog rides it
- * (claude-models.ts). Every other provider here is read through an OpenAI-compatible /v1/models — Codex and
- * Gemini and Kimi via the bundled translator — or out of xAI's "Did you mean" rejection, and those
+ * (claude-models.ts). Every other provider here is read through an OpenAI-compatible /v1/models. Codex and
+ * Gemini and Kimi via the bundled translator, or out of xAI's "Did you mean" rejection, and those
  * endpoints publish a SET, not a ranking: they hand the ids back in whatever order their registry iterates,
  * which in practice is alphabetical. Reading that as a preference is what put "GPT 5.4 Mini" at the head of the
  * Codex group with GPT 5.6 below it, and what made a fresh Codex conversation start on whichever id happened to
- * sort first — models[0] is the provider default.
+ * sort first, models[0] is the provider default.
  *
  * So for those providers the order is DERIVED from the id, out of the only two facts an id reliably carries:
- * which TIER the model is (the adjective) and which RELEASE it is (the numbers). Both are provider-agnostic —
- * every vendor names its models the same way — which is what lets the daemon's four catalog services and the
+ * which TIER the model is (the adjective) and which RELEASE it is (the numbers). Both are provider-agnostic,
+ * every vendor names its models the same way, which is what lets the daemon's four catalog services and the
  * web's picker share one rule instead of each inventing a local one. */
 
 // A version-ish segment: digits and dots, optionally prefixed by the vendor's version marker (`4`, `5.1`, `v2`,
 // `k3`, `k2.7`, `20251001`). Kimi is the one provider that fuses the marker with the generation; treating `k3`
 // as a name made the current flagship look unversioned, so K2.x sorted above it. Everything else is a NAME
-// segment and belongs to the family — which is what makes the split below exhaustive.
+// segment and belongs to the family, which is what makes the split below exhaustive.
 const VERSION_SEGMENT = /^(?:v|k)?[\d.]+$/i;
 
 // A date stamp rather than a version component: six digits or more (20251001, 250514). The distinction is not
-// cosmetic — claude-opus-4-1-20250805 (Opus 4.1) and claude-opus-4-20250514 (Opus 4.0) compare as (4,1) vs (4)
-// with the stamps held apart, and as (4,1,20250805) vs (4,20250514) — the OLDER model winning — without.
+// cosmetic, claude-opus-4-1-20250805 (Opus 4.1) and claude-opus-4-20250514 (Opus 4.0) compare as (4,1) vs (4)
+// with the stamps held apart, and as (4,1,20250805) vs (4,20250514), the OLDER model winning, without.
 const DATE_SEGMENT = /^\d{6,}$/;
 
 const segmentsOf = (id: string): string[] => id.split(/[-_]/);
 
-// A model's FAMILY — its id with every version-ish segment dropped, so claude-opus-5 and claude-opus-4-8 land
+// A model's FAMILY, its id with every version-ish segment dropped, so claude-opus-5 and claude-opus-4-8 land
 // together (as do gpt-5.1/gpt-5, and claude-haiku-4-5-20251001 with its date suffix). Derived, never listed: a
-// family that ships tomorrow groups itself. The id is the stable key here — labels get renamed, ids don't.
+// family that ships tomorrow groups itself. The id is the stable key here, labels get renamed, ids don't.
 export const familyOf = (id: string): string => {
     const stem = segmentsOf(id)
         .filter((segment) => !VERSION_SEGMENT.test(segment))
@@ -43,7 +43,7 @@ export interface ModelRelease {
     // id (kimi-latest, gemini-pro-agent), which therefore reads as the oldest of its tier: a rolling alias names
     // no release, and inventing one for it would outrank the models that do name theirs.
     readonly version: readonly number[];
-    // The id's date stamp, 0 for none — the tiebreak between two builds of the SAME version.
+    // The id's date stamp, 0 for none, the tiebreak between two builds of the SAME version.
     readonly date: number;
 }
 
@@ -75,14 +75,14 @@ const compareRelease = (left: ModelRelease, right: ModelRelease): number => {
 
 /* THE ONE CURATED FACT in this file, and the only one the providers publish nowhere the app can read: which tier
  * is the frontier and which is the cheap one. It ranks FAMILIES, never models, and it is a vocabulary of tier
- * ADJECTIVES rather than a table of ids — that scoping is the whole point, because a per-model ranking table
+ * ADJECTIVES rather than a table of ids, that scoping is the whole point, because a per-model ranking table
  * failed here once already. The words are the ones every vendor reaches for, so a release that ships tomorrow
  * ranks itself as long as it is named like its predecessors, and a release named some other way ranks as unknown.
  *
  * An UNKNOWN family LEADS rather than sinks, and that direction is the point: the ranking this replaced sank
  * unrecognized ids to a floor below the everyday tier, so a brand-new flagship sorted beneath the model it
- * replaced. An id carrying no tier word at all is the provider's BASE line (gpt-5.6, grok-4, kimi-k2) — which is
- * exactly the line a user reaches for — and a family nobody here has heard of is far likelier to be the next
+ * replaced. An id carrying no tier word at all is the provider's BASE line (gpt-5.6, grok-4, kimi-k2), which is
+ * exactly the line a user reaches for, and a family nobody here has heard of is far likelier to be the next
  * flagship than the next budget tier. Being wrong costs one row's position; being wrong the other way hides a
  * launch. */
 const TIER_RANK: Readonly<Record<string, number>> = {
@@ -113,7 +113,7 @@ const UNRANKED = -1;
 
 /* Some providers name a capability ladder INSIDE one release instead of using the cross-release adjectives
  * above. Codex 5.6's Sol/Terra/Luna rows are that shape: they must remain together ahead of the older 5.5 line,
- * but their order is not an arbitrary id tiebreak — Sol is the strongest, followed by Terra, then Luna. Keeping
+ * but their order is not an arbitrary id tiebreak. Sol is the strongest, followed by Terra, then Luna. Keeping
  * this as a separate rank lets release recency still win across generations (a future GPT 5.7 base model must
  * not be buried under a recognized 5.6 suffix), while the three siblings sort by their real tier. */
 const RELEASE_TIER_RANK: Readonly<Record<string, number>> = {
@@ -135,23 +135,23 @@ const lastRankOf = (family: string, ranks: Readonly<Record<string, number>>): nu
 
 const releaseTierRankOf = (family: string): number => lastRankOf(family, RELEASE_TIER_RANK);
 
-/* HOW HARD AN ID SAYS IT WILL THINK. A routed catalog does not publish one row per model — it publishes one row
+/* HOW HARD AN ID SAYS IT WILL THINK. A routed catalog does not publish one row per model, it publishes one row
  * per model PER THINKING LEVEL, spelling the level into the id: `gemini-3.6-flash-high` and
  * `gemini-3.5-flash-extra-low` are the same Flash at opposite ends of its reasoning budget.
  *
  * Which the ranking above cannot see at all, and that blind spot has a direction: `high` and `low` are both
- * unrecognized words, so two variants of one model tie on tier and the RELEASE tiebreak settles them — and the
+ * unrecognized words, so two variants of one model tie on tier and the RELEASE tiebreak settles them, and the
  * newest variant a channel publishes is routinely the high one. The quick model, whose entire job is to be the
  * cheap rung, would therefore reach for the most expensive reading of the cheapest model it can find.
  *
  * That is not a small mis-sort. Thinking is the difference between a commit message that is in the box before
- * the user has finished reading the file list and one that arrives half a minute later — measured at ~2s versus
+ * the user has finished reading the file list and one that arrives half a minute later, measured at ~2s versus
  * ~27s on the same model and the same diff (agent/one-shot.ts, which disables thinking for the rungs where a
  * request parameter can). For a routed rung there is no such parameter: the id IS the setting, so this ranking
  * is the only place the choice can be made.
  *
  * Read ONLY by the cheap-end order. A picker orders a catalog by what a person reaches for, and a person
- * pinning `-high` on purpose means it — see compareCheapestFirst for the seam this belongs to. */
+ * pinning `-high` on purpose means it, see compareCheapestFirst for the seam this belongs to. */
 const THINKING_RANK: Readonly<Record<string, number>> = {
     minimal: 0,
     none: 0,
@@ -164,7 +164,7 @@ const THINKING_RANK: Readonly<Record<string, number>> = {
     thinking: 4,
 };
 
-/* An id naming NO level sits between the two ends rather than at either — the provider's own default, which for
+/* An id naming NO level sits between the two ends rather than at either, the provider's own default, which for
  * a model that can think is usually some thinking. Ranking it cheapest would seat a silent default ahead of an
  * id that explicitly says `minimal`, and ranking it dearest would bury every model whose channel publishes no
  * variants at all (Anthropic's, Kimi's) beneath one that does. Neither is what the id claims. */
@@ -180,7 +180,7 @@ const thinkingRankOf = (family: string): number => {
 export const tierRankOf = (family: string): number => lastRankOf(family, TIER_RANK);
 
 // The canonical order of two model ids: broad tier first, then release, then a tier declared within that release.
-// Hand it straight to Array#toSorted — that sort is stable, so two ids this rule cannot separate keep the order
+// Hand it straight to Array#toSorted, that sort is stable, so two ids this rule cannot separate keep the order
 // they arrived in (for Claude, the provider's own).
 export const compareModelIds = (left: string, right: string): number => {
     const leftFamily = familyOf(left);
@@ -192,28 +192,28 @@ export const compareModelIds = (left: string, right: string): number => {
     );
 };
 
-/* The order for a catalog its endpoint published as a SET — Codex, Gemini, Kimi and Grok, i.e. everything but
+/* The order for a catalog its endpoint published as a SET. Codex, Gemini, Kimi and Grok, i.e. everything but
  * Anthropic's ranked list. Falling back on arrival order is what the rule above does with a tie, and for a RANKED
  * catalog that is exactly right: the tie is the provider's own opinion, so claude-opus-5 stays ahead of
  * claude-fable-5. For a set there is no opinion to keep, and the header of this file assumed the leftover order
- * was at least alphabetical — it is not. A subscription can hand tied rows back in whatever order its registry
+ * was at least alphabetical, it is not. A subscription can hand tied rows back in whatever order its registry
  * iterated THIS request, so the tie decides which model a fresh conversation opens on and can flip between
  * catalog refreshes.
  *
- * So a set breaks its own ties on the id. Which sibling that seats first is arbitrary — but it is the same
+ * So a set breaks its own ties on the id. Which sibling that seats first is arbitrary, but it is the same
  * arbitrary answer every refresh, which is the property `default` actually needs. */
 export const compareUnrankedModelIds = (left: string, right: string): number => compareModelIds(left, right) || left.localeCompare(right);
 
 /* THE SAME TIER SCALE READ FROM THE OTHER END, for the one caller that wants the WEAKEST model rather than the
  * strongest: the quick model behind an automatic helper (the commit message written at land time). A picker
  * orders a catalog by what a user reaches for; this orders it by what a helper should spend, and the two are
- * exact opposites — so they share TIER_RANK rather than each naming its own list of cheap ids.
+ * exact opposites, so they share TIER_RANK rather than each naming its own list of cheap ids.
  *
  * The direction of UNRANKED is the reason this can't just be compareModelIds reversed. There, an unrecognized
  * family LEADS, because an id carrying no tier word is the provider's base line and a family nobody here has
  * heard of is likelier the next flagship than the next budget tier. Reversing would therefore seat exactly that
- * unknown-probably-flagship id as the cheap pick. So unknown sinks to LAST here too — both orders agree it is
- * not the efficient rung — and the cheap end is only ever a family whose tier word is actually recognized.
+ * unknown-probably-flagship id as the cheap pick. So unknown sinks to LAST here too, both orders agree it is
+ * not the efficient rung, and the cheap end is only ever a family whose tier word is actually recognized.
  * Falling off the end of a catalog with no efficient tier at all (Kimi publishes none) is then honest: the
  * newest of what it does publish, chosen by the release tiebreak below. */
 export const compareCheapestFirst = (left: string, right: string): number => {
@@ -223,14 +223,14 @@ export const compareCheapestFirst = (left: string, right: string): number => {
         tierRankOf(rightFamily) - tierRankOf(leftFamily) ||
         // BEFORE release, and that placement is the point: two rows of one model differing only in thinking
         // level are the same model, so recency has nothing to say between them, and letting it speak is what
-        // seated the high variant. Tier still wins over both — a thinking Haiku is cheaper than a silent Opus.
+        // seated the high variant. Tier still wins over both, a thinking Haiku is cheaper than a silent Opus.
         thinkingRankOf(leftFamily) - thinkingRankOf(rightFamily) ||
         compareRelease(releaseOf(left), releaseOf(right)) ||
         releaseTierRankOf(rightFamily) - releaseTierRankOf(leftFamily)
     );
 };
 
-/* WOULD RUNNING THIS ID MAKE THE MODEL THINK — as far as its name admits, which for a routed catalog is as far
+/* WOULD RUNNING THIS ID MAKE THE MODEL THINK, as far as its name admits, which for a routed catalog is as far
  * as anyone can tell without running it. True only for an id that spells out a level ABOVE the quiet end, so an
  * ordinary id nobody has annotated (claude-haiku-4-5, kimi-k2) is never accused of it.
  *