@intentic/sandbox-contract 1.222.0 → 1.224.0

package/src/output-fields.ts

@@ -1,23 +1,23 @@
 import { z } from "zod";
 
-/* A DECLARED OUTPUT SHAPE — the answer to "what does this session produce?", written once and used three ways.
+/* A DECLARED OUTPUT SHAPE, the answer to "what does this session produce?", written once and used three ways.
  *
  * An agentic session's natural output is prose, and prose is unusable as an input to the next session: a step
  * that must hand "the three files worth changing" to the step after it cannot hand over a paragraph that
  * mentions them. So a session that feeds another one declares its shape here, and that one declaration
  * becomes: the sentence in the prompt that tells the model what to write, the validator that decides whether
  * it complied, and the table the run view renders. Written once because the three drift apart the moment they
- * are written twice — a prompt asking for `files` and a validator wanting `paths` fails on every iteration and
+ * are written twice, a prompt asking for `files` and a validator wanting `paths` fails on every iteration and
  * says nothing useful about why.
  *
  * WHY A FIELD LIST AND NOT JSON SCHEMA. JSON Schema is strictly more expressive and completely unauthorable in
  * a form: nobody designing a workflow is going to hand-write `{"type":"object","properties":{...}}`, and a UI
  * that generates it becomes a schema editor, which is a product of its own. Four scalar types plus a string
- * list covers what one session actually hands another — a verdict, a count, a list of paths, a summary — and
+ * list covers what one session actually hands another, a verdict, a count, a list of paths, a summary, and
  * anything past that is better carried as a file the next step reads.
  *
  * `description` IS REQUIRED, and that is the field that decides whether this works at all. `{name: "risk"}`
- * gets you the model's guess at what risk means; `{name: "risk", description: "high | medium | low — how
+ * gets you the model's guess at what risk means; `{name: "risk", description: "high | medium | low, how
  * likely this change is to break something at runtime"}` gets you the answer to the question you asked.
  */
 
@@ -28,14 +28,14 @@ const FIELD_NAME = /^[a-zA-Z_][a-zA-Z0-9_]{0,39}$/;
 export const OutputFieldSchema = z.object({
     name: z.string().regex(FIELD_NAME),
     type: z.enum(["string", "number", "boolean", "string[]"]),
-    // What the field means, in the words the model is given. Not optional — see the note above.
+    // What the field means, in the words the model is given. Not optional, see the note above.
     description: z.string().min(1),
     // An absent optional field validates; an absent required one does not, and the iteration is told which.
     required: z.boolean(),
 });
 export type OutputField = z.infer<typeof OutputFieldSchema>;
 
-// How many fields one output may declare. A shape past this is not a handoff, it is a report — and a report is
+// How many fields one output may declare. A shape past this is not a handoff, it is a report, and a report is
 // what the prose half of the document is for.
 export const OUTPUT_FIELDS_MAX = 16;
 
@@ -81,13 +81,13 @@ const validatorFor = (field: OutputField): z.ZodType => {
 /* The declared shape as a validator. Unknown keys are ALLOWED THROUGH: a model that answered everything asked
  * of it and then added a `notes` key has complied, and failing it there would burn an iteration teaching it to
  * write less. What is enforced is that every required field is present and every present field has the
- * declared type — the two things the reader downstream is entitled to assume.
+ * declared type, the two things the reader downstream is entitled to assume.
  */
 export const fieldsValidator = (fields: readonly OutputField[]): z.ZodType =>
     z.looseObject(Object.fromEntries(fields.map((field) => [field.name, field.required ? validatorFor(field) : validatorFor(field).optional()])));
 
 // A worked example of the declared shape, so the prompt can show rather than describe. Values are the field's
-// own description — a model copying the example's structure has the description in front of it as it fills each
+// own description, a model copying the example's structure has the description in front of it as it fills each
 // slot, which is where it is needed rather than in a legend three lines up.
 export const fieldsExample = (fields: readonly OutputField[]): Record<string, unknown> =>
     Object.fromEntries(
@@ -106,6 +106,6 @@ export const fieldsExample = (fields: readonly OutputField[]): Record<string, un
         }),
     );
 
-// One line per field, for surfaces with no room to render an example: "risk (string, required) — how likely …".
+// One line per field, for surfaces with no room to render an example: "risk (string, required), how likely …".
 export const describeFields = (fields: readonly OutputField[]): string =>
     fields.map((field) => `- \`${field.name}\` (${field.type}${field.required ? ", required" : ", optional"}) — ${field.description}`).join(`\n`);

package/src/path-refs.ts

@@ -1,6 +1,6 @@
 /* Which file a NAMED reference means. A path written in prose is only loosely anchored to the workspace: an
  * agent that has been working in `_editor/web/src` writes `pages/workspace/Foo.vue`, and a turn running in an
- * isolated worktree prints `/history/worktrees/<id>/_editor/web/src/foo.ts` — neither is the workspace-relative
+ * isolated worktree prints `/history/worktrees/<id>/_editor/web/src/foo.ts`, neither is the workspace-relative
  * path the file routes speak, but both END in it.
  *
  * So a reference is resolved by matching progressively shorter TAILS of it against the real tree. The rules
@@ -32,17 +32,17 @@ export const referenceTails = (raw: string, root: string): readonly string[] =>
     return tails;
 };
 
-// The paths that genuinely END in `tail` on a segment boundary, best first — the shared ranking both matchers
+// The paths that genuinely END in `tail` on a segment boundary, best first, the shared ranking both matchers
 // return their candidates in. Shallowest wins: `pages/Foo.vue` means the app's page, not the copy six
-// directories down in a fixture tree. (The daemon's glob is anchored only at the string level — `**/pages/x.vue`
-// also matches `mypages/x.vue` — so the boundary is enforced here rather than by the pattern.)
+// directories down in a fixture tree. (The daemon's glob is anchored only at the string level, `**/pages/x.vue`
+// also matches `mypages/x.vue`, so the boundary is enforced here rather than by the pattern.)
 export const rankRefCandidates = (tail: string, paths: readonly string[]): readonly string[] =>
     paths
         .filter((path) => path === tail || path.endsWith(`/${tail}`))
         .toSorted((a, b) => a.split(`/`).length - b.split(`/`).length || a.length - b.length || (a < b ? -1 : 1))
         .slice(0, MAX_REF_CANDIDATES);
 
-/* IS THIS FILE TEST CODE — the one classification rule for every surface that splits a diff into "the
+/* IS THIS FILE TEST CODE, the one classification rule for every surface that splits a diff into "the
  * change" and "the proof". The agent review header answers "how much of this is tests?" with it; anything
  * else that wants the split (fleet cards, commit summaries) must use this same predicate, because two
  * classifiers that disagree turn the readout into a lie the user can't detect.
@@ -50,7 +50,7 @@ export const rankRefCandidates = (tail: string, paths: readonly string[]): reado
  * Convention-based, matching what this monorepo (and the ecosystems it scaffolds) actually writes: a
  * `.test.` / `.spec.` filename in any extension, a `__tests__` / `__fixtures__` directory anywhere on the
  * path, an `e2e-harness`, or a test-runner config. Deliberately NOT "anything containing 'test'": a
- * `testimonials/` page or a `latest.ts` is product code, and a false "tests" tag is worse than a missed one —
+ * `testimonials/` page or a `latest.ts` is product code, and a false "tests" tag is worse than a missed one,
  * it tells a reviewer not to look. */
 const TEST_DIRS = new Set([`__tests__`, `__fixtures__`, `__mocks__`, `__snapshots__`]);
 const TEST_FILE =

package/src/publish-drafts.ts

@@ -1,16 +1,16 @@
-/* HOW AN APPROVED POST GETS SENT — the shared half, written once because the daemon acts on it, the app draws
+/* HOW AN APPROVED POST GETS SENT, the shared half, written once because the daemon acts on it, the app draws
  * it, and the two have to agree on the same seconds.
  *
  * THERE IS NO PUBLISHER AUTOMATION ANY MORE, and its absence is the design. Publishing used to be a scheduled
  * automation: a cron waking every few minutes, running a shell guard over the drafts directory, almost always
- * finding nothing — a job whose entire job was to ask "yet?" forever. It also made the approve button
+ * finding nothing, a job whose entire job was to ask "yet?" forever. It also made the approve button
  * conditional on a row in a list nobody had asked for: delete the automation and approvals silently went
  * nowhere, with the button still there and still saying yes. The daemon owns publishing now
  * (drafts-publisher.ts). It knows the moment a draft comes due because it is the process that wrote the draft,
  * so it sleeps until exactly then and costs nothing in between.
  *
  * APPROVAL IS NOT "SEND NOW", IT IS "SEND UNLESS I STOP YOU". A post is public and permanent the instant it
- * lands, and the gap between realising and clicking is about two seconds — so an approved draft carrying no
+ * lands, and the gap between realising and clicking is about two seconds, so an approved draft carrying no
  * date of its own is dated HOLD into the future, and the queue counts it down in the open. The hold is stored
  * as an ordinary scheduledAt rather than as a new state, which is what keeps it honest: it survives a restart,
  * it reads as one number in the same place a scheduled post's date is already read, and calling it off is the
@@ -21,20 +21,20 @@
 export const APPROVAL_HOLD_MS = 60_000;
 
 /* WHO CAN BE SENT BY CODE ALONE. A connector reached through a real API with a stored credential is a request
- * the daemon can make itself — no model, no browser, no turn — and it either got a 200 or it did not. A
+ * the daemon can make itself, no model, no browser, no turn, and it either got a 200 or it did not. A
  * connector that IS a logged-in browser session (reddit, x) has no such door: posting there means driving a
  * page whose markup moves under you, past dialogs and rate screens nobody can enumerate in advance, which is
  * precisely the work an agent turn exists to absorb.
  *
  * So the split follows what the platform actually offers rather than what would be cheaper, and it is stated
- * here rather than guessed at a call site — because being wrong in the optimistic direction means a post that
+ * here rather than guessed at a call site, because being wrong in the optimistic direction means a post that
  * silently never goes out. A platform absent from this set is published by an agent turn, which always works
  * and merely costs more. */
 export const DIRECT_PUBLISH_PLATFORMS: ReadonlySet<string> = new Set(["discord"]);
 
 /* WHAT THE PUBLISH TURN IS TOLD, for the drafts no API can carry. It NAMES the drafts rather than saying "go
  * and look": the daemon has already decided what is due, and a turn that re-derives that decision can disagree
- * with it — sending something the owner pulled back a second ago, or skipping something it judged not ready.
+ * with it, sending something the owner pulled back a second ago, or skipping something it judged not ready.
  * The turn's job is the part only it can do, which is working the platform's own UI.
  *
  * It still writes the outcome back into the file, because the file is where the queue reads it, and a post

package/src/quick-model.ts

@@ -2,7 +2,7 @@ import { ACCESS_COST, accessFor, modelsFor, PROVIDERS } from "./agent-catalog.js
 import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
 import type { AgentProvider } from "./schemas.js";
 
-/* THE QUICK MODEL — the cheap, fast model a small automatic job spends instead of the frontier model the chat
+/* THE QUICK MODEL, the cheap, fast model a small automatic job spends instead of the frontier model the chat
  * runs on. Today that is the commit message written when an agent's work lands; anything else of that shape (a
  * branch name, a PR description) reads the same answer, which is the reason this is a `quickModel` setting
  * rather than a commit-message one.
@@ -11,11 +11,11 @@ import type { AgentProvider } from "./schemas.js";
  * failure: the account it names spends its allowance on the chat all morning, and every job for the rest of the
  * day fails on a limit while three other connected providers sit idle. So the setting is a LIST
  * read top to bottom, the resolver hands back the whole ladder, and the daemon walks it until one answers.
- * Nothing here decides WHICH failures are worth stepping over — that is the daemon's, since only it has run
- * the call — this side only says what the running order is.
+ * Nothing here decides WHICH failures are worth stepping over, that is the daemon's, since only it has run
+ * the call, this side only says what the running order is.
  *
  * The rule lives in the contract because BOTH sides need the same answer for different jobs: the daemon runs
- * the model, and the browser has to NAME it — in the settings row's "Auto (…)" label — before anything has been
+ * the model, and the browser has to NAME it, in the settings row's "Auto (…)" label, before anything has been
  * run. Two implementations would drift precisely where it matters most, since a label promising Haiku while the
  * daemon bills Opus is worse than no label.
  *
@@ -27,14 +27,14 @@ import type { AgentProvider } from "./schemas.js";
 
 /* One provider's standing in the decision: whether a turn on it can be sent at all, and what its catalog holds.
  *
- * ACP agents are deliberately not expressible here — an ACP row's model id is empty because the agent owns its
+ * ACP agents are deliberately not expressible here, an ACP row's model id is empty because the agent owns its
  * own model, so there is no cheap rung to point it at. `endpoint/<id>` providers ARE, and have to be: their
  * models appear in the same picker the settings row builds its options from, so a pin naming one has to hold
  * rather than fall silently back to Auto and spend an account the user was deliberately steering away from. */
 export interface QuickModelSource {
     // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union. Auto's
-    // ranking degrades gracefully for one — costOf falls to the metered rung and an id with no tier word is
-    // UNRANKED, which is genuine last place — so an endpoint effectively only wins Auto when nothing else is
+    // ranking degrades gracefully for one, costOf falls to the metered rung and an id with no tier word is
+    // UNRANKED, which is genuine last place, so an endpoint effectively only wins Auto when nothing else is
     // connected, while a PIN on one holds. Both are the right answers: what a turn on someone's own model server
     // costs is not a fact this repo can know, so it is not one Auto should be asserting.
     readonly provider: AgentProvider;
@@ -67,13 +67,13 @@ export const parsePinned = (pinned: string): QuickModelChoice | undefined => {
 
 /* A pin as a person reads it: the catalog's own label for the id, or the id itself for one the static catalog
  * has not caught up with (the picker offers a custom-id escape hatch, so this is a real case rather than a
- * defensive branch). Beside parsePinned because the two are always wanted together — by any surface that has to
+ * defensive branch). Beside parsePinned because the two are always wanted together, by any surface that has to
  * name what a click is about to spend BEFORE it spends it, and the two loudest of those are extensions that
  * share no other code with each other. */
 export const pinnedModelLabel = (choice: QuickModelChoice): string =>
     modelsFor(choice.provider).find((option) => option.value === choice.model)?.label ?? choice.model;
 
-// The cheapest row a provider publishes — its whole catalog read from the cheap end. Undefined for a catalog
+// The cheapest row a provider publishes, its whole catalog read from the cheap end. Undefined for a catalog
 // that hasn't loaded yet, which is a real state: every provider serves a floor, but only once something has
 // asked it.
 const cheapestOf = (source: QuickModelSource): string | undefined => source.models.toSorted(compareCheapestFirst)[0];
@@ -83,28 +83,28 @@ const cheapestOf = (source: QuickModelSource): string | undefined => source.mode
 // so the row is the provider's base line rather than its budget one.
 const tierOf = (model: string): number => tierRankOf(familyOf(model));
 
-// PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read — the property
+// PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read, the property
 // compareUnrankedModelIds exists to guarantee, and the one a default actually needs. An endpoint is in no fixed
 // list, so it reads -1 and leads the tiebreak; unreachable in practice, since it can never tie on cost.
 const providerOrder = (provider: AgentProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
 
 // How much a call on this provider costs at the margin. Every native provider declares an access kind; an
-// endpoint declares none, and takes the metered rung — the conservative reading of a model API whose bill this
+// endpoint declares none, and takes the metered rung, the conservative reading of a model API whose bill this
 // repo cannot see, which keeps Auto from reaching for someone's paid gateway on its own initiative.
 const costOf = (provider: AgentProvider): number => {
     const access = accessFor(provider);
     return access === undefined ? ACCESS_COST.key : ACCESS_COST[access.kind];
 };
 
-/* AUTO — every connected provider's cheapest row, best-first, as a ladder rather than a winner.
+/* AUTO, every connected provider's cheapest row, best-first, as a ladder rather than a winner.
  *
  * Ranked on TIER FIRST, then cost. That order is the point of the feature: the helper exists to not be the
  * frontier model, so a free flagship is still the wrong tool, while a free Haiku-class row and a subscription
  * Haiku-class row differ only in whose quota they spend. Cost then breaks that tie towards the channel the user
- * is not paying per token for — and against the one they are.
+ * is not paying per token for, and against the one they are.
  *
  * The whole ladder, not just its head, because the same ranking that picks the best answer also states the best
- * SECOND answer — and a sandbox with three accounts connected should not lose its commit messages for six hours
+ * SECOND answer, and a sandbox with three accounts connected should not lose its commit messages for six hours
  * because one of them is spent. */
 const autoLadder = (sources: readonly QuickModelSource[]): readonly QuickModelChoice[] =>
     sources
@@ -144,7 +144,7 @@ export const resolveQuickModels = (sources: readonly QuickModelSource[], pinned:
         const choice = parsePinned(key);
         return choice === undefined || !ready.has(choice.provider) ? [] : [choice];
     });
-    // The same model twice would spend two attempts proving the same account is out — a real state, since the
+    // The same model twice would spend two attempts proving the same account is out, a real state, since the
     // list is edited by hand and Auto's ladder can rank a provider the user has also pinned.
     const chain = [...new Map(requested.map((choice) => [quickModelKey(choice), choice])).values()];
     return chain.length > 0 ? chain : autoLadder(sources);

package/src/routes.ts

@@ -6,18 +6,18 @@ import { z } from "zod";
  * normal and neither should force an update.
  *
  * What must not happen is the failure being SILENT. A route the daemon predates answers 404, which the browser
- * has no way to tell apart from "you asked for a file that isn't there" — so a missing feature reads as a
+ * has no way to tell apart from "you asked for a file that isn't there", so a missing feature reads as a
  * broken one, and diagnosing it costs an hour of "did the image rebuild?".
  *
  * So the daemon ADVERTISES the routes it implements (the /events hello frame) and the browser compares that
  * against the contract it was itself built with. Everything present on both sides works exactly as before;
  * anything the daemon lacks is a KNOWN, NAMED gap the UI can gate a feature on or explain in an error, instead
- * of a mystery 404. Old daemon + new browser stays fully supported — it just stops being confusing.
+ * of a mystery 404. Old daemon + new browser stays fully supported, it just stops being confusing.
  *
  * Route names are `<group>.<route>` (`vpn.list`, `kimi.models`), derived from the contract object both sides
  * import. Nothing is generated and nothing is hand-maintained: adding a route to the contract adds it here.
  *
- * Everything here is a pure function of a contract passed in — index.ts binds them to `sandboxContract` once it
+ * Everything here is a pure function of a contract passed in, index.ts binds them to `sandboxContract` once it
  * is assembled, which is what keeps this module out of an import cycle with it. */
 
 // The shape we read off an oRPC contract procedure. `~orpc.route` is the contract metadata oRPC attaches to
@@ -43,7 +43,7 @@ const procedureRoute = (value: unknown): { method: string; path: string } | unde
 export interface ContractRoute {
     readonly name: string;
     readonly method: string;
-    // The oRPC path template, with `{param}` placeholders — e.g. `/system/terminals/{name}`.
+    // The oRPC path template, with `{param}` placeholders, e.g. `/system/terminals/{name}`.
     readonly path: string;
 }
 
@@ -69,7 +69,7 @@ export const contractRoutes = (contract: Record<string, unknown>): ContractRoute
  *
  * The route list above answers "does this daemon have it". It cannot answer the other half: a route that
  * exists on BOTH sides but whose payload changed between the two builds. Names match, so the call goes out,
- * and a field the browser expects is simply missing from the answer — no 404, no message, nothing to attribute
+ * and a field the browser expects is simply missing from the answer, no 404, no message, nothing to attribute
  * it to. That is the one skew failure the named-gap mechanism still leaves silent.
  *
  * So each route also advertises a fingerprint of its wire shape: input and output schema together, reduced to
@@ -82,25 +82,25 @@ export const contractRoutes = (contract: Record<string, unknown>): ContractRoute
  * "hangs on someone remembering"). Changing a field in a contract schema changes that route's fingerprint by
  * itself, on both sides, with nobody to remember anything. */
 
-// The schemas oRPC hangs off a contract procedure, read structurally for the same reason as `route` above —
+// The schemas oRPC hangs off a contract procedure, read structurally for the same reason as `route` above,
 // they are internal metadata, not part of its public surface.
 interface ContractSchemasLike {
     readonly "~orpc": { readonly inputSchema?: unknown; readonly outputSchema?: unknown };
 }
 
-/* The JSON Schema keywords whose array value is a SET — order carries no meaning, so two schemas that differ
+/* The JSON Schema keywords whose array value is a SET, order carries no meaning, so two schemas that differ
  * only in it are the same wire shape. `required` is the one that matters in practice: JSON Schema spells an
  * object's fields twice, once as `properties` (an object, so key-sorting settles it) and once as `required`
- * (an array, in declaration order) — so without this, moving a field up a `z.object` for readability reads as
+ * (an array, in declaration order), so without this, moving a field up a `z.object` for readability reads as
  * drift on every route that carries it. The union keywords are here for the same reason a step lower down. */
 const UNORDERED = new Set(["required", "enum", "anyOf", "oneOf", "allOf"]);
 
 /* Canonical JSON: object keys sorted, set-valued arrays sorted, everything else left in the order it was
- * written. So the fingerprint depends on what the schema SAYS rather than how zod happened to emit it — which
+ * written. So the fingerprint depends on what the schema SAYS rather than how zod happened to emit it, which
  * is what keeps a purely cosmetic edit from being reported to a user as a payload that moved.
  *
  * Ordered arrays stay ordered: a tuple's `prefixItems` is positional, and sorting it would call two genuinely
- * different shapes identical — the failure that actually costs something here. */
+ * different shapes identical, the failure that actually costs something here. */
 const canonical = (value: unknown, key?: string): unknown => {
     if (Array.isArray(value)) {
         const items = value.map((item) => canonical(item));
@@ -114,7 +114,7 @@ const canonical = (value: unknown, key?: string): unknown => {
 };
 
 /* FNV-1a over the canonical JSON, base36. Deliberately not a cryptographic hash: this is a drift SIGNAL, and
- * the cost of a collision is one warning that never appears — never a wrong action, never a blocked call. A
+ * the cost of a collision is one warning that never appears, never a wrong action, never a blocked call. A
  * crypto digest would mean a subtle-crypto round trip in the browser (async, and unavailable on insecure
  * origins) to buy nothing this use has any need of. */
 const fingerprint = (value: unknown): string => {
@@ -133,8 +133,8 @@ const fingerprint = (value: unknown): string => {
  * way out, so reading both sides in the same direction would call two genuinely different shapes identical.
  *
  * A schema that will not convert yields undefined rather than throwing the walk away. Every such route in the
- * contract today is a streaming one — oRPC wraps an event iterator's output in an opaque type with no schema
- * underneath it — and their absence lands them in exactly the right place: a route with no advertised shape is
+ * contract today is a streaming one, oRPC wraps an event iterator's output in an opaque type with no schema
+ * underneath it, and their absence lands them in exactly the right place: a route with no advertised shape is
  * assumed compatible, which is the same "positive evidence only" rule the missing-route check already runs on. */
 const procedureShape = (value: unknown): string | undefined => {
     if (typeof value !== "object" || value === null || !("~orpc" in value)) {
@@ -174,7 +174,7 @@ export const routeShapes = (contract: Record<string, unknown>): Record<string, s
 };
 
 // Does a concrete request path match this route's template? Segment-wise, with `{param}` matching exactly one
-// segment — the same shape oRPC mounts, so a template can never match a longer or shorter path.
+// segment, the same shape oRPC mounts, so a template can never match a longer or shorter path.
 const pathMatches = (template: string, path: string): boolean => {
     const wanted = template.split("/");
     const actual = path.split("/");
@@ -185,7 +185,7 @@ const pathMatches = (template: string, path: string): boolean => {
 };
 
 // The contract route a concrete request belongs to, or undefined when the path is not a contract route at all
-// (the daemon also serves hand-written Hono routes like /health and /workspace/raw — those are never gated).
+// (the daemon also serves hand-written Hono routes like /health and /workspace/raw, those are never gated).
 // The query string is stripped first; callers pass whatever they handed to fetch.
 export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined => {
     const path = pathWithQuery.split("?")[0] ?? pathWithQuery;
@@ -193,18 +193,18 @@ export const routeNameForRequest = (routes: readonly ContractRoute[], method: st
     return routes.find((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))?.name;
 };
 
-// The route a typed client call belongs to. oRPC addresses a procedure by its position in the contract —
-// `['git','stashApply']` — which is the contract's own name for it, so this is a lookup rather than a match.
+// The route a typed client call belongs to. oRPC addresses a procedure by its position in the contract,
+// `['git','stashApply']`, which is the contract's own name for it, so this is a lookup rather than a match.
 export const routeForProcedure = (routes: readonly ContractRoute[], procedure: readonly string[]): ContractRoute | undefined =>
     routes.find((route) => route.name === procedure.join("."));
 
-// THE CONCRETE PATH A TYPED CALL WILL CARRY — the route template with every `{param}` replaced by the input
+// THE CONCRETE PATH A TYPED CALL WILL CARRY, the route template with every `{param}` replaced by the input
 // field of the same name, which is how the OpenAPI link fills them.
 //
 // This exists so a permission gate can check the string the daemon will actually route on rather than the
 // template it came from. Checking the template would quietly widen every grant: a wildcard glob matches the
 // literal `{repo}` braces just as happily as it matches a repo name, so a manifest that narrowed the grant to
-// one repo would still admit calls for every other — the gate would be comparing two patterns instead of
+// one repo would still admit calls for every other, the gate would be comparing two patterns instead of
 // testing a value against one.
 //
 // A param with no matching input field keeps its placeholder. That cannot be reached through the typed client

package/src/runtime-state.ts

@@ -1,9 +1,9 @@
-/* WHICH RUNNING THING BACKS WHICH VIEW — the twin of workspace-state.ts, for state that never touches a file.
+/* WHICH RUNNING THING BACKS WHICH VIEW, the twin of workspace-state.ts, for state that never touches a file.
  *
  * That table answers "the agent wrote a file, so which view is stale". This one answers the same question for
  * the half of the sandbox that has no file to watch: the tmux sessions, the dev-server panels, the listening
  * sockets, the agent's Chromiums, the children its turns spawn. None of them are on disk, so no
- * `workspaceChanged` batch can ever mention them — and for want of a push, every one of those views polled.
+ * `workspaceChanged` batch can ever mention them, and for want of a push, every one of those views polled.
  *
  * The polls were the tell. Six always-on timers (a 10s terminals relist behind THREE mounted surfaces, a 15s
  * port scan behind the shell rail, a 4s panel relist for as long as any dev server ran) that each asked a
@@ -14,14 +14,14 @@
  * told to. The declaration lives HERE for the reason its twin does: the daemon publishes a DOMAIN and the
  * browser turns it into query keys, and those two facts drift the moment they are written down in two packages.
  *
- * A key belongs to whoever queries it — the extension views that render ports and panels ask under the SAME key
+ * A key belongs to whoever queries it, the extension views that render ports and panels ask under the SAME key
  * as core (api.sandbox.key("ports") is sandboxKey("ports")), so one entry here refreshes both surfaces and an
  * extension needs no declaration of its own. */
 
-/* One query key as the browser files it, a segment per level — so a binding can name a NESTED key and not only
+/* One query key as the browser files it, a segment per level, so a binding can name a NESTED key and not only
  * a top-level one. Most domains here are a single segment and read as they always did; the review is not. Its
  * key is `["git", "changes"]` (the browser appends the sandbox id, and every open file diff hangs beneath it),
- * and a domain that could only say `"git"` would drop the commit log along with it — a second read of the graph
+ * and a domain that could only say `"git"` would drop the commit log along with it, a second read of the graph
  * to deliver a sentence that has nothing to do with it. */
 export type QueryKeyPath = readonly string[];
 
@@ -29,24 +29,24 @@ export interface RuntimeDomainBinding {
     // What moved, in the daemon's words. Wire data: it rides the runtimeChanged frame.
     readonly domain: string;
     /* The browser query keys this domain's state feeds. Invalidation reaches only queries something is
-     * OBSERVING, so a domain nobody has on screen costs a frame and no request — which is what lets a domain be
+     * OBSERVING, so a domain nobody has on screen costs a frame and no request, which is what lets a domain be
      * pushed eagerly without billing every tab for a view it isn't showing. */
     readonly invalidates: readonly QueryKeyPath[];
 }
 
 /* Declared `as const` so the domain names survive as literal types (see RuntimeDomain below), then published
- * under the interface — the same two-binding shape, for the same reason, as WORKSPACE_STATE_FILES. */
+ * under the interface, the same two-binding shape, for the same reason, as WORKSPACE_STATE_FILES. */
 const RUNTIME_DOMAINS = [
     /* Every attachable tmux session: the terminal panel's tab strip, the rail's activity badge, and the work
-     * popover's background-process rows all read this one list. Sampled rather than announced — a pane dies
-     * when its command exits and tmux tells nobody — but sampled ONCE in the daemon, on a connection the
+     * popover's background-process rows all read this one list. Sampled rather than announced, a pane dies
+     * when its command exits and tmux tells nobody, but sampled ONCE in the daemon, on a connection the
      * browsers already hold, instead of once per browser per 10s over the tunnel. */
     { domain: "terminals", invalidates: [["terminals"]] },
 
     /* A repo's dev server: running, healthy, and the preview URL it answers on. Two independent things move it,
-     * and it needs both — the process manager starting or reaping a session (announced), and the server
+     * and it needs both, the process manager starting or reaping a session (announced), and the server
      * actually binding its port some seconds later, which is what flips "starting" to "healthy" (seen by the
-     * port sampler, since panel health is read off the listening sockets — see panels.ts listenersByRepo).
+     * port sampler, since panel health is read off the listening sockets, see panels.ts listenersByRepo).
      *
      * `apps` rides it because a monorepo's per-app previews ARE managed processes under the same manager
      * (workspace.routes appsList reads processes.portOf), just listed per repo instead of per repo-root. One
@@ -54,13 +54,13 @@ const RUNTIME_DOMAINS = [
     { domain: "panels", invalidates: [["panels"], ["apps"]] },
 
     /* Every listening TCP socket in the sandbox, and which of them are forwarded to a public preview hostname.
-     * The daemon runs no port poller for the ANSWER — attributing a socket to its process walks every /proc fd
-     * table, far too much to do on a timer — so what is sampled is only the LISTEN set out of /proc/net/tcp:
+     * The daemon runs no port poller for the ANSWER, attributing a socket to its process walks every /proc fd
+     * table, far too much to do on a timer, so what is sampled is only the LISTEN set out of /proc/net/tcp:
      * two file reads, enough to know that the answer changed and worth nobody's while to compute until a view
      * asks. Change detection and payload are deliberately different sizes here. */
     { domain: "ports", invalidates: [["ports"]] },
 
-    // The agent's Chromiums and the pages each holds open — daemon-held records, minted from the hooks that see
+    // The agent's Chromiums and the pages each holds open, daemon-held records, minted from the hooks that see
     // the agent's own browser tool calls, so every change to this roster passes through this process.
     { domain: "browsers", invalidates: [["browsers"]] },
 
@@ -72,17 +72,17 @@ const RUNTIME_DOMAINS = [
     /* The post queue, when the DAEMON moves it rather than the owner. Approving is the owner's own mutation and
      * refetches itself, but everything after that happens while nobody is touching the page: a held post coming
      * due, a Discord send landing, a publish turn writing back what went out. Those are the moments the row on
-     * screen stops being true — and this queue is watched precisely because its rows go out in public, so it is
+     * screen stops being true, and this queue is watched precisely because its rows go out in public, so it is
      * the last place to leave someone reading a stale one. */
     { domain: "drafts", invalidates: [["drafts"]] },
 
-    /* WHAT A LANDED AGENT'S WORK IS CALLED — the commit message drafted from the diff the moment that work
+    /* WHAT A LANDED AGENT'S WORK IS CALLED, the commit message drafted from the diff the moment that work
      * reaches the main tree (agents/landed-subject.ts), which the review's "From" chip files into the commit box.
      *
      * It needs a push of its own because it arrives LATE, and alone. The review refreshes when a turn ends; the
      * sentence is a model call that STARTS there and answers seconds later, so the refresh the landing itself
      * causes is always too early to carry it. Nothing followed. The message then sat in the daemon, correct and
-     * unread, until some unrelated write happened to refresh the panel again — and a chip clicked in that window
+     * unread, until some unrelated write happened to refresh the panel again, and a chip clicked in that window
      * filed nothing at all, which is indistinguishable from the feature having been removed.
      *
      * Neither a file nor a ref, so this is the only feed that could carry it: the entry holding it lives on
@@ -91,23 +91,23 @@ const RUNTIME_DOMAINS = [
      * Being in this table also puts the review on the reconnect re-ask (runtimeBoundQueryKeys), and that is the
      * half of the fix nothing else covers: a publish with no browser connected is dropped, so a landing drafted
      * while the app was closed or the tunnel was down would otherwise stay invisible for as long as the panel's
-     * snapshot survived — which, at staleTime Infinity, is until something unrelated moved. It costs one review
+     * snapshot survived, which, at staleTime Infinity, is until something unrelated moved. It costs one review
      * read per (re)connect, against a chip that files nothing for the rest of the session. */
     { domain: "landings", invalidates: [["git", "changes"]] },
 ] as const satisfies readonly RuntimeDomainBinding[];
 
 export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;
 
-/* Every domain this table declares, as a type — so a publish site names one of THESE and nothing else, and a
+/* Every domain this table declares, as a type, so a publish site names one of THESE and nothing else, and a
  * renamed domain is a compile error in the daemon rather than a frame the browser silently routes nowhere. */
 export type RuntimeDomain = (typeof RUNTIME_DOMAINS)[number]["domain"];
 
-/* Distinct key paths, in table order — two domains in one frame routinely feed the same view, and a Set cannot
+/* Distinct key paths, in table order, two domains in one frame routinely feed the same view, and a Set cannot
  * see that because each path is its own array. Compared by their segments joined, which is exact: a segment is
  * one identifier from this file, never a caller's string, so there is no separator to collide on. */
 const dedupe = (keys: readonly QueryKeyPath[]): readonly QueryKeyPath[] => [...new Map(keys.map((key) => [key.join(`/`), key])).values()];
 
-/* The query keys a pushed set of domains makes stale, deduped and stable — the browser's `/events` handler
+/* The query keys a pushed set of domains makes stale, deduped and stable, the browser's `/events` handler
  * calls this, exactly as it calls staleQueryKeys for a path batch. Kept here rather than in the web so the rule
  * is unit-testable without a query client, and so the daemon can assert against the same table.
  *
@@ -116,7 +116,7 @@ const dedupe = (keys: readonly QueryKeyPath[]): readonly QueryKeyPath[] => [...n
 export const staleRuntimeQueryKeys = (domains: readonly string[]): readonly QueryKeyPath[] =>
     dedupe(RUNTIME_DOMAIN_BINDINGS.filter((binding) => domains.includes(binding.domain)).flatMap((binding) => binding.invalidates));
 
-/* Every query key any runtime domain feeds — what a NEW /events connection re-asks wholesale, for precisely the
+/* Every query key any runtime domain feeds, what a NEW /events connection re-asks wholesale, for precisely the
  * reason fileBoundQueryKeys exists: this push is these views' ONLY live feed, and a frame produced while the
  * stream was down is a frame nobody will resend. A panel that finished starting, a session that exited, a port
  * that closed while the browser was away would otherwise sit wrong until the next unrelated change. Re-asking