@caelo-cms/shared 0.10.22 → 0.10.23

package/src/snapshots.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Zod input schemas for the P4 snapshot ops. Lives in @caelo-cms/shared so that
+ * route actions and the ops themselves import from a single source — same
+ * pattern as packages/shared/src/content.ts for P3.
+ *
+ * Every schema is `.strict()` so unknown keys are rejected at the Validator
+ * before the handler runs. Snapshot state JSONB is *not* validated by Zod
+ * here — it is emitted by trusted ops, never user-supplied (see CMS plan
+ * §"Validator rules").
+ */
+
+import { z } from "zod";
+
+export const snapshotsListInput = z
+  .object({
+    /** ISO timestamp; only snapshots strictly before this are returned. */
+    before: z.string().datetime().optional(),
+    limit: z.number().int().min(1).max(200).default(50),
+    /** When set, only snapshots that touched this module are returned. */
+    forModuleId: z.string().uuid().optional(),
+    /** When set, only snapshots that touched this page (metadata or layout). */
+    forPageId: z.string().uuid().optional(),
+    /** When set, only snapshots that touched this template (incl. block changes). */
+    forTemplateId: z.string().uuid().optional(),
+    /** When set, only snapshots whose op_kind matches one of these values. */
+    opKinds: z.array(z.string()).optional(),
+    /** When true, archived snapshots are also returned. Defaults to false. */
+    includeArchived: z.boolean().default(false),
+    /** v0.6.0 — only snapshots tagged with this chat's branch are returned.
+     * Used by `revert_chat_changes` to enumerate everything one chat did
+     * without scanning the full timeline. */
+    forChatBranchId: z.string().uuid().optional(),
+  })
+  .strict();
+
+export const archiveOlderThanInput = z
+  .object({
+    /** ISO timestamp; snapshots with `created_at < before` get archived_at set. */
+    before: z.string().datetime(),
+    /** Hard cap to keep one call from updating the whole table by mistake. */
+    limit: z.number().int().min(1).max(10_000).default(1000),
+  })
+  .strict();
+export type ArchiveOlderThanInput = z.infer<typeof archiveOlderThanInput>;
+
+export const snapshotGetInput = z.object({ snapshotId: z.string().uuid() }).strict();
+
+export const moduleImpactInput = z.object({ moduleId: z.string().uuid() }).strict();
+
+export const revertSiteInput = z.object({ snapshotId: z.string().uuid() }).strict();
+
+export const revertModuleInput = z
+  .object({
+    moduleId: z.string().uuid(),
+    snapshotId: z.string().uuid(),
+  })
+  .strict();
+
+export const revertTemplateInput = z
+  .object({
+    templateId: z.string().uuid(),
+    snapshotId: z.string().uuid(),
+  })
+  .strict();
+
+export const revertPageInput = z
+  .object({
+    pageId: z.string().uuid(),
+    snapshotId: z.string().uuid(),
+  })
+  .strict();
+
+export type SnapshotsListInput = z.infer<typeof snapshotsListInput>;
+export type SnapshotGetInput = z.infer<typeof snapshotGetInput>;
+export type ModuleImpactInput = z.infer<typeof moduleImpactInput>;
+export type RevertSiteInput = z.infer<typeof revertSiteInput>;
+export type RevertModuleInput = z.infer<typeof revertModuleInput>;
+export type RevertTemplateInput = z.infer<typeof revertTemplateInput>;
+export type RevertPageInput = z.infer<typeof revertPageInput>;

package/src/strip-cdata.test.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { stripCdataGuards } from "./strip-cdata.js";
+
+describe("stripCdataGuards", () => {
+  it("leaves clean HTML untouched (fast path)", () => {
+    const html = '<nav><a href="/docs">Docs</a></nav>';
+    expect(stripCdataGuards(html)).toBe(html);
+  });
+
+  it("removes a bare `<![CDATA[` / `]]>` pair, preserving inner content", () => {
+    const html = "<style><![CDATA[.a{color:red}]]></style>";
+    expect(stripCdataGuards(html)).toBe("<style>.a{color:red}</style>");
+  });
+
+  it("removes the stray `]]>` that leaks into chrome slots (the bug signature)", () => {
+    const html = "<header>Site name]]></header>";
+    expect(stripCdataGuards(html)).toBe("<header>Site name</header>");
+  });
+
+  it("unwraps the block-comment guard form", () => {
+    const html = "<script>/*<![CDATA[*/ doStuff(); /*]]>*/</script>";
+    expect(stripCdataGuards(html)).toBe("<script> doStuff(); </script>");
+  });
+
+  it("unwraps the line-comment guard form", () => {
+    const html = "<script>\n//<![CDATA[\n  doStuff();\n//]]>\n</script>";
+    expect(stripCdataGuards(html)).toBe("<script>\n\n  doStuff();\n\n</script>");
+  });
+
+  it("handles multiple guards in one document", () => {
+    const html = "<style><![CDATA[.a{}]]></style><script>//<![CDATA[\nx()\n//]]>\n</script>";
+    expect(stripCdataGuards(html)).toBe("<style>.a{}</style><script>\nx()\n\n</script>");
+  });
+
+  it("does not touch a legitimate `CDATA` substring in text", () => {
+    const html = "<p>The CDATA section in XML is explained here.</p>";
+    expect(stripCdataGuards(html)).toBe(html);
+  });
+});

package/src/strip-cdata.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * CDATA-guard normalization for module HTML.
+ *
+ * The AI sometimes authors chrome/layout module HTML with XHTML-style
+ * CDATA guards wrapping inline `<style>`/`<script>` content — e.g.
+ *
+ *   <script>
+ *   //<![CDATA[
+ *     doStuff();
+ *   //]]>
+ *   </script>
+ *
+ * or the block-comment / bare forms (`/*<![CDATA[* /`, `<![CDATA[`).
+ * These are legal in XHTML but MEANINGLESS in HTML5: the compose
+ * pipeline is byte-preserving by design (see `preview-scanner.ts`), so
+ * the guards survive verbatim into the rendered page. Chrome/layout
+ * modules render straight from their stored HTML (no content_instance
+ * indirection), so a bare `<![CDATA[` in the body is parsed by the
+ * browser as a bogus comment up to the first `>`, leaving a stray,
+ * visible `]]>` in the header/footer/nav.
+ *
+ * We normalize at the module-HTML write boundary (canonical) and again
+ * defensively at render, so both freshly-authored and already-stored
+ * modules stay clean. Only the DELIMITERS are removed — the wrapped
+ * CSS/JS/markup content is preserved.
+ *
+ * This is normalization of malformed authored markup, not a data
+ * fallback (CLAUDE.md §2): there is no "missing" data to point at, and
+ * the inner content is kept intact.
+ */
+
+/**
+ * Matches every CDATA-guard delimiter form the model emits. The
+ * comment-wrapped variants come first so they're consumed as a unit
+ * before the bare `<![CDATA[` / `]]>` alternatives can match a subset.
+ */
+const CDATA_GUARDS =
+  /\/\*\s*<!\[CDATA\[\s*\*\/|\/\*\s*\]\]>\s*\*\/|\/\/[ \t]*<!\[CDATA\[|\/\/[ \t]*\]\]>|<!\[CDATA\[|\]\]>/g;
+
+/**
+ * Strip XHTML-style CDATA-section guard delimiters from module HTML,
+ * preserving the content they wrapped. Returns the input unchanged when
+ * no guard is present (fast path for the overwhelming clean-HTML case).
+ */
+export function stripCdataGuards(html: string): string {
+  if (!html.includes("CDATA") && !html.includes("]]>")) return html;
+  return html.replace(CDATA_GUARDS, "");
+}

package/src/structured-sets.ts

@@ -0,0 +1,180 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * P6.7.5 — typed schemas for the `structured_sets` table.
+ *
+ * One database table holds N kinds of named lists (nav-menus, taxonomies,
+ * theme tokens, tag lists, footer link blocks, ...). The `kind`
+ * discriminator drives both the Zod validator at the Query API layer
+ * and the renderer that turns the items into HTML at preview / deploy.
+ *
+ * Adding a new kind: add a Zod schema below, add it to the
+ * `structuredSetItem` discriminated union, add a renderer in
+ * `packages/shared/src/structured-set-renderer.ts`. No DB migration
+ * required — the table already accepts arbitrary `kind` text.
+ *
+ * Item shapes are deliberately **structured data**, not HTML strings.
+ * That's what makes `change_page_slug` able to retarget every menu
+ * link automatically: walk the JSON, swap `href` matches.
+ */
+
+import { z } from "zod";
+
+/** Recursive nav menu — supports arbitrary submenu nesting. */
+export const navMenuItem: z.ZodType<{
+  label: string;
+  href: string;
+  target?: "_self" | "_blank";
+  children?: { label: string; href: string }[];
+  /** When set, the renderer delegates this slot to the named ad plugin. */
+  adSlotId?: string;
+}> = z.lazy(() =>
+  z
+    .object({
+      label: z.string().min(1).max(120),
+      href: z.string().min(1).max(500),
+      target: z.enum(["_self", "_blank"]).optional(),
+      children: z.array(navMenuItem).optional(),
+      adSlotId: z.string().min(1).max(100).optional(),
+    })
+    .strict(),
+);
+
+/** Tree-shaped category list. Used by typed-content / tag pages (P12A). */
+export const taxonomyItem = z
+  .object({
+    slug: z.string().min(1).max(120),
+    displayName: z.string().min(1).max(200),
+    parentSlug: z.string().min(1).max(120).optional(),
+    description: z.string().max(2000).optional(),
+  })
+  .strict();
+
+/** Flat tag — used by post taxonomies, content filtering. */
+export const tagItem = z
+  .object({
+    slug: z
+      .string()
+      .min(1)
+      .max(120)
+      .regex(/^[a-z0-9-]+$/, "lowercase letters/digits/hyphens"),
+    displayName: z.string().min(1).max(200),
+    color: z
+      .string()
+      .regex(/^#[0-9a-fA-F]{3,8}$/, "hex color")
+      .optional(),
+  })
+  .strict();
+
+/** Footer "legal" / related-resources block. */
+export const linkListItem = z
+  .object({
+    label: z.string().min(1).max(200),
+    href: z.string().min(1).max(500),
+    description: z.string().max(500).optional(),
+  })
+  .strict();
+
+/**
+ * P9 review-pass — `language-selector` kind. Items are user-supplied
+ * overrides (e.g. force a specific display label per locale); empty
+ * array means "auto-populate from the locale registry at render time."
+ * The renderer (apps/static-generator + preview op) reads the locale
+ * registry + the current page's slug + resolveLocaleUrl to emit
+ * `<a hreflang lang href>` rows. Closes CMS_REQUIREMENTS §7.8.
+ */
+export const languageSelectorOverride = z
+  .object({
+    /** BCP-47 locale code; must match a row in the locales registry. */
+    locale: z.string().min(2).max(10),
+    /** Override the locale's display_name when rendering this entry. */
+    label: z.string().min(1).max(120).optional(),
+    /** Hide this locale from the rendered selector even if it has a published page. */
+    hidden: z.boolean().optional(),
+  })
+  .strict();
+
+/** Discriminated kind → items array. The Query API op picks the
+ *  validator at runtime by reading `kind` first.
+ *
+ *  v0.11.0 (#45) — `theme` is no longer a structured-set kind. The
+ *  theme primitive moved to its own `themes` table with DTCG-shaped
+ *  jsonb tokens; see `themes.ts` + `theme-render.ts`. */
+export const structuredSetKind = z.enum([
+  "nav-menu",
+  "taxonomy",
+  "tags",
+  "link-list",
+  "language-selector",
+]);
+export type StructuredSetKind = z.infer<typeof structuredSetKind>;
+
+/** Validate `items` against the right schema for `kind`. Throws a
+ *  ZodError on mismatch — callers wrap and return `Err(ValidationFailed)`. */
+export function validateStructuredSetItems(kind: StructuredSetKind, items: unknown): unknown[] {
+  if (!Array.isArray(items)) {
+    throw new z.ZodError([
+      {
+        code: "custom",
+        path: ["items"],
+        message: "items must be an array",
+      },
+    ]);
+  }
+  switch (kind) {
+    case "nav-menu":
+      return items.map((it) => navMenuItem.parse(it));
+    case "taxonomy":
+      return items.map((it) => taxonomyItem.parse(it));
+    case "tags":
+      return items.map((it) => tagItem.parse(it));
+    case "link-list":
+      return items.map((it) => linkListItem.parse(it));
+    case "language-selector":
+      return items.map((it) => languageSelectorOverride.parse(it));
+  }
+}
+
+export type NavMenuItem = z.infer<typeof navMenuItem>;
+export type TaxonomyItem = z.infer<typeof taxonomyItem>;
+export type TagItem = z.infer<typeof tagItem>;
+export type LinkListItem = z.infer<typeof linkListItem>;
+export type LanguageSelectorOverride = z.infer<typeof languageSelectorOverride>;
+
+/**
+ * Render a `<nav class="caelo-language-selector">` with one `<a>`
+ * per locale that has a published variant of the current page. Pure
+ * function — caller threads the page's published-locale list and a
+ * URL resolver. Used by `composePagePreview` (admin) and the static
+ * generator (deploy) so byte-for-byte output parity holds.
+ *
+ * Per CMS_REQUIREMENTS §7.8: locales with no published variant for the
+ * current page are excluded.
+ */
+export function renderLanguageSelector(args: {
+  /** Each locale that has a published variant of the current page. */
+  readonly availableLocales: ReadonlyArray<{
+    code: string;
+    displayName: string;
+    href: string;
+    isCurrent: boolean;
+  }>;
+  /** Owner-supplied overrides (relabel a locale, hide one). */
+  readonly overrides?: ReadonlyArray<LanguageSelectorOverride>;
+}): string {
+  const overrideByLocale = new Map<string, LanguageSelectorOverride>(
+    (args.overrides ?? []).map((o) => [o.locale, o]),
+  );
+  const enc = (s: string): string =>
+    s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const items = args.availableLocales
+    .filter((l) => !overrideByLocale.get(l.code)?.hidden)
+    .map((l) => {
+      const override = overrideByLocale.get(l.code);
+      const label = override?.label ?? l.displayName;
+      const aria = l.isCurrent ? ' aria-current="true"' : "";
+      return `<a hreflang="${enc(l.code)}" lang="${enc(l.code)}" href="${enc(l.href)}"${aria}>${enc(label)}</a>`;
+    });
+  if (items.length === 0) return "";
+  return `<nav class="caelo-language-selector" aria-label="Language">${items.join("")}</nav>`;
+}

package/src/subagents.test.ts

@@ -0,0 +1,262 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { parseSubagentResult, subagentSpec, validateSubagentResultValue } from "./subagents.js";
+
+describe("subagentSpec", () => {
+  it("accepts a minimal spec with role + task", () => {
+    const r = subagentSpec.safeParse({ role: "qa", task: "QA the page" });
+    expect(r.success).toBe(true);
+    if (!r.success) return;
+    expect(r.data.expectedReturnShape).toBe("verdict");
+    // issue #304 — no schema default: an omitted cap means "derive from
+    // the armed run budget" in the spawn orchestrator, and a default
+    // here (the old 50M µ¢) would make omission indistinguishable from
+    // an explicit choice.
+    expect(r.data.maxCostMicrocents).toBeUndefined();
+    // Default 300s — build children (Genesis draft, migration rebuild) need
+    // minutes; the old 60s aborted them mid-work (0 drafts saved).
+    expect(r.data.timeoutMs).toBe(300_000);
+  });
+
+  it("rejects empty role + task", () => {
+    expect(subagentSpec.safeParse({ role: "", task: "x" }).success).toBe(false);
+    expect(subagentSpec.safeParse({ role: "x", task: "" }).success).toBe(false);
+  });
+
+  it("rejects unknown fields (.strict)", () => {
+    expect(subagentSpec.safeParse({ role: "x", task: "y", randomField: "z" }).success).toBe(false);
+  });
+});
+
+describe("validateSubagentResultValue — double-encoded payload (submit_result bug)", () => {
+  // Bug: a provider double-encodes the verdict as a JSON STRING
+  // (`{"result":"{\"pass\":true,...}"}`); with `result` untyped in the
+  // submit_result inputSchema the encoding-repair layer couldn't decode
+  // it, so a well-formed verdict reached the validator as a string and
+  // was rejected as "string (scalar)". The validator now decodes a
+  // JSON-looking string for structured shapes as defense-in-depth.
+  it("verdict — accepts a JSON-string-encoded object", () => {
+    const encoded = JSON.stringify({ pass: true, issues: [], suggestions: ["add CTA"] });
+    const r = validateSubagentResultValue(encoded, "verdict");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.shape).toBe("verdict");
+    expect(r.value.pass).toBe(true);
+    expect(r.value.suggestions).toEqual(["add CTA"]);
+  });
+
+  it("verdict — still accepts a real object (unchanged path)", () => {
+    const r = validateSubagentResultValue({ pass: false, issues: ["x"] }, "verdict");
+    expect(r.ok).toBe(true);
+  });
+
+  it("rebuild — accepts a JSON-string-encoded object", () => {
+    const encoded = JSON.stringify({ pages: [{ slug: "/home", status: "rebuilt" }] });
+    const r = validateSubagentResultValue(encoded, "rebuild");
+    expect(r.ok).toBe(true);
+  });
+
+  it("verdict — a genuine non-JSON string still fails with the scalar hint", () => {
+    const r = validateSubagentResultValue("looks good to me", "verdict");
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toContain("scalar");
+  });
+
+  it("freeform — a bare prose string is NOT treated as JSON", () => {
+    const r = validateSubagentResultValue("plain prose", "freeform");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.text).toBe("plain prose");
+  });
+});
+
+describe("parseSubagentResult — verdict", () => {
+  it("extracts JSON from a code fence", () => {
+    const text = `\`\`\`json\n${JSON.stringify({ pass: true, issues: [], suggestions: ["add CTA"] })}\n\`\`\``;
+    const r = parseSubagentResult(text, "verdict");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.shape).toBe("verdict");
+    expect(r.value.pass).toBe(true);
+    expect(r.value.suggestions).toEqual(["add CTA"]);
+  });
+
+  it("extracts JSON from prose-wrapped output", () => {
+    const text =
+      'Here is my verdict:\n{"pass": false, "issues": ["missing disclaimer"], "suggestions": []}\nHope that helps.';
+    const r = parseSubagentResult(text, "verdict");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.pass).toBe(false);
+    expect(r.value.issues).toEqual(["missing disclaimer"]);
+  });
+
+  it("returns error on shape mismatch", () => {
+    const text = JSON.stringify({ pass: "yes", issues: [] });
+    const r = parseSubagentResult(text, "verdict");
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toContain("pass");
+  });
+
+  it("returns error on non-JSON garbage", () => {
+    const r = parseSubagentResult("not json at all", "verdict");
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe("parseSubagentResult — tree", () => {
+  it("validates tree shape", () => {
+    const text = JSON.stringify({
+      tree: [{ label: "Root", children: [] }],
+      rationale: "minimal",
+    });
+    const r = parseSubagentResult(text, "tree");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.shape).toBe("tree");
+  });
+});
+
+describe("parseSubagentResult — rebuild (issue #264)", () => {
+  it("validates a full migration-batch summary", () => {
+    const text = JSON.stringify({
+      pages: [
+        {
+          pageId: "11111111-1111-4111-8111-222222222222",
+          slug: "pricing",
+          status: "rebuilt",
+          notes: "table modernised; footnote folded into caption",
+        },
+        { slug: "pricing-archive", status: "skipped", notes: "operator marked obsolete" },
+      ],
+      contentNotes: ["source hero carried a rotating quote widget; kept the first quote only"],
+      skipped: [{ item: "legacy price calculator embed", reason: "third-party script, no data" }],
+      summary: "2-page batch: 1 rebuilt, 1 skipped.",
+    });
+    const r = parseSubagentResult(text, "rebuild");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.shape).toBe("rebuild");
+    if (r.shape !== "rebuild") return;
+    expect(r.value.pages).toHaveLength(2);
+    expect(r.value.pages[0]?.status).toBe("rebuilt");
+    expect(r.value.skipped[0]?.reason).toContain("third-party");
+  });
+
+  it("defaults contentNotes/skipped/summary when omitted", () => {
+    const text = `\`\`\`json\n${JSON.stringify({ pages: [{ slug: "home", status: "rebuilt" }] })}\n\`\`\``;
+    const r = parseSubagentResult(text, "rebuild");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    if (r.shape !== "rebuild") return;
+    expect(r.value.contentNotes).toEqual([]);
+    expect(r.value.skipped).toEqual([]);
+    expect(r.value.summary).toBe("");
+  });
+
+  it("rejects an empty pages array — a rebuild subagent must account for its batch", () => {
+    const r = parseSubagentResult(JSON.stringify({ pages: [] }), "rebuild");
+    expect(r.ok).toBe(false);
+  });
+
+  it("names the expected shape + observed keys on mismatch", () => {
+    const r = parseSubagentResult(JSON.stringify({ pass: true, issues: [] }), "rebuild");
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error).toContain("rebuild shape mismatch");
+    expect(r.error).toContain("pass");
+  });
+
+  it("rejects an out-of-enum page status", () => {
+    const r = parseSubagentResult(
+      JSON.stringify({ pages: [{ slug: "home", status: "done" }] }),
+      "rebuild",
+    );
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe("subagentSpec — rebuild shape accepted", () => {
+  it("accepts expectedReturnShape rebuild with migration-scale caps", () => {
+    const r = subagentSpec.safeParse({
+      role: "rebuild:blog",
+      task: "REBUILD TASK — rebuild the blog cluster",
+      expectedReturnShape: "rebuild",
+      timeoutMs: 600_000,
+      maxCostMicrocents: 100_000_000,
+    });
+    expect(r.success).toBe(true);
+    if (!r.success) return;
+    expect(r.data.expectedReturnShape).toBe("rebuild");
+  });
+});
+
+describe("parseSubagentResult — freeform", () => {
+  it("accepts {text: ...} JSON", () => {
+    const r = parseSubagentResult(JSON.stringify({ text: "summary here" }), "freeform");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.text).toBe("summary here");
+  });
+
+  it("falls back to raw text when JSON parse fails", () => {
+    const r = parseSubagentResult("plain text response from the subagent.", "freeform");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.value.text).toBe("plain text response from the subagent.");
+  });
+
+  it("returns error on empty text", () => {
+    expect(parseSubagentResult("   ", "freeform").ok).toBe(false);
+  });
+});
+
+describe("subagentSpec — model tier (issue #306)", () => {
+  it("defaults tier to inherit (single-model behaviour unchanged when omitted)", () => {
+    const r = subagentSpec.safeParse({ role: "qa", task: "QA the page" });
+    expect(r.success).toBe(true);
+    if (!r.success) return;
+    expect(r.data.tier).toBe("inherit");
+  });
+
+  it("accepts mid and small, rejects unknown tiers", () => {
+    for (const tier of ["mid", "small", "inherit"]) {
+      expect(subagentSpec.safeParse({ role: "x", task: "y", tier }).success).toBe(true);
+    }
+    expect(subagentSpec.safeParse({ role: "x", task: "y", tier: "large" }).success).toBe(false);
+  });
+});
+
+describe("parseSubagentResult — needs_escalation (issue #306)", () => {
+  it("accepts a needs_escalation page WITH a reason in notes", () => {
+    const r = parseSubagentResult(
+      JSON.stringify({
+        pages: [
+          { slug: "home", status: "rebuilt" },
+          { slug: "pricing", status: "needs_escalation", notes: "no matching table module" },
+        ],
+      }),
+      "rebuild",
+    );
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    if (r.shape !== "rebuild") return;
+    expect(r.value.pages[1]?.status).toBe("needs_escalation");
+    expect(r.value.pages[1]?.notes).toBe("no matching table module");
+  });
+
+  it("REJECTS needs_escalation without notes — a blind escalation cannot be briefed", () => {
+    for (const notes of [undefined, "", "   "]) {
+      const r = parseSubagentResult(
+        JSON.stringify({ pages: [{ slug: "pricing", status: "needs_escalation", notes }] }),
+        "rebuild",
+      );
+      expect(r.ok).toBe(false);
+      if (r.ok) continue;
+      expect(r.error).toContain("needs_escalation");
+    }
+  });
+});