@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/{documents.test.ts → text/documents.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 import { documentOf, documentTitle, isDocumentPath, isPlanDocumentPath } from "./documents.js";
-import { PLAN_DOCUMENTS_DIR } from "./workspace-state.js";
+import { PLAN_DOCUMENTS_DIR } from "../state/workspace-state.js";
 
 const write = (path: string, newText: string, extra: { oldText?: string; truncated?: boolean } = {}) => [
     { type: "diff" as const, path, newText, ...extra },

package/src/text/documents.ts

@@ -0,0 +1,42 @@
+import type { CardDocument, ToolCallContent } from "../events/cards.js";
+import { planParts } from "./title.js";
+import { PLAN_DOCUMENTS_DIR } from "../state/workspace-state.js";
+
+// A document is a turn's output for a person to read, distinct from a file changed for the machine; only a whole-file
+// write counts, an Edit's fragment stays a diff. Shared here so the daemon (parked-card logic) and the browser
+// (tool-card rendering) can't drift on what counts as one.
+
+// Markdown only: the chat's prose pipeline renders it; a .txt report is better left as a plain-text box.
+const DOCUMENT_EXTENSIONS = [".md", ".markdown"];
+
+export const isDocumentPath = (path: string): boolean => {
+    const lower = path.toLowerCase();
+    return DOCUMENT_EXTENSIONS.some((extension) => lower.endsWith(extension));
+};
+
+// Matched by directory, not name (a mint-fresh phrase like `map-of-this-wiggly-spring.md` carries no signal). The
+// directory is declared in workspace-state.ts, the one exception to its lock.
+export const isPlanDocumentPath = (path: string): boolean => path.startsWith(`${PLAN_DOCUMENTS_DIR}/`);
+
+// The opening heading (planParts) when there is one, else the file name; never the path, which is the CLI's mint and
+// tells the reader nothing.
+export const documentTitle = (markdown: string, path: string): string => planParts(markdown).title ?? path.split("/").pop() ?? path;
+
+// Reads the call's structured diff, not its result text: a Write's whole file already rides the frame as newText
+// (capped, truncated flags it). Works even for a published transcript with no workspace behind it.
+export const documentOf = (name: string, content: readonly ToolCallContent[] | undefined): CardDocument | undefined => {
+    if (name.toLowerCase() !== "write") {
+        return undefined;
+    }
+    const diff = content?.find((entry) => entry.type === "diff" && isDocumentPath(entry.path));
+    if (diff === undefined || diff.type !== "diff") {
+        return undefined;
+    }
+    return {
+        path: diff.path,
+        title: documentTitle(diff.newText, diff.path),
+        markdown: diff.newText,
+        ...(diff.truncated === true ? { truncated: true } : {}),
+        ...(isPlanDocumentPath(diff.path) ? { plan: true } : {}),
+    };
+};

package/src/text/embed.ts

@@ -0,0 +1,132 @@
+// The zod-free half of an embed's wire, shared by the two embeds (webchat-widget, issue-sdk) and the daemon's
+// public-door.ts. No imports, ever: this bundles into someone else's page, and the contract's barrel would drag in zod
+// (measured at 1.1 MB for two strings).
+
+// Where an embed talks to: the daemon it came from, and the automation it is the public face of.
+export interface EmbedEndpoint {
+    readonly base: string;
+    readonly automationId: string;
+}
+
+// The server's own refusal sentence ({"error": ...}), shown verbatim: it names exactly what to fix (e.g. "origin not
+// allowed").
+export class EmbedError extends Error {
+    constructor(
+        message: string,
+        readonly status: number,
+    ) {
+        super(message);
+        this.name = "EmbedError";
+    }
+}
+
+export const embedFailure = async (response: Response): Promise<EmbedError> => {
+    const body = (await response.json().catch(() => undefined)) as { error?: unknown } | undefined;
+    return new EmbedError(typeof body?.error === "string" ? body.error : `request failed (${response.status})`, response.status);
+};
+
+// One route of a public door: `<base>/<slug>/<automation>/<path>`, the daemon's own spelling.
+export const embedUrl = ({ base, automationId }: EmbedEndpoint, slug: string, path: string): string =>
+    `${base}/${slug}/${encodeURIComponent(automationId)}/${path}`;
+
+// One GET against a public door, answered as JSON or refused with the server's own sentence.
+export const fetchEmbedJson = async <T>(url: string): Promise<T> => {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw await embedFailure(response);
+    }
+    return (await response.json()) as T;
+};
+
+// Find a nonce whose SHA-256 of `salt:nonce` has `difficulty` leading zero bits, signed to one caller's id so it can't
+// be replayed elsewhere. Solved on the main thread, not a Worker: a host's CSP may forbid the blob: URL a Worker needs.
+export interface PowChallenge {
+    readonly salt: string;
+    readonly difficulty: number;
+}
+
+export const fetchEmbedChallenge = (endpoint: EmbedEndpoint, slug: string, param: string, id: string): Promise<PowChallenge> =>
+    fetchEmbedJson<PowChallenge>(`${embedUrl(endpoint, slug, "challenge")}?${param}=${encodeURIComponent(id)}`);
+
+const BATCH = 512;
+
+// Leading zero bits of a digest, up to `wanted`. Stops at the first non-zero byte, so a miss costs one byte.
+const leadingZeroBits = (digest: Uint8Array, wanted: number): number => {
+    let bits = 0;
+    for (const byte of digest) {
+        if (byte !== 0) {
+            // Math.clz32 counts 32-bit leading zeros; the byte sits in the low 8, so 24 are structural.
+            return bits + Math.clz32(byte) - 24;
+        }
+        bits += 8;
+        if (bits >= wanted) {
+            return bits;
+        }
+    }
+    return bits;
+};
+
+// Resolves to `<salt>:<nonce>`, so the daemon can re-derive the challenge without storing one. insecure is for an
+// http:// page: crypto.subtle needs a secure context, and the fix is the site's TLS.
+export const solveProofOfWork = async (challenge: PowChallenge, insecure: string, onProgress?: (attempts: number) => void): Promise<string> => {
+    if (crypto.subtle === undefined) {
+        throw new Error(insecure);
+    }
+    const encoder = new TextEncoder();
+    for (let nonce = 0; ; nonce += 1) {
+        const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(`${challenge.salt}:${nonce}`)));
+        if (leadingZeroBits(digest, challenge.difficulty) >= challenge.difficulty) {
+            return `${challenge.salt}:${nonce}`;
+        }
+        if (nonce % BATCH === BATCH - 1) {
+            onProgress?.(nonce + 1);
+            // Hands the main thread back so the page (and the "checking..." line) keeps painting.
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+    }
+};
+
+// localStorage can throw (Safari private mode, blocked storage); the embed still works, just minting a fresh id per
+// load. Silent by design: an embed must never put an error in the console.
+export const readStored = (name: string): string | undefined => {
+    try {
+        return window.localStorage.getItem(name) ?? undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+export const writeStored = (name: string, value: string): void => {
+    try {
+        window.localStorage.setItem(name, value);
+    } catch {
+        // No storage: this load keeps the value in memory, the next one mints another.
+    }
+};
+
+// A per-browser id, not identity and not a secret: it threads a visitor's messages into one conversation, or bounds a
+// rate window per tab.
+export const storedId = (name: string): string => {
+    const existing = readStored(name);
+    if (existing !== undefined && existing !== "") {
+        return existing;
+    }
+    const minted = crypto.randomUUID();
+    writeStored(name, minted);
+    return minted;
+};
+
+// The daemon to talk to is this script's own origin, the one thing a copy-paste can't get wrong; data-base overrides it
+// behind a reverse proxy. currentScript is read at module scope, valid only synchronously; querySelector is the
+// fallback.
+export const embedScript = (srcMatch: string): HTMLScriptElement | null =>
+    (document.currentScript as HTMLScriptElement | null) ?? document.querySelector<HTMLScriptElement>(`script[src*="${srcMatch}"]`);
+
+// Undefined with no automation id, the one mistake worth flagging: otherwise the embed is silently absent.
+export const embedEndpointOf = (script: HTMLScriptElement): EmbedEndpoint | undefined => {
+    const automationId = script.dataset["automation"];
+    if (automationId === undefined || automationId === "") {
+        return undefined;
+    }
+    return { automationId, base: (script.dataset["base"] ?? new URL(script.src, window.location.href).origin).replace(/\/$/, "") };
+};

package/src/text/mentions.ts

@@ -0,0 +1,21 @@
+// Two readers of the same @-mention text: the composer resolves a path into a Read-tool attachment, the fold draws
+// uploaded files as chips and hides inline mentions since they're already visible in the words. One tokenizer keeps
+// them in agreement.
+
+// Broad on purpose, including invalid mentions: old turns persisted these candidates in the attachment field, and the
+// fold needs the same broad set to hide them.
+export const mentionedPathTokens = (text: string): string[] => {
+    const paths = new Set<string>();
+    for (const match of text.matchAll(/(?:^|\s)@([^\s@]+)/g)) {
+        const token = (match[1] as string).replace(/[.,;:!?)]+$/, ``);
+        if (token.includes(`/`) || token.includes(`.`)) {
+            paths.add(token);
+        }
+    }
+    return [...paths];
+};
+
+// Excludes a copied pnpm script prefix (`@scope/package:test:`), which shares the opening shape but is not a file;
+// accepting it creates a phantom attachment.
+const PACKAGE_SCRIPT = /^[^/]+\/[^/]+:[^/]+$/u;
+export const mentionPaths = (text: string): string[] => mentionedPathTokens(text).filter((token) => !PACKAGE_SCRIPT.test(token));

package/src/text/model-answer.ts

@@ -0,0 +1,9 @@
+// Four callers ask a model for a one-line answer and always strip what wraps it (a code fence, a label prefix, a list
+// bullet) rather than reject it. The label pattern isn't shared, since each caller strips a different word. Lives here,
+// not beside a caller, since the callers span two daemon subsystems that can't import each other.
+
+// A fenced block's open (with/without a language) and close; `.replace` only, `g` makes test/exec stateful.
+export const FENCE = /^```[\w-]*\n?|\n?```$/gu;
+
+// A leading list marker, for the answer returned as a list of one.
+export const BULLET = /^[-*]\s+/u;

package/src/text/path-refs.ts

@@ -0,0 +1,39 @@
+// A prose path reference is loosely anchored (a working prefix, a worktree's absolute prefix) but ends in the real
+// workspace-relative path. Resolved by matching shorter tails against the tree; the browser and daemon run the
+// identical rule so they can't disagree.
+
+// Leading segments a reference may exceed the workspace by; a worktree's own lead is 3 segments.
+const MAX_DROPS = 6;
+// Never cut to a bare filename: one name can match a hundred files in a monorepo, worse than not linking.
+const MIN_SEGMENTS = 2;
+// Enough candidates for a picker; a reference matching more than this is ambiguous by any measure.
+export const MAX_REF_CANDIDATES = 10;
+
+// Tails ordered longest (most specific) first. root is the container workspace root: a path under it is the answer
+// minus that lead; a path under any other absolute root (a worktree) mirrors the same layout below its own lead.
+export const referenceTails = (raw: string, root: string): readonly string[] => {
+    const normalized = raw.replaceAll(`\\`, `/`).replace(/^\.\//, ``);
+    const anchored = normalized.startsWith(`${root}/`) ? normalized.slice(root.length + 1) : normalized.replace(/^\/+/, ``);
+    const segments = anchored.split(`/`).filter((segment) => segment !== `` && segment !== `.`);
+    const tails: string[] = [];
+    for (let drop = 0; drop <= MAX_DROPS && segments.length - drop >= MIN_SEGMENTS; drop++) {
+        tails.push(segments.slice(drop).join(`/`));
+    }
+    return tails;
+};
+
+// Segment-boundary matches only, best (shallowest) first: pages/Foo.vue means the app's page, not a copy nested in a
+// fixture tree. The daemon's glob only anchors at the string level, so the boundary is enforced here.
+export const rankRefCandidates = (tail: string, paths: readonly string[]): readonly string[] =>
+    paths
+        .filter((path) => path === tail || path.endsWith(`/${tail}`))
+        .toSorted((a, b) => a.split(`/`).length - b.split(`/`).length || a.length - b.length || (a < b ? -1 : 1))
+        .slice(0, MAX_REF_CANDIDATES);
+
+// The one change-vs-tests rule, shared by every surface that needs it. Convention-based (.test./.spec., __tests__ dirs,
+// e2e-harness, runner configs); never bare "contains test", which would flag testimonials/ or latest.ts.
+const TEST_DIRS = new Set([`__tests__`, `__fixtures__`, `__mocks__`, `__snapshots__`]);
+const TEST_FILE =
+    /(?:^|\/)(?:[^/]+\.(?:test|spec)\.[^/.]+|[^/]*\.e2e\.[^/]+|e2e-harness\.[^/]+|(?:vitest|jest|playwright)(?:\.[\w-]+)*\.config\.[^/]+)$/;
+
+export const isTestPath = (path: string): boolean => TEST_FILE.test(path) || path.split(`/`).some((segment) => TEST_DIRS.has(segment));

package/src/text/shell-regions.ts

@@ -0,0 +1,224 @@
+// Marks command text that is not a program, so the un-waivable hard-rule tier stops firing inside comments, heredoc
+// bodies, and quoted arguments of verbs that can't execute them (echo, grep, a -m message). Missing a region costs one
+// judge call; inventing one only skips the hard rule, never the judge. sed/awk/perl are excluded: each can run its own
+// argument.
+
+import type { CommandSpan } from "../policy/command-classes.js";
+
+// Verbs whose quoted argument this scanner treats as text; each prints or matches it, none executes it.
+const QUOTING_VERBS: ReadonlySet<string> = new Set([
+    "echo",
+    "printf",
+    "rg",
+    "grep",
+    "egrep",
+    "fgrep",
+    "ack",
+    "ag",
+    "ripgrep",
+]);
+
+// A message flag (git's -m, etc.): the quoted argument is prose, whatever verb precedes it.
+const MESSAGE_FLAGS: ReadonlySet<string> = new Set(["-m", "--message", "-am", "--body", "-b"]);
+
+// Where an unquoted word ends: whitespace, a pipeline/list operator, a redirect, a paren.
+const WORD_END = /[\s;|&<>()]/;
+
+// A variable-assignment prefix (`FOO=bar cmd`), skipped when looking for the verb.
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+// `<<EOF`, `<<-EOF`, quoted or not; the delimiter's quoting only affects expansion, not classification here.
+const HEREDOC_OPEN = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+
+// Found in their own pass, first: a heredoc body is line-oriented and can hold anything, an odd quote count in it would
+// desync the word scanner.
+const heredocBodies = (command: string): CommandSpan[] => {
+    const bodies: CommandSpan[] = [];
+    for (const open of command.matchAll(HEREDOC_OPEN)) {
+        const indented = command.slice(open.index, open.index + 3).startsWith("<<-");
+        const newline = command.indexOf("\n", open.index + open[0].length);
+        if (newline === -1) {
+            // An unterminated heredoc (nothing after the opener): no body to mark.
+            continue;
+        }
+        const start = newline + 1;
+        const terminator = new RegExp(`^${indented ? "[ \\t]*" : ""}${open[2] as string}[ \\t]*$`, "m");
+        const rest = command.slice(start);
+        const end = terminator.exec(rest)?.index;
+        // An unterminated body runs to the end of the command, same as the shell would read it.
+        bodies.push({ start, end: end === undefined ? command.length : start + end });
+    }
+    return bodies;
+};
+
+// Is this offset inside an already-found span? Heredoc bodies are skipped wholesale by the word scan.
+const within = (spans: readonly CommandSpan[], offset: number): CommandSpan | undefined =>
+    spans.find((span) => offset >= span.start && offset < span.end);
+
+// A substitution inside double quotes, the one thing that turns a quoted argument back into a program.
+const EXPANDS = /\$\(|`/;
+
+// The span covers the quotes too, so a match anywhere in `"rm -rf /"` reads as contained.
+interface QuotedSegment {
+    readonly span: CommandSpan;
+    // A double-quoted substitution is not text and never becomes a region; single quotes never set this.
+    readonly expands: boolean;
+}
+
+interface ShellWord {
+    readonly start: number;
+    // The word with quoting removed, compared against a verb name or a flag.
+    readonly text: string;
+    readonly quoted: readonly QuotedSegment[];
+    // Does this word begin a simple command? True for the first word after a separator or at the start.
+    readonly opensCommand: boolean;
+}
+
+// A verb by its bare name: `/bin/echo` and `./echo` are both echo, the path says nothing new.
+const bareVerb = (text: string): string => text.slice(Math.max(text.lastIndexOf("/"), text.lastIndexOf("\\")) + 1);
+
+// Every list/pipeline operator; past one, the next word is a verb again.
+const SEPARATORS = new Set(["\n", ";", "|", "&", "(", ")"]);
+const BLANKS = new Set([" ", "\t", "\r"]);
+
+// An unbalanced quote runs to the end of the command, as a shell waiting for more input would, keeping the caller
+// advancing.
+const readQuoted = (command: string, open: number): QuotedSegment & { readonly text: string; readonly end: number } => {
+    const quote = command[open] as string;
+    const close = command.indexOf(quote, open + 1);
+    const end = close === -1 ? command.length : close + 1;
+    const text = command.slice(open + 1, close === -1 ? command.length : close);
+    return { span: { start: open, end }, expands: quote === '"' && EXPANDS.test(text), text, end };
+};
+
+// end === start can't happen: the caller only enters here on a character that is neither blank nor a separator.
+const readWord = (command: string, start: number): { readonly word: Omit<ShellWord, "opensCommand">; readonly end: number } => {
+    const quoted: QuotedSegment[] = [];
+    let text = "";
+    let index = start;
+    while (index < command.length && !WORD_END.test(command[index] as string)) {
+        const char = command[index] as string;
+        if (char === "'" || char === '"') {
+            const segment = readQuoted(command, index);
+            quoted.push({ span: segment.span, expands: segment.expands });
+            text += segment.text;
+            index = segment.end;
+            continue;
+        }
+        if (char === "\\") {
+            text += command[index + 1] ?? "";
+            index += 2;
+            continue;
+        }
+        text += char;
+        index += 1;
+    }
+    return { word: { start, text, quoted }, end: index };
+};
+
+// A scanner, not a parser: tracks quoting and the separators that start a new command, nothing about control flow,
+// functions or expansion.
+const scanWords = (command: string, skip: readonly CommandSpan[]): ShellWord[] => {
+    const words: ShellWord[] = [];
+    let index = 0;
+    let opensCommand = true;
+    while (index < command.length) {
+        const skipped = within(skip, index);
+        if (skipped !== undefined) {
+            index = skipped.end;
+            continue;
+        }
+        const char = command[index] as string;
+        if (SEPARATORS.has(char)) {
+            opensCommand = true;
+            index += 1;
+            continue;
+        }
+        if (BLANKS.has(char)) {
+            index += 1;
+            continue;
+        }
+        if (char === "#") {
+            // Runs to end of line; only reached at a word boundary, so `a#b` is one word.
+            const newline = command.indexOf("\n", index);
+            index = newline === -1 ? command.length : newline;
+            continue;
+        }
+        const { word, end } = readWord(command, index);
+        // A stray character, neither separator nor word (e.g. a bad redirect): step over it so the loop advances.
+        index = end === index ? index + 1 : end;
+        if (end !== word.start) {
+            words.push({ ...word, opensCommand });
+            opensCommand = false;
+        }
+    }
+    return words;
+};
+
+// Unsorted and possibly overlapping; callers only ask containment of them. Computed once per command by the classifier
+// and shared across every table.
+export const inertRegions = (command: string): CommandSpan[] => {
+    const bodies = heredocBodies(command);
+    const regions: CommandSpan[] = [...bodies];
+    const words = scanWords(command, bodies);
+    // Found again here, where quoting state lives: a `#` inside a quoted string isn't a comment.
+    let quotingVerb = false;
+    let previous: ShellWord | undefined;
+    for (const word of words) {
+        if (word.opensCommand) {
+            quotingVerb = QUOTING_VERBS.has(bareVerb(word.text));
+            previous = undefined;
+        }
+        // An env assignment before the verb (`LC_ALL=C grep`) isn't the verb; re-read the next word instead.
+        if (word.opensCommand && ASSIGNMENT.test(word.text) && word.quoted.length === 0) {
+            quotingVerb = false;
+            previous = undefined;
+            continue;
+        }
+        const afterMessageFlag = previous !== undefined && MESSAGE_FLAGS.has(previous.text);
+        if (quotingVerb || afterMessageFlag) {
+            regions.push(...word.quoted.filter((segment) => !segment.expands).map((segment) => segment.span));
+        }
+        previous = word;
+    }
+    regions.push(...commentRegions(command, bodies));
+    return regions;
+};
+
+// Its own walk: the word scan needs what's inside a quote, this only needs to be past it. Sharing readQuoted keeps both
+// agreeing on where one ends.
+const commentRegions = (command: string, skip: readonly CommandSpan[]): CommandSpan[] => {
+    const comments: CommandSpan[] = [];
+    let index = 0;
+    while (index < command.length) {
+        const skipped = within(skip, index);
+        if (skipped !== undefined) {
+            index = skipped.end;
+            continue;
+        }
+        const char = command[index] as string;
+        if (char === "'" || char === '"') {
+            index = readQuoted(command, index).end;
+            continue;
+        }
+        if (char === "\\") {
+            index += 2;
+            continue;
+        }
+        // A word boundary before it is what makes it a comment, not part of a word.
+        if (char === "#" && (index === 0 || WORD_END.test(command[index - 1] as string))) {
+            const newline = command.indexOf("\n", index);
+            const end = newline === -1 ? command.length : newline;
+            comments.push({ start: index, end });
+            index = end;
+            continue;
+        }
+        index += 1;
+    }
+    return comments;
+};
+
+// Judged on where the fragment starts, not whether the whole match is contained: every pattern begins at the verb, so
+// the start is what's found. A verb outside every region stays live no matter what follows it.
+export const isLive = (span: CommandSpan, regions: readonly CommandSpan[]): boolean =>
+    !regions.some((region) => span.start >= region.start && span.start < region.end);

package/src/{title.test.ts → text/title.test.ts}

@@ -1,26 +1,20 @@
 import { expect, test } from "vitest";
-import { AgentTurnSchema } from "./schemas/agent.js";
+import { AgentTurnSchema } from "../schemas/agent.js";
 import { deriveTitle } from "./title.js";
 
-/* The name a conversation opens under. Every case here is a shape the naive rule (collapse whitespace, cut at
- * 40) got wrong in a way a user notices: the title named the paste instead of the work, spent the budget on
- * politeness, or stopped mid-syllable. */
+// Titles deriveTitle produces; every case here is a shape a naive collapse-and-cut-at-40 rule got noticeably wrong.
 
 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.
     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
-    // 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?");
 });
 
 test("titles a pasted stack trace after the sentence the user wrote around it", () => {
-    // The paste is evidence, not the ask. Titling from it gives every one of the day's pastes the same name.
     const prompt = [
         "The build is broken again.",
         "",
@@ -34,14 +28,11 @@ 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 -`.
     expect(deriveTitle("Hey, quick one —\n\nWhy does the tab title truncate mid-word?")).toBe("Why does the tab title truncate mid-word?");
 });
 
 test("keeps an ask that fits the registry's 80-character budget instead of cutting at 40", () => {
-    // The old 40-character clamp cut this to `In intentic-app/web when conflict…` on a fleet card that had
-    // room for twice that. The stored title matches what the registry and the rename input accept.
+    // Matches the registry's stored-title budget, not an arbitrary length.
     const prompt = "In intentic-app/web when conflicts happen during rebase show a resolution banner";
 
     expect(deriveTitle(prompt)).toBe(prompt);
@@ -53,26 +44,20 @@ test("cuts on a word boundary instead of mid-syllable", () => {
     const kept = title.slice(0, -1);
 
     expect(title.endsWith("…")).toBe(true);
-    // The old rule sliced at exactly 40, ending this title inside `mid-word`. Every word that survives has to
-    // be a whole one, so what precedes the ellipsis must stop where the prompt itself has a break.
     expect(prompt.startsWith(kept)).toBe(true);
     expect(prompt[kept.length]).toBe(" ");
 });
 
 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
-     * 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. */
+    // The clamp alone ends the title when no boundary is late enough; overshooting the schema's cap even by one char
+    // wedges every retry, since the browser stores the title before sending.
     const prompt = `In one of the sandboxes I have experienced "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS" limit of 20. Make it configurable in sandbox settings somewhere at /sandbox/agent`;
     const title = deriveTitle(prompt);
 
     expect(title.endsWith("…")).toBe(true);
-    // 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.
+    // Checked against the contract, not a repeated literal: a second copy of the cap is how it would 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 triggers it.
     const wide = `Investigate ${"X".repeat(120)} please`;
     expect(AgentTurnSchema.safeParse({ prompt: wide, title: deriveTitle(wide) }).success).toBe(true);
 });
@@ -80,14 +65,14 @@ test("keeps a cut it cannot put on a word boundary inside the budget anyway", ()
 test("keeps a link's last meaningful segment rather than its host and scaffolding", () => {
     const title = deriveTitle("Look at https://gitlab.com/radarsu/intentic/-/merge_requests/42 and tell me what broke");
 
-    // A numeric tail alone (`42`) names nothing, so the segment above it comes along.
+    // A numeric tail alone ("42") would name nothing, so the segment above it comes along.
     expect(title).toContain("merge_requests/42");
     expect(title).not.toContain("gitlab.com");
 });
 
 test("collapses a deep path to its basename and leaves a shallow one alone", () => {
     expect(deriveTitle("Refactor _editor/web/src/composables/chat/conversation.ts")).toBe("Refactor conversation.ts");
-    // Two segments already read as a place; collapsing them would lose the only context the reference carries.
+    // Two segments already read as a place; collapsing would lose the reference's only context.
     expect(deriveTitle("Refactor src/foo.ts")).toBe("Refactor src/foo.ts");
 });
 
@@ -96,7 +81,7 @@ test("ends on the first sentence when the prompt keeps going", () => {
 });
 
 test("does not mistake an abbreviation for the end of a sentence", () => {
-    // `i.e.` would otherwise cut the title to `i.e`, which names nothing at all.
+    // Would otherwise cut to `i.e`, naming nothing.
     expect(deriveTitle("i.e. the derived title should survive")).toBe("i.e. the derived title should survive");
 });
 
@@ -106,12 +91,11 @@ test("leaves casing alone when the opening word carries meaning in its casing",
 });
 
 test("names a prompt that is nothing but a paste after what was pasted", () => {
-    // Returning empty here would render a nameless tab; the first line of the paste at least says what it is.
     expect(deriveTitle("```ts\nconst x = 1;\n```")).toBe("const x = 1;");
 });
 
 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, and a prompt with no letters at all: both still must name a tab.
     expect(deriveTitle("Hey!")).toBe("Hey!");
     expect(deriveTitle("!!!")).toBe("!!!");
 });
@@ -121,8 +105,6 @@ 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
-    // 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 +116,12 @@ 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`.
+    // Not worth skipping for: a vague follow-up like "it" is worse context than the sentence before 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.
+    // Only narration is skippable; an imperative like "Check the broadcast path" names a step, not the ask.
     expect(deriveTitle("The fleet board flickers when agents land. Check the broadcast path.")).toBe("The fleet board flickers when agents land");
 });