@intentic/sandbox-contract 1.222.0 → 1.224.0

package/src/search-globs.ts

@@ -1,17 +1,17 @@
-/* What the search box's second field MEANS — VSCode's "files to include" grammar, read the way VSCode reads it
+/* What the search box's second field MEANS. VSCode's "files to include" grammar, read the way VSCode reads it
  * (its queryBuilder's parseSearchPaths + expandGlobalGlob), and answered as the two path-glob lists the search
  * engine takes.
  *
- * The rules that make it feel like the editor's field, each one load-bearing:
+ * The rules that make it feel like the editor's field, each one required:
  *
- *   `package.json`  a bare name is a FILE as well as a folder — every segment expands to BOTH `**\/p` and
+ *   `package.json`  a bare name is a FILE as well as a folder, every segment expands to BOTH `**\/p` and
  *                   `**\/p/**`. Reading it as a folder alone is what made a file name find nothing.
- *   `src/db`        a path is still matched at any depth, not anchored — `**\/src/db`. VSCode only anchors
+ *   `src/db`        a path is still matched at any depth, not anchored, `**\/src/db`. VSCode only anchors
  *   `./src/db`      when the segment starts with `./` (or `/`), which is how you say "the one at the root".
  *   `.ts`           a leading dot is shorthand for the extension: it becomes `*.ts`.
  *   `docs/`         a trailing slash is noise; the folder form is generated either way.
  *   `*.{ts,vue}`    commas separate patterns EXCEPT inside `{…}` or `[…]`, which are one pattern's own syntax.
- *   `!**\/*.spec.ts` a leading `!` excludes. This is ours, not VSCode's — the editor spends a second box on
+ *   `!**\/*.spec.ts` a leading `!` excludes. This is ours, not VSCode's, the editor spends a second box on
  *                   exclusions and the explorer's sidebar has room for one field.
  *
  * It lives in the contract package because both ends run it: the daemon turns it into engine scope, and the
@@ -60,7 +60,7 @@ const expand = (segment: string): string[] => {
 };
 
 export interface IncludeGlobs {
-    // Files the search is limited to — empty means the whole workspace. OR'ed: any pattern matching admits.
+    // Files the search is limited to, empty means the whole workspace. OR'ed: any pattern matching admits.
     readonly globs: readonly string[];
     // Files kept out of it, whatever the includes said.
     readonly notGlobs: readonly string[];

package/src/session-names.ts

@@ -2,14 +2,14 @@
  *
  * A turn that runs Bash gets a tmux session; a turn that browses gets a Chromium the daemon watches over CDP.
  * Both are named off the SDK session id by the same derivation, and both are listed together by
- * GET /system/terminals — so the name is wire vocabulary, not an implementation detail of either half.
+ * GET /system/terminals, so the name is wire vocabulary, not an implementation detail of either half.
  *
  * It lives in the contract because three parties derive it and none of them may guess: the daemon NAMES the
  * session, the web app OPENS it, and an extension that wants to point the user at a turn's live browser has only
  * the fleet roster's `sessionId` to work from. A second copy of this string math anywhere is a drift waiting to
- * happen — the copy would keep resolving to a plausible name that nothing has ever listed.
+ * happen, the copy would keep resolving to a plausible name that nothing has ever listed.
  *
- * Reached as `@intentic/sandbox-contract/session-names`, NOT through the barrel — the same shape tunnel-ids has,
+ * Reached as `@intentic/sandbox-contract/session-names`, NOT through the barrel, the same shape tunnel-ids has,
  * and for the same reason: this module has no dependencies, while the barrel pulls the whole contract (and
  * @intentic/extension-api behind it). One subpath keeps a daemon unit test that only wants a session name from
  * having to resolve the entire wire surface.
@@ -21,7 +21,7 @@ export const JOB_SESSION_PREFIX = "job-";
 export const BROWSER_SESSION_PREFIX = "browser-";
 
 /* Eight characters of the SDK session UUID, sanitized to the session-name charset. Eight is what groups a whole
- * turn's work — including its subagents' — under one name, and it clears the name guard
+ * turn's work, including its subagents', under one name, and it clears the name guard
  * (`^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$`) without further escaping. Undefined when the id sanitizes to empty, which
  * is never a valid session name. */
 export const sessionSuffix = (sessionId: string): string | undefined => {
@@ -29,7 +29,7 @@ export const sessionSuffix = (sessionId: string): string | undefined => {
     return id === "" ? undefined : id;
 };
 
-// The tmux session one SDK session's Bash commands run in — the same derivation the Bash hook routes commands
+// The tmux session one SDK session's Bash commands run in, the same derivation the Bash hook routes commands
 // through, so an emitted `terminal` frame and the live session can't drift.
 export const agentSessionName = (sessionId: string): string | undefined => {
     const suffix = sessionSuffix(sessionId);

package/src/share-paths.ts

@@ -1,4 +1,4 @@
-/* WHERE A SHARED CONVERSATION LIVES INSIDE THE OUTBOX — one layout, stated once, because three separate
+/* WHERE A SHARED CONVERSATION LIVES INSIDE THE OUTBOX, one layout, stated once, because three separate
  * things have to agree on it and only one of them is code that runs at the same time as the others.
  *
  *   public/
@@ -8,12 +8,12 @@
  *         index.html        the page, with its conversation baked in
  *         files/            the pictures that conversation showed, copied out of the workspace
  *
- * The VIEWER's build has to know its own address before it is ever published (its asset URLs are absolute —
- * `/conversations/_viewer/assets/…` — so that one copy of the assets serves every share and a recipient's
+ * The VIEWER's build has to know its own address before it is ever published (its asset URLs are absolute,
+ * `/conversations/_viewer/assets/…`, so that one copy of the assets serves every share and a recipient's
  * browser caches them across links). The DAEMON has to write the tree. And the outbox's own rules have to
  * leave all of it alone: nothing here begins with a dot, which is the one shape that is never served.
  *
- * A directory per share rather than a bare `<id>.html`, so a share owns its pictures — "stop sharing" is then
+ * A directory per share rather than a bare `<id>.html`, so a share owns its pictures, "stop sharing" is then
  * one directory removed, and cannot half-succeed by leaving a folder of someone's screenshots behind. */
 
 // Top-level folder inside `public/`. Reads as what it is in the address bar, which matters: this is a string
@@ -24,7 +24,7 @@ export const SHARE_DIR = "conversations";
 // machinery rather than as somebody's conversation.
 export const SHARE_VIEWER_DIR = "_viewer";
 
-// Where a share's pictures sit, relative to its own page — and therefore also the prefix every rewritten
+// Where a share's pictures sit, relative to its own page, and therefore also the prefix every rewritten
 // image path in the payload carries.
 export const SHARE_FILES_DIR = "files";
 
@@ -36,7 +36,7 @@ export const SHARE_VIEWER_BASE = `/${SHARE_DIR}/${SHARE_VIEWER_DIR}/`;
  *
  * Both halves earn their place. The stem is what makes a pasted link say what it points at ("…/conversations/
  * login-redirect-fix-3f9c…"), which is most of why anyone trusts clicking one. The tail is the security: the
- * outbox answers on an unguessable hostname AND requires the exact path (public-files.ts rule 4 — there is no
+ * outbox answers on an unguessable hostname AND requires the exact path (public-files.ts rule 4, there is no
  * listing), so an address is protected by the sum of the two, and the half this module controls must not be
  * derivable from a title anyone could guess. */
 const STEM_MAX = 48;
@@ -62,7 +62,7 @@ export const shareId = (title: string, random: string): string => {
     return stem === "" ? random : `${stem}-${random}`;
 };
 
-// What a share's own id must look like before it is ever joined onto a path — the same shape the daemon's
+// What a share's own id must look like before it is ever joined onto a path, the same shape the daemon's
 // other id guards take (transcript-record.ts FILE_ID), and the reason a share id from the wire can be trusted
 // into a directory name.
 export const SHARE_ID = /^[a-z0-9][a-z0-9-]{0,95}$/;

package/src/sse.ts

@@ -1,5 +1,5 @@
 // Low-level SSE framing for the daemon's streamed routes (oRPC eventIterator over HTTP): frames separated by
-// a blank line, each carrying one `data: <JSON>` line. Protocol-only (no domain shapes) — shared by every
+// a blank line, each carrying one `data: <JSON>` line. Protocol-only (no domain shapes), shared by every
 // consumer of the wire: the web's chat/intentic streams and the ACP bridge's daemon client.
 
 // Yields each raw SSE frame (the text between blank-line separators) as it arrives, reassembling frames split

package/src/state-portability.ts

@@ -1,35 +1,35 @@
-/* WHETHER A PIECE OF DAEMON STATE TRAVELS — the second thing every state manifest declares.
+/* WHETHER A PIECE OF DAEMON STATE TRAVELS, the second thing every state manifest declares.
  *
  * A sandbox's environment is not one directory. `/work` holds the workspace and the daemon's manifests,
  * `/history` holds the real git dirs, the fleet registry and the ledgers, and the container carries the built
  * image and its env. "Export the environment" therefore means walking state that lives in two volumes and
- * deciding, per entry, which of four things it is — and that decision has to be written down beside the entry
+ * deciding, per entry, which of four things it is, and that decision has to be written down beside the entry
  * itself, or the exporter becomes the hand-kept list that workspace-state.ts exists to argue against.
  *
  * So each manifest entry carries a class, and both the bundler and the restorer derive from it. Adding a store
  * without saying whether it travels is a failing coverage test, not a file that silently goes missing from
  * every bundle.
  *
- * The classes are exhaustive on purpose — there is no "unset" — because the failure mode of a default is
+ * The classes are exhaustive on purpose, there is no "unset", because the failure mode of a default is
  * exactly the one that matters: a credential store added later would inherit `carry` and ride out of the
  * sandbox in a file the owner thought was safe to email.
  */
 export type Portability =
     /* Ordinary state. Travels in every bundle. */
     | "carry"
-    /* Holds a credential — a provider token, a webhook secret, an ssh key. Travels ONLY when the owner opts
+    /* Holds a credential, a provider token, a webhook secret, an ssh key. Travels ONLY when the owner opts
      * in at export, and the bundle records that it did. Never the default. */
     | "secret"
     /* Binds this sandbox to its owner, its browsers or its host: who may drive it, the session-signing secret,
-     * push subscriptions, enrollments, certificates. Never travels — the target mints its own, and carrying
+     * push subscriptions, enrollments, certificates. Never travels, the target mints its own, and carrying
      * one would either hand the target's ownership to the source or leave two sandboxes claiming one identity. */
     | "identity"
     /* Regenerated by the target from state that does travel: composed files, caches, indexes, checkouts. Left
-     * out for size, not for safety — carrying it would only ship a stale copy of something the daemon rebuilds
+     * out for size, not for safety, carrying it would only ship a stale copy of something the daemon rebuilds
      * on its own. */
     | "derived";
 
-// One entry of a state manifest: the path it owns and what happens to it at export. `note` is user-facing —
+// One entry of a state manifest: the path it owns and what happens to it at export. `note` is user-facing,
 // the import report prints it beside a skipped entry, so it is written as an instruction to the owner ("log in
 // again"), not as a rationale for the next reader. Rationale belongs in a comment on the entry.
 export interface StateFile {
@@ -42,7 +42,7 @@ export interface StateFile {
  *
  * Manifests may deliberately nest when one subtree has a different lifecycle. First-match resolution would
  * classify the child by whichever entry happened to be listed first, so the specific entry has to win over the
- * general one by construction rather than by list order — the same reason a .gitignore consults its deepest
+ * general one by construction rather than by list order, the same reason a .gitignore consults its deepest
  * matcher first.
  *
  * Undefined for a path no entry claims. Callers decide what that means: workspace content (including an

package/src/terminal-protocol.ts

@@ -1,16 +1,16 @@
-// The /system/terminal WebSocket wire protocol — JSON text frames both ways (xterm speaks strings), shared by
+// The /system/terminal WebSocket wire protocol. JSON text frames both ways (xterm speaks strings), shared by
 // the daemon's terminal route and the browser's terminal session so the two can't drift. Plain types, not zod
 // schemas: `data` is the per-pty-chunk hot path between two mutually authenticated endpoints, and no oRPC
 // eventIterator validates these frames (which is why events.ts uses schemas).
 
 // `ping` is the client's 30s keepalive against tunnel idle-reaping; the server answers with `pong`, so a
-// healthy idle connection always sees a frame within the ping interval — silence beyond it means half-open.
+// healthy idle connection always sees a frame within the ping interval, silence beyond it means half-open.
 export type TerminalClientMessage =
     | { readonly type: "input"; readonly data: string }
     | { readonly type: "resize"; readonly cols: number; readonly rows: number }
     | { readonly type: "ping" };
 
 // `data` is raw pty output; `exit` fires when the tmux client ends (shell exited, or an attach-only session
-// doesn't exist) and is terminal — the client never reconnects after it.
+// doesn't exist) and is terminal, the client never reconnects after it.
 export type TerminalServerMessage =
     { readonly type: "data"; readonly data: string } | { readonly type: "exit"; readonly code: number } | { readonly type: "pong" };

package/src/title.ts

@@ -1,10 +1,10 @@
-/* HOW A CONVERSATION NAMES ITSELF from its opening prompt — the title a chat tab, a fleet card and the agent
+/* HOW A CONVERSATION NAMES ITSELF from its opening prompt, the title a chat tab, a fleet card and the agent
  * detail header wear from the first keystroke of a turn until something better arrives.
  *
  * The naive rule (collapse whitespace, cut at N) reads the prompt as if it were a headline, and opening
  * prompts are not headlines. They are pasted stack traces, links dropped in with two words of context,
  * politeness that eats half the budget before the ask begins, and multi-line asks whose first line is throat-
- * clearing. Cutting those at 40 characters yields `Error: ENOENT: no such file or directo…` — a title that
+ * clearing. Cutting those at 40 characters yields `Error: ENOENT: no such file or directo…`, a title that
  * names the paste rather than the work, and that reads identically for every one of the day's five pastes.
  *
  * So the prompt is read as prose FIRST and cut second: quoted material and fenced code are not the ask, the
@@ -12,17 +12,17 @@
  * that still says something, cut on a sentence or a word rather than mid-syllable.
  *
  * Both sides derive: the browser names a conversation the instant it sends (conversation.ts), and the daemon
- * names a turn that arrived without one — an automation, a Discord message, a webchat visitor (agents-
+ * names a turn that arrived without one, an automation, a Discord message, a webchat visitor (agents-
  * registry.ts). One rule, because two would let the same prompt open under two different names depending on
  * where it entered. Nothing here calls a model: the title has to exist before the first frame comes back.
  *
- * Which is exactly the ceiling on it. Cutting is not naming — what comes out is the user's own sentence,
+ * Which is exactly the ceiling on it. Cutting is not naming, what comes out is the user's own sentence,
  * shortened, and a column of those is scannable only where the users' sentences happened to differ early. The
  * name a conversation ends up WEARING is written a second or two later by a model that reads the same prompt
  * and answers in the fleet board's own shape (the daemon's title-namer.ts). This is the title that holds the
  * tab until that arrives, and the one it keeps if nothing is connected to write a better one. */
 
-// The registry's title budget (agents-registry MAX_TITLE_LENGTH, the rename input's maxlength) — the widest
+// The registry's title budget (agents-registry MAX_TITLE_LENGTH, the rename input's maxlength), the widest
 // any surface stores. Every surface truncates in CSS to its own width, so the clamp here is a storage cap,
 // not a display rule: cutting shorter than the widest surface (a full-width fleet card) would throw away
 // signal that surface has room to show, and no narrow surface is hurt because its CSS cuts first anyway.
@@ -35,7 +35,7 @@ const MIN_SENTENCE = 12;
 const MIN_WORD_CUT = MAX_LENGTH * 0.6;
 
 // Markdown's two fence syntaxes, and the quote marker. Both open and close on the same shape, so a fence line
-// toggles rather than matching a pair — an UNTERMINATED fence (a paste the user never closed) then swallows
+// toggles rather than matching a pair, an UNTERMINATED fence (a paste the user never closed) then swallows
 // the rest of the prompt, which is what it visually does too.
 const FENCE = /^\s*(?:```|~~~)/;
 const QUOTE = /^\s*>/;
@@ -52,11 +52,11 @@ const OPENERS: readonly RegExp[] = [
     /^(?:quick\s+(?:one|question|q)|one\s+more\s+thing)\b[\s,.:;!—–-]*/i,
 ];
 
-// A sentence ends on terminal punctuation that is actually followed by a break — which is what holds `v1.2`
+// A sentence ends on terminal punctuation that is actually followed by a break, which is what holds `v1.2`
 // and `foo.ts` together while still ending `Why is it red?`.
 const SENTENCE_END = /[.!?](?=\s|$)/;
 
-/* A report of work already done — `We have recently added…`, `I've just landed…`, `we were refactoring…`. The
+/* A report of work already done, `We have recently added…`, `I've just landed…`, `we were refactoring…`. The
  * one first-sentence shape that is reliably CONTEXT rather than the ask: prompts that open on it set the scene
  * for an instruction further down, and titling from the scene names every such conversation after last week's
  * work instead of this one's.
@@ -69,7 +69,7 @@ const NARRATION =
     /^(?:(?:recently|previously|earlier|today|yesterday|lately)[\s,]+)?(?:we|i)(?:'ve|'d|'m|'re)?(?:\s+(?:have|had|am|are|was|were|been|just|recently|already|earlier|previously|also|finally|now|currently|still))*\s+(?!(?:need|feed|speed|shed|heed|breed|bleed|embed|proceed|exceed|succeed)\b)(?:\w+ed|\w{3,}ing|built|wrote|rewrote|made|found|saw|thought|began|got|kept|put|set|sent|split|ran|did|redid|went|came|gave|held|hit|cut|let|read|understood|broke|chose|became|brought|spent|meant|lost|forgot|rebuilt|told|taught|stood|drew|grew|knew|threw|took|left|felt|hid)\b/i;
 
 // The ask read as an instruction: a sentence leading with a bare verb of the kind coding asks lead with. A
-// curated list rather than grammar — English hands out noun/verb ambiguity too freely for anything cleverer.
+// curated list rather than grammar. English hands out noun/verb ambiguity too freely for anything cleverer.
 const IMPERATIVE =
     /^(?:add|fix|make|implement|create|build|write|rewrite|refactor|rename|remove|delete|drop|update|change|convert|migrate|move|extract|split|merge|rebase|revert|restore|wire|connect|integrate|support|handle|improve|clean|simplify|redesign|rework|rethink|investigate|analyze|analyse|debug|find|figure|check|verify|test|run|try|document|describe|explain|propose|design|draft|prepare|stop|prevent|ensure|allow|enable|disable|introduce|replace|swap|optimize|optimise|reduce|bump|upgrade|deploy|ship|release|adjust|tweak|polish|finish|complete|continue|extend|unify|dedupe|deduplicate|cache|persist|expose|hide|show|render|port|automate|wrap|inline|audit|review|profile|measure|instrument|validate|parse|generate|turn|look|think|come|consider|help|start|use|keep|avoid|teach|harden|tighten|localize|localise|translate)\b/i;
 
@@ -102,11 +102,11 @@ const proseLines = (prompt: string): string[] => {
 
 /* Peel the openers off a line, but only keep the peeling when something with shape is left underneath.
  *
- * Three outcomes, and the difference between them is the whole point. A remnant of SEVERAL words is the ask —
+ * Three outcomes, and the difference between them is the whole point. A remnant of SEVERAL words is the ask,
  * `Can you please fix the auth tests?` was carrying `fix the auth tests?`. A remnant of NOTHING was pure
  * greeting (`Hey, quick one —`), and returning empty is how the caller learns to read the next line instead.
- * A remnant of ONE word means the opener was load-bearing — `Hi there` is not a conversation about `there`,
- * and `So what?` is not one about `what?` — so the line stands as written. */
+ * A remnant of ONE word means the opener was meaningful. `Hi there` is not a conversation about `there`,
+ * and `So what?` is not one about `what?`, so the line stands as written. */
 const withoutOpener = (line: string): string => {
     let text = line;
     for (let pass = 0; pass < OPENERS.length; pass++) {
@@ -141,7 +141,7 @@ const shortUrl = (token: string): string => {
     return /^\d+$/.test(last) && previous !== undefined ? `${previous}/${last}` : last;
 };
 
-// A path is worth its basename once it is deep enough that the lead is scaffolding — `src/foo.ts` already
+// A path is worth its basename once it is deep enough that the lead is scaffolding, `src/foo.ts` already
 // reads as a place, `_editor/web/src/composables/chat/conversation.ts` reads as a wall.
 const shortPath = (token: string): string => {
     const segments = token.replace(/^@/, "").split("/");
@@ -149,7 +149,7 @@ const shortPath = (token: string): string => {
 };
 
 // Trailing punctuation belongs to the sentence, not to the reference inside it, so it is set aside across the
-// shortening and put back — `see _editor/web/src/foo.ts,` collapses to `see foo.ts,`.
+// shortening and put back, `see _editor/web/src/foo.ts,` collapses to `see foo.ts,`.
 const shortReference = (token: string): string => {
     const match = /^(.*?)([\s,.;:!?)\]]*)$/s.exec(token);
     const core = match?.[1] ?? token;
@@ -175,7 +175,7 @@ const firstSentence = (text: string): string => {
     return terminator === "." ? text.slice(0, end) : text.slice(0, end + 1);
 };
 
-// Every sentence in turn, terminators handled as in firstSentence — the walk the ask-scan below reads. No
+// Every sentence in turn, terminators handled as in firstSentence, the walk the ask-scan below reads. No
 // abbreviation guard here: a fragment split off at an `e.g.` never leads with an imperative, so it simply
 // loses the scan rather than corrupting it.
 const sentencesOf = (text: string): string[] => {
@@ -194,11 +194,11 @@ const sentencesOf = (text: string): string[] => {
 };
 
 /* THE ELLIPSIS IS PART OF THE BUDGET, not an addition to it. MAX_LENGTH is a STORAGE cap the wire contract
- * enforces (AgentTurnSchema.title), so a title one character over it is not a wide tab — it is a 400 on the
+ * enforces (AgentTurnSchema.title), so a title one character over it is not a wide tab, it is a 400 on the
  * turn that carried it. Cutting to MAX_LENGTH and appending afterwards was exactly that off-by-one, and it
  * hid for as long as it did because the word-boundary backoff almost always absorbed it: an ordinary sentence
  * has a space late in the window, so `kept` came back short and the ellipsis fit. What has no such space is a
- * long unbroken token straddling the cut — a SCREAMING_SNAKE env var, a hash, a base64 blob — and there the
+ * long unbroken token straddling the cut, a SCREAMING_SNAKE env var, a hash, a base64 blob, and there the
  * fallback kept the full-width slice and made it one character too long. The conversation then wedged: the
  * browser writes the derived title into its state before it sends, so every later turn re-sent the same
  * rejected name. */
@@ -225,7 +225,7 @@ const capitalized = (text: string): string => {
 /* Split a plan's markdown into its leading heading and the remaining body.
  *
  * The heading is the one place in a turn where an agent writes a name for the WHOLE job rather than for a step
- * — a task checklist describes `Read the failing test`, `Fix the assertion`, `Run the suite`, none of which is
+ *, a task checklist describes `Read the failing test`, `Fix the assertion`, `Run the suite`, none of which is
  * what the conversation is about, whereas a plan opens `## Fix the flaky auth tests`. That makes it the only
  * authored line in the stream worth promoting to a title, which is why this lives here rather than next to the
  * plan card that also renders it: the browser titles its own tabs from it and the daemon titles fleet cards. */
@@ -248,7 +248,7 @@ export const deriveTitle = (prompt: string): string => {
     const lines = prose.map(withoutOpener).filter((line) => /\p{L}/u.test(line));
     const primary = lines[0];
     if (primary !== undefined) {
-        /* A first sentence that reports work already done is the scene, not the ask — `We have recently added
+        /* A first sentence that reports work already done is the scene, not the ask, `We have recently added
          * iq map. Now let's expose health.` is a conversation about exposing health. Skipped only for an
          * unmistakable ask further in (an instruction or an outright question); anything hazier and the
          * narration stands, exactly as every non-narrative opening always does. */
@@ -261,7 +261,7 @@ export const deriveTitle = (prompt: string): string => {
             : undefined;
         return capitalized(clamped(firstSentence(collapseReferences(ask ?? primary))));
     }
-    // Everything the user sent was code, a quote, or a greeting — title it as what it is rather than blank.
+    // Everything the user sent was code, a quote, or a greeting, title it as what it is rather than blank.
     const fallback = prose[0] ?? collapse(prompt.replaceAll(/^\s*(?:```|~~~).*$/gm, ""));
     return clamped(collapseReferences(fallback === "" ? collapse(prompt) : fallback));
 };

package/src/tunnel-ids.ts

@@ -22,33 +22,33 @@ export const hostSshIdFromToken = (connectToken: string, hostName: string): stri
  * and it is the hard cap on preview DNS records a sandbox can ever cost the shared intentic zone. */
 export const PORT_SLOT_COUNT = 8;
 
-/* THE PORT-FORWARD SLOT LABELS — the `port-<slot>` half of `port-<slot>-<sandboxId>.<zone>`.
+/* THE PORT-FORWARD SLOT LABELS, the `port-<slot>` half of `port-<slot>-<sandboxId>.<zone>`.
  *
  * These were the letters a…h, and that was the hole: a forwarded port's hostname was then a pure function of the
- * sandbox id, and the sandbox id is not a secret — it is the leading label of the URL the owner uses daily and
+ * sandbox id, and the sandbox id is not a secret, it is the leading label of the URL the owner uses daily and
  * of every preview link they have ever shared. So anyone who had seen ONE preview link could poll eight fixed
  * names forever and catch whatever the owner forwarded, at any point in the future. The Ports view says a
  * forwarded port is public, and it is; what it could not say was that "public" meant eight guessable URLs.
  *
  * Salting with the connect token fixes that without costing anything the letters bought. Still exactly eight
- * records (the reason slots exist at all — the intentic-provided zone mints per label, and dev servers churn
+ * records (the reason slots exist at all, the intentic-provided zone mints per label, and dev servers churn
  * ephemeral ports far faster than DNS should), still stable across restarts so a slot's record stays warm, and
  * still derivable with no coordination by every party that already holds the token: the daemon that forwards,
  * and the platform that mints the DNS. A party without the token has no business predicting these names.
  *
- * The browser is deliberately NOT one of those parties — it never derives a port hostname, it reads `previewUrl`
- * off the daemon's response — which is why this can live here, in the node-only half of the contract, next to
+ * The browser is deliberately NOT one of those parties, it never derives a port hostname, it reads `previewUrl`
+ * off the daemon's response, which is why this can live here, in the node-only half of the contract, next to
  * the digest it shares with sandboxIdFromToken. */
 export const portSlotsFromToken = (connectToken: string): readonly string[] =>
     Array.from({ length: PORT_SLOT_COUNT }, (_, index) => sha256Hex(`${connectToken}:port:${index}`).slice(0, 12));
 
-/* THE OUTBOX SLOT — the `public-<slot>` half of `public-<slot>-<sandboxId>.<zone>`, where the daemon serves the
+/* THE OUTBOX SLOT, the `public-<slot>` half of `public-<slot>-<sandboxId>.<zone>`, where the daemon serves the
  * workspace's `public/` directory (PUBLIC_DIR in @intentic/workspace-ignore).
  *
  * Salted for the reason above, and it matters more here than it does for ports: a forwarded port is a live
  * server the owner started minutes ago, whereas a published file sits there. One record per sandbox, stable
  * across restarts so a link stays good for as long as the file does, and derivable only by parties holding the
- * token — the daemon that serves and the platform that mints. Not the browser: it reads the URL off the /public
+ * token, the daemon that serves and the platform that mints. Not the browser: it reads the URL off the /public
  * response, exactly as it reads previewUrl off /ports.
  *
  * The unguessable hostname is also what carries the security story, because the files under it have no auth in

package/src/versions.ts

@@ -1,4 +1,4 @@
-/* COMPARING THE VERSIONS THIS SYSTEM STAMPS ON WHAT IT SHIPS — the daemon, the sandbox image, and the two agents
+/* COMPARING THE VERSIONS THIS SYSTEM STAMPS ON WHAT IT SHIPS, the daemon, the sandbox image, and the two agents
  * that run on a user's own computer. One release stamps all of them to the SAME version, so "is this one behind
  * that one" is one question with one answer, and it lives here because both ends ask it: the daemon compares its
  * own build against the latest published release, and the browser compares a computer's agent against the same.
@@ -33,14 +33,14 @@ export const DEV_VERSION = `0.0.0`;
 /* WHETHER TO TELL SOMEBODY THEIR BUILD IS OLD. Deliberately false in every uncertain case, and each one is a
  * different kind of not-knowing:
  *
- *   • no installed version — the thing does not report one, so there is nothing to be behind.
- *   • no latest version — this sandbox has not reached the registry (or is a dev build and never will).
- *   • installed is the dev sentinel — see above; a nag that cannot be satisfied is worse than silence.
+ *   • no installed version, the thing does not report one, so there is nothing to be behind.
+ *   • no latest version, this sandbox has not reached the registry (or is a dev build and never will).
+ *   • installed is the dev sentinel, see above; a nag that cannot be satisfied is worse than silence.
  *
  * A version that is not dotted-numeric is compared by its numeric prefix, which is both useful and safe in the
  * only direction that matters: a segment that will not parse compares as neither greater nor less, so it stops
  * the comparison at "not newer". A malformed INSTALLED version can therefore only ever withhold a nag, never
- * invent one — and `latest` comes from the registry, so it is well-formed by construction.
+ * invent one, and `latest` comes from the registry, so it is well-formed by construction.
  *
  * The asymmetry is the point. Saying "you are out of date" wrongly sends someone to reinstall a working agent;
  * saying nothing wrongly leaves them where they already were. */

package/src/workflow-faults.ts

@@ -1,4 +1,4 @@
-/* WHY A WORKFLOW GRAPH IS NOT RUNNABLE — the rules that `WorkflowSchema` cannot state, because each of them is
+/* WHY A WORKFLOW GRAPH IS NOT RUNNABLE, the rules that `WorkflowSchema` cannot state, because each of them is
  * about the graph rather than about one field.
  *
  * A rule per function, so the reason a graph is refused reads as one sentence in one place. They are
@@ -49,24 +49,24 @@ const stepFaults = (step: WorkflowStep, ids: ReadonlySet<string>): string[] => {
             ),
         );
     }
-    /* A STEP THAT DECLARES NOTHING IS NOT A FAULT — it is the ordinary step, and this used to refuse it.
+    /* A STEP THAT DECLARES NOTHING IS NOT A FAULT, it is the ordinary step, and this used to refuse it.
      *
      * The rule was borrowed from loops (`loopCanConverge`), where it is right: a LOOP is started to repeat
      * until something is true, so one with nothing to produce and nothing to check has no reason to run twice
      * and the dialog is correct to grey out its button. A STEP is not started to repeat. It is one agent
-     * session with a job, and the job being done is the turn ending — which is exactly what the loop machinery
+     * session with a job, and the job being done is the turn ending, which is exactly what the loop machinery
      * already does with it (loop-stop's `readDocument` answers `done` for a `none` output, so iteration 1 is
      * the only iteration).
      *
      * Keeping the rule here forced every step to declare an output or a check before the graph would save, and
-     * the cheapest way to satisfy it was a `claim` — which buys a verdict file nobody reads, a page of contract
+     * the cheapest way to satisfy it was a `claim`, which buys a verdict file nobody reads, a page of contract
      * in the prompt, and a way for a step that did the work to fail for not having described it.
      */
     return faults;
 };
 
 /* Two steps continuing the SAME session is the one graph that is legal on paper and broken in practice: both
- * would run on one conversation, in parallel, against one worktree and one turn mutex — so they would serialize
+ * would run on one conversation, in parallel, against one worktree and one turn mutex, so they would serialize
  * on a lock neither knows about and the second would inherit a session the first had moved on. A predecessor
  * can be continued once; anything else that needs its result takes it as a handover. */
 const sharedContinuationFaults = (steps: readonly WorkflowStep[]): string[] => {
@@ -110,8 +110,8 @@ const cycleFaults = (steps: readonly WorkflowStep[]): string[] => {
     return faults;
 };
 
-/* A GATE THAT CANNOT BE ANSWERED. Every rule here is about the gate against the GRAPH — which is why none of
- * them can live in the schema — and all of them fail the same expensive way if unchecked: the run spends its
+/* A GATE THAT CANNOT BE ANSWERED. Every rule here is about the gate against the GRAPH, which is why none of
+ * them can live in the schema, and all of them fail the same expensive way if unchecked: the run spends its
  * whole fan-out of sessions and then answers `blocked`, on every commit, for a reason nobody sees until they
  * go reading the daemon's log.
  *
@@ -138,7 +138,7 @@ const gateFaults = (workflow: Pick<Workflow, "steps" | "gate">): string[] => {
     if (field.type === "string[]") {
         return [`The gate reads "${gate.field}", which is a list — a release decision has to be one value.`];
     }
-    // The schema refuses this on save (pass is min(1)), but the designer edits drafts the schema never sees —
+    // The schema refuses this on save (pass is min(1)), but the designer edits drafts the schema never sees,
     // and an empty allowlist is a gate no run could ever answer "pass", which deserves a sentence, not a save error.
     if (gate.pass.length === 0) {
         return [`The gate names no passing values, so no run could ever ship.`];
@@ -163,13 +163,13 @@ export const workflowFaults = (workflow: Pick<Workflow, "steps" | "gate">): stri
     ];
 };
 
-/* WHAT ONLY A RUN CAN BE WRONG ABOUT — kept apart from the rules above because it is not about the graph, and
+/* WHAT ONLY A RUN CAN BE WRONG ABOUT, kept apart from the rules above because it is not about the graph, and
  * the graph is what gets SAVED. A design whose steps take their goal and instruction from the request is a
  * perfectly good design; it is only unrunnable on the particular run that forgot to bring one.
  *
  * Which is why this cannot be a save-time rule and must not become one: refusing to save such a workflow would
- * outlaw the entire point of a workflow being a SHAPE. The check belongs at the two doors that start runs — the
- * run route and the gate's webhook — and it has to be there rather than left to fail later, because "later"
+ * outlaw the entire point of a workflow being a SHAPE. The check belongs at the two doors that start runs, the
+ * run route and the gate's webhook, and it has to be there rather than left to fail later, because "later"
  * means every session in the fan-out has already been paid for before anyone finds out the model was handed an
  * empty instruction.
  */