@intentic/sandbox-contract 1.223.0 → 1.225.0

package/src/search-globs.test.ts

@@ -11,7 +11,7 @@ test("an empty field scopes nothing", () => {
 test("a bare name is a file as well as a folder, at any depth", () => {
     expect(includeGlobs(`package.json`).globs).toEqual([`**/package.json`, `**/package.json/**`]);
     expect(includeGlobs(`docs`).globs).toEqual([`**/docs`, `**/docs/**`]);
-    // A trailing slash is noise — the folder form is generated either way.
+    // A trailing slash is noise: the folder form is generated either way.
     expect(includeGlobs(`docs/`).globs).toEqual([`**/docs`, `**/docs/**`]);
 });
 
@@ -41,6 +41,6 @@ test("a leading ! excludes instead", () => {
         globs: [`**/src`, `**/src/**`],
         notGlobs: [`**/*.test.ts`, `**/*.test.ts/**`],
     });
-    // A lone "!" excludes nothing — expanded, it would have matched everything.
+    // A lone "!" excludes nothing: expanded, it would have matched everything.
     expect(includeGlobs(`!`)).toEqual({ globs: [], notGlobs: [] });
 });

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.test.ts

@@ -17,7 +17,7 @@ describe("the readable half", () => {
     });
 
     // A title in a writing system this alphabet cannot carry leaves the random half standing alone, which is
-    // still a perfectly good id — and a better outcome than an address full of percent-encoding.
+    // still a perfectly good id, and a better outcome than an address full of percent-encoding.
     it("falls back to the random half when a title has no letters to give", () => {
         expect(shareStem("日本語のタイトル")).toBe("");
         expect(shareId("日本語のタイトル", "3f9c")).toBe("3f9c");

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.test.ts

@@ -7,13 +7,13 @@ import { deriveTitle } from "./title.js";
  * politeness, or stopped mid-syllable. */
 
 test("spends the budget on the ask rather than on the politeness in front of it", () => {
-    // `Can you please fix the auth…` is what the naive cut produced — three of its five words are ceremony.
+    // `Can you please fix the auth…` is what the naive cut produced: three of its five words are ceremony.
     expect(deriveTitle("Can you please fix the auth tests?")).toBe("Fix the auth tests?");
     expect(deriveTitle("Hey, can you please look at the flaky test")).toBe("Look at the flaky test");
 });
 
 test("keeps a greeting whole when peeling it off would leave a fragment", () => {
-    // `Hi there` is not a conversation about `there`, and `So what?` is not one about `what?` — a one-word
+    // `Hi there` is not a conversation about `there`, and `So what?` is not one about `what?`: a one-word
     // remnant means the opener was carrying the sentence, so the line stands as the user wrote it.
     expect(deriveTitle("Hi there")).toBe("Hi there");
     expect(deriveTitle("So what?")).toBe("So what?");
@@ -35,7 +35,7 @@ test("titles a pasted stack trace after the sentence the user wrote around it",
 
 test("skips a greeting line and takes the ask from the line below it", () => {
     // A line that unwinds to nothing was throat-clearing; the ask is further down. The naive rule stopped at
-    // the greeting and named every such conversation `Hey, quick one —`.
+    // the greeting and named every such conversation `Hey, quick one -`.
     expect(deriveTitle("Hey, quick one —\n\nWhy does the tab title truncate mid-word?")).toBe("Why does the tab title truncate mid-word?");
 });
 
@@ -61,7 +61,7 @@ test("cuts on a word boundary instead of mid-syllable", () => {
 
 test("keeps a cut it cannot put on a word boundary inside the budget anyway", () => {
     /* The sibling of the case above: a long unbroken token straddling the cut leaves no space late enough to
-     * back off to, so the length clamp alone ends the title — and it used to end it one character OVER. That
+     * back off to, so the length clamp alone ends the title, and it used to end it one character OVER. That
      * character is not a cosmetic overflow, it is a 400 on the turn carrying the name, and it wedged the
      * conversation for good: the browser stores the derived title before it sends, so every retry re-sent the
      * same rejected one. */
@@ -72,7 +72,7 @@ test("keeps a cut it cannot put on a word boundary inside the budget anyway", ()
     // Asserted THROUGH the contract rather than against a repeated literal: the clamp and the cap drifting
     // apart is the entire bug, and a second copy of the number is how they drift.
     expect(AgentTurnSchema.safeParse({ prompt, title }).success).toBe(true);
-    // Not a property of that one sentence — any token wide enough to swallow the window does it.
+    // Not a property of that one sentence: any token wide enough to swallow the window does it.
     const wide = `Investigate ${"X".repeat(120)} please`;
     expect(AgentTurnSchema.safeParse({ prompt: wide, title: deriveTitle(wide) }).success).toBe(true);
 });
@@ -111,7 +111,7 @@ test("names a prompt that is nothing but a paste after what was pasted", () => {
 });
 
 test("never returns empty for a prompt that has any content at all", () => {
-    // A greeting with no ask behind it, and a prompt with no letters in it — both still have to name a tab.
+    // A greeting with no ask behind it, and a prompt with no letters in it: both still have to name a tab.
     expect(deriveTitle("Hey!")).toBe("Hey!");
     expect(deriveTitle("!!!")).toBe("!!!");
 });
@@ -121,7 +121,7 @@ test("reads past quoted material to the user's own words", () => {
 });
 
 test("skips past-work narration to the instruction behind it", () => {
-    // `We have recently added…` is the scene, not the ask — titling from it names every such conversation
+    // `We have recently added…` is the scene, not the ask: titling from it names every such conversation
     // after last week's work. The instruction further in is what the conversation is about.
     expect(deriveTitle("We have recently added iq map and iq deps commands. Now let's also add a health contract for the daemon.")).toBe(
         "Add a health contract for the daemon",
@@ -134,13 +134,13 @@ test("skips narration to an outright question", () => {
 });
 
 test("keeps narration when nothing behind it is unmistakably the ask", () => {
-    // A hazy follow-up is not worth skipping for — better a title about last week's work than one about `it`.
+    // A hazy follow-up is not worth skipping for: better a title about last week's work than one about `it`.
     expect(deriveTitle("We migrated the board to SSE last week. It feels slower since.")).toBe("We migrated the board to SSE last week");
 });
 
 test("keeps a declarative problem report even when advice follows it", () => {
     // Only NARRATION is skippable. A problem statement is the ask, and the imperative behind it is merely a
-    // pointer — `Check the broadcast path` names a step, not the conversation.
+    // pointer: `Check the broadcast path` names a step, not the conversation.
     expect(deriveTitle("The fleet board flickers when agents land. Check the broadcast path.")).toBe("The fleet board flickers when agents land");
 });
 

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. */
+ * 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 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.test.ts

@@ -34,11 +34,11 @@ test("port slots are a fixed-size pool of DNS-safe labels, stable per token", ()
     expect(portSlotsFromToken(TOKEN)).toEqual(slots);
 });
 
-/* The whole point of the salt. The sandbox id is public — it is the leading label of the sandbox's own URL and
- * of every preview link its owner has shared — so anything derived from the id ALONE is derivable by whoever
+/* The whole point of the salt. The sandbox id is public: it is the leading label of the sandbox's own URL and
+ * of every preview link its owner has shared, so anything derived from the id ALONE is derivable by whoever
  * holds one of those links. Slots must not be: knowing a sandbox's id must not tell you where its forwarded
  * ports live. */
-test("slots are not derivable from the sandbox id — only from the token behind it", () => {
+test("slots are not derivable from the sandbox id: only from the token behind it", () => {
     expect(portSlotsFromToken(OTHER)).not.toEqual(portSlotsFromToken(TOKEN));
     // No slot leaks the id it will be paired with in `port-<slot>-<sandboxId>`.
     const id = sandboxIdFromToken(TOKEN);

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.test.ts

@@ -25,15 +25,15 @@ test("isBehind stays quiet whenever it cannot be sure", () => {
 });
 
 /* A version with a segment that will not parse is read by its numeric prefix, and the failure is one-directional:
- * it can withhold a nag, never invent one. Both halves are pinned because only the second is a safety property —
+ * it can withhold a nag, never invent one. Both halves are pinned because only the second is a safety property:
  * the first is just the prefix doing its job. */
 test("a version that isn't dotted-numeric can only ever withhold the nudge", () => {
     expect(isBehind("1.2.0-rc.1", "1.183.0")).toBe(true); // the prefix already decides it: 2 is behind 183
     expect(isBehind("1.2.0-rc.1", "1.2.0")).toBe(false); // the unparseable segment is where they differ — silence
 });
 
-// The version every agent shipped before the release stamp existed. It is genuinely behind — it predates every
-// release that has one — and it must read that way, because those are the installs this whole signal is for.
+// The version every agent shipped before the release stamp existed. It is genuinely behind: it predates every
+// release that has one, and it must read that way, because those are the installs this whole signal is for.
 test("isBehind flags the hand-written version agents used to carry", () => {
     expect(isBehind("0.1.0", "1.183.0")).toBe(true);
 });

package/src/versions.ts

@@ -1,9 +1,9 @@
-/* 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.
  *
- * Shared rather than copied because the two copies would not disagree until the day it mattered — 1.9.0 against
+ * Shared rather than copied because the two copies would not disagree until the day it mattered: 1.9.0 against
  * 1.10.0 is where a hand-rolled comparator goes wrong, and it goes wrong by reporting "up to date". */
 
 // Release versions are plain dotted numerics (semantic-release picks them), so there is no semver dependency to
@@ -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.test.ts

@@ -3,7 +3,7 @@ import { type Workflow, WorkflowSchema, type WorkflowStep } from "./schemas.js";
 import { workflowFaults, workflowRunFaults } from "./workflow-faults.js";
 
 /* The GATE rules. The graph rules beside them are exercised by the scheduler's own integration tests, which
- * have a real run to check them against; these have none to check, which is the point — every fault here is one
+ * have a real run to check them against; these have none to check, which is the point: every fault here is one
  * the workflow has to be refused for BEFORE a run, because the failure it prevents costs a full fan-out of
  * sessions and then reports nothing anybody can act on.
  */
@@ -78,7 +78,7 @@ test("a gate on a field the step does not declare is refused", () => {
 test("a gate on a list field is refused", () => {
     const steps = [judge({ output: { kind: "json", fields: [{ name: "release", type: "string[]", description: "the verdicts", required: true }] } })];
     const faults = workflowFaults(gated({ steps }));
-    expect(faults).toEqual([`The gate reads "release", which is a list — a release decision has to be one value.`]);
+    expect(faults).toEqual([`The gate reads "release", which is a list: a release decision has to be one value.`]);
 });
 
 // The expensive one to discover at run time: it passes every save, then blocks a release on the one commit
@@ -86,10 +86,10 @@ test("a gate on a list field is refused", () => {
 test("a gate on an optional field is refused", () => {
     const steps = [judge({ output: { kind: "json", fields: [{ name: "release", type: "string", description: "pass | fail", required: false }] } })];
     const faults = workflowFaults(gated({ steps }));
-    expect(faults).toEqual([`The gate reads "release", which "Judge" declares optional — it has to be required.`]);
+    expect(faults).toEqual([`The gate reads "release", which "Judge" declares optional, it has to be required.`]);
 });
 
-/* THE RUN-TIME RULE, kept apart from every rule above it because it is not about the graph — and the graph is
+/* THE RUN-TIME RULE, kept apart from every rule above it 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 the ordinary shape
  * and must save cleanly; it is only unrunnable on the particular run that brought no request.
  */
@@ -102,7 +102,7 @@ test("a design whose steps inherit is a perfectly good design", () => {
 });
 
 /* Refused at the door rather than discovered by the first step, because this is the one combination with
- * nothing to tell the model at all — and by the time a step found out, the run has already opened a session per
+ * nothing to tell the model at all, and by the time a step found out, the run has already opened a session per
  * root and started paying for them.
  */
 test("running an inheriting design with no request is refused", () => {
@@ -120,7 +120,7 @@ test("a step that declares only one of the two still needs a request", () => {
     expect(workflowRunFaults(gated({ steps: [judge({ prompt: undefined })] }), undefined)).toHaveLength(1);
 });
 
-// A design that says everything itself is startable from anywhere, with no composer behind it — which is what
+// A design that says everything itself is startable from anywhere, with no composer behind it, which is what
 // keeps the gate's webhook and the workflows page working for the designs written that way.
 test("a design that declares everything runs with no request at all", () => {
     expect(workflowRunFaults(gated(), undefined)).toEqual([]);