@intentic/sandbox-contract 1.176.3 → 1.209.0

package/src/search-globs.test.ts

@@ -0,0 +1,46 @@
+import { expect, test } from "vitest";
+import { includeGlobs } from "./search-globs.js";
+
+test("an empty field scopes nothing", () => {
+    expect(includeGlobs(undefined)).toEqual({ globs: [], notGlobs: [] });
+    expect(includeGlobs(" , ")).toEqual({ globs: [], notGlobs: [] });
+});
+
+// The reported bug: a file name read as a folder name found nothing. Both forms come out, as VSCode's
+// expandGlobalGlob emits them.
+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.
+    expect(includeGlobs(`docs/`).globs).toEqual([`**/docs`, `**/docs/**`]);
+});
+
+test("a path is matched at any depth unless ./ anchors it to the root", () => {
+    expect(includeGlobs(`src/db`).globs).toEqual([`**/src/db`, `**/src/db/**`]);
+    expect(includeGlobs(`./src/db`).globs).toEqual([`./src/db`, `./src/db/**`]);
+    expect(includeGlobs(`/src/db`).globs).toEqual([`./src/db`, `./src/db/**`]);
+});
+
+test("a leading dot is the extension shorthand", () => {
+    expect(includeGlobs(`.ts`).globs).toEqual([`**/*.ts`, `**/*.ts/**`]);
+});
+
+test("wildcards are passed through as typed", () => {
+    expect(includeGlobs(`*.test.ts`).globs).toEqual([`**/*.test.ts`, `**/*.test.ts/**`]);
+    expect(includeGlobs(`src/**/*.vue`).globs).toEqual([`**/src/**/*.vue`, `**/src/**/*.vue/**`]);
+});
+
+test("commas separate patterns except inside a brace group or a character class", () => {
+    expect(includeGlobs(`*.{ts,py}`).globs).toEqual([`**/*.{ts,py}`, `**/*.{ts,py}/**`]);
+    expect(includeGlobs(`f[a,b].ts`).globs).toEqual([`**/f[a,b].ts`, `**/f[a,b].ts/**`]);
+    expect(includeGlobs(`docs, *.md`).globs).toEqual([`**/docs`, `**/docs/**`, `**/*.md`, `**/*.md/**`]);
+});
+
+test("a leading ! excludes instead", () => {
+    expect(includeGlobs(`src, !*.test.ts`)).toEqual({
+        globs: [`**/src`, `**/src/**`],
+        notGlobs: [`**/*.test.ts`, `**/*.test.ts/**`],
+    });
+    // A lone "!" excludes nothing — expanded, it would have matched everything.
+    expect(includeGlobs(`!`)).toEqual({ globs: [], notGlobs: [] });
+});

package/src/search-globs.ts

@@ -0,0 +1,76 @@
+/* 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:
+ *
+ *   `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`      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
+ *                   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
+ * recorded demo answers /workspace/search itself. Two readings of one field would make the same text mean
+ * different things depending on which one answered. */
+
+// VSCode's splitGlobAware: the split character is inert inside a brace group or a character class, so
+// `*.{ts,py}` and `f[a,b].ts` survive as single patterns.
+const splitPatterns = (include: string, splitChar: string): string[] => {
+    const segments: string[] = [];
+    let current = ``;
+    let inBraces = false;
+    let inBrackets = false;
+    for (const char of include) {
+        if (char === splitChar && !inBraces && !inBrackets) {
+            segments.push(current);
+            current = ``;
+            continue;
+        }
+        inBraces = char === `{` ? true : char === `}` ? false : inBraces;
+        inBrackets = char === `[` ? true : char === `]` ? false : inBrackets;
+        current += char;
+    }
+    segments.push(current);
+    return segments.map((segment) => segment.trim()).filter((segment) => segment !== ``);
+};
+
+/* One typed segment → the globs that answer it. The pair is the whole trick: `p` matches the file, `p/**`
+ * matches everything under a folder of that name, and either may be what the reader meant.
+ *
+ * `./p` and `/p` anchor at the workspace root; the `./` is kept on the way out because that is exactly how the
+ * engine's glob distinguishes an anchored pattern from a name it should look for at any depth. */
+const expand = (segment: string): string[] => {
+    const trimmed = segment.replace(/\/+$/, ``);
+    if (trimmed === ``) {
+        return [];
+    }
+    const anchored = /^\.?\//.test(trimmed);
+    if (anchored) {
+        const path = trimmed.replace(/^\.?\//, ``).replace(/^\/+/, ``);
+        return path === `` ? [] : [`./${path}`, `./${path}/**`];
+    }
+    // ".ts" is how people write an extension filter; VSCode reads it as "*.ts" rather than as a hidden file.
+    const pattern = trimmed.startsWith(`.`) ? `*${trimmed}` : trimmed;
+    return [`**/${pattern}`, `**/${pattern}/**`];
+};
+
+export interface IncludeGlobs {
+    // 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[];
+}
+
+export const includeGlobs = (include: string | undefined): IncludeGlobs => {
+    const segments = splitPatterns(include ?? ``, `,`);
+    return {
+        globs: segments.filter((segment) => !segment.startsWith(`!`)).flatMap(expand),
+        // A bare "!" excludes nothing; without this it would expand into a glob that matches everything.
+        notGlobs: segments.filter((segment) => segment.startsWith(`!`)).flatMap((segment) => expand(segment.slice(1))),
+    };
+};

package/src/share-paths.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { SHARE_ID, shareId, shareStem } from "./share-paths.js";
+
+/* The id a shared conversation is filed under is two things at once: the readable half of a link somebody
+ * pastes, and the half of the address that has to be safe to join onto a directory path. Both halves are
+ * checked here, because the id is minted from a TITLE the user typed. */
+
+describe("the readable half", () => {
+    it("makes a link that says what it points at", () => {
+        expect(shareId("Fix the login redirect loop", "3f9c")).toBe("fix-the-login-redirect-loop-3f9c");
+    });
+
+    it("keeps a long title from running away with the address", () => {
+        const id = shareId("a".repeat(200), "3f9c");
+        expect(id.length).toBeLessThanOrEqual(64);
+        expect(SHARE_ID.test(id)).toBe(true);
+    });
+
+    // 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.
+    it("falls back to the random half when a title has no letters to give", () => {
+        expect(shareStem("日本語のタイトル")).toBe("");
+        expect(shareId("日本語のタイトル", "3f9c")).toBe("3f9c");
+    });
+});
+
+describe("the safe half", () => {
+    /* The id is joined onto a path, so a title is the one attacker-shaped input in it. These are the shapes
+     * that would matter if the alphabet were not closed. */
+    it.each([
+        ["../../etc/passwd", "etc-passwd"],
+        ["a/b", "a-b"],
+        [".hidden", "hidden"],
+        ["  spaces  everywhere  ", "spaces-everywhere"],
+        ["Emoji 🎉 title", "emoji-title"],
+        ["UPPER Case", "upper-case"],
+    ])("reduces %j to a name that can only be a name", (title, stem) => {
+        expect(shareStem(title)).toBe(stem);
+        expect(SHARE_ID.test(shareId(title, "3f9c"))).toBe(true);
+    });
+
+    // The guard the daemon applies before joining an id onto a directory, held to the whole minted space: no
+    // title can produce something it rejects, which is what makes a rejection there a bug rather than input.
+    it("mints nothing its own guard would refuse", () => {
+        const titles = ["Fix login", "../..", "🎉", "a".repeat(300), "-leading-dash", "trailing-dash-"];
+        expect(titles.every((title) => SHARE_ID.test(shareId(title, "00112233445566ff")))).toBe(true);
+    });
+});

package/src/share-paths.ts

@@ -0,0 +1,68 @@
+/* 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/
+ *     conversations/
+ *       _viewer/            the page's built assets, copied in once and shared by every share
+ *       <id>/
+ *         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
+ * 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
+ * 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
+// people paste to each other.
+export const SHARE_DIR = "conversations";
+
+// The one copy of the page's assets. Underscored to sort away from the shares themselves and to read as
+// 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
+// image path in the payload carries.
+export const SHARE_FILES_DIR = "files";
+
+// The absolute path the built assets are served from, and the `base` the page is built with.
+export const SHARE_VIEWER_BASE = `/${SHARE_DIR}/${SHARE_VIEWER_DIR}/`;
+
+/* The id a share is filed under: a readable stem from the title, plus randomness that is the ONLY thing
+ * standing between a stranger and the conversation.
+ *
+ * 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
+ * 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;
+
+export const shareStem = (title: string): string => {
+    const stem = title
+        .toLowerCase()
+        .normalize("NFKD")
+        // Anything that is not a plain letter or digit becomes a separator, which retires accents, punctuation,
+        // emoji and every writing system that would otherwise arrive percent-encoded in the address bar.
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, STEM_MAX)
+        .replace(/-+$/, "");
+    // A title made entirely of characters the rule above drops (a CJK title, an emoji) leaves nothing to read;
+    // the id is then the random half alone, which is still a perfectly good id.
+    return stem;
+};
+
+// `<stem>-<random>`, or the random half alone when the title had no letters to give.
+export const shareId = (title: string, random: string): string => {
+    const stem = shareStem(title);
+    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
+// 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/state-portability.ts

@@ -40,15 +40,15 @@ export interface StateFile {
 
 /* The entry that owns a path, LONGEST PREFIX FIRST.
  *
- * Manifests deliberately nest: `.intentic/claude/` is a provider credential store that also contains
- * `.intentic/claude/projects/`, the agent's memory notes and transcripts, which are the single most valuable
- * thing in a bundle. First-match resolution would classify the notes 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 matcher first.
+ * 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
+ * matcher first.
  *
- * Undefined for a path no entry claims. Callers decide what that means: the bundler treats an unclaimed
- * `.intentic` path as a bug (the coverage test is what makes that safe to assume) and unclaimed ordinary
- * workspace files as `carry`, which is what they are.
+ * Undefined for a path no entry claims. Callers decide what that means: workspace content (including an
+ * extension's undeclared output) defaults to `carry`, while unclaimed history machinery defaults to `derived`.
+ * The daemon's state-path coverage guard is what prevents one of its own credential stores from relying on the
+ * workspace default.
  */
 export const stateFileFor = <T extends StateFile>(path: string, files: readonly T[]): T | undefined =>
     files

package/src/title.test.ts

@@ -1,4 +1,5 @@
 import { expect, test } from "vitest";
+import { AgentTurnSchema } from "./schemas.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
@@ -58,6 +59,24 @@ test("cuts on a word boundary instead of mid-syllable", () => {
     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. */
+    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.
+    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.
+    const wide = `Investigate ${"X".repeat(120)} please`;
+    expect(AgentTurnSchema.safeParse({ prompt: wide, title: deriveTitle(wide) }).success).toBe(true);
+});
+
 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");
 
@@ -67,7 +86,7 @@ test("keeps a link's last meaningful segment rather than its host and scaffoldin
 });
 
 test("collapses a deep path to its basename and leaves a shallow one alone", () => {
-    expect(deriveTitle("Refactor _apps/web/src/composables/chat/conversation.ts")).toBe("Refactor conversation.ts");
+    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.
     expect(deriveTitle("Refactor src/foo.ts")).toBe("Refactor src/foo.ts");
 });

package/src/title.ts

@@ -142,14 +142,14 @@ const shortUrl = (token: string): string => {
 };
 
 // A path is worth its basename once it is deep enough that the lead is scaffolding — `src/foo.ts` already
-// reads as a place, `_apps/web/src/composables/chat/conversation.ts` reads as a wall.
+// 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("/");
     return segments.length > 2 ? (segments.findLast((segment) => segment !== "") ?? token) : token;
 };
 
 // Trailing punctuation belongs to the sentence, not to the reference inside it, so it is set aside across the
-// shortening and put back — `see _apps/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;
@@ -193,11 +193,20 @@ const sentencesOf = (text: string): string[] => {
     return parts;
 };
 
+/* 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
+ * 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
+ * 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. */
 const clamped = (text: string): string => {
     if (text.length <= MAX_LENGTH) {
         return text;
     }
-    const cut = text.slice(0, MAX_LENGTH);
+    const cut = text.slice(0, MAX_LENGTH - 1);
     const boundary = cut.lastIndexOf(" ");
     const kept = boundary >= MIN_WORD_CUT ? cut.slice(0, boundary) : cut;
     return `${kept.replace(/[\s,;:—–-]+$/, "")}…`;

package/src/tunnel-ids.ts

@@ -7,7 +7,7 @@ export const sha256Hex = (value: string): string => createHash("sha256").update(
 
 // The sandbox's stable 12-hex id, digested from the connect token. Used by:
 //   • the CLI's sandbox-tunnel bootstrap (sandbox-tunnel.ts) to name the tunnel + DNS
-//   • the sandbox daemon's preview hostname builder (preview-hostname.ts)
+//   • the preview hostname builder beside it (hostnames.ts)
 //   • the sandbox daemon's sync SSH hostname derivation (sync.ts)
 // All three MUST agree on the digest, so it lives in the contract they share.
 export const sandboxIdFromToken = (connectToken: string): string | undefined =>
@@ -41,3 +41,17 @@ export const PORT_SLOT_COUNT = 8;
  * 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
+ * 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
+ * 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
+ * front of them: with no directory listing (public-files.ts refuses one) an outsider must guess a 12-hex label
+ * AND a filename to reach anything at all. */
+export const publicSlotFromToken = (connectToken: string): string => sha256Hex(`${connectToken}:public`).slice(0, 12);

package/src/versions.test.ts

@@ -0,0 +1,39 @@
+import { expect, test } from "vitest";
+import { DEV_VERSION, isBehind, isNewer } from "./versions.js";
+
+test("isNewer compares dotted numeric versions", () => {
+    expect(isNewer("1.3.0", "1.2.9")).toBe(true); // newer minor
+    expect(isNewer("1.2.10", "1.2.9")).toBe(true); // numeric, not lexical
+    expect(isNewer("2.0.0", "1.9.9")).toBe(true); // newer major
+    expect(isNewer("1.2.3", "1.2.3")).toBe(false); // equal
+    expect(isNewer("1.2.2", "1.2.3")).toBe(false); // older
+    expect(isNewer("1.2", "1.2.0")).toBe(false); // missing segment treated as 0
+});
+
+test("isBehind reports a released build that a newer release has passed", () => {
+    expect(isBehind("1.182.0", "1.183.0")).toBe(true);
+    expect(isBehind("1.183.0", "1.183.0")).toBe(false);
+    expect(isBehind("1.184.0", "1.183.0")).toBe(false); // ahead of what this sandbox knows about
+});
+
+// Every way of not knowing resolves to silence. Each of these once had a plausible argument for nagging, and
+// each would have nagged somebody who could do nothing about it.
+test("isBehind stays quiet whenever it cannot be sure", () => {
+    expect(isBehind(undefined, "1.183.0")).toBe(false); // the agent reports no version
+    expect(isBehind("1.182.0", undefined)).toBe(false); // this sandbox has no latest to compare against
+    expect(isBehind(DEV_VERSION, "1.183.0")).toBe(false); // a build made from a working tree, not a release
+});
+
+/* 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 —
+ * 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.
+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

@@ -0,0 +1,48 @@
+/* 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
+ * 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
+// take on. A MISSING segment counts as 0, which is what makes "1.2" and "1.2.0" the same version rather than
+// adjacent ones.
+export const isNewer = (a: string, b: string): boolean => {
+    const left = a.split(".").map(Number);
+    const right = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const l = left[i] ?? 0;
+        const r = right[i] ?? 0;
+        if (l !== r) {
+            return l > r;
+        }
+    }
+    return false;
+};
+
+/* The sentinel every build that is NOT a release carries: the repo keeps 0.0.0 in package.json and only
+ * semantic-release stamps a real one, so a working-tree daemon and a locally-compiled agent both answer this.
+ *
+ * It has to be excluded from the comparison rather than merely lose it. Every published release outranks 0.0.0,
+ * so a developer running the agent they just built would be told, permanently, to replace it with something
+ * older than what they are running. The daemon already draws exactly this line for itself (isDevBuild). */
+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.
+ *
+ * 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.
+ *
+ * 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. */
+export const isBehind = (installed: string | undefined, latest: string | undefined): boolean =>
+    installed !== undefined && latest !== undefined && installed !== DEV_VERSION && isNewer(latest, installed);

package/src/workflow-faults.test.ts

@@ -0,0 +1,127 @@
+import { expect, test } from "vitest";
+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
+ * 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.
+ */
+
+const judge = (over: Partial<WorkflowStep> = {}): WorkflowStep => ({
+    id: "judge",
+    title: "Judge",
+    goal: "a release decision exists",
+    prompt: "weigh what the steps before you found",
+    needs: [],
+    handoff: "fresh",
+    output: { kind: "json", fields: [{ name: "release", type: "string", description: "pass | fail", required: true }] },
+    checks: [],
+    context: "fresh",
+    ...over,
+});
+
+const gated = (over: Partial<Workflow> = {}): Workflow => ({
+    id: "release-gate",
+    name: "release gate",
+    steps: [judge()],
+    maxParallel: 1,
+    gate: { step: "judge", field: "release", pass: ["pass"] },
+    ...over,
+});
+
+test("a well-formed gate is no fault at all", () => {
+    expect(workflowFaults(gated())).toEqual([]);
+});
+
+test("a workflow with no gate is judged on its graph alone", () => {
+    const { gate: _gate, ...ungated } = gated();
+    expect(workflowFaults(ungated)).toEqual([]);
+});
+
+test("duplicate output field names are one fault at both authoring and schema boundaries", () => {
+    const duplicate = gated({
+        steps: [
+            judge({
+                output: {
+                    kind: "json",
+                    fields: [
+                        { name: "release", type: "string", description: "pass | fail", required: true },
+                        { name: "release", type: "boolean", description: "whether to release", required: true },
+                    ],
+                },
+            }),
+        ],
+    });
+
+    expect(workflowFaults(duplicate)).toContain(`"Judge" declares the output field "release" more than once; field names must be unique.`);
+    expect(WorkflowSchema.safeParse(duplicate).success).toBe(false);
+});
+
+test("a gate naming a step the workflow does not have is refused", () => {
+    const faults = workflowFaults(gated({ gate: { step: "nope", field: "release", pass: ["pass"] } }));
+    expect(faults).toEqual([`The gate reads step "nope", which is not a step in this workflow.`]);
+});
+
+test("a gate on a step that declares no output fields is refused", () => {
+    const faults = workflowFaults(gated({ steps: [judge({ output: { kind: "claim" } })] }));
+    expect(faults).toEqual([`The gate reads "Judge", but that step declares no output fields for it to read.`]);
+});
+
+test("a gate on a field the step does not declare is refused", () => {
+    const faults = workflowFaults(gated({ gate: { step: "judge", field: "shipit", pass: ["pass"] } }));
+    expect(faults).toEqual([`The gate reads "shipit", which "Judge" does not declare.`]);
+});
+
+// A list has no reading as a release decision, and the one it would fall into (join and compare) is a rule
+// nobody wrote down.
+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.`]);
+});
+
+// The expensive one to discover at run time: it passes every save, then blocks a release on the one commit
+// where the model decided the field was not worth writing.
+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.`]);
+});
+
+/* 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.
+ */
+
+// The shape the whole feature is for: a saved design that says nothing about the task, pointed at today's job.
+test("a design whose steps inherit is a perfectly good design", () => {
+    const inheriting = gated({ steps: [judge({ goal: undefined, prompt: undefined })] });
+    expect(workflowFaults(inheriting)).toEqual([]);
+    expect(workflowRunFaults(inheriting, "make the importer handle empty files")).toEqual([]);
+});
+
+/* 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
+ * root and started paying for them.
+ */
+test("running an inheriting design with no request is refused", () => {
+    const inheriting = gated({ steps: [judge({ goal: undefined, prompt: undefined })] });
+    expect(workflowRunFaults(inheriting, undefined)).toHaveLength(1);
+    expect(workflowRunFaults(inheriting, undefined)[0]).toContain(`"Judge"`);
+    // Whitespace is not a request. The composer trims before sending, but the gate's webhook body does not.
+    expect(workflowRunFaults(inheriting, "   \n ")).toHaveLength(1);
+});
+
+// Only half-inheriting is still inheriting: a step with its own instruction but no goal is measured against
+// the request, so it needs one just as much.
+test("a step that declares only one of the two still needs a request", () => {
+    expect(workflowRunFaults(gated({ steps: [judge({ goal: undefined })] }), undefined)).toHaveLength(1);
+    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
+// 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([]);
+});