@desplega.ai/agent-swarm 2.7.5 → 2.7.7

package/src/be/seed-scripts/catalog/swarm-update-check.ts

@@ -0,0 +1,150 @@
+import { z } from "zod";
+
+export const argsSchema = z.object({
+  dryRun: z
+    .boolean()
+    .optional()
+    .describe("Compute the verdict but do not notify the lead when an update is available"),
+});
+
+const RELEASES_URL = "https://api.github.com/repos/desplega-ai/agent-swarm/releases/latest";
+
+/** Parse `major.minor.patch` (a leading `v` and a pre-release/build suffix are ignored). */
+export function parseVersion(value: unknown): [number, number, number] | null {
+  if (typeof value !== "string") return null;
+  const m = value
+    .trim()
+    .replace(/^v/i, "")
+    .match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/** Numeric compare of two parsed versions: negative, zero or positive. Never a string compare. */
+export function compareVersions(a: [number, number, number], b: [number, number, number]): number {
+  for (let i = 0; i < 3; i++) {
+    const diff = (a[i] as number) - (b[i] as number);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function errorText(error: unknown): string {
+  return String((error as any)?.message ?? error).slice(0, 200);
+}
+
+/** The version the API server is running, from its own unauthenticated `/health` route. */
+async function runningVersion(ctx: any): Promise<string | null> {
+  try {
+    const base = ctx.stdlib.Redacted.value(ctx.swarm.config.mcpBaseUrl).replace(/\/+$/, "");
+    const res: any = await ctx.stdlib.fetch(base + "/health", { retries: 1, timeoutMs: 10_000 });
+    if (!res.ok) return null;
+    const body: any = await res.json();
+    return typeof body?.version === "string" && body.version.trim() ? body.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function resolveLeadId(ctx: any): Promise<string | null> {
+  const res: any = await ctx.swarm.swarm_get({});
+  const data = res?.data ?? res;
+  const agents: any[] = Array.isArray(data?.agents) ? data.agents : Array.isArray(data) ? data : [];
+  const lead = agents.find((agent) => agent?.isLead === true || agent?.isLead === 1);
+  return typeof lead?.id === "string" ? lead.id : null;
+}
+
+/**
+ * Compare the running agent-swarm version with the latest published GitHub
+ * release and, only when a newer release exists, hand the lead one task to
+ * tell the operator through its admin delivery channel.
+ */
+export default async function swarmUpdateCheck(args: any, ctx: any) {
+  const parsed = argsSchema.safeParse(args ?? {});
+  if (!parsed.success) return { error: "invalid args: " + parsed.error.message };
+  const dryRun = parsed.data.dryRun === true;
+
+  const running = await runningVersion(ctx);
+  const runningParsed = parseVersion(running);
+  if (!running || !runningParsed) {
+    // Unknown is not "up to date": say so and stop, never guess a version.
+    return {
+      checked: false,
+      status: "unknown",
+      running,
+      message: `Unable to determine running version: ${running ? `unparseable "${running}"` : "not reported by /health"}.`,
+    };
+  }
+
+  let release: any;
+  try {
+    // One attempt: a failed GitHub call is reported, never retried in a loop.
+    const res: any = await ctx.stdlib.fetch(RELEASES_URL, {
+      retries: 1,
+      timeoutMs: 15_000,
+      headers: { Accept: "application/vnd.github+json", "User-Agent": "agent-swarm-update-check" },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    release = await res.json();
+  } catch (error) {
+    return {
+      checked: false,
+      status: "github-unreachable",
+      running,
+      message: `Could not reach GitHub releases API: ${errorText(error)}`,
+    };
+  }
+
+  const latest = typeof release?.tag_name === "string" ? release.tag_name.replace(/^v/i, "") : null;
+  const latestParsed = parseVersion(latest);
+  if (!latest || !latestParsed) {
+    return {
+      checked: false,
+      status: "github-unreachable",
+      running,
+      message: `Could not read a version from the latest release tag: ${JSON.stringify(release?.tag_name ?? null)}.`,
+    };
+  }
+  const releaseUrl =
+    typeof release?.html_url === "string"
+      ? release.html_url
+      : `https://github.com/desplega-ai/agent-swarm/releases/tag/v${latest}`;
+
+  if (compareVersions(latestParsed, runningParsed) <= 0) {
+    return {
+      checked: true,
+      status: "up-to-date",
+      running,
+      latest,
+      message: `Up to date: running ${running}, latest published ${latest}.`,
+    };
+  }
+
+  const message = `Update available: running ${running}, latest ${latest} (${releaseUrl})`;
+  if (dryRun) {
+    return { checked: true, status: "update-available", running, latest, releaseUrl, notified: false, message };
+  }
+
+  const leadId = await resolveLeadId(ctx);
+  // A detected update that reaches nobody is a failed run, not a quiet success.
+  if (!leadId) throw new Error(`${message}, but the swarm has no lead to notify.`);
+  const sent: any = await ctx.swarm.task_send({
+    agentId: leadId,
+    routingReason: "skill",
+    routingNote: "Lead owns the operator's admin delivery channel for release notices.",
+    tags: ["swarm-update-check"],
+    task: [
+      `A newer agent-swarm release is published: running ${running}, latest ${latest}.`,
+      `Release: ${releaseUrl}`,
+      "",
+      "Post one short message to your configured admin delivery channel (the in-app fallback if none is configured) naming the running version, the new version and the release URL. Then complete with that message as the output.",
+      "Do not attempt the upgrade yourself: this notice only detects and reports.",
+    ].join("\n"),
+  });
+  const taskId = sent?.data?.task?.id ?? null;
+  if (sent?.success === false || sent?.data?.success === false || !taskId) {
+    const reason = sent?.data?.message ?? sent?.data?.error ?? `status ${sent?.status}`;
+    throw new Error(`${message}, but notifying the lead failed: ${errorText(reason)}`);
+  }
+  return { checked: true, status: "update-available", running, latest, releaseUrl, notified: true, leadTaskId: taskId, message };
+}

package/src/be/seed-scripts/catalog/task-failure-audit.ts

@@ -30,7 +30,11 @@ const REASON_PATTERNS: any[] = [
   { key: "context-window", re: /context (window|limit|saturat)|peakcontext|compact/i },
   { key: "reboot-sweep", re: /reboot sweep/i },
   { key: "not-found", re: /not found|404|missing|no such/i },
-  { key: "auth/credentials", re: /unauthorized|401|403|credential|token|forbidden/i },
+  {
+    key: "output-limit",
+    re: /\bmax_(?:output_)?tokens\b|\b(?:maximum|max) output (?:length|tokens)\b|\boutput (?:token|length) limit\b/i,
+  },
+  { key: "auth/credentials", re: /unauthorized|401|403|credential|\btoken\b|forbidden/i },
   { key: "ci/checks-failed", re: /\bci\b|check.?s? fail|lint|tsc|test.?s? fail/i },
   { key: "network", re: /network|econn|fetch failed|socket|dns|502|503|504/i },
   { key: "cancelled", re: /cancel|aborted/i },

package/src/be/seed-scripts/index.ts

@@ -60,6 +60,7 @@ import starHistoryRefreshSrc from "./catalog/star-history-refresh.ts" with { typ
 // @ts-expect-error Bun text imports synthesize a default string for this helper.
 import starHistoryRendererSrc from "./catalog/star-history-renderer.ts" with { type: "text" };
 import swarmOverviewSrc from "./catalog/swarm-overview.ts" with { type: "text" };
+import swarmUpdateCheckSrc from "./catalog/swarm-update-check.ts" with { type: "text" };
 import taskContextGatheringSrc from "./catalog/task-context-gathering.ts" with { type: "text" };
 import taskFailureAuditSrc from "./catalog/task-failure-audit.ts" with { type: "text" };
 import textDiffSrc from "./catalog/text-diff.ts" with { type: "text" };
@@ -217,6 +218,14 @@ export const SEED_SCRIPTS: SeedScript[] = [
       "Task onboarding: one call instead of task_get plus multiple memory_search calls. Pass the task description split into 2-4 natural-language queries.",
     source: asText(taskContextGatheringSrc),
   },
+  {
+    name: "swarm-update-check",
+    description:
+      "Compare the running agent-swarm version (API /health) with the latest GitHub release of desplega-ai/agent-swarm as numeric major.minor.patch, and hand the lead one notify task only when a newer release exists.",
+    intent:
+      "Daily zero-config upgrade watchdog behind the daily-swarm-update-check schedule; dryRun reports the verdict without notifying.",
+    source: asText(swarmUpdateCheckSrc),
+  },
   {
     name: "schedule-health",
     description:

package/src/be/seed-skills/bundled-files.generated.json

@@ -36,15 +36,15 @@
   "pages": [
     {
       "path": "examples/annotated-pr.html",
-      "content": "<!doctype html>\n<!--\n  Annotated-PR page using the auto-injected <swarm-diff> web component.\n\n  No <script> import and no bundling: <swarm-diff>, <swarm-diff-jumps> and\n  window.swarmUi.renderDiff are injected into every HTML page automatically.\n  Each hunk gets id=\"swarm-diff-<file-slug>-<old_start>\" so <swarm-diff-jumps>\n  can build the jump list and external links can deep-link a specific hunk.\n-->\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <title>PR #1234 — console.log cleanup</title>\n</head>\n<body>\n  <h1>PR #1234 — cleanup raw <code>console.log</code> calls</h1>\n  <p>Replaces ad-hoc logging with the project logger.</p>\n\n  <swarm-diff-jumps></swarm-diff-jumps>\n\n  <swarm-diff file=\"src/foo.ts\" base-sha=\"abc123\" head-sha=\"def456\">\n    { \"hunks\": [\n        { \"old_start\": 10, \"old_lines\": 3, \"new_start\": 10, \"new_lines\": 4,\n          \"lines\": [\n            { \"type\": \"context\", \"text\": \"  const x = 1;\" },\n            { \"type\": \"del\",     \"text\": \"- console.log(x);\" },\n            { \"type\": \"add\",     \"text\": \"+ logger.info({ x });\" },\n            { \"type\": \"add\",     \"text\": \"+ return x;\" }\n          ],\n          \"annotations\": [\n            { \"line\": 12, \"severity\": \"warn\", \"text\": \"Avoid raw console.log\" }\n          ]\n        }\n    ] }\n  </swarm-diff>\n\n  <swarm-diff file=\"src/bar.ts\" base-sha=\"abc123\" head-sha=\"def456\">\n    { \"hunks\": [\n        { \"old_start\": 5, \"old_lines\": 1, \"new_start\": 5, \"new_lines\": 1,\n          \"lines\": [\n            { \"type\": \"del\", \"text\": \"- console.error('boom');\" },\n            { \"type\": \"add\", \"text\": \"+ logger.error('boom');\" }\n          ]\n        }\n    ] }\n  </swarm-diff>\n</body>\n</html>\n"
+      "content": "<!doctype html>\n<!--\n  Annotated-PR page using the auto-injected <swarm-diff> web component.\n\n  No <script> import and no bundling: <swarm-diff>, <swarm-diff-jumps> and\n  window.swarmUi.renderDiff are injected into every HTML page automatically.\n\n  Each \"text\" is the code line WITHOUT its +, - or space marker: the\n  component draws the marker in its own column. old_lines counts the context\n  and deleted lines, and new_lines counts the context and added lines. Inside\n  the JSON, write < as \\u003c and & as \\u0026.\n\n  Each hunk gets id=\"swarm-diff-<slug>\". The slug is <file>-<old_start> in\n  lowercase, with each run of characters other than a-z and 0-9 changed to\n  one \"-\". So src/foo.ts at old_start 10 gets id=\"swarm-diff-src-foo-ts-10\".\n  <swarm-diff-jumps> builds its jump list from these ids, and external links\n  can deep-link a specific hunk.\n-->\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <title>PR #1234: console.log cleanup</title>\n</head>\n<body>\n  <h1>PR #1234: cleanup raw <code>console.log</code> calls</h1>\n  <p>Replaces ad-hoc logging with the project logger.</p>\n\n  <swarm-diff-jumps></swarm-diff-jumps>\n\n  <swarm-diff file=\"src/foo.ts\" base-sha=\"abc123\" head-sha=\"def456\">\n    { \"hunks\": [\n        { \"old_start\": 10, \"old_lines\": 2, \"new_start\": 10, \"new_lines\": 3,\n          \"lines\": [\n            { \"type\": \"context\", \"text\": \"export function load(id) {\" },\n            { \"type\": \"del\",     \"text\": \"  console.log(id);\" },\n            { \"type\": \"add\",     \"text\": \"  logger.info({ id });\" },\n            { \"type\": \"add\",     \"text\": \"  return cache.get(id);\" }\n          ],\n          \"annotations\": [\n            { \"line\": 12, \"severity\": \"warn\", \"text\": \"Returns undefined on a cache miss\" }\n          ]\n        }\n    ] }\n  </swarm-diff>\n\n  <swarm-diff file=\"src/bar.ts\" base-sha=\"abc123\" head-sha=\"def456\">\n    { \"hunks\": [\n        { \"old_start\": 5, \"old_lines\": 1, \"new_start\": 5, \"new_lines\": 1,\n          \"lines\": [\n            { \"type\": \"del\", \"text\": \"console.error('boom');\" },\n            { \"type\": \"add\", \"text\": \"logger.error('boom');\" }\n          ]\n        }\n    ] }\n  </swarm-diff>\n</body>\n</html>\n"
     },
     {
       "path": "examples/multiplayer-board.html",
-      "content": "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <title>Shared board</title>\n    <style>\n      :root {\n        color: #252522;\n        background: #f7f6f3;\n        font-family: \"SF Pro Display\", \"Helvetica Neue\", ui-sans-serif, system-ui, sans-serif;\n        font-synthesis: none;\n      }\n\n      * { box-sizing: border-box; }\n\n      body {\n        margin: 0;\n        min-width: 320px;\n        padding: 0;\n        background: #f7f6f3;\n        color: #252522;\n        font-family: \"SF Pro Display\", \"Helvetica Neue\", ui-sans-serif, system-ui, sans-serif;\n      }\n\n      button, input, textarea { font: inherit; }\n\n      button {\n        border: 1px solid #252522;\n        border-radius: 8px;\n        background: #252522;\n        color: #fff;\n        cursor: pointer;\n        padding: 10px 14px;\n      }\n\n      button:hover { background: #3c3c37; }\n      button:focus-visible, input:focus-visible, textarea:focus-visible { outline: 3px solid #e1a52c; outline-offset: 2px; }\n      button:disabled { cursor: not-allowed; opacity: .5; }\n\n      .page { max-width: 1120px; margin: 0 auto; padding: 32px 24px 56px; }\n\n      header {\n        display: flex;\n        align-items: flex-start;\n        justify-content: space-between;\n        gap: 24px;\n        border-bottom: 1px solid #d9d7d0;\n        padding-bottom: 24px;\n      }\n\n      h1, h2, p { margin-top: 0; }\n      h1 { font-size: clamp(2rem, 5vw, 3rem); letter-spacing: -.04em; margin-bottom: 8px; }\n      h2 { font-size: 1.15rem; letter-spacing: -.02em; margin-bottom: 16px; }\n      .lede, .muted { color: #67665f; }\n      .lede { max-width: 46rem; margin-bottom: 0; }\n\n      .viewer {\n        min-width: 170px;\n        border: 1px solid #d9d7d0;\n        border-radius: 8px;\n        background: #fff;\n        padding: 12px;\n      }\n\n      .eyebrow {\n        color: #67665f;\n        display: block;\n        font-size: .72rem;\n        font-weight: 700;\n        letter-spacing: .08em;\n        margin-bottom: 4px;\n        text-transform: uppercase;\n      }\n\n      .viewer-name { font-weight: 700; overflow-wrap: anywhere; }\n\n      .notice {\n        border: 1px solid #d9d7d0;\n        border-left: 4px solid #e1a52c;\n        border-radius: 8px;\n        background: #fffdf8;\n        margin: 24px 0;\n        min-height: 47px;\n        padding: 12px 14px;\n      }\n\n      .notice[data-tone=\"error\"] { border-left-color: #a34736; background: #fff9f7; }\n      .notice[data-tone=\"stale\"] { border-left-color: #e1a52c; background: #fffdf8; }\n      .notice:empty { display: none; }\n\n      .grid { display: grid; gap: 24px; grid-template-columns: minmax(0, 1.65fr) minmax(260px, .85fr); }\n      .panel { border: 1px solid #d9d7d0; border-radius: 12px; background: #fff; padding: 20px; }\n      .panel + .panel { margin-top: 24px; }\n\n      .add-row { display: grid; gap: 8px; grid-template-columns: minmax(0, 1fr) auto; margin-bottom: 16px; }\n      input, textarea {\n        border: 1px solid #bdbbb4;\n        border-radius: 8px;\n        background: #fff;\n        color: inherit;\n        padding: 10px 12px;\n        width: 100%;\n      }\n\n      textarea { min-height: 94px; resize: vertical; }\n      label { display: block; font-size: .88rem; font-weight: 650; margin-bottom: 8px; }\n\n      .cards, .peers { list-style: none; margin: 0; padding: 0; }\n      .cards { border-top: 1px solid #e7e5df; }\n      .card {\n        align-items: center;\n        border-bottom: 1px solid #e7e5df;\n        display: flex;\n        gap: 12px;\n        justify-content: space-between;\n        padding: 13px 0;\n      }\n\n      .card-title { font-weight: 650; overflow-wrap: anywhere; }\n      .card-status {\n        background: #fff;\n        border-color: #bdbbb4;\n        color: #252522;\n        flex: 0 0 auto;\n        font-size: .82rem;\n        padding: 7px 10px;\n      }\n\n      .card-status[data-done=\"true\"] { background: #f6efd9; border-color: #c89429; }\n      .empty { color: #67665f; padding: 16px 0 4px; }\n      .agent-note { background: #f7f6f3; border-radius: 8px; min-height: 46px; padding: 12px; white-space: pre-wrap; overflow-wrap: anywhere; }\n      .agent-note:empty::before { color: #67665f; content: \"No note yet. A server-side agent can write one here.\"; }\n\n      .peers { display: grid; gap: 8px; }\n      .peer {\n        border: 1px solid #e7e5df;\n        border-radius: 8px;\n        display: grid;\n        gap: 3px;\n        padding: 10px;\n      }\n\n      .peer-name { font-weight: 650; overflow-wrap: anywhere; }\n      .room-meta { color: #67665f; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .75rem; margin: 0 0 16px; }\n      .save-state { color: #67665f; font-size: .82rem; margin: 8px 0 0; min-height: 1.2em; }\n\n      @media (max-width: 720px) {\n        .page { padding: 24px 16px 40px; }\n        header { align-items: stretch; flex-direction: column; }\n        .viewer { min-width: 0; }\n        .grid { grid-template-columns: 1fr; }\n        .add-row { grid-template-columns: 1fr; }\n      }\n    </style>\n  </head>\n  <body>\n    <swarm-cursors room=\"match-42\"></swarm-cursors>\n    <main class=\"page\">\n      <header>\n        <div>\n          <h1>Shared board</h1>\n          <p class=\"lede\">A small board shared by everyone in match-42. Changes appear as peers make them.</p>\n        </div>\n        <section class=\"viewer\" aria-label=\"Current viewer\">\n          <span class=\"eyebrow\">Connected as</span>\n          <div class=\"viewer-name\" id=\"viewer-name\">Connecting…</div>\n        </section>\n      </header>\n\n      <div id=\"notice\" class=\"notice\" role=\"status\" aria-live=\"polite\"></div>\n\n      <div class=\"grid\">\n        <section class=\"panel\" aria-labelledby=\"board-heading\">\n          <h2 id=\"board-heading\">Match board</h2>\n          <p class=\"room-meta\">Room: match-42 · Schema: 1</p>\n          <form id=\"add-card-form\" class=\"add-row\">\n            <label for=\"card-title\" class=\"sr-only\" hidden>New card title</label>\n            <input id=\"card-title\" name=\"title\" maxlength=\"120\" placeholder=\"Write a card title\" required>\n            <button type=\"submit\">Add card</button>\n          </form>\n          <ul id=\"cards\" class=\"cards\" aria-live=\"polite\"></ul>\n        </section>\n\n        <aside>\n          <section class=\"panel\" aria-labelledby=\"peers-heading\">\n            <h2 id=\"peers-heading\">Live peers</h2>\n            <p class=\"muted\">Pointers use document-normalized coordinates and line up across viewports.</p>\n            <ul id=\"peers\" class=\"peers\" aria-live=\"polite\"></ul>\n          </section>\n\n          <section class=\"panel\" aria-labelledby=\"agent-note-heading\">\n            <h2 id=\"agent-note-heading\">Agent note</h2>\n            <div id=\"agent-note\" class=\"agent-note\" aria-live=\"polite\"></div>\n          </section>\n        </aside>\n      </div>\n\n      <section class=\"panel\" aria-labelledby=\"lobby-heading\">\n        <h2 id=\"lobby-heading\">Lobby</h2>\n        <p class=\"room-meta\">Room: lobby · Schema: 1</p>\n        <form id=\"lobby-form\">\n          <label for=\"lobby-message\">Shared lobby message</label>\n          <textarea id=\"lobby-message\" maxlength=\"1000\" placeholder=\"Leave a message for everyone in the lobby\"></textarea>\n          <button type=\"submit\">Save lobby message</button>\n          <p id=\"lobby-save-state\" class=\"save-state\" aria-live=\"polite\"></p>\n        </form>\n      </section>\n    </main>\n\n    <script>\n      (() => {\n        const ui = {\n          viewerName: document.querySelector('#viewer-name'),\n          notice: document.querySelector('#notice'),\n          cards: document.querySelector('#cards'),\n          peers: document.querySelector('#peers'),\n          agentNote: document.querySelector('#agent-note'),\n          addCardForm: document.querySelector('#add-card-form'),\n          cardTitle: document.querySelector('#card-title'),\n          lobbyForm: document.querySelector('#lobby-form'),\n          lobbyMessage: document.querySelector('#lobby-message'),\n          lobbySaveState: document.querySelector('#lobby-save-state')\n        };\n\n        let board;\n        let lobby;\n        let peers = [];\n        let lobbyDirty = false;\n\n        function message(error) {\n          return error && error.message ? error.message : String(error);\n        }\n\n        function showNotice(text, tone) {\n          ui.notice.textContent = text || '';\n          ui.notice.dataset.tone = tone || '';\n        }\n\n        function markStale(room, roomName) {\n          if (!room.stale) return false;\n          showNotice(`${roomName} uses a different schema version. Its saved state remains visible, but this page cannot write changes.`, 'stale');\n          return true;\n        }\n\n        function renderBoard(state) {\n          const cards = state && state.cards && typeof state.cards === 'object' ? state.cards : {};\n          ui.cards.replaceChildren();\n          const entries = Object.entries(cards);\n\n          if (!entries.length) {\n            const empty = document.createElement('li');\n            empty.className = 'empty';\n            empty.textContent = 'No cards yet. Add the first card.';\n            ui.cards.append(empty);\n          }\n\n          for (const [id, card] of entries) {\n            const item = document.createElement('li');\n            item.className = 'card';\n            const title = document.createElement('span');\n            title.className = 'card-title';\n            title.textContent = card && typeof card.title === 'string' ? card.title : 'Untitled card';\n            const toggle = document.createElement('button');\n            const done = Boolean(card && card.done);\n            toggle.className = 'card-status';\n            toggle.dataset.done = String(done);\n            toggle.type = 'button';\n            toggle.textContent = done ? 'Done' : 'Open';\n            toggle.setAttribute('aria-label', `Mark ${title.textContent} as ${done ? 'open' : 'done'}`);\n            toggle.addEventListener('click', () => toggleCard(id));\n            item.append(title, toggle);\n            ui.cards.append(item);\n          }\n\n          ui.agentNote.textContent = state && typeof state.agentNote === 'string' ? state.agentNote : '';\n        }\n\n        function renderPeers(nextPeers) {\n          peers = Array.isArray(nextPeers) ? nextPeers : [];\n          ui.peers.replaceChildren();\n\n          if (!peers.length) {\n            const empty = document.createElement('li');\n            empty.className = 'empty';\n            empty.textContent = 'No other peers are connected.';\n            ui.peers.append(empty);\n            return;\n          }\n\n          for (const peer of peers) {\n            const item = document.createElement('li');\n            item.className = 'peer';\n            const name = document.createElement('span');\n            name.className = 'peer-name';\n            name.textContent = peer.name || 'Guest';\n            item.append(name);\n            ui.peers.append(item);\n          }\n        }\n\n        function renderLobby(state) {\n          if (lobbyDirty) return;\n          ui.lobbyMessage.value = state && typeof state.message === 'string' ? state.message : '';\n        }\n\n        async function addCard(title) {\n          if (markStale(board, 'match-42')) return;\n          try {\n            await board.change(state => {\n              state.cards ??= {};\n              state.cards[crypto.randomUUID()] = { title, done: false };\n            });\n            ui.cardTitle.value = '';\n            showNotice('Card added.', 'success');\n          } catch (error) {\n            showNotice(`Could not add the card: ${message(error)}`, 'error');\n          }\n        }\n\n        async function toggleCard(id) {\n          if (markStale(board, 'match-42')) return;\n          try {\n            await board.change(state => {\n              const card = state.cards && state.cards[id];\n              if (card) card.done = !card.done;\n            });\n          } catch (error) {\n            showNotice(`Could not update the card: ${message(error)}`, 'error');\n          }\n        }\n\n        async function saveLobbyMessage() {\n          if (markStale(lobby, 'lobby')) return;\n          try {\n            const value = ui.lobbyMessage.value;\n            await lobby.change(state => {\n              state.message = value;\n            });\n            lobbyDirty = false;\n            ui.lobbySaveState.textContent = 'Saved to the lobby room.';\n          } catch (error) {\n            ui.lobbySaveState.textContent = `Could not save: ${message(error)}`;\n            showNotice(`Could not save the lobby message: ${message(error)}`, 'error');\n          }\n        }\n\n        async function initialize() {\n          try {\n            board = await window.swarmSdk.room('match-42', { schemaVersion: 1 });\n            lobby = await window.swarmSdk.room('lobby', { schemaVersion: 1 });\n\n            const viewer = board.me || lobby.me || {};\n            ui.viewerName.textContent = viewer.name || 'Guest';\n\n            board.on('change', renderBoard);\n            board.on('presence', renderPeers);\n            board.on('error', error => showNotice(`match-42 error: ${message(error)}`, 'error'));\n            board.on('reset', () => showNotice('match-42 was reset by another participant. The board has resynchronized.', 'stale'));\n            lobby.on('change', renderLobby);\n            lobby.on('error', error => showNotice(`lobby error: ${message(error)}`, 'error'));\n            lobby.on('reset', () => showNotice('lobby was reset by another participant. The lobby has resynchronized.', 'stale'));\n\n            renderBoard(board.state);\n            renderPeers(board.presence.peers);\n            renderLobby(lobby.state);\n            markStale(board, 'match-42');\n            markStale(lobby, 'lobby');\n\n            if (!board.stale) {\n              await board.change(state => {\n                state.cards ??= {};\n                state.agentNote ??= '';\n              });\n            }\n            if (!lobby.stale) {\n              await lobby.change(state => {\n                state.message ??= '';\n                state.activeMatch ??= 'match-42';\n              });\n            }\n          } catch (error) {\n            showNotice(`Could not connect to the shared rooms: ${message(error)}`, 'error');\n            ui.viewerName.textContent = 'Unavailable';\n          }\n        }\n\n        ui.addCardForm.addEventListener('submit', event => {\n          event.preventDefault();\n          const title = ui.cardTitle.value.trim();\n          if (title) addCard(title);\n        });\n        ui.lobbyMessage.addEventListener('input', () => { lobbyDirty = true; });\n        ui.lobbyForm.addEventListener('submit', event => {\n          event.preventDefault();\n          saveLobbyMessage();\n        });\n        window.addEventListener('pagehide', () => {\n          if (board) board.close();\n          if (lobby) lobby.close();\n        });\n\n        initialize();\n      })();\n    </script>\n  </body>\n</html>\n"
+      "content": "<!doctype html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"utf-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <title>Shared board</title>\n    <style>\n      :root {\n        color: var(--color-foreground);\n        background: var(--color-background);\n        font-family: var(--font-sans);\n        font-synthesis: none;\n      }\n\n      * { box-sizing: border-box; }\n\n      body {\n        margin: 0;\n        min-width: 320px;\n        padding: 0;\n        background: var(--color-background);\n        color: var(--color-foreground);\n        font-family: var(--font-sans);\n      }\n\n      button, input, textarea { font: inherit; }\n\n      button {\n        border: 1px solid var(--color-primary);\n        border-radius: var(--radius-md);\n        background: var(--color-primary);\n        color: var(--color-primary-foreground);\n        cursor: pointer;\n        padding: 10px 14px;\n      }\n\n      button:hover { background: color-mix(in oklab, var(--color-primary) 90%, transparent); }\n      button:focus-visible, input:focus-visible, textarea:focus-visible { outline: 3px solid var(--color-ring); outline-offset: 2px; }\n      button:disabled { cursor: not-allowed; opacity: .5; }\n\n      .page { max-width: 1120px; margin: 0 auto; padding: 32px 24px 56px; }\n\n      header {\n        display: flex;\n        align-items: flex-start;\n        justify-content: space-between;\n        gap: 24px;\n        border-bottom: 1px solid var(--color-border);\n        padding-bottom: 24px;\n      }\n\n      h1, h2, p { margin-top: 0; }\n      h1 { font-size: clamp(2rem, 5vw, 3rem); letter-spacing: -.04em; margin-bottom: 8px; }\n      h2 { font-size: 1.15rem; letter-spacing: -.02em; margin-bottom: 16px; }\n      .lede, .muted { color: var(--color-muted-foreground); }\n      .lede { max-width: 46rem; margin-bottom: 0; }\n\n      .viewer {\n        min-width: 170px;\n        border: 1px solid var(--color-border);\n        border-radius: var(--radius-md);\n        background: var(--color-card);\n        padding: 12px;\n      }\n\n      .eyebrow {\n        color: var(--color-muted-foreground);\n        display: block;\n        font-size: .72rem;\n        font-weight: 700;\n        letter-spacing: .08em;\n        margin-bottom: 4px;\n        text-transform: uppercase;\n      }\n\n      .viewer-name { font-weight: 700; overflow-wrap: anywhere; }\n\n      .notice {\n        border: 1px solid var(--color-border);\n        border-left: 4px solid var(--color-primary);\n        border-radius: var(--radius-md);\n        background: var(--color-card);\n        margin: 24px 0;\n        min-height: 47px;\n        padding: 12px 14px;\n      }\n\n      .notice[data-tone=\"error\"] { border-left-color: var(--color-status-error); background: color-mix(in oklab, var(--color-status-error) 10%, var(--color-card)); }\n      .notice[data-tone=\"stale\"] { border-left-color: var(--color-status-warning); background: color-mix(in oklab, var(--color-status-warning) 10%, var(--color-card)); }\n      .notice:empty { display: none; }\n\n      .grid { display: grid; gap: 24px; grid-template-columns: minmax(0, 1.65fr) minmax(260px, .85fr); }\n      .panel { border: 1px solid var(--color-border); border-radius: var(--radius-xl); background: var(--color-card); padding: 20px; }\n      .panel + .panel { margin-top: 24px; }\n\n      .add-row { display: grid; gap: 8px; grid-template-columns: minmax(0, 1fr) auto; margin-bottom: 16px; }\n      input, textarea {\n        border: 1px solid var(--color-input);\n        border-radius: var(--radius-md);\n        background: var(--color-card);\n        color: inherit;\n        padding: 10px 12px;\n        width: 100%;\n      }\n\n      textarea { min-height: 94px; resize: vertical; }\n      label { display: block; font-size: .88rem; font-weight: 650; margin-bottom: 8px; }\n\n      .cards, .peers { list-style: none; margin: 0; padding: 0; }\n      .cards { border-top: 1px solid var(--color-border-subtle); }\n      .card {\n        align-items: center;\n        border-bottom: 1px solid var(--color-border-subtle);\n        display: flex;\n        gap: 12px;\n        justify-content: space-between;\n        padding: 13px 0;\n      }\n\n      .card-title { font-weight: 650; overflow-wrap: anywhere; }\n      .card-status {\n        background: var(--color-card);\n        border-color: var(--color-input);\n        color: var(--color-foreground);\n        flex: 0 0 auto;\n        font-size: .82rem;\n        padding: 7px 10px;\n      }\n\n      .card-status[data-done=\"true\"] { background: var(--color-status-success); border-color: var(--color-status-success-strong); color: var(--color-status-success-foreground); }\n      .empty { color: var(--color-muted-foreground); padding: 16px 0 4px; }\n      .agent-note { background: var(--color-muted); border-radius: var(--radius-md); min-height: 46px; padding: 12px; white-space: pre-wrap; overflow-wrap: anywhere; }\n      .agent-note:empty::before { color: var(--color-muted-foreground); content: \"No note yet. A server-side agent can write one here.\"; }\n\n      .peers { display: grid; gap: 8px; }\n      .peer {\n        border: 1px solid var(--color-border-subtle);\n        border-radius: var(--radius-md);\n        display: grid;\n        gap: 3px;\n        padding: 10px;\n      }\n\n      .peer-name { font-weight: 650; overflow-wrap: anywhere; }\n      .room-meta { color: var(--color-muted-foreground); font-family: var(--font-mono); font-size: .75rem; margin: 0 0 16px; }\n      .save-state { color: var(--color-muted-foreground); font-size: .82rem; margin: 8px 0 0; min-height: 1.2em; }\n\n      @media (max-width: 720px) {\n        .page { padding: 24px 16px 40px; }\n        header { align-items: stretch; flex-direction: column; }\n        .viewer { min-width: 0; }\n        .grid { grid-template-columns: 1fr; }\n        .add-row { grid-template-columns: 1fr; }\n      }\n    </style>\n  </head>\n  <body>\n    <swarm-cursors room=\"match-42\"></swarm-cursors>\n    <main class=\"page\">\n      <header>\n        <div>\n          <h1>Shared board</h1>\n          <p class=\"lede\">A small board shared by everyone in match-42. Changes appear as peers make them.</p>\n        </div>\n        <section class=\"viewer\" aria-label=\"Current viewer\">\n          <span class=\"eyebrow\">Connected as</span>\n          <div class=\"viewer-name\" id=\"viewer-name\">Connecting…</div>\n        </section>\n      </header>\n\n      <div id=\"notice\" class=\"notice\" role=\"status\" aria-live=\"polite\"></div>\n\n      <div class=\"grid\">\n        <section class=\"panel\" aria-labelledby=\"board-heading\">\n          <h2 id=\"board-heading\">Match board</h2>\n          <p class=\"room-meta\">Room: match-42 · Schema: 1</p>\n          <form id=\"add-card-form\" class=\"add-row\">\n            <label for=\"card-title\" class=\"sr-only\" hidden>New card title</label>\n            <input id=\"card-title\" name=\"title\" maxlength=\"120\" placeholder=\"Write a card title\" required>\n            <button type=\"submit\">Add card</button>\n          </form>\n          <ul id=\"cards\" class=\"cards\" aria-live=\"polite\"></ul>\n        </section>\n\n        <aside>\n          <section class=\"panel\" aria-labelledby=\"peers-heading\">\n            <h2 id=\"peers-heading\">Live peers</h2>\n            <p class=\"muted\">Pointers use document-normalized coordinates and line up across viewports.</p>\n            <ul id=\"peers\" class=\"peers\" aria-live=\"polite\"></ul>\n          </section>\n\n          <section class=\"panel\" aria-labelledby=\"agent-note-heading\">\n            <h2 id=\"agent-note-heading\">Agent note</h2>\n            <div id=\"agent-note\" class=\"agent-note\" aria-live=\"polite\"></div>\n          </section>\n        </aside>\n      </div>\n\n      <section class=\"panel\" aria-labelledby=\"lobby-heading\">\n        <h2 id=\"lobby-heading\">Lobby</h2>\n        <p class=\"room-meta\">Room: lobby · Schema: 1</p>\n        <form id=\"lobby-form\">\n          <label for=\"lobby-message\">Shared lobby message</label>\n          <textarea id=\"lobby-message\" maxlength=\"1000\" placeholder=\"Leave a message for everyone in the lobby\"></textarea>\n          <button type=\"submit\">Save lobby message</button>\n          <p id=\"lobby-save-state\" class=\"save-state\" aria-live=\"polite\"></p>\n        </form>\n      </section>\n    </main>\n\n    <script>\n      (() => {\n        const ui = {\n          viewerName: document.querySelector('#viewer-name'),\n          notice: document.querySelector('#notice'),\n          cards: document.querySelector('#cards'),\n          peers: document.querySelector('#peers'),\n          agentNote: document.querySelector('#agent-note'),\n          addCardForm: document.querySelector('#add-card-form'),\n          cardTitle: document.querySelector('#card-title'),\n          lobbyForm: document.querySelector('#lobby-form'),\n          lobbyMessage: document.querySelector('#lobby-message'),\n          lobbySaveState: document.querySelector('#lobby-save-state')\n        };\n\n        let board;\n        let lobby;\n        let peers = [];\n        let lobbyDirty = false;\n\n        function message(error) {\n          return error && error.message ? error.message : String(error);\n        }\n\n        function showNotice(text, tone) {\n          ui.notice.textContent = text || '';\n          ui.notice.dataset.tone = tone || '';\n        }\n\n        function markStale(room, roomName) {\n          if (!room.stale) return false;\n          showNotice(`${roomName} uses a different schema version. Its saved state remains visible, but this page cannot write changes.`, 'stale');\n          return true;\n        }\n\n        function renderBoard(state) {\n          const cards = state && state.cards && typeof state.cards === 'object' ? state.cards : {};\n          ui.cards.replaceChildren();\n          const entries = Object.entries(cards);\n\n          if (!entries.length) {\n            const empty = document.createElement('li');\n            empty.className = 'empty';\n            empty.textContent = 'No cards yet. Add the first card.';\n            ui.cards.append(empty);\n          }\n\n          for (const [id, card] of entries) {\n            const item = document.createElement('li');\n            item.className = 'card';\n            const title = document.createElement('span');\n            title.className = 'card-title';\n            title.textContent = card && typeof card.title === 'string' ? card.title : 'Untitled card';\n            const toggle = document.createElement('button');\n            const done = Boolean(card && card.done);\n            toggle.className = 'card-status';\n            toggle.dataset.done = String(done);\n            toggle.type = 'button';\n            toggle.textContent = done ? 'Done' : 'Open';\n            toggle.setAttribute('aria-label', `Mark ${title.textContent} as ${done ? 'open' : 'done'}`);\n            toggle.addEventListener('click', () => toggleCard(id));\n            item.append(title, toggle);\n            ui.cards.append(item);\n          }\n\n          ui.agentNote.textContent = state && typeof state.agentNote === 'string' ? state.agentNote : '';\n        }\n\n        function renderPeers(nextPeers) {\n          peers = Array.isArray(nextPeers) ? nextPeers : [];\n          ui.peers.replaceChildren();\n\n          if (!peers.length) {\n            const empty = document.createElement('li');\n            empty.className = 'empty';\n            empty.textContent = 'No other peers are connected.';\n            ui.peers.append(empty);\n            return;\n          }\n\n          for (const peer of peers) {\n            const item = document.createElement('li');\n            item.className = 'peer';\n            const name = document.createElement('span');\n            name.className = 'peer-name';\n            name.textContent = peer.name || 'Guest';\n            item.append(name);\n            ui.peers.append(item);\n          }\n        }\n\n        function renderLobby(state) {\n          if (lobbyDirty) return;\n          ui.lobbyMessage.value = state && typeof state.message === 'string' ? state.message : '';\n        }\n\n        async function addCard(title) {\n          if (markStale(board, 'match-42')) return;\n          try {\n            await board.change(state => {\n              state.cards ??= {};\n              state.cards[crypto.randomUUID()] = { title, done: false };\n            });\n            ui.cardTitle.value = '';\n            showNotice('Card added.', 'success');\n          } catch (error) {\n            showNotice(`Could not add the card: ${message(error)}`, 'error');\n          }\n        }\n\n        async function toggleCard(id) {\n          if (markStale(board, 'match-42')) return;\n          try {\n            await board.change(state => {\n              const card = state.cards && state.cards[id];\n              if (card) card.done = !card.done;\n            });\n          } catch (error) {\n            showNotice(`Could not update the card: ${message(error)}`, 'error');\n          }\n        }\n\n        async function saveLobbyMessage() {\n          if (markStale(lobby, 'lobby')) return;\n          try {\n            const value = ui.lobbyMessage.value;\n            await lobby.change(state => {\n              state.message = value;\n            });\n            lobbyDirty = false;\n            ui.lobbySaveState.textContent = 'Saved to the lobby room.';\n          } catch (error) {\n            ui.lobbySaveState.textContent = `Could not save: ${message(error)}`;\n            showNotice(`Could not save the lobby message: ${message(error)}`, 'error');\n          }\n        }\n\n        async function initialize() {\n          try {\n            board = await window.swarmSdk.room('match-42', { schemaVersion: 1 });\n            lobby = await window.swarmSdk.room('lobby', { schemaVersion: 1 });\n\n            const viewer = board.me || lobby.me || {};\n            ui.viewerName.textContent = viewer.name || 'Guest';\n\n            board.on('change', renderBoard);\n            board.on('presence', renderPeers);\n            board.on('error', error => showNotice(`match-42 error: ${message(error)}`, 'error'));\n            board.on('reset', () => showNotice('match-42 was reset by another participant. The board has resynchronized.', 'stale'));\n            lobby.on('change', renderLobby);\n            lobby.on('error', error => showNotice(`lobby error: ${message(error)}`, 'error'));\n            lobby.on('reset', () => showNotice('lobby was reset by another participant. The lobby has resynchronized.', 'stale'));\n\n            renderBoard(board.state);\n            renderPeers(board.presence.peers);\n            renderLobby(lobby.state);\n            markStale(board, 'match-42');\n            markStale(lobby, 'lobby');\n\n            if (!board.stale) {\n              await board.change(state => {\n                state.cards ??= {};\n                state.agentNote ??= '';\n              });\n            }\n            if (!lobby.stale) {\n              await lobby.change(state => {\n                state.message ??= '';\n                state.activeMatch ??= 'match-42';\n              });\n            }\n          } catch (error) {\n            showNotice(`Could not connect to the shared rooms: ${message(error)}`, 'error');\n            ui.viewerName.textContent = 'Unavailable';\n          }\n        }\n\n        ui.addCardForm.addEventListener('submit', event => {\n          event.preventDefault();\n          const title = ui.cardTitle.value.trim();\n          if (title) addCard(title);\n        });\n        ui.lobbyMessage.addEventListener('input', () => { lobbyDirty = true; });\n        ui.lobbyForm.addEventListener('submit', event => {\n          event.preventDefault();\n          saveLobbyMessage();\n        });\n        window.addEventListener('pagehide', () => {\n          if (board) board.close();\n          if (lobby) lobby.close();\n        });\n\n        initialize();\n      })();\n    </script>\n  </body>\n</html>\n"
     },
     {
       "path": "examples/report-page.html",
-      "content": "<!doctype html>\n<!--\n  Reference report page — minimalist taste baseline + report density layer.\n\n  Copy this as the starting point for any dense report/dashboard page, then\n  replace the content. The CSS already encodes the baseline documented in the\n  `pages` skill: warm monochrome canvas, single-column 1120px spine, 8/12/16/\n  24/32/48/72 spacing scale, tabular numerals, flat bordered cards, table\n  horizontal scroll on mobile, and no decorative gradients or nested cards.\n\n  Publish with:\n    create_page({\n      title: \"Q2 SEO Performance\",\n      slug: \"q2-seo-performance\",\n      description: \"Human-readable SEO performance report.\",\n      contentType: \"text/html\",\n      authMode: \"authed\",\n      body: <this file's contents>,\n    })\n-->\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <title>Q2 SEO Performance</title>\n  <style>\n    :root {\n      color-scheme: light;\n      --bg: #f6f4f0;\n      --panel: #ffffff;\n      --ink: #18181b;\n      --muted: #62646a;\n      --line: #dedbd2;\n      --accent: #2563eb;\n      --danger: #b42318;\n      --warn: #b54708;\n      --ok: #067647;\n      --radius: 8px;\n      --shadow: 0 1px 2px rgba(24, 24, 27, 0.04);\n    }\n    * { box-sizing: border-box; }\n    body {\n      margin: 0;\n      background: var(--bg);\n      color: var(--ink);\n      font-family: \"SF Pro Display\", \"Geist Sans\", \"Helvetica Neue\", ui-sans-serif, system-ui, sans-serif;\n      font-size: 16px;\n      line-height: 1.55;\n    }\n    main {\n      width: min(1120px, calc(100% - 32px));\n      margin: 0 auto;\n      padding: 48px 0 72px;\n    }\n    header { margin-bottom: 32px; }\n    .eyebrow {\n      margin: 0 0 8px;\n      color: var(--muted);\n      font-size: 13px;\n      font-weight: 700;\n      letter-spacing: 0.08em;\n      text-transform: uppercase;\n    }\n    h1 {\n      margin: 0;\n      max-width: 780px;\n      font-size: clamp(2rem, 4vw, 3rem);\n      line-height: 1.05;\n      letter-spacing: 0;\n    }\n    .lede {\n      max-width: 760px;\n      margin: 16px 0 0;\n      color: var(--muted);\n      font-size: 18px;\n    }\n    .metrics {\n      display: grid;\n      grid-template-columns: repeat(4, minmax(0, 1fr));\n      gap: 12px;\n      margin: 32px 0;\n    }\n    .metric, .section {\n      background: var(--panel);\n      border: 1px solid var(--line);\n      border-radius: var(--radius);\n      box-shadow: var(--shadow);\n    }\n    .metric { padding: 18px; }\n    .metric strong {\n      display: block;\n      font-size: 32px;\n      line-height: 1;\n      font-variant-numeric: tabular-nums;\n    }\n    .metric span {\n      display: block;\n      margin-top: 8px;\n      color: var(--muted);\n      font-size: 13px;\n      font-weight: 650;\n    }\n    .section {\n      margin-top: 18px;\n      padding: 24px;\n    }\n    h2 { margin: 0 0 12px; font-size: 24px; line-height: 1.2; }\n    h3 { margin: 0 0 8px; font-size: 17px; line-height: 1.3; }\n    p { margin: 0 0 12px; }\n    .table-wrap { overflow-x: auto; border: 1px solid var(--line); border-radius: var(--radius); }\n    table { width: 100%; border-collapse: collapse; min-width: 640px; }\n    th, td { padding: 10px 12px; border-bottom: 1px solid var(--line); text-align: left; vertical-align: top; }\n    th { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: 0.06em; }\n    td { font-size: 14px; font-variant-numeric: tabular-nums; }\n    code, pre { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }\n    details { margin-top: 24px; }\n    summary { cursor: pointer; font-weight: 700; }\n    pre { overflow: auto; padding: 16px; background: #111827; color: #f9fafb; border-radius: var(--radius); }\n    @media (max-width: 760px) {\n      main { width: min(100% - 24px, 1120px); padding-top: 32px; }\n      .metrics { grid-template-columns: repeat(2, minmax(0, 1fr)); }\n      .section { padding: 18px; }\n    }\n    @media (max-width: 520px) {\n      .metrics { grid-template-columns: 1fr; }\n      .lede { font-size: 16px; }\n    }\n  </style>\n</head>\n<body>\n  <main>\n    <header>\n      <p class=\"eyebrow\">Generated 2026-06-04</p>\n      <h1>Q2 SEO Performance</h1>\n      <p class=\"lede\">Organic traffic grew sharply, but the next gains depend on fixing thin page metadata and publishing three high-intent pillar pages.</p>\n    </header>\n\n    <section class=\"metrics\" aria-label=\"Key metrics\">\n      <div class=\"metric\"><strong>18.6k</strong><span>Organic clicks</span></div>\n      <div class=\"metric\"><strong>+50%</strong><span>Quarter over quarter</span></div>\n      <div class=\"metric\"><strong>23</strong><span>Metadata fixes</span></div>\n      <div class=\"metric\"><strong>3</strong><span>Priority pages</span></div>\n    </section>\n\n    <section class=\"section\">\n      <h2>Summary</h2>\n      <p>Start with the conclusion. Add tables only after the reader understands what changed and what to do next.</p>\n      <div class=\"table-wrap\">\n        <table>\n          <thead><tr><th>Metric</th><th>Q1</th><th>Q2</th><th>Change</th></tr></thead>\n          <tbody><tr><td>Organic clicks</td><td>12,400</td><td>18,600</td><td>+50%</td></tr></tbody>\n        </table>\n      </div>\n    </section>\n\n    <details>\n      <summary>Raw evidence</summary>\n      <pre>{ \"source\": \"search-console\", \"range\": \"2026-04-01/2026-06-30\" }</pre>\n    </details>\n  </main>\n</body>\n</html>\n"
+      "content": "<!doctype html>\n<!--\n  Reference report page for the swarm design system (designVersion 2).\n\n  Copy this as the starting point for a dense report or dashboard page, then\n  replace the content. It uses only the swarm-* primitives, the theme tokens,\n  and a few Tailwind layout utilities. It has zero color literals, so it\n  follows the viewer's theme and dark mode inside the dashboard.\n\n  Publish with:\n    create_page({\n      title: \"Q2 SEO Performance\",\n      slug: \"q2-seo-performance\",\n      description: \"Human-readable SEO performance report.\",\n      contentType: \"text/html\",\n      authMode: \"authed\",\n      body: <this file's contents>,\n    })\n-->\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\">\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n  <title>Q2 SEO Performance</title>\n</head>\n<body>\n  <main class=\"swarm-page\">\n    <header>\n      <p class=\"swarm-eyebrow\">Search Console · Generated 2026-06-04</p>\n      <h1>Q2 SEO Performance</h1>\n      <p class=\"swarm-lede\">Organic clicks grew 50% this quarter. The next gains depend on fixing thin page metadata and on three high-intent pillar pages.</p>\n      <span class=\"swarm-badge\" data-tone=\"success\" data-dot>On track</span>\n    </header>\n\n    <section class=\"swarm-metrics\" aria-label=\"Key metrics\">\n      <div class=\"swarm-metric\">\n        <div class=\"swarm-metric-value\">18.6k</div>\n        <div class=\"swarm-metric-label\">Organic clicks</div>\n      </div>\n      <div class=\"swarm-metric\" data-tone=\"success\">\n        <div class=\"swarm-metric-value\">+50%</div>\n        <div class=\"swarm-metric-label\">Quarter over quarter</div>\n      </div>\n      <div class=\"swarm-metric\" data-tone=\"warning\">\n        <div class=\"swarm-metric-value\">23</div>\n        <div class=\"swarm-metric-label\">Metadata fixes</div>\n      </div>\n      <div class=\"swarm-metric\">\n        <div class=\"swarm-metric-value\">3</div>\n        <div class=\"swarm-metric-label\">Priority pages</div>\n      </div>\n    </section>\n\n    <section class=\"swarm-section\" aria-labelledby=\"findings-heading\">\n      <h2 id=\"findings-heading\">Findings</h2>\n      <div class=\"swarm-callout\" data-tone=\"warning\">\n        <strong>Thin metadata caps growth.</strong> 23 ranking pages share a generic title and description. Fix them before new content ships.\n      </div>\n      <div class=\"swarm-callout\">\n        <strong>One post drives the growth.</strong> The agent swarms post brought about a quarter of the new clicks.\n      </div>\n    </section>\n\n    <section class=\"swarm-section\" aria-labelledby=\"pages-heading\">\n      <h2 id=\"pages-heading\">Top pages</h2>\n      <div class=\"swarm-toolbar\">\n        <input class=\"swarm-input\" id=\"page-filter\" type=\"search\" placeholder=\"Filter pages\" aria-label=\"Filter pages\">\n        <div class=\"swarm-segmented\" role=\"group\" aria-label=\"Status\">\n          <button type=\"button\" data-status-filter=\"all\" aria-pressed=\"true\">All</button>\n          <button type=\"button\" data-status-filter=\"fix\" aria-pressed=\"false\">Needs fix</button>\n        </div>\n        <button class=\"swarm-button\" id=\"filter-reset\" type=\"button\">Reset</button>\n      </div>\n      <div class=\"swarm-table-wrap\">\n        <table class=\"swarm-table\" id=\"pages-table\">\n          <thead>\n            <tr><th>Page</th><th>Status</th><th class=\"num\">Q1 clicks</th><th class=\"num\">Q2 clicks</th><th class=\"num\">Change</th></tr>\n          </thead>\n          <tbody>\n            <tr data-status=\"ok\"><td class=\"nowrap\">/pricing</td><td><span class=\"swarm-badge\" data-tone=\"success\">Healthy</span></td><td class=\"num\">4,100</td><td class=\"num\">6,900</td><td class=\"num\">+68%</td></tr>\n            <tr data-status=\"fix\"><td class=\"nowrap\">/docs/install</td><td><span class=\"swarm-badge\" data-tone=\"warning\">Thin title</span></td><td class=\"num\">3,200</td><td class=\"num\">3,350</td><td class=\"num\">+5%</td></tr>\n            <tr data-status=\"ok\"><td class=\"nowrap\">/blog/agent-swarms</td><td><span class=\"swarm-badge\" data-tone=\"success\">Healthy</span></td><td class=\"num\">1,500</td><td class=\"num\">3,100</td><td class=\"num\">+107%</td></tr>\n            <tr data-status=\"fix\"><td class=\"nowrap\">/integrations/slack</td><td><span class=\"swarm-badge\" data-tone=\"error\">No description</span></td><td class=\"num\">1,900</td><td class=\"num\">1,700</td><td class=\"num text-status-error-strong\">-11%</td></tr>\n            <tr data-status=\"review\"><td class=\"nowrap\">/changelog</td><td><span class=\"swarm-badge\">Not reviewed</span></td><td class=\"num\">400</td><td class=\"num\">1,150</td><td class=\"num\">+188%</td></tr>\n          </tbody>\n        </table>\n      </div>\n      <p class=\"text-muted-foreground\" id=\"filter-empty\" hidden>No pages match the filter.</p>\n    </section>\n\n    <section class=\"swarm-section\" aria-labelledby=\"actions-heading\">\n      <h2 id=\"actions-heading\">Next actions</h2>\n      <div class=\"grid gap-4 md:grid-cols-2\">\n        <article class=\"swarm-panel\">\n          <h3>Fix thin metadata</h3>\n          <dl class=\"swarm-kv\">\n            <dt>Owner</dt><dd>Content team</dd>\n            <dt>Pages</dt><dd>23</dd>\n            <dt>Due</dt><dd>2026-07-15</dd>\n          </dl>\n        </article>\n        <article class=\"swarm-panel\">\n          <h3>Publish three pillar pages</h3>\n          <dl class=\"swarm-kv\">\n            <dt>Owner</dt><dd>Growth team</dd>\n            <dt>Topics</dt><dd>Agent orchestration, task routing, swarm costs</dd>\n            <dt>Due</dt><dd>2026-08-01</dd>\n          </dl>\n        </article>\n      </div>\n      <div class=\"mt-4\">\n        <a class=\"swarm-button\" data-variant=\"primary\" href=\"https://search.google.com/search-console\">Open Search Console</a>\n      </div>\n    </section>\n\n    <details>\n      <summary>Raw evidence</summary>\n      <pre>{ \"source\": \"search-console\", \"range\": \"2026-04-01/2026-06-30\" }</pre>\n    </details>\n  </main>\n\n  <script>\n    (() => {\n      const filter = document.getElementById(\"page-filter\");\n      const reset = document.getElementById(\"filter-reset\");\n      const empty = document.getElementById(\"filter-empty\");\n      const statusButtons = document.querySelectorAll(\"[data-status-filter]\");\n      const rows = document.querySelectorAll(\"#pages-table tbody tr\");\n      let status = \"all\";\n\n      function applyFilter() {\n        const query = filter.value.trim().toLowerCase();\n        let shown = 0;\n        for (const row of rows) {\n          const visible =\n            row.textContent.toLowerCase().includes(query) &&\n            (status === \"all\" || row.dataset.status === status);\n          row.style.display = visible ? \"\" : \"none\";\n          if (visible) shown += 1;\n        }\n        empty.hidden = shown > 0;\n      }\n\n      function setStatus(next) {\n        status = next;\n        for (const button of statusButtons) {\n          button.setAttribute(\"aria-pressed\", String(button.dataset.statusFilter === next));\n        }\n        applyFilter();\n      }\n\n      for (const button of statusButtons) {\n        button.addEventListener(\"click\", () => setStatus(button.dataset.statusFilter));\n      }\n      filter.addEventListener(\"input\", applyFilter);\n      reset.addEventListener(\"click\", () => {\n        filter.value = \"\";\n        setStatus(\"all\");\n      });\n    })();\n  </script>\n</body>\n</html>\n"
     }
   ],
   "planning": [

package/src/be/swarm-config-guard.ts

@@ -12,6 +12,11 @@ import {
 import { envExportRestrictedError, isEnvExportRestrictedKey } from "../utils/config-env-export";
 import { validateEgressAllowlist } from "../utils/egress-guard";
 import { parseEnabledTools } from "../utils/enabled-tools";
+import {
+  isFollowUpGateScheduleId,
+  parseFollowUpGateScheduleIds,
+} from "../utils/follow-up-gate-schedule-ids";
+import { kindForModelString } from "../utils/internal-ai/models";
 import { normalizeOrgWebsite } from "../utils/org-website";
 import { parseTaskToolManifest } from "../utils/task-tool-manifest";
 import { isTierConfigKey, validateTierConfigValue } from "./model-tier-keys";
@@ -306,6 +311,24 @@ export function validateRuntimeTokenTtlHours(value: unknown): string | null {
     : "Invalid RUNTIME_TOKEN_TTL_HOURS (must be greater than zero and at most 168)";
 }
 
+/**
+ * `TASK_AUTO_TITLE_MODEL` pins the task-title model: `provider/model-id` for a
+ * provider the internal-ai layer can call, or a bare `claude -p` alias. Empty
+ * clears the pin. The model id itself is checked at call time (an unknown id
+ * logs and falls through to the next candidate).
+ */
+export function validateTaskAutoTitleModel(value: unknown): string | null {
+  if (typeof value !== "string") return "Invalid TASK_AUTO_TITLE_MODEL (must be a string)";
+  const model = value.trim();
+  if (!model) return null;
+  if (/\s/.test(model) || model.endsWith("/")) {
+    return "Invalid TASK_AUTO_TITLE_MODEL (use provider/model-id or a claude -p alias)";
+  }
+  return kindForModelString(model)
+    ? null
+    : "Invalid TASK_AUTO_TITLE_MODEL (provider must be openrouter, anthropic, openai, or openai-codex)";
+}
+
 export const validateControllerTokenTtlDays = boundedIntegerValidators(
   ["RUNTIME_CONTROLLER_TOKEN_TTL_DAYS"],
   1,
@@ -428,6 +451,13 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   // model's weekly window (Fable/Opus/Sonnet). fallback: legacy random pick.
   ...enumValidator("MODEL_WINDOW_EXHAUSTED_POLICY", ["fail", "fallback"]),
   ...enumValidator("HEARTBEAT_CHECKLIST_GATE_MODE", ["shadow", "enforce"]),
+  // `enforce` is deliberately absent: the follow-up gate only records decisions.
+  ...enumValidator("FOLLOW_UP_GATE_MODE", ["off", "shadow"]),
+  FOLLOW_UP_GATE_SCHEDULE_IDS: (value: unknown) => {
+    const message = "Invalid FOLLOW_UP_GATE_SCHEDULE_IDS (must be comma-separated schedule UUIDs)";
+    if (typeof value !== "string") return message;
+    return parseFollowUpGateScheduleIds(value).every(isFollowUpGateScheduleId) ? null : message;
+  },
   ...enumValidator("SYSTEM_ONE_DEFAULT_PROVIDER", [...SYSTEM_ONE_DEFAULT_PROVIDER_OPTIONS]),
   // Codex credits-exhausted cooldown (ms). Permissive on range here (positive
   // integer) — the worker clamps to [5m, 7d] via resolveCodexCreditsExhaustedCooldownMs.
@@ -525,7 +555,9 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     "MODEL_AUTO_UPGRADE",
     "COMB_ENABLED",
     "AGENT_FS_PROXY",
+    "TASK_AUTO_TITLE_ENABLED",
   ]),
+  TASK_AUTO_TITLE_MODEL: validateTaskAutoTitleModel,
   ...enumValidator("SLACK_MODE", ["socket", "http"]),
   ...enumValidator("SLACK_THREAD_STEERING", ["off", "lead", "all"]),
   ...enumValidator("SLACK_THREAD_STEERING_MODE", ["steer", "queue"]),

package/src/be/task-auto-title-listener.ts

@@ -0,0 +1,127 @@
+/**
+ * Automatic task titles.
+ *
+ * Listens for `task.created` (emitted after commit by `createTaskExtended`),
+ * asks the cheapest configured model for a short title, and stores it on the
+ * task when nobody set one first. The sessions sidebar and task lists read
+ * `title` and fall back to the prompt, so a failed or skipped generation
+ * changes nothing visible.
+ *
+ * `TASK_AUTO_TITLE_ENABLED=false` turns the listener off at the next event;
+ * `TASK_AUTO_TITLE_MODEL` pins one model (see `buildTaskTitlePlan`).
+ */
+
+import { getApiKey } from "../utils/api-key";
+import { getMcpBaseUrl } from "../utils/constants";
+import { parseEnvFlag } from "../utils/env-flag";
+import { generateTaskTitle, TASK_TITLE_TIMEOUT_MS } from "../utils/internal-ai/task-title";
+import { scrubSecrets } from "../utils/secret-scrubber";
+import { workflowEventBus } from "../workflows/event-bus";
+import { getTaskById } from "./db/tasks/read";
+import { setTaskTitleIfUnset } from "./db/tasks/write";
+
+/** Titles generated at once. Bursts (a workflow fan-out) queue behind this. */
+export const TASK_AUTO_TITLE_CONCURRENCY = 3;
+
+export function isTaskAutoTitleEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return parseEnvFlag(env.TASK_AUTO_TITLE_ENABLED, true);
+}
+
+export interface TaskAutoTitleListenerOptions {
+  /** Defaults to `process.env`; read on every event so a config reload applies. */
+  env?: NodeJS.ProcessEnv;
+  /** Test injection: replaces the model call. */
+  generate?: typeof generateTaskTitle;
+}
+
+export interface TaskAutoTitleListener {
+  stop(): void;
+  /** Resolves once every queued task has been processed. */
+  idle(): Promise<void>;
+}
+
+export function startTaskAutoTitleListener(
+  options: TaskAutoTitleListenerOptions = {},
+): TaskAutoTitleListener {
+  const env = options.env ?? process.env;
+  const generate = options.generate ?? generateTaskTitle;
+  const queue: string[] = [];
+  let active = 0;
+  let idleWaiters: Array<() => void> = [];
+
+  const settleIdle = () => {
+    if (active > 0 || queue.length > 0) return;
+    const waiters = idleWaiters;
+    idleWaiters = [];
+    for (const resolve of waiters) resolve();
+  };
+
+  const pump = () => {
+    while (active < TASK_AUTO_TITLE_CONCURRENCY) {
+      const taskId = queue.shift();
+      if (!taskId) break;
+      active++;
+      void titleTask(taskId, env, generate)
+        .catch((error) => console.error("[task-title] Failed:", scrubSecrets(String(error))))
+        .finally(() => {
+          active--;
+          pump();
+          settleIdle();
+        });
+    }
+  };
+
+  const onTaskCreated = (data: unknown) => {
+    if (!isTaskAutoTitleEnabled(env)) return;
+    const taskId = (data as { taskId?: unknown }).taskId;
+    if (typeof taskId !== "string" || !taskId) return;
+    queue.push(taskId);
+    pump();
+  };
+
+  workflowEventBus.on("task.created", onTaskCreated);
+  return {
+    stop: () => workflowEventBus.off("task.created", onTaskCreated),
+    idle: () =>
+      new Promise<void>((resolve) => {
+        idleWaiters.push(resolve);
+        settleIdle();
+      }),
+  };
+}
+
+async function titleTask(
+  taskId: string,
+  env: NodeJS.ProcessEnv,
+  generate: typeof generateTaskTitle,
+): Promise<void> {
+  const task = await getTaskById(taskId);
+  if (!task || task.title) return;
+  const shortId = taskId.slice(0, 8);
+  const startedAt = Date.now();
+  const result = await generate({
+    task: task.task,
+    env,
+    // Loopback context for the codex OAuth probe; only used when no API key is set.
+    apiUrl: getMcpBaseUrl(),
+    apiKey: getApiKey(),
+    callerTag: `task-title:${task.source}`,
+    signal: AbortSignal.timeout(TASK_TITLE_TIMEOUT_MS),
+  });
+  if (!result.ok) {
+    if (result.reason !== "short-task") {
+      console.log(`[task-title] ${shortId}: no title (${result.reason})`);
+    }
+    return;
+  }
+  const updated = await setTaskTitleIfUnset(taskId, result.title);
+  const elapsed = Date.now() - startedAt;
+  // The title derives from task text, so a pasted token could reach the log.
+  console.log(
+    scrubSecrets(
+      `[task-title] ${shortId}: "${result.title}" via ${result.model} in ${elapsed}ms${
+        updated ? "" : " (kept the existing title)"
+      }`,
+    ),
+  );
+}

package/src/commands/controller.ts

@@ -15,6 +15,10 @@ async function executeCommand(
   command: ControllerCommand,
 ): Promise<unknown> {
   switch (command.op) {
+    case "release-cache":
+      if (!controller.releaseCache) throw new Error("Controller does not support cache cleanup");
+      await controller.releaseCache(command.payload);
+      return {};
     case "provision":
       return await controller.provision(command.payload);
     case "terminate":

package/src/commands/entrypoint-api-readiness.ts

@@ -0,0 +1,74 @@
+/** Worker boot step; deliberately standalone so both worker images can run it before setup. */
+export interface ApiReadinessDependencies {
+  fetch: (url: string, init: RequestInit) => Promise<Response>;
+  now: () => number;
+  sleep: (ms: number) => Promise<void>;
+  log: (message: string) => void;
+}
+
+const defaults: ApiReadinessDependencies = {
+  fetch: (url, init) => fetch(url, init),
+  now: () => performance.now(),
+  sleep: (ms) => Bun.sleep(ms),
+  log: (message) => console.log(message),
+};
+
+/** Poll the unauthenticated health endpoint before any provider reads configuration. */
+export async function waitForApiReady(
+  baseUrl: string,
+  timeoutValue = "90",
+  dependencies: Partial<ApiReadinessDependencies> = {},
+): Promise<boolean> {
+  const { fetch: probe, now, sleep, log } = { ...defaults, ...dependencies };
+  const raw = timeoutValue || "90";
+  const seconds = Number(raw);
+  if (!/^\d+$/.test(raw) || !Number.isSafeInteger(seconds) || seconds <= 0) {
+    log(
+      `[entrypoint] FATAL: WORKER_API_READY_TIMEOUT_SECONDS must be a positive integer, got '${raw}'; exiting.`,
+    );
+    return false;
+  }
+
+  const url = `${baseUrl.replace(/\/$/, "")}/health`;
+  const deadline = now() + seconds * 1000;
+  log(`[entrypoint] Waiting for API readiness at ${url} (timeout ${raw}s)...`);
+  while (true) {
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () => controller.abort(),
+      Math.min(3000, Math.max(1, deadline - now())),
+    );
+    try {
+      const response = await probe(url, { redirect: "manual", signal: controller.signal });
+      // curl -o /dev/null waited for the whole response, without retaining its body.
+      if (response.body) {
+        for await (const _chunk of response.body) {
+          // Discard health output, including error bodies, within the request timeout.
+        }
+      }
+      // Match curl -f without -L: redirects are successful and are not followed.
+      if (response.status > 0 && response.status < 400 && now() <= deadline) {
+        log(`[entrypoint] API ready at ${url}`);
+        return true;
+      }
+    } catch {
+      // The API can still be booting; retry connection, HTTP and timeout failures alike.
+    } finally {
+      clearTimeout(timer);
+    }
+    if (now() >= deadline) {
+      log(`[entrypoint] FATAL: API readiness timed out after ${raw}s waiting for ${url}; exiting.`);
+      return false;
+    }
+    await sleep(Math.min(1000, deadline - now()));
+  }
+}
+
+if (import.meta.main) {
+  process.exitCode = (await waitForApiReady(
+    Bun.argv[2] ?? "http://host.docker.internal:3013",
+    Bun.argv[3],
+  ))
+    ? 0
+    : 1;
+}

package/src/commands/onboard/agent-fs-version.ts

@@ -2,4 +2,4 @@
  * agent-fs image tag bundled by `agent-swarm onboard --yes`.
  * `bun run bump:agent-fs` rewrites it together with the other pins.
  */
-export const AGENT_FS_VERSION = "0.18.13";
+export const AGENT_FS_VERSION = "0.18.14";