@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/contracts/system.contract.ts

@@ -27,11 +27,11 @@ import {
 // connection simply never joins the roster.
 export const systemContract = {
     info: oc.route({ method: "GET", path: "/info" }).output(InfoSchema),
-    // What the daemon could not read in its own `.intentic/` manifests — a file it fell back on, a key it did
+    // What the daemon could not read in its own `.intentic/` manifests, a file it fell back on, a key it did
     // not recognise, an entry it skipped. Its own route rather than a field on /info because it is invalidated
     // by a different thing: a manifest changing on disk, which the workspace-state table already broadcasts.
     manifestProblems: oc.route({ method: "GET", path: "/system/manifest-problems" }).output(ManifestProblemsSchema),
-    // Exchange the request's verified bearer (a Google ID token — or a still-valid session, which makes this
+    // Exchange the request's verified bearer (a Google ID token, or a still-valid session, which makes this
     // route sliding renewal) for a daemon-minted session, the credential every steady-state call presents.
     session: oc.route({ method: "POST", path: "/system/session" }).output(DaemonSessionSchema),
     events: oc
@@ -44,28 +44,28 @@ export const systemContract = {
     usage: oc.route({ method: "GET", path: "/system/usage" }).output(UsageSummarySchema),
     // The web-owned tmux sessions behind the terminal tabs. `terminals` enumerates them (the panel rebuilds a tab
     // per name on load/reload); `killTerminal` destroys one when its tab's close button is clicked. The live I/O
-    // is the separate /system/terminal WebSocket — these are just the control plane. Bearer-authed like the rest
+    // is the separate /system/terminal WebSocket, these are just the control plane. Bearer-authed like the rest
     // (browser fetch sends the header), unlike the header-less WS route which app.ts exempts.
     terminals: oc.route({ method: "GET", path: "/system/terminals" }).output(TerminalsListSchema),
     killTerminal: oc.route({ method: "DELETE", path: "/system/terminals/{name}" }).input(TerminalNameParamSchema).output(OkSchema),
-    // One session's pane history as selectable text — the answer to "scroll back and copy that" in a surface
+    // One session's pane history as selectable text, the answer to "scroll back and copy that" in a surface
     // whose live view is a tmux client on the alternate screen, where the scrollback is on the far side of the
     // socket and the page has nothing to select. See TerminalScrollbackSchema.
     terminalScrollback: oc
         .route({ method: "GET", path: "/system/terminals/{name}/scrollback" })
         .input(TerminalScrollbackQuerySchema)
         .output(TerminalScrollbackSchema),
-    // The agent's live Chromiums and the pages each has open — the Browsers view's roster, polled while it is on
+    // The agent's live Chromiums and the pages each has open, the Browsers view's roster, polled while it is on
     // screen and by the rail so its tile can appear the moment a turn starts browsing. The frames are the
     // separate /system/browser-view WebSocket; this is the control plane, exactly as `terminals` is for tmux.
     // `closeBrowser` shuts one Chromium down: the agent's next browser tool call then fails as if it had crashed,
     // which is the honest account of the owner pulling the plug.
     browsers: oc.route({ method: "GET", path: "/system/browsers" }).output(BrowsersListSchema),
     closeBrowser: oc.route({ method: "DELETE", path: "/system/browsers/{name}" }).input(BrowserNameParamSchema).output(OkSchema),
-    // The agents this sandbox's agents started — SDK subagents and delegated Codex/Grok runs alike (see
+    // The agents this sandbox's agents started. SDK subagents and delegated Codex/Grok runs alike (see
     // SubagentSessionSchema). Same two-route shape as the browsers above, and same division of labour: the list
     // is polled by the Subagents area while it is on screen and loosely by the rail, so its tile can appear the
-    // moment a turn delegates. There is no third WebSocket here, because a subagent has no byte stream to watch —
+    // moment a turn delegates. There is no third WebSocket here, because a subagent has no byte stream to watch,
     // what you watch it through is its TRANSCRIPT, which `subagentTranscript` serves in the one shape every
     // other transcript route already answers in: live from the parent turn's frame log while it runs, off the
     // provider's own store once it has finished.
@@ -74,12 +74,12 @@ export const systemContract = {
         .route({ method: "GET", path: "/system/subagents/{id}/transcript" })
         .input(SubagentIdParamSchema)
         .output(SessionTranscriptSchema),
-    /* Start, stop, restart, update, rebuild, roll back or remove a sandbox on one of the user's own computers —
+    /* Start, stop, restart, update, rebuild, roll back or remove a sandbox on one of the user's own computers,
      * the Computers view's buttons, relayed to the machine over the socket it holds open to us.
      *
      * Streamed because the slowest of these takes minutes, and it is the same stream whatever the op: one door
      * for one decision, so the view has one shape to render rather than one per duration. The daemon adds no
-     * judgement — the machine enforces its own switches and its refusal arrives as the terminal `error` line,
+     * judgement, the machine enforces its own switches and its refusal arrives as the terminal `error` line,
      * in its own words, naming the control to flip. */
     manageMachineSandbox: oc
         .route({ method: "POST", path: "/system/computers/{id}/sandboxes/{slug}" })

package/src/contracts/usage.contract.ts

@@ -1,7 +1,7 @@
 import { oc } from "@orpc/contract";
 import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas.js";
 
-// The durable spend ledger (see UsageTurnSchema). Read-only over the wire — rows are appended daemon-side at
+// The durable spend ledger (see UsageTurnSchema). Read-only over the wire, rows are appended daemon-side at
 // turn end, so the ledger stays a trustworthy record of what was actually spent, the same principle as the
 // activity log. `rollup` serves every cost/usage panel: it groups by day × provider × account × model, and the
 // browser re-projects from there (spend per day, cost by model, cache hit rate) without another round trip.

package/src/contracts/vpn.contract.ts

@@ -9,22 +9,22 @@ import {
     VpnListSchema,
 } from "../schemas.js";
 
-// The live VPN surface. A VPN is ADDED as a `vpn` capability (credentials, autoConnect — capabilities.contract);
+// The live VPN surface. A VPN is ADDED as a `vpn` capability (credentials, autoConnect, capabilities.contract);
 // it is DIALLED here. The split is deliberate: connecting is a runtime operation that both the operator (the
 // Sandbox ▸ Status card) and the agent (`vpn` on its PATH, which calls these very routes) perform many times
-// over one stored connection, so it cannot be a capability re-add — and its result is richer than a
+// over one stored connection, so it cannot be a capability re-add, and its result is richer than a
 // CapabilityStatus, which is why `list` returns VpnLinks instead of {state, detail}.
 //
 // Every route reads tunnel state back from the OS rather than from daemon memory, so the agent dropping a
 // tunnel from a shell and the UI dropping it are the same event, and a daemon restart observes the truth.
 export const vpnContract = {
-    // Every configured VPN with its live link state — the Status card, the rail indicator, and `vpn list`.
+    // Every configured VPN with its live link state, the Status card, the rail indicator, and `vpn list`.
     list: oc.route({ method: "GET", path: "/vpn" }).output(VpnListSchema),
     // Dial a stored VPN. Streams the client's progress (auth, then routing) because a dial takes seconds and
-    // can fail with something the user must read — a wrong password, an untrusted gateway certificate, or a
+    // can fail with something the user must read, a wrong password, an untrusted gateway certificate, or a
     // required 2FA code. Idempotent: connecting an already-up tunnel reports it and stops.
     connect: oc.route({ method: "POST", path: "/vpn/{id}/connect" }).input(VpnConnectInputSchema).output(eventIterator(IntenticLineSchema)),
-    // Drop a tunnel. Tolerates an already-down one — "make it not be up" is the contract, not "it was up".
+    // Drop a tunnel. Tolerates an already-down one, "make it not be up" is the contract, not "it was up".
     disconnect: oc.route({ method: "POST", path: "/vpn/{id}/disconnect" }).input(VpnIdParamSchema).output(OkSchema),
     // Parse an exported FortiClient configuration into addable connections, so a user with that file fills the
     // add form by picking a connection instead of re-keying host/port/protocol per tunnel.

package/src/contracts/workflows.contract.ts

@@ -11,11 +11,11 @@ import {
     WorkflowsListSchema,
 } from "../schemas.js";
 
-/* The workflow routes — "run these sessions, in this order, each handing its result to the next".
+/* The workflow routes, "run these sessions, in this order, each handing its result to the next".
  *
  * SPLIT LIKE AUTOMATIONS, NOT LIKE LOOPS, and the split says what a workflow is. A loop has no editor because
- * it is started against a conversation and then it is history; a workflow is a DESIGN — a thing the user
- * authors once, keeps, edits, and runs repeatedly — so it gets the manifest treatment: create/update, delete,
+ * it is started against a conversation and then it is history; a workflow is a DESIGN, a thing the user
+ * authors once, keeps, edits, and runs repeatedly, so it gets the manifest treatment: create/update, delete,
  * list. What it does not get is an `enabled` toggle, because nothing fires it on its own: a workflow runs when
  * somebody (or an automation's prompt) says run it.
  *
@@ -28,25 +28,25 @@ export const workflowsContract = {
     // page shows both and a workflow with no runs is the interesting case, not an error.
     list: oc.route({ method: "GET", path: "/workflows" }).output(WorkflowsListSchema),
     /* Create or replace a workflow, with the operation made explicit so an accidental id collision cannot turn
-     * a create into replacement. Refuses a graph that cannot run — a cycle, a `needs` naming a step
-     * that is not there, a step with no way to know it is finished — with the same sentences the designer shows
+     * a create into replacement. Refuses a graph that cannot run, a cycle, a `needs` naming a step
+     * that is not there, a step with no way to know it is finished, with the same sentences the designer shows
      * while you type (see workflowFaults). Validation lives in the contract precisely so those two can never
      * disagree about what is legal. */
     save: oc.route({ method: "POST", path: "/workflows" }).input(WorkflowSaveSchema).output(WorkflowSchema),
     // Deleting a workflow does NOT stop a run of it that is in flight, and does not delete its history: the run
     // snapshotted its definition when it started, so it stays readable and stays stoppable.
     remove: oc.route({ method: "DELETE", path: "/workflows/{id}" }).input(WorkflowIdParamSchema).output(OkSchema),
-    /* Start a run, optionally pointed at a request — the sentence the user typed in the composer, which every
+    /* Start a run, optionally pointed at a request, the sentence the user typed in the composer, which every
      * step is handed on top of its own prompt. Every step is recorded `pending` up front, so the graph is
      * complete from the first frame and a missing node never has to mean two things. Several runs of one
-     * workflow may be in flight at once — they derive different conversation ids, so nothing is shared and
+     * workflow may be in flight at once, they derive different conversation ids, so nothing is shared and
      * nothing can collide, which is what makes "run this design again on a different question" free. */
     run: oc.route({ method: "POST", path: "/workflows/{id}/run" }).input(WorkflowRunStartSchema).output(WorkflowRunSchema),
-    // Every run across every workflow, newest first — the history the run view opens onto, and the only place a
+    // Every run across every workflow, newest first, the history the run view opens onto, and the only place a
     // deleted workflow's runs are still reachable.
     runs: oc.route({ method: "GET", path: "/workflows/runs" }).output(WorkflowRunsListSchema),
     /* Stop a run: nothing that has not started will start, and the steps in flight are CUT OFF where they
-     * are — their turns aborted exactly as /agent/stop aborts one, so whatever they had written stays on
+     * are, their turns aborted exactly as /agent/stop aborts one, so whatever they had written stays on
      * their branches and the step settles as stopped.
      *
      * Not the graceful "finish the iteration you are on" a LOOP's stop performs, and the difference is the
@@ -54,18 +54,18 @@ export const workflowsContract = {
      * Waiting for one meant a stopped run kept working, kept spending and kept asking questions for minutes
      * after the press, which is indistinguishable from a button that does nothing.
      *
-     * IT ALWAYS ENDS THE RUN, including one no scheduler is behind — a record left `running` by a daemon that
+     * IT ALWAYS ENDS THE RUN, including one no scheduler is behind, a record left `running` by a daemon that
      * was replaced mid-flight. That case used to be refused, which made the stuck run permanent: a Stop that
      * could not work, a step count that would never move, and no way off the board.
      */
     stopRun: oc.route({ method: "POST", path: "/workflows/runs/{runId}/stop" }).input(WorkflowRunIdParamSchema).output(OkSchema),
-    /* Take an ENDED run off the board — the run's half of `agents.archive`, and the same bargain: nothing is
+    /* Take an ENDED run off the board, the run's half of `agents.archive`, and the same bargain: nothing is
      * lost, the checkouts are reclaimed, and `unarchiveRun` puts it all back. It needs an exit of its own
      * because nothing about a run transitions once it is over, so a failed one would sit in Attention until
      * fifty more had rolled it off the ledger. Refused while the run is going.
      *
      * IT ARCHIVES THE STEPS WITH THE RUN, which is what makes it an archive rather than a dismissal. A step
-     * has no card of its own — the run's row stands for it — so merely dropping the record released the run's
+     * has no card of its own, the run's row stands for it, so merely dropping the record released the run's
      * conversations onto the board as loose cards at the exact moment the user said they were done with the
      * job. Every step that ran is archived, on the same terms as pointing `agents.archive` at those ids: that
      * route archives what the user named without re-litigating whether each one was ready to go, and a run the

package/src/contracts/workspace.contract.ts

@@ -36,7 +36,7 @@ import {
     WorkspaceTreeSchema,
 } from "../schemas.js";
 
-// The full /work view + extra-repo cloning. The binary preview (/workspace/raw) is intentionally NOT here — it
+// The full /work view + extra-repo cloning. The binary preview (/workspace/raw) is intentionally NOT here, it
 // stays a plain Hono route serving raw bytes with a Content-Type header (oRPC's request/response shape doesn't
 // fit a streamed binary body). External MCP tools moved to the unified capabilities manifest (mcp kind).
 export const workspaceContract = {
@@ -44,13 +44,13 @@ export const workspaceContract = {
     // tree. Every read route below takes it, so a link into a conversation's own checkout browses as one tree
     // rather than as one openable file surrounded by the shared one.
     tree: oc.route({ method: "GET", path: "/workspace/tree" }).input(WorkspaceScopeSchema).output(WorkspaceTreeSchema),
-    // Lazy-load one directory's children — the tree returns ignored dirs (node_modules, .git, …) without children,
+    // Lazy-load one directory's children, the tree returns ignored dirs (node_modules, .git, …) without children,
     // and the client fetches them here on expand so a giant node_modules can't blow the tree walk's entry budget.
     children: oc.route({ method: "GET", path: "/workspace/children" }).input(WorkspaceChildrenQuerySchema).output(WorkspaceChildrenSchema),
     // One WINDOW of a file's text (plus the file's total size), never the whole file: the browser reads text
     // through here, and an unbounded read on an HTTP route is a way for any open log to stall the daemon.
     file: oc.route({ method: "GET", path: "/workspace/file" }).input(WorkspaceFileReadQuerySchema).output(WorkspaceFileSchema),
-    /* The ticket a media element presents to GET /workspace/media (a plain Hono route, like /workspace/raw —
+    /* The ticket a media element presents to GET /workspace/media (a plain Hono route, like /workspace/raw,
      * it answers a streamed byte RANGE, which oRPC has no shape for). Minting is here rather than beside it so
      * it rides the bearer middleware and the contract's route advertisement: a browser can tell whether the
      * sandbox in front of it can stream video at all, instead of learning it from a 404 mid-playback. */
@@ -58,7 +58,7 @@ export const workspaceContract = {
         .route({ method: "POST", path: "/workspace/media-ticket" })
         .input(WorkspaceMediaTicketQuerySchema)
         .output(WorkspaceMediaTicketSchema),
-    // Which file a NAMED reference means — the lookup behind every clickable path in the UI. A path an agent
+    // Which file a NAMED reference means, the lookup behind every clickable path in the UI. A path an agent
     // wrote in prose is often only a suffix of the real one, so it is matched against the workspace tree rather
     // than trusted as root-relative.
     resolve: oc.route({ method: "GET", path: "/workspace/resolve" }).input(WorkspaceResolveQuerySchema).output(WorkspaceResolveSchema),
@@ -66,16 +66,16 @@ export const workspaceContract = {
     // auto-mode fusion. (Implementation detail: the daemon backs this with a resident in-process iq engine.)
     search: oc.route({ method: "GET", path: "/workspace/search" }).input(WorkspaceSearchQuerySchema).output(WorkspaceSearchResultSchema),
     // One repository's health in numbers: churn × complexity per file, index totals, and the import graph's
-    // top modules — the `hotspots` and `map` rankings the CLI prints, shaped for a panel. Repo-scoped, because
+    // top modules, the `hotspots` and `map` rankings the CLI prints, shaped for a panel. Repo-scoped, because
     // "the codebase" is a repo, not the whole /work drop.
     health: oc.route({ method: "GET", path: "/workspace/health" }).input(WorkspaceHealthQuerySchema).output(WorkspaceHealthSchema),
     // Deterministic, no-LLM classification of the dropped workspace into coarse buckets (repositories / documents
     // / media / archives / other). Read-only proposal: the browser renders it and applies accepted moves via the
-    // existing /workspace/move route — this route never touches the tree.
+    // existing /workspace/move route, this route never touches the tree.
     classify: oc.route({ method: "GET", path: "/workspace/classify" }).output(WorkspaceClassificationSchema),
     // Direct file management the browser drives against the /work tree (byte writes go through POST
     // /workspace/upload). oRPC's OpenAPI codec reads non-GET input from the JSON body, so delete sends {path}
-    // in the body too (not the query) — same as the POST routes.
+    // in the body too (not the query), same as the POST routes.
     mkdir: oc.route({ method: "POST", path: "/workspace/dir" }).input(WorkspaceDirSchema).output(OkSchema),
     delete: oc.route({ method: "DELETE", path: "/workspace/entry" }).input(WorkspaceFileQuerySchema).output(OkSchema),
     move: oc.route({ method: "POST", path: "/workspace/move" }).input(WorkspaceMoveSchema).output(OkSchema),
@@ -83,7 +83,7 @@ export const workspaceContract = {
     // Dependency readiness for every project under /work, and the install that fixes it. An imported project
     // arrives without node_modules/.venv (the drop omits them), so "the files landed" is not "this works":
     // until setup says ready, its type-checks and tests can only lie. The install runs as a one-shot tmux panel
-    // like a dev server or add-app — attachable, survives a reload, output kept in the terminal logs.
+    // like a dev server or add-app, attachable, survives a reload, output kept in the terminal logs.
     setup: oc.route({ method: "GET", path: "/workspace/setup" }).output(WorkspaceSetupSchema),
     install: oc.route({ method: "POST", path: "/workspace/setup/install" }).input(WorkspaceInstallSchema).output(WorkspaceInstallResultSchema),
     repos: oc.route({ method: "GET", path: "/workspace/repos" }).output(ReposListSchema),
@@ -91,27 +91,27 @@ export const workspaceContract = {
     // Force-fetch + guarded fast-forward every repo with a remote (mutates the tree ⇒ POST). The turn hook syncs
     // automatically each turn; this is the on-demand refresh (and how you re-sync a dirty/diverged repo after committing).
     sync: oc.route({ method: "POST", path: "/workspace/sync" }).output(WorkspaceSyncSchema),
-    // The addable app types the configured source repo offers (its templates.json) — drives the apps
+    // The addable app types the configured source repo offers (its templates.json), drives the apps
     // extension's Add-app picker.
     templates: oc.route({ method: "GET", path: "/workspace/templates" }).output(TemplatesListSchema),
     // Per-monorepo apps, driven by the web app's apps extension (owner-authed; {repo} is validated in the
     // handler): add one or more apps into an existing monorepo, list them with per-app preview URL + status,
     // and start/stop each app's preview dev server. `addApps` kicks off a one-shot tmux job (session
-    // panel-<repo>--add_apps) that runs `intentic scaffold add-app` — the attachable terminal is the progress/error
+    // panel-<repo>--add_apps) that runs `intentic scaffold add-app`, the attachable terminal is the progress/error
     // surface; the extension polls the session's `running` for completion. It returns immediately (an ack).
     addApps: oc.route({ method: "POST", path: "/workspace/repos/{repo}/apps" }).input(AddAppsSchema).output(OkSchema),
     appsList: oc.route({ method: "GET", path: "/workspace/repos/{repo}/apps" }).input(RepoAppsParamSchema).output(AppsListSchema),
     // The monorepo's workspace package dependency graph (pnpm-workspace.yaml globs + per-package package.json
-    // workspace deps) — drives the apps extension's Dependencies view.
+    // workspace deps), drives the apps extension's Dependencies view.
     packageGraph: oc.route({ method: "GET", path: "/workspace/repos/{repo}/graph" }).input(RepoAppsParamSchema).output(WorkspaceGraphSchema),
-    // Every repo's modules (the dirs owning a named package.json) — what the review panels group changed files
+    // Every repo's modules (the dirs owning a named package.json), what the review panels group changed files
     // under when the reader has asked for modules instead of paths. Whole-workspace rather than per-repo: a
     // review list spans repos, and one request per repo group would be a fan-out the panel pays on every open.
     modules: oc.route({ method: "GET", path: "/workspace/modules" }).output(WorkspaceModulesSchema),
     startApp: oc.route({ method: "POST", path: "/workspace/repos/{repo}/apps/{app}/start" }).input(AppParamSchema).output(OkSchema),
     stopApp: oc.route({ method: "POST", path: "/workspace/repos/{repo}/apps/{app}/stop" }).input(AppParamSchema).output(OkSchema),
     // Run vitest for the given repo-relative project dirs in a one-shot tmux panel session
-    // (panel-<repo>--<session>) — drives the apps extension's per-app / per-package / library Run-tests actions.
+    // (panel-<repo>--<session>), drives the apps extension's per-app / per-package / library Run-tests actions.
     // Mirrors addApps: it returns an ack; the attachable terminal is the result surface.
     runTests: oc.route({ method: "POST", path: "/workspace/repos/{repo}/tests" }).input(RunTestsSchema).output(OkSchema),
 };

package/src/conversation-ids.ts

@@ -1,37 +1,37 @@
 /* THE NAME A NEW CONVERSATION IS BORN WITH.
  *
- * A conversation's id is not an internal key — it is the most PUBLIC string this app produces. The same value
+ * A conversation's id is not an internal key, it is the most PUBLIC string this app produces. The same value
  * becomes the git branch (`agent/<id>`), the worktree directory on disk, the id in the page's address, and the
  * name printed on every board card (SessionChip). So it is read far more often than it is dereferenced, and by
  * eyes rather than by code: in `git branch`, in a terminal `cd`, on a card in a lane of twenty.
  *
  * It used to be `crypto.randomUUID()`, and a UUID fails every one of those readings. Forty-two characters of
- * hex that no one can say, remember, or tell apart from the card next to it — two agents differ in the fourth
+ * hex that no one can say, remember, or tell apart from the card next to it, two agents differ in the fourth
  * character and look identical at a glance, which is exactly when the board is being scanned rather than read.
  * It was also the widest line on a card that has a title to show. The app already knew this everywhere else:
  * the tmux session for the very same turn is called `agent-32b6cb04` (session-names.ts), eight characters,
  * because eight is what a human uses.
  *
- * So a new conversation gets a name instead: `swift-otter-k9m2`. The pair is the part a person actually uses —
+ * So a new conversation gets a name instead: `swift-otter-k9m2`. The pair is the part a person actually uses,
  * sayable over a call, distinguishable at a glance, and memorable for the hour anyone cares about it. The
  * four-character tail is the part that makes it an id: the pairs alone would start colliding within a few
  * hundred conversations (a workspace passes that in a month), and a branch name that collides is a worktree
  * that refuses to be created. Random rather than a timestamp because a timestamp in base36 is eight characters
  * of its own and would put the length straight back.
  *
- * The shape satisfies ConversationIdSchema (`^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$`) by construction — every word
+ * The shape satisfies ConversationIdSchema (`^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$`) by construction, every word
  * here is lowercase a–z, the tail is lowercase base36, and the separator is the one the regex allows. That
  * guard is the injection guard for the branch name and the path, so it is the one thing about this module that
  * is not a matter of taste; the test beside it holds the whole generated space to it.
  *
  * Conversations the SANDBOX starts keep their own minters and their own prefixes (an automation's fire is
- * `a-<automation>-<time>`, a CI fix is minted from the run) — those names say WHERE the conversation came
+ * `a-<automation>-<time>`, a CI fix is minted from the run), those names say WHERE the conversation came
  * from, which beats a random pair for a card the user did not ask for. This is the default for the ones a
  * person opens.
  */
 
 /* The two halves of the name. Kept short (nothing over seven letters) because the whole point is a string that
- * fits on a card, and visually distinct from one another — no near-rhymes and no two words sharing a first
+ * fits on a card, and visually distinct from one another, no near-rhymes and no two words sharing a first
  * syllable, since a name is only useful here if it can be told apart from its neighbour in the lane. */
 const ADJECTIVES = [
     "amber",
@@ -161,11 +161,11 @@ const randomBelow = (upperBound: number): number => {
     }
 };
 
-// Uniform over the array, drawn from the platform CSPRNG — `Math.random()` is seeded per process, and two
+// Uniform over the array, drawn from the platform CSPRNG, `Math.random()` is seeded per process, and two
 // browser tabs opened in the same instant are exactly the case this must not produce the same name for.
 const pick = <T>(values: readonly T[]): T => values[randomBelow(values.length)]!;
 
-// Lowercase base36, one character per draw — 0-9a-z, all of which the id guard accepts.
+// Lowercase base36, one character per draw: 0-9a-z, all of which the id guard accepts.
 const tail = (): string => Array.from({ length: TAIL_LENGTH }, () => randomBelow(36).toString(36)).join("");
 
 /* A fresh conversation id: `<adjective>-<noun>-<tail>`, e.g. `swift-otter-k9m2`. Sixteen characters or so

package/src/events.test.ts

@@ -3,8 +3,8 @@ import { RESUME_NOTES, resumeDisclosure, withResumeNote, withoutResumeNote } fro
 
 /* The resume note is a round trip across the wire: the daemon wraps a prompt to tell the model what interrupted
  * it, and the client unwraps the SAME prompt off an attach head to tell whether it already has that bubble. A
- * mismatch between the two halves fails silently and cosmetically — a paragraph of machine prose rendered as
- * something the user typed — which is exactly the kind of drift that stays broken. */
+ * mismatch between the two halves fails silently and cosmetically: a paragraph of machine prose rendered as
+ * something the user typed, which is exactly the kind of drift that stays broken. */
 test("a resume note round-trips back to the user's own words", () => {
     for (const note of Object.values(RESUME_NOTES)) {
         expect(withoutResumeNote(withResumeNote("ship the parser", note))).toBe("ship the parser");
@@ -39,7 +39,7 @@ test("a re-run discloses as a notice, and the answered case as a note on the mes
         const disclosure = resumeDisclosure(withResumeNote("ship the parser", RESUME_NOTES[reason]));
         expect(disclosure?.kind).toBe("notice");
     }
-    // The answer is new words the user really did type, so nothing is dropped — the interruption rides them.
+    // The answer is new words the user really did type, so nothing is dropped: the interruption rides them.
     const answered = resumeDisclosure(withResumeNote("option two", RESUME_NOTES.answered));
     expect(answered).toEqual({ kind: "note", note: { title: expect.any(String), text: RESUME_NOTES.answered } });
 });