@desplega.ai/agent-swarm 1.166.0 → 1.167.0

package/src/tests/pi-mono-extension.test.ts

@@ -1,5 +1,6 @@
 /**
- * Unit tests for `summarizeSessionForPi` in `src/providers/pi-mono-extension.ts`.
+ * Unit tests for `summarizeSessionForPi` in `src/providers/pi-mono-extension.ts`,
+ * plus the extension's advisory nudges (delivered with `pi.sendMessage`).
  *
  * Plan: thoughts/taras/plans/2026-05-10-fix-session-summarization-workers.md
  * → Phase 1 § "Test coverage"
@@ -19,8 +20,14 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { clearToolHistory } from "../hooks/tool-loop-detection";
 import type { SummarizeSessionForPiDeps, SwarmHooksConfig } from "../providers/pi-mono-extension";
-import { summarizeSessionForPi } from "../providers/pi-mono-extension";
+import {
+  createSwarmHooksExtension,
+  SWARM_NUDGE_CUSTOM_TYPE,
+  summarizeSessionForPi,
+} from "../providers/pi-mono-extension";
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -345,3 +352,155 @@ describe("summarizeSessionForPi", () => {
     expect(consoleErrors.length).toBe(0);
   });
 });
+
+describe("pi provider header attribution", () => {
+  test("uses request model URL and task env, replacing pi attribution", async () => {
+    let handler:
+      | ((event: { headers: Record<string, string> }, ctx: { model: { baseUrl: string } }) => void)
+      | undefined;
+    const pi = {
+      on: (event: string, callback: unknown) => {
+        if (event === "before_provider_headers") handler = callback as NonNullable<typeof handler>;
+      },
+    } as unknown as ExtensionAPI;
+    const config = { ...makeConfig(), env: {} as Record<string, string | undefined> };
+    await createSwarmHooksExtension(config)(pi);
+    expect(handler).toBeDefined();
+    const headers = {
+      "HTTP-Referer": "https://pi.dev",
+      "X-OpenRouter-Title": "pi",
+      "X-Custom": "keep",
+    };
+    handler!({ headers }, { model: { baseUrl: "https://openrouter.ai/api" } });
+    expect(headers).toEqual({
+      "HTTP-Referer": "https://agent-swarm.dev",
+      "X-OpenRouter-Title": "Agent Swarm",
+      "X-OpenRouter-Categories": "personal-agent,cloud-agent",
+      "X-Custom": "keep",
+    });
+    config.env.OPENROUTER_APP_ATTRIBUTION = "false";
+    const optedOut = { "X-Custom": "keep" };
+    handler!({ headers: optedOut }, { model: { baseUrl: "https://openrouter.ai/api" } });
+    expect(optedOut).toEqual({ "X-Custom": "keep" });
+    config.env = {};
+    const gateway = {};
+    handler!({ headers: gateway }, { model: { baseUrl: "http://localhost:1234/v1" } });
+    expect(gateway).toEqual({});
+  });
+});
+
+// ── advisory nudges reach the model via pi.sendMessage ───────────────────────
+
+type Handler = (event: unknown, ctx: unknown) => Promise<unknown> | unknown;
+type SentMessage = { customType: string; content: Array<{ type: string; text: string }> };
+
+/** Minimal stand-in for pi's ExtensionAPI: records handlers and sent messages. */
+function loadExtension(config: SwarmHooksConfig) {
+  const handlers = new Map<string, Handler>();
+  const sent: SentMessage[] = [];
+  const pi = {
+    on: (event: string, handler: Handler) => {
+      handlers.set(event, handler);
+    },
+    sendMessage: (message: SentMessage) => {
+      sent.push(message);
+    },
+    registerMcpServer: () => {},
+  };
+  createSwarmHooksExtension(config)(pi as unknown as Parameters<ExtensionFactory>[0]);
+  const ctx = { getContextUsage: () => undefined };
+  const fire = (event: string, payload: unknown = {}) => {
+    const handler = handlers.get(event);
+    if (!handler) throw new Error(`no handler for ${event}`);
+    return handler({ type: event, ...(payload as object) }, ctx);
+  };
+  const texts = () =>
+    sent.map((m) => {
+      expect(m.customType).toBe(SWARM_NUDGE_CUSTOM_TYPE);
+      return m.content.map((c) => c.text).join("");
+    });
+  return { fire, texts };
+}
+
+function jsonResponse(body: unknown): FetchHandlerResp {
+  return { ok: true, status: 200, text: async () => "", json: async () => body };
+}
+
+describe("createSwarmHooksExtension nudges", () => {
+  test("loop warning on tool_call is sent to the model", async () => {
+    const config = { ...makeConfig(), taskId: `task-pi-loop-${crypto.randomUUID()}` };
+    const { fire, texts } = loadExtension(config);
+    try {
+      for (let i = 0; i < 8; i++) {
+        const result = await fire("tool_call", { toolName: "bash", input: { command: "ls" } });
+        expect(result).toBeUndefined();
+      }
+      const warnings = texts().filter((t) => t.startsWith("Warning: "));
+      expect(warnings.length).toBe(1);
+      expect(warnings[0]).toContain("bash");
+    } finally {
+      await clearToolHistory(config.taskId);
+    }
+  });
+
+  test("lead send-task reminder on tool_result is sent to the model", async () => {
+    const { fire, texts } = loadExtension({ ...makeConfig(), isLead: true });
+    await fire("tool_result", { toolName: "mcp__agent-swarm__send-task", input: {} });
+    expect(texts()).toEqual([
+      "Task sent successfully. Monitor progress using the get-task-details tool periodically.",
+    ]);
+  });
+
+  test("lead concurrent context on session_start is sent to the model", async () => {
+    fetchHandler = async (url) =>
+      url.includes("/api/concurrent-context")
+        ? jsonResponse({
+            processingInboxMessages: [
+              { content: "deploy the thing", source: "slack", createdAt: "now" },
+            ],
+            recentTaskDelegations: [],
+            activeSwarmTasks: [],
+          })
+        : jsonResponse({});
+    const { fire, texts } = loadExtension({ ...makeConfig(), isLead: true });
+    await fire("session_start");
+    expect(texts().length).toBe(1);
+    expect(texts()[0]).toContain("=== CONCURRENT SESSION AWARENESS ===");
+    expect(texts()[0]).toContain("deploy the thing");
+  });
+
+  test("goal reminder is sent after compaction, not before every LLM call", async () => {
+    fetchHandler = async (url) =>
+      url.endsWith("/api/tasks/task-pi-1")
+        ? jsonResponse({ id: "task-pi-1", task: "ship the fix", progress: "tests green" })
+        : jsonResponse({});
+    const { fire, texts } = loadExtension(makeConfig());
+
+    await fire("context", { messages: [] });
+    expect(texts()).toEqual([]);
+
+    await fire("session_compact");
+    expect(texts()).toEqual([
+      [
+        "=== GOAL REMINDER (injected before context compaction) ===",
+        "Task ID: task-pi-1",
+        "Task: ship the fix",
+        "Current Progress: tests green",
+        "=== Continue working on this task after compaction ===",
+      ].join("\n"),
+    ]);
+  });
+
+  test("cancelled task on input skips the turn and leaves the nudge in the session", async () => {
+    fetchHandler = async (url) =>
+      url.includes("/cancelled-tasks")
+        ? jsonResponse({ cancelled: [{ id: "task-pi-1", failureReason: "lead stopped it" }] })
+        : jsonResponse({});
+    const { fire, texts } = loadExtension(makeConfig());
+    const result = await fire("input", { text: "go", source: "rpc" });
+    expect(result).toEqual({ action: "handled" });
+    expect(texts()).toEqual([
+      "🛑 TASK CANCELLED: lead stopped it. Stop working and use store-progress to acknowledge.",
+    ]);
+  });
+});

package/src/tests/pricing-refresh.test.ts

@@ -2,8 +2,9 @@ import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test
 import { unlink } from "node:fs/promises";
 import { closeDb, getActivePricingRow, getDbClient, getLogsByEventType, initDb } from "../be/db";
 import { getModelsCatalog, resetModelsCatalogForTests } from "../be/models-catalog";
-import type { ModelsDevCache } from "../be/modelsdev-cache";
+import { loadModelsDevCache, type ModelsDevCache } from "../be/modelsdev-cache";
 import { refreshPricingFromModelsDev } from "../be/pricing-refresh";
+import { buildModelsDevSeedRows, buildPricingSeedRows } from "../be/seed-pricing";
 
 const TEST_DB_PATH = "./test-pricing-refresh.sqlite";
 
@@ -201,6 +202,74 @@ describe("models.dev runtime pricing refresh", () => {
     expect(rows.map((row) => row.effective_from)).toEqual([2_000, 3_000]);
   });
 
+  test("refreshes when dated snapshots collapse onto one amp key at different prices", async () => {
+    // models.dev's live gpt-4o family. Amp strips the dated suffix, so all four
+    // land on amp|gpt-4o; the 2024-05-13 snapshot is priced higher. Its key
+    // comes first, as upstream serves it, so a first-wins builder would pick it.
+    const cache: ModelsDevCache = {
+      openai: {
+        models: {
+          "gpt-4o-2024-05-13": { cost: { input: 5, output: 15 } },
+          "gpt-4o": { cost: { input: 2.5, output: 10, cache_read: 1.25 } },
+          "gpt-4o-2024-08-06": { cost: { input: 2.5, output: 10, cache_read: 1.25 } },
+          "gpt-4o-2024-11-20": { cost: { input: 2.5, output: 10, cache_read: 1.25 } },
+        },
+      },
+    };
+
+    const result = await refreshPricingFromModelsDev({
+      now: 1_000,
+      fetchImpl: async () => responseFor(cache, '"etag-collapse"'),
+    });
+
+    expect(result.status).toBe("refreshed");
+    expect(await getLogsByEventType("pricing.refresh.failed")).toHaveLength(0);
+    // The undated alias wins every token class.
+    expect((await getActivePricingRow("amp", "gpt-4o", "input", 1_000))?.pricePerMillionUsd).toBe(
+      2.5,
+    );
+    expect((await getActivePricingRow("amp", "gpt-4o", "output", 1_000))?.pricePerMillionUsd).toBe(
+      10,
+    );
+    expect(
+      (await getActivePricingRow("amp", "gpt-4o", "cached_input", 1_000))?.pricePerMillionUsd,
+    ).toBe(1.25);
+    // Providers that keep the dated id still price each snapshot on its own.
+    expect(
+      (await getActivePricingRow("codex", "gpt-4o-2024-05-13", "input", 1_000))?.pricePerMillionUsd,
+    ).toBe(5);
+  });
+
+  test("picks the newest dated snapshot when no undated alias exists", () => {
+    const rows = buildModelsDevSeedRows({
+      openai: {
+        models: {
+          "gpt-x-2025-08-07": { cost: { input: 2, output: 8 } },
+          "gpt-x-2025-01-01": { cost: { input: 1, output: 4 } },
+        },
+      },
+    }).filter((row) => row.provider === "amp");
+
+    expect(rows).toEqual([
+      { provider: "amp", model: "gpt-x", tokenClass: "input", pricePerMillionUsd: 2 },
+      { provider: "amp", model: "gpt-x", tokenClass: "output", pricePerMillionUsd: 8 },
+    ]);
+  });
+
+  test("the vendored models.dev snapshot yields one row per (provider, model, tokenClass)", () => {
+    const cache = loadModelsDevCache();
+    expect(cache).not.toBeNull();
+    const rows = buildPricingSeedRows(cache);
+    const seen = new Set<string>();
+    const duplicates: string[] = [];
+    for (const row of rows) {
+      const key = `${row.provider}|${row.model}|${row.tokenClass}`;
+      if (seen.has(key)) duplicates.push(key);
+      seen.add(key);
+    }
+    expect(duplicates).toEqual([]);
+  });
+
   test("writes scrubbed audit log entries for successful refreshes", async () => {
     await refreshPricingFromModelsDev({
       now: 1_000,

package/src/tests/reasoning-effort.test.ts

@@ -305,7 +305,9 @@ describe("Claude CLI shortnames (the tier defaults) take effort like the model t
     expect(reasoningCapability("claude", "sonnet")).toEqual(
       reasoningCapability("claude", "claude-sonnet-5-5"),
     );
-    expect(reasoningCapability("claude", "haiku").levels).toContain("off");
+    expect(reasoningCapability("claude", "haiku")).toEqual(
+      reasoningCapability("claude", "claude-haiku-5-5"),
+    );
     expect(reasoningCapability("claude", "fable").supported).toBe(true);
   });
 

package/src/tests/telemetry-trigger.test.ts

@@ -127,7 +127,18 @@ describe("trigger_surface on task telemetry", () => {
   // so each one is run for real and judged on the row it persists and the
   // task.created event it emits.
   const heartbeatCreators: Array<{ taskType: string; create: () => Promise<void> }> = [
-    { taskType: "boot-triage", create: createBootTriageTask },
+    {
+      taskType: "boot-triage",
+      create: async () => {
+        // A clean boot creates no task; force one to judge its source.
+        process.env.HEARTBEAT_BOOT_TRIAGE_ALWAYS = "true";
+        try {
+          await createBootTriageTask();
+        } finally {
+          delete process.env.HEARTBEAT_BOOT_TRIAGE_ALWAYS;
+        }
+      },
+    },
     {
       taskType: "heartbeat-checklist",
       create: async () => {

package/src/tests/workflow-llm.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { DEFAULT_MODEL } from "../utils/internal-ai/models";
+import { OPENROUTER_APP_ATTRIBUTION_HEADERS } from "../utils/openrouter-base-url";
 import { resolveWorkflowLlmConfig } from "../workflows/executors/workflow-llm";
 
 describe("resolveWorkflowLlmConfig", () => {
@@ -12,10 +13,22 @@ describe("resolveWorkflowLlmConfig", () => {
     expect(config).toEqual({
       apiKey: "sk-or-test",
       baseURL: "https://gateway.example.test/v1",
+      headers: {},
       model: "deepseek/deepseek-v4.1-flash",
     });
   });
 
+  test("attributes direct openrouter.ai calls unless OPENROUTER_APP_ATTRIBUTION is off", async () => {
+    const direct = await resolveWorkflowLlmConfig(undefined, { OPENROUTER_API_KEY: "sk-or-test" });
+    expect(direct.headers).toEqual(OPENROUTER_APP_ATTRIBUTION_HEADERS);
+
+    const optedOut = await resolveWorkflowLlmConfig(undefined, {
+      OPENROUTER_API_KEY: "sk-or-test",
+      OPENROUTER_APP_ATTRIBUTION: "false",
+    });
+    expect(optedOut.headers).toEqual({});
+  });
+
   test("routes OpenAI credentials to the SDK default endpoint", async () => {
     const config = await resolveWorkflowLlmConfig(undefined, {
       OPENAI_API_KEY: "example-sk-openai-test",
@@ -24,6 +37,7 @@ describe("resolveWorkflowLlmConfig", () => {
     expect(config).toEqual({
       apiKey: "example-sk-openai-test",
       baseURL: undefined,
+      headers: {},
       model: "gpt-6-luna",
     });
   });

package/src/tests/workflow-system-one-decision-providers.test.ts

@@ -734,4 +734,37 @@ describe("system-one-decision SystemOne wire is unchanged", () => {
       expect(calls[0]?.raw).toBe(expected);
     }
   });
+
+  test("only the openrouter.ai provider carries OpenRouter app attribution", async () => {
+    const referer = async (provider: string, env: Record<string, string>) => {
+      const { executor, calls } = makeExecutor(
+        [
+          jsonResponse({
+            model: "jev",
+            answers: systemOneAnswers,
+            usage: { input_tokens: 1, output_tokens: 0 },
+          }),
+        ],
+        {
+          getApiKey: async () => OPENAI_KEY,
+          getServerUrl: async () => "https://laya.example.test",
+          env: { OPENROUTER_API_KEY: OPENAI_KEY, ...env },
+        },
+      );
+      await run(executor, { ...config({ model: "jev-1.13.0" }), provider });
+      const headers = new Headers(calls[0]?.init.headers);
+      return [headers.get("http-referer"), headers.get("x-openrouter-categories")];
+    };
+    expect(await referer("openrouter", {})).toEqual([
+      "https://agent-swarm.dev",
+      "personal-agent,cloud-agent",
+    ]);
+    expect(await referer("openrouter", { OPENROUTER_APP_ATTRIBUTION: "false" })).toEqual([
+      null,
+      null,
+    ]);
+    for (const provider of ["typesafe", "laya"]) {
+      expect(await referer(provider, {})).toEqual([null, null]);
+    }
+  });
 });

package/src/tools/request-human-input.ts

@@ -12,7 +12,10 @@ const QuestionSchema = z.object({
     .describe("Question type"),
   label: z.string().describe("The question text displayed to the user"),
   required: z.boolean().optional().describe("Whether this question is required (default: true)"),
-  description: z.string().optional().describe("Optional help text"),
+  description: z
+    .string()
+    .optional()
+    .describe("Optional help text, rendered as markdown (code fences, images)"),
   placeholder: z.string().optional().describe("Placeholder text (for text type)"),
   multiline: z.boolean().optional().describe("Use textarea instead of input (for text type)"),
   options: z
@@ -39,7 +42,9 @@ export const registerRequestHumanInputTool = (server: McpServer) => {
       description:
         "Create an approval request and return at once with the request id and URL. The answer arrives later as a hitl-follow-up task. " +
         "Supports multiple question types: approval (yes/no), text, single-select, " +
-        "multi-select, and boolean. Returns the request ID and URL for the human to respond.",
+        "multi-select, and boolean. Returns the request ID and URL for the human to respond. " +
+        "The dashboard renders each label and description as markdown: put long content in description, fence code with a language, and put an image URL alone on its own line to show it. " +
+        "No Slack message is sent; share the URL yourself.",
       inputSchema: z.object({
         title: z.string().min(1).describe("Title of the approval request"),
         questions: z.array(QuestionSchema).min(1).describe("Questions to ask the human"),

package/src/utils/enabled-tools.ts

@@ -0,0 +1,27 @@
+/**
+ * Parse the `SWARM_ENABLED_TOOLS` MCP tool allowlist.
+ *
+ * Accepts a comma-separated list (`get-tasks, store-progress`) or a JSON array
+ * of strings. Returns `undefined` when the value is unset, blank, or holds no
+ * entries, so callers keep the capability-driven surface. Throws on a JSON
+ * array that does not parse to strings.
+ */
+export function parseEnabledTools(value: string | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+
+  let entries: string[];
+  if (trimmed.startsWith("[")) {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (!Array.isArray(parsed) || !parsed.every((entry) => typeof entry === "string")) {
+      throw new Error("Expected a JSON array of tool names");
+    }
+    entries = parsed;
+  } else {
+    entries = trimmed.split(",");
+  }
+
+  const tools = [...new Set(entries.map((entry) => entry.trim()).filter(Boolean))];
+  return tools.length > 0 ? tools : undefined;
+}

package/src/utils/internal-ai/complete-structured.ts

@@ -20,7 +20,11 @@ import { complete } from "@earendil-works/pi-ai/compat";
 import { getBuiltinModel as getModel } from "@earendil-works/pi-ai/providers/all";
 import type { TSchema } from "typebox";
 import { z } from "zod";
-import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../openrouter-base-url.js";
+import {
+  DEFAULT_OPENROUTER_BASE_URL,
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../openrouter-base-url.js";
 import { scrubSecrets } from "../secret-scrubber.js";
 import { type ResolvedCredential, resolveCredential } from "./credentials.js";
 import { parseModelStr } from "./models.js";
@@ -319,10 +323,14 @@ export async function completeStructuredWithModel<TZod extends z.ZodTypeAny>(
   // through a gateway (pi-ai's stream path uses `model.baseUrl` verbatim).
   // Resolved from the caller's session env when provided — swarm_config
   // overlays don't reach `process.env`.
-  const openRouterBaseUrl = getOpenRouterBaseUrl((opts.env ?? process.env) as NodeJS.ProcessEnv);
+  const env = opts.env ?? process.env;
+  const openRouterBaseUrl = getOpenRouterBaseUrl(env as NodeJS.ProcessEnv);
   if (provider === "openrouter" && openRouterBaseUrl !== DEFAULT_OPENROUTER_BASE_URL) {
     model = { ...model, baseUrl: openRouterBaseUrl };
   }
+  // pi-ai merges `options.headers` over the provider defaults.
+  const headers =
+    provider === "openrouter" ? getOpenRouterAttributionHeaders(model.baseUrl, env) : {};
 
   const completeFn = opts._complete ?? complete;
   const toolChoice =
@@ -348,7 +356,7 @@ export async function completeStructuredWithModel<TZod extends z.ZodTypeAny>(
         },
         // pi-ai's ProviderStreamOptions type only allows known providers;
         // we pass the validated apiKey through verbatim.
-        { apiKey: cred.apiKey, signal: opts.signal, toolChoice } as Parameters<
+        { apiKey: cred.apiKey, signal: opts.signal, toolChoice, headers } as Parameters<
           typeof completeFn
         >[2],
       );

package/src/utils/openrouter-base-url.ts

@@ -26,3 +26,26 @@ export function getOpenRouterBaseUrl(env: NodeJS.ProcessEnv = process.env): stri
   }
   return DEFAULT_OPENROUTER_BASE_URL;
 }
+
+export const OPENROUTER_APP_ATTRIBUTION_HEADERS = {
+  "HTTP-Referer": "https://agent-swarm.dev",
+  "X-OpenRouter-Title": "Agent Swarm",
+  "X-OpenRouter-Categories": "personal-agent,cloud-agent",
+} as const;
+
+/** Attribute direct OpenRouter requests unless the task opts out. */
+export function getOpenRouterAttributionHeaders(
+  url: string,
+  env: Record<string, string | undefined> = process.env,
+): Record<string, string> {
+  const enabled = env.OPENROUTER_APP_ATTRIBUTION?.toLowerCase();
+  if (enabled === "false" || enabled === "0") return {};
+  try {
+    const host = new URL(url).hostname;
+    return host === "openrouter.ai" || host.endsWith(".openrouter.ai")
+      ? { ...OPENROUTER_APP_ATTRIBUTION_HEADERS }
+      : {};
+  } catch {
+    return {};
+  }
+}

package/src/workflows/executors/raw-llm.ts

@@ -32,6 +32,7 @@ export async function executeRawLlm(
     const provider = createOpenAI({
       baseURL: llmConfig.baseURL,
       apiKey: llmConfig.apiKey,
+      headers: llmConfig.headers,
     });
     const model = provider(llmConfig.model);
 

package/src/workflows/executors/system-one-decision.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ExecutorMeta } from "../../types";
+import { getOpenRouterAttributionHeaders } from "../../utils/openrouter-base-url";
 import { scrubSecrets } from "../../utils/secret-scrubber";
 import {
   type ApprovalOutcome,
@@ -1170,6 +1171,7 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
       res = await doFetch(endpoint, {
         method: "POST",
         headers: {
+          ...getOpenRouterAttributionHeaders(endpoint, this.providerContext().env),
           "content-type": "application/json",
           accept: "application/json",
           authorization: `Bearer ${apiKey}`,

package/src/workflows/executors/validate.ts

@@ -119,6 +119,7 @@ export class ValidateExecutor extends BaseExecutor<
       const provider = createOpenAI({
         baseURL: llmConfig.baseURL,
         apiKey: llmConfig.apiKey,
+        headers: llmConfig.headers,
       });
 
       const { object } = await generateObject({

package/src/workflows/executors/workflow-llm.ts

@@ -1,9 +1,14 @@
 import { DEFAULT_MODEL, resolveCredential } from "../../utils/internal-ai/credentials";
-import { getOpenRouterBaseUrl } from "../../utils/openrouter-base-url";
+import {
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../../utils/openrouter-base-url";
 
 export interface WorkflowLlmConfig {
   apiKey: string;
   baseURL?: string;
+  /** OpenRouter app attribution; empty for OpenAI and for gateway base URLs. */
+  headers: Record<string, string>;
   model: string;
 }
 
@@ -39,9 +44,11 @@ export async function resolveWorkflowLlmConfig(
   // Workflow defaults are provider-owned; MEMORY_RATER_MODEL only configures memory work.
   const model = requestedModel ?? DEFAULT_MODEL[credential.kind];
 
+  const baseURL = credential.kind === "openrouter" ? getOpenRouterBaseUrl(env) : undefined;
   return {
     apiKey: credential.apiKey,
-    baseURL: credential.kind === "openrouter" ? getOpenRouterBaseUrl(env) : undefined,
+    baseURL,
+    headers: baseURL ? getOpenRouterAttributionHeaders(baseURL, env) : {},
     model: model.startsWith(providerPrefix) ? model.slice(providerPrefix.length) : model,
   };
 }

package/templates/skills/agent-browser/SKILL.md

@@ -47,6 +47,8 @@ agent-browser close
 
 ## Recording
 
+Pass `record start` an absolute path (`/tmp/<topic>/raw.webm`). A relative path resolves against the agent-browser daemon's cwd, not yours, and fails with `ffmpeg write failed: Broken pipe` while `doctor` stays green.
+
 Default: record with `--cursor`, drive every supported pointer action (`click`, `mouse move`, `drag`) with `--human`, and ship the **1.5x video**. Keep the 1x original only if a reviewer asks for it. Human pointer movement follows an eased curve; use `--seed <n>` on `mouse move` to make the take reproducible instead of using a bare move.
 
 Open the page first, then record the interaction:

package/templates/skills/agent-browser/content.md

@@ -42,6 +42,8 @@ agent-browser close
 
 ## Recording
 
+Pass `record start` an absolute path (`/tmp/<topic>/raw.webm`). A relative path resolves against the agent-browser daemon's cwd, not yours, and fails with `ffmpeg write failed: Broken pipe` while `doctor` stays green.
+
 Default: record with `--cursor`, drive every supported pointer action (`click`, `mouse move`, `drag`) with `--human`, and ship the **1.5x video**. Keep the 1x original only if a reviewer asks for it. Human pointer movement follows an eased curve; use `--seed <n>` on `mouse move` to make the take reproducible instead of using a bare move.
 
 Open the page first, then record the interaction:

package/templates/skills/code-quality/content.md

@@ -38,6 +38,7 @@ The Repository Guidelines carry `allowMerge` and `mergeChecks`.
 
 ## Review a PR
 
+0. Re-review check. If you reviewed this PR before, compare `gh pr view <number> --json headRefOid --jq .headRefOid` with the `commit_id` of your last review (`gh api repos/<owner>/<repo>/pulls/<number>/reviews`). Same SHA: reuse that verdict, link it and stop. New SHA: review the diff since that commit, then run the full list below. If the new head merged or rebased main, also read every conflict resolution (files both sides touched), check migration numbering and order against main, grep for stale migration numbers, and confirm CI is green at the exact head you review.
 1. CI status first, including the fork checks below before treating CI as evidence. Failing CI is a REQUEST_CHANGES. Name the failing checks in the review.
 2. Detect a GitHub fork PR with `gh pr view <number> --json isCrossRepository --jq .isCrossRepository`.
 3. For a GitHub fork PR, inspect held runs with `SHA=$(gh pr view <number> --json headRefOid --jq .headRefOid); gh api --paginate "repos/<owner>/<repo>/actions/runs?head_sha=$SHA" --jq '.workflow_runs[] | "\(.conclusion // .status)|\(.name)"'`; `gh pr checks` and `statusCheckRollup` can omit them.

package/templates/skills/heartbeat-runbook/content.md

@@ -27,7 +27,7 @@ Two kinds of sections:
 
 ## Handle a heartbeat-checklist task
 
-0. Quiet check. Take the fast path when three things hold: the system status shows no failed, stalled or reboot-interrupted task; no mention has gone unanswered since the last heartbeat; and no tracked item in the task's runbook snapshot is at or past its date. On the fast path, run the two step 3 scripts. If both are clean, complete with one line that names the zero counts and skip steps 1, 2 and 4-7. Anything non-zero means continue at step 1.
+0. Quiet check. Take the fast path when three things hold: every failed, stalled or reboot-interrupted task in the system status was already named in the previous heartbeat-checklist task's output (newest completed one via `get-tasks`); no mention has gone unanswered since the last heartbeat; and no tracked item in the task's runbook snapshot is at or past its date. On the fast path, run the two step 3 scripts. If they report nothing the previous heartbeat had not already triaged, complete with one line citing the previous heartbeat task id and the counts, and skip steps 1, 2 and 4-7. Anything new means continue at step 1.
 1. Read the latest runbook. The snapshot in the task may be stale.
 2. Prune first. Check every tracked item against its lift trigger. Remove resolved, stale, and past-date items.
 3. Run the seeded scripts: `script-run` with name `schedule-health`, then `task-failure-audit`, both with `args: { days: 1, publishPage: false }`. They report failing schedules and failure clusters. Check any other standing order in the runbook yourself.

package/templates/skills/work-on-task/SKILL.md

@@ -13,4 +13,8 @@ When the task names a skill (`researching`, `planning`, `implementing`), use it.
 
 Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
 
+Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push.
+
+Write times in replies, outputs and defer notes in the requester's timezone when the Requester Profile names one, never raw UTC.
+
 If the user interrupts, follow their instructions. To resume, call `/work-on-task <taskId>` again.

package/templates/skills/work-on-task/content.md

@@ -8,4 +8,8 @@ When the task names a skill (`researching`, `planning`, `implementing`), use it.
 
 Finish the task with one of the four endings in your operating contract: `completed`, `defer-task`, `request-human-input`, or `failed`. Then stop.
 
+Resuming (a resume task, or work cut by a graceful shutdown): read the parent's last progress line, then re-read live state once (PR state and head SHA, branch, `git status`) before new work. Re-run controls only if the head moved. Never redo a pushed commit or open a second PR for the same branch. Store a progress line with branch, PR number and head SHA each time you push.
+
+Write times in replies, outputs and defer notes in the requester's timezone when the Requester Profile names one, never raw UTC.
+
 If the user interrupts, follow their instructions. To resume, call `/work-on-task <taskId>` again.

package/templates/skills/workflow-iterate/content.md

@@ -173,6 +173,15 @@ Afterwards, a `warnings` entry on `create-workflow` or a patch tool means the ke
 - Do not set `retry` or `validation.retry` on a `system-one-decision` node. It retries connection errors, 408, 429, and 5xx itself (`config.maxRetries`, 0 to 3, default 2) inside `config.timeoutMs` (default 30000). A 401, a 422, or an answer that fails validation ends after one attempt.
 - The node reads its provider's key (`TYPESAFE_API_KEY`, `OPENROUTER_API_KEY`, `LAYA_API_KEY`, `OPENAI_DECISIONS_API_KEY`, or `CLOUDFLARE_API_TOKEN`, plus `LAYA_URL` for `laya` and `CLOUDFLARE_ACCOUNT_ID` for `cloudflare`) server-side. The key never appears in the definition, the step output, or an error. A run whose key or `LAYA_URL` is missing fails before any node executes, and a 401 or 403 fails the step as `<KEY> was rejected`. An unresolved `{{token}}` fails the step before any request.
 
+### `human-in-the-loop` (how approvals render)
+
+The same rules apply to a standalone `request-human-input` call.
+
+- **Dashboard card.** `title` is plain text. Each question's `label` is its heading and renders as markdown. `description` renders as full markdown and is the only field that shows images, so put drafts, diffs, and logs there.
+- **Code.** Fence code, logs, and JSON with a language (```` ```json ````): the block keeps its lines and scrolls. Fence a prose draft with no language: it wraps. A single newline outside a fence becomes a paragraph break.
+- **Images.** Put an `http(s)` URL ending in `.png`, `.jpg`, `.jpeg`, `.gif`, or `.webp` alone on its own line in `description`, or use `![alt](url)`. The link must outlive the request: an expired presigned URL shows an "image unavailable" note.
+- **Slack.** A node's `notifications` post the title, the question labels (each collapsed to one line, capped at 3000 characters in total), a Review button, and the timeout. Descriptions, options, code, and images are not shown, so the title and labels must make sense alone. `request-human-input` posts nothing to Slack: share the returned URL yourself.
+
 ### `swarm-script`
 
 ```json