@desplega.ai/agent-swarm 1.75.0 → 1.76.0

package/src/be/memory/raters/llm-summarizer.ts

@@ -0,0 +1,218 @@
+/**
+ * `runMemoryRater` — Stop-hook helper that calls OpenRouter for the combined
+ * session-summary + LLM-rater piggyback prompt and returns a schema-validated
+ * `SummaryWithRatings`.
+ *
+ * Refactored out of `src/hooks/hook.ts` so the rater logic stays out of the
+ * hook (review feedback on PR #450). The hook just calls `runMemoryRater(...)`
+ * and inspects the typed result.
+ *
+ * Worker-safe — uses raw `fetch` + the tolerant JSON parser landed in PR #447.
+ * No `bun:sqlite` / `src/be/db` imports. Boundary script enforces this.
+ */
+import { z } from "zod";
+import { type SummaryWithRatings, SummaryWithRatingsSchema } from "./llm";
+
+/**
+ * Default model used when `MEMORY_RATER_MODEL` is unset. Gemini 3 Flash on
+ * OpenRouter — the only Gemini 3 Flash variant published as of this PR (no
+ * stable non-preview slug exists yet). CLAUDE.md project-wide default.
+ */
+export const DEFAULT_MEMORY_RATER_MODEL = "google/gemini-3-flash-preview";
+
+/**
+ * `response_format.json_schema.name` sent to OpenRouter. Used by some
+ * providers as a tag in their structured-output telemetry — keep it stable
+ * so model behaviour stays comparable across calls.
+ */
+export const MEMORY_RATER_SCHEMA_NAME = "memory_rater_output";
+
+const OPENROUTER_CHAT_COMPLETIONS_URL = "https://openrouter.ai/api/v1/chat/completions";
+
+/**
+ * JSON Schema derived from {@link SummaryWithRatingsSchema}, the source of
+ * truth. Computed once at module load via Zod v4's native `z.toJSONSchema`
+ * (Zod v3's `zod-to-json-schema` is incompatible with the v4 runtime we
+ * pin). The `$schema` key is stripped because OpenRouter / OpenAI strict
+ * json_schema mode rejects unrecognized top-level keys.
+ *
+ * Probed end-to-end against `google/gemini-3-flash-preview` with
+ * `response_format.json_schema.strict: true` — accepted, no rewrite needed.
+ */
+export const MEMORY_RATER_JSON_SCHEMA: Record<string, unknown> = (() => {
+  const schema = z.toJSONSchema(SummaryWithRatingsSchema) as Record<string, unknown>;
+  delete schema.$schema;
+  return schema;
+})();
+
+/**
+ * Resolve the OpenRouter model slug. Reads `MEMORY_RATER_MODEL` from the env;
+ * falls back to {@link DEFAULT_MEMORY_RATER_MODEL}. Self-hosters can pin a
+ * different slug (e.g. `anthropic/claude-haiku-4.5`) without a code change.
+ */
+export function getMemoryRaterModel(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = env.MEMORY_RATER_MODEL;
+  if (typeof raw === "string" && raw.trim().length > 0) return raw.trim();
+  return DEFAULT_MEMORY_RATER_MODEL;
+}
+
+/**
+ * Best-effort parse of a JSON string that may be wrapped in markdown fences
+ * (```json … ``` or plain ``` … ```), have a prose preamble, or both. Returns
+ * the parsed value or `null`. NEVER throws.
+ *
+ * Strategy: try strict parse first. On failure, strip a leading ```json /
+ * ```<lang> / ``` fence + matching trailing ```; on second failure, slice
+ * from the first `{` to the last `}` and retry.
+ *
+ * Originally landed in PR #447 to recover ratings from Haiku's occasional
+ * fenced/preambled output despite `response_format: {type: "json_object"}`.
+ * Restored here to harden the OpenRouter direct-HTTP path against the same
+ * class of provider quirks (Gemini Flash also occasionally fences output).
+ */
+export function tryParseLooseJson(raw: string): unknown {
+  const trimmed = raw.trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // fall through to fence-stripping
+  }
+  const fenced = trimmed.match(/^```[a-zA-Z0-9_-]*\s*\n?([\s\S]*?)\n?```\s*$/);
+  if (fenced?.[1]) {
+    try {
+      return JSON.parse(fenced[1].trim());
+    } catch {
+      // fall through
+    }
+  }
+  const first = trimmed.indexOf("{");
+  const last = trimmed.lastIndexOf("}");
+  if (first !== -1 && last > first) {
+    try {
+      return JSON.parse(trimmed.slice(first, last + 1));
+    } catch {
+      // fall through
+    }
+  }
+  return null;
+}
+
+export type RunMemoryRaterOpts = {
+  /** The fully-built prompt (e.g. from `buildSummaryWithRatingsPrompt`). */
+  prompt: string;
+  /** OpenRouter API key. Caller is responsible for the no-op-when-unset gate. */
+  apiKey: string;
+  /** Model slug override; falls through to {@link getMemoryRaterModel}. */
+  model?: string;
+  /** Injectable for tests — defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /**
+   * Bytes to keep when logging unexpected response payloads. Capped to avoid
+   * leaking very large bodies into stderr.
+   */
+  responseLogCap?: number;
+};
+
+export type RunMemoryRaterResult =
+  | { ok: true; data: SummaryWithRatings; model: string }
+  | {
+      ok: false;
+      reason: "transport" | "http_error" | "empty_content" | "parse" | "schema";
+      status?: number;
+    };
+
+/**
+ * Call OpenRouter's chat completions endpoint with `response_format` =
+ * `json_object`, then parse and schema-validate the assistant's content.
+ *
+ * Returns a tagged union: `ok: true` with a typed `SummaryWithRatings`, or
+ * `ok: false` with a `reason` discriminator the caller can branch on for
+ * logging. NEVER throws — the hook wraps this in its own try/catch as a
+ * second line of defence, but this function is designed to short-circuit
+ * cleanly rather than propagate exceptions.
+ */
+export async function runMemoryRater(opts: RunMemoryRaterOpts): Promise<RunMemoryRaterResult> {
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const model = opts.model ?? getMemoryRaterModel();
+  const responseLogCap = opts.responseLogCap ?? 200;
+
+  let res: Response;
+  try {
+    res = await fetchFn(OPENROUTER_CHAT_COMPLETIONS_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${opts.apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        // OpenRouter strict json_schema — forces the provider's structured-
+        // output guardrails on instead of the looser `json_object` mode.
+        // Schema is derived from the same Zod source of truth, so the
+        // request and the post-validation Zod check can't drift.
+        // https://openrouter.ai/docs/guides/features/structured-outputs
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            name: MEMORY_RATER_SCHEMA_NAME,
+            strict: true,
+            schema: MEMORY_RATER_JSON_SCHEMA,
+          },
+        },
+        messages: [{ role: "user", content: opts.prompt }],
+      }),
+    });
+  } catch (err) {
+    console.error("[memory-rater:llm] runMemoryRater fetch threw:", (err as Error).message);
+    return { ok: false, reason: "transport" };
+  }
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    console.error(
+      `[memory-rater:llm] OpenRouter ${res.status} ${res.statusText}: ${text.slice(0, responseLogCap)}`,
+    );
+    return { ok: false, reason: "http_error", status: res.status };
+  }
+
+  let body: unknown;
+  try {
+    body = await res.json();
+  } catch (err) {
+    console.error("[memory-rater:llm] OpenRouter response was not JSON:", (err as Error).message);
+    return { ok: false, reason: "parse" };
+  }
+
+  const content = extractContent(body);
+  if (typeof content !== "string" || content.length === 0) {
+    return { ok: false, reason: "empty_content" };
+  }
+
+  const candidate = tryParseLooseJson(content);
+  if (candidate === null || typeof candidate !== "object") {
+    return { ok: false, reason: "parse" };
+  }
+
+  const parsed = SummaryWithRatingsSchema.safeParse(candidate);
+  if (!parsed.success) {
+    return { ok: false, reason: "schema" };
+  }
+  return { ok: true, data: parsed.data, model };
+}
+
+/**
+ * Pull `choices[0].message.content` out of an OpenRouter chat-completion
+ * response defensively. Returns the string, or `null` when the shape doesn't
+ * match — caller treats that as `empty_content`.
+ */
+function extractContent(body: unknown): string | null {
+  if (!body || typeof body !== "object") return null;
+  const choices = (body as { choices?: unknown }).choices;
+  if (!Array.isArray(choices) || choices.length === 0) return null;
+  const first = choices[0];
+  if (!first || typeof first !== "object") return null;
+  const message = (first as { message?: unknown }).message;
+  if (!message || typeof message !== "object") return null;
+  const content = (message as { content?: unknown }).content;
+  return typeof content === "string" ? content : null;
+}

package/src/be/memory/raters/llm.ts

@@ -193,7 +193,9 @@ export function buildSummaryWithRatingsPrompt(
 
   return `${basePrompt}
 
-CRITICAL: Return JSON conforming to this schema (no prose outside the JSON, no markdown fences):
+CRITICAL: Your entire response MUST be a single JSON object that conforms to the schema below. Do NOT wrap it in triple-backtick fences (no \`\`\`json or \`\`\`), do NOT add a prose preamble, do NOT add trailing commentary. Just the JSON object, nothing else.
+
+Schema:
 {
   "summary": string,                        // your existing summary text
   "ratings": [                              // one entry per memory you can score
@@ -215,80 +217,6 @@ Memories retrieved during this session:
 ${memoryBlock}`;
 }
 
-/**
- * Best-effort parse of the structured `SummaryWithRatingsSchema` JSON out of
- * the `claude -p --output-format json` envelope (`{ result: "<inner json>" }`).
- *
- * Returns `null` on any parse failure — the caller falls back to the existing
- * summary-only path. NEVER throws.
- */
-export function parseSummaryWithRatings(claudeStdout: string): SummaryWithRatings | null {
-  let envelope: { result?: unknown };
-  try {
-    envelope = JSON.parse(claudeStdout) as { result?: unknown };
-  } catch {
-    return null;
-  }
-  const inner = envelope.result;
-  let candidate: unknown;
-  if (typeof inner === "string") {
-    try {
-      candidate = JSON.parse(inner.trim());
-    } catch {
-      return null;
-    }
-  } else if (inner && typeof inner === "object") {
-    candidate = inner;
-  } else {
-    return null;
-  }
-  const parsed = SummaryWithRatingsSchema.safeParse(candidate);
-  return parsed.success ? parsed.data : null;
-}
-
-/**
- * Fallback summary-text extractor for the hook's `claude -p` envelope. Used
- * when {@link parseSummaryWithRatings} returns null — i.e., when the LLM
- * returned a valid envelope but the inner payload either wasn't structured
- * JSON (unstructured prompt path) OR was structured JSON whose ratings failed
- * `SummaryWithRatingsSchema` validation (e.g., out-of-range scores).
- *
- * In the latter case `envelope.result` is the full inner JSON STRING such as
- * `{"summary":"...","ratings":[...]}`; indexing that verbatim into agent
- * memory would violate the step-4 contract that ratings are best-effort and
- * the existing summary-indexing behavior remains unchanged. We extract the
- * inner `summary` field if present, else return the inner string (treating
- * it as plain summary text). NEVER throws.
- */
-export function extractSummaryFromClaudeStdout(claudeStdout: string): string {
-  let envelope: { result?: unknown };
-  try {
-    envelope = JSON.parse(claudeStdout) as { result?: unknown };
-  } catch {
-    return claudeStdout;
-  }
-  const inner = envelope.result;
-  if (typeof inner === "string") {
-    try {
-      const innerParsed = JSON.parse(inner.trim()) as { summary?: unknown };
-      if (innerParsed && typeof innerParsed.summary === "string") {
-        return innerParsed.summary;
-      }
-    } catch {
-      // inner wasn't JSON — treat it as plain summary text
-    }
-    return inner;
-  }
-  if (
-    inner &&
-    typeof inner === "object" &&
-    typeof (inner as { summary?: unknown }).summary === "string"
-  ) {
-    return (inner as { summary: string }).summary;
-  }
-  return claudeStdout;
-}
-
 /**
  * `MEMORY_RATERS=...` includes `llm`? Used by the hook to gate the piggyback
  * path — strict opt-in so existing deployments are byte-identical when unset.
@@ -308,10 +236,63 @@ export type RetrievalRow = {
   name: string;
   content: string;
   scope?: string;
+  /** `agent_memory.source` — present once the API surfaces it (post-PR #451 amendment). */
+  source?: string;
+  /** `agent_tasks.scheduleId` for the writing task, or null when not a scheduled run. */
+  scheduleId?: string | null;
   similarity?: number | null;
   retrievedAt?: string;
 };
 
+/**
+ * Dedupe candidate memories before LLM rating to prevent posterior inflation
+ * from scheduled-task self-similarity.
+ *
+ * **Why this exists.** Scheduled tasks fire identical task text on every
+ * run, and the task-completion path names each memory
+ * `"Task: ${task.task.slice(0, 80)}"` (`src/tools/store-progress.ts`). When
+ * the next run searches memory, its own past runs surface as "highly
+ * similar" rows. Without dedup, the LLM rater scored 5+ near-clones at +1.0
+ * each — bumping alpha 5x in a single session and distorting the Beta(α,β)
+ * ranking vs. a normal one-shot session. Concrete case (Lead's audit of the
+ * first 37 `llm` ratings, post-PR #450): the Claude Code Changelog Monitor
+ * hourly cron (taskId `f938d74d-05af-44a7-a0aa-3463d22be502`) produced 5
+ * saturating +1s in one rater pass — every rated memory was a prior hourly
+ * run.
+ *
+ * **Discriminator.** `agent_tasks.scheduleId`. Memories sharing a non-null
+ * `scheduleId` are by definition from the same scheduled job — that is the
+ * exact duplicate class the audit identified, and the only one we want to
+ * collapse. We do NOT key on `name` alone, because the 80-char truncation in
+ * task-completion names ("Task: …") and session-summary names ("Session: …")
+ * means two distinct one-shot tasks/summaries that happen to share the first
+ * 80 chars of their description would silently collapse — the false-positive
+ * path the PR #451 reviewer flagged.
+ *
+ * **Pass-through cases (NOT deduped).**
+ *   - `scheduleId` is null/undefined (manual one-shot tasks, manual memories,
+ *     file-index memories) — no scheduled-clone risk.
+ *   - Two memories from different scheduled jobs that happen to surface in
+ *     the same retrieval set — different `scheduleId`s, both kept.
+ *
+ * **Tie-break.** Input is `ORDER BY mr.retrievedAt DESC` from
+ * `getRetrievalsForAgent`, so "first occurrence per scheduleId" = "freshest
+ * surfaced run", which is the representative we want.
+ */
+export function dedupeRetrievalsForRater<T extends { scheduleId?: string | null }>(rows: T[]): T[] {
+  const seenSchedules = new Set<string>();
+  const out: T[] = [];
+  for (const row of rows) {
+    const scheduleId = row.scheduleId;
+    if (typeof scheduleId === "string" && scheduleId.length > 0) {
+      if (seenSchedules.has(scheduleId)) continue;
+      seenSchedules.add(scheduleId);
+    }
+    out.push(row);
+  }
+  return out;
+}
+
 /**
  * GET `/api/memory/retrievals?taskId=` — best-effort. Returns `[]` on any
  * failure so a transient API outage never blocks the summary-indexing path.

package/src/be/memory/retrieval-store.ts

@@ -28,6 +28,20 @@ export type RetrievalListRow = {
   /** Up to RETRIEVAL_CONTENT_SNIPPET_CHARS chars of `agent_memory.content`. */
   content: string;
   scope: string;
+  /**
+   * `agent_memory.source` — `'task_completion' | 'session_summary' | 'manual'
+   * | 'file_index'`. Surfaced so the worker rater can scope dedup to the
+   * memory class that exhibits scheduled-task self-similarity.
+   */
+  source: string;
+  /**
+   * `agent_tasks.scheduleId` for the source task that wrote this memory, or
+   * `null` if the memory has no source task or the task wasn't a scheduled
+   * run. Worker raters use this as a precise cron-clone discriminator —
+   * memories sharing a non-null `scheduleId` are by definition from the same
+   * scheduled job and safe to dedupe.
+   */
+  scheduleId: string | null;
   similarity: number | null;
   retrievedAt: string;
 };
@@ -61,15 +75,22 @@ export function getRetrievalsForAgent(
     params.push(filter.sessionId);
   }
 
+  // LEFT JOIN agent_tasks so we can surface `scheduleId` to worker raters —
+  // a non-null `scheduleId` is the precise cron-clone discriminator that
+  // `dedupeRetrievalsForRater` keys on. The LEFT keeps memories with no
+  // source task (manual / file_index) in the result set.
   const sql = `
     SELECT am.id        AS id,
            am.name      AS name,
            substr(am.content, 1, ?) AS content,
            am.scope     AS scope,
+           am.source    AS source,
+           at.scheduleId AS scheduleId,
            mr.similarity AS similarity,
            mr.retrievedAt AS retrievedAt
       FROM memory_retrieval mr
       INNER JOIN agent_memory am ON am.id = mr.memoryId
+      LEFT JOIN  agent_tasks at  ON at.id = am.sourceTaskId
      WHERE ${conditions.join(" AND ")}
      ORDER BY mr.retrievedAt DESC
      LIMIT ?

package/src/be/migrations/054_agent_harness_provider.sql

@@ -0,0 +1,21 @@
+-- 054_agent_harness_provider.sql
+--
+-- Phase 1.5 of the cloud-personalization plan
+-- (thoughts/taras/plans/2026-05-08-cloud-personalization-phases-1-4.md).
+--
+-- Add a first-class `harness_provider` column on `agents` so each agent's
+-- harness (claude / codex / pi / devin / claude-managed / opencode) is
+-- queryable per-row, independent of `process.env.HARNESS_PROVIDER` at
+-- worker boot.
+--
+-- Workers push their `HARNESS_PROVIDER` value on registration; an operator
+-- can later re-assign via `PATCH /api/agents/:id/harness-provider`. The
+-- worker itself does NOT yet react in real time — picked up on next worker
+-- restart. Full per-agent harness with dynamic adapter loading lives in
+-- Linear DES-359.
+--
+-- Forward-only. NULL default = backward-compat for already-registered
+-- agents (their column stays NULL until they re-register or an operator
+-- patches it).
+
+ALTER TABLE agents ADD COLUMN harness_provider TEXT NULL;

package/src/be/migrations/055_agent_cred_status.sql

@@ -0,0 +1,15 @@
+-- 055_agent_cred_status.sql
+--
+-- Worker-self-reported credential snapshot. Pairs with `harness_provider`
+-- (054): the JSON describes the agent's creds for whichever harness that
+-- agent runs. NULL = unreported (worker hasn't booted yet, or
+-- CRED_CHECK_DISABLE=1 was set).
+--
+-- The existing `credentialMissing` column (053) stays. This one is additive
+-- and carries the full snapshot (ready, missing, satisfiedBy, hint,
+-- liveTest, reportedAt, reportKind). Once `cred_status.missing` is proven
+-- across deploys, `credentialMissing` can be retired in a later migration.
+--
+-- Forward-only.
+
+ALTER TABLE agents ADD COLUMN cred_status TEXT;

package/src/be/migrations/056_drop_agent_tasks_source_check.sql

@@ -0,0 +1,139 @@
+-- Drop the SQL CHECK constraint on agent_tasks.source.
+-- The Zod layer (`AgentTaskSourceSchema` in src/types.ts) is now the single
+-- source of truth for the allowed enum, so adding a new source no longer
+-- requires a forward-only migration. This makes future source additions
+-- (Phase 1 of the UI chat/session experience plan) cheap.
+--
+-- SQLite cannot ALTER a CHECK constraint in place; we follow the table-rebuild
+-- pattern from migration 043_jira_source.sql verbatim, minus the CHECK clause
+-- on `source`. All other columns, defaults, indexes, and FKs are preserved
+-- exactly. No data migration — existing rows remain valid.
+--
+-- INSERT uses an explicit column list (no `SELECT *`) to be robust against
+-- column-order drift between SQLite versions and against post-043 ALTERs
+-- (migration 044 added `provider` and `providerMeta`).
+PRAGMA foreign_keys=off;
+
+CREATE TABLE agent_tasks_new (
+  id TEXT PRIMARY KEY,
+  agentId TEXT,
+  creatorAgentId TEXT,
+  task TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'pending',
+  source TEXT NOT NULL DEFAULT 'mcp',
+  taskType TEXT,
+  tags TEXT DEFAULT '[]',
+  priority INTEGER DEFAULT 50,
+  dependsOn TEXT DEFAULT '[]',
+  offeredTo TEXT,
+  offeredAt TEXT,
+  acceptedAt TEXT,
+  rejectionReason TEXT,
+  slackChannelId TEXT,
+  slackThreadTs TEXT,
+  slackUserId TEXT,
+  mentionMessageId TEXT,
+  mentionChannelId TEXT,
+  vcsProvider TEXT,
+  vcsRepo TEXT,
+  vcsEventType TEXT,
+  vcsNumber INTEGER,
+  vcsCommentId INTEGER,
+  vcsAuthor TEXT,
+  vcsUrl TEXT,
+  parentTaskId TEXT,
+  claudeSessionId TEXT,
+  agentmailInboxId TEXT,
+  agentmailMessageId TEXT,
+  agentmailThreadId TEXT,
+  model TEXT,
+  scheduleId TEXT,
+  workflowRunId TEXT REFERENCES workflow_runs(id),
+  workflowRunStepId TEXT REFERENCES workflow_run_steps(id),
+  createdAt TEXT NOT NULL,
+  lastUpdatedAt TEXT NOT NULL,
+  finishedAt TEXT,
+  failureReason TEXT,
+  output TEXT,
+  progress TEXT,
+  notifiedAt TEXT,
+  dir TEXT,
+  outputSchema TEXT,
+  compactionCount INTEGER DEFAULT 0,
+  peakContextPercent REAL,
+  totalContextTokensUsed INTEGER,
+  contextWindowSize INTEGER,
+  was_paused INTEGER NOT NULL DEFAULT 0,
+  credentialKeySuffix TEXT,
+  credentialKeyType TEXT,
+  requestedByUserId TEXT REFERENCES users(id),
+  vcsInstallationId INTEGER,
+  vcsNodeId TEXT,
+  slackReplySent INTEGER DEFAULT 0,
+  swarmVersion TEXT,
+  contextKey TEXT,
+  provider TEXT,
+  providerMeta TEXT
+);
+
+INSERT INTO agent_tasks_new (
+  id, agentId, creatorAgentId, task, status, source, taskType, tags,
+  priority, dependsOn, offeredTo, offeredAt, acceptedAt, rejectionReason,
+  slackChannelId, slackThreadTs, slackUserId,
+  mentionMessageId, mentionChannelId,
+  vcsProvider, vcsRepo, vcsEventType, vcsNumber, vcsCommentId, vcsAuthor, vcsUrl,
+  parentTaskId, claudeSessionId,
+  agentmailInboxId, agentmailMessageId, agentmailThreadId,
+  model, scheduleId, workflowRunId, workflowRunStepId,
+  createdAt, lastUpdatedAt, finishedAt, failureReason, output, progress, notifiedAt,
+  dir, outputSchema, compactionCount, peakContextPercent,
+  totalContextTokensUsed, contextWindowSize, was_paused,
+  credentialKeySuffix, credentialKeyType, requestedByUserId,
+  vcsInstallationId, vcsNodeId, slackReplySent, swarmVersion, contextKey,
+  provider, providerMeta
+)
+SELECT
+  id, agentId, creatorAgentId, task, status, source, taskType, tags,
+  priority, dependsOn, offeredTo, offeredAt, acceptedAt, rejectionReason,
+  slackChannelId, slackThreadTs, slackUserId,
+  mentionMessageId, mentionChannelId,
+  vcsProvider, vcsRepo, vcsEventType, vcsNumber, vcsCommentId, vcsAuthor, vcsUrl,
+  parentTaskId, claudeSessionId,
+  agentmailInboxId, agentmailMessageId, agentmailThreadId,
+  model, scheduleId, workflowRunId, workflowRunStepId,
+  createdAt, lastUpdatedAt, finishedAt, failureReason, output, progress, notifiedAt,
+  dir, outputSchema, compactionCount, peakContextPercent,
+  totalContextTokensUsed, contextWindowSize, was_paused,
+  credentialKeySuffix, credentialKeyType, requestedByUserId,
+  vcsInstallationId, vcsNodeId, slackReplySent, swarmVersion, contextKey,
+  provider, providerMeta
+FROM agent_tasks;
+
+DROP TABLE agent_tasks;
+ALTER TABLE agent_tasks_new RENAME TO agent_tasks;
+
+-- Recreate every index that existed on agent_tasks (mirrors 043 + later additions):
+--   001/004/006/009/026: agentId, status, offeredTo, taskType, agentmailThreadId, scheduleId, workflowRunId
+--   031: requestedByUserId (partial)
+--   034: parentTaskId
+--   037: swarmVersion
+--   040: composite (slackChannelId, slackThreadTs, status)
+--   042: contextKey + (contextKey, status) composite
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_agentId ON agent_tasks(agentId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_status ON agent_tasks(status);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_offeredTo ON agent_tasks(offeredTo);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_taskType ON agent_tasks(taskType);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_agentmailThreadId ON agent_tasks(agentmailThreadId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_schedule_id ON agent_tasks(scheduleId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_workflow_run ON agent_tasks(workflowRunId);
+CREATE INDEX IF NOT EXISTS idx_tasks_requested_by ON agent_tasks(requestedByUserId) WHERE requestedByUserId IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_parentTaskId ON agent_tasks(parentTaskId);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_swarmVersion ON agent_tasks(swarmVersion);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_slack_thread
+  ON agent_tasks(slackChannelId, slackThreadTs, status);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_context_key
+  ON agent_tasks(contextKey);
+CREATE INDEX IF NOT EXISTS idx_agent_tasks_context_key_status
+  ON agent_tasks(contextKey, status);
+
+PRAGMA foreign_keys=on;

package/src/be/migrations/057_inbox_item_state.sql

@@ -0,0 +1,27 @@
+-- Inbox item state — per-user dismiss/snooze/done state for action-items inbox
+-- buckets (approval, credential_missing, broken_task, to_read, to_start_template).
+--
+-- itemType is enforced via Zod (`InboxItemTypeSchema` in src/types.ts), not a
+-- SQL CHECK constraint — Phase 1 lesson, lets us extend the enum without a
+-- forward-only migration. Direct SQL inserts can bypass; the HTTP layer
+-- (`PATCH /api/inbox-state`) is the only sanctioned writer.
+--
+-- itemId references the underlying entity (task id, approval-request id,
+-- agent id, template id, …) but is left as a free TEXT column rather than a
+-- typed FK because itemType disambiguates which table it points at.
+CREATE TABLE IF NOT EXISTS inbox_item_state (
+  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  userId TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  itemType TEXT NOT NULL,
+  itemId TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'open',
+  snoozeUntil TEXT,
+  dismissedAt TEXT,
+  doneAt TEXT,
+  createdAt TEXT NOT NULL DEFAULT (datetime('now')),
+  lastUpdatedAt TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE(userId, itemType, itemId)
+);
+
+CREATE INDEX IF NOT EXISTS idx_inbox_item_state_userId_status
+  ON inbox_item_state(userId, status);

package/src/be/migrations/058_task_templates.sql

@@ -0,0 +1,31 @@
+-- Task templates — "To start" bucket starters. Polymorphic from day one
+-- (kind = 'task' | 'workflow' | 'schedule') so v2 can register workflow /
+-- schedule starters without a follow-up migration. v1 only inserts/reads
+-- kind='task' rows; the schema is shaped for v2.
+--
+-- The `prompt` column is NOT NULL only because v1 only ever seeds task rows;
+-- a future migration can relax that when workflow/schedule starters land
+-- (workflows carry workflowId in `payload`, schedules carry cron + prompt).
+--
+-- Table name kept as `task_templates` for v1 to match existing references
+-- across the plan; v2 may rename to `quick_starts` if non-task kinds graduate.
+CREATE TABLE IF NOT EXISTS task_templates (
+  id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+  title TEXT NOT NULL,
+  description TEXT NOT NULL,
+  prompt TEXT NOT NULL,
+  kind TEXT NOT NULL DEFAULT 'task' CHECK(kind IN ('task','workflow','schedule')),
+  payload TEXT NOT NULL DEFAULT '{}',
+  category TEXT,
+  tags TEXT NOT NULL DEFAULT '[]',
+  createdAt TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_task_templates_kind ON task_templates(kind);
+
+INSERT INTO task_templates (title, description, prompt, category, tags) VALUES
+  ('Refactor a file', 'Improve a file without changing behavior', 'Refactor the file at <path> for readability while preserving behavior. Run typecheck + tests after.', 'engineering', '["refactor"]'),
+  ('Investigate a bug', 'Reproduce, root-cause, and propose a fix', 'Investigate the following bug: <symptom>. Reproduce locally, identify the root cause, and propose a fix.', 'engineering', '["debug"]'),
+  ('Open a PR', 'Create a PR for the current branch', 'Open a PR from the current branch with a clear summary and test plan.', 'git', '["git","pr"]'),
+  ('Write tests for X', 'Cover an under-tested module', 'Write unit tests for <module>. Aim for ~80% line coverage.', 'engineering', '["test"]'),
+  ('Daily triage', 'Review failed tasks + pending approvals', 'Triage the action-items inbox: dismiss noise, escalate blockers, summarize unread sessions.', 'ops', '["triage"]');