@desplega.ai/agent-swarm 2.5.2 → 2.5.4

package/src/be/db/workflow-runs.ts

@@ -1,10 +1,11 @@
-import type { WorkflowRunStatus } from "../../types";
+import { TERMINAL_TASK_STATUSES, type WorkflowRunStatus } from "../../types";
 import { scrubSecrets } from "../../utils/secret-scrubber";
 import { scrubJsonValue } from "../scrub-json";
 import { getDbClient } from "./runtime";
 
 // Parent/child links between workflow runs (migration 203): a `sub-workflow`
-// step starts a child run that records the step in `parentStepId`.
+// step starts a child run that records the step in `parentStepId`, and the
+// step's `retryCount` at that time in `parentStepAttempt` (migration 240).
 
 const TERMINAL_STATUSES = new Set<WorkflowRunStatus>([
   "completed",
@@ -13,15 +14,371 @@ const TERMINAL_STATUSES = new Set<WorkflowRunStatus>([
   "skipped",
 ]);
 
-/** The id of the child run a `sub-workflow` step started, if any. */
-export async function getChildWorkflowRunId(parentStepId: string): Promise<string | null> {
+/**
+ * Deepest run tree the lineage guard and the cascade cancel walk. Twice the
+ * sub-workflow nesting cap (MAX_SUB_WORKFLOW_DEPTH, 16), so any tree the
+ * engine admits fits; a deeper chain is corrupt and fails closed.
+ */
+export const WORKFLOW_RUN_TREE_MAX_DEPTH = 32;
+
+/** Thrown when a run's stored parent links cannot be walked: a cycle, or a chain past the depth bound. */
+export class WorkflowRunTreeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowRunTreeError";
+  }
+}
+
+/**
+ * Thrown when work is created for a workflow step that may no longer run: the
+ * step is not `running`, its run is not live, or the run's lineage is blocked
+ * (see `getRunLineageBlock`).
+ */
+export class WorkflowStepNotExecutableError extends Error {
+  constructor(stepId: string, reason: string) {
+    super(`Workflow step ${stepId} may not start new work: ${reason}`);
+    this.name = "WorkflowStepNotExecutableError";
+  }
+}
+
+/**
+ * Why the run and its ancestors forbid new engine work, or null when they
+ * allow it. Blocked when the run is missing, the run or an ancestor is
+ * `cancelled`, a stored parent link points at a missing step or run, the
+ * links form a cycle, or the chain is deeper than WORKFLOW_RUN_TREE_MAX_DEPTH.
+ * A completed or failed ancestor does not block: a child of an earlier
+ * attempt may outlive its parent's run. The run's own live status is left to
+ * the caller, since the retry claim also revives a `failed` run.
+ *
+ * Call it inside the transaction that writes the new work, so a cascade
+ * cancel either commits first and is seen here or sees the new row itself.
+ */
+export async function getRunLineageBlock(runId: string): Promise<string | null> {
+  const rows = await getDbClient().query<{
+    id: string;
+    status: WorkflowRunStatus;
+    parentStepId: string | null;
+    depth: number;
+  }>(
+    `WITH RECURSIVE lineage(id, status, parentStepId, depth) AS (
+       SELECT id, status, parentStepId, 0 FROM workflow_runs WHERE id = ?
+       UNION ALL
+       SELECT r.id, r.status, r.parentStepId, l.depth + 1
+         FROM lineage l
+         JOIN workflow_run_steps s ON s.id = l.parentStepId
+         JOIN workflow_runs r ON r.id = s.runId
+        WHERE l.depth < ?
+     )
+     SELECT id, status, parentStepId, depth FROM lineage ORDER BY depth`,
+    [runId, WORKFLOW_RUN_TREE_MAX_DEPTH],
+  );
+  if (rows.length === 0) return `Workflow run ${runId} is missing`;
+  const seen = new Set<string>();
+  for (const row of rows) {
+    if (seen.has(row.id)) return `Workflow run ${runId} has a cycle in its parent links`;
+    seen.add(row.id);
+    if (row.status === "cancelled") {
+      return row.id === runId
+        ? `Workflow run ${runId} is cancelled`
+        : `Ancestor workflow run ${row.id} is cancelled`;
+    }
+  }
+  const top = rows[rows.length - 1]!;
+  if (top.parentStepId == null) return null;
+  if (top.depth >= WORKFLOW_RUN_TREE_MAX_DEPTH) {
+    return `Workflow run ${runId} is nested deeper than ${WORKFLOW_RUN_TREE_MAX_DEPTH} levels`;
+  }
+  return `Parent step ${top.parentStepId} of workflow run ${top.id} is missing`;
+}
+
+/**
+ * The run and every run below it, root first: children of every attempt of
+ * every step, through terminal runs too, since a run that ended can still have
+ * a live child of an earlier attempt. The tree comes from stored links only
+ * (child.parentStepId → step → run). There is no size limit: the engine admits
+ * any number of children per run, and a tree it admitted must stay
+ * cancellable. Throws WorkflowRunTreeError on a cycle or past `maxDepth`, so
+ * the caller's transaction rolls back whole.
+ */
+export async function getWorkflowRunTreeIds(
+  rootId: string,
+  bounds: { maxDepth?: number } = {},
+): Promise<string[]> {
+  const maxDepth = bounds.maxDepth ?? WORKFLOW_RUN_TREE_MAX_DEPTH;
+  const ids = [rootId];
+  const seen = new Set(ids);
+  // One level per pass, so a cycle stops at its first repeated run instead of
+  // unrolling down to the depth bound.
+  let level = [rootId];
+  for (let depth = 1; level.length > 0; depth++) {
+    const next: string[] = [];
+    for (let i = 0; i < level.length; i += TREE_QUERY_CHUNK) {
+      const chunk = level.slice(i, i + TREE_QUERY_CHUNK);
+      const rows = await getDbClient().query<{ id: string }>(
+        `SELECT c.id
+           FROM workflow_run_steps s
+           JOIN workflow_runs c ON c.parentStepId = s.id
+          WHERE s.runId IN (${chunk.map(() => "?").join(", ")})`,
+        chunk,
+      );
+      for (const { id } of rows) {
+        // Each run has one parent link, so reaching a run twice means a cycle.
+        if (seen.has(id)) {
+          throw new WorkflowRunTreeError(`Workflow run tree of ${rootId} has a cycle at run ${id}`);
+        }
+        seen.add(id);
+        next.push(id);
+      }
+    }
+    if (next.length > 0 && depth > maxDepth) {
+      throw new WorkflowRunTreeError(
+        `Workflow run tree of ${rootId} is nested deeper than ${maxDepth} levels`,
+      );
+    }
+    ids.push(...next);
+    level = next;
+  }
+  return ids;
+}
+
+/** Parent runs per children query, well under SQLite's bound-parameter limit. */
+const TREE_QUERY_CHUNK = 500;
+
+/** A run's status alone, without opening its sealed context. Null when the run is missing. */
+export async function getWorkflowRunStatus(runId: string): Promise<WorkflowRunStatus | null> {
+  const row = await getDbClient().get<{ status: WorkflowRunStatus }>(
+    "SELECT status FROM workflow_runs WHERE id = ?",
+    [runId],
+  );
+  return row?.status ?? null;
+}
+
+/** Run `fn` over `ids` in chunks small enough for one statement's bound parameters. */
+async function forEachChunk(
+  ids: string[],
+  fn: (chunk: string[], placeholders: string) => Promise<void>,
+): Promise<void> {
+  for (let i = 0; i < ids.length; i += TREE_QUERY_CHUNK) {
+    const chunk = ids.slice(i, i + TREE_QUERY_CHUNK);
+    await fn(chunk, chunk.map(() => "?").join(", "));
+  }
+}
+
+/**
+ * Ids of the non-terminal tasks of the given runs, including tasks of earlier
+ * attempts: a retry detaches a task from its step, but the run link stays.
+ */
+export async function getOpenWorkflowTreeTaskIds(runIds: string[]): Promise<string[]> {
+  const ids: string[] = [];
+  const terminal = TERMINAL_TASK_STATUSES.map(() => "?").join(", ");
+  await forEachChunk(runIds, async (chunk, placeholders) => {
+    const rows = await getDbClient().query<{ id: string }>(
+      `SELECT id FROM agent_tasks
+        WHERE workflowRunId IN (${placeholders}) AND status NOT IN (${terminal})`,
+      [...chunk, ...TERMINAL_TASK_STATUSES],
+    );
+    for (const row of rows) ids.push(row.id);
+  });
+  return ids;
+}
+
+/**
+ * Ids of tasks that a non-terminal task lists in `dependsOn`: the only
+ * dependents a cancel can fail. One scan over open tasks, so a cancel of many
+ * tasks looks for dependents once instead of once per task.
+ */
+export async function getTaskIdsWithDependents(): Promise<Set<string>> {
+  const rows = await getDbClient().query<{ id: string }>(
+    `SELECT DISTINCT dep.value AS id
+       FROM agent_tasks t, json_each(t.dependsOn) AS dep
+      WHERE t.status NOT IN (${TERMINAL_TASK_STATUSES.map(() => "?").join(", ")})
+        AND t.dependsOn IS NOT NULL AND t.dependsOn != '[]'`,
+    [...TERMINAL_TASK_STATUSES],
+  );
+  return new Set(rows.map((row) => row.id));
+}
+
+/**
+ * True when any of the given runs still has work a cancel would close: a live
+ * run, a pending, running or waiting step, a queued retry, an open task or a
+ * pending approval. Reads only, with a LIMIT 1 probe per chunk.
+ */
+export async function workflowRunTreeHasOpenWork(runIds: string[]): Promise<boolean> {
+  const terminal = TERMINAL_TASK_STATUSES.map(() => "?").join(", ");
+  const probes: Array<{ sql: (ids: string) => string; params: string[] }> = [
+    {
+      sql: (ids) =>
+        `SELECT 1 FROM workflow_runs WHERE id IN (${ids}) AND status IN ('running', 'waiting') LIMIT 1`,
+      params: [],
+    },
+    {
+      sql: (ids) => `SELECT 1 FROM workflow_run_steps
+        WHERE runId IN (${ids})
+          AND (status IN ('pending', 'running', 'waiting')
+               OR (status = 'failed' AND nextRetryAt IS NOT NULL))
+        LIMIT 1`,
+      params: [],
+    },
+    {
+      sql: (ids) =>
+        `SELECT 1 FROM agent_tasks WHERE workflowRunId IN (${ids}) AND status NOT IN (${terminal}) LIMIT 1`,
+      params: [...TERMINAL_TASK_STATUSES],
+    },
+    {
+      sql: (ids) =>
+        `SELECT 1 FROM approval_requests WHERE workflowRunId IN (${ids}) AND status = 'pending' LIMIT 1`,
+      params: [],
+    },
+  ];
+  let open = false;
+  await forEachChunk(runIds, async (chunk, placeholders) => {
+    for (const probe of probes) {
+      if (open) return;
+      if (await getDbClient().get(probe.sql(placeholders), [...chunk, ...probe.params])) {
+        open = true;
+      }
+    }
+  });
+  return open;
+}
+
+/**
+ * Cancel the pending, running and waiting steps of the given runs. The
+ * migration-140 trigger closes each cancelled step's pending approval.
+ */
+export async function cancelOpenWorkflowTreeSteps(
+  runIds: string[],
+  reason: string,
+  finishedAt: string,
+): Promise<void> {
+  await forEachChunk(runIds, async (chunk, placeholders) => {
+    await getDbClient().run(
+      `UPDATE workflow_run_steps
+          SET status = 'cancelled', error = ?, finishedAt = ?
+        WHERE runId IN (${placeholders}) AND status IN ('pending', 'running', 'waiting')`,
+      [scrubSecrets(reason), finishedAt, ...chunk],
+    );
+  });
+}
+
+/**
+ * Drop the pending retries of the failed steps of the given runs. The step
+ * keeps its status, error, output and retryCount; only the queued next
+ * attempt goes.
+ */
+export async function disarmWorkflowTreeRetries(
+  runIds: string[],
+  finishedAt: string,
+): Promise<void> {
+  await forEachChunk(runIds, async (chunk, placeholders) => {
+    await getDbClient().run(
+      `UPDATE workflow_run_steps
+          SET nextRetryAt = NULL, finishedAt = COALESCE(finishedAt, ?)
+        WHERE runId IN (${placeholders}) AND status = 'failed' AND nextRetryAt IS NOT NULL`,
+      [finishedAt, ...chunk],
+    );
+  });
+}
+
+/**
+ * Mark the given runs that are still running or waiting `cancelled`, without
+ * the per-run `workflow.child.finished` wake-up: it is for runs whose parent
+ * step the same cancel closes. A terminal run keeps its status and reason.
+ */
+export async function cancelLiveWorkflowTreeRuns(
+  runIds: string[],
+  reason: string,
+  finishedAt: string,
+): Promise<void> {
+  await forEachChunk(runIds, async (chunk, placeholders) => {
+    await getDbClient().run(
+      `UPDATE workflow_runs
+          SET status = 'cancelled', error = ?, finishedAt = ?, lastUpdatedAt = ?
+        WHERE id IN (${placeholders}) AND status IN ('running', 'waiting')`,
+      [scrubSecrets(reason), finishedAt, finishedAt, ...chunk],
+    );
+  });
+}
+
+/** The id of the child run a `sub-workflow` step started on `attempt`, if any. */
+export async function getChildWorkflowRunId(
+  parentStepId: string,
+  attempt: number,
+): Promise<string | null> {
   const row = await getDbClient().get<{ id: string }>(
-    "SELECT id FROM workflow_runs WHERE parentStepId = ?",
-    [parentStepId],
+    "SELECT id FROM workflow_runs WHERE parentStepId = ? AND parentStepAttempt = ?",
+    [parentStepId, attempt],
   );
   return row?.id ?? null;
 }
 
+/**
+ * True while `attempt` of the step is executing in a live run: the step is
+ * `running` with that `retryCount` and no ancestor run is cancelled. A child
+ * run is created only then, so a cancelled run or tree, a step another attempt
+ * moved on, or a step already parked never gets a new child.
+ */
+export async function isParentStepAttemptCurrent(
+  parentStepId: string,
+  attempt: number,
+): Promise<boolean> {
+  const row = await getDbClient().get<{ runId: string }>(
+    `SELECT r.id AS runId
+       FROM workflow_run_steps s
+       JOIN workflow_runs r ON r.id = s.runId
+      WHERE s.id = ? AND s.status = 'running' AND s.retryCount = ?
+        AND r.status IN ('running', 'waiting')`,
+    [parentStepId, attempt],
+  );
+  return row != null && (await getRunLineageBlock(row.runId)) == null;
+}
+
+/**
+ * Why `stepId` may not start new work (a task, an approval, a child run), or
+ * null when it may: the step is `running` in a live run whose lineage is not
+ * blocked. Call it inside the transaction that inserts the work.
+ */
+export async function getStepExecutionBlock(stepId: string): Promise<string | null> {
+  const row = await getDbClient().get<{
+    stepStatus: string;
+    runId: string;
+    runStatus: WorkflowRunStatus;
+  }>(
+    `SELECT s.status AS stepStatus, r.id AS runId, r.status AS runStatus
+       FROM workflow_run_steps s
+       JOIN workflow_runs r ON r.id = s.runId
+      WHERE s.id = ?`,
+    [stepId],
+  );
+  if (!row) return "the step or its run is missing";
+  if (row.runStatus !== "running" && row.runStatus !== "waiting") {
+    return `its run is ${row.runStatus}`;
+  }
+  if (row.stepStatus !== "running") return `the step is ${row.stepStatus}`;
+  return getRunLineageBlock(row.runId);
+}
+
+/**
+ * `sub-workflow` steps left `running` in a live run: each is its node's latest
+ * row, so a row a newer one superseded is not listed. The caller skips the
+ * ones this process is still executing.
+ */
+export async function getRunningSubWorkflowSteps(): Promise<
+  Array<{ stepId: string; runId: string; nodeId: string }>
+> {
+  return getDbClient().query<{ stepId: string; runId: string; nodeId: string }>(
+    `SELECT s.id AS stepId, s.runId AS runId, s.nodeId AS nodeId
+       FROM workflow_run_steps s
+       JOIN workflow_runs r ON r.id = s.runId
+      WHERE s.status = 'running' AND s.nodeType = 'sub-workflow'
+        AND r.status IN ('running', 'waiting')
+        AND s.rowid = (
+          SELECT MAX(rowid) FROM workflow_run_steps
+           WHERE runId = s.runId AND nodeId = s.nodeId
+        )`,
+  );
+}
+
 /** Where a child run came from: the `sub-workflow` step that started it and that step's run. */
 export type WorkflowRunParent = {
   runId: string;
@@ -65,12 +422,13 @@ export async function getWorkflowRunLineage(runId: string, maxDepth: number): Pr
   return rows.map((row) => row.workflowId);
 }
 
-/** Waiting `sub-workflow` steps whose child run is terminal or deleted. */
+/** Waiting `sub-workflow` steps whose current attempt's child run is terminal or deleted. */
 export async function getSettledChildRunParentSteps(): Promise<string[]> {
   const rows = await getDbClient().query<{ id: string }>(
     `SELECT s.id
        FROM workflow_run_steps s
-       LEFT JOIN workflow_runs c ON c.parentStepId = s.id
+       LEFT JOIN workflow_runs c
+         ON c.parentStepId = s.id AND c.parentStepAttempt = s.retryCount
       WHERE s.status = 'waiting' AND s.nodeType = 'sub-workflow'
         AND (c.id IS NULL OR c.status IN ('completed', 'failed', 'cancelled', 'skipped'))`,
   );

package/src/be/db.ts

@@ -208,6 +208,7 @@ import {
   sessionPageFields,
   sessionSummaryQuery,
 } from "./db/session-tree";
+import { searchSkillRowsRanked } from "./db/skill-search";
 import { classifyTaskHumanFree, reclassifyTaskHumanFree } from "./db/tasks/human-free";
 import {
   type AgentTaskRow,
@@ -221,7 +222,14 @@ import {
   rowToAgentTaskSummary,
 } from "./db/tasks/read";
 import { configureTaskWriteDependencies, failTask } from "./db/tasks/write";
-import { emitChildRunFinished, wakeParentsOfDeletedRuns } from "./db/workflow-runs";
+import { tombstoneWorkflowIdempotencyKeys } from "./db/workflow-idempotency";
+import {
+  emitChildRunFinished,
+  getRunLineageBlock,
+  getStepExecutionBlock,
+  WorkflowStepNotExecutableError,
+  wakeParentsOfDeletedRuns,
+} from "./db/workflow-runs";
 import { scrubJsonValue } from "./scrub-json";
 import { openSealedJson, sealedJsonForDisplay, sealJson } from "./sealed-json";
 import { configSecretName, registerStoredSecret } from "./secret-registry";
@@ -2854,6 +2862,14 @@ export async function createTaskExtended(
   const claim = await getDbClient().transaction<
     { existing: ExistingTrackerContextWork } | { row: AgentTaskRow }
   >(async () => {
+    // A workflow step's task commits only while the step may still start
+    // work. Checked in the INSERT's transaction: a cascade cancel of the
+    // step's run tree either commits first and is seen here, or sees and
+    // cancels this task.
+    if (options?.workflowRunStepId) {
+      const blocked = await getStepExecutionBlock(options.workflowRunStepId);
+      if (blocked) throw new WorkflowStepNotExecutableError(options.workflowRunStepId, blocked);
+    }
     const existingTrackerWork = options?.bypassTrackerContextDedup
       ? null
       : await findExistingLinearTrackerContextWork(options?.contextKey);
@@ -4738,7 +4754,7 @@ export async function createSessionLogs(logs: {
   for (let start = 0; start < logs.lines.length; start += BATCH_SIZE) {
     // Yield to the event loop between batches.
     if (start > 0) await new Promise<void>((r) => setTimeout(r, 5));
-    const batch: { content: string; lineNumber: number }[] = [];
+    const batch: string[] = [];
     const end = Math.min(start + BATCH_SIZE, logs.lines.length);
     for (let i = start; i < end; i++) {
       const line = logs.lines[i];
@@ -4747,10 +4763,22 @@ export async function createSessionLogs(logs: {
       // content that is already scrubbed at the adapter emit site. We scrub
       // again here so any future write path that bypasses the adapter still
       // lands clean text in the persistent session_logs table.
-      batch.push({ content: scrubSecrets(line), lineNumber: i });
+      batch.push(scrubSecrets(line));
     }
     await getDbClient().transaction(async (tx) => {
-      for (const { content, lineNumber } of batch) {
+      // The worker flushes one (sessionId, iteration) in many POSTs, so the
+      // lineNumber continues from the newest stored row instead of restarting
+      // at the POST's index. Reading the newest row by rowid walks the
+      // sessionId index backwards and stops at the first hit, where MAX()
+      // would scan the whole session. Rows written here are monotonic in
+      // rowid, so this equals MAX + 1 for them.
+      const last = await tx.get<{ lineNumber: number }>(
+        `SELECT lineNumber FROM session_logs WHERE sessionId = ? AND iteration = ?
+         ORDER BY rowid DESC LIMIT 1`,
+        [logs.sessionId, logs.iteration],
+      );
+      let lineNumber = last ? last.lineNumber + 1 : 0;
+      for (const content of batch) {
         await tx.run(
           `INSERT INTO session_logs (id, taskId, sessionId, iteration, cli, content, lineNumber, createdAt)
            VALUES (?, ?, ?, ?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))`,
@@ -4761,7 +4789,7 @@ export async function createSessionLogs(logs: {
             logs.iteration,
             logs.cli,
             content,
-            lineNumber,
+            lineNumber++,
           ],
         );
       }
@@ -4769,6 +4797,10 @@ export async function createSessionLogs(logs: {
   }
 }
 
+// Session log reads order by rowid, which is insert order. Rows written before
+// lineNumber was assigned server-side restart at 0 on every worker flush, so
+// only rowid orders them. The API never runs VACUUM (runbooks/db-retention.md);
+// a manual VACUUM may renumber rowids but copies rows in rowid order.
 export async function getSessionLogsByTaskId(
   taskId: string,
   limit?: number,
@@ -4776,16 +4808,16 @@ export async function getSessionLogsByTaskId(
   if (typeof limit === "number" && limit > 0) {
     const rows = await getDbClient().query<SessionLogRow>(
       `SELECT * FROM (
-         SELECT * FROM session_logs WHERE taskId = ?
-         ORDER BY iteration DESC, lineNumber DESC
+         SELECT rowid AS seq, * FROM session_logs WHERE taskId = ?
+         ORDER BY rowid DESC
          LIMIT ?
-       ) ORDER BY iteration ASC, lineNumber ASC`,
+       ) ORDER BY seq ASC`,
       [taskId, limit],
     );
     return rows.map(rowToSessionLog);
   }
   const rows = await getDbClient().query<SessionLogRow>(
-    "SELECT * FROM session_logs WHERE taskId = ? ORDER BY iteration ASC, lineNumber ASC",
+    "SELECT * FROM session_logs WHERE taskId = ? ORDER BY rowid ASC",
     [taskId],
   );
   return rows.map(rowToSessionLog);
@@ -4796,7 +4828,7 @@ export async function getSessionLogsBySession(
   iteration: number,
 ): Promise<SessionLog[]> {
   const rows = await getDbClient().query<SessionLogRow>(
-    "SELECT * FROM session_logs WHERE sessionId = ? AND iteration = ? ORDER BY lineNumber ASC",
+    "SELECT * FROM session_logs WHERE sessionId = ? AND iteration = ? ORDER BY rowid ASC",
     [sessionId, iteration],
   );
   return rows.map(rowToSessionLog);
@@ -7789,7 +7821,9 @@ async function deleteWorkflowRows(id: string, source?: "api" | "mcp"): Promise<b
   await reclassifyTaskHumanFree(linkedTaskIds);
   // 4. Delete every user's favorite of it (no FK to the workflow)
   await client.run("DELETE FROM user_favorites WHERE itemType = 'workflow' AND itemId = ?", [id]);
-  // 5. Delete workflow
+  // 5. Keep Idempotency-Keys that created or triggered it taken, without the stored response
+  await tombstoneWorkflowIdempotencyKeys(id);
+  // 6. Delete workflow
   const result = await client.run("DELETE FROM workflows WHERE id = ?", [id]);
   const deleted = result.changes > 0;
   if (deleted) {
@@ -7842,6 +7876,8 @@ type WorkflowRunRow = {
   finishedAt: string | null;
   /** The `sub-workflow` step that started this run (migration 203). */
   parentStepId?: string | null;
+  /** That step's attempt (`retryCount`) when it started this run (migration 240). */
+  parentStepAttempt?: number | null;
 };
 
 /**
@@ -7862,6 +7898,7 @@ function rowToWorkflowRun(row: WorkflowRunRow, view: WorkflowPayloadView = "repl
     lastUpdatedAt: normalizeDateRequired(row.lastUpdatedAt),
     finishedAt: normalizeDate(row.finishedAt) ?? undefined,
     parentStepId: row.parentStepId ?? undefined,
+    parentStepAttempt: row.parentStepId ? (row.parentStepAttempt ?? 0) : undefined,
   };
   return defineWorkflowPayload(run, "context", row.context, row.context_replay, view, {
     runId: row.id,
@@ -7876,10 +7913,12 @@ export async function createWorkflowRun(data: {
   triggerData?: unknown;
   createdBy?: string;
   parentStepId?: string;
+  /** The parent step's `retryCount` when it started this run (migration 240). */
+  parentStepAttempt?: number;
 }): Promise<WorkflowRun> {
   const now = new Date().toISOString();
   const row = await getDbClient().get<WorkflowRunRow>(
-    `INSERT INTO workflow_runs (id, workflowId, triggerType, startedAt, triggerData, created_by, parentStepId) VALUES (?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+    `INSERT INTO workflow_runs (id, workflowId, triggerType, startedAt, triggerData, created_by, parentStepId, parentStepAttempt) VALUES (?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
     [
       data.id,
       data.workflowId,
@@ -7888,6 +7927,7 @@ export async function createWorkflowRun(data: {
       data.triggerData ? scrubJsonValue(data.triggerData) : null,
       data.createdBy ?? null,
       data.parentStepId ?? null,
+      data.parentStepAttempt ?? 0,
     ],
   );
   if (!row) throw new Error("Failed to create workflow run");
@@ -7992,9 +8032,10 @@ export type WorkflowRunListOptions = {
 };
 
 // Everything but `context`. `triggerData` stays: it is small, and stored
-// scripts read it off list rows (dedupe by trigger, failure reports).
+// scripts read it off list rows (dedupe by trigger, failure reports). The
+// parent link and attempt stay so a list row identifies a child's invocation.
 const WORKFLOW_RUN_SUMMARY_COLUMNS =
-  "id, workflowId, status, triggerType, triggerData, error, created_by, startedAt, lastUpdatedAt, finishedAt";
+  "id, workflowId, status, triggerType, triggerData, error, created_by, startedAt, lastUpdatedAt, finishedAt, parentStepId, parentStepAttempt";
 
 export type WorkflowRunPage = {
   runs: WorkflowRun[];
@@ -9779,15 +9820,29 @@ export async function createApprovalRequest(data: {
   const row = await getDbClient().transaction(async () => {
     let status: ApprovalRequest["status"] = "pending";
     let resolutionReason: string | null = null;
-    if (data.requireActionableWorkflow && data.workflowRunId && data.workflowRunStepId) {
-      const run = await getWorkflowRun(data.workflowRunId);
-      const step = await getWorkflowRunStep(data.workflowRunStepId);
+    // A request linked to an existing run, with or without a step, is born
+    // cancelled unless the run is live and its tree is not cancelled: a
+    // pending request in a cancelled tree would be open work no cancel may
+    // leave behind. A missing run is refused only on the workflow (HITL) path.
+    const actionable = data.requireActionableWorkflow && data.workflowRunStepId;
+    const run = data.workflowRunId ? await getWorkflowRun(data.workflowRunId, "display") : null;
+    if (data.workflowRunId && (run || actionable)) {
+      const step = actionable ? await getWorkflowRunStep(data.workflowRunStepId!) : undefined;
       if (!run || (run.status !== "running" && run.status !== "waiting")) {
         status = "cancelled";
         resolutionReason = run?.error ?? `Workflow run is ${run?.status ?? "missing"}`;
-      } else if (!step || step.runId !== run.id || step.status !== "running") {
+      } else if (
+        step !== undefined &&
+        (!step || step.runId !== run.id || step.status !== "running")
+      ) {
         status = "cancelled";
         resolutionReason = `Human-in-the-loop step is ${step?.status ?? "missing"}`;
+      } else {
+        const blocked = await getRunLineageBlock(run.id);
+        if (blocked) {
+          status = "cancelled";
+          resolutionReason = blocked;
+        }
       }
     }
 
@@ -10989,11 +11044,23 @@ export async function listSkills(filters?: SkillFilters): Promise<Skill[]> {
   return rows.map(rowToSkill);
 }
 
+/**
+ * Ranked skill search (see searchSkillRowsRanked). Falls back to the unranked
+ * substring match when the ranked query finds nothing, e.g. a partial word or
+ * a query of only stopwords. The fallback also ranks an exact name first.
+ */
 export async function searchSkills(
   query: string,
   limit = 20,
   includeContent = true,
 ): Promise<Skill[]> {
+  const ranked = await searchSkillRowsRanked<SkillRow>(
+    query,
+    limit,
+    includeContent === false ? SKILL_SLIM_COLUMNS : "skills.*",
+  );
+  if (ranked.length > 0) return ranked.map(rowToSkill);
+
   const tokens = query.split(/\s+/).filter(Boolean);
   const columns = includeContent === false ? SKILL_SLIM_COLUMNS : "*";
   const searchClauses = tokens.map(() => "(name LIKE ? OR description LIKE ? OR content LIKE ?)");
@@ -11002,8 +11069,8 @@ export async function searchSkills(
     return [term, term, term];
   });
   const rows = await getDbClient().query<SkillRow>(
-    `SELECT ${columns} FROM skills WHERE ${[...searchClauses, "isEnabled = 1"].join(" AND ")} ORDER BY name ASC LIMIT ?`,
-    [...params, limit],
+    `SELECT ${columns} FROM skills WHERE ${[...searchClauses, "isEnabled = 1"].join(" AND ")} ORDER BY lower(name) = lower(?) DESC, name ASC LIMIT ?`,
+    [...params, query.trim(), limit],
   );
   return rows.map(rowToSkill);
 }
@@ -12872,7 +12939,8 @@ export async function listTaskTemplates(opts?: {
 /**
  * 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.
+ * a plain JOIN, SQLite scanned all of agent_tasks to skip the sort. Each task carries its
+ * `totalCostUsd`, so the session header can total the whole chain, not only the root.
  */
 export async function getRootTaskChain(rootTaskId: string): Promise<AgentTask[]> {
   const rows = await getDbClient().query<AgentTaskRow>(
@@ -12882,7 +12950,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 chain
+       SELECT t.*,
+         (SELECT SUM(totalCostUsd) FROM session_costs WHERE session_costs.taskId = t.id) AS totalCostUsd
+       FROM chain
        CROSS JOIN agent_tasks t ON t.id = chain.id
        ORDER BY t.createdAt, t.rowid`,
     [rootTaskId],