@desplega.ai/agent-swarm 1.156.0 → 1.158.0

package/src/be/db.ts

@@ -154,6 +154,7 @@ import {
   reservedRoleViolation,
   rowToAgent,
 } from "./db/agents";
+import { type ApprovalRequestListFilters, approvalRequestListClause } from "./db/approvals";
 import {
   computeContentHash,
   createContextVersion,
@@ -184,6 +185,7 @@ export {
   extensionAgentAssignmentError,
   getActiveTaskCount,
   getAgentById,
+  getAgentDailyTaskCounts,
   getAgentHarnessProviders,
   getAllAgents,
   getLeadAgent,
@@ -210,6 +212,7 @@ export {
   updateAgentStatus,
   updateAgentStatusFromCapacity,
 } from "./db/agents";
+export { type ApprovalRequestSummary, listApprovalRequestSummaries } from "./db/approvals";
 export {
   computeContentHash,
   createContextVersion,
@@ -256,6 +259,7 @@ export {
   getPendingSlackRelayTasks,
   getRecentlyFinishedWorkerTasks,
   getSlackTasksMissingTree,
+  getSupersededTasksWithoutResume,
   getTaskById,
   getTaskStats,
   getTasksByAgentId,
@@ -318,9 +322,13 @@ type TaskTelemetryContext = {
   harnessVersion?: string;
 };
 
+/** LIKE pattern matching strings that start with `prefix` literally (use with `ESCAPE '\\'`). */
+function literalPrefixPattern(prefix: string): string {
+  return `${prefix.replace(/[\\%_]/g, "\\$&")}%`;
+}
+
 function assetKeyPrefixPattern(input: string): string {
-  const canonical = normalizeAssetKey(input);
-  return `${canonical.replace(/[\\%_]/g, "\\$&")}%`;
+  return literalPrefixPattern(normalizeAssetKey(input));
 }
 
 function emitTaskLifecycleTelemetryAfterCommit(
@@ -2486,7 +2494,15 @@ export async function createTaskExtended(
       if (parent.contextKey && !options.contextKey) {
         options.contextKey = parent.contextKey;
       }
-      if (parent.followUpConfig && !options.followUpConfig) {
+      // followUpConfig is opt-in: only a continuation of the same work carries
+      // the creator's onCompleted/onFailed forward. Lead follow-ups, new
+      // delegations and thread replies all pass parentTaskId too, and
+      // inheriting there spread one task's instructions down the thread.
+      if (
+        parent.followUpConfig &&
+        !options.followUpConfig &&
+        options.inheritParentFollowUpConfig === true
+      ) {
         options.followUpConfig = parent.followUpConfig;
       }
       if (parent.routingAffinityInvalid && options.inheritParentRoutingAffinity !== false) {
@@ -7634,7 +7650,8 @@ type WorkflowRunRow = {
   status: string;
   triggerType: string;
   triggerData: string | null;
-  context: string | null;
+  /** Absent from list rows: see `WORKFLOW_RUN_SUMMARY_COLUMNS`. */
+  context?: string | null;
   error: string | null;
   created_by: string | null;
   startedAt: string;
@@ -7762,8 +7779,18 @@ export type WorkflowRunListOptions = {
   status?: WorkflowRunStatus;
   limit?: number;
   offset?: number;
+  /**
+   * Read the run `context`. Off by default: it is the one large column, and
+   * `getWorkflowRun` serves it for a single run.
+   */
+  includeContext?: boolean;
 };
 
+// Everything but `context`. `triggerData` stays: it is small, and stored
+// scripts read it off list rows (dedupe by trigger, failure reports).
+const WORKFLOW_RUN_SUMMARY_COLUMNS =
+  "id, workflowId, status, triggerType, triggerData, error, created_by, startedAt, lastUpdatedAt, finishedAt";
+
 export type WorkflowRunPage = {
   runs: WorkflowRun[];
   page: {
@@ -7795,8 +7822,9 @@ export async function listWorkflowRuns(
     params.push(options.offset);
   }
 
+  const columns = options.includeContext ? "*" : WORKFLOW_RUN_SUMMARY_COLUMNS;
   const rows = await getDbClient().query<WorkflowRunRow>(
-    `SELECT * FROM workflow_runs
+    `SELECT ${columns} FROM workflow_runs
        WHERE ${conditions.join(" AND ")}
        ORDER BY startedAt DESC, id DESC${pagination}`,
     params,
@@ -7824,7 +7852,7 @@ export async function countWorkflowRuns(
 export async function listWorkflowRunsPage(
   workflowId: string,
   options: Required<Pick<WorkflowRunListOptions, "limit" | "offset">> &
-    Pick<WorkflowRunListOptions, "status">,
+    Pick<WorkflowRunListOptions, "status" | "includeContext">,
 ): Promise<WorkflowRunPage> {
   const runs = await listWorkflowRuns(workflowId, options);
   const total = await countWorkflowRuns(workflowId, { status: options.status });
@@ -8056,11 +8084,13 @@ export async function getLastRunStart(workflowId: string): Promise<WorkflowRun |
 export async function getRetryableSteps(): Promise<WorkflowRunStep[]> {
   const now = new Date().toISOString();
   const rows = await getDbClient().query<WorkflowRunStepRow>(
-    `SELECT * FROM workflow_run_steps
-       WHERE status = 'failed'
-         AND nextRetryAt IS NOT NULL
-         AND nextRetryAt <= ?
-       ORDER BY nextRetryAt ASC`,
+    `SELECT s.* FROM workflow_run_steps s
+       JOIN workflow_runs r ON r.id = s.runId
+       WHERE s.status = 'failed'
+         AND s.nextRetryAt IS NOT NULL
+         AND s.nextRetryAt <= ?
+         AND r.status IN ('running', 'waiting', 'failed')
+       ORDER BY s.nextRetryAt ASC`,
     [now],
   );
   return rows.map(rowToWorkflowRunStep);
@@ -8114,6 +8144,37 @@ export async function getLatestStepForNode(
   return row ? rowToWorkflowRunStep(row) : null;
 }
 
+/**
+ * The node's latest step when it already covers the current predecessor
+ * completions: it is running, waiting or completed, and no predecessor has
+ * completed a step inserted after it. A loop iteration always has a newer
+ * predecessor completion, so it never matches. Ordered by rowid, which
+ * follows insert order; startedAt can tie within a millisecond.
+ */
+export async function getCurrentStepForNode(
+  runId: string,
+  nodeId: string,
+  predecessorIds: string[],
+): Promise<WorkflowRunStep | null> {
+  const row = await getDbClient().get<WorkflowRunStepRow>(
+    "SELECT * FROM workflow_run_steps WHERE runId = ? AND nodeId = ? ORDER BY rowid DESC LIMIT 1",
+    [runId, nodeId],
+  );
+  if (!row || !["running", "waiting", "completed"].includes(row.status)) return null;
+  if (predecessorIds.length > 0) {
+    const newer = await getDbClient().get<{ found: number }>(
+      `SELECT 1 AS found FROM workflow_run_steps
+         WHERE runId = ? AND status = 'completed'
+           AND nodeId IN (${predecessorIds.map(() => "?").join(", ")})
+           AND rowid > (SELECT rowid FROM workflow_run_steps WHERE id = ?)
+         LIMIT 1`,
+      [runId, ...predecessorIds, row.id],
+    );
+    if (newer) return null;
+  }
+  return rowToWorkflowRunStep(row);
+}
+
 // --- Workflow Version History ---
 
 type WorkflowVersionRow = {
@@ -9550,6 +9611,7 @@ export async function resolveApprovalRequest(
     status: "approved" | "rejected" | "timeout";
     responses?: unknown;
     resolvedBy?: string;
+    resolutionReason?: string;
   },
   options?: { requireActionableWorkflow?: boolean },
 ): Promise<ApprovalRequest | null> {
@@ -9574,7 +9636,8 @@ export async function resolveApprovalRequest(
     : "";
   const row = await getDbClient().get<ApprovalRequestRow>(
     `UPDATE approval_requests
-       SET status = ?, responses = ?, resolvedBy = ?, resolvedAt = ?, updatedAt = ?
+       SET status = ?, responses = ?, resolvedBy = ?, resolutionReason = ?, resolvedAt = ?,
+           updatedAt = ?
        WHERE id = ? AND status = 'pending'
          ${actionableWorkflowClause}
        RETURNING *`,
@@ -9582,6 +9645,7 @@ export async function resolveApprovalRequest(
       data.status,
       data.responses ? JSON.stringify(data.responses) : null,
       data.resolvedBy ?? null,
+      data.resolutionReason ?? null,
       now,
       now,
       id,
@@ -9590,6 +9654,23 @@ export async function resolveApprovalRequest(
   return row ? rowToApprovalRequest(row) : null;
 }
 
+// Cancels 1 pending request. The `status = 'pending'` guard lets a concurrent
+// human answer win; null means the row was not pending.
+export async function cancelApprovalRequestById(
+  id: string,
+  data: { reason: string; resolvedBy: string | null },
+): Promise<ApprovalRequest | null> {
+  const now = new Date().toISOString();
+  const row = await getDbClient().get<ApprovalRequestRow>(
+    `UPDATE approval_requests
+       SET status = 'cancelled', resolutionReason = ?, resolvedBy = ?, resolvedAt = ?, updatedAt = ?
+       WHERE id = ? AND status = 'pending'
+       RETURNING *`,
+    [data.reason, data.resolvedBy, now, now, id],
+  );
+  return row ? rowToApprovalRequest(row) : null;
+}
+
 export async function cancelPendingApprovalRequestsForRun(
   workflowRunId: string,
   reason: string,
@@ -9725,32 +9806,14 @@ export async function updateApprovalRequestNotifications(
   );
 }
 
-export async function listApprovalRequests(filters?: {
-  status?: string;
-  workflowRunId?: string;
-  limit?: number;
-}): Promise<ApprovalRequest[]> {
-  const conditions: string[] = [];
-  const params: (string | number)[] = [];
-
-  if (filters?.status) {
-    conditions.push("status = ?");
-    params.push(filters.status);
-  }
-  if (filters?.workflowRunId) {
-    conditions.push("workflowRunId = ?");
-    params.push(filters.workflowRunId);
-  }
-
-  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-  const limit = filters?.limit ?? 100;
-  params.push(limit);
-
+export async function listApprovalRequests(
+  filters?: ApprovalRequestListFilters,
+): Promise<ApprovalRequest[]> {
+  const { sql, params } = approvalRequestListClause(filters);
   const rows = await getDbClient().query<ApprovalRequestRow>(
-    `SELECT * FROM approval_requests ${where} ORDER BY createdAt DESC LIMIT ?`,
+    `SELECT * FROM approval_requests ${sql}`,
     params,
   );
-
   return rows.map(rowToApprovalRequest);
 }
 
@@ -9793,13 +9856,34 @@ export async function getApprovalRequestByStepId(stepId: string): Promise<Approv
   return row ? rowToApprovalRequest(row) : null;
 }
 
-// TODO: Wire into a periodic cron/sweep to auto-timeout expired approval requests (Phase 2)
-export async function getExpiredPendingApprovals(): Promise<ApprovalRequest[]> {
+// Called by timeoutExpiredApprovalRequests in src/be/approval-sweeps.ts on each heartbeat tick.
+export async function getExpiredPendingApprovals(opts?: {
+  now?: string;
+}): Promise<ApprovalRequest[]> {
   const rows = await getDbClient().query<ApprovalRequestRow>(
     `SELECT * FROM approval_requests
        WHERE status = 'pending'
          AND expiresAt IS NOT NULL
-         AND expiresAt < strftime('%Y-%m-%dT%H:%M:%fZ', 'now')`,
+         AND expiresAt < ?
+       ORDER BY expiresAt ASC`,
+    [opts?.now ?? new Date().toISOString()],
+  );
+  return rows.map(rowToApprovalRequest);
+}
+
+// Pending requests with no explicit deadline created before `cutoff`. Served
+// by idx_approval_requests_pending_created (migration 166). Called by
+// autoCancelStaleApprovalRequests in src/be/approval-sweeps.ts.
+export async function getStaleApprovalRequests(opts: {
+  cutoff: string;
+}): Promise<ApprovalRequest[]> {
+  const rows = await getDbClient().query<ApprovalRequestRow>(
+    `SELECT * FROM approval_requests
+       WHERE status = 'pending'
+         AND expiresAt IS NULL
+         AND createdAt < ?
+       ORDER BY createdAt ASC`,
+    [opts.cutoff],
   );
   return rows.map(rowToApprovalRequest);
 }
@@ -12375,9 +12459,9 @@ export async function listTaskTemplates(opts?: {
 // ============================================================================
 
 /**
- * Walk the parent→child chain rooted at `rootTaskId` via recursive CTE.
- * Returns the chain ordered by `createdAt` (so the root is first; siblings
- * appear in creation order; grand-children after their parents).
+ * Walk the chain rooted at `rootTaskId`, ordered by `createdAt` (root first; `rowid` breaks
+ * ties as idx_agent_tasks_created did). `CROSS JOIN` keeps the chain as the outer loop: with
+ * a plain JOIN, SQLite scanned all of agent_tasks to skip the sort.
  */
 export async function getRootTaskChain(rootTaskId: string): Promise<AgentTask[]> {
   const rows = await getDbClient().query<AgentTaskRow>(
@@ -12387,9 +12471,9 @@ export async function getRootTaskChain(rootTaskId: string): Promise<AgentTask[]>
          SELECT t.id FROM agent_tasks t
          JOIN chain c ON t.parentTaskId = c.id
        )
-       SELECT t.* FROM agent_tasks t
-       JOIN chain ON chain.id = t.id
-       ORDER BY t.createdAt`,
+       SELECT t.* FROM chain
+       CROSS JOIN agent_tasks t ON t.id = chain.id
+       ORDER BY t.createdAt, t.rowid`,
     [rootTaskId],
   );
   return rows.map(rowToAgentTask);
@@ -12434,6 +12518,12 @@ interface ListRecentSessionsOpts {
   q?: string;
   /** When set, restrict to root tasks where `requestedByUserId` equals this value. NULL rows are excluded. */
   requestedByUserId?: string;
+  /**
+   * When set, restrict to root tasks whose `contextKey` starts with this
+   * literal prefix (`%`, `_` and `\` are escaped). Powers the UI contextual
+   * session panel's per-page dropdown.
+   */
+  contextKeyPrefix?: string;
   /** When true, return slim `SessionListItemSummary` rows (default: full). */
   slim?: boolean;
 }
@@ -12469,6 +12559,10 @@ export async function listRecentSessions(
     conditions.push("r.requestedByUserId = ?");
     params.push(requestedByUserId);
   }
+  if (opts?.contextKeyPrefix) {
+    conditions.push(`r.contextKey LIKE ? ESCAPE '\\'`);
+    params.push(literalPrefixPattern(opts.contextKeyPrefix));
+  }
   params.push(limit, offset);
 
   const rootRows = await getDbClient().query<
@@ -12505,7 +12599,7 @@ export async function listRecentSessions(
        FROM agent_tasks r
        JOIN agg a ON a.root_id = r.id
        LEFT JOIN latest_status ls ON ls.root_id = r.id
-       ORDER BY a.lastActivityAt DESC
+       ORDER BY a.lastActivityAt DESC, r.createdAt DESC, r.id DESC
        LIMIT ? OFFSET ?`,
     params,
   );
@@ -12540,7 +12634,7 @@ export async function listRecentSessions(
  * a plain count, no recursive chain walk needed.
  */
 export async function countSessions(
-  opts?: Pick<ListRecentSessionsOpts, "source" | "q" | "requestedByUserId">,
+  opts?: Pick<ListRecentSessionsOpts, "source" | "q" | "requestedByUserId" | "contextKeyPrefix">,
 ): Promise<number> {
   const sources = opts?.source?.filter((s) => s.length > 0) ?? [];
   const q = opts?.q?.trim();
@@ -12562,6 +12656,10 @@ export async function countSessions(
     conditions.push("requestedByUserId = ?");
     params.push(requestedByUserId);
   }
+  if (opts?.contextKeyPrefix) {
+    conditions.push(`contextKey LIKE ? ESCAPE '\\'`);
+    params.push(literalPrefixPattern(opts.contextKeyPrefix));
+  }
 
   const row = await getDbClient().get<{ count: number }>(
     `SELECT COUNT(*) AS count FROM agent_tasks WHERE ${conditions.join(" AND ")}`,
@@ -13434,42 +13532,96 @@ export async function incrKv(namespace: string, key: string, by: number): Promis
   });
 }
 
+/**
+ * Smallest string greater than every string that starts with `prefix`, in
+ * code-point order (which is SQLite's BINARY order over UTF-8). `null` means
+ * no upper bound exists (the prefix is all U+10FFFF).
+ */
+export function kvPrefixUpperBound(prefix: string): string | null {
+  const codePoints = Array.from(prefix);
+  while (codePoints.length > 0) {
+    const last = codePoints.pop()!.codePointAt(0)!;
+    if (last < 0x10ffff) {
+      const next = last + 1 === 0xd800 ? 0xe000 : last + 1;
+      return codePoints.join("") + String.fromCodePoint(next);
+    }
+  }
+  return null;
+}
+
+/**
+ * Key-prefix predicate as a range on the (namespace, key) primary key.
+ * `key LIKE 'p%'` cannot use that index (LIKE is case-insensitive, the PK is
+ * BINARY), so it scanned every row of the namespace. A range seeks straight
+ * to the prefix and matches it exactly (case-sensitive).
+ */
+function kvPrefixCondition(prefix: string | undefined): { sql: string; params: string[] } {
+  if (prefix === undefined || prefix.length === 0) return { sql: "", params: [] };
+  const upper = kvPrefixUpperBound(prefix);
+  return upper === null
+    ? { sql: "AND key >= ?", params: [prefix] }
+    : { sql: "AND key >= ? AND key < ?", params: [prefix, upper] };
+}
+
+/** Top-level JSON field equality, evaluated in SQLite before rows reach JS. */
+export type KvJsonFieldEquals = { field: string; value: string | number | boolean };
+
+function kvJsonFieldConditions(filters: KvJsonFieldEquals[] | undefined): {
+  sql: string;
+  params: (string | number | boolean)[];
+} {
+  const parts: string[] = [];
+  const params: (string | number | boolean)[] = [];
+  for (const filter of filters ?? []) {
+    // JSON path quoting has no escape for these characters.
+    if (/["\\]/.test(filter.field)) {
+      throw new Error(`unsupported JSON field name: ${filter.field}`);
+    }
+    // Only safe integers compare exactly: SQLite parses a stored literal like
+    // 1000000000000000100 as an exact INTEGER (and fractions with its own
+    // float parser) while the bound JS number is a double, so SQL could drop
+    // a row that JS `===` matches. Other numbers are left to the caller.
+    if (typeof filter.value === "number" && !Number.isSafeInteger(filter.value)) continue;
+    // json_valid guards the corrupt rows decodeKvRow tolerates: json_extract
+    // would abort the whole query on one of them.
+    parts.push(
+      "AND (CASE WHEN value_type = 'json' AND json_valid(value) THEN json_extract(value, ?) END) = ?",
+    );
+    params.push(`$."${filter.field}"`, filter.value);
+  }
+  return { sql: parts.join(" "), params };
+}
+
 /**
  * List entries in a namespace, optionally filtered by prefix. Expired rows
  * are filtered out by the SELECT (no inline DELETE — listing should be a
  * stable cursor; sweeping happens on point-reads instead).
  *
+ * `jsonFieldEquals` narrows the rows in SQL so non-matching values are never
+ * decoded. SQL equality is looser than JS `===` (JSON `true` equals `1`) and
+ * numbers that are not safe integers are not filtered at all, so callers that
+ * need exact semantics re-check the decoded values.
+ *
  * `limit` is capped by the caller (HTTP enforces ≤1000); helper does no extra
  * bounds-check beyond what SQL accepts.
  */
 export async function listKv(
   namespace: string,
-  opts: { prefix?: string; limit: number; offset: number },
+  opts: { prefix?: string; limit: number; offset: number; jsonFieldEquals?: KvJsonFieldEquals[] },
 ): Promise<KvEntry[]> {
   const now = Date.now();
-  if (opts.prefix !== undefined && opts.prefix.length > 0) {
-    // LIKE-escape `\` `%` `_` so a user-supplied prefix can't run wildcards.
-    const escaped = opts.prefix.replace(/[\\%_]/g, "\\$&");
-    const rows = await getDbClient().query<KvRow>(
-      `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
-           FROM kv_entries
-          WHERE namespace = ?
-            AND (expires_at IS NULL OR expires_at > ?)
-            AND key LIKE ? ESCAPE '\\'
-          ORDER BY key
-          LIMIT ? OFFSET ?`,
-      [namespace, now, `${escaped}%`, opts.limit, opts.offset],
-    );
-    return rows.map(decodeKvRow);
-  }
+  const prefix = kvPrefixCondition(opts.prefix);
+  const json = kvJsonFieldConditions(opts.jsonFieldEquals);
   const rows = await getDbClient().query<KvRow>(
     `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
          FROM kv_entries
         WHERE namespace = ?
           AND (expires_at IS NULL OR expires_at > ?)
+          ${prefix.sql}
+          ${json.sql}
         ORDER BY key
         LIMIT ? OFFSET ?`,
-    [namespace, now, opts.limit, opts.offset],
+    [namespace, now, ...prefix.params, ...json.params, opts.limit, opts.offset],
   );
   return rows.map(decodeKvRow);
 }
@@ -13480,22 +13632,13 @@ export async function listKv(
  */
 export async function countKv(namespace: string, opts: { prefix?: string }): Promise<number> {
   const now = Date.now();
-  if (opts.prefix !== undefined && opts.prefix.length > 0) {
-    const escaped = opts.prefix.replace(/[\\%_]/g, "\\$&");
-    const row = await getDbClient().get<{ n: number }>(
-      `SELECT COUNT(*) AS n FROM kv_entries
-          WHERE namespace = ?
-            AND (expires_at IS NULL OR expires_at > ?)
-            AND key LIKE ? ESCAPE '\\'`,
-      [namespace, now, `${escaped}%`],
-    );
-    return row?.n ?? 0;
-  }
+  const prefix = kvPrefixCondition(opts.prefix);
   const row = await getDbClient().get<{ n: number }>(
     `SELECT COUNT(*) AS n FROM kv_entries
         WHERE namespace = ?
-          AND (expires_at IS NULL OR expires_at > ?)`,
-    [namespace, now],
+          AND (expires_at IS NULL OR expires_at > ?)
+          ${prefix.sql}`,
+    [namespace, now, ...prefix.params],
   );
   return row?.n ?? 0;
 }

package/src/be/events.ts

@@ -238,6 +238,15 @@ export async function getEventsFiltered(filters: {
   since?: string;
   until?: string;
   limit?: number;
+  /** Match any of these event names (`event IN (...)`), ANDed with `event`. */
+  events?: EventName[];
+  /**
+   * Return only the newest row per (event, data.field) pair, for every pair of
+   * these event names and field values. Each pair is its own indexed
+   * `ORDER BY createdAt DESC LIMIT 1` lookup, so the cost does not grow with
+   * the agent's event history.
+   */
+  latestPerDataField?: { events: EventName[]; dataFields: string[] };
 }): Promise<SwarmEvent[]> {
   const conditions: string[] = [];
   const params: (string | number)[] = [];
@@ -250,6 +259,10 @@ export async function getEventsFiltered(filters: {
     conditions.push("event = ?");
     params.push(filters.event);
   }
+  if (filters.events && filters.events.length > 0) {
+    conditions.push(`event IN (${filters.events.map(() => "?").join(", ")})`);
+    params.push(...filters.events);
+  }
   if (filters.status) {
     conditions.push("status = ?");
     params.push(filters.status);
@@ -283,8 +296,27 @@ export async function getEventsFiltered(filters: {
     params.push(filters.until);
   }
 
-  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const limit = filters.limit ?? 100;
+
+  if (filters.latestPerDataField) {
+    const lookups: string[] = [];
+    const lookupParams: (string | number)[] = [];
+    for (const event of filters.latestPerDataField.events) {
+      for (const field of filters.latestPerDataField.dataFields) {
+        const where = [...conditions, "event = ?", "json_extract(data, '$.field') = ?"];
+        lookups.push(
+          `SELECT * FROM (SELECT * FROM events WHERE ${where.join(" AND ")} ORDER BY createdAt DESC LIMIT 1)`,
+        );
+        lookupParams.push(...params, event, field);
+      }
+    }
+    if (lookups.length === 0) return [];
+    const sql = `${lookups.join(" UNION ALL ")} ORDER BY createdAt DESC LIMIT ?`;
+    const rows = await getDbClient().query<EventRow>(sql, [...lookupParams, limit]);
+    return rows.map(rowToSwarmEvent);
+  }
+
+  const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   params.push(limit);
 
   const sql = `SELECT * FROM events ${where} ORDER BY createdAt DESC LIMIT ?`;

package/src/be/memory/graph-expansion.ts

@@ -118,8 +118,9 @@ export async function expandCandidatesWithGraph(
     const parent = parentById.get(row.fromMemoryId);
     if (!parent) continue;
     const strength = typeof row.linkStrength === "number" ? row.linkStrength : 1.0;
-    // Derive from the parent's RAW (pre-decay) similarity — fts/hybrid arms
-    // ship `similarity` with the parent's recency decay already applied, and
+    // Derive from the parent's pre-decay match score on the shared [0,1]
+    // scale (vec cosine, hybrid fused cosine, fts rank). The fts arm ships
+    // `similarity` with the parent's recency decay already applied, and
     // rerank() will apply the NEIGHBOR's own decay to this candidate. Using
     // the decayed value would stack two decay factors on one score.
     const parentBase = parent.rawSimilarity ?? parent.similarity;
@@ -129,6 +130,7 @@ export async function expandCandidatesWithGraph(
     neighbors.set(row.id, {
       ...rowToCandidate(row, similarity),
       retrievalSource: "graph",
+      graphParentId: parent.id,
       // The neighbor's own decay is applied exactly once by rerank().
       recencyDecayApplied: false,
     });
@@ -153,7 +155,12 @@ export async function expandCandidatesWithGraph(
     if (existingIndex !== undefined) {
       // Dedupe against organic candidates: keep whichever entry the reranker
       // will score higher (same memory, so all non-similarity factors match).
-      if (computeScore(neighbor, now) > computeScore(result[existingIndex]!, now)) {
+      // rerank() caps a graph entry at its parent's composite, so compare the
+      // capped graph score; otherwise a low-quality parent's link replaces a
+      // stronger organic match and rerank() then demotes it below the parent.
+      const parent = parentById.get(neighbor.graphParentId!)!;
+      const graphScore = Math.min(computeScore(neighbor, now), computeScore(parent, now));
+      if (graphScore > computeScore(result[existingIndex]!, now)) {
         result[existingIndex] = neighbor;
       }
       continue;